@wtfalch/auth 0.19.0 → 0.22.0

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.19.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",