@luckystack/core 0.4.0 → 0.5.0

package/docs/csrf-config.md

@@ -1,88 +1,88 @@
-# CSRF Config
-
-> Customise the framework's CSRF cookie name, header name, token length and cookie options without forking `@luckystack/server`. Source: `packages/core/src/csrfConfig.ts`. Bijgewerkt: 2026-05-21.
-
-## Overview
-
-LuckyStack's CSRF defense is double-submit: on first session write, the login package mints a per-session token; the server reads it from the session record on every state-changing request and compares it against the value the browser sends in a request header. Consumers who need to integrate with an external framework expectation (legacy `x-xsrf-token`, a custom auth gateway that rewrites cookies, FIPS-grade token length) override the defaults via `registerCsrfConfig({ ... })`.
-
-| Setting | Default | Where it is consumed |
-|---|---|---|
-| `cookieName` | `'csrf-token'` | Reserved for future cookie-issued tokens (current double-submit uses session record). |
-| `headerName` | `'x-csrf-token'` | Server: `csrfMiddleware.ts` reads `req.headers[headerName]`. Client: `httpFetch` attaches `headerName` on state-changing requests. |
-| `tokenLength` | `32` (bytes) | Session mint in `packages/login/src/session.ts` (`randomBytes(tokenLength).toString('hex')`). |
-| `cookieOptions.sameSite` | `'lax'` | Cookie attributes if/when the framework migrates to cookie-issued tokens. |
-| `cookieOptions.secure` | `true` | Same. |
-| `cookieOptions.httpOnly` | `false` | MUST be false for CSRF cookies — clients need to read the value. |
-| `cookieOptions.path` | `'/'` | Same. |
-| `cookieOptions.maxAgeMs` | `86_400_000` (1 day) | Same. |
-
-## API Reference
-
-### `registerCsrfConfig(input: Partial<CsrfConfig>): void`
-
-**Signature:**
-```typescript
-export interface CsrfConfig {
-  cookieName: string;
-  headerName: string;
-  tokenLength: number;
-  cookieOptions: CsrfCookieOptions;
-}
-export const registerCsrfConfig = (input: Partial<CsrfConfig>): void
-```
-
-**Behavior:** Shallow-merges `input` over the current config. `cookieOptions` is deep-merged so a partial override of `sameSite` does not clobber `path` / `maxAgeMs`. Last-write-wins.
-
-**Example — rename the header for an external gateway:**
-```typescript
-import { registerCsrfConfig } from '@luckystack/core';
-
-registerCsrfConfig({
-  headerName: 'x-xsrf-token',
-});
-```
-
-**Example — FIPS-grade token length + strict same-site:**
-```typescript
-import { registerCsrfConfig } from '@luckystack/core';
-
-registerCsrfConfig({
-  tokenLength: 64,
-  cookieOptions: { sameSite: 'strict' },
-});
-```
-
-### `getCsrfConfig(): CsrfConfig`
-
-Read the active config at call time. Framework code uses this — never read at module load.
-
-### `DEFAULT_CSRF_CONFIG: CsrfConfig`
-
-Exported so consumers can spread + override structurally:
-
-```typescript
-import { DEFAULT_CSRF_CONFIG, registerCsrfConfig } from '@luckystack/core';
-
-registerCsrfConfig({
-  ...DEFAULT_CSRF_CONFIG,
-  headerName: 'x-app-csrf',
-});
-```
-
-### `resetCsrfConfigForTests(): void`
-
-Test-only helper. Restore defaults between scenarios. Not part of the runtime contract.
-
-## What this does NOT change
-
-- The double-submit comparison logic itself (`csrfSession.csrfToken === provided`).
-- Token-mode session behaviour — token-mode sessions skip CSRF entirely (cross-origin requests don't auto-attach `sessionStorage`).
-- The framework's HTTP route paths (`GET /auth/csrf` is still the issuing endpoint).
-- The `csrfMismatch` hook fan-out — payload shape and timing are unchanged.
-
-## Related
-
-- Function INDEX: `packages/core/CLAUDE.md`
-- Source: `packages/core/src/csrfConfig.ts`, `packages/core/src/csrf.ts`, `packages/server/src/httpRoutes/csrfMiddleware.ts`, `packages/login/src/session.ts`
-- Architecture: `docs/ARCHITECTURE_EXTENSION_POINTS.md`, `packages/server/docs/security-defaults.md`
+# CSRF Config
+
+> Customise the framework's CSRF cookie name, header name, token length and cookie options without forking `@luckystack/server`. Source: `packages/core/src/csrfConfig.ts`. Bijgewerkt: 2026-05-21.
+
+## Overview
+
+LuckyStack's CSRF defense is double-submit: on first session write, the login package mints a per-session token; the server reads it from the session record on every state-changing request and compares it against the value the browser sends in a request header. Consumers who need to integrate with an external framework expectation (legacy `x-xsrf-token`, a custom auth gateway that rewrites cookies, FIPS-grade token length) override the defaults via `registerCsrfConfig({ ... })`.
+
+| Setting | Default | Where it is consumed |
+|---|---|---|
+| `cookieName` | `'csrf-token'` | Reserved for future cookie-issued tokens (current double-submit uses session record). |
+| `headerName` | `'x-csrf-token'` | Server: `csrfMiddleware.ts` reads `req.headers[headerName]`. Client: `httpFetch` attaches `headerName` on state-changing requests. |
+| `tokenLength` | `32` (bytes) | Session mint in `packages/login/src/session.ts` (`randomBytes(tokenLength).toString('hex')`). |
+| `cookieOptions.sameSite` | `'lax'` | Cookie attributes if/when the framework migrates to cookie-issued tokens. |
+| `cookieOptions.secure` | `true` | Same. |
+| `cookieOptions.httpOnly` | `false` | MUST be false for CSRF cookies — clients need to read the value. |
+| `cookieOptions.path` | `'/'` | Same. |
+| `cookieOptions.maxAgeMs` | `86_400_000` (1 day) | Same. |
+
+## API Reference
+
+### `registerCsrfConfig(input: Partial<CsrfConfig>): void`
+
+**Signature:**
+```typescript
+export interface CsrfConfig {
+  cookieName: string;
+  headerName: string;
+  tokenLength: number;
+  cookieOptions: CsrfCookieOptions;
+}
+export const registerCsrfConfig = (input: Partial<CsrfConfig>): void
+```
+
+**Behavior:** Shallow-merges `input` over the current config. `cookieOptions` is deep-merged so a partial override of `sameSite` does not clobber `path` / `maxAgeMs`. Last-write-wins.
+
+**Example — rename the header for an external gateway:**
+```typescript
+import { registerCsrfConfig } from '@luckystack/core';
+
+registerCsrfConfig({
+  headerName: 'x-xsrf-token',
+});
+```
+
+**Example — FIPS-grade token length + strict same-site:**
+```typescript
+import { registerCsrfConfig } from '@luckystack/core';
+
+registerCsrfConfig({
+  tokenLength: 64,
+  cookieOptions: { sameSite: 'strict' },
+});
+```
+
+### `getCsrfConfig(): CsrfConfig`
+
+Read the active config at call time. Framework code uses this — never read at module load.
+
+### `DEFAULT_CSRF_CONFIG: CsrfConfig`
+
+Exported so consumers can spread + override structurally:
+
+```typescript
+import { DEFAULT_CSRF_CONFIG, registerCsrfConfig } from '@luckystack/core';
+
+registerCsrfConfig({
+  ...DEFAULT_CSRF_CONFIG,
+  headerName: 'x-app-csrf',
+});
+```
+
+### `resetCsrfConfigForTests(): void`
+
+Test-only helper. Restore defaults between scenarios. Not part of the runtime contract.
+
+## What this does NOT change
+
+- The double-submit comparison logic itself (`csrfSession.csrfToken === provided`).
+- Token-mode session behaviour — token-mode sessions skip CSRF entirely (cross-origin requests don't auto-attach `sessionStorage`).
+- The framework's HTTP route paths (`GET /auth/csrf` is still the issuing endpoint).
+- The `csrfMismatch` hook fan-out — payload shape and timing are unchanged.
+
+## Related
+
+- Function INDEX: `packages/core/CLAUDE.md`
+- Source: `packages/core/src/csrfConfig.ts`, `packages/core/src/csrf.ts`, `packages/server/src/httpRoutes/csrfMiddleware.ts`, `packages/login/src/session.ts`
+- Architecture: `docs/ARCHITECTURE_EXTENSION_POINTS.md`, `packages/server/docs/security-defaults.md`

package/docs/error-tracker-registry.md

@@ -1,174 +1,174 @@
-# Error Tracker Registry
-
-> Deep specs for the backend-agnostic error tracker registry + legacy Sentry slot. Source: `packages/core/src/errorTrackerRegistry.ts`, `sentrySetup.ts`. Bijgewerkt: 2026-05-20.
-
-## Overview
-
-The error tracker registry is the seam between framework code (which never imports a specific observability backend) and adapters for Sentry / Datadog / PostHog / etc. The slot lives in `@luckystack/core`; adapter implementations ship in `@luckystack/error-tracking`. Multiple adapters can be active at once via `registerErrorTrackers([...])` — every event fans out to all of them, and per-adapter errors are swallowed so one buggy tracker can't break the chain.
-
-The legacy `initSharedSentry(instance)` + `captureException` / `captureMessage` / `setSentryUser` / `startSpan` API predates the multi-adapter registry. It is kept for backwards compatibility and dual-fans events through both the legacy slot AND any adapters registered with the new API, so a project can migrate incrementally.
-
-`startSpanAcrossTrackers` deliberately invokes only the first adapter that supports `startSpan` — spans don't fan out cleanly because they're nested execution scopes.
-
-## Types
-
-```typescript
-export interface ErrorTrackerContext {
-  [key: string]: unknown;
-}
-
-export interface ErrorTrackerUser {
-  id?: string;
-  email?: string;
-  username?: string;
-  [key: string]: unknown;
-}
-
-export interface ErrorTrackerEvent {
-  forwarded: boolean;
-  kind: 'exception' | 'message';
-  payload: Record<string, unknown>;
-}
-
-export type SpanResult<T> = T;
-
-export interface ErrorTracker {
-  name: string;
-  captureException: (error: unknown, context?: ErrorTrackerContext) => void;
-  captureMessage: (
-    message: string,
-    level: 'info' | 'warning' | 'error' | 'fatal',
-    context?: ErrorTrackerContext,
-  ) => void;
-  setUser: (user: ErrorTrackerUser | null) => void;
-  setContext?: (key: string, context: ErrorTrackerContext | null) => void;
-  startSpan?: <T>(name: string, op: string, fn: () => T) => T;
-  recordMetric?: (name: string, value: number, tags?: Record<string, string>) => void;
-  beforeSend?: (event: ErrorTrackerEvent) => ErrorTrackerEvent | null;
-}
-```
-
-`SpanResult<T>` is an alias for `T` — the conditional unwrap collapsed in both branches and `tsup`'s dts emit choked on the widening. Kept as an exported alias so adapter authors can still annotate intent.
-
-## API Reference — Multi-Adapter Registry
-
-### `registerErrorTracker(tracker: ErrorTracker): void`
-
-**Behavior:** Replaces the active list with `[tracker]`. Use this for single-tracker setups.
-
-### `registerErrorTrackers(trackers: ErrorTracker[]): void`
-
-**Behavior:** Replaces the active list with a copy of the input array (`[...trackers]`). Use for multi-backend setups (Sentry + Datadog, etc.).
-
-### `getActiveErrorTrackers(): ErrorTracker[]`
-
-Returns the current array (the internal reference — treat as read-only).
-
-### `captureExceptionAcrossTrackers(error, context?): void`
-
-**Behavior:** For each active tracker, calls `tracker.captureException(error, context)` inside a per-tracker `try / catch` that silently swallows failures.
-
-### `captureMessageAcrossTrackers(message, level, context?): void`
-
-Same fan-out shape as `captureExceptionAcrossTrackers` for messages.
-
-### `setErrorTrackerUser(user: ErrorTrackerUser | null): void`
-
-Calls `tracker.setUser(user)` on every active tracker (errors swallowed).
-
-### `recordMetricAcrossTrackers(name, value, tags?): void`
-
-**Behavior:** Skips trackers that don't define `recordMetric`. Errors are swallowed.
-
-### `startSpanAcrossTrackers<T>(name, op, fn): T`
-
-**Behavior:**
-- Finds the first tracker with a `startSpan` method.
-- If found, returns `tracker.startSpan(name, op, fn)` cast to `T`.
-- If none exist, returns `fn()` directly (no instrumentation).
-
-**Why not fan-out:** Spans are nested execution scopes — invoking multiple `startSpan` implementations would nest each other and produce confusing traces.
-
-### Example — register multiple adapters
-
-```typescript
-import { registerErrorTrackers, type ErrorTracker } from '@luckystack/core';
-
-const sentryAdapter: ErrorTracker = { /* ... */ };
-const datadogAdapter: ErrorTracker = { /* ... */ };
-
-registerErrorTrackers([sentryAdapter, datadogAdapter]);
-```
-
-## API Reference — Legacy Sentry Slot
-
-### `initSharedSentry(instance: SentryInstance): void`
-
-**Signature:**
-```typescript
-interface SentryInstance {
-  captureException: (exception: unknown, ...args: unknown[]) => string;
-  captureMessage: (message: string, ...args: unknown[]) => string;
-  setUser: (user: unknown) => void;
-  setContext: (key: string, context: unknown) => void;
-  startInactiveSpan?: (context: unknown) => unknown;
-}
-
-export const initSharedSentry = (instance: SentryInstance): void
-```
-
-**Behavior:** Stores the Sentry SDK instance in a module-level slot. New code should `registerErrorTracker(...)` from `@luckystack/error-tracking` instead.
-
-### `captureException(error, context?): void`
-
-**Behavior:**
-- When the legacy Sentry slot is populated, calls `sentry.captureException(error, { extra: context })` (or no second arg when no context).
-- ALSO calls `captureExceptionAcrossTrackers(error, context)` so any modern adapters receive the same event.
-
-**Concurrency note:** Context is passed inline via the hint-shaped second argument so contexts don't leak across concurrent captures. The previous implementation used `sentry.setContext('additional', context)` which was process-global and leaked under concurrent captures.
-
-### `captureMessage(message, level?, context?): void`
-
-**Behavior:** Mirror of `captureException` for messages. Level defaults to `'info'`.
-
-### `setSentryUser(user): void`
-
-Calls `sentry?.setUser(user)` and fans out via `setErrorTrackerUser(user)`.
-
-### `startSpan(name, op): unknown`
-
-**Behavior:**
-- If `sentry?.startInactiveSpan` exists, returns `sentry.startInactiveSpan({ name, op })`.
-- Otherwise falls back to `startSpanAcrossTrackers(name, op, () => undefined)` — useful when the project uses an adapter-only setup that supports spans.
-
-## Edge cases
-
-- All multi-adapter fan-out paths swallow per-tracker errors. There is no way to surface them — by design, since framework hot paths (`tryCatch`, hook dispatch) must never crash because of a misbehaving tracker.
-- `registerErrorTracker` and `registerErrorTrackers` replace the active list — call once at boot. There is no `unregister` API.
-- `beforeSend` and `forwarded` on `ErrorTrackerEvent` are advisory for adapter authors. Core does not call `beforeSend` itself; the adapter implementation is expected to honor it.
-
-## Example — minimal custom adapter
-
-```typescript
-import { registerErrorTracker, type ErrorTracker } from '@luckystack/core';
-
-const stdoutAdapter: ErrorTracker = {
-  name: 'stdout',
-  captureException: (error, context) => {
-    console.error('exception:', error, context);
-  },
-  captureMessage: (message, level, context) => {
-    console.log(`[${level}] ${message}`, context);
-  },
-  setUser: () => { /* no-op */ },
-};
-
-registerErrorTracker(stdoutAdapter);
-```
-
-## Related
-
-- Function INDEX: `packages/core/CLAUDE.md`
-- Architecture: `docs/ARCHITECTURE_EXTENSION_POINTS.md`
-- README: `packages/core/README.md`, `packages/error-tracking/README.md`
-- Source: `packages/core/src/errorTrackerRegistry.ts`, `sentrySetup.ts`
+# Error Tracker Registry
+
+> Deep specs for the backend-agnostic error tracker registry + legacy Sentry slot. Source: `packages/core/src/errorTrackerRegistry.ts`, `sentrySetup.ts`. Bijgewerkt: 2026-05-20.
+
+## Overview
+
+The error tracker registry is the seam between framework code (which never imports a specific observability backend) and adapters for Sentry / Datadog / PostHog / etc. The slot lives in `@luckystack/core`; adapter implementations ship in `@luckystack/error-tracking`. Multiple adapters can be active at once via `registerErrorTrackers([...])` — every event fans out to all of them, and per-adapter errors are swallowed so one buggy tracker can't break the chain.
+
+The legacy `initSharedSentry(instance)` + `captureException` / `captureMessage` / `setSentryUser` / `startSpan` API predates the multi-adapter registry. It is kept for backwards compatibility and dual-fans events through both the legacy slot AND any adapters registered with the new API, so a project can migrate incrementally.
+
+`startSpanAcrossTrackers` deliberately invokes only the first adapter that supports `startSpan` — spans don't fan out cleanly because they're nested execution scopes.
+
+## Types
+
+```typescript
+export interface ErrorTrackerContext {
+  [key: string]: unknown;
+}
+
+export interface ErrorTrackerUser {
+  id?: string;
+  email?: string;
+  username?: string;
+  [key: string]: unknown;
+}
+
+export interface ErrorTrackerEvent {
+  forwarded: boolean;
+  kind: 'exception' | 'message';
+  payload: Record<string, unknown>;
+}
+
+export type SpanResult<T> = T;
+
+export interface ErrorTracker {
+  name: string;
+  captureException: (error: unknown, context?: ErrorTrackerContext) => void;
+  captureMessage: (
+    message: string,
+    level: 'info' | 'warning' | 'error' | 'fatal',
+    context?: ErrorTrackerContext,
+  ) => void;
+  setUser: (user: ErrorTrackerUser | null) => void;
+  setContext?: (key: string, context: ErrorTrackerContext | null) => void;
+  startSpan?: <T>(name: string, op: string, fn: () => T) => T;
+  recordMetric?: (name: string, value: number, tags?: Record<string, string>) => void;
+  beforeSend?: (event: ErrorTrackerEvent) => ErrorTrackerEvent | null;
+}
+```
+
+`SpanResult<T>` is an alias for `T` — the conditional unwrap collapsed in both branches and `tsup`'s dts emit choked on the widening. Kept as an exported alias so adapter authors can still annotate intent.
+
+## API Reference — Multi-Adapter Registry
+
+### `registerErrorTracker(tracker: ErrorTracker): void`
+
+**Behavior:** Replaces the active list with `[tracker]`. Use this for single-tracker setups.
+
+### `registerErrorTrackers(trackers: ErrorTracker[]): void`
+
+**Behavior:** Replaces the active list with a copy of the input array (`[...trackers]`). Use for multi-backend setups (Sentry + Datadog, etc.).
+
+### `getActiveErrorTrackers(): ErrorTracker[]`
+
+Returns the current array (the internal reference — treat as read-only).
+
+### `captureExceptionAcrossTrackers(error, context?): void`
+
+**Behavior:** For each active tracker, calls `tracker.captureException(error, context)` inside a per-tracker `try / catch` that silently swallows failures.
+
+### `captureMessageAcrossTrackers(message, level, context?): void`
+
+Same fan-out shape as `captureExceptionAcrossTrackers` for messages.
+
+### `setErrorTrackerUser(user: ErrorTrackerUser | null): void`
+
+Calls `tracker.setUser(user)` on every active tracker (errors swallowed).
+
+### `recordMetricAcrossTrackers(name, value, tags?): void`
+
+**Behavior:** Skips trackers that don't define `recordMetric`. Errors are swallowed.
+
+### `startSpanAcrossTrackers<T>(name, op, fn): T`
+
+**Behavior:**
+- Finds the first tracker with a `startSpan` method.
+- If found, returns `tracker.startSpan(name, op, fn)` cast to `T`.
+- If none exist, returns `fn()` directly (no instrumentation).
+
+**Why not fan-out:** Spans are nested execution scopes — invoking multiple `startSpan` implementations would nest each other and produce confusing traces.
+
+### Example — register multiple adapters
+
+```typescript
+import { registerErrorTrackers, type ErrorTracker } from '@luckystack/core';
+
+const sentryAdapter: ErrorTracker = { /* ... */ };
+const datadogAdapter: ErrorTracker = { /* ... */ };
+
+registerErrorTrackers([sentryAdapter, datadogAdapter]);
+```
+
+## API Reference — Legacy Sentry Slot
+
+### `initSharedSentry(instance: SentryInstance): void`
+
+**Signature:**
+```typescript
+interface SentryInstance {
+  captureException: (exception: unknown, ...args: unknown[]) => string;
+  captureMessage: (message: string, ...args: unknown[]) => string;
+  setUser: (user: unknown) => void;
+  setContext: (key: string, context: unknown) => void;
+  startInactiveSpan?: (context: unknown) => unknown;
+}
+
+export const initSharedSentry = (instance: SentryInstance): void
+```
+
+**Behavior:** Stores the Sentry SDK instance in a module-level slot. New code should `registerErrorTracker(...)` from `@luckystack/error-tracking` instead.
+
+### `captureException(error, context?): void`
+
+**Behavior:**
+- When the legacy Sentry slot is populated, calls `sentry.captureException(error, { extra: context })` (or no second arg when no context).
+- ALSO calls `captureExceptionAcrossTrackers(error, context)` so any modern adapters receive the same event.
+
+**Concurrency note:** Context is passed inline via the hint-shaped second argument so contexts don't leak across concurrent captures. The previous implementation used `sentry.setContext('additional', context)` which was process-global and leaked under concurrent captures.
+
+### `captureMessage(message, level?, context?): void`
+
+**Behavior:** Mirror of `captureException` for messages. Level defaults to `'info'`.
+
+### `setSentryUser(user): void`
+
+Calls `sentry?.setUser(user)` and fans out via `setErrorTrackerUser(user)`.
+
+### `startSpan(name, op): unknown`
+
+**Behavior:**
+- If `sentry?.startInactiveSpan` exists, returns `sentry.startInactiveSpan({ name, op })`.
+- Otherwise falls back to `startSpanAcrossTrackers(name, op, () => undefined)` — useful when the project uses an adapter-only setup that supports spans.
+
+## Edge cases
+
+- All multi-adapter fan-out paths swallow per-tracker errors. There is no way to surface them — by design, since framework hot paths (`tryCatch`, hook dispatch) must never crash because of a misbehaving tracker.
+- `registerErrorTracker` and `registerErrorTrackers` replace the active list — call once at boot. There is no `unregister` API.
+- `beforeSend` and `forwarded` on `ErrorTrackerEvent` are advisory for adapter authors. Core does not call `beforeSend` itself; the adapter implementation is expected to honor it.
+
+## Example — minimal custom adapter
+
+```typescript
+import { registerErrorTracker, type ErrorTracker } from '@luckystack/core';
+
+const stdoutAdapter: ErrorTracker = {
+  name: 'stdout',
+  captureException: (error, context) => {
+    console.error('exception:', error, context);
+  },
+  captureMessage: (message, level, context) => {
+    console.log(`[${level}] ${message}`, context);
+  },
+  setUser: () => { /* no-op */ },
+};
+
+registerErrorTracker(stdoutAdapter);
+```
+
+## Related
+
+- Function INDEX: `packages/core/CLAUDE.md`
+- Architecture: `docs/ARCHITECTURE_EXTENSION_POINTS.md`
+- README: `packages/core/README.md`, `packages/error-tracking/README.md`
+- Source: `packages/core/src/errorTrackerRegistry.ts`, `sentrySetup.ts`