add_auth 0.2.1

data/ROADMAP.md

@@ -0,0 +1,244 @@
+# Roadmap
+
+AddAuth extends Rails 8's `bin/rails generate authentication` with email-link
+sign-in, passkeys, purpose-bound reauthentication, session hardening and pluggable
+captcha. It reuses the host's accounts and Session model.
+
+The canonical design lives in the companion **private** planning workspace:
+[scope](https://github.com/taimoorq/add_auth-workspace/blob/main/docs/authentication-gem-plan.md#14-scope-decision-and-roadmap)
+and [user journeys, contracts and test plan](https://github.com/taimoorq/add_auth-workspace/blob/main/docs/authentication-gem-plan.md#16-integrated-user-journeys-and-implementation-plan).
+Those links require workspace access. This public checklist stands on its own as
+progress tracking; it does not duplicate the private design. Engineering guidance
+stays only in that workspace's `AGENTS.md`.
+
+Reviewed 2026-09-07. The 0.2.1 source implements the v1
+strategy features: password/email/passkey sign-in, hardened sessions, reauthentication,
+credential management, default recovery and strict policy, security notifications,
+challenge adapters and fingerprinted ejection. Core policy, session finalization
+and leased mail delivery are shared by engine and ejected flows.
+
+The 0.2 release gate uses local real-database, generated-host, browser and
+SMTP/queue/cache acceptance. The final supported matrix is recorded in the
+[canonical evidence ledger](https://github.com/taimoorq/add_auth-workspace/blob/main/docs/authentication-gem-plan.md#20-release-020-execution--2026-09-07).
+Checked feature items mean passing relevant local specs. GitHub's required
+merge/release controls still apply. Hosts verify their own live providers,
+physical authenticators and deployment operations; those checks do not block
+the gem's 0.2 release. Email themes and branding are optional host presentation.
+
+Generated pages use shared HTML/Turbo partials. Password/email paths support
+ordinary no-JS navigation when permitted by policy; passkeys require browser
+JavaScript, and a configured captcha may also require it. Strict policy must never
+be weakened to simulate no-JS parity.
+
+## 0. Project foundations
+
+- [x] Gemspec with a capability-derived Rails floor (`>= 8.0`, the release
+      that shipped the authentication generator) and a security-patch-derived
+      Ruby floor (`>= 3.3.0`), not just whatever the newest Rails tolerates.
+- [x] MIT license, Code of Conduct, Security policy (`SECURITY.md`).
+- [x] RSpec test setup (`.rspec`, `spec/spec_helper.rb`).
+- [x] `standard` for formatting/linting.
+- [x] CI (GitHub Actions): RSpec + Standard across the Ruby support matrix,
+      plus a `bundler-audit` job.
+- [x] Dependabot, grouped by ecosystem, with the Rails family grouped
+      together — the concrete mechanism behind the "stay current" mandate in
+      the workspace's `AGENTS.md`.
+- [x] RubyGems release workflow configured for [Trusted
+      Publishing](https://guides.rubygems.org/trusted-publishing/) (OIDC from
+      GitHub Actions) instead of a long-lived API key, gated behind
+      `rubygems_mfa_required` and `allowed_push_host`.
+- [x] `bin/setup` / `bin/console` dev scripts.
+- [ ] First successful tagged release published via the Trusted Publishing
+      workflow, to lock in the gem name on RubyGems.
+
+## 1. Core primitives
+
+- [x] `AddAuth::Result` — closed success/failure type for auth outcomes.
+- [x] `AddAuth::Configuration` / `AddAuth.configure`.
+- [x] Challenge adapter contract (`AddAuth::Core::Challenge::Base`) with the
+      three-state result (success / rejected / unavailable).
+- [x] `Challenge::Null` (default, always succeeds) and `Challenge::Test`
+      (configurable, for specs) adapters.
+- [x] Purpose-separated HMAC digests with explicit strong key material,
+      real Rails key derivation, override tests and a framework-free Core check.
+
+## 2. Shared contracts and a real host harness — slices A1/A2
+
+- [x] One Core policy for eligibility, purpose, proof strength and freshness;
+      one session finalizer and public result presenter across all methods.
+- [x] Ordinary email-token store and encrypted delivery-intent contracts,
+      shared examples against fake and real SQLite/PostgreSQL adapters, with clock/digest
+      injection, replay/race/rollback/address-binding coverage.
+- [x] Passkey/recovery proof and host lifecycle contracts, with actual WebAuthn
+      cryptography, rollback and concurrency on SQLite and PostgreSQL.
+- [x] Boot `spec/dummy` through RSpec; replace generated test stubs with
+      password sign-in/reset/sign-out requests and real database coverage.
+- [x] Generate and boot Rails 8.0/8.1 hosts; exercise the persistence
+      generator and preserve host customizations. CI covers both Rails lines
+      on Ruby 3.3, 3.4 and 4.0. Commands are in CONTRIBUTING.md.
+- [x] Browser/virtual-authenticator harness with the passkey slice.
+
+## 3. Adopt the host's sessions and password flow — slice B, U1/U8
+
+- [x] Inert `add_auth:install` configuration plus additive `session_upgrade`
+      migration and shared lifecycle hooks; repeat generation preserves edits.
+- [x] Bounded signed-ID cookie transition to random digested bearers, with
+      real signature/tamper, race, cutoff and revocation tests.
+- [x] Password/reset normalization and routes preserved; password/address
+      invalidation and account deletion integrated. Hosts supply eligibility.
+- [x] Absolute/idle expiry, protected cookies, fresh session IDs and safe local
+      return destinations for implemented password/email flows.
+- [x] Current-session sign-out revokes its bearer and clears browser state.
+- [x] Session list and revoke-one, including next-request rejection in another
+      browser and cache/back-safe authenticated-page handling.
+- [x] Sign-out-everywhere, guarded by fresh allowed proof and covering every
+      active browser, with old bearers rejected on their next request.
+- [x] Account-scoped cursor pages and bounded maintenance, with optional history
+      retention, active-lease protection and completed-pass counts.
+- [x] Explicit passwordless mode, guarded stock entry routes and authenticated
+      account-management pages in hosts that also serve public pages.
+
+## 4. Complete email-link sign-in — slice C, U2
+
+- [x] Internal `EmailLink#issue`/`#consume` lifecycle: atomic replacement and
+      session persistence, one-use proof, account/address eligibility rechecks,
+      expiring encrypted delivery handoff and tested concurrent use.
+- [x] Wire the lifecycle to the hardened session finalizer and uniform
+      asynchronous/rate-limited public intake.
+- [x] Additive token model/store generator and protected pending-delivery
+      payload, cleared on consumption/revocation; no Session schema changes.
+- [x] Encrypted request jobs, idempotent issuance, leased mail delivery,
+      retry/cleanup sweep and delivered-link-to-browser integration.
+- [x] Durable security notifications share the delivery lease/retry/cancellation
+      contract and recover interrupted queue handoffs.
+- [x] Local SMTP, durable queue restart/retry and cross-process shared-cache
+      acceptance. Live transport and monitoring validation belongs to each host.
+- [x] Shared IP + keyed identifier rate policy, normalization and generic
+      request/resend responses for unknown, disabled and throttled accounts.
+- [x] Request → check-email → inert GET confirmation → explicit POST consume
+      → session; masked account confirmation and deliberate account switching.
+- [x] Resend limits, newest-link guidance, expired/used-link recovery and
+      cross-device sign-in by default.
+- [x] Optional same-browser binding, including delivered links, wrong-browser denial,
+      Turbo/no-JS browsers and generated/ejected hosts.
+- [x] Real DB concurrency and delivered-mail-to-session specs, plus HTML,
+      Turbo and no-JS request/system coverage for the complete flow.
+
+- [x] Basic scoped CSS, semantic class overrides for host Bootstrap/Tailwind
+      builds, stylesheet opt-out and view ejection with custom-file preservation.
+
+## 5. Reauthentication and recovery policy — slice D, U6/U7
+
+- [x] Core purpose/freshness evaluator with account/session binding, generic
+      elevation failures and passkey UV requirements.
+- [x] Additive session elevation metadata and bearer-rotation finalizer for a
+      previously authorized grant, now wired to public reauthentication routes.
+- [x] Host reauthentication adapters persist purpose-bound grants and rotate the
+      existing session's bearer after password/email/passkey verification.
+- [x] Password/email reauthentication adapters share policy and presentation;
+      email step-up is bound to the initiating browser/session/purpose.
+- [x] Sensitive-action return goes to a safe confirmation page; final mutation
+      rechecks authorization/grant/target and never automatically replays a POST.
+- [x] Default email recovery with explicit recovery purpose, replacement grant,
+      security notifications and post-recovery session/proof invalidation.
+- [x] Stricter opt-in policy enforced across sign-in, fallback, credential
+      management, password reset and policy changes; no hidden weaker route.
+- [x] Tests for fresh-but-insufficient proof, wrong account/session/purpose,
+      expiry, lost response, cancellation and attempted policy bypass.
+
+## 6. Complete passkeys and credential management — slice E, U3–U7
+
+- [x] Registration with discoverable credentials, server-enforced user
+      verification and transaction binding to an existing account.
+- [x] Discoverable sign-in with credential/userHandle ownership checks;
+      explicit and conditional-autofill UI share the same verification path.
+- [x] Native browser support for another device/security key, neutral cancel,
+      understandable retry/fallback and strict-policy unavailable states.
+- [x] First-passkey bootstrap and additional-passkey enrollment require
+      appropriate fresh proof. The optional post-login invitation is a host product
+      choice; v1 supplies the authenticated `/passkeys` entry point.
+- [x] Credential list, rename, remove, notifications and atomic last-usable-method
+      checks; default/strict recovery works with enrollment and lost-device flows.
+- [x] Correct sign-counter anomaly/backup-flag handling, with atomic counter
+      updates and tests for zero, equal, increasing and decreasing counters.
+- [x] Exact origin/RP policy, single-use server transactions, one shared codec,
+      payload bounds and cleanup of pending browser ceremonies.
+- [x] Virtual-authenticator and real-store coverage of success, UV/signature/
+      origin/ownership failures, replay, races, management and recovery.
+
+## 7. Challenge adapters and accessible failure paths — slice F, U9
+
+- [x] Turnstile adapter with hostname/action checks, provider-owned lifetime,
+      bounded HTTPS timeouts and safe no-retry handling for single-use tokens.
+- [x] reCAPTCHA v2/v3 adapters respecting their different verification fields
+      and configured score/action requirements where applicable.
+- [x] Shared success/rejected/unavailable behavior, fail-closed default and
+      observable explicit fail-open policy; no implicit bypass without JS.
+- [x] Retry/outage messages, preserved input, provider protocol fixtures and no
+      live-provider dependency in routine specs.
+- [x] Local keyboard/focus/status, virtual-authenticator and provider-contract
+      browser coverage in bundled and ejected UI. Broader browser/device and
+      assistive-technology verification remains a host deployment responsibility.
+
+## 8. Generators, ejection and integrated acceptance — slice G
+
+- [x] `add_auth:install` writes inert configuration; session/email feature
+      generators add reviewable wiring and preserve edits on repeat runs.
+- [x] `add_auth:views`, `add_auth:controllers`, `add_auth:javascript` and
+      `add_auth:mailer_views` reuse the same Core policy, presenter and templates.
+- [x] `add_auth:challenge` writes environment-keyed Turnstile/reCAPTCHA config,
+      adds the fixed challenge route and preserves an existing initializer.
+- [x] `add_auth:doctor` checks deployment origins, cookies/session metadata,
+      delivery, migrations and challenge policy/routes.
+- [x] `add_auth:doctor` checks recovery policy and generated-file drift.
+- [x] Every generated flow exercised before and after ejection, with Turbo
+      Drive/Frames/Streams, ordinary HTML, no-JS alternatives and strict denial.
+- [x] Auth-page cache/referrer protections, redacted app/job telemetry,
+      CSRF, safe redirects and correct success/failure HTTP contracts.
+- [x] RSpec strategy/store shared examples and host-facing test helpers,
+      including virtual authenticator lifecycle and delivered-link extraction.
+- [x] Full RSpec, Standard and dependency audit pass on supported local matrices;
+      README/roadmap distinguish working development APIs from release gates.
+- [ ] Exact-commit remote CI/CodeQL and required repository security checks;
+      refresh deployed public documentation when the gem is released.
+
+## 9. Release readiness
+
+- [x] README rewritten from skeleton status to verified usage and migration
+      instructions, linking to maintained public API docs as they ship.
+- [x] Security policy updated for shipped strategies, recovery limits and
+      supported versions; redacted events and incident/rollback guidance documented.
+- [ ] CHANGELOG entries and successful Trusted Publishing release; a tag or
+      configured workflow alone does not prove the gem was published.
+- [x] Local enabled-journey, delivery-retry/restart, expiry and transaction rollback
+      evidence. Record 0.2 operational defaults and host deployment responsibilities.
+- [x] Audit adopter-requested changes against stock Rails behavior; keep app roles,
+      invitations, authorization and email themes in the host.
+- [ ] `v1.0.0` only after the integrated acceptance gates pass.
+
+## v2 — reassess after v1 usage
+
+- [ ] AddAuth-owned password registration/reset, confirmation, lockout and
+      password policy. Existing host password integration is part of v1.
+- [ ] Password-hashing adapter seam, following the canonical cryptography
+      policy and Rails support available at implementation time.
+- [ ] Recovery codes; they are not an implied fallback for v1 strict policy.
+- [ ] Multiple realms/routing scopes.
+
+## Decisions before they become dependencies
+
+Owner and deadline details remain in the canonical plan's section 16.
+
+- [x] Review the 0.2 configuration and public integration contract. The runtime
+      uses Rails-generator User/Session conventions; authentication models must
+      share one database connection pool and cross-pool writes are rejected.
+- [x] Review lifetime/resend/legacy-bridge defaults and local failure evidence;
+      retention is opt-in, and key changes require a host deployment plan.
+- [x] Framework-neutral mail and virtual-authenticator helpers; no
+      Minitest-specific integration DSL. AddAuth's own suite stays RSpec.
+- [ ] Revisit API/token authentication after v1; outside current scope.
+
+## Potential standalone libraries
+
+- [ ] Virtual-authenticator test helpers.
+- [ ] Challenge adapter contract and its three-state result.

data/SECURITY.md

@@ -0,0 +1,75 @@
+# Security policy
+
+AddAuth handles authentication credentials -- passwords (via the host app),
+passkeys, session and sign-in tokens, and cryptographic digests. Please report
+suspected vulnerabilities privately rather than opening a public issue.
+
+## Reporting a vulnerability
+
+Use GitHub's private vulnerability reporting for this repository:
+https://github.com/taimoorq/add_auth/security/advisories/new
+
+If that isn't available to you, email taimoorq@gmail.com with:
+
+- A description of the vulnerability and its potential impact.
+- Steps to reproduce, or a proof-of-concept if you have one.
+- The AddAuth version, Rails version, and Ruby version involved.
+
+Please do not disclose the issue publicly (including in a GitHub issue,
+mailing list, or social media) until a fix has been released.
+
+## What's in scope
+
+- The `AddAuth::Core` cryptographic and authentication logic (token issuance
+  and consumption, session adoption/resume/revocation, session/sign-in
+  digesting, rate limiting and account eligibility).
+- The encrypted email intake/outbox, worker retry/lease semantics and default
+  mail logging, plus the durable security-notification outbox.
+- WebAuthn registration/assertion, UV, origin/RP and ownership verification,
+  single-use ceremonies, counters, last-credential concurrency and management.
+- Purpose-bound password/email/passkey reauthentication, bearer rotation,
+  trusted-address recovery, strict policy and host mutation-guard contracts.
+- The Turnstile and reCAPTCHA challenge adapters, their server-side verification
+  contract and scoped browser lifecycle, including failure, outage and Turbo
+  replacement handling.
+- Bounded session listing and authentication-history cleanup, including account
+  scoping, eligibility rechecks and active-delivery-lease protection.
+- The generated controllers and views this gem ships,
+  including their CSRF, enumeration-safety, and Turbo-Stream behavior.
+- The GitHub Actions release pipeline (`.github/workflows/push_gem.yml`) and
+  its Trusted Publishing configuration.
+
+Vulnerabilities in Rails itself, in `webauthn-ruby`, or in `bcrypt`/`argon2`
+should be reported to those projects directly; AddAuth will pick up fixed
+releases via Dependabot (see `AGENTS.md` in the companion workspace repo for
+the currency policy).
+
+## Supported versions
+
+Until a 1.0 is released, only the latest published version receives security
+fixes. This table will be expanded once there are stable release lines to
+support.
+
+| Version | Supported |
+| ------- | --------- |
+| latest 0.x | :white_check_mark: |
+| older 0.x  | :x: |
+
+## Response expectations
+
+This is currently a single-maintainer project. Please allow a reasonable
+window for an initial response before following up, and understand that a fix
+timeline depends on severity and complexity.
+
+## Recovery and deployment boundaries
+
+The 0.2 line includes default email replacement only when
+an explicit host callback returns a verified recovery address. Strict accounts
+cannot use password or email recovery; they require a remaining passkey or the
+host's documented support process. Password reset and feature disablement must
+not relax strict policy. Report any contrary behavior as a policy bypass.
+
+See README's operations and rollback instructions for log filtering, encrypted
+outbox handling, key rotation and migration safety. Hosts own account eligibility,
+address confirmation, resource authorization, SMTP/queue/cache/proxy configuration
+and support recovery. A local test suite does not certify those deployments.

data/app/controllers/add_auth/assets_controller.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "add_auth/rails/ejection"
+
+module AddAuth
+  # Fixed gem assets only. This works even in hosts without an asset pipeline.
+  class AssetsController < ActionController::API
+    # Stateless public files: no cookies, sessions or authenticated response data.
+    before_action do
+      response.set_header("Cross-Origin-Resource-Policy", "same-origin")
+      unless request.get? || request.head?
+        response.set_header("Allow", "GET, HEAD")
+        head :method_not_allowed
+      end
+    end
+    def stylesheet
+      expires_in 1.hour, public: true
+      send_file Rails::Engine.root.join("lib/generators/add_auth/email_link/templates/add_auth.css"),
+        type: "text/css", disposition: "inline"
+    end
+
+    def boot
+      source = 'if (!window.Turbo) await import("/add_auth/turbo.js"); await import("/add_auth/challenge.js");'
+      source += ' await import("/add_auth/passkey.js");' if Rails::Runtime.config.passkeys.enabled
+      render body: source, content_type: "text/javascript"
+    end
+
+    def turbo
+      expires_in 1.hour, public: true
+      source = File.read(Gem.loaded_specs.fetch("turbo-rails").full_gem_path + "/app/assets/javascripts/turbo.min.js")
+      render body: source, content_type: "text/javascript"
+    end
+
+    def stimulus
+      expires_in 1.hour, public: true
+      source = File.read(Gem.loaded_specs.fetch("stimulus-rails").full_gem_path + "/app/assets/javascripts/stimulus.min.js")
+      render body: source, content_type: "text/javascript"
+    end
+
+    %w[application codec passkey].each do |asset|
+      define_method(asset) do
+        expires_in 1.hour, public: true
+        send_file Rails::Ejection.new(host_root: ::Rails.root).asset(asset),
+          type: "text/javascript", disposition: "inline"
+      end
+    end
+
+    def challenge
+      expires_in 1.hour, public: true
+      send_file Rails::Ejection.new(host_root: ::Rails.root).asset("challenge"),
+        type: "text/javascript", disposition: "inline"
+    end
+  end
+end

data/app/controllers/add_auth/passkeys_controller.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module AddAuth
+  class PasskeysController < ::ApplicationController
+    include Rails::AuthenticationPages
+
+    helper AddAuth::SignInsHelper
+    skip_before_action :require_authentication, raise: false
+    before_action :private_response
+    before_action :enabled_feature
+    before_action :require_add_auth_authentication, only: %i[index registration_options register rename remove change_policy reauthentication_options reauthenticate]
+    protect_from_forgery with: :exception
+    rescue_from AddAuth::Error, with: :service_unavailable
+
+    def index
+      @credentials = service.list(user: Current.user, session: Current.session)
+      @strict = Rails::Runtime.access_policy.strict?(Current.user)
+      page("list")
+    end
+
+    def registration_options
+      return unless admitted(:passkey_enrollment)
+      options(service.registration_options(user: Current.user, session: Current.session, browser_secret: browser_secret))
+    end
+
+    def register
+      return unless admitted(:passkey_finish)
+      result = service.register(transaction: params[:transaction], credential_response: credential_payload,
+        user: Current.user, session: Current.session, browser_secret: browser_secret, nickname: params[:nickname])
+      finish(result, destination: "/passkeys", grant: result.grant)
+    end
+
+    def authentication_options
+      return unless admitted(:sign_in)
+      options(service.authentication_options(browser_secret: browser_secret))
+    end
+
+    def authenticate
+      return unless admitted(:passkey_finish)
+      result = service.authenticate(transaction: params[:transaction], credential_response: credential_payload,
+        browser_secret: browser_secret, replacing: add_auth_replacement_session, **add_auth_session_hints)
+      finish(result, destination: result.success? ? after_authentication_url : "/", grant: result.success? ? result.credential : nil)
+    end
+
+    def reauthentication_options
+      return unless admitted(:reauthenticate)
+      options(service.authentication_options(browser_secret: browser_secret, user: Current.user,
+        session: Current.session, purpose: params[:purpose]))
+    end
+
+    def reauthenticate
+      return unless admitted(:passkey_finish)
+      result = service.authenticate(transaction: params[:transaction], credential_response: credential_payload,
+        browser_secret: browser_secret, session: Current.session)
+      destination = result.success? ? Rails::Runtime.step_up_policy.return_to(result.session.elevation_purpose) : "/"
+      finish(result, destination: destination, grant: result.success? ? result.credential : nil)
+    end
+
+    def rename
+      management(service.rename(user: Current.user, session: Current.session, id: params[:id], nickname: params[:nickname]))
+    end
+
+    def remove
+      management(service.remove(user: Current.user, session: Current.session, id: params[:id]))
+    end
+
+    def change_policy
+      result = service.change_policy(user: Current.user, session: Current.session,
+        strict: {"strict" => true, "default" => false}[params[:policy]], acknowledged: params[:acknowledged] == "1")
+      add_auth_accept(result.credential) if result.success?
+      management(result, purpose: :manage_policy)
+    end
+
+    def cancel
+      service.cancel(transaction: params[:transaction], browser_secret: session[:add_auth_browser])
+      head :no_content
+    end
+
+    private
+
+    def service = Rails::Runtime.passkeys
+    def browser_secret = session[:add_auth_browser] ||= Rails::Runtime.browser_binding.generate
+
+    def enabled_feature
+      head :not_found unless Rails::Runtime.config.passkeys.enabled
+    end
+
+    def authentication_partial(partial) = "add_auth/passkeys/#{partial}"
+
+    def credential_payload
+      value = params[:credential]
+      value.to_unsafe_h if value.is_a?(ActionController::Parameters)
+    end
+
+    def admitted(action)
+      result = Rails::Runtime.intake.anonymous(ip: request.remote_ip, action: action, challenge_token: challenge_token)
+      return true if result == true
+      render json: {error: "Verification could not start. Try again shortly."}, status: if result == :rate_limited
+                                                                                          429
+                                                                                        else
+                                                                                          (result == :challenge_unavailable) ? 503 : 422
+                                                                                        end
+      false
+    end
+
+    def options(result)
+      return render(json: result.credential) if result.success?
+      return render(json: {error: "Verification could not start. Try again shortly."}, status: :too_many_requests) if result.reason == :rate_limited
+      error(result)
+    end
+
+    def finish(result, destination:, grant:)
+      return error(result) unless result.success?
+      add_auth_accept(grant) if grant
+      render json: {redirect: Core::Sessions.safe_return(destination) || "/"}
+    end
+
+    def error(result)
+      payload = {error: "Verification did not complete. Try another passkey or an allowed recovery method."}
+      if result.reason == :elevation_required && %w[registration_options register].include?(action_name)
+        payload[:redirect] = "/reauthenticate?purpose=manage_passkeys"
+      end
+      render json: payload, status: :unprocessable_entity
+    end
+
+    def management(result, purpose: :manage_passkeys)
+      if result.success?
+        redirect_to "/passkeys", status: :see_other
+      elsif result.reason == :elevation_required
+        redirect_to "/reauthenticate?#{URI.encode_www_form(purpose: purpose)}", status: :see_other
+      else
+        @error = "That change could not be made. Keep a usable sign-in method and check your selection."
+        @credentials = service.list(user: Current.user, session: Current.session)
+        @strict = Rails::Runtime.access_policy.strict?(Current.user)
+        page("list", status: :unprocessable_entity)
+      end
+    end
+
+    def service_unavailable
+      response.set_header("Retry-After", "60")
+      render json: {error: "Passkeys are temporarily unavailable. Try again shortly."}, status: :service_unavailable
+    end
+  end
+end

data/app/controllers/add_auth/reauthentications_controller.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module AddAuth
+  class ReauthenticationsController < ::ApplicationController
+    include Rails::AuthenticationPages
+
+    helper AddAuth::SignInsHelper
+    skip_before_action :require_authentication, raise: false
+    before_action :private_response
+    before_action :enabled_feature
+    before_action :require_add_auth_authentication, except: %i[link confirm]
+    before_action :load_purpose, only: %i[new password request_link check_email]
+    protect_from_forgery with: :exception
+    rescue_from AddAuth::Error, "ActiveJob::EnqueueError", with: :service_unavailable
+
+    def new = page("form")
+
+    def password
+      result = Rails::Runtime.elevate_password(user: Current.user, session: Current.session,
+        purpose: @purpose, password: params[:password], ip: request.remote_ip, challenge_token: challenge_token)
+      finish(result)
+    end
+
+    def request_link
+      admitted = Rails::Runtime.intake.call(identifier: Current.user.email_address, ip: request.remote_ip,
+        action: :reauthenticate, challenge_token: challenge_token)
+      return intake_failure(admitted) if %i[challenge_rejected challenge_unavailable].include?(admitted)
+      unless admitted.is_a?(Symbol)
+        session[:add_auth_browser] ||= Rails::Runtime.browser_binding.generate
+        Rails::Runtime.enqueue_reauthentication(user: Current.user, session: Current.session,
+          purpose: @purpose, browser_secret: session[:add_auth_browser])
+      end
+      redirect_to "/reauthenticate/check-email?#{URI.encode_www_form(purpose: @purpose)}", status: :see_other
+    end
+
+    def check_email = page("check_email")
+
+    def link
+      @preview = service.preview(token: params[:token], browser_secret: session[:add_auth_browser])
+      page(service.confirmation_page(@preview))
+    end
+
+    def confirm
+      result = service.reauthenticate(token: params[:token], session: add_auth_replacement_session,
+        browser_secret: session[:add_auth_browser])
+      finish(result, failure_page: "invalid_link")
+    end
+
+    private
+
+    def service = Rails::Runtime.email(purpose: :reauthentication)
+
+    def enabled_feature
+      head :not_found unless Rails::Runtime.config.step_up.enabled
+    end
+
+    def load_purpose
+      @rule = Rails::Runtime.step_up_policy.reauthentication_rule_for(params[:purpose])
+      return head :not_found unless @rule
+      @purpose = params[:purpose].to_s
+      @methods = Rails::Runtime.step_up_policy.methods_for(user: Current.user, purpose: @purpose)
+    end
+
+    def finish(result, failure_page: "form")
+      if result.success?
+        destination = Rails::Runtime.step_up_policy.return_to(result.session.elevation_purpose)
+        add_auth_accept(result.credential)
+        redirect_to destination, status: :see_other
+      else
+        @error = "We could not verify this request. Try again from the browser where you started."
+        if %i[rate_limited challenge_rejected challenge_unavailable].include?(result.reason)
+          intake_failure(result.reason)
+        else
+          page(failure_page, status: :unprocessable_entity)
+        end
+      end
+    end
+
+    def authentication_partial(partial) = "add_auth/reauthentications/#{partial}"
+  end
+end

data/app/controllers/add_auth/recoveries_controller.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module AddAuth
+  class RecoveriesController < ::ApplicationController
+    include Rails::AuthenticationPages
+
+    helper AddAuth::SignInsHelper
+    skip_before_action :require_authentication, raise: false
+    before_action :private_response
+    before_action :enabled_feature
+    protect_from_forgery with: :exception
+    rescue_from AddAuth::Error, "ActiveJob::EnqueueError", with: :service_unavailable
+
+    def new = page("form")
+    def check_email = page("check_email")
+
+    def request_link
+      value = Rails::Runtime.intake.call(identifier: params[:email_address], ip: request.remote_ip,
+        action: :email_link, challenge_token: challenge_token)
+      return intake_failure(value) if %i[challenge_rejected challenge_unavailable].include?(value)
+      Rails::Runtime.enqueue_recovery(value) unless value.is_a?(Symbol)
+      redirect_to "/recover/check-email", status: :see_other
+    end
+
+    def link
+      @preview = service.preview(token: params[:token])
+      page(service.confirmation_page(@preview))
+    end
+
+    def confirm
+      result = service.consume(token: params[:token], current_session: add_auth_replacement_session,
+        switch_account: params[:switch_account] == "1")
+      if result.success?
+        add_auth_accept(result.grant)
+        redirect_to "/passkeys", status: :see_other
+      else
+        page("invalid_link", status: :unprocessable_entity)
+      end
+    end
+
+    private
+
+    def service = Rails::Runtime.email(purpose: :recovery)
+    def authentication_partial(partial) = "add_auth/recoveries/#{partial}"
+
+    def enabled_feature
+      head :not_found unless Rails::Runtime.config.passkeys.enabled
+    end
+  end
+end