Skip to content

passkey.md

Latest commit

 

History

History
72 lines (64 loc) · 2.6 KB

passkey.md

File metadata and controls

72 lines (64 loc) · 2.6 KB

PasskeyUsecase

Purpose

Provides the passkey ceremonies for Frontoffice/Backoffice:

  • register options,
  • register finalize,
  • list passkeys for authenticated user,
  • delete passkey,
  • auth options,
  • auth finalize returning an access token.

Trigger / entry points

  • GraphQL auth resolver operations:
    • passkey_register_options
    • passkey_register_finalize
    • passkey_list
    • passkey_delete
    • passkey_activate_local
    • passkey_auth_options
    • passkey_auth_finalize

Inputs

  • register_options: { user_id, label, hostname, origin? }
  • register_finalize: { challenge_id, registration_json }
  • list_for_user: user_id
  • delete_for_user: { passkey_id, user_id }
  • activate_local: { passkey_id, user_id }
  • auth_options: { challenge_id, origin? }
  • auth_finalize: { auth_challenge_id, authentication_json }

Main flow (MongoDB Persisted)

  1. Register options
    • Creates a short-lived challenge in passkey_challenges collection.
    • TTL index handles expiry (5 minutes).
    • Returns challenge_id + JSON options payload for WebAuthn navigator.credentials.create.
  2. Register finalize
    • Consumes (finds and deletes) the pending challenge from MongoDB.
    • Verifies the full registration payload with SimpleWebAuthn (expectedOrigin + expectedRPID).
    • Stores passkey metadata in passkeys collection.
  3. Auth options
    • Resolves passkey by local challenge_id marker in passkeys collection.
    • Creates auth pending challenge in passkey_challenges.
    • Returns JSON options for navigator.credentials.get.
  4. Auth finalize
    • Consumes auth pending challenge from MongoDB.
    • Verifies the full authentication payload against stored passkey material in passkeys collection.
    • Updates last_used_at and signs JWT access token.
  5. Activate local
    • Validates passkey ownership for authenticated user in MongoDB.
    • Returns passkey data needed to reconstruct the local marker.

Outputs / side effects

  • Creates/deletes persistent passkey records in MongoDB.
  • Produces JWT access_token compatible with current login flow.

Error cases / edge cases

  • Expired or unknown pending challenge.
  • Unknown passkey / mismatching credential.
  • User missing during auth finalize.

Dependencies

  • bddService.passkey (MongoDB Repository)
  • bddService.user
  • jwtService
  • loggerService

Related files

  • api/src/usecases/auth/passkey.usecase.ts
  • api/src/services/db/mongo/repositories/passkey.repository.ts
  • api/src/services/db/models/passkey.model.ts
  • api/src/graphql/auth/auth.resolver.ts
  • api/src/graphql/auth/auth.gql.types.ts