mandat 0.0.0-stage → 0.1.0

package/dist/controlplane/server.js

@@ -0,0 +1,427 @@
+// Mandat control plane: STS + approvals + revocation + policy distribution + ledger + console.
+// The data plane (Guard) never needs it on the decision path except for approvals.
+import { createServer } from "node:http";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { hashApiKey } from "./config.js";
+import { Sts, OAuthError, hashSecret, GRANT_TOKEN_EXCHANGE } from "../sts/sts.js";
+import { loadOrCreateSigningKey } from "../sts/jwt.js";
+import { JsonCollection } from "../store.js";
+import { FileLedger, queryRecords, verifyLedger } from "../ledger/ledger.js";
+import { OtlpExporter, toOcsf, toOtelSpan } from "../ledger/export.js";
+import { buildReport, reportToMarkdown } from "../ledger/report.js";
+import { ApprovalError, ApprovalService, ConsoleLogNotifier, SlackNotifier, WebhookNotifier, handleSlackInteraction, verifySlackSignature } from "../approvals/approvals.js";
+import { compilePolicy, PolicyError } from "../policy/engine.js";
+import { HttpError, readBody, readJson, randomId, safeEqual, sendJson, writeJsonAtomic, parseDuration, nowSeconds } from "../util.js";
+const CONSOLE_DIR = fileURLToPath(new URL("./console/", import.meta.url));
+const asset = (name) => readFileSync(join(CONSOLE_DIR, name), "utf8");
+const REVOCATION_TYPES = ["jti", "agent", "agent_version", "subject", "task", "tenant"];
+export function createControlPlane(config) {
+    const issuer = config.issuer.replace(/\/$/, "");
+    const consoleUrl = `${issuer}/console`;
+    const key = loadOrCreateSigningKey(join(config.dataDir, "keys"));
+    const ledger = new FileLedger(join(config.dataDir, "ledger.jsonl"));
+    const agents = new JsonCollection(join(config.dataDir, "agents.json"));
+    const revocations = new JsonCollection(join(config.dataDir, "revocations.json"));
+    const otlp = config.ledger?.otlp ? new OtlpExporter({ ...config.ledger.otlp, serviceName: "mandat-control-plane" }) : null;
+    if (otlp)
+        ledger.onAppend((r) => otlp.push(r));
+    // Ids already in the ledger, so retried ingest batches are not duplicated (at-least-once -> exactly-once).
+    const seen = new Set(ledger.read().map((r) => r.id));
+    ledger.onAppend((r) => seen.add(r.id));
+    if (!existsSync(config.policyFile))
+        throw new Error(`Policy file not found: ${config.policyFile} (run \`mandat init\`)`);
+    let policyDoc = readJson(config.policyFile);
+    let policy = compilePolicy(policyDoc);
+    const notifiers = [];
+    if (config.approvals?.log !== false)
+        notifiers.push(new ConsoleLogNotifier());
+    if (config.approvals?.slack?.webhookUrl)
+        notifiers.push(new SlackNotifier({ webhookUrl: config.approvals.slack.webhookUrl, consoleUrl }));
+    for (const w of config.approvals?.webhooks ?? [])
+        notifiers.push(new WebhookNotifier({ ...w, consoleUrl }));
+    const approvals = new ApprovalService({ path: join(config.dataDir, "approvals.json"), notifiers, ledger });
+    const sts = new Sts({
+        issuer,
+        key,
+        agents: () => agents.all(),
+        revocations: () => revocations.all(),
+        trustedIssuers: config.trustedIssuers ?? [],
+        devIdp: config.devIdp,
+        defaultTtlSeconds: config.tokenTtlSeconds,
+        maxTtlSeconds: config.maxTokenTtlSeconds,
+        onIssued: (t) => ledger.append({
+            type: "token.issued",
+            source: "control-plane",
+            principal: { sub: t.sub, tenant: t.tenant },
+            agent: { id: t.agent, version: t.agent_version },
+            actor_chain: t.actor_chain,
+            task_id: t.task_id,
+            token_jti: t.jti,
+            details: { aud: t.aud, exp: new Date(t.exp * 1000).toISOString(), authorization_details: t.authorization_details },
+        }),
+    });
+    const keys = config.apiKeys;
+    const authenticate = (req, roles) => {
+        const h = req.headers.authorization;
+        const token = h?.startsWith("Bearer ") ? h.slice(7).trim() : undefined;
+        if (!token)
+            throw new HttpError(401, "unauthorized", "API key required", { "www-authenticate": 'Bearer realm="mandat"' });
+        const hash = hashApiKey(token);
+        const k = keys.find((x) => safeEqual(x.hash, hash));
+        if (!k)
+            throw new HttpError(401, "unauthorized", "Invalid API key");
+        if (!k.roles.some((r) => roles.includes(r)))
+            throw new HttpError(403, "forbidden", `Requires role: ${roles.join(" or ")}`);
+        return k;
+    };
+    const adminEvent = (type, by, details) => ledger.append({ type, source: "control-plane", principal: { sub: by }, details });
+    const asMetadata = () => ({
+        issuer,
+        token_endpoint: `${issuer}/oauth/token`,
+        jwks_uri: `${issuer}/.well-known/jwks.json`,
+        grant_types_supported: [GRANT_TOKEN_EXCHANGE],
+        token_endpoint_auth_methods_supported: ["client_secret_basic", "client_secret_post"],
+        response_types_supported: [],
+        code_challenge_methods_supported: ["S256"],
+        authorization_response_iss_parameter_supported: true,
+        client_id_metadata_document_supported: false,
+        authorization_details_types_supported: ["mandat_tool_call"],
+        token_endpoint_auth_signing_alg_values_supported: [key.alg],
+        service_documentation: `${issuer}/console`,
+        mandat_api: `${issuer}/api`,
+    });
+    async function route(req, res) {
+        const url = new URL(req.url ?? "/", issuer);
+        const p = url.pathname;
+        const m = req.method ?? "GET";
+        const json = async () => {
+            const text = await readBody(req);
+            try {
+                return (text ? JSON.parse(text) : {});
+            }
+            catch {
+                throw new HttpError(400, "invalid_json", "Body must be JSON");
+            }
+        };
+        // ----- public -----
+        if (m === "GET" && p === "/favicon.ico") {
+            res.writeHead(204).end();
+            return;
+        }
+        if (m === "GET" && p === "/healthz")
+            return sendJson(res, 200, { ok: true, ledger: { records: ledger.length, head: ledger.headHash } });
+        if (m === "GET" && (p === "/.well-known/oauth-authorization-server" || p === "/.well-known/openid-configuration"))
+            return sendJson(res, 200, asMetadata(), { "cache-control": "public, max-age=300" });
+        if (m === "GET" && p === "/.well-known/jwks.json")
+            return sendJson(res, 200, { keys: [key.publicJwk] }, { "cache-control": "public, max-age=300" });
+        if (m === "GET" && (p === "/" || p === "/console")) {
+            res.writeHead(200, {
+                "content-type": "text/html; charset=utf-8",
+                "content-security-policy": "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; frame-ancestors 'none'",
+                "x-frame-options": "DENY",
+                "referrer-policy": "no-referrer",
+            });
+            res.end(asset("index.html"));
+            return;
+        }
+        if (m === "GET" && p === "/console.js") {
+            res.writeHead(200, { "content-type": "text/javascript; charset=utf-8" });
+            res.end(asset("app.js"));
+            return;
+        }
+        if (m === "GET" && p === "/console.css") {
+            res.writeHead(200, { "content-type": "text/css; charset=utf-8" });
+            res.end(asset("app.css"));
+            return;
+        }
+        if (m === "POST" && p === "/oauth/token") {
+            const form = new URLSearchParams(await readBody(req));
+            let id = form.get("client_id") ?? undefined;
+            let secret = form.get("client_secret") ?? undefined;
+            const basic = req.headers.authorization?.match(/^Basic\s+(.+)$/i)?.[1];
+            if (basic) {
+                const [u, s] = Buffer.from(basic, "base64").toString("utf8").split(":");
+                id = decodeURIComponent(u ?? "");
+                secret = decodeURIComponent(s ?? "");
+            }
+            try {
+                return sendJson(res, 200, await sts.exchange(form, { id, secret }), { pragma: "no-cache" });
+            }
+            catch (e) {
+                if (e instanceof OAuthError)
+                    return sendJson(res, e.status, { error: e.error, error_description: e.message }, e.status === 401 ? { "www-authenticate": 'Basic realm="mandat"' } : {});
+                throw e;
+            }
+        }
+        if (m === "POST" && p === "/dev/login") {
+            if (!config.devIdp)
+                throw new HttpError(404, "not_found", "Dev IdP disabled");
+            const b = await json();
+            if (!b.sub)
+                throw new HttpError(400, "invalid_request", "sub is required");
+            return sendJson(res, 200, { id_token: sts.devLogin({ sub: b.sub, email: b.email, name: b.name, tenant: b.tenant }), token_type: "urn:ietf:params:oauth:token-type:id_token" });
+        }
+        if (m === "POST" && p === "/slack/interactions") {
+            const raw = await readBody(req);
+            const secret = config.approvals?.slack?.signingSecret;
+            if (!secret || !verifySlackSignature(raw, req.headers["x-slack-request-timestamp"], req.headers["x-slack-signature"], secret))
+                throw new HttpError(401, "bad_signature", "Invalid Slack signature");
+            return sendJson(res, 200, handleSlackInteraction(approvals, raw, consoleUrl));
+        }
+        if (!p.startsWith("/api/"))
+            throw new HttpError(404, "not_found", "Not found");
+        // ----- API -----
+        if (m === "GET" && p === "/api/whoami") {
+            const k = authenticate(req, ["admin", "approver", "auditor", "service"]);
+            return sendJson(res, 200, { id: k.id, roles: k.roles, issuer });
+        }
+        if (p === "/api/revocations") {
+            if (m === "GET") {
+                authenticate(req, ["service", "admin", "auditor"]);
+                return sendJson(res, 200, { revocations: revocations.all(), now: nowSeconds() });
+            }
+            if (m === "POST") {
+                const k = authenticate(req, ["admin"]);
+                const b = await json();
+                if (!b.type || !REVOCATION_TYPES.includes(b.type))
+                    throw new HttpError(400, "invalid_request", `type must be one of ${REVOCATION_TYPES.join(", ")}`);
+                if (!b.value)
+                    throw new HttpError(400, "invalid_request", "value is required");
+                if (b.type === "agent_version" && !b.version)
+                    throw new HttpError(400, "invalid_request", "version is required for agent_version");
+                const r = {
+                    id: randomId("rev_", 8), type: b.type, value: b.value, version: b.version,
+                    issued_before: nowSeconds(), blocks_issuance: b.block_issuance ?? b.type !== "jti",
+                    created_at: new Date().toISOString(), reason: b.reason, by: k.id,
+                };
+                revocations.put(r);
+                adminEvent("revocation.created", k.id, { ...r });
+                return sendJson(res, 201, r);
+            }
+        }
+        const revMatch = /^\/api\/revocations\/([\w-]+)$/.exec(p);
+        if (revMatch && m === "DELETE") {
+            const k = authenticate(req, ["admin"]);
+            const r = revocations.update(revMatch[1], (x) => ({ ...x, blocks_issuance: false }));
+            if (!r)
+                throw new HttpError(404, "not_found", "Revocation not found");
+            adminEvent("revocation.lifted", k.id, { id: r.id, type: r.type, value: r.value, note: "New tokens may be issued; tokens issued before the revocation stay invalid." });
+            return sendJson(res, 200, r);
+        }
+        if (p === "/api/policy") {
+            if (m === "GET") {
+                authenticate(req, ["service", "admin", "auditor"]);
+                const etag = `"${policy.version}"`;
+                if (req.headers["if-none-match"] === etag) {
+                    res.writeHead(304, { etag }).end();
+                    return;
+                }
+                return sendJson(res, 200, { version: policy.version, policy: policyDoc }, { etag });
+            }
+            if (m === "PUT") {
+                const k = authenticate(req, ["admin"]);
+                const b = await json();
+                let next;
+                try {
+                    next = compilePolicy(b.policy);
+                }
+                catch (e) {
+                    if (e instanceof PolicyError)
+                        throw new HttpError(422, "invalid_policy", e.message);
+                    throw e;
+                }
+                const before = policy.version;
+                const beforeRules = new Set(policyDoc.rules.map((r) => r.id));
+                const afterRules = new Set(b.policy.rules.map((r) => r.id));
+                writeJsonAtomic(config.policyFile, b.policy);
+                policyDoc = b.policy;
+                policy = next;
+                adminEvent("policy.changed", k.id, {
+                    from_version: before, to_version: next.version, comment: b.comment,
+                    rules_added: [...afterRules].filter((x) => !beforeRules.has(x)),
+                    rules_removed: [...beforeRules].filter((x) => !afterRules.has(x)),
+                });
+                return sendJson(res, 200, { version: next.version });
+            }
+        }
+        if (p === "/api/agents") {
+            if (m === "GET") {
+                authenticate(req, ["admin", "auditor", "approver"]);
+                const revs = revocations.all();
+                return sendJson(res, 200, {
+                    agents: agents.all().map(({ secret_hash: _s, ...a }) => ({
+                        ...a,
+                        revoked: revs.some((r) => r.blocks_issuance && (r.type === "agent" || r.type === "agent_version") && r.value === a.id),
+                    })),
+                });
+            }
+            if (m === "POST") {
+                const k = authenticate(req, ["admin"]);
+                const b = await json();
+                if (!b.id || !/^[a-z0-9][a-z0-9._-]{1,62}$/.test(b.id))
+                    throw new HttpError(400, "invalid_request", "id must match ^[a-z0-9][a-z0-9._-]{1,62}$");
+                if (agents.get(b.id))
+                    throw new HttpError(409, "conflict", "Agent already exists");
+                if (!Array.isArray(b.allowed_tools) || !b.allowed_tools.length)
+                    throw new HttpError(400, "invalid_request", "allowed_tools is required (least privilege)");
+                const secret = `mdt_as_${randomId("", 24)}`;
+                const rec = {
+                    id: b.id, name: b.name, owner: b.owner ?? k.id, secret_hash: hashSecret(secret),
+                    allowed_tools: b.allowed_tools, allowed_resources: b.allowed_resources ?? [], versions: b.versions ?? [],
+                    max_ttl_seconds: b.max_ttl_seconds, created_at: new Date().toISOString(),
+                };
+                agents.put(rec);
+                adminEvent("agent.registered", k.id, { agent: rec.id, allowed_tools: rec.allowed_tools, allowed_resources: rec.allowed_resources, versions: rec.versions });
+                const { secret_hash: _s, ...pub } = rec;
+                return sendJson(res, 201, { ...pub, client_secret: secret, note: "Store the client_secret now; it is not shown again." });
+            }
+        }
+        const agentMatch = /^\/api\/agents\/([\w.-]+)$/.exec(p);
+        if (agentMatch && m === "PATCH") {
+            const k = authenticate(req, ["admin"]);
+            const b = await json();
+            const allowed = ["name", "allowed_tools", "allowed_resources", "versions", "max_ttl_seconds", "disabled"];
+            const patch = Object.fromEntries(Object.entries(b).filter(([kk]) => allowed.includes(kk)));
+            const r = agents.update(agentMatch[1], (a) => ({ ...a, ...patch }));
+            if (!r)
+                throw new HttpError(404, "not_found", "Agent not found");
+            adminEvent("agent.updated", k.id, { agent: r.id, changes: patch });
+            const { secret_hash: _s, ...pub } = r;
+            return sendJson(res, 200, pub);
+        }
+        if (p === "/api/approvals") {
+            if (m === "POST") {
+                authenticate(req, ["service"]);
+                const b = await json();
+                if (!b.binding || !b.context?.tool || !b.context?.principal?.sub)
+                    throw new HttpError(400, "invalid_request", "binding and context are required");
+                const timeoutMs = Math.min(b.timeoutMs ?? parseDuration(config.approvals?.defaultTimeout ?? "10m"), 24 * 3_600_000);
+                return sendJson(res, 201, await approvals.create({ ...b, timeoutMs, required: b.required ?? 1, channels: b.channels ?? [] }));
+            }
+            if (m === "GET") {
+                authenticate(req, ["approver", "admin", "auditor", "service"]);
+                const status = url.searchParams.get("status");
+                return sendJson(res, 200, { approvals: approvals.list(status || undefined).slice(0, 200) });
+            }
+        }
+        const apr = /^\/api\/approvals\/([\w-]+)(?:\/(approve|deny|consume))?$/.exec(p);
+        if (apr) {
+            const [, id, action] = apr;
+            if (!action && m === "GET") {
+                authenticate(req, ["approver", "admin", "auditor", "service"]);
+                const wait = Math.min(Number(url.searchParams.get("wait") ?? 0) || 0, 30_000);
+                const r = wait ? await approvals.wait(id, wait) : approvals.get(id);
+                if (!r)
+                    throw new HttpError(404, "not_found", "Approval not found");
+                return sendJson(res, 200, r);
+            }
+            if ((action === "approve" || action === "deny") && m === "POST") {
+                const k = authenticate(req, ["approver", "admin"]);
+                const b = await json();
+                return sendJson(res, 200, approvals.decide(id, { by: k.id, decision: action, via: "api", comment: b.comment }));
+            }
+            if (action === "consume" && m === "POST") {
+                authenticate(req, ["service"]);
+                return sendJson(res, 200, { consumed: approvals.consume(id) });
+            }
+        }
+        if (m === "POST" && p === "/api/ledger/ingest") {
+            const k = authenticate(req, ["service"]);
+            const b = await json();
+            if (!Array.isArray(b.records) || b.records.length > 1000)
+                throw new HttpError(400, "invalid_request", "records: array of <= 1000");
+            let appended = 0;
+            for (const r of b.records) {
+                if (r.id && seen.has(r.id))
+                    continue;
+                if (!r.type)
+                    continue;
+                ledger.append({ ...r, source: r.source ?? k.id });
+                appended++;
+            }
+            return sendJson(res, 200, { appended, head: ledger.headHash });
+        }
+        if (m === "GET" && p === "/api/ledger") {
+            authenticate(req, ["auditor", "admin", "approver"]);
+            const q = Object.fromEntries(url.searchParams);
+            q.limit = Math.min(Number(url.searchParams.get("limit") ?? 100) || 100, 1000);
+            return sendJson(res, 200, { records: queryRecords(ledger.read(), q), head: ledger.headHash, count: ledger.length });
+        }
+        if (m === "GET" && p === "/api/ledger/verify") {
+            authenticate(req, ["auditor", "admin"]);
+            return sendJson(res, 200, verifyLedger(ledger.path));
+        }
+        if (m === "GET" && p === "/api/ledger/export") {
+            authenticate(req, ["auditor", "admin"]);
+            const fmt = url.searchParams.get("format") ?? "ocsf";
+            const recs = queryRecords(ledger.read(), { ...Object.fromEntries(url.searchParams), order: "asc" });
+            const map = fmt === "otel" ? toOtelSpan : fmt === "raw" ? (r) => r : toOcsf;
+            res.writeHead(200, { "content-type": "application/x-ndjson", "content-disposition": `attachment; filename="mandat-${fmt}.ndjson"` });
+            res.end(recs.map((r) => JSON.stringify(map(r))).join("\n") + "\n");
+            return;
+        }
+        if (m === "GET" && p === "/api/report") {
+            authenticate(req, ["auditor", "admin"]);
+            const data = buildReport(ledger.read(), { from: url.searchParams.get("from") ?? undefined, to: url.searchParams.get("to") ?? undefined, retentionDays: config.ledger?.retentionDays });
+            if (url.searchParams.get("format") === "json")
+                return sendJson(res, 200, data);
+            res.writeHead(200, { "content-type": "text/markdown; charset=utf-8" });
+            res.end(reportToMarkdown(data));
+            return;
+        }
+        if (m === "GET" && p === "/api/stats") {
+            authenticate(req, ["auditor", "admin", "approver"]);
+            const recs = ledger.read();
+            const since = new Date(Date.now() - 24 * 3_600_000).toISOString();
+            const calls = recs.filter((r) => r.type === "agent.tool_call" && r.ts >= since);
+            return sendJson(res, 200, {
+                last_24h: {
+                    calls: calls.length,
+                    allowed: calls.filter((c) => c.decision?.final === "allow").length,
+                    denied: calls.filter((c) => c.decision?.final === "deny").length,
+                    pending: calls.filter((c) => c.decision?.final === "pending").length,
+                    p99_decision_us: percentile(calls.map((c) => c.decision?.latency_us ?? 0), 0.99),
+                },
+                pending_approvals: approvals.list("pending").length,
+                agents: agents.all().length,
+                active_revocations: revocations.filter((r) => r.blocks_issuance).length,
+                policy_version: policy.version,
+                ledger: { records: ledger.length, head: ledger.headHash },
+            });
+        }
+        throw new HttpError(404, "not_found", "Not found");
+    }
+    const server = createServer(async (req, res) => {
+        try {
+            await route(req, res);
+        }
+        catch (e) {
+            if (e instanceof HttpError)
+                return sendJson(res, e.status, { error: e.code, error_description: e.message }, e.headers);
+            if (e instanceof ApprovalError)
+                return sendJson(res, e.status, { error: "approval_error", error_description: e.message });
+            console.error("[mandat] internal error:", e);
+            return sendJson(res, 500, { error: "server_error", error_description: "Internal error" });
+        }
+    });
+    return {
+        server, sts, approvals, ledger, key, config,
+        listen: () => new Promise((resolve, reject) => server.once("error", (e) => reject(e.code === "EADDRINUSE" ? new Error(`Port ${config.port} is already in use (another \`mandat serve\`?). Use --port or change "port" in the config.`) : e)).listen(config.port, config.host ?? "127.0.0.1", () => {
+            const addr = server.address();
+            resolve(typeof addr === "object" && addr ? `http://${config.host ?? "127.0.0.1"}:${addr.port}` : issuer);
+        })),
+        close: async () => {
+            approvals.close();
+            await otlp?.close();
+            await new Promise((r) => { server.close(() => r()); server.closeAllConnections(); });
+        },
+    };
+}
+function percentile(xs, p) {
+    if (!xs.length)
+        return 0;
+    const s = [...xs].sort((a, b) => a - b);
+    return s[Math.min(s.length - 1, Math.floor(p * s.length))];
+}

package/dist/guard/guard.d.ts

@@ -0,0 +1,154 @@
+import type { KeyObject } from "node:crypto";
+import { type JwtPayload } from "../sts/jwt.ts";
+import { type Revocation } from "../sts/revocation.ts";
+import { type AuthorizationDetail, type CompiledPolicy, type Decision } from "../policy/engine.ts";
+import { type ApprovalRequest, type ApprovalService, type NewApproval } from "../approvals/approvals.ts";
+import { type RedactionOptions } from "../ledger/redact.ts";
+import type { ActionRecord, LedgerSink } from "../ledger/ledger.ts";
+import { type DriftReport, type ToolDefinition } from "./pinning.ts";
+export interface PolicySource {
+    current(): CompiledPolicy;
+}
+export interface RevocationSource {
+    check(claims: JwtPayload): Revocation | null;
+    /** True when the revocation list could not be refreshed recently (control plane unreachable). */
+    stale(): boolean;
+}
+export interface ApprovalBroker {
+    request(n: NewApproval): Promise<ApprovalRequest>;
+    wait(id: string, timeoutMs: number): Promise<ApprovalRequest | undefined>;
+    consume(id: string): Promise<boolean>;
+}
+export declare class StaticPolicy implements PolicySource {
+    private p;
+    constructor(p: CompiledPolicy);
+    current(): CompiledPolicy;
+    set(p: CompiledPolicy): void;
+}
+export declare class LocalRevocations implements RevocationSource {
+    private list;
+    constructor(list: () => Iterable<Revocation>);
+    check(claims: JwtPayload): Revocation | null;
+    stale(): boolean;
+}
+export declare class LocalApprovalBroker implements ApprovalBroker {
+    private svc;
+    constructor(svc: ApprovalService);
+    request(n: NewApproval): Promise<ApprovalRequest>;
+    wait(id: string, ms: number): Promise<ApprovalRequest | undefined>;
+    consume(id: string): Promise<boolean>;
+}
+export interface VerifiedAuth {
+    token: string;
+    claims: JwtPayload;
+    principal: {
+        sub: string;
+        tenant: string | null;
+        email: string | null;
+    };
+    agent: {
+        id: string;
+        version: string | null;
+        prompt_hash: string | null;
+    };
+    actor_chain: string[];
+    task_id: string | null;
+    session_id: string | null;
+    authorization_details: AuthorizationDetail[] | null;
+}
+export interface GuardOptions {
+    /** Canonical URL of this MCP server; tokens must carry it in `aud`. */
+    resource: string;
+    /** Mandat issuer (control plane URL). */
+    issuer: string;
+    /** JWKS of the issuer. Default `${issuer}/.well-known/jwks.json`. Ignored if `publicKey` is set. */
+    jwksUri?: string;
+    publicKey?: KeyObject;
+    policy: PolicySource;
+    revocations: RevocationSource;
+    approvals: ApprovalBroker;
+    ledger: LedgerSink;
+    /** "shadow": decide and log, but never block (for rolling out new policies). */
+    mode?: "enforce" | "shadow";
+    /** How long a tool call blocks waiting for a human before returning "pending". Default 20 s. */
+    approvalWaitMs?: number;
+    pinning?: {
+        lockfile: string;
+        mode?: "warn" | "block";
+        frozen?: boolean;
+    };
+    redaction?: RedactionOptions;
+    /** Name of this guard instance in ledger records. */
+    source?: string;
+    /** Called on drift, denials etc. Default: console.warn. */
+    log?: (msg: string) => void;
+}
+export interface CallContext {
+    auth: VerifiedAuth;
+    tool: string;
+    args: Record<string, unknown>;
+    /** Transport-level session (e.g. Mcp-Session-Id). Falls back to token session / task id. */
+    sessionId?: string | null;
+}
+export declare class AuthError extends Error {
+    status: number;
+    code: string;
+    constructor(code: string, message: string, status?: number);
+}
+export declare class GuardDenied extends Error {
+    code: "denied" | "approval_pending" | "approval_denied" | "revoked" | "drift" | "fail_closed";
+    decision: Decision | null;
+    record: ActionRecord | void;
+    approvalId?: string;
+    constructor(code: GuardDenied["code"], message: string, decision: Decision | null, record: ActionRecord | void, approvalId?: string);
+}
+interface SessionState {
+    tainted: boolean;
+    taint_sources: string[];
+    calls: number;
+    touched: number;
+}
+export declare class Guard {
+    readonly opts: GuardOptions;
+    private jwks;
+    private sessions;
+    private toolDefs;
+    private blockedTools;
+    private log;
+    constructor(opts: GuardOptions);
+    /** RFC 9728 Protected Resource Metadata for this server. */
+    protectedResourceMetadata(extra?: Record<string, unknown>): Record<string, unknown>;
+    /** Verifies a bearer token. Throws AuthError (map to HTTP 401/403 + WWW-Authenticate). */
+    verify(token: string | undefined): Promise<VerifiedAuth>;
+    /**
+     * OAuthTokenVerifier for the official MCP SDK's `requireBearerAuth`. Pass the SDK's InvalidTokenError
+     * so failures become proper 401 responses.
+     */
+    sdkTokenVerifier(errors?: {
+        InvalidTokenError?: new (msg: string) => Error;
+    }): {
+        verifyAccessToken: (token: string) => Promise<{
+            token: string;
+            clientId: string;
+            scopes: string[];
+            expiresAt: number | undefined;
+            resource: URL;
+            extra: {
+                mandat: VerifiedAuth;
+            };
+        }>;
+    };
+    /** Register the server's tool definitions: computes hashes and checks them against the pin lockfile. */
+    registerTools(defs: ToolDefinition[]): DriftReport | null;
+    /**
+     * Authorises and executes one tool call. Returns the handler's result, or throws GuardDenied.
+     * Exactly one `agent.tool_call` record is written per invocation.
+     */
+    execute<T>(ctx: CallContext, handler: () => Promise<T> | T): Promise<T>;
+    /** Session taint state (for tests / introspection). */
+    sessionState(key: string): SessionState | undefined;
+    private session;
+    private redactArgs;
+    private append;
+}
+export {};