@finalbosstech/pqc-receipt-sdk 1.0.0

package/LICENSE.md

@@ -0,0 +1,31 @@
+# License
+
+This project is dual-licensed.
+
+## Non-Commercial Use
+
+Permitted under [PolyForm Noncommercial License 1.0.0](./LICENSES/PolyForm-Noncommercial-1.0.0.txt).
+
+You may use, modify, and distribute this software for any non-commercial purpose, including:
+- Personal projects and research
+- Academic and educational use
+- Non-profit organizations
+- Evaluation and testing
+
+## Commercial Use
+
+Requires a paid commercial license. See [LICENSES/FinalBoss-Commercial.txt](./LICENSES/FinalBoss-Commercial.txt).
+
+Commercial use includes:
+- Use in revenue-generating products or services
+- Use by for-profit companies in production
+- Integration into commercial software or SaaS
+
+**To obtain a commercial license:**
+
+- Email: abraham@finalbosstech.com
+- Web: https://finalbosstech.com
+
+---
+
+Copyright (c) 2025 FinalBoss Technologies. All rights reserved.

package/LICENSES/FinalBoss-Commercial.txt

@@ -0,0 +1,69 @@
+FinalBoss Commercial License Agreement
+
+Copyright (c) 2025 FinalBoss Technologies. All rights reserved.
+
+COMMERCIAL LICENSE TERMS
+
+This Commercial License Agreement ("Agreement") is entered into between
+FinalBoss Technologies ("Licensor") and the entity or individual obtaining
+this license ("Licensee").
+
+1. GRANT OF LICENSE
+
+Subject to payment of applicable license fees and compliance with this
+Agreement, Licensor grants Licensee a non-exclusive, non-transferable,
+worldwide license to:
+
+  a) Use the Software in commercial applications and services
+  b) Integrate the Software into products that generate revenue
+  c) Deploy the Software in production environments
+  d) Modify the Software for internal use
+
+2. RESTRICTIONS
+
+Licensee may NOT:
+
+  a) Sublicense, sell, or redistribute the Software as a standalone product
+  b) Remove or alter any proprietary notices
+  c) Use the Software to compete directly with Licensor's services
+  d) Reverse engineer the Software except as permitted by law
+
+3. FEES
+
+License fees are determined based on usage tier and deployment scale.
+Contact abraham@finalbosstech.com for pricing.
+
+4. SUPPORT
+
+Commercial licensees receive:
+  - Priority email support
+  - Access to private documentation
+  - Security advisories
+  - Version update notifications
+
+5. WARRANTY DISCLAIMER
+
+THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. LICENSOR
+DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING MERCHANTABILITY
+AND FITNESS FOR A PARTICULAR PURPOSE.
+
+6. LIMITATION OF LIABILITY
+
+IN NO EVENT SHALL LICENSOR BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL,
+OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THE SOFTWARE.
+
+7. TERMINATION
+
+This license terminates automatically if Licensee breaches any term.
+Upon termination, Licensee must cease all use and destroy all copies.
+
+8. GOVERNING LAW
+
+This Agreement is governed by the laws of the State of California, USA.
+
+---
+
+To obtain a Commercial License:
+
+  Email: abraham@finalbosstech.com
+  Web:   https://finalbosstech.com

package/LICENSES/PolyForm-Noncommercial-1.0.0.txt

@@ -0,0 +1,129 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software
+to do everything you might do with the software that would
+otherwise infringe the licensor's copyright in it for any
+permitted purpose.  However, you may only distribute the
+software according to [Distribution License](#distribution-license)
+and make changes or new works based on the software according
+to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to
+distribute copies of the software.  Your license to distribute
+covers distributing the software with changes and new works
+permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization.  **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

package/README.md

@@ -0,0 +1,167 @@
+# @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
+
+```bash
+npm install @finalboss/pqc-receipt-sdk @openforge-sh/liboqs-node
+```
+
+> **Note**: `@openforge-sh/liboqs-node` provides ML-DSA-65 via WASM.
+
+## Quick Start
+
+```typescript
+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
+
+```json
+{
+  "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
+
+```bash
+# 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
+
+```typescript
+// Generate new key pair
+const keyPair = await generateKeyPair();
+// { publicKey: Buffer, secretKey: Buffer, keyId: string }
+
+// Compute key fingerprint
+const keyId = computeKeyId(publicKey);
+```
+
+### Receipt Generation
+
+```typescript
+// 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
+
+```typescript
+const log = new AppendOnlyLog();
+log.append(receipt);
+
+const result = log.verify();
+// { valid: boolean, length: number, breaks: [] }
+
+const root = log.getLogRoot();
+```
+
+### Verification
+
+```typescript
+// 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)](https://csrc.nist.gov/pubs/fips/204/final)
+- [liboqs](https://openquantumsafe.org/liboqs/)
+- [RFC 8785 (JCS)](https://datatracker.ietf.org/doc/html/rfc8785)

package/bin/pqc-verify.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+/**
+ * PQC Receipt Verification CLI
+ *
+ * Usage:
+ *   pqc-verify receipt --file receipt.json --pubkey key.pub
+ *   pqc-verify chain --log receipts.jsonl
+ *   pqc-verify anchor --log-root <hash> --contract <addr> --rpc <url>
+ */
+
+import { readFileSync } from 'fs';
+import { verifyReceipt, verifyLogChain, verifyAnchor } from '../src/index.js';
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function parseArgs(args) {
+  const parsed = {};
+  for (let i = 1; i < args.length; i += 2) {
+    const key = args[i].replace(/^--/, '');
+    parsed[key] = args[i + 1];
+  }
+  return parsed;
+}
+
+function printResult(label, result) {
+  const status = result.valid ? '\x1b[32m✓ PASS\x1b[0m' : '\x1b[31m✗ FAIL\x1b[0m';
+  console.log(`\n${label}: ${status}`);
+  console.log(JSON.stringify(result, null, 2));
+}
+
+async function main() {
+  switch (command) {
+    case 'receipt': {
+      const opts = parseArgs(args);
+      if (!opts.file || !opts.pubkey) {
+        console.error('Usage: pqc-verify receipt --file <receipt.json> --pubkey <key.pub>');
+        process.exit(1);
+      }
+
+      const receipt = JSON.parse(readFileSync(opts.file, 'utf8'));
+      const publicKey = Buffer.from(readFileSync(opts.pubkey, 'utf8'), 'base64');
+
+      const result = await verifyReceipt(receipt, publicKey);
+      printResult('Receipt Verification', result);
+      process.exit(result.valid ? 0 : 1);
+      break;
+    }
+
+    case 'chain': {
+      const opts = parseArgs(args);
+      if (!opts.log) {
+        console.error('Usage: pqc-verify chain --log <receipts.jsonl>');
+        process.exit(1);
+      }
+
+      const lines = readFileSync(opts.log, 'utf8').trim().split('\n');
+      const entries = lines.map(line => JSON.parse(line));
+
+      const result = verifyLogChain(entries);
+      printResult('Chain Verification', result);
+      process.exit(result.valid ? 0 : 3);
+      break;
+    }
+
+    case 'anchor': {
+      const opts = parseArgs(args);
+      if (!opts['log-root'] || !opts.contract || !opts.rpc) {
+        console.error('Usage: pqc-verify anchor --log-root <hash> --contract <addr> --rpc <url>');
+        process.exit(1);
+      }
+
+      const result = await verifyAnchor(opts['log-root'], opts.contract, opts.rpc);
+      printResult('Anchor Verification', result);
+      process.exit(result.exists ? 0 : 4);
+      break;
+    }
+
+    case 'help':
+    case '--help':
+    case '-h':
+    default:
+      console.log(`
+PQC Receipt Verification CLI
+
+Commands:
+  receipt   Verify a single receipt's ML-DSA-65 signature
+  chain     Verify log chain integrity
+  anchor    Verify anchor exists on-chain
+
+Examples:
+  pqc-verify receipt --file receipt.json --pubkey signing_key.pub
+  pqc-verify chain --log receipts.jsonl
+  pqc-verify anchor --log-root abc123... --contract 0x... --rpc http://localhost:8545
+
+Exit Codes:
+  0  Verification passed
+  1  Signature invalid
+  2  Hash mismatch
+  3  Chain break detected
+  4  Anchor not found
+  5  Key mismatch
+`);
+      process.exit(0);
+  }
+}
+
+main().catch(err => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});

package/contracts/ReceiptAnchor.sol

@@ -0,0 +1,160 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.19;
+
+/**
+ * @title ReceiptAnchor
+ * @notice Anchors PQC receipt log roots to provide external timestamping proof
+ * @dev Used with append-only log to create verifiable anchoring points
+ */
+contract ReceiptAnchor {
+    /// @notice Emitted when a new log root is anchored
+    event Anchored(
+        bytes32 indexed logRoot,
+        uint256 indexed sequence,
+        address indexed anchor,
+        uint256 timestamp
+    );
+
+    /// @notice Anchor record structure
+    struct Anchor {
+        bytes32 logRoot;
+        uint256 sequence;
+        uint256 timestamp;
+        address anchoredBy;
+        bool exists;
+    }
+
+    /// @notice Mapping of log roots to their anchor records
+    mapping(bytes32 => Anchor) public anchors;
+
+    /// @notice Ordered history of all anchored roots
+    bytes32[] public anchorHistory;
+
+    /// @notice Mapping of authorized anchors (addresses allowed to anchor)
+    mapping(address => bool) public authorizedAnchors;
+
+    /// @notice Contract owner
+    address public owner;
+
+    modifier onlyOwner() {
+        require(msg.sender == owner, "Not owner");
+        _;
+    }
+
+    modifier onlyAuthorized() {
+        require(authorizedAnchors[msg.sender] || msg.sender == owner, "Not authorized");
+        _;
+    }
+
+    constructor() {
+        owner = msg.sender;
+        authorizedAnchors[msg.sender] = true;
+    }
+
+    /**
+     * @notice Anchor a log root
+     * @param logRoot The SHA3-256 hash of the log entry being anchored
+     * @param sequence The monotonic sequence number in the log
+     */
+    function anchor(bytes32 logRoot, uint256 sequence) external onlyAuthorized {
+        require(!anchors[logRoot].exists, "Already anchored");
+        require(logRoot != bytes32(0), "Invalid log root");
+
+        anchors[logRoot] = Anchor({
+            logRoot: logRoot,
+            sequence: sequence,
+            timestamp: block.timestamp,
+            anchoredBy: msg.sender,
+            exists: true
+        });
+
+        anchorHistory.push(logRoot);
+
+        emit Anchored(logRoot, sequence, msg.sender, block.timestamp);
+    }
+
+    /**
+     * @notice Verify if a log root has been anchored
+     * @param logRoot The log root to verify
+     * @return exists Whether the anchor exists
+     * @return sequence The sequence number if anchored
+     * @return timestamp The block timestamp when anchored
+     */
+    function verify(bytes32 logRoot) external view returns (
+        bool exists,
+        uint256 sequence,
+        uint256 timestamp
+    ) {
+        Anchor memory a = anchors[logRoot];
+        return (a.exists, a.sequence, a.timestamp);
+    }
+
+    /**
+     * @notice Get full anchor details
+     * @param logRoot The log root to query
+     * @return The complete Anchor struct
+     */
+    function getAnchor(bytes32 logRoot) external view returns (Anchor memory) {
+        return anchors[logRoot];
+    }
+
+    /**
+     * @notice Get the total number of anchors
+     * @return The count of anchored log roots
+     */
+    function getAnchorCount() external view returns (uint256) {
+        return anchorHistory.length;
+    }
+
+    /**
+     * @notice Get anchor at specific index in history
+     * @param index The index in the anchor history
+     * @return The log root at that index
+     */
+    function getAnchorAt(uint256 index) external view returns (bytes32) {
+        require(index < anchorHistory.length, "Index out of bounds");
+        return anchorHistory[index];
+    }
+
+    /**
+     * @notice Get the most recent anchor
+     * @return logRoot The most recently anchored log root
+     * @return sequence The sequence number
+     * @return timestamp The timestamp
+     */
+    function getLatestAnchor() external view returns (
+        bytes32 logRoot,
+        uint256 sequence,
+        uint256 timestamp
+    ) {
+        require(anchorHistory.length > 0, "No anchors");
+        bytes32 latest = anchorHistory[anchorHistory.length - 1];
+        Anchor memory a = anchors[latest];
+        return (a.logRoot, a.sequence, a.timestamp);
+    }
+
+    /**
+     * @notice Authorize an address to anchor
+     * @param addr The address to authorize
+     */
+    function authorize(address addr) external onlyOwner {
+        authorizedAnchors[addr] = true;
+    }
+
+    /**
+     * @notice Revoke authorization from an address
+     * @param addr The address to revoke
+     */
+    function revoke(address addr) external onlyOwner {
+        authorizedAnchors[addr] = false;
+    }
+
+    /**
+     * @notice Transfer ownership
+     * @param newOwner The new owner address
+     */
+    function transferOwnership(address newOwner) external onlyOwner {
+        require(newOwner != address(0), "Invalid address");
+        owner = newOwner;
+    }
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@finalbosstech/pqc-receipt-sdk",
+  "version": "1.0.0",
+  "description": "Post-Quantum Cryptographic Receipt Generation SDK (ML-DSA-65)",
+  "type": "module",
+  "main": "src/index.js",
+  "scripts": {
+    "demo": "node test/demo.js",
+    "verify": "node bin/pqc-verify.js"
+  },
+  "bin": {
+    "pqc-verify": "./bin/pqc-verify.js"
+  },
+  "dependencies": {
+    "@noble/post-quantum": "^0.5.2",
+    "@noble/hashes": "^1.7.0",
+    "canonicalize": "^2.0.0",
+    "uuid": "^9.0.1"
+  },
+  "devDependencies": {
+    "ethers": "^6.9.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "post-quantum",
+    "cryptography",
+    "ml-dsa",
+    "dilithium",
+    "receipts",
+    "audit",
+    "governance"
+  ],
+  "license": "PolyForm-Noncommercial-1.0.0 OR LicenseRef-FinalBoss-Commercial",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/805-ai/pqc-receipt-sdk"
+  }
+}