162 lines
10 KiB
Markdown
162 lines
10 KiB
Markdown
# Security Header Runbook
|
|
|
|
This runbook defines the expected security-header contract for the web server and Hono API runtime, plus deterministic checks for local and production triage. It intentionally avoids secrets, tenant identifiers, environment-specific values, and placeholder language.
|
|
|
|
## Expected Web Headers
|
|
|
|
The Node web server in `server/server.ts` applies these headers to React Router responses, redirects, and static asset responses:
|
|
|
|
| Header | Expected value | Purpose |
|
|
| --- | --- | --- |
|
|
| `x-content-type-options` | `nosniff` | Prevent MIME sniffing. |
|
|
| `referrer-policy` | `strict-origin-when-cross-origin` | Keep same-origin referrer detail while reducing cross-origin leakage. |
|
|
| `x-frame-options` | `DENY` | Prevent clickjacking through legacy frame controls. |
|
|
| `permissions-policy` | `camera=(), microphone=(), geolocation=()` | Disable high-risk browser capabilities by default. |
|
|
| `cross-origin-opener-policy` | `same-origin` | Isolate top-level browsing context where supported. |
|
|
| `cross-origin-resource-policy` | `same-origin` | Restrict cross-origin resource embedding by default. |
|
|
| `cross-origin-embedder-policy` | `unsafe-none` | Preserve compatibility for embedded/static assets while making the policy explicit. |
|
|
|
|
Web checks must also confirm that existing response behavior is preserved:
|
|
|
|
- `cache-control` remains unchanged for immutable static assets such as `/assets/**`.
|
|
- Redirect status and `location` behavior remain unchanged when React Router emits redirects.
|
|
- Header assignment uses single values rather than appended comma-joined duplicates.
|
|
|
|
## Expected API Headers
|
|
|
|
The API app in `apps/api/src/app.ts` applies these headers to health, OpenAPI, preflight, error, and `/v1` responses:
|
|
|
|
| Header | Expected value | Purpose |
|
|
| --- | --- | --- |
|
|
| `x-content-type-options` | `nosniff` | Prevent MIME sniffing. |
|
|
| `referrer-policy` | `no-referrer` | Avoid leaking API request paths through referrers. |
|
|
| `x-frame-options` | `DENY` | Prevent API documents or error pages from being framed. |
|
|
| `permissions-policy` | `camera=(), microphone=(), geolocation=()` | Disable browser feature access for API responses. |
|
|
| `cross-origin-opener-policy` | `same-origin` | Keep browser isolation policy explicit. |
|
|
| `cross-origin-resource-policy` | `same-origin` | Limit cross-origin resource reuse by default. |
|
|
| `cross-origin-embedder-policy` | `unsafe-none` | Avoid over-broad isolation that could break clients. |
|
|
|
|
API checks must also confirm that existing middleware contracts are preserved:
|
|
|
|
- `x-request-id` is still emitted and forwarded according to the request-id middleware contract.
|
|
- Allowed CORS requests still include the expected `access-control-allow-origin` value.
|
|
- Canonical app and admin browser origins are accepted from routing config, and explicit `WEB_ORIGIN` and `ADMIN_ORIGIN` values are treated as full origins rather than host-only aliases.
|
|
- Denied origins, including malformed variants and `https://attacker.example.invalid`, do not emit `access-control-allow-origin` while still returning `x-request-id` for incident correlation.
|
|
- Preflight responses keep CORS behavior while receiving the request-id and security headers.
|
|
- No response header includes secrets, personal data, tenant identifiers, or raw environment values.
|
|
|
|
## Local Verification Commands
|
|
|
|
Run focused checks from the repository root. These commands are scoped to the files and tests that define the security-header and CORS contracts:
|
|
|
|
```bash
|
|
pnpm --dir server exec eslint server.test.ts server.ts --max-warnings=0
|
|
pnpm --dir server exec vitest run server.test.ts
|
|
pnpm exec eslint apps/api/src/app.test.ts apps/api/src/cors.test.ts apps/api/src/app.ts apps/api/src/cors.ts --max-warnings=0
|
|
pnpm exec vitest run apps/api/src/app.test.ts apps/api/src/cors.test.ts packages/config/src/env-access-enforcement.test.ts packages/config/src/api.test.ts
|
|
test -s docs/security/runbook.md
|
|
python - <<'PY'
|
|
from pathlib import Path
|
|
text = Path('docs/security/runbook.md').read_text()
|
|
assert 'apps/api/src/cors.test.ts' in text
|
|
assert 'attacker.example.invalid' in text
|
|
assert 'T' + 'BD' not in text
|
|
assert 'TO' + 'DO' not in text
|
|
PY
|
|
```
|
|
|
|
Browser, Playwright, Cypress, or other E2E execution is manual unless a human explicitly approves the exact focused run in the current session.
|
|
|
|
## Production Curl Checklist
|
|
|
|
Use the deployed application origin and API origin appropriate for the environment under investigation. Do not paste secrets or authenticated tokens into shared logs.
|
|
|
|
### Web HTML response
|
|
|
|
```bash
|
|
curl -sSI https://example-web-origin/ | tr -d '\r' | grep -Ei '^(x-content-type-options|referrer-policy|x-frame-options|permissions-policy|cross-origin-(opener|resource|embedder)-policy):'
|
|
```
|
|
|
|
Confirm that every expected web security header is present with the values listed above.
|
|
|
|
### Web static asset response
|
|
|
|
```bash
|
|
curl -sSI https://example-web-origin/assets/app.js | tr -d '\r' | grep -Ei '^(cache-control|x-content-type-options|referrer-policy|x-frame-options|permissions-policy|cross-origin-(opener|resource|embedder)-policy):'
|
|
```
|
|
|
|
Confirm that static assets still expose the intended `cache-control` policy while also carrying the security headers.
|
|
|
|
### API health response
|
|
|
|
```bash
|
|
curl -sSI https://example-api-origin/healthz | tr -d '\r' | grep -Ei '^(x-request-id|x-content-type-options|referrer-policy|x-frame-options|permissions-policy|cross-origin-(opener|resource|embedder)-policy):'
|
|
```
|
|
|
|
Confirm that `x-request-id` and all expected API security headers are present.
|
|
|
|
### API CORS allowed app origin response
|
|
|
|
```bash
|
|
curl -sSI https://example-api-origin/v1/example \
|
|
-H 'Origin: https://example-web-origin' | \
|
|
tr -d '\r' | grep -Ei '^(access-control-allow-origin|x-request-id|x-content-type-options|referrer-policy|x-frame-options|permissions-policy|cross-origin-(opener|resource|embedder)-policy):'
|
|
```
|
|
|
|
Confirm that `access-control-allow-origin` exactly matches `https://example-web-origin`, that `x-request-id` is present, and that the API security headers match the values above.
|
|
|
|
### API CORS allowed admin origin response
|
|
|
|
```bash
|
|
curl -sSI https://example-api-origin/v1/example \
|
|
-H 'Origin: https://example-admin-origin' | \
|
|
tr -d '\r' | grep -Ei '^(access-control-allow-origin|x-request-id|x-content-type-options|referrer-policy|x-frame-options|permissions-policy|cross-origin-(opener|resource|embedder)-policy):'
|
|
```
|
|
|
|
Confirm that `access-control-allow-origin` exactly matches `https://example-admin-origin`. If the admin origin is configured through `ADMIN_ORIGIN`, compare against the full configured origin string only; do not rewrite it to a bare host in notes or logs.
|
|
|
|
### API CORS denied origin response
|
|
|
|
```bash
|
|
curl -sSI https://example-api-origin/v1/example \
|
|
-H 'Origin: https://attacker.example.invalid' | \
|
|
tr -d '\r' | grep -Ei '^(access-control-allow-origin|x-request-id|x-content-type-options|referrer-policy|x-frame-options|permissions-policy|cross-origin-(opener|resource|embedder)-policy):' || true
|
|
```
|
|
|
|
Confirm that no `access-control-allow-origin` header is emitted for `https://attacker.example.invalid`, while `x-request-id` and the API security headers remain present for safe incident correlation.
|
|
|
|
### API CORS preflight response
|
|
|
|
```bash
|
|
curl -sSI -X OPTIONS https://example-api-origin/v1/example \
|
|
-H 'Origin: https://example-web-origin' \
|
|
-H 'Access-Control-Request-Method: GET' | \
|
|
tr -d '\r' | grep -Ei '^(access-control-allow-origin|access-control-allow-methods|access-control-allow-credentials|x-request-id|x-content-type-options|referrer-policy|x-frame-options|permissions-policy|cross-origin-(opener|resource|embedder)-policy):'
|
|
```
|
|
|
|
Confirm that the allowed origin is preserved, CORS preflight headers remain present, `x-request-id` is present, and security headers are still attached to the preflight response.
|
|
|
|
## CORS Configuration Guidance
|
|
|
|
- Prefer canonical routing-derived app and admin origins for normal deployments, then add `WEB_ORIGIN` and `ADMIN_ORIGIN` only when an environment needs explicit browser origins.
|
|
- Treat `WEB_ORIGIN` and `ADMIN_ORIGIN` as complete origin strings including scheme and host, for example `https://example-web-origin` and `https://example-admin-origin`; do not document or compare them as host-only aliases.
|
|
- Do not paste raw environment dumps, secrets, tokens, tenant identifiers, or customer-specific domains into tickets or shared logs. Record only the generic origin label under test, the response header names observed, and the `x-request-id` value when needed.
|
|
- Test both positive and negative origins during triage. A positive-only check can miss an over-broad allowlist regression.
|
|
|
|
## Known Interactions
|
|
|
|
- Security headers are set rather than appended, so a response should contain one effective value per header.
|
|
- Web security headers must not overwrite static asset `cache-control` headers.
|
|
- API security headers run alongside request-id and CORS middleware; missing `x-request-id` on any API response is a regression in middleware ordering, and missing `access-control-allow-origin` is expected only for denied browser origins.
|
|
- `cross-origin-embedder-policy: unsafe-none` is intentional for both runtimes to avoid breaking existing embedding and asset-loading behavior.
|
|
- CORS remains the source of truth for allowed browser origins; the security-header layer should not relax or replace CORS decisions.
|
|
|
|
## Rollback and Triage Notes
|
|
|
|
1. Reproduce with the focused local Vitest command for the affected runtime before changing middleware order.
|
|
2. Compare curl output from a known-good response against the failing path, checking both missing security headers and preserved headers such as `cache-control`, `x-request-id`, and `access-control-allow-origin`.
|
|
3. If security headers are missing only on static assets, inspect the static response path in `server/server.ts` before changing React Router forwarding logic.
|
|
4. If API CORS headers disappear, inspect middleware ordering around request-id, security headers, and CORS in `apps/api/src/app.ts`.
|
|
5. If duplicate comma-joined policy values appear, verify that code uses `set` or `setHeader` semantics rather than `append`.
|
|
6. Roll back the smallest runtime-specific header change first; do not remove request-id, CORS, or cache-control behavior as part of header rollback.
|