mcp-authz 0.1.0 → 0.2.0

package/README.md

@@ -1,23 +1,134 @@
 # mcp-authz
 
+**Give an MCP server per-user permissions without deploying an authorization system.**
+
 A remote MCP **resource server** you put behind Claude (or any MCP client that speaks OAuth). People sign in through your authorization server; a policy decides which permissions they hold; MCP capabilities declare the permission they need, and a caller only ever sees the ones they may use.
 
-This package is the generic shell. Wire TestRail, Jira, Help Scout, or anything else behind it — the downstream service keeps its single service credential, and this decides which person may make it do what.
+This package is the generic shell. Wire TestRail, Jira, Help Scout, or anything else behind it. The downstream service keeps its single service credential, and this decides which person may make it do what.
+
+## Where it fits
+
+Use it when you can reach the server's code, or wrap the builder that makes it, and the callers are people who already sign in somewhere. Dana reads cases, Alice also writes them, and that decision sits next to the handler running the query. You install a dependency, and you run nothing new.
+
+Plenty of good tools solve the neighbouring problems. Take one of them when its row describes you:
+
+| Approach                       | Example                | What you take on                                                       |
+| ------------------------------ | ---------------------- | ---------------------------------------------------------------------- |
+| MCP gateway                    | agentgateway           | A data-plane component to deploy and keep available                    |
+| Gateway plus policy service    | Permit                 | The gateway, and the policy infrastructure behind it                   |
+| External decision point        | Cerbos                 | A PDP to run, and a call out to it on every decision                   |
+| Relationship-based permissions | Auth0 FGA              | Richer rules than this offers, in a second authorization system        |
+| Framework feature              | FastMCP                | Convenience, tied to that framework                                    |
+| OAuth plumbing                 | official SDK, mcp-auth | Authentication and resource-server mechanics, with no permission model |
+| Embedded dependency            | **mcp-authz**          | One package, and a policy engine that stays small by design            |
+
+Two cases need none of this. A stdio server on one laptop already has the OS account as its boundary. A server where every caller gets identical access wants one service credential and no policy.
+
+### You need one integration seam
+
+Which one you get decides the tool, and the source is not the only seam that
+works.
+
+```mermaid
+flowchart TD
+    Q["How much of the server can you reach?"]
+    Q -->|"You write the tools"| A["<b>authz()</b><br/>permissions declared on the capability,<br/>names checked by tsc,<br/>catalogue reconciled at boot"]
+    Q -->|"You call somebody else's<br/>builder, and it lets you<br/>wrap the server it makes"| B["<b>gate()</b><br/>a permission map over tools<br/>that were never written for one"]
+    Q -->|"All you have is a URL"| C["<b>createMcpProxy</b><br/>record the catalogue,<br/>enforce at the edge"]
+```
+
+The middle rung is the one people miss. A package you install, whose tools you
+did not write, still works here as long as its builder hands you the server
+before returning it. That hook is two lines, it is worth asking an upstream
+maintainer for, and [`gate()`](#gateserver-principal-permissions) shows both
+sides of it. Without the hook nothing in this package can help: the SDK keeps a
+built server's tool list private, so no code can filter what it never saw.
+
+Writing the server in Python? [`mcp-authz` on PyPI](https://pypi.org/project/mcp-authz/) makes the same decisions on the official Python SDK.
+
+### FastMCP and `canAccess`
+
+FastMCP gates a capability with a predicate:
+
+```ts
+canAccess: requireRole('admin');
+canAccess: (auth) => auth?.role === 'admin' && auth?.department === 'engineering';
+```
+
+That runs, and for one rule in one place it is the right amount of machinery.
+
+A predicate carries no vocabulary. TypeScript cannot derive the permission names from it, startup cannot compare the tools against the roles, and each closure agrees with the others only because you kept them in step by hand. `definePolicy` hands you one object that the compiler reads and that boot reconciles:
+
+- `permission: 'cases:wrtie'` fails `tsc` rather than a request at 3am.
+- A tool requiring `cases:delete` that no role grants refuses to boot.
+- An administrator edits one file instead of eleven closures.
+
+Twenty tools sharing a vocabulary is where this pays. One tool with one rule is where it does not.
+
+## Deployment
+
+You ship one MCP server process with this library inside it. Claude dials your
+public URL. Your authorization server runs login. TestRail or Jira keeps one
+service credential. Full stack detail is in the
+[docs](https://jagreehal.github.io/mcp-authz/concepts/deployment/).
+
+```mermaid
+flowchart LR
+    Client["MCP client"] -->|"OAuth login, PKCE"| AS["Authorization server"]
+    AS -->|"OIDC login"| IdP["Google Workspace"]
+    Client -->|"Bearer token<br/>aud = your MCP URL"| MCP["Your MCP server<br/>mcp-authz"]
+    MCP -->|"service credential"| API["Downstream API"]
+```
 
 ## Who does what
 
+```mermaid
+flowchart TD
+    Client["MCP client"] -->|"OAuth 2.1, PKCE, resource = MCP URL"| AS["Authorization server"]
+    AS -->|"OIDC login"| IdP["Google Workspace"]
+    IdP -->|"verified email, hd, groups"| AS
+    AS -->|"access token, aud = MCP URL"| Client
+    Client -->|"Bearer on POST /mcp"| Lib["mcp-authz"]
+    Lib -->|"createServer(principal)"| App["Your handlers"]
 ```
-Claude ──OAuth 2.1 (CIMD/DCR, PKCE, resource=your URL)──▶ authorization server
-                                                           │ signs the human in
-                                                           ▼
-                                                    Google Workspace (OIDC)
-                                                           │ verified email
-                                                           ▼
-                                                  this library: verify, map,
-                                                  call createServer(context)
+
+**We are a resource server, and nothing more.** Verifying tokens is ours.
+Registering Claude, showing consent and running PKCE belongs to an authorization
+server that already exists. Google cannot fill that role itself: it has no
+client registration for your MCP audience, and it will not mint a token whose
+audience is your MCP endpoint. WorkOS, Stytch and Auth0 all do both halves,
+including Google Workspace login.
+
+## What a request goes through
+
+```mermaid
+flowchart TD
+    R["POST /mcp"] --> Path{"Path matches<br/>resourceServerUrl?"}
+    Path -->|no| E404["404 naming the path<br/>this server does answer on"]
+    Path -->|yes| Bearer{"Baseline token valid?<br/>signature, iss, aud, exp"}
+    Bearer -->|no| E401["401 + WWW-Authenticate<br/>carrying resource_metadata"]
+    Bearer -->|yes| Pol["identityFromAuth → policy<br/>or authorize() → Principal"]
+    Pol -->|"no rule matched"| E403["403 forbidden / policy_denied<br/>no Bearer challenge"]
+    Pol --> Pre["Classify the request and check<br/>Mcp-Method / Mcp-Name against the body"]
+    Pre -->|"headers disagree,<br/>or are missing"| E400["400, before any tool is chosen"]
+    Pre --> Perm{"principal.can()<br/>for this capability?"}
+    Perm -->|no| E403
+    Perm -->|yes| Scope{"Token carries the<br/>capability's scope?"}
+    Scope -->|no| E403S["403 insufficient_scope<br/>the client can re-authorise"]
+    Scope -->|yes| Ctx["resolve() adds tenant,<br/>credentials, request context"]
+    Ctx --> Build["createServer registers only<br/>the capabilities this caller may use"]
+    Build --> Ask{"Does this call ask<br/>for a person?"}
+    Ask -->|no| H
+    Ask -->|"declined, unanswered,<br/>or approved by nobody"| E403A["ApprovalRefusedError,<br/>logged as decision: deny"]
+    Ask -->|approved| H["Handler runs, holding the Principal"]
 ```
 
-**We are a resource server, and nothing more.** Verifying tokens is ours. Registering Claude, showing consent and running PKCE belongs to an authorization server that already exists. Google cannot fill that role itself: it has no client registration for your MCP audience, and it will not mint a token whose audience is your MCP endpoint. WorkOS, Stytch and Auth0 all do both halves, including Google Workspace login.
+Three orderings in there are deliberate. Authentication precedes the body read,
+so nobody who cannot present a valid token can make this process parse anything.
+Header validation precedes both the permission lookup and scope selection, so an
+untrusted `Mcp-Name` can talk its way into neither a cheaper scope nor another
+capability's permission. Permission precedes scope, so an unpermitted caller is
+never prompted to re-authorise for an action your policy will refuse anyway.
 
 ## Install
 
@@ -27,6 +138,64 @@ pnpm add mcp-authz @modelcontextprotocol/server
 pnpm add @modelcontextprotocol/node
 ```
 
+Requires Node.js 24 or newer.
+
+## Point your authorization server at it
+
+Five steps, in order. Step 2 is the one people skip, and its failure is the
+confusing kind: the client completes the whole OAuth flow, receives a valid
+token, and then never sends it.
+
+1. **Settle the public URL.** `resourceServerUrl` has to be the URL clients
+   dial, path and all. The library publishes RFC 9728 metadata at
+   `/.well-known/oauth-protected-resource/mcp` for an `/mcp` path and names that
+   same URL as `resource`. A client that reads a different host there declines
+   to attach its token, and nothing in the logs says "wrong host".
+
+2. **Register that URL at your AS as a resource identifier, with RFC 8707
+   resource indicators enabled.** The client sends
+   `resource=https://mcp.acme.com/mcp`, and your AS has to mint a token whose
+   `aud` equals it. Auth0 models this as an API with an audience; WorkOS and
+   Stytch expose it as the MCP resource server settings. Without it you get a
+   perfectly signed token that this library refuses with 401.
+
+3. **Define the scopes.** The baseline is whatever you pass to `requiredScopes`
+   (default `mcp`), plus one scope for each entry in `toolScopes` or
+   `capabilityScopes`, such as `write`. Grant them to the client. The library
+   advertises the full set as `scopes_supported` in the resource metadata.
+
+4. **Decide how clients register.** Prefer an AS that supports CIMD. If yours
+   only offers DCR, publish `registration_endpoint` in `oauthMetadata`, and
+   treat it as a stopgap: DCR is deprecated in this protocol revision.
+
+5. **Check the claims your rules need.** `iss`, `sub`, `aud` and `exp` are
+   always required. Any `email` or `domain` rule also needs `email` and
+   `email_verified: true`. A Workspace `domain` rule reads `hd`, so the AS has
+   to pass it through from Google.
+
+Then hand the library the issuer and let it read the rest:
+
+```ts
+const fetch = createMcpFetch({
+  resourceServerUrl: new URL(process.env.MCP_PUBLIC_URL!),
+  oauthMetadata: await discoverOAuth(process.env.OAUTH_ISSUER!),
+  policy,
+  createServer,
+});
+```
+
+Add `https://mcp.acme.com/mcp` in Claude as a custom connector and sign in.
+
+### When it does not work
+
+| Symptom                                                | Cause                                                                        |
+| ------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| Login succeeds, then the client never attaches a token | `resourceServerUrl` is not the URL the client dialled (step 1)               |
+| 401 on every call, signature verifies fine             | `aud` is not your MCP URL (step 2), or `iss` does not match                  |
+| 401 for some people only                               | `email_verified` missing or false, or `hd` outside your Workspace            |
+| 403 `forbidden/policy_denied`                          | The token is fine and no rule matched. Working as designed                   |
+| 403 `insufficient_scope`                               | Permission granted, token lacks the capability's scope. Client re-authorises |
+
 ## API
 
 ### `createMcpFetch(options)`
@@ -51,9 +220,16 @@ Returns `(request: Request) => Promise<Response>`.
 | `onDecision`        | Awaited allow/deny decision sink                               |
 | `createServer`      | `(context) => McpServer` once per request; see `authz`         |
 | `permissions`       | Optional: the boot-time map, when a factory of yours hides it  |
-| `maxRequestBytes`   | Cap on the pre-auth body read for scopes. Default 1 MiB        |
+| `maxRequestBytes`   | Cap on the post-auth body read that names a capability. 1 MiB  |
 | `legacy`            | 2025 handling; strict `reject` by default                      |
 
+**`legacy` needs care.** The SDK client 2.0.0 still opens with an `initialize` handshake, and
+2026-07-28 removed it (SEP-2567) — so from this handler's side every client shipping today is a
+legacy client, and the default `reject` turns all of them away. A deployment real clients must
+reach wants `legacy: 'stateless'` until a client ships without the handshake. The refusal says
+so itself rather than returning a bare protocol error. The gate applies identically on both
+paths; `src/e2e.story.test.ts` drives a real client through each.
+
 `MCP_PUBLIC_URL` / `resourceServerUrl` **must** be the URL clients actually reach. Advertise anything else and a conforming client will not attach its token to a resource it was not issued for.
 
 ### `discoverOAuth(issuer)`
@@ -128,7 +304,7 @@ tool(
 
 Handed
 `definePolicy(JSON.parse(process.env.MCP_POLICY!))` the same call still validates
-the shape and still reconciles at boot — it just cannot check names TypeScript
+the shape and still reconciles at boot. It cannot check names TypeScript
 never saw. The library reads neither the environment nor the filesystem: how an
 application loads configuration is the application's business.
 
@@ -178,13 +354,18 @@ const createServer = server(
 
 Whatever the caller lacks the permission for is **never registered**, so it is absent
 from `tools/list` and there is no per-handler check to forget. Skipping the list and
-naming an unregistered prompt gets the same refusal, because registration is the
-authorization seam rather than the listing. OAuth scopes do not affect visibility:
-a permitted capability remains visible when the current token needs step-up.
-
-`onAudit` is awaited and emits `attempt`, followed by `success` or `failure`,
-with identity, capability, permission, resource, timestamp and duration. A
-rejected sink fails closed instead of silently losing the record.
+naming an unregistered prompt is refused before dispatch with the same `403
+forbidden / policy_denied`, and that denied attempt reaches `onDecision`. A probe
+for a capability somebody was never shown is exactly the one worth having in a log.
+OAuth scopes do not affect visibility: a permitted capability remains visible when
+the current token needs step-up.
+
+`onAudit` emits `attempt`, followed by `success`, `failure` or `refused`, with
+identity, capability, permission, resource, timestamp and duration. The server
+awaits each write. A rejected `attempt` write stops the handler before it runs.
+A terminal write happens after the action has reached its result, so its failure
+cannot change that result. Set `onAuditError` to send the failed event and error
+to your retry queue or operator alert.
 
 The boot-time check keys prompts and resources as `prompt:triage_case` and
 `resource:cases`, so a prompt sharing a tool's name stays its own entry. A server
@@ -207,6 +388,142 @@ A handler never checks the permission it declared, because `server` checked it b
 registering. Call `can` when one handler branches on a second permission, such as
 returning extra fields to an admin.
 
+### Where the audit events go
+
+The downstream API sees one service account. These events are the only record
+tying a person to an action, so they are worth sending somewhere a security team
+already looks — their SIEM, their warehouse, the log pipeline behind their
+dashboards. There is no sink to configure and no adapter to install: each hook is
+a function, and the useful ones are one line.
+
+```ts
+onAudit: (event) => logger.info(event),          // structured log → wherever it already ships
+onAudit: (event) => db.insert(auditLog).values(event),
+onDecision: (event) => logger.warn(event),
+```
+
+**Wire both.** `onAudit` sees calls that were permitted. `onDecision` sees the
+refusals — including somebody naming a capability they were never shown, which is
+the single most interesting line in the whole log. They are separate hooks because
+they happen in different places: one wraps the handler, the other answers the
+request before dispatch.
+
+**Keep third-party HTTP off the hot path.** The `attempt` write is awaited, and
+rejecting it stops the call before it runs — that is what makes the trail
+fail-closed, and it means a webhook here puts somebody else's uptime in front of
+your tools. Write locally, ship asynchronously; if you must call out, do it from
+`onAuditError`, or from the terminal events, which cannot change a result that has
+already happened.
+
+**Three fields exist for the reader, not the caller.** `callId` is the same on
+both events of one call and different for every other, so a store can join an
+attempt to its outcome without guessing from timestamps. `domain` is the verified
+Workspace domain — the nearest thing to an organisation this can prove, so key one
+by `(issuer, domain)`. `emitter` names the deployment, and it is the one you have
+to set yourself:
+
+```ts
+server(definitions, { name: 'cases', version: '1.0.0', emitter: 'cases-prod', onAudit });
+createMcpFetch({ ..., emitter: 'cases-prod', onDecision });
+```
+
+Set the same value in every entry point of one deployment, or a reader cannot tell
+that a refusal and a call came from the same place. Left unset the field is absent
+rather than guessed. With those three, "what does this org use, and who used it"
+is a group-by rather than a schema migration.
+
+**Every event says what it is.** `mcp_authz.audit.v1` and
+`mcp_authz.decision.v1` share half their fields and land in the same store, often
+for years, so each carries its own `type`. Query on that rather than on which
+fields happen to be present:
+
+```ts
+onAudit: (event) => sink.write({ ...event, index: event.type }); // event.type is a literal union
+```
+
+A new optional field does not move the `v1`. Changing what an existing field means
+does, because a stored query cannot tell that apart.
+
+There is no dashboard here, and there should not be: it would mean storage,
+retention, its own authentication and a tenancy model, competing with the tool
+your security team already pays for. The events are JSON with a stable shape —
+send them there.
+
+### Human approval
+
+Some actions want a second person even when the caller is permitted. Declare it
+on the capability and the call waits for an answer before it runs:
+
+```ts
+tool(
+  'delete_run',
+  {
+    permission: 'testrail:delete',
+    // `true` for every call, or a predicate when only some arguments warrant it
+    approval: ({ force }) => force,
+    audit: ({ id }) => `run:${id}`,
+  },
+  deleteRun,
+);
+
+server(definitions, {
+  name: 'acme',
+  version: '1.0.0',
+  onApproval: async (request) => {
+    const reply = await askInSlack('#ops', request); // request carries who, what, and the arguments
+    return reply.ok ? { approved: true, by: reply.user } : { approved: false, reason: reply.text };
+  },
+});
+```
+
+`{ approved: true }` will not compile without `by`, and an approval that arrives
+naming nobody is refused at runtime as well. The type is the first line and not
+the only one: an adapter written in untyped code, or one handing back a JSON
+reply from a chat tool, can still produce an anonymous yes, and that would run a
+destructive call under an audit trail claiming somebody had agreed to it.
+
+An approval nobody's name is on is not a second pair of eyes. The approver's
+name lands on the `success` audit event beside the caller's, the only place both
+people appear, because the downstream API still sees one service account.
+
+This is not the permission check repeated. The caller already holds
+`testrail:delete`; approval is the separate question of whether _this_ call
+should happen. It is also the one check here that cannot be a decision about
+whether to register something, because it turns on arguments that do not exist
+until the call. An unapproved capability is therefore visible in `tools/list` and
+refused on invocation, unlike an unpermitted one.
+
+**Silence is a refusal.** `approvalTimeoutMs` defaults to 45s, under the 60s
+idle timeout most proxies ship with. An `onApproval` that throws refuses too,
+rather than letting the action through on the strength of a Slack outage, and an
+answer arriving after the deadline changes nothing: the caller has already been
+told no.
+
+A refusal reaches the handler's place as an `ApprovalRefusedError` carrying the
+capability and, when there was one, the person who declined. The audit event is
+`phase: 'refused'` with `decision: 'deny'`, and its `durationMs` covers the wait,
+so the log shows what a call actually cost rather than what the handler did.
+
+**A capability that asks for a person while no sink can be reached fails at
+boot**, not at the first destructive call. `server(...)` and `gate(...)` both
+refuse to wire it, the same way an unreachable capability refuses to start.
+
+Nothing here is durable, and it does not need to be. The caller is still on the
+other end of an open request, so a process that dies mid-question takes the
+request with it and the action correctly did not happen. Durability is only owed
+once you have told a caller you are done and promised to act later, which is a
+promise this never makes.
+
+If you need approval that outlives the request, keep the same seam: have
+`onApproval` write a pending row, return `{ approved: false, reason: 'ticket
+appr_123' }`, and add a tool of your own that polls it. The store lives in your
+application, where you can see it, and this package stays something you install
+rather than something you run.
+
+`gate()` takes the same options for tools you did not write: an `approval` map
+keyed exactly like `permissions`, plus `onApproval`. Adding a person in front of
+somebody else's destructive tool is the best reason to reach for it.
+
 ### `gate(server, principal, permissions)`
 
 For an MCP server you already have, from another package or one you are not ready
@@ -235,6 +552,127 @@ This needs the hook because the SDK keeps a built server's tool list private, so
 nothing can filter what it never saw. Pass the same map as `permissions` to
 `createMcpFetch` and the boot-time check still covers the roles side.
 
+### `recordCapabilities(factory)` — building that map
+
+The map above has to name every capability the server registers, and nothing
+produced it: you wrote it by hand and it drifted quietly. `mcp-authz/testing`
+reads it off the server instead.
+
+```ts
+import { recordCapabilities, toPermissionsModule } from 'mcp-authz/testing';
+
+const { names, fingerprints } = await recordCapabilities(() => buildServer(TEST_CONFIG));
+
+expect(names).toEqual(Object.keys(PERMISSIONS).sort());
+expect(fingerprints).toMatchSnapshot();
+```
+
+It builds your server, connects a client over an in-memory transport, and lists
+tools, prompts, resources and templates, labelled the way `gate()` labels them.
+Build it **ungated**: a gated server answers per principal, so listing one hands
+you a map missing exactly the capabilities that most need a price.
+
+`toPermissionsModule(record)` renders the starting map as TypeScript source —
+`as const` with the derived permission type — every capability priced
+`TODO:unassigned`, which no role grants, so reconciliation refuses the boot until
+a person has decided what each one costs. Permissions are never guessed from
+`readOnlyHint`: the specification says annotations are hints and that tool-use
+decisions must not be made from them.
+
+`gate()` already refuses to start on a capability with no price, which covers a
+dependency that adds a tool. `fingerprints` covers the one it cannot see — a
+capability that keeps its name while its description, input schema, prompt
+arguments or URI template change underneath. Each digests the whole definition
+as served, so a snapshot turns that into a diff on the pull request. Nothing is
+enforced at boot: a digest in production is a second source of truth, and would
+make a description edit an outage.
+
+`@modelcontextprotocol/client` is an optional peer, needed only by this subpath.
+
+### `mcp-authz/openapi` — the same bet on an HTTP API
+
+An OpenAPI document is the other catalogue an agent reads. A tool that is never
+registered is a tool the model never sees; an operation that is never in the
+served document is an operation the agent never calls. Same move, same policy,
+same audit events, on `operationId` instead of a tool name.
+
+```ts
+import { createOpenApiFetch, recordOperations } from 'mcp-authz/openapi';
+import { toPermissionsModule } from 'mcp-authz/testing';
+
+// The map, generated from the document rather than written by hand.
+// recordOperations(spec).names → toPermissionsModule → PERMISSIONS
+export default createOpenApiFetch({
+  spec,
+  permissions: PERMISSIONS, // { getCase: 'cases:read', deleteCase: 'cases:delete', … }
+  resourceServerUrl: new URL(process.env.API_PUBLIC_URL!),
+  oauthMetadata,
+  policy,
+  onAudit: (event) => logger.info(event),
+  upstream: (request) => app.fetch(request), // your API, unchanged
+});
+```
+
+Dana fetches `/openapi.json` and gets three read operations. Alice fetches the
+same path and gets the write and the delete too. Dana calling `DELETE
+/cases/C1234` anyway is refused with the permission she lacks — the smaller
+document was a context saving, never the boundary.
+
+**Anything the document does not describe is refused**, with a 404 that says so.
+That is the same rule as `gate()`: a capability nobody priced is reachable by
+everyone or by nobody, with no error to read. Routes you deliberately keep out
+of the spec — a health check, static files — belong outside this wrapper rather
+than behind it.
+
+`recordOperations(spec)` needs the document and nothing else: no running server,
+no introspection, and it refuses an operation with no `operationId`, because a
+generated fallback name is a second naming scheme that changes under a path
+rename. Boot fails on an operation the map does not price, on a map entry naming
+an operation the document no longer has, and on a permission no role grants.
+
+Audit events are the ones you already have — `mcp_authz.audit.v1` with
+`kind: 'operation'`, the `operationId` as `name`, and the concrete path as
+`resource` — so one query covers both surfaces of the same product.
+
+This entry point does not import the MCP handler, its route classification or
+its scope step-up: it is its own bundle, ~10 kB plus the policy and verifier
+chunks it shares.
+
+### `createMcpProxy` — URL-only upstream
+
+When there is no builder hook, `mcp-authz/proxy` sits in front of a vendor MCP
+reached only by URL:
+
+```ts
+import { createMcpProxy } from 'mcp-authz/proxy';
+
+export default createMcpProxy({
+  resourceServerUrl: new URL(process.env.MCP_PUBLIC_URL!),
+  oauthMetadata: {/* same as createMcpFetch */},
+  verifier: { jwksUri: process.env.OAUTH_JWKS_URI! },
+  policy,
+  permissions: PERMISSIONS, // from recordUpstream → toPermissionsModule
+  resourceUris: RESOURCE_URIS, // same module; a read names a URI, not a label
+  upstream: {
+    url: process.env.UPSTREAM_URL!,
+    bearer: process.env.UPSTREAM_TOKEN!,
+  },
+});
+```
+
+Record the upstream with `recordUpstream` or `mcp-authz record --upstream`, price
+the map, deploy the proxy.
+
+The proxy is stricter than embed mode, because nothing downstream of it re-checks
+anything and it forwards on a service credential that outranks the caller.
+Routing headers that disagree with the body are refused rather than forwarded; a
+request with no routing headers is authorized from the body, which is what the
+upstream will act on; and a capability the map does not price is refused outright.
+The caller's `Authorization` and `Cookie` stay at the edge.
+
+See [proxy mode](https://jagreehal.github.io/mcp-authz/typescript/proxy/) and the
+[`proxy-example`](../../apps/proxy-example) app.
+
 ### Boot-time reconciliation
 
 Pass both `policy` and a server built by `authz`, and startup compares them:
@@ -248,7 +686,7 @@ Unreachable capability:
     granted by: no role
 ```
 
-An unreachable capability throws — it is dead code that looks live. A permission no capability
+An unreachable capability throws, because it is dead code that looks live. A permission no capability
 requires only warns, because granting a role ahead of the tool that will use it is
 how a staged rollout works.
 
@@ -324,6 +762,10 @@ toolScopes: {
 
 Use `capabilityScopes` when prompts or resources need step-up too. Keys are a
 bare tool name (or `tool:name`), `prompt:name`, and `resource:<uri>`.
+`createServer` route metadata lets startup reject keys that name no registered
+capability. Startup also rejects duplicate bare/`tool:` aliases. Each scope
+must contain one RFC 6749 scope token. Empty lists and space-delimited values
+fail during construction.
 
 Scopes and permissions are deliberately separate axes. A scope gap is a 403 the
 client can fix by re-authorising; a permission gap is an administrator's job.
@@ -349,16 +791,77 @@ match the JSON-RPC body. Missing, malformed or dishonest routing headers are
 HTTP 400 and never reach a tool. SEP-2243 Base64 sentinel names are decoded
 before lookup, so encoding a name cannot downgrade its scope.
 
-Choosing a scope means reading the body before the bearer gate runs, because the
-scope is what that gate checks. Only a POST is read, only up to `maxRequestBytes`
-(1 MiB by default, over it a 413), and only when its content type is JSON (415
+Choosing a scope means reading the body, because the capability is named in it
+and not trustworthily in a header. That read happens **after** the bearer gate,
+not before: the per-capability scope is checked against the token this request
+already carries, so nobody who cannot present a valid one gets to make this
+process parse anything. Only a POST is read, only up to `maxRequestBytes` (1 MiB
+by default, over it a 413), and only when its content type is JSON (415
 otherwise). A GET carries no body to check its headers against, so it is held to
 the baseline rather than to whatever its headers claim.
 
+### `policy.explain(identity)` and the CLI
+
+The decision tells you what Alice may do. It cannot tell you why, and why is
+what gets asked when somebody is surprised.
+
+```ts
+const { principal, matched, deniedBy } = policy.explain(identity);
+```
+
+`matched` carries every rule that fired, each with its index in your `rules`
+array, so the answer points at the line an administrator edits. `deniedBy` is
+set when a deny emptied the grant. Nothing on the request path calls this, so
+it costs a served request nothing.
+
+The same two questions from a terminal, with no server running:
+
+```bash
+npx mcp-authz explain policy.json --identity alice.json --capabilities caps.json
+```
+
+```text
+alice@acme.com
+
+Matched rules
+  rule 0  domain=acme.com -> reader
+  rule 1  email=alice@acme.com -> editor
+  rule 2  org.groups=qa-leads -> admin
+
+Effective roles
+  reader
+  editor
+  admin
+
+Permissions
+  cases:read
+  cases:write
+  * (every permission)
+
+Capabilities
+  get_case
+  update_case
+  prompt:triage_case
+```
+
+`--identity` takes an `Identity` or a decoded token payload (`iss`, `sub`,
+`email`, `email_verified`, `hd`), or `-` to read one from stdin. It answers a
+what-if, so it trusts the file it is handed rather than verifying a signature.
+
+```bash
+npx mcp-authz check policy.json --capabilities caps.json
+```
+
+`check` runs the same `reconcile` your server runs at boot, so a capability no
+role can reach fails the pull request rather than the deploy. It exits 1 on that
+and on an invalid policy, and 0 on an unused permission, which stays a warning
+because granting a role ahead of the tool that will use it is how a staged
+rollout works.
+
 ### `mcp-authz/policy`
 
-The policy half on its own — `definePolicy`, `definePermissions`,
-`createPrincipal`, `Principal`, `Identity`, `reconcile` — with no MCP code in
+The policy half on its own (`definePolicy`, `definePermissions`,
+`createPrincipal`, `Principal`, `Identity`, `reconcile`) with no MCP code in
 the module graph:
 
 ```ts
@@ -383,6 +886,20 @@ await listenMcp(fetch, { port: 8200, name: 'acme-mcp', info: { resource: url } }
 
 Binds every interface; the bearer gate is the security boundary.
 
+## See it work, without an authorization server
+
+```bash
+git clone https://github.com/jagreehal/mcp-authz && cd mcp-authz && pnpm install
+pnpm --filter mcp-authz-node-example dev                 # :8200, local dev key
+pnpm --filter mcp-authz-node-example token dana@acme.com # reader
+pnpm --filter mcp-authz-node-example token alice@acme.com # editor
+```
+
+Paste a token into the MCP Inspector. Dana sees `whoami` and `get_case`, Alice
+also sees `update_case`, and `sam@other.com` gets HTTP 403 before any tool runs.
+The full walkthrough, including scope step-up and an IdP group claim, is in
+[apps/node-example](https://github.com/jagreehal/mcp-authz/tree/main/apps/node-example).
+
 ## Configuration (typical deployment)
 
 | Variable                       | Purpose                                         |
@@ -396,6 +913,11 @@ Binds every interface; the bearer gate is the security boundary.
 | `GOOGLE_WORKSPACE_DOMAIN`      | Optional. Refuse tokens outside your domain     |
 | `MCP_POLICY`                   | Optional. Policy JSON, when not written in code |
 
+Every value except the last two comes off your authorization server. Pass
+`OAUTH_ISSUER` alone to `discoverOAuth` and it reads the endpoints and
+`jwks_uri` for you. See [Point your authorization server at it](#point-your-authorization-server-at-it)
+for what to configure there first.
+
 ## Spec (2026-07-28)
 
 - Strict 2026 Streamable HTTP via SDK `createMcpHandler`; opt in to legacy explicitly
@@ -404,7 +926,7 @@ Binds every interface; the bearer gate is the security boundary.
 - RFC 8707 resource indicators / audience binding
 - Prefer AS support for **CIMD**; DCR is deprecated in this protocol revision
 
-Requires Node.js 20 or newer; CI covers Node 20, 22 and 24.
+CI covers Node 24 and 26.
 
 ## License