maquina-generators 0.7.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a31ee05a1ed941cc88119c5721629c3c5089081dde3e7833d1768cb9598b202
-  data.tar.gz: 5bc0462a7009085c8a752791090347501a59886cab23eb74ba7bdd5ff0ff2f08
+  metadata.gz: 7e7ab2221409345c84231d6908e18f5f14b265d32a10229f288f23d4c5a03006
+  data.tar.gz: b4966e9de4099d0664da18fd6ba2818b560770cdb2dab121a9f06265e38b4769
 SHA512:
-  metadata.gz: 85c73f484e3ed4e09e28ec2bebf42ca13ea1dd84693b9e7abbffa0746f14aa69930d95607c0c592085ad6acd88ba2a5d81afd90e602c8265cf9122e05d86a3ef
-  data.tar.gz: bf4cec22c128729f8425b71d345a6ef166e6c9f4d18172860ef1eca3bbb894997397ce227297168f54218d6d26c87dc707dbedbd7b268594620543d22f1b6437
+  metadata.gz: f7b0d031778c2aa4b8cc03079e08f049a79d499500dfe0bb8b44b5e94e7743afdfc0ea6d0625d97b0128c937628980c9eb5317eef5bfe9ea62d68cd25f3e0487
+  data.tar.gz: 2ccfde4751e49534fb7c36149c623ea8fd93849a8e26e860fae0566556f2832173f8f488b708dca6e23f8890e8a6b4243571e61c6811723a325c1535f2a5dde5

data/README.md

@@ -62,6 +62,59 @@ All generated code lives in your app -- edit it directly:
 - **Email sender:** Edit `app/mailers/verification_mailer.rb`
 - **Translations:** Edit `config/locales/clave.*.yml`
 
+### Passkeys -- Passkey Sign-In for Clave
+
+**Passkeys** adds WebAuthn passkeys as a second way to sign in, on top of Clave. People add passkeys from a `/passkeys` page and sign in with Face ID, a fingerprint or a device PIN, either with a button or straight from the email field's autofill. The email code stays as the way in without a passkey, so removing every passkey never locks anyone out.
+
+The [`webauthn`](https://github.com/cedarcode/webauthn-ruby) gem handles only the cryptography (attestation and assertion parsing, signature, origin, challenge and user-verification checks). The flow itself, including controllers, model, views and JavaScript, is generated into your app. There is no JavaScript dependency: the Stimulus controllers use the browser's own `PublicKeyCredential.parseCreationOptionsFromJSON` / `parseRequestOptionsFromJSON` / `toJSON()`. The names (`passkeys` table, `credential_id`, `Session::PasskeysController`) follow the passkeys work proposed for Rails itself (rails/rails#57100).
+
+#### What it generates
+
+- **Gem:** `webauthn ~> 3.4`
+- **Initializer:** `config/initializers/webauthn.rb`. The relying party is `localhost` in development; production reads `WEBAUTHN_RP_ID` / `WEBAUTHN_ORIGINS` (or `webauthn:` in credentials) and refuses to boot without them, except during the asset build.
+- **Models:** `Passkey` (credential id, public key, sign count, transports, AAGUID, backup flags, last used) and `User#webauthn_id`, a random user handle created on first use
+- **Sign-in:** `Session::PasskeyChallengesController` and `Session::PasskeysController`. These need no email (discoverable credentials, empty allow-list), require user verification, use each challenge once and expire it after 5 minutes, and sign in through Clave's `start_new_session_for`. An unknown credential gets a 404 so the browser can forget it (`signalUnknownCredential`).
+- **Management:** `PasskeysController` and `PasskeyChallengesController` to add, rename and remove passkeys. Adding or removing a passkey needs a sign-in from the last 30 minutes (`PasskeyReauthentication::REAUTHENTICATE_AFTER`).
+- **Views and JavaScript:** `passkeys/index`, a `sessions/_passkey` partial rendered on the sign-in page (and `autocomplete="username webauthn"` on its email field), plus `passkey_sign_in_controller.js` and `passkey_registration_controller.js`
+- **Migrations:** `add_webauthn_id_to_users`, `create_passkeys`
+- **Locale files:** English and Spanish
+- **Rack::Attack:** a `passkey/ip` throttle when `config/initializers/rack_attack.rb` exists
+- **Tests:** a `register_passkey` and `sign_in_with_passkey(user)` helper on top of `WebAuthn::FakeClient`, loaded from `test/test_helper.rb`, and `test/integration/passkeys_test.rb` covering the flow. The test creates users the way Clave's `User` does, so adjust its `setup` if your model differs.
+
+#### Usage
+
+```bash
+rails g maquina:clave      # first
+rails g maquina:passkeys
+rails db:migrate
+```
+
+Then link to `passkeys_path` from your account or settings page. Anything the generator cannot place safely (a `User` model or sign-in page that no longer has Clave's shape) is listed after the install instead of being forced.
+
+#### Options
+
+```bash
+rails g maquina:passkeys               # Full install
+rails g maquina:passkeys --skip-views  # Endpoints only; bring your own UI
+```
+
+#### Production
+
+Passkeys are bound to a domain, and changing `rp_id` later orphans every saved passkey. Set it before the first user adds one:
+
+```bash
+WEBAUTHN_RP_ID=example.com
+WEBAUTHN_ORIGINS=https://example.com,https://app.example.com
+```
+
+`rp_id` can be a parent of the origins' host. To serve passkeys across different domains, publish `/.well-known/webauthn` (Related Origin Requests).
+
+#### Testing
+
+- **Integration tests:** `register_passkey` and `sign_in_with_passkey(user)` go through the real endpoints with `WebAuthn::FakeClient`.
+- **In a browser:** Chrome's virtual authenticator works in DevTools (More tools > WebAuthn) or over CDP (`WebAuthn.addVirtualAuthenticator` with `ctap2`, `internal`, a resident key and user verification). It answers the sign-in page's autofill request on its own, so loading `/session/new` signs you in without a click. To test the button, make `PublicKeyCredential.isConditionalMediationAvailable` return `false`.
+- **Dev server on another port:** set `WEBAUTHN_ORIGINS=http://localhost:<port>`.
+
 ### Registration -- Password-Based Authentication with Accounts
 
 **Registration** generates a password-based authentication system with multi-tenant account support. It builds on top of the Rails 8 authentication generator, adding an Account model (tenant), user roles, and a registration flow.

data/lib/generators/maquina/clave/templates/app/views/sessions/new.html.erb.tt

@@ -30,11 +30,13 @@
           <%%= form.submit t(".submit"), data: { component: "button", variant: "primary" }, class: "w-full px-4 py-3 text-base font-medium text-primary-foreground bg-primary hover:bg-primary/90 rounded-lg transition-colors cursor-pointer" %>
         </div>
       <%% end %>
+<% unless options[:skip_registration] -%>
 
       <p class="mt-6 text-center text-sm text-muted-foreground">
         <%%= t(".no_account") %>
         <%%= link_to t(".sign_up"), new_registration_path, class: "font-medium text-primary hover:text-primary/80" %>
       </p>
+<% end -%>
     </div>
   </div>
 </div>

data/lib/generators/maquina/passkeys/USAGE

@@ -0,0 +1,18 @@
+Description:
+  Adds passkey (WebAuthn) sign-in on top of Clave's email-code login. Needs
+  maquina:clave; the email code stays as the way in without a passkey.
+
+  Adds the webauthn gem, which only verifies the ceremonies; the flow is
+  generated into the app. Installs the Passkey model and a webauthn_id on
+  users, sign-in endpoints (POST /session/passkey_challenge and
+  /session/passkey) that ask for no email, a /passkeys page to add, rename
+  and remove passkeys (adding or removing needs a sign-in from the last 30
+  minutes), two Stimulus controllers that use the browser's own WebAuthn JSON
+  helpers (no JavaScript library), a passkey button and autofill on the
+  sign-in page, config/initializers/webauthn.rb, EN/ES locales, a
+  Rack::Attack throttle and a FakeClient test helper. Anything it cannot
+  place safely is listed after the install instead of being forced.
+
+Examples:
+  rails g maquina:passkeys
+  rails g maquina:passkeys --skip-views    # Endpoints only; bring your own UI

data/lib/generators/maquina/passkeys/passkeys_generator.rb

@@ -0,0 +1,260 @@
+require "rails/generators"
+require "rails/generators/migration"
+
+module Maquina
+  module Generators
+    class PasskeysGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      GEM_LINE = %(gem "webauthn", "~> 3.4")
+      USER_SESSIONS = /^  has_many :sessions, dependent: :destroy\n/
+      USER_PRIVATE = /^  private\n/
+      SIGN_IN_FORM_END = /^      <% end %>\n/
+      EMAIL_AUTOCOMPLETE = %(autocomplete: "email")
+      TEST_HELP = /^require "rails\/test_help"\n/
+      THROTTLE_LIMIT = 20
+      THROTTLE_PERIOD = "1.minute"
+
+      class_option :skip_views, type: :boolean, default: false,
+        desc: "Skip view templates and Stimulus controllers"
+      class_option :quiet, type: :boolean, default: false,
+        desc: "Suppress post-install instructions"
+
+      def self.next_migration_number(dirname)
+        current = Time.now.utc.strftime("%Y%m%d%H%M%S")
+        existing = Dir.glob("#{dirname}/[0-9]*_*.rb").map { |f| File.basename(f).split("_", 2).first }.max
+        (existing && existing >= current) ? existing.succ : current
+      end
+
+      # 1. Passkeys sign people in through clave's sessions; the email code
+      #    stays as the way to get in without one.
+      def require_clave
+        return if %w[app/models/email_verification.rb app/controllers/concerns/authentication.rb]
+          .all? { |path| File.exist?(File.join(destination_root, path)) }
+
+        raise Thor::Error, "maquina:passkeys adds passkeys to Clave's email-code sign-in. Run `rails g maquina:clave` first."
+      end
+
+      # 2. The webauthn gem verifies the ceremonies; the flow stays in the app.
+      def add_gem
+        gemfile = File.join(destination_root, "Gemfile")
+        return unless File.exist?(gemfile)
+        return if File.read(gemfile).match?(/^\s*gem ["']webauthn["']/)
+
+        append_to_file "Gemfile", "\n#{GEM_LINE}\n"
+      end
+
+      def run_bundle_install
+        return unless rails_app?
+
+        Bundler.with_unbundled_env do
+          system("bundle install", chdir: destination_root)
+        end
+      end
+
+      # 3. Relying party
+      def create_initializer
+        copy_file "config/initializers/webauthn.rb", "config/initializers/webauthn.rb"
+      end
+
+      # 4. Models
+      def create_models
+        copy_file "app/models/passkey.rb", "app/models/passkey.rb"
+
+        path = "app/models/user.rb"
+        content = File.read(File.join(destination_root, path))
+        return if content.include?("has_many :passkeys")
+
+        if content.match?(USER_SESSIONS) && content.scan(USER_PRIVATE).one?
+          inject_into_file path, user_association, after: USER_SESSIONS
+          inject_into_file path, user_webauthn_id, before: USER_PRIVATE
+        else
+          @user_pending = true
+        end
+      end
+
+      # 5. Controllers
+      def create_controllers
+        copy_file "app/controllers/concerns/passkey_challenge.rb", "app/controllers/concerns/passkey_challenge.rb"
+        copy_file "app/controllers/concerns/passkey_reauthentication.rb", "app/controllers/concerns/passkey_reauthentication.rb"
+        copy_file "app/controllers/session/passkey_challenges_controller.rb", "app/controllers/session/passkey_challenges_controller.rb"
+        copy_file "app/controllers/session/passkeys_controller.rb", "app/controllers/session/passkeys_controller.rb"
+        copy_file "app/controllers/passkey_challenges_controller.rb", "app/controllers/passkey_challenges_controller.rb"
+        copy_file "app/controllers/passkeys_controller.rb", "app/controllers/passkeys_controller.rb"
+      end
+
+      # 6. Routes
+      def add_routes
+        return if File.read(File.join(destination_root, "config/routes.rb")).include?("generated by maquina:passkeys")
+
+        route <<~RUBY
+          # Passkeys (generated by maquina:passkeys)
+          resource :session, only: [] do
+            resource :passkey_challenge, only: :create, controller: "session/passkey_challenges"
+            resource :passkey, only: :create, controller: "session/passkeys"
+          end
+          resource :passkey_challenge, only: :create
+          resources :passkeys, only: [:index, :create, :update, :destroy]
+        RUBY
+      end
+
+      # 7. Migrations
+      def add_migrations
+        migration_template "migration_add_webauthn_id_to_users.rb.tt", "db/migrate/add_webauthn_id_to_users.rb"
+        migration_template "migration_create_passkeys.rb.tt", "db/migrate/create_passkeys.rb"
+      end
+
+      # 8. Views and Stimulus controllers
+      def create_views
+        return if options[:skip_views]
+
+        copy_file "app/views/passkeys/index.html.erb", "app/views/passkeys/index.html.erb"
+        copy_file "app/views/sessions/_passkey.html.erb", "app/views/sessions/_passkey.html.erb"
+        copy_file "app/javascript/controllers/passkey_sign_in_controller.js",
+          "app/javascript/controllers/passkey_sign_in_controller.js"
+        copy_file "app/javascript/controllers/passkey_registration_controller.js",
+          "app/javascript/controllers/passkey_registration_controller.js"
+
+        add_passkey_to_sign_in_page
+      end
+
+      # 9. Locale files
+      def create_locale_files
+        copy_file "config/locales/passkeys.en.yml", "config/locales/passkeys.en.yml"
+        copy_file "config/locales/passkeys.es.yml", "config/locales/passkeys.es.yml"
+      end
+
+      # 10. Test helper and the flow's integration test
+      def create_test_helper
+        copy_file "test/test_helpers/webauthn_test_helper.rb", "test/test_helpers/webauthn_test_helper.rb"
+        copy_file "test/integration/passkeys_test.rb", "test/integration/passkeys_test.rb"
+
+        path = File.join(destination_root, "test/test_helper.rb")
+        return unless File.exist?(path)
+
+        content = File.read(path)
+        return if content.include?(test_helper_require)
+        return @test_helper_pending = true unless content.match?(TEST_HELP)
+
+        inject_into_file "test/test_helper.rb", "#{test_helper_require}\n", after: TEST_HELP
+      end
+
+      # 11. Rack::Attack: the sign-in ceremony gets its own login-style throttle.
+      def configure_rack_attack
+        path = "config/initializers/rack_attack.rb"
+        full_path = File.join(destination_root, path)
+        return @rack_attack_pending = true unless File.exist?(full_path)
+        return if File.read(full_path).include?(%("passkey/ip"))
+
+        append_to_file path, passkey_throttle
+      end
+
+      # 12. Post-install message
+      def show_post_install
+        return if options[:quiet]
+
+        say ""
+        say "Passkeys have been installed!", :green
+        say ""
+        say "Next steps:", :yellow
+        say "  1. bin/rails db:migrate"
+        say "  2. Link to passkeys_path from your account or settings page"
+        say "  3. Visit /passkeys signed in, add a passkey, and sign in with it at /session/new"
+        say ""
+        say "Production: passkeys are bound to your domain. Set them before deploying:", :yellow
+        say "  WEBAUTHN_RP_ID=example.com"
+        say "  WEBAUTHN_ORIGINS=https://example.com"
+        say "  (or webauthn: {rp_id:, origins:} in credentials; see config/initializers/webauthn.rb)"
+        say ""
+        if @user_pending
+          say "Add to app/models/user.rb:", :yellow
+          say user_association
+          say user_webauthn_id
+        end
+        if @sign_in_pending
+          say "Offer passkeys on the sign-in page (app/views/sessions/new.html.erb):", :yellow
+          say "  - render the button after the email form:  <%= render \"sessions/passkey\" %>"
+          say %(  - let the email field suggest passkeys:     autocomplete: "username webauthn")
+          say ""
+        end
+        if @test_helper_pending
+          say "Load the passkey test helper in test/test_helper.rb:", :yellow
+          say "  #{test_helper_require}"
+          say ""
+        end
+        if @rack_attack_pending
+          say "Throttle passkey sign-in in config/initializers/rack_attack.rb:", :yellow
+          say passkey_throttle
+          say ""
+        end
+        say "Optional:", :yellow
+        say "  - Serving more than one domain? Publish /.well-known/webauthn (Related Origin Requests)"
+        say "  - Edit config/locales/passkeys.*.yml to customize messages"
+        say "  - Integration tests: register_passkey and sign_in_with_passkey(user) (test/test_helpers/webauthn_test_helper.rb)"
+        say ""
+      end
+
+      private
+
+      def rails_app?
+        File.exist?(File.join(destination_root, "bin/rails"))
+      end
+
+      def migration_version
+        "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
+      end
+
+      # The button goes after clave's email form, and the email field offers
+      # saved passkeys in its autofill. A page that no longer has that shape is
+      # left alone and listed after the install.
+      def add_passkey_to_sign_in_page
+        path = "app/views/sessions/new.html.erb"
+        full_path = File.join(destination_root, path)
+        return @sign_in_pending = true unless File.exist?(full_path)
+
+        content = File.read(full_path)
+        return if content.include?(%(render "sessions/passkey"))
+        return @sign_in_pending = true unless content.scan(SIGN_IN_FORM_END).one? && content.include?(EMAIL_AUTOCOMPLETE)
+
+        inject_into_file path, %(\n      <%= render "sessions/passkey" %>\n), after: SIGN_IN_FORM_END
+        gsub_file path, EMAIL_AUTOCOMPLETE, %(autocomplete: "username webauthn")
+      end
+
+      def test_helper_require
+        %(require_relative "test_helpers/webauthn_test_helper")
+      end
+
+      def user_association
+        "  has_many :passkeys, dependent: :destroy\n"
+      end
+
+      def user_webauthn_id
+        <<~RUBY.gsub(/^(?=.)/, "  ")
+          # The WebAuthn user handle: random and stable, never the id or the email,
+          # since authenticators store it and hand it back on every sign-in.
+          def webauthn_id
+            super || begin
+              update_column(:webauthn_id, WebAuthn.generate_user_id)
+              super
+            end
+          end
+
+        RUBY
+      end
+
+      def passkey_throttle
+        <<~RUBY
+
+          # Passkey sign-in (maquina:passkeys): the challenge and the assertion,
+          # counted like the email-code login above. Keyed on the address Rails
+          # resolves through trusted proxies, not the proxy hop in req.ip.
+          Rack::Attack.throttle("passkey/ip", limit: #{THROTTLE_LIMIT}, period: #{THROTTLE_PERIOD}) do |req|
+            (req.env["action_dispatch.remote_ip"]&.to_s || req.ip) if req.path.start_with?("/session/passkey") && req.post?
+          end
+        RUBY
+      end
+    end
+  end
+end

data/lib/generators/maquina/passkeys/templates/app/controllers/concerns/passkey_challenge.rb

@@ -0,0 +1,42 @@
+# One WebAuthn challenge per ceremony, kept in the session (generated by
+# maquina:passkeys).
+#
+# The browser signs the challenge, so a stored one that could be used twice
+# would let a captured response be replayed. take_passkey_challenge removes it
+# before anything is verified, and a challenge older than CHALLENGE_TTL is
+# refused. Registration and sign-in keep theirs under separate keys, so one
+# ceremony never consumes the other's.
+module PasskeyChallenge
+  extend ActiveSupport::Concern
+
+  CHALLENGE_TTL = 5.minutes
+
+  private
+
+  def store_passkey_challenge(purpose, challenge)
+    session[passkey_challenge_key(purpose)] = {
+      "challenge" => challenge,
+      "expires_at" => CHALLENGE_TTL.from_now.to_i
+    }
+  end
+
+  def take_passkey_challenge(purpose)
+    stored = session.delete(passkey_challenge_key(purpose))
+    stored["challenge"] if stored && stored["expires_at"].to_i > Time.current.to_i
+  end
+
+  def passkey_challenge_key(purpose)
+    :"passkey_#{purpose}_challenge"
+  end
+
+  # The browser's PublicKeyCredential#toJSON(). It is checked by signature, not
+  # assigned to a record, so only the shape is permitted here.
+  def passkey_credential_params
+    params.require(:credential).permit(
+      :id, :rawId, :type, :authenticatorAttachment,
+      response: [:clientDataJSON, :attestationObject, :authenticatorData, :signature, :userHandle,
+        :publicKey, :publicKeyAlgorithm, transports: []],
+      clientExtensionResults: {}
+    ).to_h
+  end
+end

data/lib/generators/maquina/passkeys/templates/app/controllers/concerns/passkey_reauthentication.rb

@@ -0,0 +1,26 @@
+# Adding or removing a passkey asks for a recent sign-in (generated by
+# maquina:passkeys).
+#
+# A passkey added from a stolen session cookie would outlive the cookie, so
+# a session older than REAUTHENTICATE_AFTER is ended and the person signs in
+# again (email code or passkey), coming back to the passkeys page after.
+module PasskeyReauthentication
+  extend ActiveSupport::Concern
+
+  REAUTHENTICATE_AFTER = 30.minutes
+
+  private
+
+  def require_recent_sign_in
+    return if Current.session.created_at.after?(REAUTHENTICATE_AFTER.ago)
+
+    terminate_session
+    session[:return_to_after_authenticating] = passkeys_url
+    flash[:alert] = t("flash.passkeys.reauthenticate")
+
+    respond_to do |format|
+      format.html { redirect_to new_session_path }
+      format.json { render json: {redirect_url: new_session_url}, status: :unauthorized }
+    end
+  end
+end

data/lib/generators/maquina/passkeys/templates/app/controllers/passkey_challenges_controller.rb

@@ -0,0 +1,24 @@
+class PasskeyChallengesController < ApplicationController
+  include PasskeyChallenge
+  include PasskeyReauthentication
+
+  before_action :require_recent_sign_in
+
+  # POST /passkey_challenge
+  #
+  # Options for navigator.credentials.create(). A discoverable credential
+  # (resident key) is what makes it a passkey: the device keeps the account,
+  # so sign-in needs no email. The user's existing passkeys are excluded so the
+  # same authenticator is not registered twice.
+  def create
+    user = Current.user
+    options = WebAuthn::Credential.options_for_create(
+      user: {id: user.webauthn_id, name: user.email_address, display_name: user.name.presence || user.email_address},
+      exclude: user.passkeys.pluck(:credential_id),
+      authenticator_selection: {resident_key: "required", user_verification: "required"}
+    )
+    store_passkey_challenge(:registration, options.challenge)
+
+    render json: options
+  end
+end

data/lib/generators/maquina/passkeys/templates/app/controllers/passkeys_controller.rb

@@ -0,0 +1,68 @@
+class PasskeysController < ApplicationController
+  include PasskeyChallenge
+  include PasskeyReauthentication
+
+  before_action :require_recent_sign_in, only: %i[create destroy]
+  before_action :set_passkey, only: %i[update destroy]
+
+  # GET /passkeys
+  def index
+    @passkeys = Current.user.passkeys.order(:created_at)
+  end
+
+  # POST /passkeys
+  def create
+    challenge = take_passkey_challenge(:registration)
+    return render_failure(t("flash.passkeys.challenge_expired")) unless challenge
+
+    credential = WebAuthn::Credential.from_create(passkey_credential_params)
+    # Checks the challenge, the origin, the relying party and that the person
+    # was verified on the device, not just present.
+    credential.verify(challenge, user_verification: true)
+
+    aaguid = credential.response.authenticator_data.aaguid
+    Current.user.passkeys.create!(
+      credential_id: credential.id,
+      public_key: credential.public_key,
+      sign_count: credential.sign_count,
+      transports: credential.response.transports,
+      aaguid: aaguid,
+      backup_eligible: credential.backup_eligible?,
+      backed_up: credential.backed_up?,
+      name: Passkey.default_name(aaguid)
+    )
+
+    Rails.logger.info "[AUTH] Passkey added for #{Current.user.email_address} from #{request.remote_ip}"
+    flash[:notice] = t("flash.passkeys.created")
+    render json: {redirect_url: passkeys_url}, status: :created
+  rescue WebAuthn::Error, ActiveRecord::RecordInvalid => error
+    Rails.logger.info "[AUTH] Passkey registration failed (#{error.class.name.demodulize}) for #{Current.user.email_address}"
+    render_failure(t("flash.passkeys.registration_failed"))
+  end
+
+  # PATCH /passkeys/:id
+  def update
+    if @passkey.update(params.expect(passkey: [:name]))
+      redirect_to passkeys_path, notice: t("flash.passkeys.updated"), status: :see_other
+    else
+      redirect_to passkeys_path, alert: @passkey.errors.full_messages.to_sentence, status: :see_other
+    end
+  end
+
+  # DELETE /passkeys/:id
+  def destroy
+    @passkey.destroy
+    Rails.logger.info "[AUTH] Passkey removed for #{Current.user.email_address} from #{request.remote_ip}"
+    redirect_to passkeys_path, notice: t("flash.passkeys.destroyed"), status: :see_other
+  end
+
+  private
+
+  def set_passkey
+    @passkey = Current.user.passkeys.find(params[:id])
+  end
+
+  def render_failure(message)
+    render json: {error: message}, status: :unprocessable_entity
+  end
+end

data/lib/generators/maquina/passkeys/templates/app/controllers/session/passkey_challenges_controller.rb

@@ -0,0 +1,18 @@
+class Session::PasskeyChallengesController < ApplicationController
+  include PasskeyChallenge
+
+  allow_unauthenticated_access
+
+  # POST /session/passkey_challenge
+  #
+  # Options for navigator.credentials.get(). No allowCredentials: the browser
+  # offers every passkey it holds for this site, so nobody types an email and
+  # the response says nothing about which accounts exist. It is a POST so a
+  # Turbo-cached page never reuses a challenge.
+  def create
+    options = WebAuthn::Credential.options_for_get(user_verification: "required")
+    store_passkey_challenge(:authentication, options.challenge)
+
+    render json: options
+  end
+end

data/lib/generators/maquina/passkeys/templates/app/controllers/session/passkeys_controller.rb

@@ -0,0 +1,55 @@
+class Session::PasskeysController < ApplicationController
+  include PasskeyChallenge
+
+  allow_unauthenticated_access
+  rate_limit to: 10, within: 3.minutes, only: :create, with: -> { render json: {error: t("flash.general.rate_limited")}, status: :too_many_requests }
+
+  # POST /session/passkey
+  def create
+    challenge = take_passkey_challenge(:authentication)
+    return render_failure(t("flash.passkeys.challenge_expired")) unless challenge
+
+    credential = WebAuthn::Credential.from_get(passkey_credential_params)
+    passkey = Passkey.includes(:user).find_by(credential_id: credential.id)
+
+    # Deleted here but still saved on the device: the browser can be told to
+    # forget it (PublicKeyCredential.signalUnknownCredential).
+    unless passkey
+      Rails.logger.info "[AUTH] Passkey sign-in with an unknown credential from #{request.remote_ip}"
+      render json: {error: t("flash.passkeys.unknown"), credential_id: credential.id, rp_id: WebAuthn.configuration.rp_id},
+        status: :not_found
+      return
+    end
+
+    user = passkey.user
+    if user.blocked? || credential.user_handle != user.webauthn_id
+      Rails.logger.info "[AUTH] Passkey sign-in refused for #{user.email_address} from #{request.remote_ip}"
+      return render_failure(t("flash.passkeys.failed"))
+    end
+
+    # Checks the challenge, the origin, the signature with the stored public
+    # key, user verification (Face ID, fingerprint, device PIN) and that the
+    # signature counter moved forward.
+    credential.verify(challenge, public_key: passkey.public_key, sign_count: passkey.sign_count, user_verification: true)
+    passkey.record_use!(credential.sign_count)
+
+    Rails.logger.info "[AUTH] Successful passkey login for #{user.email_address} from #{request.remote_ip}"
+    start_new_session_for(user)
+    flash[:notice] = t("flash.sessions.create.success")
+    render json: {redirect_url: after_authentication_url}
+  rescue WebAuthn::SignCountVerificationError
+    # A valid signature with a counter that went backwards: possibly a cloned
+    # authenticator. Synced passkeys always report 0 and never land here.
+    Rails.logger.warn "[AUTH] Passkey sign count went backwards for #{passkey.user.email_address} from #{request.remote_ip}"
+    render_failure(t("flash.passkeys.failed"))
+  rescue WebAuthn::Error => error
+    Rails.logger.info "[AUTH] Passkey sign-in failed (#{error.class.name.demodulize}) from #{request.remote_ip}"
+    render_failure(t("flash.passkeys.failed"))
+  end
+
+  private
+
+  def render_failure(message)
+    render json: {error: message}, status: :unprocessable_entity
+  end
+end