@wtfalch/auth 0.6.0 → 0.8.0

package/dist/namespaces.d.ts

@@ -9,7 +9,9 @@ export interface NamespaceDomain {
     /** Operator-owned evidence reference; this is not an automated DNS verifier. */
     verificationRef?: string;
 }
+/** A browser service: the SDK's server or browser client at one origin. `kind` is omitted. */
 export interface NamespaceService {
+    kind?: 'web';
     id: string;
     serviceId: string;
     deploymentId: string;
@@ -18,12 +20,56 @@ export interface NamespaceService {
     postLogoutRedirectUris: string[];
     credentialRef: string;
     registration: boolean;
+    /**
+     * A sign-in link may finish a sign-in on its own, making the inbox proof
+     * enough. The broker's `App.emailLink` holds the reasoning. Omitted means
+     * off.
+     */
+    emailLink?: true;
+    /**
+     * A new device can be signed in by a QR code that an already signed-in
+     * person approves, via the issuer's OAuth device authorization grant on
+     * this binding's own OIDC client. Anyone can start one, so the approving
+     * page must show what is being approved. Omitted means off.
+     */
+    qrSignIn?: true;
 }
+/**
+ * Installed software a person signs in to by approving on another device: a
+ * public device-code client with no secret and no redirect URIs.
+ */
+export interface NamespaceNativeService {
+    kind: 'native';
+    id: string;
+    serviceId: string;
+    deploymentId: string;
+}
+/**
+ * A resource server that checks the namespace's tokens at the introspection
+ * endpoint. Its client secret is stored under `credentialRef`, never here.
+ */
+export interface NamespaceApiService {
+    kind: 'api';
+    id: string;
+    serviceId: string;
+    deploymentId: string;
+    credentialRef: string;
+}
+/** Every client of one namespace shares its accounts: one sign-in across all of them. */
+export type NamespaceBinding = NamespaceService | NamespaceNativeService | NamespaceApiService;
+export declare function isWebService<T extends NamespaceBinding>(binding: T): binding is Extract<T, NamespaceService>;
 export interface NamespaceSpec {
     id: string;
     displayName: string;
     revision: number;
     status: Exclude<NamespaceStatus, 'failed'>;
+    /**
+     * `invitation`: nobody signs themselves up. People arrive by invitation,
+     * whether from the organization's admin or when a mailbox is created on
+     * one of its `account` domains. Omitted means open, which is how every
+     * namespace behaved before.
+     */
+    admission?: 'invitation';
     loginOrigin: string;
     domains: NamespaceDomain[];
     mail: {
@@ -31,7 +77,7 @@ export interface NamespaceSpec {
         productName: string;
         locale: string;
     };
-    services: NamespaceService[];
+    services: NamespaceBinding[];
 }
 export interface NamespaceManifest {
     version: 1;
@@ -42,7 +88,7 @@ export interface NamespaceRecord extends Omit<NamespaceSpec, 'status' | 'service
     status: NamespaceStatus;
     organizationId: string;
     projectId: string;
-    services: (NamespaceService & {
+    services: (NamespaceBinding & {
         appId: string;
         clientId: string;
     })[];
@@ -66,6 +112,7 @@ export declare function resolveNamespaceBinding(registry: NamespaceRegistry, inp
     deploymentId: string;
     appOrigin: string;
 }): {
+    kind?: "web";
     id: string;
     serviceId: string;
     deploymentId: string;
@@ -74,6 +121,19 @@ export declare function resolveNamespaceBinding(registry: NamespaceRegistry, inp
     postLogoutRedirectUris: string[];
     credentialRef: string;
     registration: boolean;
+    /**
+     * A sign-in link may finish a sign-in on its own, making the inbox proof
+     * enough. The broker's `App.emailLink` holds the reasoning. Omitted means
+     * off.
+     */
+    emailLink?: true;
+    /**
+     * A new device can be signed in by a QR code that an already signed-in
+     * person approves, via the issuer's OAuth device authorization grant on
+     * this binding's own OIDC client. Anyone can start one, so the approving
+     * page must show what is being approved. Omitted means off.
+     */
+    qrSignIn?: true;
     appId: string;
     clientId: string;
     issuer: string;
@@ -100,6 +160,7 @@ export declare function resolveNamespaceContext(selection: NamespaceSelection, o
     organizationId?: string;
 }): {
     context: string;
+    kind?: "web";
     id: string;
     serviceId: string;
     deploymentId: string;
@@ -108,6 +169,19 @@ export declare function resolveNamespaceContext(selection: NamespaceSelection, o
     postLogoutRedirectUris: string[];
     credentialRef: string;
     registration: boolean;
+    /**
+     * A sign-in link may finish a sign-in on its own, making the inbox proof
+     * enough. The broker's `App.emailLink` holds the reasoning. Omitted means
+     * off.
+     */
+    emailLink?: true;
+    /**
+     * A new device can be signed in by a QR code that an already signed-in
+     * person approves, via the issuer's OAuth device authorization grant on
+     * this binding's own OIDC client. Anyone can start one, so the approving
+     * page must show what is being approved. Omitted means off.
+     */
+    qrSignIn?: true;
     appId: string;
     clientId: string;
     issuer: string;

package/dist/namespaces.js

@@ -1,3 +1,6 @@
+export function isWebService(binding) {
+    return binding.kind === undefined || binding.kind === 'web';
+}
 function invalid(field) {
     throw new Error(`Invalid namespace configuration: ${field}`);
 }
@@ -77,23 +80,57 @@ function domain(value) {
         invalid('active domain needs verificationRef');
     return { domain: name, purpose, status, ...(verificationRef ? { verificationRef } : {}) };
 }
+function credential(value) {
+    const credentialRef = string(value, 'credentialRef');
+    if (!/^[A-Z][A-Z0-9_]{2,100}$/.test(credentialRef) || credentialRef.endsWith('_PAT'))
+        invalid('credentialRef');
+    return credentialRef;
+}
+const WEB_FIELDS = [
+    'appOrigin',
+    'redirectUris',
+    'postLogoutRedirectUris',
+    'registration',
+    'emailLink',
+    'qrSignIn',
+];
 function service(value) {
     const s = object(value, 'service');
+    const kind = s.kind === undefined ? 'web' : oneOf(s.kind, ['web', 'native', 'api'], 'kind');
+    const identity = {
+        id: id(s.id, 'binding id'),
+        serviceId: id(s.serviceId, 'serviceId'),
+        deploymentId: id(s.deploymentId, 'deploymentId'),
+    };
+    if (kind !== 'web') {
+        // Nothing is redirected to installed software or a resource server; a
+        // stray browser field is a mistaken kind, not something to ignore.
+        if (WEB_FIELDS.some((field) => s[field] !== undefined))
+            invalid(`${kind} service web fields`);
+        if (kind === 'native') {
+            if (s.credentialRef !== undefined)
+                invalid('native service credentialRef');
+            return { kind, ...identity };
+        }
+        return { kind, ...identity, credentialRef: credential(s.credentialRef) };
+    }
     const appOrigin = url(s.appOrigin, 'appOrigin', true, true);
-    const credentialRef = string(s.credentialRef, 'credentialRef');
-    if (!/^[A-Z][A-Z0-9_]{2,100}$/.test(credentialRef) || credentialRef.endsWith('_PAT'))
-        invalid('credentialRef');
+    const credentialRef = credential(s.credentialRef);
     if (s.registration !== undefined && typeof s.registration !== 'boolean')
         invalid('registration');
+    if (s.emailLink !== undefined && typeof s.emailLink !== 'boolean')
+        invalid('emailLink');
+    if (s.qrSignIn !== undefined && typeof s.qrSignIn !== 'boolean')
+        invalid('qrSignIn');
     return {
-        id: id(s.id, 'binding id'),
-        serviceId: id(s.serviceId, 'serviceId'),
-        deploymentId: id(s.deploymentId, 'deploymentId'),
+        ...identity,
         appOrigin,
         redirectUris: uris(s.redirectUris, appOrigin, 'redirectUris'),
         postLogoutRedirectUris: uris(s.postLogoutRedirectUris, appOrigin, 'postLogoutRedirectUris'),
         credentialRef,
         registration: s.registration === true,
+        ...(s.emailLink === true ? { emailLink: true } : {}),
+        ...(s.qrSignIn === true ? { qrSignIn: true } : {}),
     };
 }
 function parse(raw, resolved) {
@@ -129,11 +166,21 @@ function parse(raw, resolved) {
         if (!services.length)
             invalid('namespace needs a service');
         unique(services.map((s) => `${s.serviceId}:${s.deploymentId}`), 'namespace service/deployment');
+        const admission = oneOf(n.admission ?? 'open', ['open', 'invitation'], 'admission');
+        if (admission === 'invitation') {
+            // The organization's addresses are what an invitation-only namespace
+            // is for: mail provisioning invites from them.
+            if (!domains.some((d) => d.purpose === 'account'))
+                invalid('invitation namespace needs an account domain');
+            if (services.some((s) => isWebService(s) && s.registration))
+                invalid('invitation namespace cannot open registration');
+        }
         const common = {
             id: id(n.id, 'namespace id'),
             displayName: string(n.displayName, 'displayName'),
             revision: n.revision,
             status,
+            ...(admission === 'invitation' ? { admission } : {}),
             loginOrigin,
             domains,
             services,
@@ -153,7 +200,7 @@ function parse(raw, resolved) {
     });
     unique(namespaces.map((n) => n.id), 'namespace id');
     unique(namespaces.flatMap((n) => n.services.map((s) => s.id)), 'binding id');
-    unique(namespaces.flatMap((n) => n.services.map((s) => s.credentialRef)), 'credential reference');
+    unique(namespaces.flatMap((n) => n.services.flatMap((s) => ('credentialRef' in s ? [s.credentialRef] : []))), 'credential reference');
     const domains = new Map();
     for (const n of namespaces)
         for (const d of n.domains) {
@@ -183,7 +230,9 @@ export function resolveNamespaceBinding(registry, input) {
     const namespace = validated.namespaces.find((n) => n.id === input.namespaceId);
     if (!namespace || namespace.status !== 'active')
         invalid('namespace unavailable');
-    const binding = namespace.services.find((s) => s.serviceId === input.serviceId && s.deploymentId === input.deploymentId);
+    const binding = namespace.services
+        .filter(isWebService)
+        .find((s) => s.serviceId === input.serviceId && s.deploymentId === input.deploymentId);
     if (!binding || binding.appOrigin !== url(input.appOrigin, 'appOrigin', true, true))
         invalid('service binding mismatch');
     return {
@@ -206,7 +255,7 @@ export function parseWorkspaceBindings(raw, registry) {
             namespaceId: id(w.namespaceId, 'namespaceId'),
         };
         const namespace = validated.namespaces.find((n) => n.id === binding.namespaceId);
-        if (!namespace?.services.some((s) => s.serviceId === binding.serviceId))
+        if (!namespace?.services.some((s) => isWebService(s) && s.serviceId === binding.serviceId))
             invalid('workspace service/namespace mismatch');
         return binding;
     });

package/dist/next.d.ts

@@ -1,7 +1,13 @@
 import { type NextRequest, NextResponse } from 'next/server';
-import { type Auth, type AuthRequest, type GateRules, type Intent, type NewUser, type ResetError, type SignInError, type SignUpError, type User } from './auth.js';
+import { type Auth, type AuthRequest, type GateRules, type Intent, type NewUser, type PasskeyRegistrationResult, type PasskeyRegistrationStart, type PasskeySignInStart, type QrPollStatus, type ResetError, type SignInError, type SignUpError, type User } from './auth.js';
 import type { AuthOptions } from './config.js';
 type SearchParams = Record<string, string | string[] | undefined>;
+export interface QrSignIn {
+    url: string;
+    userCode: string;
+    expiresIn: number;
+    interval: number;
+}
 export interface NextAuth {
     auth: Auth;
     /** `export const { GET, POST } = handlers` from app/auth/[...auth]/route.ts. */
@@ -67,6 +73,47 @@ export interface NextAuth {
         error: ResetError;
         message: string;
     }>;
+    /**
+     * Registers a passkey on this app's own domain for the person signed in
+     * here. Throws `AuthError('unauthenticated', ...)` for nobody, exactly as
+     * `requireUser` throws `account_changed`/`unavailable` for those.
+     */
+    startPasskeyRegistration: () => Promise<PasskeyRegistrationStart>;
+    /** The second half of `startPasskeyRegistration`. Same signed-in requirement. */
+    finishPasskeyRegistration: (input: {
+        passkeyId: string;
+        credential: unknown;
+        name: string;
+    }) => Promise<PasskeyRegistrationResult>;
+    /** The passkey half of `signIn`: a challenge to answer with `@wtfalch/auth/passkey`'s `getPasskey`. */
+    startPasskeySignIn: (input: {
+        authRequestId: string;
+        email: string;
+    }) => Promise<PasskeySignInStart>;
+    /** For a server action: redirects into the app on success, returns the error otherwise -- the passkey half of `signIn`. */
+    finishPasskeySignIn: (input: {
+        authRequestId: string;
+        sessionId: string;
+        credential: unknown;
+    }) => Promise<{
+        error: SignInError;
+    }>;
+    /**
+     * Starts a QR sign-in from a server action or route handler, setting the
+     * transaction cookie. In namespace mode, throws `AuthError('unavailable', ...)`
+     * when the binding is not active -- unlike `proxy`/`gate`, which answer a
+     * 503 for the same case rather than throwing.
+     */
+    startQrSignIn: () => Promise<QrSignIn>;
+    /**
+     * Polls the transaction `startQrSignIn` began, reading and setting cookies
+     * through `next/headers`. Never throws for an outcome of the poll itself --
+     * see `Auth['pollQrSignIn']`. `reason` is set only when `status` is `'failed'`.
+     */
+    pollQrSignIn: () => Promise<{
+        status: QrPollStatus;
+        reason?: string;
+    }>;
 }
 export declare function nextAuth(options: AuthOptions): NextAuth;
-export type { Auth, AuthOptions, AuthRequest, GateRules, Intent, NewUser, User };
+export type { Auth, AuthOptions, AuthRequest, GateRules, Intent, NewUser, PasskeyRegistrationResult, PasskeyRegistrationStart, PasskeySignInStart, QrPollStatus, User, };

package/dist/next.js

@@ -119,6 +119,29 @@ export function nextAuth(options) {
         const url = new URL(location);
         redirect(`${url.pathname}${url.search}`);
     };
+    // The passkey routes take a `Request`; a server action has none of its
+    // own, only what `cookies()` already exposes for this request. Only the
+    // cookie header matters to `read`, so a synthetic request carrying just
+    // that is exactly as good as the real one.
+    const requestFromCookies = async () => {
+        const store = await cookies();
+        const header = store
+            .getAll()
+            .map((c) => `${c.name}=${c.value}`)
+            .join('; ');
+        return new Request('http://localhost/', header ? { headers: { cookie: header } } : undefined);
+    };
+    const startPasskeyRegistration = async () => auth.startPasskeyRegistration(await requestFromCookies());
+    const finishPasskeyRegistration = async (input) => auth.finishPasskeyRegistration(await requestFromCookies(), input);
+    const finishPasskeySignIn = async (input) => {
+        const result = await auth.finishPasskeySignIn(input);
+        if (result.ok) {
+            if (result.hosted)
+                redirect(result.redirectTo);
+            return finish(result.redirectTo);
+        }
+        return { error: result.error };
+    };
     const resetPassword = async (input) => {
         const result = await auth.resetPassword(input);
         if (!result.ok)
@@ -153,6 +176,28 @@ export function nextAuth(options) {
         }
         return { error: result.error, message: result.message };
     };
+    const startQrSignIn = async () => {
+        const { cookies: set, ...start } = await auth.startQrSignIn();
+        const store = await cookies();
+        for (const c of set) {
+            if (c.value)
+                store.set(c.name, c.value, c.attributes);
+            else
+                store.delete({ name: c.name, path: '/' });
+        }
+        return start;
+    };
+    const pollQrSignIn = async () => {
+        const { status, reason, cookies: set } = await auth.pollQrSignIn(await requestFromCookies());
+        const store = await cookies();
+        for (const c of set) {
+            if (c.value)
+                store.set(c.name, c.value, c.attributes);
+            else
+                store.delete({ name: c.name, path: '/' });
+        }
+        return reason ? { status, reason } : { status };
+    };
     return {
         auth,
         handlers: { GET: auth.handle, POST: auth.handle },
@@ -169,5 +214,11 @@ export function nextAuth(options) {
         people: auth.people,
         setPersonActive: auth.setPersonActive,
         resetPassword,
+        startPasskeyRegistration,
+        finishPasskeyRegistration,
+        startPasskeySignIn: auth.startPasskeySignIn,
+        finishPasskeySignIn,
+        startQrSignIn,
+        pollQrSignIn,
     };
 }

package/dist/oidc.d.ts

@@ -1,6 +1,8 @@
 import * as jose from 'jose';
 import type { ResolvedOptions } from './config.js';
 export declare const ORG_CLAIM = "urn:zitadel:iam:user:resourceowner:id";
+/** The scopes every flow asks for: the code-exchange authorization request and the QR device grant alike. */
+export declare function scopeFor(organizationId: string): string;
 export interface Tokens {
     idToken: string;
     refreshToken?: string;
@@ -28,7 +30,9 @@ export declare class Oidc {
     verify(idToken: string): Promise<jose.JWTPayload>;
     private assertOrganization;
 }
-export type AuthErrorReason = 'expired' | 'state' | 'denied' | 'exchange' | 'organization' | 'cookie' | 'request' | 'account_changed' | 'unavailable';
+export type AuthErrorReason = 'expired' | 'state' | 'denied' | 'exchange' | 'organization' | 'cookie' | 'request' | 'account_changed' | 'unavailable'
+/** No session at all -- distinct from `account_changed`/`unavailable`, which `requireUser` already covers by redirecting instead. */
+ | 'unauthenticated';
 export declare class AuthError extends Error {
     readonly reason: AuthErrorReason;
     constructor(reason: AuthErrorReason, message: string);

package/dist/oidc.js

@@ -1,6 +1,17 @@
 import * as jose from 'jose';
 import * as client from 'openid-client';
 export const ORG_CLAIM = 'urn:zitadel:iam:user:resourceowner:id';
+/** The scopes every flow asks for: the code-exchange authorization request and the QR device grant alike. */
+export function scopeFor(organizationId) {
+    return [
+        'openid',
+        'email',
+        'profile',
+        'offline_access',
+        `urn:zitadel:iam:org:id:${organizationId}`,
+        'urn:zitadel:iam:user:resourceowner',
+    ].join(' ');
+}
 export class Oidc {
     options;
     configuration = null;
@@ -46,14 +57,7 @@ export class Oidc {
         return client.buildAuthorizationUrl(await this.config(), {
             ...(create ? { prompt: 'create' } : {}),
             redirect_uri: this.redirectUri.href,
-            scope: [
-                'openid',
-                'email',
-                'profile',
-                'offline_access',
-                `urn:zitadel:iam:org:id:${this.options.organizationId}`,
-                'urn:zitadel:iam:user:resourceowner',
-            ].join(' '),
+            scope: scopeFor(this.options.organizationId),
             state,
             nonce,
             code_challenge: await client.calculatePKCECodeChallenge(codeVerifier),

package/dist/passkey-browser.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The WebAuthn ceremony, for an app's own sign-in page: `createPasskey`
+ * answers `auth.startPasskeyRegistration`'s options, `getPasskey` answers
+ * `auth.startPasskeySignIn`'s. Both take the options JSON exactly as the
+ * broker hands it back -- ZITADEL's own `publicKeyCredentialCreationOptions`
+ * / `publicKeyCredentialRequestOptions`, base64url strings where the
+ * WebAuthn spec wants `ArrayBuffer`s and a `publicKey` wrapper around the
+ * rest -- and return a plain JSON-serialisable credential ready for
+ * `auth.finishPasskeyRegistration` / `auth.finishPasskeySignIn`.
+ *
+ * This is a browser file: no server import, nothing that would drag OIDC or
+ * cookie code into the client bundle. The base64url<->`ArrayBuffer`
+ * conversion and the credential's field names are copied from the vendored
+ * login app's own client components (`register-passkey.tsx`,
+ * `login-passkey.tsx`, `helpers/base64.ts`) -- ZITADEL is the judge of what
+ * it accepts, not the WebAuthn spec's own `toJSON`, and that app is what
+ * ZITADEL already accepts. Not a byte-for-byte port, though: a `null`
+ * `userHandle` (a non-discoverable credential need not carry one) is sent as
+ * `''` here (see `getPasskey` below), the same answer the login app's own
+ * `new Uint8Array(...)` pre-wrap already produces for the same input --
+ * `new Uint8Array(null)` is a zero-length view, not a throw -- but is not
+ * the byte a naive re-encoding of a `null` would produce.
+ */
+/** A record whose own shape nobody but the issuer needs to know; only the few fields below get touched. */
+type Loose = Record<string, unknown>;
+/** ZITADEL's `publicKeyCredentialCreationOptions`, wrapped in `publicKey` as the WebAuthn `CredentialCreationOptions` dictionary is. */
+export interface PasskeyCreationOptions {
+    publicKey: Loose & {
+        challenge: unknown;
+        user: Loose & {
+            id: unknown;
+        };
+        excludeCredentials?: Array<Loose & {
+            id: unknown;
+        }>;
+    };
+}
+/** ZITADEL's `publicKeyCredentialRequestOptions`, wrapped in `publicKey` as `CredentialRequestOptions` is. */
+export interface PasskeyRequestOptions {
+    publicKey: Loose & {
+        challenge: unknown;
+        allowCredentials?: Array<Loose & {
+            id: unknown;
+        }>;
+    };
+}
+/** What `verifyPasskeyRegistration` (ZITADEL, via the broker's `/passkey/register/finish`) accepts as `publicKeyCredential`. */
+export interface PasskeyCreationCredential {
+    id: string;
+    rawId: string;
+    type: string;
+    response: {
+        attestationObject: string;
+        clientDataJSON: string;
+    };
+}
+/** What `checkPasskey` (ZITADEL, via the broker's `/passkey/finish`) accepts as `credentialAssertionData`. */
+export interface PasskeyAssertionCredential {
+    id: string;
+    rawId: string;
+    type: string;
+    response: {
+        authenticatorData: string;
+        clientDataJSON: string;
+        signature: string;
+        userHandle: string;
+    };
+}
+/**
+ * Registers a passkey: decodes `options` (from `auth.startPasskeyRegistration`)
+ * into the `CredentialCreationOptions` the browser wants, calls
+ * `navigator.credentials.create`, and re-encodes the result for
+ * `auth.finishPasskeyRegistration`.
+ */
+export declare function createPasskey(options: PasskeyCreationOptions): Promise<PasskeyCreationCredential>;
+/**
+ * Signs in with a passkey: decodes `options` (from `auth.startPasskeySignIn`)
+ * into the `CredentialRequestOptions` the browser wants, calls
+ * `navigator.credentials.get`, and re-encodes the result for
+ * `auth.finishPasskeySignIn`.
+ */
+export declare function getPasskey(options: PasskeyRequestOptions): Promise<PasskeyAssertionCredential>;
+export {};

package/dist/passkey-browser.js

@@ -0,0 +1,150 @@
+/**
+ * The WebAuthn ceremony, for an app's own sign-in page: `createPasskey`
+ * answers `auth.startPasskeyRegistration`'s options, `getPasskey` answers
+ * `auth.startPasskeySignIn`'s. Both take the options JSON exactly as the
+ * broker hands it back -- ZITADEL's own `publicKeyCredentialCreationOptions`
+ * / `publicKeyCredentialRequestOptions`, base64url strings where the
+ * WebAuthn spec wants `ArrayBuffer`s and a `publicKey` wrapper around the
+ * rest -- and return a plain JSON-serialisable credential ready for
+ * `auth.finishPasskeyRegistration` / `auth.finishPasskeySignIn`.
+ *
+ * This is a browser file: no server import, nothing that would drag OIDC or
+ * cookie code into the client bundle. The base64url<->`ArrayBuffer`
+ * conversion and the credential's field names are copied from the vendored
+ * login app's own client components (`register-passkey.tsx`,
+ * `login-passkey.tsx`, `helpers/base64.ts`) -- ZITADEL is the judge of what
+ * it accepts, not the WebAuthn spec's own `toJSON`, and that app is what
+ * ZITADEL already accepts. Not a byte-for-byte port, though: a `null`
+ * `userHandle` (a non-discoverable credential need not carry one) is sent as
+ * `''` here (see `getPasskey` below), the same answer the login app's own
+ * `new Uint8Array(...)` pre-wrap already produces for the same input --
+ * `new Uint8Array(null)` is a zero-length view, not a throw -- but is not
+ * the byte a naive re-encoding of a `null` would produce.
+ */
+/** Base64url string, or an already-decoded `Array`/`Uint8Array`/`ArrayBuffer`, to `ArrayBuffer`. Mirrors the login app's `coerceToArrayBuffer`. */
+function coerceToArrayBuffer(value, name) {
+    let thing = value;
+    if (typeof thing === 'string') {
+        const base64 = thing.replace(/-/g, '+').replace(/_/g, '/');
+        const binary = atob(base64);
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i++)
+            bytes[i] = binary.charCodeAt(i);
+        thing = bytes;
+    }
+    if (Array.isArray(thing))
+        thing = new Uint8Array(thing);
+    if (thing instanceof Uint8Array)
+        thing = thing.buffer;
+    if (!(thing instanceof ArrayBuffer)) {
+        throw new TypeError(`@wtfalch/auth: could not coerce '${name}' to ArrayBuffer`);
+    }
+    return thing;
+}
+/** `ArrayBuffer`/`Uint8Array`/`Array` to a base64url string. Mirrors the login app's `coerceToBase64Url`. */
+function coerceToBase64Url(value, name) {
+    let thing = value;
+    if (Array.isArray(thing))
+        thing = Uint8Array.from(thing);
+    if (thing instanceof ArrayBuffer)
+        thing = new Uint8Array(thing);
+    if (thing instanceof Uint8Array) {
+        let str = '';
+        for (let i = 0; i < thing.byteLength; i++)
+            str += String.fromCharCode(thing[i]);
+        thing = btoa(str);
+    }
+    if (typeof thing !== 'string') {
+        throw new Error(`@wtfalch/auth: could not coerce '${name}' to string`);
+    }
+    return thing.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+/**
+ * Registers a passkey: decodes `options` (from `auth.startPasskeyRegistration`)
+ * into the `CredentialCreationOptions` the browser wants, calls
+ * `navigator.credentials.create`, and re-encodes the result for
+ * `auth.finishPasskeyRegistration`.
+ */
+export async function createPasskey(options) {
+    const source = options?.publicKey;
+    if (!source) {
+        throw new Error("@wtfalch/auth: passkey creation options have no 'publicKey'");
+    }
+    const publicKey = {
+        ...source,
+        challenge: coerceToArrayBuffer(source.challenge, 'challenge'),
+        user: { ...source.user, id: coerceToArrayBuffer(source.user.id, 'user.id') },
+        ...(Array.isArray(source.excludeCredentials)
+            ? {
+                excludeCredentials: source.excludeCredentials.map((cred) => ({
+                    ...cred,
+                    id: coerceToArrayBuffer(cred.id, 'excludeCredentials.id'),
+                })),
+            }
+            : {}),
+    };
+    const credential = (await navigator.credentials.create({
+        publicKey,
+    }));
+    if (!credential)
+        throw new Error('@wtfalch/auth: the browser returned no credential');
+    const response = credential.response;
+    return {
+        id: credential.id,
+        rawId: coerceToBase64Url(credential.rawId, 'rawId'),
+        type: credential.type,
+        response: {
+            attestationObject: coerceToBase64Url(response.attestationObject, 'attestationObject'),
+            clientDataJSON: coerceToBase64Url(response.clientDataJSON, 'clientDataJSON'),
+        },
+    };
+}
+/**
+ * Signs in with a passkey: decodes `options` (from `auth.startPasskeySignIn`)
+ * into the `CredentialRequestOptions` the browser wants, calls
+ * `navigator.credentials.get`, and re-encodes the result for
+ * `auth.finishPasskeySignIn`.
+ */
+export async function getPasskey(options) {
+    const source = options?.publicKey;
+    if (!source) {
+        throw new Error("@wtfalch/auth: passkey request options have no 'publicKey'");
+    }
+    const publicKey = {
+        ...source,
+        challenge: coerceToArrayBuffer(source.challenge, 'challenge'),
+        ...(Array.isArray(source.allowCredentials)
+            ? {
+                allowCredentials: source.allowCredentials.map((cred) => ({
+                    ...cred,
+                    id: coerceToArrayBuffer(cred.id, 'allowCredentials.id'),
+                })),
+            }
+            : {}),
+    };
+    const credential = (await navigator.credentials.get({
+        publicKey,
+    }));
+    if (!credential)
+        throw new Error('@wtfalch/auth: the browser returned no credential');
+    const response = credential.response;
+    // `new Uint8Array(x)` first, exactly as the login app does: a `null`
+    // `userHandle` (a non-discoverable credential need not carry one) becomes
+    // a zero-length view rather than a value `coerceToBase64Url` would refuse.
+    const authenticatorData = new Uint8Array(response.authenticatorData);
+    const clientDataJSON = new Uint8Array(response.clientDataJSON);
+    const rawId = new Uint8Array(credential.rawId);
+    const signature = new Uint8Array(response.signature);
+    const userHandle = new Uint8Array(response.userHandle ?? new ArrayBuffer(0));
+    return {
+        id: credential.id,
+        rawId: coerceToBase64Url(rawId, 'rawId'),
+        type: credential.type,
+        response: {
+            authenticatorData: coerceToBase64Url(authenticatorData, 'authenticatorData'),
+            clientDataJSON: coerceToBase64Url(clientDataJSON, 'clientDataJSON'),
+            signature: coerceToBase64Url(signature, 'signature'),
+            userHandle: coerceToBase64Url(userHandle, 'userHandle'),
+        },
+    };
+}