@vantageos/mcp-boilerplate 0.2.1 → 0.2.3

package/dist/oauth/clientRegistry.js

@@ -12,15 +12,38 @@
  */
 import { lookup } from "node:dns/promises";
 import { BlockList, isIP } from "node:net";
-export function createInMemoryClientRegistry(maxClients = 10_000) {
+/**
+ * Bounded in-memory registry. DCR is unauthenticated, so it can never grow without limit and
+ * never stops accepting registrations either: expired clients are swept on every registration,
+ * and at the cap the oldest client is evicted (an evicted client re-registers).
+ */
+export function createInMemoryClientRegistry(options = {}) {
+    const maxClients = options.maxClients ?? 10_000;
+    const ttlMs = (options.ttlSeconds ?? 30 * 24 * 3600) * 1000;
+    const now = options.now ?? (() => Date.now());
     const clients = new Map();
+    const expired = (client) => client.issuedAt * 1000 + ttlMs <= now();
     return {
         async get(clientId) {
-            return clients.get(clientId) ?? null;
+            const client = clients.get(clientId);
+            if (!client)
+                return null;
+            if (expired(client)) {
+                clients.delete(clientId);
+                return null;
+            }
+            return client;
         },
         async register(client) {
-            if (clients.size >= maxClients) {
-                throw new Error("client registry is full");
+            for (const [id, row] of clients)
+                if (expired(row))
+                    clients.delete(id);
+            clients.delete(client.clientId); // re-registering moves it to the newest position
+            while (clients.size >= maxClients) {
+                const oldest = clients.keys().next();
+                if (oldest.done)
+                    break;
+                clients.delete(oldest.value);
             }
             clients.set(client.clientId, client);
         },
@@ -73,6 +96,7 @@ const BLOCKED_V6 = [
     ["fe80::", 10], // link-local
     ["ff00::", 8], // multicast
     ["64:ff9b:1::", 48], // local-use NAT64 (RFC 8215)
+    ["2001::", 32], // Teredo (RFC 4380): embeds a server and an obfuscated client IPv4
 ];
 /** The v4 prefix `addr/len` written as a prefix under an IPv6 embedding of 96 leading bits. */
 function embedV4(v4, len, prefix6) {
@@ -81,18 +105,58 @@ function embedV4(v4, len, prefix6) {
     const lo = ((c << 8) | d).toString(16);
     return [`${prefix6}${hi}:${lo}`, 96 + len];
 }
+/** 6to4 (RFC 3056): the v4 prefix `addr/len` sits in bits 16-47, under 2002::/16. */
+function embedSixToFour(v4, len) {
+    const [a, b, c, d] = v4.split(".").map(Number);
+    const hi = ((a << 8) | b).toString(16);
+    const lo = ((c << 8) | d).toString(16);
+    return [`2002:${hi}:${lo}::`, 16 + len];
+}
 const blockList = new BlockList();
 for (const [addr, len] of BLOCKED_V4) {
     blockList.addSubnet(addr, len, "ipv4");
-    // IPv4-mapped (::ffff:a.b.c.d, any textual form) and NAT64 (64:ff9b::a.b.c.d): the embedded
-    // v4 address is held to the same list.
-    for (const prefix6 of ["::ffff:", "64:ff9b::"]) {
+    // IPv4-mapped (::ffff:a.b.c.d, any textual form), NAT64 (64:ff9b::a.b.c.d) and
+    // IPv4-translated (::ffff:0:a.b.c.d, RFC 2765): the embedded v4 address is held to the same
+    // list, in the last 32 bits of a /96.
+    for (const prefix6 of ["::ffff:", "64:ff9b::", "::ffff:0:"]) {
         const [sub, bits] = embedV4(addr, len, prefix6);
         blockList.addSubnet(sub, bits, "ipv6");
     }
+    // 6to4 (2002::/16): the v4 address is in bits 16-47.
+    const [sixToFour, sixToFourBits] = embedSixToFour(addr, len);
+    blockList.addSubnet(sixToFour, sixToFourBits, "ipv6");
 }
 for (const [addr, len] of BLOCKED_V6)
     blockList.addSubnet(addr, len, "ipv6");
+/**
+ * The eight 16-bit groups of a SYNTACTICALLY VALID IPv6 literal (`isIP` has already accepted
+ * it). Only used to read bits that no BlockList prefix can express.
+ */
+function ipv6Groups(ip) {
+    let text = ip.toLowerCase();
+    const dotted = /(\d+)\.(\d+)\.(\d+)\.(\d+)$/.exec(text);
+    if (dotted) {
+        const [, a, b, c, d] = dotted.map(Number);
+        text = `${text.slice(0, dotted.index)}${((a << 8) | b).toString(16)}:${((c << 8) | d).toString(16)}`;
+    }
+    const [head = "", tail] = text.split("::");
+    const left = head ? head.split(":") : [];
+    const right = tail === undefined ? [] : tail ? tail.split(":") : [];
+    const fill = tail === undefined ? [] : Array(8 - left.length - right.length).fill("0");
+    return [...left, ...fill, ...right].map((g) => Number.parseInt(g, 16));
+}
+/**
+ * ISATAP (RFC 5214): bits 64-95 are 0000:5efe (or 0200:5efe, universal/local variant) under ANY
+ * prefix, and the low 32 bits are an embedded IPv4. No prefix expresses that, so it is read
+ * from the groups; the embedded v4 is held to the same blocked list.
+ */
+function isatapEmbeddedV4(ip) {
+    const g = ipv6Groups(ip);
+    if (g.length !== 8 || (g[4] !== 0x0000 && g[4] !== 0x0200) || g[5] !== 0x5efe)
+        return null;
+    const [hi, lo] = [g[6], g[7]];
+    return `${hi >> 8}.${hi & 255}.${lo >> 8}.${lo & 255}`;
+}
 /** True only for a globally routable address. Fail-closed: anything unrecognised is refused. */
 export function isPublicAddress(ip) {
     if (typeof ip !== "string" || ip.includes("%"))
@@ -101,6 +165,11 @@ export function isPublicAddress(ip) {
     if (version !== 4 && version !== 6)
         return false;
     try {
+        if (version === 6) {
+            const isatap = isatapEmbeddedV4(ip);
+            if (isatap !== null && blockList.check(isatap, "ipv4"))
+                return false;
+        }
         return !blockList.check(ip, version === 4 ? "ipv4" : "ipv6");
     }
     catch {
@@ -139,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
@@ -148,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);
@@ -165,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/codeStore.d.ts

@@ -8,4 +8,22 @@
  */
 import type { AuthorizationCodeRecord, AuthorizationCodeStore, ConsumeCodeResult } from "@vantageos/cloud-identity";
 export type { AuthorizationCodeRecord, AuthorizationCodeStore, ConsumeCodeResult };
-export declare function createInMemoryCodeStore(): AuthorizationCodeStore;
+export interface InMemoryCodeStoreOptions {
+    now?: () => number;
+    /** Cap on live codes; past it the OLDEST live code is dropped. Default 10 000. */
+    maxEntries?: number;
+}
+export type InMemoryCodeStore = AuthorizationCodeStore & {
+    /** Sizes of the two internal sets, for tests and metrics. */
+    stats(): {
+        live: number;
+        used: number;
+    };
+};
+/**
+ * Bounded in-memory adapter. A code that was never redeemed is dropped once past its
+ * `expiresAt`; a redeemed code's "used" marker is kept only until that same instant, after
+ * which cloud-identity refuses the code as expired anyway. Both sweeps run on `put`, so memory
+ * stays proportional to the codes issued within one code lifetime (60 s by default).
+ */
+export declare function createInMemoryCodeStore(options?: InMemoryCodeStoreOptions): InMemoryCodeStore;

package/dist/oauth/codeStore.js

@@ -6,11 +6,35 @@
  * The in-memory adapter is NOT for a multi-instance deployment: codes live in one process,
  * so a second instance cannot redeem a code issued by the first.
  */
-export function createInMemoryCodeStore() {
+/**
+ * Bounded in-memory adapter. A code that was never redeemed is dropped once past its
+ * `expiresAt`; a redeemed code's "used" marker is kept only until that same instant, after
+ * which cloud-identity refuses the code as expired anyway. Both sweeps run on `put`, so memory
+ * stays proportional to the codes issued within one code lifetime (60 s by default).
+ */
+export function createInMemoryCodeStore(options = {}) {
+    const now = options.now ?? (() => Date.now());
+    const maxEntries = options.maxEntries ?? 10_000;
     const live = new Map();
-    const used = new Set();
+    const used = new Map(); // codeHash -> expiresAt of the redeemed code
+    const sweep = () => {
+        const t = now();
+        for (const [hash, record] of live)
+            if (record.expiresAt <= t)
+                live.delete(hash);
+        for (const [hash, expiresAt] of used)
+            if (expiresAt <= t)
+                used.delete(hash);
+    };
     return {
         async put(record) {
+            sweep();
+            while (live.size >= maxEntries) {
+                const oldest = live.keys().next();
+                if (oldest.done)
+                    break;
+                live.delete(oldest.value);
+            }
             live.set(record.codeHash, record);
         },
         // Atomic by construction: this body has no await between the read and the delete, and
@@ -19,10 +43,11 @@ export function createInMemoryCodeStore() {
             const record = live.get(codeHash);
             if (record) {
                 live.delete(codeHash);
-                used.add(codeHash);
+                used.set(codeHash, record.expiresAt);
                 return { status: "ok", record };
             }
             return used.has(codeHash) ? { status: "already-used" } : { status: "unknown" };
         },
+        stats: () => ({ live: live.size, used: used.size }),
     };
 }

package/dist/oauth/picker.d.ts

@@ -8,4 +8,9 @@ import type { OrgPickerModel } from "@vantageos/cloud-identity";
 import { type McpLocale } from "../i18n.js";
 /** CSP for the picker page: no scripts, no external assets, one hashed inline style. */
 export declare function pickerContentSecurityPolicy(): Promise<string>;
-export declare function renderOrgPicker(model: OrgPickerModel, locale: McpLocale): string;
+/** What the consent page must tell the person beyond the model: whether the client is trusted. */
+export interface ConsentContext {
+    /** True for a Dynamic Client Registration client: it vouched for itself, nobody else did. */
+    unverified: boolean;
+}
+export declare function renderOrgPicker(model: OrgPickerModel, locale: McpLocale, consent: ConsentContext): string;

package/dist/oauth/picker.js

@@ -27,7 +27,11 @@ export async function pickerContentSecurityPolicy() {
         "frame-ancestors 'none'",
     ].join("; ");
 }
-export function renderOrgPicker(model, locale) {
+export function renderOrgPicker(model, locale, consent) {
+    const destination = escapeHtml(model.redirectOrigin);
+    const unverified = consent.unverified
+        ? `<p role="alert"><strong>${escapeHtml(t(locale, "oauth.pickerUnverified"))}</strong></p>\n`
+        : "";
     const clientName = model.client.clientName ?? model.client.clientId;
     const only = model.organizations.length === 1;
     const orgs = model.organizations
@@ -48,7 +52,9 @@ export function renderOrgPicker(model, locale) {
 <main>
 <h1>${title}</h1>
 <p>${intro}</p>
-<form method="post" action="/authorize/org">
+<p>${escapeHtml(t(locale, "oauth.pickerDestination"))} <strong>${destination}</strong><br>
+${escapeHtml(t(locale, "oauth.pickerScope"))} <code>${escapeHtml(model.scope)}</code></p>
+${unverified}<form method="post" action="/authorize/org">
 <input type="hidden" name="state" value="${escapeHtml(model.state)}">
 <input type="hidden" name="consentToken" value="${escapeHtml(model.consentToken ?? "")}">
 <fieldset>

package/dist/oauth/settings.d.ts

@@ -14,8 +14,15 @@ export declare const OAUTH_ENV: {
     readonly clerkSecretKey: "CLERK_SECRET_KEY";
     readonly extraAuthorizedParties: "AUTHORIZE_AUTHORIZED_PARTIES";
     readonly signingJwk: "MCP_OAUTH_SIGNING_JWK";
+    /** Number of trusted reverse proxies in front of this server (default 0). */
+    readonly trustedProxyCount: "MCP_TRUSTED_PROXY_COUNT";
+    /** Comma-separated browser origins allowed to call /register cross-origin (default: none). */
+    readonly registerCorsOrigins: "MCP_REGISTER_CORS_ORIGINS";
+    /** Exactly "1" lets NODE_ENV=production run on the in-memory stores (single instance only). */
+    readonly allowInMemoryStores: "MCP_ALLOW_IN_MEMORY_STORES";
 };
 /** Scope granted when a client names none: MCP access plus the OIDC subject. */
+export declare const MCP_SCOPE = "mcp:full";
 export declare const DEFAULT_SCOPE = "mcp:full openid";
 export declare const SUPPORTED_SCOPES: readonly ["mcp:full", "openid", "email"];
 export interface AuthorizeSettings {
@@ -46,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

@@ -14,13 +14,31 @@ export const OAUTH_ENV = {
     clerkSecretKey: "CLERK_SECRET_KEY",
     extraAuthorizedParties: "AUTHORIZE_AUTHORIZED_PARTIES",
     signingJwk: "MCP_OAUTH_SIGNING_JWK",
+    /** Number of trusted reverse proxies in front of this server (default 0). */
+    trustedProxyCount: "MCP_TRUSTED_PROXY_COUNT",
+    /** Comma-separated browser origins allowed to call /register cross-origin (default: none). */
+    registerCorsOrigins: "MCP_REGISTER_CORS_ORIGINS",
+    /** Exactly "1" lets NODE_ENV=production run on the in-memory stores (single instance only). */
+    allowInMemoryStores: "MCP_ALLOW_IN_MEMORY_STORES",
 };
 /** Scope granted when a client names none: MCP access plus the OIDC subject. */
-export const DEFAULT_SCOPE = "mcp:full openid";
-export const SUPPORTED_SCOPES = ["mcp:full", "openid", "email"];
+export const MCP_SCOPE = "mcp:full";
+export const DEFAULT_SCOPE = `${MCP_SCOPE} openid`;
+export const SUPPORTED_SCOPES = [MCP_SCOPE, "openid", "email"];
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+/**
+ * The origin of a configured URL, or null when it is unusable: unparsable, not https, or http
+ * on a host that is not loopback. A cleartext issuer, sign-in or callback URL would put the
+ * session token, the authorization code or the signing-key set on the wire in the clear.
+ */
 function originOf(url) {
     try {
-        return new URL(url).origin;
+        const parsed = new URL(url);
+        if (parsed.protocol === "https:")
+            return parsed.origin;
+        if (parsed.protocol === "http:" && LOOPBACK_HOSTS.has(parsed.hostname))
+            return parsed.origin;
+        return null;
     }
     catch {
         return null;
@@ -98,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/dist/ui/uiResource.d.ts

@@ -3,7 +3,7 @@ import type { ExampleItem } from "../exampleItems.js";
 export declare const ITEMS_UI_RESOURCE_URI = "ui://mcp-boilerplate/items-widget.html";
 /**
  * Reads the single-file bundle produced by `npm run build:ui`
- * (vite-plugin-singlefile). Never silently swallowed: a missing bundle is a build defect, not
+ * (in-repo inlining plugin). Never silently swallowed: a missing bundle is a build defect, not
  * a runtime fallback case. The error that reaches the MCP client names no filesystem path;
  * the detail goes to stderr (server side) only.
  */

package/dist/ui/uiResource.js

@@ -33,7 +33,7 @@ function renderMarkdownFallback(items, locale) {
 }
 /**
  * Reads the single-file bundle produced by `npm run build:ui`
- * (vite-plugin-singlefile). Never silently swallowed: a missing bundle is a build defect, not
+ * (in-repo inlining plugin). Never silently swallowed: a missing bundle is a build defect, not
  * a runtime fallback case. The error that reaches the MCP client names no filesystem path;
  * the detail goes to stderr (server side) only.
  */