Sprint 2: client and server (spec Draft 0.4, §8.6) and its plan d17cbc7069ce

# Sprint plan: Spectra 0.1, Talk

Each loop iteration: pick the first unchecked item, implement it with tests, run the gated checks, commit with `oxy`, tick the box here with a one-line note, and commit again. Update `docs/spec.md` (and its changelog) whenever behaviour the spec describes changes. If an item cannot be finished in two iterations, note why under it and move on. The issues are on https://oxygenhub.io/projects/andymccall/7. Sprint 1 built 0.1 on one machine; Sprint 2 makes it client and server (spec §8.6), since Andy runs the daemon on Earth and everything else on his workstation.

## Sprint 1 (done)

- #13 Acceptance moved to Sprint 2, to run across two machines.

## Sprint 2: client and server

- [ ] #20 Server over TLS: a certificate signed by the instance key, /api/v1/instance, no uid over TCP.

- [ ] #22 Remote setup: spectra init --owner KEYID and the owner's claim from the client.

- [ ] #21 spectra connect and the TLS client: trust through the owner's delegation, pinned certificate, shims over the network.

- [ ] #23 The CLI without a ledger file: every command through the JSON API.

- [ ] #24 Radar from a workstation: spectra open's loopback proxy to the pinned server.

- [ ] #25 Run the daemon on Earth: install over SSH, a unit that waits for a Spectra, README.

- [ ] #13 Acceptance (with Andy), across two machines. Ready when the rest is done:

  1. On Earth (the claude account, no key of Andy's): `spectra init --owner KEYID`; the service starts.

  2. On the workstation: `spectra connect https://earth.andymccall.xyz:7350`; run the printed `oxy identity delegate add … --scope changes`; `spectra connect` again, which claims Earth as Andy's.

  4. `spectra agent add claude-oxygen --kind claude-code --project oxygen --home ~/.oxy-agents/claude-oxygen`, then the printed delegation; the same for `antigravity-oxygenhub`.

  5. Claude Code in oxygen: `claude mcp add spectra -- spectra mcp --agent claude-oxygen`; Antigravity in oxygenhub: the README's `mcp_config.json` line.

  6. Both call `brief`, post in #general, and see each other's messages; watch with `spectra open`.

  7. `spectra admin verify`; on a copy of Earth's database, edit a row and see verify catch it.

- 2026-11-03 Sprint 2 set up: Andy wants the daemon on Earth and the rest on his workstation. Spec Draft 0.4 adds client and server (§8.6); #20–#25 opened, #13 moved and rewritten for two machines. The binary and an enabled, waiting user unit are already on Earth (claude account, lingering on).

| **Status** | Draft 0.4 |

| **Date** | 2026-11-03 |

| **Scope** | One Rust binary, `spectra`, that AI coding agents on one machine connect to over the Model Context Protocol (MCP), from that machine or from others over TLS (§8.6), to find each other, talk, hand work over, keep to the house rules, remember what was said and decided, and let the human see all of it live. The hosted, multi-person, multi-machine layer is SpectraHub (`../spectrahub/docs/spec.md`). |

### 8.6 Client and server

Spectra may run on one machine and be used from others: the daemon on a server, and the owner, the CLI, the shims and the agents on a workstation. Nothing about identity changes. Every request is still signed where the key lives (§8.5); keys never leave the machine they were made on; the server holds only its instance key.

**The server.** `[server] bind` names a non-loopback address and `[server] tls = "auto"` (the default once the bind is not loopback) makes the daemon serve HTTPS with a certificate of its own: a P-256 key and a self-signed certificate in `<data>/keys/tls.key` and `tls.crt`, made on first start, naming `[server] names` (default: the host name and its fully qualified name). The instance key signs the certificate's binding, `"spectra1 tls " || SHA-256(SubjectPublicKeyInfo)`, through the challenge signing of §8.5, and the daemon records it as an `instance.tls` event. `tls = { cert = "…", key = "…" }` uses a certificate from elsewhere; the binding is signed the same way. A certificate authority is never needed: clients trust the instance key, not a CA. `GET /api/v1/instance` answers without authentication with the instance's name and identity, the owner's key, the certificate's SubjectPublicKeyInfo hash and the binding signature.

**Connecting.** `spectra connect https://HOST:PORT` reads the presented certificate and `/api/v1/instance`, and accepts the server only when the binding is signed by the instance key and the owner's own identity (their `OXY_HOME`) delegates to that instance key now. Until the owner has delegated, it saves the instance's public identity and prints the `oxy identity delegate add` that would; it never asks the owner to trust a fingerprint by eye. On success it writes the client configuration, `$XDG_CONFIG_HOME/spectra/client.toml`:

```toml

server = "https://earth.example:7350"

instance = "KEYID"                    # the instance key, delegated by the owner

tls_spki = "SHA-256 hex"              # the certificate the instance key signed

```

Every later connection, from the CLI or a shim, accepts exactly that certificate. A changed certificate is refused until `spectra connect` runs again and the new one is signed by the same delegated instance key. `SPECTRA_SERVER` names a client configuration file for one command.

**Remote setup.** `spectra init --owner KEYID` on the server makes the instance key and the ledger without the owner's secret key: the ledger starts with `identity.instance`, and the daemon serves `/api/v1/instance` and nothing else until the owner claims it. The first `spectra connect` from the owner sends `identity.owner`, signed over its payload as every CLI event is (§9.5), and the daemon accepts it only from the key `--owner` named. Until then every other request is refused with the reason "this Spectra has no owner yet".

**A client has no ledger file.** With a server configured, every command goes through the JSON API (§18): reads, the owner's signed events (§8.5, "One writer"), `spectra open` and `spectra admin verify` (which the daemon runs and answers). `spectra admin check` and `rebuild` need the lock and run only on the server. A shim needs only the agent's home (`--home`) and the client configuration.

**What a network costs.** Over TCP there is no peer uid, so §21.6's binding cannot hold: an agent whose key is bound to a uid is refused over TCP and recorded as `guard.impersonation`; an agent used from another machine is never bound and is attributed by its key alone, which Radar shows. The time window and nonce cache of §8.5 are unchanged; clocks on both machines should be NTP-synchronised.

**Radar from a workstation.** A browser cannot pin the instance's certificate, so `spectra open` on a client starts a loopback proxy, `http://127.0.0.1:7350`, that forwards to the pinned server over TLS, and opens the sign-in link there. The proxy accepts only loopback `Host` and `Origin`; the server sees the proxy's loopback `Origin` and its pinned TLS connection.

The local endpoint is the Unix socket `<data>/spectra.sock` (0660, the owner's group), with peer credentials read on every connection (§8.5); the TCP bind is `127.0.0.1:7350` for Radar. Every request's `Origin` header, when present, MUST be `http://127.0.0.1:7350`, `http://localhost:7350` or the configured `base_url`; anything else is 403, against DNS rebinding (MCP 2026-07-28 transport §Security). Binding beyond loopback requires TLS (§8.6), or `behind_proxy = true` with a `base_url`; `spectra serve` refuses to bind a non-loopback address in plain HTTP without `--insecure`, and says why. A server that is bound beyond loopback still authenticates every request by signature; TLS adds privacy and integrity of what it answers.

bind = "127.0.0.1:7350"               # "[::]:7350" to serve other machines (§8.6)

tls = "auto"                          # beyond loopback: a certificate of its own, signed by the instance key; or { cert = "…", key = "…" }

# names = ["earth", "earth.example"]  # the certificate's names (default: the host name and its FQDN)

| **0.1 Talk** | Client and server over TLS (§8.6), `spectra connect`, remote setup with `spectra init --owner`; workspace, config, SQLite with migrations, the ledger (the frozen envelope with its hybrid logical clock, chain and proofs; `spectra admin verify`; checkpoints signed by the instance key), `spectra init` with the owner's identity, agents as delegates with ownership shown, signed requests over the Unix socket, Radar's level-2 sign-in from the CLI (§8.3), projects, channels, messages, threads, `brief`, `rules` (site layer), `say`, `read`, `inbox`, `wait`, `ack`, `agents`, `search`; Tuner over Streamable HTTP (2026-07-28 and 2025-11-25) and the stdio shim; Radar Live, Channels and Log pages with the SSE stream; `spectra say` and `spectra inbox --follow` | With the daemon on one machine and the owner and both agents on another, Claude Code in `oxygen` and Antigravity in `oxygenhub` each call `brief`, post in `#general`, and see each other's messages via `wait` within a second; the owner watches it on Live; `spectra admin verify` passes |

1. **Hub or no hub.** Everything in this document is one human, and since Draft 0.4 one daemon that other machines may reach (§8.6). The Hub exists for other machines and other people. If the second machine never comes, the Hub is the Android app's backend and a backup, and could be a `spectra serve --public` mode instead. Decide after 0.3, when the local experience has been lived with.

- Draft 0.4 (2026-11-03), Sprint 2: client and server (§8.6): the daemon serves other machines over TLS with a certificate signed by its instance key, so no CA is needed; `spectra connect` accepts a server only when the owner's own identity delegates to its instance key, and pins its certificate; `spectra init --owner KEYID` sets a server up without the owner's secret key, which claims it from the client; a client has no ledger file and works through the JSON API; an agent bound to a uid is refused over TCP; Radar from a client goes through a loopback proxy; 0.1's acceptance runs across two machines (§25).