# Security

The pool is open: anyone can run a node. The design assumes some nodes are
hostile and some callers want free compute. This page lists what is
protected, how, and what is not solved yet.

## Identity

- A node is an Ed25519 key pair created on first run. The node id is the
  public key. No accounts, no email, nothing to steal from a database.
- Joining: the hub sends a random challenge; the node signs it. A node
  cannot claim another's id without its private key.
- Every HTTP call to the hub (route lookups, links) carries a signature over
  method, path with query, timestamp, a random nonce and the body hash.
  Timestamps outside two minutes are refused, and the hub remembers nonces,
  so a captured request cannot be replayed.
- Only nodes with an open, admitted session can look up the route or open
  links. A key that is not connected right now gets `403`.

## Nothing listens on the internet

- `llama-server` and `ggml-rpc-server` bind to `127.0.0.1`. The local API
  on port 17080 also binds to loopback, and refuses requests whose `Host`
  or `Origin` is not loopback, so a web page cannot reach it through the
  browser.
- Nodes talk to each other only through links: each side opens a TLS
  WebSocket to the hub, which pairs them and copies bytes. Home routers
  need no open ports.
- `direct` transport is an explicit opt-in on both ends, for trusted LANs.

## Links are authorized per generation

The hub knows the current plan and allows only:

- RPC links from the head to a member of the same generation.
- API links from any running node to the current head, never from the head
  to itself.

Anything else gets `403`: a worker cannot drive another worker's engine, an
outsider cannot open a link at all, and a link for an old generation is
refused. The node accepting a link checks role and generation again before
touching its engine.

## The head is the only gate to the model

- The engine API key is generated on the head and never leaves it. Requests
  from links and from the head's own owner go through the same gate.
- Only the two completion endpoints are served. Everything else returns
  `404`, so no one can reach llama.cpp's slot, props or metrics endpoints
  from outside.
- `max_tokens` is capped at 16384 and set when missing; bodies are limited
  to 8 MB.

## Abuse limits

| Limit | Value |
|-------|-------|
| Nodes per IP address | 8 |
| Nodes in the pool | 5000 |
| Link opens per node | 2 per second, bursts of 40 |
| API links open per node | 4 |
| Control message size | 64 KiB |
| Link frame size | 4 MiB |
| Hello fields | name 1 to 48 printable characters, 64 cached models at most |

## Models

The hub names a model by catalog id. Each node checks it against its own
built-in catalog and only runs files it knows, with size and sha256
checked. A hub cannot make a node download or run an arbitrary file.

## Known gaps

These are not solved and are on the roadmap:

- **Privacy.** Prompts and answers are visible to the head machine and to
  the hub, which relays the bytes. Links are encrypted between each node
  and the hub, not end to end. Do not send secrets.
- **Honest compute.** A hostile head or worker can return wrong output or
  slow the split down. There is no verification of results yet.
- **Many identities.** Keys are free, so per-node limits do not stop one
  person running many nodes from many addresses.
- **Fair use.** Using the pool is not tied to lending yet. Credits will
  close that; see [Credits](credits.md).
- **Single hub.** The hub is one process. If it is down, the pool is down;
  nodes reconnect with backoff when it returns.

## Reporting

Open an issue on <https://github.com/capitaharlock/hyverk-distributed-llm>. For
something exploitable, ask there for a private channel first and leave the
details out of the public issue.
