tina4-nodejs 3.13.138 → 3.13.139

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/graphql.d.ts

@@ -38,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;
@@ -53,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.
      *
@@ -124,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/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;

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

@@ -11,6 +11,11 @@ export interface PushOptions {
     privateKey?: string;
     ttl?: number;
     urgency?: "very-low" | "low" | "normal" | "high";
+    /**
+     * SSRF guard (ADR-0084): an explicit allow-list of hosts / host:port / CIDRs
+     * that bypass the private-endpoint refusal even with the opt-out off.
+     */
+    allowHosts?: string[];
 }
 export interface PushResult {
     ok: boolean;

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

@@ -59,7 +59,7 @@ export interface ConsumeOptions {
 export interface QueueBackendInterface {
     push(queue: string, payload: unknown, delay?: number, priority?: number): string;
     pop(queue: string): QueueJob | null;
-    size(queue: string): number;
+    size(queue: string, status?: string): number;
     clear(queue: string): void;
     /**
      * Release whatever connection the backend holds, and be safe to call twice.
@@ -74,6 +74,7 @@ export interface QueueBackendInterface {
     close(): void;
     complete?(queue: string, id: string): void;
     fail?(queue: string, id: string, error: string, maxRetries: number, retryBackoff: number): void;
+    reject?(queue: string, id: string, reason: string, maxRetries: number): void;
     /**
      * Explicit manual re-queue: returns true if the id was found and revived,
      * false otherwise (parity with Python's backend.retry_job()). A backend may
@@ -289,6 +290,11 @@ export declare class Queue {
      * after retryBackoff seconds) or dead-letter (attempts >= maxRetries).
      */
     _failJob(queue: string, job: QueueJob, error: string, maxRetries: number): void;
+    /**
+     * Dead-letter a job immediately — no retry (ADR-0023 reject()). Distinct from
+     * _failJob, which retries until maxRetries is spent.
+     */
+    _rejectJob(queue: string, job: QueueJob, reason: string, maxRetries: number): void;
     /**
      * Re-queue a job back to the main queue directory with incremented attempts.
      */

package/types/core/src/queueBackends/liteBackend.d.ts

@@ -130,5 +130,14 @@ export declare class LiteBackend {
      * dead-letter file -- two spellings of the same intent that previously
      * diverged.
      */
+    /**
+     * Reject a job permanently — dead-letter it NOW, no retry (ADR-0023).
+     *
+     * Unlike failJob(), which requeues until maxRetries is spent, rejectJob()
+     * moves a known-poison job straight to the dead-letter store. attempts is
+     * floored at maxRetries so deadLetters() (attempts >= maxRetries) returns it
+     * and size("dead") agrees.
+     */
+    rejectJob(queue: string, job: QueueJob, reason: string, maxRetries: number): void;
     retryJob(queue: string, job: QueueJob, delaySeconds?: number): void;
 }

package/types/core/src/queueBackends/mongoBackend.d.ts

@@ -76,7 +76,14 @@ export declare class MongoBackend implements QueueBackend {
     popById(queue: string, id: string): QueueJob | null;
     push(queue: string, payload: unknown, delay?: number, priority?: number): string;
     pop(queue: string): QueueJob | null;
-    size(queue: string): number;
+    size(queue: string, status?: string): number;
+    /**
+     * Dead-letter a job immediately — no retry (ADR-0023 reject()). Distinct from
+     * fail(): fail() requeues until maxRetries is spent. attempts is floored at
+     * maxRetries so deadLetters()/size("dead") (which filter/scope to the
+     * dead-letter store) see it.
+     */
+    reject(queue: string, id: string, reason: string, maxRetries: number): void;
     clear(queue: string): void;
     /**
      * Acknowledge a completed job — drop its reservation so the reclaim never

package/types/core/src/sessionHandlers/databaseHandler.d.ts

@@ -86,9 +86,33 @@ export declare class DatabaseSessionHandler implements SessionHandler {
     /** Run a statement that returns nothing. */
     private exec;
     /**
-     * Ensure the session table exists (called once on first use).
+     * Ensure the session table exists (called once on first use) - safely when
+     * several processes race to create it.
+     *
+     * Every per-engine statement above is check-then-act, so two processes can
+     * both find the table absent and both CREATE; the loser errors, and every
+     * engine spells that differently (a pg_type unique violation on PostgreSQL,
+     * Msg 2714 on SQL Server, an RDB$RELATIONS unique violation on Firebird). So
+     * a failure is judged by RE-CHECKING whether the table now exists, never by
+     * parsing the message - the rescue the Firebird note above has always
+     * assumed, and which was not here. MEASURED on the lab before it: six real
+     * processes racing lost one to five of them on PostgreSQL, SQLite and
+     * Firebird.
+     *
+     * The re-check is RETRIED because the loser can fail BEFORE the winner has
+     * committed. On MySQL, CREATE TABLE IF NOT EXISTS takes a shared metadata
+     * lock, checks, then upgrades it to exclusive; two upgrades deadlock, and when
+     * MySQL cannot back the victim off silently it answers 1213 "Deadlock found"
+     * while the winner's table is still invisible (tina4-php CI run 35972320442).
+     * Bounded, so a genuine failure (no CREATE grant) still throws. Same attempts
+     * and delays in all four frameworks.
      */
     private ensureTable;
+    /**
+     * Whether tina4_session exists, asked the one way every engine answers alike:
+     * a query against it that returns no rows succeeds only if it is there.
+     */
+    private tableExists;
     read(sessionId: string): SessionData | null;
     write(sessionId: string, data: SessionData, ttl: number): void;
     destroy(sessionId: string): void;

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

@@ -2,6 +2,7 @@ import type { Router } from "./router.js";
 export declare class SsoError extends Error {
 }
 type Json = Record<string, any>;
+export { liveSessionIdentity } from "./ssoIdentity.js";
 export interface SsoOptions {
     issuer?: string;
     clientId?: string;

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

@@ -0,0 +1,10 @@
+/**
+ * The stored SSO identity, only while it is live (ADR-0079 s5). `stored` is the
+ * reserved _tina4_sso session value. The identity needs an issuer and a
+ * subject, and a numeric expires_at that is 0 (the provider gave no lifetime)
+ * or still in the future.
+ *
+ * Its own dependency-free module, so the auth gate can use it without
+ * importing the OIDC client (and everything the client imports).
+ */
+export declare function liveSessionIdentity(stored: unknown): Record<string, any> | null;

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

@@ -0,0 +1,19 @@
+export declare const ALLOW_PRIVATE_ENV = "TINA4_ALLOW_PRIVATE_REQUESTS";
+/** Raised when the SSRF guard refuses an outbound request. */
+export declare class SsrfError extends Error {
+    constructor(message: string);
+}
+/** True when TINA4_ALLOW_PRIVATE_REQUESTS opts out of the guard. */
+export declare function allowPrivateRequests(): boolean;
+/**
+ * Classify one IP string: true = private/internal, refuse it. An IPv4-mapped
+ * IPv6 address is classified by its embedded IPv4. An unparseable value is
+ * treated as blocked - the guard refuses what it cannot classify.
+ */
+export declare function isBlockedAddress(ip: string): boolean;
+/**
+ * Refuse `url` when it targets a private/internal address. Throws SsrfError for a
+ * non-http(s) scheme, an unresolvable host, or any resolved address in the
+ * blocked space. `allowHosts` is a list of hosts / host:port / CIDRs to permit.
+ */
+export declare function guardUrl(url: string, allowHosts?: string[]): Promise<void>;