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

JSON Request

{
  "public_key": "24a1b0cd982fecba45...64 hex chars"
}

Successful Response (200 OK)

JSON Response

{
  "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

JSON Request

{
  "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

JSON Response

{
  "status": "ok",
  "next_salt": "78abef90...32 hex chars",
  "next_mutation_step": 2,
  "next_mutation_order_b64": "cGFzc3dvcmQ..."
}

Rejected Response (Silent Rejection)

JSON Response

{
  "status": "ok"
}

⚠️

Important: Heartbeat rejections return 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:

JSON Payload

{
  "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