Canon

Mathematical proof of data provenance using causal synthesis.

What is it?

Canon generates Canonical Proof IDs (CPIDs) that mathematically link data through chains. Each CPID is:

• Deterministic - same input always produces same output
• Verifiable - anyone can independently verify a CPID
• Tamper-evident - any modification breaks the chain

Use cases

• Audit trails - prove sequence of events happened in order
• Document versioning - cryptographically link document revisions
• Data provenance - verify data hasn't been modified since creation
• Supply chain - track items through processing steps
• Compliance - demonstrate data integrity for regulatory requirements

Installation

npm install canon-cpg

Quick start

# Generate a proof
CPID=$(canon prove --data "Hello World")
echo $CPID

# Verify it
canon verify --cpid $CPID --previous 0 --data "Hello World"

Building chains

Each CPID can be linked to the previous, creating a verifiable chain:

# Start a chain
CPID_1=$(canon prove --data "Genesis block")

# Add to the chain
CPID_2=$(canon prove --data "Second entry" --previous $CPID_1)
CPID_3=$(canon prove --data "Third entry" --previous $CPID_2)

# Verify entire chain
cat > chain.json << EOF
{
  "start": "0",
  "steps": [
    { "data": "Genesis block", "cpid": "$CPID_1" },
    { "data": "Second entry", "cpid": "$CPID_2" },
    { "data": "Third entry", "cpid": "$CPID_3" }
  ]
}
EOF

canon verify-chain --chain-file chain.json

How it works

CPID_n = synthesize(CPID_{n-1}, hash(data_n))

The synthesize function uses causal synthesis from the koru-lambda WASM engine to combine:

1. The previous CPID (or primordial starting point)
2. A SHA-256 hash of the data

This produces a unique 64-character hex identifier that proves the data existed at that point in the chain.

Commands

canon prove

Generate a CPID for data.

canon prove --data "your data"
canon prove --file ./document.txt
echo "piped data" | canon prove
canon prove --data "step 2" --previous $CPID_1
canon prove --data "test" --output json

Options:

• --data - Data string to prove
• --file - File to read data from
• --previous - Previous CPID to chain from (default: primordial 0)
• --output - Output format: text (default) or json
• --verbose - Show detailed output

canon verify

Verify a CPID matches expected data.

canon verify --cpid $CPID --previous 0 --data "expected data"

Options:

• --cpid - The CPID to verify (required)
• --previous - The previous CPID in chain (required)
• --data / --file - Expected data
• --output - Output format
• --quiet - Exit code only, no output

canon verify-chain

Verify an entire chain from JSON.

canon verify-chain --chain-file chain.json

canon primordials

Show the primordial starting points (0 and 1).

canon primordials

Programmatic usage

import { initEngine } from 'canon-cpg';
import { sha256 } from 'canon-cpg/utils';

const engine = await initEngine();

// Get starting point
const start = engine.getPrimordial(0);

// Create a proof
const dataHash = sha256('Hello World');
const hashDist = engine.hashToDistinction(dataHash);
const cpid = engine.synthesize(start, hashDist);

console.log(cpid);

Testing

npm test          # Run unit tests
npm run check     # Run full check suite

Tests use a falsification approach - attempting to break cryptographic guarantees rather than just confirming happy paths.

Security properties

The test suite verifies:

• Determinism - identical inputs always produce identical outputs
• Forgery resistance - cannot create valid CPID without correct data
• Chain integrity - tampering, deletion, or reordering is detectable
• Collision resistance - different inputs produce different outputs

Playground

Interactive browser interface:

npm run playground
# Opens http://localhost:8000/playground/

Project structure

canon-cpg/
├── cli/           # Command-line interface
├── tests/         # Falsification test suite
├── playground/    # Browser interface
└── scripts/       # Build and check scripts

Author

Sawyer Kent [email protected]

License

MIT OR Apache-2.0