CSC/ECE 517 Spring 2026 - E2604. Finish Password Resets

Expertiza Background

What is Expertiza?

Expertiza is an open-source educational web application built with Ruby on Rails and jointly maintained by students and faculty at North Carolina State University (NCSU). It is available publicly on GitHub.

It supports:

• Creating and configuring assignments (individual or team-based).
• Allowing students to submit work (files, links, etc.).
• Enabling peer review and teammate evaluation.
• Letting instructors define rubrics and grading criteria.

Expertiza is designed to promote learning through iterative feedback. Students review each other’s work, reflect, improve, and resubmit. Instructors can monitor progress, manage deadlines, and assess performance.

Reimplementation Repository

Front End Overview

The reimplementation-front-end project replaces Expertiza's aging Rails monolith (server-rendered ERB templates, jQuery, session cookies, no client-side state) with a decoupled React + TypeScript SPA using JWT auth, Redux, Formik/Yup forms, React Bootstrap, and Vite — separating the front end entirely from the Rails API back end.

Back End Overview

The reimplementation-back-end project transforms Expertiza from a server-rendered Rails monolith into a pure JSON REST API using stateless JWT/RSA-256 authentication, a centralized role-based authorization concern, and adds several new features including a Duties system for team role assignment, a MentoredTeam type, a TeamsParticipant join model replacing TeamsUser, an Item/Strategy pattern replacing the Question STI hierarchy, a StudentTask service object, multi-view grade reporting endpoints, a self-registration AccountRequest workflow, full invitation lifecycle management, and auto-generated Swagger API documentation.

Project Background

Motivation

Account recovery and password reset functionality is a critical part of any authentication system. The current site lacks a functional password reset or "forgot password" feature, representing a significant gap in both usability and security.

This created several issues:

• Without a working reset mechanism, there is no sanctioned path for users to change this default credential after account creation. This constitutes a vulnerability that persists indefinitely if left unaddressed.
• A user who forgets their credentials has no means of recovering access independently.
• A standards-compliant password reset mechanism relies on time-limited, single-use tokens delivered to a verified email address. This ensures that only the legitimate account owner can initiate a reset. Without such a mechanism, any ad-hoc reset approach would be either insecure or unverifiable (e.g., allowing resets without proving email ownership).

This project introduces a more structured workflow for handling password reset and account recovery operations.

The goal is to provide a consistent and secure process for users who need to reset or recover their credentials while maintaining proper validation and access control.

Typical operations in this workflow include:

• requesting a password reset
• generating a secure reset token
• validating reset requests
• updating the user's password
• preventing unauthorized reset attempts

The system should ensure that these steps are handled in a secure, predictable, and maintainable way.

Objectives

1. Implement a unified password reset workflow

The system should support a consistent flow for recovering user accounts.

Typical steps include:

• User requests password reset
• System generates a reset token
• User receives reset instructions via email
• User accesses password reset page via email link
• User submits new password
• System validates and updates credentials

This workflow should be easy to maintain and extend.

2. Improve security and validation

Password reset functionality must enforce security best practices.

This may include:

• Ensure forgot password mechanism adheres to industry standards.
• Ensure reset links are generated correctly across development, staging, and production environments.
• Validate forgot and reset password mechanism functions through unit, functional, performance, and integration testing.

The system should ensure that only authorized password reset requests are processed.

3. Improve frontend robustness and validation

The password reset workflow involves several frontend steps, including requesting a reset link and submitting a new password. The frontend should handle various edge cases gracefully.

This project includes a review and refinement of the frontend behavior to ensure consistent handling of errors and validation responses.

Key areas of focus include:

• Handling invalid or expired password reset tokens
• Properly displaying backend validation errors
• Ensuring clear success and failure messages for users
• Confirming that form validation aligns with backend rules

The goal is to ensure that the password reset workflow remains reliable and user-friendly.

Core Changes

In this project:

• The User model or authentication model was enhanced.
• A new password reset workflow was introduced.
• Controller logic was updated to handle reset requests.
• Routes were added to support password reset endpoints.
• Tests were added to verify authentication and recovery behavior.

Password Reset Workflow

Purpose

The password reset workflow allows users who have forgotten their password to regain access to their account securely.

A typical password reset flow may look like:

• User selects "Forgot Password" in the login page.
• User provides email address associated with account.
• System generates a reset token.
• System sends reset email containing link with password token in it.
• User navigates to password reset portal and creates a new password.
• System validates the request and updates credentials

This workflow must ensure both usability and security.

Implementation

The PasswordsController handles two operations in the password reset flow: initiating a reset request and completing it with a new password. Both actions bypass the standard JWT authentication (skip_before_action :authenticate_request!), as they are designed for unauthenticated users.

When a user submits their email to request a password reset.

# POST /password_resets
def create
  if @user
    token = @user.generate_token_for(:password_reset)
    UserMailer.send_password_reset_email(@user, token).deliver_later
  end

  # Always return a 200 OK to prevent email enumeration attacks
  render json: { message: I18n.t('password_reset.email_sent') }, status: :ok
end

When a user submits a new password using the token from the email link.

# PATCH/PUT /password_resets/:token
def update
  if @user.update(password_params)
    render json: { message: I18n.t('password_reset.updated') }, status: :ok
  else
    render json: { errors: @user.errors.full_messages }, status: :unprocessable_entity
  end
end

How it works

• TODO: explain how reset tokens are generated
• TODO: explain how tokens are validated
• TODO: explain how passwords are updated securely

Token Management

Purpose

Reset tokens allow the system to verify that the password reset request is legitimate.

Tokens typically have the following properties:

• unique per request
• difficult to guess
• time-limited
• associated with a specific user account

Implementation

Example structure:

def generate_reset_token
  # TODO: create secure token
end

def token_valid?
  # TODO: verify token existence
  # TODO: check expiration
end

How it works

• When a reset request is initiated, the system generates a token.
• The token is associated with the requesting user.
• The token is included in the password reset link.
• When the user submits a new password, the token is verified.

If validation fails, the reset attempt is rejected.

Updating the Password

Purpose

After the reset token has been verified, the system allows the user to submit a new password.

Implementation

def update_password
  # TODO: validate token
  # TODO: validate password rules
  # TODO: save updated credentials
end

How it works

• The system confirms that the reset request is valid.
• Password requirements are checked.
• The new password is stored securely.
• The reset token is invalidated to prevent reuse.

Security Considerations

Password reset systems must be designed carefully to prevent abuse.

Potential risks include:

• unauthorized password changes
• brute-force token guessing
• replay attacks using old reset links

To mitigate these risks, the system may include:

• TODO: token expiration
• TODO: rate limiting
• TODO: secure password hashing
• TODO: audit logging

Routing

Example routing structure for password reset operations:

resources :password_resets do
  collection do
    post :request_reset
  end

  member do
    patch :reset_password
  end
end

TODO: Modify routing according to the project's implementation.

Testing Strategy

Goals of Testing

The testing strategy verifies that password reset functionality works correctly and securely.

Key goals include:

• verifying reset request behavior
• verifying token validation
• verifying password updates
• verifying proper error handling

Model Tests

Model tests may verify:

• TODO: token generation
• TODO: token expiration behavior
• TODO: password validation rules

Controller Tests

Controller tests verify:

• TODO: reset request creation
• TODO: reset token validation
• TODO: successful password update
• TODO: rejection of invalid requests

Security Tests

Security tests ensure that:

• invalid tokens are rejected
• expired tokens cannot be used
• password updates require valid authentication

Collaborators

• TODO
• TODO
• TODO
• TODO