add_auth 0.2.1

data/lib/add_auth/core/strategies/email_link.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module AddAuth
+  module Core
+    module Strategies
+      # Internal sign-in token lifecycle, NOT an HTTP endpoint. Run issuance
+      # behind a uniform asynchronous intake/rate-limit boundary. A nil return
+      # does not make account-dependent database work timing indistinguishable.
+      # Sign-in and reauthentication have distinct purposes. Store transactions
+      # enclose Core policy, proof consumption and the session finalizer.
+      class EmailLink
+        include Delivery
+
+        DEFAULT_TOKEN_LIFETIME = 20 * 60
+        TOKEN_BYTES = 32
+        TOKEN_PATTERN = /\A[A-Za-z0-9_-]{43}\z/
+
+        def initialize(store:, digest:, delivery_cipher:, eligible:, normalize_identifier:, identifier_for:,
+          clock: Time, random: SecureRandom, token_lifetime: DEFAULT_TOKEN_LIFETIME, same_browser: false, purpose: :sign_in, sessions: nil, policy: nil, proof_allowed: ->(_user) { true })
+          unless token_lifetime.is_a?(Numeric) && token_lifetime.finite? && token_lifetime.positive?
+            raise ArgumentError, "token_lifetime must be finite and positive"
+          end
+          @store, @digest, @cipher = store, digest, delivery_cipher
+          @eligible, @normalize, @identifier_for = eligible, normalize_identifier, identifier_for
+          @clock, @random, @token_lifetime = clock, random, token_lifetime
+          raise ArgumentError, "same_browser must be true or false" unless [true, false].include?(same_browser)
+          @purpose = purpose.to_s
+          raise ArgumentError, "unsupported email purpose" unless %w[sign_in reauthentication recovery].include?(@purpose)
+          if @purpose != "sign_in" && (!sessions || !policy)
+            raise ArgumentError, "reauthentication requires sessions and purpose policy"
+          end
+          @sessions, @policy, @proof_allowed = sessions, policy, proof_allowed
+          @same_browser = same_browser || @purpose == "reauthentication"
+          @binding = BrowserBinding.new(digest: digest)
+        end
+
+        def browser_digest(secret) = @same_browser ? @binding.digest(secret) : nil
+
+        def confirmation_page(preview)
+          return "invalid_link" unless preview
+          preview.fetch(:browser_matches) ? "confirmation" : "different_browser"
+        end
+
+        def issue(identifier:, requested_ip_address: nil, request_id: nil, browser_digest: nil, session_id: nil, session_digest: nil, authentication_purpose: nil)
+          return if @same_browser && (!browser_digest.is_a?(String) || browser_digest.empty?)
+          return nil unless identifier.is_a?(String) && identifier.valid_encoding? && identifier.bytesize.between?(1, 254)
+
+          normalized = @normalize.call(identifier)
+          return nil unless normalized.is_a?(String) && normalized.valid_encoding? && normalized.bytesize.between?(1, 254)
+          raw = @random.urlsafe_base64(TOKEN_BYTES)
+          raise AddAuth::Error, "random source returned an invalid token" unless valid_token?(raw)
+          digest = @digest.digest(raw)
+          at = @clock.now
+          expires_at = at + @token_lifetime
+          payload = @cipher.encrypt(token: raw, digest: digest, expires_at: expires_at)
+          @store.with_user(identifier: normalized) do |user|
+            next if request_id && @store.issued?(request_id: request_id)
+            if user && @eligible.call(user) == true && @proof_allowed.call(user) == true && @normalize.call(@identifier_for.call(user)) == normalized
+              context = {}
+              if @purpose == "reauthentication"
+                row = @store.session_for(user: user, id: session_id)
+                next unless row && row.token_digest == session_digest && @sessions.current_in_transaction(user: user, session: row) &&
+                  @policy.reauthentication_rule_for(authentication_purpose) && @policy.methods_for(user: user, purpose: authentication_purpose).include?(:email_link)
+                context = {session_id: row.id, session_digest: row.token_digest, authentication_purpose: authentication_purpose.to_s}
+              end
+              @store.replace_pending(user: user, purpose: @purpose, **context, digest: digest, expires_at: expires_at,
+                created_at: at, delivery_payload: payload, identifier_digest: @digest.digest("identifier:#{normalized}"),
+                requested_ip_address: requested_ip_address, **(browser_digest ? {browser_digest: browser_digest} : {}), **(request_id ? {request_id: request_id} : {}))
+            end
+          end
+          nil
+        end
+
+        # The finalizer must persist the session in the same transaction; cookie
+        # writing/delivery happens only after this method successfully returns.
+        # Pass a trusted current_session snapshot here and as replacing: to the
+        # session finalizer so both accounts are locked during a browser switch.
+        def consume(token:, current_user_id: nil, current_session: nil, switch_account: false, browser_secret: nil)
+          raise ArgumentError, "use reauthenticate for this proof" if @purpose == "reauthentication"
+          raise ArgumentError, "a transactional session finalizer is required" unless block_given? || @purpose == "recovery"
+          return failure(:invalid_credentials) unless valid_token?(token)
+
+          current_user_id = current_session.user_id if current_session
+          @store.with_token(digest: @digest.digest(token), current_session: current_session) do |user, record|
+            reason = rejection(user, record)
+            reason ||= :invalid_credentials unless browser_matches?(record, browser_secret)
+            reason ||= :invalid_credentials if current_user_id && user && current_user_id != user.id && switch_account != true
+            if reason
+              failure(reason)
+            else
+              @store.consume(record: record, at: @clock.now)
+              grant = nil
+              session = @store.finalize_session(user: user) do |persist|
+                if @purpose == "recovery"
+                  grant = recovery_session(user, record, persist, current_session)
+                  grant.session
+                else
+                  yield user, persist
+                end
+              end
+              AddAuth::Result.success(user: user, strategy: :email_link, session: session, grant: grant)
+            end
+          end
+        end
+
+        def reauthenticate(token:, session:, browser_secret:)
+          return failure(:invalid_credentials) unless @purpose == "reauthentication" && valid_token?(token)
+          @store.with_token(digest: @digest.digest(token)) do |user, record|
+            reason = rejection(user, record)
+            reason ||= :invalid_credentials unless browser_matches?(record, browser_secret)
+            reason ||= :elevation_required unless session && record && session.id == record.session_id &&
+              session.token_digest == record.session_digest && user && @sessions.current_in_transaction(user: user, session: session)
+            next failure(reason) if reason
+            evidence = StepUp::Evidence.new(user_id: user.id, session_id: session.id, method: :email_link,
+              verified_at: @clock.now, session_digest: session.token_digest, credential_version: record.identifier_digest)
+            result = @policy.authorize(user: user, session_id: session.id, purpose: record.authentication_purpose, evidence: evidence)
+            next result unless result.success?
+            rotated = @sessions.rotate_in_transaction(user: user, session: session, grant: result.credential)
+            next failure(:elevation_required) unless rotated
+            @store.consume(record: record, at: @clock.now)
+            Result.success(user: user, strategy: :step_up, session: rotated.session, credential: rotated)
+          end
+        end
+
+        # Delivery workers fetch by digest/issuance identity, never raw job args.
+        # Repeated calls return the SAME token. A future worker must recheck before
+        # sending and tolerate an email becoming stale while already in transit.
+        def delivery_token(digest:)
+          @store.with_token(digest: digest) do |user, record|
+            unless rejection(user, record) || record.delivery_payload.nil?
+              token = @cipher.decrypt(payload: record.delivery_payload, digest: record.digest)
+              token if valid_token?(token) && @digest.matches?(record.digest, token)
+            end
+          end
+        end
+
+        def preview(token:, browser_secret: nil)
+          return unless valid_token?(token)
+          @store.with_token(digest: @digest.digest(token)) do |user, record|
+            unless rejection(user, record)
+              address = @identifier_for.call(user)
+              local, domain = address.split("@", 2)
+              {user_id: user.id, masked_address: "#{local[0]}•••@#{domain}", browser_matches: browser_matches?(record, browser_secret)}
+            end
+          end
+        end
+
+        private
+
+        def recovery_session(user, record, persist, previous)
+          initial = @sessions.create_in_transaction(user: user, method: :email_link, persist: persist, replacing: previous)
+          raise AddAuth::Error, "recovery could not create a session" unless initial
+          evidence = StepUp::Evidence.new(user_id: user.id, session_id: initial.session.id, method: :email_link,
+            verified_at: @clock.now, session_digest: initial.session.token_digest, credential_version: record.identifier_digest)
+          proof = @policy.authorize(user: user, session_id: initial.session.id, purpose: :recover_passkeys, evidence: evidence)
+          raise AddAuth::Error, "recovery is not permitted" unless proof.success?
+          grant = @sessions.rotate_in_transaction(user: user, session: initial.session, grant: proof.credential)
+          raise AddAuth::Error, "recovery could not finalize" unless grant
+          # Preserve the transaction writer's exact newly created row identity.
+          grant.session = @store.refresh_session(initial.session)
+          grant
+        end
+
+        def delivery_details(user, record)
+          raw = @cipher.decrypt(payload: record.delivery_payload, digest: record.digest)
+          {token: raw, recipient: @identifier_for.call(user)} if valid_token?(raw) && @digest.matches?(record.digest, raw)
+        end
+
+        def browser_matches?(record, secret)
+          stored = record.browser_digest if record&.respond_to?(:browser_digest)
+          return true if !@same_browser && stored.nil?
+          @binding.matches?(stored, secret)
+        end
+
+        def valid_token?(token)
+          token.is_a?(String) && token.bytesize == 43 && token.ascii_only? && TOKEN_PATTERN.match?(token)
+        end
+
+        def rejection(user, record)
+          return :invalid_credentials unless user && record && record.purpose == @purpose
+          return :disabled unless @eligible.call(user) == true && @proof_allowed.call(user) == true
+          identifier = @normalize.call(@identifier_for.call(user))
+          return :revoked_token unless @digest.matches?(record.identifier_digest, "identifier:#{identifier}")
+          if @purpose == "reauthentication"
+            row = @store.session_for(user: user, id: record.session_id)
+            return :elevation_required unless row && row.token_digest == record.session_digest &&
+              @sessions.current_in_transaction(user: user, session: row) &&
+              @policy.reauthentication_rule_for(record.authentication_purpose) && @policy.methods_for(user: user, purpose: record.authentication_purpose).include?(:email_link)
+          end
+          return :revoked_token if record.revoked_at
+          return :consumed_token if record.consumed_at
+          :expired_token if record.expires_at <= @clock.now
+        end
+
+        def failure(reason) = AddAuth::Result.failure(reason: reason)
+      end
+    end
+  end
+end

data/lib/add_auth/core/strategies/passkey.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+require "webauthn"
+require "json"
+require "base64"
+require "uri"
+require "public_suffix"
+
+module AddAuth
+  module Core
+    module Strategies
+      class Passkey
+        PURPOSE = :manage_passkeys
+        PAYLOAD_LIMIT = 65_536
+        Entry = Data.define(:id, :nickname, :created_at, :last_used_at, :backup_eligible, :backup_state)
+
+        def initialize(store:, sessions:, policy:, access_policy:, digest:, eligible:, rp_id:, origins:, name:,
+          notify:, limiter:, anonymous_limit: 1000, clock: Time, allow_localhost: false, support_url: nil, on_failure: ->(_reason) {})
+          @store, @sessions, @policy, @access, @digest, @eligible = store, sessions, policy, access_policy, digest, eligible
+          @clock, @notify, @support_url, @on_failure = clock, notify, support_url, on_failure
+          @limiter, @anonymous_limit = limiter, anonymous_limit
+          unless anonymous_limit.is_a?(Integer) && anonymous_limit.positive?
+            raise AddAuth::Error, "passkeys.anonymous_limit must be a positive integer"
+          end
+          raise AddAuth::Error, "support_url must be a safe local support page" if support_url && !Sessions.safe_return(support_url)
+          @binding = BrowserBinding.new(digest: digest)
+          validate_origins!(rp_id, origins, allow_localhost)
+          @rp = WebAuthn::RelyingParty.new(id: rp_id, name: name, allowed_origins: origins.dup,
+            encoding: :base64url, acceptable_attestation_types: ["None"], credential_options_timeout: 120_000)
+          @configuration_digest = digest.digest(JSON.generate([rp_id, origins.sort]))
+        end
+
+        def registration_options(user:, session:, browser_secret:)
+          @store.with_user(id: user&.id) do |account|
+            proof = management_proof(account, session, allow_recovery: true)
+            next failure(:elevation_required) unless proof.success? && @binding.valid?(browser_secret)
+            @store.update(account, webauthn_id: @binding.generate) unless account.webauthn_id
+            options = @rp.options_for_registration(user: {id: account.webauthn_id, name: account.email_address},
+              exclude: @store.credentials(user: account).map(&:external_id), attestation: "none",
+              authenticator_selection: {residentKey: "required", requireResidentKey: true, userVerification: "required"},
+              extensions: {credProps: true})
+            create_options(options, kind: "registration", user: account, session: session,
+              purpose: proof.credential.purpose, browser_secret: browser_secret)
+          end
+        end
+
+        def authentication_options(browser_secret:, user: nil, session: nil, purpose: nil)
+          return failure unless @binding.valid?(browser_secret)
+          if user || session || purpose
+            @store.with_user(id: user&.id) do |account|
+              next failure(:elevation_required) unless account && @sessions.current_in_transaction(user: account, session: session) &&
+                @policy.reauthentication_rule_for(purpose) && @policy.methods_for(user: account, purpose: purpose).include?(:passkey)
+              options = @rp.options_for_authentication(allow: @store.credentials(user: account).map(&:external_id), user_verification: "required")
+              create_options(options, kind: "assertion", user: account, session: session, purpose: purpose, browser_secret: browser_secret)
+            end
+          else
+            return failure(:rate_limited) unless @limiter.call(key: @digest.digest("passkey:anonymous-ceremonies"), limit: @anonymous_limit)
+            options = @rp.options_for_authentication(user_verification: "required")
+            create_options(options, kind: "assertion", browser_secret: browser_secret)
+          end
+        end
+
+        def register(transaction:, credential_response:, user:, session:, browser_secret:, nickname: nil)
+          payload = parse_payload(credential_response)
+          return failure unless payload && @binding.valid?(transaction)
+          @store.with_ceremony(digest: @digest.digest(transaction), user_id: user&.id) do |account, ceremony|
+            next failure unless valid_ceremony?(account, ceremony, "registration", browser_secret) &&
+              bound_session?(ceremony, session) && ceremony.user_id == account.id
+            proof = management_proof(account, session, purpose: ceremony.authentication_purpose)
+            next failure(:elevation_required) unless proof.success?
+            verified = verify { @rp.verify_registration(payload, ceremony.challenge, user_verification: true, user_presence: true) }
+            next verified if verified.is_a?(Result)
+            next failure unless valid_backup?(verified) && verified.raw_id == verified.response.authenticator_data.credential.id
+            label = normalized_label(nickname || "Passkey")
+            next failure unless label
+            credential = @store.create_credential(user: account, external_id: verified.id,
+              public_key: verified.public_key, sign_count: verified.sign_count,
+              backup_eligible: verified.backup_eligible?, backup_state: verified.backed_up?, nickname: label,
+              aaguid: verified.response.authenticator_data.aaguid, transports: transports(payload))
+            next failure unless credential
+            @store.update(ceremony, consumed_at: @clock.now)
+            grant = nil
+            if proof.credential.purpose == :recover_passkeys
+              @store.revoke_other_sessions(user: account, except: session, at: @clock.now)
+              @store.invalidate_proofs(user: account, at: @clock.now)
+              grant = @sessions.rotate_in_transaction(user: account, session: session, grant: proof.credential)
+              raise AddAuth::Error, "recovery replacement could not finalize" unless grant
+              @store.update(grant.session, elevated_at: nil, elevation_version: nil, elevation_expires_at: nil)
+              @notify.call(user: account, kind: :recovery_completed, at: @clock.now)
+            else
+              @notify.call(user: account, kind: :passkey_added, at: @clock.now)
+            end
+            Result.success(user: account, strategy: :passkey, credential: credential, session: grant&.session, grant: grant)
+          end
+        end
+
+        def authenticate(transaction:, credential_response:, browser_secret:, session: nil, replacing: nil, **hints)
+          payload = parse_payload(credential_response)
+          return failure unless payload && @binding.valid?(transaction)
+          locator = @store.credential(id: payload["id"])
+          return failure unless locator
+          @store.with_ceremony(digest: @digest.digest(transaction), user_id: locator.user_id, replacing: replacing) do |account, ceremony|
+            next failure unless valid_ceremony?(account, ceremony, "assertion", browser_secret)
+            next failure unless ceremony.user_id.nil? == session.nil?
+            credential = @store.credential(id: payload["id"])
+            next failure unless credential && credential.user_id == account.id && !credential.revoked_at
+            if ceremony.user_id
+              next failure(:elevation_required) unless ceremony.user_id == account.id && bound_session?(ceremony, session) &&
+                @sessions.current_in_transaction(user: account, session: session)
+            else
+              next failure unless @access.sign_in_allowed?(account, :passkey)
+            end
+            verified = verify do
+              @rp.verify_authentication(payload, ceremony.challenge, public_key: credential.public_key,
+                sign_count: credential.sign_count, user_verification: true, user_presence: true)
+            end
+            next verified if verified.is_a?(Result)
+            next failure unless verified.user_handle == account.webauthn_id && valid_backup?(verified) &&
+              verified.backup_eligible? == credential.backup_eligible
+            evidence = StepUp::Evidence.new(user_id: account.id, session_id: session&.id, method: :passkey,
+              verified_at: @clock.now, session_digest: session&.token_digest, credential_id: credential.external_id,
+              credential_version: credential.public_key, user_verification: true)
+            grant = if ceremony.user_id
+              authorization = @policy.authorize(user: account, session_id: session.id,
+                purpose: ceremony.authentication_purpose, evidence: evidence)
+              next authorization unless authorization.success?
+              @sessions.rotate_in_transaction(user: account, session: session, grant: authorization.credential)
+            else
+              @sessions.create_in_transaction(user: account, method: :passkey, proof: evidence, replacing: replacing, **hints)
+            end
+            next failure(:elevation_required) unless grant
+            @store.update(credential, sign_count: verified.sign_count, backup_state: verified.backed_up?, last_used_at: @clock.now)
+            @store.update(ceremony, consumed_at: @clock.now)
+            Result.success(user: account, strategy: :passkey, credential: grant, session: grant.session)
+          end
+        end
+
+        def list(user:, session:)
+          @store.with_user(id: user&.id) do |account|
+            next [] unless account && @sessions.current_in_transaction(user: account, session: session)
+            @store.credentials(user: account).map do |row|
+              Entry.new(id: row.id, nickname: row.nickname, created_at: row.created_at, last_used_at: row.last_used_at,
+                backup_eligible: row.backup_eligible, backup_state: row.backup_state)
+            end
+          end
+        end
+
+        def rename(user:, session:, id:, nickname:)
+          label = normalized_label(nickname)
+          return failure unless label
+          @store.with_user(id: user&.id) do |account|
+            next failure unless account && @sessions.current_in_transaction(user: account, session: session)
+            row = @store.credentials(user: account).find { |item| item.id.to_s == id.to_s }
+            next failure unless row
+            @store.update(row, nickname: label)
+            Result.success(user: account, strategy: :passkey)
+          end
+        end
+
+        def remove(user:, session:, id:)
+          @store.with_user(id: user&.id) do |account|
+            next failure(:elevation_required) unless management_proof(account, session).success?
+            rows = @store.credentials(user: account)
+            row = rows.find { |item| item.id.to_s == id.to_s }
+            next failure unless row
+            next failure unless rows.length > 1 || @access.fallback?(account)
+            @store.update(row, revoked_at: @clock.now)
+            @notify.call(user: account, kind: :passkey_removed, at: @clock.now)
+            Result.success(user: account, strategy: :passkey)
+          end
+        end
+
+        def change_policy(user:, session:, strict:, acknowledged:)
+          return failure unless [true, false].include?(strict)
+          return failure if strict && (acknowledged != true || @support_url.to_s.empty?)
+          @store.with_user(id: user&.id) do |account|
+            proof = @sessions.elevation_in_transaction(user: account, session: session, purpose: :manage_policy, policy: @policy)
+            next failure(:elevation_required) unless proof.success? && proof.credential.method == :passkey && proof.credential.user_verification
+            next failure unless @store.credentials(user: account).any?
+            row = @sessions.current_in_transaction(user: account, session: session)
+            @store.update(account, add_auth_strict: strict, add_auth_policy_version: @access.version(account) + 1)
+            @store.revoke_other_sessions(user: account, except: row, at: @clock.now)
+            @store.invalidate_proofs(user: account, at: @clock.now)
+            @store.update(row, authentication_policy_version: @access.version(account), authenticated_with: "passkey",
+              authenticated_at: proof.credential.verified_at, authentication_credential_id: proof.credential.credential_id,
+              authentication_uv: true)
+            grant = @sessions.rotate_in_transaction(user: account, session: row, grant: proof.credential)
+            raise AddAuth::Error, "policy transition could not finalize" unless grant
+            @notify.call(user: account, kind: :policy_changed, at: @clock.now)
+            Result.success(user: account, strategy: :passkey, session: grant.session, credential: grant)
+          end
+        end
+
+        def cancel(transaction:, browser_secret:)
+          return false unless @binding.valid?(transaction)
+          @store.cancel(digest: @digest.digest(transaction)) do |record|
+            next false unless record && @binding.matches?(record.browser_digest, browser_secret)
+            @store.update(record, consumed_at: @clock.now) unless record.consumed_at
+            true
+          end
+        end
+
+        private
+
+        def management_proof(account, session, purpose: PURPOSE, allow_recovery: false)
+          return failure(:elevation_required) unless account
+          return failure(:elevation_required) if purpose.to_sym == :recover_passkeys && !@access.recoverable?(account)
+          proof = @sessions.elevation_in_transaction(user: account, session: session, purpose: purpose, policy: @policy)
+          return proof if proof.success? || !allow_recovery || purpose.to_sym != PURPOSE || !@access.recoverable?(account)
+          @sessions.elevation_in_transaction(user: account, session: session, purpose: :recover_passkeys, policy: @policy)
+        end
+
+        def create_options(options, kind:, browser_secret:, user: nil, session: nil, purpose: nil)
+          identifier = @binding.generate
+          @store.create_ceremony(digest: @digest.digest(identifier), challenge: options.challenge, kind: kind,
+            browser_digest: @binding.digest(browser_secret), configuration_digest: @configuration_digest,
+            user_id: user&.id, session_id: session&.id, session_digest: session&.token_digest,
+            authentication_purpose: purpose&.to_s, expires_at: @clock.now + 300)
+          Result.success(user: user, strategy: :passkey, credential: {transaction: identifier, publicKey: options.as_json})
+        end
+
+        def valid_ceremony?(account, row, kind, browser_secret)
+          account && @eligible.call(account) == true && row && row.kind == kind && !row.consumed_at &&
+            row.expires_at > @clock.now && row.configuration_digest == @configuration_digest &&
+            @binding.matches?(row.browser_digest, browser_secret)
+        end
+
+        def bound_session?(ceremony, session)
+          session && ceremony.session_id == session.id && ceremony.session_digest == session.token_digest
+        end
+
+        def valid_backup?(credential) = !credential.backed_up? || credential.backup_eligible?
+
+        def normalized_label(label)
+          label.strip if label.is_a?(String) && label.valid_encoding? && label.bytesize <= 240 &&
+            label.strip.length.between?(1, 60) && !label.match?(/[\x00-\x1f\x7f]/)
+        end
+
+        def transports(payload)
+          value = payload.dig("response", "transports")
+          value.is_a?(Array) ? value & %w[usb nfc ble internal hybrid] : []
+        end
+
+        def parse_payload(value)
+          return unless value.is_a?(Hash) && JSON.generate(value).bytesize <= PAYLOAD_LIMIT
+          id = value["id"]
+          return unless id.is_a?(String) && id.bytesize.between?(1, 2048) && /\A[A-Za-z0-9_-]+\z/.match?(id) && value["rawId"] == id
+          client = JSON.parse(Base64.urlsafe_decode64(value.fetch("response").fetch("clientDataJSON")))
+          return unless client.is_a?(Hash) && [nil, false].include?(client["crossOrigin"]) && !client.key?("topOrigin")
+          value
+        rescue ArgumentError, TypeError, KeyError, NoMethodError, JSON::ParserError
+          nil
+        end
+
+        def verify
+          yield
+        rescue WebAuthn::SignCountVerificationError
+          failure(:counter_regression)
+        rescue
+          # Library parsing/verification handles attacker-controlled binary data.
+          # This rescue surrounds verification only, never persistence or finalization.
+          failure
+        end
+
+        def validate_origins!(rp_id, origins, allow_localhost)
+          valid_id = rp_id.is_a?(String) && /\A[a-z0-9]+(?:[.-][a-z0-9]+)*\z/.match?(rp_id) &&
+            (PublicSuffix.domain(rp_id) || (allow_localhost && rp_id == "localhost"))
+          valid = valid_id && origins.is_a?(Array) && origins.any? && origins.all? do |origin|
+            uri = URI.parse(origin)
+            secure = uri.scheme == "https" || (allow_localhost && uri.scheme == "http" && %w[localhost 127.0.0.1].include?(uri.host))
+            secure && uri.host && (uri.host == rp_id || uri.host.end_with?(".#{rp_id}")) &&
+              !uri.userinfo && !uri.query && !uri.fragment && uri.path.empty? && uri.to_s == origin
+          end
+          raise AddAuth::Error, "configure a stable RP ID and exact HTTPS origins" unless valid
+        rescue URI::InvalidURIError, TypeError
+          raise AddAuth::Error, "configure a stable RP ID and exact HTTPS origins"
+        end
+
+        def failure(reason = :invalid_credentials)
+          @on_failure.call(reason)
+          Result.failure(reason: reason)
+        end
+      end
+    end
+  end
+end

data/lib/add_auth/rails/authentication.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "add_auth/rails/runtime"
+
+module AddAuth
+  module Rails
+    # Included AFTER the host Authentication concern. No parallel session model.
+    module Authentication
+      private
+
+      # Authentication management always requires a named session, even if
+      # the host also serves public pages through a permissive general guard.
+      def require_add_auth_authentication
+        request_authentication unless resume_session
+      end
+
+      def find_session_by_cookie
+        grant = Runtime.sessions.resume(signed_value: cookies.signed[:session_id])
+        add_auth_write_cookie(grant) if grant&.bearer
+        grant&.session
+      end
+
+      def start_new_session_for(user)
+        grant = Runtime.sessions.start(user: user, method: :password, replacing: add_auth_replacement_session, **add_auth_session_hints)
+        raise AddAuth::Error, "account is not eligible to sign in" unless grant
+        add_auth_accept(grant)
+      end
+
+      def add_auth_session_hints
+        {user_agent: request.user_agent.to_s.truncate_bytes(512), ip_address: request.remote_ip}
+      end
+
+      def add_auth_replacement_session
+        Runtime.sessions.replacement_for(signed_value: cookies.signed[:session_id])
+      end
+
+      def add_auth_accept(grant)
+        destination = Core::Sessions.safe_return(session[:return_to_after_authenticating])
+        reset_session
+        session[:return_to_after_authenticating] = destination if destination
+        add_auth_write_cookie(grant)
+        Current.session = grant.session
+      end
+
+      def add_auth_write_cookie(grant)
+        cookies.signed[:session_id] = {value: grant.bearer, expires: grant.session.expires_at,
+          httponly: true, secure: request.ssl? || ::Rails.env.production?, same_site: :lax, path: "/"}
+      end
+
+      def terminate_session
+        Runtime.sessions.revoke(session: Current.session) if Current.session
+        Current.reset
+        reset_session
+        cookies.delete(:session_id, path: "/")
+      end
+
+      def request_authentication
+        session[:return_to_after_authenticating] = Core::Sessions.safe_return(request.fullpath) if request.get?
+        redirect_to Runtime.sign_in_path, status: request.get? ? :found : :see_other
+      end
+
+      def after_authentication_url
+        Core::Sessions.safe_return(session.delete(:return_to_after_authenticating)) || "/"
+      end
+    end
+  end
+end

data/lib/add_auth/rails/authentication_pages.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module AddAuth
+  module Rails
+    module AuthenticationPages
+      def add_auth_password_sign_in
+        return head :not_found unless Runtime.config.passwords_enabled
+        intake = Runtime.intake.call(identifier: params[:email_address], ip: request.remote_ip,
+          action: :sign_in, challenge_token: challenge_token)
+        return intake_failure(intake) if intake.is_a?(Symbol)
+        grant = Runtime.sessions.authenticate(identifier: intake, password: params[:password], replacing: add_auth_replacement_session, **add_auth_session_hints) do
+          Runtime.authenticate_password(identifier: intake, password: params[:password])
+        end
+        if grant
+          destination = after_authentication_url
+          add_auth_accept(grant)
+          redirect_to destination, status: :see_other
+        else
+          @error = "Email or password is incorrect. Try again or request a sign-in link."
+          page("form", status: :unprocessable_entity)
+        end
+      end
+
+      private
+
+      def valid_request_origin?
+        Core::Intake.origin_allowed?(origin: request.origin, base_url: request.base_url)
+      end
+
+      def challenge_token
+        params[:challenge_token].presence || params["cf-turnstile-response"].presence || params["g-recaptcha-response"].presence
+      end
+
+      def service_unavailable
+        @error = "Sign-in is temporarily unavailable. Please try again shortly."
+        response.set_header("Retry-After", "60")
+        page("form", status: :service_unavailable)
+      end
+
+      def private_response
+        response.set_header("Cache-Control", "no-store")
+        response.set_header("Referrer-Policy", "no-referrer")
+      end
+
+      def page(partial, status: :ok)
+        @page_partial = authentication_partial(partial)
+        respond_to do |format|
+          format.html { render "add_auth/sign_ins/show", layout: "add_auth/authentication", status: status }
+          format.turbo_stream { render turbo_stream: turbo_stream.update("add_auth-content", partial: @page_partial), status: status }
+        end
+      end
+
+      def authentication_partial(partial) = "add_auth/sign_ins/#{partial}"
+
+      def intake_failure(reason)
+        @error, status = {
+          rate_limited: ["Too many attempts. Try again in five minutes.", :too_many_requests],
+          challenge_unavailable: ["Verification is temporarily unavailable. Please try again shortly.", :service_unavailable],
+          challenge_rejected: ["Verification failed. Please try again.", :unprocessable_entity]
+        }.fetch(reason, ["Check your credentials and try again.", :unprocessable_entity])
+        response.set_header("Retry-After", "300") if %i[too_many_requests service_unavailable].include?(status)
+        page("form", status: status)
+      end
+    end
+  end
+end

data/lib/add_auth/rails/delivery_cipher.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "active_support/message_encryptor"
+
+module AddAuth
+  module Rails
+    # A pending delivery contains a bearer: encrypt it with a separate key and
+    # bind it to its token digest. Never enqueue or log the plaintext argument.
+    class DeliveryCipher
+      def initialize(key:)
+        raise ArgumentError, "delivery key must be 32 bytes" unless key.is_a?(String) && key.bytesize == 32
+        @encryptor = ActiveSupport::MessageEncryptor.new(key.dup.freeze,
+          cipher: "aes-256-gcm", serializer: :json)
+      end
+
+      def encrypt(token:, digest:, expires_at:)
+        @encryptor.encrypt_and_sign(token, purpose: purpose(digest), expires_at: expires_at)
+      end
+
+      def decrypt(payload:, digest:)
+        @encryptor.decrypt_and_verify(payload, purpose: purpose(digest))
+      rescue ActiveSupport::MessageEncryptor::InvalidMessage
+        nil
+      end
+
+      def inspect = "#<#{self.class} [FILTERED]>"
+
+      private
+
+      def purpose(digest) = "add_auth.email-delivery.v1:#{digest}"
+    end
+  end
+end