@agentguard-run/spend 0.14.0 → 0.15.0

package/src/workflow/context.ts

@@ -127,7 +127,7 @@ export class WorkflowContext {
     const cost = this.extractOutcomeCost(result);
     const parentReceiptId = this._last_receipt_id;
     const chainHash = this._receipts.length ? await computeChainHash(this._receipts[this._receipts.length - 1]!) : null;
-    const receipt = buildReceipt({
+    const receipt = await buildReceipt({
       workflow_id: this.workflow_id,
       outcome_name: name,
       user_id: this.user_id,
@@ -137,6 +137,7 @@ export class WorkflowContext {
       workflow_checkpoint_idx: null,
       workflow_total_spend_usd_to_date: this._total_spend_usd + cost,
       reviewer_cascade: extractReviewerCascade(result),
+      signingKeys: this.config.signingKeys,
     });
 
     this._receipts.push(receipt);
@@ -196,7 +197,7 @@ export class WorkflowContext {
 
   private async writeCheckpoint(label?: string): Promise<CheckpointReceipt> {
     const chainHash = this._receipts.length ? await computeChainHash(this._receipts[this._receipts.length - 1]!) : null;
-    const checkpoint = buildReceipt({
+    const checkpoint = await buildReceipt({
       workflow_id: this.workflow_id,
       outcome_name: 'CHECKPOINT',
       user_id: this.user_id,
@@ -208,6 +209,7 @@ export class WorkflowContext {
       is_checkpoint: true,
       checkpoint_label: label ?? null,
       receipt_type: 'checkpoint',
+      signingKeys: this.config.signingKeys,
     }) as CheckpointReceipt;
     this._receipts.push(checkpoint);
     this._last_checkpoint_id = checkpoint.receipt_id;
@@ -219,7 +221,7 @@ export class WorkflowContext {
 
   private async writeFinalReceipt(type: 'cancelled' | 'completed' | 'cap_hit', reason: string): Promise<void> {
     const chainHash = this._receipts.length ? await computeChainHash(this._receipts[this._receipts.length - 1]!) : null;
-    const receipt = buildReceipt({
+    const receipt = await buildReceipt({
       workflow_id: this.workflow_id,
       outcome_name: type === 'completed' ? 'WORKFLOW_COMPLETED' : 'WORKFLOW_STOPPED',
       user_id: this.user_id,
@@ -230,6 +232,7 @@ export class WorkflowContext {
       workflow_total_spend_usd_to_date: this._total_spend_usd,
       receipt_type: type === 'cancelled' ? 'cancel' : type,
       cancelled_reason: reason,
+      signingKeys: this.config.signingKeys,
     });
     this._receipts.push(receipt);
     this._last_receipt_id = receipt.receipt_id;

package/src/workflow/receipt.ts

@@ -1,7 +1,24 @@
-import { createHash, randomUUID } from 'crypto';
+import { createHash, createPrivateKey, createPublicKey, randomUUID, sign as cryptoSign, verify as cryptoVerify, type KeyObject } from 'crypto';
 import { canonicalJson, sha256Hex } from '../decision-log';
 import type { ProvenanceBlock } from '../receipts/schema';
-import type { ReceiptV2, ReceiptV3, ReviewerCascadeEvidence } from './types';
+import type { ReceiptV2, ReceiptV3, ReviewerCascadeEvidence, WorkflowConfig } from './types';
+
+const ED25519_PKCS8_SEED_PREFIX = Buffer.from('302e020100300506032b657004220420', 'hex');
+const ED25519_SPKI_PUBLIC_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+
+type WorkflowSigningKeys = NonNullable<WorkflowConfig['signingKeys']>;
+
+interface ResolvedSigningKey {
+  privateKey: KeyObject;
+  publicKeyRaw: Buffer;
+  publicKeyHex: string;
+  publicKeyFingerprint: string;
+}
+
+export interface WorkflowReceiptVerifyOptions {
+  publicKeyHex?: string;
+  allowedSignerPublicKeysHex?: string[];
+}
 
 export function canonicalJSONStringify(value: unknown): string {
   return canonicalJson(value);
@@ -15,11 +32,21 @@ export function workflowReceiptId(prefix = 'ag_r'): string {
   return `${prefix}_${randomUUID().replace(/-/g, '').slice(0, 16)}`;
 }
 
-export function signReceiptPayload(payload: unknown): string {
-  return sha256Hex(canonicalJson(payload));
+export async function signReceiptPayload(payload: unknown, signingKeys?: WorkflowSigningKeys): Promise<{
+  signature: string;
+  public_key_fingerprint: string;
+  public_key_hex: string;
+}> {
+  const resolved = resolveWorkflowSigningKey(signingKeys);
+  const canonical = canonicalJson(payload);
+  return {
+    signature: cryptoSign(null, Buffer.from(canonical, 'utf8'), resolved.privateKey).toString('hex'),
+    public_key_fingerprint: resolved.publicKeyFingerprint,
+    public_key_hex: resolved.publicKeyHex,
+  };
 }
 
-export function buildReceipt(args: {
+export async function buildReceipt(args: {
   workflow_id: string | null;
   outcome_name: string;
   user_id: string;
@@ -33,22 +60,20 @@ export function buildReceipt(args: {
   reviewer_cascade?: ReviewerCascadeEvidence | null;
   receipt_type?: ReceiptV2['receipt_type'];
   cancelled_reason?: string | null;
-}): ReceiptV2 {
+  signingKeys?: WorkflowSigningKeys;
+  receipt_id?: string;
+  signed_at?: string;
+}): Promise<ReceiptV2> {
   if (!Number.isFinite(args.cost_usd) || args.cost_usd < 0) {
     throw new Error('Workflow receipt cost must be a finite non-negative number');
   }
-  const publicKeyFingerprint = createHash('sha256')
-    .update(args.workflow_id || args.user_id || 'agentguard-workflow')
-    .digest('hex')
-    .slice(0, 16);
-  const unsigned: Omit<ReceiptV2, 'signature'> = {
-    receipt_id: workflowReceiptId(args.is_checkpoint ? 'ag_cp' : 'ag_r'),
+  const unsigned: Omit<ReceiptV2, 'signature' | 'public_key_fingerprint' | 'public_key_hex'> = {
+    receipt_id: args.receipt_id ?? workflowReceiptId(args.is_checkpoint ? 'ag_cp' : 'ag_r'),
     schema_version: 2,
     outcome_name: args.outcome_name,
     user_id: args.user_id,
     cost_usd: roundUsd(args.cost_usd),
-    signed_at: new Date().toISOString(),
-    public_key_fingerprint: publicKeyFingerprint,
+    signed_at: args.signed_at ?? new Date().toISOString(),
     workflow_id: args.workflow_id,
     parent_receipt_id: args.parent_receipt_id,
     chain_validation_hash: args.chain_validation_hash,
@@ -61,12 +86,10 @@ export function buildReceipt(args: {
     receipt_type: args.receipt_type ?? (args.is_checkpoint ? 'checkpoint' : 'outcome'),
     cancelled_reason: args.cancelled_reason ?? null,
   };
-  return { ...unsigned, signature: signReceiptPayload(unsigned) };
+  return { ...unsigned, ...(await signReceiptPayload(unsigned, args.signingKeys)) };
 }
 
-
-
-export function buildReceiptV3(args: {
+export async function buildReceiptV3(args: {
   workflow_id: string | null;
   outcome_name: string;
   user_id: string;
@@ -81,27 +104,108 @@ export function buildReceiptV3(args: {
   reviewer_cascade?: ReviewerCascadeEvidence | null;
   receipt_type?: ReceiptV2['receipt_type'];
   cancelled_reason?: string | null;
-}): ReceiptV3 {
-  const v2 = buildReceipt(args);
-  const unsigned: Omit<ReceiptV3, 'signature'> = {
-    ...v2,
+  signingKeys?: WorkflowSigningKeys;
+  receipt_id?: string;
+  signed_at?: string;
+}): Promise<ReceiptV3> {
+  const v2 = await buildReceipt(args);
+  const unsigned: Omit<ReceiptV3, 'signature' | 'public_key_fingerprint' | 'public_key_hex'> = {
+    ...stripReceiptSignature(v2),
     schema_version: 3,
     provenance: args.provenance,
   };
-  const { signature: _oldSignature, ...withoutSignature } = unsigned as Omit<ReceiptV3, 'signature'> & { signature?: string };
-  return { ...withoutSignature, signature: signReceiptPayload(withoutSignature) };
+  return { ...unsigned, ...(await signReceiptPayload(unsigned, args.signingKeys)) };
 }
 
-export function verifyAnyReceipt(receipt: ReceiptV2 | ReceiptV3): boolean {
-  const { signature: _signature, ...unsigned } = receipt;
-  return signReceiptPayload(unsigned) === receipt.signature;
+export function verifyAnyReceipt(receipt: ReceiptV2 | ReceiptV3, options: WorkflowReceiptVerifyOptions = {}): boolean {
+  return verifyReceipt(receipt, options);
 }
 
-export function verifyReceipt(receipt: ReceiptV2): boolean {
-  const { signature: _signature, ...unsigned } = receipt;
-  return signReceiptPayload(unsigned) === receipt.signature;
+export function verifyReceipt(receipt: ReceiptV2 | ReceiptV3, options: WorkflowReceiptVerifyOptions = {}): boolean {
+  const { signature, public_key_hex: embeddedPublicKeyHex, public_key_fingerprint: fingerprint, ...unsigned } = receipt as ReceiptV2 & { public_key_hex?: string };
+  if (!signature || !/^[0-9a-fA-F]{128}$/.test(String(signature))) return false;
+  const publicKeyHex = String(options.publicKeyHex || embeddedPublicKeyHex || '').toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(publicKeyHex)) return false;
+  const allowed = normalizeAllowedSignerKeys(options.allowedSignerPublicKeysHex);
+  if (allowed && !allowed.has(publicKeyHex)) return false;
+  const publicKeyRaw = Buffer.from(publicKeyHex, 'hex');
+  if (fingerprint && computePublicKeyFingerprint(publicKeyRaw) !== String(fingerprint)) return false;
+  const publicKey = createPublicKey({ key: Buffer.concat([ED25519_SPKI_PUBLIC_PREFIX, publicKeyRaw]), format: 'der', type: 'spki' });
+  try {
+    return cryptoVerify(null, Buffer.from(canonicalJson(unsigned), 'utf8'), publicKey, Buffer.from(signature, 'hex'));
+  } catch {
+    return false;
+  }
 }
 
 export function roundUsd(value: number): number {
   return Math.round(value * 1_000_000) / 1_000_000;
 }
+
+function stripReceiptSignature(receipt: ReceiptV2): Omit<ReceiptV2, 'signature' | 'public_key_fingerprint' | 'public_key_hex'> {
+  const { signature: _signature, public_key_fingerprint: _fingerprint, public_key_hex: _publicKeyHex, ...unsigned } = receipt;
+  return unsigned;
+}
+
+function resolveWorkflowSigningKey(signingKeys?: WorkflowSigningKeys): ResolvedSigningKey {
+  if (signingKeys) return keyFromSeed(signingKeys.privateKey, signingKeys.publicKey);
+  const raw = process.env.AGENTGUARD_SIGNING_KEY_ED25519_PRIVATE;
+  if (!raw) throw new Error('Workflow receipt signing key is required');
+  return keyFromEnvironment(raw);
+}
+
+function keyFromSeed(seed: Uint8Array, expectedPublicKey?: Uint8Array): ResolvedSigningKey {
+  if (seed.length !== 32) throw new Error(`Ed25519 private seed must be 32 bytes, got ${seed.length} bytes`);
+  const privateKey = createPrivateKey({ key: Buffer.concat([ED25519_PKCS8_SEED_PREFIX, Buffer.from(seed)]), format: 'der', type: 'pkcs8' });
+  const publicKeyRaw = rawPublicKeyFromPrivate(privateKey);
+  if (expectedPublicKey && Buffer.compare(publicKeyRaw, Buffer.from(expectedPublicKey)) !== 0) {
+    throw new Error('Workflow receipt public key does not match private seed');
+  }
+  return resolved(privateKey, publicKeyRaw);
+}
+
+function keyFromEnvironment(raw: string): ResolvedSigningKey {
+  const value = raw.trim();
+  let privateKey: KeyObject;
+  if (value.startsWith('-----BEGIN')) {
+    privateKey = createPrivateKey(value);
+  } else if (value.startsWith('{')) {
+    privateKey = createPrivateKey({ key: JSON.parse(value), format: 'jwk' });
+  } else {
+    const clean = value.replace(/^0x/, '');
+    let bytes: Buffer;
+    if (/^[0-9a-fA-F]+$/.test(clean) && clean.length % 2 === 0) bytes = Buffer.from(clean, 'hex');
+    else bytes = Buffer.from(value, 'base64');
+    privateKey = bytes.length === 32
+      ? createPrivateKey({ key: Buffer.concat([ED25519_PKCS8_SEED_PREFIX, bytes]), format: 'der', type: 'pkcs8' })
+      : createPrivateKey({ key: bytes, format: 'der', type: 'pkcs8' });
+  }
+  return resolved(privateKey, rawPublicKeyFromPrivate(privateKey));
+}
+
+function rawPublicKeyFromPrivate(privateKey: KeyObject): Buffer {
+  const der = createPublicKey(privateKey).export({ format: 'der', type: 'spki' });
+  return Buffer.from(der).subarray(-32);
+}
+
+function resolved(privateKey: KeyObject, publicKeyRaw: Buffer): ResolvedSigningKey {
+  return {
+    privateKey,
+    publicKeyRaw,
+    publicKeyHex: publicKeyRaw.toString('hex'),
+    publicKeyFingerprint: computePublicKeyFingerprint(publicKeyRaw),
+  };
+}
+
+function computePublicKeyFingerprint(publicKeyRaw: Buffer): string {
+  return createHash('sha256').update(publicKeyRaw).digest('hex').slice(0, 16);
+}
+
+function normalizeAllowedSignerKeys(explicit?: string[]): Set<string> | null {
+  const values = [...(explicit ?? [])];
+  const envAllowed = process.env.AGENTGUARD_ALLOWED_SIGNER_PUBKEYS_HEX;
+  if (envAllowed) values.push(...envAllowed.split(','));
+  if (values.length === 0) return null;
+  const clean = values.map((value) => String(value).trim().toLowerCase()).filter((value) => /^[0-9a-f]{64}$/.test(value));
+  return new Set(clean);
+}

package/src/workflow/types.ts

@@ -20,6 +20,12 @@ export interface WorkflowConfig {
   user_id?: string;
   api_base_url?: string;
   license_key?: string;
+  signingKeys?: {
+    /** 32-byte Ed25519 secret seed. */
+    privateKey: Uint8Array;
+    /** 32-byte Ed25519 public key. */
+    publicKey: Uint8Array;
+  };
   post_json?: (url: string, body: unknown, headers: Record<string, string>) => Promise<unknown>;
   get_json?: (url: string, headers: Record<string, string>) => Promise<unknown>;
 }
@@ -44,6 +50,7 @@ export interface ReceiptV2 {
   signed_at: string;
   signature: string;
   public_key_fingerprint: string;
+  public_key_hex: string;
   workflow_id: string | null;
   parent_receipt_id: string | null;
   chain_validation_hash: string | null;