stack/docs/architecture/lease-broker-protocol.md

Authenticated external lease broker protocol

The compaction-refresh lease broker is a Linux-only, newline-framed JSON protocol over a Unix stream socket. It is runtime-neutral; M1 consumers are limited to Claude and Pi. This is an internal process boundary, not an HTTP API, so it is intentionally absent from OpenAPI.

The broker, never the caller, obtains (pid, uid, gid) from kernel SO_PEERCRED. It correlates the PID with /proc/<pid>/stat field 22 (starttime) and mints session_id on register_anchor. Presence of session_id in that request is refused even when its value is null or empty. Later requests must originate from the anchor or a descendant. The broker walks parent PIDs to the (pid,starttime) anchor and then rereads every walked PID's starttime before accepting the chain.

Request and response boundary

Each connection carries exactly one UTF-8 JSON object followed by one newline, capped at 64 KiB. The protocol deliberately uses EOF to prove that there is exactly one frame: immediately after writing the newline, the client MUST half-close its write side with shutdown(SHUT_WR) (or Node socket.end()) before awaiting the response. A client that writes a newline but leaves its write side open receives no successful response; the broker's one-second connection deadline fails closed. Malformed, unterminated, multiple (including a delayed second frame), or oversized frames fail closed. Responses are one JSON object and one newline. Success has {"ok":true,...}; refusal has {"ok":false,"code":"TYPED_CODE"}. Requests are:

• register_anchor: action, non-negative runtime_generation; no session_id field.
• authenticate: action, broker-minted session_id, non-negative runtime_generation.
• mint_token: authenticated identity plus binding containing exactly compaction_epoch, request_epoch, h_source, h_payload, and schema_version.
• consume_token: authenticated identity plus token.

A higher generation for the same anchor atomically replaces the stored incarnation and consumes all prior tokens for that session. A lower generation is stale. Tokens are 256-bit values from the operating-system cryptographic RNG and are single use. Their persisted binding is the WI-1 substrate for later receipt work; WI-1 does not implement receipts, promotion, hooks, payload builders, mutator gates, or recovery.

State replacement uses a mode-0600 temporary file, fsync, atomic rename, and parent-directory fsync. Existing state is opened without following symlinks, must be a bounded regular file at mode 0600, and is fully schema- and invariant-validated before use. Session identity is uniquely keyed by (anchor_pid,anchor_starttime); duplicate logical sessions for one anchor refuse startup. State integrity or mode failures refuse startup. The daemon does not log session IDs or tokens.