nx9-chronoseal-rs/docs/PROTOCOL.md

ChronoSeal Protocol Specification (PROTOCOL)

This document defines the formal wire protocol, state transitions, cryptographic primitives, and execution invariants of the ChronoSeal browser attestation system.

---

1. Sequence Flow & Handshake

ChronoSeal operates as a stateful, sequential challenge-response chain over HTTP/REST.

Client (JS/WASM)                                         Server (chronoseald)
      |                                                        |
      | 1. POST /init { public_key: String } -----------------> |
      |                                                        | (Generates VM Opcodes)
      |                                                        | (Computes initial hash chain head H_0)
      |                                                        | (Saves initial session record)
      | <--- 200 OK { InitResponse } --------------------------|
      |                                                        |
      | [Client executes VM program & prepares gene preview]   |
      |                                                        |
      | 2. POST /hb { HeartbeatRequest } ---------------------> |
      |                                                        | (Loads session & executes CAS check)
      |                                                        | (Verifies Ed25519 signature)
      |                                                        | (Validates VM stack-state parity)
      |                                                        | (Computes expected gene mutation)
      |                                                        | (Validates hash chain continuity H_N == expected)
      |                                                        | (Rotates salt & issues next mutation order)
      | <--- 200 OK { HeartbeatResponse } ---------------------| (Saves updated session record)
      |                                                        |

---

2. Cryptographic Transition Mechanics

A. Handshake Phase (/init)

The client registers a 32-byte Ed25519 verifying key represented as a hex string. The server:

1. Generates a 32-byte session ID (ID) and a 16-byte initial salt (S_0).
2. Computes the initial hash chain head: H_0 = \text{Blake3}(ID \parallel PK_{\text{client}} \parallel S_0)
3. Generates a random VM program of size 8..=16 bytes.
4. Creates the initial mutation order program M_1.
5. Persists the session record in the database.

---

B. Heartbeat progression (/hb)

For each heartbeat step n \ge 1: The client submits:

• prev_hash: H_{n-1} (hex encoded).
• timestamp: T_n (milliseconds).
• entropy_data: Mouse movement arrays.
• stack_state: The VM final stack and instruction pointer ip after execution.
• gene_commitment: Hex-encoded commitment of the mutated gene state.
• signature: Ed25519 signature of the canonical alphabetical JSON payload.

The server:

1. Loads the session record from storage, enforcing optimistic locking (CAS check) to confirm the database last_hash matches H_{n-1}.
2. Validates the Ed25519 signature against the canonical alphabetical serialization.
3. Re-executes the session's VM opcodes and asserts the client's stack_state matches the output.
4. Applies the mutation order M_n to the stored gene state and calculates the expected commitment: C_n = \text{Blake3}(\text{CandidateGene} \parallel ID \parallel n) Asserts the client's gene_commitment matches.
5. Validates that |T_{\text{server}} - T_n| \le \text{max\_drift}.
6. Advances the hash chain: H_n = \text{Blake3}(H_{n-1} \parallel T_n \parallel \text{Blake3}(E_n) \parallel \text{Blake3}(S_n) \parallel S_{n-1})
7. Rotates the salt to S_n and issues the next mutation order M_{n+1}.

---

3. VM Instruction Specification

The client VM executes instructions sequentially. The instruction set consists of:

• 0x00: Pushes the next 4 bytes in the instruction stream onto the stack as a u32 value (little-endian).
• 0x01..=0x07: Binary operators. Requires at least 2 elements on the stack:
  • 0x01: Wrapping Add (a.wrapping_add(b))
  • 0x02: Wrapping Sub (a.wrapping_sub(b))
  • 0x03: Wrapping Mul (a.wrapping_mul(b))
  • 0x04: XOR (a ^ b)
  • 0x05: AND (a & b)
  • 0x06: OR (a | b)
  • 0x07: Rotate Left (a.rotate_left(b % 32))
• 0x08: Unary Bitwise Not (!a). Requires at least 1 element on the stack.
• 0x09: Hash Stack. Hashes all stack elements using BLAKE3 and reduces it to a single u32 value, clearing the stack and pushing the hash.
• Any other opcode: Terminates VM execution immediately.

v1.0.2 Protocol Hardening

• Fingerprint aspect ratio validation
• Device pixel ratio validation
• Hardware concurrency validation (1..=256)
• Entropy event cap (500 events)
• IP-based rate limiting
• Silent rejection preserved for protocol failures