tina4-nodejs 3.13.92 → 3.13.95

package/packages/core/src/ai.ts

@@ -995,4 +995,10 @@ export function generateContext(toolName: string = "claude-code"): string {
   }
 }
 
-export { AiTool as AiToolType };
+// `export type`, not `export {}`: AiTool is an interface, so a value re-export
+// emits a runtime binding that does not exist. tsc (without isolatedModules)
+// and esbuild both infer the intent and elide it, but any single-file
+// transpiler must be told -- Node's own TypeScript support compiles module by
+// module and threw `SyntaxError: Export 'AiTool' is not defined in module`,
+// which made every module reachable from this barrel unloadable by plain node.
+export type { AiTool as AiToolType };

package/packages/core/src/auth.ts

@@ -127,38 +127,122 @@ export function ensureDevSecret(cwd?: string): string | null {
   return newSecret;
 }
 
-// ── JWT algorithms ────────────────────────────────────────────────
+// ── JWT algorithms + runtime capability ───────────────────────────
 //
-// Mirrors the Python master (tina4_python/auth/__init__.py) — the digest is
-// LOOKED UP from the configured algorithm rather than hardcoded, so the "alg"
-// advertised in the header is always the one that actually produced the
-// signature (python#105). TINA4_JWT_ALGORITHM is read for real, and an
-// algorithm we cannot sign fails loudly instead of silently downgrading to
-// HS256 (python#106).
-
-/** HMAC algorithms → their node:crypto digest name. All in node:crypto — zero dependencies. */
+// HMAC — HS256 / HS384 / HS512 — is THE Tina4 JWT algorithm family, and it is
+// zero-dependency in all four frameworks:
+//     python  hmac + hashlib          (stdlib)
+//     php     hash_hmac               (ext-hash, PHP core)
+//     ruby    OpenSSL::HMAC           (stdlib default gem, NOT the jwt gem)
+//     node    node:crypto createHmac  (builtin)
+//
+// RS256 is an OPT-IN EXTRA, offered only where the RUNTIME provides asymmetric
+// crypto natively — never as a third-party dependency. Node gets it from the
+// same builtin node:crypto, so tina4-nodejs is the REFERENCE for what RS256
+// looks like when available; tina4-php has it from core ext-openssl and
+// tina4-ruby from its stdlib openssl default gem. tina4-python does NOT offer
+// it, because Python's standard library has no asymmetric crypto at all and
+// Tina4 will not add a package for it. That is not an outlier: HMAC is the
+// standard, not a fallback.
+//
+// The capability is PROBED rather than assumed (see `capabilityFailure`). A
+// table says what we intend to support; only running the primitive says what
+// THIS build can do. A crypto provider that refuses RSA-SHA256 must produce the
+// same loud, actionable failure a developer gets from tina4-python — never a
+// silent downgrade to HMAC, never a mysterious `false`.
+//
+// SECURITY, documented rather than buried: HMAC is SYMMETRIC. Every service
+// that VERIFIES a token holds the SAME secret that signs it, so any verifier
+// can also MINT tokens. That is fine for one app or a fleet you control, and
+// WRONG for handing tokens to a third party you do not — RS256 exists so a
+// verifier can hold only the public key.
+//
+// The digest is LOOKED UP from the configured algorithm rather than hardcoded,
+// so the "alg" advertised in the header is always the one that actually
+// produced the signature (python#105). TINA4_JWT_ALGORITHM is read for real,
+// and an algorithm we cannot sign fails loudly instead of silently downgrading
+// to HS256 (python#106).
+
+/** HMAC algorithms → their node:crypto digest name. The cross-framework standard. */
 const HMAC_DIGESTS = new Map<string, string>([
   ["HS256", "sha256"],
   ["HS384", "sha384"],
   ["HS512", "sha512"],
 ]);
 
-/**
- * RSA algorithms → their node:crypto sign/verify algorithm name.
- *
- * Node ships `node:crypto`, so RS256 is legitimately available here at zero
- * dependency cost. Python and Ruby cannot do RS256 without a third-party
- * package, so RS256 is a documented PHP/Node-only EXTRA, not a parity
- * requirement — the HMAC family is the cross-framework contract.
- */
+/** RSA algorithms → their node:crypto sign/verify algorithm name. The opt-in extra. */
 const RSA_SIGN_ALGORITHMS = new Map<string, string>([["RS256", "RSA-SHA256"]]);
 
-/** Every algorithm Tina4 for Node can sign and verify, in the order we advertise them. */
-const SUPPORTED_ALGORITHMS: readonly string[] = [
+/** Every algorithm Tina4 for Node KNOWS, available in this runtime or not. */
+const KNOWN_ALGORITHMS: readonly string[] = [
   ...HMAC_DIGESTS.keys(),
   ...RSA_SIGN_ALGORITHMS.keys(),
 ];
 
+/**
+ * How to get an algorithm back when this runtime cannot provide it. Only the
+ * remedy differs between frameworks; the sentence around it is identical, so
+ * "RS256 is not available" reads the same everywhere.
+ */
+const ALGORITHM_REMEDY = new Map<string, string>([
+  [
+    "RS256",
+    "RS256 comes from builtin node:crypto, so no package installs it — this build's " +
+      'crypto provider refused RSA-SHA256 (check `node -p "process.versions.openssl"`)',
+  ],
+]);
+
+/** Probe results, memoised: algorithm → null when usable here, else the runtime's own reason. */
+const capabilityCache = new Map<string, string | null>();
+
+/**
+ * Ask the RUNTIME — not a lookup table — whether it can actually sign and
+ * verify with `algorithm`, and remember the answer.
+ *
+ * Only meaningful for a KNOWN algorithm; every caller checks membership first.
+ *
+ * @returns `null` when the algorithm works here, else the runtime's own reason.
+ */
+function capabilityFailure(algorithm: string): string | null {
+  const cached = capabilityCache.get(algorithm);
+  if (cached !== undefined) return cached;
+
+  let failure: string | null = null;
+  try {
+    const digest = HMAC_DIGESTS.get(algorithm);
+    if (digest !== undefined) {
+      createHmac(digest, "tina4-capability-probe").update("").digest();
+    } else {
+      const rsaAlgorithm = RSA_SIGN_ALGORITHMS.get(algorithm) as string;
+      createSign(rsaAlgorithm).update("");
+      createVerify(rsaAlgorithm).update("");
+    }
+  } catch (error) {
+    failure = error instanceof Error ? error.message : String(error);
+  }
+  capabilityCache.set(algorithm, failure);
+  return failure;
+}
+
+/**
+ * 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 function algorithmAvailable(algorithm: string): boolean {
+  const chosen = String(algorithm ?? "").trim();
+  return KNOWN_ALGORITHMS.includes(chosen) && capabilityFailure(chosen) === null;
+}
+
+/** Every algorithm this runtime can sign and verify right now, in advertised order. */
+export function availableAlgorithms(): string[] {
+  return KNOWN_ALGORITHMS.filter((algorithm) => capabilityFailure(algorithm) === null);
+}
+
 /**
  * Seconds of clock skew tolerated on the "nbf" (not-before) claim.
  *
@@ -168,28 +252,77 @@ const SUPPORTED_ALGORITHMS: readonly string[] = [
  */
 export const JWT_LEEWAY_SECONDS = 60;
 
-/** The loud, actionable failure for an algorithm we cannot sign — names the supported set. */
+/**
+ * Coerce an RFC 7519 NumericDate claim to integer seconds, else `null`.
+ *
+ * RFC 7519 s2 defines `exp`/`nbf`/`iat` as a NumericDate — a JSON numeric
+ * value. A claim that is PRESENT but not a number is malformed, and a malformed
+ * constraint must never read as "no constraint": treating a non-numeric `exp`
+ * as absent turns a broken token into one that never expires.
+ *
+ * `typeof value === "number"` already excludes boolean, string, null, array and
+ * object; the finite check additionally rejects NaN and Infinity, which would
+ * otherwise make every comparison silently false. Truncation is toward the
+ * earlier second, so a fractional expiry can only expire sooner, never later.
+ */
+function numericDate(value: unknown): number | null {
+  if (typeof value !== "number" || !Number.isFinite(value)) return null;
+  return Math.floor(value);
+}
+
+/** The loud, actionable failure for an algorithm Tina4 does not know at all. */
 function unsupportedAlgorithmError(algorithm: string): Error {
   return new Error(
-    `Unsupported JWT algorithm "${algorithm}". Tina4 signs with ` +
-      `${SUPPORTED_ALGORITHMS.join(", ")} (HMAC via node:crypto; RS256 needs a PEM key pair). ` +
-      `Set TINA4_JWT_ALGORITHM to one of those.`,
+    `Unsupported JWT algorithm "${algorithm}". Tina4 knows ${KNOWN_ALGORITHMS.join(", ")} ` +
+      `(HMAC via node:crypto; RS256 needs a PEM key pair); available in this runtime: ` +
+      `${availableAlgorithms().join(", ") || "(none)"}. ` +
+      `Set TINA4_JWT_ALGORITHM to one of the available ones.`,
+  );
+}
+
+/**
+ * The loud, actionable failure for an algorithm Tina4 knows but this RUNTIME
+ * cannot provide.
+ *
+ * Never a silent fallback to HMAC and never a bare `false`: the message names
+ * WHAT is missing and HOW to get it. The sentence skeleton is identical in
+ * tina4-python / tina4-php / tina4-ruby — only `reason` and the remedy differ —
+ * so "RS256 is not available" is one recognisable experience in all four.
+ */
+function unavailableAlgorithmError(algorithm: string, reason: string): Error {
+  const remedy =
+    ALGORITHM_REMEDY.get(algorithm) ??
+    `${algorithm} comes from builtin node:crypto, so no package installs it — this ` +
+      `build's crypto provider refused it`;
+  return new Error(
+    `JWT algorithm "${algorithm}" is not available in this runtime: ${reason}. ${remedy}. ` +
+      `Available right now: ${availableAlgorithms().join(", ") || "(none)"}. ` +
+      `HMAC (HS256/HS384/HS512) is the Tina4 standard in all four frameworks and ` +
+      `needs no extra dependency.`,
   );
 }
 
 /**
  * Pick the JWT algorithm: explicit argument, else TINA4_JWT_ALGORITHM, else HS256.
  *
- * Throws (naming the supported set and the env var) when asked for an algorithm
- * we cannot sign — a silent downgrade to HS256 is the whole bug in python#106.
+ * 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 function resolveAlgorithm(algorithm?: string): string {
   const chosen = (algorithm || process.env.TINA4_JWT_ALGORITHM || "HS256").trim();
-  if (!HMAC_DIGESTS.has(chosen) && !RSA_SIGN_ALGORITHMS.has(chosen)) {
+  if (!KNOWN_ALGORITHMS.includes(chosen)) {
     throw unsupportedAlgorithmError(chosen);
   }
+  const failure = capabilityFailure(chosen);
+  if (failure !== null) {
+    throw unavailableAlgorithmError(chosen, failure);
+  }
   return chosen;
 }
 
@@ -212,8 +345,11 @@ function base64urlDecode(str: string): Buffer {
  * 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 / RS256 are supported and anything else throws.
+ * 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.
  *
@@ -318,21 +454,33 @@ export function validToken(token: string, secret?: string, algorithm?: string):
 
     const payload = JSON.parse(base64urlDecode(p).toString()) as Record<string, unknown>;
 
-    const now = Date.now() / 1000;
-    if (typeof payload.exp === "number" && now > payload.exp) {
-      return null;
+    // Integer seconds, so all four frameworks compare the SAME number. PHP/Ruby
+    // read an integer clock and Python/Node a float one; with a float clock
+    // `now > exp` and `now >= exp` differ only on an exactly integral instant,
+    // so truncating here is what makes the boundary identical everywhere rather
+    // than merely close.
+    const now = Math.floor(Date.now() / 1000);
+
+    // RFC 7519 s4.1.4: "The processing of the 'exp' claim requires that the
+    // current date/time MUST be before the expiration date/time". now == exp is
+    // therefore ALREADY expired, so the test is >=. A PRESENT but malformed exp
+    // is rejected: the old `typeof payload.exp === "number"` SKIPPED the whole
+    // check for `exp: "abc"` / `exp: null`, so a malformed claim read as a token
+    // that never expires. No exp key at all stays unconstrained (non-breaking).
+    if (Object.hasOwn(payload, "exp")) {
+      const expires = numericDate(payload.exp);
+      if (expires === null || now >= expires) return null;
     }
 
     // "nbf" (not-before): a post-dated token is not valid YET. Was honoured only
     // by Ruby, so Python/PHP/Node accepted tokens their issuer had explicitly
-    // marked as not-yet-usable (nodejs#39 / python#107). A token with no nbf is
-    // unaffected — that is what keeps this non-breaking. A PRESENT but
-    // non-numeric nbf is rejected (Python raises a TypeError there and returns
-    // None; a malformed not-before must never read as "no constraint").
+    // marked as not-yet-usable (nodejs#39 / python#107). Tolerates
+    // JWT_LEEWAY_SECONDS of clock skew, which RFC 7519 s4.1.5 permits. Same
+    // malformed-is-rejected rule as exp, through the same helper so the two
+    // claims can never drift apart.
     if (Object.hasOwn(payload, "nbf")) {
-      const notBefore = payload.nbf;
-      if (typeof notBefore !== "number" || !Number.isFinite(notBefore)) return null;
-      if (now + JWT_LEEWAY_SECONDS < notBefore) return null;
+      const notBefore = numericDate(payload.nbf);
+      if (notBefore === null || now + JWT_LEEWAY_SECONDS < notBefore) return null;
     }
 
     return payload;
@@ -504,7 +652,8 @@ export function refreshToken(
  *
  * @param headers   - Object with header keys (e.g. `{ authorization: "Bearer ..." }`)
  * @param secret    - HMAC secret or PEM public key
- * @param algorithm - "HS256" or "RS256" (default "HS256")
+ * @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 function authenticateRequest(
@@ -573,6 +722,9 @@ export function validateApiKey(
 export class Auth {
   static getToken = getToken;
   static validToken = validToken;
+  static resolveAlgorithm = resolveAlgorithm;
+  static algorithmAvailable = algorithmAvailable;
+  static availableAlgorithms = availableAlgorithms;
   static getPayload = getPayload;
   static hashPassword = hashPassword;
   static checkPassword = checkPassword;

package/packages/core/src/background.ts

@@ -27,21 +27,23 @@ interface BackgroundTask {
 }
 
 const _tasks: BackgroundTask[] = [];
-let _signalsBound = false;
 
-/**
- * Register signal handlers exactly once so SIGTERM/SIGINT during a long-running
- * process clears all background timers before the runtime exits. The handler
- * is additive — it does not call `process.exit()` or interfere with other
- * shutdown logic registered by the CLI or user code.
- */
-function _bindSignalsOnce(): void {
-  if (_signalsBound) return;
-  _signalsBound = true;
-  const cleanup = () => stopAllBackgroundTasks();
-  process.on("SIGTERM", cleanup);
-  process.on("SIGINT", cleanup);
-}
+// This module deliberately installs NO signal handlers.
+//
+// It used to bind `process.on("SIGTERM"/"SIGINT", stopAllBackgroundTasks)`,
+// described as "additive - it does not call process.exit()". That description
+// was the bug. Registering ANY listener for SIGTERM REPLACES Node's default
+// disposition, so a handler that does not exit does not "add" to the default,
+// it CANCELS it: measured against a real signal, a server with one registered
+// background task ignored SIGTERM entirely and ran forever, still answering
+// 200s, until SIGKILL. Under Kubernetes that burns the whole
+// terminationGracePeriodSeconds on every rolling deploy.
+//
+// It also bought nothing: `_arm()` unrefs every timer, so a background task
+// never holds the event loop open and never needed clearing to let the process
+// exit. The server's own graceful shutdown (server.ts) calls
+// stopAllBackgroundTasks() as its first step, and a process using background()
+// without a server keeps Node's correct default (terminate on SIGTERM).
 
 /**
  * Register a callback to run periodically alongside the HTTP server.
@@ -63,8 +65,6 @@ export function background(
     );
   }
 
-  _bindSignalsOnce();
-
   const ms = Math.max(1, Math.round(intervalSeconds * 1000));
 
   // A task must NEVER overlap itself. setInterval fires on a fixed schedule and
@@ -109,9 +109,9 @@ export function background(
 }
 
 /**
- * Clear every registered background task. Called automatically on SIGTERM/SIGINT;
- * also called from the server's `close()` so a manual server shutdown stops
- * the timer wheel along with HTTP listeners.
+ * 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 function stopAllBackgroundTasks(): void {
   while (_tasks.length > 0) {