unmagic-passkeys 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 645c820a4995965db7ac6d5a146b1c26fa058670ee99159e6b69c2fc4d8c09b9
-  data.tar.gz: f91753169ab1fad8ef5c789319babb20ee59806b3bc0bb6a56fb43075070091c
+  metadata.gz: 6ddd2eb491d1dbf70760a8fa843d6e09284b44d0031178c9312afebed493a3f5
+  data.tar.gz: a173df187a85d06e116321cb203966b6613c924771e294e1308504923d707b49
 SHA512:
-  metadata.gz: 40df919dbc7b4c5e1496bcba443898bb332af4dbe62fe87624f105ce5aa91dd2dd2e9774196a5bebddb5b3713f333343daafd02f928d575dacda5561cef69134
-  data.tar.gz: e3be802090ee4736ba752d702972857224440a95b65b1c3654ab628e33d6e5667f5298d8301968ffb8e2f399a3aa7cfba89237d28b9ab44ccd29ab33e73e43dd
+  metadata.gz: 2091181c23ecdbc5a1e1d0a1e75e7c28faa030158a452ef77c8b4ac171200ec0964cfeed4ffa69346d60b613fdfd93155108ceb009616d8e941a1659869e87ab
+  data.tar.gz: 49727646f8936293eaac8f24c26c0fc35e40c8879fb3ae5f19006d3edbf03f6017580071e8da6aa324873501c16c1108bbf91b93f154cab18cf4289026088dc3

data/CHANGELOG.md

@@ -2,8 +2,35 @@
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-06-28
+
 ### Added
 - Initial extraction: passkey (WebAuthn) registration and authentication for Rails
   as a self-contained engine — pure-Ruby CBOR/COSE/attestation/assertion, stateless
   signed challenges, a `has_passkeys` model macro, form helpers, a challenge
   endpoint, and JavaScript web components. No external dependencies.
+- `Unmagic::Passkeys.configure { |config| ... }` block as the single
+  configuration entry point, with a memoized `Unmagic::Passkeys.configuration`.
+  Adds `relying_party_id` / `relying_party_name` overrides and `base_controller`.
+- `use_unmagic_passkeys` router macro that
+  draws the multi-user sign-in (`/session`) and management (`/my/passkeys`) flows,
+  pointing at subclassable base controllers (`Unmagic::Passkeys::SessionsController`
+  / `CredentialsController`) with overridable ERB views. Supports `controllers`,
+  `skip_controllers`, and `scope`. App-specific behaviour is injected through
+  configuration hooks: `sign_in`, `sign_out`, `current_holder`. Sign-in is
+  usernameless (discoverable credentials), so it serves any number of users.
+  Account creation (signup) is left to the host app, which registers a passkey
+  for a holder it has created with the existing primitives.
+- `Unmagic::Passkeys::Test::Helpers` — test helper that mints valid WebAuthn
+  ceremony payloads from a fixed key pair (`register_passkey_for`,
+  `build_attestation_params`, `build_assertion_params`, `webauthn_challenge`,
+  `with_webauthn_request_context`). Requiring `unmagic/passkeys/test/helpers`
+  auto-includes it into Rails integration tests; RP id/origin are overridable.
+
+### Changed (breaking)
+- Configuration moved off the Rails engine options. The
+  `config.unmagic_passkeys.*` (and `config.unmagic_passkeys.web_authn.*`) settings
+  are removed entirely — there is no backward-compatible bridge. Migrate to the
+  `Unmagic::Passkeys.configure` block (e.g.
+  `config.unmagic_passkeys.web_authn.request_challenge_expiration` becomes
+  `config.request_challenge_expiration`).

data/README.md

@@ -64,21 +64,88 @@ The engine mounts a stateless challenge endpoint at `POST /unmagic/passkeys/chal
 
 ## Host wiring
 
-The engine ships the primitives; your app owns the login/registration controllers and
-views. The form helpers render self-contained web components — include the JS once:
+Include the JavaScript once — the form helpers render self-contained web components:
 
 ```js
 // app/javascript/application.js
 import "unmagic/passkeys"
 ```
 
-**Sign in** (`app/views/sessions/new.html.erb`):
+### Batteries included: `use_unmagic_passkeys`
 
-```erb
-<%= passkey_sign_in_button "Sign in with a passkey", session_passkey_path,
-      options: @authentication_options, mediation: "conditional" %>
+This draws the multi-user passkey auth flows and points them at the engine's
+base controllers:
+
+```ruby
+# config/routes.rb
+use_unmagic_passkeys
+```
+
+| Flow          | Routes                                    | Controller                                |
+| ------------- | ----------------------------------------- | ----------------------------------------- |
+| `sessions`    | `GET/POST/DELETE /session`, `/session/new`| `Unmagic::Passkeys::SessionsController`    |
+| `credentials` | `/my/passkeys` (index/create/destroy)     | `Unmagic::Passkeys::CredentialsController` |
+
+Sign-in is **usernameless** (discoverable credentials), so the one sign-in page
+authenticates any user — multi-user out of the box. The controllers are
+policy-free; they call **hooks** you configure for the app-specific bits:
+
+```ruby
+# config/initializers/passkeys.rb
+Unmagic::Passkeys.configure do |config|
+  config.base_controller = "ApplicationController"       # so hooks see your helpers
+
+  config.sign_in        { |holder| start_new_session_for(holder) }
+  config.sign_out       { terminate_session }
+  config.current_holder { Current.user }                 # for /my/passkeys
+end
 ```
 
+Customize by subclassing a base controller and re-pointing the route:
+
+```ruby
+# config/routes.rb
+use_unmagic_passkeys do
+  controllers sessions: "sessions", credentials: "my/passkeys"
+  # skip_controllers :credentials
+  # scope: "accounts"   # nest everything under a path
+end
+
+# app/controllers/sessions_controller.rb
+class SessionsController < Unmagic::Passkeys::SessionsController
+  rate_limit to: 10, within: 3.minutes
+  private def after_passkey_sign_in_path = after_authentication_url
+end
+```
+
+Each base controller exposes overridable methods for redirects and copy
+(`after_passkey_sign_in_path`, `after_passkey_sign_in_failure_path`,
+`after_passkey_sign_out_path`, `passkey_sign_in_failure_alert`). The default
+`sessions/new` and `credentials/index` views are overridable — drop a file at the
+same view path.
+
+### Signup is yours
+
+Account creation is the app's job — the engine authenticates holders, it doesn't
+own your user schema. Once you've created/identified a holder, register their
+first passkey with the same primitives the management flow uses, then sign them
+in:
+
+```ruby
+# Already-known holder (invite, email-first, OAuth, single-user bootstrap, …):
+@registration_options = Unmagic::Passkeys.registration_options(holder: user)  # -> render for the ceremony
+user.passkeys.register(passkey_registration_params)                           # verify + persist
+start_new_session_for(user)
+```
+
+### À la carte primitives
+
+Prefer to own the controllers? Skip the macro and use the building blocks
+directly. `Unmagic::Passkeys::Request` provides `passkey_registration_params`,
+`passkey_authentication_params`, `passkey_registration_options`,
+`passkey_authentication_options`, and sets `Unmagic::Passkeys::WebAuthn::Current`
+(host/origin) per request:
+
 ```ruby
 class Sessions::PasskeysController < ApplicationController
   include Unmagic::Passkeys::Request
@@ -94,46 +161,55 @@ class Sessions::PasskeysController < ApplicationController
 end
 ```
 
-**Register** (signed-in):
+## Configuration
 
-```erb
-<%= passkey_registration_button "Register a passkey", passkeys_path,
-      options: @registration_options %>
-```
+Configure the engine in a single block:
 
 ```ruby
-class PasskeysController < ApplicationController
-  include Unmagic::Passkeys::Request   # sets the WebAuthn request context + param helpers
-
-  def index
-    @registration_options = passkey_registration_options(holder: Current.user)
-  end
-
-  def create
-    Current.user.passkeys.register(passkey_registration_params)
-    redirect_to passkeys_path, notice: "Passkey added."
-  end
+# config/initializers/passkeys.rb
+Unmagic::Passkeys.configure do |config|
+  config.default_creation_options        = { attestation: :none }
+  config.default_request_options         = { user_verification: :required }
+  config.creation_challenge_expiration   = 10.minutes
+  config.request_challenge_expiration    = 5.minutes
+
+  # Relying party identity (default: request host / Rails.application.name)
+  # config.relying_party_id   = "example.com"
+  # config.relying_party_name = "Example"
+
+  # config.parent_class_name = "ApplicationRecord"
+  # config.routes_prefix     = "/unmagic/passkeys"   # set in config/application.rb if overriding
+  # config.draw_routes       = true
 end
 ```
 
-`Unmagic::Passkeys::Request` provides `passkey_registration_params`,
-`passkey_authentication_params`, `passkey_registration_options`,
-`passkey_authentication_options`, and sets `Unmagic::Passkeys::WebAuthn::Current`
-(host/origin) per request.
+## Testing
 
-## Configuration
+Mint valid WebAuthn ceremony payloads without a browser. Requiring the helper
+auto-includes it into Rails integration tests:
 
 ```ruby
-# config/initializers/passkeys.rb
-Rails.application.configure do
-  config.unmagic_passkeys.web_authn.default_creation_options = { attestation: :none }
-  config.unmagic_passkeys.web_authn.default_request_options  = { user_verification: :required }
-  config.unmagic_passkeys.web_authn.creation_challenge_expiration = 10.minutes
-  config.unmagic_passkeys.web_authn.request_challenge_expiration  = 5.minutes
-  # config.unmagic_passkeys.parent_class_name = "ApplicationRecord"
+# test/test_helper.rb
+require "unmagic/passkeys/test/helpers"
+
+# test/controllers/sessions/passkeys_controller_test.rb
+credential = register_passkey_for(@user)
+assertion  = in_webauthn_context do
+  build_assertion_params(challenge: webauthn_challenge(purpose: "authentication"), credential: credential)
 end
+post session_passkey_path, params: { passkey: assertion }
 ```
 
+For RSpec (or any non-integration test), include it yourself:
+
+```ruby
+require "unmagic/passkeys/test/helpers"
+RSpec.configure { |c| c.include Unmagic::Passkeys::Test::Helpers }
+```
+
+It defaults the relying party to `www.example.com` (the integration-test host).
+Override `webauthn_rp_id` / `webauthn_origin` in your test class to use another.
+
 ## Development
 
 ```sh

data/app/controllers/unmagic/passkeys/application_controller.rb

@@ -0,0 +1,35 @@
+# Base controller for the passkey auth flows. Inherits from the host's
+# +ApplicationController+ by default (configurable via
+# +Unmagic::Passkeys.configuration.base_controller+) so the configured hooks can
+# call your app's session helpers, and so the flows pick up your layout.
+#
+# Your app customizes behaviour by subclassing the concrete controllers
+# (SessionsController / CredentialsController) and re-pointing the routes with
+# +use_unmagic_passkeys { controllers ... }+.
+class Unmagic::Passkeys::ApplicationController < Unmagic::Passkeys.configuration.base_controller.constantize
+  include Unmagic::Passkeys::Request
+
+  private
+    # Runs the configured +sign_in+ hook in this controller's context.
+    def sign_in_holder(holder)
+      hook = Unmagic::Passkeys.configuration.sign_in
+      unless hook
+        raise Unmagic::Passkeys::ConfigurationError,
+          "Unmagic::Passkeys.configure { |c| c.sign_in { |holder| ... } } must be set to use the passkey sign-in flows"
+      end
+
+      instance_exec(holder, &hook)
+    end
+
+    # Runs the configured +sign_out+ hook, if any.
+    def sign_out_holder
+      hook = Unmagic::Passkeys.configuration.sign_out
+      instance_exec(&hook) if hook
+    end
+
+    # The signed-in holder, via the configured +current_holder+ hook.
+    def current_passkey_holder
+      hook = Unmagic::Passkeys.configuration.current_holder
+      hook ? instance_exec(&hook) : nil
+    end
+end

data/app/controllers/unmagic/passkeys/challenges_controller.rb

@@ -12,8 +12,8 @@
 #
 # == Route
 #
-# By default mounted at +/rails/action_pack/passkey/challenge+ (configurable
-# via +config.unmagic_passkeys.routes_prefix+).
+# By default mounted at +/unmagic/passkeys/challenge+ (configurable via
+# +Unmagic::Passkeys.configuration.routes_prefix+).
 #
 class Unmagic::Passkeys::ChallengesController < ActionController::Base
   include Unmagic::Passkeys::Request
@@ -38,7 +38,7 @@ class Unmagic::Passkeys::ChallengesController < ActionController::Base
     end
 
     def challenge_expiration
-      config = Rails.configuration.unmagic_passkeys.web_authn
+      config = Unmagic::Passkeys.configuration
 
       if challenge_purpose == "registration"
         config.creation_challenge_expiration

data/app/controllers/unmagic/passkeys/credentials_controller.rb

@@ -0,0 +1,25 @@
+# Passkey management for the signed-in holder: list (+index+), add (+create+),
+# and remove (+destroy+). Requires authentication via the host's base
+# controller. The holder comes from the configured +current_holder+ hook.
+class Unmagic::Passkeys::CredentialsController < Unmagic::Passkeys::ApplicationController
+  def index
+    @passkeys = passkey_holder.passkeys.order(created_at: :desc)
+    @registration_options = passkey_registration_options(holder: passkey_holder)
+  end
+
+  def create
+    passkey_holder.passkeys.register(passkey_registration_params)
+    redirect_to url_for(action: :index), notice: "Passkey added."
+  end
+
+  def destroy
+    passkey_holder.passkeys.find(params[:id]).destroy
+    redirect_to url_for(action: :index), notice: "Passkey removed."
+  end
+
+  private
+    def passkey_holder
+      current_passkey_holder or raise Unmagic::Passkeys::ConfigurationError,
+        "Unmagic::Passkeys.configure { |c| c.current_holder { ... } } must be set to manage passkeys"
+    end
+end

data/app/controllers/unmagic/passkeys/sessions_controller.rb

@@ -0,0 +1,40 @@
+# Passkey sign-in: the sign-in page (+new+), the authentication ceremony
+# (+create+), and sign-out (+destroy+).
+#
+# Sign-in is usernameless — it relies on discoverable credentials, so the same
+# page signs in any user. Subclass to add rate limiting or to change the
+# redirect targets, then re-point the route:
+#
+#   class SessionsController < Unmagic::Passkeys::SessionsController
+#     rate_limit to: 10, within: 3.minutes
+#     private def after_passkey_sign_in_path = after_authentication_url
+#   end
+class Unmagic::Passkeys::SessionsController < Unmagic::Passkeys::ApplicationController
+  # Sign-in must be reachable while signed out. No-op when the base controller
+  # has no such callback.
+  skip_before_action :require_authentication, raise: false
+
+  def new
+    @authentication_options = passkey_authentication_options
+  end
+
+  def create
+    if credential = Unmagic::Passkeys.authenticate(passkey_authentication_params)
+      sign_in_holder(credential.holder)
+      redirect_to after_passkey_sign_in_path
+    else
+      redirect_to after_passkey_sign_in_failure_path, alert: passkey_sign_in_failure_alert
+    end
+  end
+
+  def destroy
+    sign_out_holder
+    redirect_to after_passkey_sign_out_path, status: :see_other
+  end
+
+  private
+    def after_passkey_sign_in_path = "/"
+    def after_passkey_sign_in_failure_path = new_session_path
+    def after_passkey_sign_out_path = new_session_path
+    def passkey_sign_in_failure_alert = "That passkey didn't work. Try again."
+end

data/app/models/unmagic/passkeys/credential.rb

@@ -27,19 +27,19 @@
 #
 # Call +has_passkeys+ in your model to set up the association and configure ceremony options
 # per-holder. See Unmagic::Passkeys::Holder for details.
-class Unmagic::Passkeys::Credential < Rails.configuration.unmagic_passkeys.parent_class_name.constantize
+class Unmagic::Passkeys::Credential < Unmagic::Passkeys.configuration.parent_class_name.constantize
   self.table_name = "unmagic_passkeys_credentials"
   belongs_to :holder, polymorphic: true
   serialize :transports, coder: JSON, type: Array, default: []
 
   class << self
     # Returns a CreationOptions object for the given +holder+, suitable for passing to the
-    # browser's +navigator.credentials.create()+ call. Merges global defaults from the Rails
-    # configuration, holder-specific options from +holder.passkey_registration_options+, and any
-    # additional +options+ overrides.
+    # browser's +navigator.credentials.create()+ call. Merges global defaults from
+    # +Unmagic::Passkeys.configuration+, holder-specific options from
+    # +holder.passkey_registration_options+, and any additional +options+ overrides.
     def registration_options(holder:, **options)
       Unmagic::Passkeys::WebAuthn::PublicKeyCredential.creation_options(
-        **Rails.configuration.unmagic_passkeys.web_authn.default_creation_options.to_h,
+        **Unmagic::Passkeys.configuration.default_creation_options.to_h,
         **holder.passkey_registration_options.to_h,
         **options
       )
@@ -64,7 +64,7 @@ class Unmagic::Passkeys::Credential < Rails.configuration.unmagic_passkeys.paren
     # options, and any additional +options+ overrides.
     def authentication_options(holder: nil, **options)
       Unmagic::Passkeys::WebAuthn::PublicKeyCredential.request_options(
-        **Rails.configuration.unmagic_passkeys.web_authn.default_request_options.to_h,
+        **Unmagic::Passkeys.configuration.default_request_options.to_h,
         **holder&.passkey_authentication_options.to_h,
         **options
       )

data/app/views/unmagic/passkeys/credentials/index.html.erb

@@ -0,0 +1,22 @@
+<%# Default passkey management page. Override by creating a view at the same path
+    (or at your subclass controller's view path). %>
+<section class="unmagic-passkeys">
+  <h1>Passkeys</h1>
+
+  <% if @passkeys.any? %>
+    <ul>
+      <% @passkeys.each do |passkey| %>
+        <li id="<%= dom_id(passkey) %>">
+          <span><%= passkey.name.presence || "Passkey" %></span>
+          <span>added <%= passkey.created_at.to_date.to_fs(:long) %></span>
+          <%= button_to "Remove", url_for(action: :destroy, id: passkey), method: :delete %>
+        </li>
+      <% end %>
+    </ul>
+  <% else %>
+    <p>No passkeys yet.</p>
+  <% end %>
+
+  <%= passkey_registration_button "Add a passkey", url_for(action: :create),
+        options: @registration_options %>
+</section>

data/app/views/unmagic/passkeys/sessions/new.html.erb

@@ -0,0 +1,7 @@
+<%# Default sign-in page (usernameless / discoverable credentials). Override by
+    creating a view at the same path (or at your subclass controller's view path). %>
+<main class="unmagic-passkeys">
+  <p>Sign in with your passkey.</p>
+  <%= passkey_sign_in_button "Sign in with a passkey", session_path,
+        options: @authentication_options, mediation: "conditional" %>
+</main>

data/lib/unmagic/passkeys/configuration.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Passkeys
+    # Central configuration for the passkeys engine, set through a single
+    # +Unmagic::Passkeys.configure+ block. The defaults here are the single
+    # source of truth — there is no separate Rails engine config.
+    #
+    #   # config/initializers/passkeys.rb
+    #   Unmagic::Passkeys.configure do |config|
+    #     config.relying_party_name           = "Shopping"
+    #     config.request_challenge_expiration  = 5.minutes
+    #     config.default_request_options       = { user_verification: :required }
+    #   end
+    class Configuration
+      # The Active Record base class the Credential model inherits from.
+      attr_accessor :parent_class_name
+
+      # Where the stateless challenge endpoint is mounted, and whether the engine
+      # draws it at all. Override these in +config/application.rb+ if you need
+      # them applied before the engine draws its routes.
+      attr_accessor :routes_prefix, :draw_routes
+
+      # Optional callable, +instance_exec+'d in the view, returning the URL the
+      # form helpers point the challenge fetch at. Defaults to the engine's
+      # challenge path when nil.
+      attr_accessor :challenge_url
+
+      # Global option defaults merged into every registration / authentication
+      # ceremony.
+      attr_accessor :default_creation_options, :default_request_options
+
+      # How long an issued challenge stays valid, per ceremony.
+      attr_accessor :creation_challenge_expiration, :request_challenge_expiration
+
+      # Relying party identity. When nil, falls back to the request host and
+      # +Rails.application.name+ respectively.
+      attr_accessor :relying_party_id, :relying_party_name
+
+      # The controller the engine's base controllers inherit from. Inherit from
+      # the host's +ApplicationController+ so the hook blocks below can call your
+      # app's session helpers (e.g. +start_new_session_for+).
+      attr_accessor :base_controller
+
+      def initialize
+        @parent_class_name = "ApplicationRecord"
+        @routes_prefix = "/unmagic/passkeys"
+        @draw_routes = true
+        @challenge_url = nil
+        @default_creation_options = {}
+        @default_request_options = {}
+        @creation_challenge_expiration = 10.minutes
+        @request_challenge_expiration = 5.minutes
+        @relying_party_id = nil
+        @relying_party_name = nil
+        @base_controller = "ApplicationController"
+        @sign_in = nil
+        @sign_out = nil
+        @current_holder = nil
+      end
+
+      # == Controller hooks
+      #
+      # Each is a block +instance_exec+'d in the engine's base controllers, so it
+      # has full access to the request, session, and any helpers your
+      # +base_controller+ provides. Call with a block to set, without to read.
+      #
+      # +sign_in+ turns an authenticated holder into an app session (required to
+      # use the sign-in flow). +sign_out+ tears it down. +current_holder+ returns
+      # the signed-in holder (used by the credentials management controller).
+      #
+      # Account creation (signup) is the host app's responsibility — once you've
+      # created/identified a holder, register a passkey for it with
+      # +holder.passkeys.register(params)+ and call +sign_in+.
+      #
+      #   Unmagic::Passkeys.configure do |config|
+      #     config.sign_in        { |holder| start_new_session_for(holder) }
+      #     config.sign_out       { terminate_session }
+      #     config.current_holder { Current.user }
+      #   end
+      def sign_in(&block)
+        block ? @sign_in = block : @sign_in
+      end
+
+      def sign_out(&block)
+        block ? @sign_out = block : @sign_out
+      end
+
+      def current_holder(&block)
+        block ? @current_holder = block : @current_holder
+      end
+    end
+  end
+end

data/lib/unmagic/passkeys/engine.rb

@@ -9,24 +9,19 @@ module Unmagic
     # == Configuration
     #
     #   # config/initializers/passkeys.rb
-    #   config.unmagic_passkeys.web_authn.default_creation_options = { attestation: :none }
-    #   config.unmagic_passkeys.web_authn.default_request_options  = { user_verification: :required }
-    #   config.unmagic_passkeys.routes_prefix = "/unmagic/passkeys"
+    #   Unmagic::Passkeys.configure do |config|
+    #     config.default_creation_options = { attestation: :none }
+    #     config.default_request_options  = { user_verification: :required }
+    #     config.routes_prefix            = "/unmagic/passkeys"
+    #   end
     class Engine < ::Rails::Engine
-      config.unmagic_passkeys = ActiveSupport::OrderedOptions.new
-      config.unmagic_passkeys.parent_class_name = "ApplicationRecord"
-      config.unmagic_passkeys.routes_prefix = "/unmagic/passkeys"
-      config.unmagic_passkeys.draw_routes = true
-      config.unmagic_passkeys.challenge_url = nil
-
-      config.unmagic_passkeys.web_authn = ActiveSupport::OrderedOptions.new
-      config.unmagic_passkeys.web_authn.default_request_options = {}
-      config.unmagic_passkeys.web_authn.default_creation_options = {}
-      config.unmagic_passkeys.web_authn.creation_challenge_expiration = 10.minutes
-      config.unmagic_passkeys.web_authn.request_challenge_expiration = 5.minutes
+      initializer "unmagic_passkeys.routes_macro" do
+        require "unmagic/passkeys/rails/routes"
+        ActionDispatch::Routing::Mapper.include Unmagic::Passkeys::Rails::Routes::Mapper
+      end
 
       initializer "unmagic_passkeys.routes" do |app|
-        passkey_config = config.unmagic_passkeys
+        passkey_config = Unmagic::Passkeys.configuration
 
         app.routes.prepend do
           if passkey_config.draw_routes

data/lib/unmagic/passkeys/form_helper.rb

@@ -94,7 +94,7 @@ module Unmagic::Passkeys::FormHelper
     end
 
     def default_passkey_challenge_url
-      if challenge_url = Rails.configuration.unmagic_passkeys.challenge_url
+      if challenge_url = Unmagic::Passkeys.configuration.challenge_url
         instance_exec(&challenge_url)
       else
         passkey_challenge_path

data/lib/unmagic/passkeys/rails/routes.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Passkeys
+    module Rails
+      # Adds +use_unmagic_passkeys+ to the router. Draws the multi-user passkey
+      # auth flows pointing at the engine's base controllers (which your app may
+      # subclass and re-point):
+      #
+      #   resource  :session,  only: [:new, :create, :destroy]   # sign-in page + ceremony + sign-out
+      #   resources :passkeys, only: [:index, :create, :destroy] # management, mounted at /my/passkeys
+      #
+      # Sign-in is usernameless (discoverable credentials), so it works for any
+      # number of users out of the box. Account creation (signup) is the app's
+      # job — see the README.
+      #
+      # == Usage
+      #
+      #   # config/routes.rb
+      #   use_unmagic_passkeys
+      #
+      #   # Customize: re-point a flow at your own controller, skip flows, or
+      #   # nest everything under a path scope.
+      #   use_unmagic_passkeys scope: "accounts" do
+      #     controllers sessions: "sessions", credentials: "my/passkeys"
+      #     skip_controllers :credentials
+      #   end
+      module Routes
+        DEFAULT_CONTROLLERS = {
+          sessions: "unmagic/passkeys/sessions",
+          credentials: "unmagic/passkeys/credentials"
+        }.freeze
+
+        # Collects customization from the +use_unmagic_passkeys+ block.
+        class Mapping
+          attr_reader :credentials_path, :credentials_as
+
+          def initialize
+            @controller_overrides = {}
+            @skipped = []
+            @credentials_path = "my/passkeys"
+            @credentials_as = "my_passkeys"
+          end
+
+          # Re-point one or more flows at your own controllers (which should
+          # inherit from the matching engine base controller):
+          #
+          #   controllers sessions: "sessions", credentials: "my/passkeys"
+          def controllers(map = nil)
+            return resolved_controllers if map.nil?
+
+            map.each { |flow, controller| @controller_overrides[flow.to_sym] = controller.to_s }
+          end
+
+          # Skip drawing one or more flows: +skip_controllers :credentials+.
+          def skip_controllers(*names)
+            @skipped.concat(names.map(&:to_sym))
+          end
+
+          # Where the management resource is mounted and how its route helpers
+          # are named (defaults to +/my/passkeys+ and +my_passkeys_path+).
+          def credentials_at(path:, as:)
+            @credentials_path = path
+            @credentials_as = as
+          end
+
+          def draw?(flow)
+            !@skipped.include?(flow)
+          end
+
+          def controller_for(flow)
+            resolved_controllers.fetch(flow)
+          end
+
+          private
+            def resolved_controllers
+              DEFAULT_CONTROLLERS.merge(@controller_overrides)
+            end
+        end
+
+        # Mixed into ActionDispatch::Routing::Mapper.
+        module Mapper
+          def use_unmagic_passkeys(scope: nil, &block)
+            mapping = Mapping.new
+            mapping.instance_exec(&block) if block
+
+            draw = lambda do
+              if mapping.draw?(:sessions)
+                resource :session, only: %i[new create destroy], controller: mapping.controller_for(:sessions)
+              end
+
+              if mapping.draw?(:credentials)
+                resources :passkeys, only: %i[index create destroy],
+                  controller: mapping.controller_for(:credentials),
+                  path: mapping.credentials_path,
+                  as: mapping.credentials_as
+              end
+            end
+
+            scope ? self.scope(scope, &draw) : instance_exec(&draw)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/passkeys/test/helpers.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+require "json"
+require "digest"
+require "securerandom"
+
+module Unmagic
+  module Passkeys
+    module Test
+      # Mints valid WebAuthn ceremony payloads from a fixed EC P-256 key pair, so
+      # passkey registration and authentication can be exercised end to end
+      # without a browser. Ported from fizzy's test helper.
+      #
+      # In a Rails app, requiring this file auto-includes it into integration
+      # tests. Elsewhere (e.g. RSpec) include it yourself:
+      #
+      #   require "unmagic/passkeys/test/helpers"
+      #   RSpec.configure { |c| c.include Unmagic::Passkeys::Test::Helpers }
+      #
+      # The relying party defaults to "www.example.com" / "http://www.example.com"
+      # (the Rails integration-test host, so the engine's request context lines up
+      # automatically). Override +webauthn_rp_id+ / +webauthn_origin+ in your test
+      # class to test under a different host.
+      module Helpers
+        WEBAUTHN_PRIVATE_KEY = OpenSSL::PKey::EC.new(
+          [ "307702010104201dd589de7210b3318620f32150e3012cce021519df1d6e9e01" \
+            "0471146d395cdca00a06082a8648ce3d030107a14403420004116847fe19e1ad" \
+            "4471ab9980d7ff9cc1e4c7cb7a3af00e082b64fcd84f5ae70114c2495eef16f" \
+            "542b5e57dd1b263661624e3cf28f581b57a441edbd756a41d0e" ].pack("H*")
+        )
+
+        # Pre-encoded COSE EC2/ES256 public key (CBOR) for the key above.
+        COSE_PUBLIC_KEY = [ "a5010203262001215820116847fe19e1ad4471ab9980d7ff9cc1" \
+          "e4c7cb7a3af00e082b64fcd84f5ae70122582014c2495eef16f542b5e57dd1b2" \
+          "63661624e3cf28f581b57a441edbd756a41d0e" ].pack("H*")
+
+        # CBOR prefix for {"fmt": "none", "attStmt": {}, "authData": bytes(164)}.
+        ATTESTATION_OBJECT_CBOR_PREFIX =
+          [ "a363666d74646e6f6e656761747453746d74a068617574684461746158a4" ].pack("H*")
+
+        RP_ID = "www.example.com"
+        ORIGIN = "http://www.example.com"
+
+        # The relying party identity used to mint payloads. Override in a test
+        # class to exercise a different host.
+        def webauthn_rp_id = RP_ID
+        def webauthn_origin = ORIGIN
+
+        # Registers a passkey for +holder+ directly (used to set up the
+        # "already enrolled" state). Returns the persisted credential.
+        def register_passkey_for(holder)
+          with_webauthn_request_context do
+            holder.passkeys.register(build_attestation_params(challenge: webauthn_challenge(purpose: "registration")))
+          end
+        end
+
+        def with_webauthn_request_context
+          Unmagic::Passkeys::WebAuthn::Current.host = webauthn_rp_id
+          Unmagic::Passkeys::WebAuthn::Current.origin = webauthn_origin
+          yield
+        ensure
+          Unmagic::Passkeys::WebAuthn::Current.reset
+        end
+        alias_method :in_webauthn_context, :with_webauthn_request_context
+
+        def webauthn_challenge(purpose: nil)
+          Unmagic::Passkeys::WebAuthn::PublicKeyCredential::Options.new(challenge_purpose: purpose).challenge
+        end
+
+        def build_attestation_params(challenge:)
+          credential_id = SecureRandom.random_bytes(32)
+          auth_data = build_attestation_auth_data(credential_id: credential_id)
+
+          {
+            client_data_json: webauthn_client_data_json(challenge: challenge, type: "webauthn.create"),
+            attestation_object: Base64.urlsafe_encode64(ATTESTATION_OBJECT_CBOR_PREFIX + auth_data, padding: false),
+            transports: [ "internal" ]
+          }
+        end
+
+        def build_assertion_params(challenge:, credential:, sign_count: 1)
+          client_data_json = webauthn_client_data_json(challenge: challenge, type: "webauthn.get")
+          authenticator_data = build_assertion_auth_data(sign_count: sign_count)
+          signature = webauthn_sign(authenticator_data, client_data_json)
+
+          {
+            id: credential.credential_id,
+            client_data_json: client_data_json,
+            authenticator_data: Base64.urlsafe_encode64(authenticator_data, padding: false),
+            signature: Base64.urlsafe_encode64(signature, padding: false)
+          }
+        end
+
+        private
+          def webauthn_client_data_json(challenge:, type:)
+            { challenge: challenge, origin: webauthn_origin, type: type }.to_json
+          end
+
+          def build_attestation_auth_data(credential_id:)
+            [
+              Digest::SHA256.digest(webauthn_rp_id),
+              [ 0x45 ].pack("C"),                       # flags: UP + UV + AT
+              [ 0 ].pack("N"),                          # sign_count
+              "\x00" * 16,                            # aaguid
+              [ credential_id.bytesize ].pack("n"),     # credential_id_length
+              credential_id,
+              COSE_PUBLIC_KEY
+            ].join.b
+          end
+
+          def build_assertion_auth_data(sign_count:)
+            [
+              Digest::SHA256.digest(webauthn_rp_id),
+              [ 0x05 ].pack("C"),                       # flags: UP + UV
+              [ sign_count ].pack("N")
+            ].join.b
+          end
+
+          def webauthn_sign(authenticator_data, client_data_json)
+            signed_data = authenticator_data + Digest::SHA256.digest(client_data_json)
+            WEBAUTHN_PRIVATE_KEY.sign("SHA256", signed_data)
+          end
+      end
+    end
+  end
+end
+
+# Auto-include into Rails integration tests when Active Support is present.
+if defined?(ActiveSupport)
+  ActiveSupport.on_load(:action_dispatch_integration_test) do
+    include Unmagic::Passkeys::Test::Helpers
+  end
+end

data/lib/unmagic/passkeys/version.rb

@@ -1,5 +1,5 @@
 module Unmagic
   module Passkeys
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/unmagic/passkeys/web_authn/public_key_credential/creation_options.rb

@@ -52,7 +52,7 @@ class Unmagic::Passkeys::WebAuthn::PublicKeyCredential::CreationOptions < Unmagi
   attribute :resident_key, default: :required
   attribute :exclude_credentials, default: -> { [] }
   attribute :attestation, default: :none
-  attribute :challenge_expiration, default: -> { Rails.configuration.unmagic_passkeys.web_authn.creation_challenge_expiration }
+  attribute :challenge_expiration, default: -> { Unmagic::Passkeys.configuration.creation_challenge_expiration }
   attribute :challenge_purpose, default: "registration"
 
   validates :id, :name, :display_name, presence: true

data/lib/unmagic/passkeys/web_authn/public_key_credential/options.rb

@@ -64,8 +64,8 @@ class Unmagic::Passkeys::WebAuthn::PublicKeyCredential::Options
   #
   # The timestamp allows the server to reject stale challenges. The expiration
   # window is configurable per-ceremony via
-  # +config.unmagic_passkeys.web_authn.creation_challenge_expiration+ and
-  # +config.unmagic_passkeys.web_authn.request_challenge_expiration+, or per-instance
+  # +Unmagic::Passkeys.configuration.creation_challenge_expiration+ and
+  # +Unmagic::Passkeys.configuration.request_challenge_expiration+, or per-instance
   # via the +challenge_expiration+ attribute.
   def challenge
     @challenge ||= Base64.urlsafe_encode64(

data/lib/unmagic/passkeys/web_authn/public_key_credential/request_options.rb

@@ -25,7 +25,7 @@
 #   +Unmagic::Passkeys::WebAuthn.relying_party+.
 class Unmagic::Passkeys::WebAuthn::PublicKeyCredential::RequestOptions < Unmagic::Passkeys::WebAuthn::PublicKeyCredential::Options
   attribute :credentials, default: -> { [] }
-  attribute :challenge_expiration, default: -> { Rails.configuration.unmagic_passkeys.web_authn.request_challenge_expiration }
+  attribute :challenge_expiration, default: -> { Unmagic::Passkeys.configuration.request_challenge_expiration }
   attribute :challenge_purpose, default: "authentication"
 
   def initialize(attributes = {})

data/lib/unmagic/passkeys/web_authn.rb

@@ -37,9 +37,16 @@ module Unmagic::Passkeys::WebAuthn
   class InvalidOptionsError < StandardError; end
 
   class << self
-    # Returns a new RelyingParty configured from the current request context.
+    # Returns a new RelyingParty. Identity comes from +Unmagic::Passkeys.configuration+
+    # when set, otherwise falls back to the current request host and
+    # +Rails.application.name+.
     def relying_party
-      RelyingParty.new
+      config = Unmagic::Passkeys.configuration
+
+      RelyingParty.new(
+        id: config.relying_party_id || Current.host,
+        name: config.relying_party_name || Rails.application.name
+      )
     end
 
     # Returns the MessageVerifier used to sign and verify WebAuthn challenges.

data/lib/unmagic/passkeys.rb

@@ -9,6 +9,7 @@ require "json"
 require "digest"
 
 require "unmagic/passkeys/version"
+require "unmagic/passkeys/configuration"
 require "unmagic/passkeys/web_authn"
 require "unmagic/passkeys/holder"
 require "unmagic/passkeys/request"
@@ -20,7 +21,24 @@ module Unmagic
   # +Unmagic::Passkeys::Credential+ Active Record model so host code reads as
   # +Unmagic::Passkeys.authenticate(params)+.
   module Passkeys
+    # Raised when a controller flow needs a hook that has not been configured.
+    class ConfigurationError < StandardError; end
+
     class << self
+      # The singleton Configuration. Memoized with defaults; mutate via +configure+.
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      # Configure the engine in a single block:
+      #
+      #   Unmagic::Passkeys.configure do |config|
+      #     config.relying_party_name = "Shopping"
+      #   end
+      def configure
+        yield configuration
+      end
+
       def registration_options(**options)
         Credential.registration_options(**options)
       end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unmagic-passkeys
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Keith Pitt
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-26 00:00:00.000000000 Z
+date: 2026-06-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -95,18 +95,26 @@ files:
 - README.md
 - app/assets/javascripts/unmagic/passkeys/passkey.js
 - app/assets/javascripts/unmagic/passkeys/webauthn.js
+- app/controllers/unmagic/passkeys/application_controller.rb
 - app/controllers/unmagic/passkeys/challenges_controller.rb
+- app/controllers/unmagic/passkeys/credentials_controller.rb
+- app/controllers/unmagic/passkeys/sessions_controller.rb
 - app/models/unmagic/passkeys/credential.rb
+- app/views/unmagic/passkeys/credentials/index.html.erb
+- app/views/unmagic/passkeys/sessions/new.html.erb
 - config/importmap.rb
 - config/routes.rb
 - lib/generators/unmagic/passkeys/install_generator.rb
 - lib/generators/unmagic/passkeys/templates/POST_INSTALL
 - lib/generators/unmagic/passkeys/templates/create_unmagic_passkeys_credentials.rb.tt
 - lib/unmagic/passkeys.rb
+- lib/unmagic/passkeys/configuration.rb
 - lib/unmagic/passkeys/engine.rb
 - lib/unmagic/passkeys/form_helper.rb
 - lib/unmagic/passkeys/holder.rb
+- lib/unmagic/passkeys/rails/routes.rb
 - lib/unmagic/passkeys/request.rb
+- lib/unmagic/passkeys/test/helpers.rb
 - lib/unmagic/passkeys/version.rb
 - lib/unmagic/passkeys/web_authn.rb
 - lib/unmagic/passkeys/web_authn/authenticator/assertion_response.rb