tina4-nodejs 3.13.38 → 3.13.40

package/packages/core/src/logger.ts

@@ -136,18 +136,23 @@ function resolveLogFilePath(logDir: string, logFile: string): string {
 /**
  * Structured logger for Tina4.
  *
- * Production (TINA4_DEBUG not truthy): JSON or text lines to logs/tina4.log
- * Development (TINA4_DEBUG=true): Colorized human-readable to stdout + file
+ * Development (TINA4_DEBUG=true): colorized human-readable to stdout + file.
+ * Production (TINA4_DEBUG not truthy): clean structured JSON to stdout ONLY —
+ *   no log file by default (writing logs/tina4.log inside a container bloats the
+ *   writable layer + disk; 12-factor wants logs on stdout). stdout is ALWAYS on.
+ *
+ * Default file-output rule (TINA4_LOG_OUTPUT unset): the log FILE is written
+ * only in development. An explicit TINA4_LOG_OUTPUT=file/both, OR an explicit
+ * TINA4_LOG_FILE path, always forces a file (explicit wins).
  *
  * Env vars:
- *   TINA4_LOG_FILE          — explicit log file (absolute or relative). Empty = use TINA4_LOG_DIR + tina4.log
+ *   TINA4_LOG_FILE          — explicit log file (absolute or relative). Setting it forces a file even in production. Empty = use TINA4_LOG_DIR + tina4.log
  *   TINA4_LOG_DIR           — directory for log files (default: "logs")
  *   TINA4_LOG_FORMAT        — "text" | "json" (default: "text")
- *   TINA4_LOG_OUTPUT        — "stdout" | "file" | "both" (default: "stdout")
- *   TINA4_LOG_CRITICAL      — "true" to enable CRITICAL level shortcut (default: "false")
+ *   TINA4_LOG_OUTPUT        — "stdout" | "file" | "both" (default: "stdout" → file only in dev)
  *   TINA4_LOG_ROTATE_SIZE   — bytes; 0 disables rotation (default: 10485760 = 10MB)
  *   TINA4_LOG_ROTATE_KEEP   — number of historical files to keep (default: 5)
- *   TINA4_LOG_LEVEL         — minimum console level (default: "DEBUG")
+ *   TINA4_LOG_LEVEL         — minimum console level: DEBUG | INFO | WARNING | ERROR | CRITICAL (default: "INFO")
  *
  * Rotation is stdlib roll-your-own:
  *   - On each write, statSync the file. If size >= TINA4_LOG_ROTATE_SIZE, rotate.
@@ -171,10 +176,11 @@ export class Log {
     minLevel: number;
     format: "text" | "json";
     output: "stdout" | "file" | "both";
-    criticalEnabled: boolean;
+    fileEnabled: boolean;
   } {
     const logDir = process.env.TINA4_LOG_DIR ?? DEFAULT_LOG_DIR;
-    const logFile = (process.env.TINA4_LOG_FILE ?? "").trim() || DEFAULT_LOG_FILE;
+    const explicitFile = (process.env.TINA4_LOG_FILE ?? "").trim();
+    const logFile = explicitFile || DEFAULT_LOG_FILE;
 
     const rawSize = process.env.TINA4_LOG_ROTATE_SIZE;
     let rotateSize = DEFAULT_ROTATE_SIZE;
@@ -203,9 +209,57 @@ export class Log {
     if (out === "file") output = "file";
     else if (out === "both") output = "both";
 
-    const criticalEnabled = isTruthy(process.env.TINA4_LOG_CRITICAL);
+    // v3.13.39: dev/prod-aware default file output (Python master, 4c6d881).
+    // When TINA4_LOG_OUTPUT is unset (default "stdout"), the log FILE is written
+    // only in development (TINA4_DEBUG truthy). In production / containers the
+    // logger is stdout-only — writing logs/tina4.log inside a container just
+    // bloats the writable layer + disk, and 12-factor wants logs on stdout for
+    // the platform to capture. Explicit TINA4_LOG_OUTPUT=file/both OR an explicit
+    // TINA4_LOG_FILE path always wins (explicit forces a file regardless of env).
+    let fileEnabled: boolean;
+    if (output === "file" || output === "both") {
+      fileEnabled = true;
+    } else if (explicitFile !== "") {
+      fileEnabled = true;
+    } else {
+      fileEnabled = !Log.isProduction();
+    }
+
+    return { logDir, logFile, rotateSize, rotateKeep, minLevel, format, output, fileEnabled };
+  }
+
+  /**
+   * The single console-threshold predicate: does a message at `level` clear
+   * the configured minimum console level? This is the ONE place level
+   * comparison lives — both the live log() gate and the public isEnabled()
+   * predicate call it, so they can never disagree about what actually prints.
+   */
+  private static passesThreshold(level: LogLevel, minLevel: number): boolean {
+    return (LEVEL_PRIORITY[level] ?? 0) >= minLevel;
+  }
 
-    return { logDir, logFile, rotateSize, rotateKeep, minLevel, format, output, criticalEnabled };
+  /**
+   * Return true if a message at `level` would pass the configured minimum
+   * console level (TINA4_LOG_LEVEL) — the same threshold that gates stdout.
+   *
+   * This reflects CONSOLE (stdout) visibility only. The log file always
+   * records every level regardless of this threshold, so don't use it to
+   * decide whether something gets persisted — use it to skip building an
+   * expensive payload that would not be shown:
+   *
+   *     if (Log.isEnabled("debug")) {
+   *       Log.debug("state", expensiveSnapshot());
+   *     }
+   *
+   * `level` is case-insensitive. "critical" is the highest severity (priority
+   * 4 > error 3) and flows through the ordinary threshold check like every
+   * other level — there is no toggle. It reuses the same passesThreshold()
+   * check the logger itself uses, so it never drifts from what print does.
+   */
+  static isEnabled(level: string): boolean {
+    const cfg = Log.readEnv();
+    const lvl = (level ?? "").toUpperCase() as LogLevel;
+    return Log.passesThreshold(lvl, cfg.minLevel);
   }
 
   /**
@@ -257,9 +311,12 @@ export class Log {
   }
 
   /**
-   * Log a critical message. Only emitted when TINA4_LOG_CRITICAL=true,
-   * otherwise this is a no-op (matches Python parity — critical is the
-   * highest-severity bucket and is opt-in to avoid drowning noisy apps).
+   * Log a critical message. CRITICAL is the highest severity (priority 4 >
+   * error 3) and ALWAYS emits like every other level — subject only to the
+   * console threshold, which it always passes at normal levels — and is always
+   * persisted to the log file (Node tees every level to a single tina4.log;
+   * critical 4 >= warning 2 so it would be in error.log on a split-file model).
+   * Matches Python master parity — there is no enable toggle.
    */
   static critical(message: string, data?: unknown): void {
     Log.log("CRITICAL", message, data);
@@ -355,9 +412,6 @@ export class Log {
   private static log(level: LogLevel, message: string, data?: unknown): void {
     const cfg = Log.readEnv();
 
-    // Critical level is opt-in; treat as no-op when disabled.
-    if (level === "CRITICAL" && !cfg.criticalEnabled) return;
-
     const entry: LogEntry = {
       timestamp: Log.timestamp(),
       level,
@@ -393,7 +447,7 @@ export class Log {
     const fileLine =
       cfg.format === "json" || Log.isProduction() ? JSON.stringify(entry) : humanLine;
 
-    const shouldLog = (LEVEL_PRIORITY[level] ?? 0) >= cfg.minLevel;
+    const shouldLog = Log.passesThreshold(level, cfg.minLevel);
 
     // Console output. v3.13.14: stdout is NOT suppressed in production —
     // containers read PID 1 stdout (docker logs / k8s) and the old
@@ -410,17 +464,20 @@ export class Log {
       }
     }
 
-    // File output: always teed for dev (legacy behaviour), and either always
-    // (production default) or honoured per output mode.
+    // File output (v3.13.39 — Python master, 4c6d881): gated on cfg.fileEnabled.
     //
-    //   output=stdout (default): file in dev + prod (legacy parity)
-    //   output=file              file only — no console
-    //   output=both              file + console (already handled above)
+    //   output=stdout (default): file ONLY in dev (TINA4_DEBUG truthy);
+    //                            production / containers are stdout-only — no
+    //                            file to bloat the writable layer / disk.
+    //   output=file              file only — no console (always writes a file)
+    //   output=both              file + console (always writes a file)
+    //   explicit TINA4_LOG_FILE  always writes a file (explicit wins)
     //
-    // The "stdout-only without file" mode that some Python deployments want
-    // is gated on TINA4_LOG_OUTPUT=stdout combined with TINA4_LOG_FILE set
-    // explicitly to an empty string in env — we treat empty file as default.
-    const filePath = resolveLogFilePath(cfg.logDir, cfg.logFile);
-    Log.writeToFile(filePath, fileLine, cfg.rotateSize, cfg.rotateKeep);
+    // readEnv() resolves all of the above into cfg.fileEnabled, so flipping
+    // that one flag gates the whole file writer (the only persisted sink).
+    if (cfg.fileEnabled) {
+      const filePath = resolveLogFilePath(cfg.logDir, cfg.logFile);
+      Log.writeToFile(filePath, fileLine, cfg.rotateSize, cfg.rotateKeep);
+    }
   }
 }

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,18 +210,61 @@ function envTruthy(val: string | undefined): boolean {
 }
 
 /**
- * Whether the built-in MCP server should auto-start.
+ * 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.
  *
- * Default: `true` when `TINA4_DEBUG=true`, `false` otherwise. The `TINA4_MCP`
- * env var can force either state explicitly. Matches the Python framework
- * which only exposes MCP endpoints in dev mode by default.
+ * 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.
+ *
+ * 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 raw = process.env.TINA4_MCP;
-  if (raw === undefined || raw.trim() === "") {
-    return envTruthy(process.env.TINA4_DEBUG);
+  const explicit = process.env.TINA4_MCP;
+  if (explicit !== undefined && explicit.trim() !== "") {
+    return envTruthy(explicit);
   }
-  return envTruthy(raw);
+  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;
 }
 
 /**
@@ -603,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;
 }
 
@@ -848,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 };
@@ -904,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 };
       }