passkeyed 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2bee85e27d2a1bad05798dc69c2f4e0eb401c33c16cbdb7a300192b19739165e
+  data.tar.gz: 017b71f8707aff080a232197fb576d8a8633c3c18a87e82cb8ea1f516386adac
+SHA512:
+  metadata.gz: 378aaa416e294eb648ef4c2257e9f8cad8dbd2d108dfc83276f1abc0cb91bd490174f60b3207f023040c3647411e3223fcca477b81b8521ad3ad746d71a794ff
+  data.tar.gz: 9f81bcb1a00d2f3c77d99b59e81bd5d581b591dcfa48e22406307e8aad83daad71ec17a020093b29891331cbff036f1e408f6100d87409807385e3b6cd68c870

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Ardeleanu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,271 @@
+# passkeyed
+
+Passwordless, usernameless passkey ([WebAuthn](https://www.w3.org/TR/webauthn-2/))
+authentication for Rails, built on
+[webauthn-ruby](https://github.com/cedarcode/webauthn-ruby). No mountable
+engine hiding the flow: you get a model concern, a controller concern exposing
+four methods, and a Stimulus controller — you write your own routes,
+controllers, and views.
+
+A passkey is a public/private key pair created for one site. The private key
+never leaves the user's device, your server stores only the public half, and
+the browser binds each credential to its origin — nothing to phish, nothing
+worth stealing from your database.
+
+Companion to a two-part series:
+[*Passkeys from first principles*](https://www.pardel.dev/2026/06/28/passkeys-from-first-principles.html)
+(what passkeys are and how the ceremonies work) and
+[*Building passkeys in Ruby on Rails*](https://www.pardel.dev/2026/07/04/passkeys-in-ruby-on-rails.html)
+(the from-scratch build this gem packages).
+
+## Installation
+
+```ruby
+gem "passkeyed"
+```
+
+```sh
+bundle install
+bin/rails generate passkeyed:install
+bin/rails db:migrate
+```
+
+The generator adds the `passkeyed_credentials` table, a `webauthn_id` column
+on your owner model (backfilled for existing rows, so current users can
+register passkeys immediately), an initializer, the Stimulus controller, and
+`include Passkeyed::Model` in your model.
+
+There is no JavaScript dependency: the Stimulus controller uses the browser's
+native `PublicKeyCredential` JSON methods
+([shipped in every major browser](https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredential))
+and reports passkeys as unavailable on a browser too old to have them.
+
+## Configuration
+
+`config/initializers/passkeyed.rb`:
+
+```ruby
+Passkeyed.configure do |config|
+  config.rp_name           = "Acme"
+  config.rp_id             = "acme.example"            # optional in dev
+  config.allowed_origins   = ["https://acme.example"]  # required when deployed
+  config.user_verification = "required"
+  config.challenge_timeout = 300                       # seconds a challenge stays valid
+end
+```
+
+In any environment other than `development` and `test`, boot fails with a
+`Passkeyed::ConfigurationError` when `allowed_origins` is blank or non-HTTPS
+(WebAuthn requires a secure context), so the generated localhost default can't
+silently ship. passkeyed never writes to webauthn-ruby's global configuration —
+it hands an isolated `WebAuthn::RelyingParty` to every call — so an app using
+webauthn-ruby directly keeps its own settings.
+
+## Usage
+
+Mix the ceremony helpers into a controller. Each ceremony is a challenge that
+the authenticator signs and the server verifies.
+
+```ruby
+class RegistrationsController < ApplicationController
+  include Passkeyed::Ceremonies
+
+  # POST /passkeys/registration_options
+  def options
+    render json: passkey_registration_options(current_user)
+  end
+
+  # POST /passkeys
+  def create
+    passkey_register!(current_user, params[:credential], nickname: params[:nickname])
+    render json: { status: "ok" }
+  rescue Passkeyed::Error => e
+    render json: { error: e.message }, status: :unprocessable_entity
+  end
+end
+
+class SessionsController < ApplicationController
+  include Passkeyed::Ceremonies
+
+  # POST /session/options
+  def options
+    render json: passkey_authentication_options
+  end
+
+  # POST /session
+  def create
+    user = passkey_authenticate!(params[:credential])
+    session[:user_id] = user.id
+    render json: { status: "ok" }
+  rescue Passkeyed::Error
+    render json: { error: "Authentication failed" }, status: :unauthorized
+  end
+end
+```
+
+Wire the Stimulus controller in your views. To register a passkey (the optional
+`nickname` input lets the user label the device):
+
+```erb
+<div data-controller="passkey"
+     data-passkey-registration-options-url-value="<%= options_passkeys_path %>"
+     data-passkey-registration-url-value="<%= passkeys_path %>"
+     data-passkey-redirect-url-value="<%= dashboard_path %>">
+  <input data-passkey-target="nickname" placeholder="Laptop">
+  <button data-action="passkey#register">Add a passkey</button>
+  <p data-passkey-target="error" role="alert"></p>
+</div>
+```
+
+To sign in:
+
+```erb
+<div data-controller="passkey"
+     data-passkey-authentication-options-url-value="<%= options_session_path %>"
+     data-passkey-authentication-url-value="<%= session_path %>"
+     data-passkey-redirect-url-value="<%= dashboard_path %>">
+  <button data-action="passkey#authenticate">Sign in with a passkey</button>
+  <p data-passkey-target="error" role="alert"></p>
+</div>
+```
+
+(`role="alert"` makes screen readers announce a ceremony failure.)
+
+### Conditional UI (passkey autofill)
+
+Add `data-passkey-conditional-value="true"` and an input marked
+`autocomplete="username webauthn"` to also offer passkeys through the
+browser's autofill:
+
+```erb
+<div data-controller="passkey"
+     data-passkey-conditional-value="true"
+     data-passkey-authentication-options-url-value="<%= options_session_path %>"
+     data-passkey-authentication-url-value="<%= session_path %>"
+     data-passkey-redirect-url-value="<%= dashboard_path %>">
+  <input type="text" autocomplete="username webauthn" placeholder="you@example.com">
+  <button data-action="passkey#authenticate">Sign in with a passkey</button>
+  <p data-passkey-target="error" role="alert"></p>
+</div>
+```
+
+The feature is skipped where the browser lacks it, a modal ceremony or
+navigation aborts the pending request cleanly, and a failed attempt (a
+dismissed sheet, an expired challenge) re-arms autofill automatically.
+
+### Reacting to a ceremony from JavaScript
+
+After a successful ceremony the controller dispatches a cancelable
+`passkey:registered` / `passkey:authenticated` event (detail: the server's
+JSON response) before following `data-passkey-redirect-url-value` (or
+reloading). Call `event.preventDefault()` to take over — e.g. to update the
+page with Turbo. Failures dispatch `passkey:error`.
+
+## Public API
+
+| Method | Purpose |
+|---|---|
+| `Passkeyed::Model` | Include in the owner model: credentials association + `webauthn_id`. |
+| `passkey_registration_options(user)` | Build creation options (discoverable), stash the challenge. |
+| `passkey_register!(user, credential, nickname:)` | Verify and persist a new credential. |
+| `passkey_authentication_options` | Build request options (no allow-list), stash the challenge. |
+| `passkey_authenticate!(credential)` | Verify an assertion and return the owner. |
+
+All ceremony failures raise `Passkeyed::Error` or a subclass
+(`RegistrationError`, `AuthenticationError`, `CredentialNotFound`,
+`ChallengeMissing`, `ChallengeExpired`).
+
+### Managing a user's passkeys
+
+List, rename, and revoke through the owner, so a mismatched id raises
+`ActiveRecord::RecordNotFound` instead of touching another account's
+credential:
+
+```ruby
+current_user.passkeyed_credentials            # list (id, nickname, created_at, ...)
+current_user.rename_passkey(id, "Work Laptop")
+current_user.revoke_passkey(id)               # guard the last passkey in your app
+```
+
+Each credential also records metadata for richer management UIs:
+
+| Column | Meaning |
+|---|---|
+| `backed_up` / `backup_eligible` | Synced passkey (iCloud Keychain, Google Password Manager) vs device-bound. Refreshed on every sign-in. |
+| `transports` | How the authenticator talks to clients, e.g. `["internal", "hybrid"]`. |
+| `aaguid` | The authenticator model's UUID (nil when zeroed); map to names via the [community AAGUID list](https://github.com/passkeydeveloper/passkey-authenticator-aaguids). |
+| `last_used_at` | Stamped on every successful assertion. |
+
+The user entity sent at registration uses `passkey_name` (an email by default)
+and `passkey_display_name` (defaults to `passkey_name`). Override either in
+your model.
+
+### Hooks
+
+Override these private no-op methods in your controller to run after a
+successful ceremony:
+
+```ruby
+def after_passkey_authentication(credential, user)
+  AuditLog.record(:passkey_sign_in, user:, credential:)
+end
+```
+
+`after_passkey_registration(credential)` is the registration counterpart. Both
+run with full controller context and outside the ceremony's error handling, so
+an exception you raise surfaces as itself.
+
+### Instrumentation
+
+Both bang methods emit `ActiveSupport::Notifications` events —
+`register.passkeyed` and `authenticate.passkeyed` — with `:credential`/`:user`
+in the payload and, unlike the success-only hooks, the standard `:exception`
+keys on failure, so probing is observable:
+
+```ruby
+ActiveSupport::Notifications.subscribe("authenticate.passkeyed") do |event|
+  next unless event.payload[:exception]
+
+  Rails.logger.warn("passkey sign-in failed: #{event.payload[:exception_object]&.message}")
+end
+```
+
+## Notes and non-goals
+
+- **Signature counter.** A non-increasing `sign_count` from an authenticator
+  that reports nonzero counts raises `Passkeyed::AuthenticationError` — the
+  classic cloned-authenticator signal. Synced passkeys report zero on both
+  sides and are exempt.
+- **Return one generic message for failed sign-ins**, as the example above
+  does: rescue `Passkeyed::AuthenticationError` (which `CredentialNotFound`
+  subclasses) so you don't reveal whether a credential id is on record.
+  Response *timing* can still hint at it — an unknown id skips the signature
+  check — so pair the generic message with rate limiting.
+- **Rate-limit the ceremony endpoints.** They are unauthenticated and run
+  public-key crypto on every request. On Rails 8+:
+  `rate_limit to: 10, within: 1.minute, only: %i[options create]`; on older
+  Rails, use `rack-attack`.
+- **Sessions and CSRF.** Challenges are stashed in `session`, and the Stimulus
+  controller sends the CSRF token from the `csrf_meta_tags` meta tag — both
+  standard in a full-stack Rails app. In an API-only app, add session
+  middleware (or override `passkeyed_session`) and your own
+  request-authenticity scheme.
+- **Account recovery** is your responsibility: plan for the user who loses
+  their device (a second passkey, or an out-of-band recovery path).
+- Out of scope: password fallback, passkeys-as-second-factor, attestation
+  verification, and Devise integration.
+
+## Development
+
+```sh
+bin/setup
+bundle exec rake test              # Minitest; ceremonies driven by WebAuthn::FakeClient
+node --test test/javascript/*.test.mjs   # Stimulus controller tests, no npm install
+```
+
+CI also runs the suite against the oldest supported Rails:
+`BUNDLE_GEMFILE=gemfiles/rails_7.1.gemfile bundle exec rake test`.
+
+## License
+
+[MIT](LICENSE.txt).

data/lib/generators/passkeyed/install/USAGE

@@ -0,0 +1,14 @@
+Description:
+    Installs passkeyed: adds the passkeyed_credentials table and a webauthn_id
+    column on the owner model, an initializer, the passkey Stimulus controller,
+    and includes Passkeyed::Model in the owner model.
+
+Example:
+    bin/rails generate passkeyed:install
+    bin/rails generate passkeyed:install --user=Account
+
+    This will create:
+        db/migrate/XXXXXXXX_create_passkeyed_credentials.rb
+        config/initializers/passkeyed.rb
+        app/javascript/controllers/passkey_controller.js
+    And inject `include Passkeyed::Model` into the owner model.

data/lib/generators/passkeyed/install/install_generator.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Passkeyed
+  module Generators
+    # Wires passkeyed into a host Rails app:
+    #
+    #   bin/rails generate passkeyed:install
+    #
+    # Adds the credentials table (and a webauthn_id column on the owner),
+    # an initializer, the Stimulus controller, and the model concern.
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :user,
+                   type: :string,
+                   default: "User",
+                   desc: "Name of the model that owns passkeys"
+
+      def create_migration_file
+        migration_template(
+          "create_passkeyed_credentials.rb.erb",
+          "db/migrate/create_passkeyed_credentials.rb"
+        )
+      end
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/passkeyed.rb"
+      end
+
+      def copy_stimulus_controller
+        copy_file(
+          "passkey_controller.js",
+          "app/javascript/controllers/passkey_controller.js"
+        )
+      end
+
+      def inject_model_concern
+        model_path = "app/models/#{owner_model.underscore}.rb"
+        full_path = File.join(destination_root, model_path)
+
+        unless File.exist?(full_path)
+          say_status :skip, "#{model_path} not found; add `include Passkeyed::Model` to your owner model", :yellow
+          return
+        end
+
+        source = File.read(full_path)
+        class_name = owner_model.demodulize
+
+        # Idempotent: re-running the generator must not inject a second include.
+        # Anchor on a real include line (not a bare substring, which a comment or
+        # the just-injected snippet would satisfy).
+        if source.match?(/^\s*include\s+Passkeyed::Model\b/)
+          say_status :identical, "Passkeyed::Model already included in #{model_path}", :blue
+          return
+        end
+
+        # A single-line body (`class User; end`) can't take an injected line
+        # safely, so bail to a manual instruction rather than placing the include
+        # outside the class.
+        if source.match?(/^\s*class\s+#{Regexp.escape(class_name)}\b[^\n]*;\s*end/)
+          say_status :skip, "#{model_path} defines #{class_name} on one line; add `include Passkeyed::Model` manually",
+                     :yellow
+          return
+        end
+
+        # inject_into_class places the include after the class declaration with
+        # correct indentation, and handles namespaced/indented definitions.
+        inject_into_class model_path, class_name, "  include Passkeyed::Model\n"
+
+        # inject_into_class is a silent no-op when the class can't be matched, so
+        # confirm the include actually landed rather than reporting false success.
+        return if File.read(full_path).match?(/^\s*include\s+Passkeyed::Model\b/)
+
+        say_status :skip, "could not edit #{model_path}; add `include Passkeyed::Model` manually", :yellow
+      end
+
+      def print_next_steps
+        say "\npasskeyed installed. Next:", :green
+        say "  1. bin/rails db:migrate"
+        say "  2. add routes + a controller using Passkeyed::Ceremonies (see the README)"
+      end
+
+      private
+
+      def owner_model
+        options[:user]
+      end
+
+      # Used by the migration template. Resolve the real table from the model
+      # class so namespaced owners work (Admin::User.table_name => "users");
+      # tableize would wrongly produce "admin/users". Fall back to tableize when
+      # the class can't be loaded at generate time.
+      def owner_table
+        owner_model.constantize.table_name
+      rescue NameError
+        owner_model.tableize
+      end
+    end
+  end
+end

data/lib/generators/passkeyed/install/templates/create_passkeyed_credentials.rb.erb

@@ -0,0 +1,56 @@
+class CreatePasskeyedCredentials < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  # On a large, busy <%= owner_table %> table (Postgres), consider building the
+  # indexes with algorithm: :concurrently (in their own disable_ddl_transaction!
+  # migration) to avoid holding a write lock.
+  def change
+    add_column :<%= owner_table %>, :webauthn_id, :string
+
+    # Backfill a unique random WebAuthn handle for every pre-existing
+    # <%= owner_model %> *before* adding the unique index. Without this, rows that
+    # existed when passkeyed was installed keep a NULL webauthn_id (the model's
+    # before_create only fires for new rows), and their registration options
+    # would omit user.id, breaking passkey registration for the existing user base.
+    reversible do |dir|
+      dir.up do
+        backfill = Class.new(ActiveRecord::Base) { self.table_name = :<%= owner_table %> }
+        backfill.reset_column_information
+        backfill.where(webauthn_id: nil).find_each do |record|
+          record.update_columns(webauthn_id: WebAuthn.generate_user_id)
+        end
+      end
+    end
+
+    add_index :<%= owner_table %>, :webauthn_id, unique: true
+
+    create_table :passkeyed_credentials do |t|
+      t.references :user, polymorphic: true, null: false
+      t.string :external_id, null: false
+      # COSE public keys are base64url-encoded; an RSA key (RS256/PS256, which
+      # webauthn-ruby advertises by default) exceeds varchar(255) on MySQL, so
+      # use a text column to avoid truncation.
+      t.text :public_key, null: false
+      t.bigint :sign_count, null: false, default: 0
+      t.string :nickname
+      # Bumped on every successful assertion; handy for a "last used" column in a
+      # credential-management UI. Nil until the credential's first sign-in.
+      t.datetime :last_used_at
+      # Authenticator metadata captured at registration, for a management UI:
+      # backup_eligible/backed_up distinguish a synced passkey (iCloud Keychain,
+      # Google Password Manager) from a device-bound one; transports (JSON array,
+      # e.g. ["internal","hybrid"]) and aaguid (the authenticator model's UUID,
+      # nil when zeroed) hint at what kind of device holds the key. backed_up is
+      # refreshed on each sign-in — the flag may flip when a key later syncs.
+      t.boolean :backup_eligible
+      t.boolean :backed_up
+      t.string :transports
+      t.string :aaguid
+
+      t.timestamps
+    end
+
+    # Credential ids from real authenticators fit comfortably in a string + unique
+    # index. The WebAuthn spec permits ids up to 1023 bytes; if you must support
+    # such authenticators on MySQL, index a digest of external_id instead.
+    add_index :passkeyed_credentials, :external_id, unique: true
+  end
+end

data/lib/generators/passkeyed/install/templates/initializer.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# Passkeyed configuration. See https://github.com/pardel/passkeyed.
+Passkeyed.configure do |config|
+  # Shown by some authenticators during a ceremony.
+  config.rp_name = Rails.application.class.module_parent_name
+
+  # Your domain. Leave commented to derive it from the request origin in
+  # development; set it explicitly in production (e.g. "example.com").
+  # config.rp_id = "example.com"
+
+  # Origins the server will accept assertions from. Required (and must be
+  # https) in any environment other than development and test.
+  config.allowed_origins = ["http://localhost:3000"]
+
+  # "required" makes a single passkey gesture genuinely multi-factor.
+  config.user_verification = "required"
+
+  # How long (in seconds) an issued challenge may sit unsigned before the
+  # ceremony must be restarted. The default suits almost everyone.
+  # config.challenge_timeout = 300
+end
+
+# The ActiveRecord base class Passkeyed::Credential inherits from. Defaults to
+# ApplicationRecord when defined. Set this ONLY if you need a different base
+# (e.g. a secondary database), and set it *here*, before anything references
+# Passkeyed::Credential: the parent class is resolved once, when that constant
+# is first loaded, so a later assignment is ignored.
+#
+# Passkeyed.base_record_class = "SecondaryRecord"