@a5c-ai/tasks-mux 5.0.1-staging.04ca6ab00d21

package/dist/mcp/tools/verify-answer.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import { selectBreakpointAnswer, supportsProvenAnswers, unsupportedBackendFeatureMessage, } from "../../backend.js";
+import { isProvenBreakpointAnswer } from "../../types.js";
+import { verifyAnswer } from "../../proven/verify.js";
+// ── Tool Description ────────────────────────────────────────────────────
+export const verifyBreakpointAnswerDescription = "Verify the cryptographic signature of a breakpoint answer against " +
+    "trusted public keys. Returns verification status and signer identity.";
+// ── Tool Param Schema ───────────────────────────────────────────────────
+export const verifyBreakpointAnswerParams = {
+    breakpointId: z.string().describe("The ID of the breakpoint whose answer to verify."),
+    backend: z.string().optional(),
+    breakpointsDir: z.string().optional(),
+};
+// ── Handler ─────────────────────────────────────────────────────────────
+export async function handleVerifyBreakpointAnswer(params, backend) {
+    if (!params.breakpointId || params.breakpointId.length === 0) {
+        throw new Error("breakpointId is required and must be non-empty");
+    }
+    const breakpoint = await backend.getBreakpoint(params.breakpointId);
+    if (!breakpoint.answers || breakpoint.answers.length === 0) {
+        throw new Error("No answers found for this breakpoint");
+    }
+    const answer = selectBreakpointAnswer(breakpoint);
+    if (!answer) {
+        if (breakpoint.selectedAnswer) {
+            throw new Error(`Selected answer ${breakpoint.selectedAnswer} was not found on breakpoint ${breakpoint.id}`);
+        }
+        throw new Error("No answers found for this breakpoint");
+    }
+    if (!isProvenBreakpointAnswer(answer)) {
+        if (!supportsProvenAnswers(backend.name)) {
+            throw new Error(unsupportedBackendFeatureMessage(backend.name, "signed answers"));
+        }
+        throw new Error("Answer is not signed/proven -- no cryptographic signature found");
+    }
+    const result = await verifyAnswer(answer, params.breakpointsDir);
+    return result;
+}

package/dist/proven/index.d.ts

@@ -0,0 +1,5 @@
+export { generateKeyPair, saveTrustedPublicKey, savePrivateKey, loadTrustedPublicKeys, loadPrivateKey, rotateKey, } from "./keys.js";
+export type { KeyPairMetadata, PublicKeyRecord, PrivateKeyRecord, } from "./keys.js";
+export { signAnswer, signAnswerWithKeyRecord } from "./sign.js";
+export { verifyAnswer } from "./verify.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/proven/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/proven/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,cAAc,EACd,qBAAqB,EACrB,cAAc,EACd,SAAS,GACV,MAAM,WAAW,CAAC;AAEnB,YAAY,EACV,eAAe,EACf,eAAe,EACf,gBAAgB,GACjB,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,UAAU,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/dist/proven/index.js

@@ -0,0 +1,3 @@
+export { generateKeyPair, saveTrustedPublicKey, savePrivateKey, loadTrustedPublicKeys, loadPrivateKey, rotateKey, } from "./keys.js";
+export { signAnswer, signAnswerWithKeyRecord } from "./sign.js";
+export { verifyAnswer } from "./verify.js";

package/dist/proven/keys.d.ts

@@ -0,0 +1,33 @@
+import type { PublicKeyRecord, PrivateKeyRecord } from "./types.js";
+/**
+ * Generate a new Ed25519 key pair for a responder.
+ */
+export declare function generateKeyPair(responderId: string, responderName: string): {
+    publicKeyRecord: PublicKeyRecord;
+    privateKeyRecord: PrivateKeyRecord;
+};
+/**
+ * Save a public key to the trusted keys directory (git-tracked).
+ */
+export declare function saveTrustedPublicKey(publicKeyRecord: PublicKeyRecord, baseDir?: string): Promise<string>;
+/**
+ * Save a private key to the private keys directory (gitignored).
+ */
+export declare function savePrivateKey(privateKeyRecord: PrivateKeyRecord, baseDir?: string): Promise<string>;
+/**
+ * Load all trusted public keys from the trusted directory.
+ */
+export declare function loadTrustedPublicKeys(baseDir?: string): Promise<PublicKeyRecord[]>;
+/**
+ * Load a private key by fingerprint.
+ */
+export declare function loadPrivateKey(fingerprint: string, baseDir?: string): Promise<PrivateKeyRecord | null>;
+/**
+ * Rotate a key: generate new pair, save both, mark old public key as expired.
+ */
+export declare function rotateKey(responderId: string, responderName: string, oldFingerprint: string, baseDir?: string): Promise<{
+    publicKeyRecord: PublicKeyRecord;
+    privateKeyRecord: PrivateKeyRecord;
+}>;
+export type { PublicKeyRecord, PrivateKeyRecord, KeyPairMetadata } from "./types.js";
+//# sourceMappingURL=keys.d.ts.map

package/dist/proven/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../src/proven/keys.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEpE;;GAEG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,GACpB;IAAE,eAAe,EAAE,eAAe,CAAC;IAAC,gBAAgB,EAAE,gBAAgB,CAAA;CAAE,CAyB1E;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,eAAe,EAAE,eAAe,EAChC,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CASjB;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,gBAAgB,EAAE,gBAAgB,EAClC,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CASjB;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,eAAe,EAAE,CAAC,CAmB5B;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAYlC;AAED;;GAEG;AACH,wBAAsB,SAAS,CAC7B,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,EACtB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,eAAe,EAAE,eAAe,CAAC;IAAC,gBAAgB,EAAE,gBAAgB,CAAA;CAAE,CAAC,CAqBnF;AAED,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}

package/dist/proven/keys.js

@@ -0,0 +1,117 @@
+import { generateKeyPairSync, createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+/**
+ * Generate a new Ed25519 key pair for a responder.
+ */
+export function generateKeyPair(responderId, responderName) {
+    const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+    const pubDer = publicKey.export({ type: "spki", format: "der" });
+    const privPkcs8 = privateKey.export({ type: "pkcs8", format: "der" });
+    const fingerprint = createHash("sha256").update(pubDer).digest("hex");
+    const now = new Date().toISOString();
+    return {
+        publicKeyRecord: {
+            publicKey: pubDer.toString("base64"),
+            metadata: {
+                fingerprint,
+                responderId,
+                responderName,
+                createdAt: now,
+            },
+        },
+        privateKeyRecord: {
+            privateKey: privPkcs8.toString("base64"),
+            fingerprint,
+            responderId,
+        },
+    };
+}
+/**
+ * Save a public key to the trusted keys directory (git-tracked).
+ */
+export async function saveTrustedPublicKey(publicKeyRecord, baseDir) {
+    const dir = baseDir
+        ? path.join(baseDir, ".keys", "trusted")
+        : path.resolve(process.cwd(), ".breakpoints", ".keys", "trusted");
+    await fs.mkdir(dir, { recursive: true });
+    const filePath = path.join(dir, `${publicKeyRecord.metadata.fingerprint}.pub.json`);
+    await fs.writeFile(filePath, JSON.stringify(publicKeyRecord, null, 2) + "\n", "utf-8");
+    return filePath;
+}
+/**
+ * Save a private key to the private keys directory (gitignored).
+ */
+export async function savePrivateKey(privateKeyRecord, baseDir) {
+    const dir = baseDir
+        ? path.join(baseDir, ".keys", "private")
+        : path.resolve(process.cwd(), ".breakpoints", ".keys", "private");
+    await fs.mkdir(dir, { recursive: true });
+    const filePath = path.join(dir, `${privateKeyRecord.fingerprint}.key.json`);
+    await fs.writeFile(filePath, JSON.stringify(privateKeyRecord, null, 2) + "\n", "utf-8");
+    return filePath;
+}
+/**
+ * Load all trusted public keys from the trusted directory.
+ */
+export async function loadTrustedPublicKeys(baseDir) {
+    const dir = baseDir
+        ? path.join(baseDir, ".keys", "trusted")
+        : path.resolve(process.cwd(), ".breakpoints", ".keys", "trusted");
+    let files;
+    try {
+        files = await fs.readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const keys = [];
+    for (const file of files) {
+        if (!file.endsWith(".pub.json"))
+            continue;
+        const raw = await fs.readFile(path.join(dir, file), "utf-8");
+        keys.push(JSON.parse(raw));
+    }
+    return keys;
+}
+/**
+ * Load a private key by fingerprint.
+ */
+export async function loadPrivateKey(fingerprint, baseDir) {
+    const dir = baseDir
+        ? path.join(baseDir, ".keys", "private")
+        : path.resolve(process.cwd(), ".breakpoints", ".keys", "private");
+    const filePath = path.join(dir, `${fingerprint}.key.json`);
+    try {
+        const raw = await fs.readFile(filePath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Rotate a key: generate new pair, save both, mark old public key as expired.
+ */
+export async function rotateKey(responderId, responderName, oldFingerprint, baseDir) {
+    // Mark old key as expired
+    const trustedDir = baseDir
+        ? path.join(baseDir, ".keys", "trusted")
+        : path.resolve(process.cwd(), ".breakpoints", ".keys", "trusted");
+    const oldKeyPath = path.join(trustedDir, `${oldFingerprint}.pub.json`);
+    try {
+        const raw = await fs.readFile(oldKeyPath, "utf-8");
+        const oldKey = JSON.parse(raw);
+        oldKey.metadata.expiresAt = new Date().toISOString();
+        oldKey.metadata.note = `Rotated. Superseded by new key for ${responderId}.`;
+        await fs.writeFile(oldKeyPath, JSON.stringify(oldKey, null, 2) + "\n", "utf-8");
+    }
+    catch {
+        // Old key may not exist; that's fine
+    }
+    // Generate and save new pair
+    const newPair = generateKeyPair(responderId, responderName);
+    await saveTrustedPublicKey(newPair.publicKeyRecord, baseDir);
+    await savePrivateKey(newPair.privateKeyRecord, baseDir);
+    return newPair;
+}

package/dist/proven/sign.d.ts

@@ -0,0 +1,16 @@
+import type { BreakpointAnswer, ProvenBreakpointAnswer } from "../types.js";
+import type { PrivateKeyRecord } from "./types.js";
+/**
+ * Sign a BreakpointAnswer with the responder's private key.
+ *
+ * Returns a ProvenBreakpointAnswer with the signature and key metadata.
+ */
+export declare function signAnswer(answer: BreakpointAnswer, fingerprint: string, baseDir?: string): Promise<ProvenBreakpointAnswer>;
+/**
+ * Sign a BreakpointAnswer using an already-loaded PrivateKeyRecord.
+ *
+ * This avoids requiring the key to be persisted on disk and is useful
+ * for backends that load the key from a configured path.
+ */
+export declare function signAnswerWithKeyRecord(answer: BreakpointAnswer, keyRecord: PrivateKeyRecord): ProvenBreakpointAnswer;
+//# sourceMappingURL=sign.d.ts.map

package/dist/proven/sign.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sign.d.ts","sourceRoot":"","sources":["../../src/proven/sign.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAE5E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AA4BnD;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,gBAAgB,EACxB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,sBAAsB,CAAC,CAOjC;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,gBAAgB,EACxB,SAAS,EAAE,gBAAgB,GAC1B,sBAAsB,CAiBxB"}

package/dist/proven/sign.js

@@ -0,0 +1,60 @@
+import { createPrivateKey, sign as cryptoSign } from "node:crypto";
+import { loadPrivateKey } from "./keys.js";
+/**
+ * Fields included in the signature. The order is canonical.
+ */
+const SIGNED_FIELDS = [
+    "id",
+    "breakpointId",
+    "responderId",
+    "text",
+    "approved",
+    "confidence",
+    "answeredAt",
+];
+/**
+ * Build the canonical signing payload from an answer.
+ * Fields are sorted, null/undefined serialized as empty string.
+ */
+function buildSigningPayload(answer) {
+    const parts = [];
+    for (const field of SIGNED_FIELDS) {
+        const value = answer[field];
+        parts.push(`${field}=${value ?? ""}`);
+    }
+    return Buffer.from(parts.join("\n"), "utf-8");
+}
+/**
+ * Sign a BreakpointAnswer with the responder's private key.
+ *
+ * Returns a ProvenBreakpointAnswer with the signature and key metadata.
+ */
+export async function signAnswer(answer, fingerprint, baseDir) {
+    const keyRecord = await loadPrivateKey(fingerprint, baseDir);
+    if (!keyRecord) {
+        throw new Error(`Private key not found for fingerprint: ${fingerprint}`);
+    }
+    return signAnswerWithKeyRecord(answer, keyRecord);
+}
+/**
+ * Sign a BreakpointAnswer using an already-loaded PrivateKeyRecord.
+ *
+ * This avoids requiring the key to be persisted on disk and is useful
+ * for backends that load the key from a configured path.
+ */
+export function signAnswerWithKeyRecord(answer, keyRecord) {
+    const privateKey = createPrivateKey({
+        key: Buffer.from(keyRecord.privateKey, "base64"),
+        format: "der",
+        type: "pkcs8",
+    });
+    const payload = buildSigningPayload(answer);
+    const signature = cryptoSign(null, payload, privateKey);
+    return {
+        ...answer,
+        signature: signature.toString("base64"),
+        publicKeyFingerprint: keyRecord.fingerprint,
+        signedAt: new Date().toISOString(),
+        signedFields: [...SIGNED_FIELDS],
+    };
+}

package/dist/proven/types.d.ts

@@ -0,0 +1,26 @@
+export interface KeyPairMetadata {
+    /** Hex-encoded fingerprint (SHA-256 of public key DER). */
+    fingerprint: string;
+    /** Responder identity associated with this key. */
+    responderId: string;
+    responderName: string;
+    /** ISO timestamp of key creation. */
+    createdAt: string;
+    /** ISO timestamp when this key should no longer be used for signing. */
+    expiresAt?: string;
+    /** Human-readable note. */
+    note?: string;
+}
+export interface PublicKeyRecord {
+    /** Base64-encoded Ed25519 public key (DER/SPKI format). */
+    publicKey: string;
+    metadata: KeyPairMetadata;
+}
+export interface PrivateKeyRecord {
+    /** Base64-encoded Ed25519 private key (PKCS8 format). */
+    privateKey: string;
+    /** Fingerprint linking to the corresponding public key. */
+    fingerprint: string;
+    responderId: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/proven/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/proven/types.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,eAAe;IAC9B,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2BAA2B;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,eAAe,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB"}

package/dist/proven/types.js

@@ -0,0 +1,5 @@
+// ── Proven-specific types ───────────────────────────────────────────────
+// These types are used internally by the proven subsystem for key management.
+// The ProvenBreakpointAnswer and ProvenVerificationResult schemas live in
+// src/types.ts as they are part of the public domain model.
+export {};

package/dist/proven/verify.d.ts

@@ -0,0 +1,6 @@
+import type { ProvenBreakpointAnswer, ProvenVerificationResult } from "../types.js";
+/**
+ * Verify a proven breakpoint answer against trusted public keys.
+ */
+export declare function verifyAnswer(provenAnswer: ProvenBreakpointAnswer, baseDir?: string): Promise<ProvenVerificationResult>;
+//# sourceMappingURL=verify.d.ts.map

package/dist/proven/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../src/proven/verify.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,wBAAwB,EAAoB,MAAM,aAAa,CAAC;AAetG;;GAEG;AACH,wBAAsB,YAAY,CAChC,YAAY,EAAE,sBAAsB,EACpC,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,wBAAwB,CAAC,CAiDnC"}

package/dist/proven/verify.js

@@ -0,0 +1,58 @@
+import { createPublicKey, verify as cryptoVerify } from "node:crypto";
+import { loadTrustedPublicKeys } from "./keys.js";
+/**
+ * Rebuild the canonical signing payload for verification.
+ */
+function buildSigningPayload(answer, signedFields) {
+    const parts = [];
+    for (const field of signedFields) {
+        const value = answer[field];
+        parts.push(`${field}=${value ?? ""}`);
+    }
+    return Buffer.from(parts.join("\n"), "utf-8");
+}
+/**
+ * Verify a proven breakpoint answer against trusted public keys.
+ */
+export async function verifyAnswer(provenAnswer, baseDir) {
+    const trustedKeys = await loadTrustedPublicKeys(baseDir);
+    const matchingKey = trustedKeys.find((k) => k.metadata.fingerprint === provenAnswer.publicKeyFingerprint);
+    if (!matchingKey) {
+        return {
+            valid: false,
+            publicKeyFingerprint: provenAnswer.publicKeyFingerprint,
+            reason: "Public key not found in trusted keys",
+            verifiedAt: new Date().toISOString(),
+        };
+    }
+    // Check key expiration
+    if (matchingKey.metadata.expiresAt) {
+        const expiresAt = new Date(matchingKey.metadata.expiresAt);
+        const signedAt = new Date(provenAnswer.signedAt);
+        if (signedAt > expiresAt) {
+            return {
+                valid: false,
+                publicKeyFingerprint: provenAnswer.publicKeyFingerprint,
+                responderName: matchingKey.metadata.responderName,
+                reason: "Key was expired at time of signing",
+                verifiedAt: new Date().toISOString(),
+            };
+        }
+    }
+    // Verify signature
+    const publicKey = createPublicKey({
+        key: Buffer.from(matchingKey.publicKey, "base64"),
+        format: "der",
+        type: "spki",
+    });
+    const payload = buildSigningPayload(provenAnswer, provenAnswer.signedFields);
+    const signatureBuffer = Buffer.from(provenAnswer.signature, "base64");
+    const isValid = cryptoVerify(null, payload, publicKey, signatureBuffer);
+    return {
+        valid: isValid,
+        publicKeyFingerprint: provenAnswer.publicKeyFingerprint,
+        responderName: matchingKey.metadata.responderName,
+        reason: isValid ? "Signature verified successfully" : "Signature verification failed",
+        verifiedAt: new Date().toISOString(),
+    };
+}