tina4-nodejs 3.13.38 → 3.13.40

package/CLAUDE.md

@@ -1,4 +1,4 @@
-# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.37)
+# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.40)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
@@ -117,14 +117,18 @@ The HTTP foundation. Handles request/response lifecycle, route matching, middlew
 - `fakeData.ts` — Core fake data generator (names, emails, addresses, UUIDs, etc.)
 - `constants.ts` — HTTP status codes (`HTTP_OK`, `HTTP_NOT_FOUND`, etc.) and content types (`APPLICATION_JSON`, `TEXT_HTML`, etc.)
 - `devAdmin.ts` — Dev toolbar (fixed bottom bar injected into HTML pages) and admin dashboard at `/_dev/`
+- `mcp.ts` - Model Context Protocol server (mounted by `devAdmin.ts` at `/__dev/mcp`) for live AI access to project tools. **MCP environment (read by `mcp.ts` / `devAdmin.ts`):**
+  - `TINA4_MCP` / `TINA4_DEBUG` - capability gate (whether MCP is enabled at all). Explicit `TINA4_MCP` true/false wins on any host; else `TINA4_DEBUG=true` enables it.
+  - `TINA4_MCP_TOKEN` - bearer token authorising a REMOTE MCP request (fallback `TINA4_API_KEY`). Accepted as `Authorization: Bearer`, `X-MCP-Token`, or `X-Api-Key`. With no token configured a remote caller is always denied. Loopback callers never need it.
+  - `TINA4_MCP_REMOTE` - set `true` to allow non-loopback MCP callers at all (still requires a valid token).
 - `auth.ts` — Authentication helpers
 - `cache.ts` — In-memory caching
 - `session.ts` — Session management with pluggable handlers. `TINA4_SESSION_SAMESITE` env var (default: Lax)
-- `websocket.ts` — WebSocket support with backplane for scaling via Redis/NATS pub/sub (`TINA4_WS_BACKPLANE`, `TINA4_WS_BACKPLANE_URL`). The backplane is wired for real: `broadcast`/`broadcastToRoom`/`sendTo` deliver to LOCAL connections first (resiliently — a dead/slow client is pruned, never aborting the loop) then publish an envelope `{src,kind,exclude,room,path,text|b64}` to the shared channel `tina4:ws` (identical wire shape across all 4 frameworks). The subscribe callback relays directly on the event loop with an origin guard (drop our own `src` echo — no double-delivery) and never re-publishes (no cluster loop); binary messages ride as base64. Security/ops knobs (all opt-in, non-breaking): `TINA4_WS_ALLOWED_ORIGINS` (comma-separated origin allow-list enforced on upgrade — empty/unset = allow all), `TINA4_WS_IDLE_TIMEOUT` (seconds; 0/unset disables the idle-connection reaper), `TINA4_WS_MAX_BACKLOG` (bytes; a slow client whose socket write backlog exceeds this is dropped rather than buffered without bound). Rooms API: `wss.joinRoom(clientId, room)`, `wss.leaveRoom(clientId, room)`, `wss.broadcastToRoom(room, msg, excludeIds?)`, `wss.getRoomConnections(room)`, `wss.roomCount(room)`, `wss.getClientRooms(clientId)`. `originAllowed(headers)` is exported for upgrade-path checks.
+- `websocket.ts` — WebSocket support with backplane for scaling via Redis/NATS pub/sub (`TINA4_WS_BACKPLANE`, `TINA4_WS_BACKPLANE_URL`). The backplane is wired for real: `broadcast`/`broadcastToRoom`/`sendTo` deliver to LOCAL connections first (resiliently — a dead/slow client is pruned, never aborting the loop) then publish an envelope `{src,kind,exclude,room,path,text|b64}` to the shared channel `tina4:ws` (identical wire shape across all 4 frameworks). The subscribe callback relays directly on the event loop with an origin guard (drop our own `src` echo — no double-delivery) and never re-publishes (no cluster loop); binary messages ride as base64. Security/ops knobs (all opt-in, non-breaking): `TINA4_WS_ALLOWED_ORIGINS` (comma-separated origin allow-list enforced on upgrade — empty/unset = allow all), `TINA4_WS_IDLE_TIMEOUT` (seconds; 0/unset disables the idle-connection reaper), `TINA4_WS_MAX_BACKLOG` (bytes; a slow client whose socket write backlog exceeds this is dropped rather than buffered without bound). Rooms API: `wss.joinRoom(clientId, room)`, `wss.leaveRoom(clientId, room)`, `wss.broadcastToRoom(room, msg, excludeIds?)`, `wss.getRoomConnections(room)`, `wss.roomCount(room)`, `wss.getClientRooms(clientId)`. `originAllowed(headers)` is exported for upgrade-path checks. **Per-route auth (v3.13.39, Python master b5976d4):** a WS route is PUBLIC by default (mirrors GET). Mark it secured imperatively — `Router.websocket(path, fn, { secured: true })` / chain `.secure()` on the returned `WsRouteRef` / `WebSocketServer.route(path, fn, { secured: true })` — OR decorator-style via a `_secured` flag on the handler (works in either declaration order). A secured route enforces a valid JWT on the upgrade, AFTER the origin allow-list and BEFORE accept: missing/invalid → reject with HTTP 401 (never accept); public routes always pass (non-breaking). Three token transports (`wsToken(headers, query, subprotocol)`): (1) `Authorization: Bearer <jwt>` header (server/CLI/mobile); (2) the `Sec-WebSocket-Protocol` subprotocol `"bearer, <jwt>"` (browsers — `new WebSocket()` can't set headers; the server echoes `bearer` back as the accepted subprotocol); (3) `?token=<jwt>` query param. Validated via the same `validToken` (Auth) the HTTP routes use. The verified payload is exposed as `connection.auth` (`null` on public routes). `wsAuthorized(route, headers, query, subprotocol) -> [payload, ok]` is the gate. **The integrated server (`server.ts`) now dispatches user WS routes:** its `upgrade` handler routes a non-`/__dev_reload` upgrade through `serveWebSocketRoute(req, socket, head)`, which matches the WS route table, enforces per-route auth, then drives the real open/message/close lifecycle on the connection (`wsRouteManager`) — parity with Python/PHP/Ruby (previously only `/__dev_reload` was wired, so user WS routes never reached a live connection).
 - `queue.ts` — Queue system with pluggable backends
 - `graphql.ts` — GraphQL engine. **Hardening:** selection-set nesting is bounded by `TINA4_GRAPHQL_MAX_DEPTH` (default `50`; `<= 0` disables; exposed as the public `gql.maxDepth` field + `graphqlMaxDepth()` helper). Depth increments on every recursive entry — sub-selections, fragment spreads, AND inline fragments — so an over-deep query or a circular fragment fails with `Query exceeds maximum depth of N` instead of overflowing the stack (top-level starts at depth 1). A resolver exception is logged via `Log.error` and the detail is surfaced to the client **only** under `TINA4_DEBUG` (`isDebugMode()`); otherwise it returns a generic `Internal server error` (path preserved) so internal state never leaks.
 - `i18n.ts` — Internationalization / localization
-- `logger.ts` — Structured logging
+- `logger.ts` — Structured logging. Five first-class severity levels: `debug`(0) < `info`(1) < `warning`(2) < `error`(3) < `critical`(4). `critical` is the HIGHEST level, NOT a relabelled `error`, and renders magenta. `Log.critical()` ALWAYS emits like every other level — subject only to `TINA4_LOG_LEVEL` (which it always clears) and teed to the log file whenever a file is being written. There is NO enable toggle: the old `TINA4_LOG_CRITICAL` opt-in was retired in v3.13.39 (the env var is no longer read), so a critical log is never a silent no-op. `Log.isEnabled("critical")` is ordinary threshold logic (`4 >= configured min`). **Dev/prod-aware default file output (v3.13.39, Python master 4c6d881):** stdout is ALWAYS on. When `TINA4_LOG_OUTPUT` is unset (default), the log FILE (`logs/tina4.log`) is written ONLY in development (`TINA4_DEBUG` truthy); in production / containers (`TINA4_DEBUG` falsy) the logger is stdout-only — no file to bloat the writable layer / disk (12-factor: logs on stdout for the platform to capture). Explicit `TINA4_LOG_OUTPUT=file`/`both`, OR an explicit `TINA4_LOG_FILE` path, always forces a file (explicit wins). `readEnv()` resolves all of this into a single `fileEnabled` flag that gates the file writer. Full parity with Python master.
 - `rateLimiter.ts` — Rate limiting middleware
 - `dotenv.ts` — `.env` file loading
 - `health.ts` — Health check endpoint
@@ -234,6 +238,30 @@ db.getError(): string | null
 db.cacheStats(): { enabled, size, ttl }
 ```
 
+### DocStore — pymongo-style document store (zero-config SQLite fallback)
+
+`getCollection(name)` (from `@tina4/orm`) returns a Mongo-style collection. When a Mongo URI is configured it is a real Mongo collection (resolved lazily, returns a Promise); otherwise it is a `SqliteCollection` backed by a local SQLite file (`node:sqlite`, JSON1) and is synchronous. The call sites are identical either way — only the backend differs — so you develop against a zero-dependency local store and switch to MongoDB in production by setting one env var. Because `node:sqlite` is synchronous, `getCollection` is sync in the serverless path and returns a Promise only on the real-Mongo path.
+
+```typescript
+import { getCollection, isServerless, ObjectId } from "@tina4/orm";
+
+const orders = getCollection("orders") as any; // SqliteCollection in serverless mode
+const res = orders.insertOne({ customer_id: 1, total: 9.99, status: "new" });
+orders.findOne({ _id: res.insertedId });
+orders.updateOne({ _id: res.insertedId }, { $set: { status: "shipped" } });
+for (const doc of orders.find({ total: { $gt: 5 } }).sort("total", -1).limit(10)) {
+  // ...
+}
+orders.countDocuments({ status: "shipped" });
+isServerless();   // true when running on the SQLite fallback
+```
+
+Filter operators: equality, `$in`, `$nin`, `$gt`, `$gte`, `$lt`, `$lte`, `$ne`, `$exists`, `$regex`, implicit AND, `$or`, `$and`, and dotted nested keys (`addr.city`). Updates: `$set`, `$unset`, `$inc`, replace, upsert. Cursors: `sort`, `limit`, `skip`, projection. Values round-trip (Date to/from ISO-8601, `ObjectId` to/from 24-hex) and stay queryable via `json_extract`. Non-goals: aggregation pipelines, `$elemMatch`, geo queries.
+
+Selection and configuration:
+- `TINA4_MONGO_URI` — app-wide Mongo URI. Falls back to `TINA4_SESSION_MONGO_URI`, then the legacy `TINA4_SESSION_MONGO_URL`. When one is set, `getCollection` returns a real Mongo collection.
+- `TINA4_DOC_STORE_PATH` — SQLite file for the fallback store (default `data/tina4_docstore.db`).
+
 ### Request extras
 
 ```typescript
@@ -258,12 +286,20 @@ queue.consume(topic?, id?, pollInterval=1000): AsyncGenerator<QueueJob>
 ```
 
 ### @tina4/swagger (`packages/swagger/`)
-Auto-generates OpenAPI 3.0 docs.
+Auto-generates OpenAPI 3.0.3 docs.
 
 **Key files:**
 - `generator.ts` — Produces OpenAPI spec from route table + model definitions
 - `ui.ts` — Serves Swagger UI HTML (CDN-based) at `/swagger` and spec at `/swagger/openapi.json`
 
+**3.13.40 spec behaviour:** ORM models become reusable `components.schemas` entries referenced by `$ref` (no more inlined duplicate shapes); a secured route emits a `bearerAuth` security requirement; the spec is OpenAPI 3.0.3.
+
+**Environment (read by `generator.ts` / `ui.ts`):**
+- `TINA4_SWAGGER_ENABLED` - turns the `/swagger` UI + `/swagger/openapi.json` endpoints on/off (`ui.ts`). Explicit `true`/`false` wins; unset falls back to `TINA4_DEBUG`. Set `false` to DISABLE swagger in ANY environment (including dev); set `true` to expose it in production. This is the documented production on/off switch (wired for real in 3.13.40 - previously ignored). **This is how you disable swagger.**
+- `TINA4_SWAGGER_SERVERS` - comma-separated list of server URLs for the OpenAPI `servers[]` block (multi-server / multi-environment). Falls back to `SWAGGER_DEV_URL`, else the framework default.
+- `TINA4_SWAGGER_UI_CDN` - base URL for the Swagger UI assets (`swagger-ui.css` + `swagger-ui-bundle.js`). Defaults to the public CDN (`https://unpkg.com/swagger-ui-dist@5`); point it at a self-hosted mirror for air-gapped deployments.
+- Info block: `TINA4_SWAGGER_TITLE`, `TINA4_SWAGGER_VERSION`, `TINA4_SWAGGER_DESCRIPTION`, `TINA4_SWAGGER_CONTACT_EMAIL`, `TINA4_SWAGGER_CONTACT_TEAM`, `TINA4_SWAGGER_CONTACT_URL`, `TINA4_SWAGGER_LICENSE`.
+
 ### @tina4/frond (`packages/frond/`)
 Built-in zero-dependency Twig-compatible template engine (the only template engine; there is no `twig` npm dependency).
 
@@ -775,6 +811,8 @@ const adults = User.query().where("age > ?", [18]).orderBy("name").get();
 
 SQL-file based migrations under `migrations/`. The framework runs pending migrations on startup; the helpers here are for programmatic control (CLI, scripts, tests).
 
+**Auto-run on startup (`TINA4_AUTO_MIGRATE`, default on).** `startServer()` calls `autoMigrateOnStartup()` (in `server.ts`) AFTER `initDatabase()`/model sync and BEFORE the server listens. When a `migrations/` folder with at least one `.sql` file exists, `TINA4_AUTO_MIGRATE` is not falsy (default `"true"`; `false`/`0`/`no`/`off` disable), and a DB adapter is resolvable, it runs the existing `migrate()` runner so the schema is current with no manual `tina4 migrate` step. It is **non-breaking**: a failure is logged via `Log.error` and the service still starts (a bad migration must never take the backend down). The runner is wrapped in try/catch and `autoMigrateOnStartup()` never rejects/throws out of the boot path. Set `TINA4_AUTO_MIGRATE=false` to disable (e.g. multi-instance production that migrates as a separate deploy step — concurrent first-apply can race). The explicit `tina4 migrate` CLI (`packages/cli/src/commands/migrate.ts`) is unaffected and stays **fail-fast** (`process.exit(1)` on a statement error) so CI keeps the non-zero exit code.
+
 ```typescript
 import {
   migrate, rollback, status, createMigration, syncModels,
@@ -788,7 +826,16 @@ await createMigration("add users table");   // scaffolds migrations/<ts>_add_use
 syncModels(discoveredModels);               // auto-create tables / add columns from `static fields`
 ```
 
-Migration tracking lives in `tina4_migration` (id, name, batch, applied_at). Schema sync runs alongside SQL migrations on boot.
+### How migrations work internally
+
+- SQL files live in `migrations/`, named `NNNNNN_description.sql` (sequential) or `YYYYMMDDHHMMSS_description.sql` (timestamp), and are split on the `;` delimiter.
+- Files are applied in **numeric-prefix order** (`9_` before `10_` — a plain lexical sort misorders unpadded prefixes because `"10" < "9"`). A file with no numeric/timestamp prefix sorts **after** the numbered ones (lexically) and logs a `Log.warning` — its order is undefined.
+- State is tracked by **row existence** in `tina4_migration` (id, name, batch, applied_at), auto-created per engine: a migration runs once — if a row with its `name` exists it is skipped. A FAILED migration is **never** recorded (no row is written, nothing is deleted) — fix the bad file and re-run; the `migrate()` summary's `failed[]` carries the failure.
+- **Each migration FILE is wrapped in its own transaction.** On a failure the file rolls back and `migrate()` **STOPS** — later files are never applied on top of a missing earlier one (parity with Python/PHP/Ruby). Already-applied files stay applied. The explicit `tina4 migrate` CLI surfaces a non-empty `failed[]` as a non-zero exit; startup auto-migration logs it and the service still boots (see `TINA4_AUTO_MIGRATE` above).
+- **Atomicity caveat:** per-file transactions are truly atomic only on engines with **transactional DDL (PostgreSQL)**. MySQL, Firebird, and SQLite auto-commit DDL, so a multi-statement migration that fails midway on those engines leaves earlier statements applied — keep one logical change per file. `CREATE TABLE` and `ALTER TABLE ... ADD` are made idempotent on Firebird/MSSQL (existence-checked via `RDB$RELATION_FIELDS` / `tableExists`) so a re-run with a raw `CREATE`/`ADD` does not error "object already exists"; SQLite/MySQL/PostgreSQL support `IF NOT EXISTS` and are left to the engine. Only a genuine already-exists is skipped — every other error still raises.
+- The stored-proc block delimiters (`$$ … $$` / `// … //`) are extracted before splitting, but a `//` preceded by a colon is **not** treated as a delimiter, so a URL (`https://…`) or any `://` literal inside a migration is never swallowed as an opaque block.
+
+Schema sync (`syncModels`) runs alongside SQL migrations on boot.
 
 ## Module: Frond (`packages/frond/src/engine.ts`)
 
@@ -821,6 +868,8 @@ frond.unsandbox();
 
 Zero-dep HTTP client over `node:http` / `node:https`. Used by integrations, queue producers, health checks, and tests.
 
+**Retry/backoff (opt-in, default off):** pass `maxRetries` (default `0`) and `retryBackoff` (default `0.5`s base, exponential) in the options bag — `new Api(url, { bearerToken, maxRetries: 3, retryBackoff: 0.5 })`. Retries a transport error (`http_code` null) or a retryable status (429/500/502/503/504); 4xx is never retried (a retried non-idempotent request may be re-sent, so retries are opt-in). Node's `node:http`/`node:https` doesn't auto-follow redirects, so there's no cross-host Authorization-leak surface (the redirect auth-strip is Python-only).
+
 ```typescript
 import { Api } from "@tina4/core";
 

package/README.md

@@ -17,7 +17,7 @@
 ## Quick Start
 
 ```bash
-# With the Tina4 CLI (recommended — enables SCSS + live reload)
+# With the Tina4 CLI (recommended, enables SCSS + live reload)
 cargo install tina4    # or grab a binary from https://github.com/tina4stack/tina4/releases
 tina4 init nodejs ./my-app
 cd my-app && tina4 serve
@@ -57,12 +57,12 @@ export default class User {
 | Category | Features |
 |----------|----------|
 | **Core HTTP** (7) | Router with path params (`{id:int}`, `{p:path}`), Server, Request/Response, Middleware pipeline, Static file serving, CORS |
-| **Database** (6) | SQLite, PostgreSQL, MySQL, MSSQL, Firebird — unified adapter, connection pooling, query cache, transactions, race-safe ID generation, SQL dialect translation |
+| **Database** (6) | SQLite, PostgreSQL, MySQL, MSSQL, Firebird: unified adapter, connection pooling, query cache, transactions, race-safe ID generation, SQL dialect translation |
 | **ORM** (7) | Active Record with typed fields, relationships (`has_one`/`has_many`/`belongs_to`), soft delete, QueryBuilder + MongoDB support, Auto-CRUD generator, migrations with rollback |
 | **Auth & Security** (5) | JWT (HS256/RS256), password hashing (PBKDF2-SHA256), API key validation, rate limiting, CSRF form tokens |
 | **Templating** (3) | Frond engine (Twig/Jinja2-compatible, pre-compiled 2.8× faster), SCSS auto-compilation, built-in CSS (~24 KB) |
 | **API & Integration** (5) | HTTP client (zero-dep), GraphQL with ORM auto-schema + GraphiQL IDE, WSDL/SOAP with auto WSDL, WebSocket (RFC 6455) + Redis backplane, MCP server (24 dev tools) |
-| **Background** (3) | Job queue (File/RabbitMQ/Kafka/MongoDB) with priority, delay, retry, dead letters — service runner — event system (on/emit/once/off) |
+| **Background** (3) | Job queue (File/RabbitMQ/Kafka/MongoDB) with priority, delay, retry, dead letters; service runner; event system (on/emit/once/off) |
 | **Data & Storage** (4) | Session (File/Redis/Valkey/MongoDB/DB), response cache (LRU, TTL), seeder + 50+ fake data generators, messenger (SMTP/IMAP) |
 | **Developer Tools** (7) | Dev dashboard (11 tabs), dev toolbar, error overlay (Catppuccin Mocha), dev mailbox, hot reload + CSS hot-reload, code metrics (complexity, coupling, maintainability), AI context installer (7 tools) |
 | **Utilities** (7) | DI container (transient + singleton), HtmlElement builder, inline testing (`@tests` decorator), i18n (6 languages), Swagger/OpenAPI auto-generation, CLI scaffolding (`generate model/route/migration/middleware`), structured logging |
@@ -86,14 +86,14 @@ npx tina4nodejs generate model <name>
 
 ## Performance
 
-Benchmarked with `wrk` — 5,000 requests, 50 concurrent, median of 3 runs:
+Benchmarked with `wrk`: 5,000 requests, 50 concurrent, median of 3 runs:
 
 | Framework | JSON req/s | Deps | Features |
 |-----------|-----------|------|----------|
 | Raw `node:http` | 91,110 | 0 | 1 |
 | **Tina4 Node.js** | **84,771** | 0 | 55 |
 
-Tina4 Node.js runs at **93% of raw Node.js speed** while providing 55 built-in features — zero overhead architecture.
+Tina4 Node.js runs at **93% of raw Node.js speed** while providing 55 built-in features, a zero-overhead architecture.
 
 **Across all 4 Tina4 implementations:**
 
@@ -107,7 +107,7 @@ Tina4 Node.js runs at **93% of raw Node.js speed** while providing 55 built-in f
 
 ## Cross-Framework Parity
 
-Tina4 ships identical features across four languages — same architecture, same conventions, same 55 features:
+Tina4 ships identical features across four languages: same architecture, same conventions, same 55 features:
 
 | | Python | PHP | Ruby | Node.js |
 |---|--------|-----|------|---------|

package/package.json

@@ -3,7 +3,7 @@
 
 
 
-  "version": "3.13.38",
+  "version": "3.13.40",
 
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript \u2014 54 built-in features, zero dependencies",

package/packages/core/src/api.ts

@@ -18,6 +18,13 @@ export interface ApiResult {
     error: string | null;
 }
 
+/**
+ * HTTP statuses that warrant an automatic retry when `maxRetries` > 0:
+ * rate-limit (429) plus the transient server-side 5xx family. 4xx client
+ * errors (401, 404, …) are NOT retried — a repeat won't succeed.
+ */
+const RETRY_STATUSES: ReadonlySet<number> = new Set([429, 500, 502, 503, 504]);
+
 /**
  * Constructor options for {@link Api}. Used as the second argument to
  * `new Api(url, { ... })` — cross-framework parity with Python
@@ -33,6 +40,16 @@ export interface ApiOptions {
     username?: string;
     password?: string;
     headers?: Record<string, string>;
+    /**
+     * Maximum automatic retries on a transient failure (default 0 = off, so
+     * existing callers are unaffected). When > 0, a transport error or a
+     * retryable status (429/5xx) is retried up to this many times with
+     * exponential backoff. NOTE: a retried non-idempotent request (POST/…)
+     * may be re-sent — retries are opt-in for that reason.
+     */
+    maxRetries?: number;
+    /** Base backoff in seconds, doubling each attempt (default 0.5). */
+    retryBackoff?: number;
 }
 
 export class Api {
@@ -41,6 +58,8 @@ export class Api {
     private timeout: number;
     private authHeader: string;
     private ignoreSsl: boolean;
+    private maxRetries: number;
+    private retryBackoff: number;
 
     /**
      * Construct an Api client.
@@ -60,6 +79,14 @@ export class Api {
      * Bearer wins over basic-auth when both passed. `verifySsl: false` is
      * the positive form of `ignoreSsl: true`; `ignoreSsl` wins when both
      * supplied for backward compatibility.
+     *
+     * `maxRetries` (default 0 = off) enables automatic retry with
+     * exponential backoff (`retryBackoff` seconds base, doubling each
+     * attempt) on a transport error or a retryable status (429/5xx). A
+     * retried non-idempotent request (POST/…) may be re-sent — retries are
+     * opt-in for that reason.
+     *
+     *     new Api("https://api.example.com", { maxRetries: 3, retryBackoff: 0.5 });
      */
     constructor(
         baseUrl: string = "",
@@ -68,6 +95,9 @@ export class Api {
     ) {
         this.baseUrl = baseUrl.replace(/\/+$/, "");
         this.headers = {};
+        // Retry defaults: off (0) so existing callers are unaffected.
+        this.maxRetries = 0;
+        this.retryBackoff = 0.5;
 
         // Options-bag form — second arg is an object literal
         if (typeof authHeaderOrOptions === "object" && authHeaderOrOptions !== null) {
@@ -75,6 +105,8 @@ export class Api {
             this.authHeader = opts.authHeader ?? "";
             this.timeout = opts.timeout ?? timeout;
             this.ignoreSsl = (opts.ignoreSsl ?? false) || (opts.verifySsl === false);
+            this.maxRetries = Math.max(0, opts.maxRetries ?? 0);
+            this.retryBackoff = opts.retryBackoff ?? 0.5;
 
             // Bearer wins over basic-auth when both are passed
             if (opts.bearerToken != null) {
@@ -189,7 +221,38 @@ export class Api {
         return `${this.baseUrl}/${path.replace(/^\/+/, "")}`;
     }
 
-    private execute(
+    /**
+     * Execute the request with opt-in retry/backoff.
+     *
+     * With `maxRetries` > 0, a transport failure (`http_code` null) or a
+     * retryable status (429/5xx) is retried up to `maxRetries` times with
+     * exponential backoff; any other outcome (2xx, 3xx, other 4xx) returns
+     * at once. A retried non-idempotent request may be re-sent — retries
+     * are opt-in for that reason.
+     */
+    private async execute(
+        method: string,
+        url: string,
+        body?: unknown,
+        contentType: string = "application/json",
+    ): Promise<ApiResult> {
+        const attempts = this.maxRetries + 1;
+        let result: ApiResult = { http_code: null, body: null, headers: {}, error: null };
+        for (let attempt = 0; attempt < attempts; attempt++) {
+            result = await this.attempt(method, url, body, contentType);
+            const code = result.http_code;
+            const retryable = code === null || RETRY_STATUSES.has(code);
+            if (!retryable || attempt === attempts - 1) {
+                return result;
+            }
+            const delayMs = this.retryBackoff * Math.pow(2, attempt) * 1000;
+            await new Promise<void>((r) => setTimeout(r, delayMs));
+        }
+        return result;
+    }
+
+    /** A single HTTP attempt — returns the standardized result. */
+    private attempt(
         method: string,
         url: string,
         body?: unknown,

package/packages/core/src/auth.ts

@@ -29,7 +29,10 @@ import { isTruthy } from "./dotenv.js";
 /** Actionable blank-secret warning — emitted from both the bootstrap (CI/prod) and the lazy resolvers. */
 const BLANK_SECRET_WARNING =
   "Auth: TINA4_SECRET is not set — JWT signing is insecure. Set TINA4_SECRET to a random " +
-  "value (e.g. `openssl rand -hex 32`) in your environment or .env before serving traffic.";
+  "value (e.g. `openssl rand -hex 32`) in your environment or .env before serving traffic. " +
+  "For LOCAL DEV, set TINA4_DEBUG=true and a per-machine secret is generated automatically " +
+  "into .env.local (gitignored). Seeing this warning means the run was NOT detected as dev — " +
+  "typically a container or CI without TINA4_DEBUG set, or TINA4_ENV=production.";
 
 /** True when running under CI — the de-facto `CI` env var (set by every major CI). */
 function _isCi(): boolean {

package/packages/core/src/devAdmin.ts

@@ -14,12 +14,13 @@ import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync, copyFi
 import { join, dirname, resolve, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { Router } from "./router.js";
-import type { RouteHandler } from "./types.js";
+import type { RouteHandler, Tina4Request } from "./types.js";
 import { DevMailbox } from "./devMailbox.js";
 import { isTruthy } from "./dotenv.js";
 import { quickMetrics, fullAnalysis, fileDetail } from "./metrics.js";
 import { registerFeedbackRoutes } from "./feedback.js";
-import { getDefaultDevServer } from "./mcp.js";
+import { getDefaultDevServer, mcpEnabled, isRequestAllowed } from "./mcp.js";
+import { timingSafeEqual } from "node:crypto";
 
 const cpuCount = osCpus().length;
 
@@ -561,18 +562,6 @@ export class DevAdmin {
       { method: "POST", pattern: "/__dev/api/deps/install", handler: handleDepsInstall },
       // Git status
       { method: "GET", pattern: "/__dev/api/git/status", handler: handleGitStatus },
-      // MCP tool introspection over the built-in MCP server (browser dev-admin REST shim)
-      { method: "GET", pattern: "/__dev/api/mcp/tools", handler: handleMcpTools },
-      { method: "POST", pattern: "/__dev/api/mcp/call", handler: handleMcpCall },
-      // MCP JSON-RPC + SSE endpoints that REAL MCP clients (Claude Code/Desktop)
-      // speak. POST /__dev/mcp[/message] -> JSON-RPC handleMessage; GET
-      // /__dev/mcp/sse -> SSE handshake announcing the message endpoint. Mounted
-      // through the same dispatch as the REST shim above and gated by the same
-      // /__dev public-route rule. Mirrors the Python v3 fix (POST /__dev/mcp +
-      // /__dev/mcp/message, GET /__dev/mcp/sse).
-      { method: "POST", pattern: "/__dev/mcp", handler: handleMcpMessage },
-      { method: "POST", pattern: "/__dev/mcp/message", handler: handleMcpMessage },
-      { method: "GET", pattern: "/__dev/mcp/sse", handler: handleMcpSse },
       // Scaffolding
       { method: "GET", pattern: "/__dev/api/scaffold", handler: handleScaffoldList },
       { method: "POST", pattern: "/__dev/api/scaffold/run", handler: handleScaffoldRun },
@@ -610,12 +599,41 @@ export class DevAdmin {
       });
     }
 
-    // Ensure the default /__dev/mcp MCP server exists with its dev tools
-    // registered. This is the single shared instance behind both the REST shim
-    // and the JSON-RPC + SSE endpoints registered above. Doing it here (gated by
-    // the same TINA4_DEBUG check that gates DevAdmin.register) means tools/list
-    // and the REST shim return tools immediately, before any first call.
-    getDefaultDevServer();
+    // MCP exposure is gated SEPARATELY from the rest of the dev dashboard.
+    // The MCP dev tools expose powerful operations (DB query, file read/WRITE,
+    // route listing), so they must NOT auto-expose on a non-localhost
+    // TINA4_DEBUG=true deployment. mcpEnabled() honours an explicit TINA4_MCP on
+    // any host, else requires TINA4_DEBUG AND (localhost OR TINA4_MCP_REMOTE) —
+    // full parity with Python master tina4_python.mcp.is_enabled(). When the
+    // gate is closed, neither the REST shim, the JSON-RPC/SSE endpoints, nor the
+    // default dev MCP server (with its dev tools) are registered.
+    if (mcpEnabled()) {
+      const mcpRoutes: Array<{ method: string; pattern: string; handler: RouteHandler }> = [
+        // MCP tool introspection over the built-in MCP server (browser dev-admin REST shim)
+        { method: "GET", pattern: "/__dev/api/mcp/tools", handler: handleMcpTools },
+        { method: "POST", pattern: "/__dev/api/mcp/call", handler: handleMcpCall },
+        // MCP JSON-RPC + SSE endpoints that REAL MCP clients (Claude Code/Desktop)
+        // speak. POST /__dev/mcp[/message] -> JSON-RPC handleMessage; GET
+        // /__dev/mcp/sse -> SSE handshake announcing the message endpoint. Mirrors
+        // the Python v3 fix (POST /__dev/mcp + /__dev/mcp/message, GET /__dev/mcp/sse).
+        { method: "POST", pattern: "/__dev/mcp", handler: handleMcpMessage },
+        { method: "POST", pattern: "/__dev/mcp/message", handler: handleMcpMessage },
+        { method: "GET", pattern: "/__dev/mcp/sse", handler: handleMcpSse },
+      ];
+      for (const route of mcpRoutes) {
+        router.addRoute({
+          method: route.method,
+          pattern: route.pattern,
+          handler: route.handler,
+        });
+      }
+
+      // Ensure the default /__dev/mcp MCP server exists with its dev tools
+      // registered. This is the single shared instance behind both the REST shim
+      // and the JSON-RPC + SSE endpoints registered above, so tools/list and the
+      // REST shim return tools immediately, before any first call.
+      getDefaultDevServer();
+    }
   }
 
   /**
@@ -2134,7 +2152,47 @@ const handleGitStatus: RouteHandler = async (_req, res) => {
   }
 };
 
-const handleMcpTools: RouteHandler = async (_req, res) => {
+/** Constant-time string compare (length-guarded so timingSafeEqual never throws). */
+function mcpSecureEqual(expected: string, provided: string): boolean {
+  const a = Buffer.from(expected);
+  const b = Buffer.from(provided);
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}
+
+/**
+ * Whether the request carried a token matching TINA4_MCP_TOKEN (fallback
+ * TINA4_API_KEY). Transports: Authorization Bearer / X-MCP-Token / X-Api-Key.
+ * No configured token ⇒ a remote caller can never present a valid one.
+ */
+function mcpTokenOk(req: Tina4Request): boolean {
+  let expected = process.env.TINA4_MCP_TOKEN;
+  if (!expected) expected = process.env.TINA4_API_KEY;
+  if (!expected) return false;
+  let provided = "";
+  const auth = req.header("authorization") ?? "";
+  if (auth.toLowerCase().startsWith("bearer ")) provided = auth.slice(7).trim();
+  if (!provided) provided = req.header("x-mcp-token") ?? "";
+  if (!provided) provided = req.header("x-api-key") ?? "";
+  if (!provided) return false;
+  return mcpSecureEqual(expected, provided);
+}
+
+/**
+ * Per-request MCP authorisation using the RAW socket peer (never X-Forwarded-For,
+ * which is spoofable). Loopback is always allowed; a remote caller needs
+ * TINA4_MCP_REMOTE=true plus a valid token. Mirrors the Python/PHP/Ruby gate.
+ */
+function mcpRequestAllowed(req: Tina4Request): boolean {
+  const peer = (req as unknown as { socket?: { remoteAddress?: string } }).socket?.remoteAddress ?? "";
+  return isRequestAllowed(peer, mcpTokenOk(req));
+}
+
+const handleMcpTools: RouteHandler = async (req, res) => {
+  if (!mcpRequestAllowed(req)) {
+    res.json({ tools: [], error: "MCP forbidden" }, 404);
+    return;
+  }
   try {
     // Ensure the default /__dev/mcp server exists with its dev tools registered,
     // then enumerate every registered MCP server instance (app-defined servers
@@ -2155,6 +2213,10 @@ const handleMcpTools: RouteHandler = async (_req, res) => {
 };
 
 const handleMcpCall: RouteHandler = async (req, res) => {
+  if (!mcpRequestAllowed(req)) {
+    res.json({ error: "MCP forbidden" }, 404);
+    return;
+  }
   const body = (req.body as Record<string, unknown>) || {};
   const name = (body.name as string) || "";
   const args = (body.arguments as Record<string, unknown>) || {};
@@ -2186,6 +2248,10 @@ const handleMcpCall: RouteHandler = async (req, res) => {
  * clients connect without a token.
  */
 const handleMcpMessage: RouteHandler = async (req, res) => {
+  if (!mcpRequestAllowed(req)) {
+    res.json({ error: "MCP forbidden" }, 404);
+    return;
+  }
   try {
     const { getDefaultDevServer } = await import("./mcp.js");
     const server = getDefaultDevServer();
@@ -2216,6 +2282,10 @@ const handleMcpMessage: RouteHandler = async (req, res) => {
  * the Python v3 fix. Content-Type text/event-stream, status 200.
  */
 const handleMcpSse: RouteHandler = async (req, res) => {
+  if (!mcpRequestAllowed(req)) {
+    res.json({ error: "MCP forbidden" }, 404);
+    return;
+  }
   // req.path is the path only (no query); turn /__dev/mcp/sse into the message
   // endpoint /__dev/mcp/message that the client should POST to.
   const reqPath = req.path || "/__dev/mcp/sse";

package/packages/core/src/index.ts

@@ -15,7 +15,7 @@ export type {
 
 export { startServer, resolvePortAndHost, handle, start, stop, httpReason, resolveTemplate, resetTemplateCache, templateAutoRoutingEnabled, isBannerSuppressed } from "./server.js";
 export { background, stopAllBackgroundTasks, backgroundTaskCount } from "./background.js";
-export { Router, RouteGroup, RouteRef, defaultRouter, runRouteMiddlewares, resolveStringMiddleware, isTrailingSlashRedirectEnabled } from "./router.js";
+export { Router, RouteGroup, RouteRef, WsRouteRef, defaultRouter, runRouteMiddlewares, resolveStringMiddleware, isTrailingSlashRedirectEnabled } from "./router.js";
 export { get, post, put, patch, del, any, websocket, del as delete } from "./router.js";
 export type { RouteInfo } from "./router.js";
 export { discoverRoutes } from "./routeDiscovery.js";
@@ -64,6 +64,7 @@ export {
   WebSocketServer,
   devReloadWs,
   computeAcceptKey, parseUpgradeHeaders, buildFrame, parseFrame, originAllowed,
+  wsToken, wsAuthorized, offeredBearerSubprotocol, serveWebSocketRoute, wsRouteManager,
   OP_TEXT, OP_BINARY, OP_CLOSE, OP_PING, OP_PONG,
   CLOSE_NORMAL, CLOSE_GOING_AWAY, CLOSE_PROTOCOL_ERROR, CLOSE_POLICY_VIOLATION,
 } from "./websocket.js";
@@ -100,8 +101,12 @@ export type { ImapMessage, ImapFullMessage } from "./messenger.js";
 export { LiteBackend } from "./queueBackends/liteBackend.js";
 export { RabbitMQBackend, parseAmqpUrl } from "./queueBackends/rabbitmqBackend.js";
 export type { RabbitMQConfig } from "./queueBackends/rabbitmqBackend.js";
-export { KafkaBackend } from "./queueBackends/kafkaBackend.js";
-export type { KafkaConfig } from "./queueBackends/kafkaBackend.js";
+export { KafkaBackend, kafkaSecurityConfig } from "./queueBackends/kafkaBackend.js";
+export type {
+  KafkaConfig,
+  KafkaSecurityConfig,
+  KafkaClientConfig,
+} from "./queueBackends/kafkaBackend.js";
 export { MongoBackend } from "./queueBackends/mongoBackend.js";
 export type { MongoConfig as MongoQueueConfig } from "./queueBackends/mongoBackend.js";
 export { DatabaseSessionHandler } from "./sessionHandlers/databaseHandler.js";
@@ -130,7 +135,7 @@ export type {
 export {
   McpServer, mcpTool, mcpResource, registerDevTools, getDefaultDevServer,
   encodeResponse, encodeError, encodeNotification, decodeRequest,
-  schemaFromParams, isLocalhost, mcpEnabled, mcpPort,
+  schemaFromParams, isLocalhost, isLoopback, mcpEnabled, isRequestAllowed, mcpPort,
   PARSE_ERROR, INVALID_REQUEST, METHOD_NOT_FOUND, INVALID_PARAMS, INTERNAL_ERROR,
 } from "./mcp.js";
 export type { JsonRpcMessage, McpToolDefinition, McpResourceDefinition, JsonSchema, McpToolParam } from "./mcp.js";