@luckystack/core 0.10.1 → 0.11.0

package/docs/session-types.md

@@ -1,180 +1,5 @@
-# Session Types
+# Session types
 
-> Deep specs for the foundational session/auth types plus `validateRequest`, `isFalsy`, and `validateInputByType`. Source: `packages/core/src/sessionTypes.ts`, `validateRequest.ts`, `runtimeTypeValidation.ts`.
+The shared session layout provides a common identity contract across authentication and transport packages; applications extend it in their own type declarations rather than modifying the framework base. A session exposed to a browser is not a safe place for credential hashes or private adapter data. See `../src/sessionTypes.ts`, `../../login/src/sessionSanitizer.ts`.
 
-## Overview
-
-`BaseSessionLayout` is the structural contract every project session type extends. It lives in `@luckystack/core` (not `@luckystack/login`) so `validateRequest` can consume it without creating a circular dep: login depends on core for prisma/redis, so the session shape has to live in the lower layer. `@luckystack/login` re-exports the type for ergonomics — existing `import type { BaseSessionLayout } from '@luckystack/login'` paths keep working.
-
-`AuthProps` defines the auth gate that every API/sync handler exports (`login: true/false` + an optional `additional[]` predicate list). `validateRequest({ auth, user })` is the runtime check that turns those declarations into a `ValidationResult`.
-
-`validateInputByType` is the runtime input validator used by the api/sync handlers in dev. It lazy-loads `@luckystack/devkit` (the heavy TS compiler resolver) only when running in non-production. In production it short-circuits to success because the prod esbuild bundle marks devkit as external and the validator should not need TS to validate request bodies at request time.
-
-## Types
-
-```typescript
-export interface SessionLocation {
-  pathName: string;
-  searchParams?: Record<string, string>;
-}
-
-export interface BaseSessionLayout {
-  id: string;
-  token: string;
-  email?: string | null;
-  name?: string | null;
-  avatar?: string | null;
-  avatarFallback?: string | null;
-  admin?: boolean | null;
-  language?: string | null;
-  location?: SessionLocation;
-  roomCodes?: string[];
-  csrfToken?: string;
-  lastLogin?: Date | string | null;
-  previousLogin?: Date | string | null;
-}
-
-export interface AuthProps {
-  login: boolean;
-  additional?: {
-    key: keyof BaseSessionLayout;
-    value?: unknown;
-    type?: 'string' | 'number' | 'boolean';
-    nullish?: boolean;
-    mustBeFalsy?: boolean;
-  }[];
-}
-
-export interface ValidationResult {
-  status: 'success' | 'error';
-  errorCode?: string;
-  errorParams?: { key: string; value: string | number | boolean }[];
-  httpStatus?: number;
-}
-```
-
-### Extending `BaseSessionLayout`
-
-Projects extend the type in their own `config.ts`:
-
-```typescript
-import type { BaseSessionLayout } from '@luckystack/core';
-
-export interface SessionLayout extends BaseSessionLayout {
-  organizationId?: string;
-  role?: 'member' | 'admin' | 'owner';
-}
-```
-
-The framework's `validateRequest` only inspects keys it knows from `BaseSessionLayout`; project-specific keys are checked via `additional[]`.
-
-## API Reference
-
-### `isFalsy(value: unknown): boolean`
-
-**Signature:**
-```typescript
-export const isFalsy = (value: unknown): boolean
-```
-
-**Behavior:** Returns `true` for `false`, `0`, `0n`, `''`, `null`, `undefined`, or `NaN`. Everything else is truthy.
-
-**Note:** This is a stricter "falsy" than JavaScript's coercion-based check because it ALSO treats `NaN` as falsy. Used inside `validateRequest` for the `mustBeFalsy` predicate.
-
-### `validateRequest({ auth, user }): ValidationResult`
-
-**Signature:**
-```typescript
-export const validateRequest = ({
-  auth,
-  user,
-}: {
-  auth: AuthProps;
-  user: BaseSessionLayout;
-}): ValidationResult
-```
-
-**Behavior (in order):**
-1. If `auth.additional` is undefined → returns `{ status: 'success' }` immediately. (The `login` flag is enforced by the surrounding handler, not by this function.)
-2. For each `condition` in `auth.additional`:
-   - If `condition.key` is not in `user` → returns `{ status: 'error', errorCode: 'auth.invalidCondition', errorParams: [{ key: 'key', value: condition.key }], httpStatus: 500 }`. This is a developer setup error, not a runtime auth failure.
-   - Reads `val = user[condition.key]`. Computes `isNullish = val === null || val === undefined`.
-   - `nullish: true` requires `isNullish`; `nullish: false` requires NOT `isNullish`. Mismatch → forbid.
-   - `type: 'string' | 'number' | 'boolean'` requires `typeof val === <type>` (skipped when `val` is nullish). Mismatch → forbid.
-   - `'value' in condition` requires strict equality `val === condition.value`. The membership check distinguishes "no exact-value constraint" from `value: undefined` (the latter explicitly demands `val === undefined`).
-   - `mustBeFalsy: true` requires `isFalsy(val)`; `mustBeFalsy: false` requires `!isFalsy(val)`. Mismatch → forbid.
-3. After all conditions pass → returns `{ status: 'success' }`.
-
-**Forbid shape:**
-```typescript
-{ status: 'error', errorCode: 'auth.forbidden', errorParams: [{ key: 'key', value: <key> }], httpStatus: 403 }
-```
-
-**Constraint AND-semantics:** Multiple fields on a single `additional` entry are AND'd (every specified field must pass). Entries across the array are also AND'd.
-
-**Example — admin-only endpoint:**
-```typescript
-export const auth: AuthProps = {
-  login: true,
-  additional: [{ key: 'admin', value: true, type: 'boolean' }],
-};
-```
-
-**Example — verified email required:**
-```typescript
-export const auth: AuthProps = {
-  login: true,
-  additional: [{ key: 'email', nullish: false, type: 'string' }],
-};
-```
-
-### `validateInputByType({ typeText, value, rootKey, filePath? }): Promise<ValidationResult>`
-
-**Signature:**
-```typescript
-type ValidationResult =
-  | { status: 'success' }
-  | { status: 'error'; message: string };
-
-export const validateInputByType = async ({
-  typeText,
-  value,
-  rootKey,
-  filePath,
-}: {
-  typeText?: string;
-  value: unknown;
-  rootKey: string;
-  filePath?: string;
-}): Promise<ValidationResult>
-```
-
-**Behavior:**
-1. When `typeText` is empty, whitespace, or literal `'any'` → returns `{ status: 'success' }`.
-2. When `process.env.NODE_ENV === 'production'` → returns `{ status: 'success' }` (avoids loading the TS compiler in prod).
-3. Otherwise lazy-imports `@luckystack/devkit` via an indirect module ID (`const devkitModuleId: string = '@luckystack/devkit'; await import(devkitModuleId)`) so `tsc` doesn't try to resolve devkit at build time (devkit depends on core — a literal import would be a build-time circular dep).
-4. Calls `devkit.resolveRuntimeTypeText({ typeText, filePath })`. On `status: 'error'` returns `{ status: 'error', message: '<rootKey>: <message>' }`.
-5. Otherwise calls the internal `validateType(resolvedType.typeText, value, rootKey)` recursive validator.
-
-**Supported type forms (validateType):**
-- Primitives: `string`, `number`, `boolean`, `true`, `false`, `null`, `undefined`, `Date` (accepts ISO string or `Date` instance).
-- String literal types (single-quoted or double-quoted) and finite numeric literals, including negative, decimal, exponent, hexadecimal, binary, octal, and numeric-separator forms.
-- Unions (`A | B`) — succeeds on first matching branch.
-- Intersections (`A & B`) — requires all branches to succeed.
-- Arrays (`T[]`) — checks every element.
-- `Record<K, V>` — accepts any non-array object.
-- Object literals `{ key?: T; key2: T2; [index: keyof IndexKey]: T }` — checks each named field, applies index signatures for unknown keys.
-- `any` / `unknown` — always succeeds.
-- Unresolved type aliases or generics return `{ status: 'error', message: '<path>: unresolved type <name>' }`.
-
-**Edge cases:**
-- The `__RUNTIME_UNRESOLVED__::<message>` sentinel from devkit surfaces as `{ status: 'error', message: '<path>: <message>' }` so a missing project type doesn't crash the request.
-- Object validation rejects unknown keys when there is no matching index signature.
-- Index-signature keys can be `string`, `number`, string-literal unions, or literal types; `number` keys require the key to match `/^-?\d+(\.\d+)?$/`.
-
-## Related
-
-- Function INDEX: `packages/core/CLAUDE.md`
-- Architecture: `docs/ARCHITECTURE_SESSION.md`, `docs/ARCHITECTURE_AUTH.md`, `docs/ARCHITECTURE_API.md`
-- README: `packages/core/README.md`
-- Source: `packages/core/src/sessionTypes.ts`, `validateRequest.ts`, `runtimeTypeValidation.ts`
+Authorization predicates must be evaluated on server-resolved session data, not caller-supplied request fields. Missing or invalid session fields should not grant permissions; see `../src/validateRequest.ts`. Keep input validation and session authorization separate: a well-formed payload does not imply an authorized caller (`../src/runtimeTypeValidation.ts`).

package/docs/socket-bootstrap.md

@@ -1,389 +1,9 @@
-# Socket Bootstrap
+# Socket bootstrap
 
-> Deep specs for socket transport bootstrap, token extraction, CORS check, offline queue, CSRF, cookies, service-route helpers and event constants. Source: `packages/core/src/`.
+The socket entry shares transport contracts with HTTP without conflating their security models. Keep browser-only helpers behind `/client`; the server barrel can import Node APIs. Socket handshakes must apply the origin policy and the configured session mode; do not treat a declared HTTP method as socket authorization. See `../src/client.ts`, `../src/extractToken.ts`, `../src/checkOrigin.ts`, `../../server/src/loadSocket.ts`.
 
-## Overview
+Cookie-backed writes require CSRF tokens, while bearer-mode callers explicitly supply credentials. CSRF tokens cached in the browser are origin-scoped so an unrelated endpoint cannot inherit them. Offline queues are a delivery convenience, not permission to replay a request without server-side auth or validation. See `../src/csrf.ts`, `../src/offlineQueue.ts` and `../../server/docs/security-defaults.md`.
 
-This topic covers the wiring around the LuckyStack socket transport:
+**Local socket maps are unreachable by default.** The adapter's room and socket-id maps and the server's socket list know only this process's sockets, so a helper built on them looks complete on one instance and silently misses the rest of the cluster on two — a failure that surfaces only in a split deployment, where it is hardest to attribute. Three layers keep consumer code off that path (ADR 0061): a lint rule catches what is written, a cross-instance room helper makes the right path the shortest, and outside production the registered server is handed out as a guarded view that throws on the same surfaces, catching computed access no static rule sees. Looking up one socket by id stays allowed. Production returns the raw server because a throw on a hot path is worse than a missed recipient. Deliberate per-instance work (cleaning up this process's own connections, sampling its backpressure) asks for the raw server explicitly and carries a lint opt-out with a reason, so a reviewer can find it. The room helper throws when no server is registered: an empty result would be indistinguishable from an empty room. Source: `../src/roomSockets.ts`, `../src/localSocketEnumerationGuard.ts`, `../src/eslint/rules/no-local-socket-enumeration.ts`.
 
-- **Server-side socket slot** — `setIoInstance` / `getIoInstance` so framework code can broadcast, plus `getRoomSockets` for cross-instance room enumeration.
-- **Room-name formatter** — `registerRoomNameFormatter` / `formatRoomName`, and the contract a formatter must honour.
-- **Client-side socket singleton** — live binding `socket`, `setSocket`, `waitForSocket`, `incrementResponseIndex`.
-- **Token extraction** — pull the session token from a Socket.io handshake (`extractTokenFromSocket`) or a Node `IncomingMessage` (`extractTokenFromRequest`).
-- **Origin check** — `allowedOrigin` for CORS-style allow-listing, with `corsRejected` hook fan-out.
-- **Offline queue** — `enqueueApiRequest`, `enqueueSyncRequest`, flushers, and per-item `dropPolicy` overrides.
-- **CSRF + httpFetch** — lazy `/auth/csrf` token cache + drop-in fetch wrapper.
-- **Wire-protocol constants** — `socketEventNames` map + per-prefix event-name builders.
-- **Route parsers** — `parseServiceRouteName`, `parseTransportRouteName`.
-- **Cookie helpers** — `getCookieValue`, `hasCookie`.
-- **HTTP helpers** — `inferHttpMethod`, `getEffectiveHttpMethod`, `isMethodAllowed`.
-
-Token extraction respects `projectConfig.session.basedToken`: when `true` (token-mode) the framework prefers `socket.handshake.auth.token` / `Authorization: Bearer ...` with the cookie as fallback. When `false` (cookie-mode) the configured session cookie is read; the bearer / handshake-auth fallback is IGNORED by default (CORE-O10 — a stolen token replayed through a header can't bypass the cookie/CSRF model) unless `projectConfig.http.acceptBearerInCookieMode` is set `true` to restore the legacy cookie-then-bearer fallback.
-
-## API Reference — IO Instance
-
-### `setIoInstance(io: SocketIOServer | null): void`
-
-**Signature:**
-```typescript
-export const setIoInstance = (io: SocketIOServer | null): void
-```
-
-**Behavior:** Stores the running Socket.io server in a module-level slot. Framework code (`@luckystack/sync`, presence package, etc.) reads via `getIoInstance()` for broadcast paths.
-
-### `getIoInstance(options?: { raw?: boolean })`
-
-Returns the registered instance or `null` when no server has been set. Callers must null-check.
-
-**Outside production the returned server is a guarded view.** Reading `sockets.adapter.rooms`, `sockets.adapter.sids`, or enumerating `sockets.sockets` (`values` / `keys` / `entries` / `forEach` / `size` / iteration) **throws**, with the same message the ESLint rule `luckystack/no-local-socket-enumeration` prints. `sockets.sockets.get(id)` stays allowed. Why: under the Redis adapter those maps only know the sockets of *this* process, so a helper built on them looks complete on one instance and silently misses the rest of the cluster on two — the failure surfaces only in production, where it is hardest to attribute. The guard moves that discovery to the first dev run. In production the raw instance is always returned; the guard costs nothing on the hot path.
-
-Pass `{ raw: true }` for deliberate per-instance work — a sweep cleaning up this process's own connections, sampling this process's backpressure. The option is the audit trail: a reviewer can grep for it. Framework-internal code and the Redis adapter always hold the raw instance.
-
-For "who is in this room" use `getRoomSockets` below, or `io.in(room).fetchSockets()` when you already hold the physical room name.
-
-### `getRoomSockets(room, { userId? })`
-
-Cross-instance room enumeration. Routes `room` through the room-name formatter under the canonical `'broadcast'` purpose (`userId` defaults to `null`, and is context only — see the formatter contract below), then asks the adapter for every member on every instance and returns the `RemoteSocket[]`. `'all'` returns every socket everywhere.
-
-It **throws** when no Socket.io server is registered. A silent `[]` in that situation is indistinguishable from "the room is empty", which is exactly the class of failure this helper exists to prevent.
-
-## API Reference — Room-Name Formatter
-
-### `registerRoomNameFormatter(fn)` / `getRoomNameFormatter()` / `formatRoomName(raw, ctx)` / `defaultRoomNameFormatter`
-
-Every room name the framework joins, leaves, broadcasts to or uses for presence passes through the registered formatter (default: identity) with a `RoomNameFormatterContext` — a `purpose` (`'join'`, `'leave'`, `'broadcast'`, `'presence'`) and the `userId` of whoever performs the operation. The intended use is a stable, user-independent transform such as per-tenant prefixing.
-
-**The contract: `userId` is context, never an input to the physical name of a content room.** For `purpose: 'broadcast'` the framework passes whichever user performs the operation — the joiner on join and rejoin, the sender on fan-out, the originator on `broadcastStream` — so for a shared room it is a *different* value on each side. A formatter that folds `userId` into the name makes join and fan-out land in different physical rooms, and every broadcast then reaches nobody: no error, `sync.noReceiversFound` at best, silence at worst. The framework cannot detect this for you, because from its side both names are just strings.
-
-Per-user isolation belongs in the raw room code the consumer chooses (put the user in the *code*, not in the formatter), or in the separate `'presence'` family, which is per-user by design.
-
-## API Reference — Client Socket Singleton
-
-### `socket: Socket | null`
-
-A live `export let` binding — importers always see the current value after `setSocket(...)` replaces it.
-
-### `setSocket(next: Socket | null): void`
-
-Stores the project's socket.io-client instance. Called from `src/_sockets/socketInitializer.ts`.
-
-### `incrementResponseIndex(): number`
-
-**Returns:** The next monotonic response index (used to build per-request reply event names like `apiResponse-42`).
-
-**Behavior:**
-- Module-scoped counter, increments before returning so the first call returns `1`.
-- Used by `apiRequest` / `syncRequest` clients to disambiguate concurrent requests on the same socket.
-
-### `waitForSocket(): Promise<Socket | null>`
-
-**Behavior:**
-- Polls every 10 ms until `socket !== null` or 500 iterations elapse (~5 seconds).
-- Returns the socket on success, `null` on timeout.
-
-**Example:**
-```typescript
-import { waitForSocket } from '@luckystack/core/client';
-
-const s = await waitForSocket();
-if (!s) throw new Error('socket never connected');
-```
-
-## API Reference — Custom Socket Middlewares
-
-The framework lets consumers wedge their own Socket.io `io.use(...)` middlewares into the bootstrap without forking `loadSocket.ts`. Registered middlewares run in registration order, before any `connect` handler — same contract as a direct `io.use(...)` call.
-
-### `registerSocketMiddleware(mw: SocketMiddleware): void`
-
-**Signature:**
-```typescript
-export type SocketMiddleware = (socket: Socket, next: (err?: Error) => void) => void;
-export const registerSocketMiddleware = (mw: SocketMiddleware): void
-```
-
-**Behavior:** Appends the middleware to a module-level list. `@luckystack/server`'s `loadSocket` calls `applySocketMiddlewares(io)` after constructing the `SocketIOServer` and before attaching the `connect` handler, so every registered middleware runs on the handshake of every incoming socket.
-
-**Example — license-key gate:**
-```typescript
-import { registerSocketMiddleware } from '@luckystack/core';
-
-registerSocketMiddleware((socket, next) => {
-  const licenseKey = socket.handshake.auth.licenseKey;
-  if (typeof licenseKey !== 'string' || !isValidLicense(licenseKey)) {
-    return next(new Error('invalid license'));
-  }
-  next();
-});
-```
-
-**Example — observability tag (Datadog APM):**
-```typescript
-import { registerSocketMiddleware } from '@luckystack/core';
-import tracer from 'dd-trace';
-
-registerSocketMiddleware((socket, next) => {
-  const span = tracer.scope().active();
-  if (span) span.setTag('socket.id', socket.id);
-  next();
-});
-```
-
-### `getSocketMiddlewares(): readonly SocketMiddleware[]`
-
-Read the registered list (frozen view). Useful for diagnostics.
-
-### `clearSocketMiddlewares(): void`
-
-Drops every registered middleware. Test/hot-reload helper.
-
-### `applySocketMiddlewares(io: SocketIOServer): void`
-
-Framework-internal — wires every registered middleware via `io.use(...)`. Called by `@luckystack/server`'s `loadSocket`; consumers should not call this directly.
-
-## API Reference — Token Extraction
-
-### `extractTokenFromSocket(socket: Socket): string | null`
-
-**Signature:**
-```typescript
-export const extractTokenFromSocket = (socket: Socket): string | null
-```
-
-**Behavior:**
-- Reads `socket.handshake.auth.token` (when it is a string) and the configured cookie (`projectConfig.http.sessionCookieName`) from `socket.handshake.headers.cookie`.
-- When `session.basedToken === true`: returns the auth-token first, falls back to the cookie.
-- When `session.basedToken === false`: returns only the cookie by default; when `http.acceptBearerInCookieMode === true`, falls back to the auth-token for legacy compatibility.
-
-**Returns:** The token string or `null`.
-
-### `extractTokenFromRequest(req: IncomingMessage): string | null`
-
-**Signature:**
-```typescript
-export const extractTokenFromRequest = (req: IncomingMessage): string | null
-```
-
-**Behavior:**
-- Reads `req.headers.authorization` and extracts the bearer (`'Bearer <token>'`).
-- Reads the configured cookie from `req.headers.cookie`.
-- In token mode, prefers bearer and falls back to cookie. In cookie mode, returns the cookie and ignores bearer by default; `http.acceptBearerInCookieMode=true` enables the legacy bearer fallback.
-
-## API Reference — Origin Check
-
-### `allowedOrigin(origin: string): boolean`
-
-**Signature:**
-```typescript
-const allowedOrigin = (origin: string): boolean
-export default allowedOrigin
-```
-
-**Behavior (in execution order):**
-1. Normalizes the origin to `scheme://host[:port]`, strips default `:80` / `:443`, lowercases.
-2. Computes the same-origin bind location from `getBindAddress()` and the `SECURE` env var.
-3. When `cors.allowLocalhost` and the origin matches `/^https?:\/\/localhost(:\d+)?$/i` → returns `true`.
-4. When `cors.allowedOrigins` is a function → calls it; if it returns true (or the origin equals the bind location) → returns `true`.
-5. When `cors.allowedOrigins` is a string array → builds a normalized allowed set (bind location + configured list); returns `true` on match.
-6. Otherwise: dispatches the `corsRejected` hook (with origin + normalized origin + allowedOrigins + allowLocalhost) and returns `false`. Also logs via `getLogger().warn` when `logging.devLogs` is on.
-
-**Edge cases:**
-- An empty `origin` is treated as not-allowed.
-- The resolver-function form is sync only — async predicates are not supported because Socket.io's CORS check is sync.
-
-## API Reference — Offline Queue
-
-Per-queue items:
-```typescript
-interface QueueItem {
-  id: string;
-  key: string;
-  run: (socketInstance: Socket) => void;
-  createdAt: number;
-  dropPolicy?: 'drop-oldest' | 'drop-newest' | 'reject';
-}
-```
-
-### `isOnline(): boolean`
-Returns `true` in non-browser environments. In browsers, reads `navigator.onLine`.
-
-### `enqueueApiRequest(item): boolean` / `enqueueSyncRequest(item): boolean`
-
-**Behavior:**
-1. Evicts items older than `offlineQueue.maxAgeMs` from the relevant queue.
-2. If `queue.length < offlineQueue.maxSize`, pushes the new item and returns `true`.
-3. Otherwise applies the effective drop policy (per-item `dropPolicy` overrides the global default):
-   - `'drop-oldest'` — shift + push, returns `true` (logs debug).
-   - `'drop-newest'` — keep existing queue, returns `false` (logs debug).
-   - `'reject'` — returns `false` (logs warn).
-
-### `removeApiQueueItem(id)` / `removeSyncQueueItem(id)`
-Removes a single item by `id`. No-op if not found.
-
-### `removeApiQueueItemsByKey(key)`
-Removes every API queue item matching `item.key`. Used to coalesce duplicate requests.
-
-### `flushApiQueue(canRun, socketInstance)` / `flushSyncQueue(canRun, socketInstance)`
-
-**Behavior:**
-- Re-entrancy guard prevents nested flushes for the same queue.
-- Evicts expired items.
-- Drains FIFO while `canRun()` returns `true`, calling each item's `run(socketInstance)`.
-
-### `getApiQueueSize(): number` / `getSyncQueueSize(): number`
-
-Read-only sizes (after eviction triggers from enqueue/flush; reads alone do not evict).
-
-**Example:**
-```typescript
-import { enqueueApiRequest } from '@luckystack/core/client';
-
-enqueueApiRequest({
-  id: requestId,
-  key: `${routeName}:${userId}`,
-  createdAt: Date.now(),
-  dropPolicy: 'drop-newest',
-  run: (s) => s.emit('apiRequest', message),
-});
-```
-
-## API Reference — CSRF + httpFetch
-
-### `getCsrfToken(): Promise<string | null>`
-
-**Behavior:**
-- Returns `null` immediately in token-mode sessions (`session.basedToken === true`) — CSRF is unnecessary because cross-origin requests don't auto-attach sessionStorage.
-- Returns the cached token if previously fetched.
-- Otherwise fetches `/auth/csrf` with `credentials: 'include'`, caches and returns `body.csrfToken`.
-- Inflight de-duplication: concurrent callers share the same promise.
-
-### `clearCsrfToken(): void`
-
-Drops the cached token + any inflight fetch. Call on logout or when a 403 `auth.csrfMismatch` is observed.
-
-### `httpFetch(input, init?): Promise<Response>`
-
-Drop-in `fetch` replacement that:
-- Forces `credentials: 'include'` unless overridden.
-- Adds `Content-Type: application/json` when a string body is present and no content-type was set.
-- For state-changing methods (`POST`, `PUT`, `PATCH`, `DELETE`) in cookie mode: lazily fetches the CSRF token, attaches as `x-csrf-token`. On a 403 `auth.csrfMismatch` response, clears the cache and retries once with a refreshed token.
-
-**Example:**
-```typescript
-import { httpFetch } from '@luckystack/core/client';
-
-const res = await httpFetch('/api/system/myRoute/v1', {
-  method: 'POST',
-  body: JSON.stringify({ foo: 1 }),
-});
-```
-
-## API Reference — Wire Protocol Constants
-
-### `socketEventNames`
-
-A frozen record of event names:
-
-| Key | Value |
-|---|---|
-| `apiRequest` | `'apiRequest'` |
-| `sync` | `'sync'` |
-| `joinRoom` / `leaveRoom` / `getJoinedRooms` | (same literal) |
-| `updateLocation` / `updateSession` / `sessionReplaced` / `logout` | (same literal) |
-| `intentionalDisconnect` / `intentionalReconnect` / `userAfk` / `userBack` | (same literal) |
-| `connect` / `disconnect` / `reconnectAttempt` / `connectError` | underlying socket.io events |
-| `apiResponsePrefix` | `'apiResponse-'` |
-| `apiStreamPrefix` | `'apiStream-'` |
-| `syncResponsePrefix` | `'sync-'` |
-| `syncProgressPrefix` | `'sync-progress-'` |
-| `joinRoomResponsePrefix` / `leaveRoomResponsePrefix` / `getJoinedRoomsResponsePrefix` | (same prefix) |
-
-### Event name builders
-
-| Function | Behavior |
-|---|---|
-| `buildApiResponseEventName(idx)` | `'apiResponse-<idx>'` |
-| `buildApiStreamEventName(idx)` | `'apiStream-<idx>'` |
-| `buildSyncResponseEventName(idx)` | `'sync-<idx>'` |
-| `buildSyncProgressEventName(idx)` | `'sync-progress-<idx>'` |
-| `buildJoinRoomResponseEventName(idx)` | `'joinRoom-<idx>'` |
-| `buildLeaveRoomResponseEventName(idx)` | `'leaveRoom-<idx>'` |
-| `buildGetJoinedRoomsResponseEventName(idx)` | `'getJoinedRooms-<idx>'` |
-
-## API Reference — Service Route Parsers
-
-### `parseServiceRouteName(value: string): ServiceRouteParseResult`
-
-Validates `<service>/<routeName...>` strings.
-
-**Returns:**
-- `{ status: 'success', normalizedRouteName, service, routeName }` — when at least two non-empty segments are present.
-- `{ status: 'error', reason }` — for empty input, empty segments, or fewer than two segments.
-
-Normalization rules: trim, replace `\` with `/`, strip leading/trailing slashes.
-
-### `parseTransportRouteName({ value, prefix })`
-
-Validates a full transport route like `'api/system/foo/v1'`.
-
-**Parameters:**
-| Name | Type | Required | Description |
-|---|---|---|---|
-| `value` | `string` | yes | Raw route string. |
-| `prefix` | `'api' \| 'sync'` | yes | Determines whether the leading `'api'`/`'sync'` segment is stripped. |
-
-**Returns:**
-- `{ status: 'success', normalizedFullName, version, serviceRoute }` — when the trailing segment matches `/^v\d+$/` and the leading service/route part parses cleanly.
-- `{ status: 'error', reason }` — on length / version / segment violations.
-
-## API Reference — Cookies
-
-### `getCookieValue(cookieHeader: string | undefined, cookieName: string): string | null`
-
-Regex-escapes `cookieName`, searches for `(?:^|;\s*)<name>=<value>` in the header, URL-decodes the captured value (falls back to raw on decode failure). Returns `null` when input is missing or no match.
-
-### `hasCookie(cookieHeader, cookieName): boolean`
-
-Convenience wrapper — true when `getCookieValue` returns a non-null value.
-
-## API Reference — HTTP Method Inference
-
-### `inferHttpMethod(apiName: string): HttpMethod`
-
-Naming-convention heuristic (used as fallback when no `apiMethodMap` is registered):
-- starts with `get` / `fetch` / `list` → `GET`
-- starts with `delete` / `remove` → `DELETE`
-- starts with `update` / `edit` / `patch` → `PUT`
-- otherwise → `POST`
-
-Strips a trailing `v\d+` segment before applying the rule, so `api/examples/getUser/v1` resolves to `'GET'`.
-
-### `getEffectiveHttpMethod(apiConfig, apiName)`
-
-Prefers an explicit `apiConfig.httpMethod`; otherwise calls `inferHttpMethod(apiName)`.
-
-### `isMethodAllowed(requestMethod, allowedMethod): boolean`
-
-Returns `true` when the request method matches the allowed method or is `'OPTIONS'` (CORS preflight passthrough).
-
-## Hooks dispatched
-
-| Hook name | Payload type | When |
-|---|---|---|
-| `corsRejected` | `CorsRejectedPayload` | `allowedOrigin` is about to return `false`. |
-
-## Config keys consumed
-
-| Key | Where |
-|---|---|
-| `session.basedToken` | token extractors, `httpFetch`, `getCsrfToken` |
-| `http.sessionCookieName` | token extractors |
-| `http.cors.allowedOrigins`, `http.cors.allowLocalhost` | `allowedOrigin` |
-| `offlineQueue.maxSize`, `maxAgeMs`, `dropPolicy` | offline queue |
-| `logging.devLogs` | `allowedOrigin` warn-logs |
-
-## Related
-
-- Function INDEX: `packages/core/CLAUDE.md`
-- Architecture: `docs/ARCHITECTURE_SOCKET.md`, `docs/ARCHITECTURE_API.md`, `docs/ARCHITECTURE_SYNC.md`, `docs/ARCHITECTURE_AUTH.md`
-- README: `packages/core/README.md`
-- Source: `packages/core/src/socketTypes.ts`, `socketState.ts`, `socketEvents.ts`, `extractToken.ts`, `extractTokenFromRequest.ts`, `checkOrigin.ts`, `offlineQueue.ts`, `csrf.ts`, `cookies.ts`, `httpApiUtils.ts`, `serviceRoute.ts`
+**A room-name formatter receives `userId` as context, never as a name part.** Every framework join, leave, broadcast and presence room passes through the registered formatter, intended for a stable, user-independent transform such as per-tenant prefixing. For a broadcast the framework passes whoever performs the operation — the joiner on join, the sender on fan-out, the originator of a stream — so for a shared room the value differs per side. A formatter that folds it into a content room's physical name puts join and fan-out in different rooms, and every broadcast silently reaches nobody; the framework cannot detect this because both names are just strings. Put per-user isolation in the raw room code the consumer chooses, or in the presence family, which is per-user by design (ADR 0060). Source: `../src/roomNameFormatterRegistry.ts`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luckystack/core",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "private": false,
   "publishConfig": {
     "access": "public",
@@ -60,7 +60,7 @@
   "files": [
     "dist",
     "README.md",
-    "CLAUDE.md",
+    "AGENTS.md",
     "docs",
     "LICENSE",
     "CHANGELOG.md"