ChronoSeal API Reference
+ChronoSeal exposes a lightweight HTTP API for session handshakes, heartbeat attestation verification, metrics, and statistics.
+ ++ +
Endpoint Summary
+| Method | +Path | +Core Purpose | +Content Type | +
|---|---|---|---|
POST |
+ /init |
+ Create a new attestation session | +application/json |
+
POST |
+ /hb |
+ Submit and verify a signed heartbeat | +application/json |
+
GET |
+ /health |
+ Check daemon operational health | +application/json |
+
GET |
+ /stats |
+ Get runtime database statistics | +application/json |
+
GET |
+ /metrics |
+ Prometheus-compatible scraping metrics | +text/plain |
+
GET |
+ / |
+ Serve static integration files | +HTML / JS / WASM | +
Data Encoding Formats
+-
+
- Keys & Signatures: Ed25519 public keys represent 64 hex characters (32 bytes). Signatures represent 128 hex characters (64 bytes). +
- Hashes: Blake3 digests represent 64 hex characters (32 bytes). +
- Salts: Random seeds represented as 32 hex characters (16 bytes). +
- Timestamps: Integer epoch milliseconds. +
- Programs: Base64-encoded strings (representing VM opcodes or mutation steps). +
POST /init
+ Registers the browser public key and initiates the session tracker.
+ +Request Payload
+{
+ "public_key": "24a1b0cd982fecba45...64 hex chars"
+}
+ Successful Response (200 OK)
+{
+ "session_id": "8902abc345def678...64 hex chars",
+ "salt": "f51278ba...32 hex chars",
+ "opcodes_b64": "AQAFAwEG...",
+ "initial_hash": "23ab89c0...64 hex chars",
+ "expires_at": 1782390482000,
+ "heartbeat_min_interval_ms": 12000,
+ "heartbeat_max_interval_ms": 25000,
+ "gene_size": 512,
+ "mutation_step": 1,
+ "mutation_order_b64": "YWJjZGVm..."
+}
+ POST /hb
+ Verifies client compliance for the current step and rolls over session parameters.
+ +Request Payload
+{
+ "session_id": "8902abc345def678...64 hex chars",
+ "prev_hash": "23ab89c0...64 hex chars",
+ "timestamp": 1782390494000,
+ "entropy_data": {
+ "events": [
+ { "x": 124.5, "y": 308.2, "t": 120.4 }
+ ]
+ },
+ "stack_state": {
+ "stack": [108429, 3902],
+ "ip": 12
+ },
+ "fingerprint": {
+ "aspectRatio": "1.7777777778",
+ "devicePixelRatio": "2",
+ "hardwareConcurrency": 8
+ },
+ "mutation_step": 1,
+ "gene_commitment": "56ab12cd...64 hex chars",
+ "signature": "ab0921cd56ef...128 hex chars"
+}
+ Accepted Response
+{
+ "status": "ok",
+ "next_salt": "78abef90...32 hex chars",
+ "next_mutation_step": 2,
+ "next_mutation_order_b64": "cGFzc3dvcmQ..."
+}
+ Rejected Response (Silent Rejection)
+{
+ "status": "ok"
+}
+ 200 OK with status: ok but OMIT next-state fields. Clients must check for the presence of next_salt before advancing local states.
+ Canonical Signing Payload
+The Ed25519 signature covers a canonical JSON string. The server orders the keys alphabetically using camelCase notation. Ensure serialization matches this format precisely:
+{
+ "entropyData": { "events": [{ "t": 120.4, "x": 124.5, "y": 308.2 }] },
+ "fingerprint": { "aspectRatio": "1.7777777778", "devicePixelRatio": "2", "hardwareConcurrency": 8 },
+ "geneCommitment": "56ab12cd...",
+ "mutationStep": 1,
+ "prevHash": "23ab89c0...",
+ "sessionId": "8902abc3...",
+ "stackState": { "ip": 12, "stack": [108429, 3902] },
+ "timestamp": 1782390494000
+}
+ Operational Probes
+ +GET /health
+ {
+ "status": "healthy"
+}
+ GET /stats
+ {
+ "sessions": 412,
+ "expired_sessions": 3,
+ "max_chain_length": 84
+}
+ GET /metrics
+ # HELP chronoseal_sessions Active ChronoSeal sessions
+# TYPE chronoseal_sessions gauge
+chronoseal_sessions 412
+# HELP chronoseal_expired_sessions Expired sessions not yet removed
+# TYPE chronoseal_expired_sessions gauge
+chronoseal_expired_sessions 3
+# HELP chronoseal_max_chain_length Maximum heartbeat chain length
+# TYPE chronoseal_max_chain_length gauge
+chronoseal_max_chain_length 84
+