@luckystack/server 0.10.1 → 0.11.0

package/docs/create-server.md

@@ -1,329 +1,5 @@
-# Create Server (`createLuckyStackServer` + `bootstrapLuckyStack`)
+# Server creation
 
-> Deep specs. Bron: `packages/server/src/createServer.ts`, `packages/server/src/bootstrap.ts`, `packages/server/src/verifyBootstrap.ts`, `packages/server/src/hookPayloads.ts`, `packages/server/src/types.ts`. Bijgewerkt: 2026-07-22.
+The high-level bootstrap supplies a single place to verify registrations and connect HTTP, sockets and optional feature packages. A lower-level server factory exists for integrations that knowingly take over this responsibility. Starting to listen before critical config and security registrations are ready creates request-time failures; check boot prerequisites first. Source: `../src/bootstrap.ts`, `../src/createServer.ts`, `../src/verifyBootstrap.ts`.
 
-## Overview
-
-`@luckystack/server` exposes two boot entries:
-
-- `bootstrapLuckyStack(options)` — high-level, auto-imports the project's `luckystack/<package>/*.ts` overlay folder in topological order, then delegates to `createLuckyStackServer`. This is what `create-luckystack-app` scaffolds and what most apps should call.
-- `createLuckyStackServer(options)` — low-level factory. Skips overlay loading; the caller is responsible for getting every framework registry populated (project config, deploy config, runtime maps, OAuth providers, etc.) before it runs. Returns `{ httpServer, ioServer, listen }`.
-
-Both honor an explicit pre-flight check via `verifyBootstrap(requirements?)`, which fails fast when a critical registration was forgotten. `createLuckyStackServer` invokes it internally so direct callers don't have to.
-
-Boot order (effective for both entries):
-
-1. `bootstrapLuckyStack` only: load overlay files (`core` -> `deploy` -> `login` -> `email` -> `sentry` -> `presence` -> `cron` -> `docs-ui` -> `server`, each folder topologically followed by alphabetical `*.ts`).
-2. If `options.loadGeneratedMaps` was supplied, register the framework-shipped runtime-maps provider before `verifyBootstrap` so the boot check sees it.
-3. `verifyBootstrap` runs (using the per-call `requireDeployConfig` / `requireServicesConfig` / `requireOAuthProviders` flags). Throws a single descriptive `Error` if anything is missing.
-4. Resolve `port` (`options.port` -> argv-registry override -> `options.defaultPort` -> `80`) and `ip` (`options.ip` -> `SERVER_IP` -> `127.0.0.1`); validate the port in `0..65535` and register the intended address plus configured-default metadata. After listen succeeds, register `httpServer.address().port` as the actually-bound address.
-5. In dev mode (`enableDevTools !== false` and `NODE_ENV !== 'production'`): `initConsolelog()` + dynamic-import `@luckystack/devkit` -> `initializeAll()` + `setupWatchers()`. Initialization status is shared with API/sync dispatchers and `/readyz`; a fatal devkit error keeps all three fail-closed with 503. Install `SIGINT` / `SIGTERM` handlers that force-exit.
-6. `writeBootUuid()` writes a fresh boot UUID to Redis so `/_health` becomes truthful and the router can detect rolling restarts.
-7. Construct `http.createServer(handleHttpRequest)` and `loadSocket(httpServer, { maxHttpBufferSize })`.
-8. Return `{ httpServer, ioServer, listen }`. The HTTP server has NOT started listening yet; after `listen()` binds successfully it starts a non-overlapping boot-UUID heartbeat at one third of the configured TTL. `stop()` / `close()` cancels that heartbeat before graceful shutdown.
-
-## API Reference
-
-### `createLuckyStackServer(options?: CreateLuckyStackServerOptions): Promise<RunningLuckyStackServer>`
-
-**Signature:**
-
-```typescript
-export const createLuckyStackServer = async (
-  options: CreateLuckyStackServerOptions = {}
-): Promise<RunningLuckyStackServer>;
-```
-
-**Parameters:**
-
-| Field | Type | Default | Purpose |
-| --- | --- | --- | --- |
-| `port` | `number \| string` | `getParsedPort()` -> `defaultPort` -> `80` | Explicit HTTP listen port. Numeric strings are accepted; partial/non-integer/out-of-range values fail before `listen`. |
-| `defaultPort` | `number` | `80` | Config-level fallback below explicit `port` + argv; the scaffold passes `config.ports.backend`. It is also recorded so a programmatic `port` can update a callback that still names this default without overriding an unrelated local router ingress. |
-| `ip` | `string` | `process.env.SERVER_IP ?? '127.0.0.1'` | Bind address. Registered so `checkOrigin` and other framework code see the resolved value. |
-| `serveFile` | `StaticFileHandler` | none | Catch-all GET handler (Vite output, SPA `index.html`). Called for `/assets/*`, known static extensions, and the final SPA fallback. Without it the static fallback returns `404`. |
-| `serveFavicon` | `FaviconHandler` | none | Handler for `/favicon.ico`. Without it the route returns `404`. |
-| `customRoutes` | `CustomRouteHandler` | none | Inline custom-route hook. Composed after the registry handlers from `registerCustomRoute(...)`; first one to return `true` wins. |
-| `enableDevTools` | `boolean` | `NODE_ENV !== 'production'` | Toggles `initConsolelog()` + devkit hot reload + REPL. Pass `false` to opt out. |
-| `maxHttpBufferSize` | `number` | `5 * 1024 * 1024` | Forwarded to Socket.io. Raise for large payloads. |
-| `requireDeployConfig` | `boolean` | `false` | When `true`, `verifyBootstrap` fails if no `DeployConfig` was registered. |
-| `requireServicesConfig` | `boolean` | `false` | When `true`, `verifyBootstrap` fails if no `ServicesConfig` was registered (router topology). |
-| `requireOAuthProviders` | `boolean` | `false` | When `true`, `verifyBootstrap` fails if only the default `credentials` provider is registered. |
-| `loadGeneratedMaps` | `(preset: string) => Promise<unknown>` | none | Callback that resolves a generated runtime-maps module per preset. Triggers `registerProdRuntimeMapsProvider` internally. Required because dynamic-import resolution is module-scoped — the framework cannot resolve a relative path on the consumer's behalf. |
-| `runtimeMapsPreset` | `string \| string[]` | argv -> `'default'` | Overrides the argv-derived preset list. |
-
-**Returns:** `RunningLuckyStackServer`:
-
-```typescript
-interface RunningLuckyStackServer {
-  httpServer: http.Server;
-  ioServer: socket.io.Server;
-  listen: (callback?: () => void) => Promise<http.Server>;
-}
-```
-
-`listen()` resolves when the HTTP server is bound. The successful `httpServer.address().port` is registered, advertised to dev tooling, and logged, so `port: 0` reports the OS-assigned port. A busy port auto-increments by default in development (disable with `SERVER_PORT_AUTO_INCREMENT=0`) and fails by default in production. It never retries beyond `65535`. It is safe to call once; calling twice yields a Node `ERR_SERVER_ALREADY_LISTEN` from the underlying `httpServer.listen`.
-
-**Behavior (execution order):**
-
-- Auto-register prod runtime-maps provider if `loadGeneratedMaps` is set.
-- Run `verifyBootstrap` (may throw).
-- Resolve + validate port precedence and ip; call `registerBindAddress({ ip, port })` for the intended address.
-- If dev-tools enabled: load console initializer + devkit (`initializeAll`, `setupWatchers`); attach SIGINT / SIGTERM force-exit handlers.
-- `await writeBootUuid()`.
-- Create `http.Server` whose request handler is `handleHttpRequest(req, res, options)` (see `request-pipeline.md`).
-- `loadSocket(httpServer, { maxHttpBufferSize })` attaches the Socket.io server.
-- Return `{ httpServer, ioServer, listen }` without listening.
-
-**Errors / Edge cases:**
-
-- Throws (from `verifyBootstrap`) when a required registry is missing — single multi-line `Error`.
-- Dev-only branch dynamically imports `@luckystack/devkit`; production bundles exclude it so the import is never reached when `NODE_ENV === 'production'`.
-- `enableDevTools: true` in production loads devkit; this is supported but unusual.
-- SIGINT / SIGTERM handlers are installed only when dev-tools branch runs.
-- `writeBootUuid` failures bubble — boot will abort if Redis is unreachable at start.
-
-**Example — direct boot (skip overlay):**
-
-```typescript
-import 'dotenv/config';
-import './config';
-import './deploy.config';
-import { initializeSentry } from '@luckystack/error-tracking';
-import { registerPresenceHooks } from '@luckystack/presence';
-import { createLuckyStackServer } from '@luckystack/server';
-import { serveFile, serveFavicon } from './prod/serveFile';
-
-initializeSentry();
-registerPresenceHooks();
-
-const server = await createLuckyStackServer({
-  serveFile,
-  serveFavicon,
-  loadGeneratedMaps: (preset) => import(`./prod/generatedApis.${preset}`),
-  requireDeployConfig: true,
-});
-await server.listen();
-```
-
----
-
-### `afterListen(task, options?): Promise<void>`
-
-Runs work that belongs **after** the server is accepting traffic — durable queue
-workers, warm-up passes, reconciliation jobs.
-
-```typescript
-await server.listen();
-
-await server.afterListen(async () => {
-  const { startWorkers } = await import('../src/jobs/workers');
-  await startWorkers();
-}, { label: 'job workers' });
-```
-
-**Why it exists.** The scaffolded `server/server.ts` wraps its boot in an IIFE
-whose `.catch` calls `process.exit(1)`. That is right for everything *before*
-`listen()` — a failure there means there is no server. Appending post-listen work
-to the same chain silently extends "fatal" to tasks that run while the server is
-already serving, so one unreachable dependency (a queue's database, say) kills a
-healthy process. Behind a supervisor that becomes a crash-loop: restart,
-dependency still down, repeat — while the log claims `failed to start` about a
-server that started fine.
-
-| Option | Default | Effect |
-|---|---|---|
-| `fatal` | `false` | `true` re-throws instead of swallowing. Use only when the process genuinely has no purpose without the task. |
-| `label` | `'post-listen task'` | Names the task in the failure log. |
-
-Never resolves to the task's value — it is fire-and-report, not a pipeline stage.
-Read whatever you need inside the callback.
-
----
-
-### `bootstrapLuckyStack(options?: BootstrapLuckyStackOptions): Promise<RunningLuckyStackServer>`
-
-**Signature:**
-
-```typescript
-export const bootstrapLuckyStack = async (
-  options: BootstrapLuckyStackOptions = {}
-): Promise<RunningLuckyStackServer>;
-```
-
-**Parameters:** extends `CreateLuckyStackServerOptions` with:
-
-| Field | Type | Default | Purpose |
-| --- | --- | --- | --- |
-| `overlayRoot` | `string` | `'luckystack'` | Folder name (relative to `ROOT_DIR` from `@luckystack/core`) that holds the per-package overlay files. Absolute paths are honored as-is. |
-| `skipOverlayLoad` | `boolean` | `false` | Skip auto-loading the overlay folder. Useful for tests or hand-built registries. |
-
-**Returns:** identical to `createLuckyStackServer`.
-
-**Behavior:**
-
-- If `skipOverlayLoad !== true` and `<ROOT_DIR>/<overlayRoot>` exists, walk the canonical package order (`core`, `deploy`, `login`, `email`, `sentry`, `presence`, `cron`, `docs-ui`, `server`).
-- Inside each package folder: import `index.ts`/`index.js` first if present, then every remaining `*.ts` / `*.js` file in alphabetical order. Each file is responsible for its own side-effect registration.
-- Then delegate to `createLuckyStackServer(options)`.
-
-**Errors / Edge cases:**
-
-- Missing `<overlayRoot>` folder is non-fatal — the function returns silently so projects can use the legacy single-file `config.ts` layout.
-- Missing per-package subfolders (e.g. no `luckystack/docs-ui/`) are silently skipped.
-- Import errors from overlay files bubble up unchanged; fix the failing module.
-
-**Example — recommended scaffolded boot:**
-
-```typescript
-import '@luckystack/server/parseArgv';
-import 'dotenv/config';
-import './config';
-import './deploy.config';
-import { bootstrapLuckyStack, verifyBootstrap } from '@luckystack/server';
-import { serveFile, serveFavicon } from './prod/serveFile';
-
-const server = await bootstrapLuckyStack({
-  serveFile,
-  serveFavicon,
-  loadGeneratedMaps: (preset) => import(`./prod/generatedApis.${preset}`),
-});
-
-await verifyBootstrap({
-  requireDeployConfig: true,
-  requireOAuthProviders: true,
-});
-
-await server.listen();
-```
-
----
-
-### `verifyBootstrap(requirements?: BootstrapRequirements): Promise<void>`
-
-**Signature:**
-
-```typescript
-export const verifyBootstrap = async (
-  requirements: BootstrapRequirements = {},
-): Promise<void>;
-```
-
-**Parameters:**
-
-| Field | Type | Default | Purpose |
-| --- | --- | --- | --- |
-| `requireDeployConfig` | `boolean` | `false` | Fail unless `registerDeployConfig` has been called. |
-| `requireServicesConfig` | `boolean` | `false` | Fail unless `registerServicesConfig` has been called. |
-| `requireOAuthProviders` | `boolean` | `false` | Fail unless an OAuth provider beyond the default `credentials` entry has been registered. |
-
-**Returns:** `Promise<void>` — resolves silently when every required registry is in place.
-
-**Behavior:**
-
-- Builds a `missing[]` array. Checks in this order:
-  1. `isProjectConfigRegistered()` — always required.
-  2. `isDeployConfigRegistered()` — only when `requireDeployConfig`.
-  3. `isServicesConfigRegistered()` (lazy import) — only when `requireServicesConfig`.
-  4. `getOAuthProviders().length > 1` (lazy import from `@luckystack/login`) — only when `requireOAuthProviders`. Default registry length is `1` (`credentials`).
-  5. `isRuntimeMapsProviderRegistered()` — hard-fail in production, loud `getLogger().warn(...)` in dev/test.
-  6. `isLocalizedNormalizerRegistered()` — hard-fail in production, warn in dev/test.
-- If `missing.length === 0`: return. Otherwise throw a single `Error` whose message lists every missing registration with a one-line remediation hint and points at `docs/ARCHITECTURE_PACKAGING.md`.
-
-**Errors / Edge cases:**
-
-- Throws synchronously after building the missing list. No partial-state recovery.
-- The `RuntimeMapsProvider` warning in dev is intentional: devkit hot-reload normally registers one, so missing it during a bare boot is informational, not fatal.
-- The `LocalizedNormalizer` warning in dev means error responses will surface the raw `errorCode` string instead of localized copy.
-
-**Example:**
-
-```typescript
-import { verifyBootstrap } from '@luckystack/server';
-
-await verifyBootstrap({
-  requireDeployConfig: true,
-  requireServicesConfig: false,
-  requireOAuthProviders: true,
-});
-```
-
-## Hook payload types
-
-Module augmentation in `hookPayloads.ts` extends `@luckystack/core`'s `HookPayloads` interface, so `dispatchHook` / `registerHook` accept these names with the correct payload typing.
-
-| Hook name | Payload type | When it fires |
-| --- | --- | --- |
-| `onSocketConnect` | `OnSocketConnectPayload` (`{ socketId, token, ip }`) | Notification: every successful Socket.io connection. |
-| `onSocketDisconnect` | `OnSocketDisconnectPayload` (`{ socketId, token, reason }`) | Notification: every Socket.io disconnect (with reason string). |
-| `preRoomJoin` | `PreRoomJoinPayload` (`{ token, room }`) | Before the user joins a room. May stop with `HookStopSignal`. |
-| `postRoomJoin` | `PostRoomJoinPayload` (`{ token, room, allRooms }`) | After a successful join. |
-| `preRoomLeave` | `PreRoomLeavePayload` (`{ token, room }`) | Before the user leaves a room. May stop. |
-| `postRoomLeave` | `PostRoomLeavePayload` (`{ token, room, allRooms }`) | After a successful leave. |
-| `onLocationUpdate` | `OnLocationUpdatePayload` (`{ token, oldLocation?, newLocation }`) | When the presence layer reports a location change. |
-
-Naming convention (also documented in `hookPayloads.ts`):
-
-- `on*` — pure notifications; return values are ignored.
-- `pre*` — may return a `HookStopSignal` (`{ errorCode: string; httpStatus?: number }`) to abort the main flow.
-- `post*` — fire after the side-effect succeeds.
-
-## Types
-
-```typescript
-export interface CreateLuckyStackServerOptions { /* see table above */ }
-
-export interface BootstrapLuckyStackOptions extends CreateLuckyStackServerOptions {
-  overlayRoot?: string;
-  skipOverlayLoad?: boolean;
-}
-
-export interface BootstrapRequirements {
-  requireDeployConfig?: boolean;
-  requireServicesConfig?: boolean;
-  requireOAuthProviders?: boolean;
-}
-
-export interface RunningLuckyStackServer {
-  httpServer: http.Server;
-  ioServer: socket.io.Server;
-  listen: (callback?: () => void) => Promise<http.Server>;
-}
-
-export interface RouteContext {
-  routePath: string;
-  method: string;
-  queryString: string | undefined;
-  token: string | null;
-}
-
-export type StaticFileHandler = (req: IncomingMessage, res: ServerResponse) => unknown;
-export type FaviconHandler = (res: ServerResponse) => unknown;
-export type CustomRouteHandler = (
-  req: IncomingMessage,
-  res: ServerResponse,
-  ctx: RouteContext,
-) => Promise<boolean> | boolean;
-```
-
-## Config keys consumed at boot
-
-| Source | Key | Effect |
-| --- | --- | --- |
-| config/argv | `config.ports.ts` backend / positional `[port]` | Static consumer default and per-boot override; no environment port bridge. |
-| env | `SERVER_IP` | IP fallback. |
-| env | `NODE_ENV` | Switches `enableDevTools` default, dynamic-import branch for devkit, and `verifyBootstrap` warn-vs-throw for runtime-maps / localized normalizer. |
-| env | `SECURE` | When `'true'`, session cookies are emitted with the `Secure;` flag (see `request-pipeline.md`). |
-| config | `projectConfig.logging.socketStartup` / `projectConfig.logging.devLogs` | Gates the "Server is running on ..." log line emitted by `listen()`. |
-| config | `projectConfig.http.*` | Route paths + cookie + CORS + stream settings consumed at request time (not at boot). |
-| argv | `<bundles> [port]` | Parsed by `applyServerArgv()` and surfaced via `getParsedBundles()` / `getParsedPort()`. |
-
-## Related
-
-- Function INDEX: `packages/server/CLAUDE.md`
-- README (consumer quickstart): `packages/server/README.md`
-- Argv parsing: `packages/server/docs/argv-parsing.md`
-- Runtime maps: `packages/server/docs/runtime-maps.md`
-- Request pipeline: `packages/server/docs/request-pipeline.md`
-- HTTP routes: `packages/server/docs/http-routes.md`
-- Security: `packages/server/docs/security-defaults.md`
-- Architecture: `docs/ARCHITECTURE_PACKAGING.md`, `docs/ARCHITECTURE_SOCKET.md`, `docs/HOSTING.md`
+Shutdown hooks are best-effort opportunities to flush or drain dependencies, not a veto of termination. Production route maps must not depend on development-only tooling. For types, options and lifecycle implementation see `../src/types.ts`, `../src/afterListen.ts`, `../src/stopServer.ts` and `./runtime-maps.md`.

package/docs/http-routes.md

@@ -1,321 +1,5 @@
-# HTTP Routes
+# HTTP route ownership
 
-> Deep specs. Bron: `packages/server/src/httpHandler.ts`, `packages/server/src/httpRoutes/*.ts`, `packages/server/src/customRoutesRegistry.ts`.
+The server coordinates framework auth, API/sync, health, uploads and consumer routes behind one origin and CSRF boundary. A custom route must not silently bypass those protections; an origin-exempt signed webhook must validate its own signature. A static/SPA fallback must not mask errors from state-changing routes. Source: `../src/httpHandler.ts`, `../src/httpRoutes/`, `../src/customRoutesRegistry.ts`.
 
-## Overview
-
-`@luckystack/server` ships every HTTP route the framework needs: liveness / readiness / health probes, CSRF token issue + middleware, the destructive test-reset endpoint, favicon, uploads, OAuth (`/auth/api` + `/auth/callback`), the dispatcher to `/api/*` and `/sync/*`, custom routes, and a static-file SPA fallback. The orchestrator in `httpHandler.ts` runs them as two ordered tables (PRE_PARAMS and POST_PARAMS). Each handler matches its own route path and returns `boolean`. First handler to return `true` (or end the response) terminates dispatch.
-
-Pre-params handlers (no body parse) run first so probes, favicon, and CSRF stay cheap:
-
-1. `handleCsrfRoute` — `/auth/csrf`
-2. `handleFaviconRoute` — `/favicon.ico`
-3. `handleLivezRoute` — `projectConfig.http.liveEndpoint` (default `/livez`)
-4. `handleReadyzRoute` — `projectConfig.http.readyEndpoint` (default `/readyz`)
-5. `handleHealthRoute` — `projectConfig.http.healthEndpoint` (default `/_health`)
-6. `handleTestResetRoute` — `projectConfig.http.testResetEndpoint` (default `/_test/reset`)
-
-Post-params handlers (after body parsing) run next:
-
-1. `handleUploadsRoute` — `/uploads/*`
-2. `handleAuthEmailCodeRoute` — `/auth/api/email-code/request|verify` (ADR 0024; BEFORE the `/auth/api/*` catch-all)
-3. `handleAuthTwoFactorRoute` — `/auth/api/2fa` + `/auth/api/2fa/*` (ADR 0024; BEFORE the `/auth/api/*` catch-all)
-4. `handleAuthApiRoute` — `/auth/api/*`
-5. `handleAuthCallbackRoute` — `/auth/callback/*`
-6. `handleApiRoute` — `/api/*` (delegates to `@luckystack/api`)
-7. `handleSyncRoute` — `/sync/*` (delegates to `@luckystack/sync`)
-8. `handleCustomRoutes` — every handler from `registerCustomRoute(...)` + `options.customRoutes`
-9. `handleStaticAndSpaFallback` — `/assets/*`, known extensions, SPA `index.html`
-
-A custom-route registry sits in front of the static fallback. Both the legacy `customRoutes` option on `CreateLuckyStackServerOptions` and the global `registerCustomRoute(...)` registry are honored. Errors in custom handlers are caught and reported as `500 server.customRouteFailed`; the request loop is never crashed by a misbehaving handler.
-
-## Framework route reference
-
-| Route | Method(s) | Handler | Response (success) | Response (failure) |
-| --- | --- | --- | --- | --- |
-| `/auth/csrf` | GET | `handleCsrfRoute` | `200 { status: 'success', csrfToken }`; without login it also sets the double-submit cookie | `401 auth.unauthenticated` only when login is installed and no valid session exists |
-| `/favicon.ico` | GET | `handleFaviconRoute` | Whatever `options.serveFavicon(res)` writes | `404` empty when no handler supplied |
-| `/livez` | GET | `handleLivezRoute` | `200 { status: 'live' }` | Always 200 when reachable |
-| `/readyz` | GET | `handleReadyzRoute` | `200 { status: 'ready', checks: {...} }` | `503 { status: 'not-ready', checks: {...} }` |
-| `/_health` | GET | `handleHealthRoute` | `200 { status: 'ok', bootUuid, envKey, synchronizedHashes }` | `503 { status: 'degraded', ... }` when boot UUID is missing |
-| `/_test/reset` | POST | `handleTestResetRoute` | `200 { status: 'success', cleared: string[] }` | `404 notFound` or `403 auth.forbidden` — see `security-defaults.md` |
-| `/uploads/*` | GET | `handleUploadsRoute` | Avatar bytes via `@luckystack/core` `serveAvatar` | `404` from `serveAvatar` when missing |
-| `/auth/api/email-code/request` | POST | `handleAuthEmailCodeRoute` | `200 { status: true }` (anti-enumeration: also for unknown addresses) | `200 { status:false, reason }`, `429` per-IP |
-| `/auth/api/email-code/verify` | POST | `handleAuthEmailCodeRoute` | Login envelope + session transport, or 2FA-challenge envelope | `200 { status:false, reason }`, `429` per-IP |
-| `/auth/api/2fa` | POST | `handleAuthTwoFactorRoute` | Login envelope + session transport (completes the challenge) | `200 { status:false, reason }`, `429` per-IP |
-| `/auth/api/2fa/email-code` | POST | `handleAuthTwoFactorRoute` | `200 { status: true }` (fallback code sent) | `200 { status:false, reason }`, `429` per-IP |
-| `/auth/api/2fa/setup\|enable\|disable\|recovery-codes` | POST (authed) | `handleAuthTwoFactorRoute` | `200 { status:true, secret/otpauthUri \| recoveryCodes[] }` | `401 api.unauthorized` without session; `200 { status:false, reason }` |
-| `/auth/api/*` | POST | `handleAuthApiRoute` | OAuth redirect (`302`) or credentials login envelope (may carry `requiresTwoFactor` + `challengeToken`) | Rate-limited envelope, `200` envelope with `status:false, reason` |
-| `/auth/callback/*` | GET | `handleAuthCallbackRoute` | `302` to `redirectUrl` with session cookie or token | `401 'Login failed'` plain text |
-| `/api/*` | GET / POST / PUT / DELETE | `handleApiRoute` | JSON envelope from `@luckystack/api` `handleHttpApiRequest`, or SSE stream | `400 api.invalidName`, `500 api.invalidRequestFormat` |
-| `/sync/*` | POST | `handleSyncRoute` | JSON envelope from `@luckystack/sync` `handleHttpSyncRequest`, or SSE stream | `405 sync.methodNotAllowed`, `400 sync.invalidName`, `500 sync.invalidRequestFormat` |
-| `/assets/*`, `*.{png,jpg,jpeg,gif,svg,html,css,js}` | GET | `handleStaticAndSpaFallback` | Whatever `options.serveFile` writes (URL temporarily rewritten) | `404` when no `serveFile` is wired |
-| Any other extension-less path | GET | `handleStaticAndSpaFallback` | SPA fallback (rewrite URL to `/`, call `serveFile`) | `404` when no `serveFile` |
-
-> `GET /auth/csrf` issues the token; state-changing requests send it using `getCsrfConfig().headerName` (default `x-csrf-token`). `registerCsrfConfig(...)` also controls the login-absent cookie name/options and token length.
->
-> `/_test/reset` clears rate limits and only the framework's default Redis session/active-user namespaces. It does not clear application database rows or invoke a custom `SessionAdapter`; custom-storage tests own that cleanup.
-
-## API Reference — handlers
-
-All handlers conform to:
-
-```typescript
-type HttpRouteHandler = (ctx: HttpRouteContext) => Promise<boolean>;
-
-interface HttpRouteContext {
-  req: IncomingMessage;
-  res: ServerResponse;
-  options: CreateLuckyStackServerOptions;
-  routePath: string;
-  queryString: string | undefined;
-  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
-  token: string | null;
-  requestId: string;
-  sessionCookieOptions: string;
-  params: object;
-}
-```
-
-A handler returns `true` (or simply ends `res`) to short-circuit dispatch; returning `false` falls through to the next handler.
-
-### `handleLivezRoute(ctx)`
-
-**Behavior:**
-
-- Matches when `routePath === projectConfig.http.liveEndpoint` (default `/livez`).
-- Always emits `200 application/json { status: 'live' }`.
-
-**Edge cases:** no downstream dependencies; succeeds as long as the Node event loop is responsive.
-
-### `handleReadyzRoute(ctx)`
-
-**Behavior:**
-
-- Matches when `routePath === projectConfig.http.readyEndpoint` (default `/readyz`).
-- Reads the shared `DevToolsStatus`, `readBootUuid()` (Redis), `redis.ping()`, and a database check (ADR 0020):
-  1. a consumer-registered `registerDbHealthCheck(...)` probe (from `@luckystack/core`) wins;
-  2. otherwise the built-in Prisma probe runs when Prisma is part of the install (`isPrismaClientRegistered()` or a resolvable `@prisma/client`) — provider-agnostic: tries `$queryRaw\`SELECT 1\`` first, then `$runCommandRaw({ ping: 1 })` (detecting the active provider via private fields drifts between Prisma majors, so it probes by capability);
-  3. otherwise the check reports `'skipped'` — a deliberately DB-less project (`orm: 'none'`) can still go ready.
-- Returns `200 { status: 'ready', checks }` when devkit did not fail, boot UUID + Redis pass, and the database check is not `false`; `503 { status: 'not-ready', ... }` otherwise. `checks.devTools` is `true` before/after a successful initialization and `false` after a recorded fatal failure. `checks.database` carries the tri-state (`true | false | 'skipped'`); `checks.prisma` is kept for backward compatibility (`true` when the database check passed or was skipped).
-
-**Edge cases:**
-
-- A recorded devkit error forces 503 even when Redis/database probes pass, so an incomplete runtime cannot advertise readiness just because infrastructure is green.
-- `redis.ping()` errors are swallowed and surface as `redis: false`.
-- A Prisma client with neither raw method available results in `prismaOk = false`.
-
-### `handleHealthRoute(ctx)`
-
-**Behavior:**
-
-- Matches when `routePath === projectConfig.http.healthEndpoint` (default `/_health`).
-- Reads `bootUuid`, `resolveEnvKey()`, and `computeSynchronizedEnvHashes()` from `@luckystack/core`.
-- Returns `200 { status: 'ok', bootUuid, envKey, synchronizedHashes }` when boot UUID is present, otherwise `503 { status: 'degraded', ... }`.
-- Consumed by `@luckystack/router` to verify shared-Redis topology after a rolling restart.
-
-### `handleCsrfRoute(ctx)`
-
-**Behavior:**
-
-- Matches `routePath === '/auth/csrf'`.
-- Requires a session token (cookie or `Authorization`). Returns `401 auth.unauthenticated` when missing or when `getSession(token)` does not resolve a valid session.
-- On success returns `200 { status: 'success', csrfToken }`.
-
-**Note:** the matching middleware is `enforceCsrfOnStateChangingRequest` (see `request-pipeline.md`). This route only issues tokens.
-
-### `handleFaviconRoute(ctx)`
-
-**Behavior:**
-
-- Matches `routePath === '/favicon.ico'`.
-- Delegates to `options.serveFavicon(res)`. Without that option, returns an empty `404`.
-
-### `handleUploadsRoute(ctx)`
-
-**Behavior:**
-
-- Matches every path starting with `/uploads/`.
-- Delegates to `serveAvatar({ routePath, res })` from `@luckystack/core`. Response (and `404` on miss) is owned by `serveAvatar`.
-
-### `handleAuthApiRoute(ctx)`
-
-**Behavior:**
-
-- Matches `routePath` starting with `/auth/api`.
-- Looks up the provider via `getOAuthProviders().find((p) => p.name === routePath.split('/')[3])`.
-- For full OAuth providers (`isFullOAuthProvider(provider)`):
-  - `createOAuthState(provider.name)` produces a CSRF state token; failure returns `500 login.oauthStateInitFailed`.
-  - Builds the provider's authorization URL with `client_id`, `redirect_uri`, `scope`, `response_type=code`, `prompt=select_account`, `state`, and emits a `302`.
-- For credentials provider:
-  - Applies an IP-keyed rate limit (`key: ip:<remote>:auth:credentials`) using `projectConfig.rateLimiting.defaultApiLimit` + `windowMs`. On hit, dispatches `rateLimitExceeded` hook and returns `{ status: false, reason: 'api.rateLimitExceeded', errorParams: [{ key: 'seconds', value: resetIn }] }`.
-  - Calls `loginWithCredentials(params)`. On success: delete existing session, choose cookie-based vs header-based token via `x-session-based-token` header (overrides `projectConfig.session.basedToken`), then emit `Set-Cookie` or `X-Session-Token`.
-  - Final envelope: `{ status, reason, session, authenticated }`.
-
-**Errors:** unknown provider -> `{ status: false, reason: 'login.providerNotFound' }`; thrown errors bubble to the outer `httpHandler` error path.
-
-### `handleAuthCallbackRoute(ctx)`
-
-**Behavior:**
-
-- Matches `routePath` starting with `/auth/callback`.
-- Computes `baseLocation = projectConfig.app.publicUrl || '/'` (the public origin where users browse; the OAuth callback is handled on the backend origin but redirects the browser back here). `||` so an empty `publicUrl` falls through to `/`.
-- Delegates to `loginCallback(routePath, req, res, { defaultRedirectUrl })` from `@luckystack/login`.
-- On failure: `401 'Login failed'`.
-- On success: delete existing session, then redirect (`302`). With `projectConfig.session.basedToken: true` the token rides as `?token=...` in the query; otherwise it's emitted as a session cookie.
-
-### `handleApiRoute(ctx)`
-
-**Behavior:**
-
-- Matches every path starting with `/api/`.
-- Detects SSE intent via `shouldUseHttpStream({ acceptHeader, queryString })`: returns true if `Accept` contains `text/event-stream` or `?<projectConfig.http.stream.queryParam>=<enabledValue>` (or `=1`). When true, initializes an SSE response header and tracks client disconnect via `req.on('close', ...)`.
-- Strips `/api/` prefix; empty name -> `400 api.invalidName` (or SSE `final` event with same payload).
-- Calls `handleHttpApiRequest({ name, data, token, requesterIp, xLanguageHeader, acceptLanguageHeader, method, stream? })` from `@luckystack/api`. The `stream` callback emits `event: stream` SSE frames during long-running calls.
-- Emits the result (`event: final` for SSE, or `JSON.stringify(result)` + `res.writeHead(result.httpStatus)` for non-SSE).
-
-**Errors:** any thrown error is logged + captured by the registered error tracker(s), `apiError` hook dispatched, and the envelope `500 api.invalidRequestFormat` is returned (over SSE or JSON).
-
-### `handleSyncRoute(ctx)`
-
-**Behavior:**
-
-- Matches every path starting with `/sync/`.
-- Only `POST` is allowed; other methods return `405 sync.methodNotAllowed`.
-- Normalizes params into `{ data, receiver, ignoreSelf?, cb? }`. Empty `receiver` is allowed (`''`).
-- Calls `handleHttpSyncRequest({ name: 'sync/<rest>', cb, data, receiver, ignoreSelf, token, requesterIp, xLanguageHeader, acceptLanguageHeader, stream? })` from `@luckystack/sync`.
-- SSE handling mirrors `handleApiRoute`.
-
-**Errors:** mirrors `handleApiRoute` — logs, registered error tracker(s), `syncError` hook, returns `500 sync.invalidRequestFormat`.
-
-### `handleCustomRoutes(ctx)`
-
-**Behavior:**
-
-- Iterates every handler registered via `registerCustomRoute(...)` in registration order; first one to return `true` or end the response wins.
-- If none handled, falls back to the inline `options.customRoutes` if provided.
-- Each handler is wrapped in `tryCatch` — on throw it logs via `getLogger().error`, calls `captureException`, and emits `500 server.customRouteFailed` (returning `true` so dispatch stops).
-
-### `handleStaticAndSpaFallback(ctx)`
-
-**Behavior:**
-
-- `/assets/*` paths: matched via `startsWith('/assets/')`; the (percent-decoded) routePath is rejected with `404` when it contains `..` (path-traversal guard at the framework boundary), then `req.url` is temporarily rewritten to the routePath, `options.serveFile` is called, and `req.url` restored. Without `serveFile`, returns `404 Not Found`.
-- Paths matching `KNOWN_STATIC_FILE_REGEX` (`/^\/(assets\/[a-zA-Z0-9_\-/]+|[a-zA-Z0-9_\-]+)\.(png|jpg|jpeg|gif|svg|html|css|js)$/`): call `serveFile` directly without URL rewrite.
-- Other paths that have an extension `path.extname(routePath)`: `404 Not Found` (text/plain).
-- Extensionless paths (SPA routes): rewrite `req.url` to `/`, call `serveFile`. Without `serveFile`, returns `404 Not Found`.
-
-**Why the rewrite around `serveFile`:** consumers (Vite, custom static middleware) read `req.url`. We swap then restore so downstream loggers / metrics see the original URL.
-
-## Custom-route registry
-
-```typescript
-export const registerCustomRoute: (handler: CustomRouteHandler) => void;
-export const getCustomRoutes: () => readonly CustomRouteHandler[];
-export const clearCustomRoutes: () => void;
-```
-
-- `registerCustomRoute(handler)` — appends to an in-memory array. Called by overlay packages (`@luckystack/docs-ui` mounts `/_docs` this way).
-- `getCustomRoutes()` — read snapshot; iterated by `handleCustomRoutes`.
-- `clearCustomRoutes()` — empty the array; used by `@luckystack/test-runner`'s reset flow.
-
-The handler signature:
-
-```typescript
-type CustomRouteHandler = (
-  req: IncomingMessage,
-  res: ServerResponse,
-  ctx: RouteContext,
-) => Promise<boolean> | boolean;
-
-interface RouteContext {
-  routePath: string;
-  method: string;
-  queryString: string | undefined;
-  token: string | null;
-}
-```
-
-Return `true` (or end the response) when handled. Throws are caught and emit `500 server.customRouteFailed`.
-
-**Example — webhook receiver:**
-
-```typescript
-import { registerCustomRoute } from '@luckystack/server';
-
-registerCustomRoute(async (req, res, ctx) => {
-  if (ctx.routePath !== '/webhooks/stripe') return false;
-  if (ctx.method !== 'POST') {
-    res.writeHead(405);
-    res.end();
-    return true;
-  }
-  // verify signature, process body ...
-  res.writeHead(200);
-  res.end('ok');
-  return true;
-});
-```
-
-**Example — health alias for an external monitor:**
-
-```typescript
-registerCustomRoute(async (_req, res, ctx) => {
-  if (ctx.routePath !== '/healthz') return false;
-  res.statusCode = 200;
-  res.end('ok');
-  return true;
-});
-```
-
-## SSE streaming
-
-`/api/*` and `/sync/*` both support Server-Sent Events when the client opts in. Helpers live in `packages/server/src/sse.ts`:
-
-| Helper | Behavior |
-| --- | --- |
-| `shouldUseHttpStream({ acceptHeader, queryString })` | Returns `true` if `Accept` includes `text/event-stream` OR the query string contains `<projectConfig.http.stream.queryParam>=<enabledValue>` (or `=1`). |
-| `initSseResponse(res)` | Writes `200` with `Content-Type: text/event-stream`, `Cache-Control: no-cache, no-transform`, `Connection: keep-alive`, `X-Accel-Buffering: no`. Emits `projectConfig.http.stream.connectedComment` as a keepalive comment if configured. |
-| `sendSseEvent({ res, event, data })` | Writes `event: <event>\ndata: <json>\n\n`. No-op once `res.writableEnded`. |
-
-Lifecycle in `handleApiRoute` / `handleSyncRoute`:
-
-1. Decide SSE vs JSON via `shouldUseHttpStream`.
-2. If SSE, call `initSseResponse(res)` and `req.on('close', () => { streamClosed = true; })`.
-3. Pass a `stream` callback to `handleHttpApiRequest` / `handleHttpSyncRequest` that emits `event: stream` frames while the request is processing.
-4. On completion, emit `event: final` with the result envelope and call `res.end()`.
-5. On error, emit `event: error` with the `500 *.invalidRequestFormat` envelope.
-
-## Hooks dispatched
-
-| Hook | Payload | When |
-| --- | --- | --- |
-| `rateLimitExceeded` | `{ scope, key, limit, windowMs, count, route, ip }` | `handleAuthApiRoute` credentials path when IP limit is exceeded. |
-| `apiError` | `{ route, method, requestId, error }` | `handleApiRoute` outer error path. |
-| `syncError` | `{ route, method, requestId, error }` | `handleSyncRoute` outer error path. |
-| `csrfMismatch` | `{ route, method, requestId, userId, providedToken }` | `enforceCsrfOnStateChangingRequest` (see `request-pipeline.md`). |
-| `preHttpRequest` | `{ method, url, requestId, origin, headers }` | Every incoming request before dispatch (see `request-pipeline.md`). |
-
-## Config keys consumed
-
-| Source | Key | Effect |
-| --- | --- | --- |
-| config | `projectConfig.http.healthEndpoint` | Default `/_health`. |
-| config | `projectConfig.http.liveEndpoint` | Default `/livez`. |
-| config | `projectConfig.http.readyEndpoint` | Default `/readyz`. |
-| config | `projectConfig.http.testResetEndpoint` | Default `/_test/reset`. |
-| config | `projectConfig.http.stream.queryParam` / `enabledValue` / `connectedComment` | SSE opt-in query parameter + initial keepalive comment. |
-| config | `projectConfig.http.sessionCookieName` | Cookie name written by `/auth/api` / `/auth/callback`. |
-| config | `projectConfig.session.basedToken` | Cookie vs header token transport. |
-| config | `projectConfig.rateLimiting.defaultApiLimit` / `windowMs` | Credentials login rate limit. |
-| config | `projectConfig.app.publicUrl` | Public origin the OAuth callback redirects the browser back to. |
-| env | `TEST_RESET_TOKEN` | Consumed by `/_test/reset` — see `security-defaults.md`. |
-
-## Related
-
-- Function INDEX: `packages/server/CLAUDE.md`
-- Request pipeline: `packages/server/docs/request-pipeline.md`
-- Security defaults: `packages/server/docs/security-defaults.md`
-- API delegate: `docs/ARCHITECTURE_API.md`
-- Sync delegate: `docs/ARCHITECTURE_SYNC.md`
-- README: `packages/server/README.md`
+Health and test routes have different trust models: health probes need to work without browser headers, while the test reset route must fail closed in production and without its token. The reset can be scoped to named targets so an authenticated test sweep can drain rate-limit buckets without deleting its own session; the unscoped reset keeps its original meaning (ADR 0064, details in `./security-defaults.md`). Streaming requires an HTTP response lifecycle distinct from ordinary JSON, but keeps the same auth gates. See `./security-defaults.md`, `../src/httpRoutes/healthRoutes.ts`, `../src/httpRoutes/testResetRoute.ts`, `../src/sse.ts`.