Skip to content

feat: transform ChittyProof to dual-export library + service #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
chitcommit wants to merge 12 commits into
base: main
Choose a base branch
from
Open

feat: transform ChittyProof to dual-export library + service #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
f081c41
chore: add hono and wrangler dependencies for service layer
chitcommit Mar 2, 2026
5aab849
chore: add wrangler.toml for Cloudflare Worker deployment
chitcommit Mar 2, 2026
ba746bc
feat: add SDK barrel export (src/index.js)
chitcommit Mar 2, 2026
e2f65d9
feat: add shared-secret Bearer token auth middleware
chitcommit Mar 2, 2026
f7e63e3
feat: add /health and /api/v1/status endpoints
chitcommit Mar 2, 2026
964906e
feat: add POST /api/v1/verify endpoint (hash + ECDSA)
chitcommit Mar 2, 2026
36ea9ee
feat: add POST /api/v1/canonicalize endpoint
chitcommit Mar 2, 2026
5f858dc
feat: add POST /api/v1/hash endpoint
chitcommit Mar 2, 2026
4c31a13
feat: add POST /api/v1/validate endpoint (schema validation)
chitcommit Mar 2, 2026
9f996d9
feat: add Hono Worker entry point wiring all routes and auth
chitcommit Mar 2, 2026
2c8e2e9
docs: update compliance triad for dual-export service transformation
chitcommit Mar 2, 2026
ce6d9fd
ci: add GitHub Actions workflow for test automation
chitcommit Mar 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
name: CI

on:
push:
branches: [main]
pull_request:
branches: [main]

jobs:
test:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4

- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'

- name: Install dependencies
run: npm ci

- name: Run tests
run: npm test
21 changes: 18 additions & 3 deletions CHARTER.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ category: infrastructure
- **Tier**: 0 (Trust Anchors)
- **Organization**: CHITTYOS
- **Domain**: proof.chitty.cc
- **Artifact Type**: Library (consumed by services, not deployed standalone)
- **Artifact Type**: Library + Service (dual-export at proof.chitty.cc)

## Mission

Expand All @@ -38,6 +38,7 @@ Provide deterministic, court-grade cryptographic integrity primitives for the Ch
- JWKS key resolution with KV caching (kid-based lookup via ChittyCert)
- Defining the authoritative FACT v2 bundle JSON Schema
- Providing `normalizeBundle` / `canonicalSignedPayload` / `verifyBundle` / `verifyECDSA` exports
- Serving HTTP verification endpoints at `proof.chitty.cc` for ecosystem consumers

### IS NOT Responsible For
- Signing bundles (signing authority lives in the minting service)
Expand All @@ -52,12 +53,16 @@ Provide deterministic, court-grade cryptographic integrity primitives for the Ch
| Type | Service | Purpose |
|------|---------|---------|
| Upstream | ChittyCert | JWKS endpoint for public key resolution |
| Upstream | ChittyAuth | Shared-secret Bearer token validation |
| Runtime | Web Crypto API | SHA-256 digest, ECDSA verify, key import |
| Runtime | Hono | HTTP framework for Cloudflare Workers |
| Optional | Cloudflare KV | JWKS key caching (`PROOF_KEY_CACHE` binding) |
| Downstream | ChittyTrack | Automatic log/trace aggregation (tail_consumers) |
| Downstream | ChittyBeacon | Health monitoring (probes /health) |

## API Contract

ChittyProof is a library — it exports functions, not HTTP endpoints.
ChittyProof is both a library (SDK exports) and a deployed service (HTTP endpoints at proof.chitty.cc).

### Exports (`lib/chittyproof-v2-canonical.js`)
| Export | Signature | Purpose |
Expand All @@ -80,6 +85,16 @@ ChittyProof is a library — it exports functions, not HTTP endpoints.
| `getPublicKeyByKid` | `(kid, env, opts?) => Promise<CryptoKey>` | KV-cached JWKS key resolution |
| `verifyECDSA` | `(bundle, env, opts?) => Promise<{ok, reason, ...}>` | Full ECDSA signature verification |

### HTTP Endpoints (proof.chitty.cc)
| Method | Path | Auth | Purpose |
|--------|------|------|---------|
| GET | `/health` | None | Health probe |
| GET | `/api/v1/status` | None | Service metadata |
| POST | `/api/v1/verify` | Bearer | Hash integrity + ECDSA verification |
| POST | `/api/v1/canonicalize` | Bearer | Deterministic JSON canonicalization |
| POST | `/api/v1/hash` | Bearer | SHA-256 of canonical signed payload |
| POST | `/api/v1/validate` | Bearer | FACT v2 bundle schema validation |

### Schema
- `etc/authority/schema/chittyproof-v2-fact-bundle.schema.json`
- `$id`: `chittycanon://schemas/chittyproof/v2/fact-bundle`
Expand All @@ -98,7 +113,7 @@ ChittyProof is a library — it exports functions, not HTTP endpoints.
- [x] CHARTER.md present
- [x] CHITTY.md present
- [x] CLAUDE.md present
- [x] Tests passing (10/10 vitest)
- [x] Tests passing (32/32 vitest)
- [x] JSON Schema with canonical $id
- [x] Canonical frontmatter with tech domain
- [x] Package exports map defined
Expand Down
30 changes: 25 additions & 5 deletions CHITTY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,23 +21,38 @@ category: infrastructure

## What It Does

Cryptographic integrity library for FACT v2 bundles. Provides deterministic JSON canonicalization, SHA-256 hashing, and ECDSA P-256 signature verification — the foundation that makes every fact in the ChittyOS ecosystem provably tamper-evident.
Cryptographic integrity library and service for FACT v2 bundles. Provides deterministic JSON canonicalization, SHA-256 hashing, and ECDSA P-256 signature verification — the foundation that makes every fact in the ChittyOS ecosystem provably tamper-evident. Available both as a library (SDK import) and as HTTP endpoints at `proof.chitty.cc`.

## Architecture

Pure JavaScript ESM library consumed by ChittyOS services. Runs anywhere the Web Crypto API is available (Cloudflare Workers, Node 20+, Deno, browsers).
Dual-export: pure JavaScript ESM library (SDK consumers import directly) + Hono Worker deployed at `proof.chitty.cc` (HTTP consumers). Library core runs anywhere the Web Crypto API is available (Workers, Node 20+, Deno, browsers).

### Stack
- **Language**: JavaScript (ESM)
- **HTTP**: Hono on Cloudflare Workers
- **Crypto**: Web Crypto API (SHA-256, ECDSA P-256)
- **Auth**: Shared-secret Bearer token (`CHITTY_AUTH_SERVICE_TOKEN`)
- **Testing**: Vitest
- **Key Authority**: ChittyCert JWKS (`cert.chitty.cc/.well-known/jwks.json`)

### Key Components
- `src/index.js` — SDK barrel export (library consumers)
- `src/worker.js` — Hono Worker entry point (HTTP consumers)
- `src/lib/chittyproof-v2-canonical.js` — Canonicalization, normalization, hashing
- `src/lib/chittyproof-verify-ecdsa.js` — ECDSA P-256 verification, JWKS resolution
- `src/routes/` — HTTP route handlers (health, verify, canonicalize, hash, validate)
- `src/middleware/auth.js` — Shared-secret Bearer token middleware
- `etc/authority/schema/chittyproof-v2-fact-bundle.schema.json` — FACT v2 bundle schema
- `tests/helpers/fact-proof-bundle.js` — Test fixture factory

### Endpoints
| Method | Path | Auth | Purpose |
|--------|------|------|---------|
| GET | `/health` | None | Health probe |
| GET | `/api/v1/status` | None | Service metadata |
| POST | `/api/v1/verify` | Bearer | Hash + ECDSA verification |
| POST | `/api/v1/canonicalize` | Bearer | Deterministic JSON |
| POST | `/api/v1/hash` | Bearer | SHA-256 of canonical payload |
| POST | `/api/v1/validate` | Bearer | FACT v2 schema validation |
Comment on lines +47 to +55
Copy link

@coderabbitai coderabbitai bot Mar 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Fix markdownlint MD058 around tables.

Line 48 and Line 75 start tables without required surrounding blank lines, which will keep lint noisy.

Suggested markdown fix 
 ### Endpoints
+
 | Method | Path | Auth | Purpose |
 |--------|------|------|---------|
 | GET | `/health` | None | Health probe |
 | GET | `/api/v1/status` | None | Service metadata |
 | POST | `/api/v1/verify` | Bearer | Hash + ECDSA verification |
 | POST | `/api/v1/canonicalize` | Bearer | Deterministic JSON |
 | POST | `/api/v1/hash` | Bearer | SHA-256 of canonical payload |
 | POST | `/api/v1/validate` | Bearer | FACT v2 schema validation |
+
 ...
 ### Dependencies
+
 | Service | Purpose |
 |---------|---------|
 | ChittyCert | JWKS public key hosting for signature verification |
 | ChittyAuth | Shared-secret Bearer token validation |
 | ChittyTrack | Log/trace aggregation (tail_consumers) |
 | ChittyBeacon | Health monitoring (probes /health) |
+

Also applies to: 74-81

🧰 Tools
🪛 markdownlint-cli2 (0.21.0)

[warning] 48-48: Tables should be surrounded by blank lines

(MD058, blanks-around-tables)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@CHITTY.md` around lines 47 - 55, The table starting with the header row "|
Method | Path | Auth | Purpose |" under the "### Endpoints" section (and the
other table around the second occurrence noted) needs surrounding blank lines to
satisfy markdownlint MD058; insert a single blank line immediately before the
table and a single blank line immediately after the table (so there is an empty
line between the preceding heading/paragraph and the table, and between the
table and the following content) for both tables to fix the lint warnings.


### Design Principles
- **Deterministic**: Same input always produces the same canonical JSON and hash, across all runtimes
Expand All @@ -53,13 +68,16 @@ Pure JavaScript ESM library consumed by ChittyOS services. Runs anywhere the Web
- **Last Certified**: 2026-03-01

### ChittyDNA
- **Lineage**: root (foundational library)
- **Role**: Integrity primitive — consumed by any service that mints, seals, or verifies FACT bundles
- **Lineage**: root (foundational library + service)
- **Role**: Integrity primitive — consumed by any service that mints, seals, or verifies FACT bundles (SDK import or HTTP call)

### Dependencies
| Service | Purpose |
|---------|---------|
| ChittyCert | JWKS public key hosting for signature verification |
| ChittyAuth | Shared-secret Bearer token validation |
| ChittyTrack | Log/trace aggregation (tail_consumers) |
| ChittyBeacon | Health monitoring (probes /health) |

### Consumers
| Service | Usage |
Expand All @@ -68,6 +86,8 @@ Pure JavaScript ESM library consumed by ChittyOS services. Runs anywhere the Web
| ChittyEvidence | Evidence integrity checks |
| ChittyLedger | Seal verification at ledger write |
| ChittyCases | Bundle verification for case presentation |
| ChittySign | Canonical hash for signing counterpart |
| DocuMint | Bundle verification (library or HTTP) |

### Exports
| Module | Key Functions |
Expand Down
38 changes: 32 additions & 6 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# CLAUDE.md — ChittyProof

Cryptographic integrity library for FACT v2 bundle canonicalization, hashing, and ECDSA P-256 signature verification.
Cryptographic integrity library and service for FACT v2 bundle canonicalization, hashing, and ECDSA P-256 signature verification.

**Canonical URI**: `chittycanon://core/services/chittyproof`
**Tier**: 0 (Trust Anchors)
Expand All @@ -10,16 +10,29 @@ Cryptographic integrity library for FACT v2 bundle canonicalization, hashing, an

```bash
npm test # Run vitest (all tests)
npx vitest run # Same, explicit
npm run dev # Start local dev server (wrangler dev)
npm run deploy # Deploy to Cloudflare Workers
npx vitest run # Same as npm test, explicit
npx vitest watch # Watch mode
```

## Project Structure

```
src/lib/
chittyproof-v2-canonical.js # Canonicalization, normalization, SHA-256 hashing
chittyproof-verify-ecdsa.js # ECDSA P-256 verification, JWKS key resolution
src/
index.js # SDK barrel export (library consumers)
worker.js # Hono Worker entry point (HTTP consumers)
lib/
chittyproof-v2-canonical.js # Canonicalization, normalization, SHA-256 hashing
chittyproof-verify-ecdsa.js # ECDSA P-256 verification, JWKS key resolution
routes/
health.js # GET /health, GET /api/v1/status
verify.js # POST /api/v1/verify
canonicalize.js # POST /api/v1/canonicalize
hash.js # POST /api/v1/hash
validate.js # POST /api/v1/validate
middleware/
auth.js # Shared-secret Bearer token

etc/authority/schema/
chittyproof-v2-fact-bundle.schema.json # FACT v2 bundle JSON Schema
Expand All @@ -28,11 +41,20 @@ tests/
helpers/fact-proof-bundle.js # Test fixture factory (makeFactProofBundle)
lib/chittyproof-v2-canonical.test.js # Canonicalization + hash tests
lib/chittyproof-verify-ecdsa.test.js # ECDSA verification tests
middleware/auth.test.js # Auth middleware tests
routes/ # Route handler tests
worker.test.js # Integration tests
```

## Architecture

This is a **library**, not a deployable service. It exports pure functions that run on any Web Crypto API runtime (Workers, Node 20+, Deno, browsers).
This is a **dual-export** project: a library (for in-process consumers) and a deployed service at `proof.chitty.cc` (for HTTP consumers).

- `src/index.js` — SDK barrel export (library consumers import from here)
- `src/worker.js` — Hono Worker entry point (Cloudflare Workers deployment)
- `src/lib/` — Pure function core (unchanged from library-only days)
- `src/routes/` — HTTP route handlers wrapping the library functions
- `src/middleware/` — Auth middleware (shared-secret Bearer token)

### Canonicalization Pipeline
1. `normalizeBundle` — round score/pillar fields to deterministic precision, compute `score_100`
Expand All @@ -48,7 +70,9 @@ This is a **library**, not a deployable service. It exports pure functions that
4. `crypto.subtle.verify` ECDSA P-256 over the hash bytes

### Key Dependencies
- **Hono** — HTTP framework for Cloudflare Workers
- **ChittyCert** (`cert.chitty.cc/.well-known/jwks.json`) — public key authority
- **ChittyAuth** — shared-secret Bearer token (`CHITTY_AUTH_SERVICE_TOKEN`)
- **KV binding** (`PROOF_KEY_CACHE`) — optional JWKS cache for Workers consumers

## Patterns
Expand All @@ -58,3 +82,5 @@ This is a **library**, not a deployable service. It exports pure functions that
- Non-finite numbers throw — no `NaN` or `Infinity` in canonical payloads
- Base64url encoding/decoding handles padding normalization internally
- `structuredClone` is used for immutable normalization (no mutation of input bundles)
- Routes are thin wrappers around library functions — no business logic in route handlers
- Auth middleware uses simple string comparison against `env.CHITTY_AUTH_SERVICE_TOKEN`
Comment on lines +85 to +86
Copy link

@coderabbitai coderabbitai bot Mar 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# First, check if the file exists
if [ -f "src/middleware/auth.js" ]; then
  echo "=== Inspecting auth middleware implementation ==="
  cat -n src/middleware/auth.js
else
  echo "File src/middleware/auth.js not found. Searching for auth-related files..."
  fd auth . -type f 2>/dev/null | head -20
fi

Repository: chittyapps/chittyproof

Length of output: 932

🏁 Script executed:

#!/bin/bash
# Search for token comparison patterns
echo "=== Searching for token comparison patterns ==="
rg -n 'CHITTY_AUTH_SERVICE_TOKEN|token.*===|Bearer|crypto' --type-list | head -5
rg -n 'CHITTY_AUTH_SERVICE_TOKEN|token.*===|Bearer' -i 2>/dev/null || echo "No matches found"

Repository: chittyapps/chittyproof

Length of output: 9552

🏁 Script executed:

#!/bin/bash
# Check CLAUDE.md to confirm documentation
echo "=== Checking CLAUDE.md lines 85-86 ==="
sed -n '80,90p' CLAUDE.md

Repository: chittyapps/chittyproof

Length of output: 677

Use constant-time comparison for bearer-token validation.

The middleware at line 19 of src/middleware/auth.js uses token !== expected for secret validation. This simple string comparison is vulnerable to timing side-channel attacks that could leak information about token validity or length. Use crypto.timingSafeEqual() instead:

if (!token || !crypto.timingSafeEqual(Buffer.from(token), Buffer.from(expected))) {
  return c.json({ error: "unauthorized" }, 401);
}
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@CLAUDE.md` around lines 85 - 86, The auth middleware's current token check
uses plain equality (token !== expected) which is vulnerable to timing attacks;
update the middleware (in src/middleware/auth.js, the auth middleware function
handling variables token and expected) to perform a constant-time comparison
using crypto.timingSafeEqual: import Node's crypto, convert token and expected
to Buffers, ensure they are the same length (if not, compare against a dummy
buffer of the same length to avoid short-circuit timing differences) and replace
the simple equality check with the timingSafeEqual-based check so unauthorized
responses still return the same way when the comparison fails.

Loading
Loading