unmagic-passkeys 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 645c820a4995965db7ac6d5a146b1c26fa058670ee99159e6b69c2fc4d8c09b9
+  data.tar.gz: f91753169ab1fad8ef5c789319babb20ee59806b3bc0bb6a56fb43075070091c
+SHA512:
+  metadata.gz: 40df919dbc7b4c5e1496bcba443898bb332af4dbe62fe87624f105ce5aa91dd2dd2e9774196a5bebddb5b3713f333343daafd02f928d575dacda5561cef69134
+  data.tar.gz: e3be802090ee4736ba752d702972857224440a95b65b1c3654ab628e33d6e5667f5298d8301968ffb8e2f399a3aa7cfba89237d28b9ab44ccd29ab33e73e43dd

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## [Unreleased]
+
+### 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.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Keith Pitt
+
+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/NOTICE

@@ -0,0 +1,9 @@
+unmagic-passkeys
+
+The WebAuthn ceremony implementation (CBOR decoder, COSE key parsing,
+attestation/assertion handling, the passkey model, holder concern, form helpers
+and JavaScript web components) is derived from the in-progress `ActionPack::Passkey`
+work in the Rails / Basecamp codebases. It has been extracted, renamed under the
+`Unmagic::Passkeys` namespace, and packaged as a standalone Rails engine.
+
+Original authors retain credit for the underlying design and cryptography.

data/README.md

@@ -0,0 +1,151 @@
+# Unmagic::Passkeys
+
+Passkey (WebAuthn) authentication for Rails, backed by Active Record, with **no
+external dependencies**. The WebAuthn ceremonies — CBOR decoding, COSE key parsing,
+attestation and assertion verification — are implemented in pure Ruby on top of
+stdlib OpenSSL. Challenges are stateless (signed, expiring tokens), so there's no
+server-side challenge storage.
+
+## Provenance
+
+This gem is **extracted from the [`fizzy`](https://github.com/basecamp) codebase**,
+where the WebAuthn/passkey implementation lives vendored under `lib/action_pack/` as
+`ActionPack::Passkey` / `ActionPack::WebAuthn`. By the looks of it (the `ActionPack::`
+namespace, the railtie wiring, the omakase style) it's on its way to becoming a
+first-class **Rails** feature eventually.
+
+Until that lands and ships, this is the **extracted, standalone version** — the same
+code lifted out, renamed under `Unmagic::Passkeys`, and packaged as a self-contained
+Rails engine you can drop into an app today. If/when an official Rails passkeys API
+arrives, prefer it; this gem exists to bridge the gap in the meantime.
+
+See `NOTICE` for attribution.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "unmagic-passkeys"
+```
+
+```sh
+bin/rails generate unmagic:passkeys:install   # copies the migration, wires the JS
+bin/rails db:migrate
+```
+
+## Holder model
+
+Declare which model owns passkeys with `has_passkeys`. `name` is the account
+identifier shown by the authenticator; `display_name` is a friendly label.
+
+```ruby
+class User < ApplicationRecord
+  has_passkeys name: :email_address, display_name: :name
+end
+```
+
+This adds a polymorphic `has_many :passkeys` association and
+`passkey_registration_options` / `passkey_authentication_options`.
+
+## API
+
+```ruby
+# Registration ceremony
+options  = Unmagic::Passkeys.registration_options(holder: user)   # -> pass to navigator.credentials.create()
+passkey  = user.passkeys.register(params[:passkey])               # verifies attestation, persists
+
+# Authentication ceremony
+options  = Unmagic::Passkeys.authentication_options               # -> pass to navigator.credentials.get()
+passkey  = Unmagic::Passkeys.authenticate(params[:passkey])       # verified credential, or nil
+```
+
+The engine mounts a stateless challenge endpoint at `POST /unmagic/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:
+
+```js
+// app/javascript/application.js
+import "unmagic/passkeys"
+```
+
+**Sign in** (`app/views/sessions/new.html.erb`):
+
+```erb
+<%= passkey_sign_in_button "Sign in with a passkey", session_passkey_path,
+      options: @authentication_options, mediation: "conditional" %>
+```
+
+```ruby
+class Sessions::PasskeysController < ApplicationController
+  include Unmagic::Passkeys::Request
+
+  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
+  end
+end
+```
+
+**Register** (signed-in):
+
+```erb
+<%= passkey_registration_button "Register a passkey", passkeys_path,
+      options: @registration_options %>
+```
+
+```ruby
+class PasskeysController < ApplicationController
+  include Unmagic::Passkeys::Request   # sets the WebAuthn request context + param helpers
+
+  def index
+    @registration_options = passkey_registration_options(holder: Current.user)
+  end
+
+  def create
+    Current.user.passkeys.register(passkey_registration_params)
+    redirect_to passkeys_path, notice: "Passkey added."
+  end
+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.
+
+## Configuration
+
+```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"
+end
+```
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec    # specs (incl. a full register→authenticate round-trip)
+bundle exec rubocop
+```
+
+Supported algorithms: ES256 (P-256), EdDSA (Ed25519), RS256. Only the `none`
+attestation format is verified by default; register others with
+`Unmagic::Passkeys::WebAuthn.register_attestation_verifier`.
+
+## License
+
+MIT — see `LICENSE`. Attribution in `NOTICE`.

data/app/assets/javascripts/unmagic/passkeys/passkey.js

@@ -0,0 +1,236 @@
+// Web components for the Unmagic::Passkeys Ruby helpers.
+//
+// <unmagic-passkey-registration-button> — wraps a registration ceremony form
+// <unmagic-passkey-sign-in-button>  — wraps an authentication ceremony form
+//
+// The Ruby form helpers render the component markup including the inner form,
+// hidden fields, button, and error messages. The components handle the WebAuthn
+// ceremony lifecycle (challenge refresh, credential creation/authentication,
+// form submission) and error state toggling.
+//
+// Custom events (all bubble):
+//   passkey:start   — ceremony begun
+//   passkey:success — credential obtained, form about to submit
+//   passkey:error   — ceremony failed; detail: { error, cancelled }
+//
+// Attributes (rendered by the Ruby form helpers):
+//   options       — JSON WebAuthn options (creation or request, on both)
+//   challenge-url — endpoint to refresh the challenge nonce (on both)
+//   mediation     — WebAuthn mediation hint, e.g. "conditional" (on rails-passkey-sign-in-button)
+
+import { register, authenticate } from "unmagic/passkeys/webauthn"
+
+// Base class for passkey web components. Manages the shared ceremony lifecycle:
+// challenge refresh, button state, error display, and event dispatch.
+// Subclasses implement `perform()` to run the specific WebAuthn ceremony
+// and `fillForm()` to populate hidden fields before submission.
+class PasskeyButton extends HTMLElement {
+  connectedCallback() {
+    this.button.addEventListener("click", this.#perform)
+  }
+
+  disconnectedCallback() {
+    this.abortConditionalMediation?.()
+    this.button.removeEventListener("click", this.#perform)
+    this.button.disabled = false
+    this.#hideErrors()
+  }
+
+  get button() {
+    return this.querySelector("[data-passkey]")
+  }
+
+  get form() {
+    return this.querySelector("form")
+  }
+
+  get options() {
+    return JSON.parse(this.getAttribute("options"))
+  }
+
+  get challengeUrl() {
+    return this.getAttribute("challenge-url")
+  }
+
+  // Arrow function to preserve `this` binding for addEventListener/removeEventListener.
+  #perform = async () => {
+    await this.abortConditionalMediation?.()
+    this.button.disabled = true
+    this.#hideErrors()
+    this.button.dispatchEvent(new CustomEvent("passkey:start", { bubbles: true }))
+
+    try {
+      const options = this.options
+
+      if (!passkeysAvailable()) throw new Error("Passkeys are not supported by this browser")
+      if (!options) throw new Error("Missing passkey options")
+
+      await refreshChallenge(options, this.challengeUrl, this.purpose)
+      const passkey = await this.perform(options)
+
+      this.button.dispatchEvent(new CustomEvent("passkey:success", { bubbles: true }))
+      this.fillForm(passkey)
+      this.form.submit()
+    } catch (error) {
+      this.button.disabled = false
+      this.#handleError(error)
+    }
+  }
+
+  #handleError(error) {
+    console.error("Passkey ceremony failed", error)
+    const type = errorType(error)
+    this.#showError(type)
+    this.button.dispatchEvent(new CustomEvent("passkey:error", { bubbles: true, detail: { error, type } }))
+  }
+
+  #showError(type) {
+    const el = this.querySelector(`[data-passkey-error="${type}"]`)
+    if (el) el.hidden = false
+  }
+
+  #hideErrors() {
+    for (const el of this.querySelectorAll("[data-passkey-error]")) el.hidden = true
+  }
+}
+
+class PasskeyRegistrationButton extends PasskeyButton {
+  get purpose() { return "registration" }
+
+  async perform(options) {
+    return await register(options)
+  }
+
+  fillForm(passkey) {
+    fillRegistrationForm(this.form, passkey)
+  }
+}
+
+class PasskeySignInButton extends PasskeyButton {
+  #conditionalMediationController = null
+  #conditionalMediationPromise = null
+
+  get purpose() { return "authentication" }
+
+  connectedCallback() {
+    super.connectedCallback()
+    if (this.mediation === "conditional") this.#attemptConditionalMediation()
+  }
+
+  get mediation() {
+    return this.getAttribute("mediation")
+  }
+
+  async perform(options, { signal, mediation } = {}) {
+    return await authenticate(options, { signal, mediation })
+  }
+
+  fillForm(passkey) {
+    fillSignInForm(this.form, passkey)
+  }
+
+  async abortConditionalMediation() {
+    if (this.#conditionalMediationController) {
+      this.#conditionalMediationController.abort()
+      await this.#conditionalMediationPromise
+    }
+  }
+
+  async #attemptConditionalMediation() {
+    if (await this.#conditionalMediationAvailable()) {
+      const options = this.options
+
+      this.form.dispatchEvent(new CustomEvent("passkey:start", { bubbles: true }))
+
+      this.#conditionalMediationController = new AbortController()
+      this.#conditionalMediationPromise = this.#runConditionalMediation(options)
+    }
+  }
+
+  async #runConditionalMediation(options) {
+    try {
+      await refreshChallenge(options, this.challengeUrl, this.purpose)
+      const passkey = await this.perform(options, { signal: this.#conditionalMediationController.signal, mediation: this.mediation })
+
+      this.form.dispatchEvent(new CustomEvent("passkey:success", { bubbles: true }))
+      this.fillForm(passkey)
+      this.form.submit()
+    } catch (error) {
+      if (error.name === "AbortError") return
+
+      console.error("Passkey conditional mediation failed", error)
+      const type = errorType(error)
+      this.button.dispatchEvent(new CustomEvent("passkey:error", { bubbles: true, detail: { error, type } }))
+    } finally {
+      this.#conditionalMediationController = null
+      this.#conditionalMediationPromise = null
+    }
+  }
+
+  async #conditionalMediationAvailable() {
+    return this.options &&
+           passkeysAvailable() &&
+           await window.PublicKeyCredential.isConditionalMediationAvailable?.()
+  }
+}
+
+customElements.define("unmagic-passkey-registration-button", PasskeyRegistrationButton)
+customElements.define("unmagic-passkey-sign-in-button", PasskeySignInButton)
+
+// -- Shared helpers ----------------------------------------------------------
+
+function errorType(error) {
+  switch (error.name) {
+    case "AbortError":
+    case "NotAllowedError": return "cancelled"
+    case "InvalidStateError": return "duplicate"
+    default: return "error"
+  }
+}
+
+function passkeysAvailable() {
+  return !!window.PublicKeyCredential
+}
+
+async function refreshChallenge(options, challengeUrl, purpose) {
+  if (!challengeUrl) throw new Error("Missing passkey challenge URL")
+  const token = document.querySelector('meta[name="csrf-token"]')?.content
+
+  const body = new URLSearchParams()
+  if (purpose) body.append("purpose", purpose)
+
+  const response = await fetch(challengeUrl, {
+    method: "POST",
+    credentials: "same-origin",
+    headers: {
+      "X-CSRF-Token": token,
+      "Accept": "application/json"
+    },
+    body
+  })
+
+  if (!response.ok) throw new Error("Failed to refresh challenge")
+
+  const { challenge } = await response.json()
+  options.challenge = challenge
+}
+
+function fillRegistrationForm(form, passkey) {
+  form.querySelector('[data-passkey-field="client_data_json"]').value = passkey.client_data_json
+  form.querySelector('[data-passkey-field="attestation_object"]').value = passkey.attestation_object
+
+  const template = form.querySelector('[data-passkey-field="transports"]')
+  for (const transport of passkey.transports) {
+    const input = template.cloneNode()
+    input.value = transport
+    template.before(input)
+  }
+  template.remove()
+}
+
+function fillSignInForm(form, passkey) {
+  form.querySelector('[data-passkey-field="id"]').value = passkey.id
+  form.querySelector('[data-passkey-field="client_data_json"]').value = passkey.client_data_json
+  form.querySelector('[data-passkey-field="authenticator_data"]').value = passkey.authenticator_data
+  form.querySelector('[data-passkey-field="signature"]').value = passkey.signature
+}

data/app/assets/javascripts/unmagic/passkeys/webauthn.js

@@ -0,0 +1,83 @@
+// Thin wrapper around the browser WebAuthn API (navigator.credentials).
+//
+// Handles the base64url ↔ ArrayBuffer conversions required by the spec so
+// callers can work with plain JSON objects from the server-rendered meta tags.
+
+// Call navigator.credentials.create() with the given creation options.
+// Returns { client_data_json, attestation_object, transports } with all
+// binary fields encoded as base64url strings ready for form submission.
+export async function register(options) {
+  const publicKey = prepareCreationOptions(options)
+  const credential = await navigator.credentials.create({ publicKey })
+
+  return {
+    client_data_json: new TextDecoder().decode(credential.response.clientDataJSON),
+    attestation_object: bufferToBase64url(credential.response.attestationObject),
+    transports: credential.response.getTransports?.() || []
+  }
+}
+
+// Call navigator.credentials.get() with the given request options.
+// Accepts an optional signal (AbortSignal) and mediation hint ("conditional"
+// for autofill UI). Returns { id, client_data_json, authenticator_data, signature }
+// with binary fields encoded as base64url strings.
+export async function authenticate(options, { signal, mediation } = {}) {
+  const publicKey = prepareRequestOptions(options)
+  const credential = await navigator.credentials.get({ publicKey, signal, mediation })
+
+  return {
+    id: credential.id,
+    client_data_json: new TextDecoder().decode(credential.response.clientDataJSON),
+    authenticator_data: bufferToBase64url(credential.response.authenticatorData),
+    signature: bufferToBase64url(credential.response.signature)
+  }
+}
+
+// Convert JSON creation options into the format expected by the browser:
+// decode base64url challenge, user.id, and excludeCredentials[].id into ArrayBuffers.
+function prepareCreationOptions(options) {
+  return {
+    ...options,
+    challenge: base64urlToBuffer(options.challenge),
+    user: { ...options.user, id: base64urlToBuffer(options.user.id) },
+    excludeCredentials: (options.excludeCredentials || []).map(cred => ({
+      ...cred,
+      id: base64urlToBuffer(cred.id)
+    }))
+  }
+}
+
+// Convert JSON request options into the format expected by the browser:
+// decode base64url challenge and allowCredentials[].id into ArrayBuffers.
+// Strips allowCredentials entirely when empty so the browser prompts for
+// any available credential (required for conditional mediation).
+function prepareRequestOptions(options) {
+  const prepared = {
+    ...options,
+    challenge: base64urlToBuffer(options.challenge)
+  }
+
+  if (options.allowCredentials?.length) {
+    prepared.allowCredentials = options.allowCredentials.map(cred => ({
+      ...cred,
+      id: base64urlToBuffer(cred.id)
+    }))
+  } else {
+    delete prepared.allowCredentials
+  }
+
+  return prepared
+}
+
+function base64urlToBuffer(base64url) {
+  const base64 = base64url.replace(/-/g, "+").replace(/_/g, "/")
+  const padding = "=".repeat((4 - base64.length % 4) % 4)
+  const binary = atob(base64 + padding)
+  return Uint8Array.from(binary, c => c.charCodeAt(0)).buffer
+}
+
+function bufferToBase64url(buffer) {
+  const bytes = new Uint8Array(buffer)
+  const binary = String.fromCharCode(...bytes)
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "")
+}

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

@@ -0,0 +1,49 @@
+# = Action Pack Passkey Challenges Controller
+#
+# Generates fresh WebAuthn challenges for passkey ceremonies. The companion
+# JavaScript calls this endpoint before initiating a registration or
+# authentication ceremony so that the challenge is issued just-in-time rather
+# than embedded in the initial page load.
+#
+# The generated challenge is returned in the JSON response body. The challenge
+# is a signed, expiring token that the server can verify on the subsequent
+# form submission without needing server-side state — the challenge is
+# extracted from the authenticator's +clientDataJSON+ response.
+#
+# == Route
+#
+# By default mounted at +/rails/action_pack/passkey/challenge+ (configurable
+# via +config.unmagic_passkeys.routes_prefix+).
+#
+class Unmagic::Passkeys::ChallengesController < ActionController::Base
+  include Unmagic::Passkeys::Request
+
+  # Generates a fresh challenge and returns it as JSON. Accepts an optional
+  # +purpose+ parameter ("registration" or "authentication") to select the
+  # appropriate challenge expiration. Defaults to "authentication".
+  def create
+    render json: { challenge: create_passkey_challenge }
+  end
+
+  private
+    def create_passkey_challenge
+      Unmagic::Passkeys::WebAuthn::PublicKeyCredential::Options.new(
+        challenge_expiration: challenge_expiration,
+        challenge_purpose: challenge_purpose
+      ).challenge
+    end
+
+    def challenge_purpose
+      params[:purpose] == "registration" ? "registration" : "authentication"
+    end
+
+    def challenge_expiration
+      config = Rails.configuration.unmagic_passkeys.web_authn
+
+      if challenge_purpose == "registration"
+        config.creation_challenge_expiration
+      else
+        config.request_challenge_expiration
+      end
+    end
+end

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

@@ -0,0 +1,103 @@
+# Unmagic::Passkeys::Credential provides WebAuthn passkey registration and authentication backed by Active Record.
+#
+# Passkeys are scoped to a polymorphic +holder+ (typically a User or Identity) and store the
+# credential ID, public key, sign count, and transport hints needed for the WebAuthn ceremonies.
+#
+# == Registration
+#
+# Generate options for the browser's +navigator.credentials.create()+ call, then register the
+# response:
+#
+#   options = Unmagic::Passkeys::Credential.registration_options(holder: current_user)
+#   # Pass options to the browser
+#
+#   passkey = Unmagic::Passkeys::Credential.register(params[:passkey], holder: current_user)
+#
+# == Authentication
+#
+# Generate options for the browser's +navigator.credentials.get()+ call, then authenticate the
+# response:
+#
+#   options = Unmagic::Passkeys::Credential.authentication_options
+#   # Pass options to the browser
+#
+#   passkey = Unmagic::Passkeys::Credential.authenticate(params[:passkey])
+#
+# == Holder integration
+#
+# 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
+  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.
+    def registration_options(holder:, **options)
+      Unmagic::Passkeys::WebAuthn::PublicKeyCredential.creation_options(
+        **Rails.configuration.unmagic_passkeys.web_authn.default_creation_options.to_h,
+        **holder.passkey_registration_options.to_h,
+        **options
+      )
+    end
+
+    # Verifies the attestation response from the browser and persists a new passkey record.
+    # The +passkey+ hash should contain +client_data_json+, +attestation_object+, and +transports+
+    # as submitted by the registration form. The challenge is extracted from the authenticator's
+    # +clientDataJSON+ response and verified server-side. Any additional +attributes+ (e.g. +holder+)
+    # are passed through to +create!+.
+    #
+    # Raises Unmagic::Passkeys::WebAuthn::InvalidResponseError if the attestation is invalid.
+    def register(passkey, **attributes)
+      credential = Unmagic::Passkeys::WebAuthn::PublicKeyCredential.register(passkey)
+
+      create!(**credential.to_h, **attributes)
+    end
+
+    # Returns a RequestOptions object suitable for passing to the browser's
+    # +navigator.credentials.get()+ call. When a +holder+ is provided, their existing credentials
+    # are included so the browser can offer them for selection. Merges global defaults, holder
+    # 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,
+        **holder&.passkey_authentication_options.to_h,
+        **options
+      )
+    end
+
+    # Looks up a passkey by credential ID and verifies the assertion response from the browser.
+    # Returns the authenticated Passkey record, or +nil+ if the credential is not found or
+    # verification fails.
+    def authenticate(passkey)
+      find_by(credential_id: passkey[:id])&.authenticate(passkey)
+    end
+  end
+
+  # Verifies the assertion response against this passkey's stored credential and updates the
+  # +sign_count+ and +backed_up+ attributes. Returns +self+ on success, or +nil+ if the
+  # response is invalid.
+  def authenticate(passkey)
+    credential = to_public_key_credential
+    credential.authenticate(passkey)
+    update!(sign_count: credential.sign_count, backed_up: credential.backed_up)
+    self
+  rescue Unmagic::Passkeys::WebAuthn::InvalidResponseError
+    nil
+  end
+
+  # Returns an Unmagic::Passkeys::WebAuthn::PublicKeyCredential initialized from this record's stored
+  # credential data.
+  def to_public_key_credential
+    Unmagic::Passkeys::WebAuthn::PublicKeyCredential.new(
+      id: credential_id,
+      public_key: public_key,
+      sign_count: sign_count,
+      transports: transports
+    )
+  end
+end

data/config/importmap.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Pins merged into the host application's importmap by the engine.
+pin "unmagic/passkeys", to: "unmagic/passkeys/passkey.js"
+pin "unmagic/passkeys/webauthn", to: "unmagic/passkeys/webauthn.js"

data/config/routes.rb

@@ -0,0 +1,2 @@
+Unmagic::Passkeys::Engine.routes.draw do
+end