mcp-authz 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jag Reehal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,411 @@
+# mcp-authz
+
+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.
+
+## Who does what
+
+```
+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.
+
+## Install
+
+```bash
+pnpm add mcp-authz @modelcontextprotocol/server
+# optional Node helper:
+pnpm add @modelcontextprotocol/node
+```
+
+## API
+
+### `createMcpFetch(options)`
+
+Returns `(request: Request) => Promise<Response>`.
+
+| Option              | Purpose                                                        |
+| ------------------- | -------------------------------------------------------------- |
+| `resourceServerUrl` | Public URL Claude reaches, e.g. `https://mcp.acme.com/mcp`     |
+| `oauthMetadata`     | Your AS's RFC 8414 fields, or `await discoverOAuth(issuer)`    |
+| `verifier`          | Built-in JWT/JWKS verification and claim options               |
+| `tokenVerifier`     | Custom SDK verifier, including opaque-token introspection      |
+| `identityFromAuth`  | Map custom `AuthInfo` to an `Identity`                         |
+| `requiredScopes`    | Baseline scopes (default `['mcp']`)                            |
+| `toolScopes`        | Declarative tool name → scope(s) for safe step-up              |
+| `capabilityScopes`  | Tools, prompts and resource URIs → scope(s)                    |
+| `supportedScopes`   | Additional scopes advertised in resource metadata              |
+| `scopesForRequest`  | Advanced `(request, trustedRoute) => scopes` resolver          |
+| `policy`            | `definePolicy(...)`; matching no rule is HTTP 403              |
+| `authorize`         | Async alternative to `policy` for external entitlements        |
+| `resolve`           | Optional: `(identity, principal) => context` to enrich context |
+| `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        |
+| `legacy`            | 2025 handling; strict `reject` by default                      |
+
+`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)`
+
+```ts
+oauthMetadata: await discoverOAuth('https://auth.acme.com'),
+```
+
+Reads the endpoints off the authorization server rather than out of a config file,
+including `jwks_uri`, which leaves the `verifier` block optional. It tries the RFC
+8414 location first and the OIDC one second, because Auth0 and Google publish only
+the latter. A document declaring a different issuer is refused: its endpoints would
+send your users somewhere else to sign in.
+
+The cost is a fetch during boot. An AS that is down now stops your deploy rather
+than only your logins, so keep passing `oauthMetadata` by hand if you would rather
+own that trade.
+
+The built-in JWT verifier requires `email_verified: true` by default before
+email or domain rules can run. Use `verifier.emailVerifiedClaim` for a
+provider-specific assurance claim, or explicitly set `requireEmailVerified:
+false` only when the issuer contract guarantees the email another way. For
+opaque tokens, pass any SDK-compatible `tokenVerifier` plus `identityFromAuth`.
+
+### `definePolicy(spec)`
+
+```ts
+import { definePolicy } from 'mcp-authz';
+
+const policy = definePolicy({
+  roles: {
+    reader: ['cases:read'],
+    editor: ['cases:read', 'cases:write'],
+    admin: ['*'],
+  },
+  rules: [
+    { match: { domain: 'acme.com' }, role: 'reader' },
+    { match: { email: 'alice@acme.com' }, role: 'editor' },
+    { match: { claim: { 'org.groups': 'qa-leads' } }, role: 'editor' },
+    { match: { sub: 'auth0|left-last-march' }, deny: true },
+  ],
+});
+
+export type Permission = PermissionOf<typeof policy>; // 'cases:read' | 'cases:write'
+```
+
+Match on `issuer`, `sub`, `email`, `domain`, or any verified `claim` (dotted paths; a scalar
+must equal, an array must contain). Every matching rule applies and the permissions
+union; one `deny` match wins over all of them.
+
+Email and domain rules match only when the identity mapper marked the email as
+verified. Stable identities are the pair `(issuer, sub)`, not `sub` alone; include
+`issuer` in a rule when one policy accepts identities from multiple issuers.
+
+**Matching no rule means no permissions**, and there is no setting to change that.
+A default that can be widened eventually is, and the failure is silent.
+
+Written as a literal above, permission names become a string-literal union:
+
+```ts
+tool(
+  'update_case',
+  {
+    permission: 'cases:wrtie',
+    //          ^^^^^^^^^^^^^
+    // Type '"cases:wrtie"' is not assignable to
+    // type '"cases:read" | "cases:write"'.
+  },
+  updateCase,
+);
+```
+
+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
+never saw. The library reads neither the environment nor the filesystem: how an
+application loads configuration is the application's business.
+
+The full runtime shape is validated at startup: catalogues, roles, permission
+strings, rules, match fields and claim values. Malformed JSON cannot survive
+boot and become a request-time 500.
+
+For a wildcard-only policy, declare the concrete vocabulary so permission
+names remain compile-time checked:
+
+```ts
+const policy = definePolicy({
+  permissions: ['cases:read', 'cases:write'],
+  roles: { admin: ['*'] },
+  rules: [{ match: { email: 'admin@acme.com' }, role: 'admin' }],
+});
+```
+
+### `authz(policy)`
+
+One call binds everything to one policy. Each builder accepts only a permission that
+policy can grant, so `cases:wrtie` is a build error in all three.
+
+```ts
+const { tool, prompt, resource, server } = authz(policy);
+
+const createServer = server(
+  [
+    tool(
+      'update_case',
+      {
+        permission: 'cases:write',
+        inputSchema: z.object({ id: z.string(), title: z.string() }),
+        audit: ({ id }) => `case:${id}`,
+      },
+      async ({ id, title }, { principal }) => renameCase(id, title, principal),
+    ),
+
+    // A prompt is a tool call somebody else composed, so it costs what that
+    // call costs. A resource is read-only to MCP and still the whole case list.
+    prompt('triage_case', { permission: 'cases:write', argsSchema }, walkThroughRename),
+    resource('cases', { permission: 'cases:read', uri: 'cases://all' }, readCases),
+  ],
+  { name: 'acme', version: '1.0.0', onAudit: (event) => log.info(event) },
+);
+```
+
+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.
+
+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
+advertises only the kinds it actually has.
+
+Each handler takes the tool's arguments and a context carrying the `Principal` the
+policy produced:
+
+| Field             | What it holds                                                  |
+| ----------------- | -------------------------------------------------------------- |
+| `issuer`          | Exact token issuer; key durable identity with `sub`.           |
+| `sub`             | Token subject, unique only within its issuer.                  |
+| `email`           | Verified email when the issuer supplies one.                   |
+| `domain`          | Workspace domain, when the AS passes `hd` through.             |
+| `roles`           | Names of the roles that matched.                               |
+| `permissions`     | What those roles grant.                                        |
+| `can(permission)` | Honours a `*` grant, so ask this instead of reading the array. |
+
+A handler never checks the permission it declared, because `server` checked it before
+registering. Call `can` when one handler branches on a second permission, such as
+returning extra fields to an admin.
+
+### `gate(server, principal, permissions)`
+
+For an MCP server you already have, from another package or one you are not ready
+to change, whose tools were never declared with a permission.
+
+```ts
+// one hook in their builder
+const server = options.wrap ? options.wrap(new McpServer(info, opts)) : new McpServer(info, opts);
+
+// your connector
+createServer: (principal) =>
+  buildServer(config, {
+    wrap: (server) => gate(server, principal, { get_case: 'testrail:read', delete_run: 'testrail:delete' }),
+  }),
+```
+
+The reader never sees `delete_run` in `tools/list`, from a builder that knows
+nothing about any of this. Their calls land in your `onAudit` log, which is the only
+record tying a person to an action when the downstream API sees one service account.
+
+A registration with no entry in the map throws, naming the tool. Dropping it either
+way is how a tool nobody priced ends up reachable by everyone, or by nobody, with
+no error to read.
+
+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.
+
+### Boot-time reconciliation
+
+Pass both `policy` and a server built by `authz`, and startup compares them:
+
+```
+MCP policy validation failed
+
+Unreachable capability:
+  delete_case
+    requires: cases:delete
+    granted by: no role
+```
+
+An unreachable capability throws — 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.
+
+### External entitlements and rich context
+
+Use `authorize` instead of `policy` when permissions live in an IdP, database
+or policy service. `definePermissions` preserves compile-time names without
+inventing a static policy, and `createPrincipal` builds the decision safely.
+
+```ts
+import { authz, createPrincipal, definePermissions, type Principal } from 'mcp-authz';
+
+const permissions = definePermissions(['cases:read', 'cases:write'] as const);
+type Permission = (typeof permissions.permissions)[number];
+type Context = { principal: Principal<Permission>; tenant: Tenant };
+
+const { tool, server } = authz(permissions, {
+  principal: (context: Context) => context.principal,
+});
+
+const createServer = server(
+  [tool('whoami', { permission: 'cases:read' }, async (_args, context) => describeTenant(context.tenant))],
+  { name: 'acme', version: '1.0.0' },
+);
+
+const fetch = createMcpFetch({
+  // ...resourceServerUrl, oauthMetadata, verifier
+  authorize: async (identity) => {
+    const grants = await entitlementsFor(identity.issuer, identity.sub);
+    return createPrincipal(identity, grants.roles, grants.permissions);
+  },
+  resolve: async (_identity, principal) => ({
+    principal,
+    tenant: await tenantFor(principal.issuer, principal.sub),
+  }),
+  createServer,
+});
+```
+
+With a static `policy`, `resolve` still enriches its decision without widening
+it. In either mode the complete context reaches handlers directly; definitions
+stay at module scope and boot-time reconciliation remains available for static
+policies.
+
+Pass `permissions` only when your own wrapper hides the map attached to a built
+server factory.
+
+### Refusing a caller
+
+```ts
+throw AccessDeniedError.notPermitted(email);
+throw AccessDeniedError.noCredential(email, 'a TestRail API key');
+```
+
+The gate turns either one into HTTP `403` with
+`{"error":"forbidden","reason":"policy_denied"}` and the message as
+`error_description`. It deliberately carries no Bearer challenge: a token upgrade
+cannot repair company policy.
+`error.reason` is `'not_permitted'` or `'no_credential'` for your logs. A caller
+who matches no rule gets the first of these before your `resolve` runs.
+
+Throw it from `resolve`, never from `createServer`. The SDK owns factory failures,
+so a refusal raised in there reaches the caller as a 500 with the reason stripped.
+
+### Scope step-up (SEP-2243)
+
+```ts
+toolScopes: {
+  search_docs: 'mcp',
+  update_doc: ['mcp', 'write'],
+},
+```
+
+Use `capabilityScopes` when prompts or resources need step-up too. Keys are a
+bare tool name (or `tool:name`), `prompt:name`, and `resource:<uri>`.
+
+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.
+
+Permissions determine capability visibility. Scopes determine whether this token
+can invoke a visible capability. The request order is therefore: verify the baseline
+token, evaluate capability permission, challenge for missing capability scope, then
+dispatch. An unpermitted caller is never prompted through a futile step-up.
+
+```text
+cases:write permission ✓  +  write scope ✗
+    tools/list            → update_case is visible
+    tools/call            → 403 insufficient_scope, scope="mcp write"
+    client re-authorises  → retry
+```
+
+Insufficient scope becomes HTTP `403` with `WWW-Authenticate: … error="insufficient_scope"`, which a conforming client can act on. A tool `isError` cannot.
+
+The map is also used to advertise every supported scope in protected-resource
+metadata. Scope selection happens only after the 2026 request classifier and
+standard-header validation have proved `Mcp-Method` and the decoded `Mcp-Name`
+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
+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.
+
+### `mcp-authz/policy`
+
+The policy half on its own — `definePolicy`, `definePermissions`,
+`createPrincipal`, `Principal`, `Identity`, `reconcile` — with no MCP code in
+the module graph:
+
+```ts
+import { definePolicy, type Identity } from 'mcp-authz/policy';
+```
+
+The decision is `identity → principal → permissions`; MCP is one surface that
+consumes it. Gating an Agent SDK tool loop or a plain HTTP tool API reuses the
+same policy object and the same file an administrator edits.
+
+Note this shrinks what you _load_, not what you _install_: `@modelcontextprotocol/server`
+is still a dependency of the package. Splitting it out only becomes worth doing
+if a non-MCP consumer actually turns up.
+
+### Node listen helper
+
+```ts
+import { listenMcp } from 'mcp-authz/node';
+
+await listenMcp(fetch, { port: 8200, name: 'acme-mcp', info: { resource: url } });
+```
+
+Binds every interface; the bearer gate is the security boundary.
+
+## Configuration (typical deployment)
+
+| Variable                       | Purpose                                         |
+| ------------------------------ | ----------------------------------------------- |
+| `MCP_PUBLIC_URL`               | URL Claude reaches                              |
+| `OAUTH_ISSUER`                 | Authorization server issuer                     |
+| `OAUTH_AUTHORIZATION_ENDPOINT` | From AS metadata                                |
+| `OAUTH_TOKEN_ENDPOINT`         | Same                                            |
+| `OAUTH_REGISTRATION_ENDPOINT`  | Optional; needed if clients still use DCR       |
+| `OAUTH_JWKS_URI`               | Signing keys                                    |
+| `GOOGLE_WORKSPACE_DOMAIN`      | Optional. Refuse tokens outside your domain     |
+| `MCP_POLICY`                   | Optional. Policy JSON, when not written in code |
+
+## Spec (2026-07-28)
+
+- Strict 2026 Streamable HTTP via SDK `createMcpHandler`; opt in to legacy explicitly
+- Standard routing headers are validated against the body before scope selection
+- RFC 9728 Protected Resource Metadata
+- 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.
+
+## License
+
+MIT