@vantageos/mcp-boilerplate 0.2.0 → 0.2.2

package/docs/oauth-stores.md

@@ -5,6 +5,17 @@ in-memory adapters ship for tests and single-process development; a production d
 more than one instance (or one that restarts) MUST inject durable adapters through
 `AuthorizationServerDeps` (`buildHttpApp({ authMode: "oauth", authorizationServer: { codeStore, clientRegistry } })`).
 
+## Production guard
+
+The in-memory adapters lose every code and client on restart and cannot be shared by a second
+instance. With `NODE_ENV=production`, `createAuthorizationServer` therefore THROWS at boot unless
+both `codeStore` and `clientRegistry` are injected, or `MCP_ALLOW_IN_MEMORY_STORES=1` is set
+(exactly `1`; the override logs a warning on every start). Use the override only for a
+single-instance deployment that accepts forgetting codes and DCR clients on restart (for example
+a verification instance). The in-memory adapters are bounded: codes expire out of memory and the
+used set is pruned past each code's expiry; registered clients expire after 30 days and the oldest
+is evicted at the cap.
+
 ## `AuthorizationCodeStore` (cloud-identity type, `src/oauth/codeStore.ts`)
 
 ```ts
@@ -53,7 +64,7 @@ in-process).
 ## CIMD fetch and DNS rebinding
 
 `resolveCimdClient` accepts an https URL with a path only, refuses any host that resolves to a
-non-public address (loopback, private, link-local, CGNAT, multicast, and the IPv4-mapped, IPv4-compatible and NAT64 spellings of those, in any textual form), follows no
+non-public address (loopback, private, link-local, CGNAT, multicast, and the IPv4-mapped, IPv4-compatible, NAT64, IPv4-translated (`::ffff:0:0/96`) and 6to4 (`2002::/16`) spellings of those, in any textual form; Teredo `2001::/32` is refused whole), follows no
 redirect, reads at most 16 KiB (streamed, the read is cancelled once the cap is crossed) and gives up after 5 s. It resolves the host and then `fetch`
 resolves it again, so a DNS-rebinding window exists. A deployment on a hostile network injects a
 `fetchImpl` that connects to the validated address (for example an undici dispatcher with a

package/examples/oauth.env.example

@@ -23,3 +23,13 @@ MCP_OAUTH_SIGNING_JWK=
 # AUTHORIZE_AUTHORIZED_PARTIES=
 # Optional: dedicated sandbox origin of the MCP Apps widget (host-dependent).
 # MCP_UI_DOMAIN=
+
+# Number of trusted reverse proxies in front of this server (default 0): the /register rate limit
+# keys on the socket address, or on the X-Forwarded-For entry the N-th proxy appended.
+# MCP_TRUSTED_PROXY_COUNT=1
+# NODE_ENV=production refuses the in-memory stores; exactly "1" accepts them (single instance).
+# MCP_ALLOW_IN_MEMORY_STORES=1
+# Largest request body the Node entry accepts, in bytes (default 1048576); over it answers 413.
+# MCP_MAX_BODY_BYTES=1048576
+# Browser origins allowed to call /register cross-origin (comma-separated; default none).
+# MCP_REGISTER_CORS_ORIGINS=https://inspector.example.com

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vantageos/mcp-boilerplate",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Clonable MCP server skeleton on the official @modelcontextprotocol/server SDK v2 (protocol 2026-07-28 + 2025 legacy, stdio + stateless Streamable HTTP), with its own OAuth 2.1 authorization server (Clerk person + organisation, cloud-identity), MCP Apps UI, tenant scoping, FR/EN i18n and a declarative eval harness.",
   "description_fr": "Squelette de serveur MCP clonable sur le SDK officiel @modelcontextprotocol/server v2 (protocole 2026-07-28 + héritage 2025, stdio + Streamable HTTP sans état), avec son propre serveur d'autorisation OAuth 2.1 (personne + organisation Clerk, cloud-identity), UI MCP Apps, scoping tenant, i18n FR/EN et un harnais d'évaluations déclaratif.",
   "type": "module",
@@ -28,6 +28,7 @@
     "mcp.json",
     "skills",
     "scripts/plugin-manifest.source.json",
+    "scripts/generate-signing-key.mjs",
     "docs",
     "examples/claude-desktop.json",
     "examples/oauth.env.example"
@@ -74,9 +75,9 @@
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^2.0.3",
     "@modelcontextprotocol/server": "^2.3.1",
-    "@vantageos/cloud-identity": "^0.15.0",
+    "@vantageos/cloud-identity": "^0.17.0",
     "@vantageos/mosaic-i18n": "^0.1.1",
-    "hono": "^4.6.0",
+    "hono": "^4.13.13",
     "jose": "^6.2.7",
     "zod": "^4.4.3"
   },
@@ -90,8 +91,7 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "typescript": "^5.7.2",
-    "vite": "^5.4.0",
-    "vite-plugin-singlefile": "^2.0.0",
-    "vitest": "^2.1.8"
+    "vite": "^8.3.4",
+    "vitest": "^5.0.3"
   }
 }

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "vantage-mcp-boilerplate",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Clonable MCP server template: SDK v2 on protocol 2026-07-28 (stdio + stateless Streamable HTTP), its own OAuth 2.1 authorization server (Clerk person + organisation), MCP Apps UI, FR/EN i18n and a declarative eval harness. Scaffold, extend, publish.",
   "author": {
     "name": "ElPi Corp / Laurent Perello"

package/scripts/generate-signing-key.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * Prints a fresh RS256 private JWK on stdout, ready to be stored as the MCP_OAUTH_SIGNING_JWK
+ * secret of the authorization server. The key id is the RFC 7638 thumbprint, so it is derived,
+ * never typed. Nothing is written to disk; pipe it straight into your secret manager.
+ */
+import { calculateJwkThumbprint, exportJWK, generateKeyPair } from "jose";
+
+const { privateKey } = await generateKeyPair("RS256", { modulusLength: 3072, extractable: true });
+const jwk = await exportJWK(privateKey);
+jwk.kid = await calculateJwkThumbprint(jwk);
+jwk.alg = "RS256";
+jwk.use = "sig";
+process.stdout.write(`${JSON.stringify(jwk)}\n`);