mandat 0.0.0-stage → 0.1.0

package/dist/guard/guard.js

@@ -0,0 +1,290 @@
+// Mandat Guard: the Policy Enforcement Point embedded in an MCP server (or any tool-executing service).
+//
+// For every tool call:
+//   1. verify the per-task bearer token (iss, aud = this resource, exp, typ at+jwt, signature via JWKS)
+//   2. reject revoked tokens / agents / versions / users
+//   3. reject tools whose definitions drifted from the pinned lockfile (block mode)
+//   4. evaluate policy (PDP, in-process) with args, delegation chain, capability and session taint
+//   5. require_approval -> create/await a human approval bound to this exact call
+//   6. run the handler, then write ONE hash-chained Action Record with decision + outcome
+import { JwksClient, JwtError, verifyJwt } from "../sts/jwt.js";
+import { actorChain, matchRevocation } from "../sts/revocation.js";
+import { HIGH_RISK } from "../policy/engine.js";
+import { approvalBinding } from "../approvals/approvals.js";
+import { redact } from "../ledger/redact.js";
+import { checkPins, toolHash } from "./pinning.js";
+export class StaticPolicy {
+    p;
+    constructor(p) { this.p = p; }
+    current() { return this.p; }
+    set(p) { this.p = p; }
+}
+export class LocalRevocations {
+    list;
+    constructor(list) { this.list = list; }
+    check(claims) { return matchRevocation(claims, this.list()); }
+    stale() { return false; }
+}
+export class LocalApprovalBroker {
+    svc;
+    constructor(svc) { this.svc = svc; }
+    request(n) { return this.svc.create(n); }
+    wait(id, ms) { return this.svc.wait(id, ms); }
+    async consume(id) { return this.svc.consume(id); }
+}
+export class AuthError extends Error {
+    status;
+    code;
+    constructor(code, message, status = 401) {
+        super(message);
+        this.code = code;
+        this.status = status;
+    }
+}
+export class GuardDenied extends Error {
+    code;
+    decision;
+    record;
+    approvalId;
+    constructor(code, message, decision, record, approvalId) {
+        super(message);
+        this.code = code;
+        this.decision = decision;
+        this.record = record;
+        this.approvalId = approvalId;
+    }
+}
+const SESSION_TTL_MS = 6 * 3_600_000;
+export class Guard {
+    opts;
+    jwks;
+    sessions = new Map();
+    toolDefs = new Map();
+    blockedTools = new Set();
+    log;
+    constructor(opts) {
+        this.opts = { mode: "enforce", approvalWaitMs: 20_000, ...opts };
+        this.jwks = opts.publicKey ? null : new JwksClient(opts.jwksUri ?? `${opts.issuer.replace(/\/$/, "")}/.well-known/jwks.json`);
+        this.log = opts.log ?? ((m) => console.warn(`[mandat] ${m}`));
+    }
+    /** RFC 9728 Protected Resource Metadata for this server. */
+    protectedResourceMetadata(extra = {}) {
+        return {
+            resource: this.opts.resource,
+            authorization_servers: [this.opts.issuer],
+            bearer_methods_supported: ["header"],
+            resource_signing_alg_values_supported: ["ES256"],
+            authorization_details_types_supported: ["mandat_tool_call"],
+            resource_name: this.opts.source ?? "MCP server protected by Mandat",
+            ...extra,
+        };
+    }
+    /** Verifies a bearer token. Throws AuthError (map to HTTP 401/403 + WWW-Authenticate). */
+    async verify(token) {
+        if (!token)
+            throw new AuthError("invalid_token", "Bearer token required");
+        let claims;
+        try {
+            claims = await verifyJwt(token, this.opts.publicKey ? () => this.opts.publicKey : (h) => this.jwks.getKey(h.kid), { issuer: this.opts.issuer, audience: this.opts.resource, typ: "at+jwt", requireExp: true });
+        }
+        catch (e) {
+            if (e instanceof JwtError)
+                throw new AuthError("invalid_token", e.message);
+            throw new AuthError("invalid_token", `Token verification failed: ${e.message}`);
+        }
+        const chain = actorChain(claims);
+        if (!chain.length)
+            throw new AuthError("invalid_token", "Token has no `act` claim: not a delegated agent token");
+        const m = (claims.mandat ?? {});
+        const revoked = this.opts.revocations.check(claims);
+        if (revoked)
+            throw new AuthError("invalid_token", `Token revoked (${revoked.type}: ${revoked.value}${revoked.reason ? ` - ${revoked.reason}` : ""})`);
+        return {
+            token,
+            claims,
+            principal: { sub: String(claims.sub), tenant: m.tenant ?? null, email: claims.email ?? null },
+            agent: { id: chain[0].sub, version: m.agent_version ?? chain[0].mandat_agent_version ?? null, prompt_hash: m.prompt_hash ?? null },
+            actor_chain: chain.map((a) => a.sub),
+            task_id: m.task_id ?? null,
+            session_id: m.session_id ?? null,
+            authorization_details: claims.authorization_details ?? null,
+        };
+    }
+    /**
+     * OAuthTokenVerifier for the official MCP SDK's `requireBearerAuth`. Pass the SDK's InvalidTokenError
+     * so failures become proper 401 responses.
+     */
+    sdkTokenVerifier(errors = {}) {
+        return {
+            verifyAccessToken: async (token) => {
+                try {
+                    const auth = await this.verify(token);
+                    return {
+                        token,
+                        clientId: auth.agent.id,
+                        scopes: typeof auth.claims.scope === "string" ? auth.claims.scope.split(" ") : [],
+                        expiresAt: auth.claims.exp,
+                        resource: new URL(this.opts.resource),
+                        extra: { mandat: auth },
+                    };
+                }
+                catch (e) {
+                    throw errors.InvalidTokenError ? new errors.InvalidTokenError(e.message) : e;
+                }
+            },
+        };
+    }
+    /** Register the server's tool definitions: computes hashes and checks them against the pin lockfile. */
+    registerTools(defs) {
+        for (const d of defs)
+            this.toolDefs.set(d.name, toolHash(d));
+        if (!this.opts.pinning)
+            return null;
+        const res = checkPins(this.opts.pinning.lockfile, defs, { mode: this.opts.pinning.mode ?? "warn", frozen: this.opts.pinning.frozen, server: this.opts.resource });
+        this.blockedTools = res.blocked;
+        if (!res.drift.clean) {
+            const msg = `Tool definition drift: changed=[${res.drift.changed.map((c) => c.name)}] added=[${res.drift.added}] removed=[${res.drift.removed}]` +
+                (res.blocked.size ? ` — blocked until re-pinned: ${[...res.blocked].join(", ")}` : "");
+            this.log(msg);
+            this.append({ type: "tool.drift", tool: { name: "*", server: this.opts.resource }, details: { ...res.drift, mode: this.opts.pinning.mode ?? "warn" } });
+        }
+        return res.drift;
+    }
+    /**
+     * Authorises and executes one tool call. Returns the handler's result, or throws GuardDenied.
+     * Exactly one `agent.tool_call` record is written per invocation.
+     */
+    async execute(ctx, handler) {
+        const started = Date.now();
+        const policy = this.opts.policy.current();
+        const meta = policy.toolMeta(ctx.tool);
+        const sessionKey = ctx.sessionId ?? ctx.auth.session_id ?? ctx.auth.task_id ?? ctx.auth.claims.jti ?? "anonymous";
+        const session = this.session(sessionKey);
+        const shadow = this.opts.mode === "shadow";
+        const base = (decision, final) => ({
+            type: "agent.tool_call",
+            source: this.opts.source,
+            principal: ctx.auth.principal,
+            agent: ctx.auth.agent,
+            actor_chain: ctx.auth.actor_chain,
+            task_id: ctx.auth.task_id,
+            token_jti: ctx.auth.claims.jti ?? null,
+            session: { id: sessionKey, tainted: session.tainted, taint_sources: session.taint_sources },
+            tool: { name: ctx.tool, server: this.opts.resource, risk: meta.risk ?? null, definition_hash: this.toolDefs.get(ctx.tool) ?? null },
+            args: this.redactArgs(ctx.args, [...(decision?.obligations ?? [])]),
+            decision: decision
+                ? { effect: decision.effect, final, rules: decision.matched, reasons: decision.reasons, obligations: decision.obligations, policy_version: decision.policy_version, latency_us: Math.round(decision.latency_us), mode: this.opts.mode }
+                : { effect: "deny", final, rules: [], reasons: [], mode: this.opts.mode },
+            tags: decision?.obligations.filter((o) => o.type === "annotate").flatMap((o) => o.tags ?? []),
+        });
+        const deny = (code, reason, decision, extra = {}) => {
+            const rec = this.append({ ...base(decision, "deny"), ...extra, outcome: { status: "blocked", error: reason, duration_ms: Date.now() - started } });
+            throw new GuardDenied(code, reason, decision, rec, extra.approval?.id);
+        };
+        // Re-check revocation on every call (token may have been revoked after verify).
+        const revoked = this.opts.revocations.check(ctx.auth.claims);
+        if (revoked)
+            deny("revoked", `Token revoked (${revoked.type}: ${revoked.value})`, null);
+        if (this.blockedTools.has(ctx.tool) && !shadow)
+            deny("drift", `Tool '${ctx.tool}' changed since it was pinned; re-approve its definition with \`mandat pin\``, null);
+        const decision = policy.evaluate({
+            principal: { ...ctx.auth.principal, ...pickClaims(ctx.auth.claims) },
+            agent: ctx.auth.agent,
+            actor_chain: ctx.auth.actor_chain.map((sub) => ({ sub })),
+            tool: { name: ctx.tool, server: this.opts.resource },
+            args: ctx.args,
+            session: { id: sessionKey, tainted: session.tainted, taint_sources: session.taint_sources, calls: session.calls },
+            task: { id: ctx.auth.task_id, authorization_details: ctx.auth.authorization_details },
+        });
+        // Fail closed for high-risk tools when the control plane (revocations) is unreachable.
+        if (this.opts.revocations.stale() && meta.risk && HIGH_RISK.includes(meta.risk) && !shadow)
+            deny("fail_closed", `Control plane unreachable: '${meta.risk}' tools fail closed`, decision);
+        let approvalInfo;
+        if (!shadow && decision.effect === "deny")
+            deny("denied", decision.reasons.join("; "), decision);
+        if (!shadow && decision.effect === "require_approval") {
+            const a = decision.approval;
+            let req;
+            try {
+                req = await this.opts.approvals.request({
+                    binding: approvalBinding({ sub: ctx.auth.principal.sub, agent: ctx.auth.agent.id, tool: ctx.tool, server: this.opts.resource, args: ctx.args }),
+                    required: a.approvers,
+                    timeoutMs: a.timeoutMs,
+                    channels: a.channels,
+                    context: {
+                        tool: ctx.tool, server: this.opts.resource, risk: meta.risk ?? null,
+                        args: this.redactArgs(ctx.args, decision.obligations),
+                        principal: ctx.auth.principal, agent: ctx.auth.agent, actor_chain: ctx.auth.actor_chain,
+                        task_id: ctx.auth.task_id, rule: a.rule, reasons: decision.reasons, session_tainted: session.tainted,
+                    },
+                });
+                if (req.status === "pending")
+                    req = await this.opts.approvals.wait(req.id, this.opts.approvalWaitMs);
+            }
+            catch (e) {
+                deny("fail_closed", `Approval service unavailable: ${e.message}`, decision);
+            }
+            const r = req;
+            approvalInfo = { id: r.id, status: r.status, required: r.required, approvers: r.votes.filter((v) => v.decision === "approve").map((v) => v.by) };
+            if (r.status === "pending") {
+                const rec = this.append({ ...base(decision, "pending"), approval: approvalInfo, outcome: { status: "pending", duration_ms: Date.now() - started } });
+                throw new GuardDenied("approval_pending", `Human approval required (request ${r.id}, expires ${r.expires_at}). Retry the same call once it is approved.`, decision, rec, r.id);
+            }
+            if (r.status !== "approved")
+                deny("approval_denied", `Approval ${r.id} was ${r.status}`, decision, { approval: approvalInfo });
+            if (!(await this.opts.approvals.consume(r.id)))
+                deny("approval_denied", `Approval ${r.id} was already used`, decision, { approval: approvalInfo });
+        }
+        session.calls++;
+        try {
+            const result = await handler();
+            if (meta.taints && !session.tainted) {
+                session.tainted = true;
+                session.taint_sources.push(ctx.tool);
+            }
+            this.append({ ...base(decision, "allow"), approval: approvalInfo, outcome: { status: "success", duration_ms: Date.now() - started } });
+            return result;
+        }
+        catch (e) {
+            this.append({ ...base(decision, "allow"), approval: approvalInfo, outcome: { status: "error", error: e.message?.slice(0, 500), duration_ms: Date.now() - started } });
+            throw e;
+        }
+    }
+    /** Session taint state (for tests / introspection). */
+    sessionState(key) { return this.sessions.get(key); }
+    session(key) {
+        const now = Date.now();
+        let s = this.sessions.get(key);
+        if (!s) {
+            if (this.sessions.size > 10_000) {
+                for (const [k, v] of this.sessions)
+                    if (now - v.touched > SESSION_TTL_MS)
+                        this.sessions.delete(k);
+            }
+            s = { tainted: false, taint_sources: [], calls: 0, touched: now };
+            this.sessions.set(key, s);
+        }
+        s.touched = now;
+        return s;
+    }
+    redactArgs(args, obligations) {
+        const fields = obligations.filter((o) => o.type === "redact").flatMap((o) => o.fields ?? []);
+        return redact(args, { ...this.opts.redaction, fields: [...(this.opts.redaction?.fields ?? []), ...fields] });
+    }
+    append(rec) {
+        try {
+            return this.opts.ledger.append({ source: this.opts.source, ...rec });
+        }
+        catch (e) {
+            this.log(`Ledger append failed: ${e.message}`);
+        }
+    }
+}
+/** Selected token claims exposed to policies as principal.* (never the raw token). */
+function pickClaims(c) {
+    const out = {};
+    for (const k of ["scope", "client_id", "email"])
+        if (c[k] !== undefined)
+            out[k] = c[k];
+    return out;
+}

package/dist/guard/pinning.d.ts

@@ -0,0 +1,46 @@
+export interface ToolDefinition {
+    name: string;
+    title?: string;
+    description?: string;
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+    annotations?: unknown;
+}
+export interface LockFile {
+    version: 1;
+    server?: string;
+    pinned_at: string;
+    tools: Record<string, {
+        hash: string;
+        description?: string;
+    }>;
+}
+export interface DriftReport {
+    added: string[];
+    removed: string[];
+    changed: Array<{
+        name: string;
+        before: string;
+        after: string;
+        description_before?: string;
+        description_after?: string;
+    }>;
+    clean: boolean;
+}
+export declare function toolHash(t: ToolDefinition): string;
+export declare function buildLock(tools: ToolDefinition[], server?: string): LockFile;
+export declare function diffLock(lock: LockFile, tools: ToolDefinition[]): DriftReport;
+export interface PinCheckResult {
+    drift: DriftReport;
+    created: boolean;
+    blocked: Set<string>;
+}
+/**
+ * Compares tools against `lockPath`. Creates the lockfile on first use (trust-on-first-use) unless `frozen`.
+ * In "block" mode, changed and newly added tools are returned in `blocked`.
+ */
+export declare function checkPins(lockPath: string, tools: ToolDefinition[], opts: {
+    mode: "warn" | "block";
+    frozen?: boolean;
+    server?: string;
+}): PinCheckResult;

package/dist/guard/pinning.js

@@ -0,0 +1,49 @@
+// Tool definition pinning (rug-pull / tool-poisoning protection, US-9).
+// A lockfile stores sha256(name, description, inputSchema, annotations) per tool. Any later change to a
+// description or schema is "drift" and is reported (warn) or blocked until re-approved with `mandat pin`.
+import { existsSync } from "node:fs";
+import { canonicalJson, readJson, sha256, writeJsonAtomic } from "../util.js";
+export function toolHash(t) {
+    return "sha256:" + sha256(canonicalJson({
+        name: t.name, title: t.title ?? null, description: t.description ?? null,
+        inputSchema: t.inputSchema ?? null, outputSchema: t.outputSchema ?? null, annotations: t.annotations ?? null,
+    }));
+}
+export function buildLock(tools, server) {
+    const out = { version: 1, server, pinned_at: new Date().toISOString(), tools: {} };
+    for (const t of [...tools].sort((a, b) => a.name.localeCompare(b.name))) {
+        out.tools[t.name] = { hash: toolHash(t), description: t.description?.slice(0, 200) };
+    }
+    return out;
+}
+export function diffLock(lock, tools) {
+    const now = new Map(tools.map((t) => [t.name, t]));
+    const added = [...now.keys()].filter((n) => !lock.tools[n]);
+    const removed = Object.keys(lock.tools).filter((n) => !now.has(n));
+    const changed = [];
+    for (const [name, t] of now) {
+        const pinned = lock.tools[name];
+        if (!pinned)
+            continue;
+        const h = toolHash(t);
+        if (h !== pinned.hash)
+            changed.push({ name, before: pinned.hash, after: h, description_before: pinned.description, description_after: t.description?.slice(0, 200) });
+    }
+    return { added, removed, changed, clean: !added.length && !removed.length && !changed.length };
+}
+/**
+ * Compares tools against `lockPath`. Creates the lockfile on first use (trust-on-first-use) unless `frozen`.
+ * In "block" mode, changed and newly added tools are returned in `blocked`.
+ */
+export function checkPins(lockPath, tools, opts) {
+    if (!existsSync(lockPath)) {
+        if (opts.frozen) {
+            return { drift: { added: tools.map((t) => t.name), removed: [], changed: [], clean: false }, created: false, blocked: new Set(opts.mode === "block" ? tools.map((t) => t.name) : []) };
+        }
+        writeJsonAtomic(lockPath, buildLock(tools, opts.server));
+        return { drift: { added: [], removed: [], changed: [], clean: true }, created: true, blocked: new Set() };
+    }
+    const drift = diffLock(readJson(lockPath), tools);
+    const blocked = new Set(opts.mode === "block" ? [...drift.changed.map((c) => c.name), ...drift.added] : []);
+    return { drift, created: false, blocked };
+}

package/dist/guard/remote.d.ts

@@ -0,0 +1,78 @@
+import { type CompiledPolicy } from "../policy/engine.ts";
+import { type Revocation } from "../sts/revocation.ts";
+import type { JwtPayload } from "../sts/jwt.ts";
+import type { ApprovalRequest, NewApproval } from "../approvals/approvals.ts";
+import type { ActionRecord, LedgerSink, RecordInput } from "../ledger/ledger.ts";
+import type { ApprovalBroker, PolicySource, RevocationSource } from "./guard.ts";
+export interface ControlPlaneClientOptions {
+    url: string;
+    /** API key with the `service` role. */
+    apiKey: string;
+}
+/** Polls the control plane for revocations (default every 2 s, so revocation lands in <= ~3 s). */
+export declare class RemoteRevocations implements RevocationSource {
+    private list;
+    private lastOk;
+    private timer;
+    private o;
+    private staleAfterMs;
+    constructor(o: ControlPlaneClientOptions, intervalMs?: number, staleAfterMs?: number);
+    refresh(): Promise<void>;
+    check(claims: JwtPayload): Revocation | null;
+    stale(): boolean;
+    close(): void;
+}
+/** Policy pulled from the control plane (ETag polling) with an on-disk snapshot for cold starts offline. */
+export declare class RemotePolicy implements PolicySource {
+    private compiled;
+    private etag;
+    private timer;
+    private o;
+    private snapshotPath;
+    onChange?: (p: CompiledPolicy) => void;
+    constructor(o: ControlPlaneClientOptions, opts?: {
+        snapshotPath?: string;
+        intervalMs?: number;
+    });
+    refresh(): Promise<void>;
+    current(): CompiledPolicy;
+    close(): void;
+}
+/** Local policy file, hot-reloaded on change. An invalid edit keeps the previous policy. */
+export declare class FilePolicy implements PolicySource {
+    private compiled;
+    readonly path: string;
+    onChange?: (p: CompiledPolicy) => void;
+    onError?: (e: Error) => void;
+    constructor(path: string, watch?: boolean);
+    current(): CompiledPolicy;
+}
+export declare class RemoteApprovalBroker implements ApprovalBroker {
+    private o;
+    constructor(o: ControlPlaneClientOptions);
+    request(n: NewApproval): Promise<ApprovalRequest>;
+    /** Long-polls in <= 25 s slices until decided or `timeoutMs` elapses. */
+    wait(id: string, timeoutMs: number): Promise<ApprovalRequest | undefined>;
+    consume(id: string): Promise<boolean>;
+}
+/**
+ * Ships records to the control plane ledger. Asynchronous and batched (off the critical path), with
+ * at-least-once delivery: a batch stays queued until acknowledged. Records carry a client id, so the
+ * control plane de-duplicates retries.
+ */
+export declare class HttpLedgerSink implements LedgerSink {
+    private queue;
+    private timer;
+    private flushing;
+    private o;
+    private local?;
+    lastError: string | null;
+    constructor(o: ControlPlaneClientOptions, opts?: {
+        flushIntervalMs?: number;
+        local?: LedgerSink;
+    });
+    append(rec: RecordInput): ActionRecord | void;
+    flush(): Promise<void>;
+    get pending(): number;
+    close(): Promise<void>;
+}

package/dist/guard/remote.js

@@ -0,0 +1,185 @@
+// Guard <-> control plane clients. The data plane keeps working on its last snapshot when the
+// control plane is down (policy from cache file; revocations marked stale -> high-risk tools fail closed).
+import { existsSync, watchFile } from "node:fs";
+import { compilePolicy } from "../policy/engine.js";
+import { matchRevocation } from "../sts/revocation.js";
+import { readJson, writeJsonAtomic } from "../util.js";
+async function call(o, method, path, body, timeoutMs = 5000) {
+    const res = await fetch(o.url.replace(/\/$/, "") + path, {
+        method,
+        headers: { authorization: `Bearer ${o.apiKey}`, ...(body !== undefined ? { "content-type": "application/json" } : {}) },
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    const text = await res.text();
+    const data = text ? JSON.parse(text) : {};
+    if (!res.ok)
+        throw new Error(`${method} ${path}: ${res.status} ${data.error_description ?? data.error ?? text}`);
+    return data;
+}
+/** Polls the control plane for revocations (default every 2 s, so revocation lands in <= ~3 s). */
+export class RemoteRevocations {
+    list = [];
+    lastOk = 0;
+    timer;
+    o;
+    staleAfterMs;
+    constructor(o, intervalMs = 2000, staleAfterMs = 15_000) {
+        this.o = o;
+        this.staleAfterMs = staleAfterMs;
+        this.timer = setInterval(() => void this.refresh(), intervalMs);
+        this.timer.unref();
+    }
+    async refresh() {
+        try {
+            const r = await call(this.o, "GET", "/api/revocations", undefined, 3000);
+            this.list = r.revocations;
+            this.lastOk = Date.now();
+        }
+        catch { /* keep last snapshot; stale() reports it */ }
+    }
+    check(claims) { return matchRevocation(claims, this.list); }
+    stale() { return Date.now() - this.lastOk > this.staleAfterMs; }
+    close() { clearInterval(this.timer); }
+}
+/** Policy pulled from the control plane (ETag polling) with an on-disk snapshot for cold starts offline. */
+export class RemotePolicy {
+    compiled = null;
+    etag = null;
+    timer;
+    o;
+    snapshotPath;
+    onChange;
+    constructor(o, opts = {}) {
+        this.o = o;
+        this.snapshotPath = opts.snapshotPath ?? null;
+        if (this.snapshotPath && existsSync(this.snapshotPath)) {
+            try {
+                this.compiled = compilePolicy(readJson(this.snapshotPath));
+            }
+            catch { /* ignore bad snapshot */ }
+        }
+        this.timer = setInterval(() => void this.refresh(), opts.intervalMs ?? 5000);
+        this.timer.unref();
+    }
+    async refresh() {
+        try {
+            const res = await fetch(this.o.url.replace(/\/$/, "") + "/api/policy", {
+                headers: { authorization: `Bearer ${this.o.apiKey}`, ...(this.etag ? { "if-none-match": this.etag } : {}) },
+                signal: AbortSignal.timeout(3000),
+            });
+            if (res.status === 304 || !res.ok)
+                return;
+            const body = (await res.json());
+            const next = compilePolicy(body.policy);
+            this.compiled = next;
+            this.etag = res.headers.get("etag");
+            if (this.snapshotPath)
+                writeJsonAtomic(this.snapshotPath, body.policy);
+            this.onChange?.(next);
+        }
+        catch { /* keep last snapshot */ }
+    }
+    current() {
+        if (!this.compiled)
+            throw new Error("No policy available yet (control plane unreachable and no snapshot)");
+        return this.compiled;
+    }
+    close() { clearInterval(this.timer); }
+}
+/** Local policy file, hot-reloaded on change. An invalid edit keeps the previous policy. */
+export class FilePolicy {
+    compiled;
+    path;
+    onChange;
+    onError;
+    constructor(path, watch = true) {
+        this.path = path;
+        this.compiled = compilePolicy(readJson(path));
+        if (watch) {
+            watchFile(path, { interval: 1000, persistent: false }, () => {
+                try {
+                    this.compiled = compilePolicy(readJson(path));
+                    this.onChange?.(this.compiled);
+                }
+                catch (e) {
+                    (this.onError ?? ((err) => console.error(`[mandat] policy reload failed, keeping previous version: ${err.message}`)))(e);
+                }
+            });
+        }
+    }
+    current() { return this.compiled; }
+}
+export class RemoteApprovalBroker {
+    o;
+    constructor(o) { this.o = o; }
+    request(n) {
+        return call(this.o, "POST", "/api/approvals", n);
+    }
+    /** Long-polls in <= 25 s slices until decided or `timeoutMs` elapses. */
+    async wait(id, timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        let cur;
+        do {
+            const slice = Math.max(0, Math.min(25_000, deadline - Date.now()));
+            cur = await call(this.o, "GET", `/api/approvals/${encodeURIComponent(id)}?wait=${slice}`, undefined, slice + 5000);
+        } while (cur.status === "pending" && Date.now() < deadline);
+        return cur;
+    }
+    async consume(id) {
+        const r = await call(this.o, "POST", `/api/approvals/${encodeURIComponent(id)}/consume`, {});
+        return r.consumed;
+    }
+}
+/**
+ * Ships records to the control plane ledger. Asynchronous and batched (off the critical path), with
+ * at-least-once delivery: a batch stays queued until acknowledged. Records carry a client id, so the
+ * control plane de-duplicates retries.
+ */
+export class HttpLedgerSink {
+    queue = [];
+    timer;
+    flushing = null;
+    o;
+    local;
+    lastError = null;
+    constructor(o, opts = {}) {
+        this.o = o;
+        this.local = opts.local;
+        this.timer = setInterval(() => void this.flush(), opts.flushIntervalMs ?? 500);
+        this.timer.unref();
+    }
+    append(rec) {
+        const withId = { ...rec, id: rec.id ?? `rec_${crypto.randomUUID()}`, ts: rec.ts ?? new Date().toISOString() };
+        this.queue.push(withId);
+        if (this.queue.length > 100_000)
+            this.queue.shift();
+        return this.local?.append(withId);
+    }
+    flush() {
+        if (this.flushing)
+            return this.flushing;
+        if (!this.queue.length)
+            return Promise.resolve();
+        const run = async () => {
+            try {
+                while (this.queue.length) {
+                    const batch = this.queue.slice(0, 200);
+                    await call(this.o, "POST", "/api/ledger/ingest", { records: batch });
+                    this.queue.splice(0, batch.length);
+                }
+                this.lastError = null;
+            }
+            catch (e) {
+                this.lastError = e.message; // retried on the next tick
+            }
+        };
+        this.flushing = run().finally(() => { this.flushing = null; });
+        return this.flushing;
+    }
+    get pending() { return this.queue.length; }
+    async close() {
+        clearInterval(this.timer);
+        await this.flush();
+    }
+}