relay: refuse to boot when Linux effective capabilities exceed allowlist

[ilmoniemi]

User Story

As an operator deploying pyrycode-relay in a Linux container, I want the relay to refuse to start when its effective Linux capabilities exceed an explicit allowlist, so that a container runtime that grants stray capabilities (CAP_SYS_ADMIN, CAP_NET_ADMIN, etc.) fails loudly at boot rather than silently accepting elevated privileges.

Context

Container runtimes can grant capabilities via --cap-add, capability bounding sets, or default Docker profiles. A misconfigured deploy that grants the relay extra capabilities escapes CI build scans and runs with more privilege than intended.

This ticket adds a Linux-only boot-time check that parses the effective capability set from /proc/self/status (the CapEff: line) and aborts if any capability outside an explicit allowlist is present. On non-Linux platforms (darwin dev runs), the check is a no-op with a single startup log line.

Related: #9 (ErrCacheDirInsecure boot-time refusal pattern).

Acceptance Criteria

• An exported sentinel ErrUnexpectedCapability exists in internal/relay, branchable via errors.Is, alongside an exported allowlist of capabilities the relay legitimately needs. The error message identifies the unexpected capability (bit position and symbolic name where known) and the allowlist contents. Architect determines the allowlist contents by reading current code — at minimum CAP_NET_BIND_SERVICE if the relay binds privileged ports without setcap, otherwise the empty set.
• On Linux, a check function parses /proc/self/status's CapEff: hex mask and returns ErrUnexpectedCapability if any bit outside the allowlist is set, nil otherwise. On non-Linux platforms the check is a no-op returning nil and logs skipping linux-only capability check on <GOOS> exactly once at startup. The Linux/non-Linux split is handled at compile time (build tags); this ticket is the first introduction of that pattern in the repo, so architect chooses the file naming.
• The check is wired into cmd/pyrycode-relay/main.go after flag parse, before any listener is started, with fail-fast on error and a structured log line that names the unexpected capability and the operator fix (--cap-drop or equivalent).
• Unit tests cover: (a) empty CapEff → nil; (b) only-allowlisted CapEff → nil; (c) CapEff with one bit outside allowlist → sentinel; (d) malformed /proc/self/status content → wrapped error (not a panic). The CapEff string is injected via a test seam rather than touching real /proc.
• Capability check has no production-mode predicate — it runs in every environment (including dev) because stray capabilities are never legitimate. Sibling tickets (relay: refuse to boot with --insecure-listen in production mode #77, relay: refuse to boot as effective uid 0 in production mode #78) introduce the PYRYCODE_RELAY_PRODUCTION=1 contract; this ticket does not consume it.

Technical Notes

• /proc/self/status's CapEff: line is a 64-bit hex mask. Linux capability bit positions are stable kernel ABI.
• Whether to also check CapPrm / CapBnd / CapInh is architect's call — CapEff is the minimum.
• No existing _linux.go / _other.go files in the repo; this ticket establishes the convention.

Size Estimate

S

Split from #42.

[ilmoniemi]

🤖 Product Owner — creates structured issues

po agent has completed work on this ticket.

Agent output (click to expand)

Refined #79 in place. Changes:

- **Collapsed 7 ACs → 5** (within sizing red lines): merged sentinel + allowlist into one AC, merged Linux behavior + non-Linux no-op + build-tag mechanism into one AC.
- **Removed file-name prescription** (`startup_check_cap_linux.go` / `startup_check_cap_other.go`) — that's the architect's call. Body now notes this ticket *introduces* the build-tag pattern (the prior claim of "consistent with patterns already in the repo" was wrong — no `_linux.go` files exist in the tree).
- **Added explicit no-production-predicate clause** — capability check runs in every environment, unlike siblings #77/#78 which depend on the `PYRYCODE_RELAY_PRODUCTION=1` contract. This forestalls an architect-stage question about whether to gate behind production mode.
- Size kept at `S`, `security-sensitive` label already present (frame routing on internet-exposed surface — fits the contract).

No split needed: single concern (Linux capability check + wiring), under all quantitative red lines, passes the one-sentence test ("Refuse boot when Linux effective capabilities exceed an allowlist"). Dispatcher will add `ready:po` and advance to In Architecture.

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

[ilmoniemi]

Blocked by #30: overlapping changes to cmd/pyrycode-relay/main.go. #30's open PR (#43, currently CONFLICTING) modifies the ClientHandler wiring at the same handler-registration region this ticket's capability check needs to land near (post-flag-parse, pre-listener). Will write the spec once #30 lands and main is current.

[ilmoniemi]

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

architect agent flagged issues on this ticket → rework by po.

Agent output (click to expand)

Blocked #79 on #30 and routed back to PO. No spec written; worktree is clean.

**Why:** File-overlap check found `origin/feature/30` (PR #43, OPEN, currently CONFLICTING) modifies `cmd/pyrycode-relay/main.go` — the same file #79's capability-check wiring must edit (post-flag-parse, pre-listener). Per the architect playbook's branch-based overlap check, any overlap blocks even when regions differ, since git-merge conflicts can still arise and the policy is binary by design (no per-region judgment).

**Actions taken:**
- `addBlockedBy(#79, #30)` via GraphQL
- Comment on #79 explaining the block
- `+needs-rework:po`, `-wip:architect` so the ticket routes back to Backlog; it will auto-advance when #30 closes

Needs rework by po. See agent findings above.