mandat 0.0.0-stage → 0.1.0

package/dist/approvals/approvals.js

@@ -0,0 +1,262 @@
+// Human-in-the-loop approvals.
+//
+// An approval is bound to the exact call (sha256 over principal, agent, tool, server, args), so approving
+// "refund €120 to order 42" can never authorise a different refund. Approved requests are single-use.
+// Self-approval is forbidden; `required: 2` gives four-eyes. Timeout => expired => deny.
+import { EventEmitter } from "node:events";
+import { createHmac } from "node:crypto";
+import { JsonCollection } from "../store.js";
+import { canonicalJson, randomId, safeEqual, sha256 } from "../util.js";
+export function approvalBinding(p) {
+    return sha256(canonicalJson({ sub: p.sub, agent: p.agent, tool: p.tool, server: p.server ?? null, args: p.args ?? {} }));
+}
+export class ApprovalError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+export class ApprovalService {
+    store;
+    events = new EventEmitter();
+    notifiers;
+    ledger;
+    sweeper;
+    constructor(opts) {
+        this.store = new JsonCollection(opts.path);
+        this.notifiers = opts.notifiers ?? [];
+        this.ledger = opts.ledger;
+        this.events.setMaxListeners(0);
+        this.sweeper = setInterval(() => this.expireDue(), 1000);
+        this.sweeper.unref();
+    }
+    close() { clearInterval(this.sweeper); }
+    get(id) {
+        this.expireDue();
+        return this.store.get(id);
+    }
+    list(status) {
+        this.expireDue();
+        return this.store.filter((a) => !status || a.status === status).sort((a, b) => b.created_at.localeCompare(a.created_at));
+    }
+    /** Creates a request, or returns the live one with the same binding (pending, or approved and unused). */
+    async create(n) {
+        this.expireDue();
+        const existing = this.store.filter((a) => a.binding === n.binding && !a.consumed_at && (a.status === "pending" || a.status === "approved"))[0];
+        if (existing)
+            return existing;
+        const now = Date.now();
+        const req = {
+            id: randomId("apr_", 9),
+            binding: n.binding,
+            status: "pending",
+            required: Math.max(1, Math.min(n.required, 5)),
+            created_at: new Date(now).toISOString(),
+            expires_at: new Date(now + n.timeoutMs).toISOString(),
+            decided_at: null,
+            consumed_at: null,
+            votes: [],
+            channels: n.channels,
+            context: n.context,
+        };
+        this.store.put(req);
+        this.ledger?.append({
+            type: "approval.requested",
+            principal: n.context.principal,
+            agent: n.context.agent,
+            actor_chain: n.context.actor_chain,
+            task_id: n.context.task_id,
+            tool: { name: n.context.tool, server: n.context.server, risk: n.context.risk },
+            args: n.context.args,
+            approval: { id: req.id, status: "pending", required: req.required },
+            details: { rule: n.context.rule, reasons: n.context.reasons, expires_at: req.expires_at },
+        });
+        const targets = n.channels.length ? this.notifiers.filter((x) => n.channels.includes(x.name)) : this.notifiers;
+        await Promise.allSettled(targets.map((x) => x.notify(req)));
+        return req;
+    }
+    decide(id, vote) {
+        const req = this.get(id);
+        if (!req)
+            throw new ApprovalError(404, "Approval request not found");
+        if (req.status !== "pending")
+            throw new ApprovalError(409, `Approval is already ${req.status}`);
+        if (!vote.by)
+            throw new ApprovalError(400, "Approver identity is required");
+        if (vote.by === req.context.principal.sub || vote.by === req.context.principal.email)
+            throw new ApprovalError(403, "Self-approval is not allowed: the requesting principal cannot approve their own agent's action");
+        if (req.votes.some((v) => v.by === vote.by))
+            throw new ApprovalError(409, `${vote.by} has already voted`);
+        const votes = [...req.votes, { ...vote, at: new Date().toISOString() }];
+        const approvals = votes.filter((v) => v.decision === "approve").length;
+        const status = vote.decision === "deny" ? "denied" : approvals >= req.required ? "approved" : "pending";
+        const next = this.store.update(id, (r) => ({ ...r, votes, status, decided_at: status === "pending" ? null : new Date().toISOString() }));
+        if (status !== "pending")
+            this.finalised(next);
+        return next;
+    }
+    /** Marks an approved request as used. Returns false if it was already used (replay). */
+    consume(id) {
+        const req = this.get(id);
+        if (!req || req.status !== "approved" || req.consumed_at)
+            return false;
+        this.store.update(id, (r) => ({ ...r, consumed_at: new Date().toISOString() }));
+        return true;
+    }
+    /** Resolves when the request leaves `pending` or after `timeoutMs` (returning the current state). */
+    wait(id, timeoutMs) {
+        const cur = this.get(id);
+        if (!cur || cur.status !== "pending" || timeoutMs <= 0)
+            return Promise.resolve(cur);
+        return new Promise((resolve) => {
+            const done = () => { clearTimeout(t); this.events.off(id, done); resolve(this.store.get(id)); };
+            const t = setTimeout(done, Math.min(timeoutMs, Date.parse(cur.expires_at) - Date.now() + 50));
+            this.events.on(id, done);
+        });
+    }
+    expireDue() {
+        const now = new Date().toISOString();
+        for (const r of this.store.filter((a) => a.status === "pending" && a.expires_at <= now)) {
+            const next = this.store.update(r.id, (x) => ({ ...x, status: "expired", decided_at: now }));
+            this.finalised(next);
+        }
+    }
+    finalised(req) {
+        this.ledger?.append({
+            type: "approval.decided",
+            principal: req.context.principal,
+            agent: req.context.agent,
+            actor_chain: req.context.actor_chain,
+            task_id: req.context.task_id,
+            tool: { name: req.context.tool, server: req.context.server, risk: req.context.risk },
+            approval: {
+                id: req.id, status: req.status, required: req.required, decided_at: req.decided_at,
+                approvers: req.votes.filter((v) => v.decision === "approve").map((v) => v.by),
+            },
+            details: { votes: req.votes },
+        });
+        this.events.emit(req.id);
+        for (const n of this.notifiers)
+            void n.decided?.(req).catch(() => { });
+    }
+}
+// ---------- channels ----------
+function summary(req) {
+    const c = req.context;
+    return `${c.agent.id} wants to call ${c.tool} on behalf of ${c.principal.email ?? c.principal.sub}`;
+}
+/** Generic signed webhook: POST JSON, `X-Mandat-Signature: sha256=<hmac(timestamp + "." + body)>`. */
+export class WebhookNotifier {
+    name;
+    url;
+    secret;
+    consoleUrl;
+    constructor(opts) {
+        this.name = opts.name ?? "webhook";
+        this.url = opts.url;
+        this.secret = opts.secret;
+        this.consoleUrl = opts.consoleUrl;
+    }
+    async notify(req) {
+        await this.post({ event: "approval.requested", summary: summary(req), approval: req, console_url: `${this.consoleUrl}#${req.id}` });
+    }
+    async decided(req) {
+        await this.post({ event: "approval.decided", summary: `${summary(req)}: ${req.status}`, approval: req });
+    }
+    async post(payload) {
+        const body = JSON.stringify(payload);
+        const ts = Math.floor(Date.now() / 1000).toString();
+        const sig = createHmac("sha256", this.secret).update(`${ts}.${body}`).digest("hex");
+        await fetch(this.url, {
+            method: "POST",
+            headers: { "content-type": "application/json", "x-mandat-timestamp": ts, "x-mandat-signature": `sha256=${sig}` },
+            body,
+            signal: AbortSignal.timeout(5000),
+        });
+    }
+}
+/** Slack via an app's Incoming Webhook; buttons are handled by `handleSlackInteraction`. */
+export class SlackNotifier {
+    name = "slack";
+    webhookUrl;
+    consoleUrl;
+    constructor(opts) {
+        this.webhookUrl = opts.webhookUrl;
+        this.consoleUrl = opts.consoleUrl;
+    }
+    async notify(req) {
+        await fetch(this.webhookUrl, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ text: `Approval needed: ${summary(req)}`, blocks: slackBlocks(req, this.consoleUrl) }),
+            signal: AbortSignal.timeout(5000),
+        });
+    }
+}
+export function slackBlocks(req, consoleUrl) {
+    const c = req.context;
+    const args = JSON.stringify(c.args, null, 2);
+    const blocks = [
+        { type: "header", text: { type: "plain_text", text: req.status === "pending" ? "🛂 Agent action needs approval" : `Agent action ${req.status}` } },
+        { type: "section", text: { type: "mrkdwn", text: `*${c.agent.id}*${c.agent.version ? ` (v${c.agent.version})` : ""} wants to call \`${c.tool}\` on behalf of *${c.principal.email ?? c.principal.sub}*` } },
+        {
+            type: "section",
+            fields: [
+                { type: "mrkdwn", text: `*Risk*\n${c.risk ?? "unclassified"}` },
+                { type: "mrkdwn", text: `*Rule*\n${c.rule}` },
+                { type: "mrkdwn", text: `*Delegation*\n${[c.principal.sub, ...(c.actor_chain ?? []).slice().reverse()].join(" → ")}` },
+                { type: "mrkdwn", text: `*Expires*\n<!date^${Math.floor(Date.parse(req.expires_at) / 1000)}^{time}|${req.expires_at}>` },
+            ],
+        },
+        { type: "section", text: { type: "mrkdwn", text: "```" + args.slice(0, 2500) + "```" } },
+    ];
+    if (c.session_tainted)
+        blocks.push({ type: "context", elements: [{ type: "mrkdwn", text: "⚠️ Session has processed untrusted content (possible prompt injection)." }] });
+    if (req.status === "pending") {
+        blocks.push({
+            type: "actions",
+            block_id: `mandat_${req.id}`,
+            elements: [
+                { type: "button", style: "primary", text: { type: "plain_text", text: "Approve" }, action_id: "mandat_approve", value: req.id },
+                { type: "button", style: "danger", text: { type: "plain_text", text: "Deny" }, action_id: "mandat_deny", value: req.id },
+                { type: "button", text: { type: "plain_text", text: "Open in console" }, url: `${consoleUrl}#${req.id}`, action_id: "mandat_open" },
+            ],
+        });
+    }
+    else {
+        const who = req.votes.map((v) => `${v.decision === "approve" ? "✅" : "⛔"} ${v.by}`).join(", ");
+        blocks.push({ type: "context", elements: [{ type: "mrkdwn", text: `${req.status.toUpperCase()} ${who}` }] });
+    }
+    return blocks;
+}
+/** Verifies Slack's request signature (v0 HMAC-SHA256, 5 minute replay window). */
+export function verifySlackSignature(rawBody, timestamp, signature, signingSecret) {
+    if (!timestamp || !signature)
+        return false;
+    if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300)
+        return false;
+    const expected = "v0=" + createHmac("sha256", signingSecret).update(`v0:${timestamp}:${rawBody}`).digest("hex");
+    return safeEqual(expected, signature);
+}
+export function handleSlackInteraction(service, rawBody, consoleUrl) {
+    const payload = JSON.parse(new URLSearchParams(rawBody).get("payload") ?? "{}");
+    const action = payload.actions?.[0];
+    if (!action || (action.action_id !== "mandat_approve" && action.action_id !== "mandat_deny"))
+        return { replace_original: false, text: "ignored" };
+    const by = `slack:${payload.user?.username ?? payload.user?.id}`;
+    try {
+        const req = service.decide(action.value, { by, decision: action.action_id === "mandat_approve" ? "approve" : "deny", via: "slack" });
+        return { replace_original: true, text: `Approval ${req.status}`, blocks: slackBlocks(req, consoleUrl) };
+    }
+    catch (e) {
+        return { replace_original: false, text: `⚠️ ${e.message}` };
+    }
+}
+/** Dev channel: prints a hint to the control plane's stdout. */
+export class ConsoleLogNotifier {
+    name = "log";
+    async notify(req) {
+        console.log(`[approval] ${req.id}: ${summary(req)} — approve with: mandat approvals approve ${req.id}`);
+    }
+}

package/dist/bridge.d.ts

@@ -0,0 +1,38 @@
+export interface BridgeOptions {
+    /** Protected MCP server URL. */
+    url: string;
+    /** Mandat control plane URL. */
+    mandatUrl: string;
+    agentId: string;
+    agentSecret: string;
+    agentVersion?: string;
+    /** User token from a real IdP. If absent, `subjectTokenProvider` or else the dev IdP (with `user`) is used. */
+    subjectToken?: string;
+    /** Returns a fresh user ID token, e.g. from the `mandat login` session. */
+    subjectTokenProvider?: () => Promise<string>;
+    user?: {
+        sub: string;
+        email?: string;
+        tenant?: string;
+    };
+    tools?: string[];
+    log?: (msg: string) => void;
+}
+export declare class Bridge {
+    private o;
+    private token;
+    private refreshing;
+    private mcpSessionId;
+    private sessionId;
+    private log;
+    constructor(o: BridgeOptions);
+    /** Returns a valid task token, exchanging a new one when the current one expires within 30 s. */
+    taskToken(force?: boolean): Promise<string>;
+    /** Forwards one JSON-RPC message; returns the response message (or null for notifications). */
+    forward(msg: {
+        id?: unknown;
+        method?: string;
+    }): Promise<unknown>;
+    /** Runs the stdio loop until stdin closes. Requests are handled concurrently (approvals can block). */
+    run(input?: NodeJS.ReadableStream, output?: NodeJS.WritableStream): Promise<void>;
+}

package/dist/bridge.js

@@ -0,0 +1,117 @@
+// stdio <-> Streamable HTTP bridge that lets any stdio MCP client (Claude Code, Codex, Cursor, Claude Desktop)
+// talk to a Mandat-protected MCP server. It acts as the agent: it holds the agent credentials, exchanges the
+// user's token for short-lived task tokens (RFC 8693) and transparently re-exchanges before they expire.
+//
+// stdout carries only MCP JSON-RPC messages (one per line); diagnostics go to stderr.
+import { createInterface } from "node:readline";
+import { decodeJwt } from "./sts/jwt.js";
+import { devLogin, exchangeToken } from "./client.js";
+import { randomId } from "./util.js";
+export class Bridge {
+    o;
+    token = null;
+    refreshing = null;
+    mcpSessionId = null;
+    sessionId = randomId("sess_");
+    log;
+    constructor(o) {
+        this.o = o;
+        this.log = o.log ?? ((m) => process.stderr.write(`[mandat-bridge] ${m}\n`));
+    }
+    /** Returns a valid task token, exchanging a new one when the current one expires within 30 s. */
+    async taskToken(force = false) {
+        if (!force && this.token && this.token.exp - Date.now() / 1000 > 30)
+            return this.token.value;
+        this.refreshing ??= (async () => {
+            const subject = this.o.subjectToken
+                ?? (this.o.subjectTokenProvider ? await this.o.subjectTokenProvider() : await devLogin(this.o.mandatUrl, this.o.user ?? { sub: "user:local" }));
+            const details = this.o.tools?.length ? [{ type: "mandat_tool_call", tools: this.o.tools }] : undefined;
+            const t = await exchangeToken({
+                mandatUrl: this.o.mandatUrl,
+                clientId: this.o.agentId,
+                clientSecret: this.o.agentSecret,
+                subjectToken: subject,
+                resource: this.o.url,
+                agentVersion: this.o.agentVersion,
+                authorizationDetails: details,
+                sessionId: this.sessionId,
+            });
+            const exp = decodeJwt(t.access_token).payload.exp;
+            this.token = { value: t.access_token, exp };
+            this.log(`new task token for ${this.o.agentId}, valid ${t.expires_in}s`);
+            return t.access_token;
+        })().finally(() => { this.refreshing = null; });
+        return this.refreshing;
+    }
+    /** Forwards one JSON-RPC message; returns the response message (or null for notifications). */
+    async forward(msg) {
+        const send = async (token) => fetch(this.o.url, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                accept: "application/json, text/event-stream",
+                authorization: `Bearer ${token}`,
+                ...(this.mcpSessionId ? { "mcp-session-id": this.mcpSessionId } : {}),
+            },
+            body: JSON.stringify(msg),
+        });
+        try {
+            let res = await send(await this.taskToken());
+            if (res.status === 401) {
+                // Expired or revoked: try once with a fresh token (a revoked agent fails at the exchange).
+                res = await send(await this.taskToken(true));
+            }
+            const sid = res.headers.get("mcp-session-id");
+            if (sid)
+                this.mcpSessionId = sid;
+            if (res.status === 202 || msg.id === undefined)
+                return null;
+            const text = await res.text();
+            if (!res.ok) {
+                let detail = text;
+                try {
+                    detail = JSON.parse(text).error_description ?? text;
+                }
+                catch { /* keep raw */ }
+                return rpcError(msg.id, `Mandat: HTTP ${res.status}: ${detail}`);
+            }
+            return parseBody(text, res.headers.get("content-type") ?? "");
+        }
+        catch (e) {
+            this.log(e.message);
+            return msg.id === undefined ? null : rpcError(msg.id, `Mandat bridge: ${e.message}`);
+        }
+    }
+    /** Runs the stdio loop until stdin closes. Requests are handled concurrently (approvals can block). */
+    run(input = process.stdin, output = process.stdout) {
+        const rl = createInterface({ input, crlfDelay: Infinity });
+        const pending = new Set();
+        rl.on("line", (line) => {
+            if (!line.trim())
+                return;
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                output.write(JSON.stringify({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } }) + "\n");
+                return;
+            }
+            const p = this.forward(msg).then((r) => { if (r)
+                output.write(JSON.stringify(r) + "\n"); });
+            pending.add(p);
+            void p.finally(() => pending.delete(p));
+        });
+        return new Promise((resolve) => rl.on("close", () => void Promise.allSettled([...pending]).then(() => resolve())));
+    }
+}
+function rpcError(id, message) {
+    return { jsonrpc: "2.0", id, error: { code: -32001, message } };
+}
+function parseBody(text, contentType) {
+    if (contentType.includes("text/event-stream")) {
+        const data = text.split("\n").filter((l) => l.startsWith("data:")).map((l) => l.slice(5).trim()).filter(Boolean);
+        return data.length ? JSON.parse(data[data.length - 1]) : null;
+    }
+    return text ? JSON.parse(text) : null;
+}

package/dist/cli/args.d.ts

@@ -0,0 +1,9 @@
+export interface Args {
+    _: string[];
+    flags: Record<string, string | boolean>;
+    str(name: string, fallback?: string): string | undefined;
+    bool(name: string): boolean;
+    num(name: string, fallback: number): number;
+    list(name: string): string[];
+}
+export declare function parseArgs(argv: string[], booleans?: string[]): Args;

package/dist/cli/args.js

@@ -0,0 +1,39 @@
+// Minimal argv parser: positionals, --flag, --key value, --key=value, -n 5.
+export function parseArgs(argv, booleans = []) {
+    const _ = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--") {
+            _.push(...argv.slice(i + 1));
+            break;
+        }
+        if (a.startsWith("--")) {
+            const eq = a.indexOf("=");
+            const key = eq > 0 ? a.slice(2, eq) : a.slice(2);
+            if (eq > 0)
+                flags[key] = a.slice(eq + 1);
+            else if (booleans.includes(key) || argv[i + 1] === undefined || argv[i + 1].startsWith("-"))
+                flags[key] = true;
+            else
+                flags[key] = argv[++i];
+        }
+        else if (a.startsWith("-") && a.length === 2) {
+            const key = a.slice(1);
+            if (booleans.includes(key) || argv[i + 1] === undefined || argv[i + 1].startsWith("-"))
+                flags[key] = true;
+            else
+                flags[key] = argv[++i];
+        }
+        else
+            _.push(a);
+    }
+    return {
+        _,
+        flags,
+        str: (n, f) => (typeof flags[n] === "string" ? flags[n] : f),
+        bool: (n) => flags[n] === true || flags[n] === "true",
+        num: (n, f) => (typeof flags[n] === "string" && !Number.isNaN(Number(flags[n])) ? Number(flags[n]) : f),
+        list: (n) => (typeof flags[n] === "string" ? flags[n].split(",").map((s) => s.trim()).filter(Boolean) : []),
+    };
+}

package/dist/cli/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from "./main.js";
+main(process.argv.slice(2)).then((code) => { process.exitCode = code; }, (err) => { console.error(err instanceof Error ? err.message : err); process.exitCode = 1; });

package/dist/cli/main.d.ts

@@ -0,0 +1 @@
+export declare function main(argv: string[]): Promise<number>;