@wtfalch/auth 0.20.0 → 0.22.0

package/README.md

@@ -257,7 +257,7 @@ refresh token to begin with.
 | `appUrl` | This app's origin. Every URL the SDK builds starts here, never from the request's `Host`. |
 | `clientId` | The OIDC client for this origin. Each URL an app runs at is its own client, because the issuer holds one login URL per application. |
 | `organizationId` | Scopes every sign-in, and is checked on every token. |
-| `cookieSecret` | 32 bytes, `openssl rand -base64 32`. One per app. |
+| `cookieSecret` | 32 bytes, `openssl rand -base64 32`. **Each app needs its own** -- see below. |
 | `appKey` | This app's key for the sign-in service. Needed for anything that checks or creates a credential. |
 
 Values are read on first use rather than at import, so `next build` needs none
@@ -269,6 +269,13 @@ unset: the error waits until something actually reaches for the key. A secret
 that is *supplied and wrong* still throws at startup, because that is a typo
 rather than a deployment that does not need one.
 
+**Each app's `cookieSecret` must be its own, not shared with another app.**
+The AES key `cookies.ts` actually encrypts and decrypts with is HKDF-SHA256
+derived from `cookieSecret` using a fixed info string common to every
+consumer of this package -- two apps given the same `cookieSecret` would
+derive the identical key and could open each other's session cookies.
+Foundry already mints a distinct secret per app.
+
 ## What the app key can do
 
 It reaches the sign-in service, which holds ZITADEL's login client. Scoped to

package/dist/auth.d.ts

@@ -251,6 +251,18 @@ export interface Auth {
     }, requestHeaders?: Headers): Promise<SignedIn<SignInError> | (PasswordChangeRequired & {
         message: string;
     })>;
+    /**
+     * `signUp` as data, run over the same server-started transaction as
+     * `signInWithPassword` -- for a caller with no browser to carry through
+     * the OIDC redirect. Unlike `signUp`, which needs an `authRequestId` a
+     * browser flow already started with `start()`, this starts and finishes
+     * its own transaction, exactly as `signInWithPassword` does. Same two
+     * checks apply: an `ok: true` with an empty `cookies` means hosted
+     * login, and the cookie name is fixed.
+     */
+    signUpWithPassword(input: {
+        next?: string;
+    } & NewUser, requestHeaders?: Headers): Promise<SignedIn<SignUpError>>;
     /** Emails a fresh verification link. Says nothing about whether the address exists. */
     resendVerification(email: string, next?: string): Promise<void>;
     /** Emails a password-reset link to {basePath}/reset?userId=&code=. Says nothing about whether the address exists. */
@@ -280,6 +292,20 @@ export interface Auth {
         invited: boolean;
         personalEmailStored: boolean;
     }>;
+    /**
+     * A company's own test user: a new person, marked in the sign-in service
+     * so nothing it does is read as a real customer. Refused for an address
+     * that already has a user, and for an entry that acts as another (stage,
+     * a laptop) -- a test user is made from production's entry.
+     */
+    createTestUser(input: {
+        email: string;
+        givenName: string;
+        familyName: string;
+        username?: string;
+    }): Promise<{
+        userId: string;
+    }>;
     handle(request: Request): Promise<Response>;
     /**
      * `refresh: false` for callers that cannot set cookies; they get a user only while the token is valid.

package/dist/auth.js

@@ -539,6 +539,11 @@ export function createAuth(input) {
         emit({ type: 'invite', email: input.email, userId: result.userId, invited: result.invited });
         return result;
     };
+    const createTestUser = async (input) => {
+        const result = await broker().createTestUser(input);
+        emit({ type: 'createTestUser', email: input.email, userId: result.userId });
+        return result;
+    };
     /**
      * An admin's reset for somebody in this app's own organisation whom
      * `requestPasswordReset` cannot otherwise get back in -- nobody at the
@@ -670,6 +675,36 @@ export function createAuth(input) {
             return { ok: false, error: code, message };
         }
     };
+    const signUpWithPassword = async ({ next, ...user }, requestHeaders) => {
+        try {
+            const flow = await serverFlow();
+            const completed = await finishOrHandoff(() => broker().signUp({ authRequestId: flow.id, ...user }), flow, safeNextPath(next, options().afterLogin), requestHeaders);
+            emit({ type: 'signUp', email: user.email });
+            return { ok: true, ...completed };
+        }
+        catch (error) {
+            if (error instanceof BrokerError && error.error === 'email_taken') {
+                return { ok: false, error: 'email_taken', message: error.detail ?? error.error };
+            }
+            if (error instanceof BrokerError && error.error === 'registration_closed') {
+                return { ok: false, error: 'registration_closed', message: error.detail ?? error.error };
+            }
+            // Both carry a sentence about the name, for the form to show as it is.
+            if (error instanceof BrokerError && error.error === 'username_taken') {
+                return { ok: false, error: 'username_taken', message: error.detail ?? error.error };
+            }
+            if (error instanceof BrokerError && error.error === 'username_invalid') {
+                return { ok: false, error: 'username_invalid', message: error.detail ?? error.error };
+            }
+            if (error instanceof BrokerError && error.error === 'request') {
+                return { ok: false, error: 'request', message: error.detail ?? error.error };
+            }
+            if (error instanceof BrokerError && error.status < 500) {
+                return { ok: false, error: 'invalid', message: error.detail ?? error.error };
+            }
+            return { ok: false, error: 'unavailable', message: 'the sign-in service did not answer' };
+        }
+    };
     const signUp = async ({ authRequestId, ...user }) => {
         try {
             const redirectTo = await broker().signUp({ authRequestId, ...user });
@@ -936,6 +971,7 @@ export function createAuth(input) {
         resetPassword,
         sendLink,
         invite,
+        createTestUser,
         handle,
         read,
         readCookie,
@@ -954,6 +990,7 @@ export function createAuth(input) {
         setNewPassword,
         setNewPasswordHeadless,
         signInWithPassword,
+        signUpWithPassword,
         signUp,
         startPasskeyRegistration,
         finishPasskeyRegistration,

package/dist/broker.d.ts

@@ -137,6 +137,15 @@ export declare class Broker {
         personalEmailStored: boolean;
     }>;
     sendLink(email: string, next: string): Promise<unknown>;
+    /** A company's own test user, marked in the sign-in service. See `Auth['createTestUser']`. */
+    createTestUser(input: {
+        email: string;
+        givenName: string;
+        familyName: string;
+        username?: string;
+    }): Promise<{
+        userId: string;
+    }>;
     sendReset(email: string, next: string): Promise<unknown>;
     sendVerification(email: string, next: string): Promise<unknown>;
     /**

package/dist/broker.js

@@ -118,6 +118,10 @@ export class Broker {
     sendLink(email, next) {
         return this.call('POST', '/link/send', { email, next });
     }
+    /** A company's own test user, marked in the sign-in service. See `Auth['createTestUser']`. */
+    createTestUser(input) {
+        return this.call('POST', '/test-users', input);
+    }
     sendReset(email, next) {
         return this.call('POST', '/reset/send', { email, next });
     }

package/dist/browser.js

@@ -1,6 +1,10 @@
 import { createNamespaceBrowserAuth } from './namespace-browser.js';
 const TOKEN = 'wtfalch.auth.token';
 const VERIFIER = 'wtfalch.auth.verifier';
+/** CSRF protection on the callback: checked before the code exchange, never persisted past it. */
+const STATE = 'wtfalch.auth.state';
+/** Replay protection on the ID token: checked against its own claim after the exchange, never persisted past it. */
+const NONCE = 'wtfalch.auth.nonce';
 const RETURN = 'wtfalch.auth.return';
 /** Set before a silent attempt leaves, so a refusal cannot become a loop. */
 const TRIED = 'wtfalch.auth.silent-tried';
@@ -44,9 +48,26 @@ async function challengeFor(verifier) {
 }
 function verifier() {
     // 32 bytes is RFC 7636's recommendation; base64url of it is 43 characters,
-    // inside the 43..128 the spec allows.
+    // inside the 43..128 the spec allows. Reused below for `state` and `nonce`
+    // too -- a random, unguessable token is exactly what each of the three is.
     return base64url(crypto.getRandomValues(new Uint8Array(32)).buffer);
 }
+/** The payload of a JWT, read without verifying its signature -- the ID token here comes straight
+ *  from the token endpoint over TLS, which OIDC Core 1.0 3.1.3.7 allows in place of a signature
+ *  check for the authorization code flow. Never used to trust a claim from anywhere else. */
+function decodeJwtPayload(jwt) {
+    try {
+        const part = jwt.split('.')[1];
+        if (!part)
+            return null;
+        const base64 = part.replace(/-/g, '+').replace(/_/g, '/');
+        const padded = base64 + '='.repeat((4 - (base64.length % 4)) % 4);
+        return JSON.parse(atob(padded));
+    }
+    catch {
+        return null;
+    }
+}
 function publicSession(session) {
     const { refreshToken, ...rest } = session;
     return rest;
@@ -86,6 +107,8 @@ export function createBrowserAuth(options) {
     const key = (name) => (context ? `wtfalch.auth.browser.v1:${context}:${name}` : name);
     const tokenKey = key(TOKEN);
     const verifierKey = key(VERIFIER);
+    const stateKey = key(STATE);
+    const nonceKey = key(NONCE);
     const returnKey = key(RETURN);
     const triedKey = key(TRIED);
     let contexts = coordinators.get(store);
@@ -117,6 +140,8 @@ export function createBrowserAuth(options) {
     const authorize = async (prompt, returnTo) => {
         const generation = ++coordinator.generation;
         const proof = verifier();
+        const state = verifier();
+        const nonce = verifier();
         await mutate(async () => {
             if (!current(generation))
                 return;
@@ -127,6 +152,12 @@ export function createBrowserAuth(options) {
             if (!current(generation))
                 return;
             await store.set(verifierKey, proof);
+            if (!current(generation))
+                return;
+            await store.set(stateKey, state);
+            if (!current(generation))
+                return;
+            await store.set(nonceKey, nonce);
             if (!current(generation))
                 return;
             await store.set(returnKey, returnTo);
@@ -140,6 +171,8 @@ export function createBrowserAuth(options) {
         url.searchParams.set('scope', scope);
         url.searchParams.set('code_challenge', await challengeFor(proof));
         url.searchParams.set('code_challenge_method', 'S256');
+        url.searchParams.set('state', state);
+        url.searchParams.set('nonce', nonce);
         if (prompt)
             url.searchParams.set('prompt', prompt);
         if (!current(generation))
@@ -240,16 +273,27 @@ export function createBrowserAuth(options) {
                 if (!current(generation))
                     return null;
                 const proof = store.get(verifierKey);
+                const expectedState = store.get(stateKey);
+                const expectedNonce = store.get(nonceKey);
                 const returnTo = store.get(returnKey) ?? '/';
+                // Cleared together, unconditionally, before any check below runs --
+                // a mismatch is refused on its own terms, not merely by virtue of a
+                // transaction that cannot be replayed a second time either way.
                 await store.drop(verifierKey);
+                if (!current(generation))
+                    return null;
+                await store.drop(stateKey);
+                if (!current(generation))
+                    return null;
+                await store.drop(nonceKey);
                 if (!current(generation))
                     return null;
                 await store.drop(returnKey);
-                return { proof, returnTo };
+                return { proof, expectedState, expectedNonce, returnTo };
             });
             if (!transaction || !current(generation))
                 return cancelled();
-            const { proof, returnTo } = transaction;
+            const { proof, expectedState, expectedNonce, returnTo } = transaction;
             const issuerError = params.get('error');
             if (issuerError) {
                 if (['login_required', 'interaction_required', 'consent_required'].includes(issuerError)) {
@@ -257,6 +301,13 @@ export function createBrowserAuth(options) {
                 }
                 return { kind: 'error', error: params.get('error_description') ?? issuerError };
             }
+            // Checked before the code exchange: a callback whose `state` does not
+            // match this tab's own sign-in is refused before it ever reaches the
+            // issuer, exactly as a cross-site request forgery on this callback
+            // would need it not to be.
+            if (params.get('state') !== expectedState) {
+                return { kind: 'error', error: 'the callback state does not match this sign-in' };
+            }
             const code = params.get('code');
             if (!code)
                 return { kind: 'error', error: 'the issuer sent no code' };
@@ -293,6 +344,14 @@ export function createBrowserAuth(options) {
                     return cancelled();
                 if (!token.access_token)
                     return { kind: 'error', error: 'the issuer returned no access token' };
+                // Checked against the ID token's own claim, after the exchange: a
+                // code this flow never requested cannot be replayed into a session
+                // here even if it were otherwise accepted, because the token minted
+                // for it carries a different nonce.
+                const idTokenClaims = token.id_token ? decodeJwtPayload(token.id_token) : null;
+                if (idTokenClaims?.nonce !== expectedNonce) {
+                    return { kind: 'error', error: 'the ID token nonce does not match this sign-in' };
+                }
                 const session = {
                     accessToken: token.access_token,
                     expiresAt: Date.now() + (token.expires_in ?? 3600) * 1000,
@@ -326,6 +385,8 @@ export function createBrowserAuth(options) {
             await mutate(async () => {
                 await store.drop(tokenKey);
                 await store.drop(verifierKey);
+                await store.drop(stateKey);
+                await store.drop(nonceKey);
                 await store.drop(returnKey);
                 await store.set(triedKey, '1');
             });

package/dist/config.d.ts

@@ -24,6 +24,10 @@ export type AuthEvent = {
  | {
     type: 'adminResetPassword';
     userId: string;
+} | {
+    type: 'createTestUser';
+    email: string;
+    userId: string;
 };
 /**
  * Why `accessToken` refused: no session (no cookie in cookie mode, no live
@@ -158,3 +162,14 @@ export interface ResolvedOptions {
     onAuthEvent: ((event: AuthEvent) => void) | null;
 }
 export declare function resolveOptions(options: AuthOptions): ResolvedOptions;
+/**
+ * The actual AES-256 key `cookies.ts` encrypts and decrypts with -- HKDF-SHA256
+ * over the decoded `cookieSecret`, never the secret's bytes directly. A secret an
+ * operator can read (an env var, a value pasted into a terminal) is weaker key
+ * material than a key meant to be used as one; HKDF's job is exactly this gap.
+ * No fallback to the raw key: decided as a hard cut (auth#255), so the only
+ * way a cookie sealed before this shipped keeps validating is if it already
+ * carries no more than its own session's worth of trust -- which is what every
+ * cookie here already assumes of `sessionMaxAge`/`TRANSACTION_TTL`/etc.
+ */
+export declare function deriveCookieKey(secret: Uint8Array): Promise<Uint8Array>;

package/dist/config.js

@@ -105,3 +105,29 @@ function decodeKey(secret) {
     }
     return bytes;
 }
+// Fixed, not random: every server sealing or opening a cookie must derive
+// the same AES key from the same `cookieSecret`, so there is nowhere to
+// store a per-process salt even if one were generated. `COOKIE_KEY_INFO`
+// scopes the derivation to this one use of the secret, the same way a
+// derived key's `info` is meant to -- a future second use of `cookieSecret`
+// (there is none today) would derive under a different info string and
+// never collide with this key.
+const COOKIE_KEY_SALT = new TextEncoder().encode('@wtfalch/auth cookie salt v1');
+const COOKIE_KEY_INFO = new TextEncoder().encode('@wtfalch/auth cookie v1');
+/**
+ * The actual AES-256 key `cookies.ts` encrypts and decrypts with -- HKDF-SHA256
+ * over the decoded `cookieSecret`, never the secret's bytes directly. A secret an
+ * operator can read (an env var, a value pasted into a terminal) is weaker key
+ * material than a key meant to be used as one; HKDF's job is exactly this gap.
+ * No fallback to the raw key: decided as a hard cut (auth#255), so the only
+ * way a cookie sealed before this shipped keeps validating is if it already
+ * carries no more than its own session's worth of trust -- which is what every
+ * cookie here already assumes of `sessionMaxAge`/`TRANSACTION_TTL`/etc.
+ */
+export async function deriveCookieKey(secret) {
+    const keyMaterial = await crypto.subtle.importKey('raw', secret, 'HKDF', false, [
+        'deriveBits',
+    ]);
+    const bits = await crypto.subtle.deriveBits({ name: 'HKDF', hash: 'SHA-256', salt: COOKIE_KEY_SALT, info: COOKIE_KEY_INFO }, keyMaterial, 256);
+    return new Uint8Array(bits);
+}

package/dist/cookies.d.ts

@@ -1,5 +1,7 @@
 import { type JWTPayload } from 'jose';
-import type { ResolvedOptions } from './config.js';
+import { type ResolvedOptions } from './config.js';
+/** Exported for `namespace-server.ts`, which decrypts a transaction cookie itself to read its `ns` claim before any binding is chosen. */
+export declare function cookieKeyFor(options: ResolvedOptions): Promise<Uint8Array>;
 export interface SessionPayload extends JWTPayload {
     idt: string;
     rt?: string;

package/dist/cookies.js

@@ -1,5 +1,21 @@
 import { EncryptJWT, jwtDecrypt } from 'jose';
+import { deriveCookieKey } from './config.js';
 import { AuthError } from './oidc.js';
+// `options.cookieKey` decodes once per `ResolvedOptions` (config.ts) and is
+// always the same `Uint8Array` reference after that, so keying the derived
+// key's own cache off it means every seal/open after the first reuses it
+// rather than re-running HKDF per call.
+const derivedKeyCache = new WeakMap();
+/** Exported for `namespace-server.ts`, which decrypts a transaction cookie itself to read its `ns` claim before any binding is chosen. */
+export function cookieKeyFor(options) {
+    const raw = options.cookieKey;
+    let derived = derivedKeyCache.get(raw);
+    if (!derived) {
+        derived = deriveCookieKey(raw);
+        derivedKeyCache.set(raw, derived);
+    }
+    return derived;
+}
 const SESSION = 'wtfalch_auth';
 const TRANSACTION = 'wtfalch_auth_tx';
 const LINK = 'wtfalch_auth_link';
@@ -152,17 +168,21 @@ async function seal(options, kind, payload, ttl) {
         .setAudience(await audience(options, kind))
         .setIssuedAt()
         .setExpirationTime(Math.floor(Date.now() / 1000) + ttl)
-        .encrypt(options.cookieKey);
+        .encrypt(await cookieKeyFor(options));
 }
 async function open(options, kind, value) {
     if (!value)
         return null;
     try {
-        const { payload } = await jwtDecrypt(value, options.cookieKey, {
+        const { payload } = await jwtDecrypt(value, await cookieKeyFor(options), {
             issuer: options.appUrl.origin,
             audience: await audience(options, kind),
             contentEncryptionAlgorithms: ['A256GCM'],
             keyManagementAlgorithms: ['dir'],
+            // Every cookie `seal` makes already sets `exp` (the call's own `ttl`),
+            // so requiring it here signs nobody out -- it only refuses the one
+            // thing a cookie with none could otherwise be: unbounded.
+            requiredClaims: ['exp'],
         });
         return payload;
     }

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { type Auth, type AuthRequest, type Gate, type GateRules, type Intent, ty
 export type { AccessTokenReason, AccessTokenResult, AuthEvent, AuthOptions } from './config.js';
 export type { SetCookie } from './cookies.js';
 export type { SessionRecord, SessionStore, SessionUpdate } from './sessions.js';
+export type { PersonTokenConfig, PersonTokenVerifier } from './person-token.js';
 export { BrokerError } from './broker.js';
 export { AuthError, type AuthErrorReason, ORG_CLAIM } from './oidc.js';
 export { safeNextPath } from './redirect.js';

package/dist/namespace-server.js

@@ -1,6 +1,6 @@
 import { jwtDecrypt } from 'jose';
 import { resolveOptions } from './config.js';
-import { cookieFrom, openTransaction, transactionCookieName } from './cookies.js';
+import { cookieFrom, cookieKeyFor, openTransaction, transactionCookieName } from './cookies.js';
 import { isWebService, parseNamespaceRegistry, } from './namespaces.js';
 /** Resolve a shared callback from its authenticated transaction, never a URL
  * namespace hint. The second open checks the entire current registry binding. */
@@ -46,7 +46,7 @@ export async function resolveNamespaceCallback(input) {
             return null;
         // No identity is returned based on this hint alone. It only chooses which
         // current binding's audience to validate next, so decryption is bounded.
-        const { payload } = await jwtDecrypt(value, first.cookieKey, {
+        const { payload } = await jwtDecrypt(value, await cookieKeyFor(first), {
             issuer: input.appOrigin,
             requiredClaims: ['exp', 'iat', 'aud'],
             contentEncryptionAlgorithms: ['A256GCM'],

package/dist/namespace-session.js

@@ -1,3 +1,4 @@
+import { sleep } from '@wtfalch/utils/datetime';
 import * as client from 'openid-client';
 import { BrokerError } from './broker.js';
 import { contextDigest, digest, openHandle, openRecord, sealHandle, sealRecord, } from './cookies.js';
@@ -15,7 +16,6 @@ const LEASE_SECONDS = 60;
 const WAIT_STEP_MS = 100;
 const WAIT_STEPS = 50;
 const now = () => Math.floor(Date.now() / 1000);
-const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /**
  * Server-side sessions for namespace mode. The cookie holds a random handle;
  * the record holds the tokens. Refreshes are serialised across replicas by a

package/dist/person-token.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Verifies a signed-in person's own `@wtfalch/auth`/ZITADEL access token,
+ * server-side, for a service that wants to accept one directly rather than
+ * only a machine credential. Two token shapes, both checked:
+ *
+ * - A JWT (three base64url segments): `jwtVerify` against a remote JWKS
+ *   built from the issuer's discovery document -- signature (RS256),
+ *   issuer, audience, expiry. `jose`'s `createRemoteJWKSet` refetches on an
+ *   unrecognised `kid` on its own, so key rotation needs nothing here
+ *   beyond the cooldown below.
+ * - Anything else: RFC 7662 introspection against the issuer's
+ *   `introspection_endpoint`, authenticating as this resource server with
+ *   `client_secret_basic` (`introspectionClientId`/`Secret`), checking the
+ *   response's `active`, `exp` and `aud`. Not attempted -- refused outright
+ *   -- when either credential is unset, the same as an opaque token would
+ *   have refused before introspection existed. This matters because some
+ *   apps mint an *opaque* access token on purpose, and without this path no
+ *   such token could ever reach a server that only checked JWTs.
+ *
+ * Neither path checks a fixed ZITADEL organisation: a caller can come from
+ * any organisation's app, so there is nothing fixed to compare against.
+ * This module only answers "is this a live token, and whose" -- membership
+ * and authorization are the caller's own concern, same as for a machine
+ * credential.
+ *
+ * A network failure or a non-2xx from either the discovery document or the
+ * introspection endpoint fails closed: `verify` returns `null`, exactly
+ * like a bad token, never treated as good. There is no second outcome for
+ * "could not check" versus "checked and refused" -- a caller has only one
+ * response to either, refuse.
+ */
+export interface PersonTokenVerifier {
+    /** The token's subject (`sub`), or null for anything that does not stand
+     *  up: bad signature, wrong issuer/audience, expired, inactive, or
+     *  unreachable. Refusals never say which. */
+    verify(accessToken: string): Promise<{
+        sub: string;
+    } | null>;
+}
+export interface PersonTokenConfig {
+    /** The issuer every token must have been minted by, e.g.
+     *  `https://auth.wtfalch.dev`. */
+    issuer: string;
+    /** The ZITADEL project id a person's token must carry in `aud` --
+     *  requested by whatever app mints the token (an `extraScopes` entry of
+     *  `urn:zitadel:iam:org:project:id:<audience>:aud`). */
+    audience: string;
+    /** This resource server's own credentials at the issuer, for RFC 7662
+     *  introspection of an opaque (non-JWT) access token --
+     *  `client_secret_basic`. Both required together; either absent disables
+     *  introspection and an opaque bearer is refused outright. */
+    introspectionClientId?: string;
+    introspectionClientSecret?: string;
+    /** Test seam; a live deployment never sets this. */
+    fetch?: typeof fetch;
+    /** jose's default 30s would keep rejecting a token signed with a freshly
+     *  rotated key for that long; a test passes 0 so it need not sleep past a
+     *  real cooldown. */
+    jwksCooldownMs?: number;
+}
+export declare function createPersonTokenVerifier(config: PersonTokenConfig): PersonTokenVerifier;

package/dist/person-token.js

@@ -0,0 +1,191 @@
+import { createRemoteJWKSet, customFetch, jwtVerify } from 'jose';
+/** A JWT is three base64url segments; a ZITADEL opaque token is not shaped
+ *  like that at all, so this is enough to route between `jwtVerify` and
+ *  introspection without ever trying to parse either kind as the other. */
+const JWT_SHAPE = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+/** How long a positive introspection result is trusted before this host
+ *  checks again -- bounded well under the token's own `exp` so a revoked
+ *  token can't outlive a ZITADEL-side revocation for long. */
+const INTROSPECTION_CACHE_TTL_MS = 60_000;
+/** An optional endpoint from the discovery document, required to be on the
+ *  issuer's own origin -- a compromised or misconfigured discovery
+ *  response must never point signature checking, or a token's liveness,
+ *  at somebody else's server. */
+function sameOriginEndpoint(value, name, issuerOrigin) {
+    if (value === undefined)
+        return null;
+    if (typeof value !== 'string')
+        throw new Error(`person-token: ${name} is not a string`);
+    if (new URL(value).origin !== issuerOrigin)
+        throw new Error(`person-token: ${name} origin does not match the issuer`);
+    return value;
+}
+async function discoverDocument(issuer, fetchImpl) {
+    const discoveryUrl = `${issuer.replace(/\/$/, '')}/.well-known/openid-configuration`;
+    const issuerOrigin = new URL(issuer).origin;
+    const response = await fetchImpl(discoveryUrl);
+    if (!response.ok) {
+        throw new Error(`person-token: discovery document request failed with ${response.status}`);
+    }
+    const doc = (await response.json());
+    if (typeof doc.jwks_uri !== 'string') {
+        throw new Error('person-token: the issuer publishes no jwks_uri');
+    }
+    if (new URL(doc.jwks_uri).origin !== issuerOrigin) {
+        throw new Error('person-token: jwks_uri origin does not match the issuer');
+    }
+    return {
+        jwksUri: doc.jwks_uri,
+        introspectionEndpoint: sameOriginEndpoint(doc.introspection_endpoint, 'introspection_endpoint', issuerOrigin),
+    };
+}
+/**
+ * A size-bounded, least-recently-used, TTL cache for a positive
+ * introspection result only -- a refusal is never cached, so a transient
+ * issuer problem never sticks as "no" for whatever is left of the entry's
+ * life. Bounded so a flood of distinct garbage tokens cannot grow it
+ * without limit.
+ */
+class PositiveIntrospectionCache {
+    max;
+    entries = new Map();
+    constructor(max = 1000) {
+        this.max = max;
+    }
+    get(token, now) {
+        const entry = this.entries.get(token);
+        if (!entry)
+            return null;
+        if (entry.expiresAt <= now) {
+            this.entries.delete(token);
+            return null;
+        }
+        // Refresh recency: delete-then-set moves it to the end of the Map's
+        // iteration order, which eviction below reads from the front.
+        this.entries.delete(token);
+        this.entries.set(token, entry);
+        return entry.payload;
+    }
+    set(token, payload, expiresAt) {
+        this.entries.delete(token);
+        if (this.entries.size >= this.max) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest !== undefined)
+                this.entries.delete(oldest);
+        }
+        this.entries.set(token, { payload, expiresAt });
+    }
+}
+export function createPersonTokenVerifier(config) {
+    const fetchImpl = config.fetch ?? fetch;
+    let discovery = null;
+    let jwks = null;
+    const introspectionCache = new PositiveIntrospectionCache();
+    const document = () => {
+        discovery ??= discoverDocument(config.issuer, fetchImpl).catch((error) => {
+            discovery = null;
+            throw error;
+        });
+        return discovery;
+    };
+    const keys = () => {
+        jwks ??= document()
+            .then((doc) => createRemoteJWKSet(new URL(doc.jwksUri), {
+            cooldownDuration: config.jwksCooldownMs ?? 5_000,
+            [customFetch]: (url, init) => fetchImpl(url, init),
+        }))
+            .catch((error) => {
+            jwks = null;
+            throw error;
+        });
+        return jwks;
+    };
+    async function verifyJwt(accessToken) {
+        try {
+            const keyset = await keys();
+            const { payload } = await jwtVerify(accessToken, keyset, {
+                issuer: config.issuer,
+                audience: config.audience,
+                algorithms: ['RS256'],
+                clockTolerance: 60,
+            });
+            return payload;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * RFC 7662 token introspection for an opaque access token: POSTs
+     * `token=<accessToken>` to the issuer's `introspection_endpoint`,
+     * authenticating as this resource server with `client_secret_basic`.
+     * Fails closed on anything that keeps this from reaching a real
+     * `active`/`exp`/`aud` verdict: no credentials configured, no endpoint
+     * published, a network failure, a non-2xx response, or an unparseable
+     * body -- every one of those returns `null`, refused, never accepted.
+     */
+    async function introspect(accessToken) {
+        if (!config.introspectionClientId || !config.introspectionClientSecret)
+            return null;
+        const now = Date.now();
+        const cached = introspectionCache.get(accessToken, now);
+        if (cached)
+            return cached;
+        let endpoint;
+        try {
+            ({ introspectionEndpoint: endpoint } = await document());
+        }
+        catch {
+            return null;
+        }
+        if (!endpoint)
+            return null;
+        const credentials = Buffer.from(`${config.introspectionClientId}:${config.introspectionClientSecret}`).toString('base64');
+        let response;
+        try {
+            response = await fetchImpl(endpoint, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/x-www-form-urlencoded',
+                    authorization: `Basic ${credentials}`,
+                },
+                body: new URLSearchParams({ token: accessToken }).toString(),
+            });
+        }
+        catch {
+            return null;
+        }
+        if (!response.ok)
+            return null;
+        let body;
+        try {
+            body = (await response.json());
+        }
+        catch {
+            return null;
+        }
+        if (body.active !== true)
+            return null;
+        if (typeof body.exp !== 'number' || body.exp <= now / 1000)
+            return null;
+        const aud = body.aud;
+        const audiences = Array.isArray(aud) ? aud : aud === undefined ? [] : [aud];
+        if (!audiences.includes(config.audience))
+            return null;
+        if (typeof body.iss === 'string' && body.iss !== config.issuer)
+            return null;
+        const payload = body;
+        introspectionCache.set(accessToken, payload, Math.min(body.exp * 1000, now + INTROSPECTION_CACHE_TTL_MS));
+        return payload;
+    }
+    return {
+        async verify(accessToken) {
+            const payload = JWT_SHAPE.test(accessToken)
+                ? await verifyJwt(accessToken)
+                : await introspect(accessToken);
+            if (!payload || typeof payload.sub !== 'string' || !payload.sub)
+                return null;
+            return { sub: payload.sub };
+        },
+    };
+}

package/dist/qr-door-scene.d.ts

@@ -0,0 +1,66 @@
+export type QrDoorMark = 'agora' | 'boule' | 'archon';
+export interface QrDoorTheme {
+    ink: string;
+    accent: string;
+    paper: string;
+}
+export declare const QR_DOOR_THEME: QrDoorTheme;
+/** Side of the logical drawing space. */
+export declare const QR_DOOR_SIZE = 360;
+/** Half-width of the clearing the doorway sits in. */
+export declare const QR_DOOR_CLEARING = 25;
+/** Largest QR version allowed: version 7 and up put an alignment pattern dead centre, under the door. */
+export declare const QR_DOOR_MAX_VERSION = 6;
+/** Length of the approval animation. */
+export declare const QR_DOOR_DURATION: number;
+export interface QrDoorPoint {
+    x: number;
+    y: number;
+}
+export interface QrDoorPiece {
+    /** Index into `dots` of the module that lifts out. */
+    src: number;
+    sx: number;
+    sy: number;
+    tx: number;
+    ty: number;
+    /** Delay before it lifts, seconds. */
+    dl: number;
+}
+export interface QrDoorScene {
+    mark: QrDoorMark;
+    /** The error-correction level used, highest that keeps the version at or under `QR_DOOR_MAX_VERSION`. */
+    errorCorrection: 'Q' | 'M' | 'L';
+    version: number;
+    /** Modules per side, and module size in logical px. */
+    modules: number;
+    moduleSize: number;
+    /** Dark data modules, finders and the clearing left out. */
+    dots: QrDoorPoint[];
+    /** Centres of the three finder eyes. */
+    finders: QrDoorPoint[];
+    pieces: QrDoorPiece[];
+    camera: {
+        Zg: number;
+        zg: number;
+        Dp: number;
+        kk: number;
+        zf: number;
+        t1: number;
+    };
+}
+/**
+ * Builds the scene for `url` (the device grant's verification URL). Tries
+ * error correction Q, then M, then L, keeping the first that fits in version 6.
+ * The clearing knocks out about 3% of modules, well inside even L's 7%.
+ * Throws a `RangeError` for a URL too long for version 6 at any level.
+ */
+export declare function buildQrDoorScene(url: string, mark: QrDoorMark): QrDoorScene;
+/** Icon size (logical px) at time `t` after approval. Continuous by construction. */
+export declare function qrDoorIconSize(scene: QrDoorScene, t: number): number;
+type Ctx = CanvasRenderingContext2D;
+/** The code at rest, waiting for the phone. */
+export declare function drawQrDoorRest(c: Ctx, s: QrDoorScene, th?: QrDoorTheme): void;
+/** The frame `t` seconds after approval; `t` is clamped to `[0, QR_DOOR_DURATION]`. */
+export declare function drawQrDoorScene(c: Ctx, s: QrDoorScene, time: number, th?: QrDoorTheme): void;
+export {};

package/dist/qr-door-scene.js

@@ -0,0 +1,404 @@
+/**
+ * "The code builds the door": the QR sign-in code, and the short animation it
+ * plays once the phone approves. Framework-free canvas drawing; `./qr-door`
+ * wraps it in a React component.
+ *
+ * At rest it is an ordinary, scannable QR code for the device grant's `url`
+ * with a small clearing in the middle. On approval, modules lift out of the
+ * code and land on the outline of the app's mark, the solid line traces in
+ * behind them, a person (the mark's red dot) steps into the doorway, and one
+ * perspective camera move carries you through it to the app's icon.
+ *
+ * Everything is drawn in a fixed 360×360 logical space; the caller sets the
+ * canvas transform for its size and devicePixelRatio. `buildQrDoorScene` does
+ * the one-off work (QR matrix, which module flies where, the camera solve) and
+ * is plain data, safe on a server. `drawQrDoorRest` and `drawQrDoorScene` need
+ * a canvas and are a pure function of (scene, t): scrub, test or freeze them.
+ *
+ * Browser file for drawing: nothing here touches OIDC, cookies or `node:`.
+ */
+import QRCode from 'qrcode';
+const MARKS = {
+    agora: {
+        d: 'M5.6 18.2V12.6a6.4 6.4 0 0 1 12.8 0V18.2',
+        dot: [12, 15.1],
+        len: 31.3,
+        hc: [12, 13.4],
+        hr: 5.2,
+        segs: [
+            ['L', 5.6, 18.2, 5.6, 12.6],
+            ['A', 12, 12.6, 6.4, 180, 360],
+            ['L', 18.4, 12.6, 18.4, 18.2],
+        ],
+        hole: 'M7.3 18.2V12.6a4.7 4.7 0 0 1 9.4 0V18.2Z',
+    },
+    boule: {
+        d: 'M8.6 17.89A6.8 6.8 0 1 1 15.4 17.89',
+        dot: [12, 12],
+        len: 35.6,
+        hc: [12, 12],
+        hr: 5.1,
+        segs: [['A', 12, 12, 6.8, 120, 420]],
+        hole: 'M6.9 12a5.1 5.1 0 1 0 10.2 0a5.1 5.1 0 1 0 -10.2 0Z',
+    },
+    archon: {
+        d: 'M9.3 19.28A5.4 5.4 0 1 1 14.7 19.28',
+        dot: [12, 4.3],
+        len: 28.3,
+        hc: [12, 14.6],
+        hr: 3.7,
+        segs: [['A', 12, 14.6, 5.4, 120, 420]],
+        hole: 'M8.3 14.6a3.7 3.7 0 1 0 7.4 0a3.7 3.7 0 1 0 -7.4 0Z',
+    },
+};
+export const QR_DOOR_THEME = { ink: '#1D1B16', accent: '#B23A0C', paper: '#F6F3EC' };
+/* ---------- geometry (logical px) ---------- */
+/** Side of the logical drawing space. */
+export const QR_DOOR_SIZE = 360;
+const L = QR_DOOR_SIZE;
+const C0 = L / 2;
+const CODE = 290;
+const O = (L - CODE) / 2;
+const ICON = 228;
+const TAU = Math.PI * 2;
+/** Icon units to px for the doorway drawn in the code. */
+const S1 = 2.9;
+/** Half-width of the clearing the doorway sits in. */
+export const QR_DOOR_CLEARING = 25;
+/** Icon size when first seen through the doorway, and the instant the doorway clears the stage. */
+const START = 9;
+const S0 = 88;
+/** Finder-eye corner rounding. Above about 0.5 strict decoders stop finding the eyes. */
+const EYE_ROUND = 0.4;
+/** Largest QR version allowed: version 7 and up put an alignment pattern dead centre, under the door. */
+export const QR_DOOR_MAX_VERSION = 6;
+/* ---------- timeline (seconds after approval) ---------- */
+const WALK = 0.95;
+const DOLLY = 1.55;
+/** Length of the approval animation. */
+export const QR_DOOR_DURATION = WALK + DOLLY + 0.3;
+/* ---------- easing ---------- */
+const clamp = (v, a = 0, b = 1) => (v < a ? a : v > b ? b : v);
+const seg = (u, a, b) => clamp((u - a) / (b - a));
+const lerp = (a, b, t) => a + (b - a) * t;
+const io = (t) => (t < 0.5 ? 4 * t * t * t : 1 - (-2 * t + 2) ** 3 / 2);
+const sine = (t) => -(Math.cos(Math.PI * t) - 1) / 2;
+const back = (t) => 1 + 2.5 * (t - 1) ** 3 + 1.5 * (t - 1) ** 2;
+/**
+ * Builds the scene for `url` (the device grant's verification URL). Tries
+ * error correction Q, then M, then L, keeping the first that fits in version 6.
+ * The clearing knocks out about 3% of modules, well inside even L's 7%.
+ * Throws a `RangeError` for a URL too long for version 6 at any level.
+ */
+export function buildQrDoorScene(url, mark) {
+    const geo = MARKS[mark];
+    let qr = null;
+    let errorCorrection = 'Q';
+    for (const level of ['Q', 'M', 'L']) {
+        const candidate = QRCode.create(url, { errorCorrectionLevel: level });
+        if (candidate.version <= QR_DOOR_MAX_VERSION) {
+            qr = candidate;
+            errorCorrection = level;
+            break;
+        }
+    }
+    if (!qr) {
+        throw new RangeError(`qr-door: ${url.length} characters needs a QR version above ${QR_DOOR_MAX_VERSION}`);
+    }
+    const n = qr.modules.size;
+    const data = qr.modules.data;
+    const m = CODE / n;
+    const isFinder = (x, y) => (x < 7 && y < 7) || (x > n - 8 && y < 7) || (x < 7 && y > n - 8);
+    const dots = [];
+    for (let y = 0; y < n; y++) {
+        for (let x = 0; x < n; x++) {
+            if (!data[y * n + x] || isFinder(x, y))
+                continue;
+            const px = O + (x + 0.5) * m;
+            const py = O + (y + 0.5) * m;
+            if (Math.abs(px - C0) < QR_DOOR_CLEARING && Math.abs(py - C0) < QR_DOOR_CLEARING)
+                continue;
+            dots.push({ x: px, y: py });
+        }
+    }
+    const finders = [
+        [0, 0],
+        [n - 7, 0],
+        [0, n - 7],
+    ].map(([fx, fy]) => ({ x: O + (fx + 3.5) * m, y: O + (fy + 3.5) * m }));
+    // Sample the outline evenly and give each sample the nearest module not yet taken.
+    const poly = [];
+    for (const s of geo.segs) {
+        if (s[0] === 'L') {
+            for (let i = 0; i <= 30; i++)
+                poly.push([lerp(s[1], s[3], i / 30), lerp(s[2], s[4], i / 30)]);
+        }
+        else {
+            for (let i = 0; i <= 120; i++) {
+                const a = ((s[4] + ((s[5] - s[4]) * i) / 120) * Math.PI) / 180;
+                poly.push([s[1] + s[3] * Math.cos(a), s[2] + s[3] * Math.sin(a)]);
+            }
+        }
+    }
+    const cum = [0];
+    for (let i = 1; i < poly.length; i++)
+        cum.push(cum[i - 1] + Math.hypot(poly[i][0] - poly[i - 1][0], poly[i][1] - poly[i - 1][1]));
+    const len = cum[cum.length - 1];
+    const count = Math.ceil((len * S1) / 3.6);
+    const used = new Set();
+    const pieces = [];
+    for (let j = 0; j < count; j++) {
+        const l = (j / (count - 1)) * len;
+        let q = 1;
+        while (q < cum.length - 1 && cum[q] < l)
+            q++;
+        const a = poly[q - 1];
+        const b = poly[q];
+        const f = clamp((l - cum[q - 1]) / (cum[q] - cum[q - 1] || 1));
+        const tx = C0 + (lerp(a[0], b[0], f) - geo.hc[0]) * S1;
+        const ty = C0 + (lerp(a[1], b[1], f) - geo.hc[1]) * S1;
+        let best = -1;
+        let bd = Number.POSITIVE_INFINITY;
+        for (let d = 0; d < dots.length; d++) {
+            if (used.has(d))
+                continue;
+            const dd = Math.hypot(dots[d].x - tx, dots[d].y - ty);
+            if (dd < bd) {
+                bd = dd;
+                best = d;
+            }
+        }
+        used.add(best);
+        pieces.push({ src: best, sx: dots[best].x, sy: dots[best].y, tx, ty, dl: (j / count) * 0.32 });
+    }
+    // One perspective camera: the code is a plane at depth 1, the icon at depth Dp.
+    // Solved so the icon is START px when first seen, S0 px the instant the doorway
+    // fills the stage, and ICON px at rest -- no hand-off between two zooms.
+    const Zg = (1.06 * 255) / (geo.hr * S1);
+    const zg = 1 - 1 / Zg;
+    const Dp = (zg * S0) / (S0 - START);
+    const kk = START * Dp;
+    const zf = Dp - kk / ICON;
+    let lo = 0;
+    let hi = 1;
+    for (let i = 0; i < 30; i++) {
+        const mid = (lo + hi) / 2;
+        if (io(mid) * zf < zg)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    return {
+        mark,
+        errorCorrection,
+        version: qr.version,
+        modules: n,
+        moduleSize: m,
+        dots,
+        finders,
+        pieces,
+        camera: { Zg, zg, Dp, kk, zf, t1: WALK + DOLLY * hi },
+    };
+}
+/** Icon size (logical px) at time `t` after approval. Continuous by construction. */
+export function qrDoorIconSize(scene, t) {
+    const c = scene.camera;
+    const z = c.zf * io(seg(t, WALK, WALK + DOLLY));
+    return c.kk / (c.Dp - z);
+}
+const paths = new Map();
+function pathsFor(mark) {
+    let p = paths.get(mark);
+    if (!p) {
+        p = { stroke: new Path2D(MARKS[mark].d), hole: new Path2D(MARKS[mark].hole) };
+        paths.set(mark, p);
+    }
+    return p;
+}
+function rr(c, x, y, w, h, r) {
+    c.moveTo(x + r, y);
+    c.arcTo(x + w, y, x + w, y + h, r);
+    c.arcTo(x + w, y + h, x, y + h, r);
+    c.arcTo(x, y + h, x, y, r);
+    c.arcTo(x, y, x + w, y, r);
+    c.closePath();
+}
+function finder(c, s, p, th) {
+    const M = s.moduleSize;
+    const h = 3.5 * M;
+    c.save();
+    c.translate(p.x - h, p.y - h);
+    c.fillStyle = th.ink;
+    c.beginPath();
+    rr(c, 0, 0, 7 * M, 7 * M, 1.6 * M * EYE_ROUND);
+    rr(c, M, M, 5 * M, 5 * M, 0.8 * M * EYE_ROUND);
+    c.fill('evenodd');
+    c.beginPath();
+    rr(c, 2 * M, 2 * M, 3 * M, 3 * M, 0.75 * M * EYE_ROUND);
+    c.fill();
+    c.restore();
+}
+function circles(c, xyr, color) {
+    c.fillStyle = color;
+    c.beginPath();
+    for (let i = 0; i < xyr.length; i += 3) {
+        const r = xyr[i + 2];
+        if (r <= 0.1)
+            continue;
+        c.moveTo(xyr[i] + r, xyr[i + 1]);
+        c.arc(xyr[i], xyr[i + 1], r, 0, TAU);
+    }
+    c.fill();
+}
+function stroke(c, s, th, dash) {
+    c.lineWidth = 3.4;
+    c.lineCap = 'round';
+    c.strokeStyle = th.ink;
+    if (dash)
+        c.setLineDash(dash);
+    c.stroke(pathsFor(s.mark).stroke);
+    c.setLineDash([]);
+}
+function icon(c, s, th, size) {
+    const k = size / 24;
+    c.save();
+    c.translate(C0 - size / 2, C0 - size / 2);
+    c.scale(k, k);
+    c.save();
+    c.shadowColor = 'rgba(29,27,22,.16)';
+    c.shadowBlur = 18 / k;
+    c.shadowOffsetY = 6 / k;
+    c.beginPath();
+    rr(c, 0.25, 0.25, 23.5, 23.5, 5.4);
+    c.fillStyle = th.paper;
+    c.fill();
+    c.shadowColor = 'transparent';
+    c.lineWidth = 0.2;
+    c.strokeStyle = 'rgba(29,27,22,.14)';
+    c.stroke();
+    c.restore();
+    stroke(c, s, th);
+    c.restore();
+}
+/** The code at rest, waiting for the phone. */
+export function drawQrDoorRest(c, s, th = QR_DOOR_THEME) {
+    c.fillStyle = th.paper;
+    c.fillRect(0, 0, L, L);
+    const r = 0.42 * s.moduleSize;
+    const a = [];
+    for (const p of s.dots)
+        a.push(p.x, p.y, r);
+    circles(c, a, th.ink);
+    for (const f of s.finders)
+        finder(c, s, f, th);
+}
+/** The frame `t` seconds after approval; `t` is clamped to `[0, QR_DOOR_DURATION]`. */
+export function drawQrDoorScene(c, s, time, th = QR_DOOR_THEME) {
+    const t = clamp(time, 0, QR_DOOR_DURATION);
+    const geo = MARKS[s.mark];
+    const cam = s.camera;
+    const hc = geo.hc;
+    const R0 = 0.42 * s.moduleSize;
+    const halfLine = 1.7 * S1;
+    const { hole: holePath } = pathsFor(s.mark);
+    // The opening: modules fly onto the outline; the line traces in behind the landings.
+    // Each lands at exactly half the line's width, so there is no cross-fade to see.
+    const trace = clamp((t - 0.345) / 0.32);
+    const hole = io(seg(t, 0.55, 0.8));
+    const arrive = back(seg(t, 0.72, 0.95));
+    const lifted = new Set();
+    for (const p of s.pieces)
+        if (t > p.dl)
+            lifted.add(p.src);
+    // The walk: one camera for both planes.
+    const z = cam.zf * io(seg(t, WALK, WALK + DOLLY));
+    const gone = z >= cam.zg;
+    const zoom = gone ? cam.Zg : 1 / (1 - z);
+    const isz = cam.kk / (cam.Dp - z);
+    const k = isz / ICON;
+    // Far side: dotted ground and the icon, visible through the doorway from the start of the walk.
+    c.fillStyle = th.paper;
+    c.fillRect(0, 0, L, L);
+    const sp = Math.max(22 * k, 4.5);
+    const dr = sp * 0.05;
+    const g0 = C0 - Math.ceil(C0 / sp) * sp;
+    c.fillStyle = 'rgba(29,27,22,.13)';
+    c.beginPath();
+    for (let gx = g0; gx < L + sp; gx += sp) {
+        for (let gy = g0; gy < L + sp; gy += sp) {
+            c.moveTo(gx + dr, gy);
+            c.arc(gx, gy, dr, 0, TAU);
+        }
+    }
+    c.fill();
+    const iconAlpha = sine(seg(t, WALK - 0.1, WALK + 0.35));
+    if (iconAlpha > 0) {
+        c.save();
+        c.globalAlpha = iconAlpha;
+        icon(c, s, th, isz);
+        c.restore();
+    }
+    // The person: from the doorway to the icon's own dot, then rides with it.
+    const w = io(seg(t, WALK, cam.t1));
+    const px = lerp(C0 + (geo.dot[0] - hc[0]) * S1, C0 + ((geo.dot[0] - 12) * isz) / 24, w);
+    const py = lerp(C0 + (geo.dot[1] - hc[1]) * S1, C0 + ((geo.dot[1] - 12) * isz) / 24, w);
+    const pr = lerp(2.6 * S1 * arrive, (2.6 * isz) / 24, w);
+    // Near side: the code, the doorway cut out of it, rushing past the camera.
+    if (!gone) {
+        c.save();
+        c.translate(C0, C0);
+        c.scale(zoom, zoom);
+        c.translate(-C0, -C0);
+        c.save();
+        const clip = new Path2D();
+        clip.rect(-4000, -4000, 8000 + L, 8000 + L);
+        if (hole > 0) {
+            clip.addPath(holePath, new DOMMatrix()
+                .translate(C0 - hc[0] * S1, C0 - hc[1] * S1)
+                .scale(S1)
+                .translate(hc[0], hc[1])
+                .scale(hole)
+                .translate(-hc[0], -hc[1]));
+        }
+        c.clip(clip, 'evenodd');
+        c.fillStyle = th.paper;
+        c.fillRect(-4000, -4000, 8000 + L, 8000 + L);
+        const rest = [];
+        s.dots.forEach((p, i) => {
+            if (!lifted.has(i))
+                rest.push(p.x, p.y, R0);
+        });
+        circles(c, rest, th.ink);
+        for (const f of s.finders)
+            finder(c, s, f, th);
+        c.restore();
+        if (trace < 1) {
+            const fly = [];
+            for (const p of s.pieces) {
+                if (t <= p.dl)
+                    continue;
+                const e = io(seg(t, p.dl, p.dl + 0.32));
+                const lift = Math.sin(Math.PI * e) * 10;
+                fly.push(lerp(p.sx, p.tx, e), lerp(p.sy, p.ty, e) - lift, lerp(R0, halfLine, e));
+            }
+            circles(c, fly, th.ink);
+        }
+        c.restore();
+    }
+    if (pr > 0.1) {
+        c.fillStyle = th.accent;
+        c.beginPath();
+        c.arc(px, py, pr, 0, TAU);
+        c.fill();
+    }
+    if (!gone && trace > 0) {
+        c.save();
+        c.translate(C0, C0);
+        c.scale(zoom, zoom);
+        c.translate(-C0, -C0);
+        c.translate(C0 - hc[0] * S1, C0 - hc[1] * S1);
+        c.scale(S1, S1);
+        stroke(c, s, th, trace < 1 ? [geo.len * trace, geo.len * 2] : undefined);
+        c.restore();
+    }
+}

package/dist/qr-door.d.ts

@@ -0,0 +1,15 @@
+import { type QrDoorMark, type QrDoorTheme } from './qr-door-scene.js';
+export { QR_DOOR_DURATION, QR_DOOR_THEME, type QrDoorMark, type QrDoorScene, type QrDoorTheme, buildQrDoorScene, drawQrDoorRest, drawQrDoorScene, } from './qr-door-scene.js';
+export interface QrDoorProps {
+    /** What the phone scans: `startQrSignIn()`'s `url`. */
+    url: string;
+    /** Whose door: the app's mark. */
+    mark: QrDoorMark;
+    /** True once `pollQrSignIn()` answered `signed_in`. */
+    approved: boolean;
+    /** Called when the walk-through ends, or at once under reduced motion. Navigate here. */
+    onDone?: () => void;
+    theme?: Partial<QrDoorTheme>;
+    className?: string;
+}
+export declare function QrDoor({ url, mark, approved, onDone, theme, className }: QrDoorProps): import("react/jsx-runtime").JSX.Element;

package/dist/qr-door.js

@@ -0,0 +1,71 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * `<QrDoor>`: the QR sign-in code as a React component. Draws `url` (the
+ * `url` from `startQrSignIn()`) and plays the door animation once `approved`
+ * turns true -- that is, once `pollQrSignIn()` answered `signed_in`. The
+ * drawing itself lives in `qr-door-scene.ts`; this file only owns the canvas,
+ * its size, the animation clock and reduced motion.
+ *
+ * Browser file: nothing here touches OIDC, cookies or `node:`.
+ */
+import { useEffect, useMemo, useRef } from 'react';
+import { QR_DOOR_DURATION, QR_DOOR_SIZE, QR_DOOR_THEME, buildQrDoorScene, drawQrDoorRest, drawQrDoorScene, } from './qr-door-scene.js';
+export { QR_DOOR_DURATION, QR_DOOR_THEME, buildQrDoorScene, drawQrDoorRest, drawQrDoorScene, } from './qr-door-scene.js';
+export function QrDoor({ url, mark, approved, onDone, theme, className }) {
+    const canvasRef = useRef(null);
+    const scene = useMemo(() => buildQrDoorScene(url, mark), [url, mark]);
+    const ink = theme?.ink ?? QR_DOOR_THEME.ink;
+    const accent = theme?.accent ?? QR_DOOR_THEME.accent;
+    const paper = theme?.paper ?? QR_DOOR_THEME.paper;
+    const onDoneRef = useRef(onDone);
+    onDoneRef.current = onDone;
+    useEffect(() => {
+        const canvas = canvasRef.current;
+        const ctx = canvas?.getContext('2d');
+        if (!canvas || !ctx)
+            return;
+        const th = { ink, accent, paper };
+        const reduce = window.matchMedia?.('(prefers-reduced-motion: reduce)').matches ?? false;
+        const start = performance.now();
+        let raf = 0;
+        let finished = false;
+        const fit = () => {
+            const dpr = Math.min(window.devicePixelRatio || 1, 2.5);
+            const px = Math.round((canvas.clientWidth || QR_DOOR_SIZE) * dpr);
+            // A canvas starts at 300×150, so check both sides, not just the width.
+            if (canvas.width !== px || canvas.height !== px)
+                canvas.width = canvas.height = px;
+            ctx.setTransform(px / QR_DOOR_SIZE, 0, 0, px / QR_DOOR_SIZE, 0, 0);
+        };
+        const paint = () => {
+            fit();
+            if (!approved) {
+                drawQrDoorRest(ctx, scene, th);
+                return;
+            }
+            const t = reduce ? QR_DOOR_DURATION : (performance.now() - start) / 1000;
+            drawQrDoorScene(ctx, scene, t, th);
+            if (t >= QR_DOOR_DURATION) {
+                if (!finished) {
+                    finished = true;
+                    onDoneRef.current?.();
+                }
+            }
+            else {
+                raf = requestAnimationFrame(paint);
+            }
+        };
+        paint();
+        const resize = new ResizeObserver(() => {
+            if (!approved || finished)
+                paint();
+        });
+        resize.observe(canvas);
+        return () => {
+            cancelAnimationFrame(raf);
+            resize.disconnect();
+        };
+    }, [scene, approved, ink, accent, paper]);
+    return (_jsx("canvas", { ref: canvasRef, className: className, style: { display: 'block', width: '100%', aspectRatio: '1' }, role: "img", "aria-label": approved ? 'Sign-in approved' : 'Scan this code with your phone to sign in' }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/auth",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Sign in against a self-hosted ZITADEL issuer: a server session for a Next.js app, and a browser client with silent single sign-on across subdomains.",
   "repository": {
     "type": "git",
@@ -42,6 +42,14 @@
       "types": "./dist/sessions.d.ts",
       "default": "./dist/sessions.js"
     },
+    "./person-token": {
+      "types": "./dist/person-token.d.ts",
+      "default": "./dist/person-token.js"
+    },
+    "./qr-door": {
+      "types": "./dist/qr-door.d.ts",
+      "default": "./dist/qr-door.js"
+    },
     "./testing": {
       "types": "./dist/testing.d.ts",
       "default": "./dist/testing.js"
@@ -59,25 +67,32 @@
     "test:cookie-browser": "vitest run --config vitest.cookie-browser.config.ts"
   },
   "dependencies": {
+    "@wtfalch/utils": "0.1.0",
     "jose": "^6.2.10",
     "obscenity": "^0.4.6",
     "openid-client": "6.8.7",
+    "qrcode": "^1.5.4",
     "reserved-usernames": "^1.1.6"
   },
   "peerDependencies": {
-    "next": ">=15.0.0"
+    "next": ">=15.0.0",
+    "react": ">=19.0.0"
   },
   "peerDependenciesMeta": {
     "next": {
       "optional": true
+    },
+    "react": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.8",
     "@types/node": "^22",
+    "@types/qrcode": "^1.5.6",
     "@types/react": "^19",
     "@wtfalch/auth-broker": "workspace:*",
-    "next": "^16",
+    "next": "^16.4.0",
     "playwright-core": "^1.62.1",
     "react": "^19",
     "typescript": "^5.9.0",