indicatrix-worker 0.7.2

Coordinator and render worker for an indicatrix-backed design catalogue. `serve` (default build) is the coordinator: it serves indicatrix-net's read-only design-library protocol to viewers over mutual TLS and accepts joining render workers on a separate worker port. The optional `worker` feature adds render capacity -- `join` (dial a coordinator and render its requests), `serve --render` (render with the coordinator's own CPU/GPU) and `render` (a one-shot scene-to-PNG CLI).
Documentation
# indicatrix-worker — trust model


What `serve` actually protects, what it doesn't, and what each security-relevant flag
costs you. For the commands themselves see [the README](../README.md); for how the
worker is built internally see [architecture.md](architecture.md).

`serve` is a network service that accepts caller-supplied geometry and traces it. That
makes two questions load-bearing: *who may connect*, and *what may they make this
machine do*. They are answered by different mechanisms and it is worth keeping them
apart.

## Who may connect


Two independent gates, both of which must pass:

1. **Chain of trust.** The client presents a certificate signed by the same private CA
   as the server's own. Mutual TLS — the client verifies the server too.
2. **The allowlist.** The client certificate's SHA-256 fingerprint must appear in
   the listener's own allowlist: `allowlist-viewers.txt` on the viewer port (a pre-role
   `allowlist.txt` keeps serving as that list until the new file exists),
   `allowlist-workers.txt` on the coordinator's worker port.

The second is not redundant. The CA answers "was this certificate issued by me"; the
allowlist answers "is *this specific* certificate still welcome". Without it, every
certificate the CA ever signed is valid forever, because **there is no CRL and no
OCSP** — revocation *is* deleting a line from the allowlist. That file is re-read on
every connection, so a deletion takes effect immediately, with no restart.

```mermaid
flowchart LR
    A[incoming connection] --> B{chains to the CA?}
    B -- no --> R1[refused]
    B -- yes --> C{fingerprint in allowlist?}
    C -- no --> R2[refused]
    C -- yes --> D[render requests accepted]
```

### Two client roles, two ports (coordinator mode)


`serve` accepts viewers on the viewer port (7878) and `indicatrix-worker join` render
workers on a separate worker port (7880). A client certificate records its role in its
Common Name: `worker:<name>` for a worker, anything else for a viewer (a viewer
`--name` may not start with `worker:`, so the prefix only ever comes from an explicit
`--role worker`). Each listener checks the certificate against its own allowlist, but
only for a certificate of *its* role; the role itself is enforced at `HELLO`. A
certificate of the other role is not looked up in any allowlist at the TLS stage: it
completes the handshake, takes a connection slot and a database handle, and is then
refused with `ROLE_REFUSED` when its `HELLO` arrives (a `HELLO` claiming the wrong role
is refused the same way). The hold is bounded by the handshake deadline and the small
`HELLO` read limit, but for that time a CA-signed certificate that is on *no* allowlist
can occupy one connection slot. A leaked viewer certificate still cannot register as a
worker (and receive scenes to render), and a worker certificate cannot browse the
library or request renders, because neither gets past `HELLO`. `--trust-any-client-cert`
skips the allowlists, never the role check. Each role has its own enrollment listener
(7879 / 7881) with its own token registry; a token only claims on the listener that
issued it.

### What a joined worker is trusted with


An allowlisted worker receives the scenes viewers render — geometry, material and, for
an HDR-lit scene, the HDR map's bytes — and its returned samples are summed into
viewers' images. The coordinator checks the shape of what comes back: each chunk's
frames must lie inside the chunk and, once the chunk is complete, tile its sample range
exactly (sorted, contiguous, non-overlapping) or the whole chunk is discarded; buffer
sizes must match; and a pixel with a non-finite or negative value is dropped (and
counted) rather than summed. It does not check whether the numbers are *right*: a
malicious or broken worker that passed both gates can spoil the images it contributes
to with plausible-looking values.

The build check at pairing time compares what the worker *reports about itself* — a
hash of its crate version and a hash of its physics source tree. A modified worker can
report anything, so this catches mismatched installs, not a hostile peer; and an unknown
source hash only logs a warning and pairs (a peer with no build at all is paired
library-only). Only enroll machines you control as workers, and revoke one by deleting
its line from `allowlist-workers.txt`.

### HDR maps on disk


Scenes lit by an HDR map carry only the map's SHA-256. A node that lacks the bytes asks
its peer (the viewer, or the coordinator) and stores them in its bounded asset cache
(`INDICATRIX_ASSET_CACHE_DIR`, see the README). A cached file is named by its hash
alone — a peer never supplies a path or file name — and its bytes are verified against
that hash when written and re-verified when read. The cache is capped
(`INDICATRIX_ASSET_CACHE_MIB`, least recently used files evicted first), and a single
map is limited to 256 MiB on the wire. A viewer's maps therefore persist on the
coordinator and on every worker that rendered them until evicted; delete the cache
directory to remove them.

### Message size and idle limits


An authenticated peer is still bounded. Every control message (a request, a `CANCEL`, a
`PING`, a stream-event header) is read with a 1 MiB cap, and a declared length never makes
the process commit memory before the bytes arrive: payload buffers grow as data is
received. The large payloads (radiance frames, HDR assets, viewer contributions) keep
their own, separate bounds. A connection that sends no message for five minutes between
requests is closed, with the reason logged; during a request the worker's heartbeat and
liveness deadlines apply instead.

## Enrollment: how a client gets its certificate


Two paths, both supported, with different trade-offs.

### Manual (`cert issue-client`)


Writes `ca.pem`/`client.pem`/`client.key` to a directory and appends the fingerprint to
the allowlist **immediately**. You copy the directory to the viewer's machine yourself.

Kept deliberately: air-gapped and offline setups have nothing to dial out to. It is also
the only path where the allowlist gains an entry before anyone has actually taken
delivery of the certificate — which is the thing the token path improves on.

### Token (`cert issue-token` → `cert claim`)


The operator asks a *running* `serve` process for a one-time token and reads it out. The
enrolling machine redeems it and receives the same three-file bundle.

```mermaid
sequenceDiagram
    participant Op as operator
    participant S as running serve
    participant C as enrolling client
    Op->>S: cert issue-token --name laptop (loopback only, presents issue.secret)
    Note over S: mints bundle, holds it IN MEMORY<br/>stores only SHA-256(secret)<br/>180s TTL, nothing on disk
    S-->>Op: GW1-.... (secret ‖ CA fingerprint)
    Op-->>C: token, out of band
    C->>S: TLS connect to enrollment listener
    S-->>C: presents [server cert, CA cert]
    Note over C: verifies the chain roots at the CA<br/>fingerprint carried IN THE TOKEN<br/>-- before sending anything
    C->>S: secret
    Note over S: constant-time compare, single use
    S-->>C: ca.pem + client.pem + client.key
    Note over S: fingerprint appended to allowlist NOW<br/>pending record dropped and zeroized
```

Three properties are what make this safe, and each was a deliberate choice:

**The token is not the certificate's fingerprint.** It is a fresh 256-bit CSPRNG secret.
The fingerprint is a *public* value — it crosses the wire in the clear on every
handshake and is the allowlist's permanent identifier for that client. A bearer secret
and a long-term public identifier must never be the same value.

**The server never stores the secret.** Only `SHA-256(secret)`, compared in constant
time against every pending entry with no early exit, so a compromise of the running
worker yields nothing redeemable and the comparison's duration doesn't reveal which
entry matched.

**The token commits to the server's identity.** This is the subtle one. An enrolling
client has no CA certificate yet — that is the bootstrap problem. If it trusted whatever
answered, an attacker could impersonate the worker, relay to the real one, and walk away
holding a **valid client certificate**. So the token carries the CA's SHA-256 fingerprint
alongside the secret, and the client verifies the presented chain against it *before*
sending anything. Pinning is trust-anchor *selection* only: once the anchor is chosen,
the whole chain/signature/validity check is delegated to `rustls`'s own
`WebPkiServerVerifier`. Nothing is skipped.

### What a stolen token gets an attacker


A client certificate for your CA, if they redeem it before the legitimate holder does
and within 180 seconds of issuance. That is the real exposure and it is why the window
is short and the token single-use.

Mitigations already in place: the token expires, a successful claim consumes it, and the
allowlist entry appears **only on claim** — so an unclaimed or expired token leaves no
trace and grants nothing. If you suspect a token was intercepted, the legitimate holder
will find their claim fails (single use), which is itself the signal.

### Known limitation: the private key transits


The bundle contains `client.key`, so the worker generates and transmits the client's
private key. A private key ideally never leaves the machine it belongs to.

The stronger design is a CSR flow: the client generates its own keypair and sends a
signing request; the worker returns only the signed certificate, and no private key ever
crosses the wire. That is a deliberate follow-up rather than an oversight — it requires
the client side (`apps/indicatrix-cut`) to generate keypairs, so it could not land with the
worker-side change alone.

Until then, treat the enrollment connection as carrying key material: it is TLS-protected
and server-verified, but a compromise of the worker at that moment is a compromise of
that client's key.

### Other properties worth knowing


- **`serve` needs `ca.key` when enrollment is enabled** — minting a certificate
  requires signing. `--no-enroll` avoids this entirely.
- **A `serve` restart drops every pending enrollment.** Fail-closed, and intended:
  pending bundles live only in memory.
- **`cert issue-token` needs loopback and the operator secret.** The peer must be on
  loopback, enforced against the real `peer_addr()` rather than by how the listener is
  bound. Loopback alone is not authority — any local user, and any port forward onto the
  loopback listener, looks like a loopback peer — so the request must also present the
  **operator secret**: `issue.secret` in the PKI directory, 32 random bytes as hex,
  created the first time `serve` starts an enrollment listener, written with owner-only
  permissions (the same protection as `ca.key`; on Windows an `icacls` ACL), and
  compared in constant time. `cert issue-token` reads it from the PKI directory, so it
  must run as a user who can read that directory. A local user who can read the PKI
  directory is trusted: they could equally read `ca.key` and mint certificates
  directly.
- Key material is held in `Zeroizing` wrappers so ordinary `Drop` overwrites it. Nothing
  protects against an abrupt process kill.

## What each flag weakens


| Flag | What you give up |
|---|---|
| `--trust-any-client-cert` | Both allowlists (viewers and workers). Any certificate the CA ever signed with the port's role is accepted, forever — you lose per-client revocability entirely, keeping only "was it signed by my CA". |
| `--allow-remote` | Loopback-only binding. Required for any real remote worker; it exists so that exposing the machine is a visible, deliberate act rather than a default. |
| `--insecure-no-tls` | Everything: no TLS, no authentication, no client identity. Refused on a non-loopback bind, and every accepted connection logs a warning. Local debugging only. |
| `--no-enroll` | The token path, for viewers and workers alike. The manual `cert issue-client` workflow still works; this just opens no extra port. |
| `--no-workers` | Nothing — it *removes* exposure: no worker port and no worker enrollment listener are opened. |
| `--max-job-memory-mib` | Raising it lets allowlisted viewers make the coordinator hold more memory for in-flight jobs spread over workers. Each job is charged `width × height × 48` bytes, but that is only its base cost: every joined-worker lane also holds several full-frame buffers of its own, so the real memory of a job spread over many workers is a multiple of the charge. |

## What this does *not* protect against


Stated plainly, because a trust model that only lists its strengths is misleading:

- **A compromised CA private key.** Whoever holds `ca.key` can mint certificates that
  pass both gates. It is ACL-restricted at rest (on Windows, via `icacls` to the current
  user, SYSTEM and Administrators), but there is no HSM and no key ceremony.
- **A local user who can read the PKI directory.** `issue.secret` is what authorises
  `cert issue-token`, and it is readable by exactly the users who can read `ca.key`.
  Anyone with that access — or who can run code as the account that runs `serve` — can
  mint viewer and worker certificates; the enrollment listener's loopback check does
  not separate them. Keep the PKI directory owner-only (the tools set this for the files
  they create; a directory you created yourself is yours to secure).
- **A malicious but allowlisted client.** Authorization is binary. An accepted client can
  submit any scene within [the validation limits]../README.md#limits-and-validation —
  which is exactly why those limits exist and are enforced before geometry reaches the
  tracer.
- **Traffic analysis.** TLS hides content, not the fact or size of a render.
- **Certificate expiry as revocation.** Client certificates last five years. The
  allowlist is the revocation mechanism; do not rely on expiry.