gemstack-auth 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 07da1fb0891a46be619884f39979d2f3be08c87fbc629b5a001cdfc20bc20ab1
+  data.tar.gz: aadbd0585749e3e9ec04895cb720391bdf9187de4326e27fb91b83a94cb7e253
+SHA512:
+  metadata.gz: 2adc7daafeceafa6e4a8242b32f53941ee148a242529b53b83d6272371afa323b3cf3062896ee342b090b65fdc761829a63a6149bd342df280f0ad52ac31fb79
+  data.tar.gz: 808dd380d6312bcfdf198b326901b88c12220bf98cd4991a0682bee4b7f66a31b1635a5c36d03cb58c795d43eceff22b04100035b5e94c9e3d3abba201e58305

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+First release. See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shoaib Malik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,28 @@
+# gemstack-auth
+
+GemStack auth: Argon2id passwords, cookie sessions, API tokens, policies.
+
+Part of [GemStack](https://github.com/gemstack-rb/gemstack), a modular Ruby API framework for Next.js
+applications. All GemStack gems are developed together in that repository and released with the same
+version.
+
+## Installation
+
+Optional module — `gemstack add auth`:
+
+```ruby
+gem "gemstack-auth", "~> 0.1"
+```
+
+## Documentation
+
+- [Guide](https://github.com/gemstack-rb/gemstack/blob/main/docs/authentication.md)
+- [All guides](https://github.com/gemstack-rb/gemstack/tree/main/docs) ·
+  [Architecture](https://github.com/gemstack-rb/gemstack/blob/main/ARCHITECTURE.md)
+
+Source, issues and pull requests: [gemstack-rb/gemstack](https://github.com/gemstack-rb/gemstack)
+(this gem lives in `gems/gemstack-auth`).
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/lib/gemstack/auth/controller.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module GemStack
+  module Auth
+    # Authentication for controllers:
+    #
+    #   class ApplicationController < GemStack::Controller
+    #     include GemStack::Auth::Controller
+    #   end
+    #
+    #   class OrdersController < ApplicationController
+    #     before :require_login
+    #     def index = render(current_user.orders_dataset)
+    #   end
+    #
+    # A request is authenticated by the session cookie (browsers) or by
+    # `Authorization: Bearer <api token>` (scripts, other services).
+    #
+    # Cross-site request forgery: state-changing requests (POST, PUT, PATCH,
+    # DELETE) from other sites are refused with 403 unless the origin is in
+    # config.auth.trusted_origins. Browsers label every request with
+    # Sec-Fetch-Site / Origin; clients that send neither (curl, servers) are
+    # not browsers and can't carry a victim's cookie (DECISIONS D-051).
+    module Controller
+      SAFE_METHODS = %w[GET HEAD OPTIONS].freeze
+
+      def self.included(base)
+        base.include(RateLimit)
+        base.include(Policy::Authorization)
+        base.before :verify_request_origin
+      end
+
+      # The signed-in user, or nil.
+      def current_user
+        return @current_user if defined?(@current_user)
+
+        @current_user = authenticate_request
+      end
+
+      def signed_in? = !current_user.nil?
+
+      # :session, :token, or nil.
+      def authenticated_by
+        current_user
+        @authenticated_by
+      end
+
+      # The current `sessions` row (cookie authentication only).
+      def current_session
+        current_user
+        @current_session
+      end
+
+      # before :require_login — 401 for anonymous requests.
+      def require_login
+        raise Unauthorized.new("Sign in to continue.", code: "unauthenticated") unless current_user
+      end
+
+      # Starts a session: a new token (never reuses one the browser already
+      # had, which would allow session fixation) in an HttpOnly cookie.
+      def sign_in(user)
+        Sessions.revoke(session_cookie) if session_cookie
+        token = Sessions.create(user.id, ip: request.ip, user_agent: request.user_agent)
+        write_session_cookie(token)
+        @current_session = Sessions.find(token)
+        @authenticated_by = :session
+        @current_user = user
+      end
+
+      def sign_out
+        Sessions.revoke(session_cookie) if session_cookie
+        delete_session_cookie
+        @current_session = nil
+        @authenticated_by = nil
+        @current_user = nil
+      end
+
+      private
+
+      def authenticate_request
+        if (token = bearer_token)
+          row = Tokens.find(token, purpose: "api") or return nil
+          @authenticated_by = :token
+          Auth.user_class[row[:user_id]]
+        elsif (token = session_cookie)
+          session = Sessions.find(token)
+          unless session
+            delete_session_cookie # expired or revoked: stop sending it
+            return nil
+          end
+
+          write_session_cookie(token) if session[:touched] # slide the cookie's expiry too
+          @current_session = session
+          @authenticated_by = :session
+          Auth.user_class[session[:user_id]]
+        end
+      end
+
+      def bearer_token
+        header = request.get_header("HTTP_AUTHORIZATION").to_s
+        header[/\ABearer\s+(\S+)\z/i, 1]
+      end
+
+      def session_cookie
+        value = request.cookies[Auth.config.cookie_name]
+        value.nil? || value.empty? ? nil : value
+      end
+
+      def write_session_cookie(token)
+        config = Auth.config
+        replace_cookie(Rack::Utils.set_cookie_header(
+                         config.cookie_name,
+                         value: token, path: "/", httponly: true, secure: config.cookie_secure,
+                         same_site: config.cookie_same_site, max_age: config.session_ttl.to_s
+                       ))
+      end
+
+      def delete_session_cookie
+        config = Auth.config
+        replace_cookie(Rack::Utils.set_cookie_header(
+                         config.cookie_name,
+                         value: "", path: "/", httponly: true, secure: config.cookie_secure,
+                         same_site: config.cookie_same_site, max_age: "0", expires: Time.at(0)
+                       ))
+      end
+
+      def replace_cookie(line)
+        existing = headers["set-cookie"]
+        name = line[/\A[^=]+/]
+        kept = Array(existing).reject { |cookie| cookie.start_with?("#{name}=") }
+        headers["set-cookie"] = kept.empty? ? line : kept + [line]
+      end
+
+      def verify_request_origin
+        return if SAFE_METHODS.include?(request.request_method)
+        return if bearer_token && !session_cookie # custom headers can't be sent cross-site without CORS
+        return if same_origin_request?
+
+        raise Forbidden.new("Cross-site request refused.", code: "cross_site_request")
+      end
+
+      def same_origin_request?
+        origin = request.get_header("HTTP_ORIGIN")
+        return true if origin && Array(Auth.config.trusted_origins).include?(origin)
+
+        site = request.get_header("HTTP_SEC_FETCH_SITE")
+        return %w[same-origin none].include?(site) if site
+        return true if origin.nil? || origin.empty?
+
+        hosts = [request.host_with_port, request.get_header("HTTP_X_FORWARDED_HOST")].compact
+        host = URI.parse(origin).then { |uri| [uri.host, uri.port].join(":") }
+        hosts.any? { |value| normalize_host(value, origin) == host }
+      rescue URI::InvalidURIError
+        false
+      end
+
+      def normalize_host(value, origin)
+        host, port = value.split(",").first.strip.split(":", 2)
+        port ||= origin.start_with?("https:") ? "443" : "80"
+        "#{host}:#{port}"
+      end
+    end
+  end
+end

data/lib/gemstack/auth/password.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "argon2"
+
+module GemStack
+  module Auth
+    # Password hashing with Argon2id (DECISIONS D-049). Hashes from other
+    # systems in bcrypt format still verify (add gem "bcrypt") and are
+    # upgraded to Argon2id on the next successful login.
+    module Password
+      class << self
+        def create(plain)
+          config = Auth.config
+          Argon2::Password.new(t_cost: config.argon2_t_cost, m_cost: config.argon2_m_cost, p_cost: 1).create(plain)
+        end
+
+        def verify(plain, digest)
+          return false unless plain.is_a?(String) && digest.is_a?(String)
+          return false if plain.bytesize > 1024 # never spend hashing time on megabyte "passwords"
+
+          if digest.start_with?("$argon2")
+            Argon2::Password.verify_password(plain, digest)
+          elsif digest.match?(/\A\$2[aby]\$/)
+            bcrypt.new(digest) == plain
+          else
+            false
+          end
+        rescue Argon2::ArgonHashFail
+          false
+        end
+
+        # True for bcrypt hashes and Argon2 hashes weaker than the current settings.
+        def needs_rehash?(digest)
+          match = digest.to_s.match(/\A\$argon2id\$v=\d+\$m=(\d+),t=(\d+),p=\d+\$/) or return true
+          config = Auth.config
+          match[1].to_i < (1 << config.argon2_m_cost) || match[2].to_i < config.argon2_t_cost
+        end
+
+        # Spends the same time as a real verification, so "no such user" and
+        # "wrong password" can't be told apart by timing.
+        def verify_dummy(plain)
+          @dummy ||= create(SecureRandom.hex(16))
+          verify(plain.to_s[0, 1024], @dummy)
+          false
+        end
+
+        # Validation messages for a new password (length only, per NIST SP 800-63B).
+        def errors(plain)
+          config = Auth.config
+          length = plain.to_s.length
+          if plain.to_s.strip.empty? then ["is required"]
+          elsif length < config.password_min_length
+            ["is too short (minimum #{config.password_min_length} characters)"]
+          elsif length > config.password_max_length
+            ["is too long (maximum #{config.password_max_length} characters)"]
+          else []
+          end
+        end
+
+        def reset_dummy! = @dummy = nil
+
+        private
+
+        def bcrypt
+          require "bcrypt"
+          BCrypt::Password
+        rescue LoadError
+          raise ConfigurationError, "this password hash is bcrypt; add gem \"bcrypt\" to verify it"
+        end
+      end
+    end
+  end
+end

data/lib/gemstack/auth/rate_limit.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module GemStack
+  module Auth
+    # Fixed-window rate limits for controller actions, counted in
+    # GemStack.cache (use a shared store — :redis — with several servers).
+    #
+    #   rate_limit to: 10, within: 60, only: :create                        # per client IP
+    #   rate_limit to: 3, within: 3600, only: :create, name: "forgot-email",
+    #              by: -> { params[:email].to_s.downcase }
+    #
+    # Over the limit: 429 with Retry-After.
+    module RateLimit
+      def self.included(base) = base.extend(ClassMethods)
+
+      module ClassMethods
+        def rate_limit(to:, within:, by: -> { request.ip }, only: nil, except: nil, name: nil)
+          limit = Integer(to)
+          period = Integer(within)
+          before(only: only, except: except) { enforce_rate_limit(limit, period, by, name) }
+        end
+      end
+
+      private
+
+      def enforce_rate_limit(limit, period, by, name)
+        subject = instance_exec(&by).to_s
+        return if subject.empty?
+
+        now = Time.now.to_i
+        key = ["rate-limit", name || "#{self.class.name}##{action_name}", Digest::SHA256.hexdigest(subject)[0, 32],
+               now / period]
+        return if GemStack.cache.increment(key, expires_in: period) <= limit
+
+        retry_after = period - (now % period)
+        raise TooManyRequests.new("Too many attempts. Try again in #{retry_after} seconds.",
+                                  code: "rate_limited", headers: { "retry-after" => retry_after.to_s })
+      end
+    end
+  end
+end

data/lib/gemstack/auth/sessions.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module GemStack
+  module Auth
+    # Browser sessions, one row per signed-in device in the `sessions` table.
+    # Being rows (not signed cookies), they can be listed and revoked:
+    # signing out everywhere or resetting a password really ends them.
+    module Sessions
+      class << self
+        def dataset = Auth.db[:sessions]
+
+        # Returns the token to put in the cookie.
+        def create(user_id, ip: nil, user_agent: nil)
+          token = Token.generate
+          now = Time.now
+          dataset.insert(token_digest: Token.digest(token), user_id: user_id, ip: ip,
+                         user_agent: user_agent&.slice(0, 255), created_at: now, last_seen_at: now,
+                         expires_at: now + Auth.config.session_ttl)
+          token
+        end
+
+        # The live session for a token, or nil. Extends the expiry (at most
+        # once per session_touch_interval); row[:touched] tells the caller to
+        # re-send the cookie with the new expiry.
+        def find(token)
+          return nil unless Token.plausible?(token)
+
+          now = Time.now
+          row = dataset.where(token_digest: Token.digest(token)).where { expires_at > now }.first or return nil
+          if row[:last_seen_at] <= now - Auth.config.session_touch_interval
+            expires = now + Auth.config.session_ttl
+            dataset.where(id: row[:id]).update(last_seen_at: now, expires_at: expires)
+            row = row.merge(last_seen_at: now, expires_at: expires, touched: true)
+          end
+          row
+        end
+
+        def revoke(token) = Token.plausible?(token) ? dataset.where(token_digest: Token.digest(token)).delete : 0
+
+        # Ends every session of a user (optionally keeping one, by id).
+        def revoke_all(user_id, except: nil)
+          scope = dataset.where(user_id: user_id)
+          scope = scope.exclude(id: except) if except
+          scope.delete
+        end
+
+        def for_user(user_id)
+          dataset.where(user_id: user_id).where { expires_at > Time.now }.order(Sequel.desc(:last_seen_at)).all
+        end
+      end
+    end
+  end
+end

data/lib/gemstack/auth/testing.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "gemstack/auth"
+
+module GemStack
+  module Auth
+    # Test helpers (added to GemStack::TestCase by `gemstack add auth`):
+    #
+    #   sign_in_as(user)                     # later requests carry the session cookie
+    #   get_json "/api/auth/me"
+    #   get_json "/api/orders", {}, bearer_headers(user)
+    module Testing
+      def sign_in_as(user)
+        token = Sessions.create(user.id, ip: "127.0.0.1", user_agent: "test")
+        set_cookie("#{Auth.config.cookie_name}=#{token}")
+        token
+      end
+
+      def api_token_for(user, name: "test") = Tokens.issue(user.id, purpose: "api", name: name).first
+
+      def bearer_headers(user) = { "HTTP_AUTHORIZATION" => "Bearer #{api_token_for(user)}" }
+    end
+  end
+end

data/lib/gemstack/auth/tokens.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module GemStack
+  module Auth
+    # Tokens in the `auth_tokens` table:
+    #   "api"                 long-lived bearer tokens (Authorization: Bearer gs_…)
+    #   "password_reset"      single use, short-lived, emailed
+    #   "email_verification"  single use, emailed, bound to the address it was sent to
+    module Tokens
+      PURPOSES = %w[api password_reset email_verification].freeze
+      PREFIX = { "api" => "gs_" }.freeze
+      # last_used_at is written at most once a minute per token.
+      TOUCH_INTERVAL = 60
+
+      class << self
+        def dataset = Auth.db[:auth_tokens]
+
+        # Returns [token, row id]. The plain token is shown to the user once
+        # and never stored. Issuing a reset/verification token invalidates the
+        # user's earlier ones for the same purpose.
+        def issue(user_id, purpose:, name: nil, email: nil, expires_in: default_ttl(purpose))
+          check_purpose!(purpose)
+          dataset.where(user_id: user_id, purpose: purpose).delete unless purpose == "api"
+          token = Token.generate(PREFIX.fetch(purpose, ""))
+          now = Time.now
+          id = dataset.insert(user_id: user_id, purpose: purpose, token_digest: Token.digest(token), name: name,
+                              email: email, created_at: now, expires_at: expires_in && (now + expires_in))
+          [token, id]
+        end
+
+        # The live token row, or nil. API tokens record when they were last used.
+        def find(token, purpose:)
+          check_purpose!(purpose)
+          return nil unless Token.plausible?(token)
+
+          now = Time.now
+          row = live(token, purpose, now).first or return nil
+          if purpose == "api" && (row[:last_used_at].nil? || row[:last_used_at] <= now - TOUCH_INTERVAL)
+            dataset.where(id: row[:id]).update(last_used_at: now)
+          end
+          row
+        end
+
+        # Uses up a single-use token: deletes and returns its row, atomically,
+        # so two concurrent requests can't both use one reset link.
+        def consume(token, purpose:)
+          check_purpose!(purpose)
+          return nil unless Token.plausible?(token)
+
+          live(token, purpose, Time.now).returning.delete.first
+        end
+
+        def revoke(id, user_id:) = dataset.where(id: id, user_id: user_id).delete.positive?
+        def revoke_all(user_id, purpose:) = dataset.where(user_id: user_id, purpose: purpose).delete
+
+        def for_user(user_id, purpose: "api")
+          dataset.where(user_id: user_id, purpose: purpose).order(Sequel.desc(:created_at))
+                 .select(:id, :name, :created_at, :last_used_at, :expires_at).all
+        end
+
+        private
+
+        def live(token, purpose, now)
+          dataset.where(token_digest: Token.digest(token), purpose: purpose)
+                 .where(Sequel.|({ expires_at: nil }, Sequel[:expires_at] > now))
+        end
+
+        def default_ttl(purpose)
+          config = Auth.config
+          { "api" => config.api_token_ttl, "password_reset" => config.password_reset_ttl,
+            "email_verification" => config.email_verification_ttl }.fetch(purpose)
+        end
+
+        def check_purpose!(purpose)
+          raise ArgumentError, "unknown token purpose #{purpose.inspect}" unless PURPOSES.include?(purpose)
+        end
+      end
+    end
+  end
+end

data/lib/gemstack/auth/user.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module GemStack
+  module Auth
+    # Password and email behaviour for the user model:
+    #
+    #   class User < GemStack::Model
+    #     include GemStack::Auth::User
+    #   end
+    #
+    #   User.create(email: "Ada@Example.com", password: "correct horse battery")
+    #   User.authenticate_by(email: "ada@example.com", password: "…")  # => user or nil
+    #
+    # Needs the columns email (unique) and password_digest; email_verified_at
+    # for verification.
+    module User
+      EMAIL_FORMAT = /\A[^@\s]+@[^@\s.]+(\.[^@\s.]+)+\z/
+
+      def self.included(model) = model.extend(ClassMethods)
+
+      module ClassMethods
+        def normalize_email(email) = email.to_s.unicode_normalize(:nfkc).strip.downcase
+
+        # The user when the password matches; nil otherwise, in about the same
+        # time whether or not the email exists.
+        def authenticate_by(email:, password:)
+          user = first(email: normalize_email(email))
+          return user if user&.authenticate(password)
+
+          Password.verify_dummy(password) unless user
+          nil
+        end
+      end
+
+      attr_reader :password
+
+      def email=(value)
+        self[:email] = value.nil? ? nil : self.class.normalize_email(value)
+      end
+
+      # Hashed right away (when the length is acceptable); the plain text is
+      # kept in memory only for validation.
+      def password=(plain)
+        @password = plain
+        self[:password_digest] = Password.errors(plain).empty? ? Password.create(plain) : nil
+      end
+
+      # Verifies a password; upgrades the stored hash when the settings changed.
+      def authenticate(plain)
+        return false unless Password.verify(plain, self[:password_digest])
+
+        if Password.needs_rehash?(self[:password_digest])
+          digest = Password.create(plain)
+          this.update(password_digest: digest)
+          self[:password_digest] = digest
+        end
+        true
+      end
+
+      def email_verified? = !self[:email_verified_at].nil?
+
+      def validate
+        super
+        errors.add(:email, "is invalid") unless self[:email].to_s.match?(EMAIL_FORMAT) || errors.on(:email)
+        Password.errors(@password).each { |message| errors.add(:password, message) } if new? || !@password.nil?
+        return unless self[:email] && (new? || changed_columns.include?(:email))
+
+        validates_unique(:email,
+                         message: "is already taken")
+      end
+    end
+  end
+end

data/lib/gemstack/auth.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "securerandom"
+require "gemstack/core"
+require "gemstack/cache"
+require "gemstack/http"
+require "gemstack/db"
+require "gemstack/mail"
+
+module GemStack
+  # Authentication (DECISIONS D-048..D-052): Argon2id passwords, database
+  # sessions in an HttpOnly cookie for the Next.js frontend, and bearer API
+  # tokens for scripts and other services. `gemstack add auth` generates the
+  # tables, the User model, the controllers, the emails and the Next.js pages
+  # that use this module — all of it application code you can change.
+  module Auth
+    class Config < Settings
+      # The model that includes GemStack::Auth::User.
+      setting :user_class, default: "User"
+      # Sessions expire after this many seconds without use (sliding).
+      setting :session_ttl, default: 30 * 24 * 3600
+      # last_seen_at / expiry are updated at most this often (one UPDATE per session per interval).
+      setting :session_touch_interval, default: 300
+      # Secure cookies are HTTPS-only; local development runs on http://localhost.
+      setting :cookie_secure, default: -> { !GemStack.env.local? }
+      # The __Host- prefix makes browsers refuse the cookie unless it is Secure,
+      # host-only and Path=/ — no subdomain can set or overwrite it.
+      setting :cookie_name, default: -> { cookie_secure ? "__Host-session" : "gemstack_session" }
+      setting :cookie_same_site, default: :lax
+      setting :password_reset_ttl, default: 3600
+      setting :email_verification_ttl, default: 3 * 24 * 3600
+      # nil: API tokens don't expire (they can be revoked); or seconds.
+      setting :api_token_ttl, default: nil
+      setting :password_min_length, default: 12
+      setting :password_max_length, default: 128
+      # Argon2id cost: t = iterations, m = log2(memory KiB). 2 / 2^15 (32 MiB)
+      # takes ~35 ms per hash on a 2024 laptop (OWASP's minimum is 19 MiB).
+      setting :argon2_t_cost, default: -> { GemStack.env.test? ? 1 : 2 }
+      setting :argon2_m_cost, default: -> { GemStack.env.test? ? 8 : 15 }
+      # Other origins allowed to make cookie-authenticated, state-changing
+      # requests (e.g. "https://admin.example.com"). Same-origin always works.
+      setting :trusted_origins, default: []
+      # Where the frontend lives, for links in emails.
+      setting :app_url, default: -> { ENV.fetch("APP_URL", "http://localhost:#{ENV.fetch("PORT", "3000")}") }
+    end
+
+    class << self
+      def config = GemStack.config.auth
+
+      def user_class
+        name = config.user_class
+        name.is_a?(String) ? Object.const_get(name) : name
+      end
+
+      def db = DB.connection
+
+      # Deletes expired sessions and tokens; run it daily from a job.
+      def cleanup!
+        now = Time.now
+        { sessions: db[:sessions].where { expires_at <= now }.delete,
+          auth_tokens: db[:auth_tokens].exclude(expires_at: nil).where { expires_at <= now }.delete }
+      end
+
+      # A link into the frontend: Auth.url("/reset-password", token: t)
+      def url(path, **query)
+        base = config.app_url.to_s.chomp("/")
+        query.empty? ? "#{base}#{path}" : "#{base}#{path}?#{URI.encode_www_form(query)}"
+      end
+    end
+
+    # Opaque random tokens; only their SHA-256 digests are stored, so a
+    # database leak doesn't hand out working sessions or reset links.
+    module Token
+      def self.generate(prefix = "") = "#{prefix}#{SecureRandom.urlsafe_base64(32)}"
+      def self.digest(token) = OpenSSL::Digest::SHA256.hexdigest(token.to_s)
+
+      # Tokens are 43–50 characters; anything else is not worth a query.
+      def self.plausible?(token) = token.is_a?(String) && token.bytesize.between?(20, 200)
+    end
+  end
+end
+
+require_relative "auth/password"
+require_relative "auth/sessions"
+require_relative "auth/tokens"
+require_relative "auth/user"
+require_relative "auth/rate_limit"
+require_relative "auth/controller"
+require_relative "policy"
+
+GemStack::Config.namespace(:auth, GemStack::Auth::Config)

data/lib/gemstack/policy.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module GemStack
+  # Authorization rules, one policy class per model (DECISIONS D-052):
+  #
+  #   class OrderPolicy < GemStack::Policy
+  #     def show? = owner? || user&.admin?
+  #     def update? = owner?
+  #
+  #     class Scope < Scope
+  #       def resolve = user&.admin? ? scope : scope.where(user_id: user&.id)
+  #     end
+  #
+  #     private
+  #
+  #     def owner? = user && record.user_id == user.id
+  #   end
+  #
+  #   class OrdersController < ApplicationController
+  #     def index = render(paginate(policy_scope(Order.order(:id))))
+  #     def show = render(authorize!(Order.find(params[:id])))   # OrderPolicy#show?
+  #   end
+  #
+  # Everything is denied unless a policy method says otherwise.
+  class Policy
+    class NotDefined < Error; end
+
+    attr_reader :user, :record
+
+    def initialize(user, record)
+      @user = user
+      @record = record
+    end
+
+    def index? = false
+    def show? = false
+    def create? = false
+    def update? = false
+    def destroy? = false
+
+    # Narrows a dataset to the records the user may see.
+    class Scope
+      attr_reader :user, :scope
+
+      def initialize(user, scope)
+        @user = user
+        @scope = scope
+      end
+
+      def resolve
+        raise NotDefined, "#{self.class.name}#resolve is not defined; it decides which records a user may list"
+      end
+    end
+
+    # The policy class for a record, a model class or a dataset: Order,
+    # Order.where(...) and an order all use OrderPolicy.
+    def self.for(subject)
+      model = if subject.is_a?(Class) then subject
+              elsif subject.respond_to?(:model) && subject.model.is_a?(Class) then subject.model
+              else subject.class
+              end
+      name = "#{model.name}Policy"
+      Object.const_get(name)
+    rescue NameError => e
+      raise unless e.name.to_s == name.split("::").last || e.name.to_s == name
+
+      raise NotDefined, "#{name} is not defined (create app/policies/#{Inflector.underscore(name)}.rb " \
+                        "or run `gemstack generate policy #{model.name}`)"
+    end
+
+    # Controller helpers (included with GemStack::Auth::Controller by `gemstack add auth`).
+    module Authorization
+      # Returns the record when allowed; 403 otherwise. The rule defaults to
+      # "<action>?" (show → show?); a custom action maps to its own name.
+      def authorize!(record, rule = nil, policy: nil)
+        rule ||= :"#{action_name}?"
+        allowed = (policy || Policy.for(record)).new(policy_user, record).public_send(rule)
+        return record if allowed
+
+        raise Forbidden.new("You are not allowed to do that.", code: "forbidden")
+      end
+
+      def policy_scope(scope, policy: nil) = (policy || Policy.for(scope))::Scope.new(policy_user, scope).resolve
+
+      def policy(record) = Policy.for(record).new(policy_user, record)
+
+      private
+
+      def policy_user = respond_to?(:current_user) ? current_user : nil
+    end
+  end
+end

metadata

@@ -0,0 +1,140 @@
+--- !ruby/object:Gem::Specification
+name: gemstack-auth
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Shoaib Malik
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: argon2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+- !ruby/object:Gem::Dependency
+  name: gemstack-cache
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: gemstack-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: gemstack-db
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: gemstack-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: gemstack-mail
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+email:
+- gemstack26@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/gemstack/auth.rb
+- lib/gemstack/auth/controller.rb
+- lib/gemstack/auth/password.rb
+- lib/gemstack/auth/rate_limit.rb
+- lib/gemstack/auth/sessions.rb
+- lib/gemstack/auth/testing.rb
+- lib/gemstack/auth/tokens.rb
+- lib/gemstack/auth/user.rb
+- lib/gemstack/policy.rb
+homepage: https://github.com/gemstack-rb/gemstack
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/gemstack-rb/gemstack/tree/main/gems/gemstack-auth
+  changelog_uri: https://github.com/gemstack-rb/gemstack/blob/main/gems/gemstack-auth/CHANGELOG.md
+  bug_tracker_uri: https://github.com/gemstack-rb/gemstack/issues
+  documentation_uri: https://github.com/gemstack-rb/gemstack/tree/main/docs
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: 'GemStack auth: Argon2id passwords, cookie sessions, API tokens, policies'
+test_files: []