tina4-nodejs 3.13.92 → 3.13.95

package/types/cli/src/commands/migrateCreate.d.ts

@@ -0,0 +1 @@
+export declare function createMigration(description?: string): Promise<void>;

package/types/cli/src/commands/migrateRollback.d.ts

@@ -0,0 +1 @@
+export declare function migrateRollback(migrationDir?: string): Promise<void>;

package/types/cli/src/commands/migrateStatus.d.ts

@@ -0,0 +1 @@
+export declare function migrateStatus(migrationDir?: string): Promise<void>;

package/types/cli/src/commands/queue.d.ts

@@ -0,0 +1,20 @@
+/** A per-job handler declared by a consumer module (receives the job payload). */
+export type QueueHandler = (payload: unknown) => unknown | Promise<unknown>;
+/**
+ * Return the per-job handler that a consumer module declares for `topic`.
+ *
+ * A consumer module (e.g. the one `generate queue <topic>` scaffolds) exposes a
+ * default-export config; when its `topic` matches, `queue work` drives the
+ * consumer through that config's per-job `handle` callable — so the worker owns
+ * the poll loop (honouring --poll and the bounded --once drain) instead of the
+ * consumer's own endless loop. Returns the callable, or null when no consumer in
+ * `servicesDir` targets this topic. Mirrors Python's _resolve_queue_handler.
+ */
+export declare function resolveQueueHandler(servicesDir: string, topic: string): Promise<QueueHandler | null>;
+/** Subcommand names, in order — surfaced in `commands --json` for the tina4 client. */
+export declare const QUEUE_SUBCOMMAND_NAMES: string[];
+/**
+ * Top-level queue command: run workers and manage jobs. Dispatches to the
+ * subcommand handlers above; unknown / missing subcommands fail loud (exit 1).
+ */
+export declare function queueCommand(args?: string[]): Promise<void>;

package/types/cli/src/commands/routes.d.ts

@@ -0,0 +1 @@
+export declare function listRoutes(): Promise<void>;

package/types/cli/src/commands/seed.d.ts

@@ -0,0 +1 @@
+export declare function runSeeds(seedPath?: string): Promise<void>;

package/types/cli/src/commands/serve.d.ts

@@ -0,0 +1,6 @@
+export interface ServeOptions {
+    port?: number;
+    noBrowser?: boolean;
+    noReload?: boolean;
+}
+export declare function serveProject(options: ServeOptions): Promise<void>;

package/types/cli/src/commands/test.d.ts

@@ -0,0 +1 @@
+export declare function runTests(testPath?: string): Promise<void>;

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

@@ -0,0 +1,64 @@
+export interface AiTool {
+    name: string;
+    description: string;
+    contextFile: string;
+    configDir: string | null;
+}
+export declare const AI_TOOLS: AiTool[];
+export declare const DEV_SKILL = "tina4-developer-nodejs";
+/**
+ * Install the Tina4 SKILL.md skills into the project AND the global
+ * ~/.claude/skills, fetched from the release ref matching this framework
+ * version. Returns the skills that were fully installed. Network-dependent —
+ * on a fetch failure the skill is skipped, never fatal.
+ */
+export declare function installSkills(root?: string, targets?: string[]): string[];
+/**
+ * Check if a tool's context file already exists.
+ */
+export declare function isInstalled(root: string, tool: AiTool): boolean;
+/**
+ * Print the numbered menu and read user input via readline.
+ * Returns a promise that resolves to the user's selection string.
+ */
+export declare function showMenu(root?: string): Promise<string>;
+/**
+ * Install context files for the selected tools.
+ *
+ * selection: comma-separated numbers like "1,2,3" or "all"
+ * Returns list of created/updated file paths.
+ */
+export declare function installSelected(root: string, selection: string): string[];
+/**
+ * Install context for all AI tools (non-interactive).
+ */
+export declare function installAll(root?: string): string[];
+/** Return [start, end] markers for a context file. */
+export declare function markersFor(contextFile: string): [string, string];
+/** Return the marker-bracketed Tina4 skill registration block. */
+export declare function skillBlock(contextFile: string): string;
+/** True iff both start and end markers appear in order. */
+export declare function hasMarkers(existing: string, start: string, end: string): boolean;
+/** Replace the bracketed block in `existing` with `block`. */
+export declare function replaceMarkerBlock(existing: string, block: string, start: string, end: string): string;
+/**
+ * True if the file starts with a header the pre-v3.13.9 installer
+ * wrote. Used to migrate one-time off the old clobber-style install.
+ */
+export declare function looksLikeOldFrameworkInstall(existing: string): boolean;
+/**
+ * Write the context file non-destructively. Returns a human-readable
+ * action verb for the caller's log line.
+ *
+ * Four branches:
+ *   1. Doesn't exist  \u2192 write framework guide + skill block
+ *   2. Has markers    \u2192 refresh just the skill block (idempotent)
+ *   3. Old header     \u2192 migrate: replace old dump with new guide + block
+ *   4. User content   \u2192 append the skill block, preserve everything else
+ */
+export declare function writeOrMerge(contextPath: string, contextFile: string, frameworkGuide: string): string;
+/**
+ * Generate the Tina4 context document for a specific AI tool.
+ */
+export declare function generateContext(toolName?: string): string;
+export type { AiTool as AiToolType };

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

@@ -0,0 +1,262 @@
+export interface ApiResult {
+    http_code: number | null;
+    body: unknown;
+    headers: Record<string, string>;
+    error: string | null;
+}
+/**
+ * Result of {@link Api.download}. There is no `body` field — the response
+ * body went to disk. `path` is the destination on success and `null` on any
+ * error (missing dest, HTTP error status, transport failure); the file is not
+ * written on error. Keeps `http_code` (snake_case) for parity with
+ * {@link ApiResult} and the Python/PHP/Ruby `download` return.
+ */
+export interface DownloadResult {
+    http_code: number | null;
+    headers: Record<string, string>;
+    error: string | null;
+    path: string | null;
+}
+/**
+ * An injectable transport seam (constructor option `transport`). When supplied
+ * it fully REPLACES the node:http/https network call. Called as
+ * `(method, url, headers, body, timeout)` and must return the same result
+ * shape every verb returns (`{ http_code, body, headers, error }`); may be sync
+ * or async.
+ *
+ * NOTE: Tina4's own test suite must NEVER inject a fake/canned transport — the
+ * no-mock rule stands, so framework tests always exercise the real network path
+ * against a real local server. This seam exists purely so *application*
+ * developers can unit-test code that calls an `Api` instance without a live
+ * server.
+ */
+export type ApiTransport = (method: string, url: string, headers: Record<string, string>, body: Buffer | null, timeout: number) => ApiResult | Promise<ApiResult>;
+/**
+ * Options for {@link Api.upload}. Supply the file EITHER as `filePath` (a file
+ * on disk) OR as `fileBytes` + `filename` (an in-memory payload) — a caller
+ * never needs a temp file.
+ */
+export interface UploadOptions {
+    /** A file on disk. `filename` defaults to its basename. */
+    filePath?: string;
+    /** The form field the file is sent under (default `"file"`). */
+    fieldName?: string;
+    /** Additional text parts of the multipart body. */
+    extraFields?: Record<string, string>;
+    /** Extra per-call headers merged onto the request. */
+    headers?: Record<string, string>;
+    /** An in-memory payload (Buffer or string). Requires `filename` for a name. */
+    fileBytes?: Buffer | string;
+    /** Filename used in the Content-Disposition part header. */
+    filename?: string;
+}
+/**
+ * Constructor options for {@link Api}. Used as the second argument to
+ * `new Api(url, { ... })` — cross-framework parity with Python
+ * `Api(bearer_token=, ...)` kwargs added in 3.13.x.
+ */
+export interface ApiOptions {
+    authHeader?: string;
+    timeout?: number;
+    ignoreSsl?: boolean;
+    /** Positive form of ignoreSsl — `verifySsl: false` disables verification. */
+    verifySsl?: boolean;
+    bearerToken?: string;
+    username?: string;
+    password?: string;
+    headers?: Record<string, string>;
+    /**
+     * Maximum automatic retries on a transient failure (default 0 = off, so
+     * existing callers are unaffected). When > 0, a transport error or a
+     * retryable status (429/5xx) is retried up to this many times with
+     * exponential backoff. NOTE: a retried non-idempotent request (POST/…)
+     * may be re-sent — retries are opt-in for that reason.
+     */
+    maxRetries?: number;
+    /** Base backoff in seconds, doubling each attempt (default 0.5). */
+    retryBackoff?: number;
+    /**
+     * Injectable transport seam (default undefined = the real network path).
+     * When supplied it REPLACES the node:http/https call. See {@link ApiTransport}.
+     * Tina4's own suite never injects it (no-mock rule) — it exists so
+     * application developers can unit-test their own code.
+     */
+    transport?: ApiTransport;
+    /**
+     * Opt-in per-client, in-memory cookie jar (default false = off, zero
+     * behaviour change). When true, `Set-Cookie` response headers are parsed and
+     * the accumulated `Cookie` header is sent on subsequent requests. Not
+     * persisted; scoped to this instance.
+     */
+    cookies?: boolean;
+}
+export declare class Api {
+    private baseUrl;
+    private headers;
+    private timeout;
+    private authHeader;
+    private ignoreSsl;
+    private maxRetries;
+    private retryBackoff;
+    private transportFn?;
+    private cookiesEnabled;
+    private cookies;
+    /**
+     * Construct an Api client.
+     *
+     * Two construction styles supported:
+     *
+     *     // Legacy positional form
+     *     new Api("https://api.example.com", "Bearer token", 30);
+     *
+     *     // 3.13.1: ergonomic options bag (recommended) — cross-framework
+     *     // parity with Python tina4_python.api.Api kwargs.
+     *     new Api("https://api.example.com", { bearerToken: "sk-abc" });
+     *     new Api("https://api.example.com", { username: "u", password: "p" });
+     *     new Api("https://api.example.com", { headers: { "X-Tenant": "acme" } });
+     *     new Api("https://self-signed.local", { verifySsl: false });
+     *
+     * Bearer wins over basic-auth when both passed. `verifySsl: false` is
+     * the positive form of `ignoreSsl: true`; `ignoreSsl` wins when both
+     * supplied for backward compatibility.
+     *
+     * `maxRetries` (default 0 = off) enables automatic retry with
+     * exponential backoff (`retryBackoff` seconds base, doubling each
+     * attempt) on a transport error or a retryable status (429/5xx). A
+     * retried non-idempotent request (POST/…) may be re-sent — retries are
+     * opt-in for that reason.
+     *
+     *     new Api("https://api.example.com", { maxRetries: 3, retryBackoff: 0.5 });
+     *
+     * `transport` (default undefined = the real network path) is an injectable
+     * seam so USERS can unit-test their own code; `cookies` (default false)
+     * turns on a per-client, in-memory cookie jar.
+     */
+    constructor(baseUrl?: string, authHeaderOrOptions?: string | ApiOptions, timeout?: number);
+    /**
+     * Add custom headers to all subsequent requests.
+     */
+    addHeaders(headers: Record<string, string>): void;
+    /**
+     * Set Bearer token authentication.
+     */
+    setBearerToken(token: string): void;
+    /**
+     * Set Basic authentication.
+     */
+    setBasicAuth(username: string, password: string): void;
+    /**
+     * Disable SSL certificate verification (dev/self-signed certs only).
+     */
+    setIgnoreSsl(ignore: boolean): void;
+    /**
+     * HTTP GET request.
+     */
+    get(path: string, params?: Record<string, string>): Promise<ApiResult>;
+    /**
+     * HTTP POST request.
+     */
+    post(path: string, body?: unknown, contentType?: string): Promise<ApiResult>;
+    /**
+     * HTTP PUT request.
+     */
+    put(path: string, body?: unknown, contentType?: string): Promise<ApiResult>;
+    /**
+     * HTTP PATCH request.
+     */
+    patch(path: string, body?: unknown, contentType?: string): Promise<ApiResult>;
+    /**
+     * HTTP DELETE request.
+     */
+    delete(path: string, body?: unknown): Promise<ApiResult>;
+    /**
+     * Generic request method — public entry point for any HTTP method.
+     */
+    sendRequest(method: string, path: string, body?: unknown, contentType?: string): Promise<ApiResult>;
+    /**
+     * POST a `multipart/form-data` body — a file plus optional text fields.
+     *
+     * Two ways to supply the file, so a caller never needs a temp file:
+     *
+     *   - `filePath` — a file on disk. `filename` defaults to its basename.
+     *   - `fileBytes` + `filename` — an in-memory payload (Buffer or string).
+     *
+     * `fieldName` (default `"file"`) is the form field the file is sent under.
+     * `extraFields` become additional text parts. `headers` are extra per-call
+     * headers merged onto the request. The part's Content-Type is guessed from
+     * the filename (falling back to `application/octet-stream`).
+     *
+     * Returns the standard {@link ApiResult}. A missing file or no source given
+     * returns a clean error result (`http_code` null, `error` set) — it does NOT
+     * throw. Retry/backoff (if configured) applies, exactly like the verbs.
+     *
+     *     await api.upload("/avatars", { filePath: "/tmp/me.png" });
+     *     await api.upload("/avatars", { fileBytes: raw, filename: "me.png",
+     *                                    extraFields: { user_id: "42" } });
+     */
+    upload(path: string, opts?: UploadOptions): Promise<ApiResult>;
+    /**
+     * Stream a GET response body to `destPath` in chunks.
+     *
+     * The body is written to disk `DOWNLOAD_CHUNK_SIZE` bytes at a time instead
+     * of being buffered whole in memory — safe for large payloads. Redirect
+     * following, the cross-origin auth strip, the cookie jar, and the SSL flag
+     * all apply, exactly like the other verbs.
+     *
+     * Returns {@link DownloadResult} — there is no `body` field (it went to
+     * disk). `path` is `destPath` on success and `null` on any error (missing
+     * dest, HTTP error status, or a transport failure); the destination file is
+     * not written on error.
+     */
+    download(path: string, destPath: string, params?: Record<string, string>): Promise<DownloadResult>;
+    private buildUrl;
+    /**
+     * Build the request headers (auth + cookie jar + extras) and serialize the
+     * body to a Buffer. Shared by every verb, upload, and download so the wire
+     * shape is identical and the transport seam sees exactly what the network
+     * path would.
+     */
+    private buildRequest;
+    /**
+     * Execute the request with opt-in retry/backoff.
+     *
+     * With `maxRetries` > 0, a transport failure (`http_code` null) or a
+     * retryable status (429/5xx) is retried up to `maxRetries` times with
+     * exponential backoff; any other outcome (2xx, 3xx, other 4xx) returns
+     * at once. A retried non-idempotent request may be re-sent — retries
+     * are opt-in for that reason.
+     */
+    private execute;
+    /** A single HTTP attempt — returns the standardized result. */
+    private attempt;
+    /**
+     * Invoke a user-injected transport and normalize its result. The transport
+     * is called with `(method, url, headers, body, timeout)` and its returned
+     * `Set-Cookie` headers (if any) feed the cookie jar.
+     */
+    private callTransport;
+    /**
+     * Perform the network request, following up to `redirectsLeft` redirects.
+     *
+     * node:http/https `request` does NOT auto-follow redirects. On a 3xx with a
+     * Location, this drains the intermediate response and re-issues to the new
+     * URL: 301/302/303 on a non-GET/HEAD become GET (body dropped, urllib
+     * behaviour); 307/308 preserve method + body. When the redirect target is a
+     * DIFFERENT origin, the Authorization and Cookie headers are stripped so a
+     * bearer token / session cookie never leaks to a host you didn't
+     * authenticate to.
+     */
+    private performRequest;
+    /** Buffer a response body, parse JSON if possible, and store cookies. */
+    private readResponse;
+    /** The accumulated `Cookie` request header, or null when the jar is empty. */
+    private cookieHeader;
+    /**
+     * Parse `Set-Cookie` response headers into the jar (when enabled). Only the
+     * leading `name=value` pair of each is kept (Path/HttpOnly/Expires ignored);
+     * a later value for the same name overwrites an earlier one.
+     */
+    private storeCookies;
+    /** Store cookies from a plain header record (the transport seam path). */
+    private storeCookiesFromRecord;
+}

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

@@ -0,0 +1,177 @@
+import type { Middleware } from "./types.js";
+/**
+ * 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()`.
+ *
+ * Order:
+ *   1. TINA4_SECRET already set → no-op (return null).
+ *   2. NOT dev, OR CI, OR production → emit the actionable warning, return null.
+ *      NEVER generates or persists a secret in CI / production / non-dev.
+ *   3. Otherwise (dev, not CI, not prod, blank secret) → generate a 32-byte hex
+ *      secret, set it in process.env for THIS run immediately, then try to append
+ *      it to <cwd>/.env.local (create if missing; never touch .env). On a write
+ *      failure keep the in-memory secret and warn — boot must never crash.
+ *
+ * @param cwd - Directory to write .env.local into. Tests pass a temp dir; production passes nothing.
+ * @returns The newly-generated secret, or null when nothing was generated.
+ */
+export declare function ensureDevSecret(cwd?: string): string | null;
+/**
+ * Can this runtime actually sign and verify `algorithm` right now?
+ *
+ * The cross-framework capability check — same question, same answer shape, in
+ * all four frameworks. HMAC answers `true` everywhere. RS256 answers `true`
+ * only where the runtime ships asymmetric crypto natively (node:crypto here,
+ * core ext-openssl in PHP, the stdlib openssl gem in Ruby) and `false` in
+ * tina4-python. An algorithm Tina4 does not know at all answers `false`.
+ */
+export declare function algorithmAvailable(algorithm: string): boolean;
+/** Every algorithm this runtime can sign and verify right now, in advertised order. */
+export declare function availableAlgorithms(): string[];
+/**
+ * Seconds of clock skew tolerated on the "nbf" (not-before) claim.
+ *
+ * Without this, a token minted on one host and validated on another a second
+ * behind is rejected for no real reason; RFC 7519 explicitly allows "a small
+ * leeway". Same value as the Python master's `_JWT_LEEWAY_SECONDS`.
+ */
+export declare const JWT_LEEWAY_SECONDS = 60;
+/**
+ * Pick the JWT algorithm: explicit argument, else TINA4_JWT_ALGORITHM, else HS256.
+ *
+ * Throws when asked for an algorithm Tina4 does not know (naming the known set,
+ * what is available here, and the env var), and throws again — with the runtime's
+ * own reason and a remedy — when it knows the algorithm but this build cannot
+ * provide it. A silent downgrade to HS256 is the whole bug in python#106, and a
+ * silent downgrade from RS256 would be worse: it would quietly turn asymmetric
+ * verification into a shared secret.
+ *
+ * @param algorithm - Explicit algorithm; wins over the environment when given.
+ */
+export declare function resolveAlgorithm(algorithm?: string): string;
+/**
+ * Create a signed JWT token.
+ *
+ * Secret is always read from `process.env.TINA4_SECRET`.
+ * Algorithm is read from `process.env.TINA4_JWT_ALGORITHM` (default "HS256").
+ * HS256 / HS384 / HS512 is the cross-framework standard; RS256 is an opt-in
+ * extra that Node provides from builtin node:crypto (pass the PEM private key
+ * as the secret). An unknown algorithm, or one this runtime cannot provide,
+ * throws — see `resolveAlgorithm`.
+ *
+ * The header's `alg` is always the algorithm that actually signed the token.
+ *
+ * No `nbf` (not-before) claim is stamped — parity with Python and PHP. Pass your
+ * own `nbf` in the payload to post-date a token; `validToken` enforces it.
+ *
+ * @param payload          - Claims to encode (e.g. `{ userId: 1, role: "admin" }`)
+ * @param secretOrExpiresIn - Signing secret string, OR expiresIn number in MINUTES (back-compat with old 2-arg form)
+ * @param expiresIn         - Lifetime in MINUTES (default 60). `0` ⇒ no `exp` claim (non-expiring). Only used when secret is a string.
+ * @param algorithm         - Overrides TINA4_JWT_ALGORITHM for this call.
+ * @returns Signed JWT string: header.payload.signature
+ * @throws When the resolved algorithm is not one Tina4 can sign.
+ */
+export declare function getToken(payload: Record<string, unknown>, secretOrExpiresIn?: string | number, expiresIn?: number, algorithm?: string): string;
+/**
+ * Validate a JWT token. Returns the decoded payload on success, `null` if
+ * invalid/expired/malformed.
+ *
+ * 3.13.0 — return type changed from `boolean` to `Record<string, unknown> | null`.
+ * Matches the convention used by `jsonwebtoken` and the Python / PHP / Ruby
+ * Auth.validToken signatures shipped at the same time. Legacy
+ * `if (validToken(t))` patterns keep working because a non-null object is
+ * truthy and null is falsy.
+ *
+ * Secret is read from `process.env.TINA4_SECRET` when not passed explicitly.
+ * Algorithm is read from `process.env.TINA4_JWT_ALGORITHM` (default "HS256").
+ *
+ * Checks, in order: the header's `alg` must BE the expected algorithm (blocks alg
+ * substitution, including `alg: "none"`, before any signature work), then the
+ * signature, then `exp`, then `nbf` (with `JWT_LEEWAY_SECONDS` of clock skew).
+ */
+export declare function validToken(token: string, secret?: string, algorithm?: string): Record<string, unknown> | null;
+/**
+ * Get the JWT payload WITHOUT verifying signature or expiration.
+ */
+export declare function getPayload(token: string): Record<string, unknown> | null;
+/**
+ * Hash a password using PBKDF2-SHA256.
+ *
+ * @param password   - Plaintext password
+ * @param salt       - Hex-encoded salt (auto-generated if omitted)
+ * @param iterations - PBKDF2 iterations (default 260000)
+ * @returns Format: `pbkdf2_sha256$iterations$salt$hash` (all hex-encoded)
+ */
+export declare function hashPassword(password: string, salt?: string, iterations?: number): string;
+/**
+ * Check a password against a PBKDF2 hash string.
+ * Supports both $ and : delimiters for backward compatibility.
+ */
+export declare function checkPassword(password: string, hash: string): boolean;
+/**
+ * Auth middleware that extracts and verifies a Bearer JWT from the
+ * Authorization header. On success, attaches the decoded payload to
+ * `(request as any).auth`. On failure, sends a 401 JSON response.
+ *
+ * @param secret    - Signing secret / PEM public key (default: TINA4_SECRET env var).
+ * @param algorithm - JWT algorithm. Omit it to honour TINA4_JWT_ALGORITHM (then
+ *   HS256). It used to default to the literal "HS256", which SHADOWED the env
+ *   var: an app on TINA4_JWT_ALGORITHM=HS512 minted HS512 tokens and this
+ *   middleware verified them as HS256, rejecting every valid token.
+ */
+export declare function authMiddleware(secret?: string, algorithm?: string): Middleware;
+/**
+ * Refresh a JWT token — validate the existing token then re-sign
+ * with a fresh expiry.
+ *
+ * Secret is always read from `process.env.TINA4_SECRET`.
+ *
+ * @param token     - Existing JWT to refresh
+ * @param expiresIn - New lifetime in MINUTES (default 60)
+ * @returns New signed JWT string, or null if the input token is invalid/expired
+ */
+export declare function refreshToken(token: string, expiresIn?: number): string | null;
+/**
+ * Extract a Bearer token from request headers and validate it.
+ *
+ * @param headers   - Object with header keys (e.g. `{ authorization: "Bearer ..." }`)
+ * @param secret    - HMAC secret or PEM public key
+ * @param algorithm - Omit it to honour TINA4_JWT_ALGORITHM (then HS256). HS256 /
+ *   HS384 / HS512 everywhere; RS256 where the runtime provides it (it does here).
+ * @returns Decoded payload, or null if missing/invalid
+ */
+export declare function authenticateRequest(headers: Record<string, string | string[] | undefined>, secret?: string, algorithm?: string): Record<string, unknown> | null;
+/**
+ * Compare an API key against an expected value.
+ * If `expected` is omitted, falls back to the `TINA4_API_KEY` env var.
+ *
+ * Uses constant-time comparison to prevent timing attacks.
+ *
+ * @param provided - The API key provided by the caller
+ * @param expected - The correct API key (defaults to `process.env.TINA4_API_KEY`)
+ * @returns true if the keys match
+ */
+export declare function validateApiKey(provided: string, expected?: string): boolean;
+/**
+ * Auth class that wraps the standalone auth functions so both patterns work:
+ *
+ *   import { Auth } from "tina4-nodejs";
+ *   const token = Auth.getToken(payload, secret);
+ *
+ *   import { getToken } from "tina4-nodejs";
+ *   const token = getToken(payload, secret);
+ */
+export declare class Auth {
+    static getToken: typeof getToken;
+    static validToken: typeof validToken;
+    static resolveAlgorithm: typeof resolveAlgorithm;
+    static algorithmAvailable: typeof algorithmAvailable;
+    static availableAlgorithms: typeof availableAlgorithms;
+    static getPayload: typeof getPayload;
+    static hashPassword: typeof hashPassword;
+    static checkPassword: typeof checkPassword;
+    static authMiddleware: typeof authMiddleware;
+    static refreshToken: typeof refreshToken;
+    static authenticateRequest: typeof authenticateRequest;
+    static validateApiKey: typeof validateApiKey;
+}

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

@@ -0,0 +1,20 @@
+import type { Tina4Request, Tina4Response } from "./types.js";
+/** Just the auth-relevant fields of a matched route. */
+export interface AuthGateRoute {
+    secure?: boolean;
+    noAuth?: boolean;
+}
+/**
+ * Enforce auth for a matched route.
+ *
+ * Returns `true` when the request is REJECTED — a 401 has already been written
+ * to `res.raw` and the caller must stop (not run the handler). Returns `false`
+ * when the route is public OR a valid token was presented (in which case
+ * `req.user` is populated and, for a body formToken, a `FreshToken` header is
+ * set). Auth is enforced only for a route that is `secure` and not `noAuth`,
+ * and never for `/__dev` dev-admin routes.
+ *
+ * Token sources, in priority order: `Authorization: Bearer` header, a
+ * `formToken` in the parsed body, then a session token.
+ */
+export declare function enforceRouteAuth(req: Tina4Request, res: Tina4Response, match: AuthGateRoute, isDevAdmin: boolean): boolean;

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

@@ -0,0 +1,34 @@
+/**
+ * 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.
+ *
+ * @param callback         Function to call (sync or async, no arguments).
+ * @param intervalSeconds  Seconds between invocations (default: 1).
+ * @returns A handle whose `stop()` clears just this one task.
+ */
+export declare function background(callback: () => unknown | Promise<unknown>, intervalSeconds?: number): {
+    stop: () => void;
+};
+/**
+ * Clear every registered background task. Called by the server's graceful
+ * shutdown (its first step on SIGTERM/SIGINT) and by its `close()`, so both a
+ * signal and a manual shutdown stop the timer wheel along with the listeners.
+ */
+export declare function stopAllBackgroundTasks(): void;
+/** Number of currently-registered background tasks (test helper). */
+export declare function backgroundTaskCount(): number;