@homeflare/cloudflare 0.2.2 → 0.3.0

package/README.md

@@ -9,6 +9,78 @@ bun add @homeflare/cloudflare
 ⛔ **Workers only.** This package assumes workerd. For code that must also run on Node or
 in a script, use [`@homeflare/kit`](https://www.npmjs.com/package/@homeflare/kit).
 
+## Which auth path?
+
+Three, and they are **not alternatives** — pick by where your code runs:
+
+| your code                      | use                        | why                                                                                |
+| ------------------------------ | -------------------------- | ---------------------------------------------------------------------------------- |
+| a Worker **behind** Access     | `accessIdentity(ctx)`      | the edge already enforced the policy and attached the identity — no token handling |
+| an origin with no `ctx.access` | `verifyAccessJwt(request)` | service-to-service, a non-Worker origin, or a Worker reached by service binding    |
+| an **MCP server**              | `serveMcpMetadata()`       | neither of the above lets a client _discover_ how to authenticate                  |
+
+## accessIdentity — Workers behind Access
+
+```ts
+import { accessIdentity } from '@homeflare/cloudflare';
+
+export default {
+  async fetch(request, env, ctx) {
+    const who = await accessIdentity(ctx);
+    if (who === undefined) return new Response('Access did not run', { status: 401 });
+
+    return Response.json({ email: who.email, groups: who.groups });
+  },
+};
+```
+
+★ **Prefer this when it applies.** Cloudflare attaches the identity to the execution
+context (shipped 2026-08-14); verifying the assertion yourself re-checks something the
+platform already enforced.
+
+⛔ Returns `undefined` rather than throwing, unlike `verifyAccessJwt` — a Worker may
+legitimately serve open routes too, so "no Access here" is a branch you decide, visible at
+the call site.
+
+⚠️ **`ctx.access` does not propagate through service bindings or RPC.** A downstream Worker
+reached by binding sees `undefined` even though the caller was authenticated. It needs its
+own Access application, or to be told.
+
+⚠️ **Read groups from here, not from a token.** Cloudflare trims the JWT's `custom` claim
+at roughly 1 KB — silently — so group membership read from an assertion can be incomplete.
+That is an authorization bug that only shows up for users in many groups.
+
+## serveMcpMetadata — RFC 9728 for MCP servers
+
+```ts
+import { serveMcpMetadata, unauthorizedResponse } from '@homeflare/cloudflare';
+
+const auth = {
+  resource: 'https://mcp.example.com/mcp',
+  authorizationServer: 'https://team.cloudflareaccess.com',
+};
+
+export default {
+  async fetch(request, env, ctx) {
+    const discovery = serveMcpMetadata(request, auth);
+    if (discovery !== undefined) return discovery;
+
+    const who = await accessIdentity(ctx);
+    if (who === undefined) return unauthorizedResponse(auth);
+    // …serve MCP
+  },
+};
+```
+
+⛔ **Both halves, or neither works.** The MCP spec requires a server to publish Protected
+Resource Metadata _and_ a 401 to carry `WWW-Authenticate` naming it. Publishing the
+document while answering a bare 401 leaves clients that follow the header — the common
+path — with nowhere to go.
+
+⚠️ The well-known URL is **derived** from the resource URL, not chosen. That derivation is
+a security property: it stops anyone publishing metadata claiming to describe a resource
+they have no authority over.
+
 ## verifyAccessJwt
 
 ```ts

package/dist/access-identity.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Access identity WITHOUT parsing a JWT — the path Cloudflare added in August 2026.
+ *
+ * ★ WHEN ACCESS PROTECTS A WORKER, the edge attaches the authenticated identity to the
+ *   execution context: `ctx.access.getIdentity()` returns email, name and groups with no
+ *   token handling at all. Verifying the assertion yourself is the OLDER path, and it is
+ *   still correct for origins that have no `ctx.access` — see `verifyAccessJwt`.
+ *
+ * ⛔ THIS IS NOT A WEAKER CHECK. The edge has already refused the request if it did not
+ *   pass the Access policy; `ctx.access` exists only on requests that passed. Parsing the
+ *   JWT again re-verifies something the platform has already enforced.
+ *
+ * ⚠️ `ctx.access` IS NOT PROPAGATED THROUGH SERVICE BINDINGS OR RPC. A downstream Worker
+ *   reached by binding sees `undefined`, even though the caller was authenticated — so a
+ *   service-bound Worker that needs identity must be told, or must sit behind its own
+ *   Access application. Measured from Cloudflare's own documentation, 2026-08-14.
+ *
+ * ★ GROUPS COME FROM get-identity, NOT FROM THE TOKEN. Cloudflare trims the JWT's `custom`
+ *   claim at roughly 1 KB, silently, so group membership read from a token can be
+ *   incomplete — which is an authorization bug that only appears for users in many groups.
+ */
+/** What `ctx.access.getIdentity()` resolves. Narrowed to the fields worth depending on. */
+export interface AccessIdentityInfo {
+    readonly email: string | undefined;
+    readonly name: string | undefined;
+    readonly groups: readonly string[];
+    /** Everything else the platform returned, for callers needing a field not named here. */
+    readonly raw: Readonly<Record<string, unknown>>;
+}
+/**
+ * The slice of the execution context this module uses.
+ * ⚠️ Declared structurally rather than imported from `@cloudflare/workers-types`: this
+ *   package should not force a types dependency on a consumer for one optional field.
+ */
+export interface AccessContext {
+    readonly access?: {
+        readonly aud?: string;
+        readonly getIdentity: () => Promise<Record<string, unknown> | null | undefined>;
+    };
+}
+/** True when the request reached this Worker through Cloudflare Access. */
+export declare function hasAccess(ctx: AccessContext): boolean;
+/**
+ * The authenticated identity, or `undefined` when the request did not come through Access.
+ *
+ * ```ts
+ * const who = await accessIdentity(ctx);
+ * if (who === undefined) return new Response('Access did not run', { status: 401 });
+ * ```
+ *
+ * ⛔ RETURNS undefined RATHER THAN THROWING, deliberately — unlike `verifyAccessJwt`. A
+ *   Worker may legitimately serve both protected and open routes, so "no Access here" is
+ *   a branch rather than a failure. The caller decides what an unauthenticated request
+ *   means, and that decision is visible at the call site.
+ */
+export declare function accessIdentity(ctx: AccessContext): Promise<AccessIdentityInfo | undefined>;
+//# sourceMappingURL=access-identity.d.ts.map

package/dist/access-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-identity.d.ts","sourceRoot":"","sources":["../src/access-identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,2FAA2F;AAC3F,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,yFAAyF;IACzF,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACjD;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;KACjF,CAAC;CACH;AAED,2EAA2E;AAC3E,wBAAgB,SAAS,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAErD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAehG"}

package/dist/index.d.ts

@@ -8,7 +8,20 @@
  *   resolution.
  */
 export { VERSION } from './version.ts';
+/**
+ * ★ THREE AUTH PATHS, AND THEY ARE NOT ALTERNATIVES — pick by where your code runs:
+ *
+ *   accessIdentity(ctx)   A Worker BEHIND Access. The edge already enforced the policy
+ *                         and attached the identity; no token handling. Prefer this.
+ *   verifyAccessJwt(req)  An origin with no `ctx.access` — service-to-service, a
+ *                         non-Worker origin, or a Worker reached by service binding
+ *                         (⚠️ `ctx.access` does not propagate through bindings).
+ *   serveMcpMetadata()    An MCP server. Neither of the above helps a client DISCOVER
+ *                         how to authenticate; RFC 9728 is what does.
+ */
+export { accessIdentity, hasAccess, type AccessContext, type AccessIdentityInfo, } from './access-identity.ts';
 export { verifyAccessJwt, type AccessIdentity, type AccessOptions } from './access.ts';
+export { protectedResourceMetadata, serveMcpMetadata, unauthorizedResponse, wellKnownPath, type McpMetadataOptions, type ProtectedResourceMetadata, } from './mcp-metadata.ts';
 export { log, type LogFields, type Logger } from './log.ts';
 export { BREAKER_COOLDOWN_MS, breakered } from './jwks-breaker.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,eAAe,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACvF,OAAO,EAAE,GAAG,EAAE,KAAK,SAAS,EAAE,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC;;;;;;;;;;GAUG;AACH,OAAO,EACL,cAAc,EACd,SAAS,EACT,KAAK,aAAa,EAClB,KAAK,kBAAkB,GACxB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,eAAe,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACvF,OAAO,EACL,yBAAyB,EACzB,gBAAgB,EAChB,oBAAoB,EACpB,aAAa,EACb,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,GAC/B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,GAAG,EAAE,KAAK,SAAS,EAAE,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -1,5 +1,22 @@
 // src/version.ts
-var VERSION = "0.2.2";
+var VERSION = "0.3.0";
+// src/access-identity.ts
+function hasAccess(ctx) {
+  return ctx.access !== undefined;
+}
+async function accessIdentity(ctx) {
+  const access = ctx.access;
+  if (access === undefined)
+    return;
+  const raw = await access.getIdentity() ?? {};
+  const groups = raw["groups"];
+  return {
+    email: typeof raw["email"] === "string" ? raw["email"] : undefined,
+    name: typeof raw["name"] === "string" ? raw["name"] : undefined,
+    groups: Array.isArray(groups) ? groups.filter((g) => typeof g === "string") : [],
+    raw
+  };
+}
 // src/access.ts
 import { createRemoteJWKSet, customFetch, jwtVerify } from "jose";
 
@@ -56,6 +73,42 @@ async function verifyAccessJwt(request, options) {
     claims: payload
   };
 }
+// src/mcp-metadata.ts
+function wellKnownPath(resource) {
+  const path = new URL(resource).pathname.replace(/\/+$/, "");
+  return path === "" ? "/.well-known/oauth-protected-resource" : `/.well-known/oauth-protected-resource${path}`;
+}
+function protectedResourceMetadata(options) {
+  return {
+    resource: options.resource,
+    authorization_servers: [options.authorizationServer],
+    bearer_methods_supported: ["header"],
+    ...options.scopes === undefined ? {} : { scopes_supported: options.scopes },
+    ...options.documentation === undefined ? {} : { resource_documentation: options.documentation }
+  };
+}
+function unauthorizedResponse(options) {
+  const metadataUrl = new URL(wellKnownPath(options.resource), options.resource).href;
+  return new Response(JSON.stringify({ error: "unauthorized" }), {
+    status: 401,
+    headers: {
+      "content-type": "application/json",
+      "www-authenticate": `Bearer resource_metadata="${metadataUrl}"`
+    }
+  });
+}
+function serveMcpMetadata(request, options) {
+  const url = new URL(request.url);
+  if (url.pathname !== wellKnownPath(options.resource))
+    return;
+  return new Response(JSON.stringify(protectedResourceMetadata(options), null, 2), {
+    headers: {
+      "content-type": "application/json",
+      "access-control-allow-origin": "*",
+      "cache-control": "public, max-age=3600"
+    }
+  });
+}
 // src/log.ts
 function emit(level, message, fields) {
   const line = { level, message, ...fields };
@@ -79,10 +132,16 @@ var log = make({});
 export {
   BREAKER_COOLDOWN_MS,
   VERSION,
+  accessIdentity,
   breakered,
+  hasAccess,
   log,
-  verifyAccessJwt
+  protectedResourceMetadata,
+  serveMcpMetadata,
+  unauthorizedResponse,
+  verifyAccessJwt,
+  wellKnownPath
 };
 
-//# debugId=CB1B2943104FE54D64756E2164756E21
+//# debugId=4517D37BD676289464756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1,13 +1,15 @@
 {
   "version": 3,
-  "sources": ["../src/version.ts", "../src/access.ts", "../src/jwks-breaker.ts", "../src/log.ts"],
+  "sources": ["../src/version.ts", "../src/access-identity.ts", "../src/access.ts", "../src/jwks-breaker.ts", "../src/mcp-metadata.ts", "../src/log.ts"],
   "sourcesContent": [
-    "// ⛔ GENERATED by scripts/sync-versions.ts — do not edit. Source: package.json.\nexport const VERSION: string = '0.2.2';\n",
+    "// ⛔ GENERATED by scripts/sync-versions.ts — do not edit. Source: package.json.\nexport const VERSION: string = '0.3.0';\n",
+    "/**\n * Access identity WITHOUT parsing a JWT — the path Cloudflare added in August 2026.\n *\n * ★ WHEN ACCESS PROTECTS A WORKER, the edge attaches the authenticated identity to the\n *   execution context: `ctx.access.getIdentity()` returns email, name and groups with no\n *   token handling at all. Verifying the assertion yourself is the OLDER path, and it is\n *   still correct for origins that have no `ctx.access` — see `verifyAccessJwt`.\n *\n * ⛔ THIS IS NOT A WEAKER CHECK. The edge has already refused the request if it did not\n *   pass the Access policy; `ctx.access` exists only on requests that passed. Parsing the\n *   JWT again re-verifies something the platform has already enforced.\n *\n * ⚠️ `ctx.access` IS NOT PROPAGATED THROUGH SERVICE BINDINGS OR RPC. A downstream Worker\n *   reached by binding sees `undefined`, even though the caller was authenticated — so a\n *   service-bound Worker that needs identity must be told, or must sit behind its own\n *   Access application. Measured from Cloudflare's own documentation, 2026-08-14.\n *\n * ★ GROUPS COME FROM get-identity, NOT FROM THE TOKEN. Cloudflare trims the JWT's `custom`\n *   claim at roughly 1 KB, silently, so group membership read from a token can be\n *   incomplete — which is an authorization bug that only appears for users in many groups.\n */\n\n/** What `ctx.access.getIdentity()` resolves. Narrowed to the fields worth depending on. */\nexport interface AccessIdentityInfo {\n  readonly email: string | undefined;\n  readonly name: string | undefined;\n  readonly groups: readonly string[];\n  /** Everything else the platform returned, for callers needing a field not named here. */\n  readonly raw: Readonly<Record<string, unknown>>;\n}\n\n/**\n * The slice of the execution context this module uses.\n * ⚠️ Declared structurally rather than imported from `@cloudflare/workers-types`: this\n *   package should not force a types dependency on a consumer for one optional field.\n */\nexport interface AccessContext {\n  readonly access?: {\n    readonly aud?: string;\n    readonly getIdentity: () => Promise<Record<string, unknown> | null | undefined>;\n  };\n}\n\n/** True when the request reached this Worker through Cloudflare Access. */\nexport function hasAccess(ctx: AccessContext): boolean {\n  return ctx.access !== undefined;\n}\n\n/**\n * The authenticated identity, or `undefined` when the request did not come through Access.\n *\n * ```ts\n * const who = await accessIdentity(ctx);\n * if (who === undefined) return new Response('Access did not run', { status: 401 });\n * ```\n *\n * ⛔ RETURNS undefined RATHER THAN THROWING, deliberately — unlike `verifyAccessJwt`. A\n *   Worker may legitimately serve both protected and open routes, so \"no Access here\" is\n *   a branch rather than a failure. The caller decides what an unauthenticated request\n *   means, and that decision is visible at the call site.\n */\nexport async function accessIdentity(ctx: AccessContext): Promise<AccessIdentityInfo | undefined> {\n  const access = ctx.access;\n  if (access === undefined) return undefined;\n\n  const raw = (await access.getIdentity()) ?? {};\n  const groups = raw['groups'];\n\n  return {\n    email: typeof raw['email'] === 'string' ? raw['email'] : undefined,\n    name: typeof raw['name'] === 'string' ? raw['name'] : undefined,\n    // ⚠️ Always an array, never undefined: a caller writing `groups.includes(…)` on a\n    //   missing field would throw at exactly the moment authorization is being decided.\n    groups: Array.isArray(groups) ? groups.filter((g): g is string => typeof g === 'string') : [],\n    raw,\n  };\n}\n",
     "/**\n * Cloudflare Access JWT verification.\n *\n * ★ WHY jose AND NOT A HAND-ROLLED VERIFY. Signature verification is the one place where\n *   a subtle bug is silent and total: a check that never fails looks identical to a\n *   check that always passes. jose handles JWKS fetching, `kid` matching and key\n *   rotation, and it is widely deployed. This file is the Access-specific\n *   wiring around it, nothing more.\n *\n * ⚠️ THE TRAP THIS CLOSES. Cloudflare's own example does `jwtVerify(...)` inline in the\n *   handler, which builds a NEW remote JWKS on every request — an outbound fetch per\n *   request, and a thundering herd on the certs endpoint under load. The cache below is\n *   keyed by team domain and lives for the isolate's lifetime.\n *\n * ⛔ NEVER SKIP `audience`. Any Access app in your account produces a JWT this team\n *   domain will happily verify; the AUD tag is the only thing that says the token was\n *   minted for THIS app. Verifying issuer alone accepts tokens from a neighbouring app.\n *\n * Docs: developers.cloudflare.com/cloudflare-one/identity/authorization-cookie/validating-json/\n */\nimport { createRemoteJWKSet, customFetch, jwtVerify } from 'jose';\nimport { breakered } from './jwks-breaker.ts';\n\n/** The header Access puts the token in. Lowercase — Headers.get is case-insensitive. */\nconst ACCESS_HEADER = 'cf-access-jwt-assertion';\n\nexport interface AccessOptions {\n  /** `https://<team>.cloudflareaccess.com` — the issuer, and the JWKS host. */\n  readonly teamDomain: string;\n  /** The application's AUD tag, from Zero Trust → Access → Applications. */\n  readonly audience: string;\n}\n\n/** The subset of Access claims worth depending on. */\nexport interface AccessIdentity {\n  readonly email: string | undefined;\n  readonly sub: string | undefined;\n  /** Everything else, for callers that need a claim this interface does not name. */\n  readonly claims: Readonly<Record<string, unknown>>;\n}\n\n/**\n * One JWKS per team domain, reused for the isolate's life.\n * ⚠️ Module scope is per-isolate on workerd, not per-request and not global. That is\n *   exactly the right lifetime here: long enough to amortise the fetch, short enough\n *   that a rotated key is picked up when the isolate recycles. jose also refreshes on\n *   an unknown `kid`.\n */\nconst jwks = new Map<string, ReturnType<typeof createRemoteJWKSet>>();\n\nfunction keysFor(teamDomain: string): ReturnType<typeof createRemoteJWKSet> {\n  const existing = jwks.get(teamDomain);\n  if (existing !== undefined) return existing;\n\n  // ⛔ THE BREAKER IS NOT OPTIONAL. jose refetches on EVERY call while an endpoint is\n  //   down — measured on 6.2.12: 5 verifications against a 404ing certs endpoint made 5\n  //   outbound fetches, and no combination of cacheMaxAge or cooldownDuration changes it.\n  //   Without this, a Cloudflare Access outage turns every inbound request into an\n  //   outbound one. See jwks-breaker.ts.\n  const created = createRemoteJWKSet(new URL(`${teamDomain}/cdn-cgi/access/certs`), {\n    [customFetch]: breakered(),\n  });\n  jwks.set(teamDomain, created);\n  return created;\n}\n\n/**\n * Verify the Access JWT on `request`, returning the identity it asserts.\n *\n * ⛔ THROWS ON EVERY FAILURE — missing header, bad signature, wrong audience, expired.\n *   ★ Deliberately not a boolean or a null: an `if (!ok)` that a caller forgets to write\n *     is an open door, whereas an unhandled throw is a 500 and a log line. Callers that\n *     want a soft path catch it explicitly.\n */\nexport async function verifyAccessJwt(\n  request: Request,\n  options: AccessOptions,\n): Promise<AccessIdentity> {\n  const token = request.headers.get(ACCESS_HEADER);\n  if (token === null) throw new Error('access: no Cf-Access-Jwt-Assertion header');\n\n  const { payload } = await jwtVerify(token, keysFor(options.teamDomain), {\n    issuer: options.teamDomain,\n    audience: options.audience,\n  });\n\n  return {\n    email: typeof payload['email'] === 'string' ? payload['email'] : undefined,\n    sub: payload.sub,\n    claims: payload,\n  };\n}\n",
     "/**\n * A circuit breaker for JWKS fetches, installed at jose's own `customFetch` seam.\n *\n * ⛔ THE AMPLIFICATION THIS CLOSES, MEASURED ON jose 6.2.12 — the version this package\n *   pins, not an old one:\n *\n *       5 verifications of a well-formed token, certs endpoint 404ing → 5 outbound fetches\n *\n *   jose assigns `jwksTimestamp` only inside the `.then()` of a SUCCESSFUL fetch\n *   (`dist/webapi/jwks/remote.js`, line 58). While an endpoint is down, `local` stays\n *   undefined, so `if (!local || !isFreshFor(jwksTimestamp, cacheMaxAge)) await reload()`\n *   runs on EVERY call. A down Access endpoint therefore turns every inbound request into\n *   an outbound fetch, indefinitely.\n *\n * ★ NOT A REIMPLEMENTATION. `customFetch` is jose's exported, documented extension point;\n *   jose keeps doing the caching, cooldown, `kid` matching and verification. This adds the\n *   one thing it does not do — remember that a fetch FAILED.\n *   ⚠️ Measured first: neither `cacheMaxAge: Infinity` nor `cooldownDuration` nor both\n *     together change the count. It is 5 fetches in every configuration, so this is not a\n *     matter of configuring jose correctly.\n *\n * ⛔ THE BREAKER STORES PLAIN VALUES ONLY — a timestamp and an Error. NEVER a Response, a\n *   body stream, or a promise of one.\n *   🔴 On workerd, a Response and its body belong to the IoContext of the request that\n *     created them, and another request touching either throws:\n *         Cannot perform I/O on behalf of a different request.\n *     Caching a Response across requests would therefore turn a VALID token into a flat\n *     401 for every caller but the first — an outage strictly worse than the amplification\n *     it was meant to fix. Timestamps and Errors cross requests legally; I/O objects do not.\n */\n\nimport type { FetchImplementation } from 'jose';\n\n/** How long a URL stays latched open after a failed probe. */\nexport const BREAKER_COOLDOWN_MS = 30_000;\n\ntype Failure = { readonly at: number; readonly error: Error };\n\n/**\n * ⚠️ Module scope is PER ISOLATE on workerd, which is the right lifetime: long enough to\n *   stop the storm, short enough that a recycled isolate retries a recovered endpoint.\n */\nconst failures = new Map<string, Failure>();\n\n/** Visible for testing. ⛔ Not exported from the package — resetting it in production\n *  would discard exactly the memory this exists to keep. */\nexport function resetBreaker(): void {\n  failures.clear();\n}\n\n/**\n * Wrap a fetch so a failing URL is not retried for `cooldownMs`.\n *\n * ★ FAILURE IS COUNTED AT THE SEAM, not inferred from an error class further up. jose\n *   throws `JWKSNoMatchingKey` as a NORMAL answer from a perfectly healthy endpoint — a\n *   token signed with a rotated key does that — so treating it as a fault would latch a\n *   working endpoint closed and reject every valid token for 30 seconds.\n */\nexport function breakered(\n  inner: FetchImplementation = (url, options) => fetch(url, options),\n  cooldownMs: number = BREAKER_COOLDOWN_MS,\n): FetchImplementation {\n  // ⚠️ jose's OWN FetchImplementation, not `typeof fetch`. It is narrower — a string URL\n  //   and a fixed options shape — and using the global type instead fails to typecheck on\n  //   `preconnect`, a property of the platform fetch that no seam implementation has.\n  return async (url, options) => {\n    const open = failures.get(url);\n\n    if (open !== undefined && Date.now() - open.at < cooldownMs) {\n      // ⚠️ Rethrow the ORIGINAL error, not a generic one: the first failure says whether\n      //   this was a 404, a TLS problem or a timeout, and that is what an operator needs.\n      //   A \"circuit open\" message alone hides the actual fault.\n      throw open.error;\n    }\n\n    try {\n      const response = await inner(url, options);\n\n      // ⛔ A non-200 is a failure here. jose requires 200 with a JSON body; a 404 or a 502\n      //   is exactly the down-endpoint case, and it does NOT throw on its own.\n      if (!response.ok) {\n        const error = new Error(`JWKS endpoint answered ${String(response.status)}: ${url}`);\n        failures.set(url, { at: Date.now(), error });\n        throw error;\n      }\n\n      failures.delete(url);\n      return response;\n    } catch (cause) {\n      const error = cause instanceof Error ? cause : new Error(String(cause));\n      // `set` is idempotent here — a second failure simply restarts the cooldown.\n      failures.set(url, { at: Date.now(), error });\n      throw error;\n    }\n  };\n}\n",
+    "/**\n * RFC 9728 discovery for an MCP server — the third auth path, and the one a client\n * actually needs to find its way in.\n *\n * ★ THE MCP SPEC REQUIRES THIS. A server MUST publish OAuth 2.0 Protected Resource\n *   Metadata, and a client MUST use it to discover the authorization server. Without it a\n *   client cannot begin the flow, and has to be told endpoints out of band — which is\n *   exactly the gap that leaves real servers (Atlassian's, measured 2026) undiscoverable\n *   by spec-compliant clients.\n *\n * ⛔ TWO HALVES, AND ONE ALONE DOES NOT WORK:\n *     1. `GET /.well-known/oauth-protected-resource` returns the metadata document.\n *     2. A 401 carries `WWW-Authenticate` naming that document's URL.\n *   A client may start from either. Publishing the document but answering a bare 401 leaves\n *   clients that follow the header — the common path — with nowhere to go.\n *\n * ⚠️ THE WELL-KNOWN URL IS DERIVED FROM THE RESOURCE URL, NOT CHOSEN. That derivation is a\n *   security property, not a convention: it stops an attacker publishing metadata that\n *   claims to describe a resource it has no authority over.\n *\n * ★ NO I/O AT MODULE SCOPE. Everything here is pure, because a Worker cannot make network\n *   calls during module initialization — a metadata helper that fetched at import would\n *   fail on the edge and nowhere else.\n */\n\n/** The subset of RFC 9728 an MCP server needs. Extra fields pass through untouched. */\nexport interface ProtectedResourceMetadata {\n  /** The resource's own canonical URL. ⛔ Must match what clients call, exactly. */\n  readonly resource: string;\n  /** Authorization servers that issue tokens for it. */\n  readonly authorization_servers: readonly string[];\n  readonly scopes_supported?: readonly string[];\n  readonly bearer_methods_supported?: readonly string[];\n  readonly resource_documentation?: string;\n}\n\nexport interface McpMetadataOptions {\n  /** The MCP endpoint clients call, e.g. `https://mcp.example.com/mcp`. */\n  readonly resource: string;\n  /**\n   * The issuer. For Cloudflare's managed OAuth this is your team domain,\n   * `https://<team>.cloudflareaccess.com`.\n   */\n  readonly authorizationServer: string;\n  readonly scopes?: readonly string[];\n  readonly documentation?: string;\n}\n\n/**\n * The well-known path for a resource URL, derived per RFC 9728.\n *\n * ⚠️ A RESOURCE WITH A PATH KEEPS IT, AFTER the well-known segment:\n *     https://example.com/mcp → /.well-known/oauth-protected-resource/mcp\n *   Serving it at the root instead is the mistake that makes a multi-resource server\n *   advertise one resource's metadata for all of them.\n */\nexport function wellKnownPath(resource: string): string {\n  const path = new URL(resource).pathname.replace(/\\/+$/, '');\n  return path === ''\n    ? '/.well-known/oauth-protected-resource'\n    : `/.well-known/oauth-protected-resource${path}`;\n}\n\n/** Build the metadata document. Pure — no I/O, safe at module scope. */\nexport function protectedResourceMetadata(options: McpMetadataOptions): ProtectedResourceMetadata {\n  return {\n    resource: options.resource,\n    authorization_servers: [options.authorizationServer],\n    // ⚠️ `header` only. A bearer token in a query string lands in access logs and in\n    //   Referer, and RFC 6750 discourages it for exactly that reason.\n    bearer_methods_supported: ['header'],\n    ...(options.scopes === undefined ? {} : { scopes_supported: options.scopes }),\n    ...(options.documentation === undefined\n      ? {}\n      : { resource_documentation: options.documentation }),\n  };\n}\n\n/**\n * The 401 an unauthenticated MCP request must receive.\n *\n * ⛔ THE `resource_metadata` PARAMETER IS THE WHOLE POINT. A bare `WWW-Authenticate:\n *   Bearer` tells a client it needs a token but not where to get one, so discovery dead-ends\n *   and the client falls back to hardcoded endpoints — or fails.\n */\nexport function unauthorizedResponse(options: McpMetadataOptions): Response {\n  const metadataUrl = new URL(wellKnownPath(options.resource), options.resource).href;\n\n  return new Response(JSON.stringify({ error: 'unauthorized' }), {\n    status: 401,\n    headers: {\n      'content-type': 'application/json',\n      'www-authenticate': `Bearer resource_metadata=\"${metadataUrl}\"`,\n    },\n  });\n}\n\n/**\n * Serve the metadata document when the request is for it, otherwise `undefined`.\n *\n * ```ts\n * const discovery = serveMcpMetadata(request, { resource, authorizationServer });\n * if (discovery !== undefined) return discovery;\n * ```\n *\n * ⚠️ CORS IS OPEN HERE ON PURPOSE. Discovery metadata is public by definition — a client\n *   must read it BEFORE it has a token, often from a browser origin the server has never\n *   seen. Locking it down breaks the flow it exists to start.\n */\nexport function serveMcpMetadata(\n  request: Request,\n  options: McpMetadataOptions,\n): Response | undefined {\n  const url = new URL(request.url);\n  if (url.pathname !== wellKnownPath(options.resource)) return undefined;\n\n  return new Response(JSON.stringify(protectedResourceMetadata(options), null, 2), {\n    headers: {\n      'content-type': 'application/json',\n      'access-control-allow-origin': '*',\n      'cache-control': 'public, max-age=3600',\n    },\n  });\n}\n",
     "/**\n * Structured logging for Workers.\n *\n * ★ WHY NO LOGGING LIBRARY. Cloudflare Workers Logs parses `console.log` output as JSON\n *   natively and indexes every field, with unlimited cardinality — so a JSON object on\n *   console IS the structured logging integration. pino is Node-shaped (streams, worker\n *   threads) and needs a wrapper on workerd; `pino-pretty` does not work with wrangler\n *   at all (workers-sdk#6841). Adding a dependency here would buy formatting we do not\n *   want and cost bundle size on a hot path.\n *   Docs: developers.cloudflare.com/workers/observability/logs/workers-logs/\n *\n * ⛔ NEVER LOG A CREDENTIAL. There is no redaction layer here and deliberately so — a\n *   redactor implies it is safe to pass secrets in, and then quietly misses one.\n */\n\n/** Anything JSON-serialisable. Workers Logs indexes each key as its own field. */\nexport type LogFields = Readonly<Record<string, unknown>>;\n\nexport interface Logger {\n  readonly debug: (message: string, fields?: LogFields) => void;\n  readonly info: (message: string, fields?: LogFields) => void;\n  readonly warn: (message: string, fields?: LogFields) => void;\n  readonly error: (message: string, fields?: LogFields) => void;\n  /** Returns a logger that merges `bound` into every subsequent line. */\n  readonly with: (bound: LogFields) => Logger;\n}\n\ntype Level = 'debug' | 'info' | 'warn' | 'error';\n\nfunction emit(level: Level, message: string, fields: LogFields): void {\n  // ⚠️ ONE OBJECT, NOT (message, fields). console.log with several arguments is\n  //   stringified and concatenated by the runtime, which destroys the structure Workers\n  //   Logs would otherwise index — the symptom is a `message` field containing your\n  //   whole payload as text, unqueryable.\n  const line = { level, message, ...fields };\n\n  if (level === 'error') console.error(line);\n  else if (level === 'warn') console.warn(line);\n  else console.log(line);\n}\n\nfunction make(bound: LogFields): Logger {\n  return {\n    debug: (message, fields) => emit('debug', message, { ...bound, ...fields }),\n    info: (message, fields) => emit('info', message, { ...bound, ...fields }),\n    warn: (message, fields) => emit('warn', message, { ...bound, ...fields }),\n    error: (message, fields) => emit('error', message, { ...bound, ...fields }),\n    with: (extra) => make({ ...bound, ...extra }),\n  };\n}\n\n/**\n * The root logger. Bind request-scoped context rather than passing it every call:\n *\n *     const requestLog = log.with({ requestId, path: url.pathname });\n *     requestLog.info('handled', { status, ms });\n */\nexport const log: Logger = make({});\n"
   ],
-  "mappings": ";AACO,IAAM,UAAkB;;ACmB/B;;;ACcO,IAAM,sBAAsB;AAQnC,IAAM,WAAW,IAAI;AAgBd,SAAS,SAAS,CACvB,QAA6B,CAAC,KAAK,YAAY,MAAM,KAAK,OAAO,GACjE,aAAqB,qBACA;AAAA,EAIrB,OAAO,OAAO,KAAK,YAAY;AAAA,IAC7B,MAAM,OAAO,SAAS,IAAI,GAAG;AAAA,IAE7B,IAAI,SAAS,aAAa,KAAK,IAAI,IAAI,KAAK,KAAK,YAAY;AAAA,MAI3D,MAAM,KAAK;AAAA,IACb;AAAA,IAEA,IAAI;AAAA,MACF,MAAM,WAAW,MAAM,MAAM,KAAK,OAAO;AAAA,MAIzC,IAAI,CAAC,SAAS,IAAI;AAAA,QAChB,MAAM,QAAQ,IAAI,MAAM,0BAA0B,OAAO,SAAS,MAAM,MAAM,KAAK;AAAA,QACnF,SAAS,IAAI,KAAK,EAAE,IAAI,KAAK,IAAI,GAAG,MAAM,CAAC;AAAA,QAC3C,MAAM;AAAA,MACR;AAAA,MAEA,SAAS,OAAO,GAAG;AAAA,MACnB,OAAO;AAAA,MACP,OAAO,OAAO;AAAA,MACd,MAAM,QAAQ,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC;AAAA,MAEtE,SAAS,IAAI,KAAK,EAAE,IAAI,KAAK,IAAI,GAAG,MAAM,CAAC;AAAA,MAC3C,MAAM;AAAA;AAAA;AAAA;;;ADpEZ,IAAM,gBAAgB;AAwBtB,IAAM,OAAO,IAAI;AAEjB,SAAS,OAAO,CAAC,YAA2D;AAAA,EAC1E,MAAM,WAAW,KAAK,IAAI,UAAU;AAAA,EACpC,IAAI,aAAa;AAAA,IAAW,OAAO;AAAA,EAOnC,MAAM,UAAU,mBAAmB,IAAI,IAAI,GAAG,iCAAiC,GAAG;AAAA,KAC/E,cAAc,UAAU;AAAA,EAC3B,CAAC;AAAA,EACD,KAAK,IAAI,YAAY,OAAO;AAAA,EAC5B,OAAO;AAAA;AAWT,eAAsB,eAAe,CACnC,SACA,SACyB;AAAA,EACzB,MAAM,QAAQ,QAAQ,QAAQ,IAAI,aAAa;AAAA,EAC/C,IAAI,UAAU;AAAA,IAAM,MAAM,IAAI,MAAM,2CAA2C;AAAA,EAE/E,QAAQ,YAAY,MAAM,UAAU,OAAO,QAAQ,QAAQ,UAAU,GAAG;AAAA,IACtE,QAAQ,QAAQ;AAAA,IAChB,UAAU,QAAQ;AAAA,EACpB,CAAC;AAAA,EAED,OAAO;AAAA,IACL,OAAO,OAAO,QAAQ,aAAa,WAAW,QAAQ,WAAW;AAAA,IACjE,KAAK,QAAQ;AAAA,IACb,QAAQ;AAAA,EACV;AAAA;;AE7DF,SAAS,IAAI,CAAC,OAAc,SAAiB,QAAyB;AAAA,EAKpE,MAAM,OAAO,EAAE,OAAO,YAAY,OAAO;AAAA,EAEzC,IAAI,UAAU;AAAA,IAAS,QAAQ,MAAM,IAAI;AAAA,EACpC,SAAI,UAAU;AAAA,IAAQ,QAAQ,KAAK,IAAI;AAAA,EACvC;AAAA,YAAQ,IAAI,IAAI;AAAA;AAGvB,SAAS,IAAI,CAAC,OAA0B;AAAA,EACtC,OAAO;AAAA,IACL,OAAO,CAAC,SAAS,WAAW,KAAK,SAAS,SAAS,KAAK,UAAU,OAAO,CAAC;AAAA,IAC1E,MAAM,CAAC,SAAS,WAAW,KAAK,QAAQ,SAAS,KAAK,UAAU,OAAO,CAAC;AAAA,IACxE,MAAM,CAAC,SAAS,WAAW,KAAK,QAAQ,SAAS,KAAK,UAAU,OAAO,CAAC;AAAA,IACxE,OAAO,CAAC,SAAS,WAAW,KAAK,SAAS,SAAS,KAAK,UAAU,OAAO,CAAC;AAAA,IAC1E,MAAM,CAAC,UAAU,KAAK,KAAK,UAAU,MAAM,CAAC;AAAA,EAC9C;AAAA;AASK,IAAM,MAAc,KAAK,CAAC,CAAC;",
-  "debugId": "CB1B2943104FE54D64756E2164756E21",
+  "mappings": "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",
+  "debugId": "4517D37BD676289464756E2164756E21",
   "names": []
 }

package/dist/mcp-metadata.d.ts

@@ -0,0 +1,78 @@
+/**
+ * RFC 9728 discovery for an MCP server — the third auth path, and the one a client
+ * actually needs to find its way in.
+ *
+ * ★ THE MCP SPEC REQUIRES THIS. A server MUST publish OAuth 2.0 Protected Resource
+ *   Metadata, and a client MUST use it to discover the authorization server. Without it a
+ *   client cannot begin the flow, and has to be told endpoints out of band — which is
+ *   exactly the gap that leaves real servers (Atlassian's, measured 2026) undiscoverable
+ *   by spec-compliant clients.
+ *
+ * ⛔ TWO HALVES, AND ONE ALONE DOES NOT WORK:
+ *     1. `GET /.well-known/oauth-protected-resource` returns the metadata document.
+ *     2. A 401 carries `WWW-Authenticate` naming that document's URL.
+ *   A client may start from either. Publishing the document but answering a bare 401 leaves
+ *   clients that follow the header — the common path — with nowhere to go.
+ *
+ * ⚠️ THE WELL-KNOWN URL IS DERIVED FROM THE RESOURCE URL, NOT CHOSEN. That derivation is a
+ *   security property, not a convention: it stops an attacker publishing metadata that
+ *   claims to describe a resource it has no authority over.
+ *
+ * ★ NO I/O AT MODULE SCOPE. Everything here is pure, because a Worker cannot make network
+ *   calls during module initialization — a metadata helper that fetched at import would
+ *   fail on the edge and nowhere else.
+ */
+/** The subset of RFC 9728 an MCP server needs. Extra fields pass through untouched. */
+export interface ProtectedResourceMetadata {
+    /** The resource's own canonical URL. ⛔ Must match what clients call, exactly. */
+    readonly resource: string;
+    /** Authorization servers that issue tokens for it. */
+    readonly authorization_servers: readonly string[];
+    readonly scopes_supported?: readonly string[];
+    readonly bearer_methods_supported?: readonly string[];
+    readonly resource_documentation?: string;
+}
+export interface McpMetadataOptions {
+    /** The MCP endpoint clients call, e.g. `https://mcp.example.com/mcp`. */
+    readonly resource: string;
+    /**
+     * The issuer. For Cloudflare's managed OAuth this is your team domain,
+     * `https://<team>.cloudflareaccess.com`.
+     */
+    readonly authorizationServer: string;
+    readonly scopes?: readonly string[];
+    readonly documentation?: string;
+}
+/**
+ * The well-known path for a resource URL, derived per RFC 9728.
+ *
+ * ⚠️ A RESOURCE WITH A PATH KEEPS IT, AFTER the well-known segment:
+ *     https://example.com/mcp → /.well-known/oauth-protected-resource/mcp
+ *   Serving it at the root instead is the mistake that makes a multi-resource server
+ *   advertise one resource's metadata for all of them.
+ */
+export declare function wellKnownPath(resource: string): string;
+/** Build the metadata document. Pure — no I/O, safe at module scope. */
+export declare function protectedResourceMetadata(options: McpMetadataOptions): ProtectedResourceMetadata;
+/**
+ * The 401 an unauthenticated MCP request must receive.
+ *
+ * ⛔ THE `resource_metadata` PARAMETER IS THE WHOLE POINT. A bare `WWW-Authenticate:
+ *   Bearer` tells a client it needs a token but not where to get one, so discovery dead-ends
+ *   and the client falls back to hardcoded endpoints — or fails.
+ */
+export declare function unauthorizedResponse(options: McpMetadataOptions): Response;
+/**
+ * Serve the metadata document when the request is for it, otherwise `undefined`.
+ *
+ * ```ts
+ * const discovery = serveMcpMetadata(request, { resource, authorizationServer });
+ * if (discovery !== undefined) return discovery;
+ * ```
+ *
+ * ⚠️ CORS IS OPEN HERE ON PURPOSE. Discovery metadata is public by definition — a client
+ *   must read it BEFORE it has a token, often from a browser origin the server has never
+ *   seen. Locking it down breaks the flow it exists to start.
+ */
+export declare function serveMcpMetadata(request: Request, options: McpMetadataOptions): Response | undefined;
+//# sourceMappingURL=mcp-metadata.d.ts.map

package/dist/mcp-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-metadata.d.ts","sourceRoot":"","sources":["../src/mcp-metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,uFAAuF;AACvF,MAAM,WAAW,yBAAyB;IACxC,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,sDAAsD;IACtD,QAAQ,CAAC,qBAAqB,EAAE,SAAS,MAAM,EAAE,CAAC;IAClD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C,QAAQ,CAAC,wBAAwB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtD,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;CAC1C;AAED,MAAM,WAAW,kBAAkB;IACjC,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKtD;AAED,wEAAwE;AACxE,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,kBAAkB,GAAG,yBAAyB,CAYhG;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,kBAAkB,GAAG,QAAQ,CAU1E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,kBAAkB,GAC1B,QAAQ,GAAG,SAAS,CAWtB"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@homeflare/cloudflare",
-  "version": "0.2.2",
-  "description": "Cloudflare Workers helpers: Access JWT verification, typed bindings, structured logging.",
+  "version": "0.3.0",
+  "description": "Cloudflare Workers helpers: Access identity, MCP OAuth metadata, and structured logging.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/cloudflare#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",
   "license": "MIT",
@@ -30,7 +30,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@homeflare/kit": "0.2.2",
+    "@homeflare/kit": "0.2.3",
     "jose": "6.2.12"
   }
 }

package/src/access-identity.ts

@@ -0,0 +1,77 @@
+/**
+ * Access identity WITHOUT parsing a JWT — the path Cloudflare added in August 2026.
+ *
+ * ★ WHEN ACCESS PROTECTS A WORKER, the edge attaches the authenticated identity to the
+ *   execution context: `ctx.access.getIdentity()` returns email, name and groups with no
+ *   token handling at all. Verifying the assertion yourself is the OLDER path, and it is
+ *   still correct for origins that have no `ctx.access` — see `verifyAccessJwt`.
+ *
+ * ⛔ THIS IS NOT A WEAKER CHECK. The edge has already refused the request if it did not
+ *   pass the Access policy; `ctx.access` exists only on requests that passed. Parsing the
+ *   JWT again re-verifies something the platform has already enforced.
+ *
+ * ⚠️ `ctx.access` IS NOT PROPAGATED THROUGH SERVICE BINDINGS OR RPC. A downstream Worker
+ *   reached by binding sees `undefined`, even though the caller was authenticated — so a
+ *   service-bound Worker that needs identity must be told, or must sit behind its own
+ *   Access application. Measured from Cloudflare's own documentation, 2026-08-14.
+ *
+ * ★ GROUPS COME FROM get-identity, NOT FROM THE TOKEN. Cloudflare trims the JWT's `custom`
+ *   claim at roughly 1 KB, silently, so group membership read from a token can be
+ *   incomplete — which is an authorization bug that only appears for users in many groups.
+ */
+
+/** What `ctx.access.getIdentity()` resolves. Narrowed to the fields worth depending on. */
+export interface AccessIdentityInfo {
+  readonly email: string | undefined;
+  readonly name: string | undefined;
+  readonly groups: readonly string[];
+  /** Everything else the platform returned, for callers needing a field not named here. */
+  readonly raw: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * The slice of the execution context this module uses.
+ * ⚠️ Declared structurally rather than imported from `@cloudflare/workers-types`: this
+ *   package should not force a types dependency on a consumer for one optional field.
+ */
+export interface AccessContext {
+  readonly access?: {
+    readonly aud?: string;
+    readonly getIdentity: () => Promise<Record<string, unknown> | null | undefined>;
+  };
+}
+
+/** True when the request reached this Worker through Cloudflare Access. */
+export function hasAccess(ctx: AccessContext): boolean {
+  return ctx.access !== undefined;
+}
+
+/**
+ * The authenticated identity, or `undefined` when the request did not come through Access.
+ *
+ * ```ts
+ * const who = await accessIdentity(ctx);
+ * if (who === undefined) return new Response('Access did not run', { status: 401 });
+ * ```
+ *
+ * ⛔ RETURNS undefined RATHER THAN THROWING, deliberately — unlike `verifyAccessJwt`. A
+ *   Worker may legitimately serve both protected and open routes, so "no Access here" is
+ *   a branch rather than a failure. The caller decides what an unauthenticated request
+ *   means, and that decision is visible at the call site.
+ */
+export async function accessIdentity(ctx: AccessContext): Promise<AccessIdentityInfo | undefined> {
+  const access = ctx.access;
+  if (access === undefined) return undefined;
+
+  const raw = (await access.getIdentity()) ?? {};
+  const groups = raw['groups'];
+
+  return {
+    email: typeof raw['email'] === 'string' ? raw['email'] : undefined,
+    name: typeof raw['name'] === 'string' ? raw['name'] : undefined,
+    // ⚠️ Always an array, never undefined: a caller writing `groups.includes(…)` on a
+    //   missing field would throw at exactly the moment authorization is being decided.
+    groups: Array.isArray(groups) ? groups.filter((g): g is string => typeof g === 'string') : [],
+    raw,
+  };
+}

package/src/index.ts

@@ -9,6 +9,31 @@
  */
 
 export { VERSION } from './version.ts';
+/**
+ * ★ THREE AUTH PATHS, AND THEY ARE NOT ALTERNATIVES — pick by where your code runs:
+ *
+ *   accessIdentity(ctx)   A Worker BEHIND Access. The edge already enforced the policy
+ *                         and attached the identity; no token handling. Prefer this.
+ *   verifyAccessJwt(req)  An origin with no `ctx.access` — service-to-service, a
+ *                         non-Worker origin, or a Worker reached by service binding
+ *                         (⚠️ `ctx.access` does not propagate through bindings).
+ *   serveMcpMetadata()    An MCP server. Neither of the above helps a client DISCOVER
+ *                         how to authenticate; RFC 9728 is what does.
+ */
+export {
+  accessIdentity,
+  hasAccess,
+  type AccessContext,
+  type AccessIdentityInfo,
+} from './access-identity.ts';
 export { verifyAccessJwt, type AccessIdentity, type AccessOptions } from './access.ts';
+export {
+  protectedResourceMetadata,
+  serveMcpMetadata,
+  unauthorizedResponse,
+  wellKnownPath,
+  type McpMetadataOptions,
+  type ProtectedResourceMetadata,
+} from './mcp-metadata.ts';
 export { log, type LogFields, type Logger } from './log.ts';
 export { BREAKER_COOLDOWN_MS, breakered } from './jwks-breaker.ts';

package/src/mcp-metadata.ts

@@ -0,0 +1,124 @@
+/**
+ * RFC 9728 discovery for an MCP server — the third auth path, and the one a client
+ * actually needs to find its way in.
+ *
+ * ★ THE MCP SPEC REQUIRES THIS. A server MUST publish OAuth 2.0 Protected Resource
+ *   Metadata, and a client MUST use it to discover the authorization server. Without it a
+ *   client cannot begin the flow, and has to be told endpoints out of band — which is
+ *   exactly the gap that leaves real servers (Atlassian's, measured 2026) undiscoverable
+ *   by spec-compliant clients.
+ *
+ * ⛔ TWO HALVES, AND ONE ALONE DOES NOT WORK:
+ *     1. `GET /.well-known/oauth-protected-resource` returns the metadata document.
+ *     2. A 401 carries `WWW-Authenticate` naming that document's URL.
+ *   A client may start from either. Publishing the document but answering a bare 401 leaves
+ *   clients that follow the header — the common path — with nowhere to go.
+ *
+ * ⚠️ THE WELL-KNOWN URL IS DERIVED FROM THE RESOURCE URL, NOT CHOSEN. That derivation is a
+ *   security property, not a convention: it stops an attacker publishing metadata that
+ *   claims to describe a resource it has no authority over.
+ *
+ * ★ NO I/O AT MODULE SCOPE. Everything here is pure, because a Worker cannot make network
+ *   calls during module initialization — a metadata helper that fetched at import would
+ *   fail on the edge and nowhere else.
+ */
+
+/** The subset of RFC 9728 an MCP server needs. Extra fields pass through untouched. */
+export interface ProtectedResourceMetadata {
+  /** The resource's own canonical URL. ⛔ Must match what clients call, exactly. */
+  readonly resource: string;
+  /** Authorization servers that issue tokens for it. */
+  readonly authorization_servers: readonly string[];
+  readonly scopes_supported?: readonly string[];
+  readonly bearer_methods_supported?: readonly string[];
+  readonly resource_documentation?: string;
+}
+
+export interface McpMetadataOptions {
+  /** The MCP endpoint clients call, e.g. `https://mcp.example.com/mcp`. */
+  readonly resource: string;
+  /**
+   * The issuer. For Cloudflare's managed OAuth this is your team domain,
+   * `https://<team>.cloudflareaccess.com`.
+   */
+  readonly authorizationServer: string;
+  readonly scopes?: readonly string[];
+  readonly documentation?: string;
+}
+
+/**
+ * The well-known path for a resource URL, derived per RFC 9728.
+ *
+ * ⚠️ A RESOURCE WITH A PATH KEEPS IT, AFTER the well-known segment:
+ *     https://example.com/mcp → /.well-known/oauth-protected-resource/mcp
+ *   Serving it at the root instead is the mistake that makes a multi-resource server
+ *   advertise one resource's metadata for all of them.
+ */
+export function wellKnownPath(resource: string): string {
+  const path = new URL(resource).pathname.replace(/\/+$/, '');
+  return path === ''
+    ? '/.well-known/oauth-protected-resource'
+    : `/.well-known/oauth-protected-resource${path}`;
+}
+
+/** Build the metadata document. Pure — no I/O, safe at module scope. */
+export function protectedResourceMetadata(options: McpMetadataOptions): ProtectedResourceMetadata {
+  return {
+    resource: options.resource,
+    authorization_servers: [options.authorizationServer],
+    // ⚠️ `header` only. A bearer token in a query string lands in access logs and in
+    //   Referer, and RFC 6750 discourages it for exactly that reason.
+    bearer_methods_supported: ['header'],
+    ...(options.scopes === undefined ? {} : { scopes_supported: options.scopes }),
+    ...(options.documentation === undefined
+      ? {}
+      : { resource_documentation: options.documentation }),
+  };
+}
+
+/**
+ * The 401 an unauthenticated MCP request must receive.
+ *
+ * ⛔ THE `resource_metadata` PARAMETER IS THE WHOLE POINT. A bare `WWW-Authenticate:
+ *   Bearer` tells a client it needs a token but not where to get one, so discovery dead-ends
+ *   and the client falls back to hardcoded endpoints — or fails.
+ */
+export function unauthorizedResponse(options: McpMetadataOptions): Response {
+  const metadataUrl = new URL(wellKnownPath(options.resource), options.resource).href;
+
+  return new Response(JSON.stringify({ error: 'unauthorized' }), {
+    status: 401,
+    headers: {
+      'content-type': 'application/json',
+      'www-authenticate': `Bearer resource_metadata="${metadataUrl}"`,
+    },
+  });
+}
+
+/**
+ * Serve the metadata document when the request is for it, otherwise `undefined`.
+ *
+ * ```ts
+ * const discovery = serveMcpMetadata(request, { resource, authorizationServer });
+ * if (discovery !== undefined) return discovery;
+ * ```
+ *
+ * ⚠️ CORS IS OPEN HERE ON PURPOSE. Discovery metadata is public by definition — a client
+ *   must read it BEFORE it has a token, often from a browser origin the server has never
+ *   seen. Locking it down breaks the flow it exists to start.
+ */
+export function serveMcpMetadata(
+  request: Request,
+  options: McpMetadataOptions,
+): Response | undefined {
+  const url = new URL(request.url);
+  if (url.pathname !== wellKnownPath(options.resource)) return undefined;
+
+  return new Response(JSON.stringify(protectedResourceMetadata(options), null, 2), {
+    headers: {
+      'content-type': 'application/json',
+      'access-control-allow-origin': '*',
+      'cache-control': 'public, max-age=3600',
+    },
+  });
+}

package/src/version.ts

@@ -1,2 +1,2 @@
 // ⛔ GENERATED by scripts/sync-versions.ts — do not edit. Source: package.json.
-export const VERSION: string = '0.2.2';
+export const VERSION: string = '0.3.0';