@vantageos/mcp-boilerplate 0.2.0 → 0.2.2

package/dist/oauth/clientRegistry.d.ts

@@ -24,7 +24,19 @@ export interface ClientRegistry {
     get(clientId: string): Promise<RegisteredClient | null>;
     register(client: RegisteredClient): Promise<void>;
 }
-export declare function createInMemoryClientRegistry(maxClients?: number): ClientRegistry;
+export interface InMemoryClientRegistryOptions {
+    /** Hard cap on stored clients; at the cap the OLDEST client is evicted. Default 10 000. */
+    maxClients?: number;
+    /** Lifetime of a registration, counted from `issuedAt`. Default 30 days. */
+    ttlSeconds?: number;
+    now?: () => number;
+}
+/**
+ * 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 declare function createInMemoryClientRegistry(options?: InMemoryClientRegistryOptions): ClientRegistry;
 /** True for an https URL, or an http URL on a loopback host (native-app redirects). */
 export declare function isAllowedRedirectUri(raw: unknown): raw is string;
 /** True only for a globally routable address. Fail-closed: anything unrecognised is refused. */

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 {

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 {

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;

package/dist/ui/uiResource.d.ts

@@ -3,9 +3,9 @@ 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). Thrown, never silently swallowed, if the
- * bundle is missing — a missing bundle is a build defect, not a runtime
- * fallback case.
+ * (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.
  */
 export declare function readUiBundle(): string;
 /**

package/dist/ui/uiResource.js

@@ -11,13 +11,18 @@
  * shape written here.
  */
 import { readFileSync } from "node:fs";
-import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";
 export const ITEMS_UI_RESOURCE_URI = "ui://mcp-boilerplate/items-widget.html";
 // dist/ui-bundle/ — NEVER dist/ui/ (that path is tsc's compiled-server
 // output for this very module; see vite.config.ts for the collision this
-// avoids).
-const BUNDLE_PATH = path.join(process.cwd(), "dist", "ui-bundle", "widget.html");
+// avoids). Resolved relative to THIS module, never to the working directory: an installed
+// package runs from any cwd. Compiled (dist/ui/uiResource.js) the bundle is `../ui-bundle`;
+// from source (src/ui/uiResource.ts, under vitest) it is the repository's built `dist/`.
+const BUNDLE_CANDIDATES = [
+    fileURLToPath(new URL("../ui-bundle/widget.html", import.meta.url)),
+    fileURLToPath(new URL("../../dist/ui-bundle/widget.html", import.meta.url)),
+];
 function renderMarkdownFallback(items, locale) {
     const title = locale === "fr" ? "Éléments" : "Items";
     if (items.length === 0) {
@@ -28,12 +33,22 @@ function renderMarkdownFallback(items, locale) {
 }
 /**
  * Reads the single-file bundle produced by `npm run build:ui`
- * (vite-plugin-singlefile). Thrown, never silently swallowed, if the
- * bundle is missing — a missing bundle is a build defect, not a runtime
- * fallback case.
+ * (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.
  */
 export function readUiBundle() {
-    return readFileSync(BUNDLE_PATH, "utf-8");
+    let lastError;
+    for (const candidate of BUNDLE_CANDIDATES) {
+        try {
+            return readFileSync(candidate, "utf-8");
+        }
+        catch (err) {
+            lastError = err;
+        }
+    }
+    console.error(`[ui] UI bundle unreadable (tried ${BUNDLE_CANDIDATES.join(", ")}):`, lastError);
+    throw new Error("UI bundle unavailable on this server");
 }
 /**
  * Resource-level `_meta.ui` (MCP Apps spec 2026-01-26). The CSP is derived from what the