cool-workflow 0.1.78

package/dist/telemetry-attestation.js

@@ -0,0 +1,156 @@
+"use strict";
+// Telemetry attestation (Track 1) — make "auditable" a FACT, not a claim.
+//
+// The agent self-reports its token usage on stdout (parseAgentReport). A control
+// plane that records that number verbatim is recording a CLAIM: a tampered or
+// fabricated usage survives untouched. This module is the verify gate that turns
+// the claim into an attestation:
+//
+//   - The EXECUTOR signs a canonical payload binding {usage, runId, taskId,
+//     promptDigest} with its private key (ed25519). The binding context is what
+//     stops one task's signature being replayed onto another.
+//   - CW VERIFIES that signature against an operator-provisioned PUBLIC key.
+//     CW holds ONLY the public key — it can verify, but can neither forge a
+//     signature nor (the red line) call a model to measure usage itself. A
+//     third-party auditor with the same public key can re-verify independently.
+//
+// HONEST CEILING [load-bearing]: a signature proves the usage came from the
+// keyholder and was not tampered in transit — NON-REPUDIABLE ATTRIBUTION, not
+// ground-truth measurement. A dishonest keyholder can still sign a lie, but the
+// lie is now cryptographically bound to its signer. That is strictly stronger
+// than self-signed sha256 (which any party can recompute) and is the most a
+// delegating control-plane can claim without measuring (which it must not).
+//
+// Default is honest: no signature ⇒ `unattested`, no usage ⇒ `absent`. Usage is
+// NEVER silently recorded as trusted.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stableStringify = stableStringify;
+exports.canonicalTelemetryPayload = canonicalTelemetryPayload;
+exports.normalizeReportedUsage = normalizeReportedUsage;
+exports.verifyTelemetryAttestation = verifyTelemetryAttestation;
+exports.resolveTrustPublicKey = resolveTrustPublicKey;
+exports.signTelemetry = signTelemetry;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+/** Deterministic, key-sorted JSON so signer and verifier hash byte-identical
+ *  input regardless of object key order. */
+function stableStringify(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    const entries = Object.keys(value)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`);
+    return `{${entries.join(",")}}`;
+}
+/** The exact bytes the executor signs and CW verifies. */
+function canonicalTelemetryPayload(usage, ctx) {
+    return stableStringify({
+        usage: usage ?? null,
+        runId: ctx.runId,
+        taskId: ctx.taskId,
+        promptDigest: ctx.promptDigest
+    });
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function numberAt(usage, ...keys) {
+    for (const key of keys) {
+        const value = usage[key];
+        const num = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
+        if (Number.isFinite(num))
+            return num;
+    }
+    return undefined;
+}
+/** Map the agent's free-form usage report onto UsageRecord token buckets, tolerating
+ *  snake_case / camelCase variants (input_tokens vs inputTokens, etc.). CW never
+ *  invents a number — an unreported bucket stays undefined, never zero. */
+function normalizeReportedUsage(usage) {
+    if (!usage)
+        return {};
+    return {
+        inputTokens: numberAt(usage, "inputTokens", "input_tokens", "promptTokens", "prompt_tokens"),
+        outputTokens: numberAt(usage, "outputTokens", "output_tokens", "completionTokens", "completion_tokens"),
+        cacheReadTokens: numberAt(usage, "cacheReadTokens", "cache_read_tokens", "cacheReadInputTokens", "cache_read_input_tokens"),
+        cacheWriteTokens: numberAt(usage, "cacheWriteTokens", "cache_write_tokens", "cacheCreationInputTokens", "cache_creation_input_tokens"),
+        totalTokens: numberAt(usage, "totalTokens", "total_tokens")
+    };
+}
+/** Verify the agent's signed usage against the operator-provisioned public key.
+ *  Pure + deterministic (no clock, no env). Returns a status, never throws. */
+function verifyTelemetryAttestation(usage, signatureB64, trustPublicKeyPem, ctx) {
+    if (!usage || Object.keys(usage).length === 0) {
+        return { status: "absent", reason: "agent reported no usage" };
+    }
+    if (!signatureB64) {
+        return { status: "unattested", reason: "reported usage carries no signature" };
+    }
+    if (!trustPublicKeyPem) {
+        return { status: "unattested", reason: "no trust key configured (set agent attestPublicKey / CW_AGENT_ATTEST_PUBKEY)" };
+    }
+    let publicKey;
+    try {
+        publicKey = node_crypto_1.default.createPublicKey(trustPublicKeyPem);
+    }
+    catch (error) {
+        return { status: "unattested", reason: `trust key unreadable: ${messageOf(error)}` };
+    }
+    let signature;
+    try {
+        signature = Buffer.from(signatureB64, "base64");
+        if (signature.length === 0)
+            return { status: "unattested", reason: "signature is empty" };
+    }
+    catch {
+        return { status: "unattested", reason: "signature is not valid base64" };
+    }
+    const payload = Buffer.from(canonicalTelemetryPayload(usage, ctx), "utf8");
+    let ok = false;
+    try {
+        ok = node_crypto_1.default.verify(null, payload, publicKey, signature);
+    }
+    catch (error) {
+        return { status: "unattested", reason: `verification error: ${messageOf(error)}` };
+    }
+    return ok
+        ? { status: "attested", algorithm: "ed25519" }
+        : { status: "unattested", reason: "signature does not match reported usage (tampered, replayed, or wrong key)" };
+}
+/** Resolve a trust key from a config value that is EITHER an inline PEM or a path
+ *  to a `.pem` file. Returns undefined when absent/unreadable (⇒ `unattested`,
+ *  never a hard throw). CW only ever loads a PUBLIC key here. */
+function resolveTrustPublicKey(value) {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return undefined;
+    if (trimmed.includes("BEGIN") && trimmed.includes("KEY"))
+        return trimmed;
+    try {
+        // Lazy require so a bundle that never resolves a key path pays no fs cost.
+        const fs = require("node:fs");
+        if (fs.existsSync(trimmed))
+            return fs.readFileSync(trimmed, "utf8");
+    }
+    catch {
+        /* fall through to undefined */
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// EXECUTOR-SIDE HELPER — the CW RUNTIME NEVER CALLS THIS.
+// Provided for signing wrappers around `claude -p`/endpoints and for tests. It
+// touches a private key, never a model, so it does not cross the red line; it is
+// kept here only so signer and verifier share one canonicalization.
+// ---------------------------------------------------------------------------
+function signTelemetry(usage, privateKeyPem, ctx) {
+    const payload = Buffer.from(canonicalTelemetryPayload(usage, ctx), "utf8");
+    const key = node_crypto_1.default.createPrivateKey(privateKeyPem);
+    return node_crypto_1.default.sign(null, payload, key).toString("base64");
+}

package/dist/telemetry-ledger.js

@@ -0,0 +1,145 @@
+"use strict";
+// Telemetry attestation ledger (Track 1) — make the RECORDED attestation itself
+// tamper-evident, not just the in-flight signature.
+//
+// The executor's signature (telemetry-attestation.ts) proves the agent SAID a
+// given usage. This ledger proves CW RECORDED exactly that and nobody edited the
+// record afterward: an append-only, hash-chained overlay (`telemetry.json`, a
+// runDir peer of reclaimed.json), one entry per agent hop. Each entry chains to
+// the prior via prevHash; recordHash = sha256(canonical entry sans recordHash).
+// Flip a recorded verdict (`unattested`→`attested`), or edit a recorded usage
+// digest, and the chain no longer recomputes — `verifyTelemetryLedger` catches it.
+//
+// Same discipline as reclamation.ts's tombstone chain: APPEND-ONLY (never rewrite
+// a prior entry), DURABLE (temp→fsync→rename via writeJson), and verify recomputes
+// every hash independently — it never trusts the stored value.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TELEMETRY_LEDGER_SCHEMA_VERSION = void 0;
+exports.telemetryLedgerPath = telemetryLedgerPath;
+exports.loadTelemetryLedger = loadTelemetryLedger;
+exports.genesisPrevHash = genesisPrevHash;
+exports.computeRecordHash = computeRecordHash;
+exports.reportedUsageDigest = reportedUsageDigest;
+exports.appendTelemetryAttestation = appendTelemetryAttestation;
+exports.verifyTelemetryLedger = verifyTelemetryLedger;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const state_1 = require("./state");
+const execution_backend_1 = require("./execution-backend");
+const telemetry_attestation_1 = require("./telemetry-attestation");
+exports.TELEMETRY_LEDGER_SCHEMA_VERSION = 1;
+function telemetryLedgerPath(run) {
+    return node_path_1.default.join(run.paths.runDir, "telemetry.json");
+}
+/** Load the ledger; fail closed to an empty chain on a malformed overlay (a
+ *  corrupt file must never brick the run — and an empty chain verifies as such). */
+function loadTelemetryLedger(run) {
+    const file = telemetryLedgerPath(run);
+    if (!node_fs_1.default.existsSync(file))
+        return { schemaVersion: 1, runId: run.id, records: [] };
+    try {
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(file, "utf8"));
+        return { schemaVersion: 1, runId: run.id, records: Array.isArray(parsed.records) ? parsed.records : [] };
+    }
+    catch {
+        return { schemaVersion: 1, runId: run.id, records: [] };
+    }
+}
+/** genesis prevHash for a run's chain (no prior record). */
+function genesisPrevHash(runId) {
+    return (0, execution_backend_1.sha256)(`cw-telemetry-ledger:${runId}`);
+}
+/** The canonical bytes a recordHash binds — every field except recordHash itself.
+ *  Recomputed independently by verifyTelemetryLedger. */
+function recordHashInput(record) {
+    return (0, telemetry_attestation_1.stableStringify)({
+        schemaVersion: record.schemaVersion,
+        runId: record.runId,
+        recordId: record.recordId,
+        recordedAt: record.recordedAt,
+        workerId: record.workerId,
+        taskId: record.taskId,
+        promptDigest: record.promptDigest,
+        reportedUsageDigest: record.reportedUsageDigest,
+        usageSignature: record.usageSignature || null,
+        attestation: record.attestation,
+        attestationReason: record.attestationReason || null,
+        prevHash: record.prevHash
+    });
+}
+function computeRecordHash(record) {
+    return (0, execution_backend_1.sha256)(recordHashInput(record));
+}
+/** sha256 of the canonical reported usage (compact, chainable). Absent usage gets
+ *  the digest of `null`, so "the agent reported nothing" is itself bound. */
+function reportedUsageDigest(usage) {
+    return (0, execution_backend_1.sha256)((0, telemetry_attestation_1.stableStringify)(usage ?? null));
+}
+let recordCounter = 0;
+function recordId(now) {
+    recordCounter += 1;
+    const stamp = now.replace(/[-:.TZ]/g, "").slice(0, 14);
+    return `tel-${stamp}-${String(recordCounter).padStart(3, "0")}`;
+}
+/** Append one attestation record DURABLY to the append-only chain, linking it to
+ *  the prior record (or genesis). Returns the committed record. */
+function appendTelemetryAttestation(run, input) {
+    const ledger = loadTelemetryLedger(run);
+    const now = input.now || new Date().toISOString();
+    const prevHash = ledger.records.length ? ledger.records[ledger.records.length - 1].recordHash : genesisPrevHash(run.id);
+    const base = {
+        schemaVersion: 1,
+        runId: run.id,
+        recordId: recordId(now),
+        recordedAt: now,
+        workerId: input.workerId,
+        taskId: input.taskId,
+        promptDigest: input.promptDigest,
+        reportedUsageDigest: reportedUsageDigest(input.reportedUsage),
+        usageSignature: input.usageSignature,
+        attestation: input.attestation,
+        attestationReason: input.attestationReason,
+        prevHash
+    };
+    const record = { ...base, recordHash: computeRecordHash(base) };
+    ledger.records.push(record);
+    (0, state_1.writeJson)(telemetryLedgerPath(run), ledger, { durable: true });
+    return record;
+}
+/** Re-prove the whole telemetry chain for a run: prevHash linkage + per-record
+ *  hash recompute. Recomputes every hash independently — never trusts the stored
+ *  value — so an edited record/verdict is detected. An empty ledger verifies as
+ *  present:false (nothing to prove), NOT a failure. */
+function verifyTelemetryLedger(run) {
+    const records = loadTelemetryLedger(run).records;
+    const checks = [];
+    const tally = { attested: 0, unattested: 0, absent: 0 };
+    for (const record of records)
+        tally[record.attestation] += 1;
+    if (!records.length) {
+        return { present: false, verified: true, records, checks, ...tally };
+    }
+    // (a) chain linkage: genesis = sha256("cw-telemetry-ledger:"+runId).
+    let chainOk = true;
+    for (let i = 0; i < records.length; i++) {
+        const expectedPrev = i === 0 ? genesisPrevHash(run.id) : records[i - 1].recordHash;
+        const pass = records[i].prevHash === expectedPrev;
+        if (!pass)
+            chainOk = false;
+        checks.push({ name: `chain-link[${i}]`, pass, code: pass ? undefined : "telemetry-chain-broken" });
+    }
+    // (b) per-record independent hash recompute (digest integrity).
+    let digestsOk = true;
+    for (let i = 0; i < records.length; i++) {
+        const { recordHash, ...rest } = records[i];
+        const recomputed = computeRecordHash(rest);
+        const pass = recomputed === recordHash;
+        if (!pass)
+            digestsOk = false;
+        checks.push({ name: `record-hash[${i}]`, pass, code: pass ? undefined : "telemetry-digest-mismatch" });
+    }
+    return { present: true, verified: chainOk && digestsOk, records, checks, ...tally };
+}