tina4-nodejs 3.13.92 → 3.13.95

package/packages/core/src/dotenv.ts

@@ -1,5 +1,5 @@
-import { readFileSync, existsSync } from "node:fs";
-import { resolve } from "node:path";
+import { readFileSync, existsSync, statSync } from "node:fs";
+import { resolve, join, dirname } from "node:path";
 
 /**
  * Parse a .env file content string into key-value pairs.
@@ -12,13 +12,52 @@ import { resolve } from "node:path";
  *   - Empty lines
  *   - Multi-line with trailing backslash \
  */
+const VALID_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const REFERENCE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+
+/** Emit a parse warning. dotenv loads before the logger exists, so stderr. */
+function warnEnv(message: string): void {
+  process.stderr.write(`[tina4] ${message}\n`);
+}
+
+/**
+ * Expand ${VAR} against already-loaded keys plus the real environment.
+ *
+ * `process.env` is checked FIRST so the effective value wins: loading is
+ * first-wins, so a key already in the real environment is what the process will
+ * actually see, and an interpolation that resolved against the file's value
+ * instead would disagree with it. `parsed` then supplies keys set earlier in
+ * this same file, which are not in process.env until the whole file is applied.
+ *
+ * An unresolved name stays LITERAL and is warned about once per name, so a typo
+ * is visible without breaking the load.
+ */
+function interpolate(
+  value: string,
+  parsed: Record<string, string>,
+  lineNo: number,
+  warnedRefs: Set<string>
+): string {
+  return value.replace(REFERENCE, (whole, name: string) => {
+    const resolved = process.env[name] ?? parsed[name];
+    if (resolved !== undefined) return resolved;
+    if (!warnedRefs.has(name)) {
+      warnedRefs.add(name);
+      warnEnv(`.env:${lineNo}: \${${name}} is not set, left as-is`);
+    }
+    return whole;
+  });
+}
+
 function parseEnvContent(content: string): Record<string, string> {
   const result: Record<string, string> = {};
   const lines = content.split("\n");
+  const warnedRefs = new Set<string>();
   let i = 0;
 
   while (i < lines.length) {
     let line = lines[i].trim();
+    const lineNo = i + 1;
     i++;
 
     // Skip empty lines and comments
@@ -31,18 +70,41 @@ function parseEnvContent(content: string): Record<string, string> {
       line = line.slice(7).trim();
     }
 
-    // Find the first = sign
+    // Find the first = sign. A line with no "=" sets nothing, so say so rather
+    // than dropping it in silence.
     const eqIndex = line.indexOf("=");
     if (eqIndex === -1) {
+      warnEnv(`.env:${lineNo}: no '=' in "${line}", line skipped`);
       continue;
     }
 
     const key = line.slice(0, eqIndex).trim();
+    if (!VALID_KEY.test(key)) {
+      warnEnv(`.env:${lineNo}: invalid key "${key}", line skipped`);
+      continue;
+    }
     let value = line.slice(eqIndex + 1).trim();
 
-    // Handle quoted values
-    if (value.startsWith('"') && value.endsWith('"')) {
-      value = value.slice(1, -1);
+    // Handle quoted values. Quoting decides escapes AND interpolation, in that
+    // order -- the cross-framework behaviour table (feature 1 of the audit).
+    // A QUOTED value ends at its CLOSING QUOTE, and anything after it is a
+    // comment. Testing the LAST character instead was wrong: a trailing comment
+    // makes the last character non-quote, so `PW="s3cret" # note` fell to the
+    // unquoted branch, which strips only the ` #` and left the QUOTE CHARACTERS
+    // in the value -- a credential handed to a driver as '"s3cret"'. PHP already
+    // scanned for the terminator; this is that mechanism, and the scan SKIPS a
+    // quote preceded by a backslash so an escaped \" cannot end the value early.
+    const quote = value[0];
+    let closing = -1;
+    if (quote === '"' || quote === "'") {
+      for (let j = 1; j < value.length; j++) {
+        if (value[j] === "\\" && quote === '"' && j + 1 < value.length) { j++; continue; }
+        if (value[j] === quote) { closing = j; break; }
+      }
+    }
+
+    if (closing !== -1 && quote === '"') {
+      value = value.slice(1, closing);
       // Process escape sequences in double-quoted values
       value = value
         .replace(/\\n/g, "\n")
@@ -50,20 +112,25 @@ function parseEnvContent(content: string): Record<string, string> {
         .replace(/\\t/g, "\t")
         .replace(/\\"/g, '"')
         .replace(/\\\\/g, "\\");
-    } else if (value.startsWith("'") && value.endsWith("'")) {
-      // Single-quoted: literal, no escape processing
-      value = value.slice(1, -1);
+      value = interpolate(value, result, lineNo, warnedRefs);
+    } else if (closing !== -1 && quote === "'") {
+      // Single-quoted: verbatim. No escape processing, and NO interpolation --
+      // shell semantics, and the documented way to keep a literal ${...}.
+      value = value.slice(1, closing);
     } else {
-      // Unquoted: handle multi-line with trailing backslash
-      while (value.endsWith("\\") && i < lines.length) {
-        value = value.slice(0, -1) + lines[i].trim();
-        i++;
-      }
+      // NOTE: the backslash line-continuation loop that used to live here is
+      // GONE. It was a Node-only extension -- absent from Python, PHP and Ruby,
+      // absent from the shared corpus, and undocumented -- so the SAME .env file
+      // produced a DIFFERENT SET OF VARIABLES on Node than on the other three.
+      // That is the strongest form of swap break (ADR-0024), and the least-code
+      // fix is deletion: four lines removed, nothing added.
+
       // Strip inline comments (only for unquoted values)
       const commentIndex = value.indexOf(" #");
       if (commentIndex !== -1) {
         value = value.slice(0, commentIndex).trim();
       }
+      value = interpolate(value, result, lineNo, warnedRefs);
     }
 
     result[key] = value;
@@ -73,46 +140,98 @@ function parseEnvContent(content: string): Record<string, string> {
 }
 
 /**
- * Load environment variables from a .env file into process.env.
- *
- * By default does NOT override existing process.env values — it is first-wins:
- * a key is only set if it is not already present. This is how real env vars
- * always win. To get the precedence real-env > `.env.local` > `.env`, load
- * `.env.local` FIRST then `.env`, both with override=false (the default): the
- * real env (already present) wins over both, `.env.local` fills local-only keys,
- * and `.env` fills the rest. Do NOT load `.env.local` with override=true — that
- * would let a stray gitignored `.env.local` clobber an explicitly set real env
- * var (e.g. a production TINA4_SECRET).
- *
- * Resolution order for the env file path:
- *   1. Explicit `path` argument
- *   2. `TINA4_ENV_FILE` env var (if set and non-empty)
- *   3. `.env` in the current working directory
- *
- * @param path     - Path to the .env file. Optional override.
+ * Load environment variables from a root DIRECTORY or a single .env file.
+ *
+ * Pass a **directory** and it loads `<dir>/.env.local` then `<dir>/.env`, both
+ * first-wins, which IS the precedence real-env > `.env.local` > `.env`. That is
+ * the canonical form in all four frameworks.
+ *
+ * Before this, the ordering was the CALLER's job and this doc comment was the
+ * only place it was written down: load `.env.local` first, then `.env`, both
+ * with override=false. Every caller had to remember, and getting it wrong
+ * (override=true on `.env.local`) lets a stray gitignored file clobber an
+ * explicitly set real env var such as a production TINA4_SECRET. A rule nobody
+ * can forget beats a rule written in a comment.
+ *
+ * A **file** path still works exactly as before: only that file is read, and the
+ * caller owns the ordering.
+ *
+ * By default this does NOT override existing process.env values — it is
+ * first-wins, which is how a real env var always beats both files.
+ *
+ * Resolution order when `path` is omitted:
+ *   1. `TINA4_ENV_FILE` env var (if set and non-empty) — the named file, plus
+ *      `.env.local` BESIDE it, so pointing at `.env.staging` does not silently
+ *      stop honouring local overrides
+ *   2. the current working directory, as a root
+ *
+ * @param path     - A root directory (canonical) OR a path to a single .env file.
  * @param override - When true, overwrite keys already present in process.env.
- * @returns The parsed key-value pairs, or an empty object if the file doesn't exist.
+ * @returns The parsed key-value pairs. For the directory form this is the merge
+ *          of both files, with `.env.local` winning on a duplicate key.
  */
 export function loadEnv(path?: string, override = false): Record<string, string> {
   const fromEnv = (process.env.TINA4_ENV_FILE ?? "").trim();
-  const target = path ?? (fromEnv.length > 0 ? fromEnv : ".env");
-  const envPath = resolve(target);
 
+  if (path === undefined && fromEnv.length > 0) {
+    const named = resolve(fromEnv);
+    return mergeFirstWins(
+      loadEnvFile(join(dirname(named), ".env.local"), override),
+      loadEnvFile(named, override),
+    );
+  }
+
+  const target = resolve(path ?? ".");
+  if (existsSync(target) && statSync(target).isDirectory()) {
+    // .env.local FIRST so it beats .env; both first-wins, so a variable already
+    // in the real environment still beats both.
+    return mergeFirstWins(
+      loadEnvFile(join(target, ".env.local"), override),
+      loadEnvFile(join(target, ".env"), override),
+    );
+  }
+
+  return loadEnvFile(target, override);
+}
+
+/** Merge two parsed maps, first argument winning on a duplicate key. */
+function mergeFirstWins(
+  first: Record<string, string>,
+  second: Record<string, string>,
+): Record<string, string> {
+  return { ...second, ...first };
+}
+
+/**
+ * Load ONE .env file. A missing file is not an error and yields `{}` - a fresh
+ * checkout has no `.env.local`, and the directory form reads it unconditionally.
+ */
+function loadEnvFile(envPath: string, override: boolean): Record<string, string> {
   if (!existsSync(envPath)) {
     return {};
   }
 
   const content = readFileSync(envPath, "utf-8");
   const parsed = parseEnvContent(content);
+  const effective: Record<string, string> = {};
 
   for (const [key, value] of Object.entries(parsed)) {
+    // First-wins by default: a variable already in the real environment is
+    // never clobbered.
     if (override || process.env[key] === undefined) {
       process.env[key] = value;
       _loadedKeys.push(key);
     }
+    // Report the value that WON, not the one this file declared. They differ
+    // exactly when the real environment beat the file, which is the case an
+    // operator most needs to see: reporting the file's value there means the
+    // returned map says "from_local" while the process is actually running on
+    // "from_REAL". A map that disagrees with process.env is worse than no map,
+    // because it looks authoritative.
+    effective[key] = process.env[key] as string;
   }
 
-  return parsed;
+  return effective;
 }
 
 /**
@@ -133,12 +252,38 @@ export function getEnv(key: string, defaultValue?: string): string | undefined {
  * @returns The environment variable value.
  * @throws Error if the variable is not set.
  */
-export function requireEnv(key: string): string {
-  const value = process.env[key];
-  if (value === undefined) {
-    throw new Error(`Required environment variable "${key}" is not set.`);
+/**
+ * Validate that required environment variables exist, and return them.
+ *
+ * Takes VARARGS and returns a map, matching Python, PHP and Ruby. It used to
+ * take one key and return that value, so checking five variables meant five
+ * calls that each failed on the first problem - an operator fixing a deployment
+ * got one name per restart instead of the whole list.
+ *
+ * @param keys - Variable names that must be set.
+ * @returns Every requested key mapped to its value.
+ * @throws Error naming ALL missing variables, not just the first.
+ */
+export function requireEnv(...keys: string[]): Record<string, string> {
+  const missing: string[] = [];
+  const found: Record<string, string> = {};
+
+  for (const key of keys) {
+    const value = process.env[key];
+    if (value === undefined) {
+      missing.push(key);
+      continue;
+    }
+    found[key] = value;
   }
-  return value;
+
+  if (missing.length > 0) {
+    throw new Error(
+      `Missing required environment variables: ${missing.join(", ")}`,
+    );
+  }
+
+  return found;
 }
 
 /**

package/packages/core/src/index.ts

@@ -6,6 +6,7 @@ export type {
   RouteMeta,
   Tina4Config,
   Middleware,
+  MiddlewareClass,
   MiddlewareSpec,
   UploadedFile,
   CookieOptions,
@@ -29,6 +30,7 @@ export { Env } from "./env.js";
 export { Log } from "./logger.js";
 export { createHealthRoute, createHealthRoutes, healthPath } from "./health.js";
 export { rateLimiter } from "./rateLimiter.js";
+export { isTrustedProxy, trustedProxyNetworks, resolveClientIp, resetTrustedProxyCache } from "./trustedProxy.js";
 export type { RateLimiterConfig } from "./rateLimiter.js";
 export {
   HTTP_OK, HTTP_CREATED, HTTP_ACCEPTED, HTTP_NO_CONTENT,
@@ -46,9 +48,10 @@ export {
   authMiddleware,
   refreshToken, authenticateRequest, validateApiKey,
   ensureDevSecret,
+  resolveAlgorithm, algorithmAvailable, availableAlgorithms,
   Auth,
 } from "./auth.js";
-export { Session, FileSessionHandler, RedisSessionHandler, buildSessionCookie, isSecureScheme, sessionCookieName } from "./session.js";
+export { Session, FileSessionHandler, RedisSessionHandler, buildSessionCookie, isSecureScheme, isValidSessionId, sessionCookieName, VALID_SESSION_BACKENDS, CANONICAL_SESSION_BACKENDS } from "./session.js";
 export type { SessionConfig, SessionHandler } from "./session.js";
 export { I18n } from "./i18n.js";
 export { FakeData } from "./fakeData.js";
@@ -75,7 +78,7 @@ export {
 export type { WebSocketClient } from "./websocket.js";
 export { ServiceRunner, Tina4Service, matchCronField, matchesCron } from "./service.js";
 export type { ServiceOptions, ServiceContext, ServiceHandler, ServiceInfo } from "./service.js";
-export { responseCache, clearCache, cacheStats, cacheGet, cacheSet, cacheDelete, cacheClear, cacheBackendStats, createBackend, _resetBackend } from "./cache.js";
+export { responseCache, clearCache, cacheStats, cacheGet, cacheSet, cacheDelete, cacheClear, cacheBackendStats, sweep, createBackend, _resetBackend } from "./cache.js";
 export type { ResponseCacheConfig, CacheBackend } from "./cache.js";
 export { Api } from "./api.js";
 export type { ApiResult, ApiOptions, ApiTransport, DownloadResult, UploadOptions } from "./api.js";
@@ -94,9 +97,9 @@ export {
   handleFeedbackWidgetJs,
   registerFeedbackRoutes,
 } from "./feedback.js";
-export { Messenger, MessengerConnectionError } from "./messenger.js";
+export { Messenger, MessengerConnectionError, createMessenger } from "./messenger.js";
 export type { SendResult, EmailMessage } from "./messenger.js";
-export { DevMailbox, createMessenger } from "./devMailbox.js";
+export { DevMailbox } from "./devMailbox.js";
 export { WSDLService, WSDLOperation } from "./wsdl.js";
 export type { WSDLOperationMeta } from "./wsdl.js";
 export { HtmlElement, htmlElement, addHtmlHelpers, Raw, SafeString } from "./htmlElement.js";
@@ -121,8 +124,6 @@ export { MongoSessionHandler } from "./sessionHandlers/mongoHandler.js";
 export type { MongoSessionConfig } from "./sessionHandlers/mongoHandler.js";
 export { ValkeySessionHandler } from "./sessionHandlers/valkeyHandler.js";
 export type { ValkeySessionConfig } from "./sessionHandlers/valkeyHandler.js";
-export { RedisNpmSessionHandler } from "./sessionHandlers/redisHandler.js";
-export type { RedisNpmSessionConfig } from "./sessionHandlers/redisHandler.js";
 export { tests, assertEqual, assertRaises, assertTrue, assertFalse, runAll, reset } from "./testing.js";
 export { TestClient, TestResponse } from "./testClient.js";
 export { Tina4Test, AssertionError as Tina4AssertionError } from "./test.js";