@luckystack/core 0.1.9 → 0.2.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { a7 as ErrorParam, a8 as ErrorResponseInput, a9 as NormalizedErrorResponse, b as AuthProps, B as BaseSessionLayout } from './pageRouteValidation-CxZJVwZh.js';
-export { A as ApiMethodMap, a as AppConfig, aa as AuthConfig, ab as CorsConfig, D as DEFAULT_PAGE_ROUTE_RULES, ac as DEFAULT_PROJECT_CONFIG, ad as DevConfig, ae as HttpConfig, H as HttpMethodLiteral, af as HttpStreamConfig, ag as INVALID_ERROR_RESPONSE_CODE, L as Logger, c as LoggerContext, d as LoggingConfig, N as Notifier, e as NotifyInput, f as NotifyParam, ah as OfflineQueueConfig, P as PagePathValidationResult, g as PageRouteRules, ai as PasswordPolicyConfig, aj as PathsConfig, h as ProjectConfig, ak as ProjectConfigInput, R as RateLimitingConfig, S as SOCKETSTATUS, al as SecurityHeadersConfig, am as ServiceRouteParseError, an as ServiceRouteParseResult, ao as ServiceRouteParseSuccess, i as SessionConfig, j as SessionLocation, ap as SocketConfig, aq as SyncConfig, ar as SyncStreamThrottleConfig, as as TransportRouteParseError, at as TransportRouteParseResult, au as TransportRouteParseSuccess, k as buildApiResponseEventName, l as buildApiStreamEventName, m as buildGetJoinedRoomsResponseEventName, n as buildJoinRoomResponseEventName, o as buildLeaveRoomResponseEventName, p as buildSyncProgressEventName, q as buildSyncResponseEventName, r as clearCsrfToken, av as createDevLogger, aw as defaultHttpStatusForResponse, s as enqueueApiRequest, t as enqueueSyncRequest, u as flushApiQueue, v as flushSyncQueue, w as getApiQueueSize, x as getCsrfToken, y as getLogger, z as getNotifier, C as getProjectConfig, ax as getProjectName, E as getRegisteredApiMethod, F as getSyncQueueSize, G as httpFetch, I as incrementResponseIndex, J as isApiMethodMapRegistered, ay as isErrorParamArray, az as isLoggerRegistered, K as isOnline, M as isProjectConfigRegistered, O as normalizeErrorResponseCore, Q as notify, T as parseServiceRouteName, aA as parseTransportRouteName, U as registerApiMethodMap, V as registerLogger, W as registerNotifier, X as registerProjectConfig, Y as removeApiQueueItem, Z as removeApiQueueItemsByKey, _ as removeSyncQueueItem, aB as resetLoggerForTests, $ as setSocket, a0 as sleep, a1 as socket, a2 as socketEventNames, a3 as statusContent, a4 as tryCatch, a5 as validatePagePath, a6 as waitForSocket } from './pageRouteValidation-CxZJVwZh.js';
+import { a6 as ErrorParam, a7 as ErrorResponseInput, a8 as NormalizedErrorResponse, a9 as HealthHashConfig, aa as DeepPartial, B as BaseSessionLayout, b as AuthProps } from './pageRouteValidation-BoZ-rQWi.js';
+export { ab as ApiConfig, A as ApiMethodMap, a as AppConfig, ac as AuthConfig, ad as AuthRateLimitConfig, ae as CorsConfig, D as DEFAULT_PAGE_ROUTE_RULES, af as DEFAULT_PROJECT_CONFIG, ag as DevConfig, ah as HttpConfig, H as HttpMethodLiteral, ai as HttpStreamConfig, aj as INVALID_ERROR_RESPONSE_CODE, L as Logger, c as LoggerContext, d as LoggingConfig, N as Notifier, e as NotifyInput, f as NotifyParam, ak as OfflineQueueConfig, P as PagePathValidationResult, g as PageRouteRules, al as PasswordPolicyConfig, am as PathsConfig, h as ProjectConfig, an as ProjectConfigInput, ao as QueueDropReason, ap as RateLimitIdentity, aq as RateLimitIdentityParams, R as RateLimitingConfig, S as SOCKETSTATUS, ar as SecurityHeadersConfig, as as ServiceRouteParseError, at as ServiceRouteParseResult, au as ServiceRouteParseSuccess, i as SessionConfig, j as SessionLocation, av as SocketConfig, aw as SyncConfig, ax as SyncFlushPressureConfig, ay as SyncStreamThrottleConfig, az as TransportRouteParseError, aA as TransportRouteParseResult, aB as TransportRouteParseSuccess, aC as ValidationConfig, k as buildApiResponseEventName, l as buildApiStreamEventName, m as buildGetJoinedRoomsResponseEventName, n as buildJoinRoomResponseEventName, o as buildLeaveRoomResponseEventName, p as buildSyncProgressEventName, q as buildSyncResponseEventName, r as clearCsrfToken, aD as createDevLogger, aE as deepMerge, aF as defaultHttpStatusForResponse, s as enqueueApiRequest, t as enqueueSyncRequest, u as flushApiQueue, v as flushSyncQueue, w as getApiQueueSize, x as getCsrfToken, y as getLogger, z as getNotifier, C as getProjectConfig, aG as getProjectName, E as getRegisteredApiMethod, F as getSyncQueueSize, G as httpFetch, I as incrementResponseIndex, J as isApiMethodMapRegistered, aH as isErrorParamArray, aI as isLoggerRegistered, K as isOnline, aJ as isPlainObject, M as isProjectConfigRegistered, O as normalizeErrorResponseCore, Q as notify, T as parseServiceRouteName, aK as parseTransportRouteName, U as registerApiMethodMap, V as registerLogger, W as registerNotifier, X as registerProjectConfig, Y as removeApiQueueItem, Z as removeApiQueueItemsByKey, _ as removeSyncQueueItem, aL as resetLoggerForTests, $ as setSocket, a0 as sleep, a1 as socket, a2 as socketEventNames, a3 as statusContent, a4 as validatePagePath, a5 as waitForSocket } from './pageRouteValidation-BoZ-rQWi.js';
 export { ApiTypeMap, StreamPayload, SyncTypeMap } from './apiTypeStubs.js';
 import { Server, Socket } from 'socket.io';
 import { z } from 'zod';
@@ -7,9 +7,100 @@ import * as _prisma_client_runtime_library from '@prisma/client/runtime/library'
 import * as _prisma_client from '@prisma/client';
 import { PrismaClient } from '@prisma/client';
 import Redis, { Redis as Redis$1 } from 'ioredis';
-import { ServerResponse, IncomingMessage } from 'node:http';
+import { RedisAdapterOptions } from '@socket.io/redis-adapter';
+import { ServerResponse, IncomingMessage, IncomingHttpHeaders } from 'node:http';
 import 'socket.io-client';
 
+declare function tryCatch<T, P = void>(func: (values: P) => Promise<T> | T, params?: P, context?: Record<string, unknown>): Promise<[Error | null, T | null]>;
+
+declare function tryCatchSync<T, P>(func: (values: P) => T, params?: P): [Error | null, T | null];
+
+type RequireTransform<TInput, TStored> = [TInput] extends [TStored] ? {
+    transform?: (input: TInput, current: TStored) => TStored;
+} : {
+    transform: (input: TInput, current: TStored) => TStored;
+};
+interface RegistryOptionsBase<TStored> {
+    /**
+     * Called once per `register` with the freshly-stored value — used for the
+     * rate-limiter's `[RateLimiter] active strategy → …` debug line. Runs after
+     * the slot is updated so a logger registry can log through itself.
+     */
+    onRegister?: (stored: TStored) => void;
+    /**
+     * Resolve the value `get` returns when nothing has been registered yet.
+     * Defaults to returning `defaultValue`. `servicesConfig` throws here.
+     */
+    resolveDefault?: () => TStored;
+}
+type RegistryOptions<TInput, TStored> = RegistryOptionsBase<TStored> & RequireTransform<TInput, TStored>;
+interface Registry<TInput, TStored> {
+    /** Store a value (after the optional `transform`) and mark the slot registered. */
+    register: (input: TInput) => TStored;
+    /** Read the active value at call time (registered value, else the default). */
+    get: () => TStored;
+    /** True once `register` has been called at least once. */
+    isRegistered: () => boolean;
+    /** Restore the unregistered state (test-only). */
+    reset: () => void;
+}
+/**
+ * Create a single-slot registry. `defaultValue` is returned by `get` until
+ * `register` is called (unless `resolveDefault` overrides that). When
+ * `TInput` differs from `TStored`, the `transform` option is mandatory (the
+ * `RequireTransform` constraint enforces it); when they match it is optional
+ * and defaults to identity. The second positional argument is likewise
+ * optional only in the identity case.
+ */
+declare function createRegistry<TStored, TInput = TStored>(defaultValue: TStored, ...optionsArg: [TInput] extends [TStored] ? [options?: RegistryOptions<TInput, TStored>] : [options: RegistryOptions<TInput, TStored>]): Registry<TInput, TStored>;
+
+/**
+ * Escape `&`, `<`, `>`, `"`, `'` for safe interpolation into HTML text nodes
+ * and quoted attribute values. Does NOT protect against CSS/JS/URL-context
+ * injection — use a dedicated sanitizer for those contexts.
+ */
+declare const escapeHtml: (str: string) => string;
+
+/** Minimal shape of a Node `require` with the `.resolve` member these guards use. */
+interface PeerRequire {
+    (id: string): unknown;
+    resolve: (id: string) => string;
+}
+/**
+ * Assert that an optional peer package is installed, throwing a consistent,
+ * actionable error when it is not. Does NOT load the module — use `loadPeer`
+ * for that. Pass `requireFn` (a `createRequire(import.meta.url)` from the
+ * calling adapter) so resolution happens from the consumer's perspective.
+ *
+ * `hint` is appended to the standard "package X is not installed" sentence —
+ * e.g. `'Run `npm install resend`, or pick a different EmailSender adapter.'`.
+ */
+declare const ensurePeerDepInstalled: (packageName: string, hint: string, requireFn?: PeerRequire) => void;
+/**
+ * Synchronously load an optional peer package, asserting it is installed
+ * first (so a missing dependency fails with the actionable `hint` rather than
+ * a raw `MODULE_NOT_FOUND`). Returns the module typed as `T`. Pass `requireFn`
+ * (built with `createRequire(import.meta.url)` at the call site) so resolution
+ * + load happen relative to the calling module.
+ */
+declare const loadPeer: <T>(packageName: string, hint: string, requireFn?: PeerRequire) => T;
+
+interface RoomNameFormatterContext {
+    /** Why the room name is being formatted — so a formatter can branch if needed. */
+    purpose: 'join' | 'leave' | 'broadcast' | 'presence';
+    /** Session user id when known (join/leave by an authenticated socket), else null. */
+    userId?: string | null;
+}
+type RoomNameFormatter = (rawRoomName: string, ctx: RoomNameFormatterContext) => string;
+/** Override how every framework room name is namespaced (multi-tenant prefixing). */
+declare const registerRoomNameFormatter: (formatter: RoomNameFormatter) => void;
+/** Read the active formatter (defaults to identity). */
+declare const getRoomNameFormatter: () => RoomNameFormatter;
+/** Apply the active formatter — the single helper framework room-sites call. */
+declare const formatRoomName: (rawRoomName: string, ctx: RoomNameFormatterContext) => string;
+/** The built-in identity formatter (exported for tests / explicit reset). */
+declare const defaultRoomNameFormatter: RoomNameFormatter;
+
 type LanguageCode = string;
 interface TranslateInput {
     language: LanguageCode;
@@ -68,13 +159,26 @@ interface ErrorFormatterContext {
     /** Session id when available. */
     userId?: string | null;
 }
-type ErrorFormatter = (error: {
+/** The normalized error envelope handed to every formatter. */
+interface FormatterErrorEnvelope {
     status: 'error';
     errorCode?: string;
     message?: string;
     httpStatus?: number;
     [key: string]: unknown;
-}, ctx: ErrorFormatterContext) => Record<string, unknown>;
+}
+type ErrorFormatter = (error: FormatterErrorEnvelope, ctx: ErrorFormatterContext) => Record<string, unknown>;
+/**
+ * Minimal structural contract every formatter-eligible envelope satisfies:
+ * a discriminant `status` plus an open string-index so formatters can read /
+ * add arbitrary fields. Generic helpers below constrain to this so transport
+ * handlers no longer need `as unknown as` double-casts at the formatter
+ * boundary — see `applyErrorFormatter` / `buildFormattedError`.
+ */
+interface FormatterEnvelope {
+    status?: string;
+    [key: string]: unknown;
+}
 /**
  * Register a global error-response formatter. Receives the normalized
  * error envelope + context; return a (possibly extended) object that the
@@ -94,15 +198,13 @@ declare const getErrorFormatter: () => ErrorFormatter | null;
  * are caught and logged; the un-formatted envelope is returned in that
  * case to keep the error path crash-resistant.
  */
-declare const applyErrorFormatter: (input: {
-    response: Record<string, unknown> & {
-        status?: string;
-    };
+declare const applyErrorFormatter: <T extends FormatterEnvelope>(input: {
+    response: T;
     routeName: string;
     transport: "socket" | "http";
     userId?: string | null;
     perRouteFormatter?: ErrorFormatter | undefined | null;
-}) => Record<string, unknown>;
+}) => T;
 
 interface apiMessage {
     name: string;
@@ -138,6 +240,28 @@ declare const isRuntimeMapsProviderRegistered: () => boolean;
 declare const getRuntimeApiMaps: () => Promise<RuntimeApiMapsResult>;
 declare const getRuntimeSyncMaps: () => Promise<RuntimeSyncMapsResult>;
 
+/**
+ * A single email attachment (email F2). Adapters (Resend, SMTP/Nodemailer, SES)
+ * thread these into their provider payload. `content` is the raw bytes
+ * (`Buffer`/`Uint8Array`) or a base64 string; provide a `path`/`href` instead
+ * for adapters that fetch externally. Shapes are intentionally permissive so a
+ * single attachment object works across providers — each adapter maps the
+ * fields it supports.
+ */
+interface EmailAttachment {
+    /** File name shown to the recipient (e.g. `invoice.pdf`). */
+    filename: string;
+    /** Inline bytes or base64 string. Mutually exclusive with `path`/`href`. */
+    content?: Buffer | Uint8Array | string;
+    /** Local file path the adapter reads (when it supports path-based sends). */
+    path?: string;
+    /** Remote URL the adapter fetches (when it supports href-based sends). */
+    href?: string;
+    /** MIME type (e.g. `application/pdf`). Adapter may infer from `filename` if omitted. */
+    contentType?: string;
+    /** `Content-ID` for inline/embedded images referenced by `cid:` in the HTML. */
+    cid?: string;
+}
 interface EmailMessage {
     to: string | string[];
     subject: string;
@@ -147,6 +271,20 @@ interface EmailMessage {
     replyTo?: string;
     cc?: string | string[];
     bcc?: string | string[];
+    /**
+     * File attachments (email F2). Owned by core (not `@luckystack/email`) so the
+     * type is the single source of truth across the framework and every adapter;
+     * adapters thread these into their provider's attachment payload. Optional —
+     * a message without attachments behaves exactly as before.
+     */
+    attachments?: EmailAttachment[];
+    /**
+     * Custom message headers (email F2) — e.g. `X-Entity-Ref-ID`,
+     * `List-Unsubscribe`, idempotency keys. Adapters merge these over the headers
+     * they set themselves (adapter-reserved headers win to avoid breaking
+     * delivery). Optional.
+     */
+    headers?: Record<string, string>;
 }
 type EmailResult = {
     ok: true;
@@ -228,6 +366,31 @@ interface DeployRoutingShape {
     healthProbeTimeoutMs?: number;
     /** Seconds the boot-UUID Redis key lives for (default 3600 = 1h). */
     bootKeyTtlSeconds?: number;
+    /**
+     * ms before the router gives up proxying to an upstream backend (SEC-30 /
+     * router-DeployRoutingShape). Guards against slow-loris upstreams holding a
+     * router worker open. The router reads this when building its proxy request.
+     * DEFAULT undefined → router falls back to its own built-in default.
+     */
+    upstreamTimeoutMs?: number;
+    /**
+     * Name of the service that terminates websocket (Socket.io) traffic. The
+     * router pins WS upgrade requests to this service (they cannot be load-balanced
+     * round-robin without sticky sessions). DEFAULT undefined → router uses its
+     * `system` convention.
+     */
+    websocketService?: string;
+    /**
+     * Path the router exposes for its OWN health/liveness (distinct from the
+     * backend `/_health` boot-handshake endpoint). DEFAULT undefined → router
+     * uses its built-in default.
+     */
+    routerHealthPath?: string;
+    /**
+     * Max request body size (bytes) the router will buffer/forward before
+     * rejecting with 413. DEFAULT undefined → router uses its built-in default.
+     */
+    maxRequestBodyBytes?: number;
 }
 interface DeployDevelopmentShape {
     enableFallbackRouting?: boolean;
@@ -283,6 +446,11 @@ declare const setSentryUser: (user: {
 declare const startSpan: (name: string, op: string) => unknown;
 
 type ErrorTrackerContext = Record<string, unknown>;
+declare const sanitizeErrorString: (value: string) => string;
+declare const sanitizeErrorStrings: (error: unknown) => {
+    message: string;
+    stack: string | undefined;
+} | null;
 interface ErrorTrackerUser {
     id?: string;
     email?: string;
@@ -306,15 +474,75 @@ interface ErrorTracker {
     startSpan?: <T>(name: string, op: string, fn: () => T) => T;
     recordMetric?: (name: string, value: number, tags?: Record<string, string>) => void;
     beforeSend?: (event: ErrorTrackerEvent) => ErrorTrackerEvent | null;
+    /**
+     * Optional flush lifecycle hook (error-tracking ET batch). Called by
+     * {@link flushErrorTrackers} on graceful shutdown so a buffered adapter
+     * (PostHog batch, Sentry transport) can drain in-flight events before exit.
+     * Returns a promise that resolves when the adapter has flushed.
+     */
+    flush?: () => Promise<void>;
 }
+/**
+ * Open a per-request error-tracker identity scope and run `fn` inside it. Call at
+ * request ENTRY (before any await that could interleave with another request); the
+ * identity starts null and is filled in later via {@link setCurrentErrorTrackerIdentity}
+ * once the session is known. Each invocation gets an isolated box (ET-02).
+ */
+declare const runWithErrorTrackerIdentityScope: <T>(fn: () => T) => T;
+/**
+ * Run `fn` with `user` bound as the ambient error-tracker identity (ET-02). Convenience
+ * wrapper that opens a scope and immediately sets the identity — used where the user is
+ * already known up front (and by the adapter regression tests).
+ */
+declare const runWithErrorTrackerIdentity: <T>(user: ErrorTrackerUser | null, fn: () => T) => T;
+/**
+ * Write `user` into the active identity box opened by {@link runWithErrorTrackerIdentityScope}
+ * / {@link runWithErrorTrackerIdentity}. No-op when called outside any scope (a background /
+ * non-request capture has no per-request box; adapters fall back to their own global).
+ */
+declare const setCurrentErrorTrackerIdentity: (user: ErrorTrackerUser | null) => void;
+/** Read the ambient per-event identity for the active request scope, if any. */
+declare const getCurrentErrorTrackerIdentity: () => ErrorTrackerUser | null;
+type PreCaptureFilter = (event: ErrorTrackerEvent) => boolean;
+declare const registerPreCaptureFilter: (filter: PreCaptureFilter | null) => void;
 declare const registerErrorTracker: (tracker: ErrorTracker) => void;
 declare const registerErrorTrackers: (trackers: ErrorTracker[]) => void;
+/**
+ * APPEND primitive (ET-05): add a tracker WITHOUT clobbering already-registered
+ * ones. Fixes the async-PostHog-vs-consumer-overlay race where the loser of
+ * `registerErrorTracker`'s replace silently vanished. De-duplicates by `name`
+ * (re-appending the same adapter name replaces that one entry in place) so a
+ * lazy adapter that registers a proxy then the real client doesn't double-fire.
+ */
+declare const appendErrorTracker: (tracker: ErrorTracker) => void;
 declare const getActiveErrorTrackers: () => ErrorTracker[];
+/**
+ * Flush lifecycle (error-tracking ET batch): drain every adapter that exposes a
+ * `flush()` before shutdown. Per-adapter failures are swallowed + logged so one
+ * stuck adapter can't block graceful shutdown. Safe to call when no adapter has
+ * `flush`.
+ */
+declare const flushErrorTrackers: () => Promise<void>;
 declare const captureExceptionAcrossTrackers: (error: unknown, context?: ErrorTrackerContext) => void;
 declare const captureMessageAcrossTrackers: (message: string, level: "info" | "warning" | "error" | "fatal", context?: ErrorTrackerContext) => void;
 declare const setErrorTrackerUser: (user: ErrorTrackerUser | null) => void;
 declare const recordMetricAcrossTrackers: (name: string, value: number, tags?: Record<string, string>) => void;
 declare const startSpanAcrossTrackers: <T>(name: string, op: string, fn: () => T) => T;
+/**
+ * Handle-style span (error-tracking ET batch): for callers that can't wrap the
+ * measured work in a single synchronous `fn` (streaming, cross-await spans).
+ * Returns a handle whose `finish()` resolves the span's duration. The default
+ * implementation is a lightweight wall-clock timer (works with any backend);
+ * an adapter can supply a richer span via the existing `startSpan` callback
+ * form when it needs native instrumentation. `finish()` is idempotent.
+ */
+interface SpanHandle {
+    /** Stop the span; safe to call more than once (subsequent calls are no-ops). */
+    finish: () => void;
+    /** Milliseconds elapsed at the moment `finish()` first ran (0 before). */
+    readonly durationMs: number;
+}
+declare const startSpanHandle: (_name: string, _op: string) => SpanHandle;
 
 declare const EnvSchema: z.ZodObject<{
     NODE_ENV: z.ZodDefault<z.ZodEnum<{
@@ -348,6 +576,7 @@ declare const env: {
     PROJECT_NAME: string;
 };
 declare const isProduction: boolean;
+declare const getEnv: () => RuntimeEnv;
 
 declare global {
     var __luckystackPrisma: PrismaClient | undefined;
@@ -361,6 +590,7 @@ interface RedisConnectionOptions {
     password?: string;
 }
 declare const getRedisConnectionOptions: () => RedisConnectionOptions;
+declare const registerStrayPrefixCommand: (...commands: string[]) => void;
 declare const redis: Redis;
 
 type RedisKeyFormatter = (namespace: string, suffix: string) => string;
@@ -403,26 +633,147 @@ declare const getPrismaClient: () => PrismaClient;
 declare const getRedisClient: () => Redis$1;
 declare const resetClientsForTests: () => void;
 
-declare const attachSocketRedisAdapter: (io: Server) => void;
+interface AttachSocketRedisAdapterOptions {
+    /**
+     * Options forwarded to `@socket.io/redis-adapter`'s `createAdapter`
+     * (e.g. `key` prefix, `requestsTimeout`, `publishOnSpecificResponseChannel`).
+     */
+    adapterOptions?: Partial<RedisAdapterOptions>;
+    /**
+     * Supply a pre-built pub client instead of `redis.duplicate()`. Use this for
+     * a dedicated adapter connection, custom auth, or a sentinel/cluster handle.
+     * When omitted the framework duplicates the default `redis` handle.
+     */
+    pubClient?: Redis$1;
+    /** Pre-built sub client (see `pubClient`). */
+    subClient?: Redis$1;
+}
+declare const attachSocketRedisAdapter: (io: Server, options?: AttachSocketRedisAdapterOptions) => void;
 
 declare const BOOT_KEY_PREFIX = "luckystack:boot:";
 declare const resolveEnvKey: () => string;
 declare const writeBootUuid: (envKey?: string) => Promise<string>;
 declare const readBootUuid: (envKey?: string) => Promise<string | null>;
 
+/**
+ * Hash a synchronized value under an EXPLICIT `{ mode, salt }` (SEC-13). The
+ * shared primitive the router calls with the same config the backend used, so
+ * the cross-env compare still holds:
+ *   - `'plain'`  → `sha256(value)` (today's behavior; `salt` ignored).
+ *   - `'salted'` → `sha256(salt + value)`.
+ *   - `'hmac'`   → `HMAC-SHA256(key=salt, value)`.
+ * A `'salted'`/`'hmac'` mode with an empty resolved salt falls back to `'plain'`
+ * (and is the caller's responsibility to avoid) rather than silently hashing
+ * with an empty key.
+ */
+declare const hashSynchronizedValueWith: (config: Pick<HealthHashConfig, "mode"> & {
+    salt: string;
+}, value: string) => string;
+/**
+ * Resolve the effective health-hash config from `http.healthHash`, expanding the
+ * `'@bootUuid'` salt sentinel to the supplied boot UUID. Honoured for BOTH
+ * `'salted'` and `'hmac'` (the 0.2.0 default is `hmac` + `'@bootUuid'`, so the
+ * per-boot UUID becomes the HMAC key — the synchronized-env fingerprint rotates
+ * every restart instead of being a stable, dictionary-attackable `sha256`). The
+ * server passes its current boot UUID; the router, comparing, passes the same
+ * value it read from the backend's handshake. When the sentinel is in play but
+ * no boot UUID is available the config collapses to `'plain'` so the cross-env
+ * compare never silently diverges.
+ */
+declare const resolveHealthHashConfig: (bootUuid?: string | null) => {
+    mode: HealthHashConfig["mode"];
+    salt: string;
+};
+/**
+ * Safe-to-expose descriptor of the resolved health-hash config. The router needs
+ * to hash with the SAME `{ mode, salt }` the backend used, but a static `salt`
+ * (mode `'salted'`/`'hmac'` with a non-sentinel salt) is a SECRET and must never
+ * leave the backend. So `/_health` exposes only the `mode` + whether the salt is
+ * the `'@bootUuid'` sentinel (the bootUuid itself is already in the response).
+ * From this the router can reproduce the hash for `'plain'` and `'@bootUuid'`
+ * configs, and KNOWS it cannot reproduce a static-salt config (so it skips the
+ * compare instead of reporting a false drift).
+ */
+interface HealthHashDescriptor {
+    mode: HealthHashConfig['mode'];
+    bootUuidSalt: boolean;
+}
+/** Describe the active health-hash config for the `/_health` payload (no secret salt). */
+declare const describeHealthHashConfig: () => HealthHashDescriptor;
+/**
+ * Reproduce the backend's resolved `{ mode, salt }` from its `/_health`
+ * descriptor + the shared boot UUID. Returns `null` when the backend uses a
+ * STATIC salt the router cannot see — the caller must then skip the compare
+ * rather than hash with a different (default) config and report a false drift.
+ */
+declare const resolveHealthHashConfigFromDescriptor: (descriptor: HealthHashDescriptor, bootUuid: string) => {
+    mode: HealthHashConfig["mode"];
+    salt: string;
+} | null;
 declare const collectSynchronizedEnvKeys: () => string[];
-declare const computeSynchronizedEnvHashes: () => Record<string, string | null>;
-declare const hashSynchronizedValue: (value: string) => string;
+/**
+ * Compute the `/_health` hash map for every synchronized env var. Reads
+ * `http.healthHash` (call-time) so a consumer's salt/HMAC opt-in applies;
+ * `bootUuid` is consulted only when the salt is the `'@bootUuid'` sentinel.
+ * The 0.2.0 DEFAULT (`{ mode: 'hmac', salt: '@bootUuid' }`) HMAC-keys the output
+ * on `bootUuid`; pass `mode: 'plain'` to restore the historical unsalted output.
+ */
+declare const computeSynchronizedEnvHashes: (bootUuid?: string | null) => Record<string, string | null>;
+declare const hashSynchronizedValue: (value: string, bootUuid?: string | null) => string;
 
 declare const initConsolelog: () => void;
 
+declare const DEFAULT_REDACTED_LOG_KEYS: readonly string[];
 declare const registerRedactedLogKeys: (keys: readonly string[]) => void;
 declare const getRedactedLogKeys: () => readonly string[];
 declare const isRedactedLogKey: (key: string) => boolean;
 declare const resetRedactedLogKeysForTests: () => void;
+/** Placeholder substituted for a redacted value. */
+declare const REDACTED_PLACEHOLDER = "[redacted]";
+declare const DEPTH_TRUNCATED_PLACEHOLDER = "[truncated: max depth]";
+/**
+ * Recursively deep-copy `value`, replacing any property whose key matches the
+ * registered redacted-keys set (case-insensitive) with {@link REDACTED_PLACEHOLDER}
+ * (SYNC-17 defense-in-depth). Use it at raw log / `captureException` context
+ * sites so a token/password nested anywhere in a payload never lands verbatim in
+ * a logger sink or error-tracker breadcrumb.
+ *
+ * - Primitives pass through unchanged.
+ * - Arrays are mapped element-wise (array indices are never "keys", so an
+ *   element is only redacted by its own nested object keys).
+ * - Cycles / over-deep graphs are cut at {@link MAX_SANITIZE_DEPTH} with
+ *   {@link DEPTH_TRUNCATED_PLACEHOLDER}; the input is never mutated.
+ */
+declare const sanitizeForLog: (value: unknown, depth?: number) => unknown;
 
 declare const getCookieValue: (cookieHeader: string | undefined, cookieName: string) => string | null;
 declare const hasCookie: (cookieHeader: string | undefined, cookieName: string) => boolean;
+/** Attributes a cookie-builder must honour, after applying any name prefix. */
+interface CookiePrefixConstraints {
+    /** Effective cookie name (prefix prepended when applicable). */
+    name: string;
+    /** Whether `Secure` must be set (forced true by either prefix). */
+    secure: boolean;
+    /** Whether `Path=/` is forced (true under `__Host-`). */
+    forcePathRoot: boolean;
+    /** Whether a `Domain` attribute is FORBIDDEN (true under `__Host-`). */
+    forbidDomain: boolean;
+}
+/**
+ * Compute the attribute constraints a `__Host-` / `__Secure-` cookie-name prefix
+ * imposes (CORE-10/39), so the server's session + CSRF cookie builders apply the
+ * browser-enforced rules consistently:
+ *
+ *   - `'__Host-'`   → name prefixed, `Secure` forced, `Path=/` forced, `Domain` forbidden.
+ *   - `'__Secure-'` → name prefixed, `Secure` forced.
+ *   - `undefined`   → name unchanged, no forced attributes (today's behavior).
+ *
+ * Pure + deterministic — the builder still owns serialization; this only
+ * resolves the constraints so server and any other cookie-site can't drift.
+ * `secureOverride` lets the caller force `Secure` independent of a prefix
+ * (mirrors `http.sessionCookieSecure`).
+ */
+declare const applyCookiePrefixConstraints: (baseName: string, prefix: "__Host-" | "__Secure-" | undefined, secureOverride?: boolean) => CookiePrefixConstraints;
 
 /**
  * HTTP API Utilities
@@ -432,6 +783,13 @@ declare const hasCookie: (cookieHeader: string | undefined, cookieName: string)
  * - Method validation
  */
 type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+/**
+ * Single source of truth for the GET-prefix naming heuristic
+ * (`get` / `fetch` / `list`). Used by both `inferHttpMethod` here and the
+ * client transport's `isGetMethod` fallback in `apiRequest.ts`, so the two
+ * prefix heuristics can't drift apart. Expects an already-lowercased leaf name.
+ */
+declare const isGetMethodName: (methodNameLower: string) => boolean;
 /**
  * Infer the HTTP method from an API name based on common naming conventions.
  *
@@ -462,7 +820,13 @@ declare const getEffectiveHttpMethod: (apiConfig: {
  *
  * @param requestMethod - The method from the HTTP request
  * @param allowedMethod - The method the API accepts
- * @returns true if the method matches or if it's a preflight OPTIONS request
+ * @returns true only when the method matches the route's allowed method.
+ *
+ * NOTE: `OPTIONS` is intentionally NOT treated as allowed here. A custom-route
+ * author wiring this into their dispatch must answer CORS preflights BEFORE the
+ * route check — letting `OPTIONS` through would execute the handler on a request
+ * the CSRF middleware treats as non-state-changing (CSRF-exempt), opening a
+ * bypass on method-locked routes.
  */
 declare const isMethodAllowed: (requestMethod: string, allowedMethod: HttpMethod) => boolean;
 
@@ -634,9 +998,6 @@ interface AvatarConfig {
     cacheControl: string;
 }
 declare const DEFAULT_AVATAR_CONFIG: AvatarConfig;
-type DeepPartial<T> = {
-    [K in keyof T]?: T[K] extends object | undefined ? DeepPartial<NonNullable<T[K]>> : T[K];
-};
 type AvatarConfigInput = DeepPartial<AvatarConfig>;
 declare const registerAvatarConfig: (config: AvatarConfigInput) => void;
 declare const getAvatarConfig: () => AvatarConfig;
@@ -673,6 +1034,90 @@ declare const extractTokenFromSocket: (socket: Pick<Socket, "handshake">) => str
  */
 declare const extractTokenFromRequest: (req: IncomingMessage) => string | null;
 
+/**
+ * Stable sentinel returned when no usable client address could be resolved.
+ * Kept as a single exported constant so every rate-limit key-site funnels
+ * missing addresses into one deterministic bucket instead of ad-hoc literals.
+ */
+declare const UNKNOWN_CLIENT_IP = "unknown";
+interface ResolveClientIpParams {
+    /**
+     * The raw transport peer address — `socket.handshake.address` (Socket.io)
+     * or `req.socket.remoteAddress` (raw HTTP). May be `undefined`/`null` when
+     * the connection has already been torn down.
+     */
+    rawAddress: string | null | undefined;
+    /** Request / handshake headers. Only consulted when `trustProxy` is true. */
+    headers: IncomingHttpHeaders;
+    /**
+     * Whether a known reverse proxy sits in front of this server. DEFAULT false.
+     * When false the raw peer address is returned verbatim (only IPv4-mapped
+     * IPv6 canonicalization is applied), preserving historical behaviour. Only
+     * enable when a trusted proxy populates `X-Forwarded-For` / `X-Real-IP`,
+     * otherwise a client can spoof its own IP via those headers.
+     */
+    trustProxy?: boolean;
+    /**
+     * Number of proxy hops to skip from the RIGHT of `X-Forwarded-For` when
+     * `trustProxy` is on (CORE-O3). The rightmost entries are appended by your own
+     * trusted proxies; the resolved client IP is the entry that many hops in from
+     * the end. The leftmost hop is client-controlled and is never trusted. DEFAULT
+     * 1 (the immediate upstream proxy). Clamped to the list length so an over-large
+     * count falls back to the leftmost trusted hop rather than the spoofable entry.
+     */
+    trustedProxyHopCount?: number;
+}
+/**
+ * Whether a resolved client IP is a loopback / unresolved address — used by the
+ * api/sync transports to honour `rateLimiting.skipLoopbackInDev` (api F5/F11).
+ * Matches IPv4 loopback (`127.0.0.0/8`), IPv6 loopback (`::1`), the IPv4-mapped
+ * form (`::ffff:127.0.0.1`, already canonicalized away by {@link resolveClientIp}),
+ * and the {@link UNKNOWN_CLIENT_IP} sentinel. Pass an already-resolved IP.
+ */
+declare const isLoopbackIp: (ip: string) => boolean;
+/**
+ * Derive the deterministic, non-reversible bucket component for a session
+ * token. The same token always yields the same value (bucket identity is
+ * preserved) while the raw token never appears in the returned string.
+ * Used by api AND sync rate-limit key builders — lives in core so both
+ * packages can share one implementation without a cross-package dependency.
+ */
+declare const deriveTokenBucketId: (token: string) => string;
+declare const resolveClientIp: ({ rawAddress, headers, trustProxy, trustedProxyHopCount }: ResolveClientIpParams) => string;
+
+interface SessionSaveResult {
+    ok: boolean;
+    errorCode?: string;
+}
+interface SessionLogoutInput {
+    token: string | null;
+    socket?: Socket;
+    userId?: string | null;
+    skipSessionDelete?: boolean;
+}
+interface SessionProvider {
+    getSession: (token: string | null) => Promise<BaseSessionLayout | null>;
+    saveSession: (token: string, data: BaseSessionLayout, newUser?: boolean, options?: {
+        supersedeToken?: string;
+    }) => Promise<SessionSaveResult>;
+    deleteSession: (token: string, options?: {
+        skipSocketLogout?: boolean;
+    }) => Promise<boolean>;
+    logout: (input: SessionLogoutInput) => Promise<void>;
+}
+declare const registerSessionProvider: (next: SessionProvider) => void;
+declare const getRegisteredSessionProvider: () => SessionProvider | null;
+declare const isSessionProviderRegistered: () => boolean;
+declare const resetSessionProviderForTests: () => void;
+declare const readSession: (token: string | null) => Promise<BaseSessionLayout | null>;
+declare const writeSession: (token: string, data: BaseSessionLayout, newUser?: boolean, options?: {
+    supersedeToken?: string;
+}) => Promise<SessionSaveResult>;
+declare const removeSession: (token: string, options?: {
+    skipSocketLogout?: boolean;
+}) => Promise<boolean>;
+declare const performLogout: (input: SessionLogoutInput) => Promise<void>;
+
 /**
  * Shared validation utilities for API and Sync request handlers.
  * Extracted to avoid code duplication between handleApiRequest and handleSyncRequest.
@@ -711,7 +1156,7 @@ interface ValidationResult$1 {
  */
 declare const validateRequest: ({ auth, user }: {
     auth: AuthProps;
-    user: BaseSessionLayout;
+    user?: BaseSessionLayout | null;
 }) => ValidationResult$1;
 
 /**
@@ -798,7 +1243,10 @@ declare const getRateLimitStatus: (key: string, limit: number) => Promise<RateLi
 declare const clearRateLimit: (key: string) => Promise<void>;
 /**
  * Clear all rate limits.
- * Useful for testing or server restart.
+ * Intended for testing or dev-mode server reset only.
+ * CORE-O8: throws in production to prevent accidental global counter wipe across
+ * all tenants. If you need a production-safe reset, pass a scoped key to
+ * `clearRateLimit` or implement a tenant-namespaced strategy.
  */
 declare const clearAllRateLimits: () => Promise<void>;
 
@@ -815,6 +1263,10 @@ declare const validateInputByType: ({ typeText, value, rootKey, filePath, }: {
     filePath?: string;
 }) => Promise<ValidationResult>;
 
+declare const normalizeOrigin: ({ value, secure }: {
+    value: string;
+    secure: boolean;
+}) => string;
 declare const allowedOrigin: (origin: string) => boolean;
 
 declare const registerSyncAbortController: (socketId: string, cb: string, controller: AbortController) => string;
@@ -825,6 +1277,47 @@ declare const unregisterApiAbortController: (key: string) => void;
 declare const abortApiByResponseIndex: (socketId: string, responseIndex: number | string) => boolean;
 declare const abortAllForSocket: (socketId: string) => void;
 
+/**
+ * Handle returned by {@link issueOneTimeToken}. `token` is the RAW token to hand
+ * to the caller (embed in the emailed URL); call `store()` to persist its hash
+ * to Redis with the configured TTL. Persisting is a separate step so the caller
+ * can run veto logic (hooks, validation) between minting and committing without
+ * leaving an orphan Redis key.
+ */
+interface OneTimeTokenHandle {
+    /** The raw, single-use token. Returned exactly once; never stored verbatim. */
+    token: string;
+    /** Persist `sha256(token)` -> `payload` in Redis with the issue TTL. */
+    store(): Promise<void>;
+}
+/**
+ * Mint a one-time token in `namespace` carrying `payload`, redeemable for `ttl`
+ * seconds. Returns the raw token plus a `store()` committer. The payload is
+ * serialised to a string (objects via JSON); on redemption it is returned as a
+ * string and the caller parses it (or use {@link consumeOneTimeTokenJson}).
+ *
+ * @param namespace Key namespace (e.g. `'-pwreset'`, `'-email-change'`) — routed
+ *   through `formatKey` so the active key formatter / project prefix applies.
+ * @param ttlSeconds Time-to-live in seconds for the stored hash.
+ * @param payload   Value bound to the token. A string is stored verbatim; any
+ *   other value is `JSON.stringify`-d.
+ */
+declare const issueOneTimeToken: (namespace: string, ttlSeconds: number, payload: string | Record<string, unknown>) => OneTimeTokenHandle;
+/**
+ * Atomically validate + consume a one-time token from `namespace`. Returns the
+ * stored payload STRING on success (and deletes the entry, so it can never be
+ * reused), or `null` when the token is missing / expired / malformed / already
+ * consumed. A single `MULTI` `GET`+`DEL` guarantees at-most-once redemption.
+ */
+declare const consumeOneTimeToken: (namespace: string, token: string) => Promise<string | null>;
+/**
+ * Convenience wrapper over {@link consumeOneTimeToken} that JSON-parses the
+ * stored payload into `T`. Returns `null` on miss OR on a malformed JSON
+ * payload. Use when the token was issued with an object payload.
+ */
+declare const consumeOneTimeTokenJson: <T>(namespace: string, token: string) => Promise<T | null>;
+declare const oneTimeTokenKey: (namespace: string, token: string) => string;
+
 /**
  * Core hook contract: framework-generic payload shapes + augmentable registry.
  *
@@ -868,6 +1361,14 @@ interface HookStopSignal {
     stop: true;
     errorCode: string;
     httpStatus?: number;
+    /**
+     * Optional output override for per-recipient hooks (`preSyncRecipient`).
+     * When present on a stop signal the framework DOES NOT skip the recipient —
+     * instead it sends this value in place of the full `serverOutput`. Use to
+     * redact PII before delivery without excluding the socket from the fanout.
+     * Ignored by all other hook dispatch sites.
+     */
+    overrideOutput?: unknown;
 }
 /** Handlers return undefined / void to continue, or a stop signal to abort the main flow. */
 type HookResult = void | undefined | HookStopSignal;
@@ -948,6 +1449,41 @@ interface PostSyncAuthorizePayload {
     /** Optional transport tag — see {@link PreApiValidatePayload.transport}. */
     transport?: 'socket' | 'http';
 }
+interface PreSyncValidatePayload {
+    routeName: string;
+    data: Record<string, unknown>;
+    user: HookSessionShape | null;
+    receiver: string;
+    /** Optional transport tag — see {@link PreApiValidatePayload.transport}. */
+    transport?: 'socket' | 'http';
+}
+interface PostSyncValidatePayload extends PreSyncValidatePayload {
+    validation: {
+        status: 'success';
+    } | {
+        status: 'error';
+        message: string;
+    };
+}
+interface PreSyncExecutePayload {
+    routeName: string;
+    data: Record<string, unknown>;
+    user: HookSessionShape | null;
+    receiver: string;
+    /** Optional transport tag — see {@link PreApiValidatePayload.transport}. */
+    transport?: 'socket' | 'http';
+}
+interface PostSyncExecutePayload {
+    routeName: string;
+    data: Record<string, unknown>;
+    user: HookSessionShape | null;
+    receiver: string;
+    result: unknown;
+    error: Error | null;
+    durationMs: number;
+    /** Optional transport tag — see {@link PreApiValidatePayload.transport}. */
+    transport?: 'socket' | 'http';
+}
 interface PreSyncFanoutPayload {
     routeName: string;
     data: Record<string, unknown>;
@@ -1012,6 +1548,14 @@ interface CorsRejectedPayload {
     allowLocalhost: boolean;
     /** Optional route the rejected request was for. */
     route?: string;
+    /**
+     * Why the request was rejected (server HOK-27). Distinguishes a present-but-
+     * disallowed Origin (`'origin-not-allowed'`) from a MISSING Origin header
+     * (`'origin-missing'`, the 403 dispatched by the server's origin gate) and the
+     * normalization-failure case. Optional so existing `allowedOrigin()` callers
+     * that don't set it stay source-compatible.
+     */
+    reason?: 'origin-not-allowed' | 'origin-missing' | 'origin-malformed';
 }
 interface PreSessionRefreshPayload {
     token: string;
@@ -1027,6 +1571,18 @@ interface PostSessionRefreshPayload {
     /** True if Redis EXPIRE succeeded; false on failure or non-existent key. */
     applied: boolean;
 }
+interface SessionCreatedPayload {
+    token: string;
+    userId: string;
+    /** How the session came to exist (credentials login, OAuth, refresh-mint, ...). */
+    via?: string;
+}
+interface SessionRevokedPayload {
+    token: string;
+    userId: string | null;
+    /** Why the session was revoked (logout, kicked-by-new-device, admin, expiry, ...). */
+    reason?: string;
+}
 interface OnUploadStartPayload {
     userId: string;
     contentType: string;
@@ -1039,6 +1595,20 @@ interface OnUploadCompletePayload {
     sizeBytes: number;
     uploadKind: 'avatar' | string;
 }
+interface PreAvatarServePayload {
+    /** The route path requested (`/avatars/:fileId`). */
+    routePath: string;
+    /** The allowlisted file id resolved from the route path. */
+    fileId: string;
+}
+interface PostAvatarServePayload {
+    routePath: string;
+    fileId: string;
+    /** Disk extension of the format that was served (e.g. `'webp'`). */
+    extension: string;
+    /** Content-Type header sent for the served file. */
+    contentType: string;
+}
 interface CsrfMismatchPayload {
     /** Path of the rejected request. */
     route: string;
@@ -1051,6 +1621,18 @@ interface CsrfMismatchPayload {
     /** Whether a token was provided in `x-csrf-token` (presence only — never the value). */
     providedToken: boolean;
 }
+interface PreSocketMessagePayload {
+    /** Which socket pipeline received the message. */
+    channel: 'api' | 'sync';
+    /** Socket.io connection id of the originator. */
+    socketId: string;
+    /** Handshake address of the originator (best-effort; honours no proxy trust). */
+    ip: string;
+    /** Whether the originating socket carried a session token (presence only — never the value). */
+    authenticated: boolean;
+    /** Raw route name from the message envelope, when present (un-parsed, un-trusted). */
+    routeName?: string;
+}
 interface PreHttpRequestPayload {
     /** HTTP method (always uppercase: GET/POST/...). */
     method: string;
@@ -1067,8 +1649,64 @@ interface PreHttpRequestPayload {
      */
     headers: Record<string, string>;
 }
+interface PostHttpRequestPayload {
+    /** HTTP method (always uppercase). */
+    method: string;
+    /** Request URL (path + query). */
+    url: string;
+    /** Caller-supplied or framework-generated `X-Request-Id`. */
+    requestId: string;
+    /** Final HTTP status code written to the response. */
+    statusCode: number;
+    /** Wall-clock duration from request receipt to response, in ms. */
+    durationMs: number;
+}
+interface ApiAuthRejectedPayload {
+    /** Resolved route name (`api/billing/getInvoice/v1`). */
+    routeName: string;
+    /** Why auth failed. `'login-required'` = no/invalid session on a login route;
+     *  `'additional-failed'` = a session existed but an `additional[]` predicate
+     *  rejected; `'invalid-condition'` = a misconfigured predicate (setup error). */
+    reason: 'login-required' | 'additional-failed' | 'invalid-condition';
+    /** Session user id when a (insufficient) session was present, else null. */
+    userId: string | null;
+    /** Resolved client IP (honours `http.trustProxy`). */
+    ip?: string;
+    /** Transport the request arrived on. */
+    transport?: 'socket' | 'http';
+    /** The specific `additional[]` key that failed, when `reason === 'additional-failed'`. */
+    failedKey?: string;
+}
+interface PreSyncRecipientPayload {
+    /** Resolved route name (`sync/board/moveCard/v1`). */
+    routeName: string;
+    /** Room code / receiver this fanout is for. */
+    receiver: string;
+    /** Socket id of THIS recipient. */
+    recipientSocketId: string;
+    /**
+     * Recipient's session user id.  `null` by default (avoids a Redis read per
+     * recipient on the hot path).  Populated when the consumer registers a
+     * `resolveRecipientUser` function via `registerHookHandler` options.
+     */
+    recipientUserId: string | null;
+    /** The server-validated output about to be sent. */
+    serverOutput: unknown;
+}
+interface PreServerStopPayload {
+    /** Why the server is stopping — the signal name, or `'manual'` for a programmatic stop. */
+    reason: 'SIGTERM' | 'SIGINT' | 'SIGHUP' | 'manual';
+    /**
+     * Soft budget (ms) the server intends to wait for shutdown handlers + in-flight
+     * requests to drain before forcing exit. Handlers should not block longer than
+     * this. `undefined` when the server applies no deadline.
+     */
+    timeoutMs?: number;
+}
 interface HookPayloads {
     preHttpRequest: PreHttpRequestPayload;
+    postHttpRequest: PostHttpRequestPayload;
+    preSocketMessage: PreSocketMessagePayload;
     preApiValidate: PreApiValidatePayload;
     postApiValidate: PostApiValidatePayload;
     preApiExecute: PreApiExecutePayload;
@@ -1078,19 +1716,30 @@ interface HookPayloads {
     postApiRespond: PostApiRespondPayload;
     preSyncAuthorize: PreSyncAuthorizePayload;
     postSyncAuthorize: PostSyncAuthorizePayload;
+    preSyncValidate: PreSyncValidatePayload;
+    postSyncValidate: PostSyncValidatePayload;
+    preSyncExecute: PreSyncExecutePayload;
+    postSyncExecute: PostSyncExecutePayload;
     preSyncFanout: PreSyncFanoutPayload;
     postSyncFanout: PostSyncFanoutPayload;
+    preSyncRecipient: PreSyncRecipientPayload;
     preSyncStream: PreSyncStreamPayload;
     postSyncStream: PostSyncStreamPayload;
     apiError: ApiErrorPayload;
     syncError: SyncErrorPayload;
+    apiAuthRejected: ApiAuthRejectedPayload;
     rateLimitExceeded: RateLimitExceededPayload;
     corsRejected: CorsRejectedPayload;
     csrfMismatch: CsrfMismatchPayload;
     preSessionRefresh: PreSessionRefreshPayload;
     postSessionRefresh: PostSessionRefreshPayload;
+    sessionCreated: SessionCreatedPayload;
+    sessionRevoked: SessionRevokedPayload;
     onUploadStart: OnUploadStartPayload;
     onUploadComplete: OnUploadCompletePayload;
+    preAvatarServe: PreAvatarServePayload;
+    postAvatarServe: PostAvatarServePayload;
+    preServerStop: PreServerStopPayload;
 }
 interface PreErrorNormalizePayload {
     response: ErrorResponseInput;
@@ -1117,10 +1766,10 @@ type DispatchResult = {
     stopped: true;
     signal: HookStopSignal;
 };
-declare const registerHook: <TName extends HookName>(name: TName, handler: HookHandler<HookPayloads[TName]>) => void;
+declare const registerHook: <TName extends HookName>(name: TName, handler: HookHandler<HookPayloads[TName]>) => (() => void);
 declare const dispatchHook: <TName extends HookName>(name: TName, payload: HookPayloads[TName]) => Promise<DispatchResult>;
 declare const clearAllHooks: () => void;
-declare const registerSyncHook: <TName extends SyncHookName>(name: TName, handler: SyncHookHandler<SyncHookPayloads[TName]>) => void;
+declare const registerSyncHook: <TName extends SyncHookName>(name: TName, handler: SyncHookHandler<SyncHookPayloads[TName]>) => (() => void);
 declare const dispatchSyncHook: <TName extends SyncHookName>(name: TName, payload: SyncHookPayloads[TName]) => void;
 
-export { type ApiErrorPayload, type ApiResponseEnvelope, AuthProps, type AvatarConfig, type AvatarConfigInput, BOOT_KEY_PREFIX, BaseSessionLayout, type CheckRateLimitParams, type CorsRejectedPayload, type CreateLocalizedNormalizerInput, type CsrfConfig, type CsrfCookieOptions, type CsrfMismatchPayload, DEFAULT_AVATAR_CONFIG, DEFAULT_CLIENT_KEY, DEFAULT_CSRF_CONFIG, DEFAULT_ENV_FILES, type DeployConfigShape, type DeployDevelopmentShape, type DeployEnvironmentShape, type DeployResourceShape, type DeployRoutingShape, type DispatchResult, type EmailMessage, type EmailResult, type EmailSender, type EmailSenderRegistry, type ErrorFormatter, type ErrorFormatterContext, ErrorParam, ErrorResponseInput, type ErrorTracker, type ErrorTrackerContext, type ErrorTrackerEvent, type ErrorTrackerUser, GENERATED_API_DOCS_PATH, GENERATED_API_SCHEMAS_PATH, GENERATED_SOCKET_TYPES_PATH, type HookHandler, type HookName, type HookPayloads, type HookResult, type HookSessionShape, type HookStopSignal, type HttpMethod, type LanguageCode, type LocaleReloader, type LocalizedNormalizer, type NormalizeErrorResponseInput, NormalizedErrorResponse, type OnUploadCompletePayload, type OnUploadStartPayload, PUBLIC_DIR, type PostApiExecutePayload, type PostApiRespondPayload, type PostApiValidatePayload, type PostErrorNormalizePayload, type PostSessionRefreshPayload, type PostSyncFanoutPayload, type PreApiExecutePayload, type PreApiRespondPayload, type PreApiValidatePayload, type PreErrorNormalizePayload, type PreSessionRefreshPayload, type PreSyncAuthorizePayload, type PreSyncFanoutPayload, type PresetDefinition, type ProcessUploadInput, type ProcessUploadResult, ROOT_DIR, type RateLimitExceededPayload, type RateLimitResult, type RateLimitStrategy, type RedisConnectionOptions, type RedisKeyFormatter, type RuntimeApiMapsResult, type RuntimeEnv, type RuntimeMapsProvider, type RuntimeSyncMapsResult, SERVER_DIR, SERVER_FUNCTIONS_DIR, SHARED_DIR, SRC_DIR, type ServiceDefinition, type ServicesConfigShape, type SocketMiddleware, type SpanResult, type SyncErrorPayload, type SyncHookHandler, type SyncHookName, type SyncHookPayloads, TSCONFIG_ALIAS_FILES, type TranslateFunction, type TranslateInput, UPLOADS_DIR, type ValidationResult$1 as ValidationResult, abortAllForSocket, abortApiByResponseIndex, abortSyncByCb, acquireLease, allowedOrigin, type apiMessage, applyErrorFormatter, applySocketMiddlewares, applyStrayKeyPrefix, attachSocketRedisAdapter, bootstrapEnv, captureException, captureExceptionAcrossTrackers, captureMessage, captureMessageAcrossTrackers, checkRateLimit, clearAllHooks, clearAllRateLimits, clearRateLimit, clearSocketMiddlewares, collectSynchronizedEnvKeys, computeSynchronizedEnvHashes, createLocalizedNormalizer, defaultRateLimitStrategy, defaultRedisKeyFormatter, dispatchHook, dispatchSyncHook, env, extractLanguageFromHeader, extractTokenFromRequest, extractTokenFromSocket, formatKey, getActiveErrorTrackers, getAvatarConfig, getBindAddress, getCookieValue, getCsrfConfig, getDeployConfig, getEffectiveHttpMethod, getEmailSender, getEmailSenderByName, getEnvFiles, getErrorFormatter, getGeneratedApiDocsPath, getGeneratedApiSchemasPath, getGeneratedSocketTypesPath, getIoInstance, getLocaleReloader, getLocalizedNormalizer, getParams, getPrismaClient, getPrismaClientFor, getPrismaClientKeys, getPublicDir, getRateLimitStatus, getRateLimitStrategy, getRedactedLogKeys, getRedisClient, getRedisClientFor, getRedisClientKeys, getRedisConnectionOptions, getRedisKeyFormatter, getRuntimeApiMaps, getRuntimeSyncMaps, getServerDir, getServerFunctionDirs, getServerFunctionsDir, getServicesConfig, getSharedDir, getSocketMiddlewares, getSrcDir, getUploadsDir, hasCookie, hashSynchronizedValue, inferHttpMethod, initConsolelog, initSharedSentry, isDeployConfigRegistered, isEmailSenderRegistered, isFalsy, isLocalizedNormalizerRegistered, isMethodAllowed, isPrismaClientRegistered, isProduction, isRedactedLogKey, isRedisClientRegistered, isRuntimeMapsProviderRegistered, isServicesConfigRegistered, listEmailSenderNames, loadEnvFiles, normalizeErrorResponse, prisma, processUpload, readBootUuid, recordMetricAcrossTrackers, redis, registerApiAbortController, registerAvatarConfig, registerBindAddress, registerCsrfConfig, registerDeployConfig, registerEmailSender, registerEmailSenders, registerErrorFormatter, registerErrorTracker, registerErrorTrackers, registerHook, registerLocaleReloader, registerLocalizedNormalizer, registerPrismaClient, registerRateLimitStrategy, registerRedactedLogKeys, registerRedisClient, registerRedisKeyFormatter, registerRuntimeMapsProvider, registerServicesConfig, registerSocketMiddleware, registerSyncAbortController, registerSyncHook, releaseLease, renewLease, resetClientsForTests, resetCsrfConfigForTests, resetRedactedLogKeysForTests, resetRedisKeyFormatterForTests, resolveEnvKey, resolveErrorMessage, resolveFromRoot, serveAvatar, setErrorTrackerUser, setIoInstance, setSentryUser, startSpan, startSpanAcrossTrackers, type syncMessage, unregisterApiAbortController, unregisterSyncAbortController, validateInputByType, validateRequest, writeBootUuid };
+export { type ApiAuthRejectedPayload, type ApiErrorPayload, type ApiResponseEnvelope, AuthProps, type AvatarConfig, type AvatarConfigInput, BOOT_KEY_PREFIX, BaseSessionLayout, type CheckRateLimitParams, type CookiePrefixConstraints, type CorsRejectedPayload, type CreateLocalizedNormalizerInput, type CsrfConfig, type CsrfCookieOptions, type CsrfMismatchPayload, DEFAULT_AVATAR_CONFIG, DEFAULT_CLIENT_KEY, DEFAULT_CSRF_CONFIG, DEFAULT_ENV_FILES, DEFAULT_REDACTED_LOG_KEYS, DEPTH_TRUNCATED_PLACEHOLDER, DeepPartial, type DeployConfigShape, type DeployDevelopmentShape, type DeployEnvironmentShape, type DeployResourceShape, type DeployRoutingShape, type DispatchResult, type EmailAttachment, type EmailMessage, type EmailResult, type EmailSender, type EmailSenderRegistry, type ErrorFormatter, type ErrorFormatterContext, ErrorParam, ErrorResponseInput, type ErrorTracker, type ErrorTrackerContext, type ErrorTrackerEvent, type ErrorTrackerUser, type FormatterEnvelope, GENERATED_API_DOCS_PATH, GENERATED_API_SCHEMAS_PATH, GENERATED_SOCKET_TYPES_PATH, HealthHashConfig, type HealthHashDescriptor, type HookHandler, type HookName, type HookPayloads, type HookResult, type HookSessionShape, type HookStopSignal, type HttpMethod, type LanguageCode, type LocaleReloader, type LocalizedNormalizer, type NormalizeErrorResponseInput, NormalizedErrorResponse, type OnUploadCompletePayload, type OnUploadStartPayload, type OneTimeTokenHandle, PUBLIC_DIR, type PeerRequire, type PostApiExecutePayload, type PostApiRespondPayload, type PostApiValidatePayload, type PostAvatarServePayload, type PostErrorNormalizePayload, type PostHttpRequestPayload, type PostSessionRefreshPayload, type PostSyncAuthorizePayload, type PostSyncExecutePayload, type PostSyncFanoutPayload, type PostSyncValidatePayload, type PreApiExecutePayload, type PreApiRespondPayload, type PreApiValidatePayload, type PreAvatarServePayload, type PreCaptureFilter, type PreErrorNormalizePayload, type PreHttpRequestPayload, type PreServerStopPayload, type PreSessionRefreshPayload, type PreSocketMessagePayload, type PreSyncAuthorizePayload, type PreSyncExecutePayload, type PreSyncFanoutPayload, type PreSyncRecipientPayload, type PreSyncValidatePayload, type PresetDefinition, type ProcessUploadInput, type ProcessUploadResult, REDACTED_PLACEHOLDER, ROOT_DIR, type RateLimitExceededPayload, type RateLimitResult, type RateLimitStrategy, type RedisConnectionOptions, type RedisKeyFormatter, type Registry, type RegistryOptions, type ResolveClientIpParams, type RoomNameFormatter, type RoomNameFormatterContext, type RuntimeApiMapsResult, type RuntimeEnv, type RuntimeMapsProvider, type RuntimeSyncMapsResult, SERVER_DIR, SERVER_FUNCTIONS_DIR, SHARED_DIR, SRC_DIR, type ServiceDefinition, type ServicesConfigShape, type SessionCreatedPayload, type SessionLogoutInput, type SessionProvider, type SessionRevokedPayload, type SessionSaveResult, type SocketMiddleware, type SpanHandle, type SpanResult, type SyncErrorPayload, type SyncHookHandler, type SyncHookName, type SyncHookPayloads, TSCONFIG_ALIAS_FILES, type TranslateFunction, type TranslateInput, UNKNOWN_CLIENT_IP, UPLOADS_DIR, type ValidationResult$1 as ValidationResult, abortAllForSocket, abortApiByResponseIndex, abortSyncByCb, acquireLease, allowedOrigin, type apiMessage, appendErrorTracker, applyCookiePrefixConstraints, applyErrorFormatter, applySocketMiddlewares, applyStrayKeyPrefix, attachSocketRedisAdapter, bootstrapEnv, captureException, captureExceptionAcrossTrackers, captureMessage, captureMessageAcrossTrackers, checkRateLimit, clearAllHooks, clearAllRateLimits, clearRateLimit, clearSocketMiddlewares, collectSynchronizedEnvKeys, computeSynchronizedEnvHashes, consumeOneTimeToken, consumeOneTimeTokenJson, createLocalizedNormalizer, createRegistry, defaultRateLimitStrategy, defaultRedisKeyFormatter, defaultRoomNameFormatter, deriveTokenBucketId, describeHealthHashConfig, dispatchHook, dispatchSyncHook, ensurePeerDepInstalled, env, escapeHtml, extractLanguageFromHeader, extractTokenFromRequest, extractTokenFromSocket, flushErrorTrackers, formatKey, formatRoomName, getActiveErrorTrackers, getAvatarConfig, getBindAddress, getCookieValue, getCsrfConfig, getCurrentErrorTrackerIdentity, getDeployConfig, getEffectiveHttpMethod, getEmailSender, getEmailSenderByName, getEnv, getEnvFiles, getErrorFormatter, getGeneratedApiDocsPath, getGeneratedApiSchemasPath, getGeneratedSocketTypesPath, getIoInstance, getLocaleReloader, getLocalizedNormalizer, getParams, getPrismaClient, getPrismaClientFor, getPrismaClientKeys, getPublicDir, getRateLimitStatus, getRateLimitStrategy, getRedactedLogKeys, getRedisClient, getRedisClientFor, getRedisClientKeys, getRedisConnectionOptions, getRedisKeyFormatter, getRegisteredSessionProvider, getRoomNameFormatter, getRuntimeApiMaps, getRuntimeSyncMaps, getServerDir, getServerFunctionDirs, getServerFunctionsDir, getServicesConfig, getSharedDir, getSocketMiddlewares, getSrcDir, getUploadsDir, hasCookie, hashSynchronizedValue, hashSynchronizedValueWith, inferHttpMethod, initConsolelog, initSharedSentry, isDeployConfigRegistered, isEmailSenderRegistered, isFalsy, isGetMethodName, isLocalizedNormalizerRegistered, isLoopbackIp, isMethodAllowed, isPrismaClientRegistered, isProduction, isRedactedLogKey, isRedisClientRegistered, isRuntimeMapsProviderRegistered, isServicesConfigRegistered, isSessionProviderRegistered, issueOneTimeToken, listEmailSenderNames, loadEnvFiles, loadPeer, normalizeErrorResponse, normalizeOrigin, oneTimeTokenKey, performLogout, prisma, processUpload, readBootUuid, readSession, recordMetricAcrossTrackers, redis, registerApiAbortController, registerAvatarConfig, registerBindAddress, registerCsrfConfig, registerDeployConfig, registerEmailSender, registerEmailSenders, registerErrorFormatter, registerErrorTracker, registerErrorTrackers, registerHook, registerLocaleReloader, registerLocalizedNormalizer, registerPreCaptureFilter, registerPrismaClient, registerRateLimitStrategy, registerRedactedLogKeys, registerRedisClient, registerRedisKeyFormatter, registerRoomNameFormatter, registerRuntimeMapsProvider, registerServicesConfig, registerSessionProvider, registerSocketMiddleware, registerStrayPrefixCommand, registerSyncAbortController, registerSyncHook, releaseLease, removeSession, renewLease, resetClientsForTests, resetCsrfConfigForTests, resetRedactedLogKeysForTests, resetRedisKeyFormatterForTests, resetSessionProviderForTests, resolveClientIp, resolveEnvKey, resolveErrorMessage, resolveFromRoot, resolveHealthHashConfig, resolveHealthHashConfigFromDescriptor, runWithErrorTrackerIdentity, runWithErrorTrackerIdentityScope, sanitizeErrorString, sanitizeErrorStrings, sanitizeForLog, serveAvatar, setCurrentErrorTrackerIdentity, setErrorTrackerUser, setIoInstance, setSentryUser, startSpan, startSpanAcrossTrackers, startSpanHandle, type syncMessage, tryCatch, tryCatchSync, unregisterApiAbortController, unregisterSyncAbortController, validateInputByType, validateRequest, writeBootUuid, writeSession };