unmagic-passkeys 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ddd2eb491d1dbf70760a8fa843d6e09284b44d0031178c9312afebed493a3f5
-  data.tar.gz: a173df187a85d06e116321cb203966b6613c924771e294e1308504923d707b49
+  metadata.gz: 9d45bf4f51fee5d670d79d59a70518f2052417f00ecf549a263f1c23fa7d8aa3
+  data.tar.gz: a97fb1cf155def235ff658328850b0bafd5cf99b18c579501e8360839084e224
 SHA512:
-  metadata.gz: 2091181c23ecdbc5a1e1d0a1e75e7c28faa030158a452ef77c8b4ac171200ec0964cfeed4ffa69346d60b613fdfd93155108ceb009616d8e941a1659869e87ab
-  data.tar.gz: 49727646f8936293eaac8f24c26c0fc35e40c8879fb3ae5f19006d3edbf03f6017580071e8da6aa324873501c16c1108bbf91b93f154cab18cf4289026088dc3
+  metadata.gz: d00972cba516c64383dd7ab92c2301f276db4dbba1da08b7e9e6d35e878ab73df1ec47bfbfcedd51c92e58386f168317af1a1c8e131977310b2d2adc570a83aa
+  data.tar.gz: 74ecb8ef46d774e0f4ccf81ba0a33240d37bcf9b8fc4ccd0ea7fe5dbba76889f3c5b80864c4861ac196306f5c857ba253b29a9dd76345e514584a653593f531a

data/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 ## [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

data/README.md

@@ -59,11 +59,17 @@ 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 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
@@ -71,96 +77,173 @@ Include the JavaScript once — the form helpers render self-contained web compo
 import "unmagic/passkeys"
 ```
 
-### Batteries included: `use_unmagic_passkeys`
-
-This draws the multi-user passkey auth flows and points them at the engine's
-base controllers:
+Draw the routes:
 
 ```ruby
 # config/routes.rb
-use_unmagic_passkeys
+resource  :session,      only: %i[new create destroy]
+resource  :registration, only: %i[new create]
+resources :passkeys,     only: %i[index create destroy]
 ```
 
-| Flow          | Routes                                    | Controller                                |
-| ------------- | ----------------------------------------- | ----------------------------------------- |
-| `sessions`    | `GET/POST/DELETE /session`, `/session/new`| `Unmagic::Passkeys::SessionsController`    |
-| `credentials` | `/my/passkeys` (index/create/destroy)     | `Unmagic::Passkeys::CredentialsController` |
+### Sign-in
 
-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:
+Usernameless (discoverable credentials) — one page signs in any user, and
+conditional mediation offers passkeys through autofill:
 
 ```ruby
-# config/initializers/passkeys.rb
-Unmagic::Passkeys.configure do |config|
-  config.base_controller = "ApplicationController"       # so hooks see your helpers
+# app/controllers/sessions_controller.rb
+class SessionsController < ApplicationController
+  include Unmagic::Passkeys::Request
 
-  config.sign_in        { |holder| start_new_session_for(holder) }
-  config.sign_out       { terminate_session }
-  config.current_holder { Current.user }                 # for /my/passkeys
-end
-```
+  allow_unauthenticated_access only: %i[new create]
+  rate_limit to: 10, within: 3.minutes, only: :create
 
-Customize by subclassing a base controller and re-pointing the route:
+  def new
+    @authentication_options = passkey_authentication_options
+  end
 
-```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
+  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. Try again."
+    end
+  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
+  def destroy
+    terminate_session
+    redirect_to new_session_path, status: :see_other
+  end
 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.
+```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 is yours
+### Signup
 
-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:
+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
-# 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)
+# 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
 ```
 
-### À la carte primitives
+```erb
+<%# 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 } } %>
+```
 
-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:
+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
-class Sessions::PasskeysController < ApplicationController
+# app/controllers/passkeys_controller.rb
+class PasskeysController < ApplicationController
   include Unmagic::Passkeys::Request
 
+  def index
+    @passkeys = Current.user.passkeys.order(created_at: :desc)
+    @registration_options = passkey_registration_options(holder: Current.user)
+  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."
-    end
+    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
 ```
 
+```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:
@@ -178,7 +261,7 @@ Unmagic::Passkeys.configure do |config|
   # config.relying_party_name = "Example"
 
   # config.parent_class_name = "ApplicationRecord"
-  # config.routes_prefix     = "/unmagic/passkeys"   # set in config/application.rb if overriding
+  # config.routes_prefix     = "/auth/passkeys"      # set in config/application.rb if overriding
   # config.draw_routes       = true
 end
 ```
@@ -192,12 +275,12 @@ auto-includes it into Rails integration tests:
 # test/test_helper.rb
 require "unmagic/passkeys/test/helpers"
 
-# test/controllers/sessions/passkeys_controller_test.rb
+# 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_passkey_path, params: { passkey: assertion }
+post session_path, params: { passkey: assertion }
 ```
 
 For RSpec (or any non-integration test), include it yourself:

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

@@ -12,7 +12,7 @@
 #
 # == Route
 #
-# By default mounted at +/unmagic/passkeys/challenge+ (configurable via
+# By default mounted at +/auth/passkeys/challenge+ (configurable via
 # +Unmagic::Passkeys.configuration.routes_prefix+).
 #
 class Unmagic::Passkeys::ChallengesController < ActionController::Base

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

@@ -37,14 +37,9 @@ module Unmagic
       # +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"
+        @routes_prefix = "/auth/passkeys"
         @draw_routes = true
         @challenge_url = nil
         @default_creation_options = {}
@@ -53,41 +48,6 @@ module Unmagic
         @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

data/lib/unmagic/passkeys/engine.rb

@@ -12,14 +12,9 @@ module Unmagic
     #   Unmagic::Passkeys.configure do |config|
     #     config.default_creation_options = { attestation: :none }
     #     config.default_request_options  = { user_verification: :required }
-    #     config.routes_prefix            = "/unmagic/passkeys"
+    #     config.routes_prefix            = "/auth/passkeys"
     #   end
     class Engine < ::Rails::Engine
-      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 = Unmagic::Passkeys.configuration
 

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,9 +95,23 @@ 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

data/lib/unmagic/passkeys/version.rb

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

data/lib/unmagic/passkeys.rb

@@ -21,9 +21,6 @@ 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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unmagic-passkeys
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Keith Pitt
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-28 00:00:00.000000000 Z
+date: 2026-07-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -95,13 +95,8 @@ 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
@@ -112,7 +107,6 @@ files:
 - 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

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

@@ -1,35 +0,0 @@
-# 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/credentials_controller.rb

@@ -1,25 +0,0 @@
-# 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

@@ -1,40 +0,0 @@
-# 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/views/unmagic/passkeys/credentials/index.html.erb

@@ -1,22 +0,0 @@
-<%# 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

@@ -1,7 +0,0 @@
-<%# 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/rails/routes.rb

@@ -1,106 +0,0 @@
-# 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