E2604. Finish Password Resets

.gitignore

@@ -32,3 +32,11 @@
 coverage/
 rsa_keys.yml
 pg_data/
+
+# Ignore .env files
+# .env files should never be committed to prevent sensitive information from being exposed.
+# Each environment can have its own .env file, and .env.* covers all of them.
+# .env.* covers .env.development .env.test, etc
+# ** ensures that .env files are ignored regardless of their location in the directory structure.
+**/.env
+**/.env.*

README.md

@@ -7,6 +7,71 @@ Things you may want to cover:
 
 * Ruby version - 3.4.5
 
+---
+
+## Environment Configuration
+
+Before running the application, you need to configure environment variables:
+
+1. **Copy the sample environment file:**
+   ```bash
+   cp sample.env .env
+   ```
+
+2. **Configure Frontend URL Settings:**
+
+   Edit the `.env` file and set the following frontend variables based on your environment. These settings will override the defaults defined in `config/environments/(development|test|production).rb`:
+
+   - **`FRONTEND_SCHEME`**: Should be `http` for development/test or `https` for production
+   - **`FRONTEND_DOMAIN`**: The domain where your frontend is hosted
+     - **Development/Test**: Defaults to `localhost` if not set (configured in `config/environments/development.rb` and `config/environments/test.rb`)
+     - **Staging**: Requires explicit configuration via `.env`
+     - **Production**: Defaults to `expertiza.ncsu.com` if not set (configured in `config/environments/production.rb`), can be overridden via `.env`
+   - **`FRONTEND_PORT`**: Optional port number
+     - **Development/Test**: Defaults to `3000` if not set (configured in `config/environments/development.rb` and `config/environments/test.rb`)
+     - Leave blank for standard ports (80 for HTTP, 443 for HTTPS)
+     - Set to custom port if needed (e.g., `8443` for custom HTTPS)
+
+   **Example for local development** (using defaults, no .env needed):
+   ```bash
+   # No need to set anything - defaults will be used
+   # FRONTEND_DOMAIN defaults to localhost
+   # FRONTEND_PORT defaults to 3000
+   ```
+
+   **Example for local development** (overriding defaults via .env):
+   ```env
+   FRONTEND_SCHEME=http
+   FRONTEND_DOMAIN=localhost
+   FRONTEND_PORT=3000
+   ```
+
+   **Note:** `FRONTEND_DOMAIN` must be explicitly configured via `.env` in staging environments. In production, it defaults to `expertiza.ncsu.com` but can be overridden if needed. The application will fail to start if `FRONTEND_DOMAIN` is not set in staging.
+
+3. **Load environment variables** (optional, only needed if running outside of Docker):
+   > **Note:**
+   > 
+   > If you're using Docker Compose, the `.env` file is automatically loaded, so you don't need to source it manually.
+
+
+   When running the Rails server outside of Docker (e.g., `rails s`), you may need to source the `.env` file to load environment variables:
+
+   **Linux/macOS:**
+   ```
+   set -a   # automatically export all variables
+   source .env
+   set +a   # stop automatically exporting
+   rails s
+   ```
+
+   **Windows (PowerShell):**
+   ```powershell
+   Get-Content .env | ForEach-Object { if ($_ -and !$_.StartsWith("#")) { $key, $value = $_ -split '=', 2; [Environment]::SetEnvironmentVariable($key, $value) } }
+   rails s
+   ```
+
+---
+
 ## Development Environment
 
 ### Prerequisites

app/controllers/invitations_controller.rb

@@ -146,7 +146,7 @@ def inviter_team
   end
 
   def invitee_participant
-    invitee_user = User.find_by(name: params[:username])|| User.find_by(email: params[:username])
+    invitee_user = User.find_by(name: params[:username]) || User.find_by(email: params[:username])
     unless invitee_user
       render json: { error: "Participant with username #{params[:username]} not found" }, status: :not_found
       return

app/controllers/password_resets_controller.rb

@@ -0,0 +1,48 @@
+class PasswordResetsController < ApplicationController
+  before_action :find_user_by_email, only: [:create]
+  before_action :load_user_by_token, only: [:update]
+  before_action :require_valid_token!, only: [:update]
+  skip_before_action :authenticate_request!, only: [:create, :update]
+
+  # POST /password_resets
+  def create
+    if @user
+      token = @user.generate_token_for(:password_reset)
+      UserMailer.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
+
+  # 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
+
+  private
+
+  def find_user_by_email
+    @user = User.find_by(email: params[:email])
+  end
+
+  def load_user_by_token
+    @user = User.find_by_token_for(:password_reset, params[:token])
+  end
+
+  def require_valid_token!
+    render_invalid_token_response unless @user
+  end
+
+  def render_invalid_token_response
+    render json: { error: I18n.t('password_reset.errors.token_expired') }, status: :unprocessable_entity
+  end
+
+  def password_params
+    params.require(:user).permit(:password, :password_confirmation)
+  end
+end

app/mailers/user_mailer.rb

@@ -0,0 +1,15 @@
+class UserMailer < ApplicationMailer
+  default from: "expertizamailer@gmail.com"
+
+  def password_reset_email(user, token)
+    @user = user
+    @reset_url = password_reset_url(token)
+    mail(to: @user.email, subject: I18n.t('password_reset.email_subject'))
+  end
+
+  private
+
+  def password_reset_url(token)
+    "#{FRONTEND_URL}/password_edit/check_reset_url?token=#{token}"
+  end
+end

app/models/user.rb

@@ -2,6 +2,7 @@
 
 class User < ApplicationRecord
   has_secure_password
+  normalizes :email, with: ->(email) { email.strip.downcase }
   after_initialize :set_defaults
 
   # name must be lowercase and unique
@@ -48,6 +49,12 @@ def self.instantiate(record)
     end
   end
 
+  # Built-in Rails 7.1+ token generator. Token invalidates if password_salt or updated_at changes.
+  # https://api.rubyonrails.org/classes/ActiveRecord/TokenFor/ClassMethods.html
+  generates_token_for :password_reset, expires_in: 15.minutes do
+    password_salt&.last(10) || updated_at.to_s
+  end
+
   # Welcome email to be sent to the user after they sign up
   def welcome_email; end
 
@@ -62,13 +69,6 @@ def self.login_user(login)
     user
   end
 
-  # Reset the password for the user
-  def reset_password
-    random_password = SecureRandom.alphanumeric(10)
-    user.password_digest = BCrypt::Password.create(random_password)
-    user.save
-  end
-
   # Get instructor_id of the user, if the user is TA,
   # return the id of the instructor else return the id of the user for superior roles
   def instructor_id

app/views/user_mailer/password_reset_email.html.erb

@@ -0,0 +1,14 @@
+<html>
+<head>
+  <title>Expertiza password reset</title>
+</head>
+
+<body>
+<p>Hi <%= @user.full_name %>,</p>
+<p>Reset your password, and we'll get you on your way.</p>
+<p>To change your password, click or paste the following link into your browser:</p>
+<p><a href="<%= @reset_url %>"><%= @reset_url %></a></p>
+<p>The link will expire in 15 minutes, so be sure to use it right away.</p>
+</body>
+</html>
+

config/application.rb

@@ -33,5 +33,28 @@ class Application < Rails::Application
     # Skip views, helpers and assets when generating a new resource.
     config.api_only = true
     config.cache_store = :redis_store, ENV['CACHE_STORE'], { expires_in: 3.days, raise_errors: false }
+
+    # ── Action Mailer SMTP configuration ──
+    # All values are pulled from environment variables so the block is safe
+    # to load even when mailer env vars are absent (e.g. in dev/test).
+    # Delivery will simply fail at send-time if credentials are missing,
+    # rather than blowing up on boot.
+    config.action_mailer.smtp_settings = {
+      address: ENV['MAILER_SERVER'].presence || 'localhost',
+      port: (ENV['MAILER_SERVER_PORT'].presence || '587').to_i,
+      domain: ENV['MAILER_DOMAIN'].presence || 'localhost',
+
+      # Only include credentials when they're actually provided.
+      user_name: ENV['MAILER_USER'].presence,
+      password: ENV['MAILER_PASSWORD'].presence,
+
+      # :plain sends base64-encoded credentials — fine over TLS,
+      # but skip authentication entirely when no user is configured.
+      authentication: ENV['MAILER_USER'].present? ? :plain : nil,
+
+      enable_starttls_auto: ActiveModel::Type::Boolean.new.cast(
+        ENV['MAILER_ENABLE_STARTTLS'].presence || 'true'
+      )
+    }
   end
 end

config/environment.rb

@@ -5,3 +5,15 @@
 
 # Initialize the Rails application.
 Rails.application.initialize!
+
+# ── Frontend URL Configuration ──
+raise "FRONTEND_DOMAIN must be configured via environment variables or config/environments/*.rb files" if Rails.configuration.x.frontend_domain.blank?
+
+# This runs after all environment files are loaded, so environment-specific defaults are available
+# URI::Generic.build expects nil for no port, but ENV vars are strings, so convert to int and back to handle blank/zero cases
+uri = URI::Generic.build(
+  scheme: Rails.configuration.x.frontend_scheme,
+  host:   Rails.configuration.x.frontend_domain,
+  port:   Rails.configuration.x.frontend_port.to_i.nonzero?
+)
+FRONTEND_URL = uri.to_s

config/environments/development.rb

@@ -37,8 +37,13 @@
 
   # Don't care if the mailer can't send.
   config.action_mailer.raise_delivery_errors = false
-
   config.action_mailer.perform_caching = false
+  config.action_mailer.delivery_method = :smtp
+
+  # Prevent actual emails from being sent in development.
+  # Emails will still be processed and logged, but never leave the server.
+  # Set to true (and configure SMTP env vars) if you need to test real delivery locally.
+  config.action_mailer.perform_deliveries = false
 
   # Print deprecation notices to the Rails logger.
   config.active_support.deprecation = :log
@@ -65,4 +70,11 @@
   # config.action_cable.disable_request_forgery_protection = true
   config.hosts << 'localhost'
   config.hosts << "www.example.com"
+
+  # ── Frontend URL Configuration ──
+  # Set defaults for local development (can be overridden via environment variables)
+  # Rails convention recommends config.x.* for custom settings
+  config.x.frontend_scheme = ENV.fetch('FRONTEND_SCHEME', 'http')
+  config.x.frontend_domain = ENV.fetch('FRONTEND_DOMAIN', 'localhost')
+  config.x.frontend_port = ENV.fetch('FRONTEND_PORT', '3000')
 end

config/environments/production.rb

@@ -58,6 +58,8 @@
   # config.active_job.queue_name_prefix = "reimplementation_production"
 
   config.action_mailer.perform_caching = false
+  config.action_mailer.delivery_method = :smtp
+  config.action_mailer.perform_deliveries = true
 
   # Ignore bad email addresses and do not raise email delivery errors.
   # Set this to true and configure the email server for immediate delivery to raise delivery errors.
@@ -85,4 +87,11 @@
 
   # Do not dump schema after migrations.
   config.active_record.dump_schema_after_migration = false
+
+  # ── Frontend URL Configuration ──
+  # Set defaults for production (can be overridden via environment variables)
+  # Rails convention recommends config.x.* for custom settings
+  config.x.frontend_scheme = ENV.fetch('FRONTEND_SCHEME', 'https')
+  config.x.frontend_domain = ENV.fetch('FRONTEND_DOMAIN', 'expertiza.ncsu.com')
+  config.x.frontend_port = ENV.fetch('FRONTEND_PORT', nil)
 end

config/environments/test.rb

@@ -44,6 +44,8 @@
   # The :test delivery method accumulates sent emails in the
   # ActionMailer::Base.deliveries array.
   config.action_mailer.delivery_method = :test
+  config.action_mailer.perform_deliveries = true
+
   # This line let us to use expect(...).to have_enqueued_job.on_queue('mailers')
   config.active_job.queue_adapter = :test
   # Print deprecation notices to the stderr.
@@ -62,4 +64,11 @@
   # config.action_view.annotate_rendered_view_with_filenames = true
   config.hosts << 'localhost'
   config.hosts << "www.example.com"
+
+  # ── Frontend URL Configuration ──
+  # Set defaults for tests (can be overridden via environment variables)
+  # Rails convention recommends config.x.* for custom settings
+  config.x.frontend_scheme = ENV.fetch('FRONTEND_SCHEME', 'http')
+  config.x.frontend_domain = ENV.fetch('FRONTEND_DOMAIN', 'localhost')
+  config.x.frontend_port = ENV.fetch('FRONTEND_PORT', '3000')
 end

config/locales/en.yml

@@ -30,4 +30,12 @@
 # available at https://guides.rubyonrails.org/i18n.html.
 
 en:
-  hello: "Hello world"
+  user:
+    errors:
+      password_short: "Password is too short (minimum is 6 characters)"
+  password_reset:
+    email_subject: "Expertiza password reset"
+    email_sent: "If the email exists, a reset link has been sent."
+    updated: "Password successfully updated."
+    errors:
+      token_expired: "The token has expired or is invalid."

config/routes.rb

@@ -214,4 +214,5 @@
       resources :assignments do
         resources :duties, controller: 'assignments_duties', only: [:index, :create, :destroy]
       end
+      resources :password_resets, only: [:create, :update], param: :token
 end

sample.env

@@ -0,0 +1,36 @@
+# ── Frontend Configuration ──
+# Scheme should be either 'http' or 'https'
+# Defaults: 'http' in development/test, 'https' in production
+FRONTEND_SCHEME=
+# The domain of the front-end
+# Defaults: 'localhost' in development/test, 'expertiza.ncsu.com' in production
+# Should be explicitly set in non-development environments (e.g. staging, production)
+# Examples: 'localhost' (dev/test), 'staging.expertiza.ncsu.edu' (staging), 'expertiza.ncsu.com' (production)
+FRONTEND_DOMAIN=
+# Optional: Port number for the frontend service
+# Defaults: 3000 in development/test, omitted (standard port) in production
+# Omit this (or leave blank) to use standard ports (80 for http, 443 for https)
+# Examples: '3000' (dev/test), '8443' (custom HTTPS port)
+FRONTEND_PORT=
+
+# ── Mailer Configuration ──
+# All values are optional in development; see config/application.rb for defaults.
+# In production, set at minimum MAILER_SERVER, MAILER_USER, and MAILER_PASSWORD.
+
+# MAILER_USER: the email address used to authenticate with the SMTP server (e.g. no-reply@example.com)
+# When blank, authentication is skipped entirely.
+MAILER_USER=
+# MAILER_PASSWORD: the password or app-specific password for the MAILER_USER account
+MAILER_PASSWORD=
+# MAILER_SERVER: the hostname of your outgoing SMTP server (e.g. smtp.gmail.com)
+# Defaults to "localhost" if unset.
+MAILER_SERVER=
+# MAILER_SERVER_PORT: the port used by the SMTP server (commonly 587 for STARTTLS, 25 for unencrypted)
+# Defaults to 587 if unset.
+MAILER_SERVER_PORT=
+# MAILER_DOMAIN: the HELO/EHLO domain sent to the SMTP server (e.g. example.com)
+# Defaults to "localhost" if unset.
+MAILER_DOMAIN=
+# MAILER_ENABLE_STARTTLS: set to "false" to disable STARTTLS (e.g. for local relays that don't support TLS)
+# Defaults to "true" if unset.
+MAILER_ENABLE_STARTTLS=