Package Exports

@finalbosstech/pqc-receipt-sdk
@finalbosstech/pqc-receipt-sdk/src/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@finalbosstech/pqc-receipt-sdk) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@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

@finalbosstech/pqc-receipt-sdk