@zackbart/connecta 0.28.1 → 0.29.0

package/dist/auth/clerk-transport.js

@@ -0,0 +1,19 @@
+import { createClerkClient as createIsolatedClerkClient } from "./clerk-sdk/client.js";
+import { byteReadResponse } from "../byte-read-response.js";
+import { failureRecord, logFailure } from "../operator-record.js";
+/** All SDK network paths, including fresh opaque-verification clients. */
+export function createByteReadingClerkClient(options) {
+    const client = createIsolatedClerkClient({
+        ...options,
+        telemetry: { disabled: true },
+        fetch: async (input, init) => byteReadResponse(await fetch(input, init)),
+    });
+    // The upstream disabled flag does not cover recordLog or debug output.
+    client.telemetry.record = () => { };
+    client.telemetry.recordLog = () => { };
+    return client;
+}
+/** The generated SDK never forwards its diagnostic text to a console. */
+export function clerkSdkFailure(failure) {
+    logFailure(console, "Clerk authentication failed", failureRecord({}, failure));
+}

package/dist/auth/clerk.d.ts

@@ -1,11 +1,22 @@
-import { createClerkClient } from "@clerk/backend";
+import type { ClerkGateClient } from "./clerk-sdk/client.js";
 import type { InboundAuth } from "../types.js";
-type ClerkClient = ReturnType<typeof createClerkClient>;
+export type { ClerkGateClient, ClerkUser } from "./clerk-sdk/client.js";
 export interface ClerkAuthOptions {
     publishableKey: string;
     secretKey: string;
     /** Public base URL of this deployment. Defaults to the request origin. */
     publicUrl?: string;
+    /**
+     * OAuth client IDs dedicated to this deployment, used only when a verified
+     * access token has no audience/resource claim. Omitted or `[]` requires
+     * resource-bound tokens, both JWT and opaque. Enable Clerk's
+     * `aud_claim_enabled` setting and request the endpoint URL as `resource`.
+     * A present audience/resource must match
+     * the canonical `/mcp` or `/mcp/<pool>` URL even for an allowlisted client.
+     * Never share these clients with another resource server. Pool grants still
+     * narrow access; the fallback client list applies to every pool.
+     */
+    allowedOAuthClientIds?: readonly string[];
     /**
      * Email domains this deployment admits, e.g. `["acme.com"]`. An
      * authenticated user whose verified primary email is not on one of them is
@@ -14,12 +25,12 @@ export interface ClerkAuthOptions {
      * `mail.acme.com` — spell a subdomain out to allow it. Entries must be ASCII
      * (punycode for an internationalized domain) and are validated at
      * construction. Absent ⇒ every authenticated user passes this check, as
-     * before the option existed. Governs Clerk sign-in only: a co-configured
-     * `bearerToken` has no email to read and is admitted without a domain check.
+     * before the option existed. Governs Clerk sign-in only: a co-configured machine
+     * access token has no email to read and is admitted without a domain check.
      */
     allowedDomains?: readonly string[];
-    /** Optional allow-list hook. Return false to reject an authenticated user. */
-    gate?: (userId: string, clerk: ClerkClient) => boolean | Promise<boolean>;
+    /** Optional allow-list hook using Connecta's bundled user lookup client. */
+    gate?: (userId: string, clerk: ClerkGateClient) => boolean | Promise<boolean>;
     /** Advertised scopes in protected-resource metadata. */
     scopes?: string[];
     /** Optional hosted Account Portal sign-in URL for operator pages. Absolute https only. */
@@ -28,4 +39,3 @@ export interface ClerkAuthOptions {
     signUpUrl?: string;
 }
 export declare function clerkAuth(opts: ClerkAuthOptions): InboundAuth;
-export {};

package/dist/auth/clerk.js

@@ -1,25 +1,17 @@
-// Clerk as the OAuth 2.1 authorization server; connecta is the resource server.
-// Single tenant, no tenant-tag requirement, optional allowedDomains/gate() with
-// ~60s identity caching.
-import { createClerkClient } from "@clerk/backend";
+import { authorizationCredential, authorizationRequest, isMachineCredential } from "../inbound-credential.js";
+import { createByteReadingClerkClient } from "./clerk-transport.js";
+import { decodeJwt } from "@clerk/backend/jwt";
+import { byteReadResponse } from "../byte-read-response.js";
+import { failureRecord, logFailure } from "../operator-record.js";
 import { assertNoRetiredToolkitOptions } from "../retired-toolkits.js";
+function logDenial(reason, failure) {
+    logFailure(console, "Clerk request denied", failureRecord({ reason }, failure));
+}
 const CORS_HEADERS = {
     "Access-Control-Allow-Origin": "*",
-    "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+    "Access-Control-Allow-Methods": "GET, HEAD, OPTIONS",
     "Access-Control-Allow-Headers": "Content-Type, Authorization, mcp-protocol-version",
 };
-/** Coarse bearer shape for diagnostics — never the token itself. */
-function tokenShape(request) {
-    const header = request.headers.get("authorization");
-    if (!header)
-        return "none";
-    const token = header.replace(/^Bearer\s+/i, "");
-    if (token.startsWith("oat_"))
-        return "oauth-opaque";
-    if (token.startsWith("eyJ"))
-        return "jwt";
-    return "other";
-}
 /**
  * Clerk Frontend API origin, derived from pk_(test|live)_<b64 domain>.
  *
@@ -55,8 +47,7 @@ function fapiUrl(publishableKey) {
     // Clerk terminates the encoded domain with `$`; everything else is the host.
     const domain = decoded.replace(/\$$/, "");
     if (!isDomain(domain)) {
-        throw new Error("clerkAuth: `publishableKey` does not decode to a Frontend API domain." +
-            shape);
+        throw new Error("clerkAuth: `publishableKey` does not decode to a Frontend API domain." + shape);
     }
     return `https://${domain}`;
 }
@@ -101,13 +92,9 @@ function cleanActivityLabel(value) {
 }
 /** Prefer a person's name, then a verified primary email, then username. */
 function activityLabelForUser(user) {
-    const fullName = user.fullName ??
-        [user.firstName, user.lastName].filter(Boolean).join(" ");
-    const primary = user.emailAddresses?.find((address) => address.id === user.primaryEmailAddressId &&
-        address.verification?.status === "verified");
-    return (cleanActivityLabel(fullName) ??
-        cleanActivityLabel(primary?.emailAddress) ??
-        cleanActivityLabel(user.username));
+    const fullName = user.fullName ?? [user.firstName, user.lastName].filter(Boolean).join(" ");
+    const primary = user.emailAddresses?.find((address) => address.id === user.primaryEmailAddressId && address.verification?.status === "verified");
+    return cleanActivityLabel(fullName) ?? cleanActivityLabel(primary?.emailAddress) ?? cleanActivityLabel(user.username);
 }
 /**
  * One label of a domain: ASCII letters/digits, interior hyphens only, 63
@@ -160,9 +147,7 @@ function normalizeAllowedDomains(value) {
         // operator can see in the throw. Nothing is forgiven on the email side.
         const domain = entry.trim();
         if (!isDomain(domain)) {
-            const hint = domain.includes("@")
-                ? " Write the domain alone, with no `@` and no local part."
-                : "";
+            const hint = domain.includes("@") ? " Write the domain alone, with no `@` and no local part." : "";
             throw new Error(`clerkAuth: \`allowedDomains\` entry ${JSON.stringify(entry)} is not a ` +
                 `domain (expected something like "acme.com").${hint}`);
         }
@@ -170,18 +155,72 @@ function normalizeAllowedDomains(value) {
     }
     return domains;
 }
+/** No wildcard or implicit all-clients mode for unbound OAuth tokens. */
+function normalizeOAuthClientIds(value) {
+    if (value === undefined)
+        return new Set();
+    if (!Array.isArray(value)) {
+        throw new Error("clerkAuth: `allowedOAuthClientIds` must be an array of OAuth client IDs. " +
+            "Omit it or use [] to require resource-bound OAuth tokens.");
+    }
+    for (const id of value) {
+        if (typeof id !== "string" || !/^[\x21-\x7e]+$/.test(id) || id === "*") {
+            throw new Error("clerkAuth: `allowedOAuthClientIds` entries must be nonempty, " + "non-wildcard client IDs without whitespace.");
+        }
+    }
+    return new Set(value);
+}
+/** Only verified claims reach this comparison; resource URLs match exactly. */
+function oauthBindingRejection(claims, resource, clientId, allowedClientIds) {
+    const bindings = ["aud", "resource"].filter((key) => Object.prototype.hasOwnProperty.call(claims, key));
+    if (bindings.length === 0) {
+        return allowedClientIds.has(clientId) ? null : "oauth_client_not_allowed";
+    }
+    const matches = bindings.every((key) => {
+        const value = claims[key];
+        const audiences = Array.isArray(value) ? value : [value];
+        return (audiences.length > 0 &&
+            audiences.every((audience) => typeof audience === "string" && audience.length > 0) &&
+            audiences.includes(resource));
+    });
+    return matches ? null : "oauth_binding_mismatch";
+}
 /**
- * Bounded, escaped form of the denied domain for the operator log — the same
- * treatment server logs give other caller-controlled values. An email domain is
- * caller-influenced (anyone who controls a mailbox controls its domain): the
- * bound is what a 253-byte domain needs, and the escaping — JSON.stringify plus
- * the hand-rolled U+2028/U+2029 pass it leaves raw — is defense in depth behind
- * `isDomain`, which has already ruled out the newline that would forge a line.
+ * Clerk 3.12's OAuth deserializer drops `aud`. Read the same verification
+ * endpoint directly after SDK authentication, without a shared response cache
+ * or SDK patch. Its subject/client and active verdict must still agree.
  */
-function loggableDomain(domain) {
-    const bounded = domain.slice(0, 100);
-    const escaped = JSON.stringify(bounded).replace(/[\u2028\u2029]/g, (ch) => `\\u${ch.charCodeAt(0).toString(16)}`);
-    return escaped + (bounded.length < domain.length ? " (truncated)" : "");
+async function opaqueOAuthClaims(token, secretKey, userId, clientId, signal) {
+    const response = await fetch("https://api.clerk.com/v1/oauth_applications/access_tokens/verify", {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${secretKey}`,
+            "Content-Type": "application/json",
+            "Clerk-API-Version": "2026-05-12",
+        },
+        body: JSON.stringify({ access_token: token }),
+        redirect: "error",
+        signal: AbortSignal.any([signal, AbortSignal.timeout(10_000)]),
+    });
+    if (!response.ok)
+        throw new Error("Opaque OAuth verification failed");
+    const claims = await byteReadResponse(response).json();
+    if (!claims ||
+        typeof claims !== "object" ||
+        Array.isArray(claims) ||
+        !("object" in claims) ||
+        claims.object !== "clerk_idp_oauth_access_token" ||
+        !("subject" in claims) ||
+        claims.subject !== userId ||
+        !("client_id" in claims) ||
+        claims.client_id !== clientId ||
+        !("revoked" in claims) ||
+        claims.revoked !== false ||
+        !("expired" in claims) ||
+        claims.expired !== false) {
+        throw new Error("Opaque OAuth verification response invalid");
+    }
+    return claims;
 }
 /**
  * The domain of an email address, lowercased for comparison, or null when the
@@ -217,12 +256,18 @@ export function clerkAuth(opts) {
     // Before the Clerk client, so a malformed key fails as a connecta
     // configuration error rather than however the SDK happens to treat it.
     const frontendApiUrl = fapiUrl(opts.publishableKey);
-    const clerk = createClerkClient({
+    const clerk = createByteReadingClerkClient({
         secretKey: opts.secretKey,
         publishableKey: opts.publishableKey,
     });
     const allowedDomains = normalizeAllowedDomains(opts.allowedDomains);
-    const scopes = opts.scopes ?? ["openid", "profile", "email"];
+    const allowedOAuthClientIds = normalizeOAuthClientIds(opts.allowedOAuthClientIds);
+    const requestedScopes = opts.scopes ?? ["openid", "profile", "email"];
+    if (!Array.isArray(requestedScopes) ||
+        requestedScopes.some((scope) => typeof scope !== "string" || !/^[\x21\x23-\x5b\x5d-\x7e]+$/.test(scope))) {
+        throw new Error("clerkAuth: `scopes` must contain OAuth scope tokens without whitespace, quotes, or backslashes.");
+    }
+    const scopes = [...requestedScopes];
     const gateCache = new Map();
     const activityLabelCache = new Map();
     const pendingActivityLabels = new Map();
@@ -232,8 +277,7 @@ export function clerkAuth(opts) {
     const cacheActivityLabel = (userId, label) => {
         writeIdentityCache(activityLabelCache, userId, {
             ...(label ? { label } : {}),
-            exp: Date.now() +
-                (label ? ACTIVITY_LABEL_TTL_MS : ACTIVITY_LABEL_MISS_TTL_MS),
+            exp: Date.now() + (label ? ACTIVITY_LABEL_TTL_MS : ACTIVITY_LABEL_MISS_TTL_MS),
         });
     };
     const resolveActivityLabel = async (userId) => {
@@ -247,8 +291,7 @@ export function clerkAuth(opts) {
         // concurrency bounded even when requests hang forever: do not queue more
         // identities in memory, and do not start a duplicate for an id whose raw
         // lookup outlived its caller-facing deadline.
-        if (inFlightActivityLabelIds.has(userId) ||
-            activeActivityLabelLookups >= ACTIVITY_LABEL_MAX_IN_FLIGHT) {
+        if (inFlightActivityLabelIds.has(userId) || activeActivityLabelLookups >= ACTIVITY_LABEL_MAX_IN_FLIGHT) {
             cacheActivityLabel(userId, undefined);
             return undefined;
         }
@@ -289,22 +332,30 @@ export function clerkAuth(opts) {
         pendingActivityLabels.set(userId, lookup);
         return lookup;
     };
-    const unauthorized = (baseUrl, tokenPresent, request) => {
+    const challenge = (request, baseUrl) => {
+        const tokenPresent = authorizationCredential(request).kind !== "absent";
         const error = tokenPresent ? `error="invalid_token", ` : "";
         // A pool endpoint is its own protected resource: the challenge names the
         // metadata document whose `resource` matches the URL the client used, or
         // RFC 9728 tells it to reject the mismatch.
         const pool = mcpPoolSuffix(new URL(request.url).pathname);
         const meta = `${resolveBase(baseUrl)}/.well-known/oauth-protected-resource${pool ? `/mcp${pool}` : ""}`;
+        const quote = (value) => value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+        return `Bearer ${error}resource_metadata="${quote(meta)}", scope="${scopes.join(" ")}"`;
+    };
+    const unauthorized = (baseUrl, _tokenPresent, request) => {
         return new Response(JSON.stringify({ error: "unauthorized" }), {
             status: 401,
             headers: {
                 "Content-Type": "application/json",
-                "WWW-Authenticate": `Bearer ${error}resource_metadata="${meta}"`,
+                "WWW-Authenticate": challenge(request, baseUrl),
             },
         });
     };
-    const forbidden = () => new Response(JSON.stringify({ error: "forbidden" }), { status: 403, headers: { "Content-Type": "application/json" } });
+    const forbidden = () => new Response(JSON.stringify({ error: "forbidden" }), {
+        status: 403,
+        headers: { "Content-Type": "application/json" },
+    });
     /**
      * The domain half of admission. Fails CLOSED on every uncertainty — no
      * primary email, an unverified one, a malformed address, or the lookup
@@ -323,24 +374,16 @@ export function clerkAuth(opts) {
             }
         }
         catch (error) {
-            console.warn(`[connecta] clerk email lookup failed for ${userId}: ${error instanceof Error ? error.message : String(error)} — denying`);
+            logDenial("email_lookup_failed", error);
             return false;
         }
         const domain = email ? emailDomain(email) : null;
         if (!domain) {
-            // One line for three cases (no primary email, unverified, or an address
-            // with no readable domain) because the caller must not be able to tell
-            // them apart — but it must not claim the email is missing when it is
-            // there and malformed.
-            console.warn(`[connecta] clerk user ${userId} has no verified primary email with a ` +
-                "well-formed domain — denying");
+            logDenial("verified_email_invalid");
             return false;
         }
         if (!allowedDomains.has(domain)) {
-            // The domain, never the address: this is an operator log, not a place to
-            // spill the local part of someone's email on every denied request.
-            console.warn(`[connecta] clerk user ${userId} denied: email domain ` +
-                `${loggableDomain(domain)} is not on allowedDomains`);
+            logDenial("email_domain_denied");
             return false;
         }
         return true;
@@ -359,23 +402,31 @@ export function clerkAuth(opts) {
             return hit.allowed;
         let allowed = false;
         try {
-            allowed =
-                (await checkDomain(userId)) &&
-                    (opts.gate ? await opts.gate(userId, clerk) : true);
+            const domainAllowed = await checkDomain(userId);
+            allowed = domainAllowed && (opts.gate ? await opts.gate(userId, clerk) : true);
+            if (domainAllowed && !allowed)
+                logDenial("gate_denied");
         }
         catch {
+            logDenial("gate_failed");
             allowed = false;
         }
         writeIdentityCache(gateCache, userId, {
             allowed,
-            exp: Date.now() +
-                (allowed ? GATE_ALLOWED_TTL_MS : GATE_FORBIDDEN_TTL_MS),
+            exp: Date.now() + (allowed ? GATE_ALLOWED_TTL_MS : GATE_FORBIDDEN_TTL_MS),
         });
         return allowed;
     };
     return {
         kind: "clerk",
         interactiveOperator: true,
+        recognizesCredential: (request) => {
+            if (authorizationCredential(request).kind !== "absent")
+                return !isMachineCredential(request);
+            return (/(?:^|;\s*)__session(?:_[^=;]+)?=/.test(request.headers.get("cookie") ?? "") ||
+                new URL(request.url).searchParams.has("__clerk_synced"));
+        },
+        challenge,
         activityActorNamespace: frontendApiUrl,
         activityActorLabel: resolveActivityLabel,
         uiAuth: {
@@ -387,8 +438,14 @@ export function clerkAuth(opts) {
         },
         async handleMetadata(request, baseUrl) {
             const { pathname } = new URL(request.url);
-            if (!pathname.startsWith("/.well-known/"))
+            const protectedResource = pathname === "/.well-known/oauth-protected-resource" ||
+                pathname === "/.well-known/oauth-protected-resource/mcp" ||
+                /^\/\.well-known\/oauth-protected-resource\/mcp\/[a-z0-9_-]+$/.test(pathname);
+            if (!protectedResource)
                 return null;
+            if (request.method !== "GET" && request.method !== "HEAD" && request.method !== "OPTIONS") {
+                return new Response(null, { status: 405, headers: { ...CORS_HEADERS, Allow: "GET, HEAD, OPTIONS" } });
+            }
             if (request.method === "OPTIONS") {
                 return new Response(null, { status: 204, headers: CORS_HEADERS });
             }
@@ -406,74 +463,99 @@ export function clerkAuth(opts) {
                     scopes_supported: scopes,
                 }, { headers: CORS_HEADERS });
             }
-            if (pathname === "/.well-known/oauth-authorization-server") {
-                try {
-                    const upstream = await fetch(`${frontendApiUrl}/.well-known/oauth-authorization-server`);
-                    if (!upstream.ok) {
-                        return Response.json({ error: "upstream authorization server metadata unavailable" }, { status: 502, headers: CORS_HEADERS });
-                    }
-                    return Response.json(await upstream.json(), { headers: CORS_HEADERS });
-                }
-                catch {
-                    return Response.json({ error: "upstream authorization server metadata unavailable" }, { status: 502, headers: CORS_HEADERS });
-                }
-            }
             return null;
         },
         async authorize(request, baseUrl) {
-            const tokenPresent = Boolean(request.headers.get("authorization"));
+            const credential = authorizationCredential(request);
+            const tokenPresent = credential.kind !== "absent";
+            if (credential.kind === "invalid" || isMachineCredential(request)) {
+                logDenial("authorization_header_invalid");
+                return { ok: false, response: unauthorized(baseUrl, tokenPresent, request) };
+            }
+            const browserOAuthRoute = /^\/(?:connect|oauth\/callback)\//.test(new URL(request.url).pathname);
             let userId;
+            let sessionCookies;
             try {
-                const state = await clerk.authenticateRequest(request, {
-                    // MCP clients use Clerk OAuth access tokens; the browser operator UI
-                    // uses the signed-in operator's short-lived Clerk session token.
-                    // authorizedParties must NOT be passed here: OAuth access tokens may
-                    // be JWTs without an azp claim, and Clerk rejects azp=undefined when
-                    // that option is set. The sibling-subdomain pin it provided is
-                    // enforced below, only for session tokens that actually carry azp.
-                    acceptsToken: ["oauth_token", "session_token"],
+                const pathname = new URL(request.url).pathname;
+                const isMcp = pathname === "/mcp" || pathname.startsWith("/mcp/");
+                const state = await clerk.authenticateRequest(authorizationRequest(request), {
+                    acceptsToken: isMcp ? "oauth_token" : "session_token",
                 });
+                const browserOAuth = !tokenPresent && browserOAuthRoute;
+                // Consent can outlast Clerk's session JWT. Preserve the SDK's browser
+                // handshake, which returns here with a refreshed, verified session.
+                if (browserOAuth && state.status === "handshake" && state.headers.has("location")) {
+                    return {
+                        ok: false,
+                        response: new Response(null, {
+                            status: 307,
+                            headers: state.headers,
+                        }),
+                    };
+                }
+                if (browserOAuth)
+                    sessionCookies = state.headers?.getSetCookie();
                 const auth = state.toAuth();
                 if (!auth?.isAuthenticated) {
-                    // Reason (not the token) in the logs: bearer rejections are
-                    // otherwise indistinguishable 401s in `wrangler tail`.
-                    const detail = state;
-                    console.warn(`[connecta] clerk rejected request: status=${state.status}` +
-                        ` reason=${detail.reason ?? "?"} message=${detail.message ?? ""}` +
-                        ` tokenShape=${tokenShape(request)}`);
+                    logDenial("authentication_failed");
                     return {
                         ok: false,
                         response: unauthorized(baseUrl, tokenPresent, request),
                     };
                 }
-                // Session JWTs carry `azp` (the origin they were minted for); pin it
-                // to this connecta deployment so a sibling subdomain's cookie/token
-                // cannot be replayed here. OAuth access tokens may have no azp.
-                const typed = auth;
-                if (typed.tokenType === "session_token") {
-                    const azp = typed.sessionClaims?.azp;
+                if (isMcp) {
+                    const resource = `${resolveBase(baseUrl)}/mcp${mcpPoolSuffix(pathname) ?? ""}`;
+                    if (auth.tokenType !== "oauth_token") {
+                        logDenial("token_type_mismatch");
+                        return { ok: false, response: unauthorized(baseUrl, tokenPresent, request) };
+                    }
+                    const token = await auth.getToken();
+                    let claims;
+                    if (token.startsWith("oat_")) {
+                        try {
+                            claims = await opaqueOAuthClaims(token, opts.secretKey, auth.userId, auth.clientId, request.signal);
+                        }
+                        catch {
+                            logDenial("oauth_verification_failed");
+                            return { ok: false, response: unauthorized(baseUrl, tokenPresent, request) };
+                        }
+                    }
+                    else {
+                        claims = decodeJwt(token).payload;
+                    }
+                    const rejection = oauthBindingRejection(claims, resource, auth.clientId, allowedOAuthClientIds);
+                    if (rejection) {
+                        logDenial(rejection);
+                        return { ok: false, response: unauthorized(baseUrl, tokenPresent, request) };
+                    }
+                }
+                else {
+                    if (auth.tokenType !== "session_token") {
+                        logDenial("token_type_mismatch");
+                        return { ok: false, response: unauthorized(baseUrl, tokenPresent, request) };
+                    }
+                    // Browser session origins retain their existing deployment pin.
+                    const azp = auth.sessionClaims?.azp;
                     const origin = new URL(resolveBase(baseUrl)).origin;
                     if (azp && azp !== origin) {
-                        console.warn(`[connecta] session token azp mismatch: azp=${azp} expected=${origin}`);
-                        return {
-                            ok: false,
-                            response: unauthorized(baseUrl, tokenPresent, request),
-                        };
+                        logDenial("session_origin_mismatch");
+                        return { ok: false, response: unauthorized(baseUrl, tokenPresent, request) };
                     }
                 }
-                userId = typed.userId ?? undefined;
+                userId = auth.userId ?? undefined;
             }
-            catch (error) {
-                console.warn(`[connecta] clerk authenticateRequest threw: ${error instanceof Error ? error.message : String(error)} tokenShape=${tokenShape(request)}`);
+            catch {
+                logDenial("authentication_failed");
                 return { ok: false, response: unauthorized(baseUrl, true, request) };
             }
             if (!userId) {
+                logDenial("user_missing");
                 return { ok: false, response: unauthorized(baseUrl, true, request) };
             }
             if (!(await checkGate(userId))) {
                 return { ok: false, response: forbidden() };
             }
-            return { ok: true, userId };
+            return { ok: true, userId, ...(sessionCookies?.length ? { sessionCookies } : {}) };
         },
     };
 }

package/dist/auth/cloudflare-access.js

@@ -1,11 +1,15 @@
+import { authorizationCredential } from "../inbound-credential.js";
+import { validIdentityReference } from "../identity.js";
 function identityString(identity, field) {
     const value = identity[field];
-    return typeof value === "string" && value.length > 0 ? value : undefined;
+    return typeof value === "string" && validIdentityReference({ namespace: "cloudflare-access", id: value })
+        ? value
+        : undefined;
 }
 function unauthorized() {
     return {
         ok: false,
-        response: Response.json({ error: "Cloudflare Access authentication required" }, { status: 401 }),
+        response: Response.json({ error: "Cloudflare Access authentication required" }, { status: 401, headers: { "WWW-Authenticate": 'Bearer scope="openid email"' } }),
     };
 }
 /**
@@ -18,11 +22,15 @@ export function cloudflareAccessAuth() {
     return {
         kind: "cloudflare-access",
         interactiveOperator: true,
+        recognizesCredential: (request, context) => authorizationCredential(request).kind === "absent" && Boolean(context?.access),
+        challenge: () => 'Bearer scope="openid email"',
         activityActorNamespace: "cloudflare-access",
         uiAuth: { kind: "cloudflare-access" },
-        async authorize(_request, _baseUrl, runtimeContext) {
+        async authorize(request, _baseUrl, runtimeContext) {
+            if (authorizationCredential(request).kind !== "absent")
+                return unauthorized();
             const access = runtimeContext?.access;
-            if (!access)
+            if (!access || typeof access.aud !== "string" || !/^[\x21-\x7e]{1,256}$/.test(access.aud))
                 return unauthorized();
             let identity;
             try {
@@ -31,29 +39,20 @@ export function cloudflareAccessAuth() {
             catch {
                 return unauthorized();
             }
-            if (!identity) {
-                // Access service-token policies authenticate the request and attach
-                // ctx.access, but getIdentity() is a user-identity API and returns
-                // undefined. Cloudflare strips the service-token headers before the
-                // Worker, so the Access application audience is the only trusted,
-                // stable service attribution available without parsing a JWT.
-                return { ok: true, subjectId: access.aud };
-            }
-            const userId = identityString(identity, "user_uuid") ??
-                identityString(identity, "email");
-            const commonName = identityString(identity, "common_name");
-            const serviceTokenId = identityString(identity, "service_token_id");
+            // Access binds ctx.access.aud to its Worker application at the edge.
+            // Service credentials can pass that edge, but connecta machines must
+            // present a cta_ token to the machine provider instead.
+            const forbidden = () => ({
+                ok: false,
+                response: Response.json({ error: "Cloudflare Access human identity required" }, { status: 403 }),
+            });
+            if (!identity || typeof identity !== "object" || Array.isArray(identity))
+                return forbidden();
+            const userId = identityString(identity, "user_uuid") ?? identityString(identity, "email");
             if (identity.service_token_status === true ||
-                serviceTokenId ||
-                (!userId && commonName)) {
-                const subjectId = serviceTokenId ?? commonName;
-                return subjectId
-                    ? { ok: true, subjectId }
-                    : {
-                        ok: false,
-                        response: Response.json({ error: "Cloudflare Access service identity required" }, { status: 403 }),
-                    };
-            }
+                identityString(identity, "service_token_id") ||
+                identityString(identity, "common_name"))
+                return forbidden();
             if (!userId) {
                 return {
                     ok: false,

package/dist/auth/downstream-client-metadata.d.ts

@@ -0,0 +1,29 @@
+import type { OAuthClientMetadata } from "@modelcontextprotocol/client";
+import type { Connector } from "../types.js";
+import type { SentSecrets } from "../sent-secrets.js";
+/** A deployment-owned identity, bound to one authorization server. */
+export interface RemoteOAuthClient {
+    issuer: string;
+    clientId: string;
+    clientSecret?: string;
+    tokenEndpointAuthMethod?: "none" | "client_secret_basic" | "client_secret_post";
+}
+/** Normalize the deployment-selected default once, including revocation. */
+export declare function remoteClientAuthMethod(client: RemoteOAuthClient): "none" | "client_secret_basic" | "client_secret_post";
+/** Register raw OAuth client credentials from the final request before dispatch.
+ * Basic components use RFC 6749 form encoding, unlike ordinary Basic auth.
+ * Public client IDs remain visible; confidential IDs join their client secret. */
+export declare function trackRemoteClientRequest(secrets: SentSecrets, input: RequestInfo | URL, init?: RequestInit): void;
+export declare function assertRemoteOAuthClient(id: string, client: RemoteOAuthClient | undefined): void;
+/** The one metadata definition used for DCR, binding, and the public document. */
+export declare function downstreamClientMetadata(redirectUri: string, scope?: string, clientName?: string, method?: string): OAuthClientMetadata;
+/** Only configured public HTTPS deployments can publish a self-hosted client ID. */
+export declare function selfHostedClientUrl(publicUrl: string | undefined, id: string): string | undefined;
+/** One canonical callback for the served document and the SDK's whole flow. */
+export declare function downstreamRedirectUri(baseUrl: string, publicUrl: string | undefined, id: string): string;
+export declare function declareSelfHostedClient(connector: Connector, scope?: string): void;
+export declare function selfHostedClientDocument(connector: Connector, publicUrl: string | undefined, clientName: string): (OAuthClientMetadata & {
+    client_id: string;
+}) | undefined;
+/** RFC 6749 client authentication; deployment-selected methods never downgrade. */
+export declare function authenticateRemoteClient(client: RemoteOAuthClient, headers: Headers, params: URLSearchParams): void;