Skip to content

feat(auth): sign in with a passkey - #646

Merged
Tr00d merged 1 commit into
masterfrom
feat/auth.passkey.sign_in_with_passkey
Nov 3, 2026
Merged

Tr00d merged 1 commit into
masterfrom
feat/auth.passkey.sign_in_with_passkey

Conversation

@Tr00d

@Tr00d Tr00d commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

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

// IGotrueClient<TUser, TSession>, next to the passkey members
Task<PasskeySignInChallenge> StartPasskeySignInAsync(SignInWithPasskeyOptions? options = null, CancellationToken cancellationToken = default);
Task<TSession> SignInWithPasskeyAsync(Guid challengeId, JsonElement credential, CancellationToken cancellationToken = default);

// IGotrueApi<TUser, TSession>: stateless, nothing stored
Task<PasskeySignInChallenge> StartPasskeySignInAsync(SignInWithPasskeyOptions? options = null, CancellationToken cancellationToken = default);
Task<TSession?> SignInWithPasskeyAsync(Guid challengeId, JsonElement credential, CancellationToken cancellationToken = default);

New types in Supabase.Gotrue.SignInWithPasskey:

public sealed record PasskeySignInChallenge { Guid Id; JsonElement Options; DateTimeOffset ExpiresAt; }
public sealed record SignInWithPasskeyOptions { string? CaptchaToken; }
var challenge = await client.StartPasskeySignInAsync();
var assertion = await js.InvokeAsync<JsonElement>("passkeys.get", challenge.Options);
var session = await client.SignInWithPasskeyAsync(challenge.Id, assertion);

Both client members carry [ImplementedCapability("auth.passkey.sign_in_with_passkey")].

Behavior

  • Start: POST /passkeys/authentication/options with the API key and no session.
    • The body is {"gotrue_meta_security":{"captcha_token":"…"}} when a non-empty CAPTCHA token is given; otherwise there is no body.
    • Returns {challenge_id, options, expires_at} and maps it to PasskeySignInChallenge. options (W3C PublicKeyCredentialRequestOptions, base64url binary fields, discoverable) is passed through untouched. expires_at is unix seconds, mapped to DateTimeOffset.
    • A success without a body throws GotrueException.
  • Sign in: POST /passkeys/authentication/verify, body {"challenge_id":"<uuid>","credential":<assertion verbatim>}. Returns an AccessTokenResponse, mapped to Session.
    • A credential that is not a JSON object (including default(JsonElement)) throws ArgumentException before any request.
    • A success without a session or access token throws GotrueException with Reason = Unknown, and the current session is kept.
  • State: on success the session replaces the current one and is persisted. Listeners get UserUpdated then SignedIn, as with SignInWithIdToken. The IGotrueApi variants store nothing.
  • Failures: all are GotrueException. No new FailureHint.Reason.
    • Reason = Offline when the client is offline; no request is sent.
    • Start: 429 maps to UserTooManyRequests (per-IP passkey rate limit). 400 captcha_failed.
    • Sign in: 400 webauthn_challenge_not_found (unknown or already used; a failed attempt also consumes it), webauthn_challenge_expired, webauthn_verification_failed. 403 email_not_confirmed maps to UserEmailNotConfirmed; 403 phone_not_confirmed and user_banned surface on ErrorCode.
    • Both: 404 passkey_disabled.
  • Spans: gotrue.start_passkey_sign_in and gotrue.sign_in.passkey parent their HTTP spans.

Contract source: supabase/auth internal/api/passkey_authentication.go (PasskeyAuthenticationOptions, PasskeyAuthenticationVerify) and api.go (route middleware). The auth openapi.yaml does not describe /passkeys.

Deviations from supabase-js

  • No built-in ceremony. supabase-js signInWithPasskey() drives navigator.credentials.get(). A netstandard2.1 library 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.
  • No mediation or AbortSignal. These are browser-only options.
  • CAPTCHA moves to the start step, which is where the server checks it.
  • Options are JsonElement passthrough in the WebAuthn JSON format, not deserialized browser types.
  • Guid challenge id. Typed exceptions instead of { data, error }.

Tests

Tier Class Pins
E2E SignInWithPasskeyTests The challenge names the configured rp id. A software-authenticator assertion signs in the passkey's owner and stamps last_used_at. An unregistered credential gives webauthn_verification_failed. A replayed challenge gives webauthn_challenge_not_found.
Contract StartPasskeySignInContractTests Path and apikey with no session. Challenge mapping with options verbatim. Empty success. 429, captcha_failed, passkey_disabled. Cancellation, no context capture.
Contract SignInWithPasskeyContractTests Path and apikey. Session returned, stored, persisted and announced. Empty or unusable success (Unknown, session kept). WebAuthn error codes. UserEmailNotConfirmed. ArgumentException before the wire. Cancellation, no context capture incl. async session stores.
Contract SignInWithPasskeyApprovalTests Exact bodies: none without CAPTCHA, none with an empty token, gotrue_meta_security with a token, challenge_id plus the assertion verbatim.
Contract OfflineClientContractTests, ObservabilityContractTests Offline guard on both; domain spans parent the HTTP spans.

Changed-line coverage: 100% (49 lines). Mutation: 27/27 tested mutants on changed lines detected (25 killed, 2 timeouts), 0 survivors.

Notes

  • Gotrue.Tests/Support/SoftwareAuthenticator now keeps what it registers (SoftwarePasskey: credential id, P-256 key, user handle from options.user.id) and signs discoverable assertions the way supabase/auth's virtualAuthenticator.getAssertion does: flags UP|UV, sign count 0, ES256 DER signature over authenticatorData || SHA-256(clientDataJSON).
  • Options need no Clone(): System.Text.Json reads a JsonElement property through JsonElement.ParseValue, which returns an element that owns its data and outlives the response.
  • No config.toml change; 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 expose challenge_expiry_duration.

@Tr00d
Tr00d marked this pull request as ready for review November 3, 2026 07:24
@Tr00d
Tr00d force-pushed the feat/auth.passkey.sign_in_with_passkey branch from 6de16b2 to 6f5ceea Compare November 3, 2026 07:29
@Tr00d
Tr00d merged commit db8636d into master Nov 3, 2026
6 checks passed
@Tr00d
Tr00d deleted the feat/auth.passkey.sign_in_with_passkey branch November 3, 2026 07:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant