@thotischner/observability-mcp 1.7.1 → 3.0.0

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

@@ -0,0 +1,69 @@
+/**
+ * External OPA (Open Policy Agent) policy engine.
+ *
+ * Calls an OPA server over its Data API (POST /v1/data/<path>) to
+ * evaluate every RBAC decision against a Rego policy the operator
+ * authors and loads into OPA. This lets enterprise users keep their
+ * single source of policy truth (a Rego bundle deployed alongside
+ * everything else) instead of duplicating the rules in YAML here.
+ *
+ * Wire format (input):
+ *   POST /v1/data/{package}
+ *   { "input": { "roles": ["admin"], "resource": "sources", "action": "delete" } }
+ *
+ * Expected response shape:
+ *   { "result": true | false }
+ *      OR
+ *   { "result": { "allowed": true|false, "reason"?: string, "permissions"?: [{resource, action}, ...] } }
+ *
+ * The second form lets an operator return both a verdict and the
+ * full per-role permission list from the same package, which the
+ * UI uses to render the policy snapshot. Plain boolean form is
+ * also accepted for minimal policies; in that case .list() returns
+ * an empty array with a "not supported by this OPA package" reason
+ * surfaced via kind().
+ *
+ * No new dependency: uses `fetch` (already in the egress allowlist
+ * for auth/oidc/, and OPA traffic stays inside the cluster).
+ */
+import type { Permission, Resource, Action } from "../rbac.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). */
+    url: string;
+    /** Data path, e.g. "observability/authz". POSTed to /v1/data/<path>. */
+    packagePath: string;
+    /** Optional list of role names the operator wants the UI to show.
+     *  OPA doesn't expose roles natively, so this is config-side. */
+    declaredRoles?: string[];
+    /** Optional bearer token for OPA's `--authentication=token`. */
+    bearerToken?: string;
+    /** Request timeout in ms. Default 1500. OPA decisions should be
+     *  millisecond-fast; a slow OPA almost always means the network
+     *  is wrong, not the policy. */
+    timeoutMs?: number;
+    /** Custom fetcher (tests). */
+    fetcher?: Fetcher;
+}
+export declare class OpaPolicyEngine implements PolicyEngine {
+    private readonly cfg;
+    private readonly fetcher;
+    private cache;
+    private readonly cacheTtlMs;
+    private listCache;
+    private readonly listCacheTtlMs;
+    constructor(cfg: OpaConfig);
+    private cacheKey;
+    private now;
+    private query;
+    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, tenant?: string): Promise<EvalResult>;
+    list(roles: string[] | undefined, ctx?: EvalContext): Permission[];
+    warmList(roles: string[], tenant?: string): Promise<Permission[]>;
+    roles(): string[];
+    kind(): string;
+}

package/dist/auth/policy/opa.js

@@ -0,0 +1,173 @@
+/**
+ * External OPA (Open Policy Agent) policy engine.
+ *
+ * Calls an OPA server over its Data API (POST /v1/data/<path>) to
+ * evaluate every RBAC decision against a Rego policy the operator
+ * authors and loads into OPA. This lets enterprise users keep their
+ * single source of policy truth (a Rego bundle deployed alongside
+ * everything else) instead of duplicating the rules in YAML here.
+ *
+ * Wire format (input):
+ *   POST /v1/data/{package}
+ *   { "input": { "roles": ["admin"], "resource": "sources", "action": "delete" } }
+ *
+ * Expected response shape:
+ *   { "result": true | false }
+ *      OR
+ *   { "result": { "allowed": true|false, "reason"?: string, "permissions"?: [{resource, action}, ...] } }
+ *
+ * The second form lets an operator return both a verdict and the
+ * full per-role permission list from the same package, which the
+ * UI uses to render the policy snapshot. Plain boolean form is
+ * also accepted for minimal policies; in that case .list() returns
+ * an empty array with a "not supported by this OPA package" reason
+ * surfaced via kind().
+ *
+ * No new dependency: uses `fetch` (already in the egress allowlist
+ * for auth/oidc/, and OPA traffic stays inside the cluster).
+ */
+export class OpaPolicyEngine {
+    cfg;
+    fetcher;
+    // Tiny per-(role, resource, action) cache so a render of /api/me
+    // doesn't fire 30 OPA calls per second. 5s TTL is short enough
+    // that a policy update at OPA is reflected promptly; long enough
+    // that bursts of UI loads coalesce.
+    cache = new Map();
+    cacheTtlMs = 5_000;
+    // List cache is per-role and slightly longer-lived since list() is
+    // only used for /api/me / Policy UI which the user doesn't refresh
+    // every 200ms.
+    listCache = new Map();
+    listCacheTtlMs = 30_000;
+    constructor(cfg) {
+        this.cfg = { timeoutMs: 1500, ...cfg };
+        this.fetcher = cfg.fetcher ?? ((u, i) => fetch(u, i));
+    }
+    cacheKey(roles, resource, action, tenant) {
+        // NUL-delimited so role names containing "," / "|" can't alias
+        // across role sets ({"a,b"} would otherwise collide with {"a","b"}).
+        // Tenant is part of the key so cross-tenant decisions don't share
+        // cache slots — required once we thread tenant into the OPA input.
+        const tk = tenant || "";
+        return roles.slice().sort().join("\x00") + "\x01" + resource + "\x01" + action + "\x01" + tk;
+    }
+    now() {
+        return Date.now();
+    }
+    async query(payload) {
+        const url = `${this.cfg.url.replace(/\/$/, "")}/v1/data/${this.cfg.packagePath.replace(/^\//, "")}`;
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), this.cfg.timeoutMs ?? 1500);
+        try {
+            const headers = { "content-type": "application/json" };
+            if (this.cfg.bearerToken)
+                headers.authorization = `Bearer ${this.cfg.bearerToken}`;
+            const res = await this.fetcher(url, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(payload),
+                signal: ctrl.signal,
+            });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status} from ${url}`);
+            return (await res.json());
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    evaluate(roles, resource, action, ctx) {
+        const rs = roles && roles.length > 0 ? roles : [];
+        const tenant = ctx?.tenant;
+        // The PolicyEngine.evaluate contract is sync to keep the hot
+        // gate path off the await stack, so we serve from the cache
+        // synchronously and warm the cache lazily on miss. Misses fall
+        // back to a conservative deny + the cache will be populated for
+        // next time.
+        const key = this.cacheKey(rs, resource, action, tenant);
+        const cached = this.cache.get(key);
+        if (cached && this.now() - cached.at < this.cacheTtlMs)
+            return cached.result;
+        // Fire and forget: populate the cache; this call is racy on
+        // first miss (deny while warming) but the next call within the
+        // TTL returns the real verdict. For sync-required contracts we
+        // accept that trade-off vs. blocking every request handler.
+        void this.warmEvaluate(rs, resource, action, tenant);
+        return { allowed: false, reason: "OPA decision pending (warming cache); request again" };
+    }
+    /** 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. */
+    async warmEvaluate(roles, resource, action, tenant) {
+        const key = this.cacheKey(roles, resource, action, tenant);
+        try {
+            // input.tenant is always included (undefined → null in JSON
+            // serialisation, omitted by JSON.stringify default) so Rego
+            // authors can write `input.tenant == "acme"` rules without
+            // tripping on missing-field. When the caller didn't supply
+            // tenant we still include the key with `undefined` value;
+            // JSON.stringify drops it cleanly.
+            const out = await this.query({ input: { roles, resource, action, tenant } });
+            const raw = out.result;
+            let result;
+            if (raw === true || raw === false) {
+                result = { allowed: raw, reason: raw ? "allowed by OPA" : "denied by OPA" };
+            }
+            else if (raw && typeof raw === "object") {
+                result = {
+                    allowed: !!raw.allowed,
+                    reason: typeof raw.reason === "string" ? raw.reason : (raw.allowed ? "allowed by OPA" : "denied by OPA"),
+                };
+            }
+            else {
+                result = { allowed: false, reason: `OPA returned an unrecognised result shape: ${JSON.stringify(raw)}` };
+            }
+            this.cache.set(key, { at: this.now(), result });
+            return result;
+        }
+        catch (e) {
+            const result = { allowed: false, reason: `OPA query failed: ${e.message}` };
+            // Cache the failure for a SHORT window so a flapping OPA
+            // doesn't get hammered, but not for the full TTL.
+            this.cache.set(key, { at: this.now() - this.cacheTtlMs + 1000, result });
+            return result;
+        }
+    }
+    list(roles, ctx) {
+        if (!roles || roles.length === 0)
+            return [];
+        const tenant = ctx?.tenant || "";
+        const key = roles.slice().sort().join("\x00") + "\x01" + tenant;
+        const cached = this.listCache.get(key);
+        if (cached && this.now() - cached.at < this.listCacheTtlMs)
+            return cached.perms;
+        void this.warmList(roles, ctx?.tenant);
+        return [];
+    }
+    async warmList(roles, tenant) {
+        const key = roles.slice().sort().join("\x00") + "\x01" + (tenant || "");
+        try {
+            const out = await this.query({ input: { roles, list: true, tenant } });
+            const raw = out.result;
+            let perms = [];
+            if (raw && typeof raw === "object" && Array.isArray(raw.permissions)) {
+                perms = raw.permissions
+                    .filter((p) => p && typeof p.resource === "string" && typeof p.action === "string")
+                    .map((p) => ({ resource: p.resource, action: p.action }));
+            }
+            this.listCache.set(key, { at: this.now(), perms });
+            return perms;
+        }
+        catch {
+            this.listCache.set(key, { at: this.now(), perms: [] });
+            return [];
+        }
+    }
+    roles() {
+        return this.cfg.declaredRoles ?? [];
+    }
+    kind() {
+        return `opa:${this.cfg.url}`;
+    }
+}

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

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

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

@@ -0,0 +1,206 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { OpaPolicyEngine } from "./opa.js";
+function mockFetcher(handler) {
+    return (async (url, init) => {
+        const body = init?.body ? JSON.parse(String(init.body)) : null;
+        const result = handler(url, body);
+        return new Response(JSON.stringify({ result }), { status: 200, headers: { "content-type": "application/json" } });
+    });
+}
+test("OpaPolicyEngine — evaluate returns warming-deny on first call, real verdict after warm", async () => {
+    const calls = [];
+    const fetcher = (async (url, init) => {
+        const body = init?.body ? JSON.parse(String(init.body)) : null;
+        calls.push({ url, body });
+        return new Response(JSON.stringify({ result: true }), { status: 200 });
+    });
+    const e = new OpaPolicyEngine({ url: "http://opa.test", packagePath: "observability/authz", fetcher });
+    // First call: cache miss → conservative deny + async fire.
+    const first = e.evaluate(["admin"], "sources", "write");
+    assert.equal(first.allowed, false);
+    assert.match(first.reason, /OPA decision pending/);
+    // After explicit warm, the cache holds the real verdict.
+    const real = await e.warmEvaluate(["admin"], "sources", "write");
+    assert.equal(real.allowed, true);
+    const cached = e.evaluate(["admin"], "sources", "write");
+    assert.equal(cached.allowed, true);
+    assert.equal(calls.length, 2, "expected exactly two POSTs: implicit lazy warm + explicit warm");
+});
+test("OpaPolicyEngine — accepts boolean and rich result shapes", async () => {
+    const e1 = new OpaPolicyEngine({ url: "http://opa.test", packagePath: "p", fetcher: mockFetcher(() => true) });
+    assert.equal((await e1.warmEvaluate(["admin"], "sources", "read")).allowed, true);
+    const e2 = new OpaPolicyEngine({
+        url: "http://opa.test", packagePath: "p",
+        fetcher: mockFetcher(() => ({ allowed: false, reason: "blocked: not in office hours" })),
+    });
+    const r = await e2.warmEvaluate(["admin"], "sources", "read");
+    assert.equal(r.allowed, false);
+    assert.match(r.reason, /office hours/);
+});
+test("OpaPolicyEngine — unrecognised shape denies with a clear reason", async () => {
+    const e = new OpaPolicyEngine({ url: "http://opa.test", packagePath: "p", fetcher: mockFetcher(() => 42) });
+    const r = await e.warmEvaluate(["admin"], "sources", "read");
+    assert.equal(r.allowed, false);
+    assert.match(r.reason, /unrecognised result shape/);
+});
+test("OpaPolicyEngine — second evaluate() after the short failure cache reads the fresh OPA verdict", async () => {
+    // End-to-end recovery: failure → cache stale → next evaluate() hits
+    // the populated success result. We can't sleep in unit tests, so
+    // we drive the cache state directly: first warm hits OPA and
+    // caches the failure with an expired-ish timestamp (see opa.ts:
+    // failure cache stamped now - TTL + 1s = effectively expired in
+    // ~1s); second warm hits OPA again and caches a real success;
+    // third evaluate() returns the success synchronously from cache.
+    // This proves the engine never gets stuck denying after OPA recovers.
+    let calls = 0;
+    const fetcher = (async (_u) => {
+        calls++;
+        if (calls === 1)
+            return new Response("nope", { status: 503 });
+        return new Response(JSON.stringify({ result: true }), { status: 200 });
+    });
+    const e = new OpaPolicyEngine({ url: "http://opa.test", packagePath: "p", fetcher });
+    const denied = await e.warmEvaluate(["admin"], "sources", "read");
+    assert.equal(denied.allowed, false, "first call failure surfaces");
+    const recovered = await e.warmEvaluate(["admin"], "sources", "read");
+    assert.equal(recovered.allowed, true, "second warm re-queries and gets the recovered verdict");
+    // The success populated the cache; a subsequent evaluate() must
+    // return synchronously WITHOUT another fetch — this is the
+    // "engine doesn't loop forever in warming-deny after OPA recovers"
+    // invariant the user-facing gate cares about.
+    const cached = e.evaluate(["admin"], "sources", "read");
+    assert.equal(cached.allowed, true, "cached success served synchronously");
+    assert.equal(calls, 2, "evaluate() must reuse the cached success, no extra OPA call");
+});
+test("OpaPolicyEngine — http error caches a denial briefly so flapping OPA doesn't hammer", async () => {
+    let calls = 0;
+    const fetcher = (async (_u) => {
+        calls++;
+        return new Response("nope", { status: 503 });
+    });
+    const e = new OpaPolicyEngine({ url: "http://opa.test", packagePath: "p", fetcher });
+    const r1 = await e.warmEvaluate(["admin"], "sources", "read");
+    assert.equal(r1.allowed, false);
+    assert.match(r1.reason, /HTTP 503/);
+    // The next sync evaluate within ~1s uses the cached denial.
+    const r2 = e.evaluate(["admin"], "sources", "read");
+    assert.equal(r2.allowed, false);
+    assert.equal(calls, 1);
+});
+test("OpaPolicyEngine — list extracts permissions from the rich shape", async () => {
+    const fetcher = mockFetcher((_url, body) => {
+        if (body?.input?.list) {
+            return { permissions: [{ resource: "sources", action: "read" }, { resource: "sources", action: "write" }] };
+        }
+        return false;
+    });
+    const e = new OpaPolicyEngine({ url: "http://opa.test", packagePath: "p", fetcher });
+    const perms = await e.warmList(["admin"]);
+    assert.equal(perms.length, 2);
+    assert.deepEqual(perms[0], { resource: "sources", action: "read" });
+});
+test("OpaPolicyEngine — list returns [] when OPA returns plain boolean (no permissions key)", async () => {
+    const fetcher = mockFetcher(() => true);
+    const e = new OpaPolicyEngine({ url: "http://opa.test", packagePath: "p", fetcher });
+    const perms = await e.warmList(["admin"]);
+    assert.deepEqual(perms, []);
+});
+test("OpaPolicyEngine — roles() reflects declaredRoles", () => {
+    const e = new OpaPolicyEngine({
+        url: "http://opa.test", packagePath: "p",
+        declaredRoles: ["admin", "operator", "auditor"],
+    });
+    assert.deepEqual(e.roles(), ["admin", "operator", "auditor"]);
+});
+test("OpaPolicyEngine — kind() prefixes URL", () => {
+    const e = new OpaPolicyEngine({ url: "http://opa.example:8181", packagePath: "p" });
+    assert.equal(e.kind(), "opa:http://opa.example:8181");
+});
+test("OpaPolicyEngine — sends Bearer token when configured", async () => {
+    let seenAuth;
+    const fetcher = (async (_url, init) => {
+        seenAuth = init?.headers?.authorization;
+        return new Response(JSON.stringify({ result: true }), { status: 200 });
+    });
+    const e = new OpaPolicyEngine({ url: "http://opa.test", packagePath: "p", bearerToken: "shh", fetcher });
+    await e.warmEvaluate(["admin"], "sources", "read");
+    assert.equal(seenAuth, "Bearer shh");
+});
+test("OpaPolicyEngine — cache key delimiter prevents role-name collision (\"a,b\" vs [\"a\",\"b\"])", async () => {
+    const calls = [];
+    const fetcher = (async (_url, init) => {
+        calls.push(init?.body ? JSON.parse(String(init.body)) : null);
+        // Two distinct results so we can prove no cross-cache-hit.
+        return new Response(JSON.stringify({ result: calls.length === 1 }), { status: 200 });
+    });
+    const e = new OpaPolicyEngine({ url: "http://opa.test", packagePath: "p", fetcher });
+    const r1 = await e.warmEvaluate(["a,b"], "sources", "read");
+    const r2 = await e.warmEvaluate(["a", "b"], "sources", "read");
+    assert.equal(r1.allowed, true);
+    assert.equal(r2.allowed, false);
+    assert.equal(calls.length, 2, "the two role-sets must not collide on the cache key");
+});
+test("OpaPolicyEngine — tenant flows into the OPA input shape on evaluate", async () => {
+    let seenBody = null;
+    const fetcher = (async (_url, init) => {
+        seenBody = init?.body ? JSON.parse(String(init.body)) : null;
+        return new Response(JSON.stringify({ result: true }), { status: 200 });
+    });
+    const e = new OpaPolicyEngine({ url: "http://opa.test", packagePath: "p", fetcher });
+    await e.warmEvaluate(["admin"], "sources", "write", "acme");
+    const body = seenBody;
+    assert.equal(body?.input?.tenant, "acme", "tenant must reach the Rego input as input.tenant");
+    assert.equal(body?.input?.resource, "sources");
+    assert.equal(body?.input?.action, "write");
+});
+test("OpaPolicyEngine — tenant flows into the OPA input shape on list", async () => {
+    let seenBody = null;
+    const fetcher = (async (_url, init) => {
+        seenBody = init?.body ? JSON.parse(String(init.body)) : null;
+        return new Response(JSON.stringify({ result: { permissions: [] } }), { status: 200 });
+    });
+    const e = new OpaPolicyEngine({ url: "http://opa.test", packagePath: "p", fetcher });
+    await e.warmList(["admin"], "acme");
+    const body = seenBody;
+    assert.equal(body?.input?.tenant, "acme");
+    assert.equal(body?.input?.list, true);
+});
+test("OpaPolicyEngine — cache key isolates tenants (same roles+resource+action, different tenants → two OPA calls)", async () => {
+    let calls = 0;
+    const fetcher = (async (_url, init) => {
+        calls++;
+        const body = init?.body ? JSON.parse(String(init.body)) : null;
+        // Return a different verdict per tenant so a cache mix-up would
+        // surface as a wrong allowed value, not just an extra call.
+        const allowed = body?.input?.tenant === "acme";
+        return new Response(JSON.stringify({ result: allowed }), { status: 200 });
+    });
+    const e = new OpaPolicyEngine({ url: "http://opa.test", packagePath: "p", fetcher });
+    const acme = await e.warmEvaluate(["admin"], "sources", "read", "acme");
+    const bigco = await e.warmEvaluate(["admin"], "sources", "read", "bigco");
+    assert.equal(acme.allowed, true);
+    assert.equal(bigco.allowed, false);
+    assert.equal(calls, 2, "tenants must not share cache slots");
+    // Repeat — both come from cache, no extra OPA hits.
+    const acme2 = e.evaluate(["admin"], "sources", "read", { tenant: "acme" });
+    const bigco2 = e.evaluate(["admin"], "sources", "read", { tenant: "bigco" });
+    assert.equal(acme2.allowed, true);
+    assert.equal(bigco2.allowed, false);
+    assert.equal(calls, 2);
+});
+test("OpaPolicyEngine — sort-stable cache key (role-set order doesn't matter)", async () => {
+    let calls = 0;
+    const fetcher = (async (_u) => {
+        calls++;
+        return new Response(JSON.stringify({ result: true }), { status: 200 });
+    });
+    const e = new OpaPolicyEngine({ url: "http://opa.test", packagePath: "p", fetcher });
+    // Warm with one order; evaluate with another. The cache hit path
+    // (evaluate, not warmEvaluate — warm always re-queries) proves the
+    // key is order-independent: one OPA call, second is a cache hit.
+    await e.warmEvaluate(["b", "a", "c"], "sources", "read");
+    const cached = e.evaluate(["c", "b", "a"], "sources", "read");
+    assert.equal(calls, 1, "second evaluate (reordered roles) must reuse the cache, no extra fetch");
+    assert.equal(cached.allowed, true);
+});

package/dist/auth/rbac.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Role-based access control for the management plane.
+ *
+ * Roles are simple string identifiers (`viewer`, `operator`, `admin` ship
+ * built-in but the resolver is open-set — a deployment may add any number
+ * of custom roles via OIDC group claims, the local users file, or future
+ * RBAC config).
+ *
+ * Permissions are encoded as `<resource>:<action>` pairs. The permission
+ * table maps each pair to the set of roles that are granted it. A role
+ * with no entries in the table grants nothing.
+ *
+ * Anonymous mode bypasses RBAC entirely — there is no identity to check.
+ * Basic mode runs every mutating /api/* request through `requirePermission`
+ * middleware (mounted in index.ts alongside `requireSession`).
+ */
+import type { RequestHandler } from "express";
+import type { AuthRuntime } from "./middleware.js";
+import type { PolicyEngine } from "./policy/engine.js";
+export type Action = "read" | "write" | "delete" | "bypass";
+export type Resource = "sources" | "services" | "health" | "topology" | "settings" | "connectors" | "audit" | "catalog" | "users" | "redaction" | "products";
+export interface Permission {
+    resource: Resource;
+    action: Action;
+}
+/** Built-in default policy. Operators replace this via OMCP_RBAC_POLICY_FILE
+ *  (YAML/JSON file → BuiltinPolicyEngine) or OMCP_OPA_URL (external
+ *  OPA → OpaPolicyEngine). The gate consumes whichever via
+ *  `buildRequirePermissionFromEngine` so tenant-conditional Rego
+ *  rules can fire. */
+export declare const DEFAULT_POLICY: Record<string, Permission[]>;
+/** Resolve whether the given role set grants the requested permission. */
+export declare function hasPermission(roles: string[] | undefined, resource: Resource, action: Action, policy?: Record<string, Permission[]>): boolean;
+/**
+ * Express middleware factory. Returns a no-op in anonymous mode, otherwise
+ * gates the route on the named permission. Assumes `req.session` has been
+ * attached upstream by `buildSessionAttacher` and any auth requirement has
+ * already been enforced by `buildRequireSession` — so reaching this point
+ * with no session means anonymous mode is active.
+ */
+export declare function buildRequirePermission(runtime: AuthRuntime, resource: Resource, action: Action, policy?: Record<string, Permission[]>): RequestHandler;
+/**
+ * Engine-aware variant of `buildRequirePermission`. Prefer this when an
+ * external policy engine (OPA, custom Rego) is in play — the legacy
+ * `(roles, resource, action) → boolean` map cannot carry the active
+ * tenant, so a Rego rule like `allow { input.tenant == "acme" }` can
+ * never fire if you go through the map. This variant calls
+ * `engine.evaluate(roles, resource, action, { tenant: session.tenant })`
+ * so tenant-conditional rules see the input they need.
+ *
+ * Anonymous mode stays a no-op — same as the map variant.
+ *
+ * Performance: `evaluate` is sync by contract. OPA hits its cache; on
+ * first miss it returns a conservative deny and warms in the
+ * background — the second request inside the TTL gets the real
+ * verdict. Documented in opa.ts.
+ */
+export declare function buildRequirePermissionFromEngine(runtime: AuthRuntime, resource: Resource, action: Action, engine: PolicyEngine): RequestHandler;
+/** Convenience snapshot for `/api/me` — list every permission the
+ * given role set unlocks. Used by the UI to hide write controls the
+ * current user can't trigger anyway. */
+export declare function listGrantedPermissions(roles: string[] | undefined, policy?: Record<string, Permission[]>): Permission[];