relay: docs/threat-model.md — per-process surface concerns (deploy, supply chain, DoS, log hygiene)

[ilmoniemi]

User Story

As a contributor or operator of the relay, I want a threat-model doc that catalogues the per-process attack surface (distinct from the wire-protocol threats already in the protocol spec) along with current mitigations and residual risk, so that future security work has a concrete document to update and the security-review agent has structured input.

Context

The protocol spec's Security model covers wire-protocol-level threats (prompt injection, server-id race, MITM, token leak, replay, DoS). This doc covers operational threats specific to the relay binary as a deployed process — concerns that don't appear in the protocol but matter for a real-world deployed service.

Independent of other tickets; the protocol spec is on main. WS upgrade and connection-registry work are not yet built (see docs/PROJECT-MEMORY.md), so threats around the WS library and connection limits are framed in this doc as v1-deferred or prospective rather than referencing a chosen library.

Acceptance Criteria

• New file docs/threat-model.md exists, ~1–2 pages of markdown.
• First paragraph (or front-matter) explicitly distinguishes this doc from the wire-protocol threats in the protocol spec, and links to the spec's Security model section.
• The doc covers each of the following operational-threat domains, and for each gives: severity (low/medium/high), v1 mitigation (or "deferred"), residual risk, future hardening:
  • Deploy security. SSH key management for the VPS, who has access, OS update cadence, intrusion detection. What happens if the VPS is rooted (every byte through the relay is exposed; same threat as the protocol spec's "relay operator MITM" but framed from the operator's side).
  • Supply chain. Go dependencies (go.mod); govulncheck in CI; checksum verification (go.sum); SBOM as future work. Risk and mitigation for current deps (golang.org/x/crypto/acme/autocert) and the not-yet-chosen WebSocket library being compromised.
  • DoS resistance. Connection-count limits (none in v1); per-IP rate limiting (none in v1); slow-loris (mitigated by ReadHeaderTimeout); bandwidth amplification (relay forwards only; no amplification factor); accidental fork-bomb via runaway client retry (no protection in v1).
  • Log hygiene. What MUST NOT be logged (payload bodies, tokens, full headers); what IS logged (server-id, conn-id, device-name, remote host, event types). Log rotation policy; log retention.
  • Cert & key handling. Autocert cache dir at 0700 (enforced via ErrCacheDirInsecure); what happens if it becomes world/group-readable; key rotation (autocert handles it).
  • TLS configuration. Cipher suite policy (Go's secure defaults); pinned MinVersion: tls.VersionTLS12 (already in internal/relay/tls.go).
  • Error response leakage. Don't leak internal errors via 500 bodies; use generic messages to public paths.
• The doc has a "Triggers for re-review" section listing when to update it (new dependency added, deploy target changed, new public endpoint exposed, security incident).
• docs/architecture.md "Threat model" section is updated to link to the new doc instead of saying "to be written".

Technical Notes

• This is documentation, not code. Use the protocol spec's "Security model" section as the structural template (severity / mitigation / residual / deferred per threat). The architect should produce the threat list before the documentation agent drafts; the architect understands the architecture.
• nhooyr.io/websocket is not currently a dependency — supply-chain coverage should describe the deps that exist today and note that the WS library will be added to this list when chosen.
• Out of scope:
  • Pen-test write-up (we haven't done one).
  • Compliance frameworks (no GDPR/SOC2 obligations in v1; user-data flows are minimal).
  • Per-CVE response runbook (premature; revisit when there are users).

Size Estimate

S — ~150 lines of markdown, single-doc deliverable.

[ilmoniemi]

🤖 Product Owner — creates structured issues

po agent has completed work on this ticket.

Agent output (click to expand)

Refined #11. Changes:

- **Fixed factual error**: removed `nhooyr.io/websocket` as a current dep (it isn't — `go.mod` only has `golang.org/x/crypto`). Reframed supply-chain AC around real deps and noted the WS library will be added when chosen. Mirrored the same caveat in Technical Notes.
- **Reformatted to standard issue shape**: folded `## Depends on` into Context.
- **Tightened AC**: 4 top-level criteria (file, distinguishing front-matter, threat domains, triggers section, architecture cross-link) — under the 5-AC red line. Threat domains are sub-bullets of one AC since they're sections of one deliverable.
- **Anchored to existing code**: noted `ErrCacheDirInsecure` and `MinVersion: tls.VersionTLS12` already exist (per `internal/relay/tls.go` and `lessons.md`), so the doc records v1 mitigations rather than asking for new code.
- **Size: S** applied. Not security-sensitive label — pure documentation per PO rules.
- No split: single-doc deliverable, no always-split pattern triggered, no quantitative red line crossed.

Not adding `ready:po` — dispatcher handles that.

Ready for human review. Move to the next column when approved.

[ilmoniemi]

🤖 System Architect — defines Go interfaces, data flows, concurrency patterns

architect agent has completed work on this ticket.

Agent output (click to expand)

Spec committed at `docs/specs/architecture/11-threat-model-doc.md`.

Summary: documentation-only ticket, sized S, no overlap with the only in-flight branch (`feature/3`, which touches different docs), no `security-sensitive` label so the security-review pass was skipped. The spec produces the structured threat list (7 categories: deploy, supply chain, DoS, log hygiene, cert/key, TLS, error leakage) with severity/mitigation/residual/future-hardening grounded in code (`internal/relay/tls.go`, `cmd/pyrycode-relay/main.go` timeouts, `go.mod` deps), plus the architecture-doc pointer update — so the documentation agent can render markdown without re-deriving the architecture.

Ready for human review. Move to the next column when approved.

[ilmoniemi]

🤖 Developer — implements Go code with tests

developer agent has completed work on this ticket.

Agent output (click to expand)

PR opened: https://github.com/pyrycode/pyrycode-relay/pull/14

Two files changed: new `docs/threat-model.md` (101 lines, seven threat sections plus triggers-for-re-review and out-of-scope), and `docs/architecture.md` "Threat model" section now points at it. `go vet` and `go test -race ./...` both clean.

Ready for human review. Move to the next column when approved.