@interlok/cli 0.0.0-stage → 1.3.0

package/dist/gate.js

@@ -0,0 +1,338 @@
+import { execSync } from "node:child_process";
+import { readFileSync, writeFileSync, existsSync, appendFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { canonical } from "./canonical.js";
+import { summarizePlan, EXIT, MODEL_CHANGE_KINDS } from "./packs.js";
+/**
+ * `interlok gate`: the Change Gate CI step. Collects context from the CI environment and git,
+ * summarizes an optional Terraform plan locally (the full plan never leaves CI), asks Interlok,
+ * and waits for a person if the change is held. Exit codes: 0 allowed/released · 10 denied ·
+ * 11 hold expired · 12 unreachable · 13 config or auth error.
+ */
+const STATE = ".interlok-gate.json";
+const env = process.env;
+async function ciToken(api) {
+    if (env.INTERLOK_API_KEY)
+        return env.INTERLOK_API_KEY;
+    let idToken = env.INTERLOK_OIDC_TOKEN;
+    if (!idToken && env.ACTIONS_ID_TOKEN_REQUEST_URL && env.ACTIONS_ID_TOKEN_REQUEST_TOKEN) {
+        const r = await fetch(`${env.ACTIONS_ID_TOKEN_REQUEST_URL}&audience=${encodeURIComponent("https://interlok.io")}`, {
+            headers: { authorization: `Bearer ${env.ACTIONS_ID_TOKEN_REQUEST_TOKEN}` },
+        });
+        if (!r.ok)
+            throw Object.assign(new Error(`could not get the GitHub OIDC token (${r.status}); add permissions: id-token: write`), { code: EXIT.config });
+        idToken = (await r.json()).value;
+    }
+    if (!idToken)
+        throw Object.assign(new Error("no INTERLOK_API_KEY and no CI OIDC token available"), {
+            code: EXIT.config,
+        });
+    const connector_id = env.INTERLOK_CONNECTOR;
+    if (!connector_id || !/^[0-9a-f-]{36}$/i.test(connector_id))
+        throw Object.assign(new Error("set INTERLOK_CONNECTOR to your connector id (Console → Settings → Connectors)"), { code: EXIT.config });
+    const x = await fetch(`${api}/api/v1/auth/oidc-exchange`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ id_token: idToken, connector_id }),
+    });
+    if (!x.ok)
+        throw Object.assign(new Error(`OIDC exchange refused (${x.status}): ${(await x.text()).slice(0, 200)}`), { code: EXIT.config });
+    return (await x.json()).token;
+}
+const sh = (cmd) => {
+    try {
+        return execSync(cmd, { stdio: ["ignore", "pipe", "ignore"], encoding: "utf8" }).trim();
+    }
+    catch {
+        return "";
+    }
+};
+const BOT = /\[bot\]$|^(dependabot|renovate|github-actions)/i;
+const AGENT_TRAILER = /co-authored-by:.*\b(claude|copilot|cursor|devin|codex|openhands|aider|sweep|agent|bot)\b/i;
+export function collectContext(agentIds = []) {
+    let pr = null;
+    let prAuthor = null;
+    let prAuthorBot = false;
+    if (env.GITHUB_EVENT_PATH && existsSync(env.GITHUB_EVENT_PATH)) {
+        try {
+            const ev = JSON.parse(readFileSync(env.GITHUB_EVENT_PATH, "utf8"));
+            pr = ev.pull_request?.number ?? ev.number ?? null;
+            prAuthor = ev.pull_request?.user?.login ?? null;
+            prAuthorBot = ev.pull_request?.user?.type === "Bot";
+        }
+        catch {
+            /* no event payload */
+        }
+    }
+    if (pr === null) {
+        const m = /^refs\/pull\/(\d+)\//.exec(env.GITHUB_REF ?? "");
+        if (m)
+            pr = Number(m[1]);
+    }
+    const base = env.GITHUB_BASE_REF ? `origin/${env.GITHUB_BASE_REF}...HEAD` : "HEAD~1";
+    const changed = sh(`git diff --name-only ${base}`).split("\n").filter(Boolean);
+    const authors = sh(`git log --format=%an%x1f%ae -n 50 ${env.GITHUB_BASE_REF ? `origin/${env.GITHUB_BASE_REF}..HEAD` : "-1"}`)
+        .split("\n")
+        .filter(Boolean);
+    const bodies = sh(`git log --format=%B -n 20 ${env.GITHUB_BASE_REF ? `origin/${env.GITHUB_BASE_REF}..HEAD` : "-1"}`);
+    const kinds = new Set();
+    const ids = new Set();
+    const requester = env.GITHUB_ACTOR ?? env.GITLAB_USER_LOGIN ?? null;
+    const isAgent = (s) => agentIds.some((a) => a && s.toLowerCase().includes(a.toLowerCase()));
+    const classify = (name, email) => isAgent(name) || isAgent(email)
+        ? "agent"
+        : BOT.test(name) || /noreply.*bot|bot@/i.test(email)
+            ? "bot"
+            : "human";
+    if (prAuthor) {
+        kinds.add(prAuthorBot ? "bot" : classify(prAuthor, ""));
+        ids.add(prAuthor);
+    }
+    else if (requester)
+        kinds.add(classify(requester, ""));
+    for (const a of authors) {
+        const [name = "", email = ""] = a.split("\x1f");
+        kinds.add(classify(name, email));
+        if (name)
+            ids.add(name);
+        if (email)
+            ids.add(email);
+    }
+    if (AGENT_TRAILER.test(bodies))
+        kinds.add("agent");
+    return {
+        repo: env.GITHUB_REPOSITORY ??
+            env.CI_PROJECT_PATH ??
+            (sh("git config --get remote.origin.url").replace(/^.*[:/]([^/]+\/[^/]+?)(\.git)?$/, "$1") ||
+                null),
+        ref: env.GITHUB_HEAD_REF ||
+            env.GITHUB_REF_NAME ||
+            env.CI_COMMIT_REF_NAME ||
+            sh("git rev-parse --abbrev-ref HEAD") ||
+            null,
+        commit_sha: env.GITHUB_SHA ?? env.CI_COMMIT_SHA ?? (sh("git rev-parse HEAD") || null),
+        pr_number: pr,
+        requester,
+        author_kinds: [...kinds],
+        author_ids: [...ids].slice(0, 50),
+        changed_paths: changed.slice(0, 2000),
+        files_changed: changed.length,
+        source_ref: env.GITHUB_RUN_ID
+            ? `gh:${env.GITHUB_REPOSITORY}:${env.GITHUB_RUN_ID}:${env.GITHUB_RUN_ATTEMPT ?? 1}`
+            : env.CI_JOB_ID
+                ? `gl:${env.CI_PROJECT_PATH}:${env.CI_JOB_ID}`
+                : `local:${Date.now()}`,
+    };
+}
+export function planFromFile(path) {
+    const plan = JSON.parse(readFileSync(path, "utf8"));
+    const summary = summarizePlan(plan);
+    const rc = Array.isArray(plan?.resource_changes) ? plan.resource_changes : [];
+    const material = rc.map((r) => ({
+        address: r.address,
+        actions: r?.change?.actions ?? [],
+        after: r?.change?.after ?? null,
+    }));
+    const plan_hash = createHash("sha256").update(canonical(material)).digest("hex");
+    return { summary, plan_hash };
+}
+const list = (s) => (s ?? "")
+    .split(",")
+    .map((x) => x.trim())
+    .filter(Boolean);
+/** `--action model.promote` flags → the model description the Change Gate judges. */
+export function modelFromFlags(value) {
+    const model_to = value("--model-to");
+    if (!model_to)
+        return "model.promote needs --model-to";
+    const changes = list(value("--model-change"));
+    const bad = changes.filter((c) => !MODEL_CHANGE_KINDS.includes(c));
+    if (bad.length)
+        return `--model-change accepts ${MODEL_CHANGE_KINDS.join(", ")}; got ${bad.join(", ")}`;
+    for (const k of ["--digest-from", "--digest-to"])
+        if (value(k) && !/^[0-9a-f]{64}$/.test(value(k)))
+            return `${k} must be a sha256 (64 hex)`;
+    const passed = value("--eval-passed");
+    const regressions = value("--eval-regressions");
+    const out = {
+        model_to,
+        model_from: value("--model-from"),
+        provider_from: value("--provider-from"),
+        provider_to: value("--provider-to"),
+        digest_from: value("--digest-from"),
+        digest_to: value("--digest-to"),
+        changes,
+        classification: list(value("--classification")),
+    };
+    if (passed !== undefined || regressions !== undefined || value("--eval-suite"))
+        out.eval = {
+            suite: value("--eval-suite") ?? null,
+            passed: passed === undefined ? null : passed === "true" || passed === "1",
+            regressions: regressions === undefined ? null : Math.max(0, Number(regressions) || 0),
+        };
+    for (const k of Object.keys(out))
+        if (out[k] === undefined)
+            delete out[k];
+    return out;
+}
+function parseWait(s) {
+    if (!s)
+        return 3600;
+    const m = /^(\d+)\s*(s|m|h)?$/.exec(s.trim());
+    if (!m)
+        return 3600;
+    const n = Number(m[1]);
+    return m[2] === "h" ? n * 3600 : m[2] === "s" ? n : n * 60;
+}
+export async function gateCommand(args, value, has) {
+    const api = (env.INTERLOK_URL ?? value("--url") ?? "https://interlok.io").replace(/\/$/, "");
+    // Tokens travel to this URL: refuse plain http except to a local development server.
+    if (!/^https:\/\//.test(api) && !/^http:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/.test(api)) {
+        console.error("INTERLOK_URL must be https");
+        process.exitCode = EXIT.config;
+        return;
+    }
+    const fail = (code, msg) => {
+        console.error(msg);
+        process.exitCode = code;
+    };
+    if (args[0] === "report") {
+        if (!existsSync(STATE))
+            return fail(EXIT.config, "no gate state found; run `interlok gate` first in this job");
+        const st = JSON.parse(readFileSync(STATE, "utf8"));
+        const status = value("--status") ?? "unknown";
+        const outcome = status === "success"
+            ? "success"
+            : status === "failure" || status === "cancelled"
+                ? "failure"
+                : "unknown";
+        try {
+            const token = await ciToken(api);
+            const r = await fetch(`${api}/api/v1/change-requests/${st.id}`, {
+                method: "POST",
+                headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+                body: JSON.stringify({ outcome }),
+            });
+            console.log(r.ok ? `outcome recorded: ${outcome}` : `could not record the outcome (${r.status})`);
+        }
+        catch (e) {
+            return fail(e?.code ?? EXIT.unreachable, e.message);
+        }
+        return;
+    }
+    const action = (value("--action") ?? "deploy");
+    if (!["deploy", "terraform.apply", "model.promote"].includes(action))
+        return fail(EXIT.config, "--action must be deploy, terraform.apply or model.promote");
+    const ctx = collectContext((value("--agents") ?? "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean));
+    const body = {
+        ...ctx,
+        action,
+        environment: value("--env") ?? env.GITHUB_ENVIRONMENT ?? null,
+        deadline_seconds: Math.min(parseWait(value("--wait")), 86_400),
+    };
+    if (value("--plan")) {
+        try {
+            const p = planFromFile(value("--plan"));
+            body.plan = p.summary;
+            body.plan_hash = p.plan_hash;
+        }
+        catch (e) {
+            return fail(EXIT.config, `could not read the plan: ${e.message}`);
+        }
+    }
+    if (action === "model.promote") {
+        const m = modelFromFlags(value);
+        if (typeof m === "string")
+            return fail(EXIT.config, m);
+        body.model = m;
+    }
+    if (has("--emergency")) {
+        const reason = value("--reason");
+        if (!reason)
+            return fail(EXIT.config, "--emergency needs --reason");
+        body.emergency_reason = reason;
+    }
+    for (const k of Object.keys(body))
+        if (body[k] === null || body[k] === undefined)
+            delete body[k];
+    let token;
+    try {
+        token = await ciToken(api);
+    }
+    catch (e) {
+        return fail(e?.code ?? EXIT.config, e.message);
+    }
+    const headers = { authorization: `Bearer ${token}`, "content-type": "application/json" };
+    let r;
+    try {
+        const res = await fetch(`${api}/api/v1/change-requests`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        });
+        if (res.status === 401 || res.status === 403)
+            return fail(EXIT.config, `Interlok refused the request (${res.status}): ${(await res.text()).slice(0, 200)}`);
+        if (!res.ok)
+            return fail(EXIT.unreachable, `Interlok answered ${res.status}`);
+        r = await res.json();
+    }
+    catch (e) {
+        if (has("--fail-open")) {
+            console.error(`Interlok unreachable (${e.message}); --fail-open set, passing. This cannot be recorded in the ledger.`);
+            return;
+        }
+        return fail(EXIT.unreachable, `Interlok unreachable: ${e.message}`);
+    }
+    // The id is written into files GitHub reads as commands: accept only a UUID.
+    if (typeof r.id !== "string" ||
+        !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(r.id))
+        return fail(EXIT.unreachable, "Interlok returned an unexpected response");
+    writeFileSync(STATE, JSON.stringify({ id: r.id, at: new Date().toISOString() }));
+    if (env.GITHUB_ENV)
+        appendFileSync(env.GITHUB_ENV, `INTERLOK_CHANGE_ID=${r.id}\n`);
+    const line = (s) => console.log(`interlok gate: ${s}`);
+    if (r.status === "auto_allowed")
+        return line(`allowed (${r.risk_points ?? 0} points)`);
+    if (r.status === "would_hold")
+        return line(`shadow mode: would have been held (${(r.rules_fired ?? []).join(", ")}); passing`);
+    if (r.status === "emergency")
+        return line(`emergency change allowed; a second person must review within 24 h · ${r.console_url}`);
+    if (r.status === "approved")
+        return line("approved (plan already approved by a person)");
+    if (r.status !== "held")
+        return fail(EXIT.rejected, `${r.status}`);
+    line(`HELD: ${(r.rules_fired ?? []).join(", ")}`);
+    line(`waiting for a person · ${r.hold_url ?? r.console_url}`);
+    const safeRules = (r.rules_fired ?? [])
+        .map((x) => String(x).replace(/[^A-Z0-9-]/g, ""))
+        .join(", ");
+    const link = String(r.hold_url ?? r.console_url ?? "");
+    if (env.GITHUB_STEP_SUMMARY && /^https?:\/\/[^\s()<>[\]]+$/.test(link))
+        appendFileSync(env.GITHUB_STEP_SUMMARY, `### Interlok gate: held\n${safeRules} · [Release or deny](${link})\n`);
+    const deadline = Date.parse(r.deadline_at);
+    for (;;) {
+        let s;
+        try {
+            const res = await fetch(`${api}/api/v1/change-requests/${r.id}?wait=25`, { headers });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            s = await res.json();
+        }
+        catch (e) {
+            return fail(EXIT.unreachable, `lost contact with Interlok while waiting: ${e.message}`);
+        }
+        if (s.status === "approved")
+            return line("released by a person");
+        if (s.status === "failed_open")
+            return line("hold expired; connector fails open, passing (flagged in the ledger)");
+        if (s.status === "rejected")
+            return fail(EXIT.rejected, "denied by a person");
+        if (s.status === "expired")
+            return fail(EXIT.expired, "hold expired with no determination");
+        if (Date.now() > deadline + 60_000)
+            return fail(EXIT.expired, "deadline passed");
+    }
+}

package/dist/hook.d.ts

@@ -0,0 +1,108 @@
+/**
+ * `interlok hook`: a pre-tool-use hook for coding agents (Claude Code, Codex, Cursor).
+ *
+ * Every shell command and MCP call the agent is about to run is classified HERE, against a policy
+ * file, with no network call. Only a call that matches a rule leaves the machine: it becomes an
+ * Interlok approval that a named person must answer. Low-risk work is never gated.
+ *
+ * Rules this file keeps:
+ *  - Nothing here can approve. It asks the Approvals API and acts on a person's determination.
+ *  - Fail closed: a matched call with no key, no network or no answer is refused (--fail-open
+ *    relaxes the network case only).
+ *  - An approval is single-use. The hook remembers which approval it opened for a command and
+ *    consumes it the first time it lets that command run; the same command later asks again.
+ *  - The command line shown to the approver is scrubbed of credentials; `"summary": "hash-only"`
+ *    sends the rule name and a hash instead. The full tool input never leaves the machine.
+ */
+export type Agent = "claude" | "codex" | "cursor" | "gemini" | "copilot";
+/**
+ * Seconds each agent's config gives the hook. Gemini CLI and GitHub Copilot let a call through when
+ * a hook times out, so the wait for a person is always capped well inside this.
+ */
+export declare const HOOK_TIMEOUT_S = 120;
+export declare const MAX_WAIT_S: number;
+export interface Rule {
+    id: string;
+    /** Regex on the tool name. Shell commands are normalised to "Bash". Default: "^Bash$". */
+    tool?: string;
+    /** Regex on the command line (shell) or the JSON tool input (MCP). Omit to match any input. */
+    match?: string;
+    /** Regex that exempts an otherwise matching call. */
+    unless?: string;
+    /** What the approver reads before the command itself. */
+    label?: string;
+    approvers?: number;
+}
+export interface Policy {
+    version?: 1;
+    /** Include the built-in rules below (default true). */
+    defaults?: boolean;
+    environment?: string;
+    /** Seconds to wait for a person before answering "held". */
+    wait?: number;
+    /** "command" shows the scrubbed command line; "hash-only" shows only the rule and a hash. */
+    summary?: "command" | "hash-only";
+    rules?: Rule[];
+}
+/** Built-in rules: the actions that leave the worktree and are hard to take back. */
+export declare const DEFAULT_RULES: Rule[];
+export interface Call {
+    agent: Agent;
+    /** "Bash" for shell commands, `mcp__<server>__<tool>` for MCP calls. */
+    tool: string;
+    /** Shell: the command line. MCP: the tool input. */
+    input: unknown;
+    command?: string;
+    session: string;
+    cwd: string;
+}
+/** Read the agent's stdin payload into one shape. Returns null for anything the hook ignores. */
+export declare function parseCall(agent: Agent, raw: any): Call | null;
+/** The first rule a call matches, or null. Pure: no network, no file access. */
+export declare function matchRule(policy: Policy, call: Call): Rule | null;
+/** Strip credentials from a command line before an approver (and Interlok) sees it. */
+export declare function scrub(s: string): string;
+export declare const payloadHash: (call: Call) => string;
+export type Verdict = {
+    allow: true;
+} | {
+    allow: false;
+    reason: string;
+};
+/** What the agent receives on stdout. `null` means print nothing (allow). */
+export declare function render(agent: Agent, v: Verdict): string | null;
+/**
+ * Process exit code for a verdict. Copilot denies a tool call on any non-zero exit, whatever stdout
+ * says, so a refusal exits 2 there as well; every other agent reads the JSON and exits 0.
+ */
+export declare function exitCode(agent: Agent, v: Verdict): number;
+/**
+ * GitHub Copilot also runs the hooks in a repository's .claude/settings.json, with its own payload
+ * (no transcript_path, an ISO timestamp). When the repository has Interlok's Copilot hook too, the
+ * Claude entry steps aside so one tool call opens one request, not two.
+ */
+export declare function deferToCopilotHook(agent: Agent, raw: any, copilotHookInRepo: boolean): boolean;
+export interface HookDeps {
+    api: string;
+    key: string;
+    agentName: string;
+    waitSeconds: number;
+    failOpen: boolean;
+    stateDir: string;
+    fetch?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    context?: Record<string, string>;
+}
+/** Decide one call. Every path that is not a person's approval returns a refusal. */
+export declare function decide(call: Call, policy: Policy, deps: HookDeps): Promise<Verdict>;
+/** Nearest .interlok/policy.json walking up from `dir` (stops at the filesystem root). */
+export declare function loadPolicy(dir: string): Promise<{
+    policy: Policy;
+    file: string | null;
+}>;
+export declare const DEFAULT_POLICY_FILE: Policy;
+export declare const COPILOT_HOOK_FILE: string;
+/** Merge Interlok's hook into each agent's project config. Idempotent; never removes entries. */
+export declare function init(dir: string, agents: Agent[], bin: string): Promise<string[]>;
+export declare function hookCommand(args: string[], value: (flag: string) => string | undefined, has: (flag: string) => boolean): Promise<void>;