@vantageos/mcp-boilerplate 0.6.2 → 0.6.3

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "vantage-mcp-boilerplate",
   "displayName": "VantageOS MCP Boilerplate",
-  "version": "0.6.2",
+  "version": "0.6.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,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.6.3] - 2026-11-01
+
+### Fixed
+- The consent approval (and denial) no longer breaks for clients whose redirect target redirects again (VS Code: `vscode.dev/redirect`, then `vscode://` or a loopback). A browser applies the consent page's `form-action` to every redirect hop of the form submission, so the 302 to the client was blocked at the client's own next hop. The POST to `/authorize/org` now answers a same-origin hand-off page (200, meta refresh plus a visible link, CSP `default-src 'none'; form-action 'none'; frame-ancestors 'none'`), which ends the form submission here. The return from sign-in (a GET) still answers a plain redirect.
+
+### Added
+- `AUTHORIZE_ALLOWED_ORG_IDS` (comma-separated Clerk organisation ids): the consent offers only the person's organisations that this server authorises. Any other membership is not listed, an approval for one is refused with 403, and a person with none of them gets a 403 with a localized message instead of a picker. Unset, behaviour is unchanged.
+
 ## [0.6.2] - 2026-11-01
 
 ### Fixed
@@ -498,6 +506,7 @@ Initial published release.
 - MIT license, clonable as a starter template.
 
 [Unreleased]: https://github.com/elpiarthera/vantage-mcp-boilerplate/compare/v0.4.0...HEAD
+[0.6.3]: https://www.npmjs.com/package/@vantageos/mcp-boilerplate/v/0.6.3
 [0.6.2]: https://www.npmjs.com/package/@vantageos/mcp-boilerplate/v/0.6.2
 [0.6.1]: https://www.npmjs.com/package/@vantageos/mcp-boilerplate/v/0.6.1
 [0.6.0]: https://www.npmjs.com/package/@vantageos/mcp-boilerplate/v/0.6.0

package/README.fr.md

@@ -259,7 +259,14 @@ fonctionne sur un serveur que vous hébergez, dans cet ordre :
    VantagePeers : sombre par défaut, clair quand le système de la personne le demande, une
    carte par organisation avec son rôle. Elle ne charge aucune ressource externe et porte donc
    ses propres tokens. Réglez `AUTHORIZE_BRAND_NAME` pour afficher le nom de votre produit
-   au-dessus du titre ; rien n'est affiché par défaut.
+   au-dessus du titre ; rien n'est affiché par défaut. Réglez `AUTHORIZE_ALLOWED_ORG_IDS`
+   (identifiants d'organisation Clerk séparés par des virgules) pour ne proposer que les
+   organisations que ce serveur autorise : les autres appartenances ne sont pas listées, une
+   validation pour l'une d'elles est refusée (403), et une personne qui n'en a aucune reçoit un
+   403 avec un message au lieu du choix. Non réglé, toutes les appartenances sont proposées.
+   Valider ou refuser répond une courte page de la même origine qui renvoie le navigateur vers
+   le client, pour que le `form-action` de la page ne bloque pas un client dont la cible de
+   redirection redirige à nouveau (le `vscode.dev/redirect` de VS Code).
 
 ### Multi-tenance
 

package/README.md

@@ -245,7 +245,14 @@ server you host, in this order:
 6. **The consent page.** The organisation picker uses the VantagePeers dashboard design: dark
    by default, light when the person's system asks for it, one card per organisation with its
    role. It loads no external asset, so it carries its own tokens. Set `AUTHORIZE_BRAND_NAME`
-   to show your product's name above the title; nothing is shown by default.
+   to show your product's name above the title; nothing is shown by default. Set
+   `AUTHORIZE_ALLOWED_ORG_IDS` (comma-separated Clerk organisation ids) to offer only the
+   organisations this server authorises: other memberships are not listed, an approval for one
+   of them is refused (403), and a person with none of them gets a 403 with a message instead of
+   a picker. Unset, every membership is offered.
+   Approving or denying answers a short same-origin page that sends the browser on to the
+   client, so the page's `form-action` does not block a client whose redirect target redirects
+   again (VS Code's `vscode.dev/redirect`).
 
 ### Multi-tenancy
 

package/dist/locales/en.json

@@ -18,6 +18,9 @@
     "oauth": {
       "pickerTitle": "Connect {client}",
       "pickerIntro": "{client} asks to act on your behalf. Choose the organisation it may reach, then approve or deny.",
+      "handoffTitle": "Returning to the application",
+      "handoffLink": "Continue to the application",
+      "pickerNoAllowedOrganisation": "None of your organisations is authorised on this server.",
       "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.",

package/dist/locales/fr.json

@@ -18,6 +18,9 @@
     "oauth": {
       "pickerTitle": "Connecter {client}",
       "pickerIntro": "{client} demande à agir en votre nom. Choisissez l'organisation à laquelle il peut accéder, puis approuvez ou refusez.",
+      "handoffTitle": "Retour à l'application",
+      "handoffLink": "Continuer vers l'application",
+      "pickerNoAllowedOrganisation": "Aucune de vos organisations n'est autorisée sur ce serveur.",
       "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.",

package/dist/oauth/authorizationServer.js

@@ -29,7 +29,7 @@ import { createClerkBackendCollaborators } from "./clerk.js";
 import { ASSERTION_SIGNING_ALGS, createClientAssertionVerifier } from "./clientAssertion.js";
 import { RegistryFullError, createInMemoryClientRegistry, isAllowedRedirectUri, isUrlShapedClientId, resolveCimdClient, } from "./clientRegistry.js";
 import { createInMemoryCodeStore } from "./codeStore.js";
-import { pickerContentSecurityPolicy, renderOrgPicker } from "./picker.js";
+import { HANDOFF_CSP, pickerContentSecurityPolicy, renderHandoff, renderOrgPicker, } from "./picker.js";
 import { createRegisterLimiter } from "./registerLimiter.js";
 import { DEFAULT_SCOPE, OAUTH_ENV, SUPPORTED_SCOPES, isDevClerkInstanceOnRemoteServer, readAuthorizeSettings, } from "./settings.js";
 import { ACCESS_TOKEN_TTL_SECONDS, createTokenIssuer } from "./tokenIssuer.js";
@@ -198,6 +198,16 @@ export function createAuthorizationServer(deps = {}) {
         const client = await lookupClient(model.client.clientId);
         return (client?.redirectUris ?? []).filter((u) => !/^https?:/i.test(u));
     };
+    /** The organisations this server authorises (AUTHORIZE_ALLOWED_ORG_IDS), or undefined when every membership is. */
+    const allowedOrgIds = () => {
+        const raw = env[OAUTH_ENV.allowedOrgIds]?.trim();
+        if (!raw)
+            return undefined;
+        return new Set(raw
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean));
+    };
     const respond = async (c, outcome, settings) => {
         noStore(c);
         c.header("Referrer-Policy", "no-referrer");
@@ -208,12 +218,33 @@ export function createAuthorizationServer(deps = {}) {
                 // RFC 9207 section 2: identify the issuer in the authorization response.
                 const back = new URL(outcome.url);
                 back.searchParams.set("iss", settings.baseUrl);
+                // The consent form's POST ends here, in a same-origin page, so its form-action does not follow the client's
+                // own redirect hops (renderHandoff). A GET (the return from sign-in) still answers a plain redirect.
+                if (c.req.method === "POST") {
+                    c.header("Content-Security-Policy", HANDOFF_CSP);
+                    const locale = detectLocaleFromAcceptLanguage(c.req.header("accept-language"));
+                    return c.html(renderHandoff(back.toString(), locale));
+                }
                 return c.redirect(back.toString(), 302);
             }
             case "org-picker": {
+                // Only this server's authorised organisations are offered (data per server).
+                const allowed = allowedOrgIds();
+                let model = outcome.model;
+                if (allowed) {
+                    const organizations = model.organizations.filter((o) => allowed.has(o.id));
+                    if (organizations.length === 0) {
+                        const locale = detectLocaleFromAcceptLanguage(c.req.header("accept-language"));
+                        return c.json({
+                            error: "access_denied",
+                            error_description: t(locale, "oauth.pickerNoAllowedOrganisation"),
+                        }, 403);
+                    }
+                    model = { ...model, organizations };
+                }
                 let csp;
                 try {
-                    csp = await pickerContentSecurityPolicy(await redirectTargetsOf(outcome.model));
+                    csp = await pickerContentSecurityPolicy(await redirectTargetsOf(model));
                 }
                 catch (err) {
                     // Fail closed: without a parseable destination the page is not rendered at all.
@@ -222,9 +253,9 @@ export function createAuthorizationServer(deps = {}) {
                 }
                 c.header("Content-Security-Policy", csp);
                 const locale = detectLocaleFromAcceptLanguage(c.req.header("accept-language"));
-                return c.html(renderOrgPicker(outcome.model, locale, {
+                return c.html(renderOrgPicker(model, locale, {
                     // Only a URL-shaped (CIMD) client_id is bound to a domain its owner controls.
-                    unverified: !isUrlShapedClientId(outcome.model.client.clientId),
+                    unverified: !isUrlShapedClientId(model.client.clientId),
                     brandName: env[OAUTH_ENV.brandName]?.trim() || undefined,
                 }));
             }
@@ -463,6 +494,15 @@ export function createAuthorizationServer(deps = {}) {
                     }, cfg, authDeps);
                     return respond(c, denied, result.settings);
                 }
+                // An approval for an organisation this server does not authorise never reaches the code issuer.
+                const allowed = allowedOrgIds();
+                if (allowed && !allowed.has(field("orgId") ?? "")) {
+                    const locale = detectLocaleFromAcceptLanguage(c.req.header("accept-language"));
+                    return c.json({
+                        error: "access_denied",
+                        error_description: t(locale, "oauth.pickerNoAllowedOrganisation"),
+                    }, 403);
+                }
                 const outcome = await resumeAuthorize({
                     state: field("state") ?? "",
                     sessionToken: sessionTokenFrom(c),

package/dist/oauth/picker.d.ts

@@ -19,3 +19,14 @@ export interface ConsentContext {
     brandName?: string;
 }
 export declare function renderOrgPicker(model: OrgPickerModel, locale: McpLocale, consent: ConsentContext): string;
+/** The CSP of the hand-off page: nothing runs, nothing is submitted, nothing frames it. */
+export declare const HANDOFF_CSP = "default-src 'none'; form-action 'none'; frame-ancestors 'none'; base-uri 'none'";
+/**
+ * The page that ends the consent form submission inside this origin and sends the browser on to the client.
+ *
+ * A browser applies the consent page's `form-action` to every redirect hop of the form submission, so answering the
+ * POST with a 302 to the client's redirect_uri lets the client's OWN next hop (vscode.dev/redirect -> vscode:// or a
+ * loopback) be blocked by our policy. This page is a 200 response: the navigation to the client is a meta refresh (and
+ * a visible link), not a form submission, so `form-action` no longer follows it.
+ */
+export declare function renderHandoff(target: string, locale: McpLocale): string;

package/dist/oauth/picker.js

@@ -148,3 +148,30 @@ ${orgs}
 </html>
 `;
 }
+/** The CSP of the hand-off page: nothing runs, nothing is submitted, nothing frames it. */
+export const HANDOFF_CSP = "default-src 'none'; form-action 'none'; frame-ancestors 'none'; base-uri 'none'";
+/**
+ * The page that ends the consent form submission inside this origin and sends the browser on to the client.
+ *
+ * A browser applies the consent page's `form-action` to every redirect hop of the form submission, so answering the
+ * POST with a 302 to the client's redirect_uri lets the client's OWN next hop (vscode.dev/redirect -> vscode:// or a
+ * loopback) be blocked by our policy. This page is a 200 response: the navigation to the client is a meta refresh (and
+ * a visible link), not a form submission, so `form-action` no longer follows it.
+ */
+export function renderHandoff(target, locale) {
+    const url = escapeHtml(target);
+    const title = escapeHtml(t(locale, "oauth.handoffTitle"));
+    return `<!doctype html>
+<html lang="${locale}">
+<head>
+<meta charset="utf-8">
+<meta http-equiv="refresh" content="0;url=${url}">
+<title>${title}</title>
+</head>
+<body>
+<p>${title}</p>
+<p><a href="${url}">${escapeHtml(t(locale, "oauth.handoffLink"))}</a></p>
+</body>
+</html>
+`;
+}

package/dist/oauth/settings.d.ts

@@ -24,6 +24,11 @@ export declare const OAUTH_ENV: {
     readonly allowInMemoryStores: "MCP_ALLOW_IN_MEMORY_STORES";
     /** Optional display name shown above the consent page title (default: none). */
     readonly brandName: "AUTHORIZE_BRAND_NAME";
+    /**
+     * Optional comma-separated Clerk organisation ids this server authorises. When set, the consent offers only the
+     * person's memberships in this list and refuses an approval for any other. Data per server, never code.
+     */
+    readonly allowedOrgIds: "AUTHORIZE_ALLOWED_ORG_IDS";
 };
 /** Scope granted when a client names none: MCP access plus the OIDC subject. */
 export declare const MCP_SCOPE = "mcp:full";

package/dist/oauth/settings.js

@@ -24,6 +24,11 @@ export const OAUTH_ENV = {
     allowInMemoryStores: "MCP_ALLOW_IN_MEMORY_STORES",
     /** Optional display name shown above the consent page title (default: none). */
     brandName: "AUTHORIZE_BRAND_NAME",
+    /**
+     * Optional comma-separated Clerk organisation ids this server authorises. When set, the consent offers only the
+     * person's memberships in this list and refuses an approval for any other. Data per server, never code.
+     */
+    allowedOrgIds: "AUTHORIZE_ALLOWED_ORG_IDS",
 };
 /** Scope granted when a client names none: MCP access plus the OIDC subject. */
 export const MCP_SCOPE = "mcp:full";

package/mcp-server.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-boilerplate",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "capabilities": {
     "tools": {},
     "resources": {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vantageos/mcp-boilerplate",
-  "version": "0.6.2",
+  "version": "0.6.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",

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.6.2",
+  "version": "0.6.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"