tempest-express-sdk 0.10.0 → 0.20.0

package/dist/index.d.cts

@@ -1,13 +1,15 @@
 import { z } from 'zod';
 export { z } from 'zod';
 import * as tempest_db_js from 'tempest-db-js';
-import { Model, ModelClass, BaseRepository, InferModel, WhereInput, InferInsert, PaginationFilter as PaginationFilter$1, PaginationResult } from 'tempest-db-js';
+import { Model, ModelClass, BaseRepository, WhereInput, InferModel, InferInsert, PaginationFilter as PaginationFilter$1, PaginationResult, AsyncDriver, AsyncEngine, AsyncSession } from 'tempest-db-js';
 export { AsyncDriver, AsyncEngine, AsyncResult, AsyncSession, BaseRepository, BelongsTo, ColType, Column, ColumnFlags, CompiledQuery, CondNode, Condition, DeleteBuilder, DeleteNode, Dialect, EngineOptions, Executable, HasMany, InferInsert, InferModel, InsertBuilder, InsertNode, Model, ModelClass, NoResultError, NodeSqliteDriver, Operator, OrderTerm, PaginationResult, ParsedDatabaseUrl, PostgresDialect, QueryNode, RecordNotFound, Relation, RelationValue, PaginationFilter as RepositoryPaginationFilter, Returning, RowOf, SelectBuilder, SelectNode, SortDirection, SqliteDialect, SyncEngine, SyncSession, UpdateBuilder, UpdateNode, WhereArg, WhereInput, WithRelations, and, belongsTo, column, columnsOf, createEngine, createSyncEngine, del, detectDialect, getDialect, hasMany, insert, join, loadRelations, not, or, parseDatabaseUrl, select, sql, update } from 'tempest-db-js';
-import { Request, RequestHandler, Response as Response$1, Router, ErrorRequestHandler, Express } from 'express';
+import { Request, Response as Response$1, RequestHandler, Router, ErrorRequestHandler, Express } from 'express';
 import * as ws from 'ws';
 import { Server } from 'node:http';
+import { Readable } from 'node:stream';
 import { OpenAPIRegistry } from '@asteasolutions/zod-to-openapi';
 export { OpenAPIRegistry } from '@asteasolutions/zod-to-openapi';
+import { BinaryLike } from 'node:crypto';
 
 /**
  * Request-scoped context propagation via `AsyncLocalStorage`.
@@ -57,6 +59,17 @@ declare const HTTP_500_MARKER = "http_500";
 type LogLevel = "debug" | "info" | "warning" | "error";
 /** Free-form structured context merged into the emitted record. */
 type LogExtra = Record<string, unknown>;
+/** A sink receiving every emitted record (for file routing, shipping, …). */
+type LogSink = (level: LogLevel, record: Record<string, unknown>) => void;
+/**
+ * Register a sink invoked for every record every {@link JSONLogger} emits (in
+ * addition to the stdout/stderr line). Used by `configureFileLogging` to route
+ * records into per-level + `500.log` files.
+ *
+ * @param sink - The sink callback. Errors thrown by it are swallowed.
+ * @returns A function that removes the sink.
+ */
+declare function addLogSink(sink: LogSink): () => void;
 /** A minimal structured logger writing one JSON line per record. */
 declare class JSONLogger {
     private readonly name;
@@ -487,6 +500,173 @@ declare function encodeCursor(payload: Record<string, unknown>): string;
  */
 declare function decodeCursor(cursor: string): Record<string, unknown>;
 
+/**
+ * Ready-made, validated Zod field types, mirroring `utils.fields`.
+ *
+ * Reusable building blocks for DTOs so you don't re-derive the same constraint
+ * everywhere: money in cents, a price string, a percentage, a latitude, a slug,
+ * a hex color. Compose them into schemas with `z.object({ price: priceField })`.
+ */
+
+/** A strictly positive integer (`> 0`). */
+declare const positiveIntField: z.ZodNumber;
+/** A non-negative integer (`>= 0`). */
+declare const nonNegativeIntField: z.ZodNumber;
+/** A monetary amount in the smallest unit (cents), `>= 0`. Avoids float drift. */
+declare const centsField: z.ZodNumber;
+/** A TCP port (`1..65535`). */
+declare const portField: z.ZodNumber;
+/** A 0–5 star rating. */
+declare const ratingField: z.ZodNumber;
+/** A strictly positive float (`> 0`). */
+declare const positiveFloatField: z.ZodNumber;
+/** A non-negative float (`>= 0`). */
+declare const nonNegativeFloatField: z.ZodNumber;
+/** A percentage (`0..100`). */
+declare const percentField: z.ZodNumber;
+/** A ratio (`0..1`). */
+declare const ratioField: z.ZodNumber;
+/** A WGS-84 latitude (`-90..90`). */
+declare const latitudeField: z.ZodNumber;
+/** A WGS-84 longitude (`-180..180`). */
+declare const longitudeField: z.ZodNumber;
+/** A non-empty string; whitespace is trimmed before the length check. */
+declare const nonEmptyStrField: z.ZodPipeline<z.ZodEffects<z.ZodString, string, string>, z.ZodString>;
+/** A URL slug: lowercase alphanumerics separated by single hyphens. */
+declare const slugField: z.ZodString;
+/** A hex color: `#rgb` or `#rrggbb`. */
+declare const hexColorField: z.ZodString;
+/**
+ * A money amount as an exact decimal **string** with up to two decimal places
+ * (e.g. `"19.90"`). Mirrors `PriceField` — `tempest-db-js` `numeric` columns map
+ * to strings, so money stays exact instead of drifting through a float.
+ */
+declare const priceField: z.ZodString;
+
+/**
+ * Delta-sync pagination schemas, mirroring `schemas.pagination` (Sync* half).
+ *
+ * For offline-first clients that pull "everything changed since my last sync".
+ * The client sends the `serverTime` from the previous page back as `since`;
+ * using the **server** clock as the watermark avoids clock-skew gaps.
+ */
+
+/**
+ * Filter schema for a delta-sync pull. Extend with `.extend` to add domain
+ * filters; the sync keys stay reserved.
+ */
+declare const syncFilterSchema: z.ZodObject<{
+    since: z.ZodOptional<z.ZodDate>;
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    includeDeleted: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    includeDeleted: boolean;
+    cursor?: string | undefined;
+    since?: Date | undefined;
+}, {
+    cursor?: string | undefined;
+    limit?: number | undefined;
+    since?: Date | undefined;
+    includeDeleted?: boolean | undefined;
+}>;
+/** The parsed shape of {@link syncFilterSchema}. */
+type SyncFilter = z.infer<typeof syncFilterSchema>;
+/**
+ * Build the delta-sync response envelope for a given item schema. Persist
+ * `serverTime` on the client and send it back as the next `since`.
+ *
+ * @param item - The zod schema for a single item.
+ * @returns A zod object `{ items, nextCursor, hasMore, limit, serverTime }`.
+ */
+declare function syncPaginationSchema<T extends z.ZodTypeAny>(item: T): z.ZodObject<{
+    items: z.ZodArray<T, "many">;
+    nextCursor: z.ZodNullable<z.ZodString>;
+    hasMore: z.ZodBoolean;
+    limit: z.ZodNumber;
+    serverTime: z.ZodDate;
+}, "strip", z.ZodTypeAny, {
+    items: T["_output"][];
+    limit: number;
+    nextCursor: string | null;
+    hasMore: boolean;
+    serverTime: Date;
+}, {
+    items: T["_input"][];
+    limit: number;
+    nextCursor: string | null;
+    hasMore: boolean;
+    serverTime: Date;
+}>;
+
+/**
+ * RFC-5988 pagination `Link` header builder, mirroring `schemas.link_headers`.
+ *
+ * Emits the `first` / `prev` / `next` / `last` rels GitHub-style clients expect.
+ * `prev`/`next` are omitted at the ends. Assign the result to
+ * `res.setHeader("Link", value)`.
+ */
+/** Options for {@link buildPaginationLinkHeader}. */
+interface PaginationLinkOptions {
+    /** Absolute or relative collection URL; existing query params are preserved. */
+    baseUrl: string;
+    /** Current page (1-based). */
+    page: number;
+    /** Page size. */
+    pageSize: number;
+    /** Total number of pages. */
+    pages: number;
+    /** Extra query params to preserve on every link (filters, sort). */
+    extraParams?: Record<string, string>;
+    /** Query param name for the page index. Default `"page"`. */
+    pageParam?: string;
+    /** Query param name for the page size. Default `"pageSize"`. */
+    sizeParam?: string;
+}
+/**
+ * Build a `Link` header value for an offset-paginated collection.
+ *
+ * @param options - Base URL, current page, page size, total pages and param names.
+ * @returns The `Link` header value, or `""` when there's nothing to link (single page).
+ */
+declare function buildPaginationLinkHeader(options: PaginationLinkOptions): string;
+
+/**
+ * `logEntrySchema` — the shape of one structured log record, mirroring
+ * `schemas.logs.LogEntrySchema`.
+ *
+ * Matches the JSON `JSONLogger` emits. It is intentionally open (`.passthrough()`)
+ * so arbitrary `extra` keys (`path`, `requestId`, `http_500`, …) survive instead
+ * of being dropped — useful when a logs endpoint parses and returns records.
+ */
+
+/** One structured log record; extra keys pass through unchanged. */
+declare const logEntrySchema: z.ZodObject<{
+    timestamp: z.ZodString;
+    level: z.ZodString;
+    logger: z.ZodString;
+    message: z.ZodString;
+    requestId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    stack: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    timestamp: z.ZodString;
+    level: z.ZodString;
+    logger: z.ZodString;
+    message: z.ZodString;
+    requestId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    stack: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    timestamp: z.ZodString;
+    level: z.ZodString;
+    logger: z.ZodString;
+    message: z.ZodString;
+    requestId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    stack: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.ZodTypeAny, "passthrough">>;
+/** The parsed shape of {@link logEntrySchema} (plus any extra keys). */
+type LogEntry = z.infer<typeof logEntrySchema>;
+
 /**
  * Environment-driven settings, mirroring `settings.base.BaseAppSettings`.
  *
@@ -559,6 +739,155 @@ type BaseAppSettings = z.infer<typeof baseAppSettingsSchema>;
  */
 declare function loadSettings<S extends z.ZodTypeAny>(schema: S, env?: NodeJS.ProcessEnv): Readonly<z.infer<S>>;
 
+/**
+ * Composable settings fragments covering common service dependencies,
+ * mirroring `settings.mixins`.
+ *
+ * Each fragment is a plain object of zod fields keyed by the **environment
+ * variable name** (matched case-sensitively, no prefix), with the same defaults
+ * as the FastAPI SDK. Compose the ones a service needs onto
+ * {@link baseAppSettingsShape} and parse with {@link loadSettings}:
+ *
+ * ```ts
+ * import { baseAppSettingsShape, jwtSettingsShape, loadSettings, z } from "tempest-express-sdk";
+ *
+ * const settings = loadSettings(
+ *   z.object({ ...baseAppSettingsShape, ...jwtSettingsShape }),
+ * );
+ * settings.JWT_SECRET; // typed
+ * ```
+ *
+ * Nothing here reads `process.env` on its own — `loadSettings` does, so the
+ * fragments stay pure and testable.
+ */
+
+/**
+ * Parse an environment string into a boolean. Unlike `z.coerce.boolean()`
+ * (which treats every non-empty string — including `"false"` — as `true`), this
+ * reads the usual truthy tokens and treats everything else as `false`.
+ *
+ * @param defaultValue - The value when the variable is absent.
+ * @returns A zod schema coercing `"true"`/`"1"`/`"yes"`/`"on"` to `true`.
+ */
+declare function envBoolean(defaultValue: boolean): z.ZodEffects<z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodString]>>, boolean, string | boolean | undefined>;
+/**
+ * Parse a comma-separated environment string into a trimmed, non-empty list.
+ *
+ * @param defaultValue - The default CSV string when the variable is absent.
+ * @returns A zod schema producing `string[]`.
+ */
+declare function envList(defaultValue?: string): z.ZodEffects<z.ZodDefault<z.ZodString>, string[], string | undefined>;
+/** Structured logging configuration. */
+declare const logSettingsShape: {
+    readonly LOG_LEVEL: z.ZodDefault<z.ZodEnum<["DEBUG", "INFO", "WARNING", "ERROR"]>>;
+    readonly LOG_JSON: z.ZodEffects<z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodString]>>, boolean, string | boolean | undefined>;
+    readonly LOG_DIR: z.ZodDefault<z.ZodString>;
+};
+/** Redis connection settings (cache / sessions / SSE broker). */
+declare const redisSettingsShape: {
+    readonly REDIS_URL: z.ZodDefault<z.ZodString>;
+};
+/** RabbitMQ connection settings (queue broker). */
+declare const rabbitmqSettingsShape: {
+    readonly RABBITMQ_URL: z.ZodDefault<z.ZodString>;
+    readonly RABBITMQ_PREFETCH_COUNT: z.ZodDefault<z.ZodNumber>;
+};
+/** JWT signing/verification settings. */
+declare const jwtSettingsShape: {
+    readonly JWT_SECRET: z.ZodDefault<z.ZodString>;
+    readonly JWT_ALGORITHM: z.ZodDefault<z.ZodString>;
+    readonly JWT_ACCESS_TTL_SECONDS: z.ZodDefault<z.ZodNumber>;
+    readonly JWT_REFRESH_TTL_SECONDS: z.ZodDefault<z.ZodNumber>;
+    readonly JWT_ISSUER: z.ZodOptional<z.ZodString>;
+};
+/** Opaque shared-secret token settings (`X-Token` guards). */
+declare const tokenSettingsShape: {
+    readonly TOKEN_SECRET: z.ZodDefault<z.ZodString>;
+};
+/** SMTP email transport settings. */
+declare const emailSettingsShape: {
+    readonly SMTP_HOST: z.ZodDefault<z.ZodString>;
+    readonly SMTP_PORT: z.ZodDefault<z.ZodNumber>;
+    readonly SMTP_USERNAME: z.ZodOptional<z.ZodString>;
+    readonly SMTP_PASSWORD: z.ZodOptional<z.ZodString>;
+    readonly SMTP_FROM_ADDR: z.ZodDefault<z.ZodString>;
+    readonly SMTP_USE_TLS: z.ZodEffects<z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodString]>>, boolean, string | boolean | undefined>;
+    readonly SMTP_USE_SSL: z.ZodEffects<z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodString]>>, boolean, string | boolean | undefined>;
+    readonly SMTP_TIMEOUT_SECONDS: z.ZodDefault<z.ZodNumber>;
+};
+/** Local upload storage settings. */
+declare const uploadSettingsShape: {
+    readonly UPLOAD_DIR: z.ZodDefault<z.ZodString>;
+    readonly UPLOAD_MAX_SIZE_BYTES: z.ZodDefault<z.ZodNumber>;
+    readonly UPLOAD_ALLOWED_EXTENSIONS: z.ZodEffects<z.ZodDefault<z.ZodString>, string[], string | undefined>;
+    readonly UPLOAD_ALLOWED_MIMETYPES: z.ZodEffects<z.ZodDefault<z.ZodString>, string[], string | undefined>;
+};
+/** MinIO / S3 object-storage settings. */
+declare const minioSettingsShape: {
+    readonly MINIO_ENDPOINT: z.ZodDefault<z.ZodString>;
+    readonly MINIO_ACCESS_KEY: z.ZodDefault<z.ZodString>;
+    readonly MINIO_SECRET_KEY: z.ZodDefault<z.ZodString>;
+    readonly MINIO_SECURE: z.ZodEffects<z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodString]>>, boolean, string | boolean | undefined>;
+    readonly MINIO_REGION: z.ZodDefault<z.ZodString>;
+    readonly MINIO_DEFAULT_BUCKET: z.ZodDefault<z.ZodString>;
+    readonly MINIO_PUBLIC_ENDPOINT: z.ZodOptional<z.ZodString>;
+    readonly MINIO_PUBLIC_SECURE: z.ZodEffects<z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodString]>>, boolean | undefined, string | boolean | undefined>;
+};
+/** Web Push (VAPID) settings. */
+declare const webPushSettingsShape: {
+    readonly VAPID_PUBLIC_KEY: z.ZodDefault<z.ZodString>;
+    readonly VAPID_PRIVATE_KEY: z.ZodDefault<z.ZodString>;
+    readonly VAPID_SUBJECT: z.ZodDefault<z.ZodString>;
+    readonly WEBPUSH_DEFAULT_TTL_SECONDS: z.ZodDefault<z.ZodNumber>;
+};
+/** Server-side session settings (cookie + TTL). */
+declare const sessionSettingsShape: {
+    readonly SESSION_TTL_SECONDS: z.ZodDefault<z.ZodNumber>;
+    readonly SESSION_SLIDING: z.ZodEffects<z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodString]>>, boolean, string | boolean | undefined>;
+    readonly SESSION_COOKIE_NAME: z.ZodDefault<z.ZodString>;
+    readonly SESSION_COOKIE_DOMAIN: z.ZodOptional<z.ZodString>;
+    readonly SESSION_COOKIE_PATH: z.ZodDefault<z.ZodString>;
+    readonly SESSION_COOKIE_SECURE: z.ZodEffects<z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodString]>>, boolean, string | boolean | undefined>;
+    readonly SESSION_COOKIE_HTTPONLY: z.ZodEffects<z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodString]>>, boolean, string | boolean | undefined>;
+    readonly SESSION_COOKIE_SAMESITE: z.ZodDefault<z.ZodEnum<["lax", "strict", "none"]>>;
+    readonly SESSION_ROTATE_ON_LOGIN: z.ZodEffects<z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodString]>>, boolean, string | boolean | undefined>;
+};
+/** WebSocket hub tuning. */
+declare const webSocketSettingsShape: {
+    readonly WS_HEARTBEAT_SECONDS: z.ZodDefault<z.ZodNumber>;
+    readonly WS_HEARTBEAT_TIMEOUT_SECONDS: z.ZodDefault<z.ZodNumber>;
+    readonly WS_MAX_CONNECTIONS_PER_USER: z.ZodDefault<z.ZodNumber>;
+    readonly WS_MAX_MESSAGE_BYTES: z.ZodDefault<z.ZodNumber>;
+};
+/**
+ * Authentication flow settings (signup/activation/reset/MFA + token delivery).
+ * The FastAPI SDK's HTML-template fields (SSR activation/reset pages) are
+ * omitted — this SDK ships the JSON auth API and defers rendering to a
+ * decoupled frontend.
+ */
+declare const authSettingsShape: {
+    readonly AUTH_AUTO_ACTIVATE: z.ZodEffects<z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodString]>>, boolean, string | boolean | undefined>;
+    readonly AUTH_RETURN_TOKEN_IN_RESPONSE: z.ZodEffects<z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodString]>>, boolean, string | boolean | undefined>;
+    readonly AUTH_ACTIVATION_TTL_SECONDS: z.ZodDefault<z.ZodNumber>;
+    readonly AUTH_PASSWORD_RESET_TTL_SECONDS: z.ZodDefault<z.ZodNumber>;
+    readonly AUTH_ACTIVATION_URL_TEMPLATE: z.ZodDefault<z.ZodString>;
+    readonly AUTH_PASSWORD_RESET_URL_TEMPLATE: z.ZodDefault<z.ZodString>;
+    readonly AUTH_PASSWORD_MIN_LENGTH: z.ZodDefault<z.ZodNumber>;
+    readonly AUTH_PASSWORD_REQUIRE_COMPLEXITY: z.ZodEffects<z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodString]>>, boolean, string | boolean | undefined>;
+    readonly AUTH_DEFAULT_LOCALE: z.ZodDefault<z.ZodString>;
+    readonly AUTH_MFA_ENABLED: z.ZodEffects<z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodString]>>, boolean, string | boolean | undefined>;
+    readonly AUTH_MFA_ISSUER: z.ZodDefault<z.ZodString>;
+    readonly AUTH_MFA_RECOVERY_CODES_COUNT: z.ZodDefault<z.ZodNumber>;
+    readonly AUTH_MFA_TOKEN_TTL_SECONDS: z.ZodDefault<z.ZodNumber>;
+    readonly AUTH_MFA_VERIFY_WINDOW: z.ZodDefault<z.ZodNumber>;
+    readonly AUTH_TOKEN_DELIVERY: z.ZodDefault<z.ZodEnum<["bearer", "cookie", "both"]>>;
+    readonly AUTH_COOKIE_SECURE: z.ZodEffects<z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodString]>>, boolean, string | boolean | undefined>;
+    readonly AUTH_COOKIE_SAMESITE: z.ZodDefault<z.ZodEnum<["lax", "strict", "none"]>>;
+    readonly AUTH_COOKIE_DOMAIN: z.ZodOptional<z.ZodString>;
+    readonly AUTH_ACCESS_COOKIE_NAME: z.ZodDefault<z.ZodString>;
+    readonly AUTH_REFRESH_COOKIE_NAME: z.ZodDefault<z.ZodString>;
+};
+
 /**
  * Derive a conventional table name from a model class name: the trailing
  * `Model` suffix is stripped and the rest snake-cased (`UserModel` → `user`).
@@ -626,6 +955,378 @@ declare function createdByColumn(): tempest_db_js.Column<string, tempest_db_js.C
  */
 declare function updatedByColumn(): tempest_db_js.Column<string, tempest_db_js.ColumnFlags>;
 
+/**
+ * Base for an authenticated user. Subclass it, set `tablename`, and add domain
+ * columns (name, avatar, …):
+ *
+ * ```ts
+ * class UserModel extends BaseUserModel {
+ *   static tablename = tableNameFor("UserModel"); // "user"
+ *   name = column.text().notNull();
+ * }
+ * ```
+ */
+declare abstract class BaseUserModel extends BaseModel {
+    /** Login identifier; enforce uniqueness with a unique index in a migration. */
+    email: tempest_db_js.Column<string, tempest_db_js.ColumnFlags & {
+        notNull: true;
+    }>;
+    /** The password hash (never the plaintext) — see `PasswordUtils`. */
+    hashedPassword: tempest_db_js.Column<string, tempest_db_js.ColumnFlags & {
+        notNull: true;
+    }>;
+    /** Whether the user has administrative privileges. */
+    isAdmin: tempest_db_js.Column<boolean, tempest_db_js.ColumnFlags & {
+        notNull: true;
+    } & {
+        hasDefault: true;
+    }>;
+    /** Timestamp of the last successful login, or `null` if never. */
+    lastLoginAt: tempest_db_js.Column<Date, tempest_db_js.ColumnFlags>;
+}
+/** Purpose of a single-use user token. */
+declare const UserTokenPurpose: {
+    readonly ACTIVATION: "activation";
+    readonly PASSWORD_RESET: "password_reset";
+    readonly EMAIL_VERIFICATION: "email_verification";
+    readonly EMAIL_CHANGE: "email_change";
+};
+/** A `UserTokenPurpose` value. */
+type UserTokenPurpose = (typeof UserTokenPurpose)[keyof typeof UserTokenPurpose];
+/**
+ * Base for a single-use, hashed user token (activation, password reset, email
+ * verification/change). Store only the **hash** of the token; compare hashes on
+ * redemption.
+ */
+declare abstract class BaseUserTokenModel extends BaseModel {
+    /** Owning user id. */
+    userId: tempest_db_js.Column<string, tempest_db_js.ColumnFlags & {
+        notNull: true;
+    }>;
+    /** Hash of the opaque token value. */
+    tokenHash: tempest_db_js.Column<string, tempest_db_js.ColumnFlags & {
+        notNull: true;
+    }>;
+    /** Purpose discriminator (a {@link UserTokenPurpose} value). */
+    purpose: tempest_db_js.Column<string, tempest_db_js.ColumnFlags & {
+        notNull: true;
+    }>;
+    /** When the token stops being valid. */
+    expiresAt: tempest_db_js.Column<Date, tempest_db_js.ColumnFlags & {
+        notNull: true;
+    }>;
+    /** When the token was consumed, or `null` while still usable. */
+    usedAt: tempest_db_js.Column<Date, tempest_db_js.ColumnFlags>;
+    /** Optional JSON payload carried with the token (e.g. the pending email). */
+    payload: tempest_db_js.Column<Record<string, unknown>, tempest_db_js.ColumnFlags>;
+}
+/**
+ * Base for a rotating refresh token. Rotation revokes the used token and issues
+ * a new one in the same `familyId`; reuse of a revoked token in a family is the
+ * signal to revoke the whole family (theft detection).
+ */
+declare abstract class BaseUserRefreshTokenModel extends BaseModel {
+    /** Owning user id. */
+    userId: tempest_db_js.Column<string, tempest_db_js.ColumnFlags & {
+        notNull: true;
+    }>;
+    /** Hash of the opaque refresh token. */
+    tokenHash: tempest_db_js.Column<string, tempest_db_js.ColumnFlags & {
+        notNull: true;
+    }>;
+    /** Rotation family — all tokens descended from one login share it. */
+    familyId: tempest_db_js.Column<string, tempest_db_js.ColumnFlags & {
+        notNull: true;
+    } & {
+        hasDefault: true;
+    }>;
+    /** When the token expires. */
+    expiresAt: tempest_db_js.Column<Date, tempest_db_js.ColumnFlags & {
+        notNull: true;
+    }>;
+    /** When the token was rotated/consumed, or `null`. */
+    usedAt: tempest_db_js.Column<Date, tempest_db_js.ColumnFlags>;
+    /** When the token was revoked, or `null` while active. */
+    revokedAt: tempest_db_js.Column<Date, tempest_db_js.ColumnFlags>;
+}
+
+/** The kind of mutation an audit entry records. */
+declare const AuditAction: {
+    readonly CREATE: "create";
+    readonly UPDATE: "update";
+    readonly DELETE: "delete";
+};
+/** An `AuditAction` value. */
+type AuditAction = (typeof AuditAction)[keyof typeof AuditAction];
+/** A per-field before/after change. */
+interface FieldChange {
+    before: unknown;
+    after: unknown;
+}
+/**
+ * Freeze a row (ORM instance or plain object) into a plain, comparable record,
+ * dropping keys whose value is a function.
+ *
+ * @param row - The row to snapshot.
+ * @param exclude - Field names to omit (e.g. `["hashedPassword"]`).
+ * @returns A plain record of the row's own enumerable data fields.
+ */
+declare function snapshot(row: Record<string, unknown>, exclude?: readonly string[]): Record<string, unknown>;
+/**
+ * Compute the changed-field diff between two snapshots.
+ *
+ * @param before - The snapshot before the change.
+ * @param after - The snapshot after the change.
+ * @returns A map of changed field → `{ before, after }`; empty when nothing
+ *   changed. Keys present in only one side count as a change.
+ */
+declare function diffSnapshots(before: Record<string, unknown>, after: Record<string, unknown>): Record<string, FieldChange>;
+/**
+ * Base for an append-only audit log. Subclass it, set `tablename`, add indexes
+ * on `entity` / `entityId` / `actor` in a migration.
+ */
+declare abstract class BaseAuditLogModel extends BaseModel {
+    /** Changed model name (e.g. `"UserModel"`). */
+    entity: tempest_db_js.Column<string, tempest_db_js.ColumnFlags & {
+        notNull: true;
+    }>;
+    /** Changed row id, stored as text. */
+    entityId: tempest_db_js.Column<string, tempest_db_js.ColumnFlags & {
+        notNull: true;
+    }>;
+    /** Mutation kind (an {@link AuditAction} value). */
+    action: tempest_db_js.Column<string, tempest_db_js.ColumnFlags & {
+        notNull: true;
+    }>;
+    /** Who performed the change, or `null` for system/anonymous. */
+    actor: tempest_db_js.Column<string, tempest_db_js.ColumnFlags>;
+    /** Before/after diff, serialized as JSON. */
+    changes: tempest_db_js.Column<Record<string, FieldChange>, tempest_db_js.ColumnFlags & {
+        notNull: true;
+    }>;
+    /** Optional extra metadata (request id, ip, reason, …). */
+    context: tempest_db_js.Column<Record<string, unknown>, tempest_db_js.ColumnFlags>;
+}
+
+/**
+ * `TenantScopedRepository` — a `BaseRepository` that can't leak across tenants,
+ * mirroring `db.tenant`.
+ *
+ * In a shared-schema multi-tenant database every tenant's rows live in the same
+ * table, told apart by a `tenantId` column. Forget one `WHERE tenant_id = ?` and
+ * tenant A reads (or deletes) tenant B's data. This repository binds a tenant id
+ * at construction and injects it into every read filter and every write — the
+ * scoping is invisible at the call site.
+ */
+
+/**
+ * A repository whose every operation is scoped to a single tenant. Use it
+ * exactly like {@link BaseRepository}.
+ *
+ * ```ts
+ * const repo = new TenantScopedRepository(OrderModel, session, tenantId);
+ * await repo.list();                 // WHERE tenant_id = tenantId
+ * await repo.create({ total: "10" }); // tenant_id stamped automatically
+ * ```
+ *
+ * @typeParam C - the model class (must declare the tenant column).
+ */
+declare class TenantScopedRepository<C extends ModelClass, TF extends string = "tenantId"> extends BaseRepository<C> {
+    private readonly tenantId;
+    private readonly tenantField;
+    private readonly modelClass;
+    /**
+     * @param model - The model class (must have the `tenantField` column).
+     * @param session - The async session.
+     * @param tenantId - The tenant every operation is scoped to.
+     * @param tenantField - Name of the tenant column. Default `"tenantId"`.
+     */
+    constructor(model: C, session: ConstructorParameters<typeof BaseRepository<C>>[1], tenantId: unknown, tenantField?: TF);
+    /** Merge the tenant predicate into a filter object. */
+    private scoped;
+    /** Stamp the tenant id onto an insert payload. */
+    private stamped;
+    list(filters?: WhereInput<InferModel<C>>): Promise<InferModel<C>[]>;
+    first(filters?: WhereInput<InferModel<C>>): Promise<InferModel<C> | null>;
+    exists(filters: WhereInput<InferModel<C>>): Promise<boolean>;
+    count(filters?: WhereInput<InferModel<C>>): Promise<number>;
+    /** Fetch by id **within the tenant**; throws `RecordNotFound` across tenants. */
+    getById(id: unknown): Promise<InferModel<C>>;
+    getByIdOrNull(id: unknown): Promise<InferModel<C> | null>;
+    /** Insert one row; the tenant id is stamped for you (don't pass it). */
+    create(data: Omit<InferInsert<C>, TF>): Promise<InferModel<C>>;
+    /** Insert many rows; the tenant id is stamped onto each. */
+    createMany(data: readonly Omit<InferInsert<C>, TF>[]): Promise<InferModel<C>[]>;
+    update(filters: WhereInput<InferModel<C>>, set: Partial<InferModel<C>>): Promise<number>;
+    delete(filters: WhereInput<InferModel<C>>): Promise<number>;
+    paginate(filter?: PaginationFilter$1<InferModel<C>>): Promise<PaginationResult<InferModel<C>>>;
+}
+
+/** Delivery state of an outbox event. */
+declare const OutboxStatus: {
+    readonly PENDING: "pending";
+    readonly SENT: "sent";
+    readonly FAILED: "failed";
+};
+/** An `OutboxStatus` value. */
+type OutboxStatus = (typeof OutboxStatus)[keyof typeof OutboxStatus];
+/**
+ * Base for a transactional outbox row. Subclass it and set `tablename`. Insert a
+ * row in the same transaction as the write it describes.
+ */
+declare abstract class BaseOutboxModel extends BaseModel {
+    /** Destination topic / routing key. */
+    topic: tempest_db_js.Column<string, tempest_db_js.ColumnFlags & {
+        notNull: true;
+    }>;
+    /** The event body, serialized as JSON. */
+    payload: tempest_db_js.Column<Record<string, unknown>, tempest_db_js.ColumnFlags & {
+        notNull: true;
+    }>;
+    /** Delivery state (an {@link OutboxStatus} value). */
+    status: tempest_db_js.Column<string, tempest_db_js.ColumnFlags & {
+        notNull: true;
+    } & {
+        hasDefault: true;
+    }>;
+    /** How many delivery attempts have been made. */
+    attempts: tempest_db_js.Column<number, tempest_db_js.ColumnFlags & {
+        notNull: true;
+    } & {
+        hasDefault: true;
+    }>;
+    /** Give up (mark `failed`) after this many attempts. */
+    maxAttempts: tempest_db_js.Column<number, tempest_db_js.ColumnFlags & {
+        notNull: true;
+    } & {
+        hasDefault: true;
+    }>;
+    /** Earliest time the row may be delivered (drives retry backoff). */
+    availableAt: tempest_db_js.Column<Date, tempest_db_js.ColumnFlags & {
+        notNull: true;
+    } & {
+        hasDefault: true;
+    }>;
+    /** When the row was successfully delivered, or `null`. */
+    sentAt: tempest_db_js.Column<Date, tempest_db_js.ColumnFlags>;
+    /** The last delivery error message, or `null`. */
+    lastError: tempest_db_js.Column<string, tempest_db_js.ColumnFlags>;
+}
+/** Publishes one event to the broker; throws to signal a delivery failure. */
+type OutboxPublisher = (topic: string, payload: Record<string, unknown>) => Promise<void>;
+/** Options for {@link OutboxRelay}. */
+interface OutboxRelayOptions {
+    /** Max rows to drain per pass. Default `100`. */
+    batchSize?: number;
+    /** Base backoff (seconds) between retries; scaled by attempt count. Default `30`. */
+    retryBackoffSeconds?: number;
+}
+/**
+ * Polls a `BaseOutboxModel` table and publishes pending events with retries.
+ *
+ * @typeParam C - the concrete outbox model class.
+ */
+declare class OutboxRelay<C extends ModelClass> {
+    private readonly repository;
+    private readonly publish;
+    private readonly logger;
+    private readonly batchSize;
+    private readonly retryBackoffSeconds;
+    private running;
+    /**
+     * @param repository - Repository over the outbox model.
+     * @param publish - Callback that delivers one event to the broker.
+     * @param options - Batch size and retry backoff.
+     */
+    constructor(repository: BaseRepository<C>, publish: OutboxPublisher, options?: OutboxRelayOptions);
+    /**
+     * Deliver one batch of due pending events.
+     *
+     * @param now - The current time (injectable for tests). Defaults to `new Date()`.
+     * @returns The number of events successfully delivered.
+     */
+    drainOnce(now?: Date): Promise<number>;
+    private markFailure;
+    /**
+     * Run `drainOnce` on an interval until {@link stop} is called.
+     *
+     * @param intervalMs - Delay between passes in milliseconds. Default `1000`.
+     */
+    run(intervalMs?: number): Promise<void>;
+    /** Stop the {@link run} loop after the current pass. */
+    stop(): void;
+}
+
+/**
+ * Slow-query logging, mirroring `db.slow_query`.
+ *
+ * `tempest-db-js` exposes an `onQuery` hook with the SQL + params but **no
+ * duration**, so timing has to happen at the driver boundary. This wraps an
+ * `AsyncDriver` so every statement is timed and any that meets or exceeds a
+ * threshold is logged — including statements run inside a reserved transaction.
+ *
+ * ```ts
+ * import { AsyncEngine, NodeSqliteDriver } from "tempest-express-sdk";
+ * import { wrapWithSlowQueryLog } from "tempest-express-sdk";
+ *
+ * const sync = NodeSqliteDriver.open("app.db");
+ * const timed = wrapWithSlowQueryLog(
+ *   { execute: (s, p) => Promise.resolve(sync.execute(s, p)), close: async () => sync.close() },
+ *   { thresholdMs: 200 },
+ * );
+ * const engine = new AsyncEngine(timed, "sqlite");
+ * ```
+ */
+
+/** Options for {@link wrapWithSlowQueryLog}. */
+interface SlowQueryOptions {
+    /** Statements at or above this many ms are logged. Default `500`. */
+    thresholdMs?: number;
+    /** Level for the slow-query lines. Default `"warning"`. */
+    level?: LogLevel;
+    /** Include the bound params in the log line. **Dev only** — may carry PII. */
+    logParameters?: boolean;
+    /** Logger name. Default `tempest_express_sdk.db.slow_query`. */
+    loggerName?: string;
+}
+/**
+ * Wrap an `AsyncDriver` so slow statements are logged. The returned driver is a
+ * drop-in for {@link AsyncEngine}; `iterate` and `reserve` (transactions) are
+ * preserved and their statements timed too.
+ *
+ * @param driver - The driver to wrap.
+ * @param options - Threshold, level and whether to log params.
+ * @returns A timing driver delegating to `driver`.
+ */
+declare function wrapWithSlowQueryLog(driver: AsyncDriver, options?: SlowQueryOptions): AsyncDriver;
+
+/**
+ * Database backup helper, mirroring `db.backup`.
+ *
+ * `backupDatabase` detects the dialect from the URL and produces a backup file:
+ * a `pg_dump` for PostgreSQL, a file copy for SQLite. It shells out to `pg_dump`
+ * for Postgres (must be on `PATH`), so the heavy lifting stays with the battle-
+ * tested tool rather than a hand-rolled dump.
+ */
+/** Options for {@link backupDatabase}. */
+interface BackupOptions {
+    /** Path to the `pg_dump` binary. Default `"pg_dump"` (resolved on `PATH`). */
+    pgDumpPath?: string;
+    /** Extra `pg_dump` arguments (e.g. `["--no-owner", "-Fc"]`). */
+    pgDumpArgs?: string[];
+}
+/**
+ * Back up a database to `destPath`.
+ *
+ * @param databaseUrl - The connection URL (SQLite or PostgreSQL).
+ * @param destPath - Where to write the backup.
+ * @param options - `pg_dump` binary path and extra args (Postgres only).
+ * @returns The `destPath` on success.
+ * @throws {Error} For in-memory SQLite, an unsupported dialect, or a non-zero
+ *   `pg_dump` exit.
+ */
+declare function backupDatabase(databaseUrl: string, destPath: string, options?: BackupOptions): Promise<string>;
+
 /**
  * Generic async service over a `tempest-db-js` repository.
  *
@@ -1155,6 +1856,93 @@ interface ClientIpOptions {
  */
 declare function getClientIp(req: Request, options?: ClientIpOptions): string;
 
+/**
+ * File-download helpers, mirroring `utils.download`.
+ *
+ * Serve a file from disk with HTTP Range support (resumable / seekable
+ * downloads → `206 Partial Content`) or send in-memory bytes, both with a
+ * correct `Content-Disposition`. Path resolution is traversal-safe.
+ */
+
+/**
+ * Resolve a client-supplied relative path under a root, refusing traversal
+ * outside it.
+ *
+ * @param root - The directory downloads are confined to.
+ * @param relativePath - The (untrusted) relative path.
+ * @param subdir - Optional sub-directory under `root`.
+ * @returns The absolute, validated path.
+ * @throws {Error} When the resolved path escapes `root`.
+ */
+declare function resolveDownloadPath(root: string, relativePath: string, subdir?: string): string;
+/** Options for {@link sendFileDownload} / {@link sendBytesDownload}. */
+interface DownloadOptions {
+    /** Download filename; defaults to the file's basename. */
+    filename?: string;
+    /** MIME type. Default `application/octet-stream`. */
+    contentType?: string;
+    /** Serve inline (view in browser) instead of forcing a download. */
+    inline?: boolean;
+}
+/**
+ * Stream a file from disk as a download, honoring a `Range` request header
+ * (responds `206` with `Content-Range` for a partial request, else `200`).
+ *
+ * @param req - The request (read for the `Range` header).
+ * @param res - The response.
+ * @param absolutePath - The absolute file path (validate it first — see
+ *   {@link resolveDownloadPath}).
+ * @param options - Filename, content type and inline flag.
+ * @returns Resolves once the response stream is wired up.
+ */
+declare function sendFileDownload(req: Request, res: Response$1, absolutePath: string, options?: DownloadOptions): Promise<void>;
+/**
+ * Send in-memory bytes as a download.
+ *
+ * @param res - The response.
+ * @param data - The bytes to send.
+ * @param options - Filename, content type and inline flag.
+ */
+declare function sendBytesDownload(res: Response$1, data: Uint8Array, options?: DownloadOptions): void;
+
+/**
+ * File-based log routing, mirroring `utils.log` / the `core.logging` file sink.
+ *
+ * `configureFileLogging` installs a {@link LogSink} that appends every record
+ * emitted by any {@link JSONLogger} to a per-level file (`info.log`,
+ * `error.log`, …) and, additionally, routes records flagged as captured HTTP
+ * 500s to a dedicated `500.log` — so uncaught-error triage has its own stream.
+ */
+
+/** Per-level log file names. */
+declare const LEVEL_LOG_FILES: Record<LogLevel, string>;
+/** The dedicated file for captured HTTP 500 records. */
+declare const HTTP_500_LOG_FILE = "500.log";
+/** A handle to detach file logging and close the open streams. */
+interface FileLoggingHandle {
+    /** Remove the sink and close every open file stream. */
+    close(): void;
+}
+/** Options for {@link configureFileLogging}. */
+interface FileLoggingOptions {
+    /** Directory the log files are written under (created if missing). */
+    dir: string;
+}
+/**
+ * Route every emitted log record into per-level files + `500.log`.
+ *
+ * @param options - The log directory.
+ * @returns A handle whose `close()` detaches the sink and closes the streams.
+ *
+ * @example
+ * ```ts
+ * const logs = configureFileLogging({ dir: "logs" });
+ * // ... on shutdown:
+ * logs.close();
+ * ```
+ */
+declare function configureFileLogging(options: FileLoggingOptions): FileLoggingHandle;
+
 /**
  * TOTP (RFC 6238) helper for MFA, mirroring `utils.totp.TOTPHelper`.
  *
@@ -2269,6 +3057,61 @@ declare class LocalUploadStorage implements UploadStorage {
  */
 declare function buildContentDisposition(filename: string, inline?: boolean): string;
 
+/**
+ * S3 / MinIO-backed {@link UploadStorage}, mirroring `utils.storage_backends`.
+ *
+ * Implements the same narrow `UploadStorage` interface as
+ * {@link LocalUploadStorage} over a MinIO/S3 client, so services swap backends
+ * without touching call sites. The `minio` client is an **optional** peer
+ * dependency, lazy-loaded on first use (or inject your own client for tests /
+ * a custom SDK).
+ */
+
+/** Minimal MinIO/S3 client surface used by {@link S3UploadStorage}. */
+interface S3ClientLike {
+    putObject(bucket: string, key: string, data: Buffer, size?: number, metaData?: Record<string, string>): Promise<unknown>;
+    getObject(bucket: string, key: string): Promise<Readable>;
+    removeObject(bucket: string, key: string): Promise<void>;
+}
+/** Options for {@link S3UploadStorage}. */
+interface S3UploadStorageOptions {
+    /** Target bucket. */
+    bucket: string;
+    /** Public base URL for {@link S3UploadStorage.url} (e.g. a CDN or the endpoint). */
+    publicBaseUrl?: string;
+    /** Inject a ready client (e.g. a `minio` `Client`, or a mock). */
+    client?: S3ClientLike;
+    /** MinIO/S3 endpoint host (used only when `client` is not injected). */
+    endPoint?: string;
+    /** Endpoint port. */
+    port?: number;
+    /** Whether to use TLS. */
+    useSSL?: boolean;
+    /** Access key. */
+    accessKey?: string;
+    /** Secret key. */
+    secretKey?: string;
+    /** Region. */
+    region?: string;
+}
+/** {@link UploadStorage} over a MinIO/S3 client. */
+declare class S3UploadStorage implements UploadStorage {
+    private readonly bucket;
+    private readonly publicBaseUrl;
+    private client;
+    private readonly options;
+    /**
+     * @param options - Bucket, public URL and either a client or connection config.
+     */
+    constructor(options: S3UploadStorageOptions);
+    /** Resolve the client, lazy-loading `minio` when one wasn't injected. */
+    private getClient;
+    save(key: string, data: Uint8Array, options?: SaveOptions): Promise<UploadResult>;
+    read(key: string): Promise<Buffer>;
+    delete(key: string): Promise<void>;
+    url(key: string): string;
+}
+
 /** Web Push DTOs (Zod), mirroring `webpush.schemas`. */
 
 /** The browser-provided push subscription keys. */
@@ -2316,13 +3159,13 @@ declare const webPushPayloadSchema: z.ZodObject<{
     data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "strip", z.ZodTypeAny, {
     title: string;
-    url?: string | undefined;
     data?: Record<string, unknown> | undefined;
+    url?: string | undefined;
     body?: string | undefined;
 }, {
     title: string;
-    url?: string | undefined;
     data?: Record<string, unknown> | undefined;
+    url?: string | undefined;
     body?: string | undefined;
 }>;
 type WebPushKeys = z.infer<typeof webPushKeysSchema>;
@@ -2424,16 +3267,16 @@ declare const inboundMessageSchema: z.ZodObject<{
     direction: z.ZodOptional<z.ZodEnum<["incoming", "outgoing"]>>;
 }, "strip", z.ZodTypeAny, {
     from: string;
+    timestamp: string;
     messageId: string;
     mediaType: "image" | "video" | "audio" | "document" | "sticker" | null;
-    timestamp: string;
     text?: string | undefined;
     direction?: "incoming" | "outgoing" | undefined;
 }, {
     from: string;
+    timestamp: string;
     messageId: string;
     mediaType: "image" | "video" | "audio" | "document" | "sticker" | null;
-    timestamp: string;
     text?: string | undefined;
     direction?: "incoming" | "outgoing" | undefined;
 }>;
@@ -2686,6 +3529,87 @@ declare class EmailProvider implements MessagingProvider {
     status(): Promise<string>;
 }
 
+/**
+ * Broadcast + multi-channel helpers over {@link MessagingProvider}.
+ *
+ * {@link broadcastText} fans one message out to many recipients through a single
+ * provider, with bounded concurrency and a per-recipient result (one failure
+ * never aborts the rest). {@link MessagingHub} keeps named providers so app code
+ * sends by channel name and can broadcast across all of them.
+ */
+
+/** The outcome of a single recipient's send within a broadcast. */
+interface BroadcastResult {
+    /** The recipient address/handle. */
+    to: string;
+    /** Whether the send succeeded. */
+    ok: boolean;
+    /** The provider result, when successful. */
+    result?: OutboundResult;
+    /** The error message, when failed. */
+    error?: string;
+}
+/** Options for {@link broadcastText}. */
+interface BroadcastOptions extends SendOptions {
+    /** Maximum concurrent sends. Default 10. */
+    concurrency?: number;
+}
+/**
+ * Send `text` to every recipient through `provider`, bounded by concurrency.
+ *
+ * A failed recipient is captured in its {@link BroadcastResult} (`ok: false`)
+ * rather than aborting the batch.
+ *
+ * @param provider - The channel to send through.
+ * @param recipients - Recipient addresses/handles.
+ * @param text - The message body.
+ * @param options - Concurrency + send options.
+ * @returns One result per recipient, in input order.
+ */
+declare function broadcastText(provider: MessagingProvider, recipients: string[], text: string, options?: BroadcastOptions): Promise<BroadcastResult[]>;
+/** A registry of named messaging channels. */
+declare class MessagingHub {
+    private readonly channels;
+    /**
+     * Register a provider under a channel name.
+     *
+     * @param name - The channel name (e.g. `"whatsapp"`, `"sms"`).
+     * @param provider - The provider implementation.
+     * @returns The hub (chainable).
+     */
+    register(name: string, provider: MessagingProvider): this;
+    /**
+     * Get a registered provider, throwing when the channel is unknown.
+     *
+     * @param name - The channel name.
+     * @returns The provider.
+     * @throws {Error} When no provider is registered under `name`.
+     */
+    get(name: string): MessagingProvider;
+    /** The registered channel names. */
+    channelNames(): string[];
+    /**
+     * Send text through a named channel.
+     *
+     * @param channel - The channel name.
+     * @param to - The recipient.
+     * @param text - The message body.
+     * @param options - Send options.
+     * @returns The provider result.
+     */
+    send(channel: string, to: string, text: string, options?: SendOptions): Promise<OutboundResult>;
+    /**
+     * Broadcast text to many recipients on a named channel.
+     *
+     * @param channel - The channel name.
+     * @param recipients - Recipient addresses/handles.
+     * @param text - The message body.
+     * @param options - Broadcast + send options.
+     * @returns One result per recipient.
+     */
+    broadcast(channel: string, recipients: string[], text: string, options?: BroadcastOptions): Promise<BroadcastResult[]>;
+}
+
 /**
  * Admin site + resource registry, mirroring `admin.site` / `admin.config`.
  *
@@ -3459,6 +4383,62 @@ interface AuthRouterOptions {
  */
 declare function makeAuthRouter(options: AuthRouterOptions): Router;
 
+/**
+ * Optional server-rendered HTML pages for the bundled auth flows, mirroring the
+ * FastAPI SDK's activation/reset templates.
+ *
+ * This SDK favors the JSON auth API + a decoupled frontend, but a link in an
+ * email (activation, password reset) sometimes has to land on a *server* page —
+ * there's no SPA to route to. These helpers render small, self-contained,
+ * theme-aware HTML pages (no template engine, no external assets) for exactly
+ * those landings.
+ */
+/** Options for {@link renderAuthResultPage}. */
+interface AuthResultPageOptions {
+    /** `true` renders a success state, `false` an error state. */
+    ok: boolean;
+    /** Page + heading title. */
+    title: string;
+    /** Body message. */
+    message: string;
+    /** Optional call-to-action link. */
+    cta?: {
+        href: string;
+        label: string;
+    };
+}
+/**
+ * Render a success/error result page (e.g. "account activated", "link
+ * expired").
+ *
+ * @param options - Success flag, title, message and an optional CTA.
+ * @returns A complete HTML document.
+ */
+declare function renderAuthResultPage(options: AuthResultPageOptions): string;
+/** Options for {@link renderPasswordResetFormPage}. */
+interface PasswordResetFormOptions {
+    /** Form POST target. */
+    action: string;
+    /** The reset token, embedded as a hidden field. */
+    token: string;
+    /** Page + heading title. Default `"Redefinir senha"`. */
+    title?: string;
+    /** Name of the hidden token field. Default `"token"`. */
+    tokenField?: string;
+    /** Name of the password field. Default `"password"`. */
+    passwordField?: string;
+    /** Submit button label. Default `"Redefinir senha"`. */
+    submitLabel?: string;
+}
+/**
+ * Render a "set a new password" form that POSTs the token + new password to
+ * `action`.
+ *
+ * @param options - Form action, token and field/label overrides.
+ * @returns A complete HTML document.
+ */
+declare function renderPasswordResetFormPage(options: PasswordResetFormOptions): string;
+
 /**
  * Express error handling, mirroring `api.handlers`.
  *
@@ -3474,8 +4454,8 @@ declare const REQUEST_ID_HEADER = "X-Request-ID";
 /**
  * Middleware that establishes a request id and binds the request context.
  *
- * Reuses an inbound `X-Request-ID` when present, otherwise generates one, sets
- * it on the response, and runs the rest of the chain inside
+ * Reuses an inbound `X-Request-ID` when present **and well-formed**, otherwise
+ * generates one, sets it on the response, and runs the rest of the chain inside
  * {@link runWithRequestContext} so loggers and handlers can read it.
  *
  * @returns The configured middleware.
@@ -3715,7 +4695,722 @@ interface RunServerOptions {
  */
 declare function runServer(app: Express, options?: RunServerOptions): Promise<Server>;
 
+/**
+ * `bodySizeLimitMiddleware` — reject oversize request bodies early, mirroring
+ * `api.middlewares.body_size`.
+ *
+ * Without an upstream limit a client can stream gigabytes before body parsers
+ * reject it — wasting bandwidth and RAM. This middleware short-circuits the
+ * moment `Content-Length` exceeds the cap, and defensively tracks streamed
+ * bytes for chunked/unknown-length uploads.
+ */
+
+/** Options for {@link bodySizeLimitMiddleware}. */
+interface BodySizeLimitOptions {
+    /** Hard cap on the request body in bytes. */
+    maxBytes: number;
+    /** Path prefixes that bypass the check (e.g. an upload endpoint). */
+    excludePaths?: string[];
+}
+/**
+ * Build a middleware enforcing `maxBytes` per request. A `Content-Length` over
+ * the cap is rejected immediately with `413`; chunked bodies are aborted once
+ * the streamed size crosses the cap.
+ *
+ * @param options - The cap and path exclusions.
+ * @returns An Express middleware.
+ */
+declare function bodySizeLimitMiddleware(options: BodySizeLimitOptions): RequestHandler;
+
+/**
+ * `csrfMiddleware` — double-submit cookie protection for state changes,
+ * mirroring `api.middlewares.csrf`.
+ *
+ * CSRF lets a third-party site trigger authenticated mutating requests through
+ * a victim's browser, because cookies ride along automatically. The
+ * double-submit defense: issue a random `csrf_token` cookie, have the frontend
+ * echo it in an `X-CSRF-Token` header, and reject mutating requests where the
+ * header is missing or does not match the cookie. A cross-site page can't read
+ * the cookie (same-origin policy), so it can't forge the header.
+ *
+ * JWT bearer auth (`Authorization: Bearer …`) is **not** subject to CSRF (the
+ * browser doesn't auto-attach it), so `/api/` routes are typically excluded.
+ */
+
+/** Default cookie holding the CSRF token. */
+declare const CSRF_COOKIE_NAME = "csrf_token";
+/** Default header the client echoes the cookie value into. */
+declare const CSRF_HEADER_NAME = "X-CSRF-Token";
+/**
+ * Generate a URL-safe random CSRF token.
+ *
+ * @param nBytes - Entropy bytes (32 → a 43-char token). Default `32`.
+ * @returns A URL-safe base64 token without padding.
+ */
+declare function generateCsrfToken(nBytes?: number): string;
+/** Options for {@link csrfMiddleware}. */
+interface CsrfOptions {
+    /** Name of the CSRF cookie. Default `csrf_token`. */
+    cookieName?: string;
+    /** Name of the CSRF header. Default `X-CSRF-Token`. */
+    headerName?: string;
+    /** Path prefixes that bypass the check (e.g. `["/api/", "/webhooks/"]`). */
+    excludePaths?: string[];
+}
+/**
+ * Build a double-submit CSRF middleware. Safe methods (GET/HEAD/OPTIONS) pass;
+ * unsafe methods must carry a matching cookie + header or get `403`.
+ *
+ * @param options - Cookie/header names and excluded path prefixes.
+ * @returns An Express middleware.
+ */
+declare function csrfMiddleware(options?: CsrfOptions): RequestHandler;
+
+/**
+ * `GracefulShutdown` — track in-flight requests and drain on shutdown,
+ * mirroring `api.middlewares.graceful`.
+ *
+ * Wire {@link GracefulShutdown.middleware} into the app, then on `SIGTERM`
+ * call {@link GracefulShutdown.beginDrain} (new non-exempt requests get `503`)
+ * and `await` {@link GracefulShutdown.waitDrained} before closing the server —
+ * so a rolling deploy never cuts an in-flight request mid-response.
+ */
+
+/** Options for {@link GracefulShutdown}. */
+interface GracefulShutdownOptions {
+    /** Max seconds to wait for in-flight requests to finish. Default `30`. */
+    drainTimeoutSeconds?: number;
+    /** `Retry-After` seconds on the 503 served while draining. Default `5`. */
+    retryAfterSeconds?: number;
+    /** Exact paths that keep being served while draining. */
+    exemptPaths?: string[];
+}
+/** In-flight request tracker with a drain gate. */
+declare class GracefulShutdown {
+    private readonly drainTimeoutSeconds;
+    private readonly retryAfterSeconds;
+    private readonly exempt;
+    private inFlightCount;
+    private draining;
+    private idleResolvers;
+    constructor(options?: GracefulShutdownOptions);
+    /** Number of requests currently being served. */
+    get inFlight(): number;
+    /** Whether draining has begun. */
+    get isDraining(): boolean;
+    /** The Express middleware: counts in-flight requests, 503s while draining. */
+    middleware(): RequestHandler;
+    private release;
+    /** Flip into draining mode (idempotent). New non-exempt requests get 503. */
+    beginDrain(): void;
+    /**
+     * Wait until in-flight requests finish or the drain timeout elapses.
+     *
+     * @returns `true` if everything drained in time, `false` on timeout.
+     */
+    waitDrained(): Promise<boolean>;
+}
+
+/**
+ * `idempotencyMiddleware` — cache responses by `Idempotency-Key`, mirroring
+ * `api.middlewares.idempotency`.
+ *
+ * A client retrying a mutating request with the same `Idempotency-Key` gets the
+ * original response back instead of a duplicate side effect (a second charge, a
+ * second order). Only mutating verbs are eligible; the key is scoped per
+ * `(method, path, key)` so the same key on different endpoints never collides.
+ */
+
+/** The canonical header (Stripe / AWS / GitHub all use it). */
+declare const IDEMPOTENCY_HEADER = "Idempotency-Key";
+/** A serialized response stored under an idempotency key. */
+interface CachedResponse {
+    statusCode: number;
+    headers: Array<[string, string]>;
+    body: string;
+    contentType: string | null;
+}
+/** Backend every idempotency cache implements. */
+interface IdempotencyStore {
+    /** Return the cached response for `key`, or `null` when missing/expired. */
+    get(key: string): Promise<CachedResponse | null>;
+    /** Store `response` under `key` with a TTL. */
+    set(key: string, response: CachedResponse, ttlSeconds: number): Promise<void>;
+}
+/** In-process {@link IdempotencyStore} with lazy TTL eviction (single-replica). */
+declare class MemoryIdempotencyStore implements IdempotencyStore {
+    private readonly store;
+    get(key: string): Promise<CachedResponse | null>;
+    set(key: string, response: CachedResponse, ttlSeconds: number): Promise<void>;
+}
+/** Minimal async Redis surface used by {@link RedisIdempotencyStore}. */
+interface IdempotencyRedisLike {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, options: {
+        EX: number;
+    }): Promise<unknown>;
+}
+/** {@link IdempotencyStore} backed by an async Redis client (multi-replica). */
+declare class RedisIdempotencyStore implements IdempotencyStore {
+    private readonly client;
+    private readonly prefix;
+    constructor(client: IdempotencyRedisLike, options?: {
+        prefix?: string;
+    });
+    get(key: string): Promise<CachedResponse | null>;
+    set(key: string, response: CachedResponse, ttlSeconds: number): Promise<void>;
+}
+/** Options for {@link idempotencyMiddleware}. */
+interface IdempotencyOptions {
+    /** The cache backend (memory or Redis). */
+    store: IdempotencyStore;
+    /** Time-to-live for a cached response, in seconds. Default 24h. */
+    ttlSeconds?: number;
+    /** Header carrying the key. Default `Idempotency-Key`. */
+    headerName?: string;
+}
+/**
+ * Build an idempotency middleware. On a cache hit it replays the stored
+ * response; on a miss it captures the response, stores it, and forwards.
+ *
+ * @param options - Store, TTL and header name.
+ * @returns An Express middleware.
+ */
+declare function idempotencyMiddleware(options: IdempotencyOptions): RequestHandler;
+
+/**
+ * `HttpMetrics` + `prometheusMiddleware` — per-request Prometheus metrics,
+ * mirroring the FastAPI `PrometheusMiddleware`.
+ *
+ * Complements the system `/metrics` router (`MetricsUtils.toPrometheus`, which
+ * reports process/host gauges) with **per-request** instrumentation: a request
+ * counter labelled by method/path/status and a latency histogram. Everything is
+ * in-process and dependency-free; expose it with {@link HttpMetrics.render}.
+ */
+
+/**
+ * In-process HTTP request metrics: a labelled request counter and a latency
+ * histogram, rendered as Prometheus text.
+ */
+declare class HttpMetrics {
+    private readonly buckets;
+    /** `method|status` → count. */
+    private readonly requestTotals;
+    /** `method|route` → histogram. */
+    private readonly durations;
+    constructor(options?: {
+        buckets?: number[];
+    });
+    /**
+     * Record one completed request.
+     *
+     * @param method - HTTP method.
+     * @param route - The route pattern (or path) — keep cardinality bounded.
+     * @param status - Response status code.
+     * @param durationSeconds - Wall-clock request duration in seconds.
+     */
+    observe(method: string, route: string, status: number, durationSeconds: number): void;
+    /** Render the collected metrics as Prometheus exposition text. */
+    render(): string;
+    /**
+     * Build the middleware that records each request into this collector.
+     *
+     * @param options - Optional exempt paths (e.g. the metrics route itself).
+     * @returns An Express middleware.
+     */
+    middleware(options?: {
+        exemptPaths?: string[];
+    }): RequestHandler;
+}
+/**
+ * Convenience factory: a fresh {@link HttpMetrics} plus its middleware.
+ *
+ * @param options - Histogram buckets and exempt paths.
+ * @returns The collector and its middleware.
+ */
+declare function prometheusMiddleware(options?: {
+    buckets?: number[];
+    exemptPaths?: string[];
+}): {
+    metrics: HttpMetrics;
+    middleware: RequestHandler;
+};
+
+/**
+ * Sliding-window rate-limit middleware with pluggable stores and keys,
+ * mirroring `api.middlewares.rate_limit`.
+ *
+ * Two axes are pluggable:
+ *
+ * - **Store** — where the counters live. {@link MemoryRateLimitStore} (default,
+ *   in-process) fits a single worker; {@link RedisRateLimitStore} shares state
+ *   across replicas via an atomic Lua sliding-window log.
+ * - **Key** — *who* a request counts against. {@link keyByIp} (default),
+ *   {@link keyByHeader} (e.g. an API key), {@link keyByJwtClaim} /
+ *   {@link keyByJwtSubject} (per authenticated principal), each falling back to
+ *   the client IP for anonymous traffic.
+ */
+
+/** Outcome of a single rate-limit check. */
+interface RateLimitResult {
+    /** `true` when the request fits under the limit. */
+    allowed: boolean;
+    /** Requests still allowed in the current window (`0` when rejected). */
+    remaining: number;
+    /** Seconds to wait before retrying (`0` when allowed, `>= 1` on rejection). */
+    retryAfter: number;
+}
+/** Backend that counts hits per key inside a sliding window. */
+interface RateLimitStore {
+    /**
+     * Register one hit for `key` and report whether it is allowed.
+     *
+     * @param key - The rate-limit bucket key.
+     * @param maxRequests - Maximum hits allowed in the window.
+     * @param windowSeconds - Sliding-window length in seconds.
+     * @returns The decision for this hit.
+     */
+    hit(key: string, maxRequests: number, windowSeconds: number): Promise<RateLimitResult>;
+}
+/**
+ * In-process sliding-window store backed by per-key timestamp logs.
+ *
+ * State lives in this worker's memory only — correct for a single process. For
+ * multi-replica deployments use {@link RedisRateLimitStore}.
+ */
+declare class MemoryRateLimitStore implements RateLimitStore {
+    private readonly buckets;
+    hit(key: string, maxRequests: number, windowSeconds: number): Promise<RateLimitResult>;
+}
+/** Minimal async Redis surface used by {@link RedisRateLimitStore}. */
+interface RateLimitRedisLike {
+    eval(script: string, options: {
+        keys: string[];
+        arguments: string[];
+    }): Promise<unknown>;
+}
+/**
+ * Distributed sliding-window store backed by a Redis sorted set. A single Lua
+ * script prunes expired members, counts survivors and conditionally adds the
+ * new hit, so the check is atomic across replicas. On a backend error the
+ * request is allowed when `failOpen` (the default).
+ */
+declare class RedisRateLimitStore implements RateLimitStore {
+    private readonly redis;
+    private readonly namespace;
+    private readonly failOpen;
+    /**
+     * @param redis - Async Redis client exposing `eval({ keys, arguments })`.
+     * @param options - Key namespace and fail-open behavior.
+     */
+    constructor(redis: RateLimitRedisLike, options?: {
+        namespace?: string;
+        failOpen?: boolean;
+    });
+    hit(key: string, maxRequests: number, windowSeconds: number): Promise<RateLimitResult>;
+}
+/** Builds a rate-limit bucket key from a request (sync or async). */
+type RateLimitKeyFunc = (req: Request) => string | Promise<string>;
+/** Minimal JWT decoder surface used by the `keyByJwt*` helpers. */
+interface JwtDecoderLike {
+    decode(token: string): Promise<Record<string, unknown>>;
+}
+/** Build a key function that buckets by resolved client IP. */
+declare function keyByIp(options?: ClientIpOptions): RateLimitKeyFunc;
+/**
+ * Build a key function that buckets by a request header value (e.g. an API
+ * key), falling back to the client IP for anonymous callers.
+ */
+declare function keyByHeader(headerName: string, options?: {
+    scope?: string;
+    fallbackToIp?: boolean;
+    trustedIpHeader?: string;
+}): RateLimitKeyFunc;
+/**
+ * Build a key function that buckets by a claim in the bearer token, falling
+ * back to the client IP for anonymous traffic.
+ */
+declare function keyByJwtClaim(jwt: JwtDecoderLike, claim: string, options?: {
+    scope?: string;
+    fallbackToIp?: boolean;
+    trustedIpHeader?: string;
+}): RateLimitKeyFunc;
+/** Build a key function that buckets by the JWT `sub` claim (per-user). */
+declare function keyByJwtSubject(jwt: JwtDecoderLike, options?: {
+    fallbackToIp?: boolean;
+    trustedIpHeader?: string;
+}): RateLimitKeyFunc;
+/** Options for {@link rateLimitMiddleware}. */
+interface RateLimitOptions {
+    /** Maximum requests per window. Default `60`. */
+    maxRequests?: number;
+    /** Window length in seconds. Default `60`. */
+    windowSeconds?: number;
+    /** Build a rate-limit key from the request. Overrides `trustedIpHeader`. */
+    keyFunc?: RateLimitKeyFunc;
+    /** Single edge-set header to resolve the client IP from when keying by IP. */
+    trustedIpHeader?: string;
+    /** Counter backend. Defaults to an in-process {@link MemoryRateLimitStore}. */
+    store?: RateLimitStore;
+    /** Exact paths to skip entirely (e.g. health probes). */
+    exemptPaths?: string[];
+    /** Whether to add a `Retry-After` header on 429s. Default `true`. */
+    retryAfterHeader?: boolean;
+    /** Body message of the 429 response. */
+    errorMessage?: string;
+}
+/**
+ * Build a sliding-window rate-limit middleware.
+ *
+ * @param options - Limits, key/store strategy and exemptions.
+ * @returns An Express middleware rejecting excess traffic with `429`.
+ * @throws {RangeError} When `maxRequests` < 1 or `windowSeconds` <= 0.
+ */
+declare function rateLimitMiddleware(options?: RateLimitOptions): RequestHandler;
+
+/**
+ * `requestTracingMiddleware` — structured per-request access logging, mirroring
+ * the request-tracing concern of the FastAPI SDK.
+ *
+ * Logs one JSON line per request with method, path, status, duration and the
+ * request id (from the request-id context), so every request is traceable in a
+ * log aggregator. It is the lightweight, dependency-free counterpart to full
+ * OpenTelemetry tracing — the request id correlates logs across services.
+ */
+
+/** Options for {@link requestTracingMiddleware}. */
+interface RequestTracingOptions {
+    /** Logger name. Default `tempest_express_sdk.api.tracing`. */
+    loggerName?: string;
+    /** Log level for completed requests. Default `"info"`. */
+    level?: LogLevel;
+    /** Exact paths to skip (e.g. health probes). */
+    exemptPaths?: string[];
+}
+/**
+ * Build an access-logging middleware. Records the request on completion with
+ * its duration in milliseconds.
+ *
+ * @param options - Logger name, level and exempt paths.
+ * @returns An Express middleware.
+ */
+declare function requestTracingMiddleware(options?: RequestTracingOptions): RequestHandler;
+
+/**
+ * OAuth2 / OIDC clients, mirroring `api.oauth`.
+ *
+ * Three clients out of the box: {@link GoogleOAuthClient},
+ * {@link GitHubOAuthClient} and the generic {@link OIDCProvider} (Auth0,
+ * Keycloak, Okta, Entra, Cognito). They cover only the OAuth2 dance — build an
+ * authorize URL, exchange the code for tokens, fetch the user. Storing the user,
+ * minting your own session token and setting cookies are the service's calls.
+ */
+
+/** Raised when a provider rejects part of the OAuth dance. */
+declare class OAuthError extends AppException {
+    static statusCode: number;
+    static code: string;
+}
+/** The single normalized identity shape the rest of the app sees. */
+interface OAuthUser {
+    /** Provider label (`"google"`, `"github"`, `"oidc:auth0"`, …). */
+    provider: string;
+    /** Stable per-provider id; pair with `provider` for a global key. */
+    subject: string;
+    email: string | null;
+    name: string | null;
+    picture: string | null;
+    /** The raw provider payload. */
+    raw: Record<string, unknown>;
+}
+/** The token bundle returned by a code exchange. */
+interface OAuthTokens {
+    accessToken: string;
+    tokenType: string;
+    refreshToken: string | null;
+    /** The OIDC id token (JWT), or `null` on plain OAuth2. */
+    idToken: string | null;
+    expiresIn: number | null;
+    scope: string | null;
+    raw: Record<string, unknown>;
+}
+/**
+ * Generate a URL-safe random `state` value. Store it server-side (or a signed
+ * cookie) before redirecting and compare on callback — a mismatch is a forged
+ * redirect.
+ *
+ * @param nBytes - Entropy bytes. Default `32`.
+ * @returns A URL-safe token.
+ */
+declare function generateOAuthState(nBytes?: number): string;
+/** Common constructor options for the OAuth clients. */
+interface OAuthClientOptions {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    scopes?: string[];
+    httpClient?: HTTPClient;
+}
+/** Base class implementing the OAuth2 dance; subclasses fill in the endpoints. */
+declare abstract class BaseOAuthClient {
+    abstract readonly providerName: string;
+    protected readonly clientId: string;
+    protected readonly clientSecret: string;
+    protected readonly redirectUri: string;
+    protected readonly scopes: string[];
+    protected readonly http: HTTPClient;
+    constructor(options: OAuthClientOptions);
+    protected defaultScopes(): string[];
+    /** The provider's authorization endpoint. */
+    protected abstract authorizeUrl(): string;
+    /** The provider's token endpoint. */
+    protected abstract tokenUrl(): string;
+    /** The provider's userinfo endpoint, or `null` when unavailable. */
+    protected userinfoUrl(): string | null;
+    /** Map a raw userinfo payload to {@link OAuthUser}. */
+    protected abstract parseUser(payload: Record<string, unknown>): OAuthUser;
+    /**
+     * Build the fully-formed authorize URL to redirect the user to.
+     *
+     * @param state - A value from {@link generateOAuthState}, saved server-side.
+     * @param extra - Extra query params (e.g. `{ access_type: "offline" }`).
+     * @returns The authorize URL.
+     */
+    buildAuthorizeUrl(state: string, extra?: Record<string, string>): string;
+    /**
+     * Exchange an authorization code for tokens.
+     *
+     * @param code - The `code` query param from the callback.
+     * @returns The parsed token bundle.
+     * @throws {OAuthError} When the provider rejects the exchange.
+     */
+    exchangeCode(code: string): Promise<OAuthTokens>;
+    /**
+     * Fetch the normalized user identity for a token bundle.
+     *
+     * @param tokens - The tokens from {@link exchangeCode}.
+     * @returns The normalized user.
+     * @throws {OAuthError} When userinfo is unconfigured or the call fails.
+     */
+    fetchUser(tokens: OAuthTokens): Promise<OAuthUser>;
+}
+/** Google identity (OIDC). Default scopes: `openid email profile`. */
+declare class GoogleOAuthClient extends BaseOAuthClient {
+    readonly providerName = "google";
+    protected defaultScopes(): string[];
+    protected authorizeUrl(): string;
+    protected tokenUrl(): string;
+    protected userinfoUrl(): string;
+    protected parseUser(payload: Record<string, unknown>): OAuthUser;
+}
+/** GitHub OAuth (no id_token; identity from `GET /user`). */
+declare class GitHubOAuthClient extends BaseOAuthClient {
+    readonly providerName = "github";
+    protected defaultScopes(): string[];
+    protected authorizeUrl(): string;
+    protected tokenUrl(): string;
+    protected userinfoUrl(): string;
+    protected parseUser(payload: Record<string, unknown>): OAuthUser;
+}
+/** Options for {@link OIDCProvider}. */
+interface OIDCProviderOptions extends OAuthClientOptions {
+    authorizeUrl: string;
+    tokenUrl: string;
+    userinfoUrl?: string | null;
+    providerName?: string;
+}
+/**
+ * Generic discovery-driven OIDC client. Pass the authorize / token / userinfo
+ * endpoints (fetch them once at boot from `${issuer}/.well-known/openid-configuration`).
+ * Default scopes: `openid email profile`.
+ */
+declare class OIDCProvider extends BaseOAuthClient {
+    readonly providerName: string;
+    private readonly _authorizeUrl;
+    private readonly _tokenUrl;
+    private readonly _userinfoUrl;
+    constructor(options: OIDCProviderOptions);
+    protected defaultScopes(): string[];
+    protected authorizeUrl(): string;
+    protected tokenUrl(): string;
+    protected userinfoUrl(): string | null;
+    protected parseUser(payload: Record<string, unknown>): OAuthUser;
+}
+
+/**
+ * `WebhookSignatureVerifier` — HMAC signature verification for inbound
+ * webhooks, mirroring `api.webhooks`.
+ *
+ * Providers compute `hmac(secret, body)` and ship the digest in a header (hex or
+ * base64). This verifies it in constant time and exposes an Express middleware
+ * that checks the header against the **raw** request body.
+ */
+
+/** Options for {@link WebhookSignatureVerifier}. */
+interface WebhookSignatureOptions {
+    /** Digest algorithm (e.g. `"sha256"`, `"sha512"`). Default `"sha256"`. */
+    algorithm?: string;
+    /** Header carrying the signature. Default `"X-Signature"`. */
+    headerName?: string;
+    /** Digest encoding. Default `"hex"`. */
+    encoding?: "hex" | "base64";
+    /** Prefix stripped from the header before comparing (e.g. `"sha256="`). */
+    prefix?: string;
+}
+/** Verifies an HMAC webhook signature over a raw request body. */
+declare class WebhookSignatureVerifier {
+    private readonly secret;
+    private readonly algorithm;
+    private readonly headerName;
+    private readonly encoding;
+    private readonly prefix;
+    /**
+     * @param secret - The shared signing secret.
+     * @param options - Algorithm, header name, encoding and optional prefix.
+     */
+    constructor(secret: string | Buffer, options?: WebhookSignatureOptions);
+    /** The header name this verifier reads. */
+    get header(): string;
+    /**
+     * Compute the expected signature for a raw body.
+     *
+     * @param body - The raw request body.
+     * @returns The signature in the configured encoding.
+     */
+    expected(body: BinaryLike): string;
+    /**
+     * Verify a signature against a raw body (constant time).
+     *
+     * @param body - The raw request body.
+     * @param signature - The header value (including any configured prefix).
+     * @returns `true` when it matches.
+     */
+    verify(body: BinaryLike, signature: string): boolean;
+    /**
+     * Build an Express middleware that rejects requests with a bad signature.
+     *
+     * The route **must** receive the raw body as a `Buffer` — mount
+     * `express.raw({ type: "..." })` (matching every content type) before this
+     * middleware so `req.body` is the raw bytes. On success the request proceeds
+     * (parse `req.body` yourself).
+     *
+     * @param options - Custom error message.
+     * @returns An Express middleware.
+     */
+    middleware(options?: {
+        errorMessage?: string;
+    }): RequestHandler;
+}
+
+/**
+ * `makeToolSpecRouter` — a machine-readable capability manifest at the root
+ * prefix, mirroring `api.routers.tool_spec`.
+ *
+ * Services expose a small manifest so callers discover capabilities without
+ * parsing the full OpenAPI document. Pass a static object, a sync provider, or
+ * an async provider (recomputed per request).
+ */
+
+/** The manifest, or a (possibly async) provider of it. */
+type SpecProvider = Record<string, unknown> | (() => Record<string, unknown>) | (() => Promise<Record<string, unknown>>);
+/** Options for {@link makeToolSpecRouter}. */
+interface ToolSpecOptions {
+    /** Endpoint path. Default `"/tool-spec"`. */
+    path?: string;
+}
+/**
+ * Build a router serving the manifest at a root-prefix `GET` route.
+ *
+ * @param spec - A static object or a sync/async provider.
+ * @param options - The endpoint path.
+ * @returns An Express router with a single `GET` route.
+ */
+declare function makeToolSpecRouter(spec: SpecProvider, options?: ToolSpecOptions): Router;
+
+/**
+ * `makeLogsRouter` — a paginated read endpoint over the file logs, mirroring
+ * `api.routers.logs`.
+ *
+ * Reads the per-level / `500.log` files written by `configureFileLogging`,
+ * parses each JSON line, and serves the newest-first, offset-paginated. Guard it
+ * (this exposes operational data) with any middleware you pass in `guards`.
+ */
+
+/** Selector for which log file(s) to read. */
+type LogSource = "all" | "debug" | "info" | "warning" | "error" | "500";
+/** Options for {@link makeLogsRouter}. */
+interface LogsRouterOptions {
+    /** Directory holding the log files (same one passed to `configureFileLogging`). */
+    dir: string;
+    /** Endpoint path. Default `"/logs"`. */
+    path?: string;
+    /** Middlewares run before the handler (e.g. a token guard). */
+    guards?: RequestHandler[];
+}
+/**
+ * Build a router serving `GET <path>` with query params `source`, `page` and
+ * `pageSize`. Returns `{ items, total, page, pageSize, pages }`, newest first.
+ *
+ * @param options - Log directory, path and optional guards.
+ * @returns An Express router.
+ */
+declare function makeLogsRouter(options: LogsRouterOptions): Router;
+
+/**
+ * In-memory test-database helpers, mirroring `testing.database`.
+ *
+ * Stand up a fully-wired `tempest-db-js` engine over an in-memory SQLite
+ * database whose schema is created directly from your models — no migration
+ * files, no temp files, no external service. One shared connection backs both
+ * the DDL and every session, so repositories see the tables you declared.
+ *
+ * The helpers are framework-agnostic (no `vitest`/`jest` import), so wrap them
+ * in whatever harness the consuming project uses.
+ */
+
+/** A disposable in-memory test database. */
+interface TestDatabase {
+    /** The wired async engine — hand its sessions to repositories. */
+    readonly engine: AsyncEngine;
+    /** Open a fresh session on the shared in-memory connection. */
+    session(): AsyncSession;
+    /** Dispose the engine and drop the in-memory database. */
+    close(): Promise<void>;
+}
+/**
+ * Create an in-memory SQLite test database with tables reflected from `models`.
+ *
+ * @param models - The model classes whose tables should be created.
+ * @returns A {@link TestDatabase} — remember to `await close()` in teardown.
+ *
+ * @example
+ * ```ts
+ * const db = createTestDatabase([UserModel]);
+ * const repo = new UserRepository(db.session());
+ * await repo.create({ name: "Ana", email: "ana@x.com", passwordHash: "..." });
+ * await db.close();
+ * ```
+ */
+declare function createTestDatabase(models: readonly ModelClass[]): TestDatabase;
+/**
+ * Run `fn` against a fresh in-memory test database, disposing it afterwards even
+ * if `fn` throws.
+ *
+ * @param models - The model classes whose tables should be created.
+ * @param fn - Receives the {@link TestDatabase} and returns a promise.
+ * @returns Whatever `fn` resolves to.
+ *
+ * @example
+ * ```ts
+ * await withTestDatabase([UserModel], async (db) => {
+ *   const repo = new UserRepository(db.session());
+ *   expect(await repo.count()).toBe(0);
+ * });
+ * ```
+ */
+declare function withTestDatabase<T>(models: readonly ModelClass[], fn: (db: TestDatabase) => Promise<T>): Promise<T>;
+
 /** The installed SDK version. Single source of truth for the barrel + CLI. */
-declare const VERSION = "0.10.0";
+declare const VERSION = "0.20.0";
 
-export { type ActivationInput, ActivationService, type ActivationServiceOptions, type ActivationStore, type AdminField, type AdminListQuery, type AdminListResult, type AdminResource, type AdminRouterOptions, AdminSite, AppException, type AppExceptionHandlerOptions, type AppExceptionOptions, type AttachWebSocketOptions, AttemptThrottle, type AttemptThrottleOptions, type AuthResponse, type AuthRouterOptions, type AuthUser, type BaseAppSettings, BaseController, BaseModel, type BaseResponse, BaseService, type BrokerManager, CEP_PATTERN, CNPJ_PATTERN, CPF_PATTERN, type CPUMetrics, type CacheManager, type CachedOptions, type CatalogData, CircuitOpenError, type ClientIpOptions, CompositeFeatureFlagBackend, ConflictException, type CreateAppOpenApi, type CreateAppOptions, type CursorPaginationFilter, DEFAULT_LOCALE, type EmailMessage, type EmailOptions, EmailProvider, type EmailProviderOptions, EmailUtils, type Enum, type EnumHelpers, type EnumSpec, EnvFeatureFlagBackend, EventStream, type EventStreamOptions, type ExceptionDetails, ExpiredTokenException, type FeatureFlagBackend, FeatureFlags, type FlagContext, ForbiddenException, type GPUMetrics, type GenerateOpenApiOptions, HTTPClient, type HTTPClientOptions, HTTP_500_MARKER, type HandshakeInfo, type HealthCheck, type HealthRouterOptions, type InboundHandler, type InboundMessage, InvalidTokenException, type IssuedSession, JSONLogger, JWTUtils, type JWTUtilsOptions, type JwtAuthOptions, type JwtClaims, LocalUploadStorage, type LocalUploadStorageOptions, type LogExtra, type LogLevel, type LoginInput, type LoginResult, type MediaKind, MemoryBroker, MemoryCacheManager, MemoryFeatureFlagBackend, type MemoryMetrics, MemorySessionStore, MemoryThrottleBackend, MessageCatalog, type MessageHandler, type MessagingProvider, type MetricsRouterOptions, MetricsUtils, type MfaChallenge, type MfaChallengeInput, type MfaCodeInput, type MfaEnrollment, MfaService, type MfaServiceOptions, type MfaStore, NotFoundException, type OpenApiDocument, type OpenApiInfo, type OutboundMedia, type OutboundResult, PHONE_BR_PATTERN, type PaginationFilter, type PasswordResetConfirmInput, type PasswordResetRequestInput, PasswordResetService, type PasswordResetServiceOptions, type PasswordResetStore, PasswordUtils, REQUEST_ID_HEADER, RabbitBroker, type RabbitBrokerOptions, RedisCacheManager, type RedisLike, type RedisPublisherLike, RedisSSEBroker, type RedisSSEBrokerOptions, RedisSessionStore, type RedisSubscriberLike, type RedocOptions, type RefreshInput, Region, type RegionValue, type RegisterExceptionHandlersOptions, type RequestContext, type ResponseMapper, RetryPolicy, type RunServerOptions, SSEBroker, type SaveOptions, type SendOptions, ServerSentEvent, type ServerSentEventInit, type Session, type SessionMiddlewareOptions, type SessionRedisLike, SessionService, type SessionServiceOptions, type SessionStore, type SignupInput, type StateBR, type SwaggerOptions, type SystemMetrics, TOTPHelper, type TOTPOptions, type TaskHandler, TaskManager, type TaskManagerOptions, TelegramProvider, type TelegramProviderOptions, type ThrottleBackend, type ThrottleStatus, type ToDictOptions, type TokenPair, TooManyRequestsException, type TooManyRequestsOptions, TwilioSmsProvider, type TwilioSmsProviderOptions, type TwilioWebhookOptions, UF, type UFValue, UnauthorizedException, type UnhandledExceptionHandlerOptions, type UploadResult, type UploadStorage, UserAuthService, type UserAuthServiceOptions, type UserPublic, type UserStore, VERSION, ValidationException, type WSEnvelope, WebPushDispatcher, type WebPushDispatcherOptions, WebPushError, WebPushGoneError, type WebPushKeys, type WebPushPayload, type WebPushSubscription, type WebSocketConnection, WebSocketHub, type WebSocketHubOptions, type WebSocketLike, WhatsAppProvider, type WhatsAppProviderOptions, type WhatsAppWebhookOptions, activationSchema, attachWebSocketHub, authResponseSchema, baseAppSettingsSchema, baseAppSettingsShape, baseResponseSchema, bearerToken, buildContentDisposition, cached, cepField, citiesByUf, cnpjField, coerceFlag, configureLogging, corsSettingsShape, cpfField, cpfOrCnpjField, createApp, createOpenApiRegistry, createdByColumn, cursorPaginationFilterSchema, cursorPaginationSchema, databaseSettingsShape, decodeCursor, defaultMessageCatalog, defineEnum, deletedAtColumn, encodeCursor, generateOpaqueToken, generateOpenApiDocument, getAuth, getClientIp, getConditions, getPaginationConditions, getRequestId, getState, hashOpaqueToken, inboundMessageSchema, isValidCep, isValidCity, isValidCnpj, isValidCpf, isValidCpfCnpj, isValidPhoneBr, isValidUf, listStates, loadSettings, loginSchema, makeAdminRouter, makeAppExceptionHandler, makeAuthRouter, makeFlagGuard, makeHealthRouter, makeJwtAuthMiddleware, makeMetricsRouter, makeSessionMiddleware, makeTwilioWebhookRouter, makeUnhandledExceptionHandler, makeWhatsAppWebhookRouter, mfaChallengeSchema, mfaCodeSchema, mfaEnrollResponseSchema, modifyDict, mountOpenApiJson, mountRedoc, mountSwaggerUi, normalizeCep, normalizeCnpj, normalizeCpf, normalizeCpfCnpj, normalizePhoneBr, normalizeUf, notFoundHandler, onlyDigits, paginationFilterSchema, paginationSchema, parseAcceptLanguage, parseCookies, passwordResetConfirmSchema, passwordResetRequestSchema, phoneBrField, refreshSchema, registerExceptionHandlers, requestIdMiddleware, requireRoles, runServer, runWithRequestContext, serverSettingsShape, sessionCookie, setRequestId, signupSchema, sseResponse, statesByRegion, tableNameFor, toDict, toUtc, tokenFromUrl, tokenPairSchema, ufField, updatedByColumn, userPublicSchema, utcnow, validateTwilioSignature, verifyOpaqueToken, webPushKeysSchema, webPushPayloadSchema, webPushSubscriptionSchema, wsEnvelopeSchema };
+export { type ActivationInput, ActivationService, type ActivationServiceOptions, type ActivationStore, type AdminField, type AdminListQuery, type AdminListResult, type AdminResource, type AdminRouterOptions, AdminSite, AppException, type AppExceptionHandlerOptions, type AppExceptionOptions, type AttachWebSocketOptions, AttemptThrottle, type AttemptThrottleOptions, AuditAction, type AuthResponse, type AuthResultPageOptions, type AuthRouterOptions, type AuthUser, type BackupOptions, type BaseAppSettings, BaseAuditLogModel, BaseController, BaseModel, BaseOAuthClient, BaseOutboxModel, type BaseResponse, BaseService, BaseUserModel, BaseUserRefreshTokenModel, BaseUserTokenModel, type BodySizeLimitOptions, type BroadcastOptions, type BroadcastResult, type BrokerManager, CEP_PATTERN, CNPJ_PATTERN, CPF_PATTERN, type CPUMetrics, CSRF_COOKIE_NAME, CSRF_HEADER_NAME, type CacheManager, type CachedOptions, type CachedResponse, type CatalogData, CircuitOpenError, type ClientIpOptions, CompositeFeatureFlagBackend, ConflictException, type CreateAppOpenApi, type CreateAppOptions, type CsrfOptions, type CursorPaginationFilter, DEFAULT_LOCALE, type DownloadOptions, type EmailMessage, type EmailOptions, EmailProvider, type EmailProviderOptions, EmailUtils, type Enum, type EnumHelpers, type EnumSpec, EnvFeatureFlagBackend, EventStream, type EventStreamOptions, type ExceptionDetails, ExpiredTokenException, type FeatureFlagBackend, FeatureFlags, type FieldChange, type FileLoggingHandle, type FileLoggingOptions, type FlagContext, ForbiddenException, type GPUMetrics, type GenerateOpenApiOptions, GitHubOAuthClient, GoogleOAuthClient, GracefulShutdown, type GracefulShutdownOptions, HTTPClient, type HTTPClientOptions, HTTP_500_LOG_FILE, HTTP_500_MARKER, type HandshakeInfo, type HealthCheck, type HealthRouterOptions, HttpMetrics, IDEMPOTENCY_HEADER, type IdempotencyOptions, type IdempotencyRedisLike, type IdempotencyStore, type InboundHandler, type InboundMessage, InvalidTokenException, type IssuedSession, JSONLogger, JWTUtils, type JWTUtilsOptions, type JwtAuthOptions, type JwtClaims, type JwtDecoderLike, LEVEL_LOG_FILES, LocalUploadStorage, type LocalUploadStorageOptions, type LogEntry, type LogExtra, type LogLevel, type LogSink, type LogSource, type LoginInput, type LoginResult, type LogsRouterOptions, type MediaKind, MemoryBroker, MemoryCacheManager, MemoryFeatureFlagBackend, MemoryIdempotencyStore, type MemoryMetrics, MemoryRateLimitStore, MemorySessionStore, MemoryThrottleBackend, MessageCatalog, type MessageHandler, MessagingHub, type MessagingProvider, type MetricsRouterOptions, MetricsUtils, type MfaChallenge, type MfaChallengeInput, type MfaCodeInput, type MfaEnrollment, MfaService, type MfaServiceOptions, type MfaStore, NotFoundException, type OAuthClientOptions, OAuthError, type OAuthTokens, type OAuthUser, OIDCProvider, type OIDCProviderOptions, type OpenApiDocument, type OpenApiInfo, type OutboundMedia, type OutboundResult, type OutboxPublisher, OutboxRelay, type OutboxRelayOptions, OutboxStatus, PHONE_BR_PATTERN, type PaginationFilter, type PaginationLinkOptions, type PasswordResetConfirmInput, type PasswordResetFormOptions, type PasswordResetRequestInput, PasswordResetService, type PasswordResetServiceOptions, type PasswordResetStore, PasswordUtils, REQUEST_ID_HEADER, RabbitBroker, type RabbitBrokerOptions, type RateLimitKeyFunc, type RateLimitOptions, type RateLimitRedisLike, type RateLimitResult, type RateLimitStore, RedisCacheManager, RedisIdempotencyStore, type RedisLike, type RedisPublisherLike, RedisRateLimitStore, RedisSSEBroker, type RedisSSEBrokerOptions, RedisSessionStore, type RedisSubscriberLike, type RedocOptions, type RefreshInput, Region, type RegionValue, type RegisterExceptionHandlersOptions, type RequestContext, type RequestTracingOptions, type ResponseMapper, RetryPolicy, type RunServerOptions, type S3ClientLike, S3UploadStorage, type S3UploadStorageOptions, SSEBroker, type SaveOptions, type SendOptions, ServerSentEvent, type ServerSentEventInit, type Session, type SessionMiddlewareOptions, type SessionRedisLike, SessionService, type SessionServiceOptions, type SessionStore, type SignupInput, type SlowQueryOptions, type SpecProvider, type StateBR, type SwaggerOptions, type SyncFilter, type SystemMetrics, TOTPHelper, type TOTPOptions, type TaskHandler, TaskManager, type TaskManagerOptions, TelegramProvider, type TelegramProviderOptions, TenantScopedRepository, type TestDatabase, type ThrottleBackend, type ThrottleStatus, type ToDictOptions, type TokenPair, TooManyRequestsException, type TooManyRequestsOptions, type ToolSpecOptions, TwilioSmsProvider, type TwilioSmsProviderOptions, type TwilioWebhookOptions, UF, type UFValue, UnauthorizedException, type UnhandledExceptionHandlerOptions, type UploadResult, type UploadStorage, UserAuthService, type UserAuthServiceOptions, type UserPublic, type UserStore, UserTokenPurpose, VERSION, ValidationException, type WSEnvelope, WebPushDispatcher, type WebPushDispatcherOptions, WebPushError, WebPushGoneError, type WebPushKeys, type WebPushPayload, type WebPushSubscription, type WebSocketConnection, WebSocketHub, type WebSocketHubOptions, type WebSocketLike, type WebhookSignatureOptions, WebhookSignatureVerifier, WhatsAppProvider, type WhatsAppProviderOptions, type WhatsAppWebhookOptions, activationSchema, addLogSink, attachWebSocketHub, authResponseSchema, authSettingsShape, backupDatabase, baseAppSettingsSchema, baseAppSettingsShape, baseResponseSchema, bearerToken, bodySizeLimitMiddleware, broadcastText, buildContentDisposition, buildPaginationLinkHeader, cached, centsField, cepField, citiesByUf, cnpjField, coerceFlag, configureFileLogging, configureLogging, corsSettingsShape, cpfField, cpfOrCnpjField, createApp, createOpenApiRegistry, createTestDatabase, createdByColumn, csrfMiddleware, cursorPaginationFilterSchema, cursorPaginationSchema, databaseSettingsShape, decodeCursor, defaultMessageCatalog, defineEnum, deletedAtColumn, diffSnapshots, emailSettingsShape, encodeCursor, envBoolean, envList, generateCsrfToken, generateOAuthState, generateOpaqueToken, generateOpenApiDocument, getAuth, getClientIp, getConditions, getPaginationConditions, getRequestId, getState, hashOpaqueToken, hexColorField, idempotencyMiddleware, inboundMessageSchema, isValidCep, isValidCity, isValidCnpj, isValidCpf, isValidCpfCnpj, isValidPhoneBr, isValidUf, jwtSettingsShape, keyByHeader, keyByIp, keyByJwtClaim, keyByJwtSubject, latitudeField, listStates, loadSettings, logEntrySchema, logSettingsShape, loginSchema, longitudeField, makeAdminRouter, makeAppExceptionHandler, makeAuthRouter, makeFlagGuard, makeHealthRouter, makeJwtAuthMiddleware, makeLogsRouter, makeMetricsRouter, makeSessionMiddleware, makeToolSpecRouter, makeTwilioWebhookRouter, makeUnhandledExceptionHandler, makeWhatsAppWebhookRouter, mfaChallengeSchema, mfaCodeSchema, mfaEnrollResponseSchema, minioSettingsShape, modifyDict, mountOpenApiJson, mountRedoc, mountSwaggerUi, nonEmptyStrField, nonNegativeFloatField, nonNegativeIntField, normalizeCep, normalizeCnpj, normalizeCpf, normalizeCpfCnpj, normalizePhoneBr, normalizeUf, notFoundHandler, onlyDigits, paginationFilterSchema, paginationSchema, parseAcceptLanguage, parseCookies, passwordResetConfirmSchema, passwordResetRequestSchema, percentField, phoneBrField, portField, positiveFloatField, positiveIntField, priceField, prometheusMiddleware, rabbitmqSettingsShape, rateLimitMiddleware, ratingField, ratioField, redisSettingsShape, refreshSchema, registerExceptionHandlers, renderAuthResultPage, renderPasswordResetFormPage, requestIdMiddleware, requestTracingMiddleware, requireRoles, resolveDownloadPath, runServer, runWithRequestContext, sendBytesDownload, sendFileDownload, serverSettingsShape, sessionCookie, sessionSettingsShape, setRequestId, signupSchema, slugField, snapshot, sseResponse, statesByRegion, syncFilterSchema, syncPaginationSchema, tableNameFor, toDict, toUtc, tokenFromUrl, tokenPairSchema, tokenSettingsShape, ufField, updatedByColumn, uploadSettingsShape, userPublicSchema, utcnow, validateTwilioSignature, verifyOpaqueToken, webPushKeysSchema, webPushPayloadSchema, webPushSettingsShape, webPushSubscriptionSchema, webSocketSettingsShape, withTestDatabase, wrapWithSlowQueryLog, wsEnvelopeSchema };