@wtfalch/auth 0.28.0 → 0.29.0

package/dist/mcp.d.ts

@@ -13,12 +13,57 @@ export interface McpOptions {
     /** Test seam. */
     fetch?: typeof fetch;
 }
-export interface McpTokenClaims {
+/** What `verifyMcpToken` needs besides the issuer, audience and resource. */
+export interface McpVerifyOptions extends McpOptions {
+    /** The ZITADEL organisation id of this app's customers. A token from any other organisation is refused. */
+    expectedOrgId: string;
+    /** The broker's `POST /mcp/token-info` (ADR 0002), asked about every token that passes the signature check. */
+    tokenInfo: {
+        /** The full URL, e.g. `https://auth.example.com/mcp/token-info`. */
+        url: string;
+        /** This app's broker key (`AUTH_APP_KEY`). */
+        credential: string;
+        /** How long a live answer is trusted, in milliseconds. Default and maximum 60 000. */
+        cacheMs?: number;
+        /** How long to wait for the broker, in milliseconds. Default and maximum 5 000; past it the answer is `unavailable`. */
+        timeoutMs?: number;
+    };
+}
+/** Who is behind a verified MCP token and which client holds it. */
+export interface McpIdentity {
     userId: string;
+    /** The token's `jti`. */
+    tokenId: string;
+    orgId: string;
+    scope: string;
+    /** The MCP client's id (a metadata URL or a registered id), as the broker records it. */
+    clientId: string;
+    clientName: string;
+    /** The refresh family (the person's grant for this client), which Disconnect ends. */
+    familyId: string;
+    /** Epoch milliseconds. */
+    expiresAt: number;
 }
-/** 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>;
+export type McpDenyReason = 'invalid' | 'expired' | 'revoked' | 'wrong_org' | 'wrong_scope' | 'unavailable';
+/** An identity, or null with the reason. The reason is for the app's own audit log; clients get a 401 either way. */
+export type McpVerification = {
+    identity: McpIdentity;
+    reason: null;
+} | {
+    identity: null;
+    reason: McpDenyReason;
+};
+/** For tests: forgets every cached core and token-info answer. */
+export declare function resetMcpCaches(): void;
+/**
+ * Who is behind a bearer token for this resource, or why not. Checks the
+ * signature, issuer, audience and expiry locally, then asks the broker whether
+ * the grant behind the token is still live (so Disconnect works within
+ * `cacheMs`, not at the token's expiry), then that the grant belongs to this
+ * app's organisation and carries `mcp:read`. When the broker cannot be asked
+ * the answer is `unavailable`, never an identity. Never throws.
+ */
+export declare function verifyMcpToken(req: Request, opts: McpVerifyOptions): Promise<McpVerification>;
 /** 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;

package/dist/mcp.js

@@ -1,38 +1,147 @@
 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();
+/** One person-token core per (issuer, audience), so discovery and the JWKS are
+ *  fetched once and cached, not once per request. The fetch function is not
+ *  part of the key: an app that builds its options (and a timeout fetch) per
+ *  request still shares the cache. The first fetch seen is the one kept. */
+const cores = new Map();
+const MAX_CORES = 32;
 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);
+    let core = cores.get(key);
     if (!core) {
+        // Issuer and audience come from the app's config; a cap keeps a misconfigured per-request value from growing this.
+        if (cores.size >= MAX_CORES)
+            cores.clear();
         core = createPersonTokenCore({
             issuer: opts.issuer,
             audience: opts.audience,
             fetch: opts.fetch,
         });
-        byKey.set(key, core);
+        cores.set(key, core);
     }
     return core;
 }
+/** Live token-info answers, by token. In memory only; bounded; positive answers only. */
+const live = new Map();
+const MAX_LIVE = 1000;
+const CACHE_MS_MAX = 60_000;
+const TOKEN_INFO_TIMEOUT_MS = 5_000;
+const REQUIRED_SCOPE = 'mcp:read';
+const RESOURCE_OWNER = 'urn:zitadel:iam:user:resourceowner:id';
+/** For tests: forgets every cached core and token-info answer. */
+export function resetMcpCaches() {
+    cores.clear();
+    live.clear();
+}
 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. */
+const deny = (reason) => ({ identity: null, reason });
+const str = (value) => (typeof value === 'string' && value ? value : null);
+/** The broker's answer, checked field by field; null for anything that is not a well-formed active answer. */
+function parseInfo(body) {
+    if (!body || typeof body !== 'object')
+        return null;
+    const b = body;
+    const userId = str(b.sub);
+    const tokenId = str(b.jti);
+    const orgId = str(b.orgId);
+    const scope = str(b.scope);
+    const clientId = str(b.clientId);
+    const clientName = str(b.clientName);
+    const familyId = str(b.familyId);
+    if (!userId ||
+        !tokenId ||
+        !orgId ||
+        !scope ||
+        !clientId ||
+        !clientName ||
+        !familyId ||
+        typeof b.exp !== 'number' ||
+        !Number.isFinite(b.exp)) {
+        return null;
+    }
+    return { userId, tokenId, orgId, scope, clientId, clientName, familyId, expiresAt: b.exp * 1000 };
+}
+async function askBroker(token, opts) {
+    const fetchImpl = opts.fetch ?? fetch;
+    try {
+        const response = await fetchImpl(opts.tokenInfo.url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${opts.tokenInfo.credential}`,
+            },
+            body: JSON.stringify({ token }),
+            signal: AbortSignal.timeout(Math.min(Math.max(opts.tokenInfo.timeoutMs ?? TOKEN_INFO_TIMEOUT_MS, 1), TOKEN_INFO_TIMEOUT_MS)),
+        });
+        // A refused key, a 5xx and a malformed body are all "could not check".
+        if (!response.ok)
+            return { kind: 'down' };
+        const body = (await response.json());
+        if (body.active === false)
+            return { kind: 'inactive' };
+        if (body.active !== true)
+            return { kind: 'down' };
+        const identity = parseInfo(body);
+        return identity ? { kind: 'active', identity } : { kind: 'down' };
+    }
+    catch {
+        return { kind: 'down' };
+    }
+}
+/**
+ * Who is behind a bearer token for this resource, or why not. Checks the
+ * signature, issuer, audience and expiry locally, then asks the broker whether
+ * the grant behind the token is still live (so Disconnect works within
+ * `cacheMs`, not at the token's expiry), then that the grant belongs to this
+ * app's organisation and carries `mcp:read`. When the broker cannot be asked
+ * the answer is `unavailable`, never an identity. Never throws.
+ */
 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 };
+        return deny('invalid');
+    const token = match[1];
+    const outcome = await coreFor(opts).verifyJwtOutcome(token);
+    if (!outcome.ok)
+        return deny(outcome.reason);
+    const { payload } = outcome;
+    if (typeof payload.sub !== 'string' || !payload.sub)
+        return deny('invalid');
+    // ZITADEL puts the owner in the token when it was asked to; when it did, it must be ours.
+    const owner = payload[RESOURCE_OWNER];
+    if (owner !== undefined && owner !== opts.expectedOrgId)
+        return deny('wrong_org');
+    const key = `${opts.tokenInfo.url}\n${token}`;
+    const now = Date.now();
+    let identity = null;
+    const cached = live.get(key);
+    if (cached && cached.until > now && cached.identity.expiresAt > now) {
+        identity = cached.identity;
+    }
+    else {
+        live.delete(key);
+        const asked = await askBroker(token, opts);
+        if (asked.kind === 'inactive')
+            return deny('revoked');
+        if (asked.kind === 'down')
+            return deny('unavailable');
+        identity = asked.identity;
+        const cacheMs = Math.min(Math.max(opts.tokenInfo.cacheMs ?? CACHE_MS_MAX, 0), CACHE_MS_MAX);
+        if (cacheMs > 0) {
+            if (live.size >= MAX_LIVE)
+                live.delete(live.keys().next().value);
+            live.set(key, { identity, until: now + cacheMs });
+        }
+    }
+    if (identity.userId !== payload.sub)
+        return deny('invalid');
+    if (identity.expiresAt <= now)
+        return deny('expired');
+    if (identity.orgId !== opts.expectedOrgId)
+        return deny('wrong_org');
+    if (!identity.scope.split(' ').includes(REQUIRED_SCOPE))
+        return deny('wrong_scope');
+    return { identity, reason: null };
 }
 function metadataUrl(opts) {
     const url = new URL(opts.resource);

package/dist/person-token.d.ts

@@ -64,7 +64,21 @@ export interface PersonTokenConfig {
 export interface PersonTokenCore extends PersonTokenVerifier {
     /** JWT path only, no introspection: the verified claims, or null. */
     verifyJwtClaims(accessToken: string): Promise<JWTPayload | null>;
+    /**
+     * Like `verifyJwtClaims`, but says why a token failed: `expired` for a
+     * well-signed token past its `exp`, `unavailable` when the issuer's keys
+     * could not be fetched, `invalid` for everything else.
+     */
+    verifyJwtOutcome(accessToken: string): Promise<JwtOutcome>;
 }
 /** @internal */
+export type JwtOutcome = {
+    ok: true;
+    payload: JWTPayload;
+} | {
+    ok: false;
+    reason: 'invalid' | 'expired' | 'unavailable';
+};
+/** @internal */
 export declare function createPersonTokenCore(config: PersonTokenConfig): PersonTokenCore;
 export declare function createPersonTokenVerifier(config: PersonTokenConfig): PersonTokenVerifier;

package/dist/person-token.js

@@ -102,9 +102,16 @@ export function createPersonTokenCore(config) {
         });
         return jwks;
     };
-    async function verifyJwt(accessToken) {
+    async function verifyJwtOutcome(accessToken) {
+        let keyset;
+        try {
+            keyset = await keys();
+        }
+        catch {
+            // Discovery could not be fetched or is wrong: no key can be trusted, so no token is.
+            return { ok: false, reason: 'unavailable' };
+        }
         try {
-            const keyset = await keys();
             const { payload } = await jwtVerify(accessToken, keyset, {
                 issuer: config.issuer,
                 audience: config.audience,
@@ -112,12 +119,23 @@ export function createPersonTokenCore(config) {
                 clockTolerance: 60,
                 requiredClaims: ['exp', 'sub'],
             });
-            return payload;
+            return { ok: true, payload };
         }
-        catch {
-            return null;
+        catch (error) {
+            const code = error?.code;
+            if (code === 'ERR_JWT_EXPIRED')
+                return { ok: false, reason: 'expired' };
+            // A key fetch that failed or timed out is the issuer being down, not the token being bad.
+            if (code === 'ERR_JWKS_TIMEOUT' || typeof code !== 'string') {
+                return { ok: false, reason: 'unavailable' };
+            }
+            return { ok: false, reason: 'invalid' };
         }
     }
+    async function verifyJwt(accessToken) {
+        const outcome = await verifyJwtOutcome(accessToken);
+        return outcome.ok ? outcome.payload : null;
+    }
     /**
      * RFC 7662 token introspection for an opaque access token: POSTs
      * `token=<accessToken>` to the issuer's `introspection_endpoint`,
@@ -186,6 +204,11 @@ export function createPersonTokenCore(config) {
         async verifyJwtClaims(accessToken) {
             return JWT_SHAPE.test(accessToken) ? verifyJwt(accessToken) : null;
         },
+        async verifyJwtOutcome(accessToken) {
+            return JWT_SHAPE.test(accessToken)
+                ? verifyJwtOutcome(accessToken)
+                : { ok: false, reason: 'invalid' };
+        },
         async verify(accessToken) {
             const payload = JWT_SHAPE.test(accessToken)
                 ? await verifyJwt(accessToken)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/auth",
-  "version": "0.28.0",
+  "version": "0.29.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",