tina4-nodejs 3.13.78 → 3.13.81

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.78)
+# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.81)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
 ## What This Project Is
 
-Tina4 for Node.js/TypeScript v3.13.78 - The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
+Tina4 for Node.js/TypeScript v3.13.81 - The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
 
 The philosophy: zero ceremony, batteries included, file system as source of truth.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.13.78",
+  "version": "3.13.81",
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript - 54 built-in features, zero dependencies",
   "keywords": [

package/packages/core/src/index.ts

@@ -48,7 +48,7 @@ export {
   ensureDevSecret,
   Auth,
 } from "./auth.js";
-export { Session, FileSessionHandler, RedisSessionHandler, buildSessionCookie } from "./session.js";
+export { Session, FileSessionHandler, RedisSessionHandler, buildSessionCookie, isSecureScheme, sessionCookieName } from "./session.js";
 export type { SessionConfig, SessionHandler } from "./session.js";
 export { I18n } from "./i18n.js";
 export { FakeData } from "./fakeData.js";

package/packages/core/src/server.ts

@@ -1102,13 +1102,25 @@ ${reset}
 
     // Auto-start session — read cookie, create session, save + set cookie on response end
     {
-      const { Session, buildSessionCookie } = await import("./session.js");
+      const { Session, buildSessionCookie, sessionCookieName } = await import("./session.js");
       const cookieHeader = rawReq.headers.cookie ?? "";
-      const cookieName = process.env.TINA4_SESSION_NAME ?? "tina4_session";
-      // Build a regex from the (possibly customised) cookie name. Escape regex meta-chars.
-      const escapedName = cookieName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-      const sidMatch = cookieHeader.match(new RegExp(`${escapedName}=([^;]+)`));
-      const existingSid = sidMatch ? sidMatch[1] : undefined;
+      // Read the incoming session cookie by the SAME configured name the write
+      // side emits (TINA4_SESSION_NAME, default tina4_session) via the shared
+      // sessionCookieName() resolver — otherwise a renamed cookie would be
+      // written but never read back and the session would silently never
+      // resume. Match a whole cookie pair by its exact `name=` prefix (split on
+      // ";", trim, startsWith) so `tina4_session` never matches
+      // `tina4_session_foo=` nor a value mid-header. Parity with Python
+      // core/server._init_session.
+      const cookiePrefix = sessionCookieName() + "=";
+      let existingSid: string | undefined;
+      for (const part of cookieHeader.split(";")) {
+        const trimmed = part.trim();
+        if (trimmed.startsWith(cookiePrefix)) {
+          existingSid = trimmed.slice(cookiePrefix.length);
+          break;
+        }
+      }
       const sess = new Session();
       sess.start(existingSid);
       (req as any).session = sess;
@@ -1125,7 +1137,14 @@ ${reset}
         const newSid = (sess as any).sessionId ?? (sess as any).getSessionId?.();
         if (newSid && newSid !== existingSid && !rawRes.headersSent) {
           const ttl = parseInt(process.env.TINA4_SESSION_TTL ?? "3600", 10);
-          rawRes.setHeader("Set-Cookie", buildSessionCookie(newSid, ttl));
+          // Thread the client's real scheme in so an HTTPS deploy behind a
+          // TLS-terminating proxy ships the session cookie with `Secure`
+          // (nodejs#34). `x-forwarded-proto` is the same header request.ts
+          // trusts for URL construction; native socket TLS is the fallback.
+          const xfProto = rawReq.headers["x-forwarded-proto"];
+          const forwardedProto = Array.isArray(xfProto) ? xfProto[0] : xfProto;
+          const socketEncrypted = (rawReq.socket as { encrypted?: boolean })?.encrypted === true;
+          rawRes.setHeader("Set-Cookie", buildSessionCookie(newSid, ttl, undefined, forwardedProto, socketEncrypted));
         }
         return origEnd(...args);
       } as typeof rawRes.end;

package/packages/core/src/session.ts

@@ -589,6 +589,51 @@ export class Session {
   }
 }
 
+/**
+ * Is the client's scheme HTTPS? Proxy-aware.
+ *
+ * TLS is normally terminated at a proxy (nginx, HAProxy, ALB, Cloudflare, most
+ * container deploys) which then forwards plain HTTP to Node — so the native
+ * socket is NOT encrypted on exactly the deployments that ARE https, and it
+ * cannot be the only signal. `x-forwarded-proto` carries the scheme the client
+ * actually used; a chain of proxies appends each hop ("https, http") and the
+ * FIRST is the client-facing one, which is the scheme the browser used.
+ *
+ * Parity with PHP `Request::isSecureScheme` (tina4-php#175). Spoofable when the
+ * app is directly reachable, but the failure mode is self-limiting: a spoofed
+ * `https` only makes the cookie MORE restrictive, and `request.ts` already
+ * trusts the same header for URL construction — honouring it here is consistent.
+ *
+ * @param forwardedProto Raw `x-forwarded-proto` value (or a resolved scheme like
+ *                       "https"/"http"); "" / undefined means "absent".
+ * @param socketEncrypted True when Node terminated TLS itself (direct https, no
+ *                        proxy) — the native fallback when no forwarded header.
+ */
+export function isSecureScheme(forwardedProto?: string, socketEncrypted?: boolean): boolean {
+  const forwarded = (forwardedProto ?? "").trim();
+  if (forwarded !== "") {
+    return forwarded.split(",")[0].trim().toLowerCase() === "https";
+  }
+  return socketEncrypted === true;
+}
+
+/**
+ * Resolve the session cookie name — the single source of truth shared by the
+ * WRITE side (`buildSessionCookie` / `Session.cookieHeader`) and the READ side
+ * (the auto-session cookie parse in `server.ts`), so a cookie written under a
+ * renamed name is read back on the next request.
+ *
+ *   TINA4_SESSION_NAME   Cookie name (default: "tina4_session")
+ *
+ * Keeping this in one place means the default can never drift between the two
+ * sides: an operator who sets `TINA4_SESSION_NAME` renames the cookie on both
+ * the emit and the parse paths at once. Parity with Python
+ * `session.session_cookie_name()`.
+ */
+export function sessionCookieName(): string {
+  return process.env.TINA4_SESSION_NAME ?? "tina4_session";
+}
+
 /**
  * Build the `Set-Cookie` header value for a Tina4 session. Centralised so
  * the auto-cookie path in server.ts and `Session.cookieHeader()` agree on
@@ -598,10 +643,25 @@ export class Session {
  *   TINA4_SESSION_NAME      — cookie name (default: "tina4_session")
  *   TINA4_SESSION_SAMESITE  — SameSite attribute (default: "Lax")
  *   TINA4_SESSION_HTTPONLY  — emit HttpOnly (default: true)
- *   TINA4_SESSION_SECURE    — emit Secure (default: false)
+ *   TINA4_SESSION_SECURE    — emit Secure (default: false; SameSite=None forces it on)
+ *
+ * `Secure` is emitted when ANY of: TINA4_SESSION_SECURE is truthy; SameSite is
+ * `None` (browsers reject a None cookie without Secure); OR the request scheme
+ * is https, detected proxy-aware from `forwardedProto` / `socketEncrypted`. The
+ * auto-cookie path in server.ts threads the request's scheme in so an HTTPS
+ * deploy behind a TLS-terminating proxy ships Secure without the operator
+ * having to know about TINA4_SESSION_SECURE (nodejs#34). Plain HTTP with no
+ * proxy header and no native TLS stays NOT Secure — an eager Secure would make
+ * http://localhost dev cookies undeliverable.
  */
-export function buildSessionCookie(sessionId: string | null, ttl: number, cookieName?: string): string {
-  const name = cookieName ?? process.env.TINA4_SESSION_NAME ?? "tina4_session";
+export function buildSessionCookie(
+  sessionId: string | null,
+  ttl: number,
+  cookieName?: string,
+  forwardedProto?: string,
+  socketEncrypted?: boolean,
+): string {
+  const name = cookieName ?? sessionCookieName();
   const sameSite = process.env.TINA4_SESSION_SAMESITE ?? "Lax";
 
   // HttpOnly defaults to TRUE (matches existing behaviour and Python parity).
@@ -611,10 +671,10 @@ export function buildSessionCookie(sessionId: string | null, ttl: number, cookie
     ? true
     : !["false", "0", "no", "off"].includes(httpOnlyRaw.trim().toLowerCase());
 
-  // Secure defaults to FALSE — only emit when the operator opts in (https
-  // deployments). Setting it eagerly would break http://localhost dev cookies.
-  const secureRaw = process.env.TINA4_SESSION_SECURE ?? "";
-  const secure = ["true", "1", "yes", "on"].includes(secureRaw.trim().toLowerCase());
+  // Secure defaults to FALSE, then turns ON for any of the three signals above.
+  const secure = isTruthy(process.env.TINA4_SESSION_SECURE)
+    || sameSite.trim().toLowerCase() === "none"
+    || isSecureScheme(forwardedProto, socketEncrypted);
 
   const parts = [`${name}=${sessionId ?? ""}`, "Path=/"];
   if (httpOnly) parts.push("HttpOnly");