@ninomae/mcp-app-server 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-15
+
+Initial release. Extracted from the Career Note monorepo (where it was briefly named `agent-gateway`) and generalised.
+
+### Added
+- `createMcpAppServer`: OAuth 2.1 authorization server (RFC 6749 / 7591 / 7636 / 8414 / 8707 / 9728) and MCP Streamable HTTP resource server in one `fetch` handler.
+- Identity providers: `sessionIdentity`, `jwtIdentity`, `firebaseIdentity`, `fixedIdentity`.
+- Scoped tool table with grant-trimmed `tools/list`, anonymous discovery and a public `/mcp/schema` document. `scopes` is optional: without a catalogue one implicit required scope is used and consent is a plain allow/deny.
+- Opaque access tokens (`agt_`) and rotating refresh tokens (`agr_`), hashed at rest, audience-bound; replaying a code or a rotated refresh token revokes the chain.
+- `authenticate` / `carriesToken` for accepting agent tokens on host routes; `listGrants` / `revokeGrant` for user-facing management.
+- Storage contract `AppServerStore`: the core depends on no database. `memoryStore()` (reference, Maps) ships in the root; `sqlStore(db, tables?)` for Cloudflare D1 and SQLite drivers ships at `@ninomae/mcp-app-server/sql`.
+- Rate-limit contract `RateLimiter` for dynamic client registration (`registrationLimit`); `memoryRateLimiter()` is the default, `false` disables.
+- `serverJson` helper for the official MCP Registry.
+- `@ninomae/mcp-app-server/react`: headless `useAgentConsent` hook.
+- Tests: Miniflare + D1 end-to-end, replay/revocation rules on `memoryStore`, `sqlStore` on plain Node `node:sqlite`.
+
+[Unreleased]: https://github.com/erzhiqianyi/mcp-app-server/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/erzhiqianyi/mcp-app-server/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 erzhiqianyi and contributors
+
+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,262 @@
+# @ninomae/mcp-app-server
+
+**Turn your existing app into an OAuth 2.1-protected MCP server.**
+
+[![npm](https://img.shields.io/npm/v/@ninomae/mcp-app-server)](https://www.npmjs.com/package/@ninomae/mcp-app-server)
+[![CI](https://github.com/erzhiqianyi/mcp-app-server/actions/workflows/ci.yml/badge.svg)](https://github.com/erzhiqianyi/mcp-app-server/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/@ninomae/mcp-app-server)](./LICENSE)
+
+Expose **your existing app's users and data** to external AI agents (Claude, ChatGPT, Cursor, Claude Code, any MCP client) over standard **MCP + OAuth 2.1**. You do not integrate a model; users bring their own agent, read their data, work on it there, and write results back through tools you define.
+
+[中文文档](./README.zh-CN.md) · [Integration guide](./docs/integration.md) · [Publishing](./docs/publishing.md) · [Changelog](./CHANGELOG.md)
+
+- **Bring your own identity.** Your app already has a login (Firebase, Supabase, Auth0, Clerk, a session cookie, home-grown). You implement one function: `resolve(request) → { id }`.
+- **It is the OAuth authorization server.** MCP clients require dynamic client registration (RFC 7591), PKCE, resource indicators (RFC 8707), refresh-token rotation and per-agent revocation. Consumer identity providers rarely offer these, so this layer has to live in your app.
+- **A scoped tool table is your product's agent surface.** Each tool declares the scope it needs; `tools/list` is trimmed to what the user actually granted.
+- **Publicly discoverable.** `/.well-known/*`, `GET <basePath>/mcp/schema`, and anonymous `initialize` / `tools/list` need no token, so the server can be submitted to the official MCP Registry or a connector directory.
+- **Storage-agnostic.** The core depends on no database. Implement the small `AppServerStore` interface over whatever you run (SQL, KV, Redis, Mongo, an ORM), or use the bundled `memoryStore()` / `sqlStore()` (Cloudflare D1, any SQLite driver).
+
+## Install
+
+```bash
+npm install @ninomae/mcp-app-server @modelcontextprotocol/sdk zod
+```
+
+Optional peers: `jose` (for `jwtIdentity` / `firebaseIdentity`) and `react` (for the `/react` consent hook). Node ≥ 22 or any Web-standard runtime (Cloudflare Workers, Deno, Bun).
+
+## Quick start
+
+```ts
+import { z } from 'zod';
+import { createMcpAppServer, sessionIdentity } from '@ninomae/mcp-app-server';
+import { sqlStore } from '@ninomae/mcp-app-server/sql';
+
+const mcp = createMcpAppServer({
+  name: 'notes',
+  basePath: '/api/notes',                 // → /api/notes/mcp, /api/notes/mcp/schema, /api/notes/oauth/*
+  consentPath: '/oauth/authorize',        // a page in your front end (see examples/consent-page.tsx)
+  scopes: {
+    'notes:read':  { description: 'Read your notes', required: true },
+    'notes:write': { description: 'Attach AI summaries to notes', default: true },
+  },
+  identity: sessionIdentity(async (req) => await sessions.userFromCookie(req)), // { id } or null
+  storage: sqlStore(env.NOTES_DB),        // or memoryStore(), or your own AppServerStore
+  origins: { publicOrigin: 'https://notes.example.com', webOrigin: 'https://notes.example.com' },
+  tools: [
+    {
+      name: 'notes_list',
+      scope: 'notes:read',
+      description: 'List the signed-in user’s notes.',
+      inputSchema: {},
+      annotations: { readOnlyHint: true, openWorldHint: false },
+      handler: async (_args, ctx) => ({ content: [{ type: 'text', text: JSON.stringify(await listNotes(ctx.ownerId)) }] }),
+    },
+    {
+      name: 'notes_summarize',
+      scope: 'notes:write',
+      description: 'Store an agent-written summary for one note.',
+      inputSchema: { id: z.string(), summary: z.string().max(500) },
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+      handler: async ({ id, summary }, ctx) => { /* UPDATE … WHERE owner = ctx.ownerId */ },
+    },
+  ],
+});
+
+export default {
+  async fetch(request: Request, env: Env) {
+    await mcp.ensureSchema();                  // idempotent; delegates to the store
+    return (await mcp.fetch(request)) ?? app.fetch(request, env);
+  },
+};
+```
+
+Then connect an agent:
+
+```bash
+claude mcp add --transport http notes https://notes.example.com/api/notes/mcp
+```
+
+Claude Code opens the browser, your consent page shows the requested scopes, the user approves, and the agent receives a token bound to that user. A full runnable host lives in [`examples/cloudflare-worker`](./examples/cloudflare-worker); the same 60 lines back the end-to-end test in [`tests`](./tests).
+
+## How it works
+
+```
+MCP client ──► GET /.well-known/oauth-protected-resource      (RFC 9728)
+           ──► GET /.well-known/oauth-authorization-server    (RFC 8414)
+           ──► POST <base>/oauth/register                     (RFC 7591, no token)
+           ──► GET  <base>/oauth/authorize?…  ─302─► <webOrigin><consentPath>?…
+                                                          │ your login + useAgentConsent()
+                                                          ▼
+           ◄─302 code ◄── POST <base>/oauth/approve       (host identity, never an agent token)
+           ──► POST <base>/oauth/token  (PKCE)            → access_token agt_…, refresh_token agr_…
+           ──► POST <base>/mcp  Authorization: Bearer agt_… → tools/list (scoped) / tools/call
+```
+
+Every access token is bound to `ownerId` + `clientId` + granted scopes + the audience `publicOrigin + mcpPath`. Tool handlers receive that verified context as `ctx`; nothing in `ctx` ever comes from tool input.
+
+## Configuration
+
+| Option | Required | Meaning |
+| --- | --- | --- |
+| `name` | yes | MCP server name; also used in `server.json`. |
+| `basePath` | yes | Where all gateway routes hang: `<basePath>/mcp`, `<basePath>/mcp/schema`, `<basePath>/oauth/*`. |
+| `scopes` | no | Ordered scope catalogue. `required` scopes are always granted; `default` ones are pre-checked on the consent page. Omit it if your app has no scope model: one implicit required scope is used and consent is a plain allow/deny. |
+| `identity` | yes | `IdentityProvider` — see [Identity](#identity). |
+| `tools` | yes | `AgentTool[]` — see [Tools](#tools). |
+| `storage` | yes | `AppServerStore` — see [Storage](#storage). |
+| `origins` | yes | `{ publicOrigin, webOrigin }` or a function of the request. `publicOrigin` is written into metadata and token audience; `webOrigin` hosts the consent page. |
+| `consentPath` | no | Default `/oauth/authorize`. |
+| `accessTokenDays` / `refreshTokenDays` | no | Default 30 / 90. |
+| `tokenPrefix` | no | Default `agt_`. Lets your own routes recognise agent tokens. |
+| `registrationLimit` | no | `{ limiter, key? }` for `POST /oauth/register`, or `false`. Default `memoryRateLimiter()` — see [Rate limiting](#rate-limiting). |
+| `onEvent` | no | Audit hook: `authorized` / `refreshed` / `revoked` / `tool`. Never receives tool payloads. |
+| `anonymousDiscovery` | no | Default `true`. Let `initialize` / `tools/list` answer without a token. |
+| `contract` | no | Free-text (markdown) data contract published with the schema. |
+
+### Identity
+
+The only contract between your app and the server. `id` must be stable and never reused; every token is bound to it.
+
+```ts
+import { sessionIdentity, jwtIdentity, firebaseIdentity, fixedIdentity } from '@ninomae/mcp-app-server';
+
+sessionIdentity(async (req) => await sessions.userFromCookie(req));   // server-side sessions
+jwtIdentity({ jwksUrl, issuer, audience });                             // Supabase, Auth0, Clerk, Cognito, any OIDC
+firebaseIdentity(projectId);                                            // Firebase Authentication preset
+fixedIdentity('local');                                                 // single-user / local dev only
+```
+
+Or implement `IdentityProvider` yourself: `{ resolve(request) => Promise<{ id, displayName?, email? }> }`, throwing `AppServerError(401, …)` when nobody is signed in.
+
+### Storage
+
+The server must remember registered clients, single-use authorization codes, refresh-token chains and access tokens (all secrets stored as SHA-256). It does so only through `AppServerStore`, a plain-object repository interface with four collections and two optional hooks:
+
+```ts
+interface AppServerStore {
+  clients:       { create; get; touch };
+  codes:         { create; get; consume /* atomic, first caller wins */; setIssuedToken };
+  refreshTokens: { create; get; getByAccessToken; revoke /* atomic */; revokeByAccessToken; setSuccessor };
+  accessTokens:  { create; get; getByHash; listByOwner; touch; revoke };
+  prune?(now: string): Promise<void>;     // delete expired codes / refresh tokens
+  ensureSchema?(): Promise<void>;         // idempotent setup, surfaced as mcp.ensureSchema()
+}
+```
+
+Two implementations ship with the package:
+
+```ts
+import { memoryStore } from '@ninomae/mcp-app-server';        // Maps; dev, tests, single process
+import { sqlStore } from '@ninomae/mcp-app-server/sql';       // Cloudflare D1 as-is; node:sqlite / better-sqlite3 / libsql with a 10-line wrapper
+sqlStore(env.DB, { clients: 'my_clients' })                    // optional table-name overrides
+```
+
+To back it with Postgres, Redis, KV, Mongo, Prisma, Drizzle… implement the interface (about 150 lines; [`src/store.ts`](./src/store.ts) is the reference). The two methods marked *atomic* are what the replay defences rely on: `codes.consume` and `refreshTokens.revoke` must return `true` for exactly one caller. Copy [`tests/memory-store.test.mjs`](./tests/memory-store.test.mjs), swap in your store, and the suite checks both.
+
+### Rate limiting
+
+Dynamic client registration is unauthenticated and writes to storage, so it is rate limited. Like storage, the server defines only the contract:
+
+```ts
+interface RateLimiter { allow(key: string): Promise<boolean> }   // false → 429
+registrationLimit: { limiter, key?: (request) => string }        // key defaults to the client IP
+```
+
+The default `memoryRateLimiter({ limit: 20, windowMs: 3_600_000 })` counts in process memory, which is correct on one long-lived server and **not** on Workers, Lambda or any multi-instance deployment. There, plug in the platform's shared counter — Cloudflare's rate-limiting binding is three lines:
+
+```ts
+registrationLimit: { limiter: { allow: async (key) => (await env.REGISTER_LIMIT.limit({ key })).success } },
+```
+
+`registrationLimit: false` disables it (e.g. behind your own WAF rule).
+
+### Tools
+
+```ts
+interface AgentTool {
+  name: string;
+  scope?: string;                 // omit for tools every authorised agent may use
+  description: string;
+  inputSchema: ZodRawShape;       // zod v4 shape; published as JSON Schema
+  annotations: { readOnlyHint: boolean; destructiveHint?: boolean; idempotentHint?: boolean; openWorldHint: boolean };
+  handler(args, ctx: ToolContext): Promise<{ content: { type: 'text'; text: string }[]; isError?: boolean }>;
+}
+interface ToolContext { ownerId; scopes; grantId; clientId; clientName; request }
+```
+
+If your tools are thin wrappers over an existing REST API, forward `ctx.request`'s `Authorization` header to your own handlers and let that layer accept agent tokens via `mcp.authenticate(request)`.
+
+### Gateway API
+
+```ts
+mcp.fetch(request)                    // Response | null — mount first in your router
+mcp.authenticate(request)             // AuthenticatedGrant | null — accept agent tokens on your own routes
+mcp.carriesToken(request)             // cheap prefix check
+mcp.listGrants(ownerId)               // which agents are connected, with what scopes, last used when
+mcp.revokeGrant(ownerId, grantId)     // revoke a grant and its whole refresh chain
+mcp.ensureSchema()                    // idempotent table setup
+mcp.describe(request)                 // the public schema document
+mcp.serverJson(request, 'io.github.you', 'One-line description')  // MCP Registry server.json
+mcp.paths                             // { mcp, schema, oauth, consent }
+```
+
+### Consent page (React)
+
+```tsx
+import { useAgentConsent } from '@ninomae/mcp-app-server/react';
+
+const { client, chosen, toggle, decide, error, busy, destination, missingClient } = useAgentConsent({
+  basePath: '/api/notes',
+  authHeaders: () => ({ authorization: 'Bearer ' + session.token }), // or omit and rely on cookies
+});
+```
+
+The hook is headless: render your own login and layout, map `client.scopeDetails` to checkboxes (`required` ones disabled), and call `decide('approve' | 'deny')`. See [`examples/consent-page.tsx`](./examples/consent-page.tsx). Non-React front ends can call `GET <base>/oauth/client` and `POST <base>/oauth/approve` directly.
+
+## Endpoints
+
+| Path | Auth | Purpose |
+| --- | --- | --- |
+| `GET /.well-known/oauth-protected-resource[<mcpPath>]` | none | Resource metadata (RFC 9728) |
+| `GET /.well-known/oauth-authorization-server` | none | Authorization server metadata (RFC 8414) |
+| `GET <base>/mcp/schema` | none | Server name, endpoint, scopes, JSON Schema of every tool |
+| `POST <base>/mcp` (`initialize` / `ping` / `tools/list`) | none | Anonymous discovery; full tool list |
+| `POST <base>/mcp` (anything else) | agent token | MCP Streamable HTTP |
+| `POST <base>/oauth/register` | none (rate-limited via `registrationLimit`) | Dynamic client registration |
+| `GET <base>/oauth/authorize` | none | Validate, then 302 to the consent page |
+| `GET <base>/oauth/client` | none | Client + scope descriptions for the consent page |
+| `POST <base>/oauth/approve` | **host identity** | User approves/denies → authorization code |
+| `POST <base>/oauth/token` | client | Code exchange, refresh rotation |
+
+## What the server does not do
+
+It is a bridge, not an authorization system. It never decides whether a user may see a record: `ctx.ownerId` is the verified user, and your handler enforces your existing rules exactly as it would for a browser session (call your service layer with that id, or re-enter your own REST API with `ctx.request`'s `Authorization` header and let `mcp.authenticate()` identify the user there). Scopes are consent, not permissions — they narrow what *this agent* may do on the user's behalf, and you can skip them entirely.
+
+## Security model
+
+- User identity comes only from `identity.resolve`; an agent token can never approve a grant.
+- Authorization codes live 10 minutes and are single-use; replaying one revokes the tokens it issued. Both rely on the store's atomic `consume` / `revoke`.
+- Refresh tokens rotate; replaying a rotated refresh token cuts the whole chain.
+- Tokens are stored as SHA-256 only. Audience is `publicOrigin + mcpPath`, so moving domains invalidates old tokens.
+- `tools/call` always requires a token; anonymous discovery exposes tool metadata, never data.
+- Cross-site `Origin` headers on MCP requests are rejected (loopback excepted).
+- Redirect URIs are classified as `loopback` / `custom` / `https`; anything else is refused at registration.
+
+## Compared with Cloudflare `workers-oauth-provider`
+
+It solves the same OAuth layer with KV storage. This package adds: pluggable storage (any database, D1 included), pluggable host identity, a scoped tool table, grant-trimmed `tools/list`, a public schema with anonymous discovery, a consent-page hook, grant management APIs and a reusable end-to-end test. If you only need OAuth and none of the above, use the official library.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test          # Miniflare + D1 end-to-end, memoryStore replay/revocation rules, node:sqlite adapter
+npm run build     # emits dist/ (ESM + .d.ts)
+```
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) and [docs/publishing.md](./docs/publishing.md).
+
+## License
+
+[MIT](./LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,204 @@
+# @ninomae/mcp-app-server
+
+**把你已有的应用变成一个带 OAuth 2.1 授权的 MCP server。**
+
+[English](./README.md) · [接入指南](./docs/integration.md) · [发布流程](./docs/publishing.md) · [变更记录](./CHANGELOG.md)
+
+把**你已有的用户和数据**，以标准 **MCP + OAuth 2.1** 的方式授权给外部 AI Agent（Claude、ChatGPT、Cursor、Claude Code、任何 MCP 客户端）。你不需要自己接 AI 模型：用户带着自己的 Agent 来，读你的数据、在他们那边分析、再通过写工具把结果送回你的应用。
+
+- **身份不绑定任何厂商。** 你的应用已经有登录（Firebase / Supabase / Auth0 / Clerk / session cookie / 自研）——只需实现一个 `resolve(request) → { id }`。
+- **框架自己当 OAuth 授权服务器。** MCP 客户端要求的动态注册（RFC 7591）、PKCE、资源指示（RFC 8707）、refresh 轮换、按 Agent 撤销，消费级 IdP 普遍不提供，所以这一层必须在你手里。
+- **工具表 = 你的产品的 Agent 面。** 每个工具声明所需 scope，`tools/list` 按用户实际授权裁剪。
+- **公开可发现。** `/.well-known/*`、`GET <basePath>/mcp/schema`、匿名 `initialize` / `tools/list` 都不需要 token，可直接提交官方 MCP Registry / Claude 连接器目录。
+- **不绑定数据库。** 核心不依赖任何数据库实现；实现一个很小的 `AppServerStore` 接口就能接 SQL、KV、Redis、Mongo 或任意 ORM。包内自带 `memoryStore()`（开发/测试）和 `sqlStore()`（Cloudflare D1、各种 SQLite 驱动）。
+
+## 安装
+
+```bash
+npm install @ninomae/mcp-app-server @modelcontextprotocol/sdk zod
+```
+
+可选 peer：`jose`（用 `jwtIdentity` / `firebaseIdentity` 时需要）、`react`（用 `/react` 同意页 hook 时需要）。Node ≥ 22 或任何 Web 标准运行时（Cloudflare Workers、Deno、Bun）。
+
+## 接入七步
+
+### 1. 决定 scope
+
+```ts
+scopes: {
+  'notes:read':  { description: '阅读你的笔记', required: true },   // 锁定，永远授予
+  'notes:write': { description: '为笔记附加 AI 摘要', default: true }, // 同意页默认勾选
+}
+```
+
+`description` 会通过 `GET <basePath>/oauth/client` 交给同意页显示。读一个、写一个起步；写 scope 只允许 Agent 写**它自己的产出物**，不要让它改用户主数据。
+
+### 2. 实现身份
+
+```ts
+import { sessionIdentity, jwtIdentity, firebaseIdentity, fixedIdentity } from '@ninomae/mcp-app-server';
+
+// 服务端 session（NextAuth、Rails、Django、Laravel、自研 cookie）
+identity: sessionIdentity(async (req) => await mySessions.userFromCookie(req))   // 返回 { id } 或 null
+
+// 前端持有 JWT（Supabase、Auth0、Clerk、Cognito……任何 OIDC）
+identity: jwtIdentity({ jwksUrl, issuer, audience })
+
+// Firebase 预设
+identity: firebaseIdentity(env.FIREBASE_PROJECT_ID)
+
+// 单用户 / 本机开发（切勿放到公网 origin 后面）
+identity: fixedIdentity('local')
+```
+
+契约只有一条：`id` 必须稳定、不可重用。之后每个 Agent token 都绑定它，工具 handler 拿到的 `ctx.ownerId` 就是它。
+
+### 3. 定义工具
+
+```ts
+import { z } from 'zod';
+
+tools: [
+  {
+    name: 'notes_list',
+    scope: 'notes:read',
+    description: '列出当前用户的笔记。',
+    inputSchema: {},
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    handler: async (_args, ctx) => ({ content: [{ type: 'text', text: JSON.stringify(await listNotes(ctx.ownerId)) }] }),
+  },
+  {
+    name: 'notes_summarize',
+    scope: 'notes:write',
+    description: '为一条笔记保存 Agent 写的摘要。只写摘要，不改正文。',
+    inputSchema: { id: z.string(), summary: z.string().max(500) },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    handler: async ({ id, summary }, ctx) => { /* UPDATE … WHERE owner = ctx.ownerId */ },
+  },
+]
+```
+
+`ctx` 里有 `ownerId / scopes / grantId / clientId / clientName / request`——全部来自已验证的 token，绝不来自工具输入。如果你的工具只是已有 REST API 的薄包装，可以用 `ctx.request` 的 `Authorization` 头把请求转回自己的 handler，并用 `mcp.authenticate(request)` 让 REST 层接受 Agent token。
+
+### 4. 创建 server 并挂路由
+
+```ts
+import { createMcpAppServer } from '@ninomae/mcp-app-server';
+import { sqlStore } from '@ninomae/mcp-app-server/sql';
+
+const mcp = createMcpAppServer({
+  name: 'notes',
+  basePath: '/api/notes',           // → /api/notes/mcp, /api/notes/mcp/schema, /api/notes/oauth/*
+  consentPath: '/oauth/authorize',  // 你的前端页面
+  scopes, identity, tools,
+  storage: sqlStore(env.NOTES_DB),  // 或 memoryStore()，或你自己实现的 AppServerStore
+  origins: { publicOrigin: 'https://notes.example.com', webOrigin: 'https://notes.example.com' },
+  onEvent: (e) => audit.write(e),   // authorized / refreshed / revoked / tool（不含 payload）
+});
+
+export default {
+  async fetch(request, env) {
+    await mcp.ensureSchema();               // 幂等，转发给 store
+    const handled = await mcp.fetch(request);
+    if (handled) return handled;                // well-known / oauth / mcp / schema
+    // …你原有的路由
+  },
+};
+```
+
+**存储。** 本包需要记住注册过的客户端、一次性授权码、refresh token 链和 access token（密钥一律只存 SHA-256）。它只通过 `AppServerStore` 这个普通对象仓储接口访问它们：
+
+```ts
+interface AppServerStore {
+  clients:       { create; get; touch };
+  codes:         { create; get; consume /* 原子，只有第一个调用者得到 true */; setIssuedToken };
+  refreshTokens: { create; get; getByAccessToken; revoke /* 原子 */; revokeByAccessToken; setSuccessor };
+  accessTokens:  { create; get; getByHash; listByOwner; touch; revoke };
+  prune?(now): Promise<void>;        // 可选：清理过期 code / refresh token
+  ensureSchema?(): Promise<void>;    // 可选：幂等建表，对应 mcp.ensureSchema()
+}
+```
+
+自带两个实现：`memoryStore()`（Map，开发/测试/单进程）和 `@ninomae/mcp-app-server/sql` 里的 `sqlStore(db, tables?)`（D1 直接传，node:sqlite / better-sqlite3 / libsql 包十行适配器）。要接 Postgres、Redis、KV、Mongo、Prisma、Drizzle，就自己实现这个接口（约 150 行，[`src/store.ts`](./src/store.ts) 是参考实现）。标"原子"的两个方法是防重放的关键：`codes.consume` 和 `refreshTokens.revoke` 必须恰好对一个调用者返回 `true`。把 [`tests/memory-store.test.mjs`](./tests/memory-store.test.mjs) 复制一份、换成你的 store，就能验证。
+
+**注册限流。** `POST /oauth/register` 无需认证但会写存储，所以有限流。和存储一样只定义契约：`registrationLimit: { limiter: { allow(key) => Promise<boolean> }, key?: (request) => string }`，`false` 关闭。默认 `memoryRateLimiter()`（每 IP 每小时 20 次，进程内计数）——单进程服务器正确，**Workers / Lambda 等多实例环境无效**，请接平台的共享计数器，例如 Cloudflare 的 rate-limiting binding：`{ limiter: { allow: async (key) => (await env.REGISTER_LIMIT.limit({ key })).success } }`。
+
+其他可选项：`accessTokenDays`（默认 30）、`refreshTokenDays`（默认 90）、`tokenPrefix`（默认 `agt_`，用于在自己的路由里识别 Agent token）、`anonymousDiscovery`（默认 true）、`contract`（随 schema 一起发布的数据契约 markdown）。
+
+### 5. 同意页
+
+授权服务器会把用户 302 到 `webOrigin + consentPath`（原样带 query）。页面用你自己的登录，用 headless hook 完成其余部分：
+
+```tsx
+import { useAgentConsent } from '@ninomae/mcp-app-server/react';
+
+const { client, chosen, toggle, decide, error, busy, destination, missingClient } = useAgentConsent({
+  basePath: '/api/notes',
+  authHeaders: () => ({ authorization: 'Bearer ' + session.token }), // 或留空，靠 cookie
+});
+// client.scopeDetails → 渲染复选框（required 的禁用）；decide('approve' | 'deny') 会跳回 Agent
+```
+
+完整示例见 [`examples/consent-page.tsx`](./examples/consent-page.tsx)。非 React 前端直接调 `GET <base>/oauth/client` 和 `POST <base>/oauth/approve` 即可。
+
+### 6. 让用户管理授权
+
+```ts
+mcp.listGrants(ownerId)             // 哪些 Agent 连着我、什么权限、最后使用时间
+mcp.revokeGrant(ownerId, grantId)   // 撤销并切断整条 refresh 链
+```
+
+### 7. 验证与发布
+
+- `npm test` 里的 Miniflare 端到端（注册 → 授权 → 同意 → 换 token → 调工具 → 刷新 → 撤销）就是模板；fixture 在 `tests/fixtures/notes-host.ts`，60 行就是一个完整宿主。
+- 真连一次：`claude mcp add --transport http notes https://notes.example.com/api/notes/mcp`，然后在 Claude Code 里 `/mcp` → Authenticate。
+- `mcp.serverJson(request, 'io.github.<you>', '一句话描述')` 生成官方 MCP Registry 的 `server.json`；`mcp-publisher publish` 即可上架。Claude / ChatGPT 连接器目录另需人工提交（固定 HTTPS 地址、隐私政策）。
+
+各类客户端（Claude Code、Claude.ai、ChatGPT、Cursor、自写脚本）的具体接入步骤见 [docs/integration.md](./docs/integration.md)。
+
+## 端点一览
+
+| 路径 | 认证 | 作用 |
+| --- | --- | --- |
+| `GET /.well-known/oauth-protected-resource[<mcpPath>]` | 无 | 资源元数据（RFC 9728） |
+| `GET /.well-known/oauth-authorization-server` | 无 | 授权服务器元数据（RFC 8414） |
+| `GET <base>/mcp/schema` | 无 | 服务器名、端点、scope、全部工具的 JSON Schema |
+| `POST <base>/mcp`（`initialize`/`ping`/`tools/list`） | 无 | 匿名发现；返回全量工具 |
+| `POST <base>/mcp`（其他） | Agent token | MCP Streamable HTTP |
+| `POST <base>/oauth/register` | 无（限速） | 动态客户端注册 |
+| `GET <base>/oauth/authorize` | 无 | 校验后 302 到同意页 |
+| `GET <base>/oauth/client` | 无 | 同意页读取客户端与 scope 说明 |
+| `POST <base>/oauth/approve` | **宿主身份** | 用户同意/拒绝 → 授权码 |
+| `POST <base>/oauth/token` | 客户端 | 授权码换 token、refresh 轮换 |
+
+## 本包不做什么
+
+它是桥接，不是权限系统。它从不判断某个用户能不能看某条记录：`ctx.ownerId` 是验证过的用户，你的 handler 用它执行**原有**的规则——直接调你的 service 层传这个 id，或者带上 `ctx.request` 的 `Authorization` 头回调你自己的 REST API，在那里用 `mcp.authenticate()` 认出用户，其余逻辑和浏览器会话一模一样。scope 是"授权委托"而不是"权限"：它只收窄*这个 agent* 能替用户做的事，`scopes` 可以完全省略（本包会用一个隐式 scope，同意页变成单纯的允许/拒绝）。
+
+## 安全边界
+
+- 用户身份只来自 `identity.resolve`；Agent token 不能用来 approve。
+- 授权码 10 分钟、一次性；重放会吊销它签发的 token。refresh 轮换；重放已轮换的 refresh 会切断整条链。
+- token 只存 SHA-256；audience 绑定 `publicOrigin + mcpPath`，换域名后旧 token 自动失效。
+- `tools/call` 永远要 token；匿名发现只暴露工具元数据，不暴露数据。
+- 跨站 `Origin` 的 MCP 请求被拒绝（loopback 除外）。
+- redirect_uri 只接受 loopback / 自定义 scheme / https，注册时即拒绝其他形式。
+
+## 与 Cloudflare `workers-oauth-provider` 的区别
+
+它解决同一层的 OAuth 问题（KV 存储）。本包多出：可插拔存储（任意数据库，含 D1）、可插拔宿主身份、scope 化工具表、按授权裁剪的 `tools/list`、公开 schema 与匿名发现、同意页 hook、授权管理 API、以及一套可复用的端到端测试。如果你只需要 OAuth 而不需要以上任何一项，用官方库即可。
+
+## 开发
+
+```bash
+npm install
+npm run typecheck
+npm test          # Miniflare 端到端
+npm run build     # 产出 dist/（ESM + .d.ts）
+```
+
+发布到 npm 的完整步骤见 [docs/publishing.md](./docs/publishing.md)。
+
+## 许可
+
+[MIT](./LICENSE)

package/dist/identity.d.ts

@@ -0,0 +1,27 @@
+import type { Identity, IdentityProvider } from './types.js';
+export interface JwtIdentityOptions {
+    /** JWKS endpoint of the issuer (any OIDC provider publishes one). */
+    jwksUrl: string;
+    issuer: string;
+    audience: string;
+    /** Claim that carries the stable user id. Default `sub`. */
+    subjectClaim?: string;
+    algorithms?: string[];
+    /** Extra checks on the verified payload; throw AppServerError to reject. */
+    assert?: (payload: Record<string, unknown>) => void;
+}
+/**
+ * The host front end holds a JWT for the signed-in user (Firebase, Supabase, Auth0, Clerk, Cognito…)
+ * and sends it as `Authorization: Bearer` when approving. Requires the optional `jose` peer dependency.
+ */
+export declare function jwtIdentity(options: JwtIdentityOptions): IdentityProvider;
+/** Firebase Authentication preset over jwtIdentity. */
+export declare function firebaseIdentity(projectId: string, options?: Pick<JwtIdentityOptions, 'assert'>): IdentityProvider;
+/**
+ * The host keeps a server-side session (cookie, framework session store). Supply the lookup;
+ * return null when nobody is signed in.
+ */
+export declare function sessionIdentity(lookup: (request: Request) => Promise<Identity | null>): IdentityProvider;
+/** Single-user / local development: every consent is attributed to one fixed id. Never use behind a public origin. */
+export declare function fixedIdentity(id: string, displayName?: string): IdentityProvider;
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAU7D,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CACrD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,gBAAgB,CAmBzE;AAED,uDAAuD;AACvD,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,IAAI,CAAC,kBAAkB,EAAE,QAAQ,CAAM,GAAG,gBAAgB,CAOtH;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,gBAAgB,CAQxG;AAED,sHAAsH;AACtH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,SAAoB,GAAG,gBAAgB,CAE3F"}

package/dist/identity.js

@@ -0,0 +1,62 @@
+import { AppServerError } from './types.js';
+function bearer(request) {
+    const header = request.headers.get('authorization') || '';
+    const token = header.replace(/^Bearer\s+/i, '').trim();
+    if (!header.startsWith('Bearer ') || !token)
+        throw new AppServerError(401, 'Sign in first');
+    return token;
+}
+/**
+ * The host front end holds a JWT for the signed-in user (Firebase, Supabase, Auth0, Clerk, Cognito…)
+ * and sends it as `Authorization: Bearer` when approving. Requires the optional `jose` peer dependency.
+ */
+export function jwtIdentity(options) {
+    let keys;
+    return {
+        async resolve(request) {
+            const token = bearer(request);
+            const jose = await import('jose');
+            keys ??= jose.createRemoteJWKSet(new URL(options.jwksUrl));
+            let payload;
+            try {
+                payload = (await jose.jwtVerify(token, keys, { issuer: options.issuer, audience: options.audience, algorithms: options.algorithms ?? ['RS256'] })).payload;
+            }
+            catch {
+                throw new AppServerError(401, 'Sign-in expired; sign in again');
+            }
+            options.assert?.(payload);
+            const id = payload[options.subjectClaim ?? 'sub'];
+            if (typeof id !== 'string' || !id)
+                throw new AppServerError(401, 'Token missing subject');
+            return { id, email: typeof payload.email === 'string' ? payload.email : undefined, displayName: typeof payload.name === 'string' ? payload.name : undefined };
+        },
+    };
+}
+/** Firebase Authentication preset over jwtIdentity. */
+export function firebaseIdentity(projectId, options = {}) {
+    return jwtIdentity({
+        jwksUrl: 'https://www.googleapis.com/service_accounts/v1/jwk/securetoken@system.gserviceaccount.com',
+        issuer: `https://securetoken.google.com/${projectId}`,
+        audience: projectId,
+        ...options,
+    });
+}
+/**
+ * The host keeps a server-side session (cookie, framework session store). Supply the lookup;
+ * return null when nobody is signed in.
+ */
+export function sessionIdentity(lookup) {
+    return {
+        async resolve(request) {
+            const identity = await lookup(request);
+            if (!identity)
+                throw new AppServerError(401, 'Sign in first');
+            return identity;
+        },
+    };
+}
+/** Single-user / local development: every consent is attributed to one fixed id. Never use behind a public origin. */
+export function fixedIdentity(id, displayName = 'Local workspace') {
+    return { resolve: async () => ({ id, displayName }) };
+}
+//# sourceMappingURL=identity.js.map

package/dist/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import type { AuthenticatedGrant, McpAppServerConfig, Grant, Origins } from './types.js';
+import { describeServer, registryEntry } from './mcp.js';
+export * from './types.js';
+export * from './store.js';
+export * from './rate-limit.js';
+export * from './identity.js';
+export { classifyRedirect } from './oauth.js';
+export interface McpAppServer {
+    /** Handle a request if it belongs to the server; returns null for every other path. */
+    fetch(request: Request): Promise<Response | null>;
+    /** Verify an agent access token carried by any request (e.g. the host's own REST routes). Null when the request carries no server-issued token. */
+    authenticate(request: Request): Promise<AuthenticatedGrant | null>;
+    /** True when the bearer token on this request looks like a server-issued token. */
+    carriesToken(request: Request): boolean;
+    listGrants(ownerId: string): Promise<Grant[]>;
+    /** Revoke one grant and every token rotated from it. Throws 404 when the owner does not hold it. */
+    revokeGrant(ownerId: string, grantId: string): Promise<void>;
+    /** Delegates to `storage.ensureSchema()` when the store defines one; otherwise a no-op. */
+    ensureSchema(): Promise<void>;
+    /** Public schema document (same as GET <basePath>/mcp/schema). */
+    describe(request: Request): ReturnType<typeof describeServer>;
+    /** `server.json` for the official MCP registry. */
+    serverJson(request: Request, namespace: string, description: string): ReturnType<typeof registryEntry>;
+    origins(request: Request): Origins;
+    paths: {
+        mcp: string;
+        schema: string;
+        oauth: string;
+        consent: string;
+    };
+}
+export declare function createMcpAppServer(config: McpAppServerConfig): McpAppServer;
+//# sourceMappingURL=index.d.ts.map