create signup code (including email verification), as well as some login models such as refresh tokens (but no implementation created)

mailers also introduced as well

Author: mattsoh

backend/Gemfile.lock

@@ -74,6 +74,7 @@ GEM
       uri (>= 0.13.1)
     ast (2.4.3)
     base64 (0.3.0)
+    bcrypt (3.1.20)
     bcrypt_pbkdf (1.1.1)
     benchmark (0.5.0)
     bigdecimal (3.3.1)
@@ -109,6 +110,8 @@ GEM
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
     json (2.15.2)
+    jwt (3.0.0)
+      base64
     kamal (2.8.2)
       activesupport (>= 7.0)
       base64 (~> 0.2)
@@ -161,6 +164,8 @@ GEM
       racc (~> 1.4)
     nokogiri (1.18.10-arm64-darwin)
       racc (~> 1.4)
+    nokogiri (1.18.10-x64-mingw-ucrt)
+      racc (~> 1.4)
     nokogiri (1.18.10-x86_64-linux-gnu)
       racc (~> 1.4)
     nokogiri (1.18.10-x86_64-linux-musl)
@@ -174,6 +179,7 @@ GEM
     pg (1.6.2-aarch64-linux)
     pg (1.6.2-aarch64-linux-musl)
     pg (1.6.2-arm64-darwin)
+    pg (1.6.2-x64-mingw-ucrt)
     pg (1.6.2-x86_64-linux)
     pg (1.6.2-x86_64-linux-musl)
     pp (0.6.3)
@@ -300,6 +306,8 @@ GEM
     tsort (0.2.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
+    tzinfo-data (1.2025.2)
+      tzinfo (>= 1.0.0)
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
     unicode-emoji (4.1.0)
@@ -318,14 +326,17 @@ PLATFORMS
   arm-linux-gnu
   arm-linux-musl
   arm64-darwin-24
+  x64-mingw-ucrt
   x86_64-linux
   x86_64-linux-gnu
   x86_64-linux-musl
 
 DEPENDENCIES
+  bcrypt (~> 3.1.7)
   bootsnap
   brakeman
   debug
+  jwt
   kamal
   pg (~> 1.1)
   puma (>= 5.0)

backend/app/controllers/api/v1/auth_controller.rb

@@ -0,0 +1,109 @@
+module Api
+  module V1
+    class AuthController < ApplicationController
+      def signup
+        user = User.new(signup_params)
+
+        unless user.valid?
+          return render json: { errors: user.errors.full_messages }, status: :unprocessable_entity
+        end
+
+        payload = user.attributes.slice(
+          "first_name",
+          "last_name",
+          "preferred_name",
+          "username",
+          "email",
+          "password_digest"
+        )
+
+        EmailVerification.issue_for(user.email, payload)
+
+        render json: {
+          message: "Verification code sent"
+        }, status: :created
+      end
+
+      def resend_email_verification
+        email = params[:email].to_s
+
+        if email.blank?
+          return render json: { error: "Email is required" }, status: :unprocessable_entity
+        end
+
+        unless email.match?(URI::MailTo::EMAIL_REGEXP)
+          return render json: { error: "Invalid email format" }, status: :unprocessable_entity
+        end
+
+        if User.exists?(email: email.strip.downcase)
+          return render json: { error: "Account already verified" }, status: :unprocessable_entity
+        end
+
+        pending = EmailVerification.latest_for(email)
+
+        if pending.nil?
+          return render json: { error: "No pending signup" }, status: :not_found
+        end
+
+        EmailVerification.issue_for(email, pending.payload)
+        render json: { message: "Verification code sent" }, status: :ok
+      end
+
+      def verify_email
+        email = params[:email].to_s
+        code = params[:email_code].to_s
+
+        if email.blank? || code.blank?
+          return render json: { error: "Email and email_code are required" }, status: :unprocessable_entity
+        end
+
+        unless email.match?(URI::MailTo::EMAIL_REGEXP)
+          return render json: { error: "Invalid email format" }, status: :unprocessable_entity
+        end
+
+        pending = EmailVerification.active.find_by(email: email.strip.downcase)
+
+        if pending.nil?
+          return render json: { error: "Invalid or expired code" }, status: :unprocessable_entity
+        end
+
+        unless EmailVerification.consume!(email, code)
+          return render json: { error: "Invalid or expired code" }, status: :unprocessable_entity
+        end
+
+        user = User.new(pending.payload)
+
+        if user.save
+          render json: { user: user_payload(user), message: "Account created" }, status: :created
+        else
+          render json: { errors: user.errors.full_messages }, status: :unprocessable_entity
+        end
+      end
+
+      private
+
+      def signup_params
+        params.fetch(:user, params).permit(
+          :first_name,
+          :last_name,
+          :preferred_name,
+          :username,
+          :email,
+          :password,
+          :password_confirmation
+        )
+      end
+
+      def user_payload(user)
+        {
+          id: user.id,
+          first_name: user.first_name,
+          last_name: user.last_name,
+          preferred_name: user.preferred_name,
+          username: user.username,
+          email: user.email
+        }
+      end
+    end
+  end
+end

backend/app/mailers/application_mailer.rb

@@ -1,4 +1,7 @@
 class ApplicationMailer < ActionMailer::Base
-  default from: "from@example.com"
+  DEFAULT_FROM_EMAIL = "auth@youthacks.org"
+
+  default from: ENV.fetch("FROM_EMAIL", DEFAULT_FROM_EMAIL)
   layout "mailer"
 end
+

backend/app/mailers/user_mailer.rb

@@ -0,0 +1,12 @@
+class UserMailer < ApplicationMailer
+  # Subject can be set in your I18n file at config/locales/en.yml
+  # with the following lookup:
+  #
+  #   en.user_mailer.verification_code.subject
+  #
+  def verification_code
+    @code = params[:code]
+    @expires_in = params[:expires_in] || 15 # default to 15 minutes
+    mail(to: params[:email], subject: "Your verification code")
+  end
+end

backend/app/models/email_verification.rb

@@ -0,0 +1,55 @@
+require "digest"
+
+class EmailVerification < ApplicationRecord
+	TTL = 10.minutes
+
+	validates :email, :code_digest, :expires_at, :payload, presence: true
+	validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }
+
+	scope :active, -> { where(used_at: nil).where(arel_table[:expires_at].gt(Time.current)) }
+
+	def self.issue_for(email, payload)
+		normalized = normalize_email(email)
+		raw_code = format("%06d", SecureRandom.random_number(1_000_000))
+		record = nil
+
+		transaction do
+			where(email: normalized).delete_all
+			record = create!(
+				email: normalized,
+				code_digest: digest(raw_code),
+				expires_at: TTL.from_now,
+				payload: payload
+			)
+		end
+
+		UserMailer.with(email: normalized, code: raw_code, expires_in: (TTL / 60)).verification_code.deliver_later
+		record
+	end
+
+	def self.latest_for(email)
+		normalized = normalize_email(email)
+		where(email: normalized).order(created_at: :desc).first
+	end
+
+	def self.consume!(email, code)
+		normalized = normalize_email(email)
+		record = active.find_by(email: normalized)
+		return false if record.nil?
+
+		unless ActiveSupport::SecurityUtils.secure_compare(record.code_digest, digest(code))
+			return false
+		end
+
+		record.update!(used_at: Time.current)
+		true
+	end
+
+	def self.digest(code)
+		Digest::SHA256.hexdigest(code.to_s)
+	end
+
+	def self.normalize_email(email)
+		email.to_s.strip.downcase
+	end
+end

backend/app/models/refresh_token.rb

@@ -0,0 +1,36 @@
+require "digest"
+
+class RefreshToken < ApplicationRecord
+  TTL = 30.days
+
+  belongs_to :user
+
+  validates :token_digest, presence: true, uniqueness: true
+  validates :expires_at, presence: true
+
+  scope :active, -> { where(revoked_at: nil).where("expires_at > ?", Time.current) }
+
+  def self.issue_for(user, request)
+    raw_token = SecureRandom.hex(32)
+    create!(
+      user: user,
+      token_digest: digest(raw_token),
+      expires_at: TTL.from_now,
+      user_agent: request.user_agent.to_s,
+      ip_address: request.remote_ip.to_s
+    )
+    raw_token
+  end
+
+  def self.digest(raw_token)
+    Digest::SHA256.hexdigest(raw_token.to_s)
+  end
+
+  def revoke!
+    update!(revoked_at: Time.current)
+  end
+
+  def expired?
+    expires_at <= Time.current
+  end
+end

backend/app/models/user.rb

@@ -0,0 +1,26 @@
+class User < ApplicationRecord
+	has_secure_password
+
+	has_many :refresh_tokens, dependent: :delete_all
+
+	validates :first_name, :last_name, :username, :email, presence: true
+	validates :email, :username, uniqueness: true
+	validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }
+
+	before_validation :normalize_identity
+
+	def display_name
+		preferred_name.presence || first_name
+	end
+
+	def locked?
+		locked_at.present?
+	end
+
+	private
+
+	def normalize_identity
+		self.email = email.to_s.strip.downcase.presence
+		self.username = username.to_s.strip.downcase.presence
+	end
+end

backend/app/views/user_mailer/verification_code.html.erb

@@ -0,0 +1,3 @@
+<p>Your verification code is:</p>
+<p><strong><%= @code %></strong></p>
+<p>This code expires in <%= @expires_in %> minutes.</p>

backend/app/views/user_mailer/verification_code.text.erb

@@ -0,0 +1,3 @@
+Your verification code is: <%= @code %>
+
+This code expires in <%= @expires_in %> minutes.

backend/config/routes.rb

@@ -5,6 +5,14 @@
   # Can be used by load balancers and uptime monitors to verify that the app is live.
   get "up" => "rails/health#show", as: :rails_health_check
 
+  namespace :api do
+    namespace :v1 do
+      post "auth/signup", to: "auth#signup"
+      post "auth/resend_email_verification", to: "auth#resend_email_verification"
+      post "auth/verify_email", to: "auth#verify_email"
+    end
+  end
+
   # Defines the root path route ("/")
   # root "posts#index"
 end