3.9 KiB
id, title, status, wave, depends_on, plan, spec
| id | title | status | wave | depends_on | plan | spec |
|---|---|---|---|---|---|---|
| 03-configuration-docs | Configuration docs | done | 2 | plan.md | ../../specs/auth/requirements/trusted-proxies.md |
Task 03: Configuration docs
Document KANDEV_TRUSTED_PROXIES in the public startup-configuration
reference.
Acceptance
docs/public/configuration.mddocuments the variable: comma-separated IPs / CIDRs (IPv4 and IPv6), default (unset = no trusted proxies, header ignored), the spoofing security implication (a directly reachable backend whose peer falls inside a trusted range can haveX-Forwarded-Forspoofed, which also defeats the ClientIP-keyed login rate limiter), invalid-entry behavior (startup warning naming the bad value, whole variable ignored, no crash), and the note that the variable must reach the backend process: set it in the environment of the process that launches kandev (service unit, container, or parent launcher env, e.g. a systemd drop-in forkandev.service).~/.kandev/supervisor/launch.jsonis launcher-generated (rewritten every launch, env filtered by an allowlist) and is NOT an environment configuration source. The variable is read once at startup.- Copy follows the env-only variable prose pattern of
KANDEV_TASK_PREPARATION_TIMEOUTin the same file, and the no-em-dash rule for public copy (ADR 2026-08-10).
Files likely touched
docs/public/configuration.md(new###section after the Authentication / feature-flags section, before Logging)
Dependencies
None (text describes the Task 01 contract; files are disjoint from Tasks 01-02).
Parallelism
sequential by default; scheduled as Wave 2 after Tasks 01-02. Parallel-safe
candidate only when the user authorizes subagents.
Inputs
- Spec sections What, Failure modes; the task description's docs requirements.
docs/public/configuration.mdstructure (## Complete backend reference,### Authentication, Office, Plugins, and feature flags, env-only prose pattern in### Setup and launch timing).- Launcher env flow:
apps/backend/internal/launcher/env.go(backendEnvstarts fromos.Environ(), so the launcher's own environment reaches the backend child) andapps/backend/internal/launcher/supervisor.go(prepareSupervisorEnv/buildManifest/allowedSupervisorEnv: thelaunch.jsonmanifest is rewritten every launch and its env is an allowlist that omitsKANDEV_TRUSTED_PROXIES, so it is not an injection point).
Verification
node scripts/validate-public-docs.mjs && git diff --check && git diff --stat docs/public/configuration.md
Read the rendered section back and confirm the format, default, security
implication, invalid-entry behavior, and reach-the-backend note are all
present; scripts/validate-public-docs.mjs enforces the no-em-dash rule for
docs/public/** (ADR 2026-08-10).
Risks
- Adding a YAML-key row to the reference tables would imply a
config.yamlkey that does not exist; the variable is environment-only and must be documented as prose likeKANDEV_TASK_PREPARATION_TIMEOUT.
Output contract
Report the exact files changed, the added section text, diff-check evidence,
remaining risks, and synchronized task/plan status. Record every exact command
and outcome in ## Results.
Results
Added the ### Trusted proxies for X-Forwarded-For section to
docs/public/configuration.md between the Authentication / feature-flags
section and Logging: format, default (unset = no trusted proxies), security
implication (callers inside a listed range can spoof; rate-limiter impact),
fail-closed invalid-entry behavior (including trailing/doubled commas), and
reach-the-backend guidance (process-launcher environment, e.g. systemd
drop-in; launch.json explicitly noted as launcher-generated and not an
environment source).
node scripts/validate-public-docs.mjs— "Validated 41 published docs pages." (no em dashes; ADR 2026-08-10).git diff --check— clean.