qa360 2.1.7 → 2.2.0

package/core/src/proof/signer.ts

@@ -0,0 +1,293 @@
+/**
+ * Ed25519 Signature Operations
+ * 
+ * Provides key generation, signing, and verification using Ed25519.
+ * Uses tweetnacl for cryptographic operations.
+ * 
+ * @see docs/rfc/proof-bundle-v1.md#5-signature-procedure
+ */
+
+import * as naclModule from 'tweetnacl';
+import { createHash } from 'crypto';
+import { promises as fs } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+// Handle both ESM and CJS imports
+const nacl = (naclModule as any).default || naclModule;
+
+// Validate tweetnacl import
+if (!nacl?.sign?.keyPair) {
+  throw new Error('tweetnacl not loaded correctly - sign.keyPair is undefined');
+}
+
+/**
+ * Ed25519 key pair
+ */
+export interface KeyPair {
+  publicKey: Uint8Array;
+  secretKey: Uint8Array;
+}
+
+/**
+ * Key storage paths
+ */
+export interface KeyPaths {
+  privateKey: string;
+  publicKey: string;
+}
+
+/**
+ * Get default key storage directory
+ */
+export function getKeyDirectory(): string {
+  return join(homedir(), '.qa360', 'keys');
+}
+
+/**
+ * Get key file paths
+ */
+export function getKeyPaths(): KeyPaths {
+  const keyDir = getKeyDirectory();
+  return {
+    privateKey: join(keyDir, 'ed25519.key'),
+    publicKey: join(keyDir, 'ed25519.pub'),
+  };
+}
+
+/**
+ * Generate new Ed25519 key pair
+ * 
+ * @returns Key pair (public + secret)
+ */
+export function generateKeys(): KeyPair {
+  const keyPair = nacl.sign.keyPair();
+  return {
+    publicKey: keyPair.publicKey,
+    secretKey: keyPair.secretKey,
+  };
+}
+
+/**
+ * Save key pair to disk
+ * 
+ * @param keyPair - Key pair to save
+ * @param paths - Optional custom paths (defaults to ~/.qa360/keys/)
+ */
+export async function saveKeys(keyPair: KeyPair, paths?: KeyPaths): Promise<void> {
+  const keyPaths = paths || getKeyPaths();
+  const keyDir = getKeyDirectory();
+  
+  // Create directory if it doesn't exist
+  await fs.mkdir(keyDir, { recursive: true, mode: 0o700 });
+  
+  // Save private key (chmod 600)
+  await fs.writeFile(
+    keyPaths.privateKey,
+    Buffer.from(keyPair.secretKey).toString('base64'),
+    { mode: 0o600 }
+  );
+  
+  // Save public key (chmod 644)
+  await fs.writeFile(
+    keyPaths.publicKey,
+    Buffer.from(keyPair.publicKey).toString('base64'),
+    { mode: 0o644 }
+  );
+}
+
+/**
+ * Load key pair from disk
+ * 
+ * @param paths - Optional custom paths (defaults to ~/.qa360/keys/)
+ * @returns Key pair
+ * @throws Error if keys don't exist
+ */
+export async function loadKeys(paths?: KeyPaths): Promise<KeyPair> {
+  const keyPaths = paths || getKeyPaths();
+  
+  try {
+    const privateKeyB64 = await fs.readFile(keyPaths.privateKey, 'utf-8');
+    const publicKeyB64 = await fs.readFile(keyPaths.publicKey, 'utf-8');
+    
+    return {
+      secretKey: new Uint8Array(Buffer.from(privateKeyB64.trim(), 'base64')),
+      publicKey: new Uint8Array(Buffer.from(publicKeyB64.trim(), 'base64')),
+    };
+  } catch (error) {
+    throw new Error(`Failed to load keys: ${error instanceof Error ? error.message : 'Unknown error'}`);
+  }
+}
+
+/**
+ * Check if keys exist
+ * 
+ * @param paths - Optional custom paths
+ * @returns true if both keys exist
+ */
+export async function keysExist(paths?: KeyPaths): Promise<boolean> {
+  const keyPaths = paths || getKeyPaths();
+  
+  try {
+    await fs.access(keyPaths.privateKey);
+    await fs.access(keyPaths.publicKey);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Initialize keys (generate if they don't exist)
+ * 
+ * @param paths - Optional custom paths
+ * @returns Key pair (existing or newly generated)
+ */
+export async function initializeKeys(paths?: KeyPaths): Promise<KeyPair> {
+  if (await keysExist(paths)) {
+    return loadKeys(paths);
+  }
+  
+  const keyPair = generateKeys();
+  await saveKeys(keyPair, paths);
+  return keyPair;
+}
+
+/**
+ * Ensure proof keys exist (generate if missing)
+ * 
+ * @param homeDir - QA360 home directory
+ * @returns Result with creation status, paths, and optional keys
+ */
+export async function ensureProofKeys(homeDir: string): Promise<{
+  created: boolean;
+  paths: { pub: string; priv: string };
+  keys?: KeyPair;
+}> {
+  const keyDir = join(homeDir, 'keys');
+  const paths = {
+    pub: join(keyDir, 'ed25519.pub'),
+    priv: join(keyDir, 'ed25519.key'),
+  };
+  
+  // Check if keys already exist
+  try {
+    await fs.access(paths.priv);
+    await fs.access(paths.pub);
+    
+    // Keys exist, validate them
+    const privateKeyB64 = await fs.readFile(paths.priv, 'utf-8');
+    const publicKeyB64 = await fs.readFile(paths.pub, 'utf-8');
+    
+    const secretKey = new Uint8Array(Buffer.from(privateKeyB64.trim(), 'base64'));
+    const publicKey = new Uint8Array(Buffer.from(publicKeyB64.trim(), 'base64'));
+    
+    // Validate key sizes
+    if (publicKey.length !== 32) {
+      throw new Error(`Invalid public key size: ${publicKey.length} (expected 32)`);
+    }
+    if (secretKey.length !== 64) {
+      throw new Error(`Invalid secret key size: ${secretKey.length} (expected 64)`);
+    }
+    
+    return {
+      created: false,
+      paths,
+      keys: { publicKey, secretKey },
+    };
+  } catch {
+    // Keys don't exist or are invalid, generate new ones
+    await fs.mkdir(keyDir, { recursive: true, mode: 0o700 });
+    
+    const keyPair = generateKeys();
+    
+    // Validate generated keys
+    if (!keyPair.publicKey || keyPair.publicKey.length !== 32) {
+      throw new Error('Key generation failed: invalid public key');
+    }
+    if (!keyPair.secretKey || keyPair.secretKey.length !== 64) {
+      throw new Error('Key generation failed: invalid secret key');
+    }
+    
+    // Save keys
+    await fs.writeFile(
+      paths.priv,
+      Buffer.from(keyPair.secretKey).toString('base64'),
+      { mode: 0o600 }
+    );
+    await fs.writeFile(
+      paths.pub,
+      Buffer.from(keyPair.publicKey).toString('base64'),
+      { mode: 0o644 }
+    );
+    
+    return {
+      created: true,
+      paths,
+      keys: keyPair,
+    };
+  }
+}
+
+/**
+ * Compute SHA-256 hash of data
+ * 
+ * @param data - Data to hash (UTF-8 string)
+ * @returns SHA-256 hash as Buffer
+ */
+export function sha256(data: string): Buffer {
+  return createHash('sha256').update(data, 'utf-8').digest();
+}
+
+/**
+ * Sign data with Ed25519
+ * 
+ * @param data - Data to sign (canonical JSON string)
+ * @param secretKey - Ed25519 secret key (64 bytes)
+ * @returns Base64-encoded signature (88 chars)
+ */
+export function sign(data: string, secretKey: Uint8Array): string {
+  // Hash the data first (sign the hash, not the raw data)
+  const hash = sha256(data);
+  
+  // Sign the hash
+  const signature = nacl.sign.detached(hash, secretKey);
+  
+  // Return base64-encoded signature
+  return Buffer.from(signature).toString('base64');
+}
+
+/**
+ * Verify Ed25519 signature
+ * 
+ * @param data - Original data (canonical JSON string)
+ * @param signatureB64 - Base64-encoded signature
+ * @param publicKey - Ed25519 public key (32 bytes)
+ * @returns true if signature is valid
+ */
+export function verify(data: string, signatureB64: string, publicKey: Uint8Array): boolean {
+  try {
+    // Hash the data
+    const hash = sha256(data);
+    
+    // Decode signature
+    const signature = new Uint8Array(Buffer.from(signatureB64, 'base64'));
+    
+    // Verify signature
+    return nacl.sign.detached.verify(hash, signature, publicKey);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Sign and verify roundtrip test
+ * 
+ * @param data - Test data
+ * @param keyPair - Key pair to test
+ * @returns true if roundtrip succeeds
+ */
+export function testRoundtrip(data: string, keyPair: KeyPair): boolean {
+  const signature = sign(data, keyPair.secretKey);
+  return verify(data, signature, keyPair.publicKey);
+}

package/core/src/proof/verifier.ts

@@ -0,0 +1,380 @@
+/**
+ * Proof Bundle Verification
+ * 
+ * Verifies cryptographic signatures and integrity of proof bundles.
+ * 
+ * @see docs/rfc/proof-bundle-v1.md#6-verification-procedure
+ */
+
+import { promises as fs } from 'fs';
+import { createHash } from 'crypto';
+import { canonicalizeForSigning } from './canonicalize.js';
+import { verify, loadKeys, type KeyPair } from './signer.js';
+import { validateProofBundle } from './schema.js';
+import type { ProofBundle, Artifact } from './bundle.js';
+
+/**
+ * Verification result
+ */
+export interface VerificationResult {
+  valid: boolean;
+  code: VerificationCode;
+  message: string;
+  details?: VerificationDetails;
+}
+
+/**
+ * Verification error codes (matches RFC)
+ */
+export enum VerificationCode {
+  PROOF_OK = 0,
+  PROOF_INVALID_SIG = 1,
+  PROOF_INVALID_SCHEMA = 2,
+  PROOF_ARTIFACT_MISMATCH = 3,
+  PROOF_MISSING_KEY = 4,
+  PROOF_MALFORMED = 5,
+}
+
+/**
+ * Verification details
+ */
+export interface VerificationDetails {
+  signerId?: string;
+  hash?: string;
+  artifactsVerified?: number;
+  artifactsTotal?: number;
+  trustScore?: number;
+  runId?: string;
+  startedAt?: string;
+  finishedAt?: string;
+}
+
+/**
+ * Artifact verification options
+ */
+export interface ArtifactVerificationOptions {
+  basePath?: string; // Base path for resolving artifact paths
+  skipMissing?: boolean; // Skip verification if artifact file missing
+}
+
+/**
+ * Verify proof bundle signature
+ * 
+ * @param bundle - Proof bundle to verify
+ * @param publicKey - Optional public key (loads from ~/.qa360/keys if not provided)
+ * @returns Verification result
+ */
+export async function verifyProofBundle(
+  bundle: ProofBundle,
+  publicKey?: Uint8Array
+): Promise<VerificationResult> {
+  // Step 1: Validate JSON structure
+  try {
+    JSON.stringify(bundle);
+  } catch {
+    return {
+      valid: false,
+      code: VerificationCode.PROOF_MALFORMED,
+      message: 'Malformed JSON structure',
+    };
+  }
+  
+  // Step 2: Extract signature
+  const signatureB64 = bundle.signature;
+  if (!signatureB64) {
+    return {
+      valid: false,
+      code: VerificationCode.PROOF_INVALID_SIG,
+      message: 'Missing signature field',
+    };
+  }
+  
+  // Step 3: Validate schema
+  const schemaValidation = validateProofBundle(bundle);
+  if (!schemaValidation.valid) {
+    return {
+      valid: false,
+      code: VerificationCode.PROOF_INVALID_SCHEMA,
+      message: `Schema validation failed: ${schemaValidation.errors?.join(', ')}`,
+    };
+  }
+  
+  // Step 4: Load public key if not provided
+  let pubKey = publicKey;
+  if (!pubKey) {
+    try {
+      const keyPair = await loadKeys();
+      pubKey = keyPair.publicKey;
+    } catch (error) {
+      return {
+        valid: false,
+        code: VerificationCode.PROOF_MISSING_KEY,
+        message: `Public key not found: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      };
+    }
+  }
+  
+  // Step 5: Re-canonicalize (without signature)
+  const canonical = canonicalizeForSigning(bundle);
+  
+  // Step 6: Compute hash for verification details
+  const hash = createHash('sha256').update(canonical, 'utf-8').digest('hex');
+  
+  // Step 7: Verify signature
+  const signatureValid = verify(canonical, signatureB64, pubKey);
+  
+  if (!signatureValid) {
+    return {
+      valid: false,
+      code: VerificationCode.PROOF_INVALID_SIG,
+      message: 'Invalid signature',
+      details: {
+        signerId: bundle.signing.signerId,
+        hash: `sha256-${hash}`,
+      },
+    };
+  }
+  
+  // Step 8: Success
+  return {
+    valid: true,
+    code: VerificationCode.PROOF_OK,
+    message: 'Proof verified successfully',
+    details: {
+      signerId: bundle.signing.signerId,
+      hash: `sha256-${hash}`,
+      artifactsTotal: bundle.artifacts.length,
+      trustScore: bundle.results.trustScore,
+      runId: bundle.run.id,
+      startedAt: bundle.run.startedAt,
+      finishedAt: bundle.run.finishedAt,
+    },
+  };
+}
+
+/**
+ * Verify artifact integrity
+ * 
+ * @param artifact - Artifact metadata
+ * @param filePath - Path to artifact file
+ * @returns true if hash matches
+ */
+export async function verifyArtifact(artifact: Artifact, filePath: string): Promise<boolean> {
+  try {
+    const content = await fs.readFile(filePath);
+    const hash = createHash('sha256').update(content).digest('hex');
+    const expectedHash = artifact.sha256.replace('sha256-', '');
+    return hash === expectedHash;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Verify all artifacts in proof bundle
+ * 
+ * @param bundle - Proof bundle
+ * @param options - Verification options
+ * @returns Verification result with artifact details
+ */
+export async function verifyArtifacts(
+  bundle: ProofBundle,
+  options: ArtifactVerificationOptions = {}
+): Promise<VerificationResult> {
+  const { basePath = '.', skipMissing = false } = options;
+  
+  let verified = 0;
+  const total = bundle.artifacts.length;
+  
+  for (const artifact of bundle.artifacts) {
+    const filePath = artifact.path
+      ? `${basePath}/${artifact.path}`
+      : `${basePath}/${artifact.name}`;
+    
+    try {
+      const valid = await verifyArtifact(artifact, filePath);
+      if (valid) {
+        verified++;
+      } else if (!skipMissing) {
+        return {
+          valid: false,
+          code: VerificationCode.PROOF_ARTIFACT_MISMATCH,
+          message: `Artifact hash mismatch: ${artifact.name}`,
+          details: {
+            artifactsVerified: verified,
+            artifactsTotal: total,
+          },
+        };
+      }
+    } catch {
+      if (!skipMissing) {
+        return {
+          valid: false,
+          code: VerificationCode.PROOF_ARTIFACT_MISMATCH,
+          message: `Artifact not found: ${artifact.name}`,
+          details: {
+            artifactsVerified: verified,
+            artifactsTotal: total,
+          },
+        };
+      }
+    }
+  }
+  
+  return {
+    valid: true,
+    code: VerificationCode.PROOF_OK,
+    message: `All artifacts verified (${verified}/${total})`,
+    details: {
+      artifactsVerified: verified,
+      artifactsTotal: total,
+    },
+  };
+}
+
+/**
+ * Verify proof bundle and artifacts (complete verification)
+ * 
+ * @param bundle - Proof bundle
+ * @param options - Artifact verification options
+ * @param publicKey - Optional public key
+ * @returns Complete verification result
+ */
+export async function verifyComplete(
+  bundle: ProofBundle,
+  options: ArtifactVerificationOptions = {},
+  publicKey?: Uint8Array
+): Promise<VerificationResult> {
+  // Step 1: Verify signature
+  const sigResult = await verifyProofBundle(bundle, publicKey);
+  if (!sigResult.valid) {
+    return sigResult;
+  }
+  
+  // Step 2: Verify artifacts (if any)
+  if (bundle.artifacts.length > 0) {
+    const artifactResult = await verifyArtifacts(bundle, options);
+    if (!artifactResult.valid) {
+      return artifactResult;
+    }
+    
+    // Merge details
+    return {
+      ...sigResult,
+      details: {
+        ...sigResult.details,
+        ...artifactResult.details,
+      },
+    };
+  }
+  
+  return sigResult;
+}
+
+/**
+ * Load and verify proof bundle from file
+ * 
+ * @param filePath - Path to proof bundle JSON file
+ * @param options - Artifact verification options
+ * @param publicKey - Optional public key
+ * @returns Verification result
+ */
+export async function verifyProofFile(
+  filePath: string,
+  options: ArtifactVerificationOptions = {},
+  publicKey?: Uint8Array
+): Promise<VerificationResult> {
+  try {
+    const content = await fs.readFile(filePath, 'utf-8');
+    const bundle = JSON.parse(content) as ProofBundle;
+    return verifyComplete(bundle, options, publicKey);
+  } catch (error) {
+    return {
+      valid: false,
+      code: VerificationCode.PROOF_MALFORMED,
+      message: `Failed to load proof: ${error instanceof Error ? error.message : 'Unknown error'}`,
+    };
+  }
+}
+
+/**
+ * Verify Phase3 proof format (simplified)
+ * 
+ * @param filePath - Path to Phase3 proof JSON
+ * @returns Verification result
+ */
+export async function verifyPhase3Proof(filePath: string): Promise<VerificationResult> {
+  try {
+    const content = await fs.readFile(filePath, 'utf-8');
+    const proof = JSON.parse(content);
+    
+    // Check if it's Phase3 format
+    if (!proof.version || !proof.signature || !proof.runId) {
+      return {
+        valid: false,
+        code: VerificationCode.PROOF_MALFORMED,
+        message: 'Not a valid Phase3 proof format',
+      };
+    }
+    
+    // Extract signature info
+    const { signature, ...payload } = proof;
+
+    if (signature.algorithm === 'none' || !signature.publicKey) {
+      return {
+        valid: false,
+        code: VerificationCode.PROOF_INVALID_SIG,
+        message: 'Proof is unsigned',
+      };
+    }
+
+    // Decode public key from proof
+    const publicKey = new Uint8Array(Buffer.from(signature.publicKey, 'base64'));
+
+    // Canonicalize payload (same way it was signed)
+    const { canonicalize } = await import('./canonicalize.js');
+    const canonical = canonicalize(payload) + '\n';
+
+    // Compute hash for details
+    const hash = createHash('sha256').update(canonical, 'utf-8').digest();
+
+    // Verify signature
+    const isValid = verify(canonical, signature.value, publicKey);
+    
+    if (!isValid) {
+      return {
+        valid: false,
+        code: VerificationCode.PROOF_INVALID_SIG,
+        message: 'Invalid signature - proof may have been tampered with',
+        details: {
+          runId: proof.runId,
+          trustScore: proof.execution?.trustScore,
+        },
+      };
+    }
+    
+    // Success
+    return {
+      valid: true,
+      code: VerificationCode.PROOF_OK,
+      message: 'Proof verified successfully',
+      details: {
+        signerId: 'local@qa360',
+        hash: `sha256-${hash.toString('hex').substring(0, 16)}...`,
+        runId: proof.runId,
+        trustScore: proof.execution?.trustScore,
+        startedAt: proof.timestamp,
+        finishedAt: proof.timestamp,
+        artifactsTotal: 0,
+        artifactsVerified: 0,
+      },
+    };
+    
+  } catch (error) {
+    return {
+      valid: false,
+      code: VerificationCode.PROOF_MALFORMED,
+      message: `Failed to verify proof: ${error instanceof Error ? error.message : 'Unknown error'}`,
+    };
+  }
+}