tina4-nodejs 3.13.98 → 3.13.99

package/packages/core/src/devAdmin.ts

@@ -19,26 +19,115 @@ import { DevMailbox } from "./devMailbox.js";
 import { isTruthy } from "./dotenv.js";
 import { quickMetrics, fullAnalysis, fileDetail, MetricsEngineError } from "./metrics.js";
 import { registerFeedbackRoutes } from "./feedback.js";
-import { getDefaultDevServer, mcpEnabled, isRequestAllowed } from "./mcp.js";
+import { getDefaultDevServer, mcpEnabled, isRequestAllowed, isLoopback } from "./mcp.js";
 import { timingSafeEqual } from "node:crypto";
+// VERSION-DEC-01 (feature 130): the dashboard reads the SAME resolved version
+// as server.ts's banner/health and mcp.ts's default dev server -- one shared
+// walk-up resolver in ./version.ts, not this file's own two-fixed-path reader
+// (which also floored at "0.0.0" once @tina4/core was relocated out of the
+// monorepo layout).
+import { TINA4_VERSION } from "./version.js";
 
 const cpuCount = osCpus().length;
 
-// Read version from root package.json dynamically
-const TINA4_VERSION = (() => {
-  try {
-    const __dirname = dirname(fileURLToPath(import.meta.url));
-    // Try root package.json first, then core package.json
-    for (const rel of ["../../../package.json", "../../package.json"]) {
-      const p = resolve(__dirname, rel);
-      if (existsSync(p)) {
-        const pkg = JSON.parse(readFileSync(p, "utf-8"));
-        if (pkg.version) return pkg.version;
-      }
+// ── Dev-admin mutation security (feature 127, DEVADMIN-DEC-01/02/03) ──────────
+// The dashboard can write files, run SQL and install packages, so it must assume
+// the developer ALSO browses the web. Two fail-closed gates guard every /__dev
+// write, and a secret denylist guards the file-read surface. Mirrors the Python
+// master (tina4_python/dev_admin/__init__.py).
+
+/** Safe HTTP methods that never carry a state change — they skip the write gate. */
+export const DEV_SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+
+/**
+ * The MCP surface carries its OWN richer loopback+token+remote gate
+ * (mcpRequestAllowed -> 404), so the REST loopback gate skips these prefixes and
+ * lets the MCP gate govern (keeps the mcp/call refusal a 404, not a 403).
+ */
+const DEV_MCP_PREFIXES = ["/__dev/api/mcp", "/__dev/mcp"];
+
+/** Private-key / credential basenames the file endpoints must never serve. */
+const DEV_SECRET_BASENAMES = new Set([
+  ".env", ".envrc", "id_rsa", "id_dsa", "id_ecdsa", "id_ed25519",
+]);
+const DEV_SECRET_SUFFIXES = [".pem", ".key", ".pfx", ".p12", ".keystore", ".jks"];
+
+/** HTML-escape `& < > " '` — the injected toolbar reflects the raw request path. */
+function escapeHtml(value: string): string {
+  return String(value)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+/**
+ * Fail-closed same-origin check for a dev-admin mutation (DEVADMIN-DEC-01).
+ *
+ * A drive-by CSRF is a BROWSER cross-origin request, and a modern browser always
+ * sends `Sec-Fetch-Site` (and any browser sends `Origin` on a cross-origin POST):
+ *   - Sec-Fetch-Site present -> trust the browser's classification
+ *     (cross-site refused; same-origin / same-site / none ok).
+ *   - else Origin present -> require its host to match the request Host.
+ *   - else neither header -> not a browser cross-origin request (curl, a test
+ *     client, a server-side caller); it cannot be a drive-by, so allow here and
+ *     let the loopback gate still constrain the peer.
+ */
+export function devSameOriginOk(req: Tina4Request): boolean {
+  const secFetchSite = (req.header("sec-fetch-site") ?? "").trim().toLowerCase();
+  if (secFetchSite) {
+    return secFetchSite === "same-origin" || secFetchSite === "same-site" || secFetchSite === "none";
+  }
+  const origin = (req.header("origin") ?? "").trim();
+  if (origin) {
+    const netloc = origin.includes("://") ? origin.split("://", 2)[1] : origin;
+    const host = (req.header("host") ?? "").trim();
+    return host !== "" && netloc.toLowerCase() === host.toLowerCase();
+  }
+  return true;
+}
+
+/**
+ * Return `{status, error}` to REFUSE a dev-admin write, or `null` to allow.
+ *
+ * Two independent fail-closed gates on every /__dev mutation:
+ *   DEVADMIN-DEC-01  same-origin (all writes, incl. mcp/call) - drive-by CSRF.
+ *   DEVADMIN-DEC-02  loopback peer (all writes EXCEPT the MCP surface, which
+ *                    carries its own gate) - a network-exposed debug box.
+ * Reads the RAW socket peer (never X-Forwarded-For), exactly like the MCP gate.
+ */
+export function devMutationDenial(req: Tina4Request): { status: number; error: string } | null {
+  if (!devSameOriginOk(req)) {
+    return { status: 403, error: "dev-admin: refused (cross-origin request)" };
+  }
+  const path = req.path ?? "";
+  const isMcp = DEV_MCP_PREFIXES.some((prefix) => path.startsWith(prefix));
+  if (!isMcp) {
+    const peer = (req as unknown as { socket?: { remoteAddress?: string } }).socket?.remoteAddress ?? "";
+    if (!(isLoopback(peer) || mcpTokenOk(req))) {
+      return { status: 403, error: "dev-admin: refused (non-loopback peer)" };
     }
-  } catch {}
-  return "0.0.0";
-})();
+  }
+  return null;
+}
+
+/**
+ * True when `rel` names secret material the file endpoints must never serve
+ * (DEVADMIN-DEC-03): `.env` / `.env.*` (the `.env.example` template is allowed),
+ * anything under `.git/` or `secrets/`, and private-key material.
+ */
+export function isSecretPath(rel: string): boolean {
+  const norm = (rel ?? "").replace(/\\/g, "/").replace(/^\/+|\/+$/g, "").toLowerCase();
+  if (!norm) return false;
+  const parts = norm.split("/");
+  if (parts.some((p) => p === ".git" || p === "secrets")) return true;
+  const base = parts[parts.length - 1];
+  if (base === ".env.example") return false;
+  if (base === ".env" || base.startsWith(".env.")) return true;
+  if (DEV_SECRET_BASENAMES.has(base)) return true;
+  return DEV_SECRET_SUFFIXES.some((suffix) => base.endsWith(suffix));
+}
 
 // ---------------------------------------------------------------------------
 // Types
@@ -1251,7 +1340,10 @@ const handleSeed: RouteHandler = async (req, res) => {
     }
     // P1 — delegate to the shared seedTable so each row is wrapped (no
     // unhandled failure can crash the endpoint) and we get a summary back.
-    const summary = await seedTable(db, table, count, fieldMap, undefined, { clear, seed, strict });
+    // SEED-TABLE-SEED-INERT: seedTable no longer takes opts.seed (it throws
+    // if supplied) — reproducibility already comes from the seeded `fake`
+    // built above and closed over by every entry in fieldMap.
+    const summary = await seedTable(db, table, count, fieldMap, undefined, { clear, strict });
     res.json({ seeded: summary.seeded, failed: summary.failed, errors: summary.errors, table });
   } catch (e) {
     res.json({ error: (e as Error)?.message ?? "Database not connected" });
@@ -2081,7 +2173,10 @@ const DEV_FILES_IGNORED = new Set([
 // Hidden dot-entries are filtered too, except the env files.
 function devFilesHidden(name: string): boolean {
   if (DEV_FILES_IGNORED.has(name)) return true;
-  return name.startsWith(".") && name !== ".env" && name !== ".env.example";
+  // DEVADMIN-DEC-03: hide every dotfile EXCEPT the safe `.env.example` template.
+  // `.env` is a secret (TINA4_SECRET / DB password / TINA4_MCP_TOKEN) and must
+  // NOT be surfaced in the browser (it used to be un-hidden here).
+  return name.startsWith(".") && name !== ".env.example";
 }
 
 // Same 4-status mapping Python/PHP use for a porcelain code.
@@ -2171,6 +2266,9 @@ const handleFiles: RouteHandler = async (req, res) => {
     if (devFilesHidden(name)) continue;
     const full = join(target, name);
     const entryRel = relative(root, full).replace(/\\/g, "/");
+    // DEVADMIN-DEC-03: never surface secrets in the listing (.env, keys, .git/,
+    // secrets/). The .env.example template is safe and stays visible.
+    if (isSecretPath(entryRel)) continue;
 
     let isDir = false;
     let size: number | null = null;
@@ -2265,6 +2363,11 @@ export function devAdminLanguage(rel: string): string {
 const handleFileRead: RouteHandler = (req, res) => {
   const url = new URL(req.url ?? "/", "http://localhost");
   const rel = url.searchParams.get("path") ?? "";
+  // DEVADMIN-DEC-03: never serve secret material (.env, keys, .git/, secrets/).
+  if (isSecretPath(rel)) {
+    res.json({ error: "Refused: secret file", path: rel, content: "", language: "text", bytes: 0 }, 403);
+    return;
+  }
   const root = resolve(process.cwd());
   const target = safeJoin(root, rel);
   if (!target || !existsSync(target) || !statSync(target).isFile()) {
@@ -2307,6 +2410,11 @@ const handleFileSave: RouteHandler = async (req, res) => {
 const handleFileRaw: RouteHandler = (req, res) => {
   const url = new URL(req.url ?? "/", "http://localhost");
   const rel = url.searchParams.get("path") ?? "";
+  // DEVADMIN-DEC-03: never serve secret material (.env, keys, .git/, secrets/).
+  if (isSecretPath(rel)) {
+    res.json({ error: "Refused: secret file" }, 403);
+    return;
+  }
   const root = resolve(process.cwd());
   const target = safeJoin(root, rel);
   if (!target || !existsSync(target) || !statSync(target).isFile()) {
@@ -2873,6 +2981,13 @@ function renderToolbarHtml(ctx: {
   routeCount: number;
 }): string {
   const nodeVersion = process.version;
+  // DEVADMIN-DEC-04: the toolbar is injected into every text/html response
+  // (including 404s), so the reflected request path/method MUST be HTML-escaped
+  // or a crafted path reflects <script> that runs in the dev-server origin and
+  // can then drive every /__dev mutation route. (PHP already escapes; parity.)
+  const method = escapeHtml(ctx.method);
+  const path = escapeHtml(ctx.path);
+  const matchedPattern = escapeHtml(ctx.matchedPattern);
   return `<div id="tina4-dev-toolbar" style="position:fixed;bottom:0;left:0;right:0;background:#333;color:#fff;font-family:monospace;font-size:12px;padding:6px 16px;z-index:99999;display:flex;align-items:center;gap:16px;">
     <span id="tina4-ver-btn" style="color:#2e7d32;font-weight:bold;cursor:pointer;text-decoration:underline dotted;" onclick="tina4VersionModal()" title="Click to check for updates">Tina4 v${ctx.version}</span>
     <div id="tina4-ver-modal" style="display:none;position:fixed;bottom:3rem;left:1rem;background:#1e1e2e;border:1px solid #2e7d32;border-radius:8px;padding:16px 20px;z-index:100000;min-width:320px;box-shadow:0 8px 32px rgba(0,0,0,0.5);font-family:monospace;font-size:13px;color:#cdd6f4;">
@@ -2885,9 +3000,9 @@ function renderToolbarHtml(ctx: {
         <div id="tina4-ver-latest" style="color:#888;">Checking for updates...</div>
       </div>
     </div>
-    <span style="color:#4caf50;">${ctx.method}</span>
-    <span>${ctx.path}</span>
-    <span style="color:#666;">&rarr; ${ctx.matchedPattern}</span>
+    <span style="color:#4caf50;">${method}</span>
+    <span>${path}</span>
+    <span style="color:#666;">&rarr; ${matchedPattern}</span>
     <span style="color:#ffeb3b;">req:${ctx.requestId}</span>
     <span style="color:#90caf9;">${ctx.routeCount} routes</span>
     <span style="color:#888;">Node.js ${nodeVersion}</span>

package/packages/core/src/dispatchPipeline.ts

@@ -29,6 +29,8 @@
  *      the source of the stage-list-as-data pattern.
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { gzipSync } from "node:zlib";
+import { createHash } from "node:crypto";
 import type { Tina4Request } from "./types.js";
 import type { Session as SessionInstance } from "./session.js";
 import { Log } from "./logger.js";
@@ -40,6 +42,7 @@ import { Log } from "./logger.js";
 export const PROLOGUE_STAGES = [
   "resetRequestCaches",
   "headStripIntercept",
+  "compressionEtagIntercept",
   "sessionAutoStart",
 ] as const;
 
@@ -172,6 +175,178 @@ export function headStripIntercept(rawReq: IncomingMessage, rawRes: ServerRespon
   }) as typeof rawRes.end;
 }
 
+/** Content-type prefixes that benefit from gzip. Mirrors the Python master's `_is_compressible`. */
+const COMPRESSIBLE_PREFIXES = [
+  "text/",
+  "application/json",
+  "application/xml",
+  "application/javascript",
+  "image/svg",
+];
+
+/** Whether a content type benefits from gzip compression (feature 40, CE-DEC-01). */
+function isCompressibleContentType(contentType: string): boolean {
+  return COMPRESSIBLE_PREFIXES.some((prefix) => contentType.includes(prefix));
+}
+
+/**
+ * Match an If-None-Match header value against `etag` (RFC 7232 S3.2 weak
+ * comparison): an optional W/ prefix is ignored on both sides, the header may
+ * carry a comma-separated candidate list, and `*` matches any current
+ * representation. Same algorithm as static.ts's own matcher (kept local here
+ * rather than imported, since static.ts writes to the raw response directly
+ * and never reaches this interceptor).
+ */
+function etagMatchesInm(ifNoneMatch: string, etag: string): boolean {
+  const strip = (tag: string) => tag.trim().replace(/^W\//, "");
+  const target = strip(etag);
+  return ifNoneMatch.split(",").some((candidate) => {
+    const trimmed = candidate.trim();
+    return trimmed === "*" || strip(trimmed) === target;
+  });
+}
+
+/**
+ * Gzip-compress + attach an ETag, and answer a matching conditional GET with
+ * a 304 that PRESERVES whichever validators the 200 would have carried
+ * (feature 40, CE-DEC-01/02). Mirrors the Python master's `build_headers()` +
+ * `app()` dispatch — the ONE header-builder step every DYNAMIC response
+ * funnels through.
+ *
+ * Node has no single "build the response, then send it" object the way
+ * Python/PHP/Ruby do — every response.ts method (json/html/text/xml/send/
+ * file/render) calls `res.end()` directly. So this intercepts `write`/`end`
+ * on the raw `ServerResponse` and buffers the body until `end()` is finally
+ * called, which is the only point a COMPLETE body — and therefore a
+ * Content-Length, a gzip candidate, and an ETag — exists to compute.
+ *
+ * BYPASS: a response that has ALREADY sent its headers by the time
+ * write()/end() is first called here (checked via `rawRes.headersSent`) is a
+ * streaming response — `response.ts`'s `stream()` calls `res.raw.writeHead()`
+ * up front, before any chunk — and is passed straight through unbuffered,
+ * exactly like Python's "streaming responses bypass ETag/compression".
+ *
+ * Installed in the PROLOGUE, right after `headStripIntercept`: since the LAST
+ * installed wrapper runs FIRST when `end()` is finally called, and
+ * `wrapResponseEnd` (dev-toolbar/feedback injection) installs LATER (in the
+ * REQUEST stage), the real execution order at send time is
+ * injection -> this -> `headStripIntercept` -> the true Node `res.end()` — so
+ * a HEAD response's preserved Content-Length reflects the (possibly
+ * compressed) body the equivalent GET would have sent, and the injected
+ * bytes are included in the compressed body + ETag hash, matching Python's
+ * ordering exactly.
+ *
+ * A static-file response (`static.ts`) still funnels through this same
+ * intercepted `write`/`end` — it pins its own weak size+mtime ETag and (when
+ * eligible) compresses itself BEFORE calling `res.raw.end()`, so by the time
+ * this runs, its status is already 200-with-ETag-set (this never overwrites
+ * it) or already 304 (the `statusCode === 200` guard below leaves it alone).
+ *
+ * @param rawReq Node's incoming message, read for Accept-Encoding / If-None-Match / If-Modified-Since
+ * @param rawRes Node's server response, whose write/end are replaced in place
+ */
+export function compressionEtagIntercept(rawReq: IncomingMessage, rawRes: ServerResponse): void {
+  const origEnd = rawRes.end.bind(rawRes);
+  const origWrite = rawRes.write.bind(rawRes);
+  const chunks: Buffer[] = [];
+  let bypass = false;
+
+  const toBuffer = (chunk: unknown, encoding?: unknown): Buffer | null => {
+    if (chunk == null || typeof chunk === "function") return null;
+    if (Buffer.isBuffer(chunk)) return chunk;
+    return Buffer.from(String(chunk), typeof encoding === "string" ? (encoding as BufferEncoding) : "utf-8");
+  };
+
+  rawRes.write = ((chunk?: any, encodingOrCb?: any, cb?: any): boolean => {
+    if (bypass || rawRes.headersSent) {
+      bypass = true;
+      return origWrite(chunk, encodingOrCb, cb);
+    }
+    const buf = toBuffer(chunk, typeof encodingOrCb === "string" ? encodingOrCb : undefined);
+    if (buf) chunks.push(buf);
+    const realCb = typeof encodingOrCb === "function" ? encodingOrCb : cb;
+    if (typeof realCb === "function") realCb();
+    return true;
+  }) as typeof rawRes.write;
+
+  rawRes.end = ((chunk?: any, encodingOrCb?: any, cb?: any): any => {
+    if (bypass || rawRes.headersSent) {
+      return origEnd(chunk, encodingOrCb, cb);
+    }
+
+    const buf = toBuffer(chunk, typeof encodingOrCb === "string" ? encodingOrCb : undefined);
+    if (buf) chunks.push(buf);
+    let body = chunks.length > 0 ? Buffer.concat(chunks) : Buffer.alloc(0);
+    const realCb = typeof encodingOrCb === "function" ? encodingOrCb : cb;
+    const statusCode = rawRes.statusCode || 200;
+
+    // Compression: body > 1024 bytes AND Accept-Encoding offers gzip AND the
+    // content type is compressible. Applies to ANY response (matches every
+    // route, not status-gated), same as the Python master.
+    //
+    // REAL BUG (found 2026-08-13, tina4cssServed.test.ts): a static-file
+    // response (static.ts) already gzips itself and sets Content-Encoding
+    // before calling res.raw.end() — but that end() is THIS intercepted one,
+    // so without the guard below it gzipped an already-gzipped body a second
+    // time. The client's one layer of automatic decompression then handed
+    // back a still-gzipped blob instead of the real bytes. Skip compression
+    // here whenever an earlier stage already set Content-Encoding.
+    const acceptEncoding = String(rawReq.headers["accept-encoding"] ?? "");
+    const contentTypeHeader = rawRes.getHeader("content-type");
+    const contentType = typeof contentTypeHeader === "string" ? contentTypeHeader : "";
+    const alreadyEncoded = !!rawRes.getHeader("content-encoding");
+    if (!alreadyEncoded && body.length > 1024 && acceptEncoding.includes("gzip") && isCompressibleContentType(contentType)) {
+      body = gzipSync(body, { level: 6 });
+      rawRes.setHeader("Content-Encoding", "gzip");
+      rawRes.setHeader("Vary", "Accept-Encoding");
+    }
+
+    if (statusCode === 200 && body.length > 0) {
+      // ETag: a strong md5 hash (first 16 hex chars) over the FINAL
+      // (post-compression) body, UNLESS a validator is already set — a
+      // static-file response (static.ts) pins its own weak size+mtime ETag
+      // before this ever runs (CE-DEC-02), so this never overwrites it with
+      // a content hash.
+      let etag = rawRes.getHeader("etag");
+      if (!etag) {
+        etag = `"${createHash("md5").update(body).digest("hex").slice(0, 16)}"`;
+        rawRes.setHeader("ETag", etag);
+      }
+
+      // Conditional GET -> 304, preserving whichever validators are set.
+      // If-None-Match takes precedence over If-Modified-Since (RFC 9110 S13.1.3).
+      const ifNoneMatch = String(rawReq.headers["if-none-match"] ?? "");
+      const lastModifiedHeader = rawRes.getHeader("last-modified");
+      const lastModified = typeof lastModifiedHeader === "string" ? lastModifiedHeader : "";
+      let notModified = false;
+      if (ifNoneMatch) {
+        notModified = etagMatchesInm(ifNoneMatch, String(etag));
+      } else if (lastModified) {
+        const ifModifiedSince = String(rawReq.headers["if-modified-since"] ?? "");
+        if (ifModifiedSince) {
+          const modified = Date.parse(lastModified);
+          const since = Date.parse(ifModifiedSince);
+          notModified = !Number.isNaN(modified) && !Number.isNaN(since) && modified <= since;
+        }
+      }
+
+      if (notModified) {
+        rawRes.statusCode = 304;
+        rawRes.removeHeader("Content-Type");
+        rawRes.removeHeader("Content-Encoding");
+        rawRes.removeHeader("Vary");
+        rawRes.removeHeader("Content-Length");
+        return typeof realCb === "function" ? origEnd(realCb) : origEnd();
+      }
+    }
+
+    if (!rawRes.headersSent && statusCode !== 304) {
+      rawRes.setHeader("Content-Length", body.length);
+    }
+    return typeof realCb === "function" ? origEnd(body, realCb) : origEnd(body);
+  }) as typeof rawRes.end;
+}
+
 /**
  * `Type: message` for a caught value, so an operator reading the log sees the
  * REAL driver failure rather than an opaque wrapper. Mirrors the Python fix's
@@ -278,7 +453,16 @@ export async function sessionAutoStart(
       const xfProto = rawReq.headers["x-forwarded-proto"];
       const forwardedProto = Array.isArray(xfProto) ? xfProto[0] : xfProto;
       const socketEncrypted = (rawReq.socket as { encrypted?: boolean })?.encrypted === true;
-      rawRes.setHeader("Set-Cookie", buildSessionCookie(newSid, ttl, undefined, forwardedProto, socketEncrypted));
+      // appendHeader, not setHeader (feature 131 fix, found while proving
+      // TC-DEC-02): setHeader REPLACES any existing Set-Cookie value wholesale,
+      // so a route that had already called response.cookie() of its own — on
+      // the SAME request that also needs a fresh session cookie (first visit
+      // to any route, or a session id rotation) — had its own cookie(s)
+      // silently discarded, live server included, not just under TestClient.
+      // appendHeader adds to whatever is already there (promoting a scalar to
+      // an array, extending an existing array) and behaves exactly like
+      // setHeader when nothing is set yet, so the common case is unchanged.
+      rawRes.appendHeader("Set-Cookie", buildSessionCookie(newSid, ttl, undefined, forwardedProto, socketEncrypted));
     }
     return origEnd(...args);
   } as typeof rawRes.end;

package/packages/core/src/docs.ts

@@ -872,6 +872,26 @@ function buildLineIndex(text: string): (offset: number) => number {
 
 // ── Public Docs class ───────────────────────────────────────────────
 
+/**
+ * Framework-wide reflection index, shared across every `Docs` instance in
+ * this process (keyed by frameworkRoots + version — both are baked into the
+ * built entries, see buildEntriesForFile's `rel`/`version` fields).
+ *
+ * `detectFrameworkRoots()` never depends on `projectRoot` (it walks up from
+ * THIS module's own file location), so the framework source tree is the same
+ * for every instance that resolves the same roots+version — re-walking and
+ * re-parsing it per INSTANCE was pure waste. Measured: docs.test.ts alone
+ * constructs ~17 fresh `Docs` instances, each paying a full AST walk over
+ * packages/{core,orm,swagger,frond}/src on first use — fast on an idle
+ * machine (~1s total on the lab), but it blew the test runner's 60s
+ * per-file budget on a CI runner under load (many concurrent service
+ * containers sharing 2 vCPUs), landing as "died before reporting" with no
+ * useful diagnostic. Still mtime-gated exactly as before (see `ensureIndex`),
+ * so a framework source edit during a live dev session is still picked up —
+ * this changes WHEN the scan is shared, never WHETHER the index stays fresh.
+ */
+const sharedFrameworkIndex = new Map<string, { entries: Map<string, InternalEntry>; mtime: number }>();
+
 export class Docs {
   private projectRoot: string;
   private frameworkRoots: string[];
@@ -1157,16 +1177,24 @@ export class Docs {
   }
 
   private ensureIndex(): void {
-    // Framework: rebuild only if not built yet OR mtime changed.
+    // Framework: shared process-wide, rebuilt only if not built yet OR mtime
+    // changed (see `sharedFrameworkIndex` above for why this is safe to share).
+    const fwKey = `${this.frameworkRoots.join("|")}@${this.version}`;
     const fwMtime = this.maxMtime(this.frameworkRoots);
-    if (this.frameworkEntries === null || fwMtime !== this.frameworkMtime) {
-      this.frameworkEntries = new Map();
+    let shared = sharedFrameworkIndex.get(fwKey);
+    if (!shared || fwMtime !== shared.mtime) {
+      const entries = new Map<string, InternalEntry>();
       for (const root of this.frameworkRoots) {
         for (const f of walkTsFiles(root)) {
-          buildEntriesForFile(f, "framework", this.frameworkRoots, this.projectRoot, this.version, this.frameworkEntries);
+          buildEntriesForFile(f, "framework", this.frameworkRoots, this.projectRoot, this.version, entries);
         }
       }
-      this.frameworkMtime = fwMtime;
+      shared = { entries, mtime: fwMtime };
+      sharedFrameworkIndex.set(fwKey, shared);
+    }
+    if (this.frameworkEntries !== shared.entries) {
+      this.frameworkEntries = shared.entries;
+      this.frameworkMtime = shared.mtime;
       this.indexCache = null;
     }
 

package/packages/core/src/env.ts

@@ -34,7 +34,7 @@ function logWarning(message: string): void {
     import("./logger.js")
       .then((mod) => {
         try {
-          mod.Log.warn(message);
+          mod.Log.warning(message);
         } catch {
           /* Log not ready — skip */
         }

package/packages/core/src/errorOverlay.ts

@@ -1,28 +1,47 @@
 /**
  * Tina4 Debug — Rich error overlay for development mode.
  *
- * Renders a professional, syntax-highlighted HTML error page when an unhandled
- * exception occurs in a route handler.
+ * Renders a rich HTML error page (exception type + message, the full stack with a
+ * seven-line source window per frame, request details, environment) when an unhandled
+ * exception reaches the server dispatch in development.
  *
- *   import { renderErrorOverlay, renderProductionError, isDebugMode } from "./errorOverlay.js";
+ *   import { renderErrorOverlay, isDebugMode } from "./errorOverlay.js";
  *
  *   try {
  *     await handler(req, res);
  *   } catch (err) {
- *     const html = isDebugMode()
- *       ? renderErrorOverlay(err as Error, req)
- *       : renderProductionError();
- *     res.html(html, 500);
+ *     if (isDebugMode()) res.html(renderErrorOverlay(err as Error, req), 500);
  *   }
  *
- * Only activate when TINA4_DEBUG is true.
- * In production, call renderProductionError() instead.
+ * Dev-only: the caller gates this on isDebugMode() (TINA4_DEBUG). The production 500 is
+ * NOT rendered here — the server dispatch renders errors/500.twig with an empty
+ * error_message (CWE-209), so the exception detail stays in the server log only.
+ *
+ * Sensitive request fields (Authorization / Cookie / Set-Cookie headers and
+ * password-like body/param keys) are redacted even in the dev overlay, the frame count
+ * is capped, and the caller wraps this render in a guard, so a broken overlay or a
+ * recursive stack still yields a bounded, safe 500.
  */
 
 import { readFileSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 import { isTruthy } from "./dotenv.js";
 
+// OVERLAY-DEC-03: cap the rendered frames so a deep/recursive stack yields a bounded
+// page, not one source-file read per frame.
+const MAX_FRAMES = 50;
+
+// OVERLAY-DEC-02: request fields whose KEY matches this are masked in the dev overlay
+// (Authorization/Cookie/Set-Cookie headers via authorization|cookie; password/token/
+// secret/api_key body/param keys via the rest). Over-matching a benign field is the
+// SAFE direction in a dev tool — over-masking leaks nothing; under-masking leaks.
+const SENSITIVE_KEY_RE = /password|passwd|secret|token|authorization|cookie|key/i;
+const REDACTED = "[redacted]";
+
+function redact(key: string, value: string): string {
+  return SENSITIVE_KEY_RE.test(key) ? REDACTED : value;
+}
+
 // ── Colour palette (Catppuccin Mocha) ────────────────────────────────────
 const BG = "#1e1e2e";
 const SURFACE = "#313244";
@@ -196,10 +215,18 @@ export function renderErrorOverlay(error: Error, request?: any): string {
   // if the file has been modified since — protects against the "browser cached
   // an old overlay, then the AI rewrote the file" confusion where displayed
   // source no longer matches what actually raised the error.
+  // OVERLAY-DEC-03: cap the rendered frames. A recursive stack of thousands of frames
+  // would otherwise do one source-file read per frame and emit an unbounded page;
+  // render only the innermost MAX_FRAMES and note the rest.
   let framesHtml = "";
-  for (const frame of frames) {
+  for (const frame of frames.slice(0, MAX_FRAMES)) {
     framesHtml += formatFrame(frame, capturedAt);
   }
+  const hidden = frames.length - Math.min(frames.length, MAX_FRAMES);
+  if (hidden > 0) {
+    framesHtml += `<div style="color:${SUBTEXT};padding:8px 0;font-size:13px;">`
+      + `&#8230; ${hidden} more stack frames hidden (truncated at ${MAX_FRAMES})</div>`;
+  }
 
   // ── Request info ──
   const requestPairs: Array<[string, string]> = [];
@@ -216,7 +243,8 @@ export function renderErrorOverlay(error: Error, request?: any): string {
     for (const [label, val] of dictFields) {
       if (val != null && typeof val === "object" && Object.keys(val as object).length > 0) {
         for (const [k, v] of Object.entries(val as Record<string, unknown>)) {
-          requestPairs.push([`${label}.${k}`, String(v)]);
+          const pairKey = `${label}.${k}`;
+          requestPairs.push([pairKey, redact(pairKey, String(v))]);
         }
       } else if (val != null && typeof val === "string" && val !== "") {
         requestPairs.push([label, val]);
@@ -273,43 +301,6 @@ body{background:${BG};color:${TEXT};font-family:-apple-system,BlinkMacSystemFont
 </html>`;
 }
 
-/**
- * Render a safe, generic error page for production.
- */
-export function renderProductionError(statusCode = 500, message = "Internal Server Error", path = ""): string {
-  const codeColor = statusCode === 403 ? "#f59e0b" : statusCode === 404 ? "#3b82f6" : "#ef4444";
-  const pathHtml = path ? `<div class="error-path">${esc(path)}</div><br>` : "";
-  return `<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>${statusCode} — ${esc(message)}</title>
-<style>
-* { box-sizing: border-box; margin: 0; padding: 0; }
-body { font-family: system-ui, -apple-system, sans-serif; background: #0f172a; color: #e2e8f0; min-height: 100vh; display: flex; align-items: center; justify-content: center; }
-.error-card { background: #1e293b; border: 1px solid #334155; border-radius: 1rem; padding: 3rem; text-align: center; max-width: 520px; width: 90%; }
-.error-code { font-size: 8rem; font-weight: 900; color: ${codeColor}; opacity: 0.6; line-height: 1; margin-bottom: 0.5rem; }
-.error-title { font-size: 1.5rem; font-weight: 700; margin-bottom: 0.75rem; }
-.error-msg { color: #94a3b8; font-size: 1rem; margin-bottom: 1.5rem; line-height: 1.5; }
-.error-path { font-family: 'SF Mono', monospace; background: #0f172a; color: ${codeColor}; padding: 0.5rem 1rem; border-radius: 0.5rem; font-size: 0.85rem; word-break: break-all; margin-bottom: 1.5rem; display: inline-block; }
-.error-home { display: inline-block; padding: 0.6rem 2rem; background: #3b82f6; color: #fff; text-decoration: none; border-radius: 0.5rem; font-size: 0.9rem; font-weight: 600; }
-.error-home:hover { opacity: 0.9; }
-.logo { font-size: 1.5rem; margin-bottom: 1rem; opacity: 0.5; }
-</style>
-</head>
-<body>
-<div class="error-card">
-    <div class="error-code">${statusCode}</div>
-    <div class="error-title">${esc(message)}</div>
-    <div class="error-msg">Something went wrong while processing your request.</div>
-    ${pathHtml}
-    <a href="/" class="error-home">Go Home</a>
-</div>
-</body>
-</html>`;
-}
-
 /**
  * Check if TINA4_DEBUG is enabled.
  */

package/packages/core/src/fakeData.ts

@@ -1,5 +1,20 @@
 // Tina4 FakeData — Fake data generation and database seeding, zero dependencies.
 // Instance-based with optional seeded PRNG for deterministic output.
+//
+// Determinism is PER-LANGUAGE, not cross-language (SEED-DETERMINISM-PERLANG):
+// `new FakeData(42)` reproduces the identical sequence on every run *within
+// Node*, but the same seed on Python/PHP/Ruby's FakeData will NOT produce the
+// same values -- each language uses its own PRNG (Node's mulberry32, Python's
+// Mersenne Twister, PHP's per-instance Mt19937, Ruby's Random). There is no
+// shared cross-language PRNG, and hand-rolling one would add cost for no real
+// benefit -- use a seed to make ONE language's run reproducible, never to
+// compare output across languages.
+//
+// NOT FOR SECRETS (SEED-SECRETS-DOC): this is a non-cryptographic PRNG meant
+// for realistic-looking fixtures and test data. Never use it to generate API
+// keys, passwords, tokens, or anything else that must be unguessable -- use
+// node:crypto's randomBytes/randomUUID (already used here for the unseeded
+// path) directly, or Tina4's Auth helpers for password hashing.
 
 import { randomInt, randomUUID } from "node:crypto";
 import { existsSync, readdirSync } from "node:fs";