better_auth-passkey 0.1.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9d897b27289670fa9776d35b6f8d7e24232626b3079feaa9df4989bf1778d41
-  data.tar.gz: 42ca8da646e0db4a2c4ce0c7380a6bd657385470beddfa0a3e45f4d33179f578
+  metadata.gz: 509b37215dc04f3b6764922cb082261651d80b215d524b3af3fe03dffa1e046f
+  data.tar.gz: f5c58225f30016ced29b4f901d871ceac8c20c0620176961a6cf05880567935c
 SHA512:
-  metadata.gz: 653ff4209165b99511fda3f9bf433069b3ffd85915f88a014913ae9671e18abfcec1fd283a72d2014db6b9baca97441fb99ca658cb3f36b4548bb8294d22a201
-  data.tar.gz: 11af45bc047d37897caa689ef15d5dda7bd794b17c6c6a607c00e6d3b475a5f9907af6c941a7f4bb07ec5b6503587d8c1c3285dcdcc1071853f55167f248d21f
+  metadata.gz: d5b4b313d7962247d9af939d3f8edb37e649c5183f219362608c19bcd397cb236e1095700ef0d27f2338212f6a1ba83d0d05c75adbea090a0403f543264404fe
+  data.tar.gz: 1c4bb5d2f5ac3cfb1245d59103128a29fb2457242c66d709e7fe08df8f396081bd5cf99a4e8cb0327479c7a57db210f1aadd4d018e525cd86d49280cee96ceda

data/CHANGELOG.md

@@ -2,4 +2,11 @@
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-04-29
+
+- Aligned passkey registration, authentication, verification, origin handling, credential metadata, and route behavior with upstream Better Auth v1.6.9.
+- Expanded passkey documentation and test coverage for upstream server parity.
+
+## [0.1.0] - 2026-04-28
+
 - Initial external passkey package extracted from `better_auth`.

data/README.md

@@ -17,11 +17,109 @@ auth = BetterAuth.auth(
   secret: ENV.fetch("BETTER_AUTH_SECRET"),
   database: :memory,
   plugins: [
-    BetterAuth::Plugins.passkey
+    BetterAuth::Plugins.passkey(
+      rp_id: "localhost",
+      rp_name: "Example App",
+      origin: "http://localhost:3000"
+    )
   ]
 )
 ```
 
+## Options
+
+`BetterAuth::Plugins.passkey` accepts Ruby `snake_case` options:
+
+- `rp_id`: WebAuthn relying party ID. Defaults to the configured `base_url` host.
+- `rp_name`: WebAuthn relying party name. Defaults to the Better Auth app name.
+- `origin`: allowed WebAuthn origin or array of origins.
+- `authenticator_selection`: supports `resident_key`, `user_verification`, and `authenticator_attachment`.
+- `advanced.web_authn_challenge_cookie`: challenge cookie name. Defaults to `better-auth-passkey`.
+- `registration`: supports `require_session`, `resolve_user`, `after_verification`, and `extensions`.
+- `authentication`: supports `after_verification` and `extensions`.
+- `schema`: deep-merged schema overrides. The built-in SQL table remains `passkeys`, matching the Ruby adapter convention.
+
+HTTP routes and wire JSON keys are kept compatible with upstream Better Auth passkey server behavior. Ruby method names and configuration keys remain idiomatic `snake_case`.
+
+## Passkey-first registration
+
+Use `require_session: false` to register a passkey before a session exists:
+
+```ruby
+BetterAuth::Plugins.passkey(
+  registration: {
+    require_session: false,
+    resolve_user: lambda do |data|
+      invitation = Invitations.verify!(data.fetch(:context))
+      {
+        id: invitation.user_id,
+        name: invitation.email,
+        display_name: invitation.name,
+        email: invitation.email
+      }
+    end,
+    after_verification: lambda do |data|
+      Audit.passkey_registered!(
+        user_id: data.fetch(:user).fetch(:id),
+        context: data.fetch(:context)
+      )
+      nil
+    end
+  }
+)
+```
+
+Pass `context` when generating registration options:
+
+```ruby
+auth.api.generate_passkey_registration_options(query: { context: invitation_token })
+```
+
+During passkey-first registration, `after_verification` may return `{ user_id: "..." }` to attach the credential to a concrete user. During session-required registration, switching users is rejected.
+
+## Callback contracts
+
+Ruby uses hashes for the upstream TypeScript contracts:
+
+- Stored challenge value: `expectedChallenge`, `userData.id`, optional `userData.name`, optional `userData.displayName`, and optional `context`.
+- `resolve_user` receives `{ ctx:, context: }` and must return at least `id` and `name`; it may also return `display_name` and `email`.
+- Registration `after_verification` receives `{ ctx:, verification:, user:, client_data:, context: }`.
+- Authentication `after_verification` receives `{ ctx:, verification:, client_data: }`.
+- Passkey records use upstream wire keys including `userId`, `credentialID`, `publicKey`, `deviceType`, `backedUp`, `createdAt`, and optional `aaguid`.
+
+## WebAuthn extensions
+
+```ruby
+BetterAuth::Plugins.passkey(
+  registration: {
+    extensions: { credProps: true }
+  },
+  authentication: {
+    extensions: ->(_data) { { hmacGetSecret: true } }
+  }
+)
+```
+
+## Browser client scope
+
+This gem provides server WebAuthn routes. It does not ship the upstream browser-only `@better-auth/passkey/client` helper, `passkeyClient`, `startRegistration`, `startAuthentication`, conditional UI, autofill, or extension-result handling. Use the browser WebAuthn APIs directly or wrap them in application JavaScript.
+
+## WebAuthn configuration
+
+The plugin uses `WebAuthn::RelyingParty` per request for `rp_id`, `rp_name`, and allowed origins. It does not mutate global `WebAuthn.configuration`, so multiple Better Auth instances can use different relying-party settings in the same Ruby process.
+
+## Upstream parity notes
+
+The Ruby plugin tracks Better Auth `v1.6.9` upstream behavior. A few wire-shape and validation details are worth noting:
+
+- `excludeCredentials` entries (registration options) are emitted as `{id, transports?}` to match upstream's `@simplewebauthn/server` output. `allowCredentials` (authentication options) still includes `type: "public-key"` to mirror upstream's authentication wire shape.
+- `transports` is omitted entirely from credential descriptors when the stored value is missing or empty (rather than emitting an empty array).
+- The default storage table is named `passkeys` (plural) in the SQL adapters, mapped from the upstream `passkey` model. Custom SQL adapters that translate the `passkey` model name continue to work.
+- `rp_id` resolution falls back to `URI.parse(base_url).host` (port stripped). When `base_url` is empty or unparseable, `rp_id` defaults to `"localhost"`.
+- For passkey-first registration, the `after_verification` callback may return `{ user_id: nil }` or `{ user_id: "" }` to leave the resolved user unchanged. Returning any other non-empty-string value (integer, boolean, etc.) raises `RESOLVED_USER_INVALID`.
+- `update_passkey` accepts an empty-string `name` to match upstream `z.string()`. Missing or non-string `name` still raises `VALIDATION_ERROR`.
+- Cross-user `delete_passkey` raises `UNAUTHORIZED` with the `PASSKEY_NOT_FOUND` message, mirroring upstream's `requireResourceOwnership` middleware behavior when only `notFoundError` is configured.
+
 ## Notes
 
 This package depends on the maintained `webauthn` gem. Keeping passkeys outside `better_auth` avoids installing WebAuthn dependencies for applications that do not use passkeys.

data/lib/better_auth/passkey/challenges.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "json"
+
+module BetterAuth
+  module Passkey
+    module Challenges
+      CHALLENGE_MAX_AGE = 60 * 5
+
+      module_function
+
+      def store_challenge(ctx, config, challenge, user_id)
+        user_data = user_id.is_a?(Hash) ? user_id : {id: user_id}
+        verification_token = Crypto.random_string(32)
+        cookie = challenge_cookie(ctx, config)
+        ctx.set_signed_cookie(cookie.name, verification_token, ctx.context.secret, cookie.attributes.merge(max_age: CHALLENGE_MAX_AGE))
+        ctx.context.internal_adapter.create_verification_value(
+          identifier: verification_token,
+          value: JSON.generate({
+            expectedChallenge: challenge,
+            userData: user_data,
+            context: BetterAuth::Passkey::Utils.normalize_hash(ctx.query)[:context]
+          }),
+          expiresAt: Time.now + CHALLENGE_MAX_AGE
+        )
+      end
+
+      def find_challenge(ctx, verification_token)
+        verification = ctx.context.internal_adapter.find_verification_value(verification_token)
+        return nil if verification.nil? || BetterAuth::Routes.expired_time?(verification["expiresAt"] || verification[:expiresAt])
+
+        JSON.parse(verification.fetch("value") { verification.fetch(:value) })
+      rescue JSON::ParserError
+        nil
+      end
+
+      def challenge_token(ctx, config)
+        ctx.get_signed_cookie(challenge_cookie(ctx, config).name, ctx.context.secret)
+      end
+
+      def challenge_cookie(ctx, config)
+        ctx.context.create_auth_cookie(config.dig(:advanced, :web_authn_challenge_cookie), max_age: CHALLENGE_MAX_AGE)
+      end
+    end
+  end
+end

data/lib/better_auth/passkey/credentials.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Passkey
+    module Credentials
+      module_function
+
+      def webauthn_response(value)
+        data = BetterAuth::Passkey::Utils.normalize_hash(value || {})
+        response = BetterAuth::Passkey::Utils.normalize_hash(data[:response] || {})
+        webauthn = {
+          "type" => data[:type],
+          "id" => data[:id],
+          "rawId" => data[:raw_id],
+          "authenticatorAttachment" => data[:authenticator_attachment],
+          "clientExtensionResults" => data[:client_extension_results] || {},
+          "response" => {
+            "attestationObject" => response[:attestation_object],
+            "clientDataJSON" => response[:client_data_json],
+            "transports" => response[:transports],
+            "authenticatorData" => response[:authenticator_data],
+            "signature" => response[:signature],
+            "userHandle" => response[:user_handle]
+          }.compact
+        }.compact
+        webauthn["rawId"] ||= webauthn["id"]
+        webauthn
+      end
+
+      def attestation_response(credential)
+        credential.instance_variable_get(:@response)
+      end
+
+      def authenticator_data(credential)
+        attestation_response(credential)&.authenticator_data
+      end
+
+      def wire(record)
+        return record unless record.is_a?(Hash)
+
+        output = record.dup
+        output["credentialID"] = output.delete("credentialId") if output.key?("credentialId")
+        output
+      end
+
+      def credential_id(record)
+        record["credentialID"] || record["credentialId"] || record[:credentialID] || record[:credential_id]
+      end
+
+      def credential_descriptor(record, kind: :allow)
+        descriptor = {id: credential_id(record)}
+        descriptor[:type] = "public-key" if kind == :allow
+        transports = (record["transports"] || record[:transports]).to_s.split(",").map(&:strip).reject(&:empty?)
+        descriptor[:transports] = transports if transports.any?
+        descriptor
+      end
+    end
+  end
+end

data/lib/better_auth/passkey/error_codes.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Passkey
+    module ErrorCodes
+      PASSKEY_ERROR_CODES = {
+        "CHALLENGE_NOT_FOUND" => "Challenge not found",
+        "YOU_ARE_NOT_ALLOWED_TO_REGISTER_THIS_PASSKEY" => "You are not allowed to register this passkey",
+        "FAILED_TO_VERIFY_REGISTRATION" => "Failed to verify registration",
+        "PASSKEY_NOT_FOUND" => "Passkey not found",
+        "AUTHENTICATION_FAILED" => "Authentication failed",
+        "UNABLE_TO_CREATE_SESSION" => "Unable to create session",
+        "FAILED_TO_UPDATE_PASSKEY" => "Failed to update passkey",
+        "PREVIOUSLY_REGISTERED" => "Previously registered",
+        "REGISTRATION_CANCELLED" => "Registration cancelled",
+        "AUTH_CANCELLED" => "Auth cancelled",
+        "UNKNOWN_ERROR" => "Unknown error",
+        "SESSION_REQUIRED" => "Passkey registration requires an authenticated session",
+        "RESOLVE_USER_REQUIRED" => "Passkey registration requires either an authenticated session or a resolveUser callback when requireSession is false",
+        "RESOLVED_USER_INVALID" => "Resolved user is invalid"
+      }.freeze
+    end
+  end
+end

data/lib/better_auth/passkey/routes/authentication.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "base64"
+require "webauthn"
+
+module BetterAuth
+  module Passkey
+    module Routes
+      module Authentication
+        module_function
+
+        def generate_passkey_authentication_options_endpoint(config)
+          Endpoint.new(path: "/passkey/generate-authenticate-options", method: "GET") do |ctx|
+            session = BetterAuth::Routes.current_session(ctx, allow_nil: true)
+            relying_party = Utils.relying_party(config, ctx)
+            passkeys = if session
+              ctx.context.adapter.find_many(model: "passkey", where: [{field: "userId", value: session.fetch(:user).fetch("id")}])
+            else
+              []
+            end
+            get_options = {
+              extensions: Utils.resolve_extensions(config.dig(:authentication, :extensions), ctx),
+              relying_party: relying_party
+            }
+            get_options[:allow] = passkeys.map { |passkey| Credentials.credential_id(passkey) } if passkeys.any?
+            options = WebAuthn::Credential.options_for_get(**get_options)
+            Challenges.store_challenge(ctx, config, options.challenge, session ? session.fetch(:user).fetch("id") : "")
+            payload = options.as_json.merge(userVerification: "preferred")
+            payload.delete(:extensions) if payload[:extensions].nil? || payload[:extensions] == {}
+            payload.delete("extensions") if payload["extensions"].nil? || payload["extensions"] == {}
+            if passkeys.any?
+              payload[:allowCredentials] = passkeys.map { |passkey| Credentials.credential_descriptor(passkey) }
+            else
+              payload.delete(:allowCredentials)
+              payload.delete("allowCredentials")
+            end
+            ctx.json(payload)
+          end
+        end
+
+        def verify_passkey_authentication_endpoint(config)
+          Endpoint.new(path: "/passkey/verify-authentication", method: "POST") do |ctx|
+            body = Utils.normalize_hash(ctx.body)
+            Utils.require_key!(body, :response)
+            origin = Utils.origin(config, ctx)
+            raise APIError.new("BAD_REQUEST", message: "origin missing") if origin.to_s.empty?
+
+            verification_token = Challenges.challenge_token(ctx, config)
+            raise APIError.new("BAD_REQUEST", message: ErrorCodes::PASSKEY_ERROR_CODES.fetch("CHALLENGE_NOT_FOUND")) unless verification_token
+
+            challenge = Challenges.find_challenge(ctx, verification_token)
+            raise APIError.new("BAD_REQUEST", message: ErrorCodes::PASSKEY_ERROR_CODES.fetch("CHALLENGE_NOT_FOUND")) unless challenge
+
+            response = Credentials.webauthn_response(body[:response])
+            credential_id = response.fetch("id")
+            passkey = ctx.context.adapter.find_one(model: "passkey", where: [{field: "credentialID", value: credential_id}])
+            raise APIError.new("UNAUTHORIZED", message: ErrorCodes::PASSKEY_ERROR_CODES.fetch("PASSKEY_NOT_FOUND")) unless passkey
+
+            relying_party = Utils.relying_party(config, ctx, origin: origin)
+            credential = WebAuthn::Credential.from_get(response, relying_party: relying_party)
+            credential.verify(
+              challenge.fetch("expectedChallenge"),
+              public_key: Base64.strict_decode64(passkey.fetch("publicKey")),
+              sign_count: passkey.fetch("counter").to_i,
+              user_verification: false
+            )
+            Utils.call_callback(config.dig(:authentication, :after_verification), {
+              ctx: ctx,
+              verification: credential,
+              client_data: response
+            })
+            ctx.context.adapter.update(
+              model: "passkey",
+              where: [{field: "id", value: passkey.fetch("id")}],
+              update: {counter: credential.sign_count}
+            )
+            session = ctx.context.internal_adapter.create_session(passkey.fetch("userId"))
+            raise APIError.new("INTERNAL_SERVER_ERROR", message: ErrorCodes::PASSKEY_ERROR_CODES.fetch("UNABLE_TO_CREATE_SESSION")) unless session
+
+            user = ctx.context.internal_adapter.find_user_by_id(passkey.fetch("userId"))
+            raise APIError.new("INTERNAL_SERVER_ERROR", message: "User not found") unless user
+
+            Cookies.set_session_cookie(ctx, {session: session, user: user})
+            ctx.context.internal_adapter.delete_verification_by_identifier(verification_token)
+            ctx.json({session: session, user: user})
+          rescue WebAuthn::Error, ArgumentError => error
+            ctx.context.logger&.error("Failed to verify authentication", error)
+            raise APIError.new("BAD_REQUEST", message: ErrorCodes::PASSKEY_ERROR_CODES.fetch("AUTHENTICATION_FAILED"))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/better_auth/passkey/routes/management.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Passkey
+    module Routes
+      module Management
+        module_function
+
+        def list_passkeys_endpoint
+          Endpoint.new(path: "/passkey/list-user-passkeys", method: "GET") do |ctx|
+            session = BetterAuth::Routes.current_session(ctx)
+            passkeys = ctx.context.adapter.find_many(model: "passkey", where: [{field: "userId", value: session.fetch(:user).fetch("id")}])
+            ctx.json(passkeys.map { |passkey| Credentials.wire(passkey) })
+          end
+        end
+
+        def delete_passkey_endpoint
+          Endpoint.new(path: "/passkey/delete-passkey", method: "POST") do |ctx|
+            session = BetterAuth::Routes.current_session(ctx)
+            body = Utils.normalize_hash(ctx.body)
+            Utils.require_string!(body, :id)
+            passkey = ctx.context.adapter.find_one(model: "passkey", where: [{field: "id", value: body[:id]}])
+            raise APIError.new("NOT_FOUND", message: ErrorCodes::PASSKEY_ERROR_CODES.fetch("PASSKEY_NOT_FOUND")) unless passkey
+            unless passkey.fetch("userId") == session.fetch(:user).fetch("id")
+              raise APIError.new("UNAUTHORIZED", message: ErrorCodes::PASSKEY_ERROR_CODES.fetch("PASSKEY_NOT_FOUND"))
+            end
+
+            ctx.context.adapter.delete(model: "passkey", where: [{field: "id", value: passkey.fetch("id")}])
+            ctx.json({status: true})
+          end
+        end
+
+        def update_passkey_endpoint
+          Endpoint.new(path: "/passkey/update-passkey", method: "POST") do |ctx|
+            session = BetterAuth::Routes.current_session(ctx)
+            body = Utils.normalize_hash(ctx.body)
+            Utils.require_string!(body, :id)
+            unless body.key?(:name) && body[:name].is_a?(String)
+              raise APIError.new("BAD_REQUEST", message: BASE_ERROR_CODES.fetch("VALIDATION_ERROR"))
+            end
+
+            passkey = ctx.context.adapter.find_one(model: "passkey", where: [{field: "id", value: body[:id]}])
+            raise APIError.new("NOT_FOUND", message: ErrorCodes::PASSKEY_ERROR_CODES.fetch("PASSKEY_NOT_FOUND")) unless passkey
+            if passkey.fetch("userId") != session.fetch(:user).fetch("id")
+              raise APIError.new("UNAUTHORIZED", message: ErrorCodes::PASSKEY_ERROR_CODES.fetch("YOU_ARE_NOT_ALLOWED_TO_REGISTER_THIS_PASSKEY"))
+            end
+
+            updated = ctx.context.adapter.update(
+              model: "passkey",
+              where: [{field: "id", value: body[:id]}],
+              update: {name: body[:name].to_s}
+            )
+            raise APIError.new("INTERNAL_SERVER_ERROR", message: ErrorCodes::PASSKEY_ERROR_CODES.fetch("FAILED_TO_UPDATE_PASSKEY")) unless updated
+
+            ctx.json({passkey: Credentials.wire(updated)})
+          end
+        end
+      end
+    end
+  end
+end

data/lib/better_auth/passkey/routes/registration.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "base64"
+require "webauthn"
+
+module BetterAuth
+  module Passkey
+    module Routes
+      module Registration
+        module_function
+
+        def generate_passkey_registration_options_endpoint(config)
+          Endpoint.new(path: "/passkey/generate-register-options", method: "GET") do |ctx|
+            query = Utils.normalize_hash(ctx.query)
+            Utils.validate_authenticator_attachment!(query[:authenticator_attachment])
+            user = Utils.resolve_registration_user(config, ctx, query)
+            relying_party = Utils.relying_party(config, ctx)
+            existing = ctx.context.adapter.find_many(model: "passkey", where: [{field: "userId", value: user.fetch("id")}])
+            options = WebAuthn::Credential.options_for_create(
+              user: {
+                id: Crypto.random_string(32).downcase,
+                name: query[:name].to_s.empty? ? (user["email"] || user["name"] || user["id"]) : query[:name].to_s,
+                display_name: user["displayName"] || user["display_name"] || user["email"] || user["name"] || user["id"]
+              },
+              exclude: existing.map { |passkey| Credentials.credential_id(passkey) },
+              authenticator_selection: Utils.authenticator_selection(config, query),
+              extensions: Utils.resolve_extensions(config.dig(:registration, :extensions), ctx),
+              relying_party: relying_party
+            )
+            Challenges.store_challenge(ctx, config, options.challenge, {
+              id: user.fetch("id"),
+              name: user["name"] || user["email"] || user["id"],
+              displayName: user["displayName"] || user["display_name"]
+            }.compact)
+            payload = options.as_json.merge(attestation: "none", excludeCredentials: existing.map { |passkey| Credentials.credential_descriptor(passkey, kind: :exclude) })
+            payload.delete(:extensions) if payload[:extensions].nil? || payload[:extensions] == {}
+            payload.delete("extensions") if payload["extensions"].nil? || payload["extensions"] == {}
+            ctx.json(payload)
+          end
+        end
+
+        def verify_passkey_registration_endpoint(config)
+          Endpoint.new(path: "/passkey/verify-registration", method: "POST") do |ctx|
+            body = Utils.normalize_hash(ctx.body)
+            Utils.require_key!(body, :response)
+            require_session = config.dig(:registration, :require_session) != false
+            session = require_session ? BetterAuth::Routes.current_session(ctx, sensitive: true) : BetterAuth::Routes.current_session(ctx, allow_nil: true)
+            origin = Utils.origin(config, ctx)
+            raise APIError.new("BAD_REQUEST", message: ErrorCodes::PASSKEY_ERROR_CODES.fetch("FAILED_TO_VERIFY_REGISTRATION")) if origin.to_s.empty?
+
+            verification_token = Challenges.challenge_token(ctx, config)
+            raise APIError.new("BAD_REQUEST", message: ErrorCodes::PASSKEY_ERROR_CODES.fetch("CHALLENGE_NOT_FOUND")) unless verification_token
+
+            challenge = Challenges.find_challenge(ctx, verification_token)
+            unless challenge
+              raise APIError.new("BAD_REQUEST", message: ErrorCodes::PASSKEY_ERROR_CODES.fetch("CHALLENGE_NOT_FOUND"))
+            end
+            if session && challenge.fetch("userData").fetch("id") != session.fetch(:user).fetch("id")
+              raise APIError.new("UNAUTHORIZED", message: ErrorCodes::PASSKEY_ERROR_CODES.fetch("YOU_ARE_NOT_ALLOWED_TO_REGISTER_THIS_PASSKEY"))
+            end
+
+            response = Credentials.webauthn_response(body[:response])
+            relying_party = Utils.relying_party(config, ctx, origin: origin)
+            credential = WebAuthn::Credential.from_create(response, relying_party: relying_party)
+            credential.verify(challenge.fetch("expectedChallenge"), user_verification: false)
+            authenticator_data = Credentials.authenticator_data(credential)
+            target_user_id = Utils.after_registration_verification_user_id(config, ctx, credential, challenge, response, session)
+            data = ctx.context.adapter.create(
+              model: "passkey",
+              data: {
+                name: body[:name],
+                userId: target_user_id,
+                credentialID: credential.id,
+                publicKey: Base64.strict_encode64(credential.public_key),
+                counter: credential.sign_count,
+                deviceType: authenticator_data&.credential_backup_eligible? ? "multiDevice" : "singleDevice",
+                backedUp: authenticator_data&.credential_backed_up? || false,
+                transports: Array(Credentials.attestation_response(credential)&.transports).join(","),
+                createdAt: Time.now,
+                aaguid: Credentials.attestation_response(credential)&.aaguid
+              }
+            )
+            ctx.context.internal_adapter.delete_verification_by_identifier(verification_token)
+            ctx.json(Credentials.wire(data))
+          rescue WebAuthn::Error => error
+            ctx.context.logger&.error("Failed to verify registration", error)
+            raise APIError.new("INTERNAL_SERVER_ERROR", message: ErrorCodes::PASSKEY_ERROR_CODES.fetch("FAILED_TO_VERIFY_REGISTRATION"))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/better_auth/passkey/routes.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "routes/registration"
+require_relative "routes/authentication"
+require_relative "routes/management"

data/lib/better_auth/passkey/schema.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Passkey
+    module Schema
+      module_function
+
+      def passkey_schema(custom_schema = nil)
+        base = {
+          passkey: {
+            model_name: "passkeys",
+            fields: {
+              name: {type: "string", required: false},
+              publicKey: {type: "string", required: true},
+              userId: {type: "string", references: {model: "user", field: "id"}, required: true, index: true},
+              credentialID: {type: "string", required: true, index: true},
+              counter: {type: "number", required: true},
+              deviceType: {type: "string", required: true},
+              backedUp: {type: "boolean", required: true},
+              transports: {type: "string", required: false},
+              createdAt: {type: "date", required: false},
+              aaguid: {type: "string", required: false}
+            }
+          }
+        }
+        deep_merge_hashes(normalize_hash(base), normalize_hash(custom_schema || {}))
+      end
+
+      def deep_merge_hashes(base, override)
+        base.merge(override) do |_key, old_value, new_value|
+          if old_value.is_a?(Hash) && new_value.is_a?(Hash)
+            deep_merge_hashes(old_value, new_value)
+          else
+            new_value
+          end
+        end
+      end
+
+      def normalize_hash(value)
+        return {} unless value.is_a?(Hash)
+
+        value.each_with_object({}) do |(key, object), result|
+          result[normalize_key(key)] = object.is_a?(Hash) ? normalize_hash(object) : object
+        end
+      end
+
+      def normalize_key(key)
+        key.to_s
+          .delete_prefix("$")
+          .gsub(/([a-z\d])([A-Z])/, "\\1_\\2")
+          .tr("-", "_")
+          .downcase
+          .to_sym
+      end
+    end
+  end
+end