@finalboss/pqc-receipt-sdk

Post-Quantum Cryptographic Receipt Generation SDK

Generate tamper-evident, cryptographically signed receipts using ML-DSA-65 (FIPS 204 / CRYSTALS-Dilithium).

Features

• ML-DSA-65 Signatures - NIST-standardized post-quantum algorithm
• Hash Chaining - Each receipt links to previous via SHA3-256
• Append-Only Log - Tamper-evident log with integrity verification
• On-Chain Anchoring - Optional Ethereum/Hardhat anchoring support
• RFC 8785 Canonicalization - Deterministic JSON serialization

Installation

npm install @finalboss/pqc-receipt-sdk @openforge-sh/liboqs-node

Note: @openforge-sh/liboqs-node provides ML-DSA-65 via WASM.

Quick Start

import {
  generateKeyPair,
  ReceiptGenerator,
  AppendOnlyLog,
  verifyReceipt
} from '@finalboss/pqc-receipt-sdk';

// 1. Generate ML-DSA-65 key pair
const keyPair = await generateKeyPair();

// 2. Create receipt generator
const generator = new ReceiptGenerator(keyPair);
const log = new AppendOnlyLog();

// 3. Generate a signed 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'
});

// 4. Append to log
log.append(receipt);

// 5. Verify independently
const result = await verifyReceipt(receipt, keyPair.publicKey);
console.log(result.valid); // true

Receipt Schema

{
  "version": "1.0",
  "receipt_id": "uuid",
  "timestamp": "ISO8601",
  "operation": {
    "type": "intercept|verify|revoke|anchor",
    "method": "POST",
    "endpoint": "/api/...",
    "request_hash": "sha3-256",
    "response_hash": "sha3-256"
  },
  "actor": {
    "id": "subject-id",
    "org_id": "org-id",
    "key_id": "public-key-fingerprint"
  },
  "chain": {
    "sequence": 1,
    "prev_receipt_hash": "sha3-256 or null"
  },
  "pqc_signature": {
    "algorithm": "ML-DSA-65",
    "public_key_id": "fingerprint",
    "signature": "base64"
  },
  "receipt_hash": "sha3-256"
}

CLI Verification

# Verify single receipt
npx pqc-verify receipt --file receipt.json --pubkey key.pub

# Verify log chain
npx pqc-verify chain --log receipts.jsonl

# Verify on-chain anchor
npx pqc-verify anchor --log-root <hash> --contract <addr> --rpc <url>

API Reference

Key Management

// Generate new key pair
const keyPair = await generateKeyPair();
// { publicKey: Buffer, secretKey: Buffer, keyId: string }

// Compute key fingerprint
const keyId = computeKeyId(publicKey);

Receipt Generation

// Stateful generator (maintains chain)
const generator = new ReceiptGenerator(keyPair);
const receipt = await generator.generate({ ... });

// Stateless creation
const receipt = await createReceipt({ ..., chain: { sequence: 1, prev_receipt_hash: null } }, keyPair);

Log Management

const log = new AppendOnlyLog();
log.append(receipt);

const result = log.verify();
// { valid: boolean, length: number, breaks: [] }

const root = log.getLogRoot();

Verification

// Verify single receipt
const result = await verifyReceipt(receipt, publicKey);

// Verify chain of receipts
const result = await verifyReceiptChain(receipts, publicKey);

// Verify on-chain anchor
const result = await verifyAnchor(logRoot, contractAddr, rpcUrl);

Security Notes

• Experimental Library: liboqs implements FIPS 204 draft. For production, use hardened implementation.
• Key Storage: Store secret keys encrypted. Consider HSM for production.
• Clock Sync: Use NTP-synchronized time sources.

License

Apache-2.0

Links

• NIST FIPS 204 (ML-DSA)
• liboqs
• RFC 8785 (JCS)