@cloudflare/workers-oauth-provider 0.10.4 → 1.1.0

package/docs/resource-servers.md

@@ -0,0 +1,153 @@
+# Resource servers
+
+An `OAuthAuthorizationServer` issues tokens; a resource server accepts them. Every resource, whether it runs in the authorization server's Worker or in its own, is hosted the same way:
+
+```ts
+new OAuthResourceServer<Env, Props>({
+  resourceMetadata: { resource, authorization_servers: [issuer], scopes_supported: ['calendar:read'] },
+  validateToken: (env, request) => (resource, token) =>
+    Promise<{ props; audience; expiresAt?; scope?; userId?; clientId? } | null>,
+  handler: { fetch(request, env, ctx) {} }, // ctx.props: Props, ctx.auth: OAuthResourceAuth
+});
+```
+
+The host publishes RFC 9728 metadata at `/.well-known/oauth-protected-resource<path>`, answers unauthenticated requests with a Bearer challenge that names it and the `scopes_supported` to ask for, calls your validator with its own canonical resource and the presented token, refuses a result whose `audience` is not that resource, and answers `503` when the validator throws. Only `validateToken` changes between the topologies below.
+
+## What the handler sees
+
+`ctx.props` is the application data the validator returned. `ctx.auth` is what was verified about the token: `{ token, audience, expiresAt?, scope, userId?, clientId? }`. `OAuthAuthorizationServer.validateToken()` fills all of it; a validator of your own reports what it knows and `scope` defaults to `[]`.
+
+Scope policy is the handler's. When a valid token lacks what an operation needs, answer with `insufficientScope`, which builds the MCP scope challenge — `403`, `error="insufficient_scope"`, every scope the operation requires, and the same `resource_metadata` URL the `401` advertised — so the client can step up in one round trip:
+
+```ts
+handler: {
+  fetch(request, env, ctx) {
+    if (request.method === 'DELETE' && !ctx.auth.scope.includes('calendar:write')) {
+      return insufficientScope(ctx.auth, ['calendar:write']);
+    }
+    // …
+  },
+},
+```
+
+A `WorkerEntrypoint` handler reads the same fields from `this.ctx`; declare it as `OAuthResourceContext<Props>` to type them. `OAuthProvider` sets `ctx.auth` for its `apiHandler` too, from its own token record, so a handler moves between the two hosts unchanged.
+
+## Same Worker
+
+```ts
+const authorizationServer = new OAuthAuthorizationServer<Env>({
+  issuer: 'https://auth.example.com',
+  resources: ['https://calendar.example.com/mcp', 'https://drive.example.com/mcp'],
+  authorizeEndpoint: '/authorize',
+  tokenEndpoint: '/oauth/token',
+});
+
+const local = (env: Env) => (resource: string, token: string) =>
+  authorizationServer.validateToken(resource, token, env);
+
+const calendar = new OAuthResourceServer<Env, AuthProps>({
+  resourceMetadata: {
+    resource: 'https://calendar.example.com/mcp',
+    authorization_servers: ['https://auth.example.com'],
+  },
+  validateToken: local,
+  handler: calendarHandler,
+});
+```
+
+You own routing. This example (`npm install hono`) puts one Worker on three custom domains and uses Hono's hostname-aware path so no `switch` is needed; the original `Request` is forwarded as `c.req.raw` so URL validation sees the real origin:
+
+```ts
+const app = new Hono<{ Bindings: Env }>({
+  getPath: (request) => `/${new URL(request.url).hostname}${new URL(request.url).pathname}`,
+});
+
+app.get('/auth.example.com/authorize', async (c) => {
+  const oauth = authorizationServer.getOAuthApi(c.env);
+  const request = await oauth.parseAuthRequest(c.req.raw); // render AuthorizationError safely in production
+  const { redirectTo } = await oauth.completeAuthorization({
+    request,
+    userId: 'user-123',
+    metadata: {},
+    scope: request.scope,
+    props: { userId: 'user-123', scopes: request.scope },
+  });
+  return c.redirect(redirectTo);
+});
+app.all('/auth.example.com/*', (c) => authorizationServer.fetch(c.req.raw, c.env, c.executionCtx));
+app.all('/calendar.example.com/*', (c) => calendar.fetch(c.req.raw, c.env, c.executionCtx));
+app.all('/drive.example.com/*', (c) => drive.fetch(c.req.raw, c.env, c.executionCtx));
+
+export default app;
+```
+
+```jsonc
+{
+  "workers_dev": false,
+  "routes": [
+    { "pattern": "auth.example.com", "custom_domain": true },
+    { "pattern": "calendar.example.com", "custom_domain": true },
+    { "pattern": "drive.example.com", "custom_domain": true },
+  ],
+}
+```
+
+Authorization server metadata advertises every declared resource in `protected_resources`; each resource publishes its own protected resource metadata pointing back at the issuer. `resources` is fixed at construction and `defaultResource` and `legacyGrantResource` are checked against it then; a resource server that asks about an undeclared resource gets a rejection, which the host turns into `503`.
+
+## Separate Workers
+
+Only the authorization server can validate a token: the props are encrypted with a key wrapped by the token itself, and the token record lives in its KV. A resource Worker therefore asks it, over a Service Binding.
+
+Authorization Worker, exposing the method from a `WorkerEntrypoint`:
+
+```ts
+import { WorkerEntrypoint } from 'cloudflare:workers';
+
+export default class AuthServer extends WorkerEntrypoint<Env> {
+  fetch(request: Request) {
+    // Your /authorize route goes here too; everything else is the authorization server's.
+    return authorizationServer.fetch(request, this.env, this.ctx);
+  }
+  validateToken(resource: string, token: string) {
+    return authorizationServer.validateToken(resource, token, this.env);
+  }
+}
+```
+
+Resource Worker, with a binding to it:
+
+```jsonc
+{ "services": [{ "binding": "AUTH_SERVER", "service": "auth" }] }
+```
+
+```ts
+import { OAuthResourceServer, type AuthorizationServerBinding } from '@cloudflare/workers-oauth-provider';
+
+interface Env {
+  AUTH_SERVER: AuthorizationServerBinding<AuthProps>; // or Service<AuthServer> from wrangler types
+}
+
+export default new OAuthResourceServer<Env, AuthProps>({
+  resourceMetadata: {
+    resource: 'https://calendar.example.com/mcp',
+    authorization_servers: ['https://auth.example.com'],
+  },
+  validateToken: (env) => env.AUTH_SERVER.validateToken,
+  handler,
+});
+```
+
+The host calls the method it is handed with its resource and the token, so neither is repeated. The binding is not a URL: the validator is never exposed to the public internet, and the resource Worker cannot ask about another resource's tokens by accident because the host always passes its own. One RPC per request, on Cloudflare's network. `ctx.props` is the same `AuthProps` the authorization flow stored, decrypted by the authorization server; `ctx.auth` carries the token's scopes, subject and client back with it; and revocation is immediate.
+
+## Another issuer, at your own risk
+
+`validateToken` is just a function. A resource that accepts tokens from an authorization server that is not this package validates them itself — an RFC 7662 introspection call, a JWT library against that issuer's JWKS — and returns `{ props, audience, expiresAt }`:
+
+```ts
+validateToken: (env) => async (resource, token) => {
+  const { payload } = await jwtVerify(token, keys, { issuer: OTHER_ISSUER, audience: resource, typ: 'at+jwt' });
+  return { props: { userId: payload.sub! }, audience: resource, expiresAt: payload.exp };
+},
+```
+
+The host still enforces the audience and expiry it is given, and it fails closed on a malformed `scope`, `userId` or `clientId`. Everything else about that issuer's tokens is between you and it. MCP's security guidance is blunt on the point that a resource server must accept only tokens issued for it; keep `audience` honest.

package/docs/upstream-sign-in.md

@@ -0,0 +1,93 @@
+# Signing in through another provider
+
+Many MCP servers don't have their own users: they sign people in with GitHub, Sentry, Google, or another OAuth provider, and call that provider's API with the user's token. The MCP server is still the authorization server for MCP clients, but its `/authorize` page hands the user to the third party and finishes when the third party redirects back.
+
+Every MCP client then reaches the third party through your one OAuth app. MCP's security best practices call this the [confused deputy problem](https://modelcontextprotocol.io/docs/2026-07-28/tutorials/security/security_best_practices#confused-deputy-problem) and require consent per client before the redirect, a consent page that can't be framed or forged, and a `state` bound to the user's browser. The helpers below implement those requirements; the consent page itself is yours.
+
+## The flow
+
+```ts
+const oauth = authorizationServer.getOAuthApi(env); // or env.OAUTH_PROVIDER with OAuthProvider
+
+// GET /authorize: parse, then ask for consent.
+const request = await oauth.parseAuthRequest(req);
+const client = await oauth.lookupClient(request.clientId);
+const consent = await oauth.beginConsent(request);
+return new Response(renderConsentPage({ client, request, handle: consent.handle }), {
+  headers: consent.headers, // binding cookie, no framing, no caching
+});
+
+// POST /authorize: the user approved. Now, and only now, start the third-party redirect.
+const form = await req.formData();
+const approved = await oauth.approveConsent(req, String(form.get('handle')), {
+  scope: form.getAll('scope').map(String), // optional: the scopes the user ticked, from any in scopesSupported
+});
+const verifier = crypto.randomUUID() + crypto.randomUUID();
+const { state, headers } = await oauth.beginUpstream(approved.request, {
+  data: { verifier }, // returned at the callback; never sent to the third party
+  headers: approved.headers,
+});
+headers.set('Location', githubAuthorizeUrl({ state, codeChallenge: await s256(verifier) }));
+return new Response(null, { status: 302, headers });
+
+// GET /callback: recover the request, exchange the third party's code, finish.
+const { request: original, data, headers: clear } = await oauth.finishUpstream<{ verifier: string }>(req);
+const upstream = await exchangeGithubCode(new URL(req.url).searchParams.get('code')!, data.verifier);
+const { redirectTo } = await oauth.completeAuthorization({
+  request: original,
+  userId: upstream.user.id,
+  metadata: {},
+  scope: original.scope,
+  props: { githubToken: upstream.accessToken }, // encrypted; handlers get it in ctx.props
+});
+clear.set('Location', redirectTo);
+return new Response(null, { status: 302, headers: clear });
+```
+
+Build the consent page itself, and the Deny path (`denyConsent()`), as in [consent-page.md](consent-page.md), which also covers which errors to redirect and which to render. Validation failures throw `AuthorizationError` without a `redirectUri`: render them locally. A `TypeError` (bad options) or a storage failure is a bug or an outage, not the user's doing.
+
+`beginUpstream()` doesn't check consent itself: call it only after `approveConsent()`, or when `isConsentRemembered()` says yes. (A server whose clients are all pre-registered, with no dynamic registration, isn't required to ask per client and can call it directly.)
+
+If the third party sends the user back with an error (they declined there, or it failed), `finishUpstream()` still returns the original request, so answer the client with it:
+
+```ts
+const { request: original, headers } = await oauth.finishUpstream(req);
+const error = new URL(req.url).searchParams.get('error');
+if (error) {
+  const redirect = new URL(original.redirectUri);
+  redirect.searchParams.set('error', 'access_denied');
+  redirect.searchParams.set('state', original.state);
+  if (original.issuer) redirect.searchParams.set('iss', original.issuer);
+  headers.set('Location', redirect.href);
+  return new Response(null, { status: 302, headers });
+}
+```
+
+## What the helpers guarantee
+
+- **The consent page can't be forged or framed.** `beginConsent()` binds the handle to the browser with a `__Host-` cookie (`Secure`, `HttpOnly`, `SameSite=Lax`, ten minutes) and returns `Content-Security-Policy: frame-ancestors 'none'` and `X-Frame-Options: DENY`. A post from another site has the handle but not the cookie, and is refused.
+- **`state` exists only after consent.** `beginUpstream()` creates it, stores the approved request server-side, and binds it to the browser. The callback is refused without the matching cookie, so a stolen third-party code can't be replayed in another browser.
+- **Single use, ten minutes, several at once.** Each handle and `state` works once, and each has its own binding cookie, so two tabs can authorize at the same time. KV keys hold only the SHA-256 of the handle, and the record, including your `data` (a PKCE verifier, say), is encrypted with a key only the handle derives: reading KV alone reveals nothing. KV can't make `get`-then-`delete` atomic, so two simultaneous requests from the _same_ browser with the same handle could both pass; the cookie binding rules out anyone else.
+- **Nothing trusted comes from the form.** The authorization request is recovered from storage, not from hidden fields, so the page can't be made to approve a different client or redirect URI. `scope` is the page's to choose, fewer or more than the client requested, but only from `scopesSupported`.
+
+## Remembering consent
+
+Pass `remember` to `approveConsent()` and check `isConsentRemembered()` before showing the page; when it's remembered, go straight to `beginUpstream()`. See [consent-page.md](consent-page.md#remembering-consent), which also covers the cookie names.
+
+## When the third party revokes access
+
+Store the third party's refresh token in `props` and refresh it in `tokenExchangeCallback`. When it answers `invalid_grant`, the user has revoked your app or the token is gone for good. Throw `invalid_grant` too: the library revokes this grant, with its tokens, so the MCP client re-authorizes instead of retrying a grant that can never work. For a transient failure (the provider is down, rate limited), throw `temporarily_unavailable` instead, which leaves the grant for the retry.
+
+```ts
+tokenExchangeCallback: async ({ grantType, props }) => {
+  if (grantType !== 'refresh_token') return;
+  const upstream = await refreshGithubToken(props.githubRefreshToken);
+  if (upstream.error === 'bad_refresh_token') {
+    throw new OAuthError('invalid_grant', { description: 'GitHub access was revoked' }); // revokes this grant
+  }
+  if (!upstream.ok) {
+    throw new OAuthError('temporarily_unavailable', { description: 'GitHub is unavailable', statusCode: 503 });
+  }
+  return { newProps: { ...props, githubToken: upstream.accessToken, githubRefreshToken: upstream.refreshToken } };
+},
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudflare/workers-oauth-provider",
-  "version": "0.10.4",
+  "version": "1.1.0",
   "description": "OAuth provider for Cloudflare Workers",
   "main": "dist/oauth-provider.js",
   "types": "dist/oauth-provider.d.ts",
@@ -8,7 +8,9 @@
   "license": "MIT",
   "sideEffects": false,
   "files": [
-    "dist"
+    "dist",
+    "docs",
+    "skills"
   ],
   "type": "module",
   "publishConfig": {

package/skills/migrate-to-1.0/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: workers-oauth-provider-migrate-1.0
+description: Migrate a Cloudflare Worker from @cloudflare/workers-oauth-provider 0.x to 1.0. Use when upgrading that dependency, when OAuthProvider construction throws about resourceMetadata.resource or resourceMatchOriginOnly, or when asked to adopt the 1.0 role-based API (OAuthAuthorizationServer / OAuthResourceServer).
+---
+
+# Migrate @cloudflare/workers-oauth-provider 0.x → 1.0
+
+The single source of truth for every change is the migration guide shipped with the package:
+`node_modules/@cloudflare/workers-oauth-provider/docs/migration-1.0.md`
+(also at https://github.com/cloudflare/workers-oauth-provider/blob/main/docs/migration-1.0.md).
+Read it fully before editing. This skill is the procedure around it; do not work from memory of 0.x or from this file alone.
+
+## Procedure
+
+1. **Detect the shape.** Find `new OAuthProvider(` and read its options. The common shape is one Worker acting as authorization server and resource server; that shape stays on `OAuthProvider` in 1.0. Do not introduce `OAuthAuthorizationServer`/`OAuthResourceServer` unless the user asks for a multi-Worker or multi-resource topology.
+2. **Choose the canonical resource — ask the user.** `resourceMetadata: { resource }` is required in 1.0. The value is the URL MCP clients connect to (often an existing `apiRoute` on the Worker's public origin, e.g. `https://mcp.example.com/mcp`). Infer a candidate from `wrangler.jsonc` routes/custom domains plus `apiRoute`, present it, and get confirmation — it becomes the token audience, so it must be right.
+3. **Apply the guide's changes** that match the code: add `resourceMetadata.resource`; delete `resourceMatchOriginOnly`; make `resolveExternalToken` return the canonical `audience`; single-string `resource`/`aud` types; check `apiRoute`s are the resource path or descendants.
+4. **Bump the dependency** to `^1.0.0` and install.
+5. **Verify** (below), then walk the user through the guide's "Existing stored data" section so they know what their live clients will experience (nothing, in the common case).
+
+## Stop and ask the user
+
+- The canonical `resource` value (step 2). Never guess silently.
+- On a multi-resource `OAuthAuthorizationServer`: which resource is `legacyGrantResource` (the migration destination for pre-1.0 grants). Omitting it makes old grants reauthorize.
+- Any DCR client base registered with narrow `grant_types`: 1.0 enforces them; confirm the registered types cover what clients actually send before deploying.
+- Adopting new 1.0 surface (role classes, `ctx.auth`, `insufficientScope`, `onError.internal`) is optional — offer, don't do unasked.
+
+## Verify
+
+1. `tsc`/typecheck and the project's tests pass.
+2. `wrangler dev`, then:
+   - `curl -i http://localhost:8787<api route>` → 401 whose `WWW-Authenticate` names `resource_metadata="…/.well-known/oauth-protected-resource<resource path>"`. This works locally whatever the configured resource's origin.
+   - The metadata document itself is origin-strict (RFC 9728 §3): its well-known URL is `<resource origin>/.well-known/oauth-protected-resource<resource path>`. When the dev config's resource is on the loopback origin (e.g. `http://localhost:8787/mcp`), `curl http://localhost:8787/.well-known/oauth-protected-resource/mcp` → 200 with the exact `resource`. A production resource origin serves its document only there — after deploy: `curl https://<host>/.well-known/oauth-protected-resource<resource path>`.
+   - Construction errors surface on the first request and name the violated rule; fix per the guide.
+3. If the deployment has live users, re-read "Existing stored data — nothing to do" in the guide and confirm no step you took contradicts it (no KV edits, no `legacyGrantResource` changes after rollout).