mandat 0.0.0-stage → 0.1.0

package/dist/cli/templates.d.ts

@@ -0,0 +1,91 @@
+import type { PolicyDocument } from "../policy/engine.ts";
+export declare const STARTER_POLICY: PolicyDocument;
+export declare const STARTER_TESTS: ({
+    name: string;
+    input: {
+        tool: string;
+        args: {
+            amount: number;
+            currency: string;
+            order_id: string;
+            to?: undefined;
+            subject?: undefined;
+            body?: undefined;
+        };
+        session?: undefined;
+        task?: undefined;
+    };
+    expect: string;
+} | {
+    name: string;
+    input: {
+        tool: string;
+        args: {
+            to: string[];
+            subject: string;
+            body: string;
+            amount?: undefined;
+            currency?: undefined;
+            order_id?: undefined;
+        };
+        session?: undefined;
+        task?: undefined;
+    };
+    expect: string;
+} | {
+    name: string;
+    input: {
+        tool: string;
+        args: {
+            to: string[];
+            subject: string;
+            body: string;
+            amount?: undefined;
+            currency?: undefined;
+            order_id?: undefined;
+        };
+        session: {
+            tainted: boolean;
+        };
+        task?: undefined;
+    };
+    expect: string;
+} | {
+    name: string;
+    input: {
+        tool: string;
+        args: {
+            amount?: undefined;
+            currency?: undefined;
+            order_id?: undefined;
+            to?: undefined;
+            subject?: undefined;
+            body?: undefined;
+        };
+        session?: undefined;
+        task?: undefined;
+    };
+    expect: string;
+} | {
+    name: string;
+    input: {
+        tool: string;
+        args: {
+            amount: number;
+            currency: string;
+            order_id?: undefined;
+            to?: undefined;
+            subject?: undefined;
+            body?: undefined;
+        };
+        task: {
+            authorization_details: {
+                type: string;
+                tools: string[];
+            }[];
+        };
+        session?: undefined;
+    };
+    expect: string;
+})[];
+export declare function readmeSnippet(resource: string, url: string): string;

package/dist/cli/templates.js

@@ -0,0 +1,57 @@
+// Files written by `mandat init`.
+export const STARTER_POLICY = {
+    version: 1,
+    default: "deny",
+    tools: {
+        "lookup_*": { risk: "read" },
+        "list_*": { risk: "read" },
+        "get_*": { risk: "read" },
+        "read_inbox": { risk: "read", taints: true, description: "Returns untrusted e-mail content: taints the session" },
+        "fetch_url": { risk: "read", taints: true },
+        "send_email": { risk: "external_comm", redact: ["body"] },
+        "refund": { risk: "financial" },
+        "delete_*": { risk: "destructive" },
+    },
+    rules: [
+        { id: "reads", description: "Read-only tools are allowed", tool: ["lookup_*", "list_*", "get_*", "read_inbox", "fetch_url"], effect: "allow" },
+        { id: "refund-auto", description: "Small refunds are automatic", tool: "refund", when: "args.amount <= 50 && args.currency == 'EUR'", effect: "allow" },
+        { id: "refund-approval", description: "€50–500 needs a human", tool: "refund", when: "args.amount > 50 && args.amount <= 500 && args.currency == 'EUR'", effect: "require_approval", approval: { approvers: 1, timeout: "15m" } },
+        { id: "refund-limit", tool: "refund", when: "args.amount > 500 || args.currency != 'EUR'", effect: "deny", reason: "Refunds above €500 (or not in EUR) must be done by finance, not by an agent" },
+        { id: "email-internal", tool: "send_email", when: "args.to.all(r, r.endsWith('@example.com'))", effect: "allow_with_obligations", obligations: [{ type: "annotate", tags: ["internal-email"] }] },
+        { id: "email-external", tool: "send_email", when: "!args.to.all(r, r.endsWith('@example.com'))", effect: "require_approval", reason: "External recipients need approval" },
+        { id: "no-exfil-after-untrusted", description: "Lethal trifecta guard: after reading untrusted content, never write to external channels", tool: "send_email", when: "session.tainted && !args.to.all(r, r.endsWith('@example.com'))", effect: "deny", reason: "Session processed untrusted content; external e-mail is blocked (possible prompt injection)" },
+        { id: "destructive-four-eyes", description: "Deletes need two humans", tool: "delete_*", effect: "require_approval", approval: { approvers: 2, timeout: "30m" } },
+        { id: "no-prod-delete-at-night", tool: "delete_*", when: "has(args.environment) && args.environment == 'production' && (env.hour_utc < 6 || env.hour_utc >= 22)", effect: "deny", reason: "No destructive production changes outside working hours" },
+    ],
+};
+export const STARTER_TESTS = [
+    { name: "small refund is automatic", input: { tool: "refund", args: { amount: 20, currency: "EUR", order_id: "A1" } }, expect: "allow" },
+    { name: "medium refund needs approval", input: { tool: "refund", args: { amount: 120, currency: "EUR", order_id: "A1" } }, expect: "require_approval" },
+    { name: "large refund is denied", input: { tool: "refund", args: { amount: 900, currency: "EUR", order_id: "A1" } }, expect: "deny" },
+    { name: "internal e-mail allowed", input: { tool: "send_email", args: { to: ["ops@example.com"], subject: "hi", body: "x" } }, expect: "allow*" },
+    { name: "external e-mail after untrusted input is denied", input: { tool: "send_email", args: { to: ["x@evil.test"], subject: "hi", body: "x" }, session: { tainted: true } }, expect: "deny" },
+    { name: "unknown tool is denied by default", input: { tool: "drop_database", args: {} }, expect: "deny" },
+    { name: "capability from task token is enforced", input: { tool: "refund", args: { amount: 10, currency: "EUR" }, task: { authorization_details: [{ type: "mandat_tool_call", tools: ["lookup_order"] }] } }, expect: "deny" },
+];
+export function readmeSnippet(resource, url) {
+    return `
+Protect an MCP server built with the official TypeScript SDK:
+
+  import { createGuard, protect } from "mandat";
+  import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
+  import { InvalidTokenError } from "@modelcontextprotocol/sdk/server/auth/errors.js";
+
+  const guard = await createGuard({
+    resource: "${resource}",
+    controlPlane: "${url}",
+    apiKey: process.env.MANDAT_SERVICE_KEY,
+    pinning: { lockfile: "mandat.lock.json", mode: "block" },
+  });
+  const server = protect(new McpServer({ name: "my-server", version: "1.0.0" }), guard);
+  app.get("/.well-known/oauth-protected-resource/mcp", (_q, r) => r.json(guard.protectedResourceMetadata()));
+  app.use("/mcp", requireBearerAuth({ verifier: guard.sdkTokenVerifier({ InvalidTokenError }),
+    resourceMetadataUrl: "${new URL(resource).origin}/.well-known/oauth-protected-resource/mcp" }));
+
+Or with the built-in zero-dependency server:  new McpHttpServer({ name, version, guard, tools }).listen(7401)
+`;
+}

package/dist/client.d.ts

@@ -0,0 +1,54 @@
+import type { AuthorizationDetail } from "./policy/engine.ts";
+export interface ExchangeOptions {
+    /** Mandat control plane base URL. */
+    mandatUrl: string;
+    clientId: string;
+    clientSecret: string;
+    /** The user's token from the IdP (ID token / access token), or a parent Mandat token for sub-agents. */
+    subjectToken: string;
+    subjectTokenType?: string;
+    /** MCP server URL the token is for (RFC 8707). */
+    resource: string;
+    /** Narrow the capability: tools (and optional limits) for this task only. */
+    authorizationDetails?: AuthorizationDetail[];
+    agentVersion?: string;
+    /** System prompt (hashed client-side; only the hash is sent and logged). */
+    systemPrompt?: string;
+    taskId?: string;
+    sessionId?: string;
+    expiresIn?: number;
+}
+export interface TaskToken {
+    access_token: string;
+    expires_in: number;
+    authorization_details: AuthorizationDetail[];
+}
+export declare function exchangeToken(o: ExchangeOptions): Promise<TaskToken>;
+/** Dev IdP login (only when the control plane runs with `devIdp: true`). */
+export declare function devLogin(mandatUrl: string, user: {
+    sub: string;
+    email?: string;
+    tenant?: string;
+}): Promise<string>;
+export declare class McpHttpClient {
+    private url;
+    token: string;
+    private sessionId;
+    private id;
+    constructor(url: string, token: string);
+    request(method: string, params?: Record<string, unknown>): Promise<any>;
+    initialize(): Promise<any>;
+    listTools(): Promise<Array<{
+        name: string;
+        description?: string;
+    }>>;
+    callTool(name: string, args: Record<string, unknown>): Promise<{
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        isError?: boolean;
+        _meta?: Record<string, any>;
+        structuredContent?: unknown;
+    }>;
+}

package/dist/client.js

@@ -0,0 +1,88 @@
+// Agent-side helpers: obtain a per-task token (RFC 8693) and call an MCP server over Streamable HTTP.
+import { GRANT_TOKEN_EXCHANGE, TT_ID_TOKEN } from "./sts/sts.js";
+import { sha256 } from "./util.js";
+export async function exchangeToken(o) {
+    const form = new URLSearchParams({
+        grant_type: GRANT_TOKEN_EXCHANGE,
+        subject_token: o.subjectToken,
+        subject_token_type: o.subjectTokenType ?? TT_ID_TOKEN,
+        resource: o.resource,
+    });
+    if (o.authorizationDetails)
+        form.set("authorization_details", JSON.stringify(o.authorizationDetails));
+    if (o.agentVersion)
+        form.set("mandat_agent_version", o.agentVersion);
+    if (o.systemPrompt)
+        form.set("mandat_prompt_hash", "sha256:" + sha256(o.systemPrompt).slice(0, 32));
+    if (o.taskId)
+        form.set("mandat_task_id", o.taskId);
+    if (o.sessionId)
+        form.set("mandat_session_id", o.sessionId);
+    if (o.expiresIn)
+        form.set("expires_in", String(o.expiresIn));
+    const res = await fetch(`${o.mandatUrl.replace(/\/$/, "")}/oauth/token`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/x-www-form-urlencoded",
+            authorization: "Basic " + Buffer.from(`${encodeURIComponent(o.clientId)}:${encodeURIComponent(o.clientSecret)}`).toString("base64"),
+        },
+        body: form,
+    });
+    const body = (await res.json());
+    if (!res.ok)
+        throw new Error(`Token exchange failed: ${body.error}: ${body.error_description}`);
+    return body;
+}
+/** Dev IdP login (only when the control plane runs with `devIdp: true`). */
+export async function devLogin(mandatUrl, user) {
+    const res = await fetch(`${mandatUrl.replace(/\/$/, "")}/dev/login`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(user) });
+    if (!res.ok)
+        throw new Error(`dev login failed: ${res.status}`);
+    return (await res.json()).id_token;
+}
+export class McpHttpClient {
+    url;
+    token;
+    sessionId = null;
+    id = 0;
+    constructor(url, token) {
+        this.url = url;
+        this.token = token;
+    }
+    async request(method, params = {}) {
+        const res = await fetch(this.url, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                accept: "application/json, text/event-stream",
+                authorization: `Bearer ${this.token}`,
+                "mcp-protocol-version": "2026-07-28",
+                ...(this.sessionId ? { "mcp-session-id": this.sessionId } : {}),
+            },
+            body: JSON.stringify({ jsonrpc: "2.0", id: ++this.id, method, params }),
+        });
+        if (res.status === 401 || res.status === 403) {
+            const body = (await res.json().catch(() => ({})));
+            const err = new Error(`HTTP ${res.status}: ${body.error_description ?? "unauthorized"}`);
+            err.status = res.status;
+            err.challenge = res.headers.get("www-authenticate");
+            throw err;
+        }
+        const sid = res.headers.get("mcp-session-id");
+        if (sid)
+            this.sessionId = sid;
+        const msg = (await res.json());
+        if (msg.error)
+            throw new Error(`MCP error: ${msg.error.message}`);
+        return msg.result;
+    }
+    initialize() {
+        return this.request("initialize", { protocolVersion: "2026-07-28", capabilities: {}, clientInfo: { name: "mandat-client", version: "0.1.0" } });
+    }
+    async listTools() {
+        return (await this.request("tools/list")).tools;
+    }
+    callTool(name, args) {
+        return this.request("tools/call", { name, arguments: args });
+    }
+}

package/dist/controlplane/config.d.ts

@@ -0,0 +1,48 @@
+import type { TrustedIssuer } from "../sts/sts.ts";
+import type { RedactionOptions } from "../ledger/redact.ts";
+export type Role = "admin" | "approver" | "auditor" | "service";
+export declare const ROLES: Role[];
+export interface ApiKeyEntry {
+    /** Identity recorded in the ledger (e.g. "alice", "refund-mcp"). */
+    id: string;
+    /** "sha256:<hex>" of the key. */
+    hash: string;
+    roles: Role[];
+}
+export interface ControlPlaneConfig {
+    /** Public base URL; also the token issuer. */
+    issuer: string;
+    port: number;
+    host?: string;
+    dataDir: string;
+    policyFile: string;
+    devIdp?: boolean;
+    tokenTtlSeconds?: number;
+    maxTokenTtlSeconds?: number;
+    trustedIssuers?: TrustedIssuer[];
+    apiKeys: ApiKeyEntry[];
+    approvals?: {
+        defaultTimeout?: string;
+        log?: boolean;
+        slack?: {
+            webhookUrl: string;
+            signingSecret?: string;
+        };
+        webhooks?: Array<{
+            name?: string;
+            url: string;
+            secret: string;
+        }>;
+    };
+    ledger?: {
+        retentionDays?: number;
+        otlp?: {
+            endpoint: string;
+            headers?: Record<string, string>;
+        };
+        redaction?: RedactionOptions;
+    };
+}
+export declare function hashApiKey(key: string): string;
+/** Loads a config file, expands ${env:VAR}, resolves relative paths against the file's directory. */
+export declare function loadConfig(path: string): ControlPlaneConfig;

package/dist/controlplane/config.js

@@ -0,0 +1,33 @@
+import { dirname, isAbsolute, resolve } from "node:path";
+import { interpolateEnv, readJson, sha256 } from "../util.js";
+export const ROLES = ["admin", "approver", "auditor", "service"];
+export function hashApiKey(key) {
+    return "sha256:" + sha256(key);
+}
+/** Loads a config file, expands ${env:VAR}, resolves relative paths against the file's directory. */
+export function loadConfig(path) {
+    const raw = interpolateEnv(readJson(path));
+    const base = dirname(resolve(path));
+    const abs = (p) => (isAbsolute(p) ? p : resolve(base, p));
+    const cfg = {
+        host: "127.0.0.1",
+        tokenTtlSeconds: 300,
+        maxTokenTtlSeconds: 900,
+        trustedIssuers: [],
+        ...raw,
+        dataDir: abs(raw.dataDir ?? ".mandat"),
+        policyFile: abs(raw.policyFile ?? "mandat.policy.json"),
+    };
+    if (!cfg.issuer)
+        throw new Error("config: `issuer` is required");
+    if (!cfg.apiKeys?.length)
+        throw new Error("config: at least one entry in `apiKeys` is required");
+    for (const k of cfg.apiKeys) {
+        if (!k.hash?.startsWith("sha256:"))
+            throw new Error(`config: apiKeys[${k.id}].hash must be "sha256:<hex>"`);
+        for (const r of k.roles)
+            if (!ROLES.includes(r))
+                throw new Error(`config: apiKeys[${k.id}] unknown role '${r}'`);
+    }
+    return cfg;
+}