Skip to content

feat(auth): list the signed-in user's passkeys - #634

Merged
Tr00d merged 1 commit into
masterfrom
feat/auth.passkey.list_passkeys
Nov 2, 2026
Merged

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

Conversation

@Tr00d

@Tr00d Tr00d commented Nov 2, 2026

Copy link
Copy Markdown
Contributor

Summary

A signed-in user can list the passkeys registered to their account, to review the credentials tied to it.

Capability: auth.passkey.list_passkeys — List Passkeys. No capability spec exists for it. Partially addresses #251.

Public API

// IGotrueClient<TUser, TSession>, next to GetUserIdentitiesAsync
Task<IReadOnlyList<Passkey>> ListPasskeysAsync(CancellationToken cancellationToken = default);

// IGotrueApi<TUser, TSession>
Task<IReadOnlyList<Passkey>> ListPasskeysAsync(string jwt, CancellationToken cancellationToken = default);

New type, Supabase.Gotrue.ListPasskeys.Passkey:

public sealed record Passkey
{
    public Guid Id { get; init; }
    public string? FriendlyName { get; init; }
    public DateTime CreatedAt { get; init; }
    public DateTime? LastUsedAt { get; init; }   // null until the passkey signs the user in
}
var passkeys = await client.ListPasskeysAsync();
foreach (var passkey in passkeys)
{
    Console.WriteLine($"{passkey.FriendlyName ?? "Passkey"}, last used {passkey.LastUsedAt?.ToString() ?? "never"}");
}

Behavior

  • Operation: GET /auth/v1/passkeys, authenticated with the signed-in user's access token (Authorization: Bearer) and the apikey.
  • Inputs: none. Before the wire the SDK requires the client to be online and a session with an access token to exist.
  • Output: the user's passkeys in the server's order, which is created_at ascending. Each JSON item {id, friendly_name?, created_at, last_used_at?} maps to a Passkey. An empty array or an absent body (null) maps to an empty list, never null. No authenticator assurance level is required.
  • Failures:
    • Offline → GotrueException, Reason = Offline, no request sent.
    • No session, or a session without an access token → GotrueException, Reason = NoSessionFound, no request sent.
    • 404 passkey_disabled when passkeys are off on the server → GotrueException with that ErrorCode. No new FailureHint.Reason is added; the code is documented, as on the recovery-code methods.
    • Any other server rejection → GotrueException with the server's ErrorCode, through the existing error mapping.
  • State: none. A gotrue.list_passkeys span parents the HTTP span.

Contract sources: the auth server's handler, since supabase/auth openapi.yaml documents no /passkeys paths:

  • internal/api/passkey_manage.go (PasskeyList, PasskeyListItem)
  • api.go routes
  • middleware.go (requirePasskeyEnabled)

Behavioral references:

  • supabase-js auth-js/src/GoTrueClient.ts (_listPasskeys), lib/types.ts (PasskeyListItem)
  • supabase-flutter (d7eb4936) packages/supabase_auth/lib/src/auth_passkey_api.dart (list), types/passkey.dart (Passkey, same shape as this one)

Deviations from supabase-js

  • No session refresh before the call. supabase-js (_useSession) and supabase-flutter (auth_client.dart:485, _userAccessToken via getSession) refresh an expired session first. This SDK uses the current access token, like the neighbouring GetUserIdentitiesAsync and the recovery-code methods. Auto-refresh keeps that token fresh while it is enabled.
  • Guid id. Both references expose the id as a string. The server always returns a UUID, and a Guid keeps a malformed id out of the upcoming delete and update calls.
  • Typed result. The JS method returns the untyped response data. This one returns a read-only list of immutable records and throws the typed exception on failure.

Tests

Tier Class Pins
E2E ListPasskeysTests Passkeys registered through the real WebAuthn ceremony are listed in registration order. A fresh passkey reads FriendlyName = "Passkey" with no LastUsedAt. A user without passkeys gets an empty list.
Contract ListPasskeysContractTests GET /passkeys with bearer + apikey; item mapping incl. absent optional fields; empty array and null body → empty list; passkey_disabled surfaced; NoSessionFound (no session / no access token, no request sent); Offline; cancellation reaches the HTTP call; no capture of the caller's context.
Contract ObservabilityContractTests gotrue.list_passkeys domain span parents GET /passkeys.

Changed-line coverage: 100% (28 lines). Mutation: 8/8 tested mutants on changed lines killed, 0 survivors.

Notes

  • supabase/config.toml enables passkeys ([auth.passkey] enabled = true). The auth server's default is off, and every /passkeys route answers 404 passkey_disabled when it is off. The file also sets the WebAuthn relying party ([auth.webauthn], rp_id = "localhost", origin http://localhost:3000).
  • Gotrue.Tests/Support/SoftwareAuthenticator seeds passkeys without a browser or hardware key. It runs POST /passkeys/registration/options → /verify with a plain HttpClient, answering the challenge with a fresh P-256 key in the none attestation format. The CBOR is hand-encoded, the same approach as supabase/auth's passkey_virtual_authenticator_test.go. Delete and update passkey will reuse it. supabase-flutter's passkey tests are mock-only, so they do not exercise this route.
  • Spec gap: the auth OpenAPI does not describe the /passkeys endpoints.

Adds IGotrueClient.ListPasskeysAsync (GET /passkeys), enables passkeys on the local stack and adds a software WebAuthn authenticator so E2E tests can seed passkeys.

Refs #251
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