relay: refuse to boot with --insecure-listen in production mode

[ilmoniemi]

User Story

As an operator deploying pyrycode-relay, I want the relay to refuse to start when --insecure-listen is set in production, so that a dev-config promoted to a prod deploy fails loudly at boot rather than serving plaintext traffic.

Context

The relay currently exposes mutually-exclusive --domain (autocert TLS) and --insecure-listen (plaintext) flags. Today nothing distinguishes a dev environment from a production environment, so an operator who copy-pastes a dev manifest into prod can boot a plaintext listener facing the internet.

This ticket introduces a deterministic production-mode signal — the env var PYRYCODE_RELAY_PRODUCTION=1 — and a boot-time check that refuses to start when production-mode is on AND --insecure-listen is set.

The env var contract is also expected to be consumed by sibling startup checks (e.g. refuse-to-run-as-uid-0-in-production, #78). This ticket is the canonical place where the contract is defined.

Related: #9 (ErrCacheDirInsecure boot-time refusal pattern), #39 (multi-instance check). Split from #42.

Acceptance Criteria

• An exported helper in internal/relay reports whether the process is in production mode by reading PYRYCODE_RELAY_PRODUCTION; "1" means production, anything else (including unset, "0", or other values) means non-production. The PYRYCODE_RELAY_PRODUCTION=1 contract is documented in the helper's Go doc comment.
• A check function in internal/relay returns the exported sentinel ErrInsecureListenInProduction (branchable via errors.Is) when production-mode is on AND --insecure-listen is set, and returns nil otherwise.
• 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 naming the env var and the fix.
• Unit tests cover the full 2×2 matrix: (a) non-production + insecure-listen → nil; (b) production + insecure-listen → sentinel; (c) production + --domain (autocert) → nil; (d) non-production + --domain → nil. The env var is read through a test seam (injected getter or equivalent), not by mutating process env.

Technical Notes

• The env var name and "1"-means-on semantics intentionally mirror the existing PYRYCODE_RELAY_SINGLE_INSTANCE contract (relay: single-instance constraint — doc + startup self-check (registry is in-memory) #39 / relay: document v1 single-instance constraint in architecture.md #64) so operators only have to remember one shape.
• Helper name and check-function name are the architect's call; the only naming constraint is the exported sentinel ErrInsecureListenInProduction (downstream tickets reference it).
• Read the env var lazily on each call (or via injected getter); tests need to flip the value per case without process-env mutation.

Size Estimate

S

[ilmoniemi]

Refined in place. Body already followed the issue format from the #42 split; the only material change was tightening 6 acceptance criteria → 4 to stay under the red-line cap. Specifically:

• Folded the standalone "sentinel ErrInsecureListenInProduction exists" AC into the check-function AC (the check returning the sentinel implies its existence and export status).
• Folded the standalone "Go doc comment documents the contract" AC into the helper AC (documentation requirement lives with the surface being documented).

Test matrix (the substance of the gate) preserved verbatim — all 4 corners of the 2×2 (production × listen-mode) remain explicitly required, and the test-seam constraint stays in place so the env var is not mutated in the process env during tests.

Sizing red-line check:

• ACs: 4 (≤5 ✓)
• Files: ~3 (internal/relay/startup_check_insecure_listen.go or similar, its _test.go, plus the wire-in edit to cmd/pyrycode-relay/main.go) — at the boundary, acceptable for S.
• Exported symbols: 3 (sentinel, helper, check function) (≤5 ✓)
• LOC estimate: ~40–60 production (well under 100 ✓)
• One-sentence test: "Refuse boot with --insecure-listen when PYRYCODE_RELAY_PRODUCTION=1." — no "and" ✓

Labels: security-sensitive (internet-exposed boot path, governs whether plaintext traffic is served) and size:s already applied at split time — left in place.

Architect notes: helper/check-function names are deliberately left to architect's call; the sentinel name ErrInsecureListenInProduction is the only fixed identifier (downstream ticket #78 will branch on it).

[ilmoniemi]

🤖 Product Owner — creates structured issues

po agent has completed work on this ticket.

Agent output (click to expand)

Refined #77 in place. Body was already well-structured from the #42 split — material change was tightening **6 ACs → 4** to clear the red-line cap (folded sentinel-existence into check-function AC, folded doc-comment requirement into helper AC). Test matrix and test-seam constraint preserved. Labels (`security-sensitive`, `size:s`) already correct; 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 branch modifies line 51 (ClientHandler signature wiring); #77 will add the production-mode boot check around the flag-parse block. The regions are nominally distinct, but the file-overlap rule is mechanical to avoid integration-time merge conflicts (architect/code-review hours apart under WIP=N). Will write the spec once #30 lands.

This block is pre-spec — architect run halted at § 1.5 of the protocol, no spec was written.

[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)

Halted at the pre-spec file-overlap check (§ 1.5).

- **Overlap found**: `feature/30` (open in-flight branch for #30) modifies `cmd/pyrycode-relay/main.go`; #77 would too.
- **Action**: set `blockedBy(#77, #30)` via GraphQL, posted a block comment, added `needs-rework:po`. No spec was written; worktree is clean.
- **Resumption**: when #30 merges, the block flips closed and #77 auto-advances back to In Architecture against current main.

Needs rework by po. See agent findings above.