unmagic-passkeys 0.1.0

data/lib/generators/unmagic/passkeys/install_generator.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Unmagic
+  module Passkeys
+    module Generators
+      # Installs unmagic-passkeys into a host app: copies the credentials migration
+      # (matching the host's primary-key type), imports the JavaScript, and prints the
+      # remaining controller/route/view wiring to do.
+      class InstallGenerator < Rails::Generators::Base
+        include ActiveRecord::Generators::Migration
+
+        source_root File.expand_path("templates", __dir__)
+
+        desc "Copies the unmagic_passkeys_credentials migration and wires the JavaScript."
+
+        def create_migration_file
+          migration_template "create_unmagic_passkeys_credentials.rb.tt",
+            "db/migrate/create_unmagic_passkeys_credentials.rb"
+        end
+
+        def import_javascript
+          application_js = "app/javascript/application.js"
+
+          if File.exist?(File.join(destination_root, application_js))
+            append_to_file application_js, %(import "unmagic/passkeys"\n)
+          end
+        end
+
+        def show_post_install
+          readme "POST_INSTALL" if behavior == :invoke
+        end
+
+        private
+          def key_type
+            Rails.configuration.generators.options.dig(:active_record, :primary_key_type)
+          end
+
+          def table_id_option
+            ", id: :#{key_type}" if key_type
+          end
+
+          def holder_id_type
+            key_type || :bigint
+          end
+      end
+    end
+  end
+end

data/lib/generators/unmagic/passkeys/templates/POST_INSTALL

@@ -0,0 +1,19 @@
+
+  unmagic-passkeys installed.
+
+  Next:
+
+  1. Run the migration:
+       bin/rails db:migrate
+
+  2. Add passkeys to your holder model:
+       class User < ApplicationRecord
+         has_passkeys name: :email_address, display_name: :name
+       end
+
+  3. Wire up sign-in and registration controllers, routes and views.
+     See the README "Host wiring" section for copy-paste examples.
+
+  The challenge endpoint (POST /unmagic/passkeys/challenge) and the JavaScript
+  web components are already available.
+

data/lib/generators/unmagic/passkeys/templates/create_unmagic_passkeys_credentials.rb.tt

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+class CreateUnmagicPasskeysCredentials < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :unmagic_passkeys_credentials<%= table_id_option %> do |t|
+      t.references :holder, polymorphic: true, null: false, type: <%= holder_id_type.to_sym.inspect %>
+      t.string  :credential_id, null: false
+      t.binary  :public_key, null: false
+      t.integer :sign_count, null: false, default: 0
+      t.string  :name
+      t.text    :transports
+      t.string  :aaguid
+      t.boolean :backed_up
+      t.timestamps
+
+      t.index :credential_id, unique: true
+    end
+  end
+end

data/lib/unmagic/passkeys/engine.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Passkeys
+    # Integrates the WebAuthn and passkey subsystems into a host Rails app. We deliberately do
+    # NOT isolate_namespace: passkeys is an injected concern — +has_passkeys+ goes onto the host's
+    # models, the form helpers into its views, and a stateless challenge endpoint into its routes.
+    #
+    # == Configuration
+    #
+    #   # config/initializers/passkeys.rb
+    #   config.unmagic_passkeys.web_authn.default_creation_options = { attestation: :none }
+    #   config.unmagic_passkeys.web_authn.default_request_options  = { user_verification: :required }
+    #   config.unmagic_passkeys.routes_prefix = "/unmagic/passkeys"
+    class Engine < ::Rails::Engine
+      config.unmagic_passkeys = ActiveSupport::OrderedOptions.new
+      config.unmagic_passkeys.parent_class_name = "ApplicationRecord"
+      config.unmagic_passkeys.routes_prefix = "/unmagic/passkeys"
+      config.unmagic_passkeys.draw_routes = true
+      config.unmagic_passkeys.challenge_url = nil
+
+      config.unmagic_passkeys.web_authn = ActiveSupport::OrderedOptions.new
+      config.unmagic_passkeys.web_authn.default_request_options = {}
+      config.unmagic_passkeys.web_authn.default_creation_options = {}
+      config.unmagic_passkeys.web_authn.creation_challenge_expiration = 10.minutes
+      config.unmagic_passkeys.web_authn.request_challenge_expiration = 5.minutes
+
+      initializer "unmagic_passkeys.routes" do |app|
+        passkey_config = config.unmagic_passkeys
+
+        app.routes.prepend do
+          if passkey_config.draw_routes
+            scope passkey_config.routes_prefix, as: :passkey do
+              post "/challenge" => "unmagic/passkeys/challenges#create", as: :challenge
+            end
+          end
+        end
+      end
+
+      initializer "unmagic_passkeys.holder" do
+        ActiveSupport.on_load(:active_record) do
+          # Shim: Holder references the Credential model (itself Active Record), so it can't be
+          # mixed in until Active Record is ready. The first call swaps in the real macro.
+          def self.has_passkeys(**options, &block)
+            include Unmagic::Passkeys::Holder
+            has_passkeys(**options, &block)
+          end
+        end
+      end
+
+      initializer "unmagic_passkeys.form_helper" do
+        ActiveSupport.on_load(:action_view) do
+          require "unmagic/passkeys/form_helper"
+          include Unmagic::Passkeys::FormHelper
+        end
+      end
+
+      initializer "unmagic_passkeys.request" do
+        ActiveSupport.on_load(:action_controller) do
+          require "unmagic/passkeys/request"
+        end
+      end
+
+      initializer "unmagic_passkeys.assets" do |app|
+        if app.config.respond_to?(:assets)
+          app.config.assets.paths << root.join("app/assets/javascripts").to_s
+        end
+      end
+
+      initializer "unmagic_passkeys.importmap", before: "importmap" do |app|
+        if app.config.respond_to?(:importmap)
+          app.config.importmap.paths << root.join("config/importmap.rb")
+          app.config.importmap.cache_sweepers << root.join("app/assets/javascripts")
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/passkeys/form_helper.rb

@@ -0,0 +1,128 @@
+# View helpers for rendering passkey registration and sign-in buttons.
+module Unmagic::Passkeys::FormHelper
+  REGISTRATION_ERROR_MESSAGE = "Something went wrong while registering your passkey."
+  REGISTRATION_CANCELLED_MESSAGE = "Passkey registration was cancelled. Try again when you are ready."
+  REGISTRATION_DUPLICATE_MESSAGE = "You already have a passkey registered on this device. Remove the existing one first and try again."
+  SIGN_IN_ERROR_MESSAGE = "Something went wrong while signing in with your passkey."
+  SIGN_IN_CANCELLED_MESSAGE = "Passkey sign in was cancelled. Try again when you are ready."
+
+  # Renders a button for registering a new passkey. Accepts a +label+ string or a block
+  # for button content.
+  #
+  # Options:
+  # - +options+: WebAuthn creation options (JSON-serializable hash)
+  # - +challenge_url+: endpoint to refresh the challenge nonce
+  # - +wrapper+: HTML attributes for the outer web component element
+  # - +form+: additional HTML attributes for the +<form>+ tag. Supports a +:param+ key
+  #   to set the form parameter namespace (default: +:passkey+)
+  # - +error+: HTML attributes for the error message +<div>+. Supports a +:message+ key
+  #   to override the default error text
+  # - +cancellation+: HTML attributes for the cancellation message +<div>+. Supports a
+  #   +:message+ key to override the default cancellation text
+  # - All other options are passed to the +<button>+ tag
+  def passkey_registration_button(name = nil, url = nil, **options, &block)
+    url, name = name, block ? capture(&block) : nil if block_given?
+    component_options, form_options, button_options, error_options = partition_passkey_options(url, options)
+    error_options[:error][:message] ||= REGISTRATION_ERROR_MESSAGE
+    error_options[:cancellation][:message] ||= REGISTRATION_CANCELLED_MESSAGE
+    error_options[:duplicate][:message] ||= REGISTRATION_DUPLICATE_MESSAGE
+    param = form_options.delete(:param)
+
+    content_tag("unmagic-passkey-registration-button", **component_options.transform_keys { |key| key.to_s.dasherize }) do
+      tag.form(**form_options) do
+        hidden_field_tag(:authenticity_token, form_authenticity_token) +
+          hidden_field_tag("#{param}[client_data_json]", nil, id: nil, data: { passkey_field: "client_data_json" }) +
+          hidden_field_tag("#{param}[attestation_object]", nil, id: nil, data: { passkey_field: "attestation_object" }) +
+          hidden_field_tag("#{param}[transports][]", nil, id: nil, data: { passkey_field: "transports" }) +
+          tag.button(name, type: :button, data: { passkey: "register" }, **button_options)
+      end + passkey_error_messages(**error_options)
+    end
+  end
+
+  # Renders a button for signing in with a passkey. Accepts a +label+ string or a block
+  # for button content.
+  #
+  # Options:
+  # - +options+: WebAuthn request options (JSON-serializable hash)
+  # - +challenge_url+: endpoint to refresh the challenge nonce
+  # - +mediation+: WebAuthn mediation hint (e.g. +"conditional"+ for autofill-assisted sign in)
+  # - +wrapper+: HTML attributes for the outer web component element
+  # - +form+: additional HTML attributes for the +<form>+ tag. Supports a +:param+ key
+  #   to set the form parameter namespace (default: +:passkey+)
+  # - +error+: HTML attributes for the error message +<div>+. Supports a +:message+ key
+  #   to override the default error text
+  # - +cancellation+: HTML attributes for the cancellation message +<div>+. Supports a
+  #   +:message+ key to override the default cancellation text
+  # - All other options are passed to the +<button>+ tag
+  def passkey_sign_in_button(name = nil, url = nil, **options, &block)
+    url, name = name, block ? capture(&block) : nil if block_given?
+    component_options, form_options, button_options, error_options = partition_passkey_options(url, options)
+    error_options[:error][:message] ||= SIGN_IN_ERROR_MESSAGE
+    error_options[:cancellation][:message] ||= SIGN_IN_CANCELLED_MESSAGE
+    param = form_options.delete(:param)
+
+    content_tag("unmagic-passkey-sign-in-button", **component_options.transform_keys { |key| key.to_s.dasherize }) do
+      tag.form(**form_options) do
+        hidden_field_tag(:authenticity_token, form_authenticity_token) +
+          hidden_field_tag("#{param}[id]", nil, id: nil, data: { passkey_field: "id" }) +
+          hidden_field_tag("#{param}[client_data_json]", nil, id: nil, data: { passkey_field: "client_data_json" }) +
+          hidden_field_tag("#{param}[authenticator_data]", nil, id: nil, data: { passkey_field: "authenticator_data" }) +
+          hidden_field_tag("#{param}[signature]", nil, id: nil, data: { passkey_field: "signature" }) +
+          tag.button(name, type: :button, data: { passkey: "sign_in" }, **button_options)
+      end + passkey_error_messages(**error_options)
+    end
+  end
+
+  private
+    def partition_passkey_options(url, options)
+      passkey_options = options.fetch(:options, {})
+      wrapper_options = options.fetch(:wrapper, {})
+
+      component_options = options
+        .slice(:challenge_url, :mediation)
+        .reverse_merge(challenge_url: default_passkey_challenge_url, options: passkey_options.to_json(except: :challenge))
+
+      form_options = options
+        .fetch(:form, {})
+        .reverse_merge(method: :post, action: url, class: "button_to", param: :passkey)
+
+      error_options = options.slice(:error, :cancellation, :duplicate).reverse_merge(error: {}, cancellation: {}, duplicate: {})
+
+      button_options = options.except(:options, :form, :wrapper, *component_options.keys, *error_options.keys)
+
+      [ wrapper_options.merge(component_options), form_options, button_options, error_options ]
+    end
+
+    def default_passkey_challenge_url
+      if challenge_url = Rails.configuration.unmagic_passkeys.challenge_url
+        instance_exec(&challenge_url)
+      else
+        passkey_challenge_path
+      end
+    end
+
+    def passkey_error_messages(error: {}, cancellation: {}, duplicate: {})
+      error_message, error_attributes = build_passkey_error_options("error", error)
+      cancellation_message, cancellation_attributes = build_passkey_error_options("cancelled", cancellation)
+
+      messages = tag.div(error_message, hidden: true, **error_attributes) +
+        tag.div(cancellation_message, hidden: true, **cancellation_attributes)
+
+      if duplicate[:message]
+        duplicate_message, duplicate_attributes = build_passkey_error_options("duplicate", duplicate)
+        messages += tag.div(duplicate_message, hidden: true, **duplicate_attributes)
+      end
+
+      messages
+    end
+
+    def build_passkey_error_options(type, options)
+      message = options[:message]
+
+      attributes = options.except(:message)
+      attributes[:data] ||= {}
+      attributes[:data][:passkey_error] = type
+
+      [ message, attributes ]
+    end
+end

data/lib/unmagic/passkeys/holder.rb

@@ -0,0 +1,143 @@
+# Adds passkey support to an Active Record model (the "holder" of passkeys).
+#
+# == Usage
+#
+#   class User < ApplicationRecord
+#     has_passkeys name: :email_address, display_name: :name
+#   end
+#
+# This sets up a polymorphic +has_many :passkeys+ association and defines two methods on the
+# model that supply holder-specific options for the WebAuthn ceremonies:
+#
+# - +passkey_registration_options+ — merged into Unmagic::Passkeys::Credential.registration_options
+# - +passkey_authentication_options+ — merged into Unmagic::Passkeys::Credential.authentication_options
+#
+# == Options
+#
+# +has_passkeys+ accepts keyword arguments that map to WebAuthn creation or request option
+# fields. Values can be symbols (sent to the record), procs (evaluated in the record's context),
+# or plain values:
+#
+# [+name+]
+#   A human-readable account identifier (typically an email or username) shown by the
+#   authenticator when the user selects a passkey. Maps to the WebAuthn +user.name+ field.
+#
+# [+display_name+]
+#   A friendly label for the user (typically their full name) shown by the authenticator
+#   during passkey registration. Maps to the WebAuthn +user.displayName+ field.
+#
+#   has_passkeys name: :email, display_name: :name
+#
+# For more complex configuration, pass a block that receives a Unmagic::Passkeys::Holder::Config:
+#
+#   has_passkeys do |config|
+#     config.registration_options { { name: email, display_name: name } }
+#     config.authentication_options { { user_verification: "required" } }
+#   end
+module Unmagic::Passkeys::Holder
+  extend ActiveSupport::Concern
+
+  class_methods do
+    # Declares that this model can hold passkeys. Sets up a polymorphic +has_many+ association
+    # and defines +passkey_registration_options+ and +passkey_authentication_options+ instance methods used
+    # by Unmagic::Passkeys::Credential to build ceremony options.
+    #
+    # Keyword arguments matching CreationOptions or RequestOptions fields are extracted and
+    # turned into holder-scoped option procs automatically. An optional block yields a Config
+    # for more complex setup.
+    def has_passkeys(**options, &block)
+      config = Config.new(**options)
+      block&.call(config)
+
+      has_many config.association_name,
+        as: :holder,
+        dependent: config.dependent,
+        class_name: "Unmagic::Passkeys::Credential"
+
+      define_method(:passkey_registration_options) do
+        {
+          id: id,
+          exclude_credentials: public_send(config.association_name)
+        }.merge(config.evaluate_registration_options(self))
+      end
+
+      define_method(:passkey_authentication_options) do
+        { credentials: public_send(config.association_name) }.merge(config.evaluate_authentication_options(self))
+      end
+    end
+  end
+
+  # Configuration object yielded by +has_passkeys+ when a block is given. Allows setting
+  # custom association options and ceremony option blocks.
+  class Config
+    attr_accessor :association_name, :dependent
+
+    def initialize(**options)
+      @association_name = options.delete(:association_name) || :passkeys
+      @dependent = options.delete(:dependent) || :destroy
+
+      if creation_opts = extract_options_for(Unmagic::Passkeys::WebAuthn::PublicKeyCredential::CreationOptions, options)
+        @registration_options = options_to_proc(creation_opts)
+      end
+
+      if request_opts = extract_options_for(Unmagic::Passkeys::WebAuthn::PublicKeyCredential::RequestOptions, options)
+        @authentication_options = options_to_proc(request_opts)
+      end
+    end
+
+    # Sets a block to evaluate in the holder's context to produce additional authentication options.
+    #
+    #   config.authentication_options { { user_verification: "required" } }
+    def authentication_options(&block)
+      @authentication_options = block
+    end
+
+    # Sets a block to evaluate in the holder's context to produce additional creation options.
+    #
+    #   config.registration_options { { name: email, display_name: name } }
+    def registration_options(&block)
+      @registration_options = block
+    end
+
+    # Evaluates the request options block (if any) in the context of the given +record+. Called
+    # internally by the +passkey_authentication_options+ method defined on the holder.
+    def evaluate_authentication_options(record)
+      if @authentication_options
+        record.instance_exec(&@authentication_options)
+      else
+        {}
+      end
+    end
+
+    # Evaluates the creation options block (if any) in the context of the given +record+. Called
+    # internally by the +passkey_registration_options+ method defined on the holder.
+    def evaluate_registration_options(record)
+      if @registration_options
+        record.instance_exec(&@registration_options)
+      else
+        {}
+      end
+    end
+
+    private
+      def extract_options_for(klass, options)
+        keys = klass.attribute_names.map(&:to_sym)
+
+        extracted = options.slice(*keys)
+        options.except!(*keys)
+        extracted if extracted.any?
+      end
+
+      def options_to_proc(options)
+        proc do
+          options.transform_values do |value|
+            case value
+            when Symbol then send(value)
+            when Proc then instance_exec(&value)
+            else value
+            end
+          end
+        end
+      end
+  end
+end

data/lib/unmagic/passkeys/request.rb

@@ -0,0 +1,77 @@
+# = Action Pack Passkey Request
+#
+# Controller concern that sets up the WebAuthn request context and provides
+# helper methods for passkey registration and authentication. Include this
+# in any controller that handles passkey form submissions.
+#
+# == Registration example
+#
+#   class PasskeysController < ApplicationController
+#     include Unmagic::Passkeys::Request
+#
+#     def new
+#       @registration_options = passkey_registration_options(holder: Current.user)
+#     end
+#
+#     def create
+#       @passkey = Unmagic::Passkeys::Credential.register(
+#         passkey_registration_params, holder: Current.user
+#       )
+#       redirect_to settings_path
+#     end
+#   end
+#
+# == Authentication example
+#
+#   class SessionsController < ApplicationController
+#     include Unmagic::Passkeys::Request
+#
+#     def new
+#       @authentication_options = passkey_authentication_options
+#     end
+#
+#     def create
+#       if passkey = Unmagic::Passkeys::Credential.authenticate(passkey_authentication_params)
+#         sign_in passkey.holder
+#         redirect_to root_path
+#       else
+#         redirect_to new_session_path, alert: "Authentication failed"
+#       end
+#     end
+#   end
+#
+# == Before Action
+#
+# Automatically populates +Unmagic::Passkeys::WebAuthn::Current+ with the request
+# host and origin.
+#
+module Unmagic::Passkeys::Request
+  extend ActiveSupport::Concern
+
+  included do
+    before_action do
+      Unmagic::Passkeys::WebAuthn::Current.host = request.host
+      Unmagic::Passkeys::WebAuthn::Current.origin = request.base_url
+    end
+  end
+
+  # Returns strong parameters for the passkey registration ceremony.
+  def passkey_registration_params(param: :passkey)
+    params.expect(param => [ :client_data_json, :attestation_object, transports: [] ])
+  end
+
+  # Returns strong parameters for the passkey authentication ceremony.
+  def passkey_authentication_params(param: :passkey)
+    params.expect(param => [ :id, :client_data_json, :authenticator_data, :signature ])
+  end
+
+  # Returns RequestOptions for the authentication ceremony.
+  def passkey_authentication_options(**options)
+    Unmagic::Passkeys::Credential.authentication_options(**options)
+  end
+
+  # Returns RegistrationOptions for the registration ceremony.
+  def passkey_registration_options(**options)
+    Unmagic::Passkeys::Credential.registration_options(**options)
+  end
+end

data/lib/unmagic/passkeys/version.rb

@@ -0,0 +1,5 @@
+module Unmagic
+  module Passkeys
+    VERSION = "0.1.0"
+  end
+end

data/lib/unmagic/passkeys/web_authn/authenticator/assertion_response.rb

@@ -0,0 +1,88 @@
+# = Action Pack WebAuthn Assertion Response
+#
+# Handles the authenticator response from a WebAuthn authentication ceremony.
+# When a user authenticates with an existing credential, the authenticator
+# returns an assertion response containing a signature that proves possession
+# of the private key.
+#
+# == Usage
+#
+#   # Look up the credential by ID
+#   credential = user.credentials.find_by!(
+#     credential_id: params[:id]
+#   )
+#
+#   response = Unmagic::Passkeys::WebAuthn::Authenticator::AssertionResponse.new(
+#     client_data_json: params[:response][:clientDataJSON],
+#     authenticator_data: params[:response][:authenticatorData],
+#     signature: params[:response][:signature],
+#     credential: credential.to_public_key_credential,
+#     origin: "https://example.com"
+#   )
+#
+#   response.validate!
+#
+# == Validation
+#
+# In addition to the base Response validations, this class verifies:
+#
+# * The client data type is "webauthn.get"
+# * The signature is valid for the credential's public key
+#
+class Unmagic::Passkeys::WebAuthn::Authenticator::AssertionResponse < Unmagic::Passkeys::WebAuthn::Authenticator::Response
+  attr_reader :credential, :authenticator_data, :signature
+
+  validate :client_data_type_must_be_get
+  validate :signature_must_be_valid
+  validate :sign_count_must_increase
+
+  def initialize(credential:, authenticator_data:, signature:, **attributes)
+    super(**attributes)
+    @credential = credential
+    @signature = signature
+    @signature = Base64.urlsafe_decode64(@signature) unless @signature.encoding == Encoding::BINARY
+    @authenticator_data = Unmagic::Passkeys::WebAuthn::Authenticator::Data.wrap(authenticator_data)
+  rescue ArgumentError
+    raise Unmagic::Passkeys::WebAuthn::InvalidResponseError, "Invalid base64 encoding in signature"
+  end
+
+  private
+    def challenge_purpose
+      "authentication"
+    end
+
+    def client_data_type_must_be_get
+      unless client_data["type"] == "webauthn.get"
+        errors.add(:base, "Client data type is not webauthn.get")
+      end
+    end
+
+    def signature_must_be_valid
+      client_data_hash = Digest::SHA256.digest(client_data_json)
+      signed_data = authenticator_data.bytes.pack("C*") + client_data_hash
+      digest = credential.public_key.oid == "ED25519" ? nil : "SHA256"
+
+      unless credential.public_key.verify(digest, signature, signed_data)
+        errors.add(:base, "Invalid signature")
+      end
+    rescue OpenSSL::PKey::PKeyError
+      errors.add(:base, "Invalid signature")
+    end
+
+    def sign_count_must_increase
+      unless sign_count_increased?
+        errors.add(:base, "Sign count did not increase")
+      end
+    end
+
+    def sign_count_increased?
+      if authenticator_data.sign_count.zero? && credential.sign_count.zero?
+        # Some authenticators always return 0 for the sign count, even after multiple authentications.
+        # In that case, we have to check that both the stored and returned sign counts are 0,
+        # which indicates that the authenticator is likely not updating the sign count.
+        true
+      else
+        authenticator_data.sign_count > credential.sign_count
+      end
+    end
+end

data/lib/unmagic/passkeys/web_authn/authenticator/attestation.rb

@@ -0,0 +1,73 @@
+# = Action Pack WebAuthn Attestation
+#
+# Decodes and represents the attestation object returned by an authenticator
+# during registration. The attestation object is CBOR-encoded and contains
+# the authenticator data along with an optional attestation statement.
+#
+# == Usage
+#
+#   attestation = Unmagic::Passkeys::WebAuthn::Authenticator::Attestation.decode(
+#     attestation_object_bytes
+#   )
+#
+#   attestation.credential_id  # => "abc123..."
+#   attestation.public_key     # => OpenSSL::PKey::EC
+#   attestation.sign_count     # => 0
+#
+# == Attributes
+#
+# [+authenticator_data+]
+#   The parsed Data containing credential information.
+#
+# [+format+]
+#   The attestation statement format (e.g., "none", "packed", "fido-u2f").
+#
+# [+attestation_statement+]
+#   The attestation statement, which may contain a signature from the
+#   authenticator manufacturer. Empty for "none" format.
+#
+# == Delegated Methods
+#
+# The following methods are delegated to +authenticator_data+:
+#
+# * +credential_id+ - Base64URL-encoded credential identifier
+# * +public_key+ - OpenSSL public key object
+# * +public_key_bytes+ - Raw COSE key bytes
+# * +sign_count+ - Signature counter for replay detection
+#
+class Unmagic::Passkeys::WebAuthn::Authenticator::Attestation
+  attr_reader :authenticator_data, :format, :attestation_statement
+
+  delegate :credential_id, :public_key, :public_key_bytes, :sign_count, :aaguid, :backed_up?, to: :authenticator_data
+
+  # Wraps raw attestation data into an Attestation instance. Accepts an
+  # existing Attestation object (returned as-is), a Base64URL-encoded string,
+  # or raw binary.
+  def self.wrap(data)
+    if data.is_a?(self)
+      data
+    else
+      data = Base64.urlsafe_decode64(data) unless data.encoding == Encoding::BINARY
+      decode(data)
+    end
+  rescue ArgumentError
+    raise Unmagic::Passkeys::WebAuthn::InvalidResponseError, "Invalid base64 encoding in attestation object"
+  end
+
+  # Decodes a CBOR-encoded attestation object into an Attestation instance.
+  def self.decode(bytes)
+    cbor = Unmagic::Passkeys::WebAuthn::CborDecoder.decode(bytes)
+
+    new(
+      authenticator_data: Unmagic::Passkeys::WebAuthn::Authenticator::Data.decode(cbor["authData"]),
+      format: cbor["fmt"],
+      attestation_statement: cbor["attStmt"]
+    )
+  end
+
+  def initialize(authenticator_data:, format:, attestation_statement:)
+    @authenticator_data = authenticator_data
+    @format = format
+    @attestation_statement = attestation_statement
+  end
+end