harnery 0.12.1 → 0.13.0

package/dist/core/workflow/approvals.js

@@ -0,0 +1,288 @@
+import { createHash, randomUUID } from "node:crypto";
+import { chmodSync, existsSync, linkSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+export const WORKFLOW_APPROVAL_SCHEMA_VERSION = 1;
+const RECORD_LIMIT_BYTES = 128 * 1024;
+const RUN_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/;
+const APPROVAL_ID = /^apr-[a-f0-9]{20}$/;
+const DECISION_ID = /^p[1-9][0-9]{0,4}$/;
+const MAX_ACTOR = 200;
+const MAX_REASON = 2_000;
+const MAX_ADDRESSEE = 200;
+export function workflowApprovalId(runId, decisionId) {
+    assertRunId(runId);
+    if (!DECISION_ID.test(decisionId)) {
+        throw new Error(`invalid workflow policy decision id ${JSON.stringify(decisionId)}`);
+    }
+    return `apr-${createHash("sha256").update(`${runId}\0${decisionId}`).digest("hex").slice(0, 20)}`;
+}
+export function createWorkflowApproval(input) {
+    const id = workflowApprovalId(input.runId, input.decisionId);
+    const addressedTo = bounded(input.addressedTo ?? "operator", "approval addressee", MAX_ADDRESSEE);
+    const requestSha256 = approvalRequestDigest(input.policy.sha256, input.request, input.evaluation);
+    const record = {
+        schema_version: WORKFLOW_APPROVAL_SCHEMA_VERSION,
+        id,
+        run_id: input.runId,
+        decision_id: input.decisionId,
+        requested_at: (input.now ?? (() => new Date().toISOString()))(),
+        addressed_to: addressedTo,
+        policy: {
+            name: bounded(input.policy.name, "approval policy name", MAX_ACTOR),
+            sha256: sha256(input.policy.sha256, "approval policy sha256"),
+        },
+        initial_verdict: "ask",
+        request: input.request,
+        evaluation: input.evaluation,
+        request_sha256: requestSha256,
+    };
+    const dir = approvalDir(input.coordRoot, id);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    chmodSync(dir, 0o700);
+    const created = writeExclusiveJson(join(dir, "request.json"), record);
+    const approval = readWorkflowApproval(input.coordRoot, id);
+    if (approval.request.run_id !== record.run_id ||
+        approval.request.decision_id !== record.decision_id ||
+        approval.request.request_sha256 !== record.request_sha256 ||
+        approval.request.policy.sha256 !== record.policy.sha256) {
+        throw new Error(`approval ${id} already exists for a different policy request`);
+    }
+    return { approval, created };
+}
+export function resolveWorkflowApproval(input) {
+    const approval = readWorkflowApproval(input.coordRoot, input.approvalId);
+    const decision = {
+        schema_version: WORKFLOW_APPROVAL_SCHEMA_VERSION,
+        approval_id: approval.request.id,
+        run_id: approval.request.run_id,
+        verdict: input.verdict,
+        actor: bounded(input.actor, "approval actor", MAX_ACTOR),
+        reason: input.reason === undefined ? undefined : bounded(input.reason, "approval reason", MAX_REASON),
+        decided_at: (input.now ?? (() => new Date().toISOString()))(),
+    };
+    const applied = writeExclusiveJson(join(approvalDir(input.coordRoot, input.approvalId), "decision.json"), decision);
+    const resolved = readWorkflowApproval(input.coordRoot, input.approvalId);
+    if (resolved.decision?.verdict !== input.verdict) {
+        throw new Error(`approval ${input.approvalId} is already ${resolved.status}; conflicting ${input.verdict === "allow" ? "approval" : "denial"} refused`);
+    }
+    if (applied)
+        appendResolutionJournal(input.coordRoot, resolved);
+    return { approval: resolved, applied };
+}
+export function readWorkflowApproval(coordRoot, approvalId) {
+    assertApprovalId(approvalId);
+    const dir = approvalDir(coordRoot, approvalId);
+    const request = readJsonRecord(join(dir, "request.json"));
+    validateRequest(request, approvalId);
+    const decisionPath = join(dir, "decision.json");
+    const decision = existsSync(decisionPath)
+        ? readJsonRecord(decisionPath)
+        : undefined;
+    if (decision)
+        validateDecision(decision, request);
+    return {
+        request,
+        decision,
+        status: decision?.verdict === "allow" ? "approved" : decision ? "denied" : "pending",
+    };
+}
+export function listWorkflowApprovals(coordRoot, options = {}) {
+    if (options.runId)
+        assertRunId(options.runId);
+    const root = approvalsRoot(coordRoot);
+    if (!existsSync(root))
+        return [];
+    const records = [];
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !APPROVAL_ID.test(entry.name))
+            continue;
+        try {
+            const approval = readWorkflowApproval(coordRoot, entry.name);
+            if (options.status && approval.status !== options.status)
+                continue;
+            if (options.runId && approval.request.run_id !== options.runId)
+                continue;
+            records.push(approval);
+        }
+        catch {
+            // A malformed record fails closed when addressed directly, but one bad
+            // directory must not hide the rest of the operator's inbox.
+        }
+    }
+    return records.sort((a, b) => b.request.requested_at.localeCompare(a.request.requested_at));
+}
+export function renderWorkflowApproval(approval) {
+    const lines = [
+        `${approval.request.id}: ${approval.status}`,
+        `run: ${approval.request.run_id}`,
+        `addressed to: ${approval.request.addressed_to}`,
+        `requested: ${approval.request.requested_at}`,
+        `policy: ${approval.request.policy.name}`,
+        `phase: ${approval.request.request.phase}`,
+        `action: ${approval.request.request.action}`,
+        `reason: ${approval.request.evaluation.reason}`,
+    ];
+    if (approval.decision) {
+        lines.push(`decided: ${approval.decision.decided_at} by ${approval.decision.actor}`);
+        if (approval.decision.reason)
+            lines.push(`decision reason: ${approval.decision.reason}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+export function assertWorkflowRunId(runId) {
+    assertRunId(runId);
+}
+function appendResolutionJournal(coordRoot, approval) {
+    const journalPath = join(coordRoot, ".harnery", "workflows", approval.request.run_id, "journal.jsonl");
+    if (!existsSync(journalPath) || !approval.decision)
+        return;
+    const event = {
+        schema_version: 1,
+        run_id: approval.request.run_id,
+        ts: approval.decision.decided_at,
+        event: "approval.resolved",
+        stage: "",
+        approval_id: approval.request.id,
+        decision_id: approval.request.decision_id,
+        verdict: approval.decision.verdict,
+        actor: approval.decision.actor,
+        reason: approval.decision.reason ?? null,
+    };
+    writeFileSync(journalPath, `${JSON.stringify(event)}\n`, { encoding: "utf8", flag: "a" });
+}
+function approvalRequestDigest(policySha256, request, evaluation) {
+    return createHash("sha256")
+        .update(JSON.stringify({ policy_sha256: policySha256, request, evaluation }))
+        .digest("hex");
+}
+function writeExclusiveJson(path, value) {
+    const body = `${JSON.stringify(value, null, 2)}\n`;
+    if (Buffer.byteLength(body) > RECORD_LIMIT_BYTES) {
+        throw new Error(`approval record exceeds ${RECORD_LIMIT_BYTES} bytes`);
+    }
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.tmp-${process.pid}-${randomUUID()}`;
+    try {
+        writeFileSync(temporary, body, { encoding: "utf8", flag: "wx", mode: 0o600 });
+        try {
+            linkSync(temporary, path);
+        }
+        catch (error) {
+            if (error.code === "EEXIST")
+                return false;
+            throw error;
+        }
+        chmodSync(path, 0o600);
+        return true;
+    }
+    finally {
+        if (existsSync(temporary))
+            unlinkSync(temporary);
+    }
+}
+function readJsonRecord(path) {
+    if (!existsSync(path))
+        throw new Error(`approval record not found at ${path}`);
+    const bytes = statSync(path).size;
+    if (bytes <= 0 || bytes > RECORD_LIMIT_BYTES) {
+        throw new Error(`approval record at ${path} has invalid size ${bytes}`);
+    }
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`cannot parse approval record at ${path}: ${error.message}`);
+    }
+}
+function validateRequest(request, approvalId) {
+    if (request.schema_version !== WORKFLOW_APPROVAL_SCHEMA_VERSION ||
+        request.id !== approvalId ||
+        !RUN_ID.test(request.run_id) ||
+        !DECISION_ID.test(request.decision_id) ||
+        workflowApprovalId(request.run_id, request.decision_id) !== approvalId ||
+        !validTimestamp(request.requested_at) ||
+        bounded(request.addressed_to, "approval addressee", MAX_ADDRESSEE) !== request.addressed_to ||
+        bounded(request.policy?.name, "approval policy name", MAX_ACTOR) !== request.policy.name ||
+        request.initial_verdict !== "ask" ||
+        !/^[a-f0-9]{64}$/.test(request.request_sha256) ||
+        !/^[a-f0-9]{64}$/.test(request.policy?.sha256) ||
+        !validPolicyRequest(request.request) ||
+        !validPolicyEvaluation(request.evaluation) ||
+        approvalRequestDigest(request.policy.sha256, request.request, request.evaluation) !==
+            request.request_sha256) {
+        throw new Error(`approval ${approvalId} has an unsupported or mismatched request record`);
+    }
+}
+function validateDecision(decision, request) {
+    if (decision.schema_version !== WORKFLOW_APPROVAL_SCHEMA_VERSION ||
+        decision.approval_id !== request.id ||
+        decision.run_id !== request.run_id ||
+        (decision.verdict !== "allow" && decision.verdict !== "deny") ||
+        bounded(decision.actor, "approval actor", MAX_ACTOR) !== decision.actor ||
+        (decision.reason !== undefined &&
+            bounded(decision.reason, "approval reason", MAX_REASON) !== decision.reason) ||
+        !validTimestamp(decision.decided_at)) {
+        throw new Error(`approval ${request.id} has an unsupported or mismatched decision record`);
+    }
+}
+function validPolicyRequest(request) {
+    if (!request || typeof request !== "object")
+        return false;
+    return ((request.phase === "dispatch" || request.phase === "external_mutation") &&
+        typeof request.action === "string" &&
+        request.action.length > 0 &&
+        ["shared", "worktree", "sandbox", "remote"].includes(request.isolation) &&
+        ["enabled", "disabled", "unknown"].includes(request.network_access));
+}
+function validPolicyEvaluation(evaluation) {
+    if (!evaluation || typeof evaluation !== "object")
+        return false;
+    return (evaluation.verdict === "ask" &&
+        typeof evaluation.reason === "string" &&
+        evaluation.reason.length > 0 &&
+        Array.isArray(evaluation.rules) &&
+        evaluation.rules.every((rule) => rule &&
+            typeof rule.code === "string" &&
+            (rule.verdict === "allow" || rule.verdict === "ask" || rule.verdict === "deny") &&
+            typeof rule.reason === "string"));
+}
+function validTimestamp(value) {
+    return typeof value === "string" && value.length <= 40 && Number.isFinite(Date.parse(value));
+}
+function approvalsRoot(coordRoot) {
+    return join(coordRoot, ".harnery", "approvals");
+}
+function approvalDir(coordRoot, approvalId) {
+    assertApprovalId(approvalId);
+    return join(approvalsRoot(coordRoot), approvalId);
+}
+function assertApprovalId(approvalId) {
+    if (!APPROVAL_ID.test(approvalId)) {
+        throw new Error(`invalid workflow approval id ${JSON.stringify(approvalId)}`);
+    }
+}
+function assertRunId(runId) {
+    if (!RUN_ID.test(runId))
+        throw new Error(`invalid workflow run id ${JSON.stringify(runId)}`);
+}
+function sha256(value, field) {
+    if (!/^[a-f0-9]{64}$/.test(value))
+        throw new Error(`${field} must be a SHA-256 digest`);
+    return value;
+}
+function bounded(value, field, max) {
+    if (typeof value !== "string")
+        throw new Error(`${field} must be a string`);
+    const normalized = Array.from(value, (character) => {
+        const code = character.charCodeAt(0);
+        return code < 32 || code === 127 ? " " : character;
+    })
+        .join("")
+        .replace(/\s+/g, " ")
+        .trim();
+    if (!normalized)
+        throw new Error(`${field} must not be empty`);
+    if (normalized.length > max)
+        throw new Error(`${field} exceeds ${max} characters`);
+    return normalized;
+}

package/dist/core/workflow/engine.d.ts

@@ -22,5 +22,11 @@ export declare class WorkflowRunError extends Error {
     readonly proofPath: string;
     constructor(message: string, runId: string, proofPath: string, cause?: unknown);
 }
+export declare class WorkflowParkedError extends Error {
+    readonly runId: string;
+    readonly approvalId: string;
+    readonly journalPath: string;
+    constructor(message: string, runId: string, approvalId: string, journalPath: string);
+}
 export declare function runWorkflow(scriptPath: string, opts: EngineOpts): Promise<RunReport>;
 //# sourceMappingURL=engine.d.ts.map

package/dist/core/workflow/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/core/workflow/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAuBH,OAAO,KAAK,EAEV,UAAU,EAEV,SAAS,EAOV,MAAM,YAAY,CAAC;AAYpB,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAM/E;AAED,wBAAsB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAsmB1F"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/core/workflow/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAoCH,OAAO,KAAK,EAEV,UAAU,EAEV,SAAS,EAOV,MAAM,YAAY,CAAC;AAYpB,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAM/E;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAEjB,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM;CAOpF;AAED,wBAAsB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CA2B1F"}