@luckystack/server 0.10.1 → 0.11.0

package/docs/security-defaults.md

@@ -1,242 +1,13 @@
-# Security Defaults
+# Server security boundaries
 
-> Deep specs. Sources: `packages/server/src/httpHandler.ts`, `packages/server/src/httpRoutes/csrfRoute.ts`, `packages/server/src/httpRoutes/csrfMiddleware.ts`, `packages/server/src/httpRoutes/testResetRoute.ts`, `packages/server/src/securityHeadersRegistry.ts`, and `packages/server/src/errorFormatterRegistry.ts`.
+**Origin is not identity.** HTTP requests with an explicit disallowed Origin/Referer are rejected; state-changing requests without either are rejected rather than trusting the caller-controlled Host header. Origin-less read-only probes remain possible. CORS response headers are not permission to skip route authorization. For testing browser-like writes, supply an allowed `Origin` header. Source: `../src/httpHandler.ts`, `../../core/src/checkOrigin.ts`.
 
-## Overview
+**Cookies need CSRF protection.** Browsers attach cookies automatically; state-changing framework and custom routes must verify a token before execution unless covered by narrowly scoped auth bootstrap or signed-webhook exemption. With a session, compare to its CSRF token; without login use the double-submit contract. Do not log the token in mismatch hooks. Explicit bearer-mode credentials do not use the same ambient-cookie trust model. Source: `../src/httpRoutes/csrfMiddleware.ts`, `../src/httpRoutes/csrfRoute.ts`, `../../core/src/extractToken.ts`.
 
-`@luckystack/server` ships four fail-closed defenses out of the box:
+**Exemption is not authentication.** A route exempt from origin/CSRF checks must verify a signature or equivalent credential itself; an exemption must not make cookie-protected data readable by arbitrary origins. Keep OAuth state validation and redirect allowlisting intact (`../src/originExemptRegistry.ts`, `../../login/src/login.ts`). Security-header customizations must not silently remove required protection (`../src/securityHeadersRegistry.ts`).
 
-1. **Origin policy.** No `Host` fallback — non-browser callers cannot silently bypass CORS on state-changing methods.
-2. **Security headers.** Framework defaults are emitted for every response. A consumer-registered builder may override or extend.
-3. **CSRF middleware.** Cookie-mode state-changing framework and custom routes require the configured CSRF header unless they are an auth bootstrap/callback route or explicitly origin-exempt. With login installed it validates a session-bound token; without login it uses a stateless double-submit cookie/header pair. Mismatches return 403 and dispatch `csrfMismatch`.
-4. **`/_test/reset` fail-closed.** Requires `NODE_ENV` to be exactly `development` or `test` AND a non-empty `TEST_RESET_TOKEN` env var. An unset token does NOT mean "no auth"; it means the route is permanently 403.
+**Boot warnings matter.** Login-bootstrap and OAuth-callback routes cannot present a pre-existing CSRF token; their exemption depends on restrictive session-cookie SameSite policy. Relaxing that policy without a replacement origin/CSRF defense enables login CSRF. The unauthenticated health endpoint can reveal fingerprints of synchronized environment secrets: do not publish plain unsalted hashes, and do not assume a per-boot keyed hash protects low-entropy values from an attacker who can read its public boot identifier. See `../src/verifyBootstrap.ts`, `../src/httpRoutes/healthRoutes.ts`.
 
-Plus two extension seams:
+**Test reset fails closed.** Its mode and secret checks exist to prevent test-only state deletion in live environments. Do not loosen either condition. Custom session adapters must clean up their own test state; the built-in reset cannot know their storage. See `../src/httpRoutes/testResetRoute.ts`.
 
-- `registerSecurityHeaders(builder)` — append / override headers per request.
-- `registerErrorFormatter(formatter)` — shape the JSON error envelope globally.
-
-## CORS / origin policy
-
-Lives in `enforceOriginPolicy` (`httpHandler.ts`):
-
-- `origin = req.headers.origin ?? req.headers.referer ?? ''`. There is intentionally NO `Host` fallback.
-- For state-changing methods (anything other than GET / HEAD / OPTIONS) with no `Origin` and no `Referer`: respond `403 'Forbidden'` (text/plain) and stop dispatch.
-- For any method when an explicit `Origin` / `Referer` is supplied but `allowedOrigin(origin)` returns false: respond `403 'Forbidden'` and stop.
-- Read-only methods (GET / HEAD / OPTIONS) without an origin header pass through — this keeps health probes and asset fetches from non-browser tooling working.
-
-When `curl`-testing a write endpoint, attach `-H 'Origin: https://your-allowed-origin'` (the allow-list lives in `projectConfig.http.cors.allowedOrigins` and is enforced by `allowedOrigin` in `@luckystack/core`).
-
-## Security headers
-
-`setSecurityHeaders` in `httpHandler.ts` writes the framework defaults from `projectConfig.http`:
-
-| Header | Source | Notes |
-| --- | --- | --- |
-| `Access-Control-Allow-Origin` | resolved `origin` (or `''`) | Mirrors the origin policy's resolved value. |
-| `Access-Control-Allow-Methods` | `cors.allowedMethods` |  |
-| `Access-Control-Allow-Headers` | `cors.allowedHeaders` |  |
-| `Access-Control-Expose-Headers` | `cors.exposedHeaders` |  |
-| `Access-Control-Allow-Credentials` | `cors.credentials ? 'true' : (omitted)` |  |
-| `Referrer-Policy` | `securityHeaders.referrerPolicy` |  |
-| `X-Frame-Options` | `securityHeaders.frameOptions` |  |
-| `X-XSS-Protection` | `securityHeaders.xssProtection` |  |
-| `X-Content-Type-Options` | `securityHeaders.contentTypeOptions` |  |
-
-After defaults, the registered builder (if any) runs. Errors in the builder are caught and logged via `getLogger().warn('securityHeadersBuilder threw — falling back to defaults', { err })`; the request continues with defaults intact.
-
-### API — `registerSecurityHeaders(builder | null)`
-
-**Signature:**
-
-```typescript
-export type SecurityHeadersBuilder = (
-  req: IncomingMessage,
-) => Record<string, string> | null | undefined;
-
-export const registerSecurityHeaders = (builder: SecurityHeadersBuilder | null): void;
-export const getSecurityHeadersBuilder = (): SecurityHeadersBuilder | null;
-```
-
-**Behavior:**
-
-- Last-write-wins; subsequent calls replace the prior builder. Pass `null` to unregister.
-- Builder is invoked for every request after framework defaults. A returned object's entries are written via `res.setHeader(name, value)` so they REPLACE same-name defaults (per Node semantics).
-- A nullish return (`null` / `undefined`) means "use defaults only".
-
-**Example:**
-
-```typescript
-import { registerSecurityHeaders } from '@luckystack/server';
-
-registerSecurityHeaders((req) => ({
-  'Content-Security-Policy': "default-src 'self'; img-src 'self' data:; script-src 'self'",
-  'Strict-Transport-Security': 'max-age=63072000; includeSubDomains; preload',
-  'Permissions-Policy': 'camera=(), microphone=()',
-}));
-```
-
-## CSRF middleware
-
-Lives in `enforceCsrfOnStateChangingRequest` (`csrfMiddleware.ts`). Runs after origin/security-header setup but BEFORE route dispatch.
-
-**Activation predicate (all required):**
-
-- `projectConfig.session.basedToken === false` (cookie mode; the public scaffold flag is `config.sessionBasedToken`).
-- HTTP method is state-changing: not `GET`, `HEAD`, or `OPTIONS`.
-- The path is a framework API/sync/auth-API route, or any custom path outside `/auth/*` and `/assets/*`.
-- The path is not an auth callback, credentials/email-code/2FA login-bootstrap route, or a prefix registered through `registerOriginExemptPath(...)`.
-
-The validation branch then depends on whether `@luckystack/login` is installed:
-
-1. Read `getCsrfConfig().headerName` (default `x-csrf-token`; first value when the Node header is an array).
-2. **Login present:** when a valid session token/session exists, compare the header with `session.csrfToken`. Requests without a valid session continue to the downstream auth policy instead of being misclassified as CSRF failures.
-3. **Login absent:** read the configured CSRF cookie (default `csrf-token`) and compare it with the header using the timing-safe helper. No session read occurs.
-4. On mismatch, dispatch `csrfMismatch` with `{ route, method, requestId, userId, providedToken: Boolean(provided) }`—presence only, never the token—then return `403 auth.csrfMismatch`.
-
-**Token issue:** `GET /auth/csrf` is the single issuing endpoint.
-
-- With login present it requires a valid session and returns that session's CSRF token.
-- Without login it returns a new random token and sets the same value in the configurable double-submit cookie; `httpOnly: true` is supported because the client reads the matching token from the JSON response. The cookie's `Secure` attribute follows explicit CSRF config or `SECURE=true`.
-
-The client helpers fetch/cache the token per invocation origin and attach it to state-changing requests. Token mode (`sessionBasedToken=true`, internally `session.basedToken=true`) deliberately skips CSRF because JavaScript explicitly supplies the bearer/handshake token; the browser does not ambiently attach it like a cookie.
-
-## `/_test/reset` fail-closed contract
-
-Source: `httpRoutes/testResetRoute.ts`.
-
-**Activation predicate (both required):**
-
-1. `process.env.NODE_ENV` is exactly `'development'` OR `'test'`. Any other value (including unset / `'production'` / `'staging'`) returns `404 { status: 'error', errorCode: 'notFound' }`. This is the fail-closed gate — `NODE_ENV !== 'production'` is NOT a sufficient check.
-2. `process.env.TEST_RESET_TOKEN` is non-empty AND `req.headers['x-test-reset-token'] === process.env.TEST_RESET_TOKEN`. Any mismatch (including an unset token) returns `403 { status: 'error', errorCode: 'auth.forbidden' }`.
-
-**Authorization header — actual source-of-truth:**
-
-The handler reads `req.headers['x-test-reset-token']`. Wire your test client to send:
-
-```
-x-test-reset-token: <value of TEST_RESET_TOKEN>
-```
-
-(The README quickstart mentions `Authorization: Bearer ${TOKEN}` — the running code reads `x-test-reset-token`. Use that header.)
-
-**What the reset clears:**
-
-| Step | Action |
-| --- | --- |
-| 1 | `clearAllRateLimits()` — purges in-memory + Redis rate-limit counters. Always reported in `cleared`. |
-| 2 | `redis SCAN` + `DEL` keys matching `<projectName>-session:*`. Reported as `'sessions'` when at least one key is deleted. |
-| 3 | `redis SCAN` + `DEL` keys matching `<projectName>-activeUsers:*`. Reported as `'activeUsers'` when at least one key is deleted. |
-| 4 (opt-in) | When `?include=hooks` is supplied, `clearAllHooks()` empties every framework hook registration. Reported as `'hooks'`. |
-
-`getProjectName()` (from `@luckystack/core`) is the single source of truth for the default Redis key prefix—same helper used by the Redis session adapter and rate limiter.
-
-> **Custom `SessionAdapter` caveat:** `/_test/reset` clears only the framework's default Redis session and active-user namespaces. It does not call or discover a custom adapter, so sessions stored in DynamoDB, Postgres, an in-memory test adapter, or another backend survive this endpoint. Custom-adapter test suites must clear their own store in setup/teardown.
-
-**Response:** `200 application/json { status: 'success', cleared: string[] }`. The `cleared` array reflects which subsystems reported deletions.
-
-**Errors / edge cases:**
-
-- Malformed `req.url` is detected with `URL.canParse(rawUrl, base)`. When false, `?include=hooks` is treated as absent.
-- Redis `SCAN`+`DEL` errors are swallowed per pattern — the cleared array simply omits the label.
-- The hook-clear is opt-in because clearing every hook also removes framework-internal registrations (e.g. presence's `postLogout`).
-
-**Example — invoking from a test runner:**
-
-```bash
-curl -X POST http://127.0.0.1:80/_test/reset \
-  -H 'x-test-reset-token: dev-secret-123' \
-  -H 'Origin: http://127.0.0.1:80'
-```
-
-`.env.local` (dev / test only):
-
-```
-NODE_ENV=development
-TEST_RESET_TOKEN=dev-secret-123
-```
-
-`@luckystack/test-runner`'s `resetServerState` reads the same env var.
-
-## Error formatter
-
-Lives in `errorFormatterRegistry.ts`. The framework normalizes errors via `normalizeErrorResponse` from `@luckystack/core` (i18n + envelope shape). The registered formatter is the GLOBAL hook — per-endpoint `errorFormatter` exports on route files take precedence.
-
-**Resolution order at error time:**
-
-1. Per-endpoint `errorFormatter` export (when the route file declares one).
-2. Global formatter from `registerErrorFormatter(...)`.
-3. Framework default `normalizeErrorResponse`.
-
-### API — `registerErrorFormatter(formatter | null)`
-
-**Signature:**
-
-```typescript
-export interface ErrorFormatterContext {
-  routeName: string;
-  transport: 'socket' | 'http';
-  userId?: string | null;
-}
-
-export type ErrorFormatter = (
-  error: {
-    status: 'error';
-    errorCode: string;
-    message?: string;
-    httpStatus?: number;
-    [key: string]: unknown;
-  },
-  ctx: ErrorFormatterContext,
-) => Record<string, unknown>;
-
-export const registerErrorFormatter = (formatter: ErrorFormatter | null): void;
-export const getErrorFormatter = (): ErrorFormatter | null;
-```
-
-**Behavior:**
-
-- Receives the already-normalized envelope plus `{ routeName, transport, userId? }`.
-- Return a (possibly extended) object that the framework emits verbatim.
-- Pass `null` to unregister.
-
-**Example — add correlation IDs + a legacy alias key:**
-
-```typescript
-import { registerErrorFormatter } from '@luckystack/server';
-
-registerErrorFormatter((error, ctx) => ({
-  ...error,
-  // legacy clients expect `reason`; new clients read `errorCode`.
-  reason: error.errorCode,
-  correlationId: ctx.routeName + ':' + (ctx.userId ?? 'anon'),
-}));
-```
-
-## Hooks dispatched
-
-| Hook | Payload | When |
-| --- | --- | --- |
-| `csrfMismatch` | `{ route, method, requestId, userId, providedToken: boolean }` | CSRF middleware rejects a write. `providedToken` is `Boolean(value)` — never the token itself. |
-| `preHttpRequest` | `{ method, url, requestId, origin, headers }` | Every request before dispatch; can stop with `HookStopSignal`. `headers` excludes `authorization`, `cookie`, `set-cookie`, `x-csrf-token`. |
-| `rateLimitExceeded` | `{ scope, key, limit, windowMs, count, route, ip }` | Credentials login (`handleAuthApiRoute`). |
-
-## Config keys
-
-| Source | Key | Effect |
-| --- | --- | --- |
-| env | `NODE_ENV` | Gates `/_test/reset` — must be exactly `'development'` or `'test'`. |
-| env | `TEST_RESET_TOKEN` | Required for `/_test/reset` to be reachable. Compared against `x-test-reset-token`. |
-| env | `SECURE` | When `'true'`, session cookies are emitted with `Secure;`. |
-| config | `projectConfig.http.cors.*` | `Access-Control-*` headers. |
-| config | `projectConfig.http.securityHeaders.*` | `Referrer-Policy`, `X-Frame-Options`, `X-XSS-Protection`, `X-Content-Type-Options`. |
-| config | `projectConfig.session.basedToken` | Switches cookie-mode (CSRF enforced) vs header-mode (CSRF skipped — header transport already binds to the request). |
-| config | `projectConfig.http.testResetEndpoint` | Path for `handleTestResetRoute`. Default `/_test/reset`. |
-
-## Related
-
-- Function INDEX: `packages/server/CLAUDE.md`
-- Request pipeline: `packages/server/docs/request-pipeline.md`
-- HTTP routes: `packages/server/docs/http-routes.md`
-- Architecture: `docs/ARCHITECTURE_API.md`, `docs/ARCHITECTURE_AUTH.md`
-- README: `packages/server/README.md`
+**A scoped reset is exact, and a bad selector is an error.** The unscoped reset also deletes every framework session, including the one an authenticated test sweep runs on, so the reset accepts a target selector and the test-runner always narrows it to rate limits. A selected reset runs exactly the listed targets; an unknown or empty target is rejected rather than silently resetting nothing or everything. Changing the unscoped reset instead was rejected because CI setups rely on it to log users out between suites (ADR 0064). The valid targets live in one list in core that server and runner both read; a new target belongs there so the two sides cannot drift. Source: `../../core/src/testResetTargets.ts`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luckystack/server",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "private": false,
   "publishConfig": {
     "access": "public",
@@ -46,7 +46,7 @@
   "files": [
     "dist",
     "README.md",
-    "CLAUDE.md",
+    "AGENTS.md",
     "docs",
     "LICENSE",
     "CHANGELOG.md"
@@ -57,20 +57,20 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@luckystack/api": "^0.10.1",
-    "@luckystack/core": "^0.10.1"
+    "@luckystack/api": "^0.11.0",
+    "@luckystack/core": "^0.11.0"
   },
   "peerDependencies": {
     "@prisma/client": "^6.19.0",
     "socket.io": "^4.8.0",
-    "@luckystack/cron": "^0.10.1",
-    "@luckystack/devkit": "^0.10.1",
-    "@luckystack/docs-ui": "^0.10.1",
-    "@luckystack/email": "^0.10.1",
-    "@luckystack/error-tracking": "^0.10.1",
-    "@luckystack/login": "^0.10.1",
-    "@luckystack/presence": "^0.10.1",
-    "@luckystack/sync": "^0.10.1"
+    "@luckystack/cron": "^0.11.0",
+    "@luckystack/devkit": "^0.11.0",
+    "@luckystack/docs-ui": "^0.11.0",
+    "@luckystack/email": "^0.11.0",
+    "@luckystack/error-tracking": "^0.11.0",
+    "@luckystack/login": "^0.11.0",
+    "@luckystack/presence": "^0.11.0",
+    "@luckystack/sync": "^0.11.0"
   },
   "peerDependenciesMeta": {
     "@prisma/client": {

package/CLAUDE.md

@@ -1,89 +0,0 @@
-# @luckystack/server
-
-> AI summary + function INDEX. For deep specs see `docs/` next to this file.
-
-## What this package does
-
-One-call server bootstrap for a LuckyStack project. Wires together a raw Node.js HTTP server, Socket.io (with optional Redis adapter), framework routes (`/api/*`, `/sync/*`, `/_health`, `/livez`, `/readyz`, `/_test/reset`, `/auth/*`, `/uploads/*`, including `GET /auth/csrf`), CSRF middleware, CORS + security headers, presence broadcasting, and dev-only hot reload. Consumer's `server.ts` shrinks to roughly twenty lines. Boots are gated by `verifyBootstrap` so missing registrations surface a single readable error instead of mid-request crashes. If devkit initialization fails, API/sync dispatch and `/readyz` all fail closed with 503.
-
-## When to USE this package
-
-- Project needs the full LuckyStack runtime (HTTP + sockets + framework routes wired in one call).
-- Multi-bundle or multi-service deploys that need positional argv parsing (`npm run server -- <bundles> <port>`) and merged runtime maps across presets.
-- Consumers that want framework-shipped health / liveness / readiness probes, CSRF protection, and dev hot reload without building plumbing themselves.
-- Adding project-specific HTTP endpoints via `registerCustomRoute(...)` or the `customRoutes` option without forking the package.
-- Plugins / framework packages that ship socket-lifecycle behavior via the exported hook payload types (e.g. `@luckystack/presence`).
-
-## When to NOT suggest this (yet)
-
-- Standalone microservices that do not use the LuckyStack registries (project config, deploy config, runtime maps, localized normalizer) — there is nothing for `verifyBootstrap` to verify, and the wiring overhead buys nothing.
-- A pure router / load-balancer process — use `@luckystack/router` instead; `@luckystack/server` is for the actual service nodes behind the router.
-- Build-time tooling, code generation, or migration scripts that never accept HTTP / socket traffic.
-- Replacing the HTTP layer with Express / Fastify — the package owns the raw Node HTTP server and dispatch table; bringing a second framework on top breaks the route handler contract.
-
-## Function Index
-
-| Function / Export | One-liner | Deep doc |
-|---|---|---|
-| `createLuckyStackServer(options)` | Lower-level factory that returns `{ httpServer, ioServer, listen, afterListen, stop, close }`. Wires HTTP + Socket.io + framework routes; after a successful listen starts the boot-UUID TTL heartbeat, and stops it during shutdown. Installs a persistent `httpServer.on('error')` listener and (in prod) SIGTERM/SIGINT → graceful `stop()`. | -> docs/create-server.md |
-| `RunningLuckyStackServer.afterListen(task, options?)` | Runs post-listen work (queue workers, warm-up, reconciliation) isolated from the caller's fatal boot chain. A rejection is logged loudly and swallowed by default — the server is already serving, and killing it over one broken dependency turns an outage into a supervisor crash-loop. `{ fatal: true }` re-throws for a task the process cannot run without; `{ label }` names it in the log. | -> docs/create-server.md |
-| `RunningLuckyStackServer.stop(options?)` / `.close(options?)` | Graceful shutdown (MIS-016). Stops accepting new connections, dispatches the core `preServerStop` hook, flushes error-trackers (bounded by a per-step timeout race), then closes io + http + the Redis-adapter pub/sub clients. Each step isolated + time-bounded so one hanging step can't stall shutdown. Idempotent. `options`: `{ reason?, timeoutMs? }` (default `timeoutMs` 10000). | -> docs/create-server.md |
-| `bootstrapLuckyStack(options)` | High-level entry: auto-imports `luckystack/<pkg>/*.ts` overlay in topological order, then delegates to `createLuckyStackServer`. An overlay file that fails to import (classic: it imports a package removed via `luckystack remove`) aborts boot with an ACTIONABLE error naming the file, instead of a raw ERR_MODULE_NOT_FOUND. | -> docs/create-server.md |
-| `OVERLAY_ORDER` (exported const) | The canonical overlay walk order (`core, deploy, login, email, sentry, presence, cron, docs-ui, server`). Exported so the consumer's `scripts/bundleServer.mjs` imports it at build time — a hardcoded bundler copy once silently dropped the cron slot from prod; `overlayOrderParity.test.ts` pins the bundlers' fallback lists to this. | -> docs/create-server.md |
-| `collectOverlayEntries(packageDir)` | Single owner of what one `luckystack/<pkg>/` folder contributes: `{ fileNames, ignoredDirectoryNames }`. `index.*` first, then the rest alphabetically; `.ts`/`.js` only; **test files excluded** (`.tests.`/`.test.`/`.spec.`, plus `__tests__`/`__mocks__` folders) so they never boot or reach the production bundle. The walk is FLAT — any other subdirectory comes back in `ignoredDirectoryNames` and the loader warns, instead of dropping overlay code in silence. Exported so `scripts/bundleServer.mjs` decides identically. ADR 0047. | -> docs/create-server.md |
-| `registerOverlayLoader(loader)` | Production-bundle seam: the server bundler (`scripts/bundleServer.mjs`) generates an entry that statically imports the overlay files and registers this loader; `bootstrapLuckyStack` then runs it INSTEAD of the runtime `.ts` folder walk (plain `node` cannot import `.ts` — ERR_UNKNOWN_FILE_EXTENSION). | -> docs/create-server.md |
-| `verifyBootstrap(requirements?)` | Pre-flight check for ProjectConfig / DeployConfig / ServicesConfig / OAuth / RuntimeMapsProvider / LocalizedNormalizer. Throws one descriptive `Error`. | -> docs/create-server.md |
-| `parseServerArgv(argv)` | Pure parser: validates positional `<bundles> [port]` and returns `{ bundles, port }`. Throws on malformed input. | -> docs/argv-parsing.md |
-| `applyServerArgv()` | Side-effect runner: parses `process.argv.slice(2)`, stores bundles, and registers the port through browser-safe `@luckystack/core/config`. Idempotent. | -> docs/argv-parsing.md |
-| `getParsedBundles()` | Returns the preset list parsed by `applyServerArgv()` (empty array before first call). | -> docs/argv-parsing.md |
-| `getParsedPort()` | Returns the port parsed by `applyServerArgv()` (`null` if argv omitted it). | -> docs/argv-parsing.md |
-| `@luckystack/server/parseArgv` (side-effect import) | First-line import that runs `applyServerArgv()` before consumer `config.ts` reads the typed override registry. | -> docs/argv-parsing.md |
-| `createProdRuntimeMapsProvider(options)` | Build a `RuntimeMapsProvider` that loads generated maps in prod and delegates to devkit discovery in dev. Composed presets reject duplicate API/sync ownership, deduplicate equivalent full-registry function entries, and reject differing function implementations. Returns the provider without registering. | -> docs/runtime-maps.md |
-| `registerProdRuntimeMapsProvider(options)` | Convenience wrapper: builds the provider AND calls `registerRuntimeMapsProvider`. Most consumers want this. | -> docs/runtime-maps.md |
-| `registerCustomRoute(handler, options?)` | Append a custom HTTP route handler. `options.phase`: `'post-params'` (default, runs after body parse) or `'pre-params'` (runs before `getParams`, raw `req` stream intact — webhooks + streaming uploads). | -> /docs/ARCHITECTURE_HTTP.md |
-| `getCustomRoutes()` | Read the `'post-params'` registry snapshot (the default phase). | -> /docs/ARCHITECTURE_HTTP.md |
-| `getPreParamsCustomRoutes()` | Read the `'pre-params'` registry snapshot. | -> /docs/ARCHITECTURE_HTTP.md |
-| `clearCustomRoutes()` | Clear both phases (used by test resets). | -> /docs/ARCHITECTURE_HTTP.md |
-| `registerOriginExemptPath({ pathPrefix })` | Exempt a path prefix from the browser origin gate so a server-to-server webhook (no `Origin`/`Referer`) reaches its handler. Empty/fail-closed by default. **Exemption ≠ auth** — the handler MUST verify a signature/secret. | -> /docs/ARCHITECTURE_HTTP.md |
-| `getOriginExemptPaths()` / `clearOriginExemptPaths()` / `isOriginExemptPath(routePath)` | Read / clear / test the exempt-path registry. | -> /docs/ARCHITECTURE_HTTP.md |
-| `registerSecurityHeaders(builder)` | Override / extend the security-headers builder applied to every HTTP response. | -> docs/security-defaults.md |
-| `getSecurityHeadersBuilder()` | Read the currently registered builder (defaults to framework headers when no override set). | -> docs/security-defaults.md |
-| `registerErrorFormatter(formatter)` | Override the JSON error shape returned by framework error responses. | -> docs/security-defaults.md |
-| `getErrorFormatter()` | Read the currently registered formatter. | -> docs/security-defaults.md |
-| Route handler: `handleLivezRoute` | Liveness probe at `projectConfig.http.liveEndpoint`. Always 200 when reachable. | -> docs/http-routes.md |
-| Route handler: `handleReadyzRoute` | Readiness probe: boot UUID + dev-tool initialization state + Redis ping + database check (ADR 0020: a registered `registerDbHealthCheck` probe wins; else the built-in Prisma ping when Prisma is registered/resolvable; else `'skipped'` so a deliberately DB-less project can go ready). A recorded fatal devkit boot is 503 even when Redis/database are green. Response `checks.database` = tri-state, `checks.prisma` kept for compat. | -> docs/http-routes.md |
-| Route handler: `handleHealthRoute` | Health endpoint: returns boot UUID + env hashes for router topology checks. | -> docs/http-routes.md |
-| Route handler: `handleTestResetRoute` | Destructive test reset. Fail-closed on `NODE_ENV` and `TEST_RESET_TOKEN`. | -> docs/security-defaults.md |
-| Hook payload: `OnSocketConnectPayload` | Payload type for `onSocketConnect` lifecycle hook handlers. | -> docs/create-server.md |
-| Hook payload: `OnSocketDisconnectPayload` | Payload type for `onSocketDisconnect` lifecycle hook handlers. | -> docs/create-server.md |
-| Hook payload: `PreRoomJoinPayload` | Payload type for `preRoomJoin` hook handlers. | -> docs/create-server.md |
-| Hook payload: `PostRoomJoinPayload` | Payload type for `postRoomJoin` hook handlers. | -> docs/create-server.md |
-| Hook payload: `PreRoomLeavePayload` | Payload type for `preRoomLeave` hook handlers. | -> docs/create-server.md |
-| Hook payload: `PostRoomLeavePayload` | Payload type for `postRoomLeave` hook handlers. | -> docs/create-server.md |
-| Hook payload: `OnLocationUpdatePayload` | Payload type for `onLocationUpdate` hook handlers. | -> docs/create-server.md |
-| Types: `CreateLuckyStackServerOptions`, `BootstrapLuckyStackOptions`, `BootstrapRequirements`, `RunningLuckyStackServer`, `StopLuckyStackServerOptions`, `AfterListenOptions`, `RouteContext`, `StaticFileHandler`, `FaviconHandler`, `CustomRouteHandler`, `ProdRuntimeMapsLoaderOptions`, `ParsedServerArgv`, `SecurityHeadersBuilder`, `ErrorFormatter`, `ErrorFormatterContext` | Handler + option typing. | -> docs/create-server.md |
-
-## Config keys (env vars + registerProjectConfig slots)
-
-- Port precedence — `options.port` → positional argv registry override → `options.defaultPort` (the scaffold passes `config.ports.backend`) → `80`. Inputs must be integer ports in `0..65535`. After bind, `httpServer.address().port` is authoritative (including `listen(0)`). In dev, that port is advertised to `node_modules/.luckystack/dev-server.json`; cleanup removes it only when the exiting PID still owns it. The Vite proxy follows the advertisement for HTTP + WebSocket requests.
-- `SERVER_IP` (env, optional, default `127.0.0.1`) — bind address fallback when `options.ip` is omitted.
-- `NODE_ENV` (env, required for security-sensitive branches) — `development` / `test` toggle devkit hot reload + REPL and gate `/_test/reset`.
-- `TEST_RESET_TOKEN` (env, required for `/_test/reset` to be reachable at all) — must match the `x-test-reset-token` request header. No fallback "no auth" mode.
-- `projectConfig.http.healthEndpoint` (config) — path served by `handleHealthRoute`. Default `/_health`.
-- `projectConfig.http.liveEndpoint` (config) — path served by `handleLivezRoute`. Default `/livez`.
-- `projectConfig.http.readyEndpoint` (config) — path served by `handleReadyzRoute`. Default `/readyz`.
-- `projectConfig.http.testResetEndpoint` (config) — path served by `handleTestResetRoute`. Default `/_test/reset`.
-- `projectConfig.logging.socketStartup` / `projectConfig.logging.devLogs` (config) — gate the boot log line emitted by `listen()`.
-- Positional argv `<bundles> [port]` — preset list (merged in `createProdRuntimeMapsProvider`) and listen port.
-
-## Peer dependencies
-
-- **Required (runtime deps)**: `@luckystack/api`, `@luckystack/core`.
-- **Required peer**: `socket.io@^4.8.0`.
-- **Optional (all auto-detected by `bootstrapLuckyStack`; the server degrades gracefully when absent — `auth.disabled` / `sync.disabled`, presence skipped)**: `@prisma/client@^6.19.0`, `@luckystack/login`, `@luckystack/presence`, `@luckystack/sync`, `@luckystack/error-tracking`, `@luckystack/email`, `@luckystack/cron`, `@luckystack/docs-ui`, `@luckystack/devkit` (dev-only, dynamically imported by the `enableDevTools` branch).
-  - **0.2.0 install-anything-anytime**: `bootstrapLuckyStack` runs an auto-detect phase BEFORE the consumer overlay that imports each installed optional package's `@luckystack/<pkg>/register` side-effect subpath (`OPTIONAL_PACKAGES` in `capabilities.ts` = `login, email, error-tracking, presence, cron, docs-ui`). So `npm i @luckystack/<pkg>` + env + restart self-wires the BACKEND with zero code edits. Detection uses `import.meta.resolve` (the `@luckystack/*` exports maps are import-only — a CJS `require.resolve` reports them absent). Client-side mounts (presence JSX, login pages) need `npx luckystack add <feature>` (`@luckystack/cli`) because Vite can't statically import an uninstalled package and file-routing only scans `src/`.
-
-## Related
-
-- Architecture deep-dives: `/docs/ARCHITECTURE_API.md`, `/docs/ARCHITECTURE_SOCKET.md`, `/docs/ARCHITECTURE_PACKAGING.md`, `/docs/HOSTING.md`.
-- README (consumer quickstart): `./README.md`.