@gydr-ai/mcp-oauth 0.0.0-stage → 0.1.2

package/README.md

@@ -1,3 +1,718 @@
-# Temporary Holding Version
+<h1 align="center">@gydr-ai/mcp-oauth</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <strong>OAuth 2.1 for remote MCP servers, in front of the identity provider you already run.</strong><br />
+  Its own audience-bound tokens, consent on every connection, and no token passthrough.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@gydr-ai/mcp-oauth"><img alt="npm" src="https://img.shields.io/npm/v/@gydr-ai/mcp-oauth" /></a>
+  <a href="https://github.com/gydr-ai/mcp-oauth/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/gydr-ai/mcp-oauth/actions/workflows/ci.yml/badge.svg" /></a>
+  <a href="https://scorecard.dev/viewer/?uri=github.com/gydr-ai/mcp-oauth"><img alt="OpenSSF Scorecard" src="https://api.scorecard.dev/projects/github.com/gydr-ai/mcp-oauth/badge" /></a>
+  <img alt="MCP 2026-07-28" src="https://img.shields.io/badge/MCP-2026--07--28-6f42c1" />
+  <img alt="OAuth 2.1 draft-17" src="https://img.shields.io/badge/OAuth_2.1-draft--17-0969da" />
+  <img alt="CIMD draft-03" src="https://img.shields.io/badge/CIMD-draft--03-0969da" />
+  <img alt="Node.js 22.12+" src="https://img.shields.io/node/v/@gydr-ai/mcp-oauth" />
+  <a href="LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue" /></a>
+</p>
+
+<p align="center">
+  <sub>Built and maintained by <a href="https://gydr.ai"><strong>Gydr</strong></a></sub>
+</p>
+
+---
+
+A remote [Model Context Protocol](https://modelcontextprotocol.io) server
+must run an OAuth authorization server that MCP clients (Claude, ChatGPT,
+Cursor and others) can discover, register with and sign in through. You
+already have an identity provider; you do not want to hand its tokens to
+every MCP client that asks.
+
+`@gydr-ai/mcp-oauth` is that authorization server. People sign in at **your
+OpenID Connect provider**, approve the connection on a consent screen, and
+the MCP client receives **opaque tokens that only your MCP server accepts**.
+The provider's tokens never leave your server.
+
+## Highlights
+
+- **Spec-complete for MCP.** Protected-resource and authorization-server
+  metadata, Client ID Metadata Documents, Dynamic Client Registration
+  (deprecated, still on by default), PKCE, resource indicators and issuer
+  identification: everything the
+  [MCP Authorization specification](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization)
+  asks of a server.
+- **No token passthrough.** Clients get tokens bound to your MCP endpoint.
+  The person's upstream refresh token stays on the server, encrypted per
+  grant, and your code calls `getUpstreamAccessToken()` when it needs one.
+- **Consent every time.** Each authorization names the client and where the
+  result goes, which closes the "confused deputy" gap the MCP
+  [security best practices](https://modelcontextprotocol.io/specification/2026-07-28/basic/security_best_practices)
+  describe. It cannot be switched off.
+- **Hardened by default.** Exact redirect matching, browser-bound flows,
+  single-use codes, refresh-token rotation with replay detection, strict page
+  headers, and SSRF-safe metadata downloads.
+- **Fits any stack.** Web `Request` in, `Response` out: Hono, Next.js,
+  Fastify, Express, plain Node. Any OIDC provider, any database with an
+  atomic write, any key-management service.
+- **Safely extensible.** Policy hooks that can only refuse, enrichment hooks
+  that cannot touch the protocol, and every limit configurable.
+
+## Contents
+
+- [How it works](#how-it-works)
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Guides](#guides)
+- [API](#api)
+- [Security model](#security-model)
+- [Specification compliance](#specification-compliance)
+- [Compatibility](#compatibility)
+- [Security](#security)
+- [About Gydr](#about-gydr)
+
+## How it works
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant C as MCP client
+    participant B as Browser
+    participant S as Your server + mcp-oauth
+    participant I as Identity provider
+
+    C->>S: MCP request without a token
+    S-->>C: 401, WWW-Authenticate points at resource metadata
+    C->>S: discover metadata, register (or use a metadata-document client_id)
+    C->>B: open /authorize (PKCE, resource, state)
+    B->>S: GET /authorize
+    S-->>B: redirect to the IdP, plus a browser-binding cookie
+    B->>I: sign in
+    I-->>B: back to /callback
+    S->>I: exchange the code, verify the ID token
+    S-->>B: consent screen
+    B->>S: approve
+    S-->>B: redirect to the client with a one-time code
+    C->>S: POST /token (code + PKCE verifier)
+    S-->>C: opaque access and refresh tokens for your MCP endpoint
+    C->>S: MCP request with Authorization: Bearer
+    S->>I: renew the upstream token when your code needs it (server side only)
+```
+
+## Install
+
+```bash
+npm install @gydr-ai/mcp-oauth
+```
+
+Node.js 22.12 or later. ES modules only. Runtime dependencies:
+[`jose`](https://github.com/panva/jose) and
+[`@gydr-ai/safe-fetch`](https://github.com/gydr-ai/safe-fetch).
+
+## Quick start
+
+With [Hono](https://hono.dev):
+
+```ts
+import { serve } from "@hono/node-server"
+import { Hono } from "hono"
+import {
+  createAesGcmSealer,
+  createMcpAuth,
+  createMemoryStore,
+  createOidcProvider,
+} from "@gydr-ai/mcp-oauth"
+
+const ORIGIN = "https://mcp.example.com"
+
+const auth = createMcpAuth({
+  issuer: ORIGIN,
+  resource: `${ORIGIN}/mcp`,
+  identityProvider: createOidcProvider({
+    issuer: process.env.OIDC_ISSUER ?? "",
+    clientId: process.env.OIDC_CLIENT_ID ?? "",
+    clientSecret: process.env.OIDC_CLIENT_SECRET ?? "",
+    scopes: ["openid", "email", "offline_access"],
+    redirectUri: `${ORIGIN}/callback`, // register exactly this at your IdP
+  }),
+  store: createMemoryStore(), // development only, see the production checklist
+  sealer: createAesGcmSealer({
+    keys: { k1: Buffer.from(process.env.SEALING_KEY ?? "", "base64") },
+    currentKid: "k1",
+  }),
+})
+
+const app = new Hono()
+
+// OAuth routes and metadata; anything else falls through.
+app.use("*", async (c, next) => (await auth.handle(c.req.raw)) ?? next())
+
+app.all("/mcp", async (c) => {
+  const result = await auth.authenticate(c.req.raw)
+
+  if (!result.ok) return result.response // 401 with the right challenge
+
+  // result.subject, result.scopes, result.clientId, result.context
+  // await result.getUpstreamAccessToken() to call your own APIs as the person
+  return handleMcp(c.req.raw, result)
+})
+
+serve({ fetch: app.fetch, port: 3000 })
+```
+
+A sealing key is 32 random bytes:
+
+```bash
+node -e "console.log(require('node:crypto').randomBytes(32).toString('base64'))"
+```
+
+## Guides
+
+### Node `http` and Express
+
+Two small conversions, Node built-ins only. Build URLs from your configured
+public origin, never from the incoming `Host` header.
+
+```ts
+import type { IncomingMessage, ServerResponse } from "node:http"
+import { Readable } from "node:stream"
+
+const PUBLIC_ORIGIN = "https://mcp.example.com"
+
+export function toWebRequest(req: IncomingMessage): Request {
+  const headers = new Headers()
+
+  for (const [name, value] of Object.entries(req.headers)) {
+    if (Array.isArray(value)) for (const v of value) headers.append(name, v)
+    else if (value !== undefined) headers.set(name, value)
+  }
+
+  const hasBody = req.method !== "GET" && req.method !== "HEAD"
+
+  return new Request(new URL(req.url ?? "/", PUBLIC_ORIGIN), {
+    method: req.method,
+    headers,
+    body: hasBody ? Readable.toWeb(req) : null,
+    // @ts-expect-error Node needs this for a streamed request body
+    duplex: hasBody ? "half" : undefined,
+  })
+}
+
+export async function sendWebResponse(
+  res: ServerResponse,
+  response: Response,
+): Promise<void> {
+  res.statusCode = response.status
+  response.headers.forEach((value, name) => {
+    if (name !== "set-cookie") res.setHeader(name, value)
+  })
+
+  const cookies = response.headers.getSetCookie()
+
+  if (cookies.length > 0) res.setHeader("set-cookie", cookies)
+
+  res.end(Buffer.from(await response.arrayBuffer()))
+}
+```
+
+Express (mount before any body parser, so the body stream is untouched):
+
+```ts
+import express from "express"
+
+const app = express()
+
+app.use(async (req, res, next) => {
+  try {
+    const response = await auth.handle(toWebRequest(req))
+
+    if (response) await sendWebResponse(res, response)
+    else next()
+  } catch (error) {
+    next(error)
+  }
+})
+
+app.all("/mcp", async (req, res, next) => {
+  try {
+    const request = toWebRequest(req)
+    const result = await auth.authenticate(request)
+
+    if (!result.ok) return await sendWebResponse(res, result.response)
+
+    await sendWebResponse(res, await handleMcp(request, result))
+  } catch (error) {
+    next(error)
+  }
+})
+
+app.listen(3000)
+```
+
+Plain Node `http` works the same way: call `auth.handle`, then
+`auth.authenticate` on your MCP path.
+
+### Extending safely
+
+Every extension point can **tighten**, **enrich** or **observe**. None can
+switch off PKCE, exact redirect matching, consent, the browser binding and
+form token, single-use codes, refresh replay detection, audience binding,
+opaque tokens, or the escaping and Content-Security-Policy on pages.
+
+```ts
+const auth = createMcpAuth({
+  // ...issuer, resource, identityProvider, store, sealer
+  scopes: ["mcp:read", "mcp:write"],
+  scopeDescriptions: {
+    "mcp:read": "Read your documents",
+    "mcp:write": "Create and edit documents",
+  },
+  clients: [
+    {
+      clientId: "team-desktop",
+      clientName: "Team Desktop",
+      redirectUris: ["http://127.0.0.1/callback"],
+      grantTypes: ["authorization_code", "refresh_token"],
+    },
+  ],
+  authorizeClient: ({ client, scopes }) =>
+    client.kind !== "dynamic" || !scopes.includes("mcp:write"),
+  allowSubject: ({ claims }) => claims.email_verified === true,
+  mapSubject: ({ subject, claims }) => ({
+    subject,
+    displayName: typeof claims.email === "string" ? claims.email : undefined,
+  }),
+  getGrantContext: async ({ subject }) => ({ tenant: await tenantOf(subject) }),
+})
+```
+
+**Policy hooks** run only after every protocol check has passed. Only a
+literal `true` (or `{ allow: true }`) continues; `false`, any other value, a
+rejection or a throw refuses. A refusal may name a reason,
+`{ allow: false, reason: "no_seat" }` (1–64 characters of
+`A-Z a-z 0-9 _ . : -`), which reaches your error page as `policyReason`.
+Every hook receives deeply frozen copies of the data it inspects (the
+client, scopes, metadata, claims and grant), so it can read validated state
+but cannot change what the server goes on to use.
+
+| Hook                     | Called                                 | On refusal                                                                                            |
+| ------------------------ | -------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `authorizeClient`        | `/authorize`, after full validation    | 403 page (`reason: "access_denied"`)                                                                  |
+| `allowRegistration`      | `/register`, after the metadata checks | `403 invalid_client_metadata`, nothing stored                                                         |
+| `allowSubject`           | after sign-in and `mapSubject`         | 403 page, upstream refresh token revoked                                                              |
+| `allowClientMetadataUrl` | before a metadata document is fetched  | the client is unknown, nothing is fetched                                                             |
+| `beforeGrant`            | after approval, before the grant       | `access_denied` to the client, upstream revoked                                                       |
+| `beforeTokenIssue`       | before a code or refresh token is used | `invalid_grant`; a throw is `503 temporarily_unavailable`, and the code or refresh token stays usable |
+
+**Enrichment hooks**
+
+- `mapSubject({ subject, displayName, claims })` returns
+  `{ subject, displayName? }`, for example to key grants on your own user
+  id. Each returned field is read once. The subject (mapped or not) must be
+  a non-empty string of at most 512 characters, without surrounding
+  whitespace, in Unicode NFC form and free of invisible or formatting
+  characters; otherwise sign-in stops and the upstream token is revoked. A
+  display name with such characters, or longer than
+  `limits.clientNameLength`, is dropped.
+- `getGrantContext(grant)` returns JSON data exposed as
+  `AuthResult.context` (a tenant id, a plan), within
+  `limits.grantContextBytes`. It cannot change the subject, scopes or
+  audience, and tokens never carry it. If it throws, or returns data that is
+  too large or not serializable, `authenticate` returns `{ ok: false }` with a
+  generic 500 response and emits `grant_context_failed`; the hook's error
+  text is never returned or reported.
+
+**Consent extensions**
+
+Your consent page can ask for more than yes or no (a workspace, a plan),
+and the answer can travel with the grant.
+
+```ts
+const auth = createMcpAuth({
+  // ...
+  // Data for your consent page, as `details` in ConsentPageContext.
+  getConsentDetails: async ({ subject }) => ({
+    workspaces: await workspacesOf(subject),
+  }),
+  // Your page's extra fields, read only after the form token and the
+  // browser cookie were verified.
+  readConsentFields: ({ form, details }) =>
+    form.workspace === undefined
+      ? { ok: false, fieldErrors: { workspace: "Choose a workspace" } }
+      : { ok: true, grantData: { workspace: form.workspace } },
+  beforeGrant: async ({ subject }) =>
+    (await hasSeat(subject)) ? true : { allow: false, reason: "no_seat" },
+  afterGrant: ({ grant }) => recordConnection(grant.grantId, grant.subject),
+  getGrantContext: ({ data }) => ({ workspace: data }),
+})
+```
+
+- `getConsentDetails` runs at the callback; its JSON result
+  (`limits.consentDetailsBytes`) reaches the page and `readConsentFields`.
+  A throw ends the sign-in with an error page and revokes the upstream
+  token.
+- `readConsentFields` never sees the package's own fields. `fieldErrors`
+  shows the page again (status 400, with `fieldErrors` and `submitted`)
+  and uses nothing up; `grantData` (`limits.grantDataBytes`) is stored as
+  `GrantRecord.data`, passed to `getGrantContext`, and can be replaced
+  later with `auth.updateGrantData(grantId, data)`. A throw or an unusable
+  result ends the flow with a 500 page and revokes the upstream token.
+- `afterGrant` is awaited before the client is answered. If it throws, the
+  grant is deleted, the upstream token revoked and the client receives
+  `error=server_error`.
+- `scriptHashes: ["sha256-…"]` lets a custom consent page run those inline
+  scripts (`script-src`); only `sha256-` hashes are accepted.
+- A consent submission repeated from the same browser within
+  `consentReplaySeconds` (default 10, at most 60) receives the same
+  redirect again, when the store implements the optional
+  `putConsentOutcome` / `getConsentOutcome`; otherwise a repeat sees an
+  error page. The remembered redirect is stored encrypted.
+
+**Pages**
+
+`renderConsentPage` and `renderErrorPage` receive deeply frozen contexts
+with `locales` (from `Accept-Language`, most preferred first). Error pages
+carry a stable `reason` code (`client_unknown`, `invalid_scope`,
+`subject_not_permitted`, …) to switch on for your own wording, plus
+`policyReason` when a hook gave one.
+
+**Upstream tokens and connections**
+
+- `IdentityProvider.refresh(refreshToken, { grantId, subject })` tells a
+  custom provider which grant a renewal is for.
+- `result.getUpstreamAccessToken({ forceRefresh: true })` and
+  `auth.renewUpstream(grantId)` discard the cached upstream access token
+  (in memory and on the grant) and renew it, for example after the
+  provider answered 401. Concurrent renewals of one grant share one call.
+- `auth.revokeGrantsForSubject(subject)` ends every grant of one person
+  (for an account closure) when the store implements the optional
+  `listGrantsBySubject`; without it, it throws `McpAuthConfigError`.
+- The `grant_revoked` event carries a frozen copy of the grant (never its
+  encrypted upstream tokens) and is emitted before the grant is deleted.
+
+**Checked configuration**
+
+- `clients`: pre-registered public clients, held to the same rules as
+  registration. An `https` client id is refused (that form means a metadata
+  document).
+- `scopeDescriptions`: consent-screen text per supported scope, escaped.
+
+There is deliberately no hook to replace the random source or to add claims
+to tokens: either would let configuration weaken token secrecy.
+
+### Implementing a store
+
+You implement `OAuthStore` on your own database. It only ever receives
+SHA-256 hashes of tokens and codes, and upstream tokens already encrypted.
+
+Four operations decide races and **must be atomic across every process that
+shares the store**: a conditional write, a transaction, a compare-and-set,
+or a delete that returns the row, never a read followed by a write.
+
+| Operation                         | Contract                                                             | Why                                            |
+| --------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------- |
+| `consumePendingAuthorization(id)` | One caller receives the record, which is deleted.                    | A sign-in completes once.                      |
+| `consumeConsentRequest(id)`       | The same; should still return a held record that has expired.        | One approval creates one grant.                |
+| `consumeAuthorizationCode(hash)`  | Exactly one caller sees `firstUse: true`; later callers see `false`. | Codes are single-use and a repeat is detected. |
+| `useRefreshToken(hash, now)`      | Sets `usedAt` if unset; exactly one caller sees no `previousUsedAt`. | Refresh replay detection cannot be raced.      |
+
+Expired records read as absent and may be deleted at any time, for example
+by a database TTL (`getConsentRequest` may also return an expired one).
+`deleteGrant` must make `getGrant` return nothing, and should resolve with
+the deleted record so the last stored upstream token is the one revoked.
+`getAuthorizationCode` reads a code, consumed or not, without using it up:
+the token endpoint checks the client, redirect URI, resource and PKCE
+verifier against it first.
+
+Three methods are optional: `putConsentOutcome` / `getConsentOutcome`
+(answering a repeated consent submission) and `listGrantsBySubject`
+(`revokeGrantsForSubject`).
+
+Good fits: PostgreSQL or MySQL (`UPDATE … WHERE used_at IS NULL`,
+`DELETE … RETURNING`), Redis (`GETDEL`, Lua), MongoDB (`findOneAndUpdate`),
+DynamoDB (conditional writes) and Cloudflare D1.
+
+**Client lifetime.** Anyone can call `/register`, so a store should never
+evict a client that holds a live grant, should delete a dynamic client
+without one after an idle period (28 days in the memory store), and should
+evict the least recently used grant-less dynamic client first when full.
+
+### Production checklist
+
+- [ ] **A persistent, shared store** that honours the atomicity contract.
+- [ ] **Managed keys.** Sealing keys come from a secret manager, KMS or HSM.
+      Rotate by adding a key id, making it `currentKid`, and keeping the old
+      key until no grant sealed with it remains (`lifetimes.grant`).
+- [ ] **HTTPS** for the issuer and resource.
+- [ ] **Rate limiting** through `rateLimit` and `getClientIp` (or
+      `trustProxy` behind exactly one proxy you control). **Without
+      `getClientIp` or `trustProxy`, every request shares the single key
+      `"unknown"`**, so one busy client can exhaust the limit for everyone.
+      Without `rateLimit`, `POST /register` is open to flooding. A starting
+      point: 10 registrations per address per hour, 30 authorization starts
+      per address per minute.
+- [ ] **Alerts** from `onEvent` on `refresh_token_replayed`,
+      `authorization_code_replayed`, and bursts of `flow_binding_mismatch` or
+      `client_metadata_refused`.
+- [ ] **Identity provider**: register `<issuer origin><callback path>` as the
+      only redirect URI of a confidential client, request a refresh token
+      (often `offline_access`), and enable refresh rotation if offered.
+- [ ] **Connection management**: let people see and remove their
+      connections, and call `revokeGrant` when they do or when an account
+      closes.
+
+## API
+
+### `createMcpAuth(options)`
+
+| Member                            | Purpose                                                                                                                                      |
+| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `handle(request)`                 | Serves the OAuth routes and metadata. Resolves `undefined` for any other path.                                                               |
+| `authenticate(request)`           | Checks the bearer token. `{ ok: true, subject, grantId, clientId, scopes, context, getUpstreamAccessToken() }` or `{ ok: false, response }`. |
+| `unauthorized(request, error?)`   | A ready 401 challenge (403 for `insufficient_scope`), e.g. when a tool needs a scope the token lacks.                                        |
+| `revokeGrant(grantId)`            | Ends a grant: its tokens stop working and the upstream refresh token is revoked when possible.                                               |
+| `revokeGrantsForSubject(subject)` | Ends every grant of one person; needs the store's `listGrantsBySubject`. Resolves the count.                                                 |
+| `renewUpstream(grantId)`          | Discards the cached upstream access token and renews it at the identity provider.                                                            |
+| `updateGrantData(grantId, data)`  | Replaces `GrantRecord.data` (JSON, within `limits.grantDataBytes`). Resolves `false` for an unknown grant.                                   |
+
+### Options
+
+| Option                                  | Default                                                                 | Meaning                                                                                                                                                 |
+| --------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `issuer`                                | required                                                                | HTTPS URL; endpoints live under its path.                                                                                                               |
+| `resource`                              | required                                                                | Canonical URL of your MCP endpoint, the audience of every token.                                                                                        |
+| `identityProvider`                      | required                                                                | `createOidcProvider(…)` or your own `IdentityProvider`.                                                                                                 |
+| `store`                                 | required                                                                | Your `OAuthStore`.                                                                                                                                      |
+| `sealer`                                | required                                                                | `createAesGcmSealer(…)` or your own `SecretSealer`.                                                                                                     |
+| `scopes` / `defaultScopes`              | `["mcp"]` / all                                                         | Scopes offered, and those granted when none are asked for.                                                                                              |
+| `scopeDescriptions`                     | none                                                                    | Consent-screen text per scope.                                                                                                                          |
+| `resourceName`                          | none                                                                    | RFC 9728 `resource_name`.                                                                                                                               |
+| `clients`                               | none                                                                    | Pre-registered public clients.                                                                                                                          |
+| `dynamicClientRegistration`             | `true`                                                                  | Serve `POST /register`. Deprecated by MCP 2026-07-28 in favour of metadata documents; `dynamicClientRegistration: false` turns it off.                  |
+| `clientIdMetadataDocuments`             | `true`                                                                  | Accept HTTPS URL client ids.                                                                                                                            |
+| `fetchClientMetadata(url, { signal })`  | SSRF-safe fetcher                                                       | Replace how metadata documents are downloaded. Must stay SSRF-safe.                                                                                     |
+| `lifetimes`                             | see below                                                               | Token and flow lifetimes, in seconds.                                                                                                                   |
+| `limits`                                | see below                                                               | Sizes and counts.                                                                                                                                       |
+| `refreshReuseGraceSeconds`              | `10`                                                                    | Retry window (0–300) for a just-used refresh token. `0` treats any reuse as replay.                                                                     |
+| `consentReplaySeconds`                  | `10`                                                                    | Window (0–60) in which a repeated consent submission from the same browser gets the same redirect.                                                      |
+| `scriptHashes`                          | none                                                                    | `sha256-…` hashes of inline scripts a custom consent page may run.                                                                                      |
+| `paths`                                 | `/authorize`, `/callback`, `/consent`, `/token`, `/register`, `/revoke` | Route paths under the issuer path: one leading `/`, no `//`, `\`, dot segments or whitespace, distinct, and never a metadata path or the resource path. |
+| `cookiePrefix`                          | `__Host-mcp-auth-`                                                      | Must start with `__Host-`.                                                                                                                              |
+| `rateLimit(key, scope)`                 | none                                                                    | Resolve `true` to continue; anything else (including a throw) answers 429.                                                                              |
+| `getClientIp(request)` / `trustProxy`   | none / `false`                                                          | Rate-limit key. `trustProxy` uses the right-most `X-Forwarded-For` entry.                                                                               |
+| `renderConsentPage` / `renderErrorPage` | built in                                                                | Your own pages; see `ConsentPageContext`.                                                                                                               |
+| `onEvent(event)`                        | none                                                                    | Typed audit events; never contain secrets.                                                                                                              |
+| policy and enrichment hooks             | none                                                                    | See [Extending safely](#extending-safely).                                                                                                              |
+| `allowInsecureLocalhost`                | `false`                                                                 | Allow an `http://localhost` issuer and resource in development.                                                                                         |
+| `now`                                   | `Date.now`                                                              | Clock, for tests. A non-finite value fails the request instead of disabling expiry checks.                                                              |
+
+<details>
+<summary><strong><code>lifetimes</code></strong> (seconds)</summary>
+
+| Key                     | Default                                                                      | Allowed      |
+| ----------------------- | ---------------------------------------------------------------------------- | ------------ |
+| `accessToken`           | 1,800 (30 minutes)                                                           | 1–86,400     |
+| `refreshToken`          | 1,209,600 (14 days, renewed on every rotation)                               | 1–34,560,000 |
+| `grant`                 | 7,776,000 (90 days, absolute; then consent again)                            | 1–34,560,000 |
+| `authorizationCode`     | 60                                                                           | 1–600        |
+| `pendingAuthorization`  | 900 (sign-in plus consent)                                                   | 1–3,600      |
+| `clientMetadataCache`   | 1,800 (`0` disables the cache); a document's own `Cache-Control` shortens it | 0–86,400     |
+| `clientMetadataFailure` | 60 (back-off for a failed metadata URL; `0` disables)                        | 0–3,600      |
+
+</details>
+
+<details>
+<summary><strong><code>limits</code></strong></summary>
+
+| Key                       | Default                                       |
+| ------------------------- | --------------------------------------------- |
+| `clientNameLength`        | 128 characters                                |
+| `redirectUris`            | 8 per client                                  |
+| `redirectUriLength`       | 2,048 characters                              |
+| `stateLength`             | 2,048 characters                              |
+| `scopeLength`             | 1,024 characters                              |
+| `registrationBytes`       | 16 KiB                                        |
+| `formBytes`               | 32 KiB (token, revocation and consent bodies) |
+| `clientMetadataBytes`     | 5 KiB (CIMD draft-03 § 10.11)                 |
+| `clientMetadataTimeoutMs` | 4,000                                         |
+| `clientMetadataFailures`  | 10,000 failed URLs remembered                 |
+| `grantContextBytes`       | 4,096 (serialized `getGrantContext` result)   |
+| `consentDetailsBytes`     | 8,192 (serialized `getConsentDetails` result) |
+| `grantDataBytes`          | 4,096 (serialized grant data)                 |
+
+</details>
+
+### Routes
+
+| Route                                                         | Purpose                                                    |
+| ------------------------------------------------------------- | ---------------------------------------------------------- |
+| `GET /.well-known/oauth-protected-resource[/<resource path>]` | RFC 9728 metadata.                                         |
+| `GET /.well-known/oauth-authorization-server[/<issuer path>]` | RFC 8414 metadata.                                         |
+| `POST /register`                                              | RFC 7591 registration of public clients.                   |
+| `GET /authorize`                                              | Starts a flow and redirects to the identity provider.      |
+| `GET /callback`                                               | Back from the identity provider; shows the consent screen. |
+| `POST /consent`                                               | The person's answer.                                       |
+| `POST /token`                                                 | `authorization_code` and `refresh_token` grants.           |
+| `POST /revoke`                                                | RFC 7009 revocation.                                       |
+
+### Building blocks
+
+| Export                        | What it does                                                                                                                                                                          |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `createOidcProvider(options)` | Any OIDC provider: discovery, code flow with PKCE and nonce, ID token verification against the provider's keys (asymmetric algorithms only), RFC 9207 checks, renewal and revocation. |
+| `createAesGcmSealer(options)` | AES-256-GCM with a random IV per value, the grant id as authenticated data, and key ids for rotation.                                                                                 |
+| `createMemoryStore(options?)` | A correct **single-process, non-persistent** store for development and tests.                                                                                                         |
+| `escapeHtml(text)`            | The escaping the built-in pages use, for your own page renderers.                                                                                                                     |
+
+### Errors
+
+These classes reach your own code, for example from
+`getUpstreamAccessToken()`; requests to the OAuth routes are answered with
+OAuth errors or error pages instead. No error message contains a token.
+
+| Class                   | Thrown when                                                                                                                                          |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `McpAuthConfigError`    | `createMcpAuth` options are invalid, or `revokeGrantsForSubject` is called on a store without `listGrantsBySubject`.                                 |
+| `GrantInactiveError`    | `getUpstreamAccessToken()` or `renewUpstream()` runs for a grant that was revoked or has expired.                                                    |
+| `UpstreamTokenError`    | No upstream access token could be obtained for a live grant.                                                                                         |
+| `IdentityProviderError` | A call to the identity provider failed (discovery, code exchange, ID token checks, renewal). `code` is the provider's OAuth error, when it sent one. |
+| `SealerError`           | A sealed value is malformed, was altered, belongs to another owner, or uses a key id that is not configured.                                         |
+
+### Registered metadata is enforced
+
+- **`grant_types`**: a client that omits it gets `authorization_code` only
+  (RFC 7591 § 2) and **no refresh token**. Clients that want refresh tokens
+  register `["authorization_code", "refresh_token"]`. Metadata documents
+  are treated the same way.
+- **`scope`**: a client that registers a scope can only request scopes
+  within it. Unknown scopes are refused at registration and ignored in a
+  metadata document.
+
+### Client ID Metadata Documents
+
+Downloaded with [`@gydr-ai/safe-fetch`](https://github.com/gydr-ai/safe-fetch)
+by default: private and metadata addresses refused, the connection pinned
+against DNS rebinding, no redirects. Whatever fetcher you plug in, the core
+still enforces the deadline, the size cap, a `200` status and the document
+checks (`client_id` equal to the URL, public client, usable redirect URIs).
+A document listing `token_endpoint_auth_methods_supported` without `none`
+is a confidential client and refused, and so is a client id equal to the
+issuer. A document's `Cache-Control` (`max-age`, `no-store`, `no-cache`)
+is honoured, never beyond `lifetimes.clientMetadataCache`. Failed URLs back
+off, and concurrent requests for one URL share a download.
+
+## Security model
+
+**What it guarantees**
+
+- Authorization code flow, PKCE `S256` and public clients only. Client
+  credentials at the token endpoint are refused: with a 401 and a
+  `WWW-Authenticate` challenge in the client's scheme when sent in the
+  `Authorization` header, otherwise `400 invalid_client` (RFC 6749 § 5.2).
+- Redirect URIs are `https`, or `http` to a loopback host where only the
+  port may vary (RFC 8252 § 7.3); otherwise compared exactly, and may not
+  already carry `code`, `state`, `iss` or an error parameter. Every problem
+  at `/authorize` is shown as a page, never sent as a redirect, because the
+  person has not signed in yet (RFC 9700 § 4.11.2). A repeated defined
+  parameter is refused; unknown parameters are ignored.
+- The browser that starts a flow must finish it: a per-flow `__Host-`
+  cookie is compared with its stored hash before anything is consumed.
+- The consent form carries a one-time token compared in constant time. A
+  flow that ends without a grant revokes the upstream refresh token it
+  obtained.
+- Pages send a strict Content-Security-Policy, `X-Frame-Options: DENY`,
+  `Cache-Control: no-store` and `Referrer-Policy: no-referrer`, and escape
+  every value. Client names with invisible or formatting characters are
+  refused.
+- Tokens are 256-bit random values, stored only as SHA-256 hashes, bound to
+  your resource and checked against a live grant on every request. Refresh
+  tokens rotate on every use; a replay ends the grant, and so does a fully
+  valid repeat of an authorization code. A code presented with the wrong
+  client, redirect URI, resource or verifier is refused without being used
+  up and without ending anything, so whoever holds a stolen code can
+  neither spend it nor end the person's session by guessing verifiers
+  (256 bits, under your rate limit).
+- Upstream tokens are encrypted with the grant id as authenticated data and
+  never reach MCP clients or `onEvent`.
+
+**What it does not do**
+
+- Authorize individual MCP tools. Check `result.scopes` and your own
+  permissions, and answer with
+  `auth.unauthorized(request, { error: "insufficient_scope", scope })`.
+- Act as an identity provider: no passwords, MFA or account management.
+- Confidential MCP clients, implicit or password grants, JWT access tokens,
+  introspection, PAR, DPoP or mTLS.
+- Coordinate across processes beyond your store. If your identity provider
+  rotates refresh tokens with no grace period and several processes may
+  renew one grant at once, route a grant's renewals to one process.
+- Catch a refresh token copied and used within `refreshReuseGraceSeconds`
+  of the real use. Use `0` if your clients never retry.
+- Protect against a compromised browser, a client the person chose to
+  approve, or a compromised identity provider.
+
+## Specification compliance
+
+| Specification                                | Status                                                                                                                                       |
+| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| MCP Authorization (2026-07-28)               | Supported, including Client ID Metadata Documents and per-authorization consent; deprecated DCR on by default.                               |
+| OAuth 2.1 (draft-17)                         | PKCE required, exact redirect matching, refresh rotation, single-use codes, optional `redirect_uri` at `/token`, 303 after the consent form. |
+| RFC 6749 OAuth 2.0                           | Code and refresh grants; errors per § 4.1.2.1 and § 5.2.                                                                                     |
+| RFC 6750 Bearer Token Usage                  | Authorization header only; challenges per § 3 (bare when no Bearer credentials).                                                             |
+| RFC 7009 Token Revocation                    | Supported; unknown tokens answer 200.                                                                                                        |
+| RFC 7591 Dynamic Client Registration         | Public clients; `grant_types` and `scope` enforced. RFC 7592 not supported.                                                                  |
+| RFC 7636 PKCE                                | S256 only.                                                                                                                                   |
+| RFC 8252 Native Apps                         | Loopback redirects with any port; custom schemes not accepted.                                                                               |
+| RFC 8414 Authorization Server Metadata       | Supported, including path-suffixed well-known URLs.                                                                                          |
+| RFC 8707 Resource Indicators                 | Required at `/authorize`, checked at `/token` (scheme and host case-insensitive), enforced as the audience.                                  |
+| RFC 9207 Issuer Identification               | `iss` on every authorization response; checked toward the identity provider.                                                                 |
+| RFC 9700 OAuth Security BCP                  | Refresh replay detection, no redirect before sign-in, CSRF and login-CSRF protection.                                                        |
+| RFC 9728 Protected Resource Metadata         | Supported, with `resource_metadata` challenges (§ 5.1).                                                                                      |
+| OAuth Client ID Metadata Document (draft-03) | Public clients; plural auth methods, `Cache-Control`, 5 KiB cap, issuer-equal ids refused.                                                   |
+| OpenID Connect Core and Discovery            | Used toward the identity provider.                                                                                                           |
+
+## Compatibility
+
+| Area               | Supported                                                                                 |
+| ------------------ | ----------------------------------------------------------------------------------------- |
+| Runtime            | Node.js 26, 24 LTS and 22 LTS (22.12 or later), tested in CI                              |
+| Frameworks         | Anything that passes a Web `Request` and returns a `Response`                             |
+| Identity providers | Any OpenID Connect provider with discovery; anything else via a custom `IdentityProvider` |
+| Stores             | Any database with an atomic conditional write                                             |
+| Key management     | The bundled AES-256-GCM sealer, or a custom `SecretSealer` over any KMS or HSM            |
+
+## Security
+
+Report vulnerabilities privately, as described in [SECURITY.md](SECURITY.md).
+Please do not open a public issue for a vulnerability.
+
+Every release is built and published by GitHub Actions with
+[npm provenance](https://docs.npmjs.com/generating-provenance-statements),
+and a maintainer approves each one with a hardware security key. Verify what
+you installed with:
+
+```bash
+npm audit signatures
+```
+
+## Contributing
+
+Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md)
+for the development setup and the checks a change must pass.
+
+## About Gydr
+
+`@gydr-ai/mcp-oauth` is built and maintained by [Gydr](https://gydr.ai), an
+AI chatbot platform that answers customers on websites, WhatsApp, Messenger,
+Instagram and Telegram. Businesses on Gydr manage their chatbots from Claude,
+Codex and other MCP clients, and this package grew out of the authorization
+server that makes those connections safe. See also
+[`@gydr-ai/safe-fetch`](https://github.com/gydr-ai/safe-fetch), SSRF-safe
+`fetch` for Node.js.
+
+## License
+
+[Apache-2.0](LICENSE) © [Gydr.ai](https://gydr.ai)
+
+<p align="center">
+  <a href="https://gydr.ai"><img alt="Gydr" src="https://img.shields.io/badge/made_by-Gydr-0f172a?style=for-the-badge" /></a>
+</p>