@vantageos/mcp-boilerplate 0.1.1 → 0.2.0

package/dist/oauth/authorizationServer.js

@@ -0,0 +1,423 @@
+/**
+ * Own OAuth 2.1 authorization server (ruling R1). A code is issued ONLY to a signed-in Clerk
+ * person who picked one of their own organisations and approved the request on the picker
+ * page (consent ON). Routes:
+ *
+ *   GET  /.well-known/oauth-authorization-server  (+ /.well-known/openid-configuration)
+ *   GET  /.well-known/jwks.json                   public signing keys
+ *   POST /register                                Dynamic Client Registration (public clients)
+ *   GET  /authorize                               start; CIMD or DCR client_id
+ *   GET  /authorize/callback                      return from Clerk sign-in
+ *   POST /authorize/org                           person + organisation picker submit
+ *   POST /token                                   authorization_code + PKCE S256
+ *   GET  /userinfo
+ *
+ * EVERY decision lives in @vantageos/cloud-identity (startAuthorize, resumeAuthorize,
+ * exchangeAuthorizationCode, buildDiscoveryDocument, buildUserInfo, oauthErrorFor). This
+ * module owns only what the package takes as parameters: environment, stores, the client
+ * lookup, the Clerk calls, the picker page, and the RS256 signature of the access token.
+ *
+ * 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 { getCookie } from "hono/cookie";
+import { cors } from "hono/cors";
+import { detectLocaleFromAcceptLanguage, t } from "../i18n.js";
+import { createClerkBackendCollaborators } from "./clerk.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 { ACCESS_TOKEN_TTL_SECONDS, createTokenIssuer } from "./tokenIssuer.js";
+const REGISTER_LIMIT_PER_MINUTE = 20;
+const MAX_REDIRECT_URIS = 10;
+function noStore(c) {
+    c.header("Cache-Control", "no-store");
+    c.header("Pragma", "no-cache");
+}
+function sessionTokenFrom(c) {
+    const header = c.req.header("authorization");
+    if (header?.toLowerCase().startsWith("bearer ")) {
+        const token = header.slice("bearer ".length).trim();
+        if (token)
+            return token;
+    }
+    return getCookie(c, "__session") || undefined;
+}
+export function createAuthorizationServer(deps = {}) {
+    const env = deps.env ?? process.env;
+    const now = deps.now ?? (() => Date.now());
+    const codeStore = deps.codeStore ?? createInMemoryCodeStore();
+    const registry = deps.clientRegistry ?? createInMemoryClientRegistry();
+    const injectedClerk = deps.clerk;
+    const clerkInjected = Boolean(injectedClerk?.listMemberships && injectedClerk?.getUser);
+    let cachedIssuer = null;
+    const issuerFor = (settings) => {
+        const jwk = JSON.stringify(settings.signingJwk);
+        if (!cachedIssuer || cachedIssuer.jwk !== jwk) {
+            cachedIssuer = { jwk, issuer: createTokenIssuer(settings.signingJwk) };
+        }
+        return cachedIssuer.issuer;
+    };
+    // One backend instance for the process lifetime, so its JWKS cache actually caches.
+    const backendClerk = createClerkBackendCollaborators(env[OAUTH_ENV.clerkSecretKey] ?? "");
+    const clerkFor = () => ({
+        jwks: injectedClerk?.jwks ?? backendClerk.jwks,
+        listMemberships: injectedClerk?.listMemberships ?? backendClerk.listMemberships,
+        getUser: injectedClerk?.getUser ?? backendClerk.getUser,
+    });
+    const settingsNow = () => readAuthorizeSettings(env, clerkInjected);
+    const lookupClient = async (clientId) => {
+        if (isUrlShapedClientId(clientId)) {
+            return resolveCimdClient(clientId, {
+                fetchImpl: deps.fetchImpl,
+                resolveHost: deps.resolveHost,
+            });
+        }
+        const row = await registry.get(clientId);
+        if (!row)
+            return null;
+        return {
+            clientId: row.clientId,
+            redirectUris: row.redirectUris,
+            ...(row.clientName !== undefined ? { clientName: row.clientName } : {}),
+            revoked: row.revoked === true,
+        };
+    };
+    const runtimeFor = (settings) => {
+        const clerk = clerkFor();
+        const cfg = {
+            stateSecret: settings.stateSecret,
+            signInUrl: settings.signInUrl,
+            callbackUrl: settings.callbackUrl,
+            // The protected-resource metadata publishes `resource: <base>/mcp`, the URL a client
+            // configures and sends back (RFC 8707). Only that value is accepted.
+            allowedResources: [settings.resource],
+            supportedScopes: SUPPORTED_SCOPES,
+            defaultScope: DEFAULT_SCOPE,
+            session: {
+                issuer: settings.clerkIssuer,
+                jwks: () => clerk.jwks(settings.clerkIssuer),
+                authorizedParties: settings.authorizedParties,
+            },
+        };
+        const authDeps = {
+            lookupClient,
+            listMemberships: (userId) => clerk.listMemberships(userId),
+            codeStore,
+            now,
+        };
+        return { cfg, authDeps, clerk };
+    };
+    const unavailable = (c, missing) => {
+        // Names only, never values.
+        console.error(`[oauth] refused: missing configuration ${missing.join(", ")}`);
+        noStore(c);
+        return c.json({
+            error: "temporarily_unavailable",
+            error_description: t("en", "oauth.unavailable"),
+        }, 503);
+    };
+    const respond = async (c, outcome, settings) => {
+        noStore(c);
+        c.header("Referrer-Policy", "no-referrer");
+        switch (outcome.kind) {
+            case "redirect-to-sign-in":
+                return c.redirect(outcome.url, 302);
+            case "redirect-to-client": {
+                // RFC 9207 section 2: identify the issuer in the authorization response.
+                const back = new URL(outcome.url);
+                back.searchParams.set("iss", settings.baseUrl);
+                return c.redirect(back.toString(), 302);
+            }
+            case "org-picker": {
+                c.header("Content-Security-Policy", await pickerContentSecurityPolicy());
+                const locale = detectLocaleFromAcceptLanguage(c.req.header("accept-language"));
+                return c.html(renderOrgPicker(outcome.model, locale));
+            }
+            case "refused": {
+                const mapped = oauthErrorFor(outcome.refusal);
+                return c.json({ error: mapped.error, error_description: outcome.refusal.reason }, mapped.status);
+            }
+        }
+    };
+    const registerHits = new Map();
+    const registerAllowed = (key) => {
+        const t0 = now();
+        const hit = registerHits.get(key);
+        if (!hit || t0 - hit.windowStart >= 60_000) {
+            registerHits.set(key, { windowStart: t0, count: 1 });
+            if (registerHits.size > 5000)
+                registerHits.clear();
+            return true;
+        }
+        hit.count += 1;
+        return hit.count <= REGISTER_LIMIT_PER_MINUTE;
+    };
+    return {
+        async resourceServer() {
+            const result = await settingsNow();
+            if (!result.ok)
+                return result;
+            const s = result.settings;
+            const issuer = await issuerFor(s);
+            return {
+                ok: true,
+                auth: {
+                    realm: "mcp",
+                    resourceMetadataUrl: `${s.baseUrl}/.well-known/oauth-protected-resource/mcp`,
+                    resource: s.resource,
+                    // The issuer publishes RSA public members only (kty "RSA", RS256, kid), the verifier shape.
+                    jwks: issuer.jwks,
+                    issuer: s.baseUrl,
+                    audience: s.resource,
+                    authorizationServers: [s.baseUrl],
+                },
+            };
+        },
+        mount(app) {
+            app.use("/.well-known/*", cors());
+            app.use("/register", cors());
+            app.use("/token", cors());
+            const metadata = async (c) => {
+                const result = await settingsNow();
+                if (!result.ok)
+                    return unavailable(c, result.missing);
+                const s = result.settings;
+                const doc = buildDiscoveryDocument({
+                    issuer: s.baseUrl,
+                    authorizationEndpoint: `${s.baseUrl}/authorize`,
+                    tokenEndpoint: `${s.baseUrl}/token`,
+                    jwksUri: `${s.baseUrl}/.well-known/jwks.json`,
+                    userinfoEndpoint: `${s.baseUrl}/userinfo`,
+                    registrationEndpoint: `${s.baseUrl}/register`,
+                    scopesSupported: SUPPORTED_SCOPES,
+                });
+                if (!doc.ok) {
+                    const mapped = oauthErrorFor(doc.refusal);
+                    return c.json({ error: mapped.error, error_description: doc.refusal.reason }, mapped.status);
+                }
+                return c.json({
+                    ...doc.document,
+                    token_endpoint_auth_methods_supported: ["none"],
+                    // 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).
+                    client_id_metadata_document_supported: true,
+                });
+            };
+            app.get("/.well-known/oauth-authorization-server", metadata);
+            app.get("/.well-known/openid-configuration", metadata);
+            app.get("/.well-known/jwks.json", async (c) => {
+                const result = await settingsNow();
+                if (!result.ok)
+                    return unavailable(c, result.missing);
+                return c.json((await issuerFor(result.settings)).jwks);
+            });
+            app.post("/register", async (c) => {
+                const key = (c.req.header("x-forwarded-for") ?? "").split(",")[0]?.trim() || "unknown";
+                if (!registerAllowed(key)) {
+                    c.header("Retry-After", "60");
+                    return c.json({ error: "too_many_requests" }, 429);
+                }
+                let body = {};
+                try {
+                    const parsed = await c.req.json();
+                    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                        body = parsed;
+                    }
+                }
+                catch {
+                    // an unreadable body falls through to the redirect_uris refusal below
+                }
+                const uris = body.redirect_uris;
+                if (!Array.isArray(uris) ||
+                    uris.length === 0 ||
+                    uris.length > MAX_REDIRECT_URIS ||
+                    !uris.every(isAllowedRedirectUri)) {
+                    return c.json({
+                        error: "invalid_redirect_uri",
+                        error_description: "redirect_uris is required: a non-empty array of https URIs (http only on loopback), no fragment",
+                    }, 400);
+                }
+                // Public clients only: PKCE protects the code, and the server issues no client secret.
+                const method = body.token_endpoint_auth_method;
+                if (method !== undefined && method !== "none") {
+                    return c.json({
+                        error: "invalid_client_metadata",
+                        error_description: 'only token_endpoint_auth_method "none" (public client + PKCE) is supported',
+                    }, 400);
+                }
+                const clientName = typeof body.client_name === "string" ? body.client_name.slice(0, 200) : "anonymous-dcr";
+                const clientId = crypto.randomUUID();
+                const issuedAt = Math.floor(now() / 1000);
+                try {
+                    await registry.register({
+                        clientId,
+                        clientName,
+                        redirectUris: uris,
+                        issuedAt,
+                    });
+                }
+                catch (err) {
+                    console.error("[oauth] /register failed:", err instanceof Error ? err.message : err);
+                    return c.json({ error: "server_error", error_description: "failed to persist client" }, 500);
+                }
+                noStore(c);
+                return c.json({
+                    client_id: clientId,
+                    client_id_issued_at: issuedAt,
+                    redirect_uris: uris,
+                    client_name: clientName,
+                    token_endpoint_auth_method: "none",
+                    grant_types: ["authorization_code"],
+                    response_types: ["code"],
+                    scope: DEFAULT_SCOPE,
+                }, 201);
+            });
+            app.get("/authorize", async (c) => {
+                const result = await settingsNow();
+                if (!result.ok)
+                    return unavailable(c, result.missing);
+                const { cfg, authDeps } = runtimeFor(result.settings);
+                const outcome = await startAuthorize(c.req.query(), sessionTokenFrom(c), cfg, authDeps);
+                return respond(c, outcome, result.settings);
+            });
+            // The return from Clerk sign-in. The request is rebuilt only from the signed
+            // `authorize_state`; no other query parameter is read.
+            app.get("/authorize/callback", async (c) => {
+                const result = await settingsNow();
+                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);
+                return respond(c, outcome, result.settings);
+            });
+            // The picker's form post. `consentToken` is the CSRF protection: a cross-site form
+            // cannot know it, and resumeAuthorize refuses `approved` without it.
+            app.post("/authorize/org", async (c) => {
+                const result = await settingsNow();
+                if (!result.ok)
+                    return unavailable(c, result.missing);
+                let form;
+                try {
+                    form = await c.req.parseBody();
+                }
+                catch {
+                    return c.json({ error: "invalid_request", error_description: "unreadable form" }, 400);
+                }
+                const field = (name) => typeof form[name] === "string" ? form[name] : undefined;
+                if (field("approved") === "false") {
+                    noStore(c);
+                    const locale = detectLocaleFromAcceptLanguage(c.req.header("accept-language"));
+                    return c.json({ error: "access_denied", error_description: t(locale, "oauth.denied") }, 403);
+                }
+                const { cfg, authDeps } = runtimeFor(result.settings);
+                const outcome = await resumeAuthorize({
+                    state: field("state") ?? "",
+                    sessionToken: sessionTokenFrom(c),
+                    orgId: field("orgId"),
+                    approved: field("approved") === "true",
+                    consentToken: field("consentToken"),
+                }, cfg, authDeps);
+                return respond(c, outcome, result.settings);
+            });
+            app.post("/token", async (c) => {
+                const result = await settingsNow();
+                if (!result.ok)
+                    return unavailable(c, result.missing);
+                const settings = result.settings;
+                noStore(c);
+                let body = {};
+                const contentType = c.req.header("Content-Type") ?? "";
+                try {
+                    if (contentType.includes("application/x-www-form-urlencoded")) {
+                        body = Object.fromEntries(new URLSearchParams(await c.req.text()));
+                    }
+                    else {
+                        body = (await c.req.json());
+                    }
+                }
+                catch {
+                    return c.json({ error: "invalid_request", error_description: "unreadable body" }, 400);
+                }
+                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;
+                if (!code || !codeVerifier || !redirectUri || !clientId) {
+                    return c.json({
+                        error: "invalid_request",
+                        error_description: "missing code, code_verifier, redirect_uri or client_id",
+                    }, 400);
+                }
+                // Public clients only: a presented secret means the client expects authentication this
+                // server does not offer.
+                if (body.client_secret ||
+                    c.req.header("authorization")?.toLowerCase().startsWith("basic ")) {
+                    c.header("WWW-Authenticate", 'Basic realm="oauth"');
+                    return c.json({ error: "invalid_client", error_description: "public clients only" }, 401);
+                }
+                const client = await lookupClient(clientId);
+                if (!client || client.revoked)
+                    return c.json({ error: "invalid_client" }, 400);
+                const exchanged = await exchangeAuthorizationCode({
+                    code,
+                    codeVerifier,
+                    redirectUri,
+                    clientId,
+                    ...(body.resource ? { resource: body.resource } : {}),
+                }, { codeStore, now });
+                if (!exchanged.ok) {
+                    const mapped = oauthErrorFor(exchanged.refusal);
+                    return c.json({ error: mapped.error, error_description: exchanged.refusal.reason }, mapped.status);
+                }
+                const issuer = await issuerFor(settings);
+                const accessToken = await issuer.sign(exchanged.claims, settings.baseUrl, now());
+                return c.json({
+                    access_token: accessToken,
+                    token_type: "Bearer",
+                    expires_in: ACCESS_TOKEN_TTL_SECONDS,
+                    scope: exchanged.claims.scope,
+                });
+            });
+            app.get("/userinfo", async (c) => {
+                const result = await settingsNow();
+                if (!result.ok)
+                    return unavailable(c, result.missing);
+                const header = c.req.header("authorization") ?? "";
+                const token = header.toLowerCase().startsWith("bearer ") ? header.slice(7).trim() : "";
+                const invalid = () => {
+                    c.header("WWW-Authenticate", 'Bearer error="invalid_token"');
+                    return c.json({ error: "invalid_token" }, 401);
+                };
+                if (!token)
+                    return invalid();
+                const issuer = await issuerFor(result.settings);
+                let claims;
+                try {
+                    claims = await issuer.verify(token, result.settings.baseUrl, result.settings.resource);
+                }
+                catch {
+                    return invalid();
+                }
+                let user;
+                try {
+                    user = await clerkFor().getUser(claims.sub);
+                }
+                catch (err) {
+                    console.error("[oauth] /userinfo Clerk user lookup failed:", err instanceof Error ? err.message : err);
+                    return c.json({ error: "temporarily_unavailable" }, 503);
+                }
+                const info = buildUserInfo({ sub: claims.sub, scope: claims.scope }, user);
+                if (!info.ok) {
+                    const mapped = oauthErrorFor(info.refusal);
+                    return c.json({ error: mapped.error, error_description: info.refusal.reason }, mapped.status);
+                }
+                noStore(c);
+                return c.json(info.userinfo);
+            });
+        },
+    };
+}

package/dist/oauth/clerk.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Clerk collaborators the authorization server takes as parameters: the Clerk JWKS (to verify
+ * the person's session token), the person's organisation memberships and the user record.
+ * The decisions on what they return live in @vantageos/cloud-identity.
+ *
+ * The defaults call Clerk's Backend REST API with `CLERK_SECRET_KEY`; a deployment (or a test)
+ * injects its own implementation through `AuthorizationServerDeps.clerk`.
+ */
+import type { ClerkJwks, ClerkOrgMembership, ClerkUserLike } from "@vantageos/cloud-identity";
+export interface ClerkCollaborators {
+    jwks(issuer: string): Promise<ClerkJwks>;
+    listMemberships(userId: string): Promise<readonly ClerkOrgMembership[]>;
+    getUser(userId: string): Promise<ClerkUserLike>;
+}
+export declare function createClerkBackendCollaborators(secretKey: string, fetchImpl?: typeof fetch): ClerkCollaborators;

package/dist/oauth/clerk.js

@@ -0,0 +1,59 @@
+/**
+ * Clerk collaborators the authorization server takes as parameters: the Clerk JWKS (to verify
+ * the person's session token), the person's organisation memberships and the user record.
+ * The decisions on what they return live in @vantageos/cloud-identity.
+ *
+ * The defaults call Clerk's Backend REST API with `CLERK_SECRET_KEY`; a deployment (or a test)
+ * injects its own implementation through `AuthorizationServerDeps.clerk`.
+ */
+const CLERK_API = "https://api.clerk.com/v1";
+const JWKS_CACHE_MS = 10 * 60 * 1000;
+const MEMBERSHIP_PAGE_LIMIT = 100;
+export function createClerkBackendCollaborators(secretKey, fetchImpl = fetch) {
+    let cachedJwks = null;
+    const api = async (path) => {
+        const res = await fetchImpl(`${CLERK_API}${path}`, {
+            headers: { Authorization: `Bearer ${secretKey}`, Accept: "application/json" },
+        });
+        if (!res.ok)
+            throw new Error(`Clerk Backend API answered ${res.status}`);
+        return (await res.json());
+    };
+    return {
+        async jwks(issuer) {
+            const now = Date.now();
+            if (cachedJwks && cachedJwks.issuer === issuer && now - cachedJwks.at < JWKS_CACHE_MS) {
+                return cachedJwks.keys;
+            }
+            const res = await fetchImpl(`${issuer}/.well-known/jwks.json`);
+            if (!res.ok)
+                throw new Error(`Clerk JWKS answered ${res.status}`);
+            const keys = (await res.json());
+            cachedJwks = { at: now, issuer, keys };
+            return keys;
+        },
+        async listMemberships(userId) {
+            const page = await api(`/users/${encodeURIComponent(userId)}/organization_memberships?limit=${MEMBERSHIP_PAGE_LIMIT}`);
+            return page.data.map((m) => ({
+                role: m.role,
+                organization: {
+                    id: m.organization.id,
+                    slug: m.organization.slug ?? null,
+                    name: m.organization.name,
+                },
+            }));
+        },
+        async getUser(userId) {
+            const user = await api(`/users/${encodeURIComponent(userId)}`);
+            return {
+                id: user.id,
+                primaryEmailAddressId: user.primary_email_address_id ?? null,
+                emailAddresses: (user.email_addresses ?? []).map((e) => ({
+                    id: e.id,
+                    emailAddress: e.email_address,
+                    verification: e.verification ?? null,
+                })),
+            };
+        },
+    };
+}

package/dist/oauth/clientRegistry.d.ts

@@ -0,0 +1,50 @@
+/**
+ * OAuth client registry: how `/authorize` and `/token` learn who a `client_id` is.
+ *
+ * Two sources, tried by the SHAPE of the client_id:
+ *  - a URL-shaped client_id is a Client ID Metadata Document (CIMD): fetched over https,
+ *    SSRF-guarded (public addresses only, no redirects, size and time capped), and accepted
+ *    only when the document names exactly that URL;
+ *  - anything else is a Dynamic Client Registration (DCR) id looked up in the registry.
+ *
+ * Only PUBLIC clients (PKCE, no client secret) exist here: MCP clients are public clients,
+ * so the server issues and stores no client secret at all.
+ */
+import type { AuthorizeClient } from "@vantageos/cloud-identity";
+export interface RegisteredClient {
+    clientId: string;
+    clientName?: string;
+    redirectUris: string[];
+    /** Epoch seconds. */
+    issuedAt: number;
+    revoked?: boolean;
+}
+/** Durable-adapter contract: docs/oauth-stores.md. */
+export interface ClientRegistry {
+    get(clientId: string): Promise<RegisteredClient | null>;
+    register(client: RegisteredClient): Promise<void>;
+}
+export declare function createInMemoryClientRegistry(maxClients?: number): 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. */
+export declare function isPublicAddress(ip: string): boolean;
+export declare function defaultResolveHost(host: string): Promise<string[]>;
+export interface CimdOptions {
+    fetchImpl?: typeof fetch;
+    resolveHost?: (host: string) => Promise<string[]>;
+    maxBytes?: number;
+    timeoutMs?: number;
+}
+/** True when a client_id is URL-shaped, i.e. a CIMD identifier (valid or not). */
+export declare function isUrlShapedClientId(clientId: string): boolean;
+/**
+ * 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
+ * unknown client, never a partial one.
+ *
+ * Limitation (documented in docs/oauth-stores.md): the address check resolves the host and
+ * 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 resolveCimdClient(clientId: string, options?: CimdOptions): Promise<AuthorizeClient | null>;