@thotischner/observability-mcp 1.8.1 → 3.0.0

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", () => {

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

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

@@ -0,0 +1,140 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { evaluateBatch, batchResultToCsv, DEFAULT_BATCH_LIMITS, } from "./batch-dry-run.js";
+class FakeEngine {
+    // Allow when the roles array contains "admin", or
+    // when ((resource, action) is (sources, read) for any role).
+    evaluate(roles, resource, action) {
+        if (roles?.includes("admin"))
+            return { allowed: true, reason: "admin role" };
+        if (resource === "sources" && action === "read")
+            return { allowed: true, reason: "public read" };
+        return { allowed: false, reason: `denied: roles=${(roles ?? []).join(",")} can't ${action} on ${resource}` };
+    }
+    list() {
+        return []; // not exercised by these tests
+    }
+    roles() {
+        return ["admin", "viewer"];
+    }
+    kind() {
+        return "fake";
+    }
+}
+const VALID_RES = new Set(["sources", "services", "settings"]);
+const VALID_ACT = new Set(["read", "write", "delete"]);
+function req(overrides = {}) {
+    return {
+        subjects: [{ key: "alice", roles: ["viewer"] }],
+        resources: ["sources"],
+        actions: ["read"],
+        ...overrides,
+    };
+}
+test("evaluateBatch: empty request → empty matrix + zero totals", async () => {
+    const r = await evaluateBatch(new FakeEngine(), { subjects: [], resources: [], actions: [] }, VALID_RES, VALID_ACT);
+    assert.deepEqual(r.matrix, {});
+    assert.deepEqual(r.totals, { cells: 0, allow: 0, deny: 0 });
+    assert.deepEqual(r.dropped, []);
+});
+test("evaluateBatch: 1×1×1 returns one verdict cell", async () => {
+    const r = await evaluateBatch(new FakeEngine(), req(), VALID_RES, VALID_ACT);
+    assert.equal(r.matrix.alice.sources.read.allowed, true);
+    assert.equal(r.matrix.alice.sources.read.reason, "public read");
+    assert.equal(r.totals.cells, 1);
+    assert.equal(r.totals.allow, 1);
+    assert.equal(r.totals.deny, 0);
+});
+test("evaluateBatch: full 2×2×2 matrix populated end-to-end", async () => {
+    const r = await evaluateBatch(new FakeEngine(), {
+        subjects: [
+            { key: "alice", roles: ["viewer"] },
+            { key: "bob", roles: ["admin"] },
+        ],
+        resources: ["sources", "services"],
+        actions: ["read", "delete"],
+    }, VALID_RES, VALID_ACT);
+    assert.equal(r.totals.cells, 8);
+    assert.equal(r.matrix.alice.sources.read.allowed, true); // public read
+    assert.equal(r.matrix.alice.services.read.allowed, false); // viewer can't read services
+    assert.equal(r.matrix.bob.services.delete.allowed, true); // admin
+});
+test("evaluateBatch: unknown resource → dropped + matrix omits it", async () => {
+    const r = await evaluateBatch(new FakeEngine(), req({ resources: ["sources", "totally-bogus"] }), VALID_RES, VALID_ACT);
+    assert.equal(r.dropped.length, 1);
+    assert.equal(r.dropped[0].kind, "resource");
+    assert.equal(r.dropped[0].value, "totally-bogus");
+    // Matrix has only the surviving resource
+    assert.deepEqual(Object.keys(r.matrix.alice), ["sources"]);
+});
+test("evaluateBatch: unknown action → dropped", async () => {
+    const r = await evaluateBatch(new FakeEngine(), req({ actions: ["read", "blow-up"] }), VALID_RES, VALID_ACT);
+    assert.equal(r.dropped.some((d) => d.kind === "action" && d.value === "blow-up"), true);
+});
+test("evaluateBatch: deduplicates repeated inputs", async () => {
+    const r = await evaluateBatch(new FakeEngine(), {
+        subjects: [
+            { key: "alice", roles: ["viewer"] },
+            { key: "alice", roles: ["admin"] }, // dropped because key already seen
+        ],
+        resources: ["sources", "sources", "services"],
+        actions: ["read", "read", "delete"],
+    }, VALID_RES, VALID_ACT);
+    // alice runs once, with the first-seen roles array (viewer); 1 subject × 2 resources × 2 actions = 4 cells.
+    assert.equal(Object.keys(r.matrix).length, 1);
+    assert.equal(r.totals.cells, 4);
+});
+test("evaluateBatch: malformed subject (missing roles) dropped with note", async () => {
+    const r = await evaluateBatch(new FakeEngine(), {
+        subjects: [
+            { key: "alice", roles: ["viewer"] },
+            { key: "broken" },
+        ],
+        resources: ["sources"],
+        actions: ["read"],
+    }, VALID_RES, VALID_ACT);
+    assert.equal(Object.keys(r.matrix).length, 1);
+    assert.ok(r.dropped.some((d) => d.kind === "subject" && d.value === "broken"));
+});
+test("evaluateBatch: cap enforcement truncates oversize lists, notes in dropped", async () => {
+    const subjects = Array.from({ length: 5 }, (_, i) => ({ key: `s${i}`, roles: ["viewer"] }));
+    const resources = Array.from({ length: 3 }, (_, i) => `sources`); // dedup → 1
+    const r = await evaluateBatch(new FakeEngine(), { subjects, resources, actions: ["read"] }, VALID_RES, VALID_ACT, { maxSubjects: 2, maxResources: 5, maxActions: 5 });
+    // truncated to 2 subjects × 1 resource × 1 action
+    assert.equal(r.totals.cells, 2);
+    assert.ok(r.dropped.some((d) => d.kind === "cap" && d.value.startsWith("subjects=")));
+});
+test("evaluateBatch: per-subject tenant is threaded into engine.evaluate", async () => {
+    let lastTenant;
+    class TenantTracker {
+        evaluate(_roles, _r, _a, ctx) {
+            lastTenant = ctx?.tenant;
+            return { allowed: true };
+        }
+        list() { return []; }
+        roles() { return []; }
+        kind() { return "tracker"; }
+    }
+    await evaluateBatch(new TenantTracker(), {
+        subjects: [{ key: "alice", roles: ["viewer"], tenant: "acme" }],
+        resources: ["sources"],
+        actions: ["read"],
+    }, VALID_RES, VALID_ACT);
+    assert.equal(lastTenant, "acme");
+});
+test("batchResultToCsv: produces the documented header + escapes commas and quotes", async () => {
+    const r = await evaluateBatch(new FakeEngine(), {
+        subjects: [{ key: 'alice,senior "lead"', roles: ["viewer"] }],
+        resources: ["sources"],
+        actions: ["read"],
+    }, VALID_RES, VALID_ACT);
+    const csv = batchResultToCsv(r);
+    assert.match(csv.split("\n")[0], /^subject,resource,action,allowed,reason$/);
+    // Quoted because of comma + embedded quotes doubled
+    assert.match(csv, /"alice,senior ""lead"""/);
+});
+test("DEFAULT_BATCH_LIMITS matches the documented 100×100×10 cap", () => {
+    assert.equal(DEFAULT_BATCH_LIMITS.maxSubjects, 100);
+    assert.equal(DEFAULT_BATCH_LIMITS.maxResources, 100);
+    assert.equal(DEFAULT_BATCH_LIMITS.maxActions, 10);
+});

package/dist/auth/policy/engine.d.ts

@@ -23,11 +23,20 @@ export interface EvalResult {
     /** Optional human-readable explanation (for /api/policy?dry-run). */
     reason?: string;
 }
+/** Optional context the gate can pass when it has more identity
+ *  info than just the role set — e.g. the active tenant. Engines
+ *  that consult external policy (OPA) thread this into the Rego
+ *  input so tenant-conditional rules can fire. Built-in engines
+ *  ignore it. Adding fields here is additive: future-engine code
+ *  reads what it needs, callers populate what they have. */
+export interface EvalContext {
+    tenant?: string;
+}
 export interface PolicyEngine {
     /** One-shot evaluation: does this role-set grant the permission? */
-    evaluate(roles: string[] | undefined, resource: Resource, action: Action): EvalResult;
+    evaluate(roles: string[] | undefined, resource: Resource, action: Action, ctx?: EvalContext): EvalResult;
     /** Enumerate every (resource, action) the role-set grants. */
-    list(roles: string[] | undefined): Permission[];
+    list(roles: string[] | undefined, ctx?: EvalContext): Permission[];
     /** Surface the active role catalogue (for UI tabs / docs). */
     roles(): string[];
     /** Short identifier for logging / /api/info — "builtin", "file:…",
@@ -39,10 +48,17 @@ export declare class BuiltinPolicyEngine implements PolicyEngine {
     private readonly policy;
     private readonly origin;
     constructor(policy: Record<string, Permission[]>, origin?: string);
-    evaluate(roles: string[] | undefined, resource: Resource, action: Action): EvalResult;
-    list(roles: string[] | undefined): Permission[];
+    evaluate(roles: string[] | undefined, resource: Resource, action: Action, _ctx?: EvalContext): EvalResult;
+    list(roles: string[] | undefined, _ctx?: EvalContext): Permission[];
     roles(): string[];
     kind(): string;
     /** Expose the underlying policy for /api/policy reflection. */
     raw(): Record<string, Permission[]>;
+    /** Hot-swap the policy in place. Existing gate middleware closed
+     *  over THIS engine instance will see the new map on the next
+     *  evaluate() call — no restart required. The `readonly` modifier
+     *  on `policy` only forbids reassignment of the field (TS); the
+     *  underlying object reference stays the same, so we clear-and-
+     *  refill instead of replacing it. */
+    replace(policy: Record<string, Permission[]>): void;
 }

package/dist/auth/policy/engine.js

@@ -25,7 +25,8 @@ export class BuiltinPolicyEngine {
         this.policy = policy;
         this.origin = origin;
     }
-    evaluate(roles, resource, action) {
+    evaluate(roles, resource, action, _ctx) {
+        void _ctx; // builtin engine has no tenant-conditional rules
         if (!roles || roles.length === 0) {
             return { allowed: false, reason: "no roles on principal" };
         }
@@ -41,7 +42,8 @@ export class BuiltinPolicyEngine {
         }
         return { allowed: false, reason: `roles [${roles.join(",")}] do not grant ${resource}:${action}` };
     }
-    list(roles) {
+    list(roles, _ctx) {
+        void _ctx;
         if (!roles || roles.length === 0)
             return [];
         const seen = new Set();
@@ -70,4 +72,16 @@ export class BuiltinPolicyEngine {
     raw() {
         return this.policy;
     }
+    /** Hot-swap the policy in place. Existing gate middleware closed
+     *  over THIS engine instance will see the new map on the next
+     *  evaluate() call — no restart required. The `readonly` modifier
+     *  on `policy` only forbids reassignment of the field (TS); the
+     *  underlying object reference stays the same, so we clear-and-
+     *  refill instead of replacing it. */
+    replace(policy) {
+        for (const k of Object.keys(this.policy))
+            delete this.policy[k];
+        for (const [k, v] of Object.entries(policy))
+            this.policy[k] = v;
+    }
 }

package/dist/auth/policy/loader.d.ts

@@ -21,7 +21,7 @@
  * `admin` REPLACES the built-in `admin`. Inheritance / patching is
  * an operator-side concern (anchor / merge in YAML, jq filters, etc.).
  */
-import type { Resource, Action } from "../rbac.js";
+import type { Permission, Resource, Action } from "../rbac.js";
 import { type PolicyEngine } from "./engine.js";
 export declare const VALID_RESOURCES: ReadonlySet<Resource>;
 export declare const VALID_ACTIONS: ReadonlySet<Action>;
@@ -33,3 +33,13 @@ export declare function loadPolicyFromString(text: string, origin: string): Poli
 /** Read a file (utf-8) and load it as a policy. Lets operators
  *  surface the on-disk path in error messages. */
 export declare function loadPolicyFromFile(path: string): PolicyEngine;
+/** Render a policy map into the YAML/JSON shape the loader reads.
+ *  Pure helper — separated from the file-write step so a future
+ *  PolicyEngine implementation that doesn't speak the file format
+ *  can compose differently. */
+export declare function serializePolicy(policy: Record<string, Permission[]>): string;
+/** Atomic write of the policy file. Same tmp+rename pattern used by
+ *  products + users — a crash mid-write leaves the previous file
+ *  intact. mode 0o600 so the on-disk RBAC catalogue isn't
+ *  world-readable on multi-tenant hosts. */
+export declare function writePolicyFile(path: string, policy: Record<string, Permission[]>): Promise<void>;