@vantageos/mcp-boilerplate 0.2.1 → 0.2.3

package/dist/oauth/authorizationServer.js

@@ -20,15 +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;
@@ -36,6 +38,39 @@ function noStore(c) {
     c.header("Cache-Control", "no-store");
     c.header("Pragma", "no-cache");
 }
+/**
+ * The rate-limit key of a request: who is really on the other end.
+ *
+ * `X-Forwarded-For` is client-controlled up to the point a trusted proxy appends to it. With
+ * N trusted proxies the real client is the N-th entry from the END (each proxy appended the
+ * peer it saw); anything left of it was supplied by the client and is ignored. With none
+ * configured the header is not read at all and the socket address decides.
+ */
+export function clientKeyOf(c, trustedProxyCount) {
+    const socket = c.env?.remoteAddress || "unknown";
+    if (trustedProxyCount <= 0)
+        return socket;
+    const chain = (c.req.header("x-forwarded-for") ?? "")
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    return chain.length >= 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 ")) {
@@ -47,7 +82,25 @@ function sessionTokenFrom(c) {
 }
 export function createAuthorizationServer(deps = {}) {
     const env = deps.env ?? process.env;
+    // Operator knobs are validated here, at construction: a bad value stops the boot.
+    const trustedProxyCount = integerKnob(env, OAUTH_ENV.trustedProxyCount, 0, 10) ?? 0;
+    const registerOrigins = originListKnob(env, OAUTH_ENV.registerCorsOrigins);
+    const allowInMemory = flagKnob(env, OAUTH_ENV.allowInMemoryStores) === true;
     const now = deps.now ?? (() => Date.now());
+    // Fail at boot, loudly, rather than lose every code and client on the first restart.
+    if (!deps.codeStore || !deps.clientRegistry) {
+        if (env.NODE_ENV === "production") {
+            if (!allowInMemory) {
+                throw new Error(`NODE_ENV=production refuses the in-memory OAuth stores (codes and registered clients are lost on restart and not shared between instances). Inject durable adapters (docs/oauth-stores.md), or set ${OAUTH_ENV.allowInMemoryStores}=1 to accept a single-instance deployment that forgets them on restart.`);
+            }
+            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;
@@ -68,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, {
@@ -134,7 +192,10 @@ export function createAuthorizationServer(deps = {}) {
             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));
+                return c.html(renderOrgPicker(outcome.model, locale, {
+                    // Only a URL-shaped (CIMD) client_id is bound to a domain its owner controls.
+                    unverified: !isUrlShapedClientId(outcome.model.client.clientId),
+                }));
             }
             case "refused": {
                 const mapped = oauthErrorFor(outcome.refusal);
@@ -178,7 +239,9 @@ export function createAuthorizationServer(deps = {}) {
         },
         mount(app) {
             app.use("/.well-known/*", cors());
-            app.use("/register", cors());
+            // /register is for native and server-side clients, which send no Origin. A browser origin
+            // may call it only when the operator lists it.
+            app.use("/register", cors({ origin: (origin) => (registerOrigins.includes(origin) ? origin : null) }));
             app.use("/token", cors());
             const metadata = async (c) => {
                 const result = await settingsNow();
@@ -200,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).
@@ -216,7 +280,7 @@ export function createAuthorizationServer(deps = {}) {
                 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";
+                const key = clientKeyOf(c, trustedProxyCount);
                 if (!registerAllowed(key)) {
                     c.header("Retry-After", "60");
                     return c.json({ error: "too_many_requests" }, 429);
@@ -291,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
@@ -308,12 +403,20 @@ export function createAuthorizationServer(deps = {}) {
                     return c.json({ error: "invalid_request", error_description: "unreadable form" }, 400);
                 }
                 const field = (name) => typeof form[name] === "string" ? form[name] : undefined;
+                const { cfg, authDeps } = runtimeFor(result.settings);
+                // A denial is the package's `denied` outcome: it verifies state, expiry, client and
+                // 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") {
-                    noStore(c);
-                    const locale = detectLocaleFromAcceptLanguage(c.req.header("accept-language"));
-                    return c.json({ error: "access_denied", error_description: t(locale, "oauth.denied") }, 403);
+                    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 { cfg, authDeps } = runtimeFor(result.settings);
                 const outcome = await resumeAuthorize({
                     state: field("state") ?? "",
                     sessionToken: sessionTokenFrom(c),
@@ -345,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/clerk.d.ts

@@ -12,4 +12,8 @@ export interface ClerkCollaborators {
     listMemberships(userId: string): Promise<readonly ClerkOrgMembership[]>;
     getUser(userId: string): Promise<ClerkUserLike>;
 }
-export declare function createClerkBackendCollaborators(secretKey: string, fetchImpl?: typeof fetch): ClerkCollaborators;
+export interface ClerkBackendOptions {
+    /** Per-call time budget (JWKS, memberships, user). Default 5 s. */
+    timeoutMs?: number;
+}
+export declare function createClerkBackendCollaborators(secretKey: string, fetchImpl?: typeof fetch, options?: ClerkBackendOptions): ClerkCollaborators;

package/dist/oauth/clerk.js

@@ -9,11 +9,16 @@
 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) {
+/** 50 pages x 100 = 5 000 memberships: past it the lookup FAILS rather than truncate. */
+const MEMBERSHIP_MAX_PAGES = 50;
+const CLERK_TIMEOUT_MS = 5000;
+export function createClerkBackendCollaborators(secretKey, fetchImpl = fetch, options = {}) {
+    const timeoutMs = options.timeoutMs ?? CLERK_TIMEOUT_MS;
     let cachedJwks = null;
     const api = async (path) => {
         const res = await fetchImpl(`${CLERK_API}${path}`, {
             headers: { Authorization: `Bearer ${secretKey}`, Accept: "application/json" },
+            signal: AbortSignal.timeout(timeoutMs),
         });
         if (!res.ok)
             throw new Error(`Clerk Backend API answered ${res.status}`);
@@ -25,7 +30,9 @@ export function createClerkBackendCollaborators(secretKey, fetchImpl = fetch) {
             if (cachedJwks && cachedJwks.issuer === issuer && now - cachedJwks.at < JWKS_CACHE_MS) {
                 return cachedJwks.keys;
             }
-            const res = await fetchImpl(`${issuer}/.well-known/jwks.json`);
+            const res = await fetchImpl(`${issuer}/.well-known/jwks.json`, {
+                signal: AbortSignal.timeout(timeoutMs),
+            });
             if (!res.ok)
                 throw new Error(`Clerk JWKS answered ${res.status}`);
             const keys = (await res.json());
@@ -33,15 +40,26 @@ export function createClerkBackendCollaborators(secretKey, fetchImpl = fetch) {
             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,
-                },
-            }));
+            const all = [];
+            for (let page = 0; page < MEMBERSHIP_MAX_PAGES; page++) {
+                const offset = page * MEMBERSHIP_PAGE_LIMIT;
+                const body = await api(`/users/${encodeURIComponent(userId)}/organization_memberships?limit=${MEMBERSHIP_PAGE_LIMIT}&offset=${offset}`);
+                all.push(...body.data);
+                const last = body.data.length < MEMBERSHIP_PAGE_LIMIT ||
+                    (typeof body.total_count === "number" && all.length >= body.total_count);
+                if (last) {
+                    return all.map((m) => ({
+                        role: m.role,
+                        organization: {
+                            id: m.organization.id,
+                            slug: m.organization.slug ?? null,
+                            name: m.organization.name,
+                        },
+                    }));
+                }
+            }
+            // A truncated list would hide organisations the person belongs to: refuse instead.
+            throw new Error(`Clerk memberships exceed ${MEMBERSHIP_MAX_PAGES * MEMBERSHIP_PAGE_LIMIT}`);
         },
         async getUser(userId) {
             const user = await api(`/users/${encodeURIComponent(userId)}`);

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

@@ -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. */
@@ -38,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
@@ -47,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>;