@finalbosstech/pqc-receipt-sdk 1.0.0

package/src/log.ts

@@ -0,0 +1,195 @@
+/**
+ * PQC Receipt SDK - Append-Only Log Management
+ */
+
+import { v4 as uuidv4 } from 'uuid';
+import { hash } from './crypto.js';
+import type { LogEntry, Receipt, ChainVerificationResult } from './types.js';
+
+export class AppendOnlyLog {
+  private entries: LogEntry[] = [];
+  private sequence: number = 0;
+
+  /**
+   * Append a receipt to the log
+   */
+  append(receipt: Receipt): LogEntry {
+    this.sequence++;
+
+    const prevEntry = this.entries[this.entries.length - 1];
+    const prevEntryHash = prevEntry ? prevEntry.entry_hash : null;
+
+    const entry: LogEntry = {
+      entry_id: uuidv4(),
+      sequence: this.sequence,
+      timestamp: new Date().toISOString(),
+      receipt_hash: receipt.receipt_hash,
+      prev_entry_hash: prevEntryHash,
+      entry_hash: '', // Computed below
+      anchor: { type: 'none' }
+    };
+
+    // Compute entry hash
+    entry.entry_hash = this.computeEntryHash(entry);
+
+    this.entries.push(entry);
+    return entry;
+  }
+
+  /**
+   * Compute hash of a log entry
+   */
+  private computeEntryHash(entry: Omit<LogEntry, 'entry_hash'>): string {
+    const preimage = [
+      entry.sequence.toString(),
+      entry.receipt_hash,
+      entry.prev_entry_hash || 'GENESIS',
+      entry.timestamp
+    ].join('|');
+
+    return hash(preimage);
+  }
+
+  /**
+   * Get all entries
+   */
+  getEntries(): LogEntry[] {
+    return [...this.entries];
+  }
+
+  /**
+   * Get entry by sequence number
+   */
+  getEntry(sequence: number): LogEntry | undefined {
+    return this.entries.find(e => e.sequence === sequence);
+  }
+
+  /**
+   * Get latest entry
+   */
+  getLatest(): LogEntry | undefined {
+    return this.entries[this.entries.length - 1];
+  }
+
+  /**
+   * Get current log root (latest entry hash)
+   */
+  getLogRoot(): string | null {
+    const latest = this.getLatest();
+    return latest ? latest.entry_hash : null;
+  }
+
+  /**
+   * Verify the integrity of the log chain
+   */
+  verify(): ChainVerificationResult {
+    const breaks: Array<{ index: number; error: string }> = [];
+
+    for (let i = 0; i < this.entries.length; i++) {
+      const entry = this.entries[i];
+
+      // Verify entry_hash is correct
+      const expectedHash = this.computeEntryHash({
+        entry_id: entry.entry_id,
+        sequence: entry.sequence,
+        timestamp: entry.timestamp,
+        receipt_hash: entry.receipt_hash,
+        prev_entry_hash: entry.prev_entry_hash,
+        anchor: entry.anchor
+      });
+
+      if (entry.entry_hash !== expectedHash) {
+        breaks.push({ index: i, error: 'ENTRY_HASH_INVALID' });
+        continue;
+      }
+
+      // Verify chain linkage (except genesis)
+      if (i > 0) {
+        const prevEntry = this.entries[i - 1];
+        if (entry.prev_entry_hash !== prevEntry.entry_hash) {
+          breaks.push({ index: i, error: 'CHAIN_BREAK' });
+        }
+      } else {
+        // Genesis entry must have null prev_entry_hash
+        if (entry.prev_entry_hash !== null) {
+          breaks.push({ index: i, error: 'GENESIS_INVALID' });
+        }
+      }
+
+      // Verify sequence is monotonic
+      if (entry.sequence !== i + 1) {
+        breaks.push({ index: i, error: 'SEQUENCE_GAP' });
+      }
+    }
+
+    return {
+      valid: breaks.length === 0,
+      length: this.entries.length,
+      breaks
+    };
+  }
+
+  /**
+   * Mark an entry as anchored
+   */
+  markAnchored(
+    sequence: number,
+    anchor: { type: 'hardhat' | 'ethereum' | 'external'; tx_hash: string; block_number: number }
+  ): void {
+    const entry = this.entries.find(e => e.sequence === sequence);
+    if (entry) {
+      entry.anchor = {
+        ...anchor,
+        anchored_at: new Date().toISOString()
+      };
+    }
+  }
+
+  /**
+   * Export log to JSON Lines format
+   */
+  exportJSONL(): string {
+    return this.entries.map(e => JSON.stringify(e)).join('\n');
+  }
+
+  /**
+   * Import log from JSON Lines format
+   */
+  static fromJSONL(jsonl: string): AppendOnlyLog {
+    const log = new AppendOnlyLog();
+    const lines = jsonl.trim().split('\n').filter(Boolean);
+
+    for (const line of lines) {
+      const entry = JSON.parse(line) as LogEntry;
+      log.entries.push(entry);
+      log.sequence = Math.max(log.sequence, entry.sequence);
+    }
+
+    return log;
+  }
+
+  /**
+   * Export log as JSON array
+   */
+  toJSON(): LogEntry[] {
+    return this.entries;
+  }
+
+  /**
+   * Import log from JSON array
+   */
+  static fromJSON(entries: LogEntry[]): AppendOnlyLog {
+    const log = new AppendOnlyLog();
+    log.entries = [...entries];
+    log.sequence = entries.length > 0 ? entries[entries.length - 1].sequence : 0;
+    return log;
+  }
+}
+
+/**
+ * Standalone function to verify a log chain
+ */
+export function verifyLogChain(entries: LogEntry[]): ChainVerificationResult {
+  const log = AppendOnlyLog.fromJSON(entries);
+  return log.verify();
+}

package/src/receipt.js

@@ -0,0 +1,141 @@
+/**
+ * PQC Receipt SDK - Receipt Generation
+ */
+
+import { v4 as uuidv4 } from 'uuid';
+import { hash, canonicalizePayload, signReceipt } from './crypto.js';
+
+export class ReceiptGenerator {
+  constructor(keyPair) {
+    this.keyPair = keyPair;
+    this.sequence = 0;
+    this.prevReceiptHash = null;
+  }
+
+  /**
+   * Get current chain state
+   */
+  getChainState() {
+    return {
+      sequence: this.sequence,
+      prev_receipt_hash: this.prevReceiptHash
+    };
+  }
+
+  /**
+   * Set chain state (for recovery/resumption)
+   */
+  setChainState(sequence, prevReceiptHash) {
+    this.sequence = sequence;
+    this.prevReceiptHash = prevReceiptHash;
+  }
+
+  /**
+   * Generate a signed PQC receipt
+   */
+  async generate(input) {
+    // Increment sequence
+    this.sequence++;
+
+    // Hash request and response bodies
+    const requestHash = hash(canonicalizePayload(input.requestBody));
+    const responseHash = hash(canonicalizePayload(input.responseBody));
+
+    // Build unsigned receipt
+    const unsignedReceipt = {
+      version: '1.0',
+      receipt_id: uuidv4(),
+      timestamp: new Date().toISOString(),
+      operation: {
+        type: input.type,
+        method: input.method,
+        endpoint: input.endpoint,
+        request_hash: requestHash,
+        response_hash: responseHash
+      },
+      actor: {
+        id: input.actorId,
+        org_id: input.orgId,
+        key_id: this.keyPair.keyId
+      },
+      chain: {
+        sequence: this.sequence,
+        prev_receipt_hash: this.prevReceiptHash
+      }
+    };
+
+    // Sign with ML-DSA-65
+    const { pqc_signature, receipt_hash } = await signReceipt(
+      unsignedReceipt,
+      this.keyPair.secretKey,
+      this.keyPair.publicKey
+    );
+
+    // Update chain state
+    this.prevReceiptHash = receipt_hash;
+
+    // Return complete signed receipt
+    return {
+      ...unsignedReceipt,
+      pqc_signature,
+      receipt_hash
+    };
+  }
+
+  /**
+   * Generate a genesis receipt (first in chain)
+   */
+  async generateGenesis(orgId, actorId) {
+    this.sequence = 0;
+    this.prevReceiptHash = null;
+
+    return this.generate({
+      type: 'anchor',
+      method: 'GENESIS',
+      endpoint: '/chain/genesis',
+      requestBody: { chain_initialized: true },
+      responseBody: { status: 'genesis_created' },
+      actorId,
+      orgId
+    });
+  }
+}
+
+/**
+ * Standalone function to create a single receipt
+ */
+export async function createReceipt(input, keyPair) {
+  const requestHash = hash(canonicalizePayload(input.requestBody));
+  const responseHash = hash(canonicalizePayload(input.responseBody));
+
+  const unsignedReceipt = {
+    version: '1.0',
+    receipt_id: uuidv4(),
+    timestamp: new Date().toISOString(),
+    operation: {
+      type: input.type,
+      method: input.method,
+      endpoint: input.endpoint,
+      request_hash: requestHash,
+      response_hash: responseHash
+    },
+    actor: {
+      id: input.actorId,
+      org_id: input.orgId,
+      key_id: keyPair.keyId
+    },
+    chain: input.chain
+  };
+
+  const { pqc_signature, receipt_hash } = await signReceipt(
+    unsignedReceipt,
+    keyPair.secretKey,
+    keyPair.publicKey
+  );
+
+  return {
+    ...unsignedReceipt,
+    pqc_signature,
+    receipt_hash
+  };
+}

package/src/receipt.ts

@@ -0,0 +1,148 @@
+/**
+ * PQC Receipt SDK - Receipt Generation
+ */
+
+import { v4 as uuidv4 } from 'uuid';
+import { hash, canonicalizePayload, signReceipt } from './crypto.js';
+import type { Receipt, CreateReceiptInput, KeyPair, Chain } from './types.js';
+
+export class ReceiptGenerator {
+  private keyPair: KeyPair;
+  private sequence: number = 0;
+  private prevReceiptHash: string | null = null;
+
+  constructor(keyPair: KeyPair) {
+    this.keyPair = keyPair;
+  }
+
+  /**
+   * Get current chain state
+   */
+  getChainState(): Chain {
+    return {
+      sequence: this.sequence,
+      prev_receipt_hash: this.prevReceiptHash
+    };
+  }
+
+  /**
+   * Set chain state (for recovery/resumption)
+   */
+  setChainState(sequence: number, prevReceiptHash: string | null): void {
+    this.sequence = sequence;
+    this.prevReceiptHash = prevReceiptHash;
+  }
+
+  /**
+   * Generate a signed PQC receipt
+   */
+  async generate(input: CreateReceiptInput): Promise<Receipt> {
+    // Increment sequence
+    this.sequence++;
+
+    // Hash request and response bodies
+    const requestHash = hash(canonicalizePayload(input.requestBody));
+    const responseHash = hash(canonicalizePayload(input.responseBody));
+
+    // Build unsigned receipt
+    const unsignedReceipt = {
+      version: '1.0' as const,
+      receipt_id: uuidv4(),
+      timestamp: new Date().toISOString(),
+      operation: {
+        type: input.type,
+        method: input.method,
+        endpoint: input.endpoint,
+        request_hash: requestHash,
+        response_hash: responseHash
+      },
+      actor: {
+        id: input.actorId,
+        org_id: input.orgId,
+        key_id: this.keyPair.keyId
+      },
+      chain: {
+        sequence: this.sequence,
+        prev_receipt_hash: this.prevReceiptHash
+      }
+    };
+
+    // Sign with ML-DSA-65
+    const { pqc_signature, receipt_hash } = await signReceipt(
+      unsignedReceipt,
+      this.keyPair.secretKey,
+      this.keyPair.publicKey
+    );
+
+    // Update chain state
+    this.prevReceiptHash = receipt_hash;
+
+    // Return complete signed receipt
+    return {
+      ...unsignedReceipt,
+      pqc_signature,
+      receipt_hash
+    };
+  }
+
+  /**
+   * Generate a genesis receipt (first in chain)
+   */
+  async generateGenesis(orgId: string, actorId: string): Promise<Receipt> {
+    this.sequence = 0;
+    this.prevReceiptHash = null;
+
+    return this.generate({
+      type: 'anchor',
+      method: 'GENESIS',
+      endpoint: '/chain/genesis',
+      requestBody: { chain_initialized: true },
+      responseBody: { status: 'genesis_created' },
+      actorId,
+      orgId
+    });
+  }
+}
+
+/**
+ * Standalone function to create a single receipt
+ * (for stateless use cases)
+ */
+export async function createReceipt(
+  input: CreateReceiptInput & { chain: Chain },
+  keyPair: KeyPair
+): Promise<Receipt> {
+  const requestHash = hash(canonicalizePayload(input.requestBody));
+  const responseHash = hash(canonicalizePayload(input.responseBody));
+
+  const unsignedReceipt = {
+    version: '1.0' as const,
+    receipt_id: uuidv4(),
+    timestamp: new Date().toISOString(),
+    operation: {
+      type: input.type,
+      method: input.method,
+      endpoint: input.endpoint,
+      request_hash: requestHash,
+      response_hash: responseHash
+    },
+    actor: {
+      id: input.actorId,
+      org_id: input.orgId,
+      key_id: keyPair.keyId
+    },
+    chain: input.chain
+  };
+
+  const { pqc_signature, receipt_hash } = await signReceipt(
+    unsignedReceipt,
+    keyPair.secretKey,
+    keyPair.publicKey
+  );
+
+  return {
+    ...unsignedReceipt,
+    pqc_signature,
+    receipt_hash
+  };
+}

package/src/types.ts

@@ -0,0 +1,86 @@
+/**
+ * PQC Receipt SDK - Type Definitions
+ * Algorithm: ML-DSA-65 (FIPS 204 / CRYSTALS-Dilithium)
+ */
+
+export interface Operation {
+  type: 'intercept' | 'verify' | 'revoke' | 'anchor';
+  method: string;
+  endpoint: string;
+  request_hash: string;
+  response_hash: string;
+}
+
+export interface Actor {
+  id: string;
+  org_id: string;
+  key_id: string;
+}
+
+export interface Chain {
+  sequence: number;
+  prev_receipt_hash: string | null;
+}
+
+export interface PQCSignature {
+  algorithm: 'ML-DSA-65';
+  public_key_id: string;
+  signature: string; // base64
+}
+
+export interface Receipt {
+  version: '1.0';
+  receipt_id: string;
+  timestamp: string;
+  operation: Operation;
+  actor: Actor;
+  chain: Chain;
+  pqc_signature: PQCSignature;
+  receipt_hash: string;
+}
+
+export interface LogEntry {
+  entry_id: string;
+  sequence: number;
+  timestamp: string;
+  receipt_hash: string;
+  prev_entry_hash: string | null;
+  entry_hash: string;
+  anchor: {
+    type: 'none' | 'hardhat' | 'ethereum' | 'external';
+    tx_hash?: string;
+    block_number?: number;
+    anchored_at?: string;
+  };
+}
+
+export interface KeyPair {
+  publicKey: Buffer;
+  secretKey: Buffer;
+  keyId: string;
+}
+
+export interface VerificationResult {
+  valid: boolean;
+  error?: 'KEY_MISMATCH' | 'SIGNATURE_INVALID' | 'HASH_MISMATCH' | 'CHAIN_BREAK' | 'SEQUENCE_GAP';
+  details?: string;
+}
+
+export interface ChainVerificationResult {
+  valid: boolean;
+  length: number;
+  breaks: Array<{
+    index: number;
+    error: string;
+  }>;
+}
+
+export interface CreateReceiptInput {
+  type: Operation['type'];
+  method: string;
+  endpoint: string;
+  requestBody: unknown;
+  responseBody: unknown;
+  actorId: string;
+  orgId: string;
+}

package/src/verifier.js

@@ -0,0 +1,115 @@
+/**
+ * PQC Receipt SDK - Independent Verification
+ */
+
+import { verifySignature, hash, canonicalizePayload } from './crypto.js';
+import { verifyLogChain } from './log.js';
+
+/**
+ * Verify a single receipt
+ */
+export async function verifyReceipt(receipt, publicKey) {
+  return verifySignature(receipt, publicKey);
+}
+
+/**
+ * Verify receipt hash integrity (without signature verification)
+ */
+export function verifyReceiptHash(receipt) {
+  const receiptCopy = { ...receipt };
+  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, publicKey) {
+  const failed = [];
+
+  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, logEntries, publicKey) {
+  // 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 = [];
+  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
+    }
+  };
+}