pneumo

M2: Server skeleton — config, logging, health, static web app, security headers (ENG-247) #11

Merged

demi.dev 1w ago

targeting main from stoopkidddd/eng-247-m2-server-skeleton-config-logging-health-static-web-app

Merged opened by and assigned to

demi.dev 1w ago targeting main from stoopkidddd/eng-247-m2-server-skeleton-config-logging-health-static-web-app

Linear: https://linear.app/engineereddev/issue/ENG-247

What's in this PR:

Config: zod covers every §12.3 variable with its default, including the RAILWAY_PUBLIC_DOMAIN → PUBLIC_URL and RAILWAY_ENVIRONMENT → TRUST_PROXY fallbacks. Errors list names, never values, and exit 1.
Logging: pino with the §12.4 redaction paths and a child logger per request.
App and startup: createApp(deps) injects config, storage (stub), clock, logger and instanceState. index.ts uses real deps, @hono/node-server, and a graceful-shutdown hook list (close code 1012, 10 s drain).
Middleware: a JSON ErrorBody error handler (via @pneumo/protocol), a 128 KiB body limit → 413, and request logging with no query strings on /api/files.
Routes and serving: GET /api/health; static WEB_DIST_DIR with §12.6 cache rules; SPA fallback; JSON 404 for unknown /api.
Headers: CSP built from a bucket-origin parameter, HSTS over HTTPS, nosniff, no-referrer and Permissions-Policy.
Build (lead decision): tsup bundles @pneumo/* into dist/index.js, so plain node can run it. This fixes the ENG-239 follow-up recorded on this issue. check:server now builds and launches the bundle (health, HTML, config failure, SIGTERM).

Verify (lead, clean install):

pnpm install --frozen-lockfile → exit 0
mise run check:server → exit 0 · Test Files 5 passed · Tests 54 passed
pnpm --filter @pneumo/web build && pnpm --filter @pneumo/server build → exit 0
.env.example + PORT=8099 node apps/server/dist/index.js:
  /api/health → {"ok":true,"version":"0.1.0","initialized":false}
  / → 200, no-cache, CSP "default-src 'self'; script-src 'self'; … connect-src 'self' wss://localhost:8080; … frame-ancestors 'none'; base-uri 'none'; form-action 'self'", nosniff, no-referrer, Permissions-Policy
  /devices → index.html (SPA) · /api/nope → {"error":{"code":"not_found","message":"Not found."}}
  server log: 0 lines containing authorization/bearer
mise run check → exit 0

Deviations:

README Development notes were updated; README was added to Touches by the lead.
Package version 0.1.0.
The spec leaves HSTS and Permissions-Policy values open; this PR uses max-age=31536000; includeSubDomains and camera=(), microphone=(), geolocation=().

Commits 2

M2: Use epoch milliseconds for the server clock (ENG-247)

+15 -4

M2: Add hardened server skeleton and bundled runtime (ENG-247)

+2132 -20

Comments

v0 1w ago

demi.dev 1w ago

pneumo-reviewer — round 1 (v0) (Claude Opus 5.5, xhigh)

VERDICT: REQUEST_CHANGES

SUMMARY: The skeleton is solid and matches the spec: all 19 §12.3 variables with their defaults; redaction; JSON errors; the 128 KiB limit; SPA fallback; JSON 404 for /api; exact CSP and headers; 1012 shutdown hooks; and the tsup bundle. All are tested and checked on the built server, including path-traversal probes. One change is needed: the production clock is performance.now() (milliseconds since process start), not wall time.

FINDINGS:

FIX often=5 bad=7 score=35 apps/server/src/index.ts:15. Every later route will use the injected clock for createdAt, invTs, expiresAt, lastSeenAt and retention. With performance.now() that would write 1970 timestamps that reset on every restart. Fix: { now: () => Date.now() }, documented as Unix epoch milliseconds.
FILE score 4. The hashed-asset regex marks dashed unhashed icons as immutable.
FILE score 3. Errors are logged without diagnostic detail.
FILE score 4. HSTS includeSubDomains with an apex PUBLIC_URL.
FILE score 3. The 128 KiB limit covers only JSON content types; later routes must parse through the validator.

Notes: connect-src 'self' wss://localhost:8080 for an http PUBLIC_URL is correct per §12.6. Later /api routes must mount above app.all("/api/*").

SPEC CHECK: §8 conventions and health, §12.1 (apart from the clock), §12.3, §12.4 and §12.7 are OK. §12.6 is OK apart from icon caching (FILE 2).

DOD CHECK: fake-clock unit tests; app.request() route tests; redaction assertions; a real @pneumo/protocol import; the build-and-run test inside check:server; no bucket touch at boot; README. All present.

TESTS RUN: check:server → 54 tests pass; the build bundles protocol inline; built-server probes (health, HTML, caching, traversal, 413, SIGTERM).

Lead: FIX 1 goes to omp (round 2). FILE 2–5 are recorded on ENG-275, ENG-262, ENG-260 and ENG-250.

v1 1w ago

demi.dev 1w ago

pneumo-reviewer — round 2 (v1) (Claude Opus 5.5, xhigh)

VERDICT: APPROVE

SUMMARY: Round v1 (afa282d) resolves FIX 1. systemClock = { now: () => Date.now() } is documented as Unix epoch milliseconds and injected in index.ts. Test fixtures use epoch-millisecond fake clocks, and a new test pins the production unit; it would fail if performance.now() returned. The only other change is 4 README lines.

FINDINGS: FIX 1 is RESOLVED (app.ts:20, app.test.ts:62-64). FILE 2–5 are recorded on ENG-275, ENG-262, ENG-260 and ENG-250. No new findings.

SPEC CHECK: §8 health, §12.1 (the clock is now wall time, which suits §5.1 timestamps and §5.3 invTs), §12.3, §12.4, §12.6 and §12.7 are OK.

DOD CHECK: all present; the round touches only app.ts, index.ts, app.test.ts and README.

TESTS RUN: check:server → 55 tests pass. Built-server smoke: health, the HTML headers and SIGTERM exit 0, with nothing left listening.

Versions