@wtfalch/auth 0.29.0 → 0.30.0

package/dist/onboarding.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The onboarding hold: what the broker hands an app's onboarding page during an
+ * MCP sign-in (ADR 0002), and what the app checks before it trusts the page's
+ * caller. Only WebCrypto, so this entry runs on workerd and in Node alike.
+ *
+ * `HOLD = base64url(JSON {h, s, o, e}) . base64url(HMAC-SHA256(appKey, firstPart))`
+ * where `h` is the hold id, `s` the person's ZITADEL user id, `o` their
+ * organisation id and `e` the expiry in epoch seconds. The key is the app's
+ * broker key (`AUTH_APP_KEY`), which only the broker and that app hold. A hold
+ * is a bearer proof that the broker just signed this person in; it carries no
+ * token and it is single use at the broker.
+ */
+export interface OnboardingHold {
+    holdId: string;
+    sub: string;
+    organizationId: string;
+}
+/** How long the broker accepts a hold it issued. */
+export declare const ONBOARDING_HOLD_TTL_SECONDS = 600;
+/** Signs a hold for `appKey`. `expiresAt` is epoch seconds. */
+export declare function signOnboardingHold(input: OnboardingHold & {
+    expiresAt: number;
+}, appKey: string): Promise<string>;
+/**
+ * The hold's contents when it is well formed, signed with `appKey` and not
+ * expired; otherwise null, with no hint which check failed. `now` is unix
+ * seconds, the unit of the hold's `e` (a test seam). The signature is compared by `crypto.subtle.verify`,
+ * which is constant time.
+ */
+export declare function verifyOnboardingHold(hold: string, appKey: string, now?: number): Promise<OnboardingHold | null>;

package/dist/onboarding.js

@@ -0,0 +1,93 @@
+/**
+ * The onboarding hold: what the broker hands an app's onboarding page during an
+ * MCP sign-in (ADR 0002), and what the app checks before it trusts the page's
+ * caller. Only WebCrypto, so this entry runs on workerd and in Node alike.
+ *
+ * `HOLD = base64url(JSON {h, s, o, e}) . base64url(HMAC-SHA256(appKey, firstPart))`
+ * where `h` is the hold id, `s` the person's ZITADEL user id, `o` their
+ * organisation id and `e` the expiry in epoch seconds. The key is the app's
+ * broker key (`AUTH_APP_KEY`), which only the broker and that app hold. A hold
+ * is a bearer proof that the broker just signed this person in; it carries no
+ * token and it is single use at the broker.
+ */
+/** How long the broker accepts a hold it issued. */
+export const ONBOARDING_HOLD_TTL_SECONDS = 600;
+const encoder = new TextEncoder();
+const HOLD_RE = /^([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]{43})$/;
+const MAX_HOLD_LENGTH = 2048;
+const toBase64Url = (bytes) => {
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+};
+const fromBase64Url = (value) => {
+    try {
+        const padded = value.replace(/-/g, '+').replace(/_/g, '/');
+        const binary = atob(padded + '='.repeat((4 - (padded.length % 4)) % 4));
+        return Uint8Array.from(binary, (char) => char.charCodeAt(0));
+    }
+    catch {
+        return null;
+    }
+};
+const hmacKey = (appKey, usage) => crypto.subtle.importKey('raw', encoder.encode(appKey), { name: 'HMAC', hash: 'SHA-256' }, false, [
+    usage,
+]);
+/** Signs a hold for `appKey`. `expiresAt` is epoch seconds. */
+export async function signOnboardingHold(input, appKey) {
+    const payload = toBase64Url(encoder.encode(JSON.stringify({
+        h: input.holdId,
+        s: input.sub,
+        o: input.organizationId,
+        e: input.expiresAt,
+    })));
+    const mac = await crypto.subtle.sign('HMAC', await hmacKey(appKey, 'sign'), encoder.encode(payload));
+    return `${payload}.${toBase64Url(new Uint8Array(mac))}`;
+}
+/**
+ * The hold's contents when it is well formed, signed with `appKey` and not
+ * expired; otherwise null, with no hint which check failed. `now` is unix
+ * seconds, the unit of the hold's `e` (a test seam). The signature is compared by `crypto.subtle.verify`,
+ * which is constant time.
+ */
+export async function verifyOnboardingHold(hold, appKey, now = Math.floor(Date.now() / 1000)) {
+    if (typeof hold !== 'string' || hold.length > MAX_HOLD_LENGTH || !appKey)
+        return null;
+    const match = HOLD_RE.exec(hold);
+    if (!match)
+        return null;
+    const [, payload, signature] = match;
+    const mac = fromBase64Url(signature);
+    if (!mac)
+        return null;
+    let valid;
+    try {
+        valid = await crypto.subtle.verify('HMAC', await hmacKey(appKey, 'verify'), mac, encoder.encode(payload));
+    }
+    catch {
+        return null;
+    }
+    if (!valid)
+        return null;
+    const bytes = fromBase64Url(payload);
+    if (!bytes)
+        return null;
+    let claims;
+    try {
+        claims = JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch {
+        return null;
+    }
+    if (claims === null || typeof claims !== 'object')
+        return null;
+    const { h, s, o, e } = claims;
+    if (typeof h !== 'string' || !h || typeof s !== 'string' || !s)
+        return null;
+    if (typeof o !== 'string' || !o || typeof e !== 'number' || !Number.isFinite(e))
+        return null;
+    if (e <= now)
+        return null;
+    return { holdId: h, sub: s, organizationId: o };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/auth",
-  "version": "0.29.0",
+  "version": "0.30.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",
@@ -50,6 +50,10 @@
       "types": "./dist/mcp.d.ts",
       "default": "./dist/mcp.js"
     },
+    "./onboarding": {
+      "types": "./dist/onboarding.d.ts",
+      "default": "./dist/onboarding.js"
+    },
     "./worker-session": {
       "types": "./dist/worker-session.d.ts",
       "default": "./dist/worker-session.js"