@thotischner/observability-mcp 1.8.1 → 3.0.1

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,144 @@
+// 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;
+    }
+    // Reject keys that could mutate Object.prototype if injected from
+    // user input — `__proto__`, `constructor`, `prototype`. CodeQL
+    // js/prototype-polluting-assignment + js/remote-property-injection.
+    const DANGEROUS = new Set(["__proto__", "constructor", "prototype"]);
+    const isSafeKey = (k) => !DANGEROUS.has(k);
+    // Plain object so JSON round-trip + deep-equal in tests keeps
+    // working; the DANGEROUS guard below is the actual protection.
+    const matrix = {};
+    let allowCount = 0;
+    let denyCount = 0;
+    for (const s of subjects) {
+        if (!isSafeKey(s.key)) {
+            dropped.push({ kind: "subject", value: s.key, reason: "reserved key name" });
+            continue;
+        }
+        matrix[s.key] = {};
+        for (const r of resources) {
+            if (!isSafeKey(String(r)))
+                continue;
+            matrix[s.key][r] = {};
+            for (const a of actions) {
+                if (!isSafeKey(String(a)))
+                    continue;
+                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>;

package/dist/auth/policy/loader.js

@@ -27,6 +27,7 @@ import { BuiltinPolicyEngine } from "./engine.js";
 export const VALID_RESOURCES = new Set([
     "sources", "services", "health", "topology", "settings",
     "connectors", "audit", "catalog", "users", "redaction",
+    "products",
 ]);
 export const VALID_ACTIONS = new Set(["read", "write", "delete", "bypass"]);
 export class PolicyLoadError extends Error {
@@ -98,3 +99,39 @@ export function loadPolicyFromFile(path) {
     }
     return loadPolicyFromString(text, `file:${path}`);
 }
+/** 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 function serializePolicy(policy) {
+    // Lock in the field order so a round-trip-through-this-function
+    // is stable diffs in a version-controlled file. Roles sorted
+    // alphabetically; grants sorted by (resource, action) inside
+    // each role.
+    const rolesOut = {};
+    for (const role of Object.keys(policy).sort()) {
+        const grants = policy[role] || [];
+        const sorted = grants
+            .slice()
+            .sort((a, b) => (a.resource + ":" + a.action).localeCompare(b.resource + ":" + b.action))
+            .map((g) => ({ resource: g.resource, action: g.action }));
+        rolesOut[role] = sorted;
+    }
+    return yaml.dump({ roles: rolesOut }, { sortKeys: false, lineWidth: 100 });
+}
+/** 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 async function writePolicyFile(path, policy) {
+    // Validate via the parse path before writing — a bad input
+    // shape would otherwise produce a file the boot loader then
+    // rejects (fail-closed reboot). Validate-then-write keeps the
+    // good-policy invariant.
+    loadPolicyFromString(serializePolicy(policy), "(in-memory)");
+    const { writeFile, rename } = await import("node:fs/promises");
+    const text = serializePolicy(policy);
+    const tmp = path + ".tmp";
+    await writeFile(tmp, text, { encoding: "utf8", mode: 0o600 });
+    await rename(tmp, path);
+}

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

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

package/dist/auth/policy/loader.test.js

@@ -0,0 +1,86 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { writePolicyFile, loadPolicyFromFile, loadPolicyFromString, serializePolicy, VALID_RESOURCES } from "./loader.js";
+import { BuiltinPolicyEngine } from "./engine.js";
+test("VALID_RESOURCES — includes products (closes a pre-existing inconsistency vs rbac.ts)", () => {
+    assert.ok(VALID_RESOURCES.has("products"), "products must be a recognised resource for file-loaded policies");
+});
+test("serializePolicy — round-trips through the parser cleanly", () => {
+    const text = serializePolicy({
+        admin: [
+            { resource: "sources", action: "delete" },
+            { resource: "users", action: "delete" },
+        ],
+        viewer: [{ resource: "sources", action: "read" }],
+    });
+    // Parsing the serialised text via loadPolicyFromString must yield
+    // an engine with the same role grants — round-trip is stable.
+    const e = loadPolicyFromString(text, "test");
+    assert.deepEqual(e.roles().sort(), ["admin", "viewer"]);
+    const admin = e.list(["admin"]).map((p) => p.resource + ":" + p.action).sort();
+    assert.deepEqual(admin, ["sources:delete", "users:delete"]);
+});
+test("serializePolicy — deterministic ordering (roles + grants both sorted)", () => {
+    const a = serializePolicy({
+        z: [{ resource: "sources", action: "write" }, { resource: "audit", action: "read" }],
+        a: [{ resource: "users", action: "read" }],
+    });
+    const b = serializePolicy({
+        a: [{ resource: "users", action: "read" }],
+        z: [{ resource: "audit", action: "read" }, { resource: "sources", action: "write" }],
+    });
+    // Same logical policy → byte-identical text. Important for git-diff sanity.
+    assert.equal(a, b);
+});
+test("writePolicyFile — atomic round-trip preserves shape", async () => {
+    const { mkdtemp, rm } = await import("node:fs/promises");
+    const { tmpdir } = await import("node:os");
+    const { join } = await import("node:path");
+    const dir = await mkdtemp(join(tmpdir(), "omcp-policy-"));
+    try {
+        const path = join(dir, "policy.yaml");
+        await writePolicyFile(path, {
+            admin: [{ resource: "sources", action: "delete" }],
+            operator: [{ resource: "sources", action: "write" }],
+        });
+        const engine = loadPolicyFromFile(path);
+        assert.deepEqual(engine.roles().sort(), ["admin", "operator"]);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});
+test("writePolicyFile — rejects an invalid resource before writing the file", async () => {
+    const { mkdtemp, rm, readdir } = await import("node:fs/promises");
+    const { tmpdir } = await import("node:os");
+    const { join } = await import("node:path");
+    const dir = await mkdtemp(join(tmpdir(), "omcp-policy-reject-"));
+    try {
+        const path = join(dir, "policy.yaml");
+        await assert.rejects(writePolicyFile(path, {
+            admin: [{ resource: "nope", action: "read" }],
+        }), /unknown/i);
+        // No file (or tmp) was created — validate-then-write held.
+        const entries = await readdir(dir);
+        assert.deepEqual(entries, []);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});
+test("BuiltinPolicyEngine.replace — mutates the inner map in place (gate closures see the new policy)", () => {
+    const engine = new BuiltinPolicyEngine({
+        admin: [{ resource: "sources", action: "delete" }],
+    });
+    // Capture a reference to the raw map BEFORE replace — verify the
+    // reference is preserved (hot-swap, not reassign).
+    const before = engine.raw();
+    engine.replace({
+        admin: [{ resource: "sources", action: "delete" }, { resource: "audit", action: "read" }],
+        viewer: [{ resource: "sources", action: "read" }],
+    });
+    assert.equal(before, engine.raw(), "raw() must return the same object reference after replace()");
+    assert.deepEqual(engine.roles().sort(), ["admin", "viewer"]);
+    assert.equal(engine.evaluate(["admin"], "audit", "read").allowed, true);
+    assert.equal(engine.evaluate(["viewer"], "sources", "read").allowed, true);
+});

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

@@ -27,7 +27,7 @@
  * for auth/oidc/, and OPA traffic stays inside the cluster).
  */
 import type { Permission, Resource, Action } from "../rbac.js";
-import type { PolicyEngine, EvalResult } from "./engine.js";
+import type { PolicyEngine, EvalResult, EvalContext } from "./engine.js";
 export type Fetcher = (url: string, init?: RequestInit) => Promise<Response>;
 export interface OpaConfig {
     /** Base URL, e.g. http://opa:8181 (no trailing slash). */
@@ -57,13 +57,13 @@ export declare class OpaPolicyEngine implements PolicyEngine {
     private cacheKey;
     private now;
     private query;
-    evaluate(roles: string[] | undefined, resource: Resource, action: Action): EvalResult;
+    evaluate(roles: string[] | undefined, resource: Resource, action: Action, ctx?: EvalContext): EvalResult;
     /** Async warm of the evaluate cache. Public so a long-running
      *  caller can `await engine.warmEvaluate(...)` before the gate
      *  check if it cannot tolerate the warming-deny window. */
-    warmEvaluate(roles: string[], resource: string, action: string): Promise<EvalResult>;
-    list(roles: string[] | undefined): Permission[];
-    warmList(roles: string[]): Promise<Permission[]>;
+    warmEvaluate(roles: string[], resource: string, action: string, tenant?: string): Promise<EvalResult>;
+    list(roles: string[] | undefined, ctx?: EvalContext): Permission[];
+    warmList(roles: string[], tenant?: string): Promise<Permission[]>;
     roles(): string[];
     kind(): string;
 }