47eb2615ec
- rate-limiting: correct BRouter limit to 300/hour (was 60); add Overpass rate-limit requirement (120/min per IP) - security-hardening: BROUTER_AUTH_TOKEN lives in secrets.app.env, not infra.env - account-management: email-change verification does not re-auth; existing session stays valid - planner-journal-handoff: full rewrite — documents the actual JWT callback architecture (edit-in-planner → POST /api/sessions → callback endpoint), token claims, notes round-trip via GPX <metadata><desc>, session lifecycle - route-drag-reshape: rewrite to describe permanent segment midpoint handles (not proximity hover ghost marker); click-to-insert + waypoint drag model - route-splitting: rewrite to match midpoint handle model; notes geometric midpoint placement (not cursor-snapped) - road-type-coloring: redirect to route-coloring (all requirements already covered there) - osm-tile-overlays: mark profile-aware auto-enable as not yet implemented (profileOverlayDefaults exported but not wired) - osm-poi-overlays: zoom threshold is 10 not 12; user override persistence marked as not yet implemented - shared-packages: add all 7 missing packages (map-core, fit, api, db, jobs, sentry-config, correct map description); document map vs map-core boundary Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
81 lines
3.7 KiB
Markdown
81 lines
3.7 KiB
Markdown
## Purpose
|
|
|
|
Security headers, scanner path blocking, secret scanning, dependency auditing, non-root containers, and vulnerability disclosure policy.
|
|
## Requirements
|
|
### Requirement: Security response headers
|
|
All HTTP responses SHALL include security headers to protect against common web attacks.
|
|
|
|
#### Scenario: HSTS header
|
|
- **WHEN** a browser receives a response from trails.cool
|
|
- **THEN** the response includes `Strict-Transport-Security: max-age=31536000; includeSubDomains; preload`
|
|
|
|
#### Scenario: Content sniffing prevention
|
|
- **WHEN** a browser receives a response
|
|
- **THEN** the response includes `X-Content-Type-Options: nosniff`
|
|
|
|
#### Scenario: Clickjacking prevention
|
|
- **WHEN** a browser receives a response
|
|
- **THEN** the response includes `X-Frame-Options: DENY`
|
|
|
|
### Requirement: Scanner path blocking
|
|
Known vulnerability scanner paths SHALL be blocked at the reverse proxy level before reaching the application.
|
|
|
|
#### Scenario: Env file scanner
|
|
- **WHEN** a request is made to `/.env`, `/.env.local`, `/.env.prod`, or similar paths
|
|
- **THEN** Caddy returns 403 without forwarding to the application
|
|
|
|
#### Scenario: Git config scanner
|
|
- **WHEN** a request is made to `/.git/config` or `/.git/HEAD`
|
|
- **THEN** Caddy returns 403 without forwarding to the application
|
|
|
|
### Requirement: Secret scanning in CI
|
|
The CI pipeline SHALL scan commits for accidentally committed secrets.
|
|
|
|
#### Scenario: Secret detected
|
|
- **WHEN** a PR contains a committed API key, token, or password
|
|
- **THEN** the CI pipeline fails with a clear message indicating the leaked secret
|
|
|
|
#### Scenario: Known public values allowed
|
|
- **WHEN** a known-public value (e.g., Sentry DSN) is committed
|
|
- **THEN** gitleaks allows it via the `.gitleaks.toml` allowlist
|
|
|
|
### Requirement: Dependency vulnerability scanning
|
|
The CI pipeline SHALL check for known vulnerabilities in dependencies.
|
|
|
|
#### Scenario: High severity vulnerability
|
|
- **WHEN** a dependency has a high or critical vulnerability advisory
|
|
- **THEN** the CI pipeline fails
|
|
|
|
### Requirement: Non-root Docker containers
|
|
Application containers SHALL run as a non-root user.
|
|
|
|
#### Scenario: Container user
|
|
- **WHEN** a container starts
|
|
- **THEN** the process runs as a non-root user (not UID 0)
|
|
|
|
### Requirement: Vulnerability disclosure policy
|
|
The repository SHALL include a SECURITY.md with responsible disclosure instructions.
|
|
|
|
#### Scenario: Security contact
|
|
- **WHEN** a security researcher finds a vulnerability
|
|
- **THEN** SECURITY.md provides clear instructions for reporting it
|
|
|
|
### Requirement: BRouter access control
|
|
The BRouter service SHALL be reachable only from the flagship host over a private Hetzner vSwitch, and every request SHALL carry a valid `X-BRouter-Auth` shared-secret header. The token SHALL be stored only in SOPS-encrypted secrets and GitHub Actions secrets, never committed in cleartext.
|
|
|
|
#### Scenario: Request from public internet
|
|
- **WHEN** an attacker sends a request to the BRouter host's public IP on the BRouter service port
|
|
- **THEN** the host firewall refuses the connection
|
|
|
|
#### Scenario: Request from vSwitch without token
|
|
- **WHEN** a request arrives on the BRouter host over the vSwitch without a valid `X-BRouter-Auth` header
|
|
- **THEN** the Caddy sidecar responds with HTTP 403 and BRouter never sees the request
|
|
|
|
#### Scenario: Token storage
|
|
- **WHEN** `BROUTER_AUTH_TOKEN` is added or rotated
|
|
- **THEN** the token is written only to `infrastructure/secrets.app.env` (SOPS-encrypted, shared app secrets) and to the GitHub Actions secret store, and is never committed in cleartext to the repository
|
|
|
|
#### Scenario: Token rotation
|
|
- **WHEN** the token is rotated
|
|
- **THEN** operators update SOPS, redeploy the Planner (new token in outbound header), and redeploy the Caddy sidecar (new token in the matcher), in that order, with zero downtime
|
|
|