passkeyed 0.1.0

data/lib/generators/passkeyed/install/templates/passkey_controller.js

@@ -0,0 +1,246 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Drives the two WebAuthn ceremonies from the browser. The endpoints are
+// supplied as Stimulus values, so this controller stays app-agnostic:
+//
+//   <div data-controller="passkey"
+//        data-passkey-registration-options-url-value="/passkeys/registration_options"
+//        data-passkey-registration-url-value="/passkeys"
+//        data-passkey-redirect-url-value="/dashboard">
+//     <input data-passkey-target="nickname">
+//     <button data-action="passkey#register">Add a passkey</button>
+//     <p data-passkey-target="error" role="alert"></p>
+//   </div>
+//
+// Serialisation uses the browser's own PublicKeyCredential JSON methods
+// (parseCreationOptionsFromJSON / parseRequestOptionsFromJSON / toJSON), which
+// handle the base64url <-> ArrayBuffer conversion natively — no JavaScript
+// dependency needed.
+//
+// Set data-passkey-conditional-value="true" on a sign-in form to also offer
+// passkeys through the browser's autofill (conditional UI). Pair it with an
+// <input autocomplete="username webauthn"> inside the same element.
+//
+// After a successful ceremony the controller dispatches a cancelable
+// "passkey:registered" / "passkey:authenticated" event (detail: the server's
+// JSON response) and then follows data-passkey-redirect-url-value (or reloads).
+// Call event.preventDefault() in a listener to handle the outcome yourself.
+export default class extends Controller {
+  static values = {
+    registrationOptionsUrl: String,
+    registrationUrl: String,
+    authenticationOptionsUrl: String,
+    authenticationUrl: String,
+    redirectUrl: String,
+    conditional: Boolean
+  }
+
+  static targets = ["error", "nickname"]
+
+  // Re-entrancy guard: a second ceremony would rotate the server's challenge
+  // and make the first fail confusingly.
+  #busy = false
+
+  // Aborts the pending conditional (autofill) request: browsers allow only one
+  // in-flight WebAuthn request, so a modal ceremony must cancel it first.
+  #conditionalAbort = null
+
+  connect() {
+    if (this.conditionalValue) this.#startConditional()
+  }
+
+  disconnect() {
+    this.#abortConditional()
+  }
+
+  async register(event) {
+    event.preventDefault()
+    await this.#runCeremony(event, async () => {
+      const optionsJSON = await this.#postJson(this.registrationOptionsUrlValue)
+      const options = window.PublicKeyCredential.parseCreationOptionsFromJSON(optionsJSON)
+      // Prompts for Touch ID / Windows Hello / a PIN and mints the key pair
+      // inside the device's secure hardware.
+      const credential = await navigator.credentials.create({ publicKey: options })
+
+      const body = { credential: credential.toJSON() }
+      if (this.hasNicknameTarget && this.nicknameTarget.value) {
+        body.nickname = this.nicknameTarget.value
+      }
+
+      const response = await this.#postJson(this.registrationUrlValue, body)
+      this.#finish("registered", response)
+    })
+  }
+
+  async authenticate(event) {
+    event.preventDefault()
+    await this.#runCeremony(event, async () => {
+      const response = await this.#assert()
+      this.#finish("authenticated", response)
+    })
+  }
+
+  // The assertion ceremony shared by the modal button and the autofill path:
+  // fetch options, let the authenticator sign, post the assertion back.
+  async #assert(mediationOptions = {}) {
+    const optionsJSON = await this.#postJson(this.authenticationOptionsUrlValue)
+    const options = window.PublicKeyCredential.parseRequestOptionsFromJSON(optionsJSON)
+    // The browser shows the account picker and asks for the user's gesture.
+    const credential = await navigator.credentials.get({
+      publicKey: options,
+      ...mediationOptions
+    })
+
+    return this.#postJson(this.authenticationUrlValue, { credential: credential.toJSON() })
+  }
+
+  // Conditional UI: park an assertion request behind the browser's autofill,
+  // so a <input autocomplete="username webauthn"> offers stored passkeys. The
+  // request hangs until the user picks one (or it is aborted), so it must not
+  // take the busy lock that guards the modal ceremonies.
+  async #startConditional() {
+    if (!this.#webAuthnAvailable()) return
+    if (!window.PublicKeyCredential.isConditionalMediationAvailable) return
+    if (!(await window.PublicKeyCredential.isConditionalMediationAvailable())) return
+    if (this.#conditionalAbort) return
+
+    this.#conditionalAbort = new AbortController()
+    let restart = false
+    try {
+      const response = await this.#assert({
+        mediation: "conditional",
+        signal: this.#conditionalAbort.signal
+      })
+      this.#finish("authenticated", response)
+    } catch (error) {
+      this.#handleError(error)
+      // Re-arm autofill unless the abort was deliberate (a modal ceremony took
+      // over, or the element disconnected). The user dismissing the sheet, or
+      // the server rejecting the assertion (say, an expired challenge in an
+      // idle tab), would otherwise leave passkey autofill dead until a reload.
+      restart = error.name !== "AbortError"
+    } finally {
+      this.#conditionalAbort = null
+    }
+    if (restart) this.#startConditional()
+  }
+
+  #abortConditional() {
+    if (this.#conditionalAbort) {
+      this.#conditionalAbort.abort()
+      this.#conditionalAbort = null
+    }
+  }
+
+  // Shared ceremony scaffolding: feature-detect, guard against double-submit,
+  // disable the button for the duration, then run the body. On failure the
+  // conditional request is restarted so autofill keeps working after a
+  // cancelled modal prompt.
+  async #runCeremony(event, body) {
+    if (this.#busy) return
+    this.#clearError()
+
+    if (!this.#webAuthnAvailable()) {
+      this.#showMessage("Passkeys aren't available in this browser.")
+      return
+    }
+
+    this.#abortConditional()
+
+    const button = event.currentTarget
+    this.#busy = true
+    if (button) button.disabled = true
+
+    try {
+      await body()
+    } catch (error) {
+      this.#handleError(error)
+      if (this.conditionalValue) this.#startConditional()
+    } finally {
+      this.#busy = false
+      if (button) button.disabled = false
+    }
+  }
+
+  async #postJson(url, body) {
+    const headers = {
+      "Content-Type": "application/json",
+      Accept: "application/json"
+    }
+    // Only send the header when the token exists; otherwise fetch coerces
+    // `undefined` to the literal string "undefined" and the POST 422s.
+    const csrfToken = this.#csrfToken()
+    if (csrfToken) headers["X-CSRF-Token"] = csrfToken
+
+    const response = await fetch(url, {
+      method: "POST",
+      credentials: "same-origin",
+      headers,
+      body: body ? JSON.stringify(body) : "{}"
+    })
+
+    if (!response.ok) {
+      const data = await response.json().catch(() => ({}))
+      throw new Error(data.error || `Request failed (${response.status})`)
+    }
+
+    return response.json()
+  }
+
+  // Requires the native JSON serialisation methods alongside WebAuthn itself;
+  // both have shipped in every major browser (see MDN: PublicKeyCredential).
+  #webAuthnAvailable() {
+    return Boolean(
+      window.PublicKeyCredential &&
+        window.isSecureContext &&
+        window.PublicKeyCredential.parseCreationOptionsFromJSON &&
+        window.PublicKeyCredential.parseRequestOptionsFromJSON
+    )
+  }
+
+  #csrfToken() {
+    return document.querySelector("meta[name='csrf-token']")?.content
+  }
+
+  #handleError(error) {
+    // Cancelling the OS prompt or letting it time out rejects with
+    // NotAllowedError (and AbortError for an aborted request) — a normal
+    // outcome, not something to show as a failure.
+    if (error.name === "NotAllowedError" || error.name === "AbortError") return
+
+    this.#showError(error)
+  }
+
+  // Announce the outcome, then redirect unless a listener claimed it.
+  #finish(eventName, detail) {
+    const event = this.dispatch(eventName, { detail, cancelable: true })
+    if (event.defaultPrevented) return
+
+    this.#redirect()
+  }
+
+  #redirect() {
+    if (this.hasRedirectUrlValue) {
+      window.location.assign(this.redirectUrlValue)
+    } else {
+      window.location.reload()
+    }
+  }
+
+  #showError(error) {
+    this.dispatch("error", { detail: { error } })
+    this.#showMessage(error.message)
+  }
+
+  #showMessage(message) {
+    if (this.hasErrorTarget) {
+      this.errorTarget.textContent = message
+    } else {
+      console.error(message)
+    }
+  }
+
+  #clearError() {
+    if (this.hasErrorTarget) this.errorTarget.textContent = ""
+  }
+}

data/lib/passkeyed/ceremonies.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+module Passkeyed
+  # Controller-side helpers for the two WebAuthn ceremonies. Include in a
+  # controller (it relies on +session+):
+  #
+  #   class SessionsController < ApplicationController
+  #     include Passkeyed::Ceremonies
+  #   end
+  #
+  # Each ceremony is the same shape: issue a challenge, let the authenticator
+  # sign it, verify the signature. The +*_options+ methods stash the challenge
+  # in the session; the bang methods consume it and verify.
+  #
+  # Both bang methods emit an ActiveSupport::Notifications event
+  # ("register.passkeyed" / "authenticate.passkeyed") whose payload carries
+  # +:credential+ and +:user+ on success and the standard +:exception+ keys on
+  # failure — subscribe to observe failed sign-ins, which the success-only
+  # after_* hooks never see.
+  module Ceremonies
+    # Build creation options for a passwordless, discoverable credential and
+    # remember the challenge. Render the return value as JSON to the browser.
+    def passkey_registration_options(user)
+      # Resolve (and, for a pre-existing user, lazily assign) the WebAuthn user
+      # handle before building options, so user.id is never nil in the JSON.
+      user_handle = user.passkeyed_webauthn_id!
+
+      options = WebAuthn::Credential.options_for_create(
+        user: {
+          id: user_handle,
+          name: user.passkey_name,
+          display_name: user.passkey_display_name
+        },
+        exclude: user.passkeyed_credentials.pluck(:external_id),
+        authenticator_selection: {
+          resident_key: "required",
+          user_verification: Passkeyed.configuration.user_verification
+        },
+        relying_party: Passkeyed.configuration.relying_party
+      )
+
+      stash_challenge(Passkeyed.configuration.registration_challenge_key, options.challenge)
+      options
+    end
+
+    # Verify a registration response against the stored challenge and persist
+    # the new credential. Returns the Passkeyed::Credential, or raises
+    # Passkeyed::RegistrationError / ChallengeMissing / ChallengeExpired.
+    def passkey_register!(user, credential, nickname: nil)
+      record = ActiveSupport::Notifications.instrument("register.passkeyed", user: user) do |payload|
+        verify_registration(user, credential, nickname: nickname).tap do |created|
+          payload[:credential] = created
+        end
+      end
+
+      # Outside the instrumented block and the ceremony's rescues, so a raising
+      # hook surfaces as itself and doesn't mark the ceremony event as failed.
+      after_passkey_registration(record)
+      record
+    end
+
+    # Build request options for a passwordless sign-in. No allow-list is sent,
+    # so the authenticator offers whatever discoverable passkeys it holds for
+    # this site. Remembers the challenge; render the return value as JSON.
+    def passkey_authentication_options
+      options = WebAuthn::Credential.options_for_get(
+        user_verification: Passkeyed.configuration.user_verification,
+        relying_party: Passkeyed.configuration.relying_party
+      )
+
+      stash_challenge(Passkeyed.configuration.authentication_challenge_key, options.challenge)
+      options
+    end
+
+    # Verify an authentication response. Resolves the credential by its id,
+    # checks the signature against the stored public key and challenge, enforces
+    # user verification when configured, bumps the signature counter, and
+    # returns the owning record. Raises Passkeyed::AuthenticationError /
+    # CredentialNotFound / ChallengeMissing / ChallengeExpired.
+    def passkey_authenticate!(credential)
+      stored = ActiveSupport::Notifications.instrument("authenticate.passkeyed", {}) do |payload|
+        verify_authentication(credential).tap do |verified|
+          payload[:credential] = verified
+          payload[:user] = verified.user
+        end
+      end
+
+      after_passkey_authentication(stored, stored.user)
+      stored.user
+    end
+
+    private
+
+    # The registration ceremony proper: consume the challenge, verify the
+    # attestation, persist. Kept apart from passkey_register! so its rescues
+    # never rewrite an exception raised by the after_* hook.
+    def verify_registration(user, credential, nickname: nil)
+      challenge = consume_challenge(Passkeyed.configuration.registration_challenge_key, "registration")
+
+      webauthn_credential = parse_credential(:from_create, credential, Passkeyed::RegistrationError)
+
+      # user_verification: true makes webauthn-ruby check the User-Verified flag
+      # server-side, which is what actually enforces the configured policy. The
+      # value sent to the client is only advisory.
+      webauthn_credential.verify(challenge, user_verification: passkeyed_user_verification?)
+
+      user.passkeyed_credentials.create!(
+        external_id: webauthn_credential.id,
+        public_key: webauthn_credential.public_key,
+        sign_count: webauthn_credential.sign_count,
+        nickname: nickname.presence,
+        **credential_metadata(webauthn_credential)
+      )
+    rescue WebAuthn::Error => e
+      raise Passkeyed::RegistrationError, e.message
+    rescue ActiveRecord::RecordNotUnique
+      # A check-then-insert race past the uniqueness validation would otherwise
+      # escape as a 500. Surface it as a typed "already registered" error.
+      raise Passkeyed::RegistrationError, "Credential already registered"
+    rescue ActiveRecord::RecordInvalid => e
+      # A credential id already on record (a double-submit, or a credential held
+      # by another account) is the common validation failure; report it as
+      # "already registered". Any other invalidity — e.g. an over-long nickname —
+      # surfaces its own message rather than being mislabeled.
+      raise Passkeyed::RegistrationError, "Credential already registered" if
+        e.record.errors.of_kind?(:external_id, :taken)
+
+      raise Passkeyed::RegistrationError, e.record.errors.full_messages.to_sentence
+    end
+
+    # The authentication ceremony proper; see verify_registration for why it is
+    # separate from passkey_authenticate!.
+    def verify_authentication(credential)
+      challenge = consume_challenge(Passkeyed.configuration.authentication_challenge_key, "authentication")
+
+      webauthn_credential = parse_credential(:from_get, credential, Passkeyed::AuthenticationError)
+
+      stored = Passkeyed::Credential.find_by(external_id: webauthn_credential.id)
+      # CredentialNotFound is a subclass of AuthenticationError, so a single
+      # `rescue Passkeyed::AuthenticationError` collapses both outcomes; do that
+      # in your controller and return one generic message to avoid leaking
+      # whether a credential id is on record.
+      raise Passkeyed::CredentialNotFound, "Unknown credential" unless stored
+
+      # The owner association is polymorphic, so there is no foreign key: a
+      # credential can outlive its owner when rows are removed without callbacks
+      # (delete/delete_all, raw SQL). Same error and message as an unknown id,
+      # so nothing is leaked about the orphan.
+      owner = stored.user
+      raise Passkeyed::CredentialNotFound, "Unknown credential" if owner.nil?
+
+      # Defense in depth: a discoverable assertion carries the user handle the
+      # authenticator stored. When present, it must match the credential's owner;
+      # a mismatch means the credential/owner mapping doesn't line up.
+      asserted_handle = webauthn_credential.user_handle
+      if asserted_handle.present? && owner.webauthn_id != asserted_handle
+        raise Passkeyed::AuthenticationError, "Credential does not match its owner"
+      end
+
+      webauthn_credential.verify(
+        challenge,
+        public_key: stored.public_key,
+        sign_count: stored.sign_count,
+        user_verification: passkeyed_user_verification?
+      )
+
+      stored.record_sign_in!(webauthn_credential.sign_count, backed_up: webauthn_credential.backed_up?)
+      stored
+    rescue WebAuthn::Error => e
+      raise Passkeyed::AuthenticationError, e.message
+    end
+
+    # Overridable hooks, called after a ceremony succeeds. Defaults are no-ops;
+    # override in your controller to audit-log, send a "new device" email, bump a
+    # "last used" timestamp, etc. They run with full controller context (request,
+    # current_user) and outside the ceremony's error handling, so an exception
+    # raised here propagates unchanged rather than becoming a Passkeyed::Error.
+    def after_passkey_registration(credential); end
+
+    def after_passkey_authentication(credential, user); end
+
+    # Where challenges are stashed. Defaults to the controller's session;
+    # overridable (and easy to stub in tests).
+    def passkeyed_session
+      session
+    end
+
+    # Challenges are stored with their issue time (string keys survive the
+    # cookie session's JSON round-trip) so consumption can enforce a lifetime.
+    def stash_challenge(key, challenge)
+      passkeyed_session[key] = { "challenge" => challenge, "issued_at" => Time.now.to_i }
+    end
+
+    # Read-and-delete the stashed challenge: single-use by construction. Raises
+    # ChallengeMissing when absent (or not in the expected hash format) and
+    # ChallengeExpired when older than the configured challenge_timeout.
+    def consume_challenge(key, ceremony)
+      stash = passkeyed_session.delete(key)
+      challenge = stash["challenge"] if stash.is_a?(Hash)
+      raise Passkeyed::ChallengeMissing, "No #{ceremony} challenge in session" if challenge.blank?
+
+      age = Time.now.to_i - stash["issued_at"].to_i
+      if age > Passkeyed.configuration.challenge_timeout
+        raise Passkeyed::ChallengeExpired, "The #{ceremony} challenge has expired; restart the ceremony"
+      end
+
+      challenge
+    end
+
+    # Authenticator metadata worth keeping for a credential-management UI:
+    # whether the passkey is synced (backed up) or device-bound, how the
+    # authenticator talks to clients, and which authenticator model minted it.
+    # Each attribute is guarded on its column so apps that trimmed the optional
+    # columns from the generated migration keep registering.
+    def credential_metadata(webauthn_credential)
+      columns = Passkeyed::Credential.column_names
+      metadata = {}
+      metadata[:backup_eligible] = webauthn_credential.backup_eligible? if columns.include?("backup_eligible")
+      metadata[:backed_up] = webauthn_credential.backed_up? if columns.include?("backed_up")
+      metadata[:transports] = webauthn_credential.response.transports.presence if columns.include?("transports")
+      metadata[:aaguid] = webauthn_credential.response.aaguid if columns.include?("aaguid")
+      metadata
+    end
+
+    # True when the configured policy demands the User-Verified flag. webauthn-ruby
+    # treats a truthy value as "enforce UV".
+    def passkeyed_user_verification?
+      Passkeyed.configuration.user_verification == "required"
+    end
+
+    # Parse a browser credential into a webauthn-ruby object, turning malformed
+    # input into a clean Passkeyed error instead of a stray NoMethodError that
+    # would surface as a 500. Accepts ActionController::Parameters or a Hash.
+    # The parsed credential carries the relying party its later +verify+ checks
+    # against, so passkeyed's settings apply without touching webauthn-ruby's
+    # global configuration.
+    def parse_credential(method, credential, error_class)
+      WebAuthn::Credential.public_send(
+        method,
+        normalize_credential(credential),
+        relying_party: Passkeyed.configuration.relying_party
+      )
+    rescue WebAuthn::Error
+      raise
+    rescue StandardError
+      raise error_class, "Malformed credential"
+    end
+
+    # Accept ActionController::Parameters (what `params[:credential]` is) as
+    # well as a plain Hash, so callers need not convert by hand.
+    def normalize_credential(credential)
+      credential.respond_to?(:to_unsafe_h) ? credential.to_unsafe_h : credential
+    end
+  end
+end

data/lib/passkeyed/configuration.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Passkeyed
+  # Holds passkeyed's settings. The relevant ones are handed to webauthn-ruby
+  # as an isolated WebAuthn::RelyingParty (see +relying_party+), never written
+  # to WebAuthn's global configuration.
+  #
+  #   Passkeyed.configure do |config|
+  #     config.rp_name          = "Acme"
+  #     config.rp_id            = "acme.example"           # optional
+  #     config.allowed_origins  = ["https://acme.example"] # required when deployed
+  #     config.user_verification = "required"
+  #   end
+  class Configuration
+    # The WebAuthn userVerification enum. We normalize to these exact strings so
+    # the value advertised to the client and the value enforced server-side can
+    # never diverge (a symbol or mis-cased string would silently disable
+    # enforcement while still advertising "required").
+    USER_VERIFICATION_LEVELS = %w[required preferred discouraged].freeze
+
+    # Human-readable name of the relying party (your app), shown by some
+    # authenticators during the ceremony.
+    attr_accessor :rp_name
+
+    # The relying party id (effectively your domain). When nil, webauthn-ruby
+    # derives it from the request origin.
+    attr_accessor :rp_id
+
+    # Array of origins the server will accept assertions from, e.g.
+    # ["https://acme.example"]. Left nil only for local development; required
+    # (https-only) in any deployed environment — see +validate!+.
+    attr_accessor :allowed_origins
+
+    # User-verification requirement for both ceremonies. "required" is what
+    # makes a single passkey gesture genuinely multi-factor. Read via the
+    # accessor; always one of USER_VERIFICATION_LEVELS (see the writer).
+    attr_reader :user_verification
+
+    # Base session key from which the per-ceremony challenge keys are derived
+    # (see +registration_challenge_key+ / +authentication_challenge_key+).
+    attr_accessor :session_key
+
+    # How long (in seconds) a stashed challenge stays valid. A ceremony should
+    # complete within moments; a challenge consumed hours after it was issued
+    # points at a stale tab or a replay attempt, so it is rejected with
+    # Passkeyed::ChallengeExpired. Also advertised to the browser as the
+    # ceremony timeout (via the relying party), so the credential prompt and
+    # the server agree on the lifetime. Read via the accessor; always a
+    # positive Integer (see the writer).
+    attr_reader :challenge_timeout
+
+    def initialize
+      @rp_name = "Passkeyed"
+      @rp_id = nil
+      @allowed_origins = nil
+      self.user_verification = "required"
+      @session_key = :passkeyed_challenge
+      self.challenge_timeout = 300
+    end
+
+    # Normalize and validate on assignment so that, e.g., +:required+ (symbol)
+    # or "Required" can't slip through as a value that is advertised to the
+    # client but not enforced by +verify+. Raises on anything outside the enum.
+    def user_verification=(value)
+      normalized = value.to_s.downcase
+      unless USER_VERIFICATION_LEVELS.include?(normalized)
+        raise Passkeyed::ConfigurationError,
+              "user_verification must be one of #{USER_VERIFICATION_LEVELS.join(", ")}; got #{value.inspect}"
+      end
+
+      @user_verification = normalized
+    end
+
+    # Validate on assignment so a nonsensical timeout (zero, negative, "5m")
+    # fails at boot rather than expiring every challenge or none.
+    def challenge_timeout=(value)
+      seconds = begin
+        Integer(value)
+      rescue TypeError, ArgumentError
+        raise Passkeyed::ConfigurationError,
+              "challenge_timeout must be a positive number of seconds; got #{value.inspect}"
+      end
+
+      unless seconds.positive?
+        raise Passkeyed::ConfigurationError,
+              "challenge_timeout must be a positive number of seconds; got #{value.inspect}"
+      end
+
+      @challenge_timeout = seconds
+    end
+
+    # Distinct session keys for the two ceremonies, derived from +session_key+.
+    # Keeping them separate means a registration and an authentication ceremony
+    # running concurrently in the same session (a background tab, a stale form)
+    # can't overwrite each other's single-use challenge.
+    def registration_challenge_key
+      :"#{session_key}_registration"
+    end
+
+    def authentication_challenge_key
+      :"#{session_key}_authentication"
+    end
+
+    # The WebAuthn::RelyingParty these settings describe, passed explicitly to
+    # every webauthn-ruby entry point. Keeping it off WebAuthn's global
+    # configuration means a host app (or another gem) using webauthn-ruby
+    # directly is never clobbered. Built fresh on each call — the object is
+    # cheap, and this way later configuration writes are always reflected.
+    def relying_party
+      WebAuthn::RelyingParty.new(
+        name: rp_name,
+        id: rp_id,
+        allowed_origins: allowed_origins,
+        # Also advertised to the browser as the ceremony timeout, so the
+        # credential prompt can't outlive the server-side challenge.
+        credential_options_timeout: challenge_timeout * 1000
+      )
+    end
+
+    # Refuse to boot a deployed app with development origins. WebAuthn requires
+    # a secure context, so a blank allow-list or an http:// origin outside
+    # development and test is always a misconfiguration — most often the
+    # generated localhost default left in place. Fail loud at boot rather than
+    # silently rejecting every sign-in (or, worse, trusting an insecure
+    # origin). Runs in every non-local environment (production, staging, any
+    # custom deploy env); no-op in development/test and when Rails isn't
+    # loaded (e.g. the gem's own suite).
+    def validate!
+      return unless enforce_secure_origins?
+
+      if allowed_origins.blank?
+        raise Passkeyed::ConfigurationError,
+              "allowed_origins is required outside development and test; " \
+              "set config.allowed_origins to your HTTPS origin(s)"
+      end
+
+      insecure = allowed_origins.reject { |origin| origin.to_s.start_with?("https://") }
+      return if insecure.empty?
+
+      raise Passkeyed::ConfigurationError,
+            "allowed_origins must use https outside development and test; got #{insecure.inspect} " \
+            "(the generated localhost default cannot be used in a deployed environment)"
+    end
+
+    private
+
+    # True in any deployed environment: everything except Rails.env.local?
+    # (development and test, per Rails >= 7.1 — the gem's declared floor).
+    def enforce_secure_origins?
+      defined?(Rails) && Rails.respond_to?(:env) && !Rails.env.local?
+    end
+  end
+
+  class << self
+    # The ActiveRecord base class Passkeyed::Credential inherits from. Defaults
+    # to the host app's ApplicationRecord when defined (so multi-database
+    # connects_to/role config is inherited), falling back to ActiveRecord::Base.
+    # Set in an initializer to override. Accepts a class or a class name string.
+    #
+    # Ordering matters: the parent class is resolved once, when Credential is
+    # first autoloaded, so assign this before anything references
+    # Passkeyed::Credential (an initializer is early enough; a later assignment
+    # is silently ignored).
+    def base_record_class
+      klass = @base_record_class || (defined?(ApplicationRecord) ? ApplicationRecord : ActiveRecord::Base)
+      klass.is_a?(String) ? klass.constantize : klass
+    end
+
+    attr_writer :base_record_class
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Yields the configuration for editing, then validates it. Call once during
+    # boot (an initializer).
+    def configure
+      yield(configuration) if block_given?
+      configuration.validate!
+      configuration
+    end
+
+    # Mainly for tests: forget all configuration.
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end