@thotischner/observability-mcp 1.8.1 → 3.0.1

package/dist/auth/middleware.d.ts

@@ -13,6 +13,7 @@
  */
 import type { Request, RequestHandler } from "express";
 import { type SessionPayload, type SessionConfig } from "./session.js";
+import type { OidcRuntime } from "./oidc/runtime.js";
 export type AuthMode = "anonymous" | "basic" | "oidc";
 export interface AuthRuntime {
     mode: AuthMode;
@@ -23,12 +24,12 @@ export interface AuthRuntime {
      * process — sessions will not survive a restart. The wire-up code logs a
      * warning once when this happens. */
     secretEphemeral?: boolean;
-    /** OIDC runtime, present only when mode === "oidc". Opaque to this
-     *  module — the OIDC HTTP endpoints in src/index.ts consume it.
-     *  Typed as `unknown` here to avoid importing the OIDC sub-module
-     *  and pulling its node:crypto dependency into the middleware
-     *  surface. The OIDC wire-up casts on the way in. */
-    oidc?: unknown;
+    /** OIDC runtime, present only when mode === "oidc". The OIDC HTTP
+     *  endpoints in src/index.ts consume it. The import above is
+     *  type-only and erased at compile time, so this typing adds zero
+     *  runtime coupling — middleware.ts still doesn't depend on the
+     *  OIDC sub-module's node:crypto path. */
+    oidc?: OidcRuntime;
 }
 export interface AuthedRequest extends Request {
     session?: SessionPayload;

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 {};

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

@@ -0,0 +1,109 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { validateDcrRequest, mintRegistration, appendRegistration, loadRegistrations, toResponse, dcrEnabled, dcrStorePath, DcrValidationError, } from "./dcr.js";
+function tmp() {
+    return join(mkdtempSync(join(tmpdir(), "dcr-")), "dcr.json");
+}
+test("dcrEnabled — true/1/yes/on (any case), unset = false", () => {
+    for (const v of ["true", "1", "yes", "on", "TRUE", "Yes"]) {
+        assert.equal(dcrEnabled({ OMCP_OIDC_DCR_ENABLED: v }), true, v);
+    }
+    for (const v of ["", "false", "0", "anything-else"]) {
+        assert.equal(dcrEnabled({ OMCP_OIDC_DCR_ENABLED: v }), false, v);
+    }
+    assert.equal(dcrEnabled({}), false);
+});
+test("dcrStorePath — defaults to /tmp/oidc-dcr.json, env override wins", () => {
+    assert.equal(dcrStorePath({}), "/tmp/oidc-dcr.json");
+    assert.equal(dcrStorePath({ OMCP_OIDC_DCR_STORE: "/var/lib/dcr.json" }), "/var/lib/dcr.json");
+});
+test("validateDcrRequest — requires non-empty redirect_uris", () => {
+    assert.throws(() => validateDcrRequest({}), DcrValidationError);
+    assert.throws(() => validateDcrRequest({ redirect_uris: [] }), DcrValidationError);
+});
+test("validateDcrRequest — rejects http:// for non-loopback hosts", () => {
+    assert.throws(() => validateDcrRequest({ redirect_uris: ["http://example.com/cb"] }), /must use https/);
+    assert.doesNotThrow(() => validateDcrRequest({ redirect_uris: ["http://localhost:5173/cb"] }));
+    assert.doesNotThrow(() => validateDcrRequest({ redirect_uris: ["http://127.0.0.1:5173/cb"] }));
+});
+test("validateDcrRequest — accepts https:// always", () => {
+    const v = validateDcrRequest({
+        redirect_uris: ["https://app.example.com/oauth/callback"],
+    });
+    assert.deepEqual(v.redirect_uris, ["https://app.example.com/oauth/callback"]);
+});
+test("validateDcrRequest — defaults for grant_types/response_types/auth_method", () => {
+    const v = validateDcrRequest({ redirect_uris: ["https://x/cb"] });
+    assert.deepEqual(v.grant_types, ["authorization_code"]);
+    assert.deepEqual(v.response_types, ["code"]);
+    assert.equal(v.token_endpoint_auth_method, "client_secret_basic");
+});
+test("validateDcrRequest — preserves explicit values", () => {
+    const v = validateDcrRequest({
+        redirect_uris: ["https://x/cb"],
+        grant_types: ["refresh_token"],
+        response_types: ["code id_token"],
+        token_endpoint_auth_method: "none",
+        client_name: "Claude.ai",
+        scope: "openid profile",
+    });
+    assert.deepEqual(v.grant_types, ["refresh_token"]);
+    assert.equal(v.token_endpoint_auth_method, "none");
+    assert.equal(v.client_name, "Claude.ai");
+    assert.equal(v.scope, "openid profile");
+});
+test("mintRegistration — issues client_id (UUID), client_secret (base64url), no secret for 'none' auth", () => {
+    const now = new Date("2026-06-05T20:00:00Z");
+    const validated = validateDcrRequest({ redirect_uris: ["https://x/cb"] });
+    const reg = mintRegistration(validated, "10.0.0.1", { now: () => now });
+    assert.match(reg.client_id, /^[0-9a-f-]{36}$/);
+    assert.ok(reg.client_secret && reg.client_secret.length > 30);
+    assert.equal(reg.client_id_issued_at, Math.floor(now.getTime() / 1000));
+    assert.equal(reg.client_secret_expires_at, 0);
+    assert.ok(reg.registration_access_token && reg.registration_access_token.length > 30);
+    assert.equal(reg._meta.sourceIp, "10.0.0.1");
+    assert.equal(reg._meta.createdAtIso, now.toISOString());
+    // Public client (PKCE, no secret) — RFC 7591 §3.2.1
+    const pub = mintRegistration(validateDcrRequest({
+        redirect_uris: ["https://x/cb"],
+        token_endpoint_auth_method: "none",
+    }), "10.0.0.1", { now: () => now });
+    assert.equal(pub.client_secret, undefined);
+});
+test("appendRegistration + loadRegistrations — round-trips, file is 0600", async () => {
+    const store = tmp();
+    const validated = validateDcrRequest({ redirect_uris: ["https://x/cb"] });
+    const reg = mintRegistration(validated, "10.0.0.7");
+    await appendRegistration(store, reg);
+    const loaded = await loadRegistrations(store);
+    assert.equal(loaded.length, 1);
+    assert.equal(loaded[0]?.client_id, reg.client_id);
+    // File-mode check — DCR registrations contain secrets.
+    const mode = statSync(store).mode & 0o777;
+    assert.equal(mode, 0o600, `expected mode 0o600 got ${mode.toString(8)}`);
+});
+test("loadRegistrations — missing file returns []", async () => {
+    const store = tmp();
+    // No file written.
+    const loaded = await loadRegistrations(store);
+    assert.deepEqual(loaded, []);
+});
+test("toResponse — strips internal _meta so secrets don't leak source IP", () => {
+    const validated = validateDcrRequest({ redirect_uris: ["https://x/cb"] });
+    const reg = mintRegistration(validated, "10.0.0.7");
+    const response = toResponse(reg);
+    assert.equal(response._meta, undefined);
+    assert.equal(response.client_id, reg.client_id);
+    assert.equal(response.client_secret, reg.client_secret);
+});
+test("appendRegistration — atomic write (tmp+rename) survives a missing parent dir", async () => {
+    const parent = mkdtempSync(join(tmpdir(), "dcr-parent-"));
+    const store = join(parent, "sub", "nested", "dcr.json");
+    const reg = mintRegistration(validateDcrRequest({ redirect_uris: ["https://x/cb"] }), "10.0.0.7");
+    await appendRegistration(store, reg);
+    const onDisk = JSON.parse(readFileSync(store, "utf8"));
+    assert.equal(onDisk.length, 1);
+});

package/dist/auth/oidc/endpoints.js

@@ -9,8 +9,10 @@
  * Response) but otherwise pure; the OIDC client + role resolver come
  * from the runtime built in `./runtime.ts`.
  */
+import rateLimit from "express-rate-limit";
 import { issueSession, setCookieHeader, clearCookieHeader } from "../session.js";
 import { issueFlowCookie, verifyFlowCookie, setFlowCookieHeader, clearFlowCookieHeader, readFlowCookie, isSafeReturnTo, } from "./flow-cookie.js";
+import { dcrEnabled, dcrStorePath, validateDcrRequest, mintRegistration, appendRegistration, toResponse, DcrValidationError, } from "./dcr.js";
 function isSecure(req) {
     return req.secure || req.headers["x-forwarded-proto"] === "https";
 }
@@ -104,6 +106,48 @@ export function registerOidcRoutes(app, deps) {
         // navigates the user.
         res.status(204).end();
     });
+    // RFC 7591 Dynamic Client Registration. Off by default; flip
+    // OMCP_OIDC_DCR_ENABLED=true to accept self-registration POSTs
+    // (Claude.ai / Cursor / future MCP clients use this to introduce
+    // themselves to the gateway). Registrations land at
+    // OMCP_OIDC_DCR_STORE (default /tmp/oidc-dcr.json, mode 0600).
+    if (dcrEnabled()) {
+        const storePath = dcrStorePath();
+        // Per-source-IP throttle: 10 registrations per IP per hour. The
+        // endpoint is unauthenticated by design (RFC 7591) so without a
+        // limiter a single misbehaving client can fill the JSON store.
+        // Operators that need a different rate front the gateway with
+        // their ingress limiter and lift this floor accordingly.
+        const dcrLimiter = rateLimit({
+            windowMs: 60 * 60 * 1000,
+            max: 10,
+            standardHeaders: true,
+            legacyHeaders: false,
+            message: { error: "rate_limit_exceeded", error_description: "DCR rate limit hit; try later" },
+        });
+        app.post("/api/auth/oidc/register", dcrLimiter, async (req, res) => {
+            try {
+                const validated = validateDcrRequest((req.body ?? {}));
+                const sourceIp = req.headers["x-forwarded-for"]?.split(",")[0]?.trim() ||
+                    req.ip ||
+                    "unknown";
+                const reg = mintRegistration(validated, sourceIp);
+                await appendRegistration(storePath, reg);
+                res.status(201).json(toResponse(reg));
+            }
+            catch (e) {
+                if (e instanceof DcrValidationError) {
+                    // RFC 7591 §3.2.2 error response shape.
+                    res.status(400).json({
+                        error: e.error,
+                        error_description: e.message,
+                    });
+                    return;
+                }
+                respondError(res, 500, "registration_failed", e.message);
+            }
+        });
+    }
 }
 function respondError(res, status, code, message) {
     res.status(status).json({ error: code, message });

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

@@ -0,0 +1,22 @@
+export interface VendorProfile {
+    /** Profile id, matches OMCP_OIDC_PROFILE. */
+    readonly name: string;
+    /** Human-readable label for logs + UI. */
+    readonly label: string;
+    /** Default OAuth scopes. */
+    readonly scopes: string;
+    /** Dotted claim path the IdP puts the user's group/role list under. */
+    readonly rolesClaim: string;
+    /** Default dotted claim path for tenant identification. Empty = all
+     *  sessions land in the default tenant (operators usually leave
+     *  this off unless they really do multi-tenant federation). */
+    readonly tenantClaim: string;
+    /** Doc URL deep-linked from the boot log on misconfiguration. */
+    readonly docs: string;
+}
+/** Returns the profile or undefined. Case-insensitive. */
+export declare function getProfile(name: string | undefined): VendorProfile | undefined;
+/** All known profile names, useful for help text + the boot log. */
+export declare function profileNames(): string[];
+/** Default profile = generic (matches pre-F6 behaviour exactly). */
+export declare const DEFAULT_PROFILE: VendorProfile;

package/dist/auth/oidc/profiles.js

@@ -0,0 +1,95 @@
+// SSO vendor presets.
+//
+// Each profile preconfigures the OIDC fields that differ between
+// well-known providers (scopes, claim paths for roles/groups, default
+// logout URL pattern). The operator still provides issuer / clientId
+// / redirectUri / clientSecret via env; the profile fills in the rest
+// so a typical Entra or Okta rollout doesn't need a custom config.
+//
+// Explicit env vars ALWAYS override profile defaults — profiles are
+// best-effort defaults, never a hard override.
+const PROFILES = {
+    // Generic OIDC — the existing behaviour (matches Keycloak, Authentik,
+    // Auth0, and any compliant provider that uses standard claims).
+    generic: {
+        name: "generic",
+        label: "Generic OIDC",
+        scopes: "openid profile email",
+        rolesClaim: "groups",
+        tenantClaim: "",
+        docs: "docs/auth-oidc.md",
+    },
+    // Keycloak ships groups under "groups" or "realm_access.roles"
+    // depending on mapper config. Default to "groups" to match the
+    // out-of-the-box realm export the demo profile uses.
+    keycloak: {
+        name: "keycloak",
+        label: "Keycloak",
+        scopes: "openid profile email",
+        rolesClaim: "groups",
+        tenantClaim: "",
+        // The existing OIDC reference covers Keycloak end-to-end (the
+        // demo profile ships a Keycloak realm export). A dedicated
+        // per-vendor page would duplicate it.
+        docs: "docs/auth-oidc.md",
+    },
+    // GitHub does not expose groups natively in its OIDC tokens; the
+    // common pattern is to use the "Teams" mapper or a custom claim
+    // provider. We default to "groups" so an operator who sets up a
+    // mapper sees their roles flow through; if they use a different
+    // claim, OMCP_OIDC_ROLES_CLAIM still overrides.
+    github: {
+        name: "github",
+        label: "GitHub",
+        scopes: "openid profile email read:org",
+        rolesClaim: "groups",
+        tenantClaim: "",
+        docs: "docs/auth-oidc-providers/github.md",
+    },
+    // Google Workspace exposes group membership via the "groups" claim
+    // when the directory API consent is granted; otherwise treat it as
+    // a single-user case (no group → no role mapping → user inherits
+    // the OIDC default role).
+    google: {
+        name: "google",
+        label: "Google Workspace",
+        scopes: "openid profile email",
+        rolesClaim: "groups",
+        tenantClaim: "hd", // "hd" = hosted domain, useful as a tenant key
+        docs: "docs/auth-oidc-providers/google.md",
+    },
+    // Microsoft Entra ID (formerly Azure AD) puts group IDs (object IDs)
+    // under "groups". For >200 groups it switches to a graph link
+    // claim — operators in that case must use a custom claim mapping
+    // policy; documented in the per-vendor doc.
+    "microsoft-entra": {
+        name: "microsoft-entra",
+        label: "Microsoft Entra ID",
+        scopes: "openid profile email",
+        rolesClaim: "groups",
+        tenantClaim: "tid", // "tid" = tenant id (Entra-native)
+        docs: "docs/auth-oidc-providers/microsoft-entra.md",
+    },
+    // Okta exposes groups via the "groups" claim when an OIDC Group
+    // claim mapper is added (default for any non-trivial app).
+    okta: {
+        name: "okta",
+        label: "Okta",
+        scopes: "openid profile email groups",
+        rolesClaim: "groups",
+        tenantClaim: "",
+        docs: "docs/auth-oidc-providers/okta.md",
+    },
+};
+/** Returns the profile or undefined. Case-insensitive. */
+export function getProfile(name) {
+    if (!name)
+        return undefined;
+    return PROFILES[name.toLowerCase()];
+}
+/** All known profile names, useful for help text + the boot log. */
+export function profileNames() {
+    return Object.keys(PROFILES);
+}
+/** Default profile = generic (matches pre-F6 behaviour exactly). */
+export const DEFAULT_PROFILE = PROFILES.generic;

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

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

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

@@ -0,0 +1,51 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { getProfile, profileNames, DEFAULT_PROFILE, } from "./profiles.js";
+test("profiles: getProfile returns known profiles, case-insensitive", () => {
+    assert.equal(getProfile("github")?.name, "github");
+    assert.equal(getProfile("Github")?.name, "github");
+    assert.equal(getProfile("MICROSOFT-ENTRA")?.name, "microsoft-entra");
+});
+test("profiles: getProfile returns undefined for unknown / empty", () => {
+    assert.equal(getProfile(undefined), undefined);
+    assert.equal(getProfile(""), undefined);
+    assert.equal(getProfile("nope"), undefined);
+});
+test("profiles: profileNames lists the 6 baked-in profiles", () => {
+    const names = profileNames();
+    for (const expected of [
+        "generic",
+        "keycloak",
+        "github",
+        "google",
+        "microsoft-entra",
+        "okta",
+    ]) {
+        assert.ok(names.includes(expected), `missing profile ${expected}`);
+    }
+});
+test("profiles: DEFAULT_PROFILE is generic and preserves the pre-F6 defaults", () => {
+    assert.equal(DEFAULT_PROFILE.name, "generic");
+    assert.equal(DEFAULT_PROFILE.scopes, "openid profile email");
+    assert.equal(DEFAULT_PROFILE.rolesClaim, "groups");
+    assert.equal(DEFAULT_PROFILE.tenantClaim, "");
+});
+test("profiles: vendor-specific tenant claims match the IdP-native key", () => {
+    // hd = hosted domain (Google) — useful as a tenant key for
+    // multi-org Workspace deployments
+    assert.equal(getProfile("google")?.tenantClaim, "hd");
+    // tid = tenant id (Entra-native)
+    assert.equal(getProfile("microsoft-entra")?.tenantClaim, "tid");
+});
+test("profiles: Okta scopes include 'groups' so the claim is actually returned", () => {
+    // Okta's group claim is only emitted when 'groups' is in the
+    // requested scope set; profile must include it as a default.
+    assert.match(getProfile("okta")?.scopes ?? "", /\bgroups\b/);
+});
+test("profiles: each profile has a docs path", () => {
+    for (const name of profileNames()) {
+        const p = getProfile(name);
+        assert.ok(p.docs, `profile ${name} has no docs path`);
+        assert.match(p.docs, /^docs\//, `profile ${name} docs should be a repo-relative path`);
+    }
+});

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

@@ -34,6 +34,9 @@ export interface OidcRuntimeConfig {
     /** Dotted claim path to read the tenant from. Empty / missing → all
      *  OIDC sessions land in the "default" tenant. */
     tenantClaim: string;
+    /** Vendor profile id (generic / github / google / microsoft-entra /
+     *  okta / keycloak) — surfaced in /api/info for diagnostics. */
+    profile?: string;
 }
 export interface ResolveOidcResult {
     /** Fully validated runtime config; absent when `error` is set. */

package/dist/auth/oidc/runtime.js

@@ -23,6 +23,7 @@
  */
 import { OidcClient } from "./client.js";
 import { DEFAULT_TENANT, tenantFromClaim } from "../../tenancy/context.js";
+import { getProfile, DEFAULT_PROFILE } from "./profiles.js";
 /** Pure env-to-config translator. No I/O. */
 export function resolveOidcConfig(env = process.env) {
     const issuer = nonEmpty(env.OMCP_OIDC_ISSUER);
@@ -63,17 +64,29 @@ export function resolveOidcConfig(env = process.env) {
             return { error: `OMCP_OIDC_ROLE_MAP is not valid JSON: ${e.message}` };
         }
     }
+    // Vendor profile resolves IdP-shaped defaults (scopes / rolesClaim /
+    // tenantClaim) when OMCP_OIDC_PROFILE is set. Explicit env vars
+    // always win — profiles only fill the gaps an operator chose not to
+    // set, so this is fully backwards-compatible with pre-F6 configs.
+    const profileName = nonEmpty(env.OMCP_OIDC_PROFILE);
+    const profile = (profileName && getProfile(profileName)) || DEFAULT_PROFILE;
+    if (profileName && !getProfile(profileName)) {
+        return {
+            error: `OMCP_OIDC_PROFILE=${profileName} is not a known profile (try one of: generic, keycloak, github, google, microsoft-entra, okta)`,
+        };
+    }
     return {
         config: {
             issuer: issuer.replace(/\/$/, ""),
             clientId: clientId,
             clientSecret: nonEmpty(env.OMCP_OIDC_CLIENT_SECRET),
             redirectUri: redirectUri,
-            scopes: nonEmpty(env.OMCP_OIDC_SCOPES) ?? "openid profile email",
-            rolesClaim: nonEmpty(env.OMCP_OIDC_ROLES_CLAIM) ?? "groups",
+            scopes: nonEmpty(env.OMCP_OIDC_SCOPES) ?? profile.scopes,
+            rolesClaim: nonEmpty(env.OMCP_OIDC_ROLES_CLAIM) ?? profile.rolesClaim,
             roleMap,
             logoutRedirect: nonEmpty(env.OMCP_OIDC_LOGOUT_REDIRECT) ?? "/",
-            tenantClaim: nonEmpty(env.OMCP_OIDC_TENANT_CLAIM) ?? "",
+            tenantClaim: nonEmpty(env.OMCP_OIDC_TENANT_CLAIM) ?? profile.tenantClaim,
+            profile: profile.name,
         },
     };
 }

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

@@ -21,6 +21,7 @@ test("resolveOidcConfig — happy path with required vars only", () => {
         roleMap: {},
         logoutRedirect: "/",
         tenantClaim: "",
+        profile: "generic",
     });
 });
 test("resolveOidcConfig — honours OMCP_OIDC_TENANT_CLAIM", () => {