tina4-nodejs 3.13.39 → 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,6 +117,10 @@ 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)
@@ -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).
 

package/package.json

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

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, mcpEnabled } from "./mcp.js";
+import { getDefaultDevServer, mcpEnabled, isRequestAllowed } from "./mcp.js";
+import { timingSafeEqual } from "node:crypto";
 
 const cpuCount = osCpus().length;
 
@@ -2151,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
@@ -2172,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>) || {};
@@ -2203,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();
@@ -2233,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

@@ -135,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";

package/packages/core/src/mcp.ts

@@ -187,6 +187,14 @@ export function schemaFromParams(params: McpToolParam[]): JsonSchema {
 
 // ── Localhost detection ──────────────────────────────────────
 
+/**
+ * Informational only — whether the CONFIGURED host looks local.
+ *
+ * NOT the security gate. Reads `TINA4_HOST_NAME` (the configured bind address),
+ * which on a 0.0.0.0 bind looks "local" while still accepting remote clients.
+ * Trust decisions use {@link isRequestAllowed} with the RAW socket peer instead.
+ * Kept for diagnostics / back-compat.
+ */
 export function isLocalhost(): boolean {
   const hostEnv = process.env.TINA4_HOST_NAME || "localhost:7148";
   const host = hostEnv.split(":")[0];
@@ -202,35 +210,61 @@ function envTruthy(val: string | undefined): boolean {
 }
 
 /**
- * Whether the built-in MCP dev tools / `/__dev/mcp` endpoint should be enabled.
+ * Whether an address is a loopback (in-process / same-host) peer.
+ *
+ * Operates on the RAW socket peer, never X-Forwarded-For. Empty/undefined means
+ * an in-process / synthetic request (no socket) and is trusted. The `::ffff:`
+ * IPv4-mapped prefix is stripped. NOTE: 0.0.0.0 is a BIND address, never a
+ * client address, so it is deliberately NOT loopback.
+ *
+ * Python master parity: tina4_python.mcp.is_loopback.
+ */
+export function isLoopback(ip: string | undefined | null): boolean {
+  if (ip == null || ip === "") return true;
+  let addr = ip.trim().toLowerCase();
+  if (addr.startsWith("::ffff:")) addr = addr.slice(7);
+  return addr === "::1" || addr === "localhost" || addr.startsWith("127.");
+}
+
+/**
+ * Capability gate — whether MCP may run at all.
  *
- * Resolution order (highest priority first), matching Python master
- * `tina4_python.mcp.is_enabled()`:
- *   1. `TINA4_MCP` — explicit on/off override, honoured on ANY host. An
- *      explicit truthy value opts a remote / debug-disabled deployment in
- *      (e.g. for a remote AI assistant); an explicit falsy value force-disables
- *      it everywhere.
- *   2. `TINA4_DEBUG=true` — implicit on for dev, but LOCALHOST-ONLY unless
- *      `TINA4_MCP_REMOTE=true`. The MCP dev tools expose powerful operations
- *      (DB query, file read/WRITE, route listing), so they never auto-expose on
- *      a non-localhost host without an explicit opt-in.
+ * Pure capability, host-INDEPENDENT (Python master parity):
+ *   1. `TINA4_MCP` explicit on/off override (sysadmin, any host).
+ *   2. Else `TINA4_DEBUG=true` → MCP is a capability of this deployment.
  *   3. Otherwise off.
  *
- * Wired in v3.13.39: previously this was `TINA4_MCP` else `TINA4_DEBUG`, with
- * `isLocalhost()` unused for the gate and `TINA4_MCP_REMOTE` read by zero code
- * — so the documented localhost guard was not actually enforced and a
- * non-localhost `TINA4_DEBUG=true` deployment auto-exposed the dev tools.
+ * This NO LONGER consults the host. A debug box bound to 0.0.0.0 still "has"
+ * the capability, but {@link isRequestAllowed} decides whether a given CALLER
+ * may use it — loopback always, remote only with an explicit opt-in plus a
+ * valid token. Splitting capability from per-request authorisation closes the
+ * hole where a 0.0.0.0 bind auto-exposed DB/file tools to remote
+ * unauthenticated callers (the pre-3.13.40 isLocalhost() treated 0.0.0.0 local).
  */
 export function mcpEnabled(): boolean {
   const explicit = process.env.TINA4_MCP;
   if (explicit !== undefined && explicit.trim() !== "") {
     return envTruthy(explicit);
   }
-  if (!envTruthy(process.env.TINA4_DEBUG)) {
-    return false;
-  }
-  // Dev auto-enable: localhost only, unless explicitly opted into remote.
-  return isLocalhost() || envTruthy(process.env.TINA4_MCP_REMOTE);
+  return envTruthy(process.env.TINA4_DEBUG);
+}
+
+/**
+ * Per-request authorisation — whether THIS caller may use MCP.
+ *
+ * @param remoteIp        Raw socket peer (`req.socket.remoteAddress`), never XFF.
+ * @param hasValidToken   True when the request carried a token matching TINA4_MCP_TOKEN.
+ *
+ * Rules (Python master parity, tina4_python.mcp.is_request_allowed):
+ *   - Capability off ({@link mcpEnabled} false) → deny.
+ *   - Loopback peer → allow.
+ *   - Remote peer → only when TINA4_MCP_REMOTE is truthy AND a valid token was
+ *     presented. No configured token ⇒ remote can never pass.
+ */
+export function isRequestAllowed(remoteIp: string | undefined | null, hasValidToken = false): boolean {
+  if (!mcpEnabled()) return false;
+  if (isLoopback(remoteIp)) return true;
+  return envTruthy(process.env.TINA4_MCP_REMOTE) && hasValidToken;
 }
 
 /**
@@ -620,9 +654,30 @@ export function mcpResource(
  */
 function safePath(projectRoot: string, relPath: string): string {
   const resolved = path.resolve(projectRoot, relPath);
-  if (!resolved.startsWith(projectRoot)) {
+  // Compare against root + separator, not a bare prefix: a plain
+  // startsWith(projectRoot) also accepts a sibling like "<root>-evil".
+  // path.resolve collapses ".." so a climb-out lands outside root.
+  const rootPrefix = projectRoot.endsWith(path.sep) ? projectRoot : projectRoot + path.sep;
+  if (resolved !== projectRoot && !resolved.startsWith(rootPrefix)) {
     throw new Error(`Path escapes project directory: ${relPath}`);
   }
+  // Belt-and-braces against symlink escapes: if the path exists, canonicalise
+  // it and re-check containment. A symlink inside the tree pointing outside
+  // would otherwise slip past the textual check. New paths (parent not yet
+  // created) have no realpath and rely on the resolve() containment above.
+  let real: string | null = null;
+  try {
+    real = fs.realpathSync(resolved);
+  } catch {
+    real = null; // not created yet — textual guard above holds
+  }
+  if (real !== null) {
+    const realRoot = fs.realpathSync(projectRoot);
+    const realPrefix = realRoot.endsWith(path.sep) ? realRoot : realRoot + path.sep;
+    if (real !== realRoot && !real.startsWith(realPrefix)) {
+      throw new Error(`Path escapes project directory: ${relPath}`);
+    }
+  }
   return resolved;
 }
 
@@ -865,8 +920,22 @@ export function registerDevTools(server: McpServer): void {
       try {
         const db = (globalThis as any).__tina4_db;
         if (!db) return { error: "No database connection" };
-        const params = typeof args.params === "string" ? JSON.parse(args.params as string) : (args.params || []);
-        const result = await db.fetch(args.sql as string, params);
+        let params = typeof args.params === "string" ? JSON.parse(args.params as string) : (args.params || []);
+        if (!Array.isArray(params)) params = [];
+        // Defense-in-depth: this tool is read-only. Strip comments, reject
+        // multiple statements, and require a leading SELECT/WITH so it can never
+        // mutate data even if reached (database_execute is the write surface,
+        // gated separately). Mirrors the Python master.
+        const cleaned = (args.sql as string)
+          .replace(/--[^\r\n]*/g, " ")
+          .replace(/\/\*[\s\S]*?\*\//g, " ")
+          .trim()
+          .replace(/[;\s]+$/, "");
+        if (cleaned.includes(";")) return { error: "database_query rejects multiple statements" };
+        if (!/^(select|with)\b/i.test(cleaned)) {
+          return { error: "database_query is read-only (SELECT/WITH only)" };
+        }
+        const result = await db.fetch(cleaned, params);
         return { records: result.records || [], count: result.count || 0 };
       } catch (e) {
         return { error: (e as Error).message };
@@ -921,7 +990,14 @@ export function registerDevTools(server: McpServer): void {
       try {
         const db = (globalThis as any).__tina4_db;
         if (!db) return { error: "No database connection" };
-        return (await db.getColumns?.(args.table as string)) ?? [];
+        // Constrain the table name to a safe identifier (optionally
+        // schema-qualified) — defense-in-depth so it can never be abused for
+        // injection even if an adapter interpolates it. Parity with Python/PHP.
+        const table = String(args.table ?? "");
+        if (!/^[A-Za-z_][A-Za-z0-9_$]*(\.[A-Za-z_][A-Za-z0-9_$]*)?$/.test(table)) {
+          return { error: "Invalid table name" };
+        }
+        return (await db.getColumns?.(table)) ?? [];
       } catch (e) {
         return { error: (e as Error).message };
       }

package/packages/core/src/server.ts

@@ -183,8 +183,13 @@ export function _checkLegacyEnvVars(): void {
   }
   lines.push(
     "",
-    "Run `tina4 env --migrate` to rewrite your .env automatically,",
-    "or rename manually. See https://tina4.com/release/3.12.0",
+    "Note: these may come from a .env file loaded by dotenv, not just",
+    "the runtime environment — check your image / build context (a .env",
+    "baked into a Docker image is loaded at startup) as well as k8s/CI env.",
+    "",
+    "FIX: run `tina4 env --migrate` to rewrite your .env automatically",
+    "(it renames every legacy name to its TINA4_ form in place).",
+    "Or rename manually. See https://tina4.com/release/3.12.0",
     "Set TINA4_ALLOW_LEGACY_ENV=true to bypass during migration.",
     bar,
     "",

package/packages/core/src/sessionHandlers/mongoHandler.ts

@@ -66,8 +66,10 @@ export class MongoSessionHandler implements SessionHandler {
       ?? (process.env.TINA4_SESSION_MONGO_PORT
         ? parseInt(process.env.TINA4_SESSION_MONGO_PORT, 10)
         : 27017);
+    // Canonical TINA4_SESSION_MONGO_URI; TINA4_SESSION_MONGO_URL is a legacy alias.
     this.uri = config?.uri
       ?? process.env.TINA4_SESSION_MONGO_URI
+      ?? process.env.TINA4_SESSION_MONGO_URL
       ?? "";
     this.username = config?.username
       ?? process.env.TINA4_SESSION_MONGO_USERNAME

package/packages/core/src/types.ts

@@ -134,6 +134,10 @@ export interface RouteMeta {
   description?: string;
   tags?: string[];
   responses?: Record<string, { description: string }>;
+  /** Request-body example surfaced in the OpenAPI requestBody. */
+  example?: unknown;
+  /** Marks the operation deprecated in the spec. */
+  deprecated?: boolean;
 }
 
 export interface Tina4Config {