@wtfalch/auth 0.25.0 → 0.26.0

package/dist/mcp.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Resource side of MCP authorization for an org app (ADR 0002, section 4).
+ * Only `jose` and `fetch`: this entry runs on workerd, so nothing here may
+ * reach a `node:` module.
+ */
+export interface McpOptions {
+    /** The bound login host, e.g. `https://login.candorfx.com`. */
+    issuer: string;
+    /** The ZITADEL project id of the MCP project (env `MCP_AUDIENCE`). */
+    audience: string;
+    /** The MCP URL clients send as `resource` (env `MCP_RESOURCE`). */
+    resource: string;
+    /** Test seam. */
+    fetch?: typeof fetch;
+}
+export interface McpTokenClaims {
+    userId: string;
+}
+/** Claims for a valid bearer token for this resource, otherwise null. Never
+ *  throws on a bad token; says nothing about why. */
+export declare function verifyMcpToken(req: Request, opts: McpOptions): Promise<McpTokenClaims | null>;
+/** The 401 or 403 the app returns when `verifyMcpToken` gives null (401) or
+ *  the user may not do the thing (403). */
+export declare function mcpChallenge(opts: McpOptions, status: 401 | 403): Response;
+/** The document the app serves at `/.well-known/oauth-protected-resource` (and
+ *  the path form). */
+export declare function protectedResourceMetadata(opts: McpOptions): {
+    resource: string;
+    authorization_servers: string[];
+};

package/dist/mcp.js

@@ -0,0 +1,55 @@
+import { createPersonTokenCore } from './person-token.js';
+/** One person-token core per (fetch, issuer, audience), so discovery and the
+ *  JWKS are fetched once and cached, not once per request. Weakly keyed by the
+ *  fetch function so a test seam never leaks across tests. */
+const cores = new WeakMap();
+function coreFor(opts) {
+    const fetchImpl = opts.fetch ?? fetch;
+    let byKey = cores.get(fetchImpl);
+    if (!byKey) {
+        byKey = new Map();
+        cores.set(fetchImpl, byKey);
+    }
+    const key = JSON.stringify([opts.issuer, opts.audience]);
+    let core = byKey.get(key);
+    if (!core) {
+        core = createPersonTokenCore({
+            issuer: opts.issuer,
+            audience: opts.audience,
+            fetch: opts.fetch,
+        });
+        byKey.set(key, core);
+    }
+    return core;
+}
+const BEARER = /^Bearer ([^\s]+)$/i;
+/** Claims for a valid bearer token for this resource, otherwise null. Never
+ *  throws on a bad token; says nothing about why. */
+export async function verifyMcpToken(req, opts) {
+    const match = BEARER.exec(req.headers.get('authorization') ?? '');
+    if (!match?.[1])
+        return null;
+    const payload = await coreFor(opts).verifyJwtClaims(match[1]);
+    if (!payload || typeof payload.sub !== 'string' || !payload.sub)
+        return null;
+    return { userId: payload.sub };
+}
+function metadataUrl(opts) {
+    const url = new URL(opts.resource);
+    const path = url.pathname === '/' ? '' : url.pathname;
+    return `${url.origin}/.well-known/oauth-protected-resource${path}`;
+}
+/** The 401 or 403 the app returns when `verifyMcpToken` gives null (401) or
+ *  the user may not do the thing (403). */
+export function mcpChallenge(opts, status) {
+    const resourceMetadata = `resource_metadata="${metadataUrl(opts)}"`;
+    const challenge = status === 403
+        ? `Bearer error="insufficient_scope", ${resourceMetadata}`
+        : `Bearer ${resourceMetadata}`;
+    return new Response(null, { status, headers: { 'WWW-Authenticate': challenge } });
+}
+/** The document the app serves at `/.well-known/oauth-protected-resource` (and
+ *  the path form). */
+export function protectedResourceMetadata(opts) {
+    return { resource: opts.resource, authorization_servers: [opts.issuer] };
+}

package/dist/person-token.d.ts

@@ -1,3 +1,4 @@
+import { type JWTPayload } from 'jose';
 /**
  * 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
@@ -58,4 +59,12 @@ export interface PersonTokenConfig {
      *  real cooldown. */
     jwksCooldownMs?: number;
 }
+/** @internal Shared by `createPersonTokenVerifier` and `./mcp`: one discovery
+ *  document and one JWKS cache per core. Not part of the public contract. */
+export interface PersonTokenCore extends PersonTokenVerifier {
+    /** JWT path only, no introspection: the verified claims, or null. */
+    verifyJwtClaims(accessToken: string): Promise<JWTPayload | null>;
+}
+/** @internal */
+export declare function createPersonTokenCore(config: PersonTokenConfig): PersonTokenCore;
 export declare function createPersonTokenVerifier(config: PersonTokenConfig): PersonTokenVerifier;

package/dist/person-token.js

@@ -77,7 +77,8 @@ class PositiveIntrospectionCache {
         this.entries.set(token, { payload, expiresAt });
     }
 }
-export function createPersonTokenVerifier(config) {
+/** @internal */
+export function createPersonTokenCore(config) {
     const fetchImpl = config.fetch ?? fetch;
     let discovery = null;
     let jwks = null;
@@ -182,6 +183,9 @@ export function createPersonTokenVerifier(config) {
         return payload;
     }
     return {
+        async verifyJwtClaims(accessToken) {
+            return JWT_SHAPE.test(accessToken) ? verifyJwt(accessToken) : null;
+        },
         async verify(accessToken) {
             const payload = JWT_SHAPE.test(accessToken)
                 ? await verifyJwt(accessToken)
@@ -192,3 +196,7 @@ export function createPersonTokenVerifier(config) {
         },
     };
 }
+export function createPersonTokenVerifier(config) {
+    const { verify } = createPersonTokenCore(config);
+    return { verify };
+}

package/dist/worker-session.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The same OIDC sign-in the Next apps use, for a Cloudflare Worker: Request in,
+ * Response out, no `next`, no `node:`. It is `createAuth` with the app's origin
+ * taken from each request, so the session cookie (id token + refresh token,
+ * never an access token), the PKCE and state transaction, the organisation
+ * check and the refresh rules are the Next path's own code, not a copy.
+ */
+export interface WorkerSessionOptions {
+    /** The org's login host, e.g. `https://login.candorfx.com`. */
+    issuer: string;
+    /** The entry's client id. */
+    clientId: string;
+    /** The org's ZITADEL organisation id. A person from any other organisation is refused. */
+    orgId: string;
+    /** Where the issuer sends the browser back, e.g. `/auth/callback`. Must end in `/callback` and have a prefix; the app routes it to `callback`. */
+    redirectPath: string;
+    /** 32 bytes, base64 or hex. Never logged. */
+    cookieSecret: string;
+    /** Test seam. */
+    fetch?: typeof fetch;
+}
+export interface WorkerSignedIn {
+    userId: string;
+    orgId: string;
+    /**
+     * `Set-Cookie` header values to add to the app's response. Empty unless the
+     * session was refreshed on this request. The refresh token is single use:
+     * an app that drops these signs the person out at the next refresh.
+     */
+    setCookies: string[];
+}
+export interface WorkerSession {
+    /** Redirects to the issuer. `register` opens registration, `returnTo` is a path on this app. */
+    signIn(req: Request, o?: {
+        register?: boolean;
+        returnTo?: string;
+    }): Promise<Response>;
+    /** Route `redirectPath` here. Always a redirect: to `returnTo` on success, to `/?auth_error=<reason>` otherwise. */
+    callback(req: Request): Promise<Response>;
+    currentUser(req: Request): Promise<WorkerSignedIn | null>;
+    /** POST from the app's own origin only. */
+    signOut(req: Request): Promise<Response>;
+}
+export declare function createWorkerSession(opts: WorkerSessionOptions): WorkerSession;

package/dist/worker-session.js

@@ -0,0 +1,106 @@
+import { createAuth } from './auth.js';
+import { resolveOptions } from './config.js';
+import { FETCH_TIMEOUT_MS } from './util.js';
+const CALLBACK = /^(\/[A-Za-z0-9._~-]+)+\/callback$/;
+/** The fetch the SDK is given: every outside call (discovery, token, JWKS, revoke) is abandoned after FETCH_TIMEOUT_MS unless the caller set its own signal. */
+function withTimeout(fetchImpl) {
+    return (input, init) => fetchImpl(input, { ...init, signal: init?.signal ?? AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+}
+export function createWorkerSession(opts) {
+    for (const name of ['issuer', 'clientId', 'orgId', 'redirectPath', 'cookieSecret']) {
+        if (typeof opts[name] !== 'string' || !opts[name]) {
+            throw new Error(`@wtfalch/auth: ${name} is required`);
+        }
+    }
+    if (!CALLBACK.test(opts.redirectPath)) {
+        throw new Error('@wtfalch/auth: redirectPath must be a path ending in /callback, like /auth/callback');
+    }
+    let issuerUrl;
+    try {
+        issuerUrl = new URL(opts.issuer);
+    }
+    catch {
+        throw new Error('@wtfalch/auth: issuer must be an absolute URL');
+    }
+    if (issuerUrl.protocol !== 'https:' && issuerUrl.hostname !== 'localhost') {
+        throw new Error('@wtfalch/auth: issuer must be https');
+    }
+    const basePath = opts.redirectPath.slice(0, -'/callback'.length);
+    const fetchImpl = withTimeout(opts.fetch ?? globalThis.fetch);
+    const config = (appUrl) => ({
+        appUrl,
+        clientId: opts.clientId,
+        organizationId: opts.orgId,
+        issuer: opts.issuer,
+        cookieSecret: opts.cookieSecret,
+        basePath,
+        fetch: fetchImpl,
+    });
+    // A bad secret or client is a startup error, not the first visitor's.
+    resolveOptions(config('https://placeholder.invalid'));
+    // One Auth per origin, so the discovery document, JWKS and refresh dedupe are shared across requests in an isolate.
+    const byOrigin = new Map();
+    const authFor = (req) => {
+        const origin = new URL(req.url).origin;
+        let auth = byOrigin.get(origin);
+        if (!auth) {
+            auth = createAuth(config(origin));
+            byOrigin.set(origin, auth);
+        }
+        return auth;
+    };
+    // An outside failure is logged by its class only: messages can carry URLs and token fragments.
+    const unavailable = (what, error) => {
+        console.error(`@wtfalch/auth: worker session ${what} failed`, error instanceof Error ? error.name : 'unknown');
+        return new Response('Sign-in is unavailable', { status: 503 });
+    };
+    return {
+        async signIn(req, o = {}) {
+            const url = new URL(`${basePath}/start`, req.url);
+            if (o.register)
+                url.searchParams.set('intent', 'register');
+            if (o.returnTo !== undefined)
+                url.searchParams.set('next', o.returnTo);
+            try {
+                return await authFor(req).start(new Request(url, { headers: req.headers }));
+            }
+            catch (error) {
+                return unavailable('start', error);
+            }
+        },
+        async callback(req) {
+            try {
+                return await authFor(req).callback(req);
+            }
+            catch (error) {
+                return unavailable('callback', error);
+            }
+        },
+        async currentUser(req) {
+            try {
+                const { user, cookies } = await authFor(req).read(req);
+                if (!user)
+                    return null;
+                return {
+                    userId: user.id,
+                    orgId: user.organizationId,
+                    setCookies: cookies.map((c) => c.header),
+                };
+            }
+            catch (error) {
+                unavailable('session read', error);
+                return null;
+            }
+        },
+        async signOut(req) {
+            if (req.method !== 'POST')
+                return new Response('Method not allowed', { status: 405 });
+            try {
+                return await authFor(req).logout(req);
+            }
+            catch (error) {
+                return unavailable('sign-out', error);
+            }
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/auth",
-  "version": "0.25.0",
+  "version": "0.26.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",
@@ -46,6 +46,14 @@
       "types": "./dist/person-token.d.ts",
       "default": "./dist/person-token.js"
     },
+    "./mcp": {
+      "types": "./dist/mcp.d.ts",
+      "default": "./dist/mcp.js"
+    },
+    "./worker-session": {
+      "types": "./dist/worker-session.d.ts",
+      "default": "./dist/worker-session.js"
+    },
     "./qr-door": {
       "types": "./dist/qr-door.d.ts",
       "default": "./dist/qr-door.js"
@@ -64,6 +72,7 @@
     "prepack": "pnpm build",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
+    "test:workerd": "vitest run --config vitest.workerd.config.ts",
     "test:cookie-browser": "vitest run --config vitest.cookie-browser.config.ts"
   },
   "dependencies": {
@@ -87,6 +96,7 @@
     }
   },
   "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "0.23.0",
     "@electric-sql/pglite": "^0.5.8",
     "@types/node": "^22",
     "@types/qrcode": "^1.5.6",