tina4-nodejs 3.13.36 → 3.13.38

package/packages/core/src/wsdl.ts

@@ -19,6 +19,9 @@
  *   }
  */
 
+import { Log } from "./logger.js";
+import { isDebugMode } from "./errorOverlay.js";
+
 // ── Types ────────────────────────────────────────────────────
 
 export interface WSDLOperationMeta {
@@ -261,13 +264,27 @@ export abstract class WSDLService {
   private convertValue(value: string, typeName: string): unknown {
     switch (typeName) {
       case "int":
-      case "integer":
-        return parseInt(value, 10);
+      case "integer": {
+        // Match Python's int(value) — a non-numeric value RAISES rather than
+        // silently yielding NaN. The thrown Error is caught in handle() and
+        // becomes a Server fault.
+        const n = parseInt(value, 10);
+        if (Number.isNaN(n)) {
+          throw new Error(`invalid integer value: ${JSON.stringify(value)}`);
+        }
+        return n;
+      }
       case "float":
       case "double":
       case "number":
-      case "numeric":
-        return parseFloat(value);
+      case "numeric": {
+        // Match Python's float(value) — non-numeric raises (→ Server fault).
+        const f = parseFloat(value);
+        if (Number.isNaN(f)) {
+          throw new Error(`invalid numeric value: ${JSON.stringify(value)}`);
+        }
+        return f;
+      }
       case "bool":
       case "boolean":
         return ["true", "1", "yes"].includes(value.toLowerCase());
@@ -389,6 +406,16 @@ export abstract class WSDLService {
   async handle(soapXml: string = ""): Promise<string> {
     const ops = this.discoverOperations();
 
+    // SOAP 1.1 (§3) forbids a Document Type Declaration in a SOAP message.
+    // Rejecting any DOCTYPE/DTD up front — BEFORE the body is parsed — also
+    // closes the XML entity-expansion (billion-laughs) and external-entity
+    // (XXE) attack surface regardless of parser internals. The operation
+    // never runs. (Node's parser is hand-rolled and already immune; this is
+    // defence in depth + consistent fault behaviour across all 4 frameworks.)
+    if (/<!DOCTYPE/i.test(soapXml)) {
+      return this.soapFault("Client", "DOCTYPE declarations are not allowed in SOAP messages");
+    }
+
     // Parse SOAP body
     const body = extractSoapBody(soapXml);
     if (!body) {
@@ -413,33 +440,40 @@ export abstract class WSDLService {
       return this.soapFault("Client", `Operation not implemented: ${opName}`);
     }
 
-    // Extract parameters from the operation element
-    const children = extractChildren(operation.content);
-    const params: unknown[] = [];
-
-    if (opMeta.input) {
-      for (const [paramName, paramType] of Object.entries(opMeta.input)) {
-        const child = children.find((c) => c.name === paramName);
-        if (child) {
-          params.push(this.convertValue(child.value, paramType));
-        } else {
-          params.push(null);
-        }
-      }
-    }
-
     // Lifecycle hook: before invocation
     this.onRequest(soapXml);
 
-    // Invoke the method
+    // Invoke the method. Parameter conversion runs INSIDE the try so a
+    // non-numeric value for an int/float param (convertValue throws, matching
+    // Python's int()/float() raise) becomes a Server fault — not a silent NaN.
     try {
+      // Extract parameters from the operation element
+      const children = extractChildren(operation.content);
+      const params: unknown[] = [];
+
+      if (opMeta.input) {
+        for (const [paramName, paramType] of Object.entries(opMeta.input)) {
+          const child = children.find((c) => c.name === paramName);
+          if (child) {
+            params.push(this.convertValue(child.value, paramType));
+          } else {
+            params.push(null);
+          }
+        }
+      }
+
       const rawResult = await (method as (...args: unknown[]) => Promise<unknown>).call(this, ...params);
       // Lifecycle hook: after invocation — allow result transformation
       const result = this.onResult(rawResult as Record<string, unknown>);
       return this.soapResponse(opName, result);
     } catch (err) {
+      // Log the real cause, but only leak the detail to the client in debug
+      // mode — a resolver exception can carry internal state (DB credentials,
+      // file paths) that must not reach a SOAP client.
       const errMsg = err instanceof Error ? err.message : String(err);
-      return this.soapFault("Server", errMsg);
+      Log.error(`WSDL operation '${opName}' failed: ${errMsg}`);
+      const detail = isDebugMode() ? errMsg : "Internal server error";
+      return this.soapFault("Server", detail);
     }
   }
 

package/packages/orm/src/adapters/pg-types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Minimal ambient type surface for the optional `pg` (node-postgres) peer
+ * dependency. `@types/pg` is intentionally NOT a dependency (pg is an optional
+ * peer loaded lazily via createRequire), so without this declaration the
+ * `typeof import("pg")` references in postgres.ts resolve to an *implicit* any
+ * (TS7016) and collapse `this.client` to `never`.
+ *
+ * This declares only the subset of the pg API that the PostgresAdapter uses:
+ * the `Client` class (connect/query/end) and the global `types.setTypeParser`
+ * registry. It carries no runtime weight — purely a compile-time contract that
+ * matches node-postgres' real shape.
+ */
+declare module "pg" {
+  export interface QueryResultRow {
+    [column: string]: unknown;
+  }
+
+  export interface QueryResult<R extends QueryResultRow = QueryResultRow> {
+    rows: R[];
+    rowCount: number | null;
+    command: string;
+    oid: number;
+    fields: unknown[];
+  }
+
+  export interface ClientConfig {
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    database?: string;
+    connectionString?: string;
+  }
+
+  export class Client {
+    constructor(config?: ClientConfig | string);
+    connect(): Promise<void>;
+    query<R extends QueryResultRow = QueryResultRow>(
+      queryText: string,
+      values?: unknown[],
+    ): Promise<QueryResult<R>>;
+    end(): Promise<void>;
+  }
+
+  export class Pool {
+    constructor(config?: ClientConfig | string);
+    connect(): Promise<Client>;
+    query<R extends QueryResultRow = QueryResultRow>(
+      queryText: string,
+      values?: unknown[],
+    ): Promise<QueryResult<R>>;
+    end(): Promise<void>;
+  }
+
+  export interface TypeParsers {
+    setTypeParser(oid: number, parseFn: (value: string) => unknown): void;
+  }
+
+  export const types: TypeParsers;
+}

package/packages/orm/src/adapters/postgres.ts

@@ -86,7 +86,13 @@ export class PostgresAdapter implements DatabaseAdapter {
     await this.client!.connect();
   }
 
-  private ensureConnected(): asserts this is { client: NonNullable<PostgresAdapter["client"]> } {
+  // NOTE: a plain runtime guard, not an `asserts this is ...` predicate. A
+  // type-narrowing predicate that re-declares the private `client` member
+  // intersects the class with a structural literal and collapses `this` to
+  // `never` (TS treats the private brand as unsatisfiable). The non-null
+  // `this.client!` assertions at the (already-guarded) call sites carry the
+  // narrowing instead, so behaviour is unchanged.
+  private ensureConnected(): void {
     if (!this.client) {
       throw new Error("PostgreSQL adapter not connected. Call connect() first.");
     }
@@ -107,6 +113,22 @@ export class PostgresAdapter implements DatabaseAdapter {
     });
   }
 
+  /**
+   * Normalise an `id` column value (typed `unknown` because pg row values are
+   * `unknown`) into the `number | bigint | null` shape `_lastInsertId` /
+   * `DatabaseResult.lastInsertId` expect. At runtime PG returns numeric PKs as
+   * number/bigint (the int8/numeric type parsers above coerce them to Number);
+   * a numeric string is coerced, anything else (null/undefined/non-numeric)
+   * becomes null.
+   */
+  private normalizeId(value: unknown): number | bigint | null {
+    if (typeof value === "number" || typeof value === "bigint") return value;
+    if (typeof value === "string" && value.trim() !== "" && !Number.isNaN(Number(value))) {
+      return Number(value);
+    }
+    return null;
+  }
+
   execute(sql: string, params?: unknown[]): unknown {
     this.ensureConnected();
     const convertedSql = this.convertPlaceholders(sql);
@@ -139,7 +161,7 @@ export class PostgresAdapter implements DatabaseAdapter {
     const convertedSql = this.convertPlaceholders(sql);
     const result = await this.client!.query(convertedSql, params);
     if (result.rows?.[0]?.id !== undefined) {
-      this._lastInsertId = result.rows[0].id;
+      this._lastInsertId = this.normalizeId(result.rows[0].id);
     }
     return result;
   }
@@ -194,12 +216,12 @@ export class PostgresAdapter implements DatabaseAdapter {
     try {
       const result = await this.client!.query(sql, values);
       const insertedRow = result.rows[0];
-      const id = insertedRow?.id ?? null;
+      const id = this.normalizeId(insertedRow?.id);
       if (id !== null) this._lastInsertId = id;
       return {
         success: true,
         rowsAffected: result.rowCount ?? 1,
-        lastInsertId: id,
+        lastInsertId: id ?? undefined,
       };
     } catch (e) {
       return { success: false, rowsAffected: 0, error: (e as Error).message };

package/packages/orm/src/adapters/sqlite.ts

@@ -9,6 +9,45 @@ function isIdentifier(str: string): boolean {
   return /^[A-Za-z_][A-Za-z0-9_]*$/.test(str);
 }
 
+/**
+ * The value shape `node:sqlite` binds as a statement parameter. Mirrors the
+ * module-internal `SQLInputValue` type (which is not exported from
+ * `node:sqlite`, so it cannot be imported). The DatabaseAdapter interface
+ * carries params as `unknown[]`; this narrows them to the bindable shape at the
+ * `.run()`/`.all()`/`.get()` call sites without an `any` cast.
+ */
+type SqlParam = null | number | bigint | string | NodeJS.ArrayBufferView;
+
+/** Narrow adapter-level `unknown[]` params to node:sqlite's bindable type. */
+function toSqlParams(params: readonly unknown[]): SqlParam[] {
+  return params as SqlParam[];
+}
+
+/**
+ * Whether the linked SQLite library is at least the given version.
+ *
+ * Used to gate `UPDATE ... RETURNING` (SQLite >= 3.35) in the atomic
+ * sequence path. Memoised — the version never changes at runtime.
+ */
+let _sqliteVersionInfo: [number, number, number] | null = null;
+function sqliteVersionAtLeast(major: number, minor: number, patch: number): boolean {
+  if (_sqliteVersionInfo === null) {
+    try {
+      const probe = new DatabaseSync(":memory:");
+      const row = probe.prepare("SELECT sqlite_version() AS v").get() as { v?: string };
+      probe.close();
+      const parts = String(row?.v ?? "0.0.0").split(".").map((n) => parseInt(n, 10) || 0);
+      _sqliteVersionInfo = [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0];
+    } catch {
+      _sqliteVersionInfo = [0, 0, 0];
+    }
+  }
+  const [ma, mi, pa] = _sqliteVersionInfo;
+  if (ma !== major) return ma > major;
+  if (mi !== minor) return mi > minor;
+  return pa >= patch;
+}
+
 /**
  * Resolve a SQLite path argument against the project root (cwd).
  *
@@ -55,7 +94,7 @@ export class SQLiteAdapter implements DatabaseAdapter {
 
   execute(sql: string, params?: unknown[]): unknown {
     const stmt = this.db.prepare(sql);
-    const result = params ? stmt.run(...params) : stmt.run();
+    const result = params ? stmt.run(...toSqlParams(params)) : stmt.run();
     if (result && typeof result === "object" && "lastInsertRowid" in result) {
       this._lastInsertId = result.lastInsertRowid as number | bigint;
     }
@@ -70,8 +109,8 @@ export class SQLiteAdapter implements DatabaseAdapter {
     this.db.exec("BEGIN TRANSACTION");
     try {
       for (const params of paramsList) {
-        const result = stmt.run(...params);
-        totalAffected += result.changes;
+        const result = stmt.run(...toSqlParams(params));
+        totalAffected += Number(result.changes);
         if (result.lastInsertRowid) {
           lastId = result.lastInsertRowid;
           this._lastInsertId = result.lastInsertRowid;
@@ -88,7 +127,7 @@ export class SQLiteAdapter implements DatabaseAdapter {
 
   query<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[] {
     const stmt = this.db.prepare(sql);
-    return (params ? stmt.all(...params) : stmt.all()) as T[];
+    return (params ? stmt.all(...toSqlParams(params)) : stmt.all()) as T[];
   }
 
   fetch<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): T[] {
@@ -108,7 +147,7 @@ export class SQLiteAdapter implements DatabaseAdapter {
 
   fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null {
     const stmt = this.db.prepare(sql);
-    const row = params ? stmt.get(...params) : stmt.get();
+    const row = params ? stmt.get(...toSqlParams(params)) : stmt.get();
     return (row as T) ?? null;
   }
 
@@ -129,9 +168,9 @@ export class SQLiteAdapter implements DatabaseAdapter {
     const values = Object.values(data);
 
     try {
-      const result = this.db.prepare(sql).run(...values);
+      const result = this.db.prepare(sql).run(...toSqlParams(values));
       this._lastInsertId = result.lastInsertRowid;
-      return { success: true, rowsAffected: result.changes, lastInsertId: result.lastInsertRowid };
+      return { success: true, rowsAffected: Number(result.changes), lastInsertId: result.lastInsertRowid };
     } catch (e) {
       return { success: false, rowsAffected: 0, error: (e as Error).message };
     }
@@ -144,8 +183,8 @@ export class SQLiteAdapter implements DatabaseAdapter {
     const values = [...Object.values(data), ...Object.values(filter)];
 
     try {
-      const result = this.db.prepare(sql).run(...values);
-      return { success: true, rowsAffected: result.changes };
+      const result = this.db.prepare(sql).run(...toSqlParams(values));
+      return { success: true, rowsAffected: Number(result.changes) };
     } catch (e) {
       return { success: false, rowsAffected: 0, error: (e as Error).message };
     }
@@ -164,8 +203,8 @@ export class SQLiteAdapter implements DatabaseAdapter {
     if (typeof filter === "string") {
       const sql = filter ? `DELETE FROM "${table}" WHERE ${filter}` : `DELETE FROM "${table}"`;
       try {
-        const result = this.db.prepare(sql).run(...(params ?? []));
-        return { success: true, rowsAffected: result.changes };
+        const result = this.db.prepare(sql).run(...toSqlParams(params ?? []));
+        return { success: true, rowsAffected: Number(result.changes) };
       } catch (e) {
         return { success: false, rowsAffected: 0, error: (e as Error).message };
       }
@@ -176,8 +215,8 @@ export class SQLiteAdapter implements DatabaseAdapter {
     const values = Object.values(filter);
 
     try {
-      const result = this.db.prepare(sql).run(...values);
-      return { success: true, rowsAffected: result.changes };
+      const result = this.db.prepare(sql).run(...toSqlParams(values));
+      return { success: true, rowsAffected: Number(result.changes) };
     } catch (e) {
       return { success: false, rowsAffected: 0, error: (e as Error).message };
     }
@@ -233,6 +272,66 @@ export class SQLiteAdapter implements DatabaseAdapter {
   lastInsertId(): number | bigint | null { return this._lastInsertId; }
   close(): void { this.db.close(); }
 
+  /**
+   * Atomically increment and return the next value of a tina4_sequences row.
+   *
+   * DB-contract B (no duplicate primary keys under concurrency): the old
+   * read-increment-read path in Database.sequenceNext() yields at every `await`
+   * between the read and the write, so two concurrent async callers can read the
+   * same `current_value` and return the same id. This method runs the WHOLE
+   * operation — ensure-table, seed-if-absent, and the increment-and-return — as
+   * ONE synchronous burst on the single shared `node:sqlite` connection. Because
+   * `node:sqlite` is synchronous and JavaScript is single-threaded, no other
+   * async task can interleave between the statements (there is no `await`
+   * inside), so the increment is atomic and every caller gets a distinct id.
+   * This is the Node analog of the Python master holding SQLiteAdapter._write_lock
+   * across the whole op.
+   *
+   * On SQLite >= 3.35 a single `UPDATE ... SET current_value = current_value + 1
+   * ... RETURNING current_value` is itself atomic and returns the new value in
+   * one statement (read via prepare().all() — stmt.run() does not surface
+   * RETURNING rows). Older SQLite does `UPDATE ... + 1` then `SELECT`, still
+   * race-safe because both run in the same synchronous burst.
+   *
+   * @throws if the sequence row vanishes mid-increment (never silently returns 1).
+   */
+  sequenceNextSqlite(seqName: string, seedValue: number): number {
+    // Ensure the sequence table exists (idempotent).
+    this.db.exec(
+      "CREATE TABLE IF NOT EXISTS tina4_sequences (" +
+      "seq_name VARCHAR(200) NOT NULL PRIMARY KEY, " +
+      "current_value INTEGER NOT NULL DEFAULT 0)",
+    );
+    // Race-safe seed: INSERT OR IGNORE is a no-op if the row already exists, so
+    // there is never a read-then-insert gap.
+    this.db.prepare(
+      "INSERT OR IGNORE INTO tina4_sequences (seq_name, current_value) VALUES (?, ?)",
+    ).run(seqName, seedValue);
+
+    const supportsReturning = sqliteVersionAtLeast(3, 35, 0);
+    let row: { current_value?: number | bigint } | undefined;
+    if (supportsReturning) {
+      // One atomic increment-and-return.
+      row = this.db.prepare(
+        "UPDATE tina4_sequences SET current_value = current_value + 1 " +
+        "WHERE seq_name = ? RETURNING current_value",
+      ).get(seqName) as { current_value?: number | bigint } | undefined;
+    } else {
+      // Older SQLite (< 3.35, no RETURNING): increment then read. Still
+      // race-safe because both run in the same synchronous burst (no await).
+      this.db.prepare(
+        "UPDATE tina4_sequences SET current_value = current_value + 1 WHERE seq_name = ?",
+      ).run(seqName);
+      row = this.db.prepare(
+        "SELECT current_value FROM tina4_sequences WHERE seq_name = ?",
+      ).get(seqName) as { current_value?: number | bigint } | undefined;
+    }
+    if (!row || row.current_value == null) {
+      throw new Error(`getNextId: sequence row '${seqName}' vanished mid-increment`);
+    }
+    return Number(row.current_value);
+  }
+
   tableExists(name: string): boolean {
     // v3.13.14 (#48): a SQLite "schema" is an ATTACH alias ("extra.widget").
     // Query that database's own sqlite_master when the prefix is a plain

package/packages/orm/src/baseModel.ts

@@ -1086,7 +1086,10 @@ export class BaseModel {
 
     const related = new relatedClass(rows[0] as Record<string, unknown>) as R;
     const relKey = relatedClass.tableName.toLowerCase();
-    this[relKey] = related;
+    // Write through the BaseModel index signature: a generic `T` cannot be
+    // indexed for writing (TS2862), but `T extends BaseModel` guarantees `this`
+    // is a BaseModel, whose `[key: string]: unknown` signature is writable.
+    (this as BaseModel)[relKey] = related;
     return related;
   }
 
@@ -1118,7 +1121,8 @@ export class BaseModel {
     const rows = await adapterQuery(db, sql, [pkValue]);
     const related = rows.map((row) => new relatedClass(row as Record<string, unknown>) as R);
     const relKey = relatedClass.tableName.toLowerCase();
-    this[relKey] = related;
+    // See hasOne: write through BaseModel's writable index signature (TS2862).
+    (this as BaseModel)[relKey] = related;
     return related;
   }
 
@@ -1153,7 +1157,8 @@ export class BaseModel {
 
     const related = new relatedClass(rows[0] as Record<string, unknown>) as R;
     const relKey = relatedClass.tableName.toLowerCase();
-    this[relKey] = related;
+    // See hasOne: write through BaseModel's writable index signature (TS2862).
+    (this as BaseModel)[relKey] = related;
     return related;
   }
 

package/packages/orm/src/cachedDatabase.ts

@@ -7,11 +7,14 @@
  *
  * One store, two layers (mirrors the Python master — tina4_python/database/connection.py):
  *
- *   • request-scoped (DEFAULT ON, off-switch TINA4_AUTO_CACHING=false) — dedupes
+ *   • request-scoped (DEFAULT OFF, opt-in TINA4_AUTO_CACHING=true) — dedupes
  *     identical SELECTs to protect the DB from rapid repeat reads. Cleared at the
  *     START of every HTTP request (via Database.resetRequestCaches()) AND on any
  *     write, with a short safety TTL (TINA4_AUTO_CACHING_TTL, default 5s) for
- *     non-request contexts (scripts/workers).
+ *     non-request contexts (scripts/workers). Default OFF because a request-scoped
+ *     cache defaulting ON is a footgun — a read-after-write in one request (e.g.
+ *     SELECT MAX(id) then INSERT) returns a cached pre-write value. Opt in for
+ *     read-heavy endpoints.
  *   • persistent (opt-in, TINA4_DB_CACHE=true) — cross-request TTL cache that is
  *     NOT cleared per request; entries expire by TINA4_DB_CACHE_TTL (default 30s).
  *
@@ -45,7 +48,7 @@ function isTruthy(val: string | undefined): boolean {
 export interface CachedAdapterOptions {
   /** Force-enable the persistent (cross-request) layer. Defaults to TINA4_DB_CACHE. */
   persistent?: boolean;
-  /** Force-enable the request-scoped layer. Defaults to TINA4_AUTO_CACHING (default true). */
+  /** Force-enable the request-scoped layer. Defaults to TINA4_AUTO_CACHING (default false / opt-in). */
   requestScoped?: boolean;
   /** Override the effective TTL (seconds). Defaults to the mode-appropriate env var. */
   ttl?: number;
@@ -65,7 +68,7 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
   private cache: QueryCache;
   /** Persistent (cross-request) layer — TINA4_DB_CACHE. */
   private cachePersistent: boolean;
-  /** Request-scoped layer — TINA4_AUTO_CACHING (default ON). */
+  /** Request-scoped layer — TINA4_AUTO_CACHING (default OFF / opt-in). */
   private cacheRequestScoped: boolean;
   private enabled: boolean;
   private ttl: number;
@@ -94,8 +97,14 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
   constructor(adapter: DatabaseAdapter, options: CachedAdapterOptions = {}) {
     this.adapter = adapter;
     this.cachePersistent = options.persistent ?? isTruthy(process.env.TINA4_DB_CACHE);
-    this.cacheRequestScoped = options.requestScoped
-      ?? (process.env.TINA4_AUTO_CACHING === undefined ? true : isTruthy(process.env.TINA4_AUTO_CACHING));
+    // Request-scoped cache defaults to OFF (opt-in). A request-scoped cache
+    // defaulting ON is a footgun: a `SELECT MAX(id)` (or generator read) right
+    // before an INSERT in the same request returns a cached pre-write value →
+    // duplicate primary keys; any read-after-write in one request shows stale
+    // state. So the DEFAULT is OFF; opt in for read-heavy endpoints with
+    // TINA4_AUTO_CACHING=true. Mirrors the Python master
+    // (tina4_python/database/connection.py: default literal "false").
+    this.cacheRequestScoped = options.requestScoped ?? isTruthy(process.env.TINA4_AUTO_CACHING);
     this.enabled = this.cachePersistent || this.cacheRequestScoped;
 
     if (options.ttl !== undefined) {