@wtfalch/auth 0.19.0 → 0.22.0

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 {};