@finalbosstech/pqc-receipt-sdk 1.0.0

package/src/verifier.ts

@@ -0,0 +1,175 @@
+/**
+ * PQC Receipt SDK - Independent Verification
+ */
+
+import { verifySignature, hash, canonicalizePayload } from './crypto.js';
+import { verifyLogChain } from './log.js';
+import type { Receipt, LogEntry, VerificationResult, ChainVerificationResult } from './types.js';
+
+/**
+ * Verify a single receipt
+ */
+export async function verifyReceipt(
+  receipt: Receipt,
+  publicKey: Buffer
+): Promise<VerificationResult> {
+  return verifySignature(receipt, publicKey);
+}
+
+/**
+ * Verify receipt hash integrity (without signature verification)
+ */
+export function verifyReceiptHash(receipt: Receipt): VerificationResult {
+  const receiptCopy = { ...receipt } as any;
+  delete receiptCopy.receipt_hash;
+
+  const expectedHash = hash(canonicalizePayload(receiptCopy));
+
+  if (receipt.receipt_hash !== expectedHash) {
+    return { valid: false, error: 'HASH_MISMATCH' };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Verify a chain of receipts
+ */
+export async function verifyReceiptChain(
+  receipts: Receipt[],
+  publicKey: Buffer
+): Promise<{
+  valid: boolean;
+  verified: number;
+  failed: Array<{ index: number; receipt_id: string; error: string }>;
+}> {
+  const failed: Array<{ index: number; receipt_id: string; error: string }> = [];
+
+  for (let i = 0; i < receipts.length; i++) {
+    const receipt = receipts[i];
+
+    // Verify signature
+    const sigResult = await verifySignature(receipt, publicKey);
+    if (!sigResult.valid) {
+      failed.push({
+        index: i,
+        receipt_id: receipt.receipt_id,
+        error: sigResult.error || 'UNKNOWN'
+      });
+      continue;
+    }
+
+    // Verify chain linkage
+    if (i > 0) {
+      const prevReceipt = receipts[i - 1];
+      if (receipt.chain.prev_receipt_hash !== prevReceipt.receipt_hash) {
+        failed.push({
+          index: i,
+          receipt_id: receipt.receipt_id,
+          error: 'CHAIN_BREAK'
+        });
+      }
+    } else {
+      // First receipt should have null prev_receipt_hash
+      if (receipt.chain.prev_receipt_hash !== null) {
+        failed.push({
+          index: i,
+          receipt_id: receipt.receipt_id,
+          error: 'GENESIS_INVALID'
+        });
+      }
+    }
+
+    // Verify sequence
+    if (receipt.chain.sequence !== i + 1) {
+      failed.push({
+        index: i,
+        receipt_id: receipt.receipt_id,
+        error: 'SEQUENCE_GAP'
+      });
+    }
+  }
+
+  return {
+    valid: failed.length === 0,
+    verified: receipts.length - failed.length,
+    failed
+  };
+}
+
+/**
+ * Full verification: receipts + log entries
+ */
+export async function verifyFull(
+  receipts: Receipt[],
+  logEntries: LogEntry[],
+  publicKey: Buffer
+): Promise<{
+  receipts: { valid: boolean; verified: number; failed: any[] };
+  log: ChainVerificationResult;
+  crossCheck: { valid: boolean; mismatches: number[] };
+}> {
+  // Verify receipts
+  const receiptResult = await verifyReceiptChain(receipts, publicKey);
+
+  // Verify log
+  const logResult = verifyLogChain(logEntries);
+
+  // Cross-check: each log entry should reference corresponding receipt
+  const mismatches: number[] = [];
+  for (let i = 0; i < Math.min(receipts.length, logEntries.length); i++) {
+    if (logEntries[i].receipt_hash !== receipts[i].receipt_hash) {
+      mismatches.push(i);
+    }
+  }
+
+  return {
+    receipts: receiptResult,
+    log: logResult,
+    crossCheck: {
+      valid: mismatches.length === 0,
+      mismatches
+    }
+  };
+}
+
+/**
+ * Verify an anchor exists on-chain
+ */
+export async function verifyAnchor(
+  logRoot: string,
+  contractAddress: string,
+  rpcUrl: string
+): Promise<{
+  exists: boolean;
+  sequence?: number;
+  timestamp?: number;
+  error?: string;
+}> {
+  try {
+    const { ethers } = await import('ethers');
+
+    const provider = new ethers.JsonRpcProvider(rpcUrl);
+
+    const abi = [
+      'function verify(bytes32 logRoot) view returns (bool exists, uint256 sequence, uint256 timestamp)'
+    ];
+
+    const contract = new ethers.Contract(contractAddress, abi, provider);
+
+    const [exists, sequence, timestamp] = await contract.verify(
+      '0x' + logRoot
+    );
+
+    return {
+      exists,
+      sequence: Number(sequence),
+      timestamp: Number(timestamp)
+    };
+  } catch (error: any) {
+    return {
+      exists: false,
+      error: error.message
+    };
+  }
+}

package/test/demo.js

@@ -0,0 +1,159 @@
+/**
+ * PQC Receipt SDK - Demonstration Script
+ *
+ * This script demonstrates the complete flow:
+ * 1. Generate ML-DSA-65 key pair
+ * 2. Create receipts with PQC signatures
+ * 3. Append to tamper-evident log
+ * 4. Verify independently
+ *
+ * Run: node test/demo.js
+ */
+
+import {
+  generateKeyPair,
+  ReceiptGenerator,
+  AppendOnlyLog,
+  verifyReceipt,
+  verifyReceiptChain,
+  ALGORITHM,
+  VERSION,
+  PUBLIC_KEY_SIZE,
+  SECRET_KEY_SIZE,
+  SIGNATURE_SIZE
+} from '../src/index.js';
+
+console.log(`
+╔═══════════════════════════════════════════════════════════════╗
+║         PQC Receipt SDK Demo - ML-DSA-65 (FIPS 204)           ║
+║                     Version ${VERSION}                             ║
+║              Using @noble/post-quantum                        ║
+╚═══════════════════════════════════════════════════════════════╝
+`);
+
+async function runDemo() {
+  console.log('═══════════════════════════════════════════════════════════════');
+
+  // Step 1: Generate key pair
+  console.log('\n📐 Step 1: Generating ML-DSA-65 key pair...');
+  const startKey = Date.now();
+
+  const keyPair = await generateKeyPair();
+
+  console.log(`   ✓ Key generated in ${Date.now() - startKey}ms`);
+  console.log(`   ✓ Public key: ${keyPair.publicKey.length} bytes (expected: ${PUBLIC_KEY_SIZE})`);
+  console.log(`   ✓ Secret key: ${keyPair.secretKey.length} bytes (expected: ${SECRET_KEY_SIZE})`);
+  console.log(`   ✓ Key ID: ${keyPair.keyId.slice(0, 32)}...`);
+
+  // Step 2: Create receipt generator
+  console.log('\n📝 Step 2: Creating receipt generator...');
+  const generator = new ReceiptGenerator(keyPair);
+  console.log('   ✓ Generator initialized');
+
+  // Step 3: Generate receipts
+  console.log('\n🔏 Step 3: Generating PQC-signed receipts...');
+  const receipts = [];
+  const log = new AppendOnlyLog();
+
+  const operations = [
+    { type: 'intercept', method: 'POST', endpoint: '/api/v1/verify', req: { user: 'alice' }, res: { verified: true } },
+    { type: 'verify', method: 'GET', endpoint: '/api/v1/status', req: {}, res: { status: 'active' } },
+    { type: 'intercept', method: 'POST', endpoint: '/api/v1/consent', req: { purpose: 'marketing' }, res: { granted: true } },
+    { type: 'revoke', method: 'DELETE', endpoint: '/api/v1/consent/123', req: {}, res: { revoked: true } },
+    { type: 'anchor', method: 'POST', endpoint: '/api/v1/anchor', req: { checkpoint: true }, res: { anchored: true } }
+  ];
+
+  for (const op of operations) {
+    const startSign = Date.now();
+
+    const receipt = await generator.generate({
+      type: op.type,
+      method: op.method,
+      endpoint: op.endpoint,
+      requestBody: op.req,
+      responseBody: op.res,
+      actorId: 'demo-user',
+      orgId: 'demo-org'
+    });
+
+    receipts.push(receipt);
+    log.append(receipt);
+
+    const sigSize = Buffer.from(receipt.pqc_signature.signature, 'base64').length;
+    console.log(`   ✓ Receipt #${receipt.chain.sequence}: ${op.type.padEnd(10)} ${op.endpoint.padEnd(25)} (${Date.now() - startSign}ms, sig: ${sigSize} bytes)`);
+  }
+
+  // Step 4: Verify receipts individually
+  console.log('\n✅ Step 4: Verifying receipts independently...');
+  let allValid = true;
+  for (const receipt of receipts) {
+    const result = await verifyReceipt(receipt, keyPair.publicKey);
+    const status = result.valid ? '✓' : '✗';
+    console.log(`   ${status} Receipt #${receipt.chain.sequence}: ${result.valid ? 'VALID' : result.error}`);
+    if (!result.valid) allValid = false;
+  }
+
+  // Step 5: Verify chain
+  console.log('\n🔗 Step 5: Verifying receipt chain integrity...');
+  const chainResult = await verifyReceiptChain(receipts, keyPair.publicKey);
+  console.log(`   Chain valid: ${chainResult.valid}`);
+  console.log(`   Verified: ${chainResult.verified}/${receipts.length}`);
+  if (chainResult.failed.length > 0) {
+    console.log(`   Failed: ${JSON.stringify(chainResult.failed)}`);
+  }
+
+  // Step 6: Verify log
+  console.log('\n📋 Step 6: Verifying append-only log...');
+  const logResult = log.verify();
+  console.log(`   Log valid: ${logResult.valid}`);
+  console.log(`   Entries: ${logResult.length}`);
+  console.log(`   Log root: ${log.getLogRoot()?.slice(0, 32)}...`);
+  if (logResult.breaks.length > 0) {
+    console.log(`   Breaks: ${JSON.stringify(logResult.breaks)}`);
+  }
+
+  // Step 7: Tamper detection test
+  console.log('\n🔍 Step 7: Testing tamper detection...');
+  const tamperedReceipt = JSON.parse(JSON.stringify(receipts[2]));
+  tamperedReceipt.operation.response_hash = 'tampered_hash_value';
+
+  const tamperResult = await verifyReceipt(tamperedReceipt, keyPair.publicKey);
+  console.log(`   Tampered receipt verification: ${tamperResult.valid ? 'FAILED TO DETECT' : 'DETECTED ✓'}`);
+  console.log(`   Error returned: ${tamperResult.error}`);
+
+  // Summary
+  const allPassed = allValid && chainResult.valid && logResult.valid && !tamperResult.valid;
+
+  console.log(`
+╔═══════════════════════════════════════════════════════════════╗
+║                      DEMO COMPLETE                            ║
+╠═══════════════════════════════════════════════════════════════╣
+║  Algorithm:        ${ALGORITHM.padEnd(43)}║
+║  Hash:             SHA3-256                                   ║
+║  Receipts:         ${receipts.length.toString().padEnd(43)}║
+║  All signatures:   ${(allValid ? 'VALID' : 'INVALID').padEnd(43)}║
+║  Chain integrity:  ${(chainResult.valid ? 'VERIFIED' : 'BROKEN').padEnd(43)}║
+║  Log integrity:    ${(logResult.valid ? 'VERIFIED' : 'BROKEN').padEnd(43)}║
+║  Tamper detection: ${(!tamperResult.valid ? 'WORKING' : 'FAILED').padEnd(43)}║
+╠═══════════════════════════════════════════════════════════════╣
+║  OVERALL:          ${(allPassed ? '✓ ALL TESTS PASSED' : '✗ SOME TESTS FAILED').padEnd(43)}║
+╚═══════════════════════════════════════════════════════════════╝
+`);
+
+  // Output sample receipt
+  console.log('\n📄 Sample Receipt (JSON):');
+  console.log(JSON.stringify(receipts[0], null, 2));
+
+  // Output log entry
+  console.log('\n📜 Sample Log Entry:');
+  console.log(JSON.stringify(log.getEntries()[0], null, 2));
+
+  return allPassed;
+}
+
+runDemo()
+  .then(passed => process.exit(passed ? 0 : 1))
+  .catch(err => {
+    console.error('Demo failed:', err);
+    process.exit(1);
+  });

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test", "contracts"]
+}