Getting Started

Setup guide for the buyer. From clone to first notarized certificate in under 15 minutes.

Prerequisites

Clone and Build

# Clone the repository
git clone https://github.com/SuarezPM/trai
cd trai

# Build all Rust crates (release mode)
cargo build --workspace --release

# Build the Python wheel (heavy SDK)
cd sdk/python && maturin develop --release

# Build the TypeScript SDK
cd sdk/typescript && pnpm install && pnpm run build

# Build the Go SDK
cd sdk/go && go build ./...

Or use the Makefile shortcut

make build    # Rust workspace + Python wheel + TypeScript SDK

Run the Test Suite

# Rust tests (release) -- 1,375 pass, 0 fail
cargo test --workspace --release

# Python tests -- 1,400 pass, 8 skipped, 4 xfailed
cd sdk/python && pytest -m 'not integration' tests/

# TypeScript SDK
cd sdk/typescript && pnpm test

# Go SDK
cd sdk/go && go test ./...

Lint Gates

# Python lint -- zero errors
ruff check

# Rust lint -- zero warnings
cargo clippy --workspace --all-targets -- -D warnings

Control Plane Setup

The control plane is a Python 3.11+ FastAPI application. In dev mode, it uses ephemeral Ed25519 keys, mock TSA, and mock SCITT -- clearly labeled as "Toy Mode" with no cryptographic validity.

# Start the control plane in dev mode
cd services/control_plane

# Set dev mode
export TL_DEV_MODE=1

# Start with uvicorn
PYTHONPATH=. uv run --with pydantic --with sqlalchemy \
    --with fastapi --with uvicorn --with httpx \
    uvicorn app.main:app --reload --port 8000

Or use the Makefile shortcut

make demo    # Boot control plane, generate + verify certificate

First Notarization

The end-to-end acceptance gate boots a uvicorn subprocess, sends a notarization request, and verifies the response:

# Run the acceptance gate script
bash services/control_plane/scripts/run_first_real_cert.sh

This script:

1. Boots a uvicorn subprocess with dev defaults
2. POSTs to /v1/notarize with a test disclosure
3. Asserts that GET /v1/verify/{cert_id} returns the expected COSE protected header
4. Downloads the JSON packet and optionally the PDF
5. Fails non-zero with full stack trace on any HTTP error

What Happens (The Crypto Pipeline)

When you submit a disclosure to POST /v1/notarize, here is what happens under the hood, explained in plain terms:

1. Content hashing -- The disclosure content is hashed with BLAKE3 to produce a content-addressable fingerprint.
2. Signing -- The content hash is signed with Ed25519 (or ML-DSA-65 hybrid in production) inside a COSE_Sign1 envelope per RFC 9052.
3. Timestamping -- An RFC 3161 timestamp request is sent to a Time-Stamp Authority (Actalis Italia in production, FreeTSA in dev). The TSA signs a token proving the content existed at that point in time.
4. SCITT anchoring -- The signed envelope is anchored in a SCITT transparency log with an RFC 9162 Merkle inclusion proof. This makes the evidence tamper-evident and publicly verifiable.
5. Hash chain -- The event is appended to a BLAKE3 hash chain scoped to the tenant's organization ID, ensuring sequential ordering.
6. PDF rendering -- A multi-section A4 PDF certificate is generated with the cryptographic details, an embedded QR code for quick verification, and a 3-tier disclosure (L1 summary, L2 raw CWT, L3 verification steps).
7. Receipt -- The Evidence Packet + Receipt are persisted to PostgreSQL and returned to the caller. The certificate can be verified at any time via GET /v1/verify/{cert_id}.