passkeyed 0.1.0

data/lib/passkeyed/credential.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Passkeyed
+  # A stored passkey: the public half of a WebAuthn credential, plus the
+  # signature counter used to spot cloned authenticators. The private key
+  # never reaches us, so there is nothing secret in this table.
+  #
+  # The owner is polymorphic (+user+) so any model can hold passkeys, not just
+  # one called User.
+  class Credential < Passkeyed.base_record_class
+    self.table_name = "passkeyed_credentials"
+
+    belongs_to :user, polymorphic: true, optional: false
+
+    # The WebAuthn credential id (base64url). Unique across the whole table:
+    # authentication looks a credential up by this alone.
+    validates :external_id, presence: true, uniqueness: true
+    validates :public_key, presence: true
+    validates :sign_count,
+              presence: true,
+              numericality: { only_integer: true, greater_than_or_equal_to: 0 }
+    # Optional user-supplied label. Cap it at the string column's width so a long
+    # value is rejected cleanly rather than silently truncated (e.g. on MySQL).
+    validates :nickname, length: { maximum: 255 }, allow_nil: true
+
+    # Persist the state a successful assertion produces: the advanced signature
+    # counter, and — when the columns are present — a last-used timestamp and
+    # the current backup state (a device-bound passkey may later start syncing,
+    # flipping the flag). The columns are guarded so authentication keeps
+    # working on apps that trimmed the optional columns from the migration.
+    def record_sign_in!(new_sign_count, backed_up: nil)
+      attributes = { sign_count: new_sign_count }
+      attributes[:last_used_at] = Time.current if has_attribute?(:last_used_at)
+      attributes[:backed_up] = backed_up if !backed_up.nil? && has_attribute?(:backed_up)
+      assign_attributes(attributes)
+      # Everything written here is server-derived, so skip validations: a record
+      # invalid by rules added after it was persisted (e.g. a nickname cap
+      # introduced in a future version) must not start failing every sign-in.
+      save!(validate: false)
+    end
+
+    # +transports+ is stored as a JSON string (portable across databases);
+    # expose it as the Array WebAuthn reported, e.g. ["internal", "hybrid"].
+    # Unparseable stored data (a manual write, a botched import) reads as nil
+    # rather than raising out of every page that lists credentials.
+    def transports
+      raw = super
+      raw.is_a?(String) ? JSON.parse(raw) : raw
+    rescue JSON::ParserError
+      nil
+    end
+
+    def transports=(value)
+      value = JSON.generate(value) unless value.nil? || value.is_a?(String)
+      super
+    end
+  end
+end

data/lib/passkeyed/errors.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Passkeyed
+  # Base class for every error raised by passkeyed. Rescue this to catch any
+  # ceremony failure in one place.
+  class Error < StandardError; end
+
+  # Raised when a registration (attestation) ceremony fails verification.
+  class RegistrationError < Error; end
+
+  # Raised when an authentication (assertion) ceremony fails verification.
+  class AuthenticationError < Error; end
+
+  # Raised during authentication when the asserted credential is not one we
+  # have on record.
+  class CredentialNotFound < AuthenticationError; end
+
+  # Raised when the server-issued challenge is absent from the session, which
+  # usually means the ceremony was started in a different session or the
+  # challenge was already consumed.
+  class ChallengeMissing < Error; end
+
+  # Raised when the stored challenge is older than the configured
+  # +challenge_timeout+. A challenge should be signed within moments of being
+  # issued; a stale one usually means a form left open for hours. Subclasses
+  # ChallengeMissing because the remedy is identical (restart the ceremony), so
+  # one rescue can handle both.
+  class ChallengeExpired < ChallengeMissing; end
+
+  # Raised at boot/use time when passkeyed is misconfigured or the host model
+  # is missing required schema (e.g. an invalid +user_verification+ value or a
+  # missing +webauthn_id+ column). Fails fast rather than degrading silently.
+  class ConfigurationError < Error; end
+end

data/lib/passkeyed/model.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Passkeyed
+  # Mix into the model that owns passkeys (typically your User):
+  #
+  #   class User < ApplicationRecord
+  #     include Passkeyed::Model
+  #   end
+  #
+  # It wires up the credentials association and assigns the random WebAuthn
+  # user handle (+webauthn_id+) on create. The host table needs a
+  # +webauthn_id:string+ column (the install generator adds it).
+  module Model
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :passkeyed_credentials,
+               class_name: "Passkeyed::Credential",
+               as: :user,
+               dependent: :destroy
+
+      before_create :assign_passkeyed_webauthn_id
+    end
+
+    # The name passed to the authenticator at registration time. Prefers an
+    # +email+, then a +name+, falling back to the opaque handle. Override in
+    # your model if you want something else shown.
+    def passkey_name
+      return email if respond_to?(:email) && email.present?
+      return name if respond_to?(:name) && name.present?
+
+      passkeyed_webauthn_id!
+    end
+
+    # The human-friendly display name (WebAuthn's user.displayName) shown by
+    # account pickers, distinct from +passkey_name+ (the account identifier).
+    # Defaults to +passkey_name+; override to show e.g. a full name next to an
+    # email.
+    def passkey_display_name
+      passkey_name
+    end
+
+    # Rename one of this owner's passkeys (e.g. from a credential-management UI).
+    # Looked up *through the association*, so an id belonging to another owner
+    # raises ActiveRecord::RecordNotFound rather than letting one user relabel
+    # another's credential. A blank nickname clears the label. Returns the
+    # credential.
+    def rename_passkey(credential_id, nickname)
+      credential = passkeyed_credentials.find(credential_id)
+      credential.update!(nickname: nickname.presence)
+      credential
+    end
+
+    # Revoke (delete) one of this owner's passkeys. Scoped through the
+    # association like +rename_passkey+. Returns the destroyed credential; raises
+    # ActiveRecord::RecordNotFound if the id isn't this owner's.
+    #
+    # This does not stop a user removing their last passkey — guard against that
+    # in your app if it would lock the account out.
+    def revoke_passkey(credential_id)
+      passkeyed_credentials.find(credential_id).destroy!
+    end
+
+    # Return this record's WebAuthn user handle, assigning one when absent.
+    # +before_create+ only covers rows created after the gem is installed, so a
+    # pre-existing user (or one whose backfill was missed) would otherwise reach
+    # the ceremony with a nil handle, which webauthn-ruby drops from the options
+    # JSON and the browser then rejects. Persists the handle when the record is
+    # already saved; assigns it in memory otherwise (the +before_create+ keeps
+    # it for an unsaved record). Raises if the +webauthn_id+ column is missing.
+    def passkeyed_webauthn_id!
+      ensure_webauthn_id_column!
+      return webauthn_id if webauthn_id.present?
+
+      handle = WebAuthn.generate_user_id
+      self.webauthn_id = handle
+      update_column(:webauthn_id, handle) if persisted?
+      handle
+    end
+
+    private
+
+    def assign_passkeyed_webauthn_id
+      ensure_webauthn_id_column!
+      self.webauthn_id ||= WebAuthn.generate_user_id
+    end
+
+    def ensure_webauthn_id_column!
+      return if self.class.column_names.include?("webauthn_id")
+
+      raise Passkeyed::ConfigurationError,
+            "#{self.class.name} has no webauthn_id column; run the passkeyed install migration " \
+            "(bin/rails generate passkeyed:install && bin/rails db:migrate)"
+    end
+  end
+end

data/lib/passkeyed/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Passkeyed
+  VERSION = "0.1.0"
+end

data/lib/passkeyed.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "webauthn"
+require "active_support"
+
+require "passkeyed/version"
+require "passkeyed/errors"
+require "passkeyed/configuration"
+
+# passkeyed adds passwordless, usernameless passkey (WebAuthn) authentication
+# to Rails apps as a small, transparent runtime plus an install generator.
+#
+# The heavier pieces (the ActiveRecord credential model and the two concerns)
+# are autoloaded so the gem can be required before ActiveRecord is ready.
+module Passkeyed
+  autoload :Credential, "passkeyed/credential"
+  autoload :Model, "passkeyed/model"
+  autoload :Ceremonies, "passkeyed/ceremonies"
+end

data/sig/passkeyed/ceremonies.rbs

@@ -0,0 +1,22 @@
+module Passkeyed
+  module Ceremonies
+    def passkey_registration_options: (untyped user) -> untyped
+    def passkey_register!: (untyped user, untyped credential, ?nickname: String?) -> untyped
+    def passkey_authentication_options: () -> untyped
+    def passkey_authenticate!: (untyped credential) -> untyped
+
+    private
+
+    def after_passkey_registration: (untyped credential) -> void
+    def after_passkey_authentication: (untyped credential, untyped user) -> void
+    def verify_registration: (untyped user, untyped credential, ?nickname: String?) -> untyped
+    def verify_authentication: (untyped credential) -> untyped
+    def passkeyed_session: () -> untyped
+    def stash_challenge: (Symbol key, String challenge) -> void
+    def consume_challenge: (Symbol key, String ceremony) -> String
+    def credential_metadata: (untyped webauthn_credential) -> Hash[Symbol, untyped]
+    def passkeyed_user_verification?: () -> bool
+    def parse_credential: (Symbol method, untyped credential, untyped error_class) -> untyped
+    def normalize_credential: (untyped credential) -> untyped
+  end
+end

data/sig/passkeyed/configuration.rbs

@@ -0,0 +1,31 @@
+module Passkeyed
+  class Configuration
+    USER_VERIFICATION_LEVELS: Array[String]
+
+    attr_accessor rp_name: String
+    attr_accessor rp_id: String?
+    attr_accessor allowed_origins: Array[String]?
+    attr_reader user_verification: String
+    attr_accessor session_key: Symbol
+    attr_reader challenge_timeout: Integer
+
+    def initialize: () -> void
+    def user_verification=: (untyped value) -> String
+    def challenge_timeout=: (untyped value) -> Integer
+    def registration_challenge_key: () -> Symbol
+    def authentication_challenge_key: () -> Symbol
+    # WebAuthn::RelyingParty (webauthn-ruby ships no RBS, so left untyped).
+    def relying_party: () -> untyped
+    def validate!: () -> void
+
+    private
+
+    def enforce_secure_origins?: () -> bool
+  end
+
+  def self.base_record_class: () -> untyped
+  def self.base_record_class=: (untyped) -> untyped
+  def self.configuration: () -> Configuration
+  def self.configure: () ?{ (Configuration) -> void } -> Configuration
+  def self.reset_configuration!: () -> Configuration
+end

data/sig/passkeyed/credential.rbs

@@ -0,0 +1,9 @@
+module Passkeyed
+  # Inherits Passkeyed.base_record_class (ApplicationRecord / ActiveRecord::Base)
+  # at load time; declared here against ActiveRecord::Base for typing.
+  class Credential < ActiveRecord::Base
+    def record_sign_in!: (Integer new_sign_count, ?backed_up: bool?) -> void
+    def transports: () -> Array[String]?
+    def transports=: (Array[String] | String | nil value) -> untyped
+  end
+end

data/sig/passkeyed/errors.rbs

@@ -0,0 +1,22 @@
+module Passkeyed
+  class Error < StandardError
+  end
+
+  class RegistrationError < Error
+  end
+
+  class AuthenticationError < Error
+  end
+
+  class CredentialNotFound < AuthenticationError
+  end
+
+  class ChallengeMissing < Error
+  end
+
+  class ChallengeExpired < ChallengeMissing
+  end
+
+  class ConfigurationError < Error
+  end
+end

data/sig/passkeyed/model.rbs

@@ -0,0 +1,16 @@
+module Passkeyed
+  module Model
+    extend ActiveSupport::Concern
+
+    def passkey_name: () -> String
+    def passkey_display_name: () -> String
+    def rename_passkey: (untyped credential_id, String? nickname) -> untyped
+    def revoke_passkey: (untyped credential_id) -> untyped
+    def passkeyed_webauthn_id!: () -> String
+
+    private
+
+    def assign_passkeyed_webauthn_id: () -> void
+    def ensure_webauthn_id_column!: () -> void
+  end
+end

data/sig/passkeyed/version.rbs

@@ -0,0 +1,3 @@
+module Passkeyed
+  VERSION: String
+end

metadata

@@ -0,0 +1,208 @@
+--- !ruby/object:Gem::Specification
+name: passkeyed
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Paul Ardeleanu
+bindir: bin
+cert_chain: []
+date: 2026-07-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: webauthn
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.4'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.60'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.60'
+- !ruby/object:Gem::Dependency
+  name: rubocop-minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.34'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.34'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.6'
+description: |-
+  passkeyed adds passwordless, usernameless passkey sign-in to Rails apps:
+  a small, transparent runtime (a model concern, a controller concern, and a
+  Stimulus controller) plus an install generator, built on webauthn-ruby.
+email:
+- pardel@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/generators/passkeyed/install/USAGE
+- lib/generators/passkeyed/install/install_generator.rb
+- lib/generators/passkeyed/install/templates/create_passkeyed_credentials.rb.erb
+- lib/generators/passkeyed/install/templates/initializer.rb
+- lib/generators/passkeyed/install/templates/passkey_controller.js
+- lib/passkeyed.rb
+- lib/passkeyed/ceremonies.rb
+- lib/passkeyed/configuration.rb
+- lib/passkeyed/credential.rb
+- lib/passkeyed/errors.rb
+- lib/passkeyed/model.rb
+- lib/passkeyed/version.rb
+- sig/passkeyed/ceremonies.rbs
+- sig/passkeyed/configuration.rbs
+- sig/passkeyed/credential.rbs
+- sig/passkeyed/errors.rbs
+- sig/passkeyed/model.rbs
+- sig/passkeyed/version.rbs
+homepage: https://github.com/pardel/passkeyed
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/pardel/passkeyed
+  source_code_uri: https://github.com/pardel/passkeyed
+  bug_tracker_uri: https://github.com/pardel/passkeyed/issues
+  documentation_uri: https://rubydoc.info/gems/passkeyed
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Passwordless passkey (WebAuthn) authentication for Rails.
+test_files: []