tina4-nodejs 3.13.137 → 3.13.139

package/packages/core/public/licenses/tina4-js-MIT.txt

@@ -0,0 +1,20 @@
+MIT License
+
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/packages/core/src/__feedback/widget.js

@@ -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/.
+*/
+
 (function(){"use strict";(()=>{try{const t=window.location.pathname||"";return t.startsWith("/__dev")||t.startsWith("/__feedback")}catch{return!1}})()?console.info("tina4-feedback-widget: skipping on developer path"):window.__tina4FeedbackLoaded?console.warn("tina4-feedback-widget already loaded; skipping"):(window.__tina4FeedbackLoaded=!0,b());function b(){const c=(getComputedStyle(document.documentElement).getPropertyValue("--primary")||"").trim()||"#3b82f6";h(c);const l=m();document.body.appendChild(l);let e=null,u;const r=[];l.addEventListener("click",()=>{if(e){e.remove(),e=null,l.style.display="";return}e=g(),document.body.appendChild(e),l.style.display="none",setTimeout(()=>e?.querySelector("textarea")?.focus(),0)});function g(){const o=document.createElement("div");o.className="tina4-fb-modal",o.innerHTML=`
       <div class="tina4-fb-head">
         <span class="tina4-fb-title">Tell us what's not working</span>

package/packages/core/src/_missing.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/.
+*/
+
 /**
  * Last-resort finder for `@tina4/core/<subpath>` under Node's ESM resolver.
  *

package/packages/core/src/ai.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 AI — Install AI coding assistant context files.
  *

package/packages/core/src/aiClient.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/.
+*/
+
 /** Zero-dependency app-facing AI client (ADR-0053 + ADR-0060). */
 import http, { type IncomingMessage } from "node:http";
 import https from "node:https";

package/packages/core/src/api.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 API Client — HTTP client using Node.js built-in modules only.
  *
@@ -21,6 +29,7 @@ import { promises as fsp, createWriteStream } from "node:fs";
 import { basename } from "node:path";
 import { pipeline } from "node:stream/promises";
 import { TINA4_VERSION } from "./version.js";
+import { guardUrl } from "./ssrf.js";
 
 export interface ApiResult {
     http_code: number | null;
@@ -221,6 +230,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[];
 }
 
 /** True when two URLs share scheme + host + (effective) port. */
@@ -422,6 +436,7 @@ export class Api {
     private transportFn?: ApiTransport;
     private cookiesEnabled: boolean;
     private cookies: Record<string, string>;
+    private allowHosts: string[];
 
     /**
      * Construct an Api client.
@@ -468,6 +483,7 @@ export class Api {
         this.transportFn = undefined;
         this.cookiesEnabled = false;
         this.cookies = {};
+        this.allowHosts = [];
 
         // Options-bag form — second arg is an object literal
         if (typeof authHeaderOrOptions === "object" && authHeaderOrOptions !== null) {
@@ -479,6 +495,7 @@ export class Api {
             this.retryBackoff = opts.retryBackoff ?? 0.5;
             this.transportFn = opts.transport;
             this.cookiesEnabled = opts.cookies ?? false;
+            this.allowHosts = opts.allowHosts ?? [];
 
             // Bearer wins over basic-auth when both are passed
             if (opts.bearerToken != null) {
@@ -667,7 +684,7 @@ export class Api {
             url += (url.includes("?") ? "&" : "?") + qs;
         }
 
-        const { headers, data } = this.buildRequest("GET", "application/json", undefined);
+        const { headers, data } = this.buildRequest("GET", "application/json", undefined, undefined, url);
 
         // An injected transport can't stream (it returns a buffered result), so
         // write its body out; only the real network path streams chunk-by-chunk.
@@ -760,7 +777,7 @@ export class Api {
         const url = this.buildUrl(path);
         const method = (opts.method ?? "GET").toUpperCase();
         const contentType = opts.contentType ?? "application/json";
-        const { headers, data } = this.buildRequest(method, contentType, opts.body, opts.headers);
+        const { headers, data } = this.buildRequest(method, contentType, opts.body, opts.headers, url);
         const totalSec = this.streamSeconds(opts.timeout, "TINA4_API_TIMEOUT", this.timeout);
         const connectSec = this.streamSeconds(opts.connectTimeout, "TINA4_API_CONNECT_TIMEOUT", 10);
         const opened = await this.openStreamRequest(method, url, headers, data, connectSec);
@@ -834,13 +851,19 @@ export class Api {
      * body-phase timeout is applied by the caller (streamBytes) via
      * `res.destroy()`.
      */
-    private openStreamRequest(
+    private async openStreamRequest(
         method: string,
         url: string,
         headers: Record<string, string>,
         data: Buffer | undefined,
         connectSec: number,
     ): Promise<{ res: http.IncomingMessage }> {
+        // SSRF guard (ADR-0084): refuse a private/internal target before connect.
+        try {
+            await guardUrl(url, this.allowHosts);
+        } catch (err) {
+            throw new ApiStreamError(err instanceof Error ? err.message : String(err), null);
+        }
         return new Promise((resolve, reject) => {
             let parsed: URL;
             try {
@@ -904,14 +927,21 @@ export class Api {
         contentType: string,
         body: unknown,
         extraHeaders?: Record<string, string>,
+        targetUrl?: string,
     ): { headers: Record<string, string>; data: Buffer | undefined } {
         const headers: Record<string, string> = { "User-Agent": `Tina4/${TINA4_VERSION}`, ...this.headers };
-        if (this.authHeader) {
+        // Attach the configured Authorization / Cookie ONLY when the request
+        // target is same-origin as the configured base. A path that is itself
+        // an absolute off-origin URL (e.g. get("http://evil/x")) otherwise
+        // leaks the bearer token / session cookie to an attacker-chosen host —
+        // the same cross-origin strip already applied to followed redirects.
+        const sameOriginAsBase = targetUrl === undefined || sameOrigin(targetUrl, this.baseUrl);
+        if (this.authHeader && sameOriginAsBase) {
             headers["Authorization"] = this.authHeader;
         }
 
         // Cookie jar: attach the accumulated Cookie header when enabled.
-        if (this.cookiesEnabled) {
+        if (this.cookiesEnabled && sameOriginAsBase) {
             const cookieHeader = this.cookieHeader();
             if (cookieHeader) {
                 headers["Cookie"] = cookieHeader;
@@ -943,6 +973,9 @@ export class Api {
             Object.assign(headers, extraHeaders);
         }
 
+        if (targetUrl !== undefined && !sameOrigin(targetUrl, this.baseUrl)) {
+            for (const name of STRIP_ON_CROSS_ORIGIN) deleteHeaderCaseInsensitive(headers, name);
+        }
         return { headers, data };
     }
 
@@ -985,7 +1018,7 @@ export class Api {
         contentType: string = "application/json",
         extraHeaders?: Record<string, string>,
     ): Promise<ApiResult> {
-        const { headers, data } = this.buildRequest(method, contentType, body, extraHeaders);
+        const { headers, data } = this.buildRequest(method, contentType, body, extraHeaders, url);
 
         // A user-injected transport fully replaces the network call.
         if (this.transportFn) {
@@ -1037,13 +1070,21 @@ export class Api {
      * bearer token / session cookie never leaks to a host you didn't
      * authenticate to.
      */
-    private performRequest(
+    private async performRequest(
         method: string,
         url: string,
         headers: Record<string, string>,
         data: Buffer | undefined,
         redirectsLeft: number,
     ): Promise<NetworkResult> {
+        // SSRF guard (ADR-0084): re-validated per hop (this method recurses on a
+        // redirect), so a hop to a private/internal address is refused even when
+        // the initial URL was public.
+        try {
+            await guardUrl(url, this.allowHosts);
+        } catch (err) {
+            return { kind: "error", error: err instanceof Error ? err.message : String(err) };
+        }
         return new Promise<NetworkResult>((resolve) => {
             let parsed: URL;
             try {

package/packages/core/src/auth.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 Auth — Zero-dependency JWT, password hashing, and auth middleware.
  *
@@ -12,7 +20,7 @@
  *   checkPassword("secret123", hash);  // true
  */
 import { createHmac, createSign, createVerify, pbkdf2Sync, randomBytes, timingSafeEqual } from "node:crypto";
-import { appendFileSync, existsSync, readFileSync } from "node:fs";
+import { appendFileSync, existsSync, readFileSync, openSync, closeSync, fstatSync, fchmodSync, constants } from "node:fs";
 import { join } from "node:path";
 import type { Middleware, Tina4Request, Tina4Response } from "./types.js";
 import { isTruthy } from "./dotenv.js";
@@ -74,6 +82,58 @@ function _warnBlankSecret(): void {
   void _logWarning(BLANK_SECRET_WARNING);
 }
 
+// ── Auth-token rules (ADR-0079) ────────────────────────────────────
+
+/**
+ * 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 const NON_IDENTITY_TOKEN_TYPES: readonly string[] = ["form"];
+
+/**
+ * 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 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 function isIdentityPayload(payload: Record<string, unknown> | null | undefined): payload is Record<string, unknown> {
+  return payload != null && !NON_IDENTITY_TOKEN_TYPES.includes(payload.type as string);
+}
+
+/** The actionable error for a weak HMAC key, or null when the key is usable. */
+export function insecureSecretMessage(secret: string | undefined | null): string | null {
+  const length = Buffer.byteLength(secret ?? "", "utf8");
+  if (length >= MIN_SECRET_BYTES) return null;
+  const what = length === 0 ? "is not set" : `is ${length} bytes`;
+  return `Auth: TINA4_SECRET ${what}; an HMAC JWT secret must be at least ${MIN_SECRET_BYTES} bytes. ` +
+    "Generate one with `openssl rand -hex 32` and set TINA4_SECRET in your environment or .env.";
+}
+
+/**
+ * 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 function requireBootSecret(): void {
+  const algorithm = (process.env.TINA4_JWT_ALGORITHM ?? "").trim() || "HS256";
+  if (RSA_SIGN_ALGORITHMS.has(algorithm)) return;
+  const secret = process.env.TINA4_SECRET ?? "";
+  if (secret === "" && _isDev()) return;
+  const message = insecureSecretMessage(secret);
+  if (message) throw new Error(message);
+}
+
 /**
  * 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()`.
@@ -107,14 +167,19 @@ export function ensureDevSecret(cwd?: string): string | null {
   const baseDir = cwd ?? process.cwd();
   const envLocalPath = join(baseDir, ".env.local");
   try {
-    // If the file exists and its content doesn't end in a newline, prepend one
-    // so the new key lands on its own line.
-    let prefix = "";
-    if (existsSync(envLocalPath)) {
-      const existing = readFileSync(envLocalPath, "utf-8");
-      if (existing.length > 0 && !existing.endsWith("\n")) prefix = "\n";
+    // Read and append through one descriptor so replacing a pathname cannot
+    // redirect either operation to an unrelated file.
+    const fd = openSync(envLocalPath, constants.O_RDWR | constants.O_APPEND | constants.O_CREAT | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0), 0o600);
+    try {
+      const info = fstatSync(fd);
+      if (!info.isFile() || info.nlink !== 1) throw new Error("Refusing a non-regular or multiply-linked configuration file");
+      fchmodSync(fd, 0o600);
+      const existing = readFileSync(fd, "utf-8");
+      const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+      appendFileSync(fd, `${prefix}TINA4_SECRET=${newSecret}\n`);
+    } finally {
+      closeSync(fd);
     }
-    appendFileSync(envLocalPath, `${prefix}TINA4_SECRET=${newSecret}\n`);
     void _logInfo("Auth: generated a development secret, saved to .env.local (gitignored)");
   } catch {
     // Keep the in-memory secret for this run; warn but never crash boot.
@@ -447,6 +512,14 @@ export function validToken(token: string, secret?: string, algorithm?: string):
     const header = JSON.parse(base64urlDecode(h).toString()) as Record<string, unknown>;
     if (header.alg !== resolvedAlgorithm) return null;
 
+    // A blank or short HMAC key verifies tokens anyone can mint, so the token is
+    // REJECTED (fail closed with a 401, never a 500) and the operator is told
+    // why. ADR-0079 s2.
+    if (HMAC_DIGESTS.has(resolvedAlgorithm)) {
+      const weak = insecureSecretMessage(resolvedSecret);
+      if (weak) { void _logWarning(weak); return null; }
+    }
+
     const signingInput = `${h}.${p}`;
     if (!verifySignature(signingInput, sig, resolvedSecret, resolvedAlgorithm)) {
       return null;
@@ -509,6 +582,8 @@ function sign(input: string, secret: string, algorithm: string): string {
   // the header is the one that actually produced this signature.
   const digest = HMAC_DIGESTS.get(algorithm);
   if (digest) {
+    const weak = insecureSecretMessage(secret);
+    if (weak) throw new Error(weak);
     return base64urlEncode(createHmac(digest, secret).update(input).digest());
   }
   const rsaAlgorithm = RSA_SIGN_ALGORITHMS.get(algorithm);
@@ -609,12 +684,14 @@ export function authMiddleware(secret?: string, algorithm?: string): Middleware
     }
 
     const token = authHeader.slice(7);
-    if (!validToken(token, secret, algorithm)) {
+    const payload = validToken(token, secret, algorithm);
+    // Invalid, expired, or a form token (not an identity, ADR-0079 s1).
+    if (!isIdentityPayload(payload)) {
       res({ error: "Unauthorized" }, 401);
       return;
     }
 
-    (req as any).auth = getPayload(token);
+    (req as any).auth = payload;
     next();
   };
 }
@@ -635,11 +712,12 @@ export function refreshToken(
   token: string,
   expiresIn: number = 60,
 ): string | null {
-  if (!validToken(token)) return null;
-
-  const payload = getPayload(token);
+  const payload = validToken(token);
   if (!payload) return null;
 
+  // Refresh preserves PURPOSE: a form token comes back as a form token (CSRF
+  // rotation) and so can still never pass an identity gate. The route gate
+  // issues a FreshToken only for an identity token. ADR-0079 s1.
   // Strip standard timing claims so getToken sets fresh ones
   const { iat: _iat, exp: _exp, ...claims } = payload;
   return getToken(claims, expiresIn);
@@ -673,7 +751,9 @@ export function authenticateRequest(
   // algorithm= silently got the env values instead, and `algorithm` defaulted to
   // the literal "HS256" which additionally shadowed TINA4_JWT_ALGORITHM. Python,
   // PHP and Ruby all honour these; Node was the last one that did not.
-  if (validToken(token, secret, algorithm)) return getPayload(token);
+  const payload = validToken(token, secret, algorithm);
+  // A form token is not an identity (ADR-0079 s1).
+  if (payload) return isIdentityPayload(payload) ? payload : null;
 
   // Fallback: treat Bearer value as API key
   if (validateApiKey(token)) {

package/packages/core/src/authGate.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/.
+*/
+
 /**
  * Secure-by-default route auth gate — shared by the live server dispatch and the
  * in-process TestClient so the test surface enforces the IDENTICAL gate as
@@ -9,7 +17,8 @@
  * verification layer lied. This is the same defect fixed in tina4-python under
  * #PY2; extracting the gate here lets both callers share one implementation.
  */
-import { validToken, getPayload, refreshToken } from "./auth.js";
+import { validToken, refreshToken, isIdentityPayload } from "./auth.js";
+import { liveSessionIdentity } from "./ssoIdentity.js";
 import type { Tina4Request, Tina4Response } from "./types.js";
 
 /** Just the auth-relevant fields of a matched route. */
@@ -44,52 +53,58 @@ export function enforceRouteAuth(
     return false;
   }
 
+  // Token slots in priority order: Bearer header, body formToken (frond.js
+  // puts the auth token it received as a FreshToken there), session token.
+  // Each slot is accepted only when it carries an IDENTITY token: a Frond
+  // form token (`type: "form"`) proves where a write came from, not who sent
+  // it, so it is skipped and the search moves on (ADR-0079 s1).
   const authHeader = req.headers.authorization ?? "";
   const headerToken = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : "";
 
-  let resolvedToken = "";
+  let payload: Record<string, unknown> | null = null;
   let tokenSource: "header" | "body" | "session" | "" = "";
+  let resolvedToken = "";
 
   // Priority 1: Authorization Bearer header
-  if (headerToken && validToken(headerToken)) {
-    resolvedToken = headerToken;
-    tokenSource = "header";
+  if (headerToken) {
+    const candidate = validToken(headerToken);
+    if (isIdentityPayload(candidate)) { payload = candidate; tokenSource = "header"; resolvedToken = headerToken; }
   }
 
   // Priority 2: formToken from request body
-  if (!resolvedToken) {
+  if (!payload) {
     const bodyToken = (req.body as Record<string, unknown>)?.formToken as string | undefined;
-    if (bodyToken && validToken(bodyToken)) {
-      resolvedToken = bodyToken;
-      tokenSource = "body";
+    if (bodyToken) {
+      const candidate = validToken(bodyToken);
+      if (isIdentityPayload(candidate)) { payload = candidate; tokenSource = "body"; resolvedToken = bodyToken; }
     }
   }
 
-  // Priority 3: Session token
-  if (!resolvedToken) {
-    const sso = (req as any).session?.get?.("_tina4_sso") as Record<string, any> | undefined;
-    const identity = sso?.identity;
-    if (identity?.issuer && identity?.subject) {
+  // Priority 3: Session — a provider-verified SSO identity while it is live
+  // (ADR-0079 s5), then the session token.
+  if (!payload) {
+    const identity = liveSessionIdentity((req as any).session?.get?.("_tina4_sso"));
+    if (identity) {
       req.user = identity;
       // RBAC guards apply to the SSO identity too (Feature 138).
       return rbacForbidden(match, identity, res);
     }
     const sessionToken = (req as any).session?.get?.("token") as string | undefined;
-    if (sessionToken && validToken(sessionToken)) {
-      resolvedToken = sessionToken;
-      tokenSource = "session";
+    if (sessionToken) {
+      const candidate = validToken(sessionToken);
+      if (isIdentityPayload(candidate)) { payload = candidate; tokenSource = "session"; resolvedToken = sessionToken; }
     }
   }
 
-  if (!resolvedToken) {
+  if (!payload) {
     res.raw.writeHead(401, { "Content-Type": "application/json" });
     res.raw.end(JSON.stringify({ error: "Unauthorized" }));
     return true;
   }
 
-  req.user = getPayload(resolvedToken) ?? {};
+  req.user = payload;
 
-  // When a body formToken validates, return a FreshToken header with a refreshed JWT
+  // When a body token authenticates, return a FreshToken header with a refreshed JWT
   if (tokenSource === "body") {
     const fresh = refreshToken(resolvedToken);
     if (fresh) {

package/packages/core/src/background.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/.
+*/
+
 /**
  * Background tasks — periodic callbacks that run alongside the HTTP server.
  *

package/packages/core/src/cache.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/.
+*/
+
 /**
  * Multi-backend response cache for GET requests.
  *
@@ -56,6 +64,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import * as crypto from "node:crypto";
 import * as net from "node:net";
+import { optionalPackageMissing } from "./optionalPackage.js";
 
 // ── Credential parsing (WHATWG URL or TINA4_CACHE_USERNAME / _PASSWORD) ──
 
@@ -181,6 +190,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;
 }
 
 // ── Memory backend ────────────────────────────────────────────────
@@ -1141,6 +1156,7 @@ class MongoBackend implements CacheBackend {
   private misses = 0;
   private maxEntries: number;
   private available = false;
+  private missingDriverMessage: string | null = null;
   private readyPromise: Promise<void>;
   // The mongodb driver types aren't depended on at compile time (optional dep).
   private client: any = null;
@@ -1178,8 +1194,15 @@ class MongoBackend implements CacheBackend {
     try {
       // Dynamic import so @tina4/core has no hard dependency on `mongodb` and an
       // absent driver degrades to file-fallback (never an import-time crash).
-      const mod: any = await import("mongodb").catch(() => null);
-      if (!mod || !mod.MongoClient) { this.available = false; return; }
+      let importError: any = null;
+      const mod: any = await import("mongodb").catch((error) => { importError = error; return null; });
+      if (!mod || !mod.MongoClient) {
+        this.available = false;
+        if (importError?.code === "ERR_MODULE_NOT_FOUND") {
+          this.missingDriverMessage = optionalPackageMissing("the mongodb cache backend", ["mongodb"]).message;
+        }
+        return;
+      }
       const client = new mod.MongoClient(this.url, { serverSelectionTimeoutMS: 4000 });
       await client.connect();
       await client.db(this.dbName).command({ ping: 1 });
@@ -1200,6 +1223,10 @@ class MongoBackend implements CacheBackend {
     return this.readyPromise;
   }
 
+  missingDriver(): string | null {
+    return this.missingDriverMessage;
+  }
+
   async isAvailable(): Promise<boolean> {
     await this.readyPromise;
     return this.available;
@@ -1291,6 +1318,7 @@ class DatabaseBackend implements CacheBackend {
   private misses = 0;
   private maxEntries: number;
   private available = false;
+  private missingDriverMessage: string | null = null;
   private readyPromise: Promise<void>;
   // @tina4/orm Database instance (optional dep, loaded dynamically).
   private db: any = null;
@@ -1324,8 +1352,13 @@ class DatabaseBackend implements CacheBackend {
       try { db.commit(); } catch { /* sqlite autocommits DDL */ }
       this.db = db;
       this.available = true;
-    } catch {
+    } catch (error) {
       this.available = false;
+      // The ORM adapters already phrase a missing driver as the install
+      // command; carry THAT through, and nothing else (a connect error can
+      // name the host and user).
+      const message = error instanceof Error ? error.message : String(error);
+      if (/npm install \S/.test(message)) this.missingDriverMessage = message;
     } finally {
       if (prevAuto === undefined) delete process.env.TINA4_AUTO_CACHING; else process.env.TINA4_AUTO_CACHING = prevAuto;
       if (prevDb === undefined) delete process.env.TINA4_DB_CACHE; else process.env.TINA4_DB_CACHE = prevDb;
@@ -1336,6 +1369,10 @@ class DatabaseBackend implements CacheBackend {
     return this.readyPromise;
   }
 
+  missingDriver(): string | null {
+    return this.missingDriverMessage;
+  }
+
   async isAvailable(): Promise<boolean> {
     await this.readyPromise;
     return this.available;
@@ -1531,9 +1568,11 @@ export async function createBackend(config?: {
   // degrading to a no-op cache. Mirrors the Python master.
   if (typeof backend.isAvailable === "function" && !(await backend.isAvailable())) {
     // eslint-disable-next-line no-console
+    const installHint = backend.missingDriver?.() ?? null;
     console.warn(
       `[tina4] Cache backend '${backendName}' is unavailable ` +
-      `(driver missing or service unreachable) — falling back to 'file'.`,
+      `(driver missing or service unreachable) — falling back to 'file'.` +
+      (installHint ? ` ${installHint}` : ""),
     );
     return new FileBackend(cacheDir(), maxEntries);
   }

package/packages/core/src/constants.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 Constants — HTTP status codes and content types.
  *

package/packages/core/src/container.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/.
+*/
+
 /**
  * Lightweight dependency injection container.
  *