better_auth-passkey 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9d897b27289670fa9776d35b6f8d7e24232626b3079feaa9df4989bf1778d41
-  data.tar.gz: 42ca8da646e0db4a2c4ce0c7380a6bd657385470beddfa0a3e45f4d33179f578
+  metadata.gz: bd306893b45a068e5d878de3b262cae1283fd77c4b32a572c389940cf0802bd9
+  data.tar.gz: b28b537cc8cf727bc5b7d4c9c370b0d32953f80e25137f097cd5c80b1e417221
 SHA512:
-  metadata.gz: 653ff4209165b99511fda3f9bf433069b3ffd85915f88a014913ae9671e18abfcec1fd283a72d2014db6b9baca97441fb99ca658cb3f36b4548bb8294d22a201
-  data.tar.gz: 11af45bc047d37897caa689ef15d5dda7bd794b17c6c6a607c00e6d3b475a5f9907af6c941a7f4bb07ec5b6503587d8c1c3285dcdcc1071853f55167f248d21f
+  metadata.gz: d18c881ba150a5bd6ae0f635b8b45ecffc09936292995448b301ef5a990e6fef4715c208aee4a067049e95c69b6478915771dd4a53c28e3e061a88fa02b19be0
+  data.tar.gz: 4dc7a18a75749e3c53374ab5183d690a3160c581d7fbdad150eaf86c25cf9534a83354a2a317e79639e0af6ec97afae70e3f0daec6d4ab68dbb5ed0af53966bc

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,99 @@ 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.
+
+## 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/version.rb

@@ -2,6 +2,6 @@
 
 module BetterAuth
   module Passkey
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/better_auth/plugins/passkey.rb

@@ -62,8 +62,9 @@ module BetterAuth
     def generate_passkey_registration_options_endpoint(config)
       Endpoint.new(path: "/passkey/generate-register-options", method: "GET") do |ctx|
         query = normalize_hash(ctx.query)
+        passkey_validate_authenticator_attachment!(query[:authenticator_attachment])
         user = passkey_resolve_registration_user(config, ctx, query)
-        passkey_configure_webauthn(config, ctx)
+        relying_party = passkey_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: {
@@ -73,43 +74,53 @@ module BetterAuth
           },
           exclude: existing.map { |passkey| passkey_credential_id(passkey) },
           authenticator_selection: passkey_authenticator_selection(config, query),
-          extensions: passkey_resolve_extensions(config.dig(:registration, :extensions), ctx)
+          extensions: passkey_resolve_extensions(config.dig(:registration, :extensions), ctx),
+          relying_party: relying_party
         )
         passkey_store_challenge(ctx, config, options.challenge, {
           id: user.fetch("id"),
           name: user["name"] || user["email"] || user["id"],
           displayName: user["displayName"] || user["display_name"]
         }.compact)
-        ctx.json(options.as_json.merge(excludeCredentials: existing.map { |passkey| passkey_credential_descriptor(passkey) }))
+        ctx.json(options.as_json.merge(attestation: "none", excludeCredentials: existing.map { |passkey| passkey_credential_descriptor(passkey, kind: :exclude) }))
       end
     end
 
     def generate_passkey_authentication_options_endpoint(config)
       Endpoint.new(path: "/passkey/generate-authenticate-options", method: "GET") do |ctx|
         session = Routes.current_session(ctx, allow_nil: true)
-        passkey_configure_webauthn(config, ctx)
+        relying_party = passkey_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
-        options = WebAuthn::Credential.options_for_get(
-          allow: passkeys.map { |passkey| passkey_credential_id(passkey) },
-          extensions: passkey_resolve_extensions(config.dig(:authentication, :extensions), ctx)
-        )
+        get_options = {
+          extensions: passkey_resolve_extensions(config.dig(:authentication, :extensions), ctx),
+          relying_party: relying_party
+        }
+        get_options[:allow] = passkeys.map { |passkey| passkey_credential_id(passkey) } if passkeys.any?
+        options = WebAuthn::Credential.options_for_get(**get_options)
         passkey_store_challenge(ctx, config, options.challenge, session ? session.fetch(:user).fetch("id") : "")
         payload = options.as_json.merge(userVerification: "preferred")
-        payload[:allowCredentials] = passkeys.map { |passkey| passkey_credential_descriptor(passkey) } if passkeys.any?
+        if passkeys.any?
+          payload[:allowCredentials] = passkeys.map { |passkey| passkey_credential_descriptor(passkey) }
+        else
+          payload.delete(:allowCredentials)
+          payload.delete("allowCredentials")
+        end
         ctx.json(payload)
       end
     end
 
     def verify_passkey_registration_endpoint(config)
       Endpoint.new(path: "/passkey/verify-registration", method: "POST") do |ctx|
+        body = normalize_hash(ctx.body)
+        passkey_require_key!(body, :response)
         require_session = config.dig(:registration, :require_session) != false
-        session = require_session ? Routes.current_session(ctx, sensitive: true) : Routes.current_session(ctx, allow_nil: true, sensitive: true)
+        session = require_session ? Routes.current_session(ctx, sensitive: true) : Routes.current_session(ctx, allow_nil: true)
         origin = passkey_origin(config, ctx)
-        raise APIError.new("BAD_REQUEST", message: "origin missing") if origin.to_s.empty?
+        raise APIError.new("BAD_REQUEST", message: PASSKEY_ERROR_CODES.fetch("FAILED_TO_VERIFY_REGISTRATION")) if origin.to_s.empty?
 
         verification_token = passkey_challenge_token(ctx, config)
         raise APIError.new("BAD_REQUEST", message: PASSKEY_ERROR_CODES.fetch("CHALLENGE_NOT_FOUND")) unless verification_token
@@ -122,12 +133,11 @@ module BetterAuth
           raise APIError.new("UNAUTHORIZED", message: PASSKEY_ERROR_CODES.fetch("YOU_ARE_NOT_ALLOWED_TO_REGISTER_THIS_PASSKEY"))
         end
 
-        response = passkey_webauthn_response(normalize_hash(ctx.body)[:response])
-        passkey_configure_webauthn(config, ctx, origin: origin)
-        credential = WebAuthn::Credential.from_create(response)
+        response = passkey_webauthn_response(body[:response])
+        relying_party = passkey_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 = passkey_authenticator_data(credential)
-        body = normalize_hash(ctx.body)
         target_user_id = passkey_after_registration_verification_user_id(config, ctx, credential, challenge, response, session)
         data = ctx.context.adapter.create(
           model: "passkey",
@@ -154,6 +164,8 @@ module BetterAuth
 
     def verify_passkey_authentication_endpoint(config)
       Endpoint.new(path: "/passkey/verify-authentication", method: "POST") do |ctx|
+        body = normalize_hash(ctx.body)
+        passkey_require_key!(body, :response)
         origin = passkey_origin(config, ctx)
         raise APIError.new("BAD_REQUEST", message: "origin missing") if origin.to_s.empty?
 
@@ -163,13 +175,13 @@ module BetterAuth
         challenge = passkey_find_challenge(ctx, verification_token)
         raise APIError.new("BAD_REQUEST", message: PASSKEY_ERROR_CODES.fetch("CHALLENGE_NOT_FOUND")) unless challenge
 
-        response = passkey_webauthn_response(normalize_hash(ctx.body)[:response])
+        response = passkey_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: PASSKEY_ERROR_CODES.fetch("PASSKEY_NOT_FOUND")) unless passkey
 
-        passkey_configure_webauthn(config, ctx, origin: origin)
-        credential = WebAuthn::Credential.from_get(response)
+        relying_party = passkey_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")),
@@ -213,9 +225,12 @@ module BetterAuth
       Endpoint.new(path: "/passkey/delete-passkey", method: "POST") do |ctx|
         session = Routes.current_session(ctx)
         body = normalize_hash(ctx.body)
+        passkey_require_string!(body, :id)
         passkey = ctx.context.adapter.find_one(model: "passkey", where: [{field: "id", value: body[:id]}])
         raise APIError.new("NOT_FOUND", message: PASSKEY_ERROR_CODES.fetch("PASSKEY_NOT_FOUND")) unless passkey
-        raise APIError.new("UNAUTHORIZED") unless passkey.fetch("userId") == session.fetch(:user).fetch("id")
+        unless passkey.fetch("userId") == session.fetch(:user).fetch("id")
+          raise APIError.new("UNAUTHORIZED", message: 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})
@@ -226,6 +241,11 @@ module BetterAuth
       Endpoint.new(path: "/passkey/update-passkey", method: "POST") do |ctx|
         session = Routes.current_session(ctx)
         body = normalize_hash(ctx.body)
+        passkey_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: PASSKEY_ERROR_CODES.fetch("PASSKEY_NOT_FOUND")) unless passkey
         if passkey.fetch("userId") != session.fetch(:user).fetch("id")
@@ -261,11 +281,7 @@ module BetterAuth
           }
         }
       }
-      return base unless custom_schema.is_a?(Hash)
-
-      base.merge(custom_schema) do |_key, old_value, new_value|
-        (old_value.is_a?(Hash) && new_value.is_a?(Hash)) ? old_value.merge(new_value) : new_value
-      end
+      passkey_deep_merge_hashes(normalize_hash(base), normalize_hash(custom_schema || {}))
     end
 
     def passkey_store_challenge(ctx, config, challenge, user_id)
@@ -301,10 +317,12 @@ module BetterAuth
       ctx.context.create_auth_cookie(config.dig(:advanced, :web_authn_challenge_cookie), max_age: PASSKEY_CHALLENGE_MAX_AGE)
     end
 
-    def passkey_configure_webauthn(config, ctx, origin: nil)
-      WebAuthn.configuration.rp_id = passkey_rp_id(config, ctx)
-      WebAuthn.configuration.rp_name = config[:rp_name] || ctx.context.app_name
-      WebAuthn.configuration.allowed_origins = passkey_allowed_origins(config, ctx, origin: origin)
+    def passkey_relying_party(config, ctx, origin: nil)
+      WebAuthn::RelyingParty.new(
+        id: passkey_rp_id(config, ctx),
+        name: config[:rp_name] || ctx.context.app_name,
+        allowed_origins: passkey_allowed_origins(config, ctx, origin: origin)
+      )
     end
 
     def passkey_origin(config, ctx)
@@ -318,7 +336,10 @@ module BetterAuth
     def passkey_rp_id(config, ctx)
       return config[:rp_id] if config[:rp_id]
 
-      URI.parse(ctx.context.options.base_url.to_s).host || "localhost"
+      base_url = ctx.context.options.base_url.to_s
+      return "localhost" if base_url.empty?
+
+      URI.parse(base_url).host || "localhost"
     rescue URI::InvalidURIError
       "localhost"
     end
@@ -334,6 +355,25 @@ module BetterAuth
       }.compact
     end
 
+    def passkey_validate_authenticator_attachment!(value)
+      return if value.nil? || ["platform", "cross-platform"].include?(value)
+
+      raise APIError.new("BAD_REQUEST", message: BASE_ERROR_CODES.fetch("VALIDATION_ERROR"))
+    end
+
+    def passkey_require_key!(body, key)
+      return if body.key?(key)
+
+      raise APIError.new("BAD_REQUEST", message: BASE_ERROR_CODES.fetch("VALIDATION_ERROR"))
+    end
+
+    def passkey_require_string!(body, key)
+      passkey_require_key!(body, key)
+      return if body[key].is_a?(String)
+
+      raise APIError.new("BAD_REQUEST", message: BASE_ERROR_CODES.fetch("VALIDATION_ERROR"))
+    end
+
     def passkey_resolve_registration_user(config, ctx, query)
       require_session = config.dig(:registration, :require_session) != false
       if require_session
@@ -409,9 +449,9 @@ module BetterAuth
         context: challenge["context"]
       }) || {})
       returned_user_id = result[:user_id]
-      return target_user_id if returned_user_id.to_s.empty?
+      return target_user_id if returned_user_id.nil? || returned_user_id == ""
 
-      unless returned_user_id.is_a?(String)
+      unless returned_user_id.is_a?(String) && returned_user_id.length.positive?
         raise APIError.new("BAD_REQUEST", message: PASSKEY_ERROR_CODES.fetch("RESOLVED_USER_INVALID"))
       end
 
@@ -474,14 +514,22 @@ module BetterAuth
       record["credentialID"] || record["credentialId"] || record[:credentialID] || record[:credential_id]
     end
 
-    def passkey_credential_descriptor(record)
-      descriptor = {
-        id: passkey_credential_id(record),
-        type: "public-key"
-      }
+    def passkey_credential_descriptor(record, kind: :allow)
+      descriptor = {id: passkey_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
+
+    def passkey_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)
+          passkey_deep_merge_hashes(old_value, new_value)
+        else
+          new_value
+        end
+      end
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: better_auth-passkey
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Sebastian Sala