Phase 2: Security Baseline + Dockerfile (Week 2)

[Number531]

Overview

Two parallel workstreams: Security hardening (helmet, CORS, env validation, 529 retry, credential rotation) and container setup (Dockerfile, .dockerignore, DB pool config).

Execution Plan: docs/pending-updates/deploy-week-2.md
Reference: docs/pending-updates/deployment-guide.md — Sections 2.8-2.9, 4.1-4.6, 7.1-7.2

Stream A: Security Hardening

• A1 Add helmet security headers (CSP, HSTS, X-Frame-Options) — DEFERRED (CSP complexity, 50+ inline styles need browser validation)
• A2 CORS lockdown — DEFERRED (SSE writeHead conflict at line 936, needs atomic commit with frontend)
• A3 Environment validation on startup — fail fast if ANTHROPIC_API_KEY missing ✅ d790714
• A4 Anthropic 529 retry with exponential backoff — DEFERRED (async iterator complexity, duplicate tool execution risk)
• A5 🔴 Credential rotation — ALL keys in committed .env must be rotated immediately
• A6 Migrate API keys out of query strings — DESCOPED (upstream APIs don't support header auth)
• A7 Request size limits — DEFERRED (current 50MB works; reducing is behavioral change)

Stream B: Container Setup

• B1 Dockerfile with node:22-slim, pandoc, typst, non-root user + package.json engines >=22.0.0 ✅ d790714
• B2 .dockerignore — exclude tests, docs, .env, coverage ✅ d790714
• B3 .nvmrc (value: 22) ✅ d790714
• B4 Configurable DB pool: max: 5 → Number(process.env.PG_POOL_MAX || 10) ✅ d790714
• B5 Update .env.example with ALLOWED_ORIGINS, PG_POOL_MAX ✅ d790714

Progress

• Implemented (6/12): A3, B1, B2, B3, B4, B5 — merged to main via deploy-week-2 branch (2026-03-11)
• Deferred (4/12): A1, A2, A4, A7 — documented in CHANGELOG, not required for deployment
• Descoped (1/12): A6 — upstream APIs don't support header auth
• Remaining (1/12): A5 credential rotation — operational task, not code change
• Test baseline: 37 suites / 1160 tests passing (zero regressions)
• Version: v4.5.0

Effort

~2 days (2 developers, 1 per stream)

Depends On

• Phase 0: Critical Runtime Fixes — 8 Pre-Deployment Blockers (Week 1) #34 (Phase 0 runtime fixes — Week 1) ✅ Complete

Blocks

• Phase 1: Authentication + Cloud Run (Week 3) #35 (Auth & Multi-Tenancy — Week 3, needs Dockerfile for CI/CD)

🤖 Generated with Claude Code

[Number531]

P0 Prerequisite Complete ✅

b8e429f (v4.4.0) implements all 8 P0 runtime fixes. This issue is now unblocked.

Key P0 changes relevant to Week 2:

• postinstall: patch-package removed — npm ci --omit=dev now succeeds (Dockerfile builds work)
• Global exception handlers added — containerized process won't silently crash
• archiveOldSessions deferred to post-listen — faster container cold start
• Promise singletons — no duplicate rate limiters under concurrent Cloud Run requests

[Number531]

Week 2 Implementation Complete — v4.5.0

Branch: deploy-week-2 merged to main (fast-forward, zero conflicts)
Commit: d790714

Completed (6 tasks)

Task	Description
A3	Env validation on startup — ANTHROPIC_API_KEY required, PG_CONNECTION_STRING/ALLOWED_ORIGINS recommended
B1	Dockerfile (Node 22-slim, pandoc/typst, non-root, healthcheck) + engines >=22.0.0
B2	.dockerignore (excludes tests/docs/reports, whitelists prompts)
B3	.nvmrc (22)
B4	Configurable DB pool (PG_POOL_MAX, default 10)
B5	.env.example updated with deployment vars

Deferred (4 tasks)

• A1 Helmet: CSP complexity (50+ inline styles)
• A2 CORS: SSE writeHead conflict
• A4 529 retry: Async iterator complexity + duplicate tool risk
• A7 Request size: Current 50MB works

Verification

• Test baseline: 37 suites / 1160 tests (zero regressions)
• 4 independent explore agents verified zero pipeline impact
• Pool change: measured load <1% of even 5 connections
• Env validation: runs once at module load, cannot re-trigger mid-run

Next: Week 3 (#35) is unblocked — Dockerfile ready for CI/CD

[Number531]

Update (2026-03-12): Week 3 (v4.6.0, 460b34e) resolved the CORS lockdown item (A2):

• SSE Access-Control-Allow-Origin: '*' replaced with ALLOWED_ORIGINS env var + Access-Control-Allow-Credentials: 'true'
• Frontend credentials: 'include' added to all 17 fetch calls
• This was done atomically with the auth frontend work, as noted in the deferral reason

Remaining open items: A1 (Helmet/CSP), A4 (529 retry), A5 (credential rotation), A7 (request size limits).

[Number531]

Dockerfile shipped with tini, pandoc, poppler-utils, typst. AUTH_ENABLED=true on GCE with bcrypt login. Cookie-based auth with Obsidian+Gold login page.