@cloudflare/workers-oauth-provider 0.10.3 → 1.0.0

package/docs/advanced-configuration.md

@@ -0,0 +1,370 @@
+# Advanced configuration
+
+This guide covers features that are useful for proxying another authorization system, changing token data during exchange, or operating the provider over time. Start with the main [README](../README.md) for MCP discovery, client registration, and a minimal Worker.
+
+## Token exchange callback
+
+`tokenExchangeCallback` runs during authorization code and refresh token exchanges. It is useful when the Worker also acts as an OAuth client to an upstream service.
+
+```ts
+new OAuthProvider({
+  // Other options...
+  tokenExchangeCallback: async (options) => {
+    if (options.grantType === 'authorization_code') {
+      const upstream = await exchangeUpstream(options.props.authorizationCode);
+      return {
+        accessTokenProps: {
+          ...options.props,
+          upstreamAccessToken: upstream.access_token,
+        },
+        newProps: {
+          ...options.props,
+          upstreamRefreshToken: upstream.refresh_token,
+        },
+        accessTokenTTL: upstream.expires_in,
+      };
+    }
+
+    if (options.grantType === 'refresh_token') {
+      const upstream = await refreshUpstream(options.props.upstreamRefreshToken);
+      return {
+        accessTokenProps: {
+          ...options.props,
+          upstreamAccessToken: upstream.access_token,
+        },
+        newProps: {
+          ...options.props,
+          upstreamRefreshToken: upstream.refresh_token,
+        },
+        accessTokenTTL: upstream.expires_in,
+        // The upstream just issued a new refresh token; let this grant live as long as it does.
+        refreshTokenIdleTTL: upstream.refresh_expires_in,
+      };
+    }
+  },
+});
+```
+
+The callback receives the grant type, client ID, user ID, grant ID, grant scopes, effective requested scopes, and decrypted props. It may return:
+
+- `accessTokenProps` for the current access token.
+- `newProps` for the grant and future refreshes.
+- `accessTokenTTL` for the current access token.
+- `refreshTokenTTL` during authorization code exchange.
+- `refreshTokenIdleTTL` during refresh token exchange, to move the grant's expiry to that many seconds from now.
+- `accessTokenScope` to narrow the current token.
+
+Return nothing to keep the existing values. If `newProps` is returned without `accessTokenProps`, the current access token also uses `newProps`.
+
+Throw `OAuthError` when an upstream failure should become an OAuth token response:
+
+```ts
+throw new OAuthError('temporarily_unavailable', {
+  description: 'The upstream authorization server is rate limited',
+  statusCode: 429,
+  headers: { 'Retry-After': '60' },
+});
+```
+
+Plain errors continue to surface as 500 responses.
+
+## OAuth 2.0 Token Exchange
+
+Set `allowTokenExchangeGrant: true` to enable RFC 8693. Clients can exchange an existing access token for a token with narrower scopes or a shorter lifetime. Token exchange cannot change the subject grant's registered canonical resource audience.
+
+Application code can also call:
+
+```ts
+await env.OAUTH_PROVIDER.exchangeToken({
+  subjectToken,
+  scope: ['documents:read'],
+  aud: 'https://mcp.example.com/mcp', // Must match the subject grant's resource
+  expiresIn: 900,
+});
+```
+
+The new token cannot exceed the subject token's scope ceiling or remaining lifetime. Its subject audience and any `aud` request value must resolve to the same registered resource. Subject-token failures return `invalid_request`, as RFC 8693 §2.2.2 requires.
+
+A client must register `urn:ietf:params:oauth:grant-type:token-exchange` in its `grant_types` to use the grant at the token endpoint. A token is exchanged by the client its grant was issued to. Exchanging a token that another client obtained is rejected with `invalid_request` unless `tokenExchangeCallback` allows that specific exchange. The callback sees both parties, so the decision can be per client pair:
+
+```ts
+tokenExchangeCallback: (options) => {
+  if (options.grantType === 'urn:ietf:params:oauth:grant-type:token-exchange') {
+    // options.clientId is the exchanging client; options.subjectClientId issued the grant.
+    const trusted = options.subjectClientId === options.clientId || DELEGATES.has(options.clientId);
+    return { allowCrossClientExchange: trusted };
+  }
+},
+```
+
+## Enterprise-managed authorization
+
+**Experimental.** The [MCP Enterprise-Managed Authorization extension](https://modelcontextprotocol.io/extensions/auth/enterprise-managed-authorization) is itself young, so the `enterpriseManagedAuthorization` option and its exported types (`EmaValidationError`, trust-policy shapes) are exempt from 1.x semver: they may change in a minor release, with the change documented in the changelog. Everything else on this page is stable API.
+
+The token endpoint accepts a validated ID-JAG assertion using the JWT bearer grant and returns an opaque, resource-bound access token.
+
+```ts
+new OAuthProvider({
+  // Other options...
+  resourceMetadata: { resource: 'https://mcp.example.com/mcp' },
+  enterpriseManagedAuthorization: {
+    trustedIssuers: async ({ iss }) =>
+      iss === 'https://idp.example.com'
+        ? {
+            issuer: iss,
+            jwksUri: 'https://idp.example.com/.well-known/jwks.json',
+            algorithms: ['RS256'],
+          }
+        : null,
+    mapClaims: async ({ claims, requestedScope }) => ({
+      userId: `enterprise-${encodeURIComponent(claims.sub)}`,
+      scope: requestedScope,
+      metadata: { issuer: claims.iss, subject: claims.sub },
+      props: { subject: claims.sub, email: claims.email },
+    }),
+  },
+});
+```
+
+The provider validates ID-JAG type, signature, issuer, audience, client binding, resource, timestamps, maximum lifetime, and replay identifier. The audience must be the authorization server issuer as a string or a single-element array. Assertions containing `authorization_details` or `cnf` fail closed until typed authorization-detail and DPoP processing are implemented. Refresh tokens are not issued for this grant.
+
+The grant requires client authentication by default. Set `allowPublicClients: true` only when public clients, including CIMD clients, must use it and the ID-JAG trust model is appropriate for the deployment.
+
+The default replay marker uses KV and is best effort across Cloudflare locations because KV is eventually consistent. Signature checks, short assertion lifetime, audience, resource, and client binding limit the replay window. The package does not currently expose a custom replay store, so do not describe ID-JAG redemption as globally single-use.
+
+## Client registration policy
+
+`clientRegistrationCallback` runs before a DCR client is stored. Return nothing to allow registration, or return an object to reject it:
+
+```ts
+clientRegistrationCallback: async ({ clientMetadata, request }) => {
+  if (!(await registrationIsAllowed(clientMetadata, request))) {
+    return {
+      code: 'access_denied',
+      description: 'Client registration is not permitted',
+      status: 403,
+    };
+  }
+};
+```
+
+The callback receives raw client metadata and a clone of the request whose body can still be read. If `software_statement` is present, the application is responsible for verifying it and applying its claims.
+
+`disallowPublicClientRegistration` affects DCR only. It does not prevent administrative code from creating a public client through `OAuthHelpers.createClient()`.
+
+## CIMD fetch errors
+
+A client ID Metadata Document can fail because of a timeout, network error, upstream response, or invalid document. Those failures are different from a client that does not exist.
+
+At the token endpoint, the provider keeps the wire response generic as `invalid_client`. It sends the diagnostic reason to `onError.internal` with category `client-id-metadata-document`, stable reason `metadata_resolution_failed`, the metadata URL, and the underlying message.
+
+`OAuthHelpers.lookupClient()`, `parseAuthRequest()`, `completeAuthorization()`, and `exchangeToken()` throw the exported `CimdFetchError` when they cannot resolve a CIMD client. `lookupClient()` returns `null` only when the client does not exist:
+
+```ts
+import { CimdFetchError } from '@cloudflare/workers-oauth-provider';
+
+try {
+  const client = await env.OAUTH_PROVIDER.lookupClient(clientId);
+} catch (error) {
+  if (error instanceof CimdFetchError) {
+    console.error(error.reason, error.metadataUrl, error.detail);
+  }
+  throw error;
+}
+```
+
+Do not log credentials or request bodies when recording these failures.
+
+## Custom error responses
+
+`onError` runs whenever the provider is about to return an OAuth error. Use it for logging or monitoring:
+
+```ts
+new OAuthProvider({
+  // Other options...
+  onError({ code, description, status, headers, internal }) {
+    console.warn({ code, description, status, headers, internal });
+  },
+});
+```
+
+Return a `Response` to replace the default response. Return nothing to use the provider's RFC-formatted response.
+
+### The internal reason
+
+Every OAuth error response the library builds — everything `onError` observes — carries `internal: { category, reason, detail? }`: the exact check that failed, which the wire response deliberately does not reveal (RFC 6749 §5.2). Bare non-OAuth responses (the credential-less `401` challenge, `404`/`405` on metadata URLs) carry no OAuth error and do not run `onError`. It exists only on the path to `onError` and is never sent to the client, so `error_description` can stay generic while logs and alerting key on stable slugs instead of matching text:
+
+```ts
+onError({ code, internal }) {
+  metrics.increment(`oauth.${internal.category}.${internal.reason}`);
+},
+```
+
+`category` names the subsystem (kebab-case), `reason` the failed check (snake_case); both are stable across versions — treat additions like new enum members. `detail`, when present, carries structured context such as the caught error, a CIMD fetch diagnosis, or the offending parameter name; it never carries a secret.
+
+| Category                           | Examples of `reason`                                                                                |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `token-endpoint-request`           | `method_not_allowed`, `repeated_parameter`, `grant_type_not_supported`, `grant_type_not_registered` |
+| `client-authentication`            | `client_not_found`, `client_secret_mismatch`, `multiple_authentication_methods`                     |
+| `client-id-metadata-document`      | `metadata_resolution_failed` and the other typed CIMD reasons                                       |
+| `authorization-code-grant`         | `code_replayed`, `code_verifier_mismatch`, `redirect_uri_mismatch`, `grant_not_found`               |
+| `refresh-token-grant`              | `refresh_token_mismatch`, `refresh_token_expired`, `client_mismatch`, `grant_not_found`             |
+| `token-exchange-grant`             | `subject_token_invalid`, `subject_token_near_expiry`, `requested_ttl_too_short`                     |
+| `enterprise-managed-authorization` | the typed EMA validator reasons (`signature_failed`, `replayed`, `aud_mismatch`, …)                 |
+| `resource-indicator`               | `resource_not_configured`, `resource_grant_mismatch`, `legacy_grant_unbound`                        |
+| `token-issuance`                   | `kv_rate_limited`, `requested_ttl_too_short`                                                        |
+| `token-revocation`                 | `token_missing`                                                                                     |
+| `client-registration`              | `json_malformed`, `metadata_invalid`, `callback_denied`, `payload_too_large`                        |
+| `protected-resource`               | `token_not_found`, `token_expired`, `audience_mismatch`, `resolver_rejected`                        |
+| `token-exchange-callback`          | `callback_error` — an `OAuthError` thrown by a deployer callback without its own `internal`         |
+
+`OAuthError(code, options)` supports token-endpoint errors from `tokenExchangeCallback`. `ExternalTokenError(code, options)` supports protected-resource errors from `resolveExternalToken`, including `requiredScopes` for an `insufficient_scope` challenge.
+
+Both classes accept a public `description`, `statusCode`, and response `headers`. Only the exported class intended for that callback boundary is converted. Other errors remain unexpected failures. An `OAuthError` may also set `options.internal` to give `onError` its own category and reason; without one it arrives as `{ category: 'token-exchange-callback', reason: 'callback_error', detail: error }`.
+
+## Token and client lifetimes
+
+| Option                  | Default           | Notes                                                                               |
+| ----------------------- | ----------------- | ----------------------------------------------------------------------------------- |
+| `accessTokenTTL`        | 3,600 seconds     | Must be at least 60 seconds because of KV limits                                    |
+| `refreshTokenTTL`       | 2,592,000 seconds | 30 days; set to `0` to disable refresh tokens; explicit `undefined` means no expiry |
+| `refreshTokenIdleTTL`   | unset             | Sliding expiry: each successful refresh moves the grant's expiry this far out       |
+| `clientRegistrationTTL` | 7,776,000 seconds | 90 days for DCR clients, renewed while in use; explicit `undefined` means no expiry |
+
+A refresh rotates the token. The newly issued token and the immediately previous token can both recover a refresh whose response was lost. Once the new token is used, the previous token is invalidated and another token is issued.
+
+Per-token `accessTokenTTL` and `refreshTokenTTL` overrides are available through `tokenExchangeCallback`.
+
+### Sliding expiry
+
+By default a grant's lifetime is fixed at the code exchange: it expires `refreshTokenTTL` seconds later no matter how often it is refreshed, which is the right policy when users must re-authenticate on a schedule. A Worker that proxies an upstream OAuth service usually wants the opposite: the grant should live as long as the upstream credentials it holds, and no longer.
+
+`refreshTokenIdleTTL` makes the lifetime slide. Every successful refresh moves the grant's expiry, and the KV expiration of its record, to that many seconds after the refresh. `refreshTokenTTL` still sets a new grant's lifetime, so "30 days to start, then at least weekly" is `refreshTokenTTL: 30 * 86400` with `refreshTokenIdleTTL: 7 * 86400`. A grant that never expired keeps that status until its first refresh, after which it too idles out.
+
+Returning `refreshTokenIdleTTL` from `tokenExchangeCallback` sets the lifetime for that one refresh and overrides the option, as in the example above. It sets rather than extends, so returning the upstream's remaining lifetime makes the grant track it exactly; return nothing when the upstream did not rotate and the option, or the fixed lifetime, applies.
+
+The slide is committed by the same grant write that rotates the refresh token. A callback that throws fails the refresh before that write, so a failed upstream refresh never renews the downstream grant. A grant that has already expired, including one that expires while a slow callback runs, is rejected with `invalid_grant` and is not revived. If the access-token write after the grant write fails, the grant is already rotated and extended, and the client's previous refresh token is still valid to retry with; that retry slides the expiry again.
+
+There is no built-in absolute maximum. A grant with `refreshTokenTTL: undefined` already lives indefinitely, and the callback is the place for lifetime policy: record the authorization time in `props` when the grant is created, and return a shrinking `refreshTokenIdleTTL`, or throw, once the grant is older than you allow.
+
+## KV cleanup
+
+KV TTLs remove expiring records automatically. `purgeExpiredData()` provides a defense-in-depth sweep for orphaned or expired grants and tokens:
+
+```ts
+const provider = new OAuthProvider({
+  // Options...
+});
+
+export default {
+  fetch(request, env, ctx) {
+    return provider.fetch(request, env, ctx);
+  },
+  async scheduled(_event, env) {
+    const result = await provider.purgeExpiredData(env, { batchSize: 100 });
+    console.log(result);
+  },
+};
+```
+
+The default batch size is 50. `result.done` reports whether both key spaces were scanned completely during that invocation.
+
+Deleting a client through `OAuthHelpers.deleteClient()` also revokes its grants and associated tokens across users.
+
+## Multiple protected handlers
+
+Use `apiHandlers` when different route prefixes need different handlers:
+
+```ts
+new OAuthProvider({
+  apiHandlers: {
+    '/api/users/': UsersApiHandler,
+    '/api/documents/': DocumentsApiHandler,
+    'https://api.example.com/': ExternalApiHandler,
+  },
+  // Other options...
+});
+```
+
+Use either `apiHandlers` or `apiRoute` plus `apiHandler`, not both. Routes can be paths or full URLs.
+
+## Helper access outside fetch
+
+`getOAuthApi(options, env)` returns `OAuthHelpers` for RPC methods and other Worker entrypoints that do not receive the injected `env.OAUTH_PROVIDER` value.
+
+## External token resolution
+
+`resolveExternalToken` accepts a bearer credential that was not issued or stored by this provider. It runs only after the internal token lookup fails. The credential can be an external OAuth access token, opaque API key, or personal access token (PAT).
+
+### MCP compatibility warning
+
+This is an advanced compatibility feature, not the normal MCP authorization flow. The MCP 2026-07-28 specification says:
+
+- MCP clients must not send tokens other than ones issued by the MCP server's authorization server.
+- MCP servers must accept only tokens intended for their own resource.
+- If an MCP server calls an upstream API, it must use a separate upstream token and must not forward the token received from the MCP client.
+
+Accepting an API key minted by an upstream API directly at the MCP endpoint therefore falls outside the MCP authorization profile. Setting `audience` in the callback applies the provider's local resource policy, but it does not change who issued the credential or make an upstream API key MCP-compliant.
+
+Some deployments intentionally use this compatibility pattern so users can present API keys minted by an existing upstream API. `resolveExternalToken` supports that choice, including validation through a trusted upstream endpoint and passing derived identity or permissions to the protected handler. If the handler forwards the same key to access upstream application data, that is token passthrough under the MCP security guidance and must not be described as MCP-conformant.
+
+The preferred MCP design is to issue a local, audience-bound access token for the MCP server and keep any separate upstream credential in encrypted `props`. When compatibility requires direct upstream keys, restrict validation and use to fixed upstream hosts, request the narrowest permissions possible, never log the key, do not include it in errors or metadata, and make the non-conformant trust model explicit to operators.
+
+### Validating an upstream API key
+
+```ts
+import { ExternalTokenError, OAuthProvider } from '@cloudflare/workers-oauth-provider';
+
+const MCP_RESOURCE = 'https://mcp.example.com/mcp';
+
+new OAuthProvider({
+  // Other options...
+  resourceMetadata: { resource: MCP_RESOURCE },
+
+  resolveExternalToken: async ({ token, request, env }) => {
+    const result = await validateUpstreamApiKey(token, request, env);
+
+    if (result.kind === 'invalid') return null;
+    if (result.kind === 'insufficient_scope') {
+      throw new ExternalTokenError('insufficient_scope', {
+        description: 'The API key needs account:read permission',
+        statusCode: 403,
+        requiredScopes: ['account:read'],
+      });
+    }
+    if (result.kind === 'rate_limited') {
+      throw new ExternalTokenError('temporarily_unavailable', {
+        description: 'API key validation is temporarily rate limited',
+        statusCode: 429,
+        headers: { 'Retry-After': result.retryAfter },
+      });
+    }
+
+    return {
+      props: {
+        upstreamSubject: result.subject,
+        permissions: result.permissions,
+      },
+
+      // An opaque key has no MCP audience claim. This is an explicit local
+      // policy binding applied only after successful validation.
+      audience: MCP_RESOURCE,
+    };
+  },
+});
+```
+
+The callback can:
+
+- Return `{ props, audience }` to authenticate. The audience is required, must be a single string, and must identify the configured canonical `resourceMetadata.resource`; scheme and host comparisons are ASCII case-insensitive and an empty path equals `/`, while port, path, query, and trailing slash are strict. An array is rejected.
+- Return `null` for a generic `401 invalid_token` response.
+- Throw the exported `ExternalTokenError` for an intentional structured response.
+
+`audience` means the local protected resource where the credential is accepted. It does not mean the issuer, user, upstream API, or permissions. For an opaque key, the callback supplies this as a local policy decision after validation. Do not use an upstream API URL as the audience for requests to the Worker.
+
+Unexpected errors, plain objects, `OAuthError`, and app-local lookalike classes are re-thrown so validator bugs remain visible as 500 responses. Existing callback behavior is unchanged unless the callback deliberately throws this package's `ExternalTokenError`.
+
+References:
+
+- [MCP access token handling](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization#token-handling)
+- [MCP access token privilege restriction](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/security-considerations#access-token-privilege-restriction)

package/docs/migration-1.0.md

@@ -0,0 +1,97 @@
+# Migrating from 0.x to 1.0
+
+1.0 binds every grant and access token to one canonical resource (RFC 8707 / RFC 9728) and adds role classes for multi-Worker deployments. Stored 0.x data keeps working — there is no KV migration. For most deployments the code diff is one field.
+
+## Am I affected?
+
+- **Single Worker on `OAuthProvider`** (the common shape): add `resourceMetadata: { resource }` if you don't have it. Usually that is the whole migration.
+- **You set `resourceMatchOriginOnly`**: remove it; construction now rejects it.
+- **You use `resolveExternalToken`**: return `audience` (now required).
+- **You registered clients over DCR with an explicit narrow `grant_types`**: registered grant types are now enforced at the token endpoint.
+- **Your clients send a different `redirect_uri` at code exchange than at authorization**: OAuth 2.1 §4.1.3 is now enforced.
+- **Nothing else**: existing grants, refresh tokens, access tokens and authorization codes keep working under the legacy rules below.
+
+## The canonical resource is required
+
+```diff
+ export default new OAuthProvider<Env>({
+   apiRoute: ['/mcp'],
+   apiHandler,
+   defaultHandler,
+   authorizeEndpoint: '/authorize',
+   tokenEndpoint: '/oauth/token',
++  resourceMetadata: { resource: 'https://mcp.example.com/mcp' },
+ });
+```
+
+`resource` is the URL your MCP clients connect to: an absolute HTTPS URI with lowercase scheme and host, no fragment, userinfo, default port, or dot segments. A bare origin (`https://mcp.example.com`) is allowed and covers every path. `http` is accepted only on loopback hosts, so `wrangler dev` works at `http://localhost:8787`.
+
+Construction validates the whole configuration against it and throws with a named rule when something is off:
+
+- Every `apiRoute` / `apiHandlers` key must be the resource's path or a path-boundary descendant (`/mcp` covers `/mcp` and `/mcp/tools`, not `/mcp-other`); absolute routes must be on the resource's origin.
+- The resource must not sit inside `/.well-known/oauth-protected-resource`.
+
+In 0.x the metadata document was derived per request when `resourceMetadata` was omitted; in 1.0 the configured resource is the identity every token is bound to, so it cannot be implicit.
+
+## Removed: `resourceMatchOriginOnly`
+
+A configuration that still sets it fails at construction. Audiences are now compared exactly against the canonical resource, with two tolerances: ASCII case in scheme and host is folded, and an empty path equals `/` (RFC 3986 §6.2.3). Port, path, query, and trailing slash stay strict.
+
+## `resolveExternalToken` names its audience
+
+`ResolveExternalTokenResult.audience` is required and a single string, and must be the configured canonical resource — a token accepted for another audience is a 401:
+
+```diff
+ resolveExternalToken: async ({ token }) => {
+   const session = await upstream.introspect(token);
+   if (!session) return null;
+-  return { props: { userId: session.sub } };
++  return { props: { userId: session.sub }, audience: 'https://mcp.example.com/mcp' };
+ },
+```
+
+## Registered grant types are enforced
+
+A token request for a grant type the client did not register fails with `unauthorized_client`. `refresh_token` is implied by `authorization_code`; token exchange must be registered explicitly (and enabled with `allowTokenExchangeGrant`). This is a data-side change: clients registered under 0.x with a deliberately narrow `grant_types` array may now be refused where 0.x ignored the field.
+
+## Token exchange
+
+- A subject token is exchanged by the client its grant was issued to. The cross-client case requires `tokenExchangeCallback` to return `allowCrossClientExchange: true`; the callback receives `subjectClientId` to decide.
+- Subject-token failures return `invalid_request`.
+- The exchange cannot retarget the resource: the subject token's audience and any explicit `resource` parameter must resolve to the same registered value.
+
+## `redirect_uri` is bound to the authorization request
+
+OAuth 2.1 §4.1.3: the `redirect_uri` presented at code exchange must equal the one used in the authorization request (0.x accepted any registered URI). Without PKCE, `redirect_uri` is required at exchange.
+
+## One grant per user, client, and resource
+
+Completing a new authorization replaces the user and client's earlier grant _for the same resource_ only. In 0.x replacement was per user and client, so a central server issuing tokens for several resources no longer drops one resource's grant when the user authorizes another.
+
+## Existing stored data — nothing to do
+
+- An access token stored without an audience keeps working until it expires. It is treated as bound to the migration resource: the sole configured resource, or `legacyGrantResource` on a multi-resource server.
+- Refresh binds the grant to that resource and returns a bound replacement token.
+- A stored 0.x audience array resolves to the registered resource it contains.
+- A grant bound only to unregistered values fails refresh with `invalid_grant`; conformant clients (Claude, the MCP SDKs) answer that by starting a fresh authorization.
+- A multi-resource `OAuthAuthorizationServer` without `legacyGrantResource` has no safe destination for unbound records and rejects them; set it for the migration window and keep it fixed.
+- Authorization codes issued by 0.x redeem under the same rules.
+
+## Type-level changes
+
+| 0.x                                                 | 1.0                 |
+| --------------------------------------------------- | ------------------- |
+| `ExchangeTokenOptions.aud?: string \| string[]`     | `aud?: string`      |
+| `AuthRequest.resource?: string \| string[]`         | `resource?: string` |
+| `TokenExchangeCallbackOptions.resource` (array-ish) | single `string`     |
+| `ResolveExternalTokenResult.audience?` (optional)   | required `string`   |
+
+## New in 1.0, adopt when useful
+
+None of these require changes to a migrated 0.x deployment:
+
+- **Role classes** — `OAuthAuthorizationServer` (one AS, many resources) and `OAuthResourceServer` (host a resource in the AS Worker or its own, validating over a Service Binding). See [resource-servers.md](resource-servers.md).
+- **`ctx.auth` and `insufficientScope()`** — handlers see the verified token facts beside `ctx.props` and answer scope shortfalls with the MCP `403` challenge. See the README's scopes section.
+- **`onError.internal`** — every library error carries a stable `{ category, reason }` for logs and alerting; the wire stays generic.
+- **`refreshTokenIdleTTL`** — opt-in sliding refresh-token expiry.
+- Dynamically registered clients in active use renew automatically; grant listing and revocation are KV-bounded.

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudflare/workers-oauth-provider",
-  "version": "0.10.3",
+  "version": "1.0.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": {