@luckystack/server 0.10.2 → 0.11.0

package/AGENTS.md

@@ -0,0 +1,7 @@
+# @luckystack/server — design context
+
+Server owns boot order and the single HTTP/Socket.io security perimeter. Use the high-level bootstrap for normal deployments, and the lower-level entry only when taking responsibility for the missing registrations and checks. Source: `src/bootstrap.ts`, `src/createServer.ts`, `src/verifyBootstrap.ts`.
+
+Never treat CORS as authentication. The HTTP origin gate has no Host-header fallback; requests without a browser-attributable origin are rejected for state changes unless deliberately exempted. Exemptions for signed webhooks remove the origin/CSRF check, not the requirement to verify the caller in the route. Keep cookie-mode CSRF protection on state-changing custom routes and login bootstrap exceptions narrowly defined. Socket origin/auth checks and HTTP route checks are separate boundaries. Source: `src/httpHandler.ts`, `src/httpRoutes/csrfMiddleware.ts`, `src/originExemptRegistry.ts`, `src/loadSocket.ts`.
+
+The test-reset endpoint must fail closed outside explicit test/development mode and without a secret. Its scoped targets come from core's shared list so server and test-runner cannot drift; an unknown target is an error, and the unscoped reset keeps its meaning (ADR 0064). Do not allow development map loading or tools to leak into production. See `docs/security-defaults.md`, `docs/runtime-maps.md`, `../login/AGENTS.md`.

package/CHANGELOG.md

@@ -5,12 +5,18 @@ All notable changes to `@luckystack/server` are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.11.0] - 2026-10-14
+
+### Changed
+
+- Type declarations are emitted per source file by TypeScript 7 (`tsc -b`) instead of one bundled `.d.ts` per entry, so the framework build no longer runs package by package. The exported types are unchanged; relative imports inside the declarations carry `.js`, so `moduleResolution: "node16"`/`"nodenext"` projects resolve them as before.
+- Package design guidance now ships as `AGENTS.md`, not `CLAUDE.md`. Handwritten docs focus on rationale and safety; exact API contracts remain in installed declarations/source.
+
 ## [0.10.2] - 2026-10-09
 
 ### Added
 
 - `/_test/reset` accepts `?only=<target>[,<target>]` to clear exactly those targets (the shared list in core `TEST_RESET_TARGETS`). An unknown or empty target is `400 test.invalidResetTarget` — a typo must not silently reset nothing, or everything. Without `only` the default reset is unchanged. This lets an authenticated test sweep drain limiter buckets without deleting its own session.
-
 ## [0.8.7] - 2026-08-18
 
 ### Added

package/README.md

@@ -1,203 +1,5 @@
 # @luckystack/server
 
-> One-call server bootstrap for [LuckyStack](https://github.com/ItsLucky23/LuckyStack-v2). HTTP + Socket.io + framework routes (`/api/*`, `/sync/*`, `/_health`, `/_test/reset`, `/auth/*`, `/uploads/*`) wired together. Your `server.ts` shrinks to ~20 lines.
+Bootstrap for LuckyStack HTTP and Socket.io. Install with `npm install @luckystack/server socket.io`; add feature packages such as `@luckystack/api` or `@luckystack/sync` only when used (optional peers in `package.json`). Prefer `bootstrapLuckyStack` for ordinary boot: register project configuration, bootstrap with your application's static-file handlers, run `verifyBootstrap` after registration, then listen. `createLuckyStackServer` requires ownership of registration and readiness checks. See `src/bootstrap.ts` and `src/verifyBootstrap.ts` for current requirements.
 
-## Install
-
-```bash
-npm install @luckystack/server socket.io
-
-# Add the features your project uses; the server auto-detects these optional peers.
-# For the standard API + realtime stack, for example:
-npm install @luckystack/api @luckystack/sync
-```
-
-## Quickstart — recommended (`bootstrapLuckyStack`)
-
-`bootstrapLuckyStack` is a thin wrapper around `createLuckyStackServer` that auto-imports your `luckystack/<pkg>/*.ts` overlay files in topological order before listening, so registries (DI, hooks, providers) are populated by the time the HTTP server boots. This is what `create-luckystack-app` scaffolds.
-
-```ts
-import 'dotenv/config';
-import '../config';            // your registerProjectConfig(...)
-import '../deploy.config';     // your registerDeployConfig(...)
-import '../services.config';   // your registerServicesConfig(...)
-
-import { bootstrapLuckyStack } from '@luckystack/server';
-import { serveFile, serveFavicon } from './prod/serveFile';
-
-const server = await bootstrapLuckyStack({
-  serveFile,
-  serveFavicon,
-});
-
-await server.listen();
-```
-
-The bootstrap call runs (in order):
-
-1. Auto-imports `luckystack/core/*.ts`, `luckystack/deploy/*.ts`, `luckystack/login/*.ts`, `luckystack/email/*.ts`, `luckystack/sentry/*.ts`, `luckystack/presence/*.ts`, `luckystack/cron/*.ts`, `luckystack/docs-ui/*.ts`, `luckystack/server/*.ts` (topologically sorted, then alphabetically inside each folder).
-2. Hands off to `createLuckyStackServer(options)`.
-
-Set `skipOverlayLoad: true` to handle every registration yourself, or `overlayRoot: 'custom-folder'` to load from somewhere other than `./luckystack`.
-
-### Pre-flight check — `verifyBootstrap`
-
-Call `verifyBootstrap` **after** the overlay loads (or after your manual registrations) and **before** `server.listen()` if you want to fail fast on missing registrations instead of silent runtime crashes:
-
-```ts
-import { bootstrapLuckyStack, verifyBootstrap } from '@luckystack/server';
-
-const server = await bootstrapLuckyStack({ serveFile, serveFavicon });
-
-await verifyBootstrap({
-  requireDeployConfig: true,    // single-instance deploys can omit this
-  requireServicesConfig: true,  // only true when the router will run
-  requireOAuthProviders: true,  // false if you only use credentials login
-});
-
-await server.listen();
-```
-
-`verifyBootstrap` throws a single descriptive `Error` listing every missing registration. The full check covers:
-
-- `ProjectConfig` — always required.
-- `DeployConfig` — when `requireDeployConfig: true`.
-- `ServicesConfig` — when `requireServicesConfig: true`.
-- OAuth providers — when `requireOAuthProviders: true` and only the default `credentials` entry has been registered.
-- `RuntimeMapsProvider` — hard-fails in production; loud-warns in dev because devkit hot-reload normally registers one. Without it, every API/sync request silently resolves to `notFound`.
-- `LocalizedNormalizer` — hard-fails in production; warns in dev. Without it, error responses degrade to `errorCode`-as-message (no i18n).
-
-## Lower-level entry — `createLuckyStackServer`
-
-Use this directly when you want to control the order of imports yourself or skip the overlay convention:
-
-```ts
-import { initializeSentry } from '@luckystack/error-tracking';
-import { registerPresenceHooks } from '@luckystack/presence';
-import { createLuckyStackServer } from '@luckystack/server';
-
-initializeSentry();
-registerPresenceHooks();
-
-const server = await createLuckyStackServer({
-  serveFile,
-  serveFavicon,
-});
-await server.listen();
-```
-
-Both entries handle devkit hot reload + console init in dev mode automatically — opt out with `enableDevTools: false` if you have your own.
-
-## Options
-
-```ts
-interface CreateLuckyStackServerOptions {
-  port?: number | string;          // options.port > argv > defaultPort > 80
-  defaultPort?: number;             // scaffold's config.ports.ts backend default
-  ip?: string;                     // default: process.env.SERVER_IP ?? '127.0.0.1'
-  serveFile?: StaticFileHandler;   // catch-all for non-framework GETs (Vite output, SPA fallback)
-  serveFavicon?: FaviconHandler;   // /favicon.ico
-  customRoutes?: CustomRouteHandler; // pre-fallback hook; return true to mark handled
-  enableDevTools?: boolean;        // default: NODE_ENV !== 'production'
-  maxHttpBufferSize?: number;      // default: 5 MB
-}
-```
-
-`customRoutes` runs before the static file serving, so you can add project-specific HTTP endpoints (webhooks, OG image generation, etc.) without forking the package. Return `true` if you ended the response.
-
-You can also register custom routes globally via `registerCustomRoute(handler)` — the bootstrap call composes every registered handler into the running server. This is what `@luckystack/docs-ui` uses to mount `/_docs`.
-
-```ts
-import { registerCustomRoute } from '@luckystack/server';
-
-registerCustomRoute(async (req, res) => {
-  if (req.url !== '/healthz') return false;
-  res.statusCode = 200;
-  res.end('ok');
-  return true;
-});
-```
-
-## What it wires
-
-- **HTTP server** with CORS + security headers, OPTIONS preflight, method validation, cookie sliding, CSRF middleware.
-- **Socket.io server** attached to the HTTP server, with optional Redis adapter when configured in deploy config.
-- **Framework routes:** `/_health`, `/livez`, `/readyz`, `/_test/reset` (dev/test only), `/api/*` and `/sync/*` (with SSE streaming), `/auth/api`, `/auth/callback/*`, `GET /auth/csrf`, `/uploads/*`, and `/assets/*`.
-- **Presence broadcasting** (when enabled in project config): connect / disconnect / reconnect, location updates, peer notifications.
-- **Boot UUID** written on startup so the load-balancer (`@luckystack/router`) can detect rolling restarts.
-- **Dev tools** in non-production: devkit hot reload, console initializer.
-
-### HTTP route handler layout
-
-`handleHttpRequest` is now a thin (~190-line) orchestrator that sets up CORS / origin / security headers, runs the CSRF middleware, then dispatches a route-handler table. Each handler matches its own route path and returns `boolean` (handled or not). The handlers live in `packages/server/src/httpRoutes/`:
-
-| File | Routes |
-| --- | --- |
-| `csrfMiddleware.ts` + `csrfRoute.ts` | CSRF guard on cookie-mode writes + `GET /auth/csrf` token issue |
-| `healthRoutes.ts` | `/livez`, `/readyz`, `/_health` |
-| `testResetRoute.ts` | `/_test/reset` (dev/test only — see Security below) |
-| `faviconRoute.ts` | `/favicon.ico` |
-| `uploadsRoute.ts` | `/uploads/*` (avatar serving via `serveAvatar`) |
-| `authApiRoute.ts` | `/auth/api/*` |
-| `authCallbackRoute.ts` | `/auth/callback/*` |
-| `apiRoute.ts` | `/api/*` (delegates to `@luckystack/api`'s `handleHttpApiRequest`) |
-| `syncRoute.ts` | `/sync/*` (delegates to `@luckystack/sync`'s `handleHttpSyncRequest`) |
-| `customRoutes.ts` | Calls every handler registered via `registerCustomRoute(...)` and the inline `customRoutes` option |
-| `staticRoutes.ts` | Final fallback to the consumer's `serveFile(...)` (Vite SPA, etc.) |
-
-Top-level `handleHttpRequest` + `dispatchRoutes(handlers, ctx)` are the only orchestration; everything else is a flat list of single-purpose handlers. SSE handling, error fall-through, and dispatch order are preserved.
-
-### Security defaults that may surprise you
-
-- **CORS fail-closed.** If neither `Origin` nor `Referer` is present, only read-only methods (GET, HEAD, OPTIONS) are allowed; state-changing methods are rejected with 403. Earlier builds fell back to `Host`, which silently bypassed CORS for non-browser callers (`curl`, server-to-server). When you `curl` a write endpoint, set `-H 'Origin: https://your-allowed-origin'`.
-- **`/_test/reset` is fail-closed.** It requires both `NODE_ENV` to be exactly `development` or `test` AND a non-empty `TEST_RESET_TOKEN` env var. Any other state returns 403 (no silent allow-list). Wire `TEST_RESET_TOKEN` in your dev/test `.env.local` and pass it as the `x-test-reset-token: ${TOKEN}` header on the reset call. `@luckystack/test-runner`'s `resetServerState` reads the same env var.
-- **CSRF middleware.** In cookie mode, state-changing framework routes and eligible custom routes require the configured CSRF header (default `x-csrf-token`). With login installed it must match the session-bound token; without login it must match the stateless double-submit cookie issued by `GET /auth/csrf`. The `apiRequest` helper in `@luckystack/core/client` fetches and attaches it automatically. Auth bootstrap/callback routes and explicitly origin-exempt paths are excluded. Rejections dispatch `csrfMismatch` before returning 403; the hook receives token presence only, never the value. Configure the header name, token length, and cookie name/options through `registerCsrfConfig(...)` — see `packages/core/docs/csrf-config.md` and `packages/server/docs/security-defaults.md`.
-
-## Public API
-
-| Export | Purpose |
-| --- | --- |
-| `bootstrapLuckyStack(options)` | High-level entry: verifies config, auto-imports overlay, then calls `createLuckyStackServer`. |
-| `createLuckyStackServer(options)` | Lower-level factory that returns `{ httpServer, ioServer, listen, stop, close }` (`stop`/`close` = graceful MIS-016 shutdown). |
-| `verifyBootstrap(requirements?)` | Pre-flight check for project/deploy/services config and required env keys. |
-| `registerCustomRoute(handler)` / `getCustomRoutes()` / `clearCustomRoutes()` | Global custom-route registry composed by `bootstrapLuckyStack`. |
-| Hook payload types: `OnSocketConnectPayload`, `OnSocketDisconnectPayload`, `PreRoomJoinPayload`, `PostRoomJoinPayload`, `PreRoomLeavePayload`, `PostRoomLeavePayload`, `OnLocationUpdatePayload` | For socket-lifecycle hook handlers. |
-| Types: `CreateLuckyStackServerOptions`, `BootstrapLuckyStackOptions`, `BootstrapRequirements`, `RunningLuckyStackServer`, `RouteContext`, `StaticFileHandler`, `FaviconHandler`, `CustomRouteHandler` | Handler typing. |
-
-## Dependencies
-
-- Runtime: `@luckystack/api`, `@luckystack/core`
-- Required peer: `socket.io@^4.8.0`
-- Optional peers: `@prisma/client@^6.19.0`, `@luckystack/login`, `@luckystack/presence`, `@luckystack/sync`, `@luckystack/error-tracking`, `@luckystack/email`, `@luckystack/cron`, `@luckystack/docs-ui`, and `@luckystack/devkit` (dev-only). Bootstrap auto-detects installed optional peers and degrades when they are absent.
-
-## Selecting bundles + port at runtime
-
-`@luckystack/server/parseArgv` is a side-effect-only entrypoint. Import it as the **first line** of your `server.ts` so a positional CLI port reaches the browser-safe `@luckystack/core/config` registry before your project's `config.ts` evaluates.
-
-```ts
-// server.ts
-import '@luckystack/server/parseArgv';
-// ...rest of your bootstrap
-```
-
-Argv shape: `<bundle[,bundle...]> [port]`. The positional port overrides the
-scaffold's `defaultPort: ports.backend`. Generic boots with no explicit,
-positional, or default port retain the numeric fallback `80`.
-
-```bash
-npm run server                              # default preset, config.ports.ts backend
-npm run server -- billing                   # one bundle, config.ports.ts backend
-npm run server -- billing,vehicles 4001     # merge bundles, listen on 4001
-```
-
-When multiple presets are passed, the framework loads each preset's generated route map and shallow-merges `apis` / `syncs` / `functions`. Key collisions across presets throw at boot (services must own exactly one preset).
-
-## Related architecture docs
-
-- [`docs/ARCHITECTURE_PACKAGING.md`](../../docs/ARCHITECTURE_PACKAGING.md) — package split, multi-service builds, preset bundles.
-- [`docs/ARCHITECTURE_SOCKET.md`](../../docs/ARCHITECTURE_SOCKET.md) — Socket.io setup, Redis adapter, room model.
-- [`docs/HOSTING.md`](../../docs/HOSTING.md) — multi-instance deployment, `@luckystack/router`, health probes.
-
-## License
-
-MIT — see [LICENSE](../../LICENSE).
+Server is the common security perimeter: preserve origin, CSRF, socket authorization and route-specific checks when adding custom routes. Webhook origin exemptions require independent caller authentication. Test-only reset must remain unreachable in production. See [design context](./AGENTS.md), [security rationale](./docs/security-defaults.md), and [runtime maps](./docs/runtime-maps.md). Runtime arguments and options are defined by `src/argv.ts` and `src/types.ts`.

package/dist/afterListen.d.ts

@@ -0,0 +1,2 @@
+import type { AfterListenOptions } from './types.js';
+export declare const runAfterListenTask: (task: () => void | Promise<void>, { fatal, label }?: AfterListenOptions) => Promise<void>;

package/dist/argv.d.ts

@@ -0,0 +1,8 @@
+export interface ParsedServerArgv {
+    bundles: string[];
+    port: number | null;
+}
+export declare const parseServerArgv: (argv: string[]) => ParsedServerArgv;
+export declare const applyServerArgv: () => void;
+export declare const getParsedBundles: () => string[];
+export declare const getParsedPort: () => number | null;

package/dist/bootstrap.d.ts

@@ -0,0 +1,36 @@
+import type { CreateLuckyStackServerOptions, RunningLuckyStackServer } from './types.js';
+export interface BootstrapLuckyStackOptions extends CreateLuckyStackServerOptions {
+    /**
+     * Folder name (relative to project root) that contains the overlay files.
+     * Default: `luckystack`. Each subfolder mirrors a framework package and
+     * holds the project's overrides for that package.
+     */
+    overlayRoot?: string;
+    /**
+     * Skip auto-loading the overlay folder. Useful for tests that build the
+     * registries by hand.
+     */
+    skipOverlayLoad?: boolean;
+}
+export declare const OVERLAY_ORDER: string[];
+type OverlayLoader = () => Promise<void>;
+export declare const registerOverlayLoader: (loader: OverlayLoader) => void;
+export interface OverlayEntries {
+    /** Files to import, in load order: `index.*` first, then the rest alphabetically. */
+    fileNames: string[];
+    /**
+     * Subdirectories the flat walk skipped, minus conventional test folders.
+     * The caller warns about these — silently dropping them meant overlay code
+     * one level down simply never ran, with nothing to point at.
+     */
+    ignoredDirectoryNames: string[];
+}
+/**
+ * Decide what a single overlay package folder contributes. Exported because
+ * both the runtime walk here and `scripts/bundleServer.mjs` must agree exactly:
+ * a file the bundler includes but the loader skips (or the reverse) is a
+ * dev/prod divergence, which is the defect class ADR 0046 exists for.
+ */
+export declare const collectOverlayEntries: (packageDir: string) => OverlayEntries;
+export declare const bootstrapLuckyStack: (options?: BootstrapLuckyStackOptions) => Promise<RunningLuckyStackServer>;
+export {};

package/dist/capabilities.d.ts

@@ -0,0 +1,10 @@
+export declare const capabilities: {
+    readonly login: boolean;
+    readonly presence: boolean;
+    readonly sync: boolean;
+};
+export declare const OPTIONAL_PACKAGES: readonly ['login', 'email', 'error-tracking', 'presence', 'cron', 'docs-ui'];
+export declare const canResolve: (specifier: string) => boolean;
+export declare const getLogin: () => Promise<typeof import('@luckystack/login') | null>;
+export declare const getPresence: () => Promise<typeof import('@luckystack/presence') | null>;
+export declare const getSync: () => Promise<typeof import('@luckystack/sync') | null>;

package/dist/createServer.d.ts

@@ -0,0 +1,4 @@
+import { type Server as HttpServer } from 'node:http';
+import type { CreateLuckyStackServerOptions, RunningLuckyStackServer } from './types.js';
+export declare const listenLuckyStackServer: (httpServer: HttpServer, ip: string, port: string | number, callback?: () => void) => Promise<HttpServer>;
+export declare const createLuckyStackServer: (options?: CreateLuckyStackServerOptions) => Promise<RunningLuckyStackServer>;

package/dist/customRoutesRegistry.d.ts

@@ -0,0 +1,9 @@
+import type { CustomRouteHandler, CustomRoutePhase } from './types.js';
+export interface RegisterCustomRouteOptions {
+    /** Pipeline phase the handler runs in. Defaults to `'post-params'`. */
+    phase?: CustomRoutePhase;
+}
+export declare const registerCustomRoute: (handler: CustomRouteHandler, options?: RegisterCustomRouteOptions) => void;
+export declare const getCustomRoutes: () => readonly CustomRouteHandler[];
+export declare const getPreParamsCustomRoutes: () => readonly CustomRouteHandler[];
+export declare const clearCustomRoutes: () => void;

package/dist/devServerInfo.d.ts

@@ -0,0 +1,7 @@
+export interface DevServerInfo {
+    ip: string;
+    port: number;
+    pid: number;
+}
+export declare const writeDevServerInfo: (ip: string, port: number) => void;
+export declare const clearDevServerInfo: () => void;

package/dist/devToolsStatus.d.ts

@@ -0,0 +1,3 @@
+export declare const markDevToolsInitFailed: (error: Error) => void;
+export declare const getDevToolsInitError: () => Error | null;
+export declare const clearDevToolsInitError: () => void;

package/dist/errorFormatterRegistry.d.ts

@@ -0,0 +1,2 @@
+export { registerErrorFormatter, getErrorFormatter, applyErrorFormatter, } from '@luckystack/core';
+export type { ErrorFormatter, ErrorFormatterContext } from '@luckystack/core';

package/dist/hookPayloads.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Module augmentation: extends `@luckystack/core`'s `HookPayloads` interface
+ * with socket lifecycle hooks owned by this package. Side-effect imported
+ * by `index.ts` so consumers get the augmentation automatically.
+ *
+ * Hook semantics:
+ *   - `on*` hooks are notifications. Handlers may side-effect; return values
+ *     are ignored.
+ *   - `pre*` hooks may return a `HookStopSignal` to abort the main flow. The
+ *     stop signal carries an `errorCode` that's emitted back to the client.
+ *   - `post*` hooks fire after the side-effect succeeds.
+ */
+export interface OnSocketConnectPayload {
+    socketId: string;
+    token: string | null;
+    ip: string;
+}
+export interface OnSocketDisconnectPayload {
+    socketId: string;
+    token: string | null;
+    reason: string;
+}
+export interface PreRoomJoinPayload {
+    token: string;
+    room: string;
+}
+export interface PostRoomJoinPayload {
+    token: string;
+    room: string;
+    allRooms: string[];
+}
+export interface PreRoomLeavePayload {
+    token: string;
+    room: string;
+}
+export interface PostRoomLeavePayload {
+    token: string;
+    room: string;
+    allRooms: string[];
+}
+export interface OnLocationUpdatePayload {
+    token: string;
+    oldLocation: {
+        pathName: string;
+        searchParams?: Record<string, string>;
+    } | undefined;
+    newLocation: {
+        pathName: string;
+        searchParams?: Record<string, string>;
+    };
+}
+declare module '@luckystack/core' {
+    interface HookPayloads {
+        onSocketConnect: OnSocketConnectPayload;
+        onSocketDisconnect: OnSocketDisconnectPayload;
+        preRoomJoin: PreRoomJoinPayload;
+        postRoomJoin: PostRoomJoinPayload;
+        preRoomLeave: PreRoomLeavePayload;
+        postRoomLeave: PostRoomLeavePayload;
+        onLocationUpdate: OnLocationUpdatePayload;
+    }
+}

package/dist/httpHandler.d.ts

@@ -0,0 +1,3 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { CreateLuckyStackServerOptions } from './types.js';
+export declare const handleHttpRequest: (req: IncomingMessage, res: ServerResponse, options: CreateLuckyStackServerOptions) => Promise<void>;

package/dist/httpRoutes/apiRoute.d.ts

@@ -0,0 +1,2 @@
+import type { HttpRouteHandler } from './types.js';
+export declare const handleApiRoute: HttpRouteHandler;

package/dist/httpRoutes/authApiRoute.d.ts

@@ -0,0 +1,2 @@
+import type { HttpRouteHandler } from './types.js';
+export declare const handleAuthApiRoute: HttpRouteHandler;

package/dist/httpRoutes/authCallbackRoute.d.ts

@@ -0,0 +1,2 @@
+import type { HttpRouteHandler } from './types.js';
+export declare const handleAuthCallbackRoute: HttpRouteHandler;

package/dist/httpRoutes/authLogoutRoute.d.ts

@@ -0,0 +1,2 @@
+import type { HttpRouteHandler } from './types.js';
+export declare const handleAuthLogoutRoute: HttpRouteHandler;

package/dist/httpRoutes/authProvidersRoute.d.ts

@@ -0,0 +1,2 @@
+import type { HttpRouteHandler } from './types.js';
+export declare const handleAuthProvidersRoute: HttpRouteHandler;

package/dist/httpRoutes/authSecondFactorRoutes.d.ts

@@ -0,0 +1,3 @@
+import type { HttpRouteHandler } from './types.js';
+export declare const handleAuthEmailCodeRoute: HttpRouteHandler;
+export declare const handleAuthTwoFactorRoute: HttpRouteHandler;

package/dist/httpRoutes/csrfMiddleware.d.ts

@@ -0,0 +1,8 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export declare const enforceCsrfOnStateChangingRequest: ({ req, res, routePath, token, requestId, }: {
+    req: IncomingMessage;
+    res: ServerResponse;
+    routePath: string;
+    token: string | null;
+    requestId?: string;
+}) => Promise<boolean>;

package/dist/httpRoutes/csrfRoute.d.ts

@@ -0,0 +1,2 @@
+import type { HttpRouteHandler } from './types.js';
+export declare const handleCsrfRoute: HttpRouteHandler;

package/dist/httpRoutes/customRoutes.d.ts

@@ -0,0 +1,3 @@
+import type { HttpRouteHandler } from './types.js';
+export declare const handlePreParamsCustomRoutes: HttpRouteHandler;
+export declare const handleCustomRoutes: HttpRouteHandler;

package/dist/httpRoutes/faviconRoute.d.ts

@@ -0,0 +1,2 @@
+import type { HttpRouteHandler } from './types.js';
+export declare const handleFaviconRoute: HttpRouteHandler;

package/dist/httpRoutes/healthRoutes.d.ts

@@ -0,0 +1,4 @@
+import type { HttpRouteHandler } from './types.js';
+export declare const handleLivezRoute: HttpRouteHandler;
+export declare const handleReadyzRoute: HttpRouteHandler;
+export declare const handleHealthRoute: HttpRouteHandler;

package/dist/httpRoutes/resolveRequesterIp.d.ts

@@ -0,0 +1,27 @@
+import type { IncomingMessage } from 'node:http';
+/**
+ * Resolve the real client IP for per-IP rate limiting on the HTTP api/sync
+ * transports.
+ *
+ * Extracted verbatim from the previously-duplicated inline block in
+ * `apiRoute.ts` and `syncRoute.ts` (both were byte-identical). Behaviour is
+ * preserved exactly:
+ *
+ * - Reads `http.trustProxy` from the active project config. Default
+ *   `trustProxy: false` returns the raw `req.socket.remoteAddress` (with only
+ *   IPv4-mapped IPv6 canonicalization via `resolveClientIp`); a trusted proxy
+ *   honours `X-Forwarded-For` / `X-Real-IP`.
+ * - Preserves the historical `undefined` fallback when there is genuinely no
+ *   address to resolve (no raw socket address AND — when proxied — no trusted
+ *   forwarded header), so downstream `?? 'anonymous'` / `?? 'unknown'`
+ *   bucketing stays byte-identical. This `undefined` short-circuit is the
+ *   reason this helper exists rather than calling `resolveClientIp` directly:
+ *   `resolveClientIp` would return the `'unknown'` sentinel here, which the
+ *   api/sync transports historically did NOT key on.
+ *
+ * NOTE: the `/auth/api` route intentionally does NOT use this helper — it
+ * keys on `resolveClientIp(...)` unconditionally (returning the `'unknown'`
+ * sentinel when nothing resolves), which is a different, deliberate
+ * contract. Unifying the two would change behaviour, so it is left as-is.
+ */
+export declare const resolveRequesterIp: (req: IncomingMessage) => string | undefined;

package/dist/httpRoutes/sessionCookie.d.ts

@@ -0,0 +1 @@
+export declare const resolveCookieSecure: (sessionCookieSecure: boolean | undefined, secureEnv: string | undefined) => boolean;

package/dist/httpRoutes/staticRoutes.d.ts

@@ -0,0 +1,2 @@
+import type { HttpRouteHandler } from './types.js';
+export declare const handleStaticAndSpaFallback: HttpRouteHandler;

package/dist/httpRoutes/syncRoute.d.ts

@@ -0,0 +1,2 @@
+import type { HttpRouteHandler } from './types.js';
+export declare const handleSyncRoute: HttpRouteHandler;

package/dist/httpRoutes/testResetRoute.d.ts

@@ -0,0 +1,2 @@
+import type { HttpRouteHandler } from './types.js';
+export declare const handleTestResetRoute: HttpRouteHandler;

package/dist/httpRoutes/timingSafeEqual.d.ts

@@ -0,0 +1 @@
+export declare const timingSafeStringEqual: (a: string, b: string) => boolean;

package/dist/httpRoutes/types.d.ts

@@ -0,0 +1,15 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { CreateLuckyStackServerOptions } from '../types.js';
+export 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;
+}
+export type HttpRouteHandler = (ctx: HttpRouteContext) => Promise<boolean>;

package/dist/httpRoutes/uploadsRoute.d.ts

@@ -0,0 +1,2 @@
+import type { HttpRouteHandler } from './types.js';
+export declare const handleUploadsRoute: HttpRouteHandler;