🛡️ CooL.ledger

AI Decision Evidence & Audit Platform

AI systems make consequential decisions, but ordinary logs are editable.
CooL.ledger creates cryptographically verifiable evidence for offline audit of AI decisions with zero vendor dependencies.

📑 Table of Contents

The Problem We're Solving
Visual Tour & Screenshots
What We Built
How CooL SDK is Architected & Used
Why CooL is Important
Project Structure
How to Run the Project
Architecture & Workflow
Technical Decisions
Technical Details
Limitations & Future Improvements
References & Resources
Contributing
License

🎯 The Problem We're Solving

AI systems increasingly make high-stakes, consequential decisions:

Credit underwriting & loan approvals with autonomous decision boundaries
Risk scoring systems that determine financial eligibility
Identity verification and compliance checks

The core issue: Traditional database logs are:

✗ Editable and backdatable
✗ Centralized and subject to tampering
✗ Non-repudiateable at audit time
✗ Require vendor API access for verification

Without cryptographic evidence at the AI decision boundary, post-hoc audits cannot determine when a decision was truly made, who made it, or whether the evidence has been tampered with.

📸 Visual Tour & Screenshots

Live demo: reverse-hackathon.vercel.app — explore the live interactive application directly.

Explore every screen, workflow, cryptographic proof view, attack simulation, and mobile layout of the CooL.ledger platform:

┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                   PLATFORM SCREENSHOT DIRECTORY                                  │
├───────────────────────────────┬──────────────────────────────────┬───────────────────────────────┤
│ 1. Core Dashboards            │ 2. Cryptographic Proof Exhibits  │ 3. Forensic Tamper Lab        │
│   • Case Overview             │   • Dual Signatures (Ed25519/PQC)│   • Pristine Baseline         │
│   • Decision Console (Approve)│   • Phala TEE & Merkle Tree      │   • Decision Flipped Attack   │
│   • Decision Console (Deny)   │   • Canonical JSON Inspector     │   • Signature Forgery Attack  │
│   • Audit Docket Ledger       │                                  │   • Merkle Log Tamper Attack  │
├───────────────────────────────┴──────────────────────────────────┴───────────────────────────────┤
│ 4. Mobile & Responsive Layouts                                                                   │
│   • Mobile Overview · Mobile Decision Pipeline · Mobile Evidence Receipt                         │
└──────────────────────────────────────────────────────────────────────────────────────────────────┘

1. Core Dashboards & Decision Boundary

🏛️ Case Overview & Trust Infrastructure

Complete institutional overview showcasing active cryptographic key registry (Ed25519, NIST FIPS 204 ML-DSA-65, Phala dstack TEE), key metrics, and current case file docket entries.

⚡ Decision Console — Autonomous AI Underwriting (Approved)

Real-time credit decision simulator on synthetic applicant Sarah Chen (#8842). The live 5-stage CooL evidence pipeline seals state: Model decides → Salted SHA-256 seal → Ed25519 signature → ML-DSA-65 quantum countersignature → Receipt issued & logged.

🛑 Decision Console — Adverse Action & Denial Flow (Rejected)

Credit evaluation of Elena Rostova (#8844) resulting in autonomous rejection. Sealed evidence captures adverse action reasons (Credit score below threshold, Excessive DTI ratio) and generates non-repudiable audit trails.

📜 Institutional Audit Docket & Multi-Case Ledger

Searchable and filterable institutional ledger of all recorded evidence receipts. Reviewers can filter by status (All, Verified, Tampered), verify batch integrity, and copy cryptographic decision IDs.

2. Cryptographic Evidence Exhibits & Proofs

🔐 Exhibit A — Salted PII Commitments & Dual Signatures

The cryptographic evidence receipt. Raw applicant PII is never stored — only salted SHA-256 commitments. Includes classical Ed25519 signature and post-quantum ML-DSA-65 (FIPS 204) countersignature.

🛡️ Exhibit A — Phala dstack TEE Attestation & RFC 6962 Merkle Audit Path

Hardware-rooted trust via Phala Network Trusted Execution Environment attestation measurement and cryptographic RFC 6962 transparency log inclusion proof.

📋 Raw Canonical JSON Exhibit Inspector

High-contrast modal inspector presenting the canonical JSON exhibit format. Ready for one-click clipboard copying and ingestion by offline command-line verifiers (cool verify).

3. Forensic Tamper Lab (Attack Simulation & Live Detection)

🟢 Pristine Baseline — Unaltered Evidence (5/5 Checks Passing)

Forensic testing laboratory displaying the unaltered sealed receipt. The offline verification engine verifies all 5 independent checks: Input Salt Match, Decision Fingerprint, Ed25519 Signature, ML-DSA-65 Signature, and RFC 6962 Merkle Audit Path.

🔴 Attack Vector 1: Decision Flipping Caught

An attacker attempts to alter a loan decision from REJECTED to APPROVED after issuance. The offline verification engine immediately flags Evidence Tampered, detects Commitment Mismatch, and presents the forensic examiner's findings.

🔴 Attack Vector 2: Signature Forgery Caught

An attacker attempts to substitute a forged signature on the sealed record. The engine rejects the fake signature bytes and flags non-repudiation invalidation.

🔴 Attack Vector 3: Transparency Log Tampering Caught

An attacker attempts to alter the public transparency log tree root to conceal evidence. The Merkle audit path check fails closed, proving the record is unverified against the log.

4. Mobile & Responsive Layouts

Case Overview (Mobile)	Decision Pipeline (Mobile)	Evidence Receipt (Mobile)

Responsive Trust Status & Metrics	Live 5-Stage Mobile Pipeline	Mobile Exhibit & Verification Stamp

🏗️ What We Built

CooL.ledger is a full-stack AI audit platform that:

Captures cryptographic evidence at the moment an AI system makes a consequential decision
Seals decision state with salted SHA-256 commitments that hide raw PII
Creates dual-signature proofs using classical (Ed25519) and post-quantum (ML-DSA-65/Dilithium) cryptography
Generates hardware-rooted attestations via Phala Network TEE (Trusted Execution Environment)
Appends to RFC 6962 transparency logs for append-only, externally-auditable proof
Enables offline verification of evidence integrity without any external API calls

Core Components

Component	Location	Description
Web UI Dashboard	`src/components/`	Interactive evidence explorer with tamper demonstration lab
CooL Evidence Core	`src/evidence/`	Cryptographic evidence generation & verification
AI Credit Model	`src/model/creditModel.ts`	Autonomous decision boundary producing credit decisions
Evidence Service	`src/services/evidenceService.ts`	Persistent receipt storage and retrieval
Verification Engine	`src/evidence/verify.ts`	Offline 5-point cryptographic validation

🔐 How CooL SDK is Architected & Used

SDK Implementation Note: CooL is the evidence-layer SDK we designed and built for this hackathon (src/evidence/), implementing the complete record → hash → sign → attest → log → verify pipeline specified by the challenge. Rather than wrapping a phantom or mock dependency, our CooL SDK runs real, audited cryptographic primitives (@noble/curves for Ed25519, @noble/post-quantum for ML-DSA-65, and @noble/hashes for SHA-256) directly within a resilient, fail-closed client interface.

The CooL SDK is executed at the exact moment of consequential AI decision:

1. `cool.record()` — Cryptographic Evidence Generation

// src/evidence/client.ts
const receipt = await cool.record({
  applicant: applicantData,
  decision: 'APPROVED',
  modelId: 'CreditRisk-v3',
  modelVersion: '3.4.1-prod',
  metadata: decisionMetadata,
});

Records:

Salted PII commitments (no raw data exposure)
Hybrid Ed25519 + ML-DSA-65 signatures
TEE enclave quotes from Phala dstack
RFC 6962 transparency log entry

2. `createSaltedCommitment()` — PII-Safe State Sealing

// src/evidence/hash.ts
const commitment = await createSaltedCommitment(
  applicantInput,   // ApplicantInput
  'APPROVED',       // decision string
  decisionMetadata, // DecisionMetadata
);
// Result: { salt, saltedInputHash, saltedOutputHash, combinedStateHash }
// ✓ Proves what was decided without exposing PII

3. `createHybridSignatures()` — Dual-Strength Signatures

// src/evidence/sign.ts
const signatures = await createHybridSignatures(commitment.combinedStateHash);
// Ed25519: Classical, widely-supported (via @noble/curves)
// ML-DSA-65: Post-quantum resistant FIPS 204 (via @noble/post-quantum)

4. `createTEEAttestation()` — Hardware-Rooted Trust

// src/evidence/phala/dstack.ts
const teeQuote = await createTEEAttestation(
  commitment.combinedStateHash,  // payload hash
  true                            // enabled
);
// SHA-256 integrity binding to mrEnclave/mrSigner measurements

5. `appendToTransparencyLog()` — Append-Only Audit Trail

// src/evidence/phala/log.ts
const merkleProof = await appendToTransparencyLog(commitment.combinedStateHash);
// RFC 6962 Merkle tree inclusion proof
// ✓ Auditable without any API access

6. `verifyReceipt()` — Offline Verification

// src/evidence/verify.ts
const verification = await verifyReceipt(receipt);
// Runs 5 independent fail-closed cryptographic checks:
// ✓ Hash commitment integrity
// ✓ Ed25519 signature validity (real @noble/curves verification)
// ✓ ML-DSA-65 post-quantum signature validity (real @noble/post-quantum verification)
// ✓ TEE quote authenticity
// ✓ Merkle tree consistency

⭐ Why CooL is Important to Our Solution

"At the consequential AI decision boundary, CooL creates the cryptographic evidence that the rest of the application audits. Without this evidence layer, the application falls back to ordinary logs."

Challenge	Without CooL	With CooL
Non-repudiation	✗ Auditor can't prove when decision was made	✓ Cryptographic timestamp in transparency log
Tamper Detection	✗ Any evidence changes are undetectable	✓ Any mutation fails signature verification
PII Exposure	✗ Raw applicant data stored in audit logs	✓ Only salted commitment hashes stored
Audit Independence	✗ Requires vendor API access during review	✓ Fully offline verification possible
Post-Quantum Safety	✗ Classical signatures vulnerable to QC attacks	✓ ML-DSA-65 provides quantum resistance
External Audit Trail	✗ Single-entity control, no transparency	✓ Merkle tree enables third-party log auditing

Why this matters:

Regulatory Compliance: Fintech & NBFC regulators (RBI, SEBI) demand tamper-proof AI audit trails
Fairness & Accountability: Proves whether discriminatory decisions were corrected post-hoc
Fraud Prevention: Any attempt to backdate or modify a decision is cryptographically detectable
Model Governance: Evidence chains decisions to specific model versions & parameters

📁 Project Structure

Reverse-Hackathon/
├── 📄 README.md                          # Project documentation (this file)
├── 📄 ARCHITECTURE.md                    # Detailed system architecture
├── 📄 DEMO.md                            # Demonstration guide
├── 📄 SECURITY.md                        # Security considerations
├── 📄 CHANGELOG.md                       # Version history
├── 📄 LICENSE.md                         # MIT License
├── 📄 package.json                       # Node.js dependencies & scripts
├── 📄 vite.config.ts                     # Vite build configuration
├── 📄 vercel.json                        # Vercel deployment config
├── 📄 tsconfig.json                      # TypeScript base config
├── 📄 .env.example                       # Environment variables template
├── 📄 index.html                         # Entry HTML file
│
├── 📂 src/                               # Main application source code
│   ├── 📄 main.tsx                       # Application entry point
│   ├── 📄 App.tsx                        # Root React component (main dashboard)
│   ├── 📄 App.css                        # App-level styles
│   ├── 📄 index.css                      # Global styles
│   │
│   ├── 📂 components/                    # React UI components
│   │   ├── 📄 Header.tsx                 # App header with branding & navigation
│   │   ├── 📄 OverviewTab.tsx            # System overview dashboard
│   │   ├── 📄 SimulatorTab.tsx           # Credit decision simulator
│   │   ├── 📄 EvidenceReceiptTab.tsx     # Evidence receipt inspector
│   │   ├── 📄 AuditDashboardTab.tsx      # Audit ledger dashboard
│   │   ├── 📄 TamperLabTab.tsx           # Interactive tamper demonstration
│   │   ├── 📄 ReceiptInspectorModal.tsx  # Receipt detail modal
│   │   ├── 📄 DisclaimerBanner.tsx       # Legal disclaimer banner
│   │   └── 📂 ui/                        # Shared UI primitives
│   │
│   ├── 📂 evidence/                      # CooL cryptographic evidence core
│   │   ├── 📄 adapter.ts                 # CooL invocation & adaptation layer
│   │   ├── 📄 client.ts                  # CooL client (record() entry point)
│   │   ├── 📄 hash.ts                    # Salted SHA-256 commitment hashing
│   │   ├── 📄 sign.ts                    # Ed25519 + ML-DSA-65 hybrid signatures
│   │   ├── 📄 verify.ts                  # 5-point offline verification engine
│   │   ├── 📄 types.ts                   # TypeScript cryptographic types
│   │   └── 📂 phala/                     # Phala Network TEE integration
│   │       ├── 📄 dstack.ts              # TEE attestation (dstack quotes)
│   │       └── 📄 log.ts                 # RFC 6962 transparency log management
│   │
│   ├── 📂 model/                         # AI Credit Decision Model
│   │   └── 📄 creditModel.ts             # Autonomous credit risk scoring logic
│   │
│   ├── 📂 services/                      # Application services
│   │   └── 📄 evidenceService.ts         # Receipt persistence & retrieval
│   │
│   └── 📂 assets/                        # Static assets
│
├── 📂 tests/                             # Test suite
│   └── 📄 cool.test.ts                   # CooL cryptographic & integration tests (9 tests)
│
├── 📂 docs/                              # Additional documentation
│   └── 📂 screenshots/                   # Application screenshots
│
├── 📂 scripts/                           # Utility scripts
│   └── 📄 generate-keys.ts              # Cryptographic key generation utility
│
└── 📂 public/                            # Public static files
    ├── 📄 favicon.svg                    # Application favicon
    └── 📄 icons.svg                      # Icon sprite sheet

Directory Descriptions

`src/evidence/` — Cryptographic Evidence Core

File	Purpose
`adapter.ts`	CooL service adapter — orchestrates the full evidence generation flow with fail-closed error handling
`client.ts`	`CooLClient` class with `record()` entry point that composes the hash → sign → TEE → log pipeline
`hash.ts`	Salted SHA-256 hashing via `@noble/hashes` to create PII-safe commitments
`sign.ts`	Real Ed25519 (`@noble/curves`) + ML-DSA-65 (`@noble/post-quantum`) hybrid signatures with env key overrides
`verify.ts`	5-point offline verification engine (hash, Ed25519, ML-DSA-65, TEE, Merkle)
`types.ts`	TypeScript interfaces for cryptographic primitives and receipts
`phala/dstack.ts`	TEE attestation with SHA-256 integrity binding to mrEnclave/mrSigner measurements
`phala/log.ts`	RFC 6962 Merkle transparency log with append, inclusion proof generation, and verification

`src/components/` — User Interface

File	Purpose
`Header.tsx`	Application header with branding and tab navigation
`OverviewTab.tsx`	System overview with cryptographic infrastructure status
`SimulatorTab.tsx`	Interactive credit decision simulator with real-time pipeline animation
`EvidenceReceiptTab.tsx`	Receipt inspector showing all cryptographic fields
`AuditDashboardTab.tsx`	Institutional audit ledger
`TamperLabTab.tsx`	Interactive tamper demonstration (modify receipts, see verification fail)
`ReceiptInspectorModal.tsx`	Detailed receipt modal
`DisclaimerBanner.tsx`	Legal disclaimer banner

`src/model/` — AI Decision Model

File	Purpose
`creditModel.ts`	Deterministic credit risk scoring with 3 preset synthetic applicants

`src/services/` — Application Services

File	Purpose
`evidenceService.ts`	Persists cryptographic receipts to browser localStorage with CooL adapter integration

`tests/` — Test Suite

File	Purpose
`cool.test.ts`	9 integration tests covering recording, persistence, verification, tampering, fail-closed handling, PII safety, and env key overrides

🚀 How to Run the Project

Prerequisites

Node.js 20.19+ or 22.12+ (required by Vite 8 — Node 18 will fail the install/build)
npm 9.x or higher
Git

Quick Start

# 1. Clone the repository
git clone https://github.com/aadi-learner77/Reverse-Hackathon.git
cd Reverse-Hackathon

# 2. Install dependencies
npm install

# 3. Create environment file
cp .env.example .env.local   # Linux / macOS
# Copy-Item .env.example .env.local   # Windows PowerShell

# 4. Run development server
npm run dev
# → Server runs on http://localhost:5173

# 5. Run tests
npx vitest run
# → 9/9 tests pass

# 6. Build for production
npm run build

# 7. Preview production build
npm run preview

Environment Variables (`.env.local`)

# CooL SDK Configuration
VITE_COOL_DOMAIN=nbfc.credit_scoring
VITE_ENABLE_TEE_ATTESTATION=true

# AI Model Configuration
VITE_MODEL_ID=CreditRisk-v3
VITE_MODEL_VERSION=3.4.1-prod

# Fail-Closed Security (default: true)
VITE_FAIL_CLOSED_SECURITY=true

# Optional: Custom Cryptographic Keys
# Generate fresh keys: npm run keys:generate
# VITE_ED25519_SECRET_HEX=<64-char hex>
# VITE_MLDSA_SEED_HEX=<64-char hex>

Vercel Deployment

# Deploy to Vercel
npx vercel

# Set environment variables in Vercel dashboard:
# VITE_COOL_DOMAIN=nbfc.credit_scoring
# VITE_ENABLE_TEE_ATTESTATION=true
# VITE_MODEL_ID=CreditRisk-v3
# VITE_MODEL_VERSION=3.4.1-prod

NPM Scripts

Script	Command	Description
`dev`	`npm run dev`	Start Vite dev server with HMR
`build`	`npm run build`	TypeScript compile + production bundle
`test`	`npm test`	Run Vitest test suite (9 tests)
`preview`	`npm run preview`	Preview production build locally
`keys:generate`	`npm run keys:generate`	Generate fresh Ed25519 + ML-DSA-65 keypairs

🏗️ Architecture & Workflow

System Flow Diagram

┌─────────────────────┐
│  Synthetic Applicant│
│   Submission #8842  │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  AI Credit Model    │
│  CreditRisk-v3      │
│  (Autonomous)       │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ Consequential       │
│ Decision: APPROVED  │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────────────────────────┐
│     CooL SDK at Decision Boundary       │
│       (src/evidence/adapter.ts)         │
└──────────┬──────────────────────────────┘
           │
    ┌──────┴──────────────────┬──────────────────┬──────────────┐
    │                         │                  │              │
    ▼                         ▼                  ▼              ▼
┌─────────────┐      ┌─────────────┐    ┌────────────────┐  ┌──────────┐
│   Salted    │      │   Hybrid    │    │  TEE Phala     │  │RFC 6962  │
│   SHA-256   │      │  Signatures │    │  dstack Quote  │  │ Merkle   │
│ PII Commit  │      │  (Ed25519 + │    │  Attestation   │  │   Log    │
│ H(SALT:I||O)│      │ ML-DSA-65)  │    │                │  │ Proof    │
└──────┬──────┘      └──────┬──────┘    └────────┬───────┘  └──────┬───┘
       │                    │                    │                 │
       └────────────────────┼────────────────────┼─────────────────┘
                            │
                            ▼
                  ┌──────────────────────┐
                  │ Cryptographic Evidence│
                  │    Receipt (JSON)     │
                  └──────────┬───────────┘
                            │
           ┌────────────────┼────────────────┐
           │                │                │
           ▼                ▼                ▼
    ┌──────────────┐ ┌────────────────┐ ┌──────────────┐
    │ Storage:     │ │ Dashboard:     │ │ Offline:     │
    │ evService.ts │ │ Evidence Tab   │ │ verify.ts    │
    └──────────────┘ └────────────────┘ └──────────────┘

Mermaid Flowchart

graph TD
    A[Synthetic Applicant #8842] -->|Submit| B[AI Credit Model<br/>CreditRisk-v3]
    B -->|Decision| C{Consequential<br/>Decision?}
    C -->|Yes| D[CooL Service Adapter<br/>src/evidence/adapter.ts]
    D -->|cool.record| E[CooL Core SDK]
    E --> F["Salted SHA-256<br/>PII Commitment<br/>H(SALT : input || output)"]
    E --> G[Ed25519 +<br/>ML-DSA-65<br/>Hybrid Signatures]
    E --> H[Phala dstack<br/>TEE Quote]
    E --> I[RFC 6962<br/>Transparency Log<br/>Merkle Proof]
    F & G & H & I --> J[Cryptographic Evidence<br/>Receipt JSON]
    J --> K[Evidence Service<br/>src/services/evidenceService.ts]
    K --> L[Storage & Ledger]
    J --> M[Offline Verifier<br/>src/evidence/verify.ts]
    M -->|5-Point Check| N{Evidence<br/>Valid?}
    N -->|✓ Yes| O[Audit Lab<br/>Non-Repudiation Proof]
    N -->|✗ No| P[Tamper Lab<br/>Tampering Detected]
    O --> Q[Institutional Audit Ledger]
    P --> R[Compliance Alert]

Key Integration Points

Component	File	Purpose
AI Decision Generation	`src/model/creditModel.ts`	Autonomous credit risk scoring
CooL Record Invocation	`src/evidence/adapter.ts`	Evidence capture at decision boundary
CooL Client	`src/evidence/client.ts`	`record()` entry point composing evidence pipeline
Salted Commitment	`src/evidence/hash.ts`	PII-safe state hashing via `@noble/hashes`
Cryptographic Signing	`src/evidence/sign.ts`	Real Ed25519 + ML-DSA-65 dual signatures
TEE Attestation	`src/evidence/phala/dstack.ts`	SHA-256 integrity binding to enclave measurements
Transparency Log	`src/evidence/phala/log.ts`	RFC 6962 Merkle tree management
Evidence Storage	`src/services/evidenceService.ts`	Receipt persistence & retrieval
Offline Verification	`src/evidence/verify.ts`	5-point cryptographic validation
Evidence Dashboard	`src/components/EvidenceReceiptTab.tsx`	Receipt inspection UI
Tamper Laboratory	`src/components/TamperLabTab.tsx`	Interactive tampering demonstrations

🔧 Important Technical Decisions

1. Salted SHA-256 for PII Commitment ✓

Decision: Use H(SALT : input || output) instead of storing raw applicant data.

Why:

✓ Proves decision was made without exposing raw PII
✓ Auditors can verify commitment without accessing sensitive data
✓ Satisfies GDPR & data minimization principles
✓ Prevents accidental PII leakage in audit logs

Trade-off:

× Cannot reverse-engineer original input from commitment alone
× Audit requires applicant consent to reveal salt for dispute resolution

2. Hybrid Ed25519 + ML-DSA-65 Signatures ✓

Decision: Use dual classical and post-quantum signatures instead of single algorithm.

Why:

✓ Ed25519 is cryptographically mature, widely supported, and efficient
✓ ML-DSA-65 (Dilithium) is FIPS 204 standardized post-quantum algorithm
✓ Protects against future quantum computer attacks (harvest-now-decrypt-later)
✓ Redundancy: Either signature alone is sufficient for verification

Trade-off:

× 2x signature storage overhead
× Slightly longer verification time (negligible in practice)

3. Phala Network dstack for TEE Attestation ✓

Decision: Use Phala dstack hardware quotes instead of browser Web Crypto API alone.

Why:

✓ Hardware-rooted trust: TEE enclave proves execution happened inside SGX/TDX
✓ Tamper-proof: Enclave has cryptographic isolation from OS/hypervisor
✓ Auditable: Third parties can verify attestation without running code
✓ Supports privacy-preserving computation

Trade-off:

× Browser environment simulates TEE (no true SGX/TDX in browser)
× Requires Phala Network integration (additional dependency)

4. RFC 6962 Transparency Logs for Append-Only Audit Trail ✓

Decision: Use Merkle tree inclusion proofs (Certificate Transparency spec) instead of simple sequential logs.

Why:

✓ Append-only: Impossible to modify or delete past entries
✓ Auditability: Third parties can independently verify log consistency
✓ Efficient: Merkle proofs scale logarithmically with log size
✓ Externally auditable: No vendor API required for verification

Trade-off:

× Merkle tree complexity adds architectural overhead
× Log storage grows linearly with decision volume

5. TypeScript + Vite for Frontend ✓

Decision: Use TypeScript + Vite instead of JavaScript + Webpack.

Why:

✓ Type safety: Catch cryptographic configuration errors at compile time
✓ Fast HMR: Vite enables sub-second page refresh during development
✓ Smaller bundle: Tree-shaking removes unused crypto code
✓ Modern: Native ESM support, simpler configuration

Trade-off:

× Smaller ecosystem than React/Vue (though growing)
× Build step required for production

6. Vitest for Cryptographic Unit Tests ✓

Decision: Use Vitest (Vite-native test runner) instead of Jest.

Why:

✓ Fast: Native ESM, no transpilation overhead
✓ Integrated: Shares Vite config, no duplicate setup
✓ Snapshot-friendly: Easy to verify cryptographic output consistency
✓ Debugging: Better source map support

Trade-off:

× Smaller community than Jest (though Vitest adoption growing)

7. Key Management (Demo vs Production) ✓

Decision: The shipped demo defaults to deterministic institutional keypairs for offline reproducibility, backed by configurable environment variable overrides (VITE_ED25519_SECRET_HEX, VITE_MLDSA_SEED_HEX) and a dedicated key generation utility (npm run keys:generate).

Why (Hackathon & Grading Evaluation):

✓ Reproducible Evaluation: Judges and evaluators can clone, run tests, and verify receipts offline immediately without needing to provision cloud secrets or KMS accounts.
✓ Deterministic Verification: Guarantees that pre-recorded audit logs and sample receipts remain verifiable across multiple execution environments.
✓ Zero Unexplained Secrets: Key loading explicitly prioritizes environment variables and flags fallback mode transparently.

Production Architecture Requirements:

Hardware Security Modules (HSM): In production NBFCs and financial institutions, private keys are never committed or held in web application memory. Signing keys must reside within FIPS 140-2 Level 3/4 HSMs (e.g. AWS CloudHSM, Google Cloud KMS, or YubiHSM).
Per-Tenant Key Isolation & Rotation: Separate keyrings per credit product and institutional branch, rotated every 90 days with RFC 3161 cryptographic timestamping.
Enclave-Bound Signing: Private signing keys can be derived and retained entirely inside the Phala TEE enclave boundary, preventing extraction even by cloud infrastructure administrators.

⚙️ Technical Details

Tech Stack

Category	Technology	Version
Language	TypeScript	6.0.2
Framework	React	19.2.8
Build Tool	Vite	8.3.0
Styling	Tailwind CSS	4.3.3
Test Runner	Vitest	5.0.0
Classical Crypto	`@noble/curves` (ed25519 module)	via `@noble/post-quantum`'s dependency tree
Post-Quantum Crypto	`@noble/post-quantum`	0.7.1
Hash Functions	`@noble/hashes`	2.4.0
Icons	Lucide React	1.45.0

Dependency note: sign.ts imports Ed25519 from @noble/curves/ed25519.js. @noble/ed25519 is still listed in package.json but isn't imported anywhere in src/ — either import it directly where it's declared, or drop it from dependencies and declare @noble/curves explicitly instead of relying on it resolving as a transitive dependency.

Cryptographic Primitives

Hash: SHA-256 (FIPS 180-4)
Classical Signature: Ed25519 (RFC 8032)
Post-Quantum Signature: ML-DSA-65 a.k.a. Dilithium (FIPS 204)
Random Generation: crypto.getRandomValues() (Web Crypto API)

Verification Checklist (5 Points)

✓ Commitment hash is correctly computed
✓ Ed25519 signature verifies
✓ ML-DSA-65 signature verifies
✓ TEE quote is authentic and recent
✓ Merkle tree inclusion proof is valid

All 5 checks must pass for evidence to be deemed authentic. Any failure returns EVIDENCE TAMPERED.

🎬 Demo Walkthrough

Follow these steps to experience the full CooL.ledger workflow:

Step	Action	What Happens
1	Open Decision Console tab	Select a synthetic applicant (e.g. #8842)
2	Click RUN AI DECISION	AI model evaluates credit risk and produces APPROVED/REJECTED/MANUAL_REVIEW
3	Observe CooL evidence pipeline	Watch real-time animation: `AI Decision → CooL Boundary → Commitment → Hybrid Signatures → Receipt Sealed`
4	Open Evidence tab	Inspect the full cryptographic receipt — salted PII hashes, dual signatures, TEE attestation, Merkle proof
5	Click VERIFY EVIDENCE	Runs 5-point offline verification → `CRYPTOGRAPHIC EVIDENCE: ✓ VALID`
6	Open Tamper Lab tab	Click TAMPER WITH EVIDENCE to flip the decision or forge a signature
7	Observe tamper detection	`EVIDENCE TAMPERED` — verification fails with specific check failures
8	Click Restore Original	Receipt restored and re-verified → `ORIGINAL: ✓ VERIFIED`

Synthetic Applicant Profiles

Applicant	Income	Credit Score	Debt	Expected Decision
Sarah Chen (#8842)	$145,000	785	$12,000	✅ APPROVED
Marcus Vance (#8843)	$58,000	635	$28,000	⚠️ MANUAL_REVIEW
Elena Rostova (#8844)	$28,000	512	$34,000	❌ REJECTED

📋 Limitations & Future Improvements

Current Limitations

Limitation	Description	Impact	Future Solution
Browser TEE	Browser cannot execute true SGX/TDX enclave code	Crypto ops are real; hardware isolation requires remote deployment	Deploy backend TEE on Phala Network
PII Reversibility	Salted commitments cannot be reverse-engineered	Audit requires applicant consent for dispute resolution	Zero-knowledge proof protocol
Model Fairness	CooL proves record integrity, not model fairness	Auditors must independently validate model behavior	Integrate fairness metrics & bias detection
Single-Threaded	Verification runs synchronously	Suitable for < 1000 receipts/audit session	Worker pool for parallel verification
Public Evidence	No field-level encryption	May expose proprietary model logic	Confidential compute zones

Planned Future Enhancements

Priority	Feature	Target Timeline
High	Backend TEE Enclave (Phala)	Q4 2026
High	Batch Receipt Verification (1M+)	Q4 2026
High	Zero-Knowledge Dispute Resolution	Q1 2027
Medium	Model Fairness Metrics Integration	Q1 2027
Medium	Confidential Evidence Fields	Q2 2027
Medium	GraphQL API for Evidence Query	Q2 2027
Low	IPFS Decentralized Log Storage	Q3 2027
Low	Multi-Signature Threshold Schemes	Q4 2027

📚 References & Resources

RFC 6962: Certificate Transparency (Merkle Tree Logs) — https://tools.ietf.org/html/rfc6962
FIPS 204: ML-DSA Post-Quantum Digital Signature Algorithm — https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.204.pdf
RFC 8032: Elliptic Curve Digital Signature Algorithm (Ed25519) — https://tools.ietf.org/html/rfc8032
Phala Network dstack: TEE Attestation — https://docs.phala.network
Web Crypto API: MDN Documentation — https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API
EU AI Act Article 12: Record-keeping requirements for high-risk AI systems
California AB 316: AI accountability and audit requirements
RBI FREE-AI Assurance: India NBFC AI audit trail mandates

📄 License

MIT License — See LICENSE.md for details.

🤝 Contributing

We welcome contributions! Please:

Fork the repository
Create a feature branch (git checkout -b feature/your-feature)
Commit changes (git commit -m 'Add feature')
Push to branch (git push origin feature/your-feature)
Open a Pull Request

Built for the Reverse Hackathon | Team Beta Onepiece

SHA-256 · Ed25519 · ML-DSA-65 (FIPS 204) · Phala dstack TEE · RFC 6962

Name		Name	Last commit message	Last commit date
docs		docs
public		public
scripts		scripts
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.oxlintrc.json		.oxlintrc.json
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
DEMO.md		DEMO.md
LICENSE.md		LICENSE.md
README.md		README.md
SECURITY.md		SECURITY.md
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vercel.json		vercel.json
vite.config.ts		vite.config.ts

Latest commit

History

Folders and files

Repository files navigation

🛡️ CooL.ledger

AI Decision Evidence & Audit Platform

📑 Table of Contents

🎯 The Problem We're Solving

📸 Visual Tour & Screenshots

1. Core Dashboards & Decision Boundary

🏛️ Case Overview & Trust Infrastructure

⚡ Decision Console — Autonomous AI Underwriting (Approved)

🛑 Decision Console — Adverse Action & Denial Flow (Rejected)

📜 Institutional Audit Docket & Multi-Case Ledger

2. Cryptographic Evidence Exhibits & Proofs

🔐 Exhibit A — Salted PII Commitments & Dual Signatures

🛡️ Exhibit A — Phala dstack TEE Attestation & RFC 6962 Merkle Audit Path

📋 Raw Canonical JSON Exhibit Inspector

3. Forensic Tamper Lab (Attack Simulation & Live Detection)

🟢 Pristine Baseline — Unaltered Evidence (5/5 Checks Passing)

🔴 Attack Vector 1: Decision Flipping Caught

🔴 Attack Vector 2: Signature Forgery Caught

🔴 Attack Vector 3: Transparency Log Tampering Caught

4. Mobile & Responsive Layouts

🏗️ What We Built

Core Components

🔐 How CooL SDK is Architected & Used

1. cool.record() — Cryptographic Evidence Generation

2. createSaltedCommitment() — PII-Safe State Sealing

3. createHybridSignatures() — Dual-Strength Signatures

4. createTEEAttestation() — Hardware-Rooted Trust

5. appendToTransparencyLog() — Append-Only Audit Trail

6. verifyReceipt() — Offline Verification

⭐ Why CooL is Important to Our Solution

📁 Project Structure

Directory Descriptions

src/evidence/ — Cryptographic Evidence Core

src/components/ — User Interface

src/model/ — AI Decision Model

src/services/ — Application Services

tests/ — Test Suite

🚀 How to Run the Project

Prerequisites

Quick Start

Environment Variables (.env.local)

Vercel Deployment

NPM Scripts

🏗️ Architecture & Workflow

System Flow Diagram

Mermaid Flowchart

Key Integration Points

🔧 Important Technical Decisions

1. Salted SHA-256 for PII Commitment ✓

2. Hybrid Ed25519 + ML-DSA-65 Signatures ✓

3. Phala Network dstack for TEE Attestation ✓

4. RFC 6962 Transparency Logs for Append-Only Audit Trail ✓

5. TypeScript + Vite for Frontend ✓

6. Vitest for Cryptographic Unit Tests ✓

7. Key Management (Demo vs Production) ✓

⚙️ Technical Details

Tech Stack

Cryptographic Primitives

Verification Checklist (5 Points)

🎬 Demo Walkthrough

Synthetic Applicant Profiles

📋 Limitations & Future Improvements

Current Limitations

Planned Future Enhancements

📚 References & Resources

📄 License

🤝 Contributing

About

Resources

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

1. `cool.record()` — Cryptographic Evidence Generation

2. `createSaltedCommitment()` — PII-Safe State Sealing

3. `createHybridSignatures()` — Dual-Strength Signatures

4. `createTEEAttestation()` — Hardware-Rooted Trust

5. `appendToTransparencyLog()` — Append-Only Audit Trail

6. `verifyReceipt()` — Offline Verification

`src/evidence/` — Cryptographic Evidence Core

`src/components/` — User Interface

`src/model/` — AI Decision Model

`src/services/` — Application Services

`tests/` — Test Suite

Environment Variables (`.env.local`)