@vantageos/mcp-boilerplate 0.2.0 → 0.2.2

package/.claude-plugin/plugin.json

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

@@ -7,6 +7,69 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [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
+
+- The MCP Apps UI bundle is resolved relative to the module, not to `process.cwd()`: the
+  published package failed `resources/read ui://mcp-boilerplate/items-widget.html` whenever it
+  was run from any directory other than its own root.
+- A missing UI bundle now answers an MCP error with no filesystem path in its message (the
+  detail is logged on stderr only); it used to leak the absolute `ENOENT` path to the client.
+- `scripts/generate-signing-key.mjs`, which the README tells users to run, is now in the
+  published `files`.
+
 ## [0.2.0] - 2026-10-10
 
 SDK v2 / protocol 2026-07-28 migration, own authorization server, MCP Apps + ChatGPT

package/README.fr.md

@@ -122,6 +122,27 @@ 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
@@ -217,11 +238,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.17.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,6 +118,25 @@ 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.
@@ -211,11 +230,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.17.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,6 +12,9 @@
     "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",

package/dist/locales/fr.json

@@ -12,6 +12,9 @@
     "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",

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,63 @@
+/**
+ * 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;
+            response.headers.forEach((value, key) => res.setHeader(key, value));
+            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,19 @@ 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;
 export declare function createAuthorizationServer(deps?: AuthorizationServerDeps): AuthorizationServer;
 export {};

package/dist/oauth/authorizationServer.js

@@ -23,6 +23,7 @@
 import { buildDiscoveryDocument, buildUserInfo, exchangeAuthorizationCode, oauthErrorFor, resumeAuthorize, startAuthorize, } from "@vantageos/cloud-identity";
 import { getCookie } from "hono/cookie";
 import { cors } from "hono/cors";
+import { flagKnob, integerKnob, originListKnob } from "../envKnobs.js";
 import { detectLocaleFromAcceptLanguage, t } from "../i18n.js";
 import { createClerkBackendCollaborators } from "./clerk.js";
 import { createInMemoryClientRegistry, isAllowedRedirectUri, isUrlShapedClientId, resolveCimdClient, } from "./clientRegistry.js";
@@ -36,6 +37,26 @@ function noStore(c) {
     c.header("Cache-Control", "no-store");
     c.header("Pragma", "no-cache");
 }
+/**
+ * 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 function clientKeyOf(c, trustedProxyCount) {
+    const socket = c.env?.remoteAddress || "unknown";
+    if (trustedProxyCount <= 0)
+        return socket;
+    const chain = (c.req.header("x-forwarded-for") ?? "")
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    return chain.length >= trustedProxyCount
+        ? (chain[chain.length - trustedProxyCount] ?? socket)
+        : socket;
+}
 function sessionTokenFrom(c) {
     const header = c.req.header("authorization");
     if (header?.toLowerCase().startsWith("bearer ")) {
@@ -47,7 +68,20 @@ function sessionTokenFrom(c) {
 }
 export function createAuthorizationServer(deps = {}) {
     const env = deps.env ?? process.env;
+    // Operator knobs are validated here, at construction: a bad value stops the boot.
+    const trustedProxyCount = integerKnob(env, OAUTH_ENV.trustedProxyCount, 0, 10) ?? 0;
+    const registerOrigins = originListKnob(env, OAUTH_ENV.registerCorsOrigins);
+    const allowInMemory = flagKnob(env, OAUTH_ENV.allowInMemoryStores) === true;
     const now = deps.now ?? (() => Date.now());
+    // Fail at boot, loudly, rather than lose every code and client on the first restart.
+    if (!deps.codeStore || !deps.clientRegistry) {
+        if (env.NODE_ENV === "production") {
+            if (!allowInMemory) {
+                throw new Error(`NODE_ENV=production refuses the in-memory OAuth stores (codes and registered clients are lost on restart and not shared between instances). Inject durable adapters (docs/oauth-stores.md), or set ${OAUTH_ENV.allowInMemoryStores}=1 to accept a single-instance deployment that forgets them on restart.`);
+            }
+            console.warn(`[oauth] running on in-memory stores in production (${OAUTH_ENV.allowInMemoryStores}=1): single instance only, state is lost on restart`);
+        }
+    }
     const codeStore = deps.codeStore ?? createInMemoryCodeStore();
     const registry = deps.clientRegistry ?? createInMemoryClientRegistry();
     const injectedClerk = deps.clerk;
@@ -134,7 +168,10 @@ export function createAuthorizationServer(deps = {}) {
             case "org-picker": {
                 c.header("Content-Security-Policy", await pickerContentSecurityPolicy());
                 const locale = detectLocaleFromAcceptLanguage(c.req.header("accept-language"));
-                return c.html(renderOrgPicker(outcome.model, locale));
+                return c.html(renderOrgPicker(outcome.model, locale, {
+                    // Only a URL-shaped (CIMD) client_id is bound to a domain its owner controls.
+                    unverified: !isUrlShapedClientId(outcome.model.client.clientId),
+                }));
             }
             case "refused": {
                 const mapped = oauthErrorFor(outcome.refusal);
@@ -178,7 +215,9 @@ export function createAuthorizationServer(deps = {}) {
         },
         mount(app) {
             app.use("/.well-known/*", cors());
-            app.use("/register", cors());
+            // /register is for native and server-side clients, which send no Origin. A browser origin
+            // may call it only when the operator lists it.
+            app.use("/register", cors({ origin: (origin) => (registerOrigins.includes(origin) ? origin : null) }));
             app.use("/token", cors());
             const metadata = async (c) => {
                 const result = await settingsNow();
@@ -216,7 +255,7 @@ export function createAuthorizationServer(deps = {}) {
                 return c.json((await issuerFor(result.settings)).jwks);
             });
             app.post("/register", async (c) => {
-                const key = (c.req.header("x-forwarded-for") ?? "").split(",")[0]?.trim() || "unknown";
+                const key = clientKeyOf(c, trustedProxyCount);
                 if (!registerAllowed(key)) {
                     c.header("Retry-After", "60");
                     return c.json({ error: "too_many_requests" }, 429);
@@ -308,12 +347,14 @@ export function createAuthorizationServer(deps = {}) {
                     return c.json({ error: "invalid_request", error_description: "unreadable form" }, 400);
                 }
                 const field = (name) => typeof form[name] === "string" ? form[name] : undefined;
+                const { cfg, authDeps } = runtimeFor(result.settings);
+                // A denial is the package's `denied` outcome: it verifies state, expiry, client and
+                // session, then answers the redirect-to-client with error=access_denied and the
+                // client's state. `respond` appends `iss` to it like to every authorization response.
                 if (field("approved") === "false") {
-                    noStore(c);
-                    const locale = detectLocaleFromAcceptLanguage(c.req.header("accept-language"));
-                    return c.json({ error: "access_denied", error_description: t(locale, "oauth.denied") }, 403);
+                    const denied = await resumeAuthorize({ state: field("state") ?? "", sessionToken: sessionTokenFrom(c), denied: true }, cfg, authDeps);
+                    return respond(c, denied, result.settings);
                 }
-                const { cfg, authDeps } = runtimeFor(result.settings);
                 const outcome = await resumeAuthorize({
                     state: field("state") ?? "",
                     sessionToken: sessionTokenFrom(c),

package/dist/oauth/clerk.d.ts

@@ -12,4 +12,8 @@ export interface ClerkCollaborators {
     listMemberships(userId: string): Promise<readonly ClerkOrgMembership[]>;
     getUser(userId: string): Promise<ClerkUserLike>;
 }
-export declare function createClerkBackendCollaborators(secretKey: string, fetchImpl?: typeof fetch): ClerkCollaborators;
+export interface ClerkBackendOptions {
+    /** Per-call time budget (JWKS, memberships, user). Default 5 s. */
+    timeoutMs?: number;
+}
+export declare function createClerkBackendCollaborators(secretKey: string, fetchImpl?: typeof fetch, options?: ClerkBackendOptions): ClerkCollaborators;

package/dist/oauth/clerk.js

@@ -9,11 +9,16 @@
 const CLERK_API = "https://api.clerk.com/v1";
 const JWKS_CACHE_MS = 10 * 60 * 1000;
 const MEMBERSHIP_PAGE_LIMIT = 100;
-export function createClerkBackendCollaborators(secretKey, fetchImpl = fetch) {
+/** 50 pages x 100 = 5 000 memberships: past it the lookup FAILS rather than truncate. */
+const MEMBERSHIP_MAX_PAGES = 50;
+const CLERK_TIMEOUT_MS = 5000;
+export function createClerkBackendCollaborators(secretKey, fetchImpl = fetch, options = {}) {
+    const timeoutMs = options.timeoutMs ?? CLERK_TIMEOUT_MS;
     let cachedJwks = null;
     const api = async (path) => {
         const res = await fetchImpl(`${CLERK_API}${path}`, {
             headers: { Authorization: `Bearer ${secretKey}`, Accept: "application/json" },
+            signal: AbortSignal.timeout(timeoutMs),
         });
         if (!res.ok)
             throw new Error(`Clerk Backend API answered ${res.status}`);
@@ -25,7 +30,9 @@ export function createClerkBackendCollaborators(secretKey, fetchImpl = fetch) {
             if (cachedJwks && cachedJwks.issuer === issuer && now - cachedJwks.at < JWKS_CACHE_MS) {
                 return cachedJwks.keys;
             }
-            const res = await fetchImpl(`${issuer}/.well-known/jwks.json`);
+            const res = await fetchImpl(`${issuer}/.well-known/jwks.json`, {
+                signal: AbortSignal.timeout(timeoutMs),
+            });
             if (!res.ok)
                 throw new Error(`Clerk JWKS answered ${res.status}`);
             const keys = (await res.json());
@@ -33,15 +40,26 @@ export function createClerkBackendCollaborators(secretKey, fetchImpl = fetch) {
             return keys;
         },
         async listMemberships(userId) {
-            const page = await api(`/users/${encodeURIComponent(userId)}/organization_memberships?limit=${MEMBERSHIP_PAGE_LIMIT}`);
-            return page.data.map((m) => ({
-                role: m.role,
-                organization: {
-                    id: m.organization.id,
-                    slug: m.organization.slug ?? null,
-                    name: m.organization.name,
-                },
-            }));
+            const all = [];
+            for (let page = 0; page < MEMBERSHIP_MAX_PAGES; page++) {
+                const offset = page * MEMBERSHIP_PAGE_LIMIT;
+                const body = await api(`/users/${encodeURIComponent(userId)}/organization_memberships?limit=${MEMBERSHIP_PAGE_LIMIT}&offset=${offset}`);
+                all.push(...body.data);
+                const last = body.data.length < MEMBERSHIP_PAGE_LIMIT ||
+                    (typeof body.total_count === "number" && all.length >= body.total_count);
+                if (last) {
+                    return all.map((m) => ({
+                        role: m.role,
+                        organization: {
+                            id: m.organization.id,
+                            slug: m.organization.slug ?? null,
+                            name: m.organization.name,
+                        },
+                    }));
+                }
+            }
+            // A truncated list would hide organisations the person belongs to: refuse instead.
+            throw new Error(`Clerk memberships exceed ${MEMBERSHIP_MAX_PAGES * MEMBERSHIP_PAGE_LIMIT}`);
         },
         async getUser(userId) {
             const user = await api(`/users/${encodeURIComponent(userId)}`);