Repository navigation
feat(auth): sign in with a passkey - #646
Merged
Merged
Conversation
Tr00d
marked this pull request as ready for review
November 3, 2026 07:24
Tr00d
force-pushed
the
feat/auth.passkey.sign_in_with_passkey
branch
from
November 3, 2026 07:29
6de16b2 to
6f5ceea
Compare
This was referenced Nov 10, 2026
6 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
A user can sign in with a passkey. The SDK fetches the WebAuthn challenge from the auth server and exchanges the assertion for a session. The caller runs the WebAuthn ceremony on their platform in between.
Capability:
auth.passkey.sign_in_with_passkey, Sign In with Passkey. No capability spec exists.Public API
New types in
Supabase.Gotrue.SignInWithPasskey:Both client members carry
[ImplementedCapability("auth.passkey.sign_in_with_passkey")].Behavior
POST /passkeys/authentication/optionswith the API key and no session.{"gotrue_meta_security":{"captcha_token":"…"}}when a non-empty CAPTCHA token is given; otherwise there is no body.{challenge_id, options, expires_at}and maps it toPasskeySignInChallenge.options(W3CPublicKeyCredentialRequestOptions, base64url binary fields, discoverable) is passed through untouched.expires_atis unix seconds, mapped toDateTimeOffset.GotrueException.POST /passkeys/authentication/verify, body{"challenge_id":"<uuid>","credential":<assertion verbatim>}. Returns an AccessTokenResponse, mapped toSession.credentialthat is not a JSON object (includingdefault(JsonElement)) throwsArgumentExceptionbefore any request.GotrueExceptionwithReason = Unknown, and the current session is kept.UserUpdatedthenSignedIn, as withSignInWithIdToken. TheIGotrueApivariants store nothing.GotrueException. No newFailureHint.Reason.Reason = Offlinewhen the client is offline; no request is sent.UserTooManyRequests(per-IP passkey rate limit). 400captcha_failed.webauthn_challenge_not_found(unknown or already used; a failed attempt also consumes it),webauthn_challenge_expired,webauthn_verification_failed. 403email_not_confirmedmaps toUserEmailNotConfirmed; 403phone_not_confirmedanduser_bannedsurface onErrorCode.passkey_disabled.gotrue.start_passkey_sign_inandgotrue.sign_in.passkeyparent their HTTP spans.Contract source: supabase/auth
internal/api/passkey_authentication.go(PasskeyAuthenticationOptions,PasskeyAuthenticationVerify) andapi.go(route middleware). The authopenapi.yamldoes not describe/passkeys.Deviations from supabase-js
signInWithPasskey()drivesnavigator.credentials.get(). Anetstandard2.1library has no cross-platform WebAuthn API, so the SDK exposes the two server steps and the caller runs the ceremony: Blazor JS interop, Android Credential Manager,webauthn.dll, or a browser on a later request to an ASP.NET backend, since the challenge lives server-side. supabase-kt, supabase-flutter and supabase-swift (off Apple platforms) take the same split.mediationorAbortSignal. These are browser-only options.JsonElementpassthrough in the WebAuthn JSON format, not deserialized browser types.Guidchallenge id. Typed exceptions instead of{ data, error }.Tests
SignInWithPasskeyTestslast_used_at. An unregistered credential giveswebauthn_verification_failed. A replayed challenge giveswebauthn_challenge_not_found.StartPasskeySignInContractTestscaptcha_failed,passkey_disabled. Cancellation, no context capture.SignInWithPasskeyContractTestsUnknown, session kept). WebAuthn error codes.UserEmailNotConfirmed.ArgumentExceptionbefore the wire. Cancellation, no context capture incl. async session stores.SignInWithPasskeyApprovalTestsgotrue_meta_securitywith a token,challenge_idplus the assertion verbatim.OfflineClientContractTests,ObservabilityContractTestsChanged-line coverage: 100% (49 lines). Mutation: 27/27 tested mutants on changed lines detected (25 killed, 2 timeouts), 0 survivors.
Notes
Gotrue.Tests/Support/SoftwareAuthenticatornow keeps what it registers (SoftwarePasskey: credential id, P-256 key, user handle fromoptions.user.id) and signs discoverable assertions the way supabase/auth'svirtualAuthenticator.getAssertiondoes: flags UP|UV, sign count 0, ES256 DER signature overauthenticatorData || SHA-256(clientDataJSON).Clone(): System.Text.Json reads aJsonElementproperty throughJsonElement.ParseValue, which returns an element that owns its data and outlives the response.config.tomlchange; passkeys and the WebAuthn relying party are already enabled (feat(auth): list the signed-in user's passkeys #634). The challenge-expiry path is contract-only, because the CLI does not exposechallenge_expiry_duration.