@thotischner/observability-mcp 1.7.1 → 3.0.0

package/dist/auth/middleware.test.js

@@ -0,0 +1,90 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { buildSessionAttacher, buildRequireSession } from "./middleware.js";
+import { issueSession } from "./session.js";
+const secret = "x".repeat(48);
+const sessionCfg = { secret };
+function mkReq(opts = {}) {
+    return {
+        path: opts.path ?? "/api/sources",
+        headers: { cookie: opts.cookieHeader || "" },
+    };
+}
+function mkRes() {
+    let statusCode = 0;
+    let body = null;
+    return {
+        status(c) { statusCode = c; return this; },
+        json(b) { body = b; return this; },
+        get statusCode() { return statusCode; },
+        get body() { return body; },
+    };
+}
+test("session attacher — anonymous passes through unchanged, no session", () => {
+    const attach = buildSessionAttacher({ mode: "anonymous" });
+    const req = mkReq();
+    let called = false;
+    attach(req, mkRes(), () => { called = true; });
+    assert.equal(called, true);
+    assert.equal(req.session, undefined);
+});
+test("session attacher — basic mode without cookie still flows, no session attached", () => {
+    const attach = buildSessionAttacher({ mode: "basic", session: sessionCfg });
+    const req = mkReq();
+    let called = false;
+    attach(req, mkRes(), () => { called = true; });
+    assert.equal(called, true);
+    assert.equal(req.session, undefined);
+});
+test("session attacher — basic mode WITH valid cookie attaches session", () => {
+    const { cookie } = issueSession({ sub: "alice", name: "Alice", roles: ["operator"] }, sessionCfg);
+    const attach = buildSessionAttacher({ mode: "basic", session: sessionCfg });
+    const req = mkReq({ cookieHeader: `omcp_session=${cookie}` });
+    let called = false;
+    attach(req, mkRes(), () => { called = true; });
+    assert.equal(called, true);
+    assert.ok(req.session);
+    assert.equal(req.session?.sub, "alice");
+});
+test("session attacher — tampered cookie leaves session undefined and still flows", () => {
+    const { cookie } = issueSession({ sub: "alice", name: "Alice" }, sessionCfg);
+    const tampered = cookie.replace(/.$/, (c) => (c === "A" ? "B" : "A"));
+    const attach = buildSessionAttacher({ mode: "basic", session: sessionCfg });
+    const req = mkReq({ cookieHeader: `omcp_session=${tampered}` });
+    let called = false;
+    attach(req, mkRes(), () => { called = true; });
+    assert.equal(called, true);
+    assert.equal(req.session, undefined);
+});
+test("require-session — anonymous always allows", () => {
+    const gate = buildRequireSession({ mode: "anonymous" });
+    const req = mkReq();
+    const res = mkRes();
+    let called = false;
+    gate(req, res, () => { called = true; });
+    assert.equal(called, true);
+    assert.equal(res.statusCode, 0);
+});
+test("require-session — basic mode without session returns 401", () => {
+    const runtime = { mode: "basic", session: sessionCfg };
+    const gate = buildRequireSession(runtime);
+    const req = mkReq();
+    const res = mkRes();
+    let called = false;
+    gate(req, res, () => { called = true; });
+    assert.equal(called, false);
+    assert.equal(res.statusCode, 401);
+    const body = res.body;
+    assert.equal(body.code, "OMCP_AUTH_REQUIRED");
+});
+test("require-session — basic mode WITH attached session flows through", () => {
+    const runtime = { mode: "basic", session: sessionCfg };
+    const gate = buildRequireSession(runtime);
+    const req = mkReq();
+    req.session = { sub: "alice", name: "Alice", iat: 0, exp: Date.now() / 1000 + 60 };
+    const res = mkRes();
+    let called = false;
+    gate(req, res, () => { called = true; });
+    assert.equal(called, true);
+    assert.equal(res.statusCode, 0);
+});

package/dist/auth/oidc/client.d.ts

@@ -0,0 +1,73 @@
+/**
+ * High-level OIDC client: glues discovery + JWKS + JWT verify + the
+ * auth-code+PKCE token exchange behind a single small surface.
+ *
+ * Designed to be wired into the existing session middleware in a
+ * later slice. This module stays HTTP-framework agnostic — the caller
+ * decides how to ferry the state/nonce/code_verifier between the
+ * `start()` redirect and the `complete()` callback (we recommend a
+ * short-lived signed cookie).
+ */
+import { type DiscoveryDocument, type Fetcher } from "./discovery.js";
+import { type JwtPayload } from "./jwt.js";
+export interface OidcConfig {
+    /** Issuer URL — what the IdP advertises in its discovery `issuer` field. */
+    issuer: string;
+    clientId: string;
+    /** Confidential clients only. Public/SPA clients omit and rely on PKCE. */
+    clientSecret?: string;
+    /** Absolute callback URL registered with the IdP. */
+    redirectUri: string;
+    /** Space-delimited scopes. Default: "openid profile email". */
+    scopes?: string;
+    /** Custom fetcher (tests). */
+    fetcher?: Fetcher;
+    /** Test clock. */
+    now?: () => number;
+}
+export interface StartResult {
+    /** Where to 302 the browser. */
+    authorizeUrl: string;
+    /** Caller stores these in a short-lived cookie until /callback. */
+    flow: {
+        state: string;
+        nonce: string;
+        codeVerifier: string;
+    };
+}
+export interface CompleteOpts {
+    /** Authorization code from the callback URL. */
+    code: string;
+    /** State returned by the IdP — must match the cookie's flow.state. */
+    state: string;
+    /** The flow object the caller stashed in the cookie at start(). */
+    flow: {
+        state: string;
+        nonce: string;
+        codeVerifier: string;
+    };
+}
+export interface CompleteResult {
+    /** Decoded + verified ID-token claims. */
+    claims: JwtPayload;
+    /** Raw ID token (for upstream propagation if the caller wants it). */
+    idToken: string;
+    /** Access token (opaque). */
+    accessToken?: string;
+}
+export declare class OidcClient {
+    private readonly discovery;
+    private readonly jwks;
+    private readonly cfg;
+    private readonly fetcher;
+    private readonly now;
+    constructor(cfg: OidcConfig);
+    /** Build an authorize URL + mint the state/nonce/PKCE-verifier the
+     * caller must persist until the callback. */
+    start(): Promise<StartResult>;
+    /** Validate the callback: state match → token exchange → ID-token
+     *  signature + claim verification. Throws on any failure. */
+    complete(opts: CompleteOpts): Promise<CompleteResult>;
+    /** Verify a standalone ID token (refresh flows, replay checks). */
+    verify(idToken: string, doc?: DiscoveryDocument, nonce?: string): Promise<JwtPayload>;
+}

package/dist/auth/oidc/client.js

@@ -0,0 +1,104 @@
+/**
+ * High-level OIDC client: glues discovery + JWKS + JWT verify + the
+ * auth-code+PKCE token exchange behind a single small surface.
+ *
+ * Designed to be wired into the existing session middleware in a
+ * later slice. This module stays HTTP-framework agnostic — the caller
+ * decides how to ferry the state/nonce/code_verifier between the
+ * `start()` redirect and the `complete()` callback (we recommend a
+ * short-lived signed cookie).
+ */
+import { DiscoveryClient } from "./discovery.js";
+import { JwksClient } from "./jwks.js";
+import { generatePkcePair } from "./pkce.js";
+import { verifyIdToken } from "./jwt.js";
+import { randomBytes } from "node:crypto";
+export class OidcClient {
+    discovery;
+    jwks;
+    cfg;
+    fetcher;
+    now;
+    constructor(cfg) {
+        this.cfg = cfg;
+        this.fetcher = cfg.fetcher ?? ((u, i) => fetch(u, i));
+        this.now = cfg.now ?? Date.now;
+        this.discovery = new DiscoveryClient({ fetcher: this.fetcher, now: this.now });
+        this.jwks = new JwksClient({ fetcher: this.fetcher, now: this.now });
+    }
+    /** Build an authorize URL + mint the state/nonce/PKCE-verifier the
+     * caller must persist until the callback. */
+    async start() {
+        const doc = await this.discovery.discover(this.cfg.issuer);
+        const pkce = generatePkcePair();
+        const state = base64url(randomBytes(24));
+        const nonce = base64url(randomBytes(24));
+        const params = new URLSearchParams({
+            response_type: "code",
+            client_id: this.cfg.clientId,
+            redirect_uri: this.cfg.redirectUri,
+            scope: this.cfg.scopes ?? "openid profile email",
+            state,
+            nonce,
+            code_challenge: pkce.challenge,
+            code_challenge_method: pkce.method,
+        });
+        return {
+            authorizeUrl: `${doc.authorization_endpoint}?${params.toString()}`,
+            flow: { state, nonce, codeVerifier: pkce.verifier },
+        };
+    }
+    /** Validate the callback: state match → token exchange → ID-token
+     *  signature + claim verification. Throws on any failure. */
+    async complete(opts) {
+        if (opts.state !== opts.flow.state)
+            throw new Error("OIDC callback: state mismatch");
+        const doc = await this.discovery.discover(this.cfg.issuer);
+        const body = new URLSearchParams({
+            grant_type: "authorization_code",
+            code: opts.code,
+            redirect_uri: this.cfg.redirectUri,
+            client_id: this.cfg.clientId,
+            code_verifier: opts.flow.codeVerifier,
+        });
+        const headers = { "content-type": "application/x-www-form-urlencoded", accept: "application/json" };
+        if (this.cfg.clientSecret) {
+            const basic = Buffer.from(`${encodeURIComponent(this.cfg.clientId)}:${encodeURIComponent(this.cfg.clientSecret)}`).toString("base64");
+            headers.authorization = `Basic ${basic}`;
+        }
+        const res = await this.fetcher(doc.token_endpoint, { method: "POST", headers, body: body.toString() });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`OIDC token exchange failed: HTTP ${res.status} ${text}`);
+        }
+        const tokens = (await res.json());
+        if (!tokens.id_token)
+            throw new Error("OIDC token response missing id_token");
+        const claims = await this.verify(tokens.id_token, doc, opts.flow.nonce);
+        return { claims, idToken: tokens.id_token, accessToken: tokens.access_token };
+    }
+    /** Verify a standalone ID token (refresh flows, replay checks). */
+    async verify(idToken, doc, nonce) {
+        const d = doc ?? (await this.discovery.discover(this.cfg.issuer));
+        const header = parseHeader(idToken);
+        const key = await this.jwks.findKey(d.jwks_uri, header.kid);
+        if (!key)
+            throw new Error(`OIDC: no JWKS key for kid=${header.kid ?? "?"}`);
+        return verifyIdToken(idToken, [key], {
+            issuer: this.cfg.issuer,
+            audience: this.cfg.clientId,
+            nonce,
+            now: this.now,
+        });
+    }
+}
+function base64url(buf) {
+    return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function parseHeader(jwt) {
+    const [h] = jwt.split(".");
+    if (!h)
+        throw new Error("malformed JWT");
+    const pad = h.length % 4 === 0 ? "" : "=".repeat(4 - (h.length % 4));
+    return JSON.parse(Buffer.from(h.replace(/-/g, "+").replace(/_/g, "/") + pad, "base64").toString("utf8"));
+}

package/dist/auth/oidc/client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/auth/oidc/client.test.js

@@ -0,0 +1,121 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { generateKeyPairSync, createPublicKey, createSign } from "node:crypto";
+import { OidcClient } from "./client.js";
+function b64u(s) {
+    const b = typeof s === "string" ? Buffer.from(s, "utf8") : s;
+    return b.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+// PEM-encoded sign — see jwt.test.ts for the Node-version-stability
+// reason this avoids the raw KeyObject destructure path.
+function signRs256(payload, privateKeyPem, kid) {
+    const header = b64u(JSON.stringify({ alg: "RS256", typ: "JWT", kid }));
+    const body = b64u(JSON.stringify(payload));
+    const signer = createSign("RSA-SHA256");
+    signer.update(`${header}.${body}`);
+    signer.end();
+    return `${header}.${body}.${b64u(signer.sign(privateKeyPem))}`;
+}
+function rsaKey() {
+    const { publicKey, privateKey } = generateKeyPairSync("rsa", {
+        modulusLength: 2048,
+        publicKeyEncoding: { type: "spki", format: "pem" },
+        privateKeyEncoding: { type: "pkcs8", format: "pem" },
+    });
+    const jwk = createPublicKey(publicKey).export({ format: "jwk" });
+    jwk.kid = "test-kid";
+    return { jwk, privateKeyPem: privateKey };
+}
+function makeFetcher(handlers) {
+    return async (url, init) => {
+        for (const [pattern, handler] of Object.entries(handlers)) {
+            if (url === pattern)
+                return Promise.resolve(handler(init));
+        }
+        return new Response("not found", { status: 404 });
+    };
+}
+const ISSUER = "https://idp.test";
+const DISCOVERY = {
+    issuer: ISSUER,
+    authorization_endpoint: `${ISSUER}/auth`,
+    token_endpoint: `${ISSUER}/token`,
+    jwks_uri: `${ISSUER}/jwks`,
+};
+test("OidcClient.start — builds authorize URL with PKCE + nonce + state", async () => {
+    const fetcher = makeFetcher({
+        [`${ISSUER}/.well-known/openid-configuration`]: () => new Response(JSON.stringify(DISCOVERY), { status: 200 }),
+    });
+    const client = new OidcClient({ issuer: ISSUER, clientId: "c-1", redirectUri: "https://app.test/cb", fetcher });
+    const r = await client.start();
+    const u = new URL(r.authorizeUrl);
+    assert.equal(u.origin + u.pathname, `${ISSUER}/auth`);
+    assert.equal(u.searchParams.get("response_type"), "code");
+    assert.equal(u.searchParams.get("client_id"), "c-1");
+    assert.equal(u.searchParams.get("redirect_uri"), "https://app.test/cb");
+    assert.equal(u.searchParams.get("code_challenge_method"), "S256");
+    assert.ok(u.searchParams.get("code_challenge"));
+    assert.equal(u.searchParams.get("state"), r.flow.state);
+    assert.equal(u.searchParams.get("nonce"), r.flow.nonce);
+    assert.ok(r.flow.codeVerifier.length >= 43);
+});
+test("OidcClient.complete — verifies state, exchanges code, verifies id_token", async () => {
+    const { jwk, privateKeyPem } = rsaKey();
+    const now = 1_700_000_000;
+    const flow = { state: "S", nonce: "N", codeVerifier: "V_43charsminimum_______________________________________________" };
+    const idToken = signRs256({ iss: ISSUER, aud: "c-1", sub: "alice", exp: now + 60, iat: now, nonce: "N" }, privateKeyPem, jwk.kid);
+    const fetcher = makeFetcher({
+        [`${ISSUER}/.well-known/openid-configuration`]: () => new Response(JSON.stringify(DISCOVERY), { status: 200 }),
+        [`${ISSUER}/jwks`]: () => new Response(JSON.stringify({ keys: [jwk] }), { status: 200 }),
+        [`${ISSUER}/token`]: () => new Response(JSON.stringify({ id_token: idToken, access_token: "AT" }), { status: 200 }),
+    });
+    const client = new OidcClient({ issuer: ISSUER, clientId: "c-1", redirectUri: "https://app.test/cb", fetcher, now: () => now * 1000 });
+    const r = await client.complete({ code: "ABC", state: "S", flow });
+    assert.equal(r.claims.sub, "alice");
+    assert.equal(r.accessToken, "AT");
+});
+test("OidcClient.complete — rejects state mismatch", async () => {
+    const fetcher = makeFetcher({
+        [`${ISSUER}/.well-known/openid-configuration`]: () => new Response(JSON.stringify(DISCOVERY), { status: 200 }),
+    });
+    const client = new OidcClient({ issuer: ISSUER, clientId: "c-1", redirectUri: "https://app.test/cb", fetcher });
+    await assert.rejects(client.complete({ code: "x", state: "wrong", flow: { state: "real", nonce: "n", codeVerifier: "v" } }), /state mismatch/);
+});
+test("OidcClient.complete — surfaces token-endpoint failures", async () => {
+    const fetcher = makeFetcher({
+        [`${ISSUER}/.well-known/openid-configuration`]: () => new Response(JSON.stringify(DISCOVERY), { status: 200 }),
+        [`${ISSUER}/token`]: () => new Response(JSON.stringify({ error: "invalid_grant" }), { status: 400 }),
+    });
+    const client = new OidcClient({ issuer: ISSUER, clientId: "c-1", redirectUri: "https://app.test/cb", fetcher });
+    await assert.rejects(client.complete({ code: "x", state: "S", flow: { state: "S", nonce: "n", codeVerifier: "v" } }), /HTTP 400/);
+});
+test("OidcClient.complete — rejects missing id_token in token response", async () => {
+    const fetcher = makeFetcher({
+        [`${ISSUER}/.well-known/openid-configuration`]: () => new Response(JSON.stringify(DISCOVERY), { status: 200 }),
+        [`${ISSUER}/token`]: () => new Response(JSON.stringify({ access_token: "AT" }), { status: 200 }),
+    });
+    const client = new OidcClient({ issuer: ISSUER, clientId: "c-1", redirectUri: "https://app.test/cb", fetcher });
+    await assert.rejects(client.complete({ code: "x", state: "S", flow: { state: "S", nonce: "n", codeVerifier: "v" } }), /missing id_token/);
+});
+test("OidcClient.complete — uses Basic auth when clientSecret set", async () => {
+    const { jwk, privateKeyPem } = rsaKey();
+    const now = 1_700_000_000;
+    const idToken = signRs256({ iss: ISSUER, aud: "c-1", sub: "alice", exp: now + 60, iat: now, nonce: "n" }, privateKeyPem, jwk.kid);
+    let captured;
+    const fetcher = async (url, init) => {
+        if (url === `${ISSUER}/.well-known/openid-configuration`)
+            return new Response(JSON.stringify(DISCOVERY), { status: 200 });
+        if (url === `${ISSUER}/jwks`)
+            return new Response(JSON.stringify({ keys: [jwk] }), { status: 200 });
+        if (url === `${ISSUER}/token`) {
+            captured = (init?.headers).authorization;
+            return new Response(JSON.stringify({ id_token: idToken }), { status: 200 });
+        }
+        return new Response("nf", { status: 404 });
+    };
+    const client = new OidcClient({ issuer: ISSUER, clientId: "c-1", clientSecret: "shh", redirectUri: "https://app.test/cb", fetcher, now: () => now * 1000 });
+    await client.complete({ code: "x", state: "S", flow: { state: "S", nonce: "n", codeVerifier: "v" } });
+    assert.ok(captured?.startsWith("Basic "));
+    const decoded = Buffer.from(captured.slice("Basic ".length), "base64").toString();
+    assert.equal(decoded, "c-1:shh");
+});

package/dist/auth/oidc/dcr.d.ts

@@ -0,0 +1,70 @@
+export interface DcrRegistrationRequest {
+    client_name?: string;
+    redirect_uris?: string[];
+    grant_types?: string[];
+    response_types?: string[];
+    token_endpoint_auth_method?: string;
+    scope?: string;
+    [k: string]: unknown;
+}
+export interface DcrRegistrationResponse {
+    client_id: string;
+    client_secret?: string;
+    client_id_issued_at: number;
+    client_secret_expires_at: number;
+    registration_access_token: string;
+    client_name?: string;
+    redirect_uris: string[];
+    grant_types: string[];
+    response_types: string[];
+    token_endpoint_auth_method: string;
+    scope?: string;
+}
+export interface DcrStoreEntry extends DcrRegistrationResponse {
+    _meta: {
+        sourceIp: string;
+        createdAtIso: string;
+    };
+}
+export declare class DcrValidationError extends Error {
+    readonly error: string;
+    constructor(error: string, message: string);
+}
+/** Stable in-process clock for tests. */
+export interface DcrDeps {
+    now?: () => Date;
+    randomToken?: () => string;
+    storePath?: string;
+}
+export declare function dcrStorePath(env?: NodeJS.ProcessEnv): string;
+export declare function dcrEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Validate + normalise a DCR request body. RFC 7591 is permissive,
+ * so this is the minimum set the gateway insists on:
+ *   - redirect_uris MUST be a non-empty array of absolute https:// URLs
+ *     (http:// allowed only when host is localhost / 127.0.0.1)
+ *   - grant_types / response_types default to {authorization_code} / {code}
+ *   - token_endpoint_auth_method defaults to client_secret_basic
+ *
+ * Throws DcrValidationError on rejection; the route layer maps it to
+ * an RFC 7591 error JSON.
+ */
+export declare function validateDcrRequest(body: DcrRegistrationRequest): {
+    redirect_uris: string[];
+    grant_types: string[];
+    response_types: string[];
+    token_endpoint_auth_method: string;
+    client_name?: string;
+    scope?: string;
+};
+/** Mint a fresh registration. Pure compute except for the random/now
+ *  hooks; the route layer is responsible for persisting + emitting
+ *  the audit entry. */
+export declare function mintRegistration(validated: ReturnType<typeof validateDcrRequest>, sourceIp: string, deps?: DcrDeps): DcrStoreEntry;
+/** File-backed JSON store of DCR registrations. Single-file, single-
+ *  process — multi-replica setups need the F8 shared session store. */
+export declare function loadRegistrations(storePath: string): Promise<DcrStoreEntry[]>;
+export declare function appendRegistration(storePath: string, entry: DcrStoreEntry): Promise<void>;
+/** Surface-only representation: strips `_meta` before sending the
+ *  response. */
+export declare function toResponse(entry: DcrStoreEntry): DcrRegistrationResponse;

package/dist/auth/oidc/dcr.js

@@ -0,0 +1,160 @@
+// Dynamic Client Registration (RFC 7591) — minimal implementation.
+//
+// MCP clients like Claude.ai and Cursor expect to self-register at an
+// OAuth authorization server; this endpoint accepts that shape and
+// stores the registered metadata on disk so the gateway recognises
+// the client on subsequent flows.
+//
+// Off by default (OMCP_OIDC_DCR_ENABLED=true to enable). Persisted
+// to JSON at OMCP_OIDC_DCR_STORE (default /tmp/oidc-dcr.json). Each
+// registration is rate-limited per source IP at the route layer to
+// keep an unauthenticated POST endpoint from being abused.
+import { randomBytes, randomUUID } from "node:crypto";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+export class DcrValidationError extends Error {
+    error;
+    constructor(error, message) {
+        super(message);
+        this.error = error;
+        this.name = "DcrValidationError";
+    }
+}
+const DEFAULT_STORE_PATH = "/tmp/oidc-dcr.json";
+export function dcrStorePath(env = process.env) {
+    return env.OMCP_OIDC_DCR_STORE || DEFAULT_STORE_PATH;
+}
+export function dcrEnabled(env = process.env) {
+    return /^(1|true|yes|on)$/i.test(env.OMCP_OIDC_DCR_ENABLED ?? "");
+}
+/**
+ * Validate + normalise a DCR request body. RFC 7591 is permissive,
+ * so this is the minimum set the gateway insists on:
+ *   - redirect_uris MUST be a non-empty array of absolute https:// URLs
+ *     (http:// allowed only when host is localhost / 127.0.0.1)
+ *   - grant_types / response_types default to {authorization_code} / {code}
+ *   - token_endpoint_auth_method defaults to client_secret_basic
+ *
+ * Throws DcrValidationError on rejection; the route layer maps it to
+ * an RFC 7591 error JSON.
+ */
+export function validateDcrRequest(body) {
+    if (!body || typeof body !== "object") {
+        throw new DcrValidationError("invalid_client_metadata", "body must be a JSON object");
+    }
+    const uris = Array.isArray(body.redirect_uris) ? body.redirect_uris : [];
+    if (uris.length === 0) {
+        throw new DcrValidationError("invalid_redirect_uri", "redirect_uris is required and must be a non-empty array");
+    }
+    for (const u of uris) {
+        if (typeof u !== "string") {
+            throw new DcrValidationError("invalid_redirect_uri", "redirect_uris entries must be strings");
+        }
+        let parsed;
+        try {
+            parsed = new URL(u);
+        }
+        catch {
+            throw new DcrValidationError("invalid_redirect_uri", `redirect_uri "${u}" is not a valid URL`);
+        }
+        if (parsed.protocol === "http:") {
+            const isLoopback = parsed.hostname === "localhost" ||
+                parsed.hostname === "127.0.0.1" ||
+                parsed.hostname === "::1";
+            if (!isLoopback) {
+                throw new DcrValidationError("invalid_redirect_uri", `redirect_uri "${u}" must use https:// (http:// only allowed for localhost loopback)`);
+            }
+        }
+        else if (parsed.protocol !== "https:") {
+            throw new DcrValidationError("invalid_redirect_uri", `redirect_uri "${u}" must use http:// (loopback) or https://`);
+        }
+    }
+    const grants = Array.isArray(body.grant_types) && body.grant_types.length > 0
+        ? body.grant_types
+        : ["authorization_code"];
+    for (const g of grants) {
+        if (typeof g !== "string") {
+            throw new DcrValidationError("invalid_client_metadata", "grant_types entries must be strings");
+        }
+    }
+    const responses = Array.isArray(body.response_types) && body.response_types.length > 0
+        ? body.response_types
+        : ["code"];
+    for (const r of responses) {
+        if (typeof r !== "string") {
+            throw new DcrValidationError("invalid_client_metadata", "response_types entries must be strings");
+        }
+    }
+    const authMethod = typeof body.token_endpoint_auth_method === "string" && body.token_endpoint_auth_method.length > 0
+        ? body.token_endpoint_auth_method
+        : "client_secret_basic";
+    return {
+        redirect_uris: uris,
+        grant_types: grants,
+        response_types: responses,
+        token_endpoint_auth_method: authMethod,
+        client_name: typeof body.client_name === "string" ? body.client_name : undefined,
+        scope: typeof body.scope === "string" ? body.scope : undefined,
+    };
+}
+/** Mint a fresh registration. Pure compute except for the random/now
+ *  hooks; the route layer is responsible for persisting + emitting
+ *  the audit entry. */
+export function mintRegistration(validated, sourceIp, deps = {}) {
+    const now = (deps.now ?? (() => new Date()))();
+    const randomToken = deps.randomToken ?? (() => randomBytes(32).toString("base64url"));
+    const clientId = randomUUID();
+    // Public clients (e.g. SPAs with PKCE) typically request
+    // token_endpoint_auth_method=none — in that case we don't issue a
+    // secret, matching RFC 7591 §3.2.1.
+    const clientSecret = validated.token_endpoint_auth_method === "none"
+        ? undefined
+        : randomToken();
+    return {
+        client_id: clientId,
+        client_secret: clientSecret,
+        client_id_issued_at: Math.floor(now.getTime() / 1000),
+        client_secret_expires_at: 0, // 0 = never expires per RFC 7591
+        registration_access_token: randomToken(),
+        client_name: validated.client_name,
+        redirect_uris: validated.redirect_uris,
+        grant_types: validated.grant_types,
+        response_types: validated.response_types,
+        token_endpoint_auth_method: validated.token_endpoint_auth_method,
+        scope: validated.scope,
+        _meta: {
+            sourceIp,
+            createdAtIso: now.toISOString(),
+        },
+    };
+}
+/** File-backed JSON store of DCR registrations. Single-file, single-
+ *  process — multi-replica setups need the F8 shared session store. */
+export async function loadRegistrations(storePath) {
+    try {
+        const raw = await readFile(storePath, "utf8");
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+}
+export async function appendRegistration(storePath, entry) {
+    await mkdir(dirname(storePath), { recursive: true }).catch(() => undefined);
+    const existing = await loadRegistrations(storePath);
+    existing.push(entry);
+    // Write to a tmp file and rename for atomicity.
+    const tmp = `${storePath}.tmp`;
+    await writeFile(tmp, JSON.stringify(existing, null, 2), { mode: 0o600 });
+    await (await import("node:fs/promises")).rename(tmp, storePath);
+}
+/** Surface-only representation: strips `_meta` before sending the
+ *  response. */
+export function toResponse(entry) {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { _meta, ...rest } = entry;
+    return rest;
+}

package/dist/auth/oidc/dcr.test.d.ts

@@ -0,0 +1 @@
+export {};