@wtfalch/auth 0.29.0 → 0.31.0

package/dist/desktop.js

@@ -0,0 +1,528 @@
+import { createCipheriv, createDecipheriv, createHash, hkdfSync, randomBytes, randomUUID, timingSafeEqual, } from 'node:crypto';
+export class DesktopHandoffError extends Error {
+    status;
+    code;
+    constructor(status, code) {
+        super(code);
+        this.status = status;
+        this.code = code;
+    }
+}
+const fail = (status, code) => new DesktopHandoffError(status, code);
+/** 32 random bytes as base64url: the shape of a challenge, a verifier and a browser nonce. */
+const OPAQUE = /^[A-Za-z0-9_-]{43}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** The error page's reasons, and an admission hook's, are a closed shape: letters and underscores only. */
+const SAFE_REASON = /^[a-z_]{1,20}$/;
+/** Same shape `@wtfalch/desktop`'s `cookieHandoff({ scheme })` requires. */
+const SCHEME = /^[a-z][a-z0-9+.-]*$/;
+const APP_ID = /^[a-z][a-z0-9-]*$/;
+const HINT = /^[^\s@<>]{1,64}@[^\s@<>]{1,190}$/;
+const NO_STORE = { 'Cache-Control': 'no-store' };
+const digest = (value) => createHash('sha256').update(value).digest('base64url');
+const newNonce = () => randomBytes(32).toString('base64url');
+function same(a, b) {
+    const x = Buffer.from(a);
+    const y = Buffer.from(b);
+    return x.length === y.length && timingSafeEqual(x, y);
+}
+/**
+ * The key that seals a payload, derived from the cookie secret the app
+ * already holds, so no new secret exists. The fixed label keeps it apart
+ * from every other use of that secret. It is not the label Boule and Archon
+ * used (`boule-desktop-handoff`, `archon-desktop-handoff`): a row sealed under
+ * the old label fails to open here, so a sign-in in flight when an app cuts
+ * over to this handler ends in `payload_invalid`. The window is the row's
+ * lifetime, five minutes.
+ */
+function sealKey(secret) {
+    return Buffer.from(hkdfSync('sha256', secret, Buffer.alloc(0), 'wtfalch-auth-desktop-handoff', 32));
+}
+/** AES-256-GCM. `aad` is authenticated, not secret: it ties the ciphertext to one row and one origin. */
+function seal(key, aad, plaintext) {
+    const iv = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', key, iv);
+    cipher.setAAD(Buffer.from(aad));
+    const data = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    return Buffer.concat([iv, cipher.getAuthTag(), data]).toString('base64url');
+}
+/** Throws when the ciphertext, the tag or the `aad` is not what `seal` was given. */
+function open(key, aad, sealed) {
+    const data = Buffer.from(sealed, 'base64url');
+    const decipher = createDecipheriv('aes-256-gcm', key, data.subarray(0, 12));
+    decipher.setAAD(Buffer.from(aad));
+    decipher.setAuthTag(data.subarray(12, 28));
+    return Buffer.concat([decipher.update(data.subarray(28)), decipher.final()]).toString('utf8');
+}
+const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+/**
+ * The code the browser and the shell each derive from the challenge, so the
+ * person can see both belong to one sign-in: the first 30 bits of
+ * sha256("boule-desktop-pair:" + challenge), 5 bits each, shown as `ABC-DEF`.
+ * The label is fixed text, not this app's id: it is shared with
+ * `@wtfalch/desktop`'s `login.mjs`, which derives the same code
+ * independently of which app it is signing into. Changing it breaks pairing
+ * for every shell already built against it.
+ */
+function pairingCode(challenge) {
+    const bits = createHash('sha256')
+        .update(`boule-desktop-pair:${challenge}`)
+        .digest()
+        .readUInt32BE(0);
+    let code = '';
+    for (let i = 0; i < 6; i++)
+        code += CROCKFORD[(bits >>> (27 - 5 * i)) & 31];
+    return `${code.slice(0, 3)}-${code.slice(3)}`;
+}
+/**
+ * One process only. For tests and a single-instance development server: two
+ * replicas with separate memory stores do not share rows.
+ */
+export function createMemoryDesktopHandoffStore(options) {
+    const capacity = options?.capacity ?? 128;
+    const ttlMs = options?.ttlMs ?? 5 * 60 * 1000;
+    const pollGapMs = options?.pollGapMs ?? 1000;
+    const rows = new Map();
+    /** Per row id, the end of the line of transactions waiting for it. */
+    const lineEnds = new Map();
+    async function acquire(tx, id) {
+        if (tx.held.has(id))
+            return;
+        const before = lineEnds.get(id) ?? Promise.resolve();
+        let release;
+        const turn = new Promise((resolve) => {
+            release = resolve;
+        });
+        const end = before.then(() => turn);
+        lineEnds.set(id, end);
+        await before;
+        tx.held.set(id, () => {
+            if (lineEnds.get(id) === end)
+                lineEnds.delete(id);
+            release();
+        });
+    }
+    const sweep = () => {
+        const now = Date.now();
+        for (const [id, entry] of rows)
+            if (entry.expiresAt <= now)
+                rows.delete(id);
+    };
+    const found = (entry) => {
+        const { expiresAt, lastPoll, callerHash: _caller, ...row } = entry;
+        return {
+            row,
+            live: expiresAt > Date.now(),
+            pollOk: lastPoll === null || lastPoll < Date.now() - pollGapMs,
+        };
+    };
+    return {
+        async admit(row, limits) {
+            sweep();
+            if (rows.size >= capacity)
+                return false;
+            let mine = 0;
+            for (const entry of rows.values())
+                if (entry.callerHash === row.callerHash)
+                    mine++;
+            if (mine >= limits.perCaller)
+                return false;
+            rows.set(row.id, {
+                id: row.id,
+                status: 'started',
+                challenge: row.challenge,
+                browserHash: row.browserHash,
+                stateHash: row.stateHash,
+                payload: null,
+                subject: null,
+                email: null,
+                revision: null,
+                expiresAt: Date.now() + ttlMs,
+                lastPoll: null,
+                callerHash: row.callerHash,
+            });
+            return true;
+        },
+        async transaction(fn) {
+            const tx = { held: new Map() };
+            try {
+                return await fn(tx);
+            }
+            finally {
+                for (const release of tx.held.values())
+                    release();
+            }
+        },
+        async lock(tx, id) {
+            await acquire(tx, id);
+            const entry = rows.get(id);
+            return entry ? found(entry) : undefined;
+        },
+        async read(id) {
+            const entry = rows.get(id);
+            return entry ? found(entry) : undefined;
+        },
+        async patch(_tx, id, set) {
+            const entry = rows.get(id);
+            if (entry)
+                Object.assign(entry, set);
+        },
+        async remove(_tx, id) {
+            rows.delete(id);
+        },
+        async polled(_tx, id) {
+            const entry = rows.get(id);
+            if (entry)
+                entry.lastPoll = Date.now();
+        },
+    };
+}
+/** Fail-open on purpose, for an app with nothing further to check; see `DesktopHandoffConfig.admit`. */
+const alwaysAdmit = async (user) => ({ ok: true, user: { id: user.id } });
+export function createDesktopHandoff({ auth, appUrl, secret, appId, scheme, store, admit = alwaysAdmit, onError, clientAddressHeader = 'cf-connecting-ip', maxStartsPerCaller = 8, }) {
+    if (!APP_ID.test(appId))
+        throw new Error('createDesktopHandoff needs a valid appId');
+    if (!SCHEME.test(scheme))
+        throw new Error('createDesktopHandoff needs a valid scheme');
+    const origin = new URL(appUrl).origin;
+    const secure = origin.startsWith('https:');
+    // `__Host-` needs Secure, so plain-http localhost gets the bare name.
+    const cookieName = `${secure ? '__Host-' : ''}${appId}_desktop`;
+    const key = sealKey(secret);
+    const aad = (id) => `${origin}|${id}`;
+    const returnUrl = (id) => `${scheme}://auth/done?id=${id}`;
+    const redirect = (location, cookies = []) => {
+        const response = new Response(null, {
+            status: 303,
+            headers: { ...NO_STORE, Location: new URL(location, origin).href },
+        });
+        for (const cookie of cookies)
+            response.headers.append('Set-Cookie', cookie);
+        return response;
+    };
+    const browserCookie = (value) => `${cookieName}=${value}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${value ? 300 : 0}${secure ? '; Secure' : ''}`;
+    const reasonOf = (error) => error instanceof DesktopHandoffError ? error.code : 'unavailable';
+    /** Tells the host about a failure nobody planned for; a throwing hook never changes the answer. */
+    function report(step, error) {
+        if (error instanceof DesktopHandoffError || !onError)
+            return;
+        try {
+            onError({
+                step,
+                reason: reasonOf(error),
+                errorName: error instanceof Error ? error.name : 'unknown',
+            });
+        }
+        catch (hookError) {
+            console.error('desktop handoff onError hook threw', hookError instanceof Error ? hookError.name : 'unknown');
+        }
+    }
+    /** A browser step answers with a page; a failure sends it to the error page, with a reason from a closed list. */
+    async function page(step, run) {
+        try {
+            return await run();
+        }
+        catch (error) {
+            report(step, error);
+            return redirect(`/auth/desktop/error?reason=${reasonOf(error)}`);
+        }
+    }
+    /** A digest of the caller's address; null when the trusted header is absent (those callers share one bucket). */
+    function callerOf(request) {
+        const value = request.headers.get(clientAddressHeader)?.trim();
+        return value ? digest(value) : null;
+    }
+    /** The id and nonce the browser holds; the row is the only place either is checked. */
+    function browserOf(cookieHeader) {
+        const values = (cookieHeader ?? '')
+            .split(';')
+            .map((part) => part.trim())
+            .filter((part) => part.startsWith(`${cookieName}=`));
+        const [id, nonce, extra] = (values.length === 1 ? values[0].slice(cookieName.length + 1) : '').split('.');
+        if (!UUID.test(id ?? '') || !OPAQUE.test(nonce ?? '') || extra !== undefined)
+            throw fail(401, 'browser_required');
+        return { id, nonce };
+    }
+    /** The row this browser started, locked: it must exist, be unexpired, and carry this browser's nonce. */
+    async function browserRow(tx, cookieHeader) {
+        const browser = browserOf(cookieHeader);
+        const found = await store.lock(tx, browser.id);
+        if (!found)
+            throw fail(404, 'not_found');
+        if (!found.live)
+            throw fail(410, 'expired');
+        if (!found.row.browserHash || !same(found.row.browserHash, digest(browser.nonce)))
+            throw fail(403, 'browser_mismatch');
+        return found.row;
+    }
+    function sameOrigin(request) {
+        if (request.headers.get('origin') !== origin)
+            throw fail(403, 'origin');
+    }
+    const withoutSession = (cookieHeader) => (cookieHeader ?? '')
+        .split(';')
+        .map((part) => part.trim())
+        .filter((part) => part && !part.startsWith(`${auth.sessionCookieName}=`))
+        .join('; ');
+    async function formRevision(request) {
+        const value = (await request.formData().catch(() => null))?.get('revision');
+        if (typeof value !== 'string' || !UUID.test(value))
+            throw fail(400, 'invalid_request');
+        return value;
+    }
+    /** A body is read only when its length is declared and within `max`: a missing length is refused too. */
+    function bodyWithin(request, max) {
+        const length = request.headers.get('content-length');
+        return length !== null && /^\d{1,9}$/.test(length) && Number(length) <= max;
+    }
+    return {
+        /** The cookie name, for the one place a test or a route needs to read it. */
+        cookieName,
+        /** GET /auth/desktop/start */
+        start: (request) => page('start', async () => {
+            const params = new URL(request.url).searchParams;
+            const challenge = params.get('challenge');
+            if (params.getAll('challenge').length !== 1 || !challenge || !OPAQUE.test(challenge))
+                throw fail(400, 'invalid_challenge');
+            const hint = params.get('login_hint');
+            const prompt = params.get('prompt') === 'select_account' ? '?prompt=select_account' : '';
+            // The SDK reads only `prompt` from the request it is given, and wants a navigation.
+            const started = await auth.start(new Request(`${origin}/auth/desktop/start${prompt}`, {
+                headers: { accept: 'text/html', 'sec-fetch-mode': 'navigate' },
+            }));
+            const location = started.headers.get('location');
+            const target = location ? new URL(location) : null;
+            const state = target?.searchParams.get('state');
+            if (!target || !state)
+                throw fail(503, 'unavailable');
+            // The SDK does not forward `login_hint`; the issuer's authorize URL takes it as a plain parameter.
+            if (hint && hint.length <= 254 && HINT.test(hint))
+                target.searchParams.set('login_hint', hint);
+            const id = randomUUID();
+            const nonce = newNonce();
+            const admitted = await store.admit({
+                id,
+                challenge,
+                browserHash: digest(nonce),
+                stateHash: digest(state),
+                callerHash: callerOf(request),
+            }, { perCaller: maxStartsPerCaller });
+            if (!admitted)
+                throw fail(429, 'capacity');
+            return redirect(target.href, [
+                ...started.headers.getSetCookie(),
+                browserCookie(`${id}.${nonce}`),
+            ]);
+        }),
+        /** GET /auth/desktop/callback: where the issuer sends the browser. Sets no session cookie. */
+        callback: (request) => page('callback', async () => {
+            const cookieHeader = request.headers.get('cookie');
+            const url = new URL(request.url);
+            // Three steps, and no transaction open across the issuer's answer: validate and let go,
+            // ask the issuer, then lock again and apply only if the row is still waiting.
+            await store.transaction(async (tx) => {
+                const row = await browserRow(tx, cookieHeader);
+                if (row.status !== 'started')
+                    throw fail(409, 'step_changed');
+                const states = url.searchParams.getAll('state');
+                if (states.length !== 1 || !row.stateHash || !same(row.stateHash, digest(states[0])))
+                    throw fail(409, 'state_mismatch');
+            });
+            // Behind a proxy `request.url` can carry an internal host; the path and query are what the browser asked for.
+            const result = await auth.complete(new URL(`${url.pathname}${url.search}`, origin).href, withoutSession(cookieHeader));
+            const cookie = result.cookies.find((c) => c.name === auth.sessionCookieName && c.value);
+            // Only the SDK's transaction cookie, cleared, ever goes to the browser: never a cookie
+            // of the session's name, set or cleared, which would sign the person out of the app.
+            const cleared = result.cookies
+                .filter((c) => !c.value && c.name !== auth.sessionCookieName)
+                .map((c) => c.header);
+            const user = cookie ? (await auth.readCookie(cookie.value, { refresh: false })).user : null;
+            if (!cookie || !user) {
+                // No write: the row (and the binding cookie) stay for a valid callback that may still be running.
+                const reason = new URL(result.location, origin).searchParams.get('auth_error');
+                return redirect(`/auth/desktop/error?reason=${reason && SAFE_REASON.test(reason) ? reason : 'failed'}`, cleared);
+            }
+            // Refused here, not at the first request with the cookie: the shell is never handed a
+            // session the app would turn away. `admit` runs under the row's lock, so two concurrent
+            // callbacks on one row take turns and only the first reaches it: the second finds the
+            // row `completed`. The host's hook may be slow; the lock is held for as long as it is.
+            return store.transaction(async (tx) => {
+                const row = await browserRow(tx, cookieHeader);
+                if (row.status !== 'started')
+                    throw fail(409, 'step_changed');
+                const admission = await admit(user);
+                if (!admission.ok)
+                    return redirect(`/auth/desktop/error?reason=${SAFE_REASON.test(admission.reason) ? admission.reason : 'denied'}`, cleared);
+                const payload = {
+                    name: cookie.name,
+                    value: cookie.value,
+                    secure: cookie.attributes.secure,
+                    maxAge: cookie.attributes.maxAge,
+                };
+                await store.patch(tx, row.id, {
+                    status: 'completed',
+                    payload: seal(key, aad(row.id), JSON.stringify(payload)),
+                    subject: admission.user.id,
+                    email: user.email,
+                    revision: randomUUID(),
+                });
+                return redirect('/auth/desktop/confirm', cleared);
+            });
+        }),
+        /**
+         * What the confirm and done pages show, for the browser that holds the cookie; null for any
+         * other. A row that is gone (redeemed or cancelled rows are deleted) answers `gone` to the
+         * browser that held its binding, which is how the done page still says the app is signed in.
+         */
+        async current(cookieHeader) {
+            try {
+                const browser = browserOf(cookieHeader);
+                const found = await store.read(browser.id);
+                if (!found)
+                    return {
+                        id: browser.id,
+                        status: 'gone',
+                        email: null,
+                        revision: null,
+                        code: null,
+                        returnUrl: null,
+                    };
+                if (!found.live ||
+                    !found.row.browserHash ||
+                    !same(found.row.browserHash, digest(browser.nonce)))
+                    return null;
+                const { id, status, email, revision, challenge } = found.row;
+                return {
+                    id,
+                    status,
+                    email,
+                    revision,
+                    code: pairingCode(challenge),
+                    returnUrl: status === 'approved' ? returnUrl(id) : null,
+                };
+            }
+            catch {
+                return null;
+            }
+        },
+        /** POST /auth/desktop/approve: the person confirms the account the page showed. */
+        approve: (request) => page('approve', async () => {
+            sameOrigin(request);
+            if (!bodyWithin(request, 4096))
+                throw fail(413, 'body_too_large');
+            const seen = await formRevision(request);
+            return store.transaction(async (tx) => {
+                const row = await browserRow(tx, request.headers.get('cookie'));
+                if (row.status !== 'completed' || !row.revision || !same(row.revision, seen))
+                    throw fail(409, 'step_changed');
+                await store.patch(tx, row.id, { status: 'approved' });
+                return redirect('/auth/desktop/done');
+            });
+        }),
+        /** POST /auth/desktop/cancel: ends the sign-in and deletes its row. */
+        cancel: (request) => page('cancel', async () => {
+            sameOrigin(request);
+            if (!bodyWithin(request, 4096))
+                throw fail(413, 'body_too_large');
+            return store.transaction(async (tx) => {
+                const row = await browserRow(tx, request.headers.get('cookie'));
+                await store.remove(tx, row.id);
+                return redirect('/auth/desktop/error?reason=cancelled', [browserCookie('')]);
+            });
+        }),
+        /** POST /auth/desktop/redeem, with the body still unread: refuses one that is not small and declared. */
+        async redeemRequest(request) {
+            const json = request.headers.get('content-type')?.split(';')[0]?.trim() === 'application/json';
+            if (!bodyWithin(request, 1024))
+                return Response.json({ error: 'body_too_large' }, { status: 413, headers: NO_STORE });
+            let input = null;
+            try {
+                if (json)
+                    input = JSON.parse(await request.text());
+            }
+            catch {
+                // Not JSON: `input` stays null, and `redeem` refuses it as `invalid_request`.
+                input = null;
+            }
+            return this.redeem(input);
+        },
+        /** The shell trades its verifier for the cookie, once. No browser cookie involved. */
+        async redeem(input) {
+            try {
+                const { id, verifier } = (input ?? {});
+                if (typeof id !== 'string' ||
+                    !UUID.test(id) ||
+                    typeof verifier !== 'string' ||
+                    !OPAQUE.test(verifier))
+                    throw fail(400, 'invalid_request');
+                // Step one: check the verifier, stamp the attempt, and let go of the row. A refusal after
+                // the stamp is returned, not thrown, so the stamp (or the delete of an expired row) commits.
+                const claimed = await store.transaction(async (tx) => {
+                    const found = await store.lock(tx, id);
+                    if (!found)
+                        throw fail(404, 'not_found');
+                    const { row } = found;
+                    if (!same(row.challenge, digest(verifier)))
+                        throw fail(403, 'invalid_verifier');
+                    if (!found.live) {
+                        await store.remove(tx, row.id);
+                        return { error: fail(410, 'expired') };
+                    }
+                    if (!found.pollOk)
+                        throw fail(429, 'too_fast');
+                    await store.polled(tx, row.id);
+                    if (row.status !== 'approved' || !row.payload)
+                        return { error: fail(409, 'not_approved') };
+                    return { id: row.id, payload: row.payload, subject: row.subject };
+                });
+                if ('error' in claimed)
+                    throw claimed.error;
+                // Step two, with no lock held: `readCookie` is not local. It verifies the id token and
+                // may fetch the issuer's signing keys.
+                let payload;
+                try {
+                    payload = JSON.parse(open(key, aad(claimed.id), claimed.payload));
+                }
+                catch {
+                    throw fail(500, 'payload_invalid');
+                }
+                const verified = await auth.readCookie(payload.value, { refresh: false }).catch(() => {
+                    throw fail(503, 'unavailable');
+                });
+                const admitted = verified.user ? await admit(verified.user) : null;
+                if (!admitted?.ok || admitted.user.id !== claimed.subject)
+                    throw fail(401, 'identity_expired');
+                // Step three: lock again and take the row. Whoever deletes it first wins.
+                await store.transaction(async (tx) => {
+                    const found = await store.lock(tx, claimed.id);
+                    if (!found)
+                        throw fail(404, 'not_found');
+                    if (found.row.status !== 'approved')
+                        throw fail(409, 'not_approved');
+                    if (!found.live)
+                        throw fail(410, 'expired');
+                    await store.remove(tx, claimed.id);
+                });
+                const { name, value, secure: cookieSecure, maxAge } = payload;
+                return Response.json({
+                    cookies: [
+                        {
+                            name,
+                            value,
+                            path: '/',
+                            httpOnly: true,
+                            secure: cookieSecure,
+                            sameSite: 'lax',
+                            maxAge,
+                        },
+                    ],
+                }, { headers: NO_STORE });
+            }
+            catch (error) {
+                report('redeem', error);
+                const status = error instanceof DesktopHandoffError ? error.status : 503;
+                return Response.json({ error: reasonOf(error) }, { status, headers: NO_STORE });
+            }
+        },
+    };
+}

package/dist/index.d.ts

@@ -2,7 +2,8 @@ export { type Auth, type AuthRequest, type ChangePasswordError, type ChangePassw
 export type { AccessTokenReason, AccessTokenResult, AuthEvent, AuthOptions } from './config.js';
 export type { SetCookie } from './cookies.js';
 export type { SessionRecord, SessionStore, SessionUpdate } from './sessions.js';
-export type { PersonTokenConfig, PersonTokenVerifier } from './person-token.js';
+export { DesktopHandoffError, type DesktopHandoffAdmit, type DesktopHandoffAuth, type DesktopHandoffConfig, type DesktopHandoffCurrent, type DesktopHandoffFound, type DesktopHandoffRow, type DesktopHandoffStatus, type DesktopHandoffStore, } from './desktop.js';
+export type { PersonIdentity, PersonTokenConfig, PersonTokenOutcome, PersonTokenRefusal, PersonTokenVerifier, } from './person-token.js';
 export { BrokerError, type PeoplePage, type Person } from './broker.js';
 export { AuthError, type AuthErrorReason, ORG_CLAIM } from './oidc.js';
 export { safeLoginHint, safeNextPath } from './redirect.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export { STEP_UP_MAX_AGE, createAuth, } from './auth.js';
+export { DesktopHandoffError, } from './desktop.js';
 export { BrokerError } from './broker.js';
 export { AuthError, ORG_CLAIM } from './oidc.js';
 export { safeLoginHint, safeNextPath } from './redirect.js';

package/dist/mcp.d.ts

@@ -10,7 +10,10 @@ export interface McpOptions {
     audience: string;
     /** The MCP URL clients send as `resource` (env `MCP_RESOURCE`). */
     resource: string;
-    /** Test seam. */
+    /**
+     * Test seam. Pass a stateless function: the first `fetch` seen for an issuer and audience
+     * is the one every later call uses, whatever the options of that call say.
+     */
     fetch?: typeof fetch;
 }
 /** What `verifyMcpToken` needs besides the issuer, audience and resource. */
@@ -60,15 +63,23 @@ export declare function resetMcpCaches(): void;
  * 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
+ * app's organisation, was issued for `opts.resource`, 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>;
+/**
+ * Where an app serves the protected-resource metadata for this resource: the
+ * path-suffixed well-known path of RFC 9728 section 3.1, the resource's own
+ * path appended as it is. `https://host/a/mcp` gives
+ * `/.well-known/oauth-protected-resource/a/mcp`, a root resource gives
+ * `/.well-known/oauth-protected-resource`. Exact: `/a/mcp` and `/a/mcp2` get
+ * different paths, and a trailing slash is part of the path.
+ */
+export declare function protectedResourceMetadataPath(opts: McpOptions): string;
 /** 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). */
+/** The document the app serves at `protectedResourceMetadataPath(opts)`. */
 export declare function protectedResourceMetadata(opts: McpOptions): {
     resource: string;
     authorization_servers: string[];

package/dist/mcp.js

@@ -1,4 +1,5 @@
 import { createPersonTokenCore } from './person-token.js';
+import { ORG_CLAIM } from './util.js';
 /** 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
@@ -27,7 +28,6 @@ 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();
@@ -82,7 +82,8 @@ async function askBroker(token, opts) {
         if (body.active !== true)
             return { kind: 'down' };
         const identity = parseInfo(body);
-        return identity ? { kind: 'active', identity } : { kind: 'down' };
+        const resource = str(body.resource);
+        return identity && resource ? { kind: 'active', identity, resource } : { kind: 'down' };
     }
     catch {
         return { kind: 'down' };
@@ -93,7 +94,7 @@ async function askBroker(token, opts) {
  * 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
+ * app's organisation, was issued for `opts.resource`, 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) {
@@ -108,10 +109,11 @@ export async function verifyMcpToken(req, opts) {
     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];
+    const owner = payload[ORG_CLAIM];
     if (owner !== undefined && owner !== opts.expectedOrgId)
         return deny('wrong_org');
-    const key = `${opts.tokenInfo.url}\n${token}`;
+    // The resource is part of the key: an answer is only reused for the resource it was checked against.
+    const key = `${opts.tokenInfo.url}\n${opts.resource}\n${token}`;
     const now = Date.now();
     let identity = null;
     const cached = live.get(key);
@@ -125,6 +127,9 @@ export async function verifyMcpToken(req, opts) {
             return deny('revoked');
         if (asked.kind === 'down')
             return deny('unavailable');
+        // A token minted for another MCP resource is not good here, however live it is.
+        if (asked.resource !== opts.resource)
+            return deny('invalid');
         identity = asked.identity;
         const cacheMs = Math.min(Math.max(opts.tokenInfo.cacheMs ?? CACHE_MS_MAX, 0), CACHE_MS_MAX);
         if (cacheMs > 0) {
@@ -143,10 +148,20 @@ export async function verifyMcpToken(req, opts) {
         return deny('wrong_scope');
     return { identity, reason: null };
 }
+/**
+ * Where an app serves the protected-resource metadata for this resource: the
+ * path-suffixed well-known path of RFC 9728 section 3.1, the resource's own
+ * path appended as it is. `https://host/a/mcp` gives
+ * `/.well-known/oauth-protected-resource/a/mcp`, a root resource gives
+ * `/.well-known/oauth-protected-resource`. Exact: `/a/mcp` and `/a/mcp2` get
+ * different paths, and a trailing slash is part of the path.
+ */
+export function protectedResourceMetadataPath(opts) {
+    const { pathname } = new URL(opts.resource);
+    return `/.well-known/oauth-protected-resource${pathname === '/' ? '' : pathname}`;
+}
 function metadataUrl(opts) {
-    const url = new URL(opts.resource);
-    const path = url.pathname === '/' ? '' : url.pathname;
-    return `${url.origin}/.well-known/oauth-protected-resource${path}`;
+    return `${new URL(opts.resource).origin}${protectedResourceMetadataPath(opts)}`;
 }
 /** The 401 or 403 the app returns when `verifyMcpToken` gives null (401) or
  *  the user may not do the thing (403). */
@@ -157,8 +172,7 @@ export function mcpChallenge(opts, status) {
         : `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). */
+/** The document the app serves at `protectedResourceMetadataPath(opts)`. */
 export function protectedResourceMetadata(opts) {
     return { resource: opts.resource, authorization_servers: [opts.issuer] };
 }