add_auth 0.2.1

data/lib/add_auth/core/digest/hmac.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module AddAuth
+  module Core
+    module Digest
+      # Rails derives the base secret; Core only receives key material.
+      # Purpose separation remains identical for injected and Rails-derived keys.
+      class Hmac < Base
+        KEY_LENGTH = 32
+
+        def initialize(salt:, secret:)
+          unless salt.is_a?(String) && !salt.strip.empty?
+            raise ArgumentError, "salt must be a nonblank string"
+          end
+          unless secret.is_a?(String) && secret.bytesize >= KEY_LENGTH
+            raise ArgumentError, "secret must contain at least 32 bytes of key material"
+          end
+          @key = OpenSSL::HMAC.digest("SHA256", secret, salt).freeze
+        end
+
+        def digest(token)
+          unless token.is_a?(String) && !token.empty?
+            raise ArgumentError, "token must be a nonempty string"
+          end
+          OpenSSL::HMAC.hexdigest("SHA256", @key, token)
+        end
+
+        def matches?(digest, token)
+          return false unless digest.is_a?(String) && digest.bytesize == 64
+          return false unless token.is_a?(String) && !token.empty?
+
+          OpenSSL.fixed_length_secure_compare(digest, self.digest(token))
+        end
+
+        def inspect = "#<#{self.class} [FILTERED]>"
+      end
+    end
+  end
+end

data/lib/add_auth/core/intake.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module AddAuth
+  module Core
+    class Intake
+      def initialize(digest:, normalizer:, limiter:, challenge:, challenge_on:, challenge_when_unavailable: :closed,
+        on_challenge_unavailable: nil)
+        @digest, @normalizer, @limiter = digest, normalizer, limiter
+        @challenge, @challenge_on = challenge, challenge_on
+        @challenge_when_unavailable = challenge_when_unavailable.to_sym
+        unless %i[closed open].include?(@challenge_when_unavailable)
+          raise ArgumentError, "challenge_when_unavailable must be :closed or :open"
+        end
+        @on_challenge_unavailable = on_challenge_unavailable
+      end
+
+      def call(identifier:, ip:, action:, challenge_token: nil)
+        value = (identifier.is_a?(String) && identifier.valid_encoding? && identifier.bytesize.between?(1, 254)) ? @normalizer.call(identifier) : ""
+        value = "" unless value.is_a?(String) && value.valid_encoding? && value.bytesize.between?(1, 254)
+        ip_ok = @limiter.call(key: @digest.digest("ip:#{ip}:#{action}"), limit: 30)
+        identifier_ok = @limiter.call(key: @digest.digest("identifier:#{value}:#{action}"), limit: 5)
+        return :rate_limited unless ip_ok && identifier_ok
+        return :invalid_credentials if value.to_s.empty?
+        rejection = verify_challenge(ip: ip, action: action, challenge_token: challenge_token)
+        rejection || value
+      end
+
+      def anonymous(ip:, action:, challenge_token: nil)
+        return :rate_limited unless @limiter.call(key: @digest.digest("ip:#{ip}:#{action}"), limit: 30)
+        verify_challenge(ip: ip, action: action, challenge_token: challenge_token) || true
+      end
+
+      private def verify_challenge(ip:, action:, challenge_token:)
+        if @challenge_on.include?(action)
+          result = @challenge.verify(token: challenge_token, remote_ip: ip, action: action)
+          if result.unavailable?
+            return :challenge_unavailable if @challenge_when_unavailable == :closed
+            @on_challenge_unavailable&.call(action: action)
+          elsif result.rejected?
+            return :challenge_rejected
+          end
+        end
+        nil
+      end
+
+      def self.email_available?(config) = config.session.enabled && config.email_link.enabled
+
+      # no-referrer form navigation may send null; this is never a substitute
+      # for the adapter's mandatory session-bound CSRF-token verification.
+      def self.origin_allowed?(origin:, base_url:)
+        origin.nil? || origin == "null" || origin == base_url
+      end
+
+      def self.revoke_after_change?(changes)
+        (changes.keys.map(&:to_s) & %w[password_digest email_address]).any?
+      end
+    end
+  end
+end

data/lib/add_auth/core/maintenance.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module AddAuth
+  module Core
+    # One bounded, replayable pass. Stores repeat cutoffs at mutation time;
+    # returning counts records committed work, never a claim of an empty backlog.
+    class Maintenance
+      def initialize(stores:, options:, enqueue:, clock: Time)
+        @stores, @options, @enqueue, @clock = stores, options, enqueue, clock
+        unless options.batch_size.is_a?(Integer) && (1..1000).cover?(options.batch_size)
+          raise ArgumentError, "maintenance.batch_size must be an integer from 1 to 1000"
+        end
+        %i[session email notification].each do |kind|
+          value = options.public_send(:"#{kind}_retention")
+          valid = value.nil? || (value.is_a?(Numeric) && value.finite? && value >= 0)
+          unless valid
+            raise ArgumentError, "maintenance.#{kind}_retention must be nonnegative seconds or nil"
+          end
+        end
+      end
+
+      def call
+        now, limit = @clock.now, @options.batch_size
+        counts = {}
+        @stores.each do |kind, store|
+          if kind == :ceremony
+            counts[:ceremonies_deleted] = store.purge_expired(before: now, now: now, limit: limit)
+            next
+          end
+          retention = @options.public_send(:"#{kind}_retention")
+          if kind != :session
+            counts[:"#{kind}_payloads_erased"] = store.erase_expired_payloads(now: now, limit: limit)
+            ids = store.pending_ids(now: now, limit: limit)
+            ids.each { |id| @enqueue.call(kind, id) }
+            counts[:"#{kind}_enqueued"] = ids.length
+          end
+          if retention
+            counts[:"#{kind}_deleted"] = store.purge_expired(before: now - retention, now: now, limit: limit)
+          end
+        end
+        counts
+      end
+    end
+  end
+end

data/lib/add_auth/core/rate_limit.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module AddAuth
+  module Core
+    class RateLimit
+      WINDOW = 300
+      STAGGER = 60
+      DURATION = WINDOW + STAGGER
+
+      def initialize(counter:, clock: Time)
+        @counter, @clock = counter, clock
+      end
+
+      def call(key:, limit:)
+        now = @clock.now.to_i
+        # Every rolling five-minute interval fits in at least one of these
+        # overlapping six-minute windows. Atomic increments keep that bound
+        # across workers without a read/modify/write race or a boundary burst.
+        counts = (DURATION / STAGGER).times.map do |phase|
+          bucket = (now - phase * STAGGER) / DURATION
+          @counter.call(key: "add_auth:rate:v2:#{phase}:#{bucket}:#{key}", expires_in: DURATION)
+        end
+        unless counts.all? { |count| count.is_a?(Integer) && count.positive? }
+          raise AddAuth::Error, "rate limit store must support atomic increment"
+        end
+        counts.all? { |count| count <= limit }
+      end
+    end
+  end
+end

data/lib/add_auth/core/security_events.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+
+module AddAuth
+  module Core
+    class SecurityEvents
+      include Delivery
+
+      KINDS = %i[password_changed email_changed passkey_added passkey_removed policy_changed recovery_completed].freeze
+
+      def initialize(store:, digest:, delivery_cipher:, clock: Time, random: SecureRandom)
+        @store, @digest, @cipher, @clock, @random = store, digest, delivery_cipher, clock, random
+      end
+
+      # Called inside the authentication/account mutation transaction. The
+      # encrypted outbox survives an enqueue failure or a process crash.
+      def issue(user:, kind:, at:, recipient: user.email_address)
+        raise ArgumentError, "unsupported security event" unless KINDS.include?(kind.to_sym)
+        unless recipient.is_a?(String) && recipient.valid_encoding? && recipient.bytesize.between?(3, 254) &&
+            recipient.include?("@") && !recipient.match?(/[\r\n]/)
+          raise ArgumentError, "invalid notification recipient"
+        end
+        digest = @digest.digest(@random.urlsafe_base64(32))
+        expires_at = at + 7 * 86_400
+        payload = @cipher.encrypt(token: JSON.generate(recipient: recipient, kind: kind.to_s), digest: digest, expires_at: expires_at)
+        @store.append(user: user, kind: kind.to_s, digest: digest, expires_at: expires_at, delivery_payload: payload, created_at: at)
+      end
+
+      private
+
+      def rejection(_user, record)
+        !record || record.revoked_at || record.expires_at <= @clock.now
+      end
+
+      def delivery_details(_user, record)
+        raw = @cipher.decrypt(payload: record.delivery_payload, digest: record.digest)
+        return unless raw
+        value = JSON.parse(raw)
+        return unless value["kind"] == record.kind && KINDS.map(&:to_s).include?(record.kind)
+        {recipient: value.fetch("recipient"), kind: record.kind}
+      rescue JSON::ParserError, KeyError
+        nil
+      end
+    end
+  end
+end

data/lib/add_auth/core/sessions.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module AddAuth
+  module Core
+    class Sessions
+      Grant = Struct.new(:session, :bearer) do
+        def inspect = "#<AddAuth::Core::Sessions::Grant [FILTERED]>"
+      end
+      class Entry
+        attr_reader :id, :current, :authenticated_with, :authenticated_at, :created_at,
+          :last_seen_at, :expires_at, :ip_address, :user_agent
+
+        def initialize(id:, current:, authenticated_with:, authenticated_at:, created_at:,
+          last_seen_at:, expires_at:, ip_address:, user_agent:)
+          @id, @current, @authenticated_with, @authenticated_at, @created_at = id, current,
+            authenticated_with, authenticated_at, created_at
+          @last_seen_at, @expires_at, @ip_address, @user_agent = last_seen_at, expires_at,
+            ip_address, user_agent
+        end
+
+        def inspect = "#<AddAuth::Core::Sessions::Entry id=#{id} current=#{current.inspect}>"
+      end
+      PATTERN = /\Alk1:[A-Za-z0-9_-]{43}\z/
+      PAGE_SIZE = 50
+      Page = Struct.new(:entries, :next_cursor)
+
+      def initialize(store:, digest:, eligible:, lifetime: 43_200, idle_timeout: 1800,
+        legacy_bridge_until: nil, clock: Time, access_policy: nil)
+        unless [lifetime, idle_timeout].all? { |n| n.is_a?(Numeric) && n.finite? && n.positive? } && idle_timeout <= lifetime
+          raise ArgumentError, "session timeouts must be positive and idle_timeout <= lifetime"
+        end
+        unless legacy_bridge_until.nil? || legacy_bridge_until.is_a?(Time)
+          raise ArgumentError, "legacy_bridge_until must be an absolute Time or nil"
+        end
+        @store, @digest, @eligible, @clock = store, digest, eligible, clock
+        @access_policy = access_policy
+        @lifetime, @idle, @deadline = lifetime, idle_timeout, legacy_bridge_until
+      end
+
+      def start(user:, method:, replacing: nil, **hints)
+        # The original Rails controller verifies before calling its session hook.
+        # A reset between that proof and this lock must invalidate the proof too.
+        return if method.to_s == "password" && !user.respond_to?(:password_digest)
+        verified_password_digest = user.password_digest if method.to_s == "password"
+        @store.with_user(id: user.id, replacing: replacing) do |account|
+          next if method.to_s == "password" && account && account.password_digest != verified_password_digest
+          create_in_transaction(user: account, method: method, replacing: replacing, **hints)
+        end
+      end
+
+      def authenticate(identifier:, password:, replacing: nil, **hints)
+        @store.with_identifier(identifier: identifier, replacing: replacing) do |user|
+          verified = yield
+          create_in_transaction(user: user, method: :password, replacing: replacing, **hints) if user && verified && verified.id == user.id
+        end
+      end
+
+      # Runs inside the store's account transaction. When replacing a browser,
+      # that session's account must also be locked on the same connection.
+      def create_in_transaction(user:, method:, persist: nil, replacing: nil, proof: nil, **hints)
+        return unless user && @eligible.call(user) == true
+        raise ArgumentError, "unsupported proof" unless %w[password email_link passkey].include?(method.to_s)
+        return if @access_policy && !@access_policy.sign_in_allowed?(user, method)
+        if method.to_s == "passkey"
+          return unless proof.is_a?(StepUp::Evidence) && proof.strong? && proof.user_id == user.id &&
+            proof.verified_at <= @clock.now && proof.verified_at > @clock.now - 300
+        end
+        if user.respond_to?(:add_auth_policy_version)
+          hints = hints.merge(authentication_policy_version: @access_policy ? @access_policy.version(user) : user.add_auth_policy_version,
+            authentication_credential_id: proof&.credential_id, authentication_uv: proof&.user_verification || false)
+        end
+        raw = bearer
+        now = @clock.now
+        if replacing
+          prior = @store.find_for_user_in_transaction(user_id: replacing.user_id, session_id: replacing.id)
+          @store.update(prior, revoked_at: now) if prior && !prior.revoked_at && prior.token_digest == replacing.token_digest
+        end
+        writer = persist || ->(**attributes) { @store.create(user: user, **attributes) }
+        row = writer.call(token_digest: @digest.digest(raw), authenticated_with: method.to_s,
+          authenticated_at: now, expires_at: now + @lifetime, last_seen_at: now, **hints)
+        Grant.new(session: row, bearer: raw)
+      end
+
+      # The adapter must pass only the value returned by Rails cookies.signed.
+      def resume(signed_value:)
+        lookup = cookie_lookup(signed_value)
+        return unless lookup
+        legacy = lookup.key?(:id)
+        @store.with_session(**lookup) do |user, row|
+          now = @clock.now
+          next unless live?(user, row, now: now)
+          if legacy
+            next if row.token_digest || now >= @deadline
+            raw = bearer
+            @store.update(row, token_digest: @digest.digest(raw), expires_at: [now + @lifetime, @deadline, row.expires_at].compact.min,
+              last_seen_at: now, authenticated_with: nil, authenticated_at: nil)
+            Grant.new(session: row, bearer: raw)
+          else
+            @store.update(row, last_seen_at: now) if row.last_seen_at <= now - 60
+            Grant.new(session: row)
+          end
+        end
+      end
+
+      # A trusted cookie identifies what to retire, even if that account is now
+      # ineligible. This snapshot is replacement input, never authentication.
+      def replacement_for(signed_value:)
+        lookup = cookie_lookup(signed_value)
+        return unless lookup
+        @store.with_session(**lookup) do |_user, row|
+          row unless lookup.key?(:id) && row&.token_digest
+        end
+      end
+
+      def revoke(session:)
+        @store.with_session(id: session.id) do |_user, row|
+          @store.update(row, revoked_at: @clock.now) if row && !row.revoked_at && row.token_digest == session.token_digest
+        end
+      end
+
+      # Returns display-safe metadata only. Bearers and digests never cross this
+      # boundary, even when a host chooses to render its own management page.
+      def list(user:, current_session_id: nil)
+        list_page(user: user, current_session_id: current_session_id).entries
+      end
+
+      def list_page(user:, current_session_id: nil, before: nil)
+        empty = Page.new(entries: [])
+        return empty unless user && @eligible.call(user) == true
+        return empty unless before.nil? || before.to_s.match?(/\A[1-9]\d{0,18}\z/)
+
+        now = @clock.now
+        candidates = @store.list_for_user(user_id: user.id, before: before&.to_i,
+          excluding: current_session_id, limit: PAGE_SIZE + 1, now: now,
+          active_after: now - @idle, legacy: !!(@deadline && now < @deadline))
+        cursor = candidates[PAGE_SIZE - 1].id if candidates.length > PAGE_SIZE
+        rows = candidates.first(PAGE_SIZE)
+        if before.nil? && current_session_id
+          current = @store.find_for_user(user_id: user.id, session_id: current_session_id)
+          rows.unshift(current) if current
+        end
+        entries = rows.filter_map do |row|
+          next unless live?(user, row, now: now)
+
+          Entry.new(id: row.id, current: row.id == current_session_id,
+            authenticated_with: row.authenticated_with, authenticated_at: row.authenticated_at,
+            created_at: row.created_at, last_seen_at: row.last_seen_at, expires_at: row.expires_at,
+            ip_address: row.ip_address, user_agent: row.user_agent)
+        end
+        Page.new(entries: entries, next_cursor: cursor)
+      end
+
+      # Both the initiating bearer and target ownership are checked under lock.
+      def revoke_one(user:, session:, session_id:)
+        return false unless session_id.is_a?(Integer) || session_id.to_s.match?(/\A[1-9]\d*\z/)
+
+        with_live_session(user: user, session: session) do |account, _current, now|
+          target = @store.find_for_user_in_transaction(user_id: account.id, session_id: session_id.to_i)
+          next false unless target
+          @store.update(target, revoked_at: now) unless target.revoked_at
+          true
+        end || false
+      end
+
+      # Password proof is obtained from the locked, current account. Intake
+      # limits must be applied by the caller before reaching this expensive port.
+      def reauthenticate(user:, session:, purpose:, policy:)
+        with_live_session(user: user, session: session) do |account, row, _now|
+          next Result.failure(reason: :elevation_required) if @access_policy && !@access_policy.sign_in_allowed?(account, :password)
+          verified = yield account
+          next Result.failure(reason: :invalid_credentials) unless verified && verified.id == account.id
+          evidence = StepUp::Evidence.new(user_id: account.id, session_id: row.id,
+            method: :password, verified_at: @clock.now, session_digest: row.token_digest,
+            credential_version: policy.password_version(account))
+          policy.authorize(user: account, session_id: row.id, purpose: purpose, evidence: evidence)
+        end || Result.failure(reason: :elevation_required)
+      end
+
+      def revoke_all(user:, session:, grant:)
+        with_authority(user: user, session: session, grant: grant, purpose: :sign_out_everywhere) do |account, _row, now|
+          @store.revoke_all_in_transaction(user_id: account.id, at: now)
+        end || false
+      end
+
+      def rotate_for_step_up(user:, session:, grant:)
+        return unless grant.is_a?(StepUp::Grant)
+        with_authority(user: user, session: session, grant: grant, purpose: grant.purpose) do |account, row, _now|
+          rotate_in_transaction(user: account, session: row, grant: grant)
+        end
+      end
+
+      # Caller owns the account transaction, as with email-token consumption.
+      def current_in_transaction(user:, session:)
+        return unless user && session && session.user_id == user.id
+        row = @store.find_for_user_in_transaction(user_id: user.id, session_id: session.id)
+        row if live?(user, row, now: @clock.now) && row.token_digest == session.token_digest
+      end
+
+      def rotate_in_transaction(user:, session:, grant:)
+        row = current_in_transaction(user: user, session: session)
+        return unless row && grant.is_a?(StepUp::Grant) && grant.valid_for?(user: user,
+          user_id: user.id, session_id: row.id, session_digest: row.token_digest, purpose: grant.purpose, now: @clock.now)
+        raw = bearer
+        attributes = {token_digest: @digest.digest(raw), elevated_at: grant.verified_at,
+                      elevated_with: grant.method.to_s, elevation_purpose: grant.purpose.to_s,
+                      elevation_credential_id: grant.credential_id, elevation_uv: grant.user_verification,
+                      last_seen_at: @clock.now}
+        if row.respond_to?(:elevation_version)
+          attributes[:elevation_version] = grant.credential_version
+          attributes[:elevation_expires_at] = grant.expires_at
+        end
+        @store.update(row, **attributes)
+        Grant.new(session: row, bearer: raw)
+      end
+
+      # A guard can call this without a block. Mutations must use the block so
+      # eligibility, bearer generation and proof are checked under the same lock.
+      # Hosts own resource authorization and target/version checks inside it.
+      def with_elevation(user:, session:, purpose:, policy:)
+        with_live_session(user: user, session: session) do |account, row, _now|
+          result = elevation_in_transaction(user: account, session: row, purpose: purpose, policy: policy)
+          next result unless result.success?
+          yield account if block_given?
+          result
+        end || Result.failure(reason: :elevation_required)
+      end
+
+      def elevation_in_transaction(user:, session:, purpose:, policy:)
+        row = current_in_transaction(user: user, session: session)
+        now = @clock.now
+        return Result.failure(reason: :elevation_required) unless row&.respond_to?(:elevation_version) && row.elevated_at &&
+          row.elevation_purpose == purpose.to_s && row.elevation_expires_at && now < row.elevation_expires_at
+        evidence = StepUp::Evidence.new(user_id: user.id, session_id: row.id,
+          method: row.elevated_with, verified_at: row.elevated_at, session_digest: row.token_digest,
+          credential_id: row.elevation_credential_id, user_verification: row.elevation_uv,
+          credential_version: row.elevation_version)
+        policy.authorize(user: user, session_id: row.id, purpose: purpose, evidence: evidence)
+      end
+
+      def self.safe_return(value)
+        value if value.is_a?(String) && value.start_with?("/") && !value.start_with?("//") &&
+          !value.match?(/[\\\x00-\x20\x7f]/) && !value.match?(/%[0-9a-f]{2}/i)
+      end
+
+      private
+
+      def cookie_lookup(value)
+        if value.is_a?(String) && PATTERN.match?(value)
+          {digest: @digest.digest(value)}
+        elsif value.is_a?(Integer) && value.positive? && @deadline && @clock.now < @deadline
+          {id: value}
+        end
+      end
+
+      def with_authority(user:, session:, grant:, purpose:)
+        return unless grant.is_a?(StepUp::Grant)
+        with_live_session(user: user, session: session) do |account, row, now|
+          next unless grant.valid_for?(user: account, user_id: account.id, session_id: row.id,
+            session_digest: row.token_digest, purpose: purpose, now: now)
+          yield account, row, now
+        end
+      end
+
+      def with_live_session(user:, session:)
+        return unless user && session
+        @store.with_session(id: session.id) do |account, row|
+          now = @clock.now
+          next unless account && account.id == user.id && live?(account, row, now: now) &&
+            row.token_digest == session.token_digest
+          yield account, row, now
+        end
+      end
+
+      def live?(user, row, now:)
+        return false unless user && row && @eligible.call(user) == true && !row.revoked_at
+        return false if @access_policy && !@access_policy.session_allowed?(user, row)
+        legacy = !row.token_digest && @deadline && now < @deadline
+        (legacy || (row.expires_at && row.last_seen_at)) &&
+          (!row.expires_at || row.expires_at > now) && (!row.last_seen_at || row.last_seen_at > now - @idle)
+      end
+
+      def bearer = "lk1:#{SecureRandom.urlsafe_base64(32)}"
+    end
+  end
+end

data/lib/add_auth/core/step_up.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module AddAuth
+  module Core
+    # Evidence is issued by a trusted verifier, never deserialized from a client.
+    # A grant retains that verifier's current policy and the proof's original age.
+    class StepUp
+      METHODS = %i[password email_link passkey].freeze
+
+      class Evidence
+        attr_reader :user_id, :session_id, :method, :verified_at, :credential_id,
+          :user_verification, :session_digest, :credential_version
+
+        def initialize(user_id:, session_id:, method:, verified_at:, credential_id: nil,
+          user_verification: false, session_digest: nil, credential_version: nil)
+          @user_id, @session_id, @method, @verified_at = user_id, session_id, method.to_sym, verified_at
+          @credential_id, @user_verification = credential_id, user_verification == true
+          @session_digest, @credential_version = session_digest&.dup&.freeze, credential_version&.dup&.freeze
+          @verified_at = verified_at.dup.freeze
+          @credential_id = credential_id&.dup&.freeze
+          freeze
+        end
+
+        def strong?
+          method == :passkey && user_verification && credential_id.is_a?(String) && !credential_id.empty?
+        end
+
+        def inspect = "#<AddAuth::Core::StepUp::Evidence [FILTERED]>"
+      end
+
+      class Grant
+        attr_reader :purpose, :expires_at
+        def initialize(evidence:, purpose:, expires_at:, policy:)
+          @evidence, @purpose, @expires_at, @policy = evidence, purpose, expires_at, policy
+          freeze
+        end
+
+        %i[user_id session_id method verified_at credential_id user_verification session_digest credential_version].each do |attribute|
+          define_method(attribute) { @evidence.public_send(attribute) }
+        end
+
+        def valid_for?(user_id:, session_id:, purpose:, now:, user: nil, session_digest: nil)
+          user && user.id == user_id && @evidence.user_id == user_id && @evidence.session_id == session_id &&
+            purpose.to_sym == @purpose && @evidence.session_digest == session_digest &&
+            now.is_a?(Time) && now >= verified_at && now < @expires_at &&
+            @policy.current?(user: user, purpose: @purpose, evidence: @evidence)
+        end
+
+        def inspect = "#<AddAuth::Core::StepUp::Grant purpose=#{purpose.inspect} method=#{method.inspect}>"
+      end
+
+      class Rule
+        attr_reader :methods, :require_passkey, :return_to, :label, :reauthentication
+        def initialize(methods:, require_passkey: false, return_to: "/", label: "Continue", reauthentication: true)
+          @reauthentication = reauthentication == true
+          @methods = Array(methods).map(&:to_sym).uniq.freeze
+          raise ArgumentError, "unsupported step-up method" unless (@methods - METHODS).empty?
+          raise ArgumentError, "return_to must be a safe local GET path" unless Sessions.safe_return(return_to)
+          @return_to, @label = return_to.dup.freeze, label.to_s.dup.freeze
+          @require_passkey = require_passkey == true
+          freeze
+        end
+      end
+
+      def initialize(purposes:, fresh_for: 600, strong_for: 300, clock: Time, credential_current: nil, password_version: ->(user) { user.password_digest }, methods_available: ->(_user) { METHODS })
+        unless [fresh_for, strong_for].all? { |value| value.is_a?(Numeric) && value.finite? && value.positive? }
+          raise ArgumentError, "step-up windows must be positive"
+        end
+        raise ArgumentError, "strong_for must not exceed fresh_for" if strong_for > fresh_for
+        @purposes = purposes.transform_keys(&:to_sym).transform_values do |rule|
+          rule.is_a?(Rule) ? rule : Rule.new(**rule)
+        end.freeze
+        @fresh_for, @strong_for, @clock, @credential_current = fresh_for, strong_for, clock, credential_current
+        @password_version, @methods_available = password_version, methods_available
+      end
+
+      def rule_for(purpose)
+        return unless purpose.is_a?(String) || purpose.is_a?(Symbol)
+        return if purpose.to_s.bytesize > 64
+        @purposes[purpose.to_sym]
+      end
+
+      def reauthentication_rule_for(purpose)
+        rule = rule_for(purpose)
+        rule if rule&.reauthentication
+      end
+
+      def return_to(purpose) = rule_for(purpose)&.return_to || "/"
+
+      def methods_for(user:, purpose:)
+        rule = rule_for(purpose)
+        return [] unless user && rule
+        available = rule.methods & @methods_available.call(user)
+        rule.require_passkey ? available & [:passkey] : available
+      end
+
+      def password_version(user) = @password_version.call(user)
+
+      def authorize(user:, session_id:, purpose:, evidence:)
+        now = @clock.now
+        unless evidence.is_a?(Evidence) && user && evidence.user_id == user.id &&
+            evidence.session_id == session_id && evidence.verified_at.is_a?(Time) && now.is_a?(Time) &&
+            current?(user: user, purpose: purpose, evidence: evidence)
+          return Result.failure(reason: :elevation_required)
+        end
+        window = evidence.strong? ? @strong_for : @fresh_for
+        return Result.failure(reason: :elevation_required) unless evidence.verified_at <= now && now < evidence.verified_at + window
+
+        grant = Grant.new(evidence: evidence, purpose: purpose.to_sym,
+          expires_at: evidence.verified_at + window, policy: self)
+        Result.success(user: user, strategy: :step_up, credential: grant)
+      end
+
+      def current?(user:, purpose:, evidence:)
+        rule = rule_for(purpose)
+        return false unless rule && methods_for(user: user, purpose: purpose).include?(evidence.method)
+        return false if rule.require_passkey && !evidence.strong?
+        return false unless evidence.session_digest.is_a?(String) && !evidence.session_digest.empty?
+        return false if evidence.method == :passkey && !evidence.strong?
+        if evidence.method == :password
+          return false unless evidence.credential_version.is_a?(String) && !evidence.credential_version.empty?
+          return false unless user.respond_to?(:password_digest) && password_version(user) == evidence.credential_version
+          return true unless @credential_current
+        end
+        @credential_current && @credential_current.call(user: user, evidence: evidence) == true
+      end
+    end
+  end
+end