mcp-trellis 2.1.0 → 2.2.0

package/README.md

@@ -1,57 +1,55 @@
 # mcp-trellis
 
-**Existing SaaS → authenticated AI connector SDK.**
+Add authenticated AI connectors to your existing SaaS.
+Reuse your users, login and permissions. Trellis handles MCP + OAuth.
 
-Claude, ChatGPT and Gemini against the login and data you already have. No new
-database. No auth vendor. One TypeScript package.
-
-mcp-trellis is the **vendor-neutral embedded BYO-auth** path: MCP handler and
-self-hosted OAuth AS in one npm install. Contrast composition stacks such as
-**xmcp + Scalekit** (or WorkOS / Descope connectors) that split the MCP runtime
-and the identity product across 2–3 packages.
+```
+Existing SaaS
+users + login + data
+       ↓
+  mcp-trellis
+       ↓
+Claude / ChatGPT / Gemini
+```
 
-Your app already knows who the user is. Connecting an AI client still means
-wiring OAuth discovery, registration, consent, PKCE and token exchange.
-**mcp-trellis handles that protocol work**, while your app keeps login, token
-verification and data permissions.
+[![npm](https://img.shields.io/npm/v/mcp-trellis)](https://www.npmjs.com/package/mcp-trellis)
+[![CI](https://github.com/amir1824/mcp-trellis/actions/workflows/ci.yml/badge.svg)](https://github.com/amir1824/mcp-trellis/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-```mermaid
-flowchart LR
-  A[Existing app: login + user data] --> B[mcp-trellis: OAuth + MCP]
-  B --> C[AI client: user-scoped tools]
-```
+## Demo
 
-## The 30-second example
+![Project desk local demo — login, consent, user-scoped tool result](docs/diagrams/demo-tool-result.png)
 
 ```bash
 npm install mcp-trellis
 ```
 
+## The 30-second example
+
 ```ts
-import { createMcpApp } from "mcp-trellis";
-import { existingAuth, projectsForUser } from "./your-app.js";
+import { createMcpApp, signedTokenAuth } from "mcp-trellis";
+import { session, projectsForUser, codeStore } from "./your-app.js";
 
 export const mcp = createMcpApp<{ userId: string }>({
   serverInfo: { name: "my-saas", version: "1.0.0" },
-  clients: ["claude"],
-  // existingAuth must include codeStore (required since 2.0) plus the usual ports.
-  auth: existingAuth,
-  context: (_request, principal) => ({ userId: principal!.id }),
-  tools: [{
-    name: "list_my_projects",
-    description: "List the signed-in user's projects",
-    inputSchema: { type: "object", properties: {} },
-    scope: "mcp",
-    handler: async ({ userId }) => JSON.stringify(await projectsForUser(userId)),
-  }],
+  auth: signedTokenAuth({
+    secret: process.env.MCP_SECRET!,
+    resolveUser: (req) => session(req),
+    loginUrl: (_r, n) => `/login?next=${encodeURIComponent(n)}`,
+    codeStore,
+  }),
+  context: (_r, p) => ({ userId: p!.id }),
+  tools: [{ name: "list_my_projects", description: "List projects",
+    inputSchema: { type: "object", properties: {} }, scope: "mcp",
+    handler: async ({ userId }) => JSON.stringify(await projectsForUser(userId)) }],
 });
 ```
 
-This shows the integration shape: `your-app.js` is your application's auth/data adapter, not a supplied module. Production needs a shared `codeStore` (see [examples/stores.ts](examples/stores.ts)). **[Run the complete Node demo](examples/saas-demo/README.md)** for working login, token handling and two users with different projects. Node ≥20 is required.
+`codeStore` must be a shared single-use store (Redis/KV — see [examples/stores.ts](examples/stores.ts)). Advanced ports (`mintAccessToken`, `verifyToken`, refresh, revoke) remain available when you outgrow the helper. Node ≥20.
 
-[![npm](https://img.shields.io/npm/v/mcp-trellis)](https://www.npmjs.com/package/mcp-trellis)
-[![CI](https://github.com/amir1824/mcp-trellis/actions/workflows/ci.yml/badge.svg)](https://github.com/amir1824/mcp-trellis/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+**[View the complete SaaS demo](examples/saas-demo/README.md)** — working login, consent, two users with different projects.
+
+Also listed on the Official MCP Registry as **Project desk** (reference remote server; not the SDK) — see [`examples/project-desk`](examples/project-desk/).
 
 ## When should I use this?
 
@@ -68,7 +66,7 @@ This shows the integration shape: `your-app.js` is your application's auth/data
 
 ## Run a real tool
 
-The [Project desk demo](examples/saas-demo/README.md) proves the local flow: app login → OAuth consent → access token → `list_my_projects`. Alice sees her two projects; Bob sees his own. It uses fictional data and an independent app session.
+The [Project desk demo](examples/saas-demo/README.md) is the canonical example ([`examples/project-desk`](examples/project-desk/) implementation): app login → OAuth consent → access token → `list_my_projects`. Alice sees her two projects; Bob sees his own. It uses fictional data and an independent app session.
 
 **Live Claude / ChatGPT recordings are still pending.** Automated OAuth tests are not evidence that a current vendor client has connected successfully.
 
@@ -84,9 +82,13 @@ Protocol versions implemented: `2024-11-05`, `2025-03-26`, `2025-06-18`; default
 
 ## Integrate with your app
 
-Implement `resolveUser`, `loginUrl`, `mintAccessToken` and `verifyToken` using your app's existing auth. Mint tokens for the requested MCP resource and return their verified `audience`; the library rejects an audience mismatch before executing tools. A logged-in user still sees an OAuth consent screen. Your data layer must enforce ownership and tenant permissions. Browser callers that send an `Origin` header need `allowedRequestOrigins` (fail-closed by default) — see [security.md](docs/security.md).
+Prefer `signedTokenAuth` for a one-secret start. For refresh, revoke, or your own JWT/JWKS, implement `resolveUser`, `loginUrl`, `mintAccessToken` and `verifyToken` yourself. Mint tokens for the requested MCP resource and return their verified `audience`; the library rejects an audience mismatch before executing tools. A logged-in user still sees an OAuth consent screen. Your data layer must enforce ownership and tenant permissions. Browser callers that send an `Origin` header need `allowedRequestOrigins` (fail-closed by default) — see [security.md](docs/security.md).
+
+[SaaS demo](examples/saas-demo/README.md) · [Next.js starter](examples/nextjs-saas/README.md) · [Host recipes](docs/guide.md) · [Security](docs/security.md) · [npm](https://www.npmjs.com/package/mcp-trellis)
+
+## How it compares
 
-[Node demo](examples/saas-demo/README.md) · [Host recipes](docs/guide.md) · [Security responsibilities](docs/security.md) · [npm](https://www.npmjs.com/package/mcp-trellis)
+mcp-trellis is the **vendor-neutral embedded BYO-auth** path: MCP handler and self-hosted OAuth AS in one npm install. Contrast composition stacks such as **xmcp + Scalekit** (or WorkOS / Descope connectors) that split the MCP runtime and the identity product across 2–3 packages. Full comparison table: [docs/ROADMAP.md](docs/ROADMAP.md).
 
 ## Architecture
 
@@ -107,7 +109,7 @@ Host recipes, ports, tools, and multi-tenant: [docs/guide.md](docs/guide.md).
 | [docs/security.md](docs/security.md) | Protocol promises, threat model, not in scope |
 | [docs/ROADMAP.md](docs/ROADMAP.md) | What's next |
 
-Examples: [`examples/`](examples/) — HTTP server, Worker, multi-tenant, stores, audit.
+Canonical example: [`examples/project-desk`](examples/project-desk/) ([local docs](examples/saas-demo/)). Recipes: [`examples/`](examples/).
 
 ## Contributing
 

package/dist/auth/signed-token.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Convenience auth: one secret seals OAuth codes (via `codeSecret`) and
+ * signs short-lived access tokens. Domain separation is HKDF, not luck —
+ * access-token HMAC uses `mcp-trellis:signed-access-token:v1`, distinct from
+ * the sealed-code and client-secret-hash labels.
+ *
+ * ponytail: stateless tokens cannot be revoked before `exp`. No
+ * `refreshAccessToken` / `revokeToken` — `/revoke` stays unmounted and
+ * refresh unadvertised. Upgrade: supply those ports plus a store (see
+ * `examples/project-desk/src/tokens.ts`).
+ */
+import type { McpAppAuth } from "../app-options.js";
+import type { CodeStore } from "../oauth/crypto/codes.js";
+import type { OAuthUser } from "../oauth/types.js";
+export type SignedTokenAuthOptions = {
+    secret: string;
+    resolveUser: (request: Request) => Promise<OAuthUser | null>;
+    loginUrl: (request: Request, nextPath: string) => string;
+    /** Access-token lifetime in seconds. Default 3600. Must be finite and > 0. */
+    ttlSeconds?: number;
+    /** Passthrough — production still needs a shared store across instances. */
+    codeStore?: CodeStore;
+};
+/** Builds a complete `McpAppAuth` from one secret plus your session resolver. */
+export declare const signedTokenAuth: (options: SignedTokenAuthOptions) => McpAppAuth;
+//# sourceMappingURL=signed-token.d.ts.map

package/dist/auth/signed-token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signed-token.d.ts","sourceRoot":"","sources":["../../src/auth/signed-token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAiB,MAAM,mBAAmB,CAAC;AAEnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE1D,OAAO,KAAK,EAAqC,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAMtF,MAAM,MAAM,sBAAsB,GAAG;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAC7D,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;IACzD,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB,CAAC;AA8EF,iFAAiF;AACjF,eAAO,MAAM,eAAe,GAAI,SAAS,sBAAsB,KAAG,UAiBjE,CAAC"}

package/dist/auth/signed-token.js

@@ -0,0 +1,96 @@
+/**
+ * Convenience auth: one secret seals OAuth codes (via `codeSecret`) and
+ * signs short-lived access tokens. Domain separation is HKDF, not luck —
+ * access-token HMAC uses `mcp-trellis:signed-access-token:v1`, distinct from
+ * the sealed-code and client-secret-hash labels.
+ *
+ * ponytail: stateless tokens cannot be revoked before `exp`. No
+ * `refreshAccessToken` / `revokeToken` — `/revoke` stays unmounted and
+ * refresh unadvertised. Upgrade: supply those ports plus a store (see
+ * `examples/project-desk/src/tokens.ts`).
+ */
+import { bytesToBase64Url, fromBase64Url } from "../oauth/crypto/base64url.js";
+import { hkdfKey } from "../oauth/crypto/hkdf.js";
+const HKDF_INFO = "mcp-trellis:signed-access-token:v1";
+const HMAC_SHA256 = { name: "HMAC", hash: "SHA-256", length: 256 };
+const DEFAULT_TTL_SECONDS = 3600;
+const accessKey = (secret, usage) => hkdfKey(secret, { info: HKDF_INFO, algorithm: HMAC_SHA256, usage });
+const signPayload = async (secret, payload) => {
+    const key = await accessKey(secret, "sign");
+    const body = bytesToBase64Url(new TextEncoder().encode(JSON.stringify(payload)));
+    const signature = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(body));
+    return `${body}.${bytesToBase64Url(signature)}`;
+};
+const parsePayload = (raw) => {
+    if (raw === null || typeof raw !== "object")
+        return null;
+    const record = raw;
+    if (typeof record.userId !== "string" || typeof record.audience !== "string")
+        return null;
+    if (typeof record.exp !== "number" || !Number.isFinite(record.exp))
+        return null;
+    if (record.exp < Date.now())
+        return null;
+    if (!Array.isArray(record.scopes) || !record.scopes.every((s) => typeof s === "string")) {
+        return null;
+    }
+    return {
+        userId: record.userId,
+        scopes: record.scopes,
+        audience: record.audience,
+        exp: record.exp,
+    };
+};
+const verifyPayload = async (secret, token) => {
+    const parts = token.split(".");
+    if (parts.length !== 2)
+        return null;
+    const [body, signature] = parts;
+    if (!body || !signature)
+        return null;
+    try {
+        const key = await accessKey(secret, "verify");
+        const ok = await crypto.subtle.verify("HMAC", key, fromBase64Url(signature), new TextEncoder().encode(body));
+        if (!ok)
+            return null;
+        return parsePayload(JSON.parse(new TextDecoder().decode(fromBase64Url(body))));
+    }
+    catch {
+        return null;
+    }
+};
+const mint = async (secret, ttlSeconds, input) => {
+    const scopes = input.scope.split(" ").filter(Boolean);
+    const accessToken = await signPayload(secret, {
+        userId: input.userId,
+        scopes,
+        audience: input.resource,
+        exp: Date.now() + ttlSeconds * 1000,
+    });
+    return { accessToken, expiresIn: ttlSeconds, scope: input.scope };
+};
+const toVerified = (payload) => ({
+    userId: payload.userId,
+    scopes: payload.scopes,
+    audience: payload.audience,
+});
+/** Builds a complete `McpAppAuth` from one secret plus your session resolver. */
+export const signedTokenAuth = (options) => {
+    const ttlSeconds = options.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+    if (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0) {
+        throw new Error(`signedTokenAuth: ttlSeconds must be a finite number > 0 (got ${ttlSeconds})`);
+    }
+    const { secret } = options;
+    return {
+        codeSecret: secret,
+        resolveUser: options.resolveUser,
+        loginUrl: options.loginUrl,
+        mintAccessToken: (input) => mint(secret, ttlSeconds, input),
+        verifyToken: async (token) => {
+            const payload = await verifyPayload(secret, token);
+            return payload ? toVerified(payload) : null;
+        },
+        ...(options.codeStore !== undefined ? { codeStore: options.codeStore } : {}),
+    };
+};
+//# sourceMappingURL=signed-token.js.map

package/dist/auth/signed-token.js.map

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

package/dist/server.d.ts

@@ -1,6 +1,7 @@
 export { createMcpApp, type McpApp, type McpAppAuth, type McpAppOptions, type UnifiedAuditEntry, type VerifiedToken, } from "./app.js";
 export { consoleAudit } from "./audit.js";
 export { parseBearer, rejectQueryToken, type WwwAuthenticateOptions, wwwAuthenticateHeader, } from "./auth/bearer.js";
+export { type SignedTokenAuthOptions, signedTokenAuth, } from "./auth/signed-token.js";
 export { authMethodsFor, CLIENT_PROFILES, type ClientName, type ClientProfile, DEFAULT_CLIENTS, hasDynamicClient, preRegisteredClients, redirectUrisFor, } from "./clients.js";
 export * from "./deprecated.js";
 export { type JsonResponseInput, type JsonResponseOptions, jsonResponse, } from "./http/http.js";

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,KAAK,MAAM,EACX,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,aAAa,GACnB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,KAAK,sBAAsB,EAC3B,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,cAAc,EACd,eAAe,EACf,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,GAChB,MAAM,cAAc,CAAC;AAEtB,cAAc,iBAAiB,CAAC;AAChC,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,KAAK,UAAU,EACf,gBAAgB,EAChB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,QAAQ,EACb,KAAK,SAAS,EACd,KAAK,UAAU,GAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,EACvB,wBAAwB,EACxB,mBAAmB,EACnB,oBAAoB,EACpB,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,QAAQ,EACR,SAAS,GACV,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAChF,OAAO,EACL,kBAAkB,EAClB,KAAK,eAAe,EACpB,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,UAAU,GAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,OAAO,EACP,KAAK,iBAAiB,EACtB,UAAU,EACV,KAAK,gBAAgB,GACtB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,YAAY,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,kFAAkF;AAClF,YAAY,EACV,WAAW,EACX,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,WAAW,EACX,SAAS,EACT,uBAAuB,EACvB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,KAAK,MAAM,EACX,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,aAAa,GACnB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,KAAK,sBAAsB,EAC3B,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,KAAK,sBAAsB,EAC3B,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,cAAc,EACd,eAAe,EACf,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,GAChB,MAAM,cAAc,CAAC;AAEtB,cAAc,iBAAiB,CAAC;AAChC,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,KAAK,UAAU,EACf,gBAAgB,EAChB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,QAAQ,EACb,KAAK,SAAS,EACd,KAAK,UAAU,GAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,EACvB,wBAAwB,EACxB,mBAAmB,EACnB,oBAAoB,EACpB,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,QAAQ,EACR,SAAS,GACV,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAChF,OAAO,EACL,kBAAkB,EAClB,KAAK,eAAe,EACpB,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,UAAU,GAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,OAAO,EACP,KAAK,iBAAiB,EACtB,UAAU,EACV,KAAK,gBAAgB,GACtB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,YAAY,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,kFAAkF;AAClF,YAAY,EACV,WAAW,EACX,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,WAAW,EACX,SAAS,EACT,uBAAuB,EACvB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC"}

package/dist/server.js

@@ -1,6 +1,7 @@
 export { createMcpApp, } from "./app.js";
 export { consoleAudit } from "./audit.js";
 export { parseBearer, rejectQueryToken, wwwAuthenticateHeader, } from "./auth/bearer.js";
+export { signedTokenAuth, } from "./auth/signed-token.js";
 export { authMethodsFor, CLIENT_PROFILES, DEFAULT_CLIENTS, hasDynamicClient, preRegisteredClients, redirectUrisFor, } from "./clients.js";
 // Moved to `mcp-trellis/advanced`; deprecated aliases until 3.0.
 export * from "./deprecated.js";

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,GAMb,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EACL,WAAW,EACX,gBAAgB,EAEhB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,cAAc,EACd,eAAe,EAGf,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,GAChB,MAAM,cAAc,CAAC;AACtB,iEAAiE;AACjE,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAGL,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAEL,gBAAgB,GAMjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,EACvB,wBAAwB,EACxB,mBAAmB,EACnB,oBAAoB,EAIpB,QAAQ,EACR,SAAS,GACV,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAChF,OAAO,EACL,kBAAkB,GAOnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAGL,OAAO,EAEP,UAAU,GAEX,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,GAMb,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EACL,WAAW,EACX,gBAAgB,EAEhB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAEL,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,cAAc,EACd,eAAe,EAGf,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,GAChB,MAAM,cAAc,CAAC;AACtB,iEAAiE;AACjE,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAGL,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAEL,gBAAgB,GAMjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,EACvB,wBAAwB,EACxB,mBAAmB,EACnB,oBAAoB,EAIpB,QAAQ,EACR,SAAS,GACV,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAChF,OAAO,EACL,kBAAkB,GAOnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAGL,OAAO,EAEP,UAAU,GAEX,MAAM,gBAAgB,CAAC"}

package/docs/ROADMAP.md

@@ -231,7 +231,9 @@ a proper JSON-RPC error.
 - **Unified `audit` sink** on `createMcpApp` — one callback for MCP and
   OAuth events (`source: "mcp" | "oauth"`); `auth.audit` remains an
   OAuth-only override.
-- **Framework recipes** — `examples/nextjs-route.ts`, `examples/express.ts`.
+- **Framework recipes** — `examples/nextjs-saas/`, `examples/express.ts`.
+- **Reference MCP Registry server** — `examples/project-desk/`
+  (`io.github.amir1824/project-desk`, remotes only; not the SDK package).
 - Fail-closed defaults: `allowInMemoryCodeStore` / `validateArgs`.
 - **RFC 9207 `iss`** on authorize / error redirects; AS metadata advertises
   `authorization_response_iss_parameter_supported`.

package/docs/compatibility.md

@@ -18,24 +18,25 @@ The Gemini profile does not imply compatibility with Gemini CLI or every Gemini
 
 ## Demo deploy (Worker)
 
-Compile-checked Worker sketch: [`examples/cloudflare-worker.ts`](../examples/cloudflare-worker.ts).
-
-One-liner after you add a minimal `wrangler.toml` (name, `compatibility_date`, and secrets
-`OAUTH_CODE_SECRET` / `ACCESS_TOKEN_SECRET`):
+**Project desk** (Registry remotes target): [`examples/project-desk/worker.ts`](../examples/project-desk/worker.ts)
+via root [`wrangler.toml`](../wrangler.toml).
 
 ```bash
+npx wrangler secret put DEMO_PASSWORD   # project-desk-demo for the public demo
 npx wrangler secret put OAUTH_CODE_SECRET
-npx wrangler secret put ACCESS_TOKEN_SECRET
-npx wrangler deploy examples/cloudflare-worker.ts
+npx wrangler deploy
 ```
 
-Point a connector at `https://YOUR-WORKER/mcp` only after secrets and an origin
-allowlist match your route. This path proves the Worker mounts; it does **not**
-replace the live client rows below.
+MCP URL: `https://mcp-trellis-project-desk.<workers-subdomain>.workers.dev/mcp`.
+Operator checklist: [`examples/project-desk/PUBLISH.md`](../examples/project-desk/PUBLISH.md).
+This does **not** replace the live client rows below.
+
+Minimal ping-only Worker recipe (not the hosted demo):
+[`examples/cloudflare-worker.ts`](../examples/cloudflare-worker.ts).
 
 ## Host contract covered in-repo
 
-`examples/saas-demo` now mints refresh tokens and enforces RFC 6749 §6: requested
+`examples/project-desk` mints refresh tokens and enforces RFC 6749 §6: requested
 refresh `scope` must be ⊆ the scopes originally bound to that refresh token
 (`isScopeSubset` pattern also in `examples/stores.ts`). Escalation →
 `invalid_grant`. Covered by `test/e2e/saas-demo.test.ts`.
@@ -58,10 +59,11 @@ release; it does **not** replace the live client row.
 
 Record client product, version/build (or web UI and test date), account tier, package version/commit, hosting environment and configured callback. Capture discovery → registration → app login → consent → token exchange → initialize → tools/list → `list_my_projects`. Verify wrong audience/invalid token rejection and user isolation separately. Save sanitized output or recording; exclude cookies, passwords, codes and tokens.
 
-Against a public HTTPS demo (`PUBLIC_ORIGIN` + `DEMO_PASSWORD`):
+Against a public HTTPS demo (`PUBLIC_ORIGIN` + `DEMO_PASSWORD=project-desk-demo`):
 
 ```bash
 npm run demo   # reverse-proxy to HTTPS; set PUBLIC_ORIGIN
+# or use the deployed Worker from examples/project-desk/PUBLISH.md
 node scripts/prep-claude-oauth.mjs   # scripted OAuth + refresh scope + tool
 # Then open the vendor UI with MCP URL https://YOUR-HOST/mcp and record below.
 ```

package/docs/guide.md

@@ -2,8 +2,11 @@
 
 Practical deep dive: architecture, host recipes, ports, tools, and multi-tenant
 connectors. For a working minimal server, start from the [README](../README.md).
-API tables and exports live in [reference.md](reference.md). Security guarantees
-and threat model: [security.md](security.md).
+The **canonical example** is [`examples/project-desk`](../examples/project-desk/)
+(Project desk: login → consent → user-scoped tools; local docs in
+[`examples/saas-demo`](../examples/saas-demo/)). API tables and exports live
+in [reference.md](reference.md). Security guarantees and threat model:
+[security.md](security.md).
 
 [Architecture](#how-it-fits-together) · [Clients](#clients) · [Recipes](#recipes) ·
 [Compose the primitives](#advanced-compose-the-primitives) ·
@@ -69,7 +72,7 @@ registration.
 // Worker
 export default { fetch: (req: Request, env: Env) => buildApp(env).fetch(req) };
 
-// Next.js App Router — app/[[...mcp]]/route.ts
+// Next.js App Router — see examples/nextjs-saas/
 export const GET = (req: Request) => app.fetch(req);
 export const POST = (req: Request) => app.fetch(req);
 export const OPTIONS = (req: Request) => app.fetch(req);
@@ -181,8 +184,7 @@ Also mount `.well-known/*` and `/mcp/oauth/*` the same way (or route everything
 
 Express, Cloud Functions, Cloud Run, `http.createServer` — bridge with
 `asNodeHandler`. Runnable recipe: [`examples/http-server.ts`](../examples/http-server.ts)
-(set `OAUTH_CODE_SECRET` and `ACCESS_TOKEN_SECRET`, e.g. from `openssl rand -base64 32`,
-then `npx tsx examples/http-server.ts`).
+(set `MCP_SECRET`, e.g. from `openssl rand -base64 32`, then `npx tsx examples/http-server.ts`).
 
 ## Ports — what you implement
 
@@ -192,6 +194,10 @@ The library stays protocol-shaped. Your app plugs in the seams:
 
 ### App (`createMcpApp`)
 
+Prefer `signedTokenAuth({ secret, resolveUser, loginUrl, codeStore })` to fill
+`codeSecret` / `mintAccessToken` / `verifyToken` from one secret. The table
+below is the advanced port surface when you outgrow the helper.
+
 | Port | Role |
 |------|------|
 | `verifyToken(token, req)` | Decode a bearer and return `{ userId, scopes, audience, claims? }`, or `null`. **The library compares `audience` against this server's canonical resource** — you cannot forget the check. Optional `claims` are passed to `context` on `principal` |

package/docs/reference.md

@@ -157,6 +157,7 @@ A single-scope server has no such ambiguity and is unaffected.
 - `defineTool`, `apiTool` — typed, validated tool authoring on top of `ToolDef`. `apiTool`'s `timeoutMs` (default 30000, or `false` to disable) and `maxResponseBytes` (default 1 MiB) bound the upstream call; either surfaces as `isError: true`, not a thrown exception
 - `CLIENT_PROFILES`, `DEFAULT_CLIENTS`, `authMethodsFor`, `redirectUrisFor`, `preRegisteredClients`, `hasDynamicClient`
 - `parseBearer`, `wwwAuthenticateHeader`, `rejectQueryToken`
+- `signedTokenAuth` — one-secret convenience `McpAppAuth` (HMAC access tokens via HKDF; no refresh/revoke). Type `SignedTokenAuthOptions`
 - `rpcResult`, `rpcError`, JSON-RPC error constants
 - `PROTOCOL_VERSIONS`, `DEFAULT_PROTOCOL_VERSION`
 - `jsonResponse({ data, status?, headers?, cors? })` — type `JsonResponseInput` exported

package/docs/security.md

@@ -43,7 +43,7 @@ This is a **library** threat model, not a third-party audit badge.
 | CIMD fetch as SSRF proxy (attacker supplies `https://…` `client_id`) | **Off by default** (`cimd: true` to enable). When on: HTTPS-only fetch, private/loopback/link-local/NAT64/`::ffff:` blocked (incl. bracketed IPv6 **and full-form mapped encodings DNS may return**, e.g. `0:0:0:0:0:ffff:7f00:1`), DNS lookup required before fetch and re-checked after the body, unparseable IPv6 lookup results fail closed, 5 KB stream-capped body / 10 s per hop covering the body read / 3 same-origin redirects (cross-origin redirects rejected), public clients only, `http:` redirect_uris loopback-only (`127.0.0.1` / `[::1]`, never `localhost`). Also blocked: `192.0.0/24`, `198.18/15`, multicast/reserved `224/4`–`240/4`, IPv6 multicast `ff00::/8`, 6to4 `2002::/16`, IPv4-compatible `::a.b.c.d` (and full-form private embeds). `/token` and `/revoke` **re-resolve** CIMD — never accept URL-shaped ids by shape alone; pass `cimdCache` (strongly recommended) or every refresh/revoke re-fetches the document, and a failed re-resolve is audited as `cimd_resolve_failed`. **Ceiling:** TCP connect is not pinned to the looked-up addresses (zero-dep Web `fetch`); classic DNS rebinding between lookup and connect remains possible until a custom dispatcher pins the IP — do not treat CIMD as production-complete SSRF defense until then |
 | Naming only confidential clients doesn't actually block public ones | `clients: ["gemini"]` (or `allowUnregisteredClients: false`) is **enforced**: DCR unmounted, dropped from AS metadata, unresolved `client_id` rejected with `unauthorized_client` at `authorize` and `invalid_client` at `token` and `revoke` |
 | DCR / token-endpoint abuse | Edge or reverse-proxy rate limiting on `/register` and `/token`, **plus** a library-enforced request body cap (see "Also designed in") — the library does not rate-limit by request count, but an unbounded body was previously a memory-exhaustion vector on its own regardless of rate |
-| A weak or copy-pasted `codeSecret` (it can forge an auth code — or, since 0.3.0, a consent ticket or DCR client assertion — for any userId/scope/resource) | Validated at the point of use: a string or array form throws at `createOAuthRouter` construction (every array entry checked, and the array itself must be non-empty), a function form on every call. Minimum 32 characters per entry, and the exact literals this package's own docs and examples have published are denylisted by name, as is any secret containing the examples' `do-not-reuse` marker — copy-paste is the realistic failure mode. The examples themselves read `OAUTH_CODE_SECRET` / `ACCESS_TOKEN_SECRET` from the environment and ship no usable default, and a test fails if any `codeSecret` literal in `examples/`, `README.md` or `docs/` is one the library would accept. This only catches the obvious cases; a leaked or brute-forceable 32+ character secret is still a full bypass, same as before |
+| A weak or copy-pasted `codeSecret` (it can forge an auth code — or, since 0.3.0, a consent ticket or DCR client assertion — for any userId/scope/resource) | Validated at the point of use: a string or array form throws at `createOAuthRouter` construction (every array entry checked, and the array itself must be non-empty), a function form on every call. Minimum 32 characters per entry, and the exact literals this package's own docs and examples have published are denylisted by name, as is any secret containing the examples' `do-not-reuse` marker — copy-paste is the realistic failure mode. The examples themselves read `MCP_SECRET` (or `OAUTH_CODE_SECRET` for the advanced multi-secret recipes) from the environment and ship no usable default, and a test fails if any `codeSecret` literal in `examples/`, `README.md` or `docs/` is one the library would accept. This only catches the obvious cases; a leaked or brute-forceable 32+ character secret is still a full bypass, same as before |
 | An operator unable to diagnose *why* a client was rejected, once `/token`/`/revoke` collapsed every failure to one generic `invalid_client` (see the enumeration-oracle row above) | `OAuthPorts.audit` (and `McpAppAuth.audit` on `createMcpApp`) — opt-in, sees the real reason (`"client requires client_secret_basic, got none"`, a rejected `codeSecret`'s actual message, …) that never reaches the caller. Same "never fails the request" guarantee as the MCP-side `audit` port |
 | A hanging `ports.audit` sink stalling every audited response indefinitely | `auditTimeoutMs` (default 1000ms) on both `McpHandlerOptions` and `OAuthRouterOptions` races the audit call against a timeout; "can't fail a request" already held, this adds "can't delay one" past a bound. A slow sink keeps running in the background and its own internal `catch` means it can never surface as an unhandled rejection later |
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mcp-trellis",
-  "version": "2.1.0",
-  "description": "Build secure remote MCP servers for Claude, ChatGPT and Gemini using your existing auth.",
+  "version": "2.2.0",
+  "description": "Add authenticated remote MCP connectors to existing TypeScript SaaS apps using your existing users and auth.",
   "type": "module",
   "license": "MIT",
   "sideEffects": false,
@@ -27,7 +27,11 @@
     "authorization-server",
     "connector",
     "typescript",
-    "mcp-server"
+    "mcp-server",
+    "saas",
+    "remote-mcp",
+    "byo-auth",
+    "ai-connector"
   ],
   "types": "./dist/server.d.ts",
   "exports": {