SDK API reference. · ComplicatedAuth

Browser package

`@complicatedauth/browser`

Framework-neutral browser client. It communicates only with a same-origin BFF and never accepts a Project service credential.

`new ComplicatedAuthClient(options)`

Option	Type	Meaning
`baseUrl`	`string`	Required BFF mount path, typically `/api/auth`.
`storage`	`StorageLike`	Defaults to `sessionStorage`, or memory outside a browser.
`fetch`	`typeof fetch`	Optional transport injection for tests or runtimes.
`storageKeyPrefix`	`string`	Defaults to `complicatedauth`.

Methods

Method	Returns	Behavior
`startLogin(email)`	`Promise<LoginAttempt>`	Creates a non-enumerating login attempt and stores its browser token.
`startPasswordAuth(password)`	`Promise<AuthProgress>`	Verifies the password. Returns factor_verified, or authenticated only when policy permits a completed session.
`startPasskeyAuth()`	`Promise<AuthenticatedSession>`	Runs a platform-passkey WebAuthn ceremony for the current login attempt.
`startSecurityKeyAuth()`	`Promise<AuthenticatedSession>`	Runs a cross-platform security-key ceremony.
`startHybridAuth()`	`Promise<AuthenticatedSession>`	Runs a hybrid/phone-assisted WebAuthn ceremony.
`startFirstPasskeyEnrollment()`	`Promise<AuthenticatedSession>`	After password verification, enrolls the user's first passkey and completes login.
`startFirstSecurityKeyEnrollment()`	`Promise<AuthenticatedSession>`	After password verification, enrolls the user's first attested security key and completes login.
`startPasskeyEnrollment()`	`Promise<FidoCredential>`	Enrolls a platform passkey for the current session.
`startSecurityKeyEnrollment()`	`Promise<FidoCredential>`	Enrolls a cross-platform security key for the current session.
`removeFidoCredential(uid)`	`Promise<void>`	Deletes a passkey or security-key credential owned by the current user.
`restoreSession()`	`Promise<AuthenticatedSession \| null>`	Introspects stored state. Clears and returns null for an invalid or expired session.
`getSession()`	`AuthenticatedSession \| null`	Returns the locally stored session without a network request.
`logout()`	`Promise<void>`	Revokes the backend session when present and always clears browser state.
`cancelLogin()`	`void`	Forgets the current login attempt without touching an authenticated session.
`supportsWebAuthn()`	`boolean`	Reports basic browser WebAuthn support.
`supportsWebAuthnAutofill()`	`Promise<boolean>`	Reports conditional mediation/autofill support.
`platformAuthenticatorAvailable()`	`Promise<boolean>`	Reports whether a platform authenticator is available.

Core values

interface AuthenticatedSession {
  token: string;
  expiresAt: string;
  projectUser: ProjectUser;
}

interface ProjectUser {
  uid: string;
  email: string;
  email_verified: boolean;
  status: "active" | "disabled";
  passkey_count: number;
  created_at: string;
}

type AuthProgress =
  | { status: "factor_verified"; factor: "password"; expiresAt: string }
  | { status: "authenticated"; session: AuthenticatedSession };

requestPlugin() and acceptPluginSession() are public extension hooks for official packages. Application code normally should not call them directly.

Server package

`@complicatedauth/server`

ComplicatedAuthServer is a Web-standard request handler for BFF routes. It adds a scoped Project service credential, exchanges sensitive backend references for random browser tokens, and sets Cache-Control: no-store.

`new ComplicatedAuthServer(options)`

Option	Type	Meaning
`backendUrl`	`string`	Required ComplicatedAuth API origin.
`projectUid`	`string`	Required Project UUID.
`serviceCredential`	`string`	Required expiring secret; keep it exclusively on the server.
`store`	`ReferenceStore`	Use `RedisReferenceStore` in production. Defaults to memory for development.
`fetch`	`typeof fetch`	Optional server transport injection.

`handle(request): Promise<Response>`

Mount the same handler for GET, POST, and DELETE beneath a route ending in /auth. Unknown paths return a structured 404 and unexpected handler failures return bff_error.

BFF route	Behavior
`POST /login/start`	Start a login and replace the backend reference with a browser-safe token.
`POST /login/password`	Verify the password factor for the current login token.
`POST /login/fido/options`	Return WebAuthn request options.
`POST /login/fido/verify`	Verify FIDO and exchange the resulting session reference.
`POST /login/fido/enrollment/options`	Begin initial FIDO enrollment after password verification.
`POST /login/fido/enrollment/verify`	Enroll the first FIDO credential and exchange the completed session.
`POST /login/biometric`	Verify a selfie through the configured biometric provider.
`POST /enrollments/fido/options`	Begin authenticated FIDO enrollment.
`POST /enrollments/fido/verify`	Finish authenticated FIDO enrollment.
`DELETE /enrollments/fido/:uid`	Delete the current user's FIDO credential.
`POST\|DELETE /enrollments/biometric`	Create, replace, or delete facial enrollment.
`GET /session`	Restore and introspect a browser session.
`POST /logout`	Revoke the server session and forget the browser token.

`ReferenceStore`

interface ReferenceStore {
  get(token: string): Promise<StoredReference | null>;
  set(token: string, value: StoredReference): Promise<void>;
  delete(token: string): Promise<void>;
}

interface StoredReference {
  kind: "login" | "session";
  reference: string;
  expiresAt: string;
}

RedisReferenceStore accepts the official Redis client's get, set(..., {PX}), and del methods. It uses the backend expiry as the Redis TTL, rejects malformed records, and supports multiple BFF instances.

Biometric package

`@complicatedauth/biometrics`

Optional browser extension that uploads an image through the core client's authenticated plugin transport.

API	Returns	Behavior
`new BiometricClient({client, maxSelfieBytes?})`	`BiometricClient`	Defaults the image limit to 5 MiB.
`startBiometricAuth(selfie)`	`Promise<AuthenticatedSession>`	Requires an active login attempt and verified password policy.
`startBiometricEnrollment(selfie)`	`Promise<BiometricEnrollment>`	Creates or replaces enrollment for the authenticated user.
`removeBiometricEnrollment()`	`Promise<void>`	Deletes current enrollment.
`startSelfieCamera(video, constraints?)`	`Promise<MediaStream>`	Requests the front camera, attaches it, and starts playback.
`captureSelfie(video, options?)`	`Promise<Blob>`	Mirrors and encodes the current frame; defaults to JPEG, 0.9 quality, 1280 px.
`stopSelfieCamera(videoOrStream)`	`void`	Stops every media track and detaches the video element.

This package validates file type and size, not liveness. The deployment must define provider assurance, consent, retention, retry, and fallback policies.

Failure model

`ComplicatedAuthError`

Browser operations reject with ComplicatedAuthError when the failure comes from API, network, state, or WebAuthn handling.

Property	Type	Meaning
`kind`	`"api" \| "network" \| "state" \| "webauthn"`	Stable failure category for UI branching.
`code`	`string`	API error code or SDK code such as `login_not_started`.
`status`	`number?`	HTTP status when an API response exists.
`cause`	`unknown?`	Original network or WebAuthn error where available.

try {
  await auth.startPasskeyAuth();
} catch (error) {
  if (error instanceof ComplicatedAuthError) {
    report(error.kind, error.code, error.status);
  }
}