@thotischner/observability-mcp 1.7.1 → 3.0.0

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

@@ -0,0 +1,66 @@
+/**
+ * Resolve the OIDC configuration from environment variables and turn
+ * it into the runtime shape the rest of the auth layer consumes.
+ *
+ * Mirrors the basic-mode resolution in src/index.ts: fail-closed on
+ * missing required config, allow an `OMCP_AUTH_ALLOW_FALLBACK=true`
+ * opt-out (handled by the caller — this module just signals via the
+ * `error` field).
+ *
+ * Required env (when OMCP_AUTH=oidc):
+ *   OMCP_OIDC_ISSUER         — IdP base URL (no trailing /.well-known/...)
+ *   OMCP_OIDC_CLIENT_ID
+ *   OMCP_OIDC_REDIRECT_URI   — absolute, MUST match the registration
+ *
+ * Optional env:
+ *   OMCP_OIDC_CLIENT_SECRET  — confidential clients; public clients omit
+ *   OMCP_OIDC_SCOPES         — default "openid profile email"
+ *   OMCP_OIDC_ROLES_CLAIM    — dotted path; default "groups"
+ *   OMCP_OIDC_ROLE_MAP       — JSON {"<claim-value>": "<omcp-role>"};
+ *                              entries map directly to RBAC roles
+ *                              (viewer / operator / admin or custom).
+ *   OMCP_OIDC_LOGOUT_REDIRECT — post-logout landing URL (default "/")
+ */
+import { OidcClient } from "./client.js";
+export interface OidcRuntimeConfig {
+    issuer: string;
+    clientId: string;
+    clientSecret?: string;
+    redirectUri: string;
+    scopes: string;
+    rolesClaim: string;
+    roleMap: Record<string, string>;
+    logoutRedirect: string;
+    /** 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. */
+    config?: OidcRuntimeConfig;
+    /** Human-readable misconfiguration reason; used for the boot log
+     *  + fail-closed exit. */
+    error?: string;
+}
+/** Pure env-to-config translator. No I/O. */
+export declare function resolveOidcConfig(env?: NodeJS.ProcessEnv): ResolveOidcResult;
+/** Build the OidcClient + the role-resolution helper from a resolved
+ * runtime config. Tests can stub OidcClient by passing a custom one. */
+export interface OidcRuntime {
+    cfg: OidcRuntimeConfig;
+    client: OidcClient;
+    /** Walk a JWT claim set, follow the rolesClaim dotted path, and
+     *  return the OMCP role names the user inherits via roleMap.
+     *  Unknown claim values are silently dropped (least-privilege). */
+    resolveRoles(claims: Record<string, unknown>): string[];
+    /** Walk a JWT claim set, follow the configured tenant claim path,
+     *  and return a normalised tenant id. Empty / missing / invalid →
+     *  DEFAULT_TENANT. */
+    resolveTenant(claims: Record<string, unknown>): string;
+}
+export declare function buildOidcRuntime(cfg: OidcRuntimeConfig, opts?: {
+    client?: OidcClient;
+}): OidcRuntime;

package/dist/auth/oidc/runtime.js

@@ -0,0 +1,142 @@
+/**
+ * Resolve the OIDC configuration from environment variables and turn
+ * it into the runtime shape the rest of the auth layer consumes.
+ *
+ * Mirrors the basic-mode resolution in src/index.ts: fail-closed on
+ * missing required config, allow an `OMCP_AUTH_ALLOW_FALLBACK=true`
+ * opt-out (handled by the caller — this module just signals via the
+ * `error` field).
+ *
+ * Required env (when OMCP_AUTH=oidc):
+ *   OMCP_OIDC_ISSUER         — IdP base URL (no trailing /.well-known/...)
+ *   OMCP_OIDC_CLIENT_ID
+ *   OMCP_OIDC_REDIRECT_URI   — absolute, MUST match the registration
+ *
+ * Optional env:
+ *   OMCP_OIDC_CLIENT_SECRET  — confidential clients; public clients omit
+ *   OMCP_OIDC_SCOPES         — default "openid profile email"
+ *   OMCP_OIDC_ROLES_CLAIM    — dotted path; default "groups"
+ *   OMCP_OIDC_ROLE_MAP       — JSON {"<claim-value>": "<omcp-role>"};
+ *                              entries map directly to RBAC roles
+ *                              (viewer / operator / admin or custom).
+ *   OMCP_OIDC_LOGOUT_REDIRECT — post-logout landing URL (default "/")
+ */
+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);
+    const clientId = nonEmpty(env.OMCP_OIDC_CLIENT_ID);
+    const redirectUri = nonEmpty(env.OMCP_OIDC_REDIRECT_URI);
+    const missing = [];
+    if (!issuer)
+        missing.push("OMCP_OIDC_ISSUER");
+    if (!clientId)
+        missing.push("OMCP_OIDC_CLIENT_ID");
+    if (!redirectUri)
+        missing.push("OMCP_OIDC_REDIRECT_URI");
+    if (missing.length > 0) {
+        return { error: `OMCP_AUTH=oidc requires ${missing.join(", ")}` };
+    }
+    if (!/^https?:\/\//i.test(issuer)) {
+        return { error: `OMCP_OIDC_ISSUER must be an absolute http(s):// URL, got ${issuer}` };
+    }
+    if (!/^https?:\/\//i.test(redirectUri)) {
+        return { error: `OMCP_OIDC_REDIRECT_URI must be an absolute http(s):// URL, got ${redirectUri}` };
+    }
+    let roleMap = {};
+    const roleMapRaw = nonEmpty(env.OMCP_OIDC_ROLE_MAP);
+    if (roleMapRaw) {
+        try {
+            const parsed = JSON.parse(roleMapRaw);
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                return { error: "OMCP_OIDC_ROLE_MAP must be a JSON object of {\"claim-value\":\"omcp-role\"}" };
+            }
+            for (const [k, v] of Object.entries(parsed)) {
+                if (typeof v !== "string") {
+                    return { error: `OMCP_OIDC_ROLE_MAP[${k}] must be a string, got ${typeof v}` };
+                }
+                roleMap[k] = v;
+            }
+        }
+        catch (e) {
+            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) ?? 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) ?? profile.tenantClaim,
+            profile: profile.name,
+        },
+    };
+}
+export function buildOidcRuntime(cfg, opts = {}) {
+    const client = opts.client ?? new OidcClient({
+        issuer: cfg.issuer,
+        clientId: cfg.clientId,
+        clientSecret: cfg.clientSecret,
+        redirectUri: cfg.redirectUri,
+        scopes: cfg.scopes,
+    });
+    return {
+        cfg,
+        client,
+        resolveRoles(claims) {
+            const raw = lookupClaim(claims, cfg.rolesClaim);
+            const values = Array.isArray(raw)
+                ? raw.filter((v) => typeof v === "string")
+                : typeof raw === "string"
+                    ? [raw]
+                    : [];
+            const roles = new Set();
+            for (const v of values) {
+                const mapped = cfg.roleMap[v];
+                if (mapped)
+                    roles.add(mapped);
+            }
+            return [...roles];
+        },
+        resolveTenant(claims) {
+            return cfg.tenantClaim ? tenantFromClaim(claims, cfg.tenantClaim) : DEFAULT_TENANT;
+        },
+    };
+}
+function nonEmpty(v) {
+    if (v === undefined)
+        return undefined;
+    const t = v.trim();
+    return t.length > 0 ? t : undefined;
+}
+function lookupClaim(claims, dottedPath) {
+    const parts = dottedPath.split(".");
+    let cur = claims;
+    for (const p of parts) {
+        if (cur && typeof cur === "object" && !Array.isArray(cur) && p in cur) {
+            cur = cur[p];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return cur;
+}

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

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

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

@@ -0,0 +1,181 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { resolveOidcConfig, buildOidcRuntime } from "./runtime.js";
+function envOf(overrides) {
+    return { ...overrides };
+}
+test("resolveOidcConfig — happy path with required vars only", () => {
+    const r = resolveOidcConfig(envOf({
+        OMCP_OIDC_ISSUER: "https://idp.test",
+        OMCP_OIDC_CLIENT_ID: "c-1",
+        OMCP_OIDC_REDIRECT_URI: "https://app.test/cb",
+    }));
+    assert.equal(r.error, undefined);
+    assert.deepEqual(r.config, {
+        issuer: "https://idp.test",
+        clientId: "c-1",
+        clientSecret: undefined,
+        redirectUri: "https://app.test/cb",
+        scopes: "openid profile email",
+        rolesClaim: "groups",
+        roleMap: {},
+        logoutRedirect: "/",
+        tenantClaim: "",
+        profile: "generic",
+    });
+});
+test("resolveOidcConfig — honours OMCP_OIDC_TENANT_CLAIM", () => {
+    const r = resolveOidcConfig(envOf({
+        OMCP_OIDC_ISSUER: "https://idp.test",
+        OMCP_OIDC_CLIENT_ID: "c-1",
+        OMCP_OIDC_REDIRECT_URI: "https://app.test/cb",
+        OMCP_OIDC_TENANT_CLAIM: "app.tenant_id",
+    }));
+    assert.equal(r.config?.tenantClaim, "app.tenant_id");
+});
+test("buildOidcRuntime.resolveTenant — empty claim path → default", () => {
+    const r = resolveOidcConfig(envOf({
+        OMCP_OIDC_ISSUER: "https://idp.test", OMCP_OIDC_CLIENT_ID: "c",
+        OMCP_OIDC_REDIRECT_URI: "https://app.test/cb",
+    }));
+    const rt = buildOidcRuntime(r.config);
+    assert.equal(rt.resolveTenant({ tenant: "acme" }), "default");
+});
+test("buildOidcRuntime.resolveTenant — dotted path", () => {
+    const r = resolveOidcConfig(envOf({
+        OMCP_OIDC_ISSUER: "https://idp.test", OMCP_OIDC_CLIENT_ID: "c",
+        OMCP_OIDC_REDIRECT_URI: "https://app.test/cb",
+        OMCP_OIDC_TENANT_CLAIM: "app.tenant_id",
+    }));
+    const rt = buildOidcRuntime(r.config);
+    assert.equal(rt.resolveTenant({ app: { tenant_id: "acme" } }), "acme");
+    assert.equal(rt.resolveTenant({ app: { other: "x" } }), "default");
+});
+test("resolveOidcConfig — surfaces ALL missing required vars in one message", () => {
+    const r = resolveOidcConfig(envOf({}));
+    assert.match(r.error ?? "", /OMCP_OIDC_ISSUER.*OMCP_OIDC_CLIENT_ID.*OMCP_OIDC_REDIRECT_URI/);
+    assert.equal(r.config, undefined);
+});
+test("resolveOidcConfig — rejects non-URL issuer / redirect", () => {
+    const r1 = resolveOidcConfig(envOf({
+        OMCP_OIDC_ISSUER: "idp.test",
+        OMCP_OIDC_CLIENT_ID: "c", OMCP_OIDC_REDIRECT_URI: "https://app.test/cb",
+    }));
+    assert.match(r1.error ?? "", /OMCP_OIDC_ISSUER must be an absolute/);
+    const r2 = resolveOidcConfig(envOf({
+        OMCP_OIDC_ISSUER: "https://idp.test", OMCP_OIDC_CLIENT_ID: "c",
+        OMCP_OIDC_REDIRECT_URI: "/cb",
+    }));
+    assert.match(r2.error ?? "", /OMCP_OIDC_REDIRECT_URI must be an absolute/);
+});
+test("resolveOidcConfig — strips a single trailing slash off issuer", () => {
+    const r = resolveOidcConfig(envOf({
+        OMCP_OIDC_ISSUER: "https://idp.test/",
+        OMCP_OIDC_CLIENT_ID: "c", OMCP_OIDC_REDIRECT_URI: "https://app.test/cb",
+    }));
+    assert.equal(r.config?.issuer, "https://idp.test");
+});
+test("resolveOidcConfig — empty strings count as missing", () => {
+    const r = resolveOidcConfig(envOf({
+        OMCP_OIDC_ISSUER: "  ",
+        OMCP_OIDC_CLIENT_ID: "",
+        OMCP_OIDC_REDIRECT_URI: "https://app.test/cb",
+    }));
+    assert.match(r.error ?? "", /OMCP_OIDC_ISSUER.*OMCP_OIDC_CLIENT_ID/);
+});
+test("resolveOidcConfig — parses OMCP_OIDC_ROLE_MAP JSON", () => {
+    const r = resolveOidcConfig(envOf({
+        OMCP_OIDC_ISSUER: "https://idp.test", OMCP_OIDC_CLIENT_ID: "c",
+        OMCP_OIDC_REDIRECT_URI: "https://app.test/cb",
+        OMCP_OIDC_ROLE_MAP: '{"omcp-admin":"admin","omcp-ops":"operator","omcp-viewers":"viewer"}',
+    }));
+    assert.deepEqual(r.config?.roleMap, { "omcp-admin": "admin", "omcp-ops": "operator", "omcp-viewers": "viewer" });
+});
+test("resolveOidcConfig — rejects malformed OMCP_OIDC_ROLE_MAP", () => {
+    const bad = resolveOidcConfig(envOf({
+        OMCP_OIDC_ISSUER: "https://idp.test", OMCP_OIDC_CLIENT_ID: "c",
+        OMCP_OIDC_REDIRECT_URI: "https://app.test/cb",
+        OMCP_OIDC_ROLE_MAP: "not json",
+    }));
+    assert.match(bad.error ?? "", /not valid JSON/);
+    const wrongType = resolveOidcConfig(envOf({
+        OMCP_OIDC_ISSUER: "https://idp.test", OMCP_OIDC_CLIENT_ID: "c",
+        OMCP_OIDC_REDIRECT_URI: "https://app.test/cb",
+        OMCP_OIDC_ROLE_MAP: '["arr"]',
+    }));
+    assert.match(wrongType.error ?? "", /JSON object/);
+    const wrongValue = resolveOidcConfig(envOf({
+        OMCP_OIDC_ISSUER: "https://idp.test", OMCP_OIDC_CLIENT_ID: "c",
+        OMCP_OIDC_REDIRECT_URI: "https://app.test/cb",
+        OMCP_OIDC_ROLE_MAP: '{"x": 1}',
+    }));
+    assert.match(wrongValue.error ?? "", /must be a string/);
+});
+test("resolveOidcConfig — propagates OMCP_OIDC_CLIENT_SECRET (confidential client)", () => {
+    const r = resolveOidcConfig(envOf({
+        OMCP_OIDC_ISSUER: "https://idp.test",
+        OMCP_OIDC_CLIENT_ID: "c-1",
+        OMCP_OIDC_CLIENT_SECRET: "confidential-shared-secret",
+        OMCP_OIDC_REDIRECT_URI: "https://app.test/cb",
+    }));
+    assert.equal(r.config?.clientSecret, "confidential-shared-secret");
+});
+test("resolveOidcConfig — honours OMCP_OIDC_SCOPES / ROLES_CLAIM / LOGOUT_REDIRECT", () => {
+    const r = resolveOidcConfig(envOf({
+        OMCP_OIDC_ISSUER: "https://idp.test", OMCP_OIDC_CLIENT_ID: "c",
+        OMCP_OIDC_REDIRECT_URI: "https://app.test/cb",
+        OMCP_OIDC_SCOPES: "openid email custom-scope",
+        OMCP_OIDC_ROLES_CLAIM: "realm_access.roles",
+        OMCP_OIDC_LOGOUT_REDIRECT: "https://app.test/bye",
+    }));
+    assert.equal(r.config?.scopes, "openid email custom-scope");
+    assert.equal(r.config?.rolesClaim, "realm_access.roles");
+    assert.equal(r.config?.logoutRedirect, "https://app.test/bye");
+});
+test("buildOidcRuntime.resolveRoles — flat groups claim with array value", () => {
+    const r = resolveOidcConfig(envOf({
+        OMCP_OIDC_ISSUER: "https://idp.test", OMCP_OIDC_CLIENT_ID: "c",
+        OMCP_OIDC_REDIRECT_URI: "https://app.test/cb",
+        OMCP_OIDC_ROLE_MAP: '{"omcp-admin":"admin","omcp-ops":"operator","other":"viewer"}',
+    }));
+    const rt = buildOidcRuntime(r.config);
+    assert.deepEqual(rt.resolveRoles({ groups: ["omcp-admin", "unknown", "omcp-ops"] }).sort(), ["admin", "operator"]);
+});
+test("buildOidcRuntime.resolveRoles — dotted claim path (Keycloak realm_access.roles shape)", () => {
+    const r = resolveOidcConfig(envOf({
+        OMCP_OIDC_ISSUER: "https://idp.test", OMCP_OIDC_CLIENT_ID: "c",
+        OMCP_OIDC_REDIRECT_URI: "https://app.test/cb",
+        OMCP_OIDC_ROLES_CLAIM: "realm_access.roles",
+        OMCP_OIDC_ROLE_MAP: '{"omcp-admin":"admin"}',
+    }));
+    const rt = buildOidcRuntime(r.config);
+    assert.deepEqual(rt.resolveRoles({ realm_access: { roles: ["omcp-admin"] } }), ["admin"]);
+});
+test("buildOidcRuntime.resolveRoles — scalar string claim value still maps", () => {
+    const r = resolveOidcConfig(envOf({
+        OMCP_OIDC_ISSUER: "https://idp.test", OMCP_OIDC_CLIENT_ID: "c",
+        OMCP_OIDC_REDIRECT_URI: "https://app.test/cb",
+        OMCP_OIDC_ROLES_CLAIM: "role",
+        OMCP_OIDC_ROLE_MAP: '{"sso-admin":"admin"}',
+    }));
+    const rt = buildOidcRuntime(r.config);
+    assert.deepEqual(rt.resolveRoles({ role: "sso-admin" }), ["admin"]);
+});
+test("buildOidcRuntime.resolveRoles — missing claim path yields empty roles (least privilege)", () => {
+    const r = resolveOidcConfig(envOf({
+        OMCP_OIDC_ISSUER: "https://idp.test", OMCP_OIDC_CLIENT_ID: "c",
+        OMCP_OIDC_REDIRECT_URI: "https://app.test/cb",
+        OMCP_OIDC_ROLE_MAP: '{"x":"admin"}',
+    }));
+    const rt = buildOidcRuntime(r.config);
+    assert.deepEqual(rt.resolveRoles({ sub: "alice" }), []);
+});
+test("buildOidcRuntime.resolveRoles — deduplicates when multiple claim values map to same role", () => {
+    const r = resolveOidcConfig(envOf({
+        OMCP_OIDC_ISSUER: "https://idp.test", OMCP_OIDC_CLIENT_ID: "c",
+        OMCP_OIDC_REDIRECT_URI: "https://app.test/cb",
+        OMCP_OIDC_ROLE_MAP: '{"a":"admin","b":"admin"}',
+    }));
+    const rt = buildOidcRuntime(r.config);
+    assert.deepEqual(rt.resolveRoles({ groups: ["a", "b"] }), ["admin"]);
+});

package/dist/auth/policy/batch-dry-run.d.ts

@@ -0,0 +1,56 @@
+import type { PolicyEngine } from "./engine.js";
+export interface BatchSubject {
+    /** Human-readable identifier echoed in the response (UI heat-map
+     *  row label). Usually `<name>@<tenant>` or a group name. */
+    key: string;
+    /** Roles the subject would have at evaluation time. */
+    roles: string[];
+    /** Tenant the subject is acting under. Optional; defaults to the
+     *  caller's session tenant at the handler level. */
+    tenant?: string;
+}
+export interface BatchDryRunRequest {
+    subjects: BatchSubject[];
+    /** Resources to probe — should match VALID_RESOURCES on the
+     *  active engine. Unknown resources are dropped with a note. */
+    resources: string[];
+    /** Actions to probe — should match VALID_ACTIONS. */
+    actions: string[];
+}
+export interface BatchCellVerdict {
+    allowed: boolean;
+    reason?: string;
+}
+export interface BatchDryRunResult {
+    /** result[subjectKey][resource][action] = { allowed, reason } */
+    matrix: Record<string, Record<string, Record<string, BatchCellVerdict>>>;
+    /** Anything the handler skipped: bad resource, bad action, too
+     *  many cells, etc. Helps the operator fix the next batch quickly. */
+    dropped: Array<{
+        kind: "resource" | "action" | "subject" | "cap";
+        value: string;
+        reason: string;
+    }>;
+    /** Summary counts to power the UI's headline stats. */
+    totals: {
+        cells: number;
+        allow: number;
+        deny: number;
+    };
+}
+export interface BatchLimits {
+    maxSubjects: number;
+    maxResources: number;
+    maxActions: number;
+}
+export declare const DEFAULT_BATCH_LIMITS: BatchLimits;
+/**
+ * Run a batch dry-run against the policy engine. The engine is
+ * called once per cell — for the BuiltinPolicyEngine this is pure
+ * compute and cheap; for the OPA engine it's one Rego query per
+ * cell. The handler caps the matrix so a careless caller can't DoS
+ * an external OPA.
+ */
+export declare function evaluateBatch(engine: PolicyEngine, req: BatchDryRunRequest, validResources: ReadonlySet<string>, validActions: ReadonlySet<string>, limits?: BatchLimits): Promise<BatchDryRunResult>;
+/** Turn a batch result into CSV — `subject,resource,action,allowed,reason`. */
+export declare function batchResultToCsv(result: BatchDryRunResult): string;

package/dist/auth/policy/batch-dry-run.js

@@ -0,0 +1,129 @@
+// Batch policy dry-run — Phase F16.
+//
+// The existing single-call dry-run probe (`GET /api/policy?roles=…
+// &resource=…&action=…`) is great for "why did this one call fail"
+// but doesn't scale to a security-review session reviewing a
+// proposed role change. F16 adds a batch variant that evaluates
+// every (subject × resource × action) combination in one pass and
+// returns a matrix the UI can render as a heat-map.
+//
+// The handler stays out of the route file — pure compute is easier
+// to unit-test and easier to reuse from a CI policy-diff job later.
+export const DEFAULT_BATCH_LIMITS = {
+    maxSubjects: 100,
+    maxResources: 100,
+    maxActions: 10,
+};
+/**
+ * Run a batch dry-run against the policy engine. The engine is
+ * called once per cell — for the BuiltinPolicyEngine this is pure
+ * compute and cheap; for the OPA engine it's one Rego query per
+ * cell. The handler caps the matrix so a careless caller can't DoS
+ * an external OPA.
+ */
+export async function evaluateBatch(engine, req, validResources, validActions, limits = DEFAULT_BATCH_LIMITS) {
+    const dropped = [];
+    // De-duplicate inputs; preserve first-seen order.
+    const seenSubjectKeys = new Set();
+    const subjects = [];
+    for (const s of req.subjects ?? []) {
+        if (!s || typeof s.key !== "string" || !Array.isArray(s.roles)) {
+            dropped.push({ kind: "subject", value: String(s?.key ?? "<malformed>"), reason: "missing key or roles[]" });
+            continue;
+        }
+        if (seenSubjectKeys.has(s.key))
+            continue;
+        seenSubjectKeys.add(s.key);
+        subjects.push(s);
+    }
+    const resources = unique(req.resources ?? []).filter((r) => {
+        if (!validResources.has(r)) {
+            dropped.push({ kind: "resource", value: r, reason: "not in active engine's VALID_RESOURCES" });
+            return false;
+        }
+        return true;
+    });
+    const actions = unique(req.actions ?? []).filter((a) => {
+        if (!validActions.has(a)) {
+            dropped.push({ kind: "action", value: a, reason: "not in active engine's VALID_ACTIONS" });
+            return false;
+        }
+        return true;
+    });
+    // Cap enforcement — favour clear-cap-error over partial silent results.
+    if (subjects.length > limits.maxSubjects) {
+        dropped.push({ kind: "cap", value: `subjects=${subjects.length}`, reason: `truncated to ${limits.maxSubjects} (cap)` });
+        subjects.length = limits.maxSubjects;
+    }
+    if (resources.length > limits.maxResources) {
+        dropped.push({ kind: "cap", value: `resources=${resources.length}`, reason: `truncated to ${limits.maxResources} (cap)` });
+        resources.length = limits.maxResources;
+    }
+    if (actions.length > limits.maxActions) {
+        dropped.push({ kind: "cap", value: `actions=${actions.length}`, reason: `truncated to ${limits.maxActions} (cap)` });
+        actions.length = limits.maxActions;
+    }
+    const matrix = {};
+    let allowCount = 0;
+    let denyCount = 0;
+    for (const s of subjects) {
+        matrix[s.key] = {};
+        for (const r of resources) {
+            matrix[s.key][r] = {};
+            for (const a of actions) {
+                const verdict = await Promise.resolve(engine.evaluate(s.roles, r, a, s.tenant ? { tenant: s.tenant } : undefined));
+                matrix[s.key][r][a] = {
+                    allowed: verdict.allowed,
+                    reason: verdict.reason,
+                };
+                if (verdict.allowed)
+                    allowCount += 1;
+                else
+                    denyCount += 1;
+            }
+        }
+    }
+    return {
+        matrix,
+        dropped,
+        totals: {
+            cells: subjects.length * resources.length * actions.length,
+            allow: allowCount,
+            deny: denyCount,
+        },
+    };
+}
+function unique(xs) {
+    const seen = new Set();
+    const out = [];
+    for (const x of xs) {
+        if (seen.has(x))
+            continue;
+        seen.add(x);
+        out.push(x);
+    }
+    return out;
+}
+/** Turn a batch result into CSV — `subject,resource,action,allowed,reason`. */
+export function batchResultToCsv(result) {
+    const lines = ["subject,resource,action,allowed,reason"];
+    for (const [subject, perResource] of Object.entries(result.matrix)) {
+        for (const [resource, perAction] of Object.entries(perResource)) {
+            for (const [action, verdict] of Object.entries(perAction)) {
+                lines.push([
+                    csvEscape(subject),
+                    csvEscape(resource),
+                    csvEscape(action),
+                    verdict.allowed ? "allow" : "deny",
+                    csvEscape(verdict.reason ?? ""),
+                ].join(","));
+            }
+        }
+    }
+    return lines.join("\n");
+}
+function csvEscape(v) {
+    if (/[",\n\r]/.test(v))
+        return `"${v.replace(/"/g, '""')}"`;
+    return v;
+}

package/dist/auth/policy/batch-dry-run.test.d.ts

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