@finalbosstech/pqc-receipt-sdk 1.0.0

package/src/crypto.js

@@ -0,0 +1,153 @@
+/**
+ * PQC Receipt SDK - Cryptographic Operations
+ * ML-DSA-65 (FIPS 204) via @noble/post-quantum
+ */
+
+import { ml_dsa65 } from '@noble/post-quantum/ml-dsa.js';
+import { sha3_256 } from '@noble/hashes/sha3';
+import { bytesToHex } from '@noble/hashes/utils';
+import canonicalize from 'canonicalize';
+
+/**
+ * Generate ML-DSA-65 key pair
+ * @returns {Promise<{publicKey: Uint8Array, secretKey: Uint8Array, keyId: string}>}
+ */
+export async function generateKeyPair() {
+  const seed = crypto.getRandomValues(new Uint8Array(32));
+  const keypair = ml_dsa65.keygen(seed);
+
+  return {
+    publicKey: keypair.publicKey,
+    secretKey: keypair.secretKey,
+    keyId: computeKeyId(keypair.publicKey)
+  };
+}
+
+/**
+ * Compute SHA3-256 fingerprint of public key
+ * @param {Uint8Array} publicKey
+ * @returns {string}
+ */
+export function computeKeyId(publicKey) {
+  return bytesToHex(sha3_256(publicKey));
+}
+
+/**
+ * SHA3-256 hash of any data
+ * @param {string|Uint8Array} data
+ * @returns {string}
+ */
+export function hash(data) {
+  if (typeof data === 'string') {
+    return bytesToHex(sha3_256(new TextEncoder().encode(data)));
+  }
+  return bytesToHex(sha3_256(data));
+}
+
+/**
+ * Canonicalize JSON per RFC 8785 (JCS)
+ * @param {unknown} obj
+ * @returns {string}
+ */
+export function canonicalizePayload(obj) {
+  if (obj === null || obj === undefined) {
+    return '';
+  }
+  if (typeof obj === 'string') {
+    return obj;
+  }
+  return canonicalize(obj) || '';
+}
+
+/**
+ * Build the signing payload from a receipt (excludes signature fields)
+ * @param {object} receipt
+ * @returns {string}
+ */
+export function buildSigningPayload(receipt) {
+  return canonicalizePayload({
+    version: receipt.version,
+    receipt_id: receipt.receipt_id,
+    timestamp: receipt.timestamp,
+    operation: receipt.operation,
+    actor: receipt.actor,
+    chain: receipt.chain
+  });
+}
+
+/**
+ * Sign a receipt with ML-DSA-65
+ * @param {object} receipt - Unsigned receipt
+ * @param {Uint8Array} secretKey
+ * @param {Uint8Array} publicKey
+ * @returns {Promise<{pqc_signature: object, receipt_hash: string}>}
+ */
+export async function signReceipt(receipt, secretKey, publicKey) {
+  // Build canonical signing payload
+  const signingPayload = buildSigningPayload(receipt);
+  const payloadBytes = new TextEncoder().encode(signingPayload);
+
+  // Sign with ML-DSA-65: sign(message, secretKey)
+  const signature = ml_dsa65.sign(payloadBytes, secretKey);
+
+  const pqc_signature = {
+    algorithm: 'ML-DSA-65',
+    public_key_id: computeKeyId(publicKey),
+    signature: Buffer.from(signature).toString('base64')
+  };
+
+  // Compute final receipt hash (includes signature)
+  const fullReceipt = { ...receipt, pqc_signature };
+  const receipt_hash = hash(canonicalizePayload(fullReceipt));
+
+  return { pqc_signature, receipt_hash };
+}
+
+/**
+ * Verify a receipt's ML-DSA-65 signature
+ * @param {object} receipt
+ * @param {Uint8Array} publicKey
+ * @returns {Promise<{valid: boolean, error?: string}>}
+ */
+export async function verifySignature(receipt, publicKey) {
+  // Verify key fingerprint
+  const expectedKeyId = computeKeyId(publicKey);
+  if (receipt.pqc_signature.public_key_id !== expectedKeyId) {
+    return { valid: false, error: 'KEY_MISMATCH' };
+  }
+
+  // Rebuild signing payload
+  const signingPayload = buildSigningPayload(receipt);
+  const payloadBytes = new TextEncoder().encode(signingPayload);
+
+  // Decode signature from base64
+  const signature = new Uint8Array(Buffer.from(receipt.pqc_signature.signature, 'base64'));
+
+  // Verify ML-DSA signature: verify(signature, message, publicKey)
+  try {
+    const isValid = ml_dsa65.verify(signature, payloadBytes, publicKey);
+    if (!isValid) {
+      return { valid: false, error: 'SIGNATURE_INVALID' };
+    }
+  } catch (e) {
+    return { valid: false, error: 'SIGNATURE_INVALID' };
+  }
+
+  // Verify receipt_hash integrity
+  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 };
+}
+
+// Export algorithm info
+export const ALGORITHM = 'ML-DSA-65';
+export const HASH_ALGORITHM = 'SHA3-256';
+export const PUBLIC_KEY_SIZE = 1952;
+export const SECRET_KEY_SIZE = 4032;
+export const SIGNATURE_SIZE = 3309;

package/src/crypto.ts

@@ -0,0 +1,183 @@
+/**
+ * PQC Receipt SDK - Cryptographic Operations
+ * ML-DSA-65 (Dilithium3) via liboqs
+ */
+
+import { sha3_256 } from 'js-sha3';
+import canonicalize from 'canonicalize';
+import type { KeyPair, Receipt, PQCSignature } from './types.js';
+
+// Lazy-loaded liboqs (peer dependency)
+let Dilithium: any = null;
+
+async function getDilithium() {
+  if (!Dilithium) {
+    try {
+      const liboqs = await import('@openforge-sh/liboqs-node');
+      Dilithium = liboqs.Dilithium;
+    } catch (e) {
+      throw new Error(
+        'PQC library not found. Install: npm install @openforge-sh/liboqs-node'
+      );
+    }
+  }
+  return new Dilithium('Dilithium3'); // ML-DSA-65
+}
+
+/**
+ * Generate ML-DSA-65 key pair
+ */
+export async function generateKeyPair(): Promise<KeyPair> {
+  const dilithium = await getDilithium();
+  const keypair = await dilithium.generateKeyPair();
+
+  return {
+    publicKey: keypair.publicKey,
+    secretKey: keypair.secretKey,
+    keyId: computeKeyId(keypair.publicKey)
+  };
+}
+
+/**
+ * Compute SHA3-256 fingerprint of public key
+ */
+export function computeKeyId(publicKey: Buffer): string {
+  return sha3_256(publicKey);
+}
+
+/**
+ * SHA3-256 hash of any data
+ */
+export function hash(data: string | Buffer): string {
+  return sha3_256(data);
+}
+
+/**
+ * Canonicalize JSON per RFC 8785 (JCS)
+ */
+export function canonicalizePayload(obj: unknown): string {
+  if (obj === null || obj === undefined) {
+    return '';
+  }
+  if (typeof obj === 'string') {
+    return obj;
+  }
+  return canonicalize(obj) || '';
+}
+
+/**
+ * Build the signing payload from a receipt (excludes signature fields)
+ */
+export function buildSigningPayload(receipt: Omit<Receipt, 'pqc_signature' | 'receipt_hash'>): string {
+  return canonicalizePayload({
+    version: receipt.version,
+    receipt_id: receipt.receipt_id,
+    timestamp: receipt.timestamp,
+    operation: receipt.operation,
+    actor: receipt.actor,
+    chain: receipt.chain
+  });
+}
+
+/**
+ * Sign a receipt with ML-DSA-65
+ */
+export async function signReceipt(
+  receipt: Omit<Receipt, 'pqc_signature' | 'receipt_hash'>,
+  secretKey: Buffer,
+  publicKey: Buffer
+): Promise<{ pqc_signature: PQCSignature; receipt_hash: string }> {
+  const dilithium = await getDilithium();
+
+  // Build canonical signing payload
+  const signingPayload = buildSigningPayload(receipt);
+
+  // Sign with ML-DSA-65
+  const signature = await dilithium.sign(
+    Buffer.from(signingPayload, 'utf8'),
+    secretKey
+  );
+
+  const pqc_signature: PQCSignature = {
+    algorithm: 'ML-DSA-65',
+    public_key_id: computeKeyId(publicKey),
+    signature: signature.toString('base64')
+  };
+
+  // Compute final receipt hash (includes signature)
+  const fullReceipt = { ...receipt, pqc_signature };
+  const receipt_hash = hash(canonicalizePayload(fullReceipt));
+
+  return { pqc_signature, receipt_hash };
+}
+
+/**
+ * Verify a receipt's ML-DSA-65 signature
+ */
+export async function verifySignature(
+  receipt: Receipt,
+  publicKey: Buffer
+): Promise<{ valid: boolean; error?: string }> {
+  const dilithium = await getDilithium();
+
+  // Verify key fingerprint
+  const expectedKeyId = computeKeyId(publicKey);
+  if (receipt.pqc_signature.public_key_id !== expectedKeyId) {
+    return { valid: false, error: 'KEY_MISMATCH' };
+  }
+
+  // Rebuild signing payload
+  const signingPayload = buildSigningPayload(receipt);
+
+  // Verify ML-DSA signature
+  const signature = Buffer.from(receipt.pqc_signature.signature, 'base64');
+  const isValid = await dilithium.verify(
+    Buffer.from(signingPayload, 'utf8'),
+    signature,
+    publicKey
+  );
+
+  if (!isValid) {
+    return { valid: false, error: 'SIGNATURE_INVALID' };
+  }
+
+  // Verify receipt_hash integrity
+  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 };
+}
+
+/**
+ * Fallback: Classical RSA-PSS signing for dual-signature mode
+ * (Used when liboqs is unavailable)
+ */
+export async function signWithFallback(
+  receipt: Omit<Receipt, 'pqc_signature' | 'receipt_hash'>,
+  privateKeyPem: string
+): Promise<{ pqc_signature: PQCSignature; receipt_hash: string }> {
+  const crypto = await import('crypto');
+
+  const signingPayload = buildSigningPayload(receipt);
+
+  const sign = crypto.createSign('RSA-SHA256');
+  sign.update(signingPayload);
+  const signature = sign.sign(privateKeyPem);
+
+  // Mark as fallback in algorithm field
+  const pqc_signature: PQCSignature = {
+    algorithm: 'ML-DSA-65', // Will be replaced when real PQC available
+    public_key_id: hash(privateKeyPem).slice(0, 64),
+    signature: signature.toString('base64')
+  };
+
+  const fullReceipt = { ...receipt, pqc_signature };
+  const receipt_hash = hash(canonicalizePayload(fullReceipt));
+
+  return { pqc_signature, receipt_hash };
+}

package/src/index.js

@@ -0,0 +1,65 @@
+/**
+ * @finalboss/pqc-receipt-sdk
+ *
+ * Post-Quantum Cryptographic Receipt Generation SDK
+ * Algorithm: ML-DSA-65 (FIPS 204 / CRYSTALS-Dilithium)
+ *
+ * @example
+ * ```javascript
+ * import { generateKeyPair, ReceiptGenerator, AppendOnlyLog, verifyReceipt } from '@finalboss/pqc-receipt-sdk';
+ *
+ * // Generate PQC key pair
+ * const keyPair = await generateKeyPair();
+ *
+ * // Create receipt generator
+ * const generator = new ReceiptGenerator(keyPair);
+ *
+ * // Generate a receipt
+ * const receipt = await generator.generate({
+ *   type: 'intercept',
+ *   method: 'POST',
+ *   endpoint: '/api/v1/verify',
+ *   requestBody: { user_id: 'alice' },
+ *   responseBody: { verified: true },
+ *   actorId: 'alice',
+ *   orgId: 'acme-corp'
+ * });
+ *
+ * // Verify independently
+ * const result = await verifyReceipt(receipt, keyPair.publicKey);
+ * console.log(result.valid); // true
+ * ```
+ */
+
+// Cryptographic operations
+export {
+  generateKeyPair,
+  computeKeyId,
+  hash,
+  canonicalizePayload,
+  signReceipt,
+  verifySignature,
+  buildSigningPayload,
+  ALGORITHM,
+  HASH_ALGORITHM,
+  PUBLIC_KEY_SIZE,
+  SECRET_KEY_SIZE,
+  SIGNATURE_SIZE
+} from './crypto.js';
+
+// Receipt generation
+export { ReceiptGenerator, createReceipt } from './receipt.js';
+
+// Append-only log
+export { AppendOnlyLog, verifyLogChain } from './log.js';
+
+// Verification
+export {
+  verifyReceipt,
+  verifyReceiptHash,
+  verifyReceiptChain,
+  verifyFull
+} from './verifier.js';
+
+// Version
+export const VERSION = '1.0.0';

package/src/index.ts

@@ -0,0 +1,78 @@
+/**
+ * @finalboss/pqc-receipt-sdk
+ *
+ * Post-Quantum Cryptographic Receipt Generation SDK
+ * Algorithm: ML-DSA-65 (FIPS 204 / CRYSTALS-Dilithium)
+ *
+ * @example
+ * ```typescript
+ * import { generateKeyPair, ReceiptGenerator, AppendOnlyLog, verifyReceipt } from '@finalboss/pqc-receipt-sdk';
+ *
+ * // Generate PQC key pair
+ * const keyPair = await generateKeyPair();
+ *
+ * // Create receipt generator
+ * const generator = new ReceiptGenerator(keyPair);
+ *
+ * // Generate a receipt
+ * const receipt = await generator.generate({
+ *   type: 'intercept',
+ *   method: 'POST',
+ *   endpoint: '/api/v1/verify',
+ *   requestBody: { user_id: 'alice' },
+ *   responseBody: { verified: true },
+ *   actorId: 'alice',
+ *   orgId: 'acme-corp'
+ * });
+ *
+ * // Verify independently
+ * const result = await verifyReceipt(receipt, keyPair.publicKey);
+ * console.log(result.valid); // true
+ * ```
+ */
+
+// Types
+export type {
+  Receipt,
+  LogEntry,
+  KeyPair,
+  Operation,
+  Actor,
+  Chain,
+  PQCSignature,
+  VerificationResult,
+  ChainVerificationResult,
+  CreateReceiptInput
+} from './types.js';
+
+// Cryptographic operations
+export {
+  generateKeyPair,
+  computeKeyId,
+  hash,
+  canonicalizePayload,
+  signReceipt,
+  verifySignature,
+  buildSigningPayload,
+  signWithFallback
+} from './crypto.js';
+
+// Receipt generation
+export { ReceiptGenerator, createReceipt } from './receipt.js';
+
+// Append-only log
+export { AppendOnlyLog, verifyLogChain } from './log.js';
+
+// Verification
+export {
+  verifyReceipt,
+  verifyReceiptHash,
+  verifyReceiptChain,
+  verifyFull,
+  verifyAnchor
+} from './verifier.js';
+
+// Version
+export const VERSION = '1.0.0';
+export const ALGORITHM = 'ML-DSA-65';
+export const HASH_ALGORITHM = 'SHA3-256';

package/src/log.js

@@ -0,0 +1,193 @@
+/**
+ * PQC Receipt SDK - Append-Only Log Management
+ */
+
+import { v4 as uuidv4 } from 'uuid';
+import { hash } from './crypto.js';
+
+export class AppendOnlyLog {
+  constructor() {
+    this.entries = [];
+    this.sequence = 0;
+  }
+
+  /**
+   * Append a receipt to the log
+   */
+  append(receipt) {
+    this.sequence++;
+
+    const prevEntry = this.entries[this.entries.length - 1];
+    const prevEntryHash = prevEntry ? prevEntry.entry_hash : null;
+
+    const entry = {
+      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
+   */
+  computeEntryHash(entry) {
+    const preimage = [
+      entry.sequence.toString(),
+      entry.receipt_hash,
+      entry.prev_entry_hash || 'GENESIS',
+      entry.timestamp
+    ].join('|');
+
+    return hash(preimage);
+  }
+
+  /**
+   * Get all entries
+   */
+  getEntries() {
+    return [...this.entries];
+  }
+
+  /**
+   * Get entry by sequence number
+   */
+  getEntry(sequence) {
+    return this.entries.find(e => e.sequence === sequence);
+  }
+
+  /**
+   * Get latest entry
+   */
+  getLatest() {
+    return this.entries[this.entries.length - 1];
+  }
+
+  /**
+   * Get current log root (latest entry hash)
+   */
+  getLogRoot() {
+    const latest = this.getLatest();
+    return latest ? latest.entry_hash : null;
+  }
+
+  /**
+   * Verify the integrity of the log chain
+   */
+  verify() {
+    const breaks = [];
+
+    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, anchor) {
+    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() {
+    return this.entries.map(e => JSON.stringify(e)).join('\n');
+  }
+
+  /**
+   * Import log from JSON Lines format
+   */
+  static fromJSONL(jsonl) {
+    const log = new AppendOnlyLog();
+    const lines = jsonl.trim().split('\n').filter(Boolean);
+
+    for (const line of lines) {
+      const entry = JSON.parse(line);
+      log.entries.push(entry);
+      log.sequence = Math.max(log.sequence, entry.sequence);
+    }
+
+    return log;
+  }
+
+  /**
+   * Export log as JSON array
+   */
+  toJSON() {
+    return this.entries;
+  }
+
+  /**
+   * Import log from JSON array
+   */
+  static fromJSON(entries) {
+    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) {
+  const log = AppendOnlyLog.fromJSON(entries);
+  return log.verify();
+}