tina4-nodejs 3.13.137 → 3.13.139

package/packages/orm/src/sqlTranslator.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * Tina4 SQL Translation — Cross-engine SQL translator.
  *
@@ -259,11 +267,11 @@ export class SQLTranslator {
         return sql
           .replace(/\bBIGINT\s+PRIMARY\s+KEY\s+AUTOINCREMENT\b/gi, "BIGSERIAL PRIMARY KEY")
           .replace(/\bINTEGER\s+PRIMARY\s+KEY\s+AUTOINCREMENT\b/gi, "SERIAL PRIMARY KEY")
-          .replace(/\s*\bAUTOINCREMENT\b/gi, "");
+          .split(/\bAUTOINCREMENT\b/gi).map((part, index, parts) => index < parts.length - 1 ? part.trimEnd() : part).join("");
       case "mssql":
         return sql.replace(/AUTOINCREMENT/gi, "IDENTITY(1,1)");
       case "firebird":
-        return sql.replace(/\s*AUTOINCREMENT\b/gi, "");
+        return sql.split(/\bAUTOINCREMENT\b/gi).map((part, index, parts) => index < parts.length - 1 ? part.trimEnd() : part).join("");
       default:
         return sql;
     }
@@ -322,18 +330,105 @@ export class SQLTranslator {
    */
   static placeholderStyle(sql: string, style: string): string {
     if (style === "%s") {
-      return sql.replace(/\?/g, "%s");
+      // A pyformat driver (psycopg, PyMySQL) reads EVERY `%` as the start of a
+      // placeholder once parameters are passed, literals included, so a literal
+      // `%` is doubled before the real `?` markers become `%s` (tina4-python#138).
+      const doubled = sql.replace(/%/g, "%%");
+      return SQLTranslator.replacePlaceholders(doubled, () => "%s");
     }
     if (style.startsWith(":")) {
-      let count = 0;
-      return sql.replace(/\?/g, () => {
-        count++;
-        return `:${count}`;
-      });
+      return SQLTranslator.replacePlaceholders(sql, (i) => `:${i + 1}`);
     }
     return sql;
   }
 
+  /**
+   * Offsets of the REAL `?` placeholders in a statement: every `?` that is not
+   * inside a string literal ('...', Postgres E'...', dollar-quoted $$...$$ /
+   * $tag$...$tag$), a quoted identifier ("..." or `...`), or a comment (-- to
+   * end of line, /* ... *\/). A plain text replace turned the `?` in
+   * `SELECT 'why?' AS v, ? AS n` into a placeholder and shifted every binding
+   * after it (tina4-python#138).
+   *
+   * @param sql Raw SQL, exactly as the caller wrote it.
+   * @param options.backslashEscapes Treat `\` as an escape inside '...' and
+   *   "..." as well (MySQL's default string syntax). E'...' always does.
+   */
+  static placeholderPositions(sql: string, options: { backslashEscapes?: boolean } = {}): number[] {
+    const positions: number[] = [];
+    const n = sql.length;
+    const isIdent = (ch: string | undefined): boolean => !!ch && /[A-Za-z0-9_]/.test(ch);
+    let i = 0;
+    while (i < n) {
+      const c = sql[i];
+      const next = sql[i + 1];
+
+      if (c === "'" || c === '"' || c === "`") {
+        // E'...' (Postgres escape string) honours backslash escapes; so does
+        // every quoted string when the engine does (MySQL).
+        const prev = sql[i - 1];
+        const escapeString = c === "'" && (prev === "E" || prev === "e") && !isIdent(sql[i - 2]);
+        const backslash = c !== "`" && (escapeString || options.backslashEscapes === true);
+        i++;
+        while (i < n) {
+          if (backslash && sql[i] === "\\") { i += 2; continue; }
+          if (sql[i] === c) {
+            if (sql[i + 1] === c) { i += 2; continue; }
+            i++;
+            break;
+          }
+          i++;
+        }
+        continue;
+      }
+
+      if (c === "-" && next === "-") {
+        while (i < n && sql[i] !== "\n") i++;
+        continue;
+      }
+
+      if (c === "/" && next === "*") {
+        const end = sql.indexOf("*/", i + 2);
+        i = end === -1 ? n : end + 2;
+        continue;
+      }
+
+      if (c === "$" && !isIdent(sql[i - 1])) {
+        const tag = sql.slice(i).match(/^\$([A-Za-z_][A-Za-z0-9_]*)?\$/);
+        if (tag) {
+          const end = sql.indexOf(tag[0], i + tag[0].length);
+          i = end === -1 ? n : end + tag[0].length;
+          continue;
+        }
+      }
+
+      if (c === "?") positions.push(i);
+      i++;
+    }
+    return positions;
+  }
+
+  /**
+   * Replace each REAL `?` placeholder (see placeholderPositions) with
+   * `marker(index)`, index counting from 0. Literals, quoted identifiers and
+   * comments are copied through untouched.
+   */
+  static replacePlaceholders(
+    sql: string,
+    marker: (index: number) => string,
+    options: { backslashEscapes?: boolean } = {},
+  ): string {
+    const positions = SQLTranslator.placeholderPositions(sql, options);
+    if (positions.length === 0) return sql;
+    let out = "";
+    let last = 0;
+    positions.forEach((pos, index) => {
+      out += sql.slice(last, pos) + marker(index);
+      last = pos + 1;
+    });
+    return out + sql.slice(last);
+  }
+
   /**
    * Detect and strip RETURNING clause from INSERT/UPDATE statements.
    * Returns the cleaned SQL and the list of RETURNING columns.
@@ -607,6 +702,88 @@ export class SQLTranslator {
     return re.test(SQLTranslator.scrubSqlText(sql));
   }
 
+  /**
+   * Strip a trailing TOP-LEVEL `ORDER BY` so the statement can be wrapped in
+   * `SELECT COUNT(*) FROM (<sql>) AS _count_query` for the row-count probe.
+   *
+   * SQL Server rejects an ORDER BY inside a derived table unless it carries
+   * TOP/OFFSET/FETCH (error 1033), so the probe failed - and the total fell
+   * back to the page length - for any read ending in ORDER BY. ORDER BY cannot
+   * change a COUNT, so dropping it for the probe ONLY is safe; the paginated
+   * query keeps it. An ORDER BY nested in a subquery, or one already legalised
+   * by a following OFFSET/FETCH/FOR, is left intact. Positions are found on the
+   * scrubbed text, so an `ORDER BY` inside a literal or comment is ignored.
+   * Parity with Python `_strip_trailing_order_by` / PHP `stripTrailingOrderBy`.
+   *
+   * @param sql The read statement the probe is about to wrap.
+   */
+  static stripTrailingOrderBy(sql: string): string {
+    const scrubbed = SQLTranslator.scrubSqlText(sql ?? "");
+    const re = /\bORDER\s+BY\b/gi;
+    let lastTopLevel = -1;
+    for (let m = re.exec(scrubbed); m; m = re.exec(scrubbed)) {
+      const before = scrubbed.slice(0, m.index);
+      const balancedBefore = (before.match(/\(/g)?.length ?? 0) === (before.match(/\)/g)?.length ?? 0);
+      let depth = 0;
+      let balancedAfter = true;
+      for (const ch of scrubbed.slice(m.index)) {
+        if (ch === "(") depth++;
+        else if (ch === ")" && --depth < 0) { balancedAfter = false; break; }
+      }
+      if (balancedBefore && balancedAfter) lastTopLevel = m.index;
+    }
+    if (lastTopLevel === -1) return sql;
+    if (/\b(?:OFFSET|FETCH|FOR)\b/i.test(scrubbed.slice(lastTopLevel))) return sql;
+    return sql.slice(0, lastTopLevel).trimEnd();
+  }
+
+  /**
+   * True when the statement CHANGES data, even though it may return rows.
+   *
+   * fetch()/fetchOne() are the natural way to run a write that RETURNS rows
+   * (`INSERT ... RETURNING id`, SQL Server's `OUTPUT inserted.id`), so they
+   * cannot treat every statement as a read (tina4-python#133). A write is one
+   * whose first word is a DML verb, or a `WITH` whose body holds one (a
+   * data-modifying CTE ends in SELECT). The shared cross-framework contract:
+   * a write through fetch/fetchOne runs exactly once, with no COUNT probe and
+   * no LIMIT/OFFSET/ROWS/TOP pagination, is never cached, and commits like
+   * execute(). Python's `_is_write_statement` answers identically.
+   *
+   * Literals and comments are scrubbed first, so `WHERE note = 'DELETE'` stays
+   * a read. Erring towards "write" is the safe direction: a read misread as a
+   * write only loses its pagination and cache for that one call.
+   *
+   * @param sql Raw SQL, exactly as the caller wrote it.
+   */
+  static isWriteStatement(sql: string): boolean {
+    const scrubbed = SQLTranslator.scrubSqlText(sql ?? "").replace(/^[\s(]+/, "");
+    const verb = (scrubbed.match(/^[A-Za-z]+/)?.[0] ?? "").toUpperCase();
+    if (["INSERT", "UPDATE", "DELETE", "MERGE", "UPSERT", "REPLACE"].includes(verb)) return true;
+    if (verb === "WITH") return /\b(INSERT|UPDATE|DELETE|MERGE)\b/i.test(scrubbed);
+    return false;
+  }
+
+  /**
+   * Which kind of rows a statement produces, for execute() (cross-framework
+   * contract): "read" (SELECT, WITH ... SELECT, VALUES, SHOW, EXPLAIN,
+   * DESCRIBE), "returning" (a write with RETURNING, or SQL Server's OUTPUT
+   * inserted./deleted.), "procedure" (CALL / EXEC / EXECUTE, which may return a
+   * result set), or null for a statement that produces none. A data-modifying
+   * CTE (WITH ... INSERT ... SELECT) produces rows too, so it is "read" here and
+   * a write for isWriteStatement(). Literals and comments are scrubbed first.
+   *
+   * @param sql Raw SQL, exactly as the caller wrote it.
+   */
+  static rowsKind(sql: string): "read" | "returning" | "procedure" | null {
+    const scrubbed = SQLTranslator.scrubSqlText(sql ?? "").replace(/^[\s(]+/, "");
+    const verb = (scrubbed.match(/^[A-Za-z]+/)?.[0] ?? "").toUpperCase();
+    if (["SELECT", "WITH", "VALUES", "SHOW", "EXPLAIN", "DESCRIBE"].includes(verb)) return "read";
+    if (["CALL", "EXEC", "EXECUTE"].includes(verb)) return "procedure";
+    if (SQLTranslator.isWriteStatement(sql)
+      && /\bRETURNING\b|\bOUTPUT\s+(INSERTED|DELETED)\./i.test(scrubbed)) return "returning";
+    return null;
+  }
+
   /**
    * Append `LIMIT`/`OFFSET` to a statement unless it already carries its own.
    *

package/packages/orm/src/types.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 export type FieldType = "string" | "integer" | "number" | "numeric" | "decimal" | "boolean" | "datetime" | "text" | "json" | "foreignKey" | "point";
 
 export interface FieldDefinition {
@@ -119,6 +127,13 @@ export interface DatabaseAdapter {
   /** Return the canonical, credential-free engine name ("sqlite", "postgres", ...). */
   getDatabaseType(): string;
 
+  /**
+   * Quote a table/column name the ORM emits, in this engine's dialect
+   * (Python master: `quote_identifier`). Optional: an adapter without it gets
+   * the ANSI `"name"` default through `quoteIdentifier(adapter, name)`.
+   */
+  quoteIdentifier?(name: string): string;
+
   /** Execute a statement (INSERT, UPDATE, DELETE, DDL). */
   execute(sql: string, params?: unknown[]): unknown;
 

package/packages/orm/src/validation.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 import type { FieldDefinition } from "./types.js";
 
 export interface ValidationError {

package/packages/swagger/src/generator.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 import type { RouteDefinition } from "../../core/src/index.js";
 import type { ModelDefinition, FieldDefinition } from "../../orm/src/index.js";
 

package/packages/swagger/src/index.ts

@@ -1,2 +1,10 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 export { generate, addSecurityScheme, addSchema, resetRegistry } from "./generator.js";
 export { createSwaggerRoutes, swaggerEnabled } from "./ui.js";

package/packages/swagger/src/ui.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 import type { Tina4Request, Tina4Response, RouteDefinition } from "../../core/src/index.js";
 
 // The UI assets load from a CDN by default (a documented architecture decision —

package/types/core/src/api.d.ts

@@ -121,6 +121,11 @@ export interface ApiOptions {
      * persisted; scoped to this instance.
      */
     cookies?: boolean;
+    /**
+     * SSRF guard (ADR-0084): an explicit allow-list of hosts / host:port / CIDRs
+     * that bypass the private-address refusal even with the opt-out off.
+     */
+    allowHosts?: string[];
 }
 /**
  * Split an async byte iterable into UTF-8 lines. Handles LF and CRLF; a
@@ -155,6 +160,7 @@ export declare class Api {
     private transportFn?;
     private cookiesEnabled;
     private cookies;
+    private allowHosts;
     /**
      * Construct an Api client.
      *

package/types/core/src/auth.d.ts

@@ -1,4 +1,34 @@
 import type { Middleware } from "./types.js";
+/**
+ * Token purposes that are never an identity (ADR-0079 s1). Frond's formToken()
+ * signs a JWT with the same TINA4_SECRET as an auth token, marked
+ * `type: "form"`. A form token proves where a write came from, never who the
+ * caller is, so every identity gate refuses these purposes. validToken itself
+ * stays purpose-neutral: the CSRF middleware needs it for form tokens.
+ */
+export declare const NON_IDENTITY_TOKEN_TYPES: readonly string[];
+/**
+ * Minimum HMAC key length in bytes (ADR-0079 s2): the HS256 output size, RFC
+ * 7518 s3.2. A blank key is the shortest case - anyone can reproduce it.
+ */
+export declare const MIN_SECRET_BYTES = 32;
+/**
+ * True when a VERIFIED payload may stand for a caller's identity. A payload
+ * whose `type` is a reserved non-identity purpose (a Frond form token) is
+ * refused; application payloads are otherwise untouched.
+ */
+export declare function isIdentityPayload(payload: Record<string, unknown> | null | undefined): payload is Record<string, unknown>;
+/** The actionable error for a weak HMAC key, or null when the key is usable. */
+export declare function insecureSecretMessage(secret: string | undefined | null): string | null;
+/**
+ * Refuse to boot with a secret that makes tokens forgeable (ADR-0079 s2).
+ * Outside dev a blank TINA4_SECRET is refused; in any mode a set-but-short one
+ * is refused. Dev with a blank secret has already had one minted into
+ * .env.local by ensureDevSecret(). RS256 keys are PEMs and are not measured.
+ *
+ * @throws Error with the actionable message naming TINA4_SECRET.
+ */
+export declare function requireBootSecret(): void;
 /**
  * Ensure a usable TINA4_SECRET exists. Run ONCE at server boot, after env load
  * and before auth is used. Mirrors Python's `ensure_dev_secret()`.

package/types/core/src/background.d.ts

@@ -1,19 +1,3 @@
-/**
- * Background tasks — periodic callbacks that run alongside the HTTP server.
- *
- * Mirrors Python's `tina4_python.core.server.background(fn, interval=1.0)`.
- * Use this instead of `setInterval` directly, so timers integrate with the
- * server lifecycle and clear cleanly on graceful shutdown (SIGTERM/SIGINT)
- * or when `stopAllBackgroundTasks()` is called.
- *
- *   import { background } from "@tina4/core";
- *
- *   background(() => processQueue(), 2);          // every 2 seconds
- *   background(async () => await healthCheck(), 30);  // async also fine
- *
- * Errors thrown from a callback are caught and logged so a single failing
- * task cannot bring down the rest of the timer wheel.
- */
 /**
  * Register a callback to run periodically alongside the HTTP server.
  *

package/types/core/src/cache.d.ts

@@ -102,6 +102,12 @@ interface CacheBackend {
     /** One-time async connect/probe. Resolves once the backend has decided
      *  availability; createBackend() awaits this before falling back to file. */
     ready?(): Promise<void>;
+    /**
+     * When unavailable because the app has not installed the backend's driver
+     * (an optional peer, ADR-0067): the actionable install message, appended to
+     * the fallback warning. null for every other cause.
+     */
+    missingDriver?(): string | null;
 }
 /** Public shape of a unified cache backend (for cross-package reuse). */
 export type { CacheBackend };

package/types/core/src/devAdmin.d.ts

@@ -1,13 +1,3 @@
-/**
- * Tina4 Dev Admin — Built-in development dashboard, zero dependencies.
- *
- * Auto-registered admin panel for development mode.
- * Provides API endpoints and a single-page UI at /__dev/ for:
- *   - Route inspector (all registered routes, methods)
- *   - Message log (tracked debug messages)
- *   - Request inspector (captured HTTP requests)
- *   - System info (Node.js version, V8, memory, uptime, platform)
- */
 import type { Router } from "./router.js";
 import type { RouteHandler, Tina4Request } from "./types.js";
 /** Safe HTTP methods that never carry a state change — they skip the write gate. */
@@ -17,8 +7,8 @@ export declare const DEV_SAFE_METHODS: Set<string>;
  *
  * 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).
+ *   - Sec-Fetch-Site present -> only same-origin (the dashboard itself) and
+ *     none (a typed URL) pass; same-site is a different origin (ADR-0082).
  *   - 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
@@ -38,6 +28,22 @@ export declare function devMutationDenial(req: Tina4Request): {
     status: number;
     error: string;
 } | null;
+/**
+ * True when a Host header names the loopback machine or the configured
+ * TINA4_HOST (ADR-0082), so a rebound DNS name cannot reach /__dev. A missing
+ * Host is not a browser request (every browser sends one); the peer gate
+ * governs it instead.
+ */
+export declare function devHostAllowed(hostHeader: string | undefined | null): boolean;
+/**
+ * Return `{status, error}` to REFUSE any /__dev request (read or write), or
+ * `null` to allow (ADR-0082): Host allow-list, then same-origin, then the
+ * loopback peer (the MCP surface keeps its own 404 gate for the peer part).
+ */
+export declare function devRequestDenial(req: Tina4Request): {
+    status: number;
+    error: string;
+} | null;
 /**
  * True when `rel` names secret material the file endpoints must never serve
  * (DEVADMIN-DEC-03): `.env` / `.env.*` (the `.env.example` template is allowed),

package/types/core/src/docs.d.ts

@@ -1,20 +1,3 @@
-/**
- * Tina4 Live API RAG — `Docs` module.
- *
- * Walks framework packages (`@tina4/core`, `@tina4/orm`, `@tina4/swagger`,
- * `@tina4/frond`) and the user project's `src/` tree via lightweight TS
- * regex parsing (no AST — works on .ts files without importing them, so
- * user-code import errors don't break reflection).
- *
- * Exposes ranked search, class/method specs, a flat index, MCP-style
- * static mirrors, and a Markdown drift/sync helper. Zero new runtime
- * dependencies — Node stdlib only.
- *
- * Spec: plan/v3/22-LIVE-API-RAG.md
- *
- * Method names follow Tina4 Node.js convention (camelCase) — see PHP
- * `Tina4\Docs` and Python `tina4_python.docs.Docs` for parity references.
- */
 export interface DocsHit {
     fqn: string;
     kind: "class" | "method" | "function" | "property";

package/types/core/src/errorOverlay.d.ts

@@ -1,27 +1,3 @@
-/**
- * Tina4 Debug — Rich error overlay for development mode.
- *
- * 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, isDebugMode } from "./errorOverlay.js";
- *
- *   try {
- *     await handler(req, res);
- *   } catch (err) {
- *     if (isDebugMode()) res.html(renderErrorOverlay(err as Error, req), 500);
- *   }
- *
- * 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.
- */
 /**
  * Render a rich HTML error overlay.
  *

package/types/core/src/events.d.ts

@@ -1,15 +1,3 @@
-/**
- * Tina4 Events — Simple observer pattern for decoupled communication.
- *
- * Zero-dependency event system. Fire events, register listeners.
- *
- *   Events.on("user.created", (user) => console.log(`Welcome ${user.name}!`));
- *   Events.emit("user.created", { name: "Alice", email: "alice@example.com" });
- *
- * One-time listeners:
- *
- *   Events.once("app.ready", () => console.log("App started!"));
- */
 export declare class Events {
     /**
      * Register a listener for an event.

package/types/core/src/feedback.d.ts

@@ -1,26 +1,3 @@
-/**
- * Customer feedback widget — Tier 4 port from tina4-python.
- *
- * End-users of a shipped Tina4 app give UX feedback via a floating bubble
- * widget. Widget visibility + API are gated by TWO env flags:
- *
- *   - TINA4_ENABLE_FEEDBACK   master switch (explicit opt-in)
- *   - TINA4_FEEDBACK_WHITELIST comma-separated emails / user IDs
- *
- * Architecture (mirrors Python `tina4_python/dev_admin/__init__.py`
- * lines 1440-1645):
- *
- *   1. Framework middleware injects <script src="/__feedback/widget.js">
- *      into HTML responses for whitelisted users only.
- *   2. Widget POSTs to /__feedback/api/turn for each conversational turn.
- *   3. That handler verifies whitelist + rate-limit, stamps the user
- *      identity server-side (client cannot fake `sender`), then forwards
- *      to the Rust agent's /feedback/intake.
- *
- * The widget is for END USERS of a shipped app — the /__dev paths get
- * skipped so the dev admin's own chat bubble doesn't sit on top of the
- * customer feedback bubble.
- */
 import type { RouteHandler, Tina4Request } from "./types.js";
 import type { Router } from "./router.js";
 /**

package/types/core/src/graphql.d.ts

@@ -1,24 +1,3 @@
-/**
- * Tina4 GraphQL — Zero-dependency GraphQL engine.
- *
- * Recursive-descent parser, schema builder, and query executor.
- *
- *   import { GraphQL } from "@tina4/core";
- *
- *   const gql = new GraphQL();
- *   gql.addType("User", { id: { type: "ID" }, name: { type: "String" } });
- *   gql.addQuery("user", { id: "ID!" }, "User", (root, args) => getUser(args.id));
- *   const result = gql.execute('{ user(id: "1") { name } }');
- *
- * Supported:
- *   - Queries, mutations
- *   - Variables, default values
- *   - Aliases
- *   - Nested selections
- *   - List types ([Type])
- *   - Non-null types (Type!)
- *   - Error capture (resolver exceptions become GraphQL errors)
- */
 export interface GraphQLField {
     type: string;
     description?: string;
@@ -59,6 +38,16 @@ export declare function graphqlAutoSchemaEnabled(): boolean;
  * set `<= 0` to disable the guard. A non-numeric value falls back to 50.
  */
 export declare function graphqlMaxDepth(): number;
+/**
+ * F2: maximum number of expanded selection nodes a single query may request.
+ * The depth guard bounds NESTING but not WIDTH: a fragment that spreads another
+ * fragment many times (a "fragment bomb") stays shallow while expanding to
+ * millions of fields, and a query with thousands of aliases of one field is not
+ * deep at all. This budget bounds the expanded selection tree (fragments
+ * expanded, aliases counted) so both are rejected before any resolver runs.
+ * `TINA4_GRAPHQL_MAX_NODES` overrides the default (1000); `<= 0` disables it.
+ */
+export declare function graphqlMaxNodes(): number;
 export declare class GraphQL {
     private types;
     private queries;
@@ -74,6 +63,12 @@ export declare class GraphQL {
      * spread / inline fragment, so circular fragments are caught too.
      */
     maxDepth: number;
+    /**
+     * Maximum expanded selection nodes per query (from `TINA4_GRAPHQL_MAX_NODES`,
+     * default 1000; `<= 0` disables). Bounds query WIDTH — fragment bombs and
+     * alias explosions — which the depth guard does not. See {@link graphqlMaxNodes}.
+     */
+    maxNodes: number;
     /**
      * Decorator-style resolver registration.
      *
@@ -145,6 +140,15 @@ export declare class GraphQL {
      * instead of recursing until the interpreter stack overflows. Top-level
      * starts at depth 1; `maxDepth <= 0` disables the guard.
      */
+    /**
+     * Count the expanded selection nodes, throwing {@link ComplexityError} past
+     * `maxNodes` (F2). Fragment spreads are expanded (so a fragment bomb is
+     * counted, not the small unexpanded document) and every field — including
+     * each alias — counts once. The count is capped by `maxNodes` and the walk by
+     * `maxDepth`, so a circular fragment trips the budget instead of looping and
+     * the check itself can never cost more than the budget.
+     */
+    private assertComplexity;
     private resolveSelectionsInto;
     /**
      * Generate SDL schema string.

package/types/core/src/htmlElement.d.ts

@@ -1,18 +1,3 @@
-/**
- * Programmatic HTML builder — avoids string concatenation.
- *
- * Usage:
- *   const el = new HtmlElement("div", { class: "card" }, ["Hello"]);
- *   el.toString();  // '<div class="card">Hello</div>'
- *
- *   // Builder pattern
- *   const el = htmlElement("div")(htmlElement("p")("Text"));
- *
- *   // Helper functions
- *   const h: Record<string, any> = {};
- *   addHtmlHelpers(h);
- *   const html = h._div({ class: "card" }, h._p("Hello"));
- */
 /**
  * Raw — marker for trusted, pre-sanitised HTML that must render UNESCAPED.
  *

package/types/core/src/index.d.ts

@@ -40,6 +40,7 @@ export type { ServiceOptions, ServiceContext, ServiceHandler, ServiceInfo } from
 export { responseCache, clearCache, cacheStats, cacheGet, cacheSet, cacheDelete, cacheClear, cacheBackendStats, sweep, createBackend, _resetBackend } from "./cache.js";
 export type { ResponseCacheConfig, CacheBackend } from "./cache.js";
 export { Api, ApiStreamError, parseLineStream, parseSseStream } from "./api.js";
+export { guardUrl, isBlockedAddress, allowPrivateRequests, SsrfError, ALLOW_PRIVATE_ENV } from "./ssrf.js";
 export type { ApiResult, ApiOptions, ApiTransport, DownloadResult, UploadOptions, StreamOptions, SseEvent } from "./api.js";
 export { Context, defaultContext, existingContext, fts5Supported, _sharedContexts } from "./context/index.js";
 export type { SearchHit } from "./context/index.js";

package/types/core/src/job.d.ts

@@ -31,6 +31,7 @@ export interface JobLifecycle {
 export type QueueJob = JobData & JobLifecycle;
 export interface JobQueueBridge {
     _failJob(topic: string, job: QueueJob, reason: string, maxRetries: number): void;
+    _rejectJob(topic: string, job: QueueJob, reason: string, maxRetries: number): void;
     _retryJob(topic: string, job: QueueJob, delaySeconds?: number): void;
     _completeJob(topic: string, job: QueueJob): void;
     getMaxRetries(): number;