@vantageos/mcp-boilerplate 0.2.1 → 0.2.3

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "vantage-mcp-boilerplate",
   "displayName": "VantageOS MCP Boilerplate",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "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/CHANGELOG.md

@@ -7,6 +7,96 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.2.3] - 2026-10-11
+
+### Added
+
+- `/authorize/callback` resolves the person's Clerk session with Clerk's own handshake
+  (`@vantageos/cloud-identity` `^0.19.0`, `resolveClerkSessionFromRequest`, built on
+  `@clerk/backend` `authenticateRequest()`). A return from Clerk's hosted sign-in with no session
+  on this host used to answer `403 session-required`; it now redirects through the handshake and
+  continues. An explicit Bearer token and injected Clerk collaborators keep their path. The
+  publishable key is `CLERK_PUBLISHABLE_KEY` or derived from `CLERK_DOMAIN`.
+- README section "Sign-in with ChatGPT and Claude" (EN + FR): the production instance on the
+  server's own registrable domain, the three URLs including `AUTHORIZE_SIGN_IN_URL`, why no
+  redirect URL is registered, development-instance limits, how the session arrives, what is and
+  is not yet measured.
+- The handshake redirect carries `Cache-Control: no-store`, and a forged or stale
+  `__clerk_handshake` continues signed out instead of answering 500.
+- Boot warning (EN + FR) when the Clerk instance is a development one (`sk_test_` key or an
+  `accounts.dev` domain) and `PUBLIC_BASE_URL` is not localhost: it names the Home URL
+  requirement. A warning, never a refusal.
+
+### Fixed
+
+- The Node adapter emitted only the last `Set-Cookie` of a response. A response with N cookies
+  now yields N (Clerk's handshake return sets five).
+- The deny route (`POST /authorize/org` with `approved=false`) forwards `consentToken`;
+  cloud-identity 0.18 and later verify it on a denial too.
+
+- CIMD: a Client ID Metadata Document that declares `token_endpoint_auth_method` other than
+  `none` (for example ChatGPT's `private_key_jwt`) is now accepted when its
+  `token_endpoint_auth_methods_supported` includes `none`. A document with neither is still
+  refused. All other checks (client_id equality, https, SSRF guard, size cap, redirect_uris)
+  are unchanged. `/authorize` no longer answers `unknown-client` for ChatGPT.
+- `/token` verifies a `private_key_jwt` client assertion instead of ignoring it: keys from the
+  CIMD document's `jwks_uri` (same SSRF-guarded fetch), RS256 only, `iss` = `sub` = `client_id`,
+  `aud` = the token endpoint or the issuer, `exp` required (30 s skew), `jti` required and
+  accepted once (bounded in-memory set, fail closed when full). Any failure answers 401
+  `invalid_client`. A request without an assertion keeps the public-client path (`client_id` +
+  PKCE). AS metadata advertises `["none","private_key_jwt"]` and RS256.
+
+## [0.2.2] - 2026-10-10
+
+### Security
+
+- Consent page shows the ORIGIN the authorization code is sent to and the requested scope, and
+  flags a Dynamic-Client-Registration client as unverified (FR + EN).
+- `/register` rate limit keys on the socket address, or on the `X-Forwarded-For` entry the
+  N-th trusted proxy appended (`MCP_TRUSTED_PROXY_COUNT`, default 0); a client-supplied first
+  entry no longer bypasses it.
+- In-memory client registry expires registrations (30 days) and evicts the oldest at the cap
+  instead of refusing forever; in-memory code store drops expired codes and prunes its used set.
+- `NODE_ENV=production` refuses the in-memory stores unless both durable adapters are injected
+  or `MCP_ALLOW_IN_MEMORY_STORES=1` is set (explicit, logged opt-in).
+- The Node entry caps the request body (`MCP_MAX_BODY_BYTES`, default 1 MiB): `413` before any
+  handler runs, counted while the body streams in.
+- `/mcp` enforces the `mcp:full` scope on the own-authorization-server tier (`403
+  insufficient_scope`).
+- Clerk Backend calls time out (5 s); organisation memberships are paginated past 100 and fail
+  loudly rather than truncate past 5 000.
+- `http:` issuer, sign-in and callback URLs are refused outside loopback.
+- A consent denial answers the OAuth error redirect (`error=access_denied`, `state`, `iss`)
+  instead of a `403` JSON body; the redirect target is read only from a state the flow verified.
+- `/register` sends no CORS headers unless the origin is listed in `MCP_REGISTER_CORS_ORIGINS`.
+- SSRF guard also blocks the IPv4 ranges embedded in IPv4-translated (`::ffff:0:0/96`) and
+  6to4 (`2002::/16`) addresses, and refuses Teredo (`2001::/32`).
+
+- A SET but invalid `MCP_MAX_BODY_BYTES`, `MCP_TRUSTED_PROXY_COUNT`, `MCP_REGISTER_CORS_ORIGINS`
+  or `MCP_ALLOW_IN_MEMORY_STORES` refuses to start, naming the variable and what was expected
+  (the value is never echoed); unset or empty keeps the default. No silent fallback.
+- SSRF guard reads the IPv4 embedded in ISATAP addresses (interface id `0000:5efe` /
+  `0200:5efe`, any prefix) and refuses it when that IPv4 is in a blocked range.
+
+- `@vantageos/cloud-identity` ^0.17.0: the consent page reads `OrgPickerModel.redirectOrigin` and a
+  denial is `resumeAuthorize({ denied: true })` (a verified redirect-to-client, `iss` appended in
+  one place). The local authorize-state parser (`src/oauth/stateBlob.ts`) is removed.
+
+### Changed
+
+- `createInMemoryClientRegistry` takes an options object (`maxClients`, `ttlSeconds`, `now`)
+  instead of a bare number; `createInMemoryCodeStore` takes `{ now, maxEntries }` and exposes
+  `stats()`; `renderOrgPicker` takes a third `ConsentContext` argument (`redirectUri`,
+  `unverified`).
+- `tests/toolRecordComplete.test.ts` asserts the four annotations are declared booleans, not
+  fixed values (a fork's write tool is rightly `readOnlyHint: false`).
+
+### Dependencies
+
+- `hono` 4.13.13, `vitest` 5, `vite` 8. `vite-plugin-singlefile` is removed (its
+  `micromatch` -> `braces` chain has an advisory with no patched release); `vite.config.ts`
+  inlines the bundle itself. `npm audit`: 0 critical, 0 high.
+
 ## [0.2.1] - 2026-10-10
 
 ### Fixed

package/README.fr.md

@@ -122,11 +122,79 @@ interfaces avec adaptateurs en mémoire pour les tests et le développement
 mono-processus. Utilisez des adaptateurs durables en production — contrat dans
 [`docs/oauth-stores.md`](docs/oauth-stores.md).
 
+**Garde de production** : avec `NODE_ENV=production`, le serveur refuse de démarrer
+sur les stores en mémoire (codes et clients enregistrés perdus au redémarrage, non
+partagés entre instances) sauf si les deux adaptateurs durables sont injectés ou si
+`MCP_ALLOW_IN_MEMORY_STORES=1` est défini — un choix explicite et journalisé pour un
+déploiement mono-instance. Derrière un reverse proxy, réglez `MCP_TRUSTED_PROXY_COUNT`
+sur le nombre de proxys de confiance (défaut `0`) : la limite de débit de `/register`
+se fonde alors sur l'entrée `X-Forwarded-For` ajoutée par le proxy, jamais sur la
+première, fournie par le client ; avec `0`, elle se fonde sur l'adresse du socket et
+ignore l'en-tête.
+
+**Limites de requête et CORS** : Une variable d'exploitation définie mais invalide (par exemple `MCP_MAX_BODY_BYTES=abc`) arrête le serveur au démarrage avec le nom de la variable et la forme attendue, jamais un défaut silencieux ; non définie ou vide, le défaut s'applique. l'entrée Node lit au plus `MCP_MAX_BODY_BYTES`
+(défaut 1 Mio) du corps d'une requête et répond `413` avant tout handler.
+`/register` n'envoie aucun en-tête CORS sauf si l'origine du navigateur figure dans
+`MCP_REGISTER_CORS_ORIGINS` (séparées par des virgules). `/mcp` exige le scope
+`mcp:full` sur le palier serveur d'autorisation propre (`403 insufficient_scope`
+sinon). La page de consentement affiche l'origine vers laquelle le code est envoyé et
+le scope demandé, signale comme non vérifié un client issu de l'enregistrement
+dynamique, et un refus redirige vers le client avec `error=access_denied` (plus
+`state` et `iss`). Les URL `http:` d'émetteur, de connexion et de rappel sont refusées
+hors boucle locale.
+
 **Non inclus** : jetons de rafraîchissement (les jetons d'accès durent une heure),
 clés d'API par organisation pour les clients hors ChatGPT (ce code n'a jamais eu ce
 chemin ; c'est un manque, pas une régression), URI de redirection à joker, et liste
 de révocation des jetons.
 
+### Connexion avec ChatGPT et Claude
+
+ChatGPT et Claude envoient la personne sur le `/authorize` de ce serveur, qui l'envoie vers la
+page de connexion hébergée par Clerk puis la ramène sur `/authorize/callback`. Pour que cela
+fonctionne sur un serveur que vous hébergez, dans cet ordre :
+
+1. **Utilisez une instance Clerk de PRODUCTION sur le domaine enregistrable du serveur.** Un
+   serveur sur `mcp.example.com` prend le domaine Clerk `example.com` : Clerk sert alors
+   `clerk.example.com` et `accounts.example.com`. Tout autre domaine relève d'une configuration
+   satellite, non mesurée. Ajoutez les CNAME DNS listés par le tableau de bord Clerk. Créez votre propre client OAuth Google
+   avec l'URI de redirection autorisée `https://clerk.<domaine>/v1/oauth_callback`, renseignez
+   son identifiant et son secret dans le tableau de bord Clerk, et publiez l'écran de
+   consentement Google avec une page d'accueil d'application et une politique de
+   confidentialité (un écran non publié n'admet que les utilisateurs de test).
+2. **Réglez les trois URL.** `PUBLIC_BASE_URL` = `https://<serveur>` ; `AUTHORIZE_CALLBACK_URL`
+   = `https://<serveur>/authorize/callback` ; `AUTHORIZE_SIGN_IN_URL` = la page de connexion
+   hébergée de l'instance : `https://accounts.<domaine>/sign-in` en production,
+   `https://<instance>.accounts.dev/sign-in` en développement (l'URL de l'Account Portal,
+   affichée dans le tableau de bord Clerk sous **Account Portal**). Ce parcours n'a aucune
+   « URL de redirection autorisée » à remplir dans le tableau de bord : la page hébergée ne
+   renvoie le navigateur que vers un hôte du domaine de l'instance (production, selon la
+   documentation Clerk, pas encore mesuré) ou vers `localhost` / la Home URL (développement,
+   mesuré). C'est pourquoi l'étape 1 met le serveur et l'instance sur un même domaine.
+   *Mesuré* : la liste `redirect_urls` de l'API Backend n'est pas consultée par les pages
+   hébergées.
+3. **Une instance de développement sert uniquement en local ou en test.** Sa page de connexion
+   hébergée ne redirige que vers `localhost` ou vers l'URL d'accueil (Home URL) de l'instance.
+   Pour un test distant, réglez l'origine de développement / Home URL de l'instance de
+   développement sur l'origine du serveur dans le tableau de bord Clerk, faites le test, puis
+   rétablissez-la.
+4. **Comment la session arrive au serveur.** Après la connexion, le navigateur revient sur
+   `/authorize/callback` sans session sur votre hôte. Le serveur la résout avec la poignée de
+   main (handshake) propre à Clerk (`@vantageos/cloud-identity` 0.19.0, fondé sur
+   `authenticateRequest()` de `@clerk/backend`) : il redirige le navigateur par le point
+   d'entrée handshake de Clerk, et Clerk pose `__session` sur votre hôte. Il faut
+   `CLERK_SECRET_KEY` et la clé publiable : `CLERK_PUBLISHABLE_KEY`, ou, à défaut, dérivée de
+   `CLERK_DOMAIN` sous la forme `pk_test_` / `pk_live_` (selon la clé secrète) +
+   base64(`<hôte de l'API Frontend>$`). *Mesuré* : une instance de développement avec un serveur
+   distant fonctionne dès que sa Home URL pointe sur le serveur. *Pas encore mesuré* : une
+   instance de production sur un domaine enregistrable différent de celui du serveur.
+5. **Avertissement au démarrage.** Quand l'instance configurée est de développement (clé
+   `sk_test_`, ou `CLERK_DOMAIN` sous `accounts.dev`) et que `PUBLIC_BASE_URL` n'est pas
+   localhost, le serveur écrit un avertissement au démarrage, en anglais et en français, qui
+   nomme l'exigence de Home URL. C'est un avertissement, jamais un refus : il signifie « une
+   connexion distante ne marchera que si la Home URL pointe sur ce serveur, ou si vous passez à
+   une instance de production ». Il ne contient ni clé ni secret.
+
 ### Multi-tenance
 
 `list_items` filtre les lignes par leur `orgId` stocké face à l'organisation
@@ -217,11 +285,11 @@ de `npm publish`.
   qui ne négocient jamais l'extension.
 
 Le widget (`src/ui/`) réutilise une famille `MosaicCard` vendorisée et est empaqueté
-en un seul fichier HTML autonome (`vite-plugin-singlefile`,
+en un seul fichier HTML autonome (un plugin d'inlining local dans `vite.config.ts`,
 `dist/ui-bundle/widget.html`) par `npm run build:ui`, sur un chemin qui n'entre
 jamais en collision avec `dist/ui/` de tsc.
 
-**Couche d'identité** : `@vantageos/cloud-identity` (^0.15.0) est le seul paquet
+**Couche d'identité** : `@vantageos/cloud-identity` (^0.19.0) est le seul paquet
 d'identité. Son point d'entrée resource-server (`verifyMcpAccessToken`,
 `buildProtectedResourceMetadata`) vérifie le jeton Bearer sur `/mcp` ; `jose` ne sert
 plus qu'à signer les jetons d'accès du serveur d'autorisation. Un jeu de clés

package/README.md

@@ -118,10 +118,72 @@ log (names, never values). There is no auto-approve path.
 with in-memory adapters for tests and single-process development. Use durable
 adapters in production — contract in [`docs/oauth-stores.md`](docs/oauth-stores.md).
 
+**Production guard**: with `NODE_ENV=production` the server refuses to start on
+the in-memory stores (codes and registered clients are lost on restart and not
+shared between instances) unless both durable adapters are injected or
+`MCP_ALLOW_IN_MEMORY_STORES=1` is set — an explicit, logged opt-in for a
+single-instance deployment. Behind a reverse proxy set `MCP_TRUSTED_PROXY_COUNT`
+to the number of trusted proxies (default `0`): the `/register` rate limit then
+keys on the proxy-appended `X-Forwarded-For` entry, never on the client-supplied
+first one; with `0` it keys on the socket address and ignores the header.
+
+**Request limits and CORS**: An operator variable that is set but invalid (for example `MCP_MAX_BODY_BYTES=abc`) stops the server at startup with the variable's name and the expected form, never a silent default; unset or empty keeps the default. the Node entry reads at most `MCP_MAX_BODY_BYTES`
+(default 1 MiB) of a request body and answers `413` before any handler runs.
+`/register` sends no CORS headers unless the browser origin is listed in
+`MCP_REGISTER_CORS_ORIGINS` (comma-separated). `/mcp` requires the `mcp:full`
+scope on the own-authorization-server tier (`403 insufficient_scope` otherwise).
+The consent page shows the origin the code is sent to and the requested scope,
+flags a Dynamic-Client-Registration client as unverified, and a denial redirects
+to the client with `error=access_denied` (plus `state` and `iss`). `http:` issuer,
+sign-in and callback URLs are refused outside loopback.
+
 **Not included**: refresh tokens (access tokens last one hour), per-organisation
 API keys for non-ChatGPT clients (this code never had that path; it is a gap, not
 a regression), wildcard redirect URIs, and a token revocation list.
 
+### Sign-in with ChatGPT and Claude
+
+ChatGPT and Claude send the person to this server's `/authorize`, which sends them to
+Clerk's hosted sign-in and takes them back to `/authorize/callback`. To make that work on a
+server you host, in this order:
+
+1. **Use a Clerk PRODUCTION instance on the server's own registrable domain.** A server at
+   `mcp.example.com` takes the Clerk domain `example.com`, so Clerk serves `clerk.example.com`
+   and `accounts.example.com`. Any other domain is a satellite setup and is not measured. Add
+   the DNS CNAMEs the Clerk dashboard lists. Create your own Google OAuth client with the authorized redirect URI
+   `https://clerk.<domain>/v1/oauth_callback`, put its id and secret in the Clerk dashboard, and
+   publish the Google consent screen with an application home page and a privacy policy (an
+   unpublished consent screen only lets test users in).
+2. **Set the three URLs.** `PUBLIC_BASE_URL` = `https://<server>`; `AUTHORIZE_CALLBACK_URL` =
+   `https://<server>/authorize/callback`; `AUTHORIZE_SIGN_IN_URL` = the instance's hosted
+   sign-in page: `https://accounts.<domain>/sign-in` on production,
+   `https://<instance>.accounts.dev/sign-in` on development (the Account Portal URL, shown in
+   the Clerk dashboard under **Account Portal**). There is no "allowed redirect URL" to fill in
+   the dashboard for this flow: the hosted page sends the browser back only to a host under
+   the instance's own domain (production, per Clerk's documentation, not yet measured) or to
+   `localhost` / the Home URL (development, measured). This is why step 1 puts the server and
+   the instance on one domain. *Measured*: the Backend API `redirect_urls` list is not
+   consulted by the hosted pages.
+3. **A development instance is for local or test use only.** Its hosted sign-in page redirects
+   only to `localhost` or to the instance Home URL. For a remote test, set the development
+   instance's development origin / Home URL to the server origin in the Clerk dashboard, run
+   the test, and revert it afterwards.
+4. **How the session reaches the server.** After sign-in the browser comes back to
+   `/authorize/callback` without a session on your host. The server resolves it with Clerk's
+   own handshake (`@vantageos/cloud-identity` 0.19.0, built on `@clerk/backend`
+   `authenticateRequest()`): it redirects the browser through Clerk's handshake endpoint and
+   Clerk sets `__session` on your host. It needs `CLERK_SECRET_KEY` and the publishable key:
+   `CLERK_PUBLISHABLE_KEY`, or, when unset, derived from `CLERK_DOMAIN` as
+   `pk_test_` / `pk_live_` (following the secret key) + base64(`<frontend API host>$`).
+   *Measured*: a development instance with a remote server works once its Home URL points at
+   the server. *Not yet measured*: a production instance on a registrable domain different
+   from the server's.
+5. **Boot warning.** When the configured instance is a development one (an `sk_test_` key, or
+   a `CLERK_DOMAIN` under `accounts.dev`) and `PUBLIC_BASE_URL` is not localhost, the server
+   logs one warning at boot, in English and French, naming the Home URL requirement. It is a
+   warning, never a refusal: it means "a remote sign-in will only work if the Home URL points
+   at this server, or if you move to a production instance". It carries no key or secret.
+
 ### Multi-tenancy
 
 `list_items` filters rows by their stored `orgId` against the caller's verified
@@ -211,11 +273,11 @@ Publication is proven at the registry's `dist-tag`, never by the exit code of
   negotiate the extension.
 
 The widget (`src/ui/`) reuses a vendored `MosaicCard` family and is bundled to
-one self-contained HTML file (`vite-plugin-singlefile`,
+one self-contained HTML file (an in-repo inlining plugin in `vite.config.ts`,
 `dist/ui-bundle/widget.html`) by `npm run build:ui`, on a path that never
 collides with tsc's `dist/ui/`.
 
-**Identity layer**: `@vantageos/cloud-identity` (^0.15.0) is the only identity
+**Identity layer**: `@vantageos/cloud-identity` (^0.19.0) is the only identity
 package. Its resource-server entry point (`verifyMcpAccessToken`,
 `buildProtectedResourceMetadata`) verifies the Bearer token on `/mcp`; `jose` is
 kept only to mint the authorization server's access tokens. An unreachable key set

package/dist/envKnobs.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Operator knobs read from the environment. UNSET (or empty) means the default; a value that is
+ * SET and invalid throws at startup, naming the variable and what was expected. The value is
+ * never echoed (it may be a secret pasted into the wrong variable) and never replaced by the
+ * default: a silent fallback would run the server on a setting its operator did not choose.
+ */
+/** The raw value, or undefined when the variable is unset or empty. */
+export declare function rawKnob(env: NodeJS.ProcessEnv, name: string): string | undefined;
+/** A base-10 integer within [min, max]; undefined when unset. */
+export declare function integerKnob(env: NodeJS.ProcessEnv, name: string, min: number, max?: number): number | undefined;
+/** Exactly "0" or "1"; undefined when unset. */
+export declare function flagKnob(env: NodeJS.ProcessEnv, name: string): boolean | undefined;
+/** A comma-separated list of origins (`scheme://host[:port]`, http or https, no path). */
+export declare function originListKnob(env: NodeJS.ProcessEnv, name: string): string[];

package/dist/envKnobs.js

@@ -0,0 +1,54 @@
+/**
+ * Operator knobs read from the environment. UNSET (or empty) means the default; a value that is
+ * SET and invalid throws at startup, naming the variable and what was expected. The value is
+ * never echoed (it may be a secret pasted into the wrong variable) and never replaced by the
+ * default: a silent fallback would run the server on a setting its operator did not choose.
+ */
+/** The raw value, or undefined when the variable is unset or empty. */
+export function rawKnob(env, name) {
+    const raw = env[name];
+    return raw === undefined || raw === "" ? undefined : raw;
+}
+/** A base-10 integer within [min, max]; undefined when unset. */
+export function integerKnob(env, name, min, max = Number.MAX_SAFE_INTEGER) {
+    const raw = rawKnob(env, name);
+    if (raw === undefined)
+        return undefined;
+    const n = /^\d+$/.test(raw) ? Number(raw) : Number.NaN;
+    if (!Number.isSafeInteger(n) || n < min || n > max) {
+        const range = max === Number.MAX_SAFE_INTEGER ? `at least ${min}` : `from ${min} to ${max}`;
+        throw new Error(`${name} is set but invalid: expected ${min > 0 ? "a positive" : "a non-negative"} integer ${range} (value not shown)`);
+    }
+    return n;
+}
+/** Exactly "0" or "1"; undefined when unset. */
+export function flagKnob(env, name) {
+    const raw = rawKnob(env, name);
+    if (raw === undefined)
+        return undefined;
+    if (raw !== "0" && raw !== "1") {
+        throw new Error(`${name} is set but invalid: expected "0" or "1" (value not shown)`);
+    }
+    return raw === "1";
+}
+/** A comma-separated list of origins (`scheme://host[:port]`, http or https, no path). */
+export function originListKnob(env, name) {
+    const raw = rawKnob(env, name);
+    if (raw === undefined)
+        return [];
+    const origins = raw.split(",").map((entry) => entry.trim());
+    for (const entry of origins) {
+        let ok = false;
+        try {
+            const url = new URL(entry);
+            ok = (url.protocol === "https:" || url.protocol === "http:") && url.origin === entry;
+        }
+        catch {
+            ok = false;
+        }
+        if (!ok) {
+            throw new Error(`${name} is set but invalid: expected a comma-separated list of origins like https://app.example.com (scheme, host, optional port; no path, no "*") (value not shown)`);
+        }
+    }
+    return origins;
+}

package/dist/http.js

@@ -1,5 +1,6 @@
 import { loadAuthConfig, loadAuthMode } from "./config.js";
 import { buildHttpApp } from "./httpApp.js";
+import { createNodeListener, maxBodyBytesFrom } from "./nodeAdapter.js";
 const authMode = loadAuthMode();
 const uiDomain = process.env.MCP_UI_DOMAIN || undefined;
 // OAuth tier: MCP_OAUTH_ISSUER + MCP_OAUTH_AUDIENCE select an EXTERNAL issuer (resource server
@@ -13,26 +14,9 @@ const app = buildHttpApp(authMode === "oauth"
         : { authMode, authorizationServer: {}, uiDomain }
     : { authMode, uiDomain });
 const port = Number(process.env.PORT ?? 8787);
-// Hono's fetch handler adapted onto Node's http server (no extra framework
-// dependency beyond hono + node:http).
+// Hono's fetch handler adapted onto Node's http server, with the request-body cap
+// (MCP_MAX_BODY_BYTES, default 1 MiB) enforced while the body streams in: src/nodeAdapter.ts.
 const { createServer } = await import("node:http");
-createServer(async (req, res) => {
-    const url = `http://${req.headers.host ?? "localhost"}${req.url}`;
-    const chunks = [];
-    for await (const chunk of req)
-        chunks.push(chunk);
-    const body = req.method === "GET" || req.method === "HEAD" ? undefined : Buffer.concat(chunks);
-    const headers = new Headers();
-    for (const [key, value] of Object.entries(req.headers)) {
-        if (typeof value === "string")
-            headers.set(key, value);
-    }
-    const request = new Request(url, { method: req.method, headers, body });
-    const response = await app.fetch(request);
-    res.statusCode = response.status;
-    response.headers.forEach((value, key) => res.setHeader(key, value));
-    const buf = Buffer.from(await response.arrayBuffer());
-    res.end(buf);
-}).listen(port, () => {
+createServer(createNodeListener(app, { maxBodyBytes: maxBodyBytesFrom(process.env) })).listen(port, () => {
     console.log(`mcp-boilerplate HTTP transport listening on :${port} (authMode: ${authMode})`);
 });

package/dist/httpApp.js

@@ -23,11 +23,13 @@
  *    trusted (mirrors stdio's trust model). The DEFAULT when `buildHttpApp()` gets no deps.
  */
 import { createMcpHandler } from "@modelcontextprotocol/server";
+import { unauthorizedChallenge } from "@vantageos/cloud-identity";
 import { Hono } from "hono";
 import { authenticateRequest, protectedResourceMetadataDocument } from "./auth.js";
 import { detectLocale, t } from "./i18n.js";
 import { createBoilerplateMcpServer } from "./mcpServerFactory.js";
 import { createAuthorizationServer, } from "./oauth/authorizationServer.js";
+import { MCP_SCOPE } from "./oauth/settings.js";
 import { resolveTenantFromJwtPayload } from "./tenancy.js";
 const PRM_PATHS = [
     "/.well-known/oauth-protected-resource",
@@ -82,6 +84,21 @@ export function buildHttpApp(deps = {}) {
                 c.header("WWW-Authenticate", result.headers["WWW-Authenticate"]);
                 return c.json({ error: t(locale, "auth.unauthorized") }, result.status);
             }
+            // A token must carry the scope this resource is protected by. Only the own-authorization-
+            // server tier knows its scope vocabulary; an external issuer's scopes are its own.
+            if (deps.authorizationServer) {
+                const granted = String(result.session.claims.scope ?? "").split(/\s+/);
+                if (!granted.includes(MCP_SCOPE)) {
+                    const challenge = unauthorizedChallenge({
+                        realm: rs.auth.realm,
+                        resourceMetadataUrl: rs.auth.resourceMetadataUrl,
+                        error: "insufficient_scope",
+                        scope: MCP_SCOPE,
+                    });
+                    c.header("WWW-Authenticate", challenge.headers["WWW-Authenticate"]);
+                    return c.json({ error: "insufficient_scope" }, 403);
+                }
+            }
             // Tenant resolution (tenancy.ts) is attempted here but is NOT request-fatal:
             // `initialize`/`tools/list` and any tenant-agnostic tool (e.g. `ping`) must keep working
             // for a verified caller with no organization on their token. Tenant-scoped tools enforce

package/dist/locales/en.json

@@ -12,11 +12,15 @@
     "oauth": {
       "pickerTitle": "Connect {client}",
       "pickerIntro": "{client} asks to act on your behalf. Choose the organisation it may reach, then approve or deny.",
+      "pickerDestination": "After approval you are sent to:",
+      "pickerScope": "Requested access:",
+      "pickerUnverified": "Unverified client: it registered itself automatically and nobody has vouched for it. Approve only if you recognise the address above.",
       "pickerOrganisation": "Organisation",
       "approve": "Approve",
       "deny": "Deny",
       "denied": "The request was denied; you can close this window.",
-      "unavailable": "Authorization is not configured on this server."
+      "unavailable": "Authorization is not configured on this server.",
+      "devInstanceRemote": "Development Clerk instance on a remote server: its hosted sign-in page redirects only to localhost or to the instance Home URL. Set the development instance's Home URL (development origin) to this server's origin for a remote test and revert it afterwards, or use a Clerk production instance (see README, \"Sign-in with ChatGPT and Claude\")."
     }
   }
 }

package/dist/locales/fr.json

@@ -12,11 +12,15 @@
     "oauth": {
       "pickerTitle": "Connecter {client}",
       "pickerIntro": "{client} demande à agir en votre nom. Choisissez l'organisation à laquelle il peut accéder, puis approuvez ou refusez.",
+      "pickerDestination": "Redirection après validation vers :",
+      "pickerScope": "Accès demandé :",
+      "pickerUnverified": "Client non vérifié : il s'est enregistré automatiquement et personne ne s'en porte garant. N'approuvez que si vous reconnaissez l'adresse ci-dessus.",
       "pickerOrganisation": "Organisation",
       "approve": "Approuver",
       "deny": "Refuser",
       "denied": "La demande a été refusée ; vous pouvez fermer cette fenêtre.",
-      "unavailable": "L'autorisation n'est pas configurée sur ce serveur."
+      "unavailable": "L'autorisation n'est pas configurée sur ce serveur.",
+      "devInstanceRemote": "Instance Clerk de développement sur un serveur distant : sa page de connexion hébergée ne redirige que vers localhost ou vers l'URL d'accueil (Home URL) de l'instance. Pour un test distant, réglez l'URL d'accueil (origine de développement) de l'instance sur l'origine de ce serveur, puis rétablissez-la ; sinon utilisez une instance Clerk de production (voir README, « Connexion avec ChatGPT et Claude »)."
     }
   }
 }

package/dist/nodeAdapter.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Hono's fetch handler adapted onto Node's `http` server (no framework beyond hono + node:http).
+ *
+ * The request body is read here, so the cap lives here: bytes are counted as they stream in and
+ * the read stops the moment the cap is crossed — an oversized body is answered 413 before any
+ * handler runs and is never held whole in memory.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+/** 1 MiB: far above any MCP JSON-RPC request or OAuth form this server accepts. */
+export declare const DEFAULT_MAX_BODY_BYTES = 1048576;
+/** `MCP_MAX_BODY_BYTES`, a positive integer. Unset = default; set and invalid throws. */
+export declare function maxBodyBytesFrom(env: NodeJS.ProcessEnv): number;
+export interface FetchApp {
+    fetch(request: Request, bindings?: {
+        remoteAddress?: string;
+    }): Response | Promise<Response>;
+}
+export declare function createNodeListener(app: FetchApp, options?: {
+    maxBodyBytes?: number;
+}): (req: IncomingMessage, res: ServerResponse) => Promise<void>;

package/dist/nodeAdapter.js

@@ -0,0 +1,71 @@
+/**
+ * Hono's fetch handler adapted onto Node's `http` server (no framework beyond hono + node:http).
+ *
+ * The request body is read here, so the cap lives here: bytes are counted as they stream in and
+ * the read stops the moment the cap is crossed — an oversized body is answered 413 before any
+ * handler runs and is never held whole in memory.
+ */
+import { integerKnob } from "./envKnobs.js";
+/** 1 MiB: far above any MCP JSON-RPC request or OAuth form this server accepts. */
+export const DEFAULT_MAX_BODY_BYTES = 1_048_576;
+/** `MCP_MAX_BODY_BYTES`, a positive integer. Unset = default; set and invalid throws. */
+export function maxBodyBytesFrom(env) {
+    return integerKnob(env, "MCP_MAX_BODY_BYTES", 1) ?? DEFAULT_MAX_BODY_BYTES;
+}
+function tooLarge(res, maxBodyBytes) {
+    res.writeHead(413, { "content-type": "application/json", connection: "close" });
+    res.end(JSON.stringify({
+        error: "payload_too_large",
+        error_description: `request body exceeds ${maxBodyBytes} bytes`,
+    }));
+}
+export function createNodeListener(app, options = {}) {
+    const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+    return async (req, res) => {
+        try {
+            const hasBody = req.method !== "GET" && req.method !== "HEAD";
+            let body;
+            if (hasBody) {
+                const declared = Number(req.headers["content-length"]);
+                if (Number.isFinite(declared) && declared > maxBodyBytes)
+                    return tooLarge(res, maxBodyBytes);
+                const chunks = [];
+                let received = 0;
+                for await (const chunk of req) {
+                    const piece = chunk;
+                    received += piece.byteLength;
+                    if (received > maxBodyBytes)
+                        return tooLarge(res, maxBodyBytes);
+                    chunks.push(piece);
+                }
+                body = new Uint8Array(Buffer.concat(chunks));
+            }
+            const headers = new Headers();
+            for (const [key, value] of Object.entries(req.headers)) {
+                if (typeof value === "string")
+                    headers.set(key, value);
+            }
+            const url = `http://${req.headers.host ?? "localhost"}${req.url}`;
+            const request = new Request(url, { method: req.method, headers, body });
+            const response = await app.fetch(request, { remoteAddress: req.socket.remoteAddress });
+            res.statusCode = response.status;
+            // `forEach` hands back Set-Cookie folded into one value, and setHeader overwrites: several
+            // cookies (Clerk's handshake sets five) would collapse to the last. Emit them as an array.
+            const cookies = response.headers.getSetCookie();
+            response.headers.forEach((value, key) => {
+                if (key.toLowerCase() !== "set-cookie")
+                    res.setHeader(key, value);
+            });
+            if (cookies.length > 0)
+                res.setHeader("Set-Cookie", cookies);
+            res.end(Buffer.from(await response.arrayBuffer()));
+        }
+        catch (err) {
+            console.error("[http] request failed:", err instanceof Error ? err.message : err);
+            if (!res.headersSent) {
+                res.writeHead(500, { "content-type": "application/json" });
+            }
+            res.end(JSON.stringify({ error: "server_error" }));
+        }
+    };
+}

package/dist/oauth/authorizationServer.d.ts

@@ -21,7 +21,7 @@
  * No refresh tokens are issued; access tokens live one hour.
  */
 import { type AuthorizationCodeStore } from "@vantageos/cloud-identity";
-import type { Hono } from "hono";
+import type { Context, Hono } from "hono";
 import type { AuthConfig } from "../auth.js";
 import { type ClerkCollaborators } from "./clerk.js";
 import { type CimdOptions, type ClientRegistry } from "./clientRegistry.js";
@@ -52,5 +52,25 @@ export interface AuthorizationServer {
     /** The resource-server (`/mcp` gate) configuration derived from the same settings. */
     resourceServer(): Promise<ResourceServerConfig>;
 }
+/** Bindings the Node entry (src/http.ts) hands to `app.fetch(request, bindings)`. */
+export interface NodeBindings {
+    /** Address of the TCP peer, from the socket. */
+    remoteAddress?: string;
+}
+/**
+ * The rate-limit key of a request: who is really on the other end.
+ *
+ * `X-Forwarded-For` is client-controlled up to the point a trusted proxy appends to it. With
+ * N trusted proxies the real client is the N-th entry from the END (each proxy appended the
+ * peer it saw); anything left of it was supplied by the client and is ignored. With none
+ * configured the header is not read at all and the socket address decides.
+ */
+export declare function clientKeyOf(c: Context, trustedProxyCount: number): string;
+/**
+ * The instance publishable key: `CLERK_PUBLISHABLE_KEY` when set, else derived from the Frontend
+ * API host in `CLERK_DOMAIN` as `pk_<test|live>_` + base64(host + "$"), the format Clerk documents
+ * (the prefix follows the secret key's `sk_live_` / `sk_test_`).
+ */
+export declare function publishableKeyFor(env: Record<string, string | undefined>, clerkIssuer: string): string;
 export declare function createAuthorizationServer(deps?: AuthorizationServerDeps): AuthorizationServer;
 export {};