@vantageos/mcp-boilerplate 0.2.2 → 0.2.3

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "vantage-mcp-boilerplate",
   "displayName": "VantageOS MCP Boilerplate",
-  "version": "0.2.2",
+  "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,45 @@ 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

package/README.fr.md

@@ -148,6 +148,53 @@ clés d'API par organisation pour les clients hors ChatGPT (ce code n'a jamais e
 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
@@ -242,7 +289,7 @@ en un seul fichier HTML autonome (un plugin d'inlining local dans `vite.config.t
 `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.17.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

@@ -141,6 +141,49 @@ sign-in and callback URLs are refused outside loopback.
 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
@@ -234,7 +277,7 @@ 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.17.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/locales/en.json

@@ -19,7 +19,8 @@
       "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

@@ -19,7 +19,8 @@
       "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.js

@@ -49,7 +49,15 @@ export function createNodeListener(app, options = {}) {
             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));
+            // `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) {

package/dist/oauth/authorizationServer.d.ts

@@ -66,5 +66,11 @@ export interface NodeBindings {
  * 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 {};

package/dist/oauth/authorizationServer.js

@@ -20,16 +20,17 @@
  * FAIL-CLOSED: any missing configuration value answers 503 `temporarily_unavailable`.
  * No refresh tokens are issued; access tokens live one hour.
  */
-import { buildDiscoveryDocument, buildUserInfo, exchangeAuthorizationCode, oauthErrorFor, resumeAuthorize, startAuthorize, } from "@vantageos/cloud-identity";
+import { buildDiscoveryDocument, buildUserInfo, exchangeAuthorizationCode, oauthErrorFor, resumeAuthorize, startAuthorize, resolveClerkSessionFromRequest, } 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 { ASSERTION_SIGNING_ALGS, createClientAssertionVerifier } from "./clientAssertion.js";
 import { createInMemoryClientRegistry, isAllowedRedirectUri, isUrlShapedClientId, resolveCimdClient, } from "./clientRegistry.js";
 import { createInMemoryCodeStore } from "./codeStore.js";
 import { pickerContentSecurityPolicy, renderOrgPicker } from "./picker.js";
-import { DEFAULT_SCOPE, OAUTH_ENV, SUPPORTED_SCOPES, readAuthorizeSettings, } from "./settings.js";
+import { DEFAULT_SCOPE, OAUTH_ENV, SUPPORTED_SCOPES, isDevClerkInstanceOnRemoteServer, readAuthorizeSettings, } from "./settings.js";
 import { ACCESS_TOKEN_TTL_SECONDS, createTokenIssuer } from "./tokenIssuer.js";
 const REGISTER_LIMIT_PER_MINUTE = 20;
 const MAX_REDIRECT_URIS = 10;
@@ -57,6 +58,19 @@ export function clientKeyOf(c, trustedProxyCount) {
         ? (chain[chain.length - trustedProxyCount] ?? socket)
         : socket;
 }
+/**
+ * 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 function publishableKeyFor(env, clerkIssuer) {
+    const explicit = env.CLERK_PUBLISHABLE_KEY;
+    if (explicit)
+        return explicit;
+    const live = (env[OAUTH_ENV.clerkSecretKey] ?? "").startsWith("sk_live_");
+    const host = new URL(clerkIssuer).host;
+    return `pk_${live ? "live" : "test"}_${Buffer.from(`${host}$`).toString("base64")}`;
+}
 function sessionTokenFrom(c) {
     const header = c.req.header("authorization");
     if (header?.toLowerCase().startsWith("bearer ")) {
@@ -82,6 +96,11 @@ export function createAuthorizationServer(deps = {}) {
             console.warn(`[oauth] running on in-memory stores in production (${OAUTH_ENV.allowInMemoryStores}=1): single instance only, state is lost on restart`);
         }
     }
+    // A warning, never a refusal: a development Clerk instance is legitimate for a remote test once
+    // its Home URL points at this server. English then French, the boot has no request locale.
+    if (isDevClerkInstanceOnRemoteServer(env)) {
+        console.warn(`[oauth] ${t("en", "oauth.devInstanceRemote")}\n[oauth] ${t("fr", "oauth.devInstanceRemote")}`);
+    }
     const codeStore = deps.codeStore ?? createInMemoryCodeStore();
     const registry = deps.clientRegistry ?? createInMemoryClientRegistry();
     const injectedClerk = deps.clerk;
@@ -102,6 +121,11 @@ export function createAuthorizationServer(deps = {}) {
         getUser: injectedClerk?.getUser ?? backendClerk.getUser,
     });
     const settingsNow = () => readAuthorizeSettings(env, clerkInjected);
+    const assertionVerifier = createClientAssertionVerifier({
+        fetchImpl: deps.fetchImpl,
+        resolveHost: deps.resolveHost,
+        now,
+    });
     const lookupClient = async (clientId) => {
         if (isUrlShapedClientId(clientId)) {
             return resolveCimdClient(clientId, {
@@ -239,7 +263,8 @@ export function createAuthorizationServer(deps = {}) {
                 }
                 return c.json({
                     ...doc.document,
-                    token_endpoint_auth_methods_supported: ["none"],
+                    token_endpoint_auth_methods_supported: ["none", "private_key_jwt"],
+                    token_endpoint_auth_signing_alg_values_supported: [...ASSERTION_SIGNING_ALGS],
                     // RFC 9207 — /authorize appends `iss` to every authorization response.
                     authorization_response_iss_parameter_supported: true,
                     // Client ID Metadata Documents are fetched SSRF-guarded (clientRegistry.ts).
@@ -330,7 +355,38 @@ export function createAuthorizationServer(deps = {}) {
                 if (!result.ok)
                     return unavailable(c, result.missing);
                 const { cfg, authDeps } = runtimeFor(result.settings);
-                const outcome = await resumeAuthorize({ state: c.req.query("authorize_state") ?? "", sessionToken: sessionTokenFrom(c) }, cfg, authDeps);
+                let sessionToken = sessionTokenFrom(c);
+                // On return from Clerk's hosted sign-in the session is not on this host yet (on a
+                // development instance it lives on accounts.dev). Clerk's own handshake brings it:
+                // the SDK answers `handshake` (redirect + Set-Cookie) and comes back with `__session`.
+                // An explicit Bearer token is the signed-in case already; injected collaborators (tests,
+                // custom deployments) skip the SDK, which needs the secret key.
+                const hasBearer = c.req.header("authorization")?.toLowerCase().startsWith("bearer ");
+                if (!hasBearer && !clerkInjected && (env[OAUTH_ENV.clerkSecretKey] ?? "") !== "") {
+                    // A forged or stale `__clerk_handshake` makes the SDK throw. That is no session,
+                    // never a 500: the request continues signed out and resumeAuthorize refuses it.
+                    const session = await resolveClerkSessionFromRequest(c.req.raw, {
+                        secretKey: env[OAUTH_ENV.clerkSecretKey] ?? "",
+                        publishableKey: publishableKeyFor(env, result.settings.clerkIssuer),
+                        authorizedParties: result.settings.authorizedParties,
+                    }).catch(() => ({ kind: "signed-out" }));
+                    if (session.kind === "handshake") {
+                        // A raw Response bypasses the context's headers, so no-store is set on it directly.
+                        const headers = new Headers(session.headers);
+                        headers.set("Cache-Control", "no-store");
+                        headers.set("Pragma", "no-cache");
+                        return new Response(null, { status: session.status, headers });
+                    }
+                    sessionToken = session.kind === "signed-in" ? session.sessionToken : undefined;
+                    // The handshake return carries the cookies (`__session`, `__client_uat`) the picker's
+                    // form post needs on this host: hand them to the browser with the response.
+                    if (session.kind === "signed-in") {
+                        for (const cookie of session.headers.getSetCookie()) {
+                            c.header("Set-Cookie", cookie, { append: true });
+                        }
+                    }
+                }
+                const outcome = await resumeAuthorize({ state: c.req.query("authorize_state") ?? "", sessionToken }, cfg, authDeps);
                 return respond(c, outcome, result.settings);
             });
             // The picker's form post. `consentToken` is the CSRF protection: a cross-site form
@@ -352,7 +408,13 @@ export function createAuthorizationServer(deps = {}) {
                 // 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") {
-                    const denied = await resumeAuthorize({ state: field("state") ?? "", sessionToken: sessionTokenFrom(c), denied: true }, cfg, authDeps);
+                    const denied = await resumeAuthorize({
+                        state: field("state") ?? "",
+                        sessionToken: sessionTokenFrom(c),
+                        denied: true,
+                        // cloud-identity >= 0.18 verifies the consent token on a denial too.
+                        consentToken: field("consentToken"),
+                    }, cfg, authDeps);
                     return respond(c, denied, result.settings);
                 }
                 const outcome = await resumeAuthorize({
@@ -386,7 +448,22 @@ export function createAuthorizationServer(deps = {}) {
                 if (body.grant_type !== "authorization_code") {
                     return c.json({ error: "unsupported_grant_type" }, 400);
                 }
-                const { code, code_verifier: codeVerifier, redirect_uri: redirectUri, client_id: clientId, } = body;
+                const { code, code_verifier: codeVerifier, redirect_uri: redirectUri, client_id: sentClientId, } = body;
+                // A presented credential is never ignored: an assertion is verified before anything else
+                // and yields the client_id. Without an assertion the public-client path applies.
+                let clientId = sentClientId;
+                if (body.client_assertion !== undefined || body.client_assertion_type !== undefined) {
+                    const verified = await assertionVerifier.verify({
+                        assertionType: body.client_assertion_type,
+                        assertion: body.client_assertion,
+                        clientId: sentClientId,
+                        audiences: [`${settings.baseUrl}/token`, settings.baseUrl],
+                    });
+                    if (!verified.ok) {
+                        return c.json({ error: "invalid_client", error_description: verified.reason }, 401);
+                    }
+                    clientId = verified.clientId;
+                }
                 if (!code || !codeVerifier || !redirectUri || !clientId) {
                     return c.json({
                         error: "invalid_request",

package/dist/oauth/clientAssertion.d.ts

@@ -0,0 +1,28 @@
+import { type CimdOptions } from "./clientRegistry.js";
+export declare const JWT_BEARER_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer";
+export declare const ASSERTION_SIGNING_ALGS: readonly ["RS256"];
+export type AssertionResult = {
+    ok: true;
+    clientId: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Bounded set of accepted jti values, each held until its assertion expires. */
+export declare function createJtiStore(maxEntries?: number): {
+    /** True when the jti is new (and is now recorded); false on a replay or when full. */
+    accept(clientId: string, jti: string, exp: number, nowSeconds: number): boolean;
+};
+export interface AssertionVerifierOptions extends CimdOptions {
+    now?: () => number;
+    jtiStore?: ReturnType<typeof createJtiStore>;
+}
+export declare function createClientAssertionVerifier(options?: AssertionVerifierOptions): {
+    verify(input: {
+        assertionType: string | undefined;
+        assertion: string | undefined;
+        /** The `client_id` request parameter, when sent. */
+        clientId: string | undefined;
+        audiences: string[];
+    }): Promise<AssertionResult>;
+};

package/dist/oauth/clientAssertion.js

@@ -0,0 +1,106 @@
+/**
+ * private_key_jwt client authentication at `/token` (RFC 7523 / OIDC Core 9).
+ *
+ * A presented assertion is VERIFIED, never ignored and never trusted unverified:
+ *  - the key set comes from the `jwks_uri` of the client's CIMD document, fetched through the
+ *    same SSRF guard as the document itself;
+ *  - alg is pinned to RS256 (a document declaring another signing alg is refused), so `none`
+ *    and HMAC assertions cannot verify;
+ *  - `iss` and `sub` equal the client_id; `aud` is this token endpoint or this issuer; `exp`
+ *    is required (30 s skew); `jti` is required and accepted ONCE.
+ */
+import { createLocalJWKSet, decodeJwt, jwtVerify } from "jose";
+import { fetchGuardedJson, isUrlShapedClientId, resolveCimdDocument, } from "./clientRegistry.js";
+export const JWT_BEARER_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer";
+export const ASSERTION_SIGNING_ALGS = ["RS256"];
+const SKEW_SECONDS = 30;
+const MAX_JWKS_BYTES = 64 * 1024;
+/** Bounded set of accepted jti values, each held until its assertion expires. */
+export function createJtiStore(maxEntries = 10_000) {
+    const seen = new Map(); // `${clientId}\n${jti}` -> exp (epoch seconds)
+    return {
+        /** True when the jti is new (and is now recorded); false on a replay or when full. */
+        accept(clientId, jti, exp, nowSeconds) {
+            for (const [k, e] of seen)
+                if (e + SKEW_SECONDS <= nowSeconds)
+                    seen.delete(k);
+            const key = `${clientId}\n${jti}`;
+            if (seen.has(key))
+                return false;
+            if (seen.size >= maxEntries)
+                return false; // fail closed: never evict a live jti
+            seen.set(key, exp);
+            return true;
+        },
+    };
+}
+export function createClientAssertionVerifier(options = {}) {
+    const now = options.now ?? (() => Date.now());
+    const jtiStore = options.jtiStore ?? createJtiStore();
+    const fetchOpts = {
+        fetchImpl: options.fetchImpl,
+        resolveHost: options.resolveHost,
+        maxBytes: MAX_JWKS_BYTES,
+        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+    };
+    return {
+        async verify(input) {
+            const fail = (reason) => ({ ok: false, reason });
+            if (input.assertionType !== JWT_BEARER_ASSERTION_TYPE || !input.assertion) {
+                return fail("unsupported client assertion");
+            }
+            // The unverified iss only LOCATES the key set; it is re-checked against the verified claims.
+            let claimedIss;
+            try {
+                claimedIss = decodeJwt(input.assertion).iss;
+            }
+            catch {
+                return fail("malformed client assertion");
+            }
+            if (!claimedIss || !isUrlShapedClientId(claimedIss))
+                return fail("unknown client");
+            if (input.clientId !== undefined && input.clientId !== claimedIss) {
+                return fail("client_id does not match the assertion issuer");
+            }
+            const clientId = claimedIss;
+            const cimd = await resolveCimdDocument(clientId, options);
+            if (!cimd?.jwksUri)
+                return fail("client has no verifiable key set");
+            if (cimd.signingAlg !== undefined &&
+                !ASSERTION_SIGNING_ALGS.includes(cimd.signingAlg)) {
+                return fail("unsupported signing algorithm");
+            }
+            let jwksUrl;
+            try {
+                jwksUrl = new URL(cimd.jwksUri);
+            }
+            catch {
+                return fail("invalid jwks_uri");
+            }
+            const jwks = (await fetchGuardedJson(jwksUrl, fetchOpts));
+            if (!jwks || !Array.isArray(jwks.keys))
+                return fail("key set unavailable");
+            let payload;
+            try {
+                const verified = await jwtVerify(input.assertion, createLocalJWKSet(jwks), {
+                    algorithms: [...ASSERTION_SIGNING_ALGS],
+                    issuer: clientId,
+                    subject: clientId,
+                    audience: input.audiences,
+                    clockTolerance: SKEW_SECONDS,
+                    currentDate: new Date(now()),
+                    requiredClaims: ["iss", "sub", "aud", "exp", "jti"],
+                });
+                payload = verified.payload;
+            }
+            catch {
+                return fail("client assertion rejected");
+            }
+            const exp = payload.exp;
+            if (!payload.jti || !jtiStore.accept(clientId, payload.jti, exp, Math.floor(now() / 1000))) {
+                return fail("client assertion replayed");
+            }
+            return { ok: true, clientId };
+        },
+    };
+}

package/dist/oauth/clientRegistry.d.ts

@@ -50,6 +50,20 @@ export interface CimdOptions {
 }
 /** True when a client_id is URL-shaped, i.e. a CIMD identifier (valid or not). */
 export declare function isUrlShapedClientId(clientId: string): boolean;
+/**
+ * The one SSRF-guarded fetch shared by the CIMD document and the client's JWKS: https only,
+ * public addresses only, no redirects, size and time capped. Returns the parsed JSON, or null
+ * for ANY failure.
+ */
+export declare function fetchGuardedJson(url: URL, options?: CimdOptions): Promise<unknown>;
+/** A validated CIMD: the client plus what `/token` needs to verify a private_key_jwt assertion. */
+export interface CimdDocument {
+    client: AuthorizeClient;
+    /** Present only when the document declares an https `jwks_uri`. */
+    jwksUri?: string;
+    /** The document's `token_endpoint_auth_signing_alg`, when declared. */
+    signingAlg?: string;
+}
 /**
  * Fetches and validates a Client ID Metadata Document. Returns null for ANY failure — an
  * unreachable, oversized, malformed, private-addressed or self-contradicting document is an
@@ -59,4 +73,5 @@ export declare function isUrlShapedClientId(clientId: string): boolean;
  * the fetch resolves it again, so a DNS-rebinding window exists. A hostile-network deployment
  * injects a `fetchImpl` that pins the validated address (for example an undici dispatcher).
  */
+export declare function resolveCimdDocument(clientId: string, options?: CimdOptions): Promise<CimdDocument | null>;
 export declare function resolveCimdClient(clientId: string, options?: CimdOptions): Promise<AuthorizeClient | null>;

package/dist/oauth/clientRegistry.js

@@ -208,6 +208,38 @@ async function readCappedText(res, maxBytes) {
 export function isUrlShapedClientId(clientId) {
     return /^https?:\/\//i.test(clientId);
 }
+/**
+ * The one SSRF-guarded fetch shared by the CIMD document and the client's JWKS: https only,
+ * public addresses only, no redirects, size and time capped. Returns the parsed JSON, or null
+ * for ANY failure.
+ */
+export async function fetchGuardedJson(url, options = {}) {
+    const { fetchImpl = fetch, resolveHost = defaultResolveHost } = options;
+    const maxBytes = options.maxBytes ?? 16 * 1024;
+    const timeoutMs = options.timeoutMs ?? 5000;
+    try {
+        if (url.protocol !== "https:" || url.username || url.password || url.hash)
+            return null;
+        const host = url.hostname.replace(/^\[|\]$/g, "");
+        const addresses = isIP(host) ? [host] : await resolveHost(host);
+        if (addresses.length === 0 || !addresses.every(isPublicAddress))
+            return null;
+        const res = await fetchImpl(url, {
+            redirect: "error",
+            headers: { Accept: "application/json" },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok)
+            return null;
+        const text = await readCappedText(res, maxBytes);
+        if (text === null)
+            return null;
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Fetches and validates a Client ID Metadata Document. Returns null for ANY failure — an
  * unreachable, oversized, malformed, private-addressed or self-contradicting document is an
@@ -217,10 +249,7 @@ export function isUrlShapedClientId(clientId) {
  * the fetch resolves it again, so a DNS-rebinding window exists. A hostile-network deployment
  * injects a `fetchImpl` that pins the validated address (for example an undici dispatcher).
  */
-export async function resolveCimdClient(clientId, options = {}) {
-    const { fetchImpl = fetch, resolveHost = defaultResolveHost } = options;
-    const maxBytes = options.maxBytes ?? 16 * 1024;
-    const timeoutMs = options.timeoutMs ?? 5000;
+export async function resolveCimdDocument(clientId, options = {}) {
     let url;
     try {
         url = new URL(clientId);
@@ -234,39 +263,37 @@ export async function resolveCimdClient(clientId, options = {}) {
         return null; // the spec requires a path
     if (url.href !== clientId)
         return null; // client_id is compared as a string; no normalisation
-    try {
-        const host = url.hostname.replace(/^\[|\]$/g, "");
-        const addresses = isIP(host) ? [host] : await resolveHost(host);
-        if (addresses.length === 0 || !addresses.every(isPublicAddress))
-            return null;
-        const res = await fetchImpl(url, {
-            redirect: "error",
-            headers: { Accept: "application/json" },
-            signal: AbortSignal.timeout(timeoutMs),
-        });
-        if (!res.ok)
-            return null;
-        const text = await readCappedText(res, maxBytes);
-        if (text === null)
-            return null;
-        const doc = JSON.parse(text);
-        if (doc.client_id !== clientId)
-            return null;
-        const method = doc.token_endpoint_auth_method;
-        if (method !== undefined && method !== "none")
-            return null; // public clients only
-        const uris = doc.redirect_uris;
-        if (!Array.isArray(uris) || uris.length === 0 || uris.length > 20)
-            return null;
-        if (!uris.every(isAllowedRedirectUri))
-            return null;
-        return {
+    const parsed = await fetchGuardedJson(url, options);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        return null;
+    const doc = parsed;
+    if (doc.client_id !== clientId)
+        return null;
+    // The document must offer "none", either as its method or among the methods it supports (a
+    // client such as ChatGPT declares private_key_jwt and lists "none"). A client that sends no
+    // assertion is a public client and PKCE carries the proof; one that does is verified at /token.
+    const method = doc.token_endpoint_auth_method;
+    const supported = doc.token_endpoint_auth_methods_supported;
+    const acceptsNone = Array.isArray(supported) && supported.includes("none");
+    if (method !== undefined && method !== "none" && !acceptsNone)
+        return null;
+    const uris = doc.redirect_uris;
+    if (!Array.isArray(uris) || uris.length === 0 || uris.length > 20)
+        return null;
+    if (!uris.every(isAllowedRedirectUri))
+        return null;
+    return {
+        client: {
             clientId,
             redirectUris: uris,
             ...(typeof doc.client_name === "string" ? { clientName: doc.client_name.slice(0, 200) } : {}),
-        };
-    }
-    catch {
-        return null;
-    }
+        },
+        ...(typeof doc.jwks_uri === "string" ? { jwksUri: doc.jwks_uri } : {}),
+        ...(typeof doc.token_endpoint_auth_signing_alg === "string"
+            ? { signingAlg: doc.token_endpoint_auth_signing_alg }
+            : {}),
+    };
+}
+export async function resolveCimdClient(clientId, options = {}) {
+    return (await resolveCimdDocument(clientId, options))?.client ?? null;
 }

package/dist/oauth/settings.d.ts

@@ -53,3 +53,11 @@ export type AuthorizeSettingsResult = {
  * secret key is then not required.
  */
 export declare function readAuthorizeSettings(env: NodeJS.ProcessEnv, clerkCollaboratorsInjected?: boolean): Promise<AuthorizeSettingsResult>;
+/**
+ * True when the configured Clerk instance is a DEVELOPMENT one (an `sk_test_` secret key, or a
+ * Frontend API domain under `accounts.dev`) while PUBLIC_BASE_URL is not loopback. A development
+ * instance's hosted sign-in redirects only to localhost or to the instance Home URL, so a remote
+ * server needs that Home URL pointed at it. Absent or malformed values answer `false`: this feeds
+ * a warning, and the readiness of the settings is decided by `readAuthorizeSettings`, not here.
+ */
+export declare function isDevClerkInstanceOnRemoteServer(env: NodeJS.ProcessEnv): boolean;

package/dist/oauth/settings.js

@@ -116,3 +116,32 @@ export async function readAuthorizeSettings(env, clerkCollaboratorsInjected = fa
         },
     };
 }
+/**
+ * True when the configured Clerk instance is a DEVELOPMENT one (an `sk_test_` secret key, or a
+ * Frontend API domain under `accounts.dev`) while PUBLIC_BASE_URL is not loopback. A development
+ * instance's hosted sign-in redirects only to localhost or to the instance Home URL, so a remote
+ * server needs that Home URL pointed at it. Absent or malformed values answer `false`: this feeds
+ * a warning, and the readiness of the settings is decided by `readAuthorizeSettings`, not here.
+ */
+export function isDevClerkInstanceOnRemoteServer(env) {
+    let baseHost;
+    try {
+        baseHost = new URL(env[OAUTH_ENV.publicBaseUrl] ?? "").hostname;
+    }
+    catch {
+        return false;
+    }
+    if (baseHost === "" || LOOPBACK_HOSTS.has(baseHost) || LOOPBACK_HOSTS.has(`[${baseHost}]`)) {
+        return false;
+    }
+    const devKey = (env[OAUTH_ENV.clerkSecretKey] ?? "").startsWith("sk_test_");
+    let devDomain = false;
+    try {
+        const host = new URL(env[OAUTH_ENV.clerkIssuer] ?? "").hostname;
+        devDomain = host === "accounts.dev" || host.endsWith(".accounts.dev");
+    }
+    catch {
+        devDomain = false;
+    }
+    return devKey || devDomain;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vantageos/mcp-boilerplate",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Clonable MCP server skeleton on the official @modelcontextprotocol/server SDK v2 (protocol 2026-07-28 + 2025 legacy, stdio + stateless Streamable HTTP), with its own OAuth 2.1 authorization server (Clerk person + organisation, cloud-identity), MCP Apps UI, tenant scoping, FR/EN i18n and a declarative eval harness.",
   "description_fr": "Squelette de serveur MCP clonable sur le SDK officiel @modelcontextprotocol/server v2 (protocole 2026-07-28 + héritage 2025, stdio + Streamable HTTP sans état), avec son propre serveur d'autorisation OAuth 2.1 (personne + organisation Clerk, cloud-identity), UI MCP Apps, scoping tenant, i18n FR/EN et un harnais d'évaluations déclaratif.",
   "type": "module",
@@ -75,7 +75,7 @@
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^2.0.3",
     "@modelcontextprotocol/server": "^2.3.1",
-    "@vantageos/cloud-identity": "^0.17.0",
+    "@vantageos/cloud-identity": "^0.19.0",
     "@vantageos/mosaic-i18n": "^0.1.1",
     "hono": "^4.13.13",
     "jose": "^6.2.7",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "vantage-mcp-boilerplate",
-  "version": "0.2.2",
+  "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"