tina4-nodejs 3.13.147 → 3.13.148

package/CLAUDE.md

@@ -13,13 +13,13 @@ Even if the skill text is not currently loaded, these are non-negotiable:
 
 The full discipline lives in `.claude/skills/tina4-maintainer/SKILL.md`; this block is the always-on floor.
 
-# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.147)
+# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.148)
 
 > 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.147 - 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.148 - 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.147",
+  "version": "3.13.148",
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript - native TypeScript conventions and shared Tina4 contracts",
   "keywords": [

package/packages/cli/dist/bin.js

@@ -23878,6 +23878,7 @@ __export(session_exports, {
   isSecureScheme: () => isSecureScheme,
   isValidSessionId: () => isValidSessionId,
   sessionCookieName: () => sessionCookieName,
+  sessionCookieToSend: () => sessionCookieToSend,
   sessionStrictMode: () => sessionStrictMode
 });
 import { createHash as createHash5, randomBytes as randomBytes6 } from "node:crypto";
@@ -23938,6 +23939,15 @@ function buildSessionCookie(sessionId, ttl, cookieName, forwardedProto, socketEn
   parts.push(`Max-Age=${ttl}`);
   return parts.join("; ");
 }
+function sessionCookieToSend(sess, existingSid, rawReq, rawRes) {
+  const newSid = sess.sessionId ?? sess.getSessionId?.();
+  if (!newSid || newSid === existingSid || sess.isFresh() || rawRes.headersSent) return null;
+  const ttl = parseInt(process.env.TINA4_SESSION_TTL ?? "3600", 10);
+  const xfProto = rawReq.headers["x-forwarded-proto"];
+  const forwardedProto = Array.isArray(xfProto) ? xfProto[0] : xfProto;
+  const socketEncrypted = rawReq.socket?.encrypted === true;
+  return buildSessionCookie(newSid, ttl, void 0, forwardedProto, socketEncrypted);
+}
 var SESSION_ID_PATTERN, VALID_SESSION_BACKENDS, CANONICAL_SESSION_BACKENDS, RETIRED_SESSION_BACKENDS, FileSessionHandler, RedisSessionHandler, FLASH_PREFIX, Session;
 var init_session = __esm({
   "../core/src/session.ts"() {
@@ -24300,7 +24310,6 @@ var init_session = __esm({
         const now = Math.floor(Date.now() / 1e3);
         this.data = { _created: now, _accessed: now };
         this.dirty = false;
-        this.safeWrite(this.sessionId, this.data, this.ttl);
         this.stored = false;
         this.loaded = /* @__PURE__ */ new Map();
         this.cleared = false;
@@ -24451,6 +24460,19 @@ var init_session = __esm({
         const result = this.flash(key);
         return result !== void 0 ? result : defaultValue;
       }
+      /**
+       * Whether this session is only an id: nothing has stored it and it holds no
+       * data of its own (its `_created` / `_accessed` bookkeeping does not count).
+       * Such a session has no record and needs no cookie, so save() writes nothing
+       * for it and the server sends no cookie for it. It stops being fresh when
+       * something is stored in it. Calls that mark a session changed without leaving
+       * anything in it (deleting a key it never had, clear(), regenerate() on an
+       * empty session) leave it fresh: a record with no data is not a session.
+       */
+      isFresh() {
+        if (this.stored) return false;
+        return !this.data || Object.keys(this.data).every((k) => k === "_created" || k === "_accessed");
+      }
       /**
        * Get the current session ID.
        */
@@ -24513,7 +24535,7 @@ var init_session = __esm({
        */
       save() {
         if (!this.sessionId || !this.data) return true;
-        if (!this.dirty && !this.stored) return true;
+        if (this.isFresh()) return true;
         let record = this.data;
         if (this.stored) {
           const current = this.safeRead(this.sessionId);
@@ -24700,7 +24722,7 @@ function errorLabel(err) {
   return err instanceof Error ? `${err.name}: ${err.message}` : String(err);
 }
 async function sessionAutoStart(rawReq, rawRes, req2) {
-  const { Session: Session2, buildSessionCookie: buildSessionCookie2, sessionCookieName: sessionCookieName2, sessionStrictMode: sessionStrictMode2 } = await Promise.resolve().then(() => (init_session(), session_exports));
+  const { Session: Session2, sessionCookieToSend: sessionCookieToSend2, sessionCookieName: sessionCookieName2, sessionStrictMode: sessionStrictMode2 } = await Promise.resolve().then(() => (init_session(), session_exports));
   const cookieHeader = rawReq.headers.cookie ?? "";
   const cookiePrefix = sessionCookieName2() + "=";
   let existingSid;
@@ -24739,13 +24761,9 @@ async function sessionAutoStart(rawReq, rawRes, req2) {
       } catch {
       }
     }
-    const newSid = sess.sessionId ?? sess.getSessionId?.();
-    if (newSid && newSid !== existingSid && !rawRes.headersSent) {
-      const ttl = parseInt(process.env.TINA4_SESSION_TTL ?? "3600", 10);
-      const xfProto = rawReq.headers["x-forwarded-proto"];
-      const forwardedProto = Array.isArray(xfProto) ? xfProto[0] : xfProto;
-      const socketEncrypted = rawReq.socket?.encrypted === true;
-      rawRes.appendHeader("Set-Cookie", buildSessionCookie2(newSid, ttl, void 0, forwardedProto, socketEncrypted));
+    const sessionCookie = sessionCookieToSend2(sess, existingSid, rawReq, rawRes);
+    if (sessionCookie !== null) {
+      rawRes.appendHeader("Set-Cookie", sessionCookie);
     }
     return origEnd(...args);
   };

package/packages/core/dist/index.js

@@ -23857,6 +23857,7 @@ __export(session_exports, {
   isSecureScheme: () => isSecureScheme,
   isValidSessionId: () => isValidSessionId,
   sessionCookieName: () => sessionCookieName,
+  sessionCookieToSend: () => sessionCookieToSend,
   sessionStrictMode: () => sessionStrictMode
 });
 import { createHash as createHash5, randomBytes as randomBytes6 } from "node:crypto";
@@ -23917,6 +23918,15 @@ function buildSessionCookie(sessionId, ttl, cookieName, forwardedProto, socketEn
   parts.push(`Max-Age=${ttl}`);
   return parts.join("; ");
 }
+function sessionCookieToSend(sess, existingSid, rawReq, rawRes) {
+  const newSid = sess.sessionId ?? sess.getSessionId?.();
+  if (!newSid || newSid === existingSid || sess.isFresh() || rawRes.headersSent) return null;
+  const ttl = parseInt(process.env.TINA4_SESSION_TTL ?? "3600", 10);
+  const xfProto = rawReq.headers["x-forwarded-proto"];
+  const forwardedProto = Array.isArray(xfProto) ? xfProto[0] : xfProto;
+  const socketEncrypted = rawReq.socket?.encrypted === true;
+  return buildSessionCookie(newSid, ttl, void 0, forwardedProto, socketEncrypted);
+}
 var SESSION_ID_PATTERN, VALID_SESSION_BACKENDS, CANONICAL_SESSION_BACKENDS, RETIRED_SESSION_BACKENDS, FileSessionHandler, RedisSessionHandler, FLASH_PREFIX, Session;
 var init_session = __esm({
   "src/session.ts"() {
@@ -24279,7 +24289,6 @@ var init_session = __esm({
         const now = Math.floor(Date.now() / 1e3);
         this.data = { _created: now, _accessed: now };
         this.dirty = false;
-        this.safeWrite(this.sessionId, this.data, this.ttl);
         this.stored = false;
         this.loaded = /* @__PURE__ */ new Map();
         this.cleared = false;
@@ -24430,6 +24439,19 @@ var init_session = __esm({
         const result = this.flash(key);
         return result !== void 0 ? result : defaultValue;
       }
+      /**
+       * Whether this session is only an id: nothing has stored it and it holds no
+       * data of its own (its `_created` / `_accessed` bookkeeping does not count).
+       * Such a session has no record and needs no cookie, so save() writes nothing
+       * for it and the server sends no cookie for it. It stops being fresh when
+       * something is stored in it. Calls that mark a session changed without leaving
+       * anything in it (deleting a key it never had, clear(), regenerate() on an
+       * empty session) leave it fresh: a record with no data is not a session.
+       */
+      isFresh() {
+        if (this.stored) return false;
+        return !this.data || Object.keys(this.data).every((k) => k === "_created" || k === "_accessed");
+      }
       /**
        * Get the current session ID.
        */
@@ -24492,7 +24514,7 @@ var init_session = __esm({
        */
       save() {
         if (!this.sessionId || !this.data) return true;
-        if (!this.dirty && !this.stored) return true;
+        if (this.isFresh()) return true;
         let record = this.data;
         if (this.stored) {
           const current = this.safeRead(this.sessionId);
@@ -24679,7 +24701,7 @@ function errorLabel(err) {
   return err instanceof Error ? `${err.name}: ${err.message}` : String(err);
 }
 async function sessionAutoStart(rawReq, rawRes, req2) {
-  const { Session: Session2, buildSessionCookie: buildSessionCookie2, sessionCookieName: sessionCookieName2, sessionStrictMode: sessionStrictMode2 } = await Promise.resolve().then(() => (init_session(), session_exports));
+  const { Session: Session2, sessionCookieToSend: sessionCookieToSend2, sessionCookieName: sessionCookieName2, sessionStrictMode: sessionStrictMode2 } = await Promise.resolve().then(() => (init_session(), session_exports));
   const cookieHeader = rawReq.headers.cookie ?? "";
   const cookiePrefix = sessionCookieName2() + "=";
   let existingSid;
@@ -24718,13 +24740,9 @@ async function sessionAutoStart(rawReq, rawRes, req2) {
       } catch {
       }
     }
-    const newSid = sess.sessionId ?? sess.getSessionId?.();
-    if (newSid && newSid !== existingSid && !rawRes.headersSent) {
-      const ttl = parseInt(process.env.TINA4_SESSION_TTL ?? "3600", 10);
-      const xfProto = rawReq.headers["x-forwarded-proto"];
-      const forwardedProto = Array.isArray(xfProto) ? xfProto[0] : xfProto;
-      const socketEncrypted = rawReq.socket?.encrypted === true;
-      rawRes.appendHeader("Set-Cookie", buildSessionCookie2(newSid, ttl, void 0, forwardedProto, socketEncrypted));
+    const sessionCookie = sessionCookieToSend2(sess, existingSid, rawReq, rawRes);
+    if (sessionCookie !== null) {
+      rawRes.appendHeader("Set-Cookie", sessionCookie);
     }
     return origEnd(...args);
   };

package/packages/core/src/dispatchPipeline.ts

@@ -367,7 +367,7 @@ export async function sessionAutoStart(
   rawRes: ServerResponse,
   req: Tina4Request,
 ): Promise<void> {
-  const { Session, buildSessionCookie, sessionCookieName, sessionStrictMode } =
+  const { Session, sessionCookieToSend, sessionCookieName, sessionStrictMode } =
     await import("./session.js");
   const cookieHeader = rawReq.headers.cookie ?? "";
 
@@ -433,16 +433,8 @@ export async function sessionAutoStart(
       try { sess.gc(); } catch { /* GC failure is non-critical */ }
     }
 
-    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);
-      // 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;
+    const sessionCookie = sessionCookieToSend(sess, existingSid, rawReq, rawRes);
+    if (sessionCookie !== null) {
       // appendHeader, not setHeader (feature 131 fix, found while proving
       // TC-DEC-02): setHeader REPLACES any existing Set-Cookie value wholesale,
       // so a route that had already called response.cookie() of its own — on
@@ -452,7 +444,7 @@ export async function sessionAutoStart(
       // appendHeader adds to whatever is already there (promoting a scalar to
       // an array, extending an existing array) and behaves exactly like
       // setHeader when nothing is set yet, so the common case is unchanged.
-      rawRes.appendHeader("Set-Cookie", buildSessionCookie(newSid, ttl, undefined, forwardedProto, socketEncrypted));
+      rawRes.appendHeader("Set-Cookie", sessionCookie);
     }
     return origEnd(...args);
   } as typeof rawRes.end;

package/packages/core/src/session.ts

@@ -610,12 +610,14 @@ export class Session {
       }
     }
 
-    // Generate new session
+    // Generate new session. Nothing is written for it yet: a session nobody
+    // writes to has nothing to keep, and writing it here stored one record for
+    // every request that arrived without a cookie (static files, 404s and
+    // /health included). Its first save() after a change writes it whole.
     this.sessionId = randomBytes(16).toString("hex");
     const now = Math.floor(Date.now() / 1000);
     this.data = { _created: now, _accessed: now };
     this.dirty = false;
-    this.safeWrite(this.sessionId, this.data, this.ttl);
     this.stored = false;
     this.loaded = new Map();
     this.cleared = false;
@@ -785,6 +787,20 @@ export class Session {
     return result !== undefined ? result : defaultValue;
   }
 
+  /**
+   * Whether this session is only an id: nothing has stored it and it holds no
+   * data of its own (its `_created` / `_accessed` bookkeeping does not count).
+   * Such a session has no record and needs no cookie, so save() writes nothing
+   * for it and the server sends no cookie for it. It stops being fresh when
+   * something is stored in it. Calls that mark a session changed without leaving
+   * anything in it (deleting a key it never had, clear(), regenerate() on an
+   * empty session) leave it fresh: a record with no data is not a session.
+   */
+  isFresh(): boolean {
+    if (this.stored) return false;
+    return !this.data || Object.keys(this.data).every((k) => k === "_created" || k === "_accessed");
+  }
+
   /**
    * Get the current session ID.
    */
@@ -850,7 +866,7 @@ export class Session {
    */
   save(): boolean {
     if (!this.sessionId || !this.data) return true;
-    if (!this.dirty && !this.stored) return true;
+    if (this.isFresh()) return true;
     let record: SessionData = this.data;
     if (this.stored) {
       const current = this.safeRead(this.sessionId);
@@ -1018,3 +1034,29 @@ export function buildSessionCookie(
   parts.push(`Max-Age=${ttl}`);
   return parts.join("; ");
 }
+
+/**
+ * The Set-Cookie value that hands the client this request's session, or null
+ * when none is owed: the client already holds the id, headers have gone out, or
+ * the session is fresh. A fresh session (only an id: minted for this request
+ * and holding no data) was not stored, so a cookie for it would name nothing:
+ * the next request could not resume it and would be handed another one.
+ */
+export function sessionCookieToSend(
+  sess: { isFresh(): boolean },
+  existingSid: string | undefined,
+  rawReq: { headers: Record<string, string | string[] | undefined>; socket?: unknown },
+  rawRes: { headersSent: boolean },
+): string | null {
+  const newSid = (sess as any).sessionId ?? (sess as any).getSessionId?.();
+  if (!newSid || newSid === existingSid || sess.isFresh() || rawRes.headersSent) return null;
+  const ttl = parseInt(process.env.TINA4_SESSION_TTL ?? "3600", 10);
+  // 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 } | undefined)?.encrypted === true;
+  return buildSessionCookie(newSid, ttl, undefined, forwardedProto, socketEncrypted);
+}

package/packages/orm/dist/index.js

@@ -11833,6 +11833,7 @@ __export(session_exports, {
   isSecureScheme: () => isSecureScheme,
   isValidSessionId: () => isValidSessionId,
   sessionCookieName: () => sessionCookieName,
+  sessionCookieToSend: () => sessionCookieToSend,
   sessionStrictMode: () => sessionStrictMode
 });
 import { createHash as createHash5, randomBytes as randomBytes4 } from "node:crypto";
@@ -11893,6 +11894,15 @@ function buildSessionCookie(sessionId, ttl, cookieName, forwardedProto, socketEn
   parts.push(`Max-Age=${ttl}`);
   return parts.join("; ");
 }
+function sessionCookieToSend(sess, existingSid, rawReq, rawRes) {
+  const newSid = sess.sessionId ?? sess.getSessionId?.();
+  if (!newSid || newSid === existingSid || sess.isFresh() || rawRes.headersSent) return null;
+  const ttl = parseInt(process.env.TINA4_SESSION_TTL ?? "3600", 10);
+  const xfProto = rawReq.headers["x-forwarded-proto"];
+  const forwardedProto = Array.isArray(xfProto) ? xfProto[0] : xfProto;
+  const socketEncrypted = rawReq.socket?.encrypted === true;
+  return buildSessionCookie(newSid, ttl, void 0, forwardedProto, socketEncrypted);
+}
 var SESSION_ID_PATTERN, VALID_SESSION_BACKENDS, CANONICAL_SESSION_BACKENDS, RETIRED_SESSION_BACKENDS, FileSessionHandler, RedisSessionHandler, FLASH_PREFIX, Session;
 var init_session = __esm({
   "../core/src/session.ts"() {
@@ -12255,7 +12265,6 @@ var init_session = __esm({
         const now = Math.floor(Date.now() / 1e3);
         this.data = { _created: now, _accessed: now };
         this.dirty = false;
-        this.safeWrite(this.sessionId, this.data, this.ttl);
         this.stored = false;
         this.loaded = /* @__PURE__ */ new Map();
         this.cleared = false;
@@ -12406,6 +12415,19 @@ var init_session = __esm({
         const result = this.flash(key);
         return result !== void 0 ? result : defaultValue;
       }
+      /**
+       * Whether this session is only an id: nothing has stored it and it holds no
+       * data of its own (its `_created` / `_accessed` bookkeeping does not count).
+       * Such a session has no record and needs no cookie, so save() writes nothing
+       * for it and the server sends no cookie for it. It stops being fresh when
+       * something is stored in it. Calls that mark a session changed without leaving
+       * anything in it (deleting a key it never had, clear(), regenerate() on an
+       * empty session) leave it fresh: a record with no data is not a session.
+       */
+      isFresh() {
+        if (this.stored) return false;
+        return !this.data || Object.keys(this.data).every((k) => k === "_created" || k === "_accessed");
+      }
       /**
        * Get the current session ID.
        */
@@ -12468,7 +12490,7 @@ var init_session = __esm({
        */
       save() {
         if (!this.sessionId || !this.data) return true;
-        if (!this.dirty && !this.stored) return true;
+        if (this.isFresh()) return true;
         let record = this.data;
         if (this.stored) {
           const current = this.safeRead(this.sessionId);
@@ -12655,7 +12677,7 @@ function errorLabel(err) {
   return err instanceof Error ? `${err.name}: ${err.message}` : String(err);
 }
 async function sessionAutoStart(rawReq, rawRes, req2) {
-  const { Session: Session2, buildSessionCookie: buildSessionCookie2, sessionCookieName: sessionCookieName2, sessionStrictMode: sessionStrictMode2 } = await Promise.resolve().then(() => (init_session(), session_exports));
+  const { Session: Session2, sessionCookieToSend: sessionCookieToSend2, sessionCookieName: sessionCookieName2, sessionStrictMode: sessionStrictMode2 } = await Promise.resolve().then(() => (init_session(), session_exports));
   const cookieHeader = rawReq.headers.cookie ?? "";
   const cookiePrefix = sessionCookieName2() + "=";
   let existingSid;
@@ -12694,13 +12716,9 @@ async function sessionAutoStart(rawReq, rawRes, req2) {
       } catch {
       }
     }
-    const newSid = sess.sessionId ?? sess.getSessionId?.();
-    if (newSid && newSid !== existingSid && !rawRes.headersSent) {
-      const ttl = parseInt(process.env.TINA4_SESSION_TTL ?? "3600", 10);
-      const xfProto = rawReq.headers["x-forwarded-proto"];
-      const forwardedProto = Array.isArray(xfProto) ? xfProto[0] : xfProto;
-      const socketEncrypted = rawReq.socket?.encrypted === true;
-      rawRes.appendHeader("Set-Cookie", buildSessionCookie2(newSid, ttl, void 0, forwardedProto, socketEncrypted));
+    const sessionCookie = sessionCookieToSend2(sess, existingSid, rawReq, rawRes);
+    if (sessionCookie !== null) {
+      rawRes.appendHeader("Set-Cookie", sessionCookie);
     }
     return origEnd(...args);
   };

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

@@ -258,6 +258,16 @@ export declare class Session {
      * Get flash data by key (alias for flash(key) without value).
      */
     getFlash(key: string, defaultValue?: unknown): unknown;
+    /**
+     * Whether this session is only an id: nothing has stored it and it holds no
+     * data of its own (its `_created` / `_accessed` bookkeeping does not count).
+     * Such a session has no record and needs no cookie, so save() writes nothing
+     * for it and the server sends no cookie for it. It stops being fresh when
+     * something is stored in it. Calls that mark a session changed without leaving
+     * anything in it (deleting a key it never had, clear(), regenerate() on an
+     * empty session) leave it fresh: a record with no data is not a session.
+     */
+    isFresh(): boolean;
     /**
      * Get the current session ID.
      */
@@ -388,4 +398,19 @@ export declare function sessionStrictMode(): boolean;
  * http://localhost dev cookies undeliverable.
  */
 export declare function buildSessionCookie(sessionId: string | null, ttl: number, cookieName?: string, forwardedProto?: string, socketEncrypted?: boolean): string;
+/**
+ * The Set-Cookie value that hands the client this request's session, or null
+ * when none is owed: the client already holds the id, headers have gone out, or
+ * the session is fresh. A fresh session (only an id: minted for this request
+ * and holding no data) was not stored, so a cookie for it would name nothing:
+ * the next request could not resume it and would be handed another one.
+ */
+export declare function sessionCookieToSend(sess: {
+    isFresh(): boolean;
+}, existingSid: string | undefined, rawReq: {
+    headers: Record<string, string | string[] | undefined>;
+    socket?: unknown;
+}, rawRes: {
+    headersSent: boolean;
+}): string | null;
 export {};