@thotischner/observability-mcp 1.7.1 → 1.8.1

package/dist/auth/oidc/runtime.js

@@ -0,0 +1,129 @@
+/**
+ * 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";
+/** 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}` };
+        }
+    }
+    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",
+            roleMap,
+            logoutRedirect: nonEmpty(env.OMCP_OIDC_LOGOUT_REDIRECT) ?? "/",
+            tenantClaim: nonEmpty(env.OMCP_OIDC_TENANT_CLAIM) ?? "",
+        },
+    };
+}
+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,180 @@
+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: "",
+    });
+});
+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/engine.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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;
+}
+export interface PolicyEngine {
+    /** One-shot evaluation: does this role-set grant the permission? */
+    evaluate(roles: string[] | undefined, resource: Resource, action: Action): EvalResult;
+    /** Enumerate every (resource, action) the role-set grants. */
+    list(roles: string[] | undefined): 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): EvalResult;
+    list(roles: string[] | undefined): Permission[];
+    roles(): string[];
+    kind(): string;
+    /** Expose the underlying policy for /api/policy reflection. */
+    raw(): Record<string, Permission[]>;
+}

package/dist/auth/policy/engine.js

@@ -0,0 +1,73 @@
+/**
+ * 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) {
+        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) {
+        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;
+    }
+}

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,35 @@
+/**
+ * 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 { 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;

package/dist/auth/policy/loader.js

@@ -0,0 +1,100 @@
+/**
+ * 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",
+]);
+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}`);
+}