@vantageos/mcp-boilerplate 0.4.0 → 0.6.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "vantage-mcp-boilerplate",
   "displayName": "VantageOS MCP Boilerplate",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "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,79 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-11-01
+
+### Added
+- `mcp-readme-fr` (bin, `scripts/readme-fr.mjs`): generates `README.fr.md` from a bilingual `README.md` whose passages carry explicit `<!-- lang:en -->` / `<!-- lang:fr -->` / `<!-- /lang -->` markers (mcp-standard C-1: one French file, never hand-copied). `--check` fails when the two diverge, a malformed marker is an error naming its line, and a hand-written `README.fr.md` (no banner) is never overwritten. `tests/readmeFr.test.ts`.
+
+### Fixed
+- The CHANGELOG link block covers every version: a GitHub compare or tag link where a tag exists (v0.1.1, v0.1.2, v0.3.0, v0.4.0), the npm page of the version otherwise (0.1.0, 0.2.x, 0.5.0; the dead `v0.1.0` tag link is replaced). `[Unreleased]` compares the newest tag, v0.4.0. `tests/changelogLinks.test.ts` fails when a `## [x]` heading has no link line, a link has no heading, or a URL is of no known form.
+
+## [0.5.0] - 2026-10-29
+
+> **Breaking for multi-instance deployments.** Cursors are now signed under a key drawn once per
+> process. Two instances behind a load balancer reject each other's cursors, and a restart
+> invalidates outstanding ones (`invalid_cursor`, the caller starts again). Migration: build one
+> signer on a shared key of at least 32 bytes, `createCursorSigner({ key })`, and pass it as
+> `cursorSigner` to `buildHttpApp` / `createBoilerplateMcpServer` and to every
+> `createPaginatedUpstreamClient`.
+>
+> **Rupture pour les déploiements multi-instance.** Les curseurs sont désormais signés sous une clé
+> tirée une fois par processus. Deux instances derrière un répartiteur de charge refusent les
+> curseurs l'une de l'autre, et un redémarrage invalide ceux en circulation (`invalid_cursor`,
+> l'appelant recommence). Migration : construire un signataire sur une clé partagée d'au moins
+> 32 octets, `createCursorSigner({ key })`, et le passer en `cursorSigner` à `buildHttpApp` /
+> `createBoilerplateMcpServer` et à chaque `createPaginatedUpstreamClient`.
+
+### Added
+
+- **`createCursorSigner({ key? })`** (EN), exported with `InvalidCursorError`,
+  `INVALID_CURSOR_CODE` and `CURSOR_KEY_BYTES`: `sign(payload)` returns
+  `<base64url payload>.<base64url HMAC-SHA256 tag>`, `verify(token)` returns the payload or throws
+  `InvalidCursorError` with a named `reason` (`empty`, `missing_separator`, `extra_separator`,
+  `empty_part`, `not_base64url`, `tag_length`, `tag_mismatch`). Constant-time tag comparison, no
+  unsigned fallback; default key 32 random bytes, an injected key shorter than 32 bytes throws.
+- **`createCursorSigner({ key? })`** (FR), exporté avec `InvalidCursorError`,
+  `INVALID_CURSOR_CODE` et `CURSOR_KEY_BYTES` : `sign(payload)` renvoie
+  `<charge base64url>.<étiquette HMAC-SHA256 base64url>`, `verify(token)` renvoie la charge ou lève
+  `InvalidCursorError` avec une `reason` nommée. Comparaison des étiquettes en temps constant, aucun
+  repli non signé ; clé par défaut de 32 octets aléatoires, une clé injectée de moins de 32 octets
+  lève une erreur.
+- `cursorSigner` option on `createPaginatedUpstreamClient`, `createBoilerplateMcpServer` and
+  `buildHttpApp` / option `cursorSigner` sur ces trois points d'entrée.
+
+### Security
+
+- **Signed cursors** (EN): the `readPage` upstream offset cursor and the `list_items` cursor were
+  base64url JSON guarded by an UNKEYED fingerprint, so a caller could edit the offset (or the list
+  key), recompute the fingerprint and have the cursor accepted. Both are now signed: an edited or
+  minted cursor is refused as `invalid_cursor` before any upstream request or lake read.
+- **Curseurs signés** (FR) : le curseur d'offset amont de `readPage` et le curseur de `list_items`
+  étaient du JSON base64url gardé par une empreinte NON signée ; un appelant pouvait modifier
+  l'offset (ou la clé de liste), recalculer l'empreinte et faire accepter le curseur. Les deux sont
+  désormais signés : un curseur modifié ou fabriqué est refusé en `invalid_cursor` avant toute
+  requête amont ou lecture du lac.
+
+- **S-13 outbound request timeout** (EN): every request the server emits (paginated upstream pages,
+  token-source API calls, external-issuer JWKS, Convex lake reads) carries a timeout set by
+  `UPSTREAM_TIMEOUT_MS` (declared variable, default 30000 ms, range 1000 to 300000, `ConfigurationError`
+  naming the variable when invalid); a timeout surfaces as the typed error each site already uses.
+  The JWKS fetch and the Convex fetch had none.
+- **Délai des requêtes sortantes S-13** (FR) : toute requête émise par le serveur (pages d'amont
+  paginées, appels d'API de la source de jetons, JWKS de l'émetteur externe, lectures du lac Convex)
+  porte un délai fixé par `UPSTREAM_TIMEOUT_MS` (variable déclarée, 30000 ms par défaut, de 1000 à
+  300000, `ConfigurationError` nommant la variable si invalide) ; un dépassement remonte sous
+  l'erreur typée que chaque site utilise déjà. Le JWKS et le fetch Convex n'en avaient aucun.
+- **S-22 Origin validation on `/mcp`** (EN): a request carrying an `Origin` header not listed in
+  `MCP_ALLOWED_ORIGINS` (declared variable, default empty) is refused `403 origin_not_allowed`
+  (FR+EN message) before the auth gate; no `Origin` passes; a wildcard or path in the list stops the
+  server at start. OAuth/discovery routes and `/health` are not covered.
+- **Validation de l'origine S-22 sur `/mcp`** (FR) : une requête dont l'en-tête `Origin` ne figure
+  pas dans `MCP_ALLOWED_ORIGINS` (variable déclarée, vide par défaut) est refusée `403
+  origin_not_allowed` (message FR+EN) avant la barrière d'authentification ; sans `Origin`, elle
+  passe ; un joker ou un chemin dans la liste arrête le serveur au démarrage. Les routes
+  OAuth/découverte et `/health` ne sont pas couvertes.
+
 ## [0.4.0] - 2026-10-28
 
 > **BREAKING for forks.** `CONTEXT_CEILING` is no longer exported and `mcp-server.json` must declare
@@ -414,6 +487,16 @@ Initial published release.
 - Reproducible build via `npm ci`; 52/52 tests passing at release time.
 - MIT license, clonable as a starter template.
 
-[Unreleased]: https://github.com/elpiarthera/vantage-mcp-boilerplate/compare/v0.1.1...HEAD
-[0.1.1]: https://github.com/elpiarthera/vantage-mcp-boilerplate/compare/v0.1.0...v0.1.1
-[0.1.0]: https://github.com/elpiarthera/vantage-mcp-boilerplate/releases/tag/v0.1.0
+[Unreleased]: https://github.com/elpiarthera/vantage-mcp-boilerplate/compare/v0.4.0...HEAD
+[0.6.0]: https://www.npmjs.com/package/@vantageos/mcp-boilerplate/v/0.6.0
+[0.5.0]: https://www.npmjs.com/package/@vantageos/mcp-boilerplate/v/0.5.0
+[0.4.0]: https://github.com/elpiarthera/vantage-mcp-boilerplate/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/elpiarthera/vantage-mcp-boilerplate/compare/v0.1.2...v0.3.0
+[0.2.4]: https://www.npmjs.com/package/@vantageos/mcp-boilerplate/v/0.2.4
+[0.2.3]: https://www.npmjs.com/package/@vantageos/mcp-boilerplate/v/0.2.3
+[0.2.2]: https://www.npmjs.com/package/@vantageos/mcp-boilerplate/v/0.2.2
+[0.2.1]: https://www.npmjs.com/package/@vantageos/mcp-boilerplate/v/0.2.1
+[0.2.0]: https://www.npmjs.com/package/@vantageos/mcp-boilerplate/v/0.2.0
+[0.1.2]: https://github.com/elpiarthera/vantage-mcp-boilerplate/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/elpiarthera/vantage-mcp-boilerplate/releases/tag/v0.1.1
+[0.1.0]: https://www.npmjs.com/package/@vantageos/mcp-boilerplate/v/0.1.0

package/README.fr.md

@@ -22,6 +22,7 @@ src/
   serverManifest.ts     # chargeur fail-closed de mcp-server.json (le manifeste serveur)
   toolRecord.ts         # fiche d'outil typée : autorité, verbe, table, mécanisme, pagination, coût
   pagination.ts         # pagination par curseur appliquée par l'outil (défaut, max fini, invalid_cursor)
+  signedCursor.ts       # primitive de curseur signé HMAC (createCursorSigner), utilisée par tout curseur
   buildIdentity.ts      # identité de build dérivée de l'arbre servi
   stdio.ts              # serveStdio(factory) : les deux ères du protocole sur stdio
   http.ts               # adaptateur Node http.Server autour de l'app Hono
@@ -100,7 +101,7 @@ Les ensembles sont des unions TypeScript fermées : une valeur hors ensemble ne
 compile pas, et un outil de liste ne peut omettre ni son mécanisme ni sa pagination.
 La fiche de chaque outil est un objet de littéraux, lisible par un contrôleur
 statique. `list_items` pagine ses lignes : `limit` (20 par
-défaut, plafonné à 100) et un `cursor` opaque ; une page tronquée porte `nextCursor`
+défaut, plafonné à 100) et un `cursor` opaque et signé ; une page tronquée porte `nextCursor`
 et `exhausted: false`, la dernière page `exhausted: true` ; un curseur invalide ou expiré est
 une erreur d'entrée de l'outil : un résultat `isError: true` avec
 `structuredContent.error.code` valant `invalid_cursor` (message FR/EN), jamais une
@@ -180,6 +181,29 @@ 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.
 
+**Validation de l'origine sur `/mcp` (S-22)** : une requête vers `/mcp` qui porte un en-tête
+`Origin` (un navigateur) est refusée `403 {"code":"origin_not_allowed","message_en":...,"message_fr":...}`,
+avant la barrière d'authentification et sans répéter l'origine, sauf si l'origine figure dans
+`MCP_ALLOWED_ORIGINS` (`schéma://hôte[:port]` séparés par des virgules, correspondance exacte
+et insensible à la casse, déclarée dans `src/settings.ts`). Le défaut est vide : toute origine
+de navigateur est refusée. `null`, une valeur vide et les quasi-correspondances comme
+`https://claude.ai.evil.example` sont refusées. Une requête sans en-tête `Origin` (serveur à
+serveur, Claude Code) passe comme avant. Un joker ou une entrée avec chemin arrête le serveur
+au démarrage avec une `ConfigurationError` qui nomme la variable. Les routes OAuth et de
+découverte (`/.well-known/*`, `/authorize`, `/token`, `/register`) et `/health` ne sont pas
+couvertes : ce sont des navigations de navigateur ou des appels CORS du parcours de connexion.
+
+**Délai des requêtes sortantes (S-13)** : toute requête que le serveur émet vers un amont (pages
+d'API paginées, appels d'API via la source de jetons client-credentials, JWKS de l'émetteur
+externe, lecteur de lac Convex) porte un délai, `UPSTREAM_TIMEOUT_MS` (entier en millisecondes,
+`30000` par défaut, de `1000` à `300000`, déclaré dans `src/settings.ts`). Une requête qui le
+dépasse est interrompue et remonte sous l'erreur typée que le site d'appel utilise déjà
+(`UpstreamPageError` `unreachable` nommant `TimeoutError`, `LakeReadError` `read_failed`, un
+échec de récupération du JWKS que le vérificateur traduit en 503) ; un appel qui progresse ne
+lève jamais le plafond. Une valeur non entière ou hors plage arrête le serveur au démarrage avec
+une `ConfigurationError` qui nomme la variable. Le mécanisme commun est `src/upstream/timeout.ts`,
+qui liste chaque site d'appel sortant.
+
 **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
@@ -344,10 +368,10 @@ est refusé avant tout appel réseau : le jeton ne part jamais vers un hôte nom
 d'outil, et les redirections sont refusées, jamais suivies (`redirect: "error"`). `readAll` s'arrête
 sur la page incomplète (ou au total, avec `extractTotal`) et refuse un ensemble au-delà du plafond
 avec `row_ceiling_exceeded`, jamais un ensemble tronqué en silence. `readPage` renvoie
-`{ rows, nextCursor?, exhausted }` ; son curseur est lié au chemin et aux paramètres, et un curseur rejoué
-sur une autre requête ou altéré sans recalcul de son empreinte est refusé en `invalid_cursor`.
-L'empreinte n'est pas signée : elle détecte un mauvais usage, pas une falsification ; l'offset ne
-confère aucun droit et un offset forgé au-delà du plafond est refusé avant toute requête. Une page
+`{ rows, nextCursor?, exhausted }` ; son curseur est signé (voir
+[Curseurs signés](#curseurs-signés)) et lié au chemin et aux paramètres : un curseur rejoué sur une
+autre requête, modifié, ou signé sous une autre clé est refusé en `invalid_cursor` avant toute
+requête. Une page
 vide avant le total déclaré est refusée en `inconsistent_page`, jamais redemandée. Les 429 et 503
 sont rejoués avec un délai exponentiel (5 tentatives par défaut, base 500 ms, plafond 30 s) et
 respectent `Retry-After` ; aucun autre statut n'est rejoué. Les erreurs (`UpstreamPageError`)
@@ -355,6 +379,33 @@ nomment le chemin et le statut, jamais un jeton, une valeur de paramètre ni le
 `pageSize` (défaut 100) dans le maximum réel de l'amont : une page plafonnée en silence en dessous
 se lit comme la dernière, sauf si la réponse déclare un total.
 
+### Curseurs signés
+
+Tout curseur émis par le boilerplate (le curseur de `list_items` et celui de `readPage`) est un jeton
+`<charge base64url>.<étiquette base64url>`, l'étiquette étant le HMAC-SHA256 de la charge sous une clé
+du serveur (`src/signedCursor.ts`). Un appelant peut lire un curseur mais ni le modifier ni en
+fabriquer un : une charge modifiée, une étiquette faite sous une autre clé, ou un jeton mal formé
+(vide, sans séparateur, tronqué, hors base64url) est refusé en `invalid_cursor` avant toute lecture,
+avec une `reason` destinée à l'opérateur sur l'`InvalidCursorError`. La vérification compare les
+étiquettes en temps constant ; il n'existe aucun repli non signé. Un serveur dérivé qui émet ses
+propres curseurs utilise la même primitive :
+
+```ts
+import { createCursorSigner } from "@vantageos/mcp-boilerplate";
+
+const signer = createCursorSigner(); // 32 octets aléatoires, tirés une fois
+const cursor = signer.sign(JSON.stringify({ v: 1, after: "item-20" }));
+const payload = signer.verify(cursor); // ou lève InvalidCursorError
+```
+
+**Limite : la clé par défaut vit dans le processus.** Un redémarrage invalide tous les curseurs en
+circulation (l'appelant reçoit `invalid_cursor` et recommence sans curseur), et des instances
+derrière un répartiteur de charge refusent les curseurs les unes des autres. Un déploiement
+multi-instance injecte dans chaque instance une même clé partagée d'au moins 32 octets (une clé plus
+courte lève une erreur) : `createCursorSigner({ key })`, passé en `cursorSigner` à `buildHttpApp` /
+`createBoilerplateMcpServer` (curseur de `list_items`) et à `createPaginatedUpstreamClient` (curseur
+amont).
+
 ## Déclarer sa propre configuration
 
 Un serveur dérivé déclare une fois les variables d'environnement qu'il lit, et reçoit au
@@ -466,6 +517,24 @@ le client envoie `X-MCP-Locale: fr|en` (défaut `en`) ; le sélecteur navigateur
 convention `<Namespace>.<category>.<key>` de `@vantageos/mosaic-i18n`, FR et EN en
 parité.
 
+## Un README français généré depuis un README bilingue
+
+Un serveur dont le `README.md` porte l'anglais et le français côte à côte livre un `README.fr.md` généré depuis lui
+(mcp-standard C-1), jamais recopié à la main. Marquez chaque passage bilingue, puis lancez le générateur :
+
+```markdown
+<!-- lang:en -->
+A demo server.
+<!-- lang:fr -->
+Un serveur de démonstration.
+<!-- /lang -->
+```
+
+Le texte hors d'une région marquée (code, tableaux, liens) est copié dans les deux. `npx mcp-readme-fr --write` écrit
+`README.fr.md` ; `npx mcp-readme-fr --check` (à mettre dans `npm test`) échoue quand les deux divergent. Un marqueur
+mal formé est une erreur qui nomme sa ligne, et le générateur n'écrase jamais un `README.fr.md` écrit à la main (sans
+sa bannière). Ce dépôt garde sa propre traduction écrite à la main.
+
 ## Tests
 
 ```bash

package/README.md

@@ -21,6 +21,7 @@ src/
   serverManifest.ts     # fail-closed loader of mcp-server.json (the server manifest)
   toolRecord.ts         # typed tool record: authority, verb, table, mechanism, pagination, cost
   pagination.ts         # cursor pagination applied by the tool (default, finite max, invalid_cursor)
+  signedCursor.ts       # HMAC-signed cursor primitive (createCursorSigner), used by every cursor
   buildIdentity.ts      # build identity derived from the served tree
   stdio.ts              # serveStdio(factory): both protocol eras over stdio
   http.ts               # Node http.Server adapter around the Hono app
@@ -98,7 +99,7 @@ and returns `structuredContent` plus a text block with the same JSON. Its
 The sets are closed TypeScript unions: a value outside them does not compile, and a
 list tool cannot omit its mechanism or its pagination. Each tool's record is a plain
 object of literals so a static checker can read it. `list_items` pages
-its rows: `limit` (default 20, capped at 100) and an opaque
+its rows: `limit` (default 20, capped at 100) and an opaque, signed
 `cursor`; a truncated page carries `nextCursor` and `exhausted: false`, the last page
 `exhausted: true`; an invalid or expired cursor is a tool
 input error: a result with `isError: true` and `structuredContent.error.code`
@@ -174,6 +175,27 @@ 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.
 
+**Origin validation on `/mcp` (S-22)**: a request to `/mcp` that carries an `Origin` header
+(a browser) is refused `403 {"code":"origin_not_allowed","message_en":...,"message_fr":...}`,
+before the auth gate and without echoing the origin, unless the origin is listed in
+`MCP_ALLOWED_ORIGINS` (comma-separated `scheme://host[:port]`, exact and case-insensitive,
+declared in `src/settings.ts`). The default is empty: every browser origin is refused. `null`,
+an empty value and near-misses such as `https://claude.ai.evil.example` are refused. A request
+with no `Origin` header (server-to-server, Claude Code) passes as before. A wildcard or an entry
+with a path stops the server at start with a `ConfigurationError` naming the variable. The
+OAuth and discovery routes (`/.well-known/*`, `/authorize`, `/token`, `/register`) and `/health`
+are not covered: they are browser navigations or CORS calls of the sign-in flow.
+
+**Outbound request timeout (S-13)**: every request the server emits to an upstream (paginated
+API pages, API calls through the client-credentials token source, the external-issuer JWKS, the
+Convex lake reader) carries a timeout, `UPSTREAM_TIMEOUT_MS` (integer milliseconds, default
+`30000`, range `1000` to `300000`, declared in `src/settings.ts`). A request that exceeds it is
+aborted and surfaces as the typed error the call site already uses (`UpstreamPageError`
+`unreachable` naming `TimeoutError`, `LakeReadError` `read_failed`, a JWKS fetch failure the verifier
+answers 503); a progressing call never lifts the ceiling. A value that is not an integer or is out of
+range stops the server at start with a `ConfigurationError` naming the variable. The shared mechanism
+is `src/upstream/timeout.ts`, which lists every outbound call site.
+
 **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.
@@ -325,10 +347,9 @@ const page = await things.readPage("things", { status: "active" }, cursor); // o
 any network call, so the bearer token never leaves for a host a tool argument names, and redirects
 are refused rather than followed (`redirect: "error"`). `readAll` stops on the short page (or at the
 total, with `extractTotal`) and refuses a set above the ceiling with `row_ceiling_exceeded`, never a
-silently truncated one. `readPage` returns `{ rows, nextCursor?, exhausted }`; its cursor is bound
-to the path and params, and one replayed against another query or altered without recomputing its
-fingerprint is refused as `invalid_cursor`. The fingerprint is unkeyed: it detects misuse, not
-forgery; the offset carries no authority and a minted offset above the ceiling is refused before any
+silently truncated one. `readPage` returns `{ rows, nextCursor?, exhausted }`; its cursor is signed
+(see [Signed cursors](#signed-cursors)) and bound to the path and params: one replayed against
+another query, edited, or signed under another key is refused as `invalid_cursor` before any
 request. An empty page before a declared total is refused as `inconsistent_page`, never
 re-requested. 429 and 503 are retried with exponential backoff (default 5 attempts, 500 ms base,
 30 s cap) and honour `Retry-After`; no other status is retried. Errors (`UpstreamPageError`) name the
@@ -336,6 +357,31 @@ path and the status, never a token, a parameter value or the body. Keep `pageSiz
 within the upstream's real maximum: a page silently capped below it reads as the last one unless the
 response declares a total.
 
+### Signed cursors
+
+Every cursor the boilerplate issues (the `list_items` cursor and the `readPage` cursor) is a token
+`<base64url payload>.<base64url tag>`, the tag being HMAC-SHA256 of the payload under a server key
+(`src/signedCursor.ts`). A caller can read a cursor but cannot edit or mint one: an edited payload,
+a tag made under another key, or a malformed token (empty, no separator, truncated, not base64url)
+is refused as `invalid_cursor` before any read, with an operator-facing `reason` on the
+`InvalidCursorError`. Verification compares tags in constant time; there is no unsigned fallback.
+A derived server that issues its own cursors uses the same primitive:
+
+```ts
+import { createCursorSigner } from "@vantageos/mcp-boilerplate";
+
+const signer = createCursorSigner(); // 32 random bytes, drawn once
+const cursor = signer.sign(JSON.stringify({ v: 1, after: "item-20" }));
+const payload = signer.verify(cursor); // or throws InvalidCursorError
+```
+
+**Limit: the default key lives in the process.** A restart invalidates every outstanding cursor
+(the caller gets `invalid_cursor` and starts again without one), and instances behind a load
+balancer reject each other's cursors. A multi-instance deployment injects one shared key of at
+least 32 bytes (a shorter one throws) into every instance: `createCursorSigner({ key })`, passed as
+`cursorSigner` to `buildHttpApp` / `createBoilerplateMcpServer` (the `list_items` cursor) and to
+`createPaginatedUpstreamClient` (the upstream cursor).
+
 ## Declaring your own configuration
 
 A derived server declares the environment variables it reads, once, and gets a typed, validated,
@@ -443,6 +489,24 @@ client sends `X-MCP-Locale: fr|en` (default `en`); the browser picker follows
 `<Namespace>.<category>.<key>` convention of `@vantageos/mosaic-i18n`, FR and EN
 in lockstep.
 
+## A French README generated from a bilingual one
+
+A server whose `README.md` carries English and French side by side ships a `README.fr.md` generated from it
+(mcp-standard C-1), never hand-copied. Mark each bilingual passage, then run the generator:
+
+```markdown
+<!-- lang:en -->
+A demo server.
+<!-- lang:fr -->
+Un serveur de démonstration.
+<!-- /lang -->
+```
+
+Text outside a marked region (code, tables, links) is copied to both. `npx mcp-readme-fr --write` writes
+`README.fr.md`; `npx mcp-readme-fr --check` (put it in `npm test`) fails when the two diverge. A malformed marker is
+an error naming its line, and the generator never overwrites a hand-written `README.fr.md` (one without its banner).
+This repository keeps its own hand translation.
+
 ## Testing
 
 ```bash

package/dist/config.d.ts

@@ -25,4 +25,4 @@ export declare function loadAuthConfig(env?: NodeJS.ProcessEnv, jwksOverride?: A
  * that into a 503 (`jwks-unavailable`), never a 401 — unless a previously fetched set is still
  * held, which is served rather than failing every request during a brief issuer blip.
  */
-export declare function createCachedJwksFetcher(url: string, fetchImpl?: typeof fetch, nowMs?: () => number): () => Promise<ClerkJwks>;
+export declare function createCachedJwksFetcher(url: string, fetchImpl?: typeof fetch, nowMs?: () => number, timeoutMs?: number): () => Promise<ClerkJwks>;

package/dist/config.js

@@ -13,6 +13,7 @@
  * URL, issuer, audience) comes from the environment, never a literal in
  * code.
  */
+import { configuredUpstreamTimeoutMs, upstreamSignal } from "./upstream/timeout.js";
 export function loadAuthMode(env = process.env) {
     const raw = (env.AUTH_MODE ?? "oauth").toLowerCase();
     if (raw !== "oauth" && raw !== "public") {
@@ -47,13 +48,13 @@ const JWKS_TTL_MS = 10 * 60 * 1000;
  * that into a 503 (`jwks-unavailable`), never a 401 — unless a previously fetched set is still
  * held, which is served rather than failing every request during a brief issuer blip.
  */
-export function createCachedJwksFetcher(url, fetchImpl = fetch, nowMs = Date.now) {
+export function createCachedJwksFetcher(url, fetchImpl = fetch, nowMs = Date.now, timeoutMs = configuredUpstreamTimeoutMs()) {
     let cached;
     return async () => {
         if (cached && nowMs() - cached.fetchedAt < JWKS_TTL_MS)
             return cached.jwks;
         try {
-            const res = await fetchImpl(url);
+            const res = await fetchImpl(url, { signal: upstreamSignal(timeoutMs) });
             if (!res.ok)
                 throw new Error(`JWKS fetch ${url} answered ${res.status}`);
             const body = (await res.json());

package/dist/http.js

@@ -1,8 +1,12 @@
 import { loadAuthConfig, loadAuthMode } from "./config.js";
 import { buildHttpApp } from "./httpApp.js";
 import { createNodeListener, maxBodyBytesFrom } from "./nodeAdapter.js";
+import { loadHttpSettings } from "./settings.js";
 const authMode = loadAuthMode();
 const uiDomain = process.env.MCP_UI_DOMAIN || undefined;
+// S-22: MCP_ALLOWED_ORIGINS, declared in src/settings.ts. A wildcard or a path stops the server
+// here with a ConfigurationError naming the variable.
+const { allowedOrigins } = loadHttpSettings();
 // OAuth tier: MCP_OAUTH_ISSUER + MCP_OAUTH_AUDIENCE select an EXTERNAL issuer (resource server
 // only); otherwise this server is its own authorization server (ruling R1) and reads its
 // settings from the environment per request — a missing value answers 503, see
@@ -10,9 +14,9 @@ const uiDomain = process.env.MCP_UI_DOMAIN || undefined;
 const externalIssuer = Boolean(process.env.MCP_OAUTH_ISSUER && process.env.MCP_OAUTH_AUDIENCE);
 const app = buildHttpApp(authMode === "oauth"
     ? externalIssuer
-        ? { authMode, auth: loadAuthConfig(), uiDomain }
-        : { authMode, authorizationServer: {}, uiDomain }
-    : { authMode, uiDomain });
+        ? { authMode, auth: loadAuthConfig(), uiDomain, allowedOrigins }
+        : { authMode, authorizationServer: {}, uiDomain, allowedOrigins }
+    : { authMode, uiDomain, allowedOrigins });
 const port = Number(process.env.PORT ?? 8787);
 // 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.

package/dist/httpApp.d.ts

@@ -28,6 +28,7 @@ import type { AuthMode } from "./config.js";
 import type { ExampleItem } from "./exampleItems.js";
 import type { LakeReader } from "./lake/reader.js";
 import { type AuthorizationServerDeps } from "./oauth/authorizationServer.js";
+import type { CursorSigner } from "./signedCursor.js";
 import { type ResolvedTenant } from "./tenancy.js";
 import { type CallerResolution, type IdentityDeps } from "./verifiedPerson.js";
 export interface AppDeps {
@@ -51,6 +52,17 @@ export interface AppDeps {
      * Injected by the deployment like `identity`; absent, the in-memory seed is read.
      */
     lake?: LakeReader<ExampleItem>;
+    /**
+     * Browser origins allowed to call `/mcp` (S-22). Data from `MCP_ALLOWED_ORIGINS`
+     * (src/settings.ts), never a constant; empty or absent refuses every browser origin.
+     */
+    allowedOrigins?: readonly string[];
+    /**
+     * Signs and verifies the `list_items` cursor (src/signedCursor.ts). Absent: the process-wide
+     * signer, random key per process. Behind a load balancer, inject one signer built on a shared
+     * key (`createCursorSigner({ key })`) into every instance.
+     */
+    cursorSigner?: CursorSigner;
 }
 type Variables = {
     tenant?: ResolvedTenant;

package/dist/httpApp.js

@@ -49,6 +49,25 @@ export function buildHttpApp(deps = {}) {
     // Unauthenticated (S-7): the version AND the identity of the tree being served (C-25), so a
     // deployment is proven from what the server returns, not from what the deploy printed.
     app.get("/health", (c) => c.json({ status: "ok", version: SERVER_VERSION, buildId: getBuildIdentity() }));
+    // S-22 Origin validation, on /mcp ONLY and registered BEFORE the auth gate: a request that carries
+    // an Origin header (a browser) must name an allowed origin (exact full-origin match, case-
+    // insensitive), else 403 before any token is looked at. No Origin header (server-to-server, Claude
+    // Code, a connector backend) passes as before. `null`, an empty value and near-misses such as
+    // `https://claude.ai.evil.example` are not in the list, so they are refused.
+    // Declared divergence: /health and the OAuth/discovery routes (/.well-known/*, /authorize, /token,
+    // /register) are NOT covered — they are browser navigations or CORS calls of the sign-in flow
+    // (/register has its own MCP_REGISTER_CORS_ORIGINS allowlist) and S-22 guards the MCP endpoint.
+    const allowedOrigins = new Set((deps.allowedOrigins ?? []).map((o) => o.toLowerCase()));
+    app.use("/mcp", async (c, next) => {
+        const origin = c.req.raw.headers.get("origin");
+        if (origin === null || allowedOrigins.has(origin.toLowerCase()))
+            return next();
+        return c.json({
+            code: "origin_not_allowed",
+            message_en: t("en", "auth.originNotAllowed"),
+            message_fr: t("fr", "auth.originNotAllowed"),
+        }, 403);
+    });
     if (authMode === "oauth") {
         // Resolves the resource-server configuration per request: the own-AS tier reads its
         // environment lazily, so a missing value is a 503 on the request, not a crash at boot.
@@ -142,6 +161,7 @@ export function buildHttpApp(deps = {}) {
             locale,
             uiDomain: deps.uiDomain,
             lake: deps.lake,
+            cursorSigner: deps.cursorSigner,
         }));
         return handler.fetch(c.req.raw);
     });

package/dist/index.d.ts

@@ -4,6 +4,8 @@ export { createBoilerplateMcpServer } from "./mcpServerFactory.js";
 export { EXAMPLE_ITEMS_READER, LAKE_UNREADABLE_CODE, LakeReadError, checkLakePage, createInMemoryLakeReader, } from "./lake/reader.js";
 export type { LakePage, LakePageRequest, LakeReadErrorCode, LakeReader, LakeScope, } from "./lake/reader.js";
 export { readPage } from "./pagination.js";
+export { CURSOR_KEY_BYTES, INVALID_CURSOR_CODE, InvalidCursorError, createCursorSigner, } from "./signedCursor.js";
+export type { CursorSigner, CursorSignerOptions, InvalidCursorReason } from "./signedCursor.js";
 export { buildHttpApp } from "./httpApp.js";
 export type { AppDeps } from "./httpApp.js";
 export { PERSON_UNRESOLVED_CODE, resolveVerifiedPerson, withVerifiedPerson, } from "./verifiedPerson.js";

package/dist/index.js

@@ -2,6 +2,7 @@ export { ConfigurationError, VARIABLE_TYPES, VariableDeclarationError, defineVar
 export { createBoilerplateMcpServer } from "./mcpServerFactory.js";
 export { EXAMPLE_ITEMS_READER, LAKE_UNREADABLE_CODE, LakeReadError, checkLakePage, createInMemoryLakeReader, } from "./lake/reader.js";
 export { readPage } from "./pagination.js";
+export { CURSOR_KEY_BYTES, INVALID_CURSOR_CODE, InvalidCursorError, createCursorSigner, } from "./signedCursor.js";
 export { buildHttpApp } from "./httpApp.js";
 export { PERSON_UNRESOLVED_CODE, resolveVerifiedPerson, withVerifiedPerson, } from "./verifiedPerson.js";
 export { UpstreamTokenError, clientCredentialsFromEnv, createClientCredentialsTokenSource, } from "./upstream/clientCredentials.js";

package/dist/lake/convex.d.ts

@@ -79,6 +79,8 @@ export interface ConvexLakeReaderOptions<Row = RawRow> {
     readonly client?: ConvexLakeQueryClient;
     /** A fetch implementation passed to the `ConvexHttpClient` built when `client` is absent. */
     readonly fetch?: typeof globalThis.fetch;
+    /** Time budget of one read. Default: `UPSTREAM_TIMEOUT_MS` (30 s). Applies when `client` is absent. */
+    readonly timeoutMs?: number;
 }
 /**
  * A read-only lake reader over a Convex deployment. Throws on an unreadable configuration (the

package/dist/lake/convex.js

@@ -49,6 +49,7 @@
 import { ConvexHttpClient } from "convex/browser";
 import { makeFunctionReference } from "convex/server";
 import { defineVariables, isSecureUrl, loadVariables } from "../declaredVariables.js";
+import { boundedFetch, configuredUpstreamTimeoutMs } from "../upstream/timeout.js";
 import { LakeReadError, assertOrderedKeys } from "./reader.js";
 const ARGUMENT_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 function configurationError(message) {
@@ -91,10 +92,13 @@ function checkOptions(options) {
     return options.url.replace(/\/+$/, "");
 }
 /** A ConvexHttpClient seen through the read-only surface. Its constructor errors name the URL. */
-function httpClient(url, fetchImpl) {
+function httpClient(url, fetchImpl, timeoutMs) {
     let http;
     try {
-        http = new ConvexHttpClient(url, { logger: false, ...(fetchImpl ? { fetch: fetchImpl } : {}) });
+        http = new ConvexHttpClient(url, {
+            logger: false,
+            fetch: boundedFetch(fetchImpl ?? globalThis.fetch, timeoutMs),
+        });
     }
     catch {
         throw configurationError("the Convex client refused the deployment url (value not shown)");
@@ -114,7 +118,8 @@ function isRawRow(value) {
 export function createConvexLakeReader(options) {
     const url = checkOptions(options);
     const { functions, keyField, token, tokenArg, parseRow } = options;
-    const client = options.client ?? httpClient(url, options.fetch);
+    const client = options.client ??
+        httpClient(url, options.fetch, options.timeoutMs ?? configuredUpstreamTimeoutMs());
     if (token !== undefined && tokenArg === undefined)
         client.setAuth(token);
     const refs = {

package/dist/locales/en.json

@@ -1,7 +1,8 @@
 {
   "Mcp": {
     "auth": {
-      "unauthorized": "Unauthorized"
+      "unauthorized": "Unauthorized",
+      "originNotAllowed": "This origin is not allowed to call this endpoint"
     },
     "tenant": {
       "permissionDenied": "permission denied: no tenant resolved for this caller"

package/dist/locales/fr.json

@@ -1,7 +1,8 @@
 {
   "Mcp": {
     "auth": {
-      "unauthorized": "Non autorisé"
+      "unauthorized": "Non autorisé",
+      "originNotAllowed": "Cette origine n'est pas autorisée à appeler ce point d'accès"
     },
     "tenant": {
       "permissionDenied": "permission refusée : aucun tenant résolu pour cet appelant"

package/dist/mcpServerFactory.d.ts

@@ -32,6 +32,7 @@ import { McpServer } from "@modelcontextprotocol/server";
 import type { ExampleItem } from "./exampleItems.js";
 import { type McpLocale } from "./i18n.js";
 import { type LakeReader } from "./lake/reader.js";
+import type { CursorSigner } from "./signedCursor.js";
 import { type ResolvedTenant } from "./tenancy.js";
 import type { CallerResolution } from "./verifiedPerson.js";
 /** Oldest 2025-era protocol revision served; the legacy `initialize` handshake never offers older. */
@@ -74,5 +75,11 @@ export interface McpServerDeps {
      * before. A derived server injects its own (e.g. `@vantageos/mcp-boilerplate/lake/convex`).
      */
     lake?: LakeReader<ExampleItem>;
+    /**
+     * Signs and verifies the `list_items` cursor (src/signedCursor.ts). Default: the process-wide
+     * signer of src/pagination.ts, whose key is random per process. A multi-instance deployment
+     * injects one signer built on a shared key, or its instances reject each other's cursors.
+     */
+    cursorSigner?: CursorSigner;
 }
 export declare function createBoilerplateMcpServer(deps?: McpServerDeps): McpServer;

package/dist/mcpServerFactory.js

@@ -187,7 +187,7 @@ export function createBoilerplateMcpServer(deps = {}) {
         try {
             const tenantId = deps.tenant?.tenantId;
             const scope = tenantId === undefined ? undefined : { tenantId };
-            const { items, ...page } = await readPage(lake, args, PAGINATION, scope);
+            const { items, ...page } = await readPage(lake, args, PAGINATION, scope, deps.cursorSigner);
             // Defence in depth: the scope was applied inside the read; a row of another tenant that
             // still comes back means the reader ignored it. Refuse the page, never filter it.
             if (tenantId !== undefined && scopeRowsForTenant(tenantId, items).length !== items.length) {