unmagic-passkeys 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 645c820a4995965db7ac6d5a146b1c26fa058670ee99159e6b69c2fc4d8c09b9
-  data.tar.gz: f91753169ab1fad8ef5c789319babb20ee59806b3bc0bb6a56fb43075070091c
+  metadata.gz: 9d45bf4f51fee5d670d79d59a70518f2052417f00ecf549a263f1c23fa7d8aa3
+  data.tar.gz: a97fb1cf155def235ff658328850b0bafd5cf99b18c579501e8360839084e224
 SHA512:
-  metadata.gz: 40df919dbc7b4c5e1496bcba443898bb332af4dbe62fe87624f105ce5aa91dd2dd2e9774196a5bebddb5b3713f333343daafd02f928d575dacda5561cef69134
-  data.tar.gz: e3be802090ee4736ba752d702972857224440a95b65b1c3654ab628e33d6e5667f5298d8301968ffb8e2f399a3aa7cfba89237d28b9ab44ccd29ab33e73e43dd
+  metadata.gz: d00972cba516c64383dd7ab92c2301f276db4dbba1da08b7e9e6d35e878ab73df1ec47bfbfcedd51c92e58386f168317af1a1c8e131977310b2d2adc570a83aa
+  data.tar.gz: 74ecb8ef46d774e0f4ccf81ba0a33240d37bcf9b8fc4ccd0ea7fe5dbba76889f3c5b80864c4861ac196306f5c857ba253b29a9dd76345e514584a653593f531a

data/CHANGELOG.md

@@ -2,8 +2,73 @@
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-07-14
+
+### Added
+- `params:` option on `passkey_registration_button` / `passkey_sign_in_button`,
+  rendering extra hidden fields inside the ceremony form (like `button_to`'s
+  `params:`). The signup example uses it to carry the email through the
+  two-phase ceremony.
+- README "Host wiring" rewritten around copy-pasteable sign-in, signup, and
+  passkey-management controllers (Rails 8 `generate authentication`
+  vocabulary). The same controllers live in `spec/dummy` and are exercised end
+  to end by the request specs, including a two-phase signup ceremony where
+  `find_or_create_by!` makes signup and "existing user enrolling a new device"
+  the same flow.
+
+### Removed (breaking)
+- The shipped flow controllers and everything that existed to customize them:
+  `Unmagic::Passkeys::SessionsController` / `CredentialsController` /
+  `ApplicationController`, their views, the `use_unmagic_passkeys` router
+  macro, and the `sign_in` / `sign_out` / `current_holder` / `base_controller`
+  configuration hooks (plus `Unmagic::Passkeys::ConfigurationError`). They were
+  glue around app policy — session handling, redirects, flash copy — behind
+  three layers of indirection (hooks, subclassing, view overrides). Copy the
+  README's controllers into your app instead; the gem keeps the protocol-shaped
+  pieces: the WebAuthn library, `Credential` + `has_passkeys`, the challenge
+  endpoint, the `Request` concern, form helpers, JavaScript, and test helpers.
+
+### Changed (breaking)
+- Default `routes_prefix` (the challenge endpoint mount point) changed from
+  `/unmagic/passkeys` to `/auth/passkeys`. Set
+  `config.routes_prefix = "/unmagic/passkeys"` to keep the old URL.
+
+### Fixed
+- `rails generate unmagic:passkeys:install` crashed on load in 0.2.0
+  (`uninitialized constant Unmagic::Passkeys::Rails::Generators`): the nested
+  `Unmagic::Passkeys::Rails` module shadowed the framework's `Rails` during the
+  generator's constant lookup. The generator now references `::Rails`
+  explicitly, with a regression spec covering the shadowed case.
+
+## [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

@@ -59,53 +59,148 @@ options  = Unmagic::Passkeys.authentication_options               # -> pass to n
 passkey  = Unmagic::Passkeys.authenticate(params[:passkey])       # verified credential, or nil
 ```
 
-The engine mounts a stateless challenge endpoint at `POST /unmagic/passkeys/challenge`
+The engine mounts a stateless challenge endpoint at `POST /auth/passkeys/challenge`
 (`passkey_challenge_path`), which the JavaScript refreshes before each ceremony.
 
 ## 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:
+The gem ships the WebAuthn machinery — the ceremonies, the model, the form
+helpers, the JavaScript, and the challenge endpoint. The controllers are
+yours: copy the examples below into your app and edit them to fit. (They use
+the vocabulary of `bin/rails generate authentication`:
+`start_new_session_for`, `terminate_session`, `Current.user`.)
+
+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`):
+Draw the routes:
 
-```erb
-<%= passkey_sign_in_button "Sign in with a passkey", session_passkey_path,
-      options: @authentication_options, mediation: "conditional" %>
+```ruby
+# config/routes.rb
+resource  :session,      only: %i[new create destroy]
+resource  :registration, only: %i[new create]
+resources :passkeys,     only: %i[index create destroy]
 ```
 
+### Sign-in
+
+Usernameless (discoverable credentials) — one page signs in any user, and
+conditional mediation offers passkeys through autofill:
+
 ```ruby
-class Sessions::PasskeysController < ApplicationController
+# app/controllers/sessions_controller.rb
+class SessionsController < ApplicationController
   include Unmagic::Passkeys::Request
 
+  allow_unauthenticated_access only: %i[new create]
+  rate_limit to: 10, within: 3.minutes, only: :create
+
+  def new
+    @authentication_options = passkey_authentication_options
+  end
+
   def create
     if credential = Unmagic::Passkeys.authenticate(passkey_authentication_params)
       start_new_session_for credential.holder
       redirect_to after_authentication_url
     else
-      redirect_to new_session_path, alert: "That passkey didn't work."
+      redirect_to new_session_path, alert: "That passkey didn't work. Try again."
     end
   end
+
+  def destroy
+    terminate_session
+    redirect_to new_session_path, status: :see_other
+  end
 end
 ```
 
-**Register** (signed-in):
+```erb
+<%# app/views/sessions/new.html.erb %>
+<p>Sign in with your passkey.</p>
+<%= passkey_sign_in_button "Sign in with a passkey", session_path,
+      options: @authentication_options, mediation: "conditional" %>
+```
+
+### Signup
+
+The ceremony runs in two phases through one `create` action: submitted with an
+email it renders the ceremony page (the email rides along via the form
+helper's `params:` option); submitted with the attestation it verifies, saves
+the passkey, and signs the user in. `find_or_create_by!` makes the two phases
+idempotent — and makes signup and "existing user enrolling a new device" the
+same flow:
+
+```ruby
+# app/controllers/registrations_controller.rb
+class RegistrationsController < ApplicationController
+  include Unmagic::Passkeys::Request
+
+  allow_unauthenticated_access
+  rate_limit to: 10, within: 3.minutes, only: :create
+
+  def new
+  end
+
+  # Called twice: with an email it renders the ceremony page; with the
+  # attestation it verifies, saves the passkey, and signs the user in.
+  def create
+    @email = params.expect(registration: [ :email ])[:email]
+    user = User.find_or_create_by!(email_address: @email)
+    # TODO: verify the visitor owns @email before handing back an existing
+    # account (emailed code, invite token, …) — otherwise a stranger can add
+    # a passkey to it.
+
+    if params[:passkey].present?
+      user.passkeys.register(passkey_registration_params)
+      start_new_session_for user
+      redirect_to root_path
+    else
+      @registration_options = passkey_registration_options(holder: user)
+      render :create
+    end
+  rescue ActiveRecord::RecordInvalid
+    redirect_to new_registration_path, alert: "Enter a valid email address."
+  rescue Unmagic::Passkeys::WebAuthn::InvalidResponseError
+    redirect_to new_registration_path, alert: "That didn't work. Try again."
+  end
+end
+```
 
 ```erb
-<%= passkey_registration_button "Register a passkey", passkeys_path,
-      options: @registration_options %>
+<%# app/views/registrations/new.html.erb %>
+<p>Create your account.</p>
+<%= form_with scope: :registration, url: registration_path do |form| %>
+  <%= form.email_field :email, required: true, autocomplete: "email" %>
+  <%= form.submit "Continue" %>
+<% end %>
+```
+
+```erb
+<%# app/views/registrations/create.html.erb %>
+<p>Secure your account with a passkey.</p>
+<%= passkey_registration_button "Create a passkey", registration_path,
+      options: @registration_options, params: { registration: { email: @email } } %>
 ```
 
+Two things the example leaves to you: **identifier ownership** (nothing above
+proves the visitor owns the email they typed) and **abandoned signups** (the
+user row is created in the email phase; retries reuse it, sweep the
+passkey-less ones if you care).
+
+### Managing passkeys
+
 ```ruby
+# app/controllers/passkeys_controller.rb
 class PasskeysController < ApplicationController
-  include Unmagic::Passkeys::Request   # sets the WebAuthn request context + param helpers
+  include Unmagic::Passkeys::Request
 
   def index
+    @passkeys = Current.user.passkeys.order(created_at: :desc)
     @registration_options = passkey_registration_options(holder: Current.user)
   end
 
@@ -113,27 +208,91 @@ class PasskeysController < ApplicationController
     Current.user.passkeys.register(passkey_registration_params)
     redirect_to passkeys_path, notice: "Passkey added."
   end
+
+  def destroy
+    Current.user.passkeys.find(params[:id]).destroy
+    redirect_to passkeys_path, notice: "Passkey removed."
+  end
 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.
+```erb
+<%# app/views/passkeys/index.html.erb %>
+<ul>
+  <% @passkeys.each do |passkey| %>
+    <li id="<%= dom_id(passkey) %>">
+      <%= passkey.name.presence || "Passkey" %> — added <%= passkey.created_at.to_date.to_fs(:long) %>
+      <%= button_to "Remove", passkey_path(passkey), method: :delete %>
+    </li>
+  <% end %>
+</ul>
+<%= passkey_registration_button "Add a passkey", passkeys_path,
+      options: @registration_options %>
+```
+
+These controllers live in `spec/dummy`, where the request specs exercise them
+end to end.
+
+### The building blocks
+
+`Unmagic::Passkeys::Request` provides the ceremony strong parameters
+(`passkey_registration_params`, `passkey_authentication_params`), the option
+builders (`passkey_registration_options`, `passkey_authentication_options`),
+and sets `Unmagic::Passkeys::WebAuthn::Current` (host/origin) per request.
+`passkey_sign_in_button` / `passkey_registration_button` render web components
+that refresh the challenge, run the browser ceremony, and submit the result;
+their `params:` option renders extra hidden fields into the ceremony form
+(like `button_to`'s).
 
 ## Configuration
 
+Configure the engine in a single block:
+
 ```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"
+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     = "/auth/passkeys"      # set in config/application.rb if overriding
+  # config.draw_routes       = true
+end
+```
+
+## Testing
+
+Mint valid WebAuthn ceremony payloads without a browser. Requiring the helper
+auto-includes it into Rails integration tests:
+
+```ruby
+# test/test_helper.rb
+require "unmagic/passkeys/test/helpers"
+
+# test/integration/passkey_sign_in_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_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/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 +/auth/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/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/lib/generators/unmagic/passkeys/install_generator.rb

@@ -9,7 +9,11 @@ module Unmagic
       # Installs unmagic-passkeys into a host app: copies the credentials migration
       # (matching the host's primary-key type), imports the JavaScript, and prints the
       # remaining controller/route/view wiring to do.
-      class InstallGenerator < Rails::Generators::Base
+      #
+      # +Rails+ is referenced with a leading +::+ throughout: inside the
+      # Unmagic::Passkeys namespace a nested constant named Rails (0.2.0 had one
+      # for the routes macro) shadows the framework and breaks the generator.
+      class InstallGenerator < ::Rails::Generators::Base
         include ActiveRecord::Generators::Migration
 
         source_root File.expand_path("templates", __dir__)
@@ -35,7 +39,7 @@ module Unmagic
 
         private
           def key_type
-            Rails.configuration.generators.options.dig(:active_record, :primary_key_type)
+            ::Rails.configuration.generators.options.dig(:active_record, :primary_key_type)
           end
 
           def table_id_option

data/lib/generators/unmagic/passkeys/templates/POST_INSTALL

@@ -14,6 +14,6 @@
   3. Wire up sign-in and registration controllers, routes and views.
      See the README "Host wiring" section for copy-paste examples.
 
-  The challenge endpoint (POST /unmagic/passkeys/challenge) and the JavaScript
+  The challenge endpoint (POST /auth/passkeys/challenge) and the JavaScript
   web components are already available.
 

data/lib/unmagic/passkeys/configuration.rb

@@ -0,0 +1,54 @@
+# 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
+
+      def initialize
+        @parent_class_name = "ApplicationRecord"
+        @routes_prefix = "/auth/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
+      end
+    end
+  end
+end

data/lib/unmagic/passkeys/engine.rb

@@ -9,24 +9,14 @@ 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            = "/auth/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" 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

@@ -12,6 +12,8 @@ module Unmagic::Passkeys::FormHelper
   # Options:
   # - +options+: WebAuthn creation options (JSON-serializable hash)
   # - +challenge_url+: endpoint to refresh the challenge nonce
+  # - +params+: extra params submitted with the ceremony (rendered as hidden
+  #   fields, nested hashes/arrays supported — like +button_to+'s +params+)
   # - +wrapper+: HTML attributes for the outer web component element
   # - +form+: additional HTML attributes for the +<form>+ tag. Supports a +:param+ key
   #   to set the form parameter namespace (default: +:passkey+)
@@ -22,7 +24,7 @@ module Unmagic::Passkeys::FormHelper
   # - All other options are passed to the +<button>+ tag
   def passkey_registration_button(name = nil, url = nil, **options, &block)
     url, name = name, block ? capture(&block) : nil if block_given?
-    component_options, form_options, button_options, error_options = partition_passkey_options(url, options)
+    component_options, form_options, button_options, error_options, extra_params = partition_passkey_options(url, options)
     error_options[:error][:message] ||= REGISTRATION_ERROR_MESSAGE
     error_options[:cancellation][:message] ||= REGISTRATION_CANCELLED_MESSAGE
     error_options[:duplicate][:message] ||= REGISTRATION_DUPLICATE_MESSAGE
@@ -31,6 +33,7 @@ module Unmagic::Passkeys::FormHelper
     content_tag("unmagic-passkey-registration-button", **component_options.transform_keys { |key| key.to_s.dasherize }) do
       tag.form(**form_options) do
         hidden_field_tag(:authenticity_token, form_authenticity_token) +
+          passkey_extra_param_fields(extra_params) +
           hidden_field_tag("#{param}[client_data_json]", nil, id: nil, data: { passkey_field: "client_data_json" }) +
           hidden_field_tag("#{param}[attestation_object]", nil, id: nil, data: { passkey_field: "attestation_object" }) +
           hidden_field_tag("#{param}[transports][]", nil, id: nil, data: { passkey_field: "transports" }) +
@@ -45,6 +48,8 @@ module Unmagic::Passkeys::FormHelper
   # Options:
   # - +options+: WebAuthn request options (JSON-serializable hash)
   # - +challenge_url+: endpoint to refresh the challenge nonce
+  # - +params+: extra params submitted with the ceremony (rendered as hidden
+  #   fields, nested hashes/arrays supported — like +button_to+'s +params+)
   # - +mediation+: WebAuthn mediation hint (e.g. +"conditional"+ for autofill-assisted sign in)
   # - +wrapper+: HTML attributes for the outer web component element
   # - +form+: additional HTML attributes for the +<form>+ tag. Supports a +:param+ key
@@ -56,7 +61,7 @@ module Unmagic::Passkeys::FormHelper
   # - All other options are passed to the +<button>+ tag
   def passkey_sign_in_button(name = nil, url = nil, **options, &block)
     url, name = name, block ? capture(&block) : nil if block_given?
-    component_options, form_options, button_options, error_options = partition_passkey_options(url, options)
+    component_options, form_options, button_options, error_options, extra_params = partition_passkey_options(url, options)
     error_options[:error][:message] ||= SIGN_IN_ERROR_MESSAGE
     error_options[:cancellation][:message] ||= SIGN_IN_CANCELLED_MESSAGE
     param = form_options.delete(:param)
@@ -64,6 +69,7 @@ module Unmagic::Passkeys::FormHelper
     content_tag("unmagic-passkey-sign-in-button", **component_options.transform_keys { |key| key.to_s.dasherize }) do
       tag.form(**form_options) do
         hidden_field_tag(:authenticity_token, form_authenticity_token) +
+          passkey_extra_param_fields(extra_params) +
           hidden_field_tag("#{param}[id]", nil, id: nil, data: { passkey_field: "id" }) +
           hidden_field_tag("#{param}[client_data_json]", nil, id: nil, data: { passkey_field: "client_data_json" }) +
           hidden_field_tag("#{param}[authenticator_data]", nil, id: nil, data: { passkey_field: "authenticator_data" }) +
@@ -77,6 +83,7 @@ module Unmagic::Passkeys::FormHelper
     def partition_passkey_options(url, options)
       passkey_options = options.fetch(:options, {})
       wrapper_options = options.fetch(:wrapper, {})
+      extra_params = options.fetch(:params, {})
 
       component_options = options
         .slice(:challenge_url, :mediation)
@@ -88,13 +95,27 @@ module Unmagic::Passkeys::FormHelper
 
       error_options = options.slice(:error, :cancellation, :duplicate).reverse_merge(error: {}, cancellation: {}, duplicate: {})
 
-      button_options = options.except(:options, :form, :wrapper, *component_options.keys, *error_options.keys)
+      button_options = options.except(:options, :form, :wrapper, :params, *component_options.keys, *error_options.keys)
 
-      [ wrapper_options.merge(component_options), form_options, button_options, error_options ]
+      [ wrapper_options.merge(component_options), form_options, button_options, error_options, extra_params ]
+    end
+
+    # Renders the +params+ option as hidden fields, flattening nested hashes
+    # and arrays into standard Rails parameter names.
+    def passkey_extra_param_fields(params, namespace = nil)
+      safe_join(params.map do |key, value|
+        name = namespace ? "#{namespace}[#{key}]" : key.to_s
+
+        case value
+        when Hash then passkey_extra_param_fields(value, name)
+        when Array then safe_join(value.map { |item| hidden_field_tag("#{name}[]", item, id: nil) })
+        else hidden_field_tag(name, value, id: nil)
+        end
+      end)
     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/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.3.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"
@@ -21,6 +22,20 @@ module Unmagic
   # +Unmagic::Passkeys.authenticate(params)+.
   module Passkeys
     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.3.0
 platform: ruby
 authors:
 - Keith Pitt
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-26 00:00:00.000000000 Z
+date: 2026-07-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -103,10 +103,12 @@ files:
 - 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/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