@thotischner/observability-mcp 1.7.1 → 3.0.0

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

@@ -0,0 +1,64 @@
+/**
+ * Policy-engine abstraction.
+ *
+ * Today the management-plane RBAC checks call `hasPermission()` /
+ * `listGrantedPermissions()` which read the built-in DEFAULT_POLICY
+ * map. That's fine for the single-deployment case, but the plan
+ * (E5) wires in:
+ *
+ *   - File-loaded custom policies (slice 2, this module)
+ *   - External OPA via HTTP eval (slice 4)
+ *
+ * Both surfaces share the same shape: given (role, resource, action),
+ * answer allowed / not allowed; and given a role, enumerate every
+ * granted (resource, action) pair for UI display.
+ *
+ * This interface is deliberately narrow so a future Rego engine, a
+ * remote OPA call, or any operator-supplied evaluator drops in
+ * without touching the call sites.
+ */
+import type { Permission, Resource, Action } from "../rbac.js";
+export interface EvalResult {
+    allowed: boolean;
+    /** 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, ctx?: EvalContext): EvalResult;
+    /** Enumerate every (resource, action) the role-set grants. */
+    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:…",
+     *  "opa:…". */
+    kind(): string;
+}
+/** Built-in engine — wraps a plain {role: Permission[]} map. */
+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, _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

@@ -0,0 +1,87 @@
+/**
+ * Policy-engine abstraction.
+ *
+ * Today the management-plane RBAC checks call `hasPermission()` /
+ * `listGrantedPermissions()` which read the built-in DEFAULT_POLICY
+ * map. That's fine for the single-deployment case, but the plan
+ * (E5) wires in:
+ *
+ *   - File-loaded custom policies (slice 2, this module)
+ *   - External OPA via HTTP eval (slice 4)
+ *
+ * Both surfaces share the same shape: given (role, resource, action),
+ * answer allowed / not allowed; and given a role, enumerate every
+ * granted (resource, action) pair for UI display.
+ *
+ * This interface is deliberately narrow so a future Rego engine, a
+ * remote OPA call, or any operator-supplied evaluator drops in
+ * without touching the call sites.
+ */
+/** Built-in engine — wraps a plain {role: Permission[]} map. */
+export class BuiltinPolicyEngine {
+    policy;
+    origin;
+    constructor(policy, origin = "builtin") {
+        this.policy = policy;
+        this.origin = origin;
+    }
+    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" };
+        }
+        for (const r of roles) {
+            const grants = this.policy[r];
+            if (!grants)
+                continue;
+            for (const g of grants) {
+                if (g.resource === resource && g.action === action) {
+                    return { allowed: true, reason: `granted by role ${r}` };
+                }
+            }
+        }
+        return { allowed: false, reason: `roles [${roles.join(",")}] do not grant ${resource}:${action}` };
+    }
+    list(roles, _ctx) {
+        void _ctx;
+        if (!roles || roles.length === 0)
+            return [];
+        const seen = new Set();
+        const out = [];
+        for (const r of roles) {
+            const grants = this.policy[r];
+            if (!grants)
+                continue;
+            for (const g of grants) {
+                const key = g.resource + ":" + g.action;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                out.push(g);
+            }
+        }
+        return out;
+    }
+    roles() {
+        return Object.keys(this.policy);
+    }
+    kind() {
+        return this.origin;
+    }
+    /** Expose the underlying policy for /api/policy reflection. */
+    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/engine.test.d.ts

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

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

@@ -0,0 +1,98 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { BuiltinPolicyEngine } from "./engine.js";
+import { DEFAULT_POLICY } from "../rbac.js";
+import { loadPolicyFromString, PolicyLoadError } from "./loader.js";
+test("BuiltinPolicyEngine — evaluate returns allowed for granted perm", () => {
+    const e = new BuiltinPolicyEngine(DEFAULT_POLICY);
+    const r = e.evaluate(["viewer"], "sources", "read");
+    assert.equal(r.allowed, true);
+    assert.match(r.reason, /granted by role viewer/);
+});
+test("BuiltinPolicyEngine — evaluate returns denied with role context", () => {
+    const e = new BuiltinPolicyEngine(DEFAULT_POLICY);
+    const r = e.evaluate(["viewer"], "sources", "write");
+    assert.equal(r.allowed, false);
+    assert.match(r.reason, /viewer.*do not grant sources:write/);
+});
+test("BuiltinPolicyEngine — evaluate denies when roles missing / empty", () => {
+    const e = new BuiltinPolicyEngine(DEFAULT_POLICY);
+    assert.equal(e.evaluate(undefined, "sources", "read").allowed, false);
+    assert.equal(e.evaluate([], "sources", "read").allowed, false);
+});
+test("BuiltinPolicyEngine — list dedupes across overlapping roles", () => {
+    const e = new BuiltinPolicyEngine(DEFAULT_POLICY);
+    const both = e.list(["viewer", "operator"]);
+    // operator inherits viewer's reads; the union shouldn't contain dupes
+    const keys = new Set(both.map((p) => p.resource + ":" + p.action));
+    assert.equal(keys.size, both.length);
+});
+test("BuiltinPolicyEngine.roles / kind", () => {
+    const e = new BuiltinPolicyEngine(DEFAULT_POLICY);
+    assert.deepEqual(e.roles().sort(), ["admin", "operator", "viewer"]);
+    assert.equal(e.kind(), "builtin");
+});
+test("loadPolicyFromString — happy path YAML", () => {
+    const yamlText = `
+roles:
+  viewer:
+    - { resource: sources, action: read }
+    - { resource: services, action: read }
+  custom-bot:
+    - { resource: redaction, action: bypass }
+`;
+    const e = loadPolicyFromString(yamlText, "test");
+    assert.equal(e.kind(), "test");
+    assert.equal(e.evaluate(["viewer"], "sources", "read").allowed, true);
+    assert.equal(e.evaluate(["custom-bot"], "redaction", "bypass").allowed, true);
+    assert.equal(e.evaluate(["viewer"], "redaction", "bypass").allowed, false);
+});
+test("loadPolicyFromString — rejects unknown resource", () => {
+    const yamlText = `
+roles:
+  viewer:
+    - { resource: sourcez, action: read }
+`;
+    assert.throws(() => loadPolicyFromString(yamlText, "t"), /resource 'sourcez' unknown/);
+});
+test("loadPolicyFromString — rejects unknown action", () => {
+    const yamlText = `
+roles:
+  viewer:
+    - { resource: sources, action: peek }
+`;
+    assert.throws(() => loadPolicyFromString(yamlText, "t"), /action 'peek' unknown/);
+});
+test("loadPolicyFromString — rejects unexpected key (typo guard)", () => {
+    const yamlText = `
+roles:
+  viewer:
+    - { tesource: sources, action: read }
+`;
+    assert.throws(() => loadPolicyFromString(yamlText, "t"), /unexpected key 'tesource'/);
+});
+test("loadPolicyFromString — rejects non-object root / missing roles", () => {
+    assert.throws(() => loadPolicyFromString("[1,2,3]", "t"), /expected an object/);
+    assert.throws(() => loadPolicyFromString("foo: bar", "t"), /missing or non-object 'roles'/);
+});
+test("loadPolicyFromString — rejects role with non-array grants", () => {
+    assert.throws(() => loadPolicyFromString("roles:\n  viewer: 'read-everything'", "t"), /viewer must be a list/);
+});
+test("loadPolicyFromString — surfaces YAML parse errors with origin", () => {
+    // Tab character is invalid YAML indentation.
+    assert.throws(() => loadPolicyFromString("\troles:\n\tviewer: []", "my-test"), PolicyLoadError);
+});
+test("loadPolicyFromString — file-supplied admin REPLACES built-in admin (no merge)", () => {
+    // The default admin role gets redaction:bypass. A custom admin that
+    // omits it must not silently inherit; otherwise an operator's
+    // attempt to lock down the role would be defeated.
+    const text = `
+roles:
+  admin:
+    - { resource: sources, action: read }
+`;
+    const e = loadPolicyFromString(text, "t");
+    assert.equal(e.evaluate(["admin"], "sources", "read").allowed, true);
+    assert.equal(e.evaluate(["admin"], "redaction", "bypass").allowed, false, "custom admin must NOT inherit redaction:bypass");
+    assert.equal(e.evaluate(["admin"], "users", "delete").allowed, false, "custom admin must NOT inherit users:delete");
+});

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

@@ -0,0 +1,45 @@
+/**
+ * Load a policy from a YAML or JSON file and turn it into a
+ * BuiltinPolicyEngine. Validation enforces every entry has a
+ * known resource + action shape; unknown fields are rejected so a
+ * typo in operator-facing config fails fast and loud rather than
+ * silently dropping grants.
+ *
+ * File shape:
+ *   roles:
+ *     viewer:
+ *       - { resource: sources, action: read }
+ *       - { resource: services, action: read }
+ *     operator:
+ *       - { resource: sources, action: write }
+ *       - { resource: settings, action: write }
+ *     admin:
+ *       - { resource: redaction, action: bypass }
+ *       # etc.
+ *
+ * The loader does NOT inherit-merge built-in roles — a file-supplied
+ * `admin` REPLACES the built-in `admin`. Inheritance / patching is
+ * an operator-side concern (anchor / merge in YAML, jq filters, etc.).
+ */
+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>;
+export declare class PolicyLoadError extends Error {
+    constructor(msg: string);
+}
+/** Parse a YAML/JSON string into a validated policy + return an engine. */
+export declare function loadPolicyFromString(text: string, origin: string): PolicyEngine;
+/** 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

@@ -0,0 +1,137 @@
+/**
+ * Load a policy from a YAML or JSON file and turn it into a
+ * BuiltinPolicyEngine. Validation enforces every entry has a
+ * known resource + action shape; unknown fields are rejected so a
+ * typo in operator-facing config fails fast and loud rather than
+ * silently dropping grants.
+ *
+ * File shape:
+ *   roles:
+ *     viewer:
+ *       - { resource: sources, action: read }
+ *       - { resource: services, action: read }
+ *     operator:
+ *       - { resource: sources, action: write }
+ *       - { resource: settings, action: write }
+ *     admin:
+ *       - { resource: redaction, action: bypass }
+ *       # etc.
+ *
+ * The loader does NOT inherit-merge built-in roles — a file-supplied
+ * `admin` REPLACES the built-in `admin`. Inheritance / patching is
+ * an operator-side concern (anchor / merge in YAML, jq filters, etc.).
+ */
+import { readFileSync } from "node:fs";
+import yaml from "js-yaml";
+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 {
+    constructor(msg) {
+        super(msg);
+        this.name = "PolicyLoadError";
+    }
+}
+/** Parse a YAML/JSON string into a validated policy + return an engine. */
+export function loadPolicyFromString(text, origin) {
+    let parsed;
+    try {
+        parsed = yaml.load(text);
+    }
+    catch (e) {
+        throw new PolicyLoadError(`failed to parse policy ${origin}: ${e.message}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new PolicyLoadError(`${origin}: expected an object with a 'roles' map`);
+    }
+    const roles = parsed.roles;
+    if (!roles || typeof roles !== "object" || Array.isArray(roles)) {
+        throw new PolicyLoadError(`${origin}: missing or non-object 'roles' field`);
+    }
+    const policy = {};
+    for (const [role, grants] of Object.entries(roles)) {
+        if (!Array.isArray(grants)) {
+            throw new PolicyLoadError(`${origin}: roles.${role} must be a list of {resource, action} entries`);
+        }
+        const perms = [];
+        for (let i = 0; i < grants.length; i++) {
+            const g = grants[i];
+            if (!g || typeof g !== "object" || Array.isArray(g)) {
+                throw new PolicyLoadError(`${origin}: roles.${role}[${i}] must be an object`);
+            }
+            // Reject unexpected keys FIRST so a typo like `tesource:` gets
+            // the helpful "unexpected key 'tesource'" message instead of
+            // the misleading "resource 'undefined' unknown" that the value
+            // check below would otherwise emit (no `resource` field
+            // present in the object).
+            for (const k of Object.keys(g)) {
+                if (k !== "resource" && k !== "action") {
+                    throw new PolicyLoadError(`${origin}: roles.${role}[${i}] has unexpected key '${k}'`);
+                }
+            }
+            const resource = g.resource;
+            const action = g.action;
+            if (typeof resource !== "string" || !VALID_RESOURCES.has(resource)) {
+                throw new PolicyLoadError(`${origin}: roles.${role}[${i}].resource '${String(resource)}' unknown (allowed: ${[...VALID_RESOURCES].join(", ")})`);
+            }
+            if (typeof action !== "string" || !VALID_ACTIONS.has(action)) {
+                throw new PolicyLoadError(`${origin}: roles.${role}[${i}].action '${String(action)}' unknown (allowed: ${[...VALID_ACTIONS].join(", ")})`);
+            }
+            perms.push({ resource: resource, action: action });
+        }
+        policy[role] = perms;
+    }
+    return new BuiltinPolicyEngine(policy, origin);
+}
+/** Read a file (utf-8) and load it as a policy. Lets operators
+ *  surface the on-disk path in error messages. */
+export function loadPolicyFromFile(path) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (e) {
+        throw new PolicyLoadError(`failed to read policy ${path}: ${e.message}`);
+    }
+    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);
+});