# workers-oauth-provider-migrate-1.0

Adopt this skill: https://proskills.md/skills/other/cloudflare-workers-oauth-provider-skills-migrate-to-1-0

Page: https://proskills.md/skills/other/cloudflare-workers-oauth-provider-skills-migrate-to-1-0
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/migrate-to-1.0/SKILL.md
size: 3791
upstream: https://github.com/cloudflare/workers-oauth-provider/blob/main/skills/migrate-to-1.0/SKILL.md

```text
---
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).
```

## File: README.md
upstream: https://github.com/cloudflare/workers-oauth-provider/blob/main/README.md

````text
# OAuth 2.1 Provider Framework for Cloudflare Workers

`@cloudflare/workers-oauth-provider` adds OAuth 2.1 authorization to HTTP APIs and remote MCP servers running on Cloudflare Workers.

> **Upgrading from 0.x, 1.0 or 1.1?** Read the [migration guide](docs/migration-1.x.md), which covers every change since 0.10 with code, or point your coding agent at [`skills/migrate-to-1.x/`](skills/migrate-to-1.x/SKILL.md), which also ships in the npm package.

## Install

```sh
npm install @cloudflare/workers-oauth-provider
```

The authorization server needs a KV namespace bound as `OAUTH_KV`, and the `global_fetch_strictly_public` compatibility flag if it accepts Client ID Metadata Documents.

## Quick start

An MCP deployment has two roles. The **authorization server** signs users in and issues tokens. The **resource server** is your MCP endpoint: it accepts those tokens and checks them with the authorization server over a [Service Binding](https://developers.cloudflare.com/workers/runtime-apis/bindings/service-bindings/).

```ts
// auth-server/index.ts
const authorizationServer = new OAuthAuthorizationServer<Env>({
  issuer: 'https://auth.example.com',
  resources: ['https://mcp.example.com/mcp'],
  scopesSupported: ['mcp:read', 'mcp:write', 'offline_access'], // everything this server can grant
  clientIdMetadataDocumentEnabled: true,
});

export default class AuthServer extends WorkerEntrypoint<Env> {
  fetch(request: Request) {
    // /authorize is yours: parseAuthRequest(), sign the user in and ask for consent, completeAuthorization().
    if (new URL(request.url).pathname === '/authorize') return authorize(request, this.env);
    return authorizationServer.fetch(request, this.env, this.ctx); // discovery, token, revocation
  }

  // Resource servers call this over their Service Binding.
  validateToken(resource: string, token: string) {
    return authorizationServer.validateToken(resource, token, this.env);
  }
}
```

```ts
// mcp-server/index.ts
export default new OAuthResourceServer<Env, AuthProps>({
  resourceMetadata: {
    resource: 'https://mcp.example.com/mcp',
    authorization_servers: ['https://auth.example.com'],
  },
  requiredScopes: ['mcp:read'], // needed for any access; clients request these first
  validateToken: (env) => env.AUTH_SERVER.validateToken,
  handler: {
    fetch(request, env, ctx) {
      // ctx.props: what completeAuthorization() stored. ctx.auth: the verified token.
      // Step-up: a 403 naming the missing scope, and the client re-authorizes for it.
      const needed = request.method === 'GET' ? ['mcp:read'] : ['mcp:read', 'mcp:write'];
      if (!needed.every((scope) => ctx.auth.scope.includes(scope))) return insufficientScope(ctx.auth, needed);
      return Response.json({ userId: ctx.props.userId });
    },
  },
});
```

**[`examples/split-workers`](examples/split-workers)** has both Workers in full, including the `/authorize` handler and `wrangler.jsonc`, with an end-to-end test that runs them in workerd.

The resource server publishes its RFC 9728 metadata, answers unauthenticated requests with a challenge pointing at it, and accepts only tokens issued for its own resource. The handler owns authorization beyond that: scopes, ownership, tenancy.

On the wire both lists are called `scopes_supported`, as the specs name them, but they mean different things: `scopesSupported` is everything the authorization server can grant; a resource's `requiredScopes` is what any access needs, so MCP clients request it first, and more comes by step-up. The handler checks `ctx.auth.scope`: the library advertises the required scopes but doesn't enforce them, since only your code knows which scopes imply others. See [Scopes](docs/authorization-server.md#scopes-and-step-up-authorization).

## One Worker: `OAuthProvider`

The split roles above are the recommended shape. `OAuthProvider` remains fully supported for one Worker that is both the authorization server and its only resource, which was the 0.x shape: it combines the roles. Requests under `apiRoute` reach `apiHandler` with `ctx.props` and `ctx.auth`; everything else goes to `defaultHandler`, which owns `/authorize` and reaches the helpers as `env.OAUTH_PROVIDER`:

```ts
export default new OAuthProvider<Env>({
  apiRoute: '/mcp',
  apiHandler: McpApiHandler,
  defaultHandler, // your /authorize page
  authorizeEndpoint: '/authorize',
  tokenEndpoint: '/oauth/token',
  scopesSupported: ['mcp:read', 'mcp:write', 'offline_access'], // everything this server can grant
  resourceMetadata: {
    resource: 'https://mcp.example.com/mcp',
    authorization_servers: ['https://mcp.example.com'],
  },
  requiredScopes: ['mcp:read'], // needed for any access; clients request these first
  clientIdMetadataDocumentEnabled: true,
});
```

## Documentation

- [Resource servers](docs/resource-servers.md): more resources, both roles in one Worker, what the handler sees, other issuers.
- [Consent page](docs/consent-page.md): what it must show, Allow and Deny, remembering consent.
- [Signing in through another provider](docs/upstream-sign-in.md): GitHub, Google and friends as the identity step.
- [Authorization server reference](docs/authorization-server.md): the authorize endpoint, client registration (pre-registered, CIMD, DCR), PKCE and token lifetimes, resources and audiences, scopes, KV storage, every option.
- [MCP authorization discovery](docs/mcp-discovery.md): how a client gets from a `401` to your authorization server.
- [Advanced configuration](docs/advanced-configuration.md): external tokens, token exchange, `tokenExchangeCallback`, `onError`, Enterprise-Managed Authorization (experimental).
- [Storage schema](storage-schema.md): the KV layout. Tokens, codes and secrets are stored only as hashes; `props` are encrypted with a key only the token holder can unwrap.

## Standards

[MCP authorization 2026-07-28](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization), [OAuth 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13), and RFCs [6750](https://datatracker.ietf.org/doc/html/rfc6750), [7009](https://datatracker.ietf.org/doc/html/rfc7009), [7591](https://datatracker.ietf.org/doc/html/rfc7591), [7636](https://datatracker.ietf.org/doc/html/rfc7636), [8414](https://datatracker.ietf.org/doc/html/rfc8414), [8693](https://datatracker.ietf.org/doc/html/rfc8693), [8707](https://datatracker.ietf.org/doc/html/rfc8707), [9207](https://datatracker.ietf.org/doc/html/rfc9207) and [9728](https://datatracker.ietf.org/doc/html/rfc9728), plus [Client ID Metadata Documents](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document-00), [OpenID Connect RP Metadata Choices](https://openid.net/specs/openid-connect-rp-metadata-choices-1_0-final.html) and, experimentally, [MCP Enterprise-Managed Authorization](https://modelcontextprotocol.io/extensions/auth/enterprise-managed-authorization).

## Development

Node 24 or newer. `npm install`, `npm run build`, `npm run check`. Changes that affect behavior or the public API need a Changeset; see [AGENTS.md](AGENTS.md) for conventions, [SECURITY.md](SECURITY.md) for vulnerability reporting, and [HISTORY.md](HISTORY.md) for how the library began.
````
