tina4-nodejs 3.13.134 → 3.13.136

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.134)
+# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.136)
 
 > 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.134 - 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.136 - 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.134",
+  "version": "3.13.136",
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript - native TypeScript conventions and shared Tina4 contracts",
   "keywords": [

package/packages/cli/dist/bin.js

@@ -35062,6 +35062,13 @@ function toolbarJs() {
         el.className = 't4-ok';
         el.innerHTML = 'Latest: <strong class="t4-ok">v' + latest + '</strong> &mdash; You are up to date!';
     }
+    // A check that did not happen is not a clean bill of health. The server
+    // sends latest: null when it could not reach the registry, and saying so is
+    // the whole point -- "up to date" here would be a guess dressed as a fact.
+    function couldNotCheck(el, why) {
+        el.className = 't4-err';
+        el.textContent = 'Could not check for updates' + (why ? ' (' + why + ')' : '');
+    }
     function checkVersion() {
         if (modal.style.display === 'block') { modal.style.display = 'none'; return; }
         modal.style.display = 'block';
@@ -35070,6 +35077,7 @@ function toolbarJs() {
         el.textContent = 'Checking for updates...';
         fetch('/__dev/api/version-check').then(function (r) { return r.json(); }).then(function (d) {
             var latest = d.latest, current = d.current;
+            if (!latest) { couldNotCheck(el, d.error); return; }
             if (latest === current) { upToDate(el, latest); return; }
             var cP = current.split('.').map(Number), lP = latest.split('.').map(Number);
             var isNewer = false, i, c, l;
@@ -36412,21 +36420,28 @@ var init_devAdmin = __esm({
     };
     handleVersionCheck = async (_req, res) => {
       const current = TINA4_VERSION;
-      let latest = current;
+      const url = process.env.TINA4_VERSION_CHECK_URL || "https://registry.npmjs.org/tina4-nodejs/latest";
+      const failed = (why) => res.json({ current, latest: null, error: why });
+      let data;
       try {
         const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), 5e3);
-        const resp = await fetch("https://registry.npmjs.org/tina4-nodejs/latest", {
-          signal: controller.signal
-        });
-        clearTimeout(timeout);
-        if (resp.ok) {
-          const data = await resp.json();
-          if (typeof data.version === "string") latest = data.version;
+        const timer = setTimeout(() => controller.abort(), 5e3);
+        try {
+          const resp = await fetch(url, {
+            signal: controller.signal,
+            headers: { "User-Agent": `tina4-nodejs/${current}` }
+          });
+          if (!resp.ok) return failed(`npm registry responded ${resp.status}`);
+          data = await resp.json();
+        } finally {
+          clearTimeout(timer);
         }
-      } catch {
+      } catch (exc) {
+        return failed(exc instanceof Error && exc.message ? exc.message : String(exc));
       }
-      res.json({ current, latest });
+      const latest = typeof data.version === "string" ? data.version : "";
+      if (!latest) return failed("npm registry did not report a version");
+      return res.json({ current, latest });
     };
     handleThoughts = (req2, res) => {
       const url = new URL(req2.url ?? "/", "http://localhost");
@@ -37940,13 +37955,37 @@ function swaggerEnabled() {
   return ["true", "1", "yes", "on"].includes(raw);
 }
 function createSwaggerRoutes(getSpec) {
+  const serveUi = async (_req, res) => {
+    res.html(SWAGGER_UI_HTML("/swagger/openapi.json"));
+  };
   return [
     {
       method: "GET",
       pattern: "/swagger",
-      handler: async (_req, res) => {
-        res.html(SWAGGER_UI_HTML("/swagger/openapi.json"));
-      }
+      handler: serveUi
+    },
+    {
+      // The trailing-slash form, registered rather than left to fall through.
+      //
+      // Matching "/foo/" against a "/foo" route is opt-in via
+      // TINA4_TRAILING_SLASH_REDIRECT and OFF by default, so /swagger/ missed
+      // this route and was answered by the framework-bundled
+      // public/swagger/index.html instead. That mattered twice over. It used to
+      // be a 200 carrying a permanently empty UI, because the bundled file asked
+      // for an unsubstituted {SWAGGER_ROUTE}/swagger.json -- fixed in that file.
+      // And it is a SECOND Swagger UI implementation: the bundled one hardcodes
+      // cdnjs, while the page this handler renders loads from
+      // TINA4_SWAGGER_UI_CDN, so an air-gapped deployment pointing that at a
+      // local mirror silently kept reaching cdnjs on this one path.
+      //
+      // Registering it keeps the fix inside swagger rather than changing how
+      // every route treats trailing slashes, satisfies the shared contract that
+      // already requires a 200 here, and matches python and ruby, which both
+      // serve /swagger and /swagger/ with no env var set. Excluded from the
+      // generated document by INTERNAL_PREFIXES like /swagger itself.
+      method: "GET",
+      pattern: "/swagger/",
+      handler: serveUi
     },
     {
       method: "GET",
@@ -39650,7 +39689,7 @@ async function configureSwagger(router, ormDir, modelsDir) {
   try {
     const swagger = await Promise.resolve().then(() => (init_src2(), src_exports2));
     enabled = swagger.swaggerEnabled();
-    if (!swaggerAssetsEnabled) {
+    if (!enabled) {
       throw new Error("__swagger_disabled__");
     }
     let modelDefs = [];
@@ -44258,6 +44297,9 @@ function decodeBase64Url(value, name) {
   }
   return Buffer.from(value.replace(/-/g, "+").replace(/_/g, "/"), "base64");
 }
+function pad32(value) {
+  return value.length >= 32 ? value : Buffer.concat([Buffer.alloc(32 - value.length), value]);
+}
 function vapidPrivateKey(rawPrivate, rawPublic) {
   if (rawPublic.length !== 65 || rawPublic[0] !== 4) throw new PushError("P-256 public keys must be 65-byte uncompressed points");
   const x = encodeBase64Url(rawPublic.subarray(1, 33));
@@ -44266,7 +44308,7 @@ function vapidPrivateKey(rawPrivate, rawPublic) {
     key: {
       kty: "EC",
       crv: "P-256",
-      d: encodeBase64Url(rawPrivate),
+      d: encodeBase64Url(pad32(rawPrivate)),
       x,
       y,
       ext: true
@@ -44360,8 +44402,10 @@ function generateVapidKeys() {
   const ecdh = createECDH(CURVE);
   ecdh.generateKeys();
   return {
+    // getPublicKey keeps its 65-byte width; getPrivateKey drops a leading zero
+    // byte, so the scalar must be padded to the fixed field width.
     publicKey: encodeBase64Url(ecdh.getPublicKey(void 0, "uncompressed")),
-    privateKey: encodeBase64Url(ecdh.getPrivateKey())
+    privateKey: encodeBase64Url(pad32(ecdh.getPrivateKey()))
   };
 }
 var CURVE, RECORD_SIZE, MAX_PAYLOAD, PushError, Push;
@@ -44453,10 +44497,11 @@ var init_push = __esm({
               TTL: String(this.options.ttl ?? 60),
               ...this.options.urgency ? { Urgency: this.options.urgency } : {}
             },
-            // Node's fetch accepts Buffer at runtime, while the DOM declaration
-            // used by the published type build narrows BodyInit to ArrayBuffer
-            // backed views. Keep the binary payload intact and make that boundary
-            // explicit rather than converting the encrypted bytes to text.
+            // Node's fetch accepts a Buffer at runtime. The typecheck build
+            // (lib ES2022, no DOM) does not know the global `BodyInit` name, and
+            // the DOM declaration narrows it to ArrayBuffer-backed views — a
+            // `Uint8Array` (which a Buffer is) satisfies both, so cast to that and
+            // keep the encrypted bytes intact rather than converting them to text.
             body
           });
         } catch (error2) {

package/packages/core/dist/index.js

@@ -35041,6 +35041,13 @@ function toolbarJs() {
         el.className = 't4-ok';
         el.innerHTML = 'Latest: <strong class="t4-ok">v' + latest + '</strong> &mdash; You are up to date!';
     }
+    // A check that did not happen is not a clean bill of health. The server
+    // sends latest: null when it could not reach the registry, and saying so is
+    // the whole point -- "up to date" here would be a guess dressed as a fact.
+    function couldNotCheck(el, why) {
+        el.className = 't4-err';
+        el.textContent = 'Could not check for updates' + (why ? ' (' + why + ')' : '');
+    }
     function checkVersion() {
         if (modal.style.display === 'block') { modal.style.display = 'none'; return; }
         modal.style.display = 'block';
@@ -35049,6 +35056,7 @@ function toolbarJs() {
         el.textContent = 'Checking for updates...';
         fetch('/__dev/api/version-check').then(function (r) { return r.json(); }).then(function (d) {
             var latest = d.latest, current = d.current;
+            if (!latest) { couldNotCheck(el, d.error); return; }
             if (latest === current) { upToDate(el, latest); return; }
             var cP = current.split('.').map(Number), lP = latest.split('.').map(Number);
             var isNewer = false, i, c, l;
@@ -36391,21 +36399,28 @@ var init_devAdmin = __esm({
     };
     handleVersionCheck = async (_req, res) => {
       const current = TINA4_VERSION;
-      let latest = current;
+      const url = process.env.TINA4_VERSION_CHECK_URL || "https://registry.npmjs.org/tina4-nodejs/latest";
+      const failed = (why) => res.json({ current, latest: null, error: why });
+      let data;
       try {
         const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), 5e3);
-        const resp = await fetch("https://registry.npmjs.org/tina4-nodejs/latest", {
-          signal: controller.signal
-        });
-        clearTimeout(timeout);
-        if (resp.ok) {
-          const data = await resp.json();
-          if (typeof data.version === "string") latest = data.version;
+        const timer = setTimeout(() => controller.abort(), 5e3);
+        try {
+          const resp = await fetch(url, {
+            signal: controller.signal,
+            headers: { "User-Agent": `tina4-nodejs/${current}` }
+          });
+          if (!resp.ok) return failed(`npm registry responded ${resp.status}`);
+          data = await resp.json();
+        } finally {
+          clearTimeout(timer);
         }
-      } catch {
+      } catch (exc) {
+        return failed(exc instanceof Error && exc.message ? exc.message : String(exc));
       }
-      res.json({ current, latest });
+      const latest = typeof data.version === "string" ? data.version : "";
+      if (!latest) return failed("npm registry did not report a version");
+      return res.json({ current, latest });
     };
     handleThoughts = (req2, res) => {
       const url = new URL(req2.url ?? "/", "http://localhost");
@@ -37919,13 +37934,37 @@ function swaggerEnabled() {
   return ["true", "1", "yes", "on"].includes(raw);
 }
 function createSwaggerRoutes(getSpec) {
+  const serveUi = async (_req, res) => {
+    res.html(SWAGGER_UI_HTML("/swagger/openapi.json"));
+  };
   return [
     {
       method: "GET",
       pattern: "/swagger",
-      handler: async (_req, res) => {
-        res.html(SWAGGER_UI_HTML("/swagger/openapi.json"));
-      }
+      handler: serveUi
+    },
+    {
+      // The trailing-slash form, registered rather than left to fall through.
+      //
+      // Matching "/foo/" against a "/foo" route is opt-in via
+      // TINA4_TRAILING_SLASH_REDIRECT and OFF by default, so /swagger/ missed
+      // this route and was answered by the framework-bundled
+      // public/swagger/index.html instead. That mattered twice over. It used to
+      // be a 200 carrying a permanently empty UI, because the bundled file asked
+      // for an unsubstituted {SWAGGER_ROUTE}/swagger.json -- fixed in that file.
+      // And it is a SECOND Swagger UI implementation: the bundled one hardcodes
+      // cdnjs, while the page this handler renders loads from
+      // TINA4_SWAGGER_UI_CDN, so an air-gapped deployment pointing that at a
+      // local mirror silently kept reaching cdnjs on this one path.
+      //
+      // Registering it keeps the fix inside swagger rather than changing how
+      // every route treats trailing slashes, satisfies the shared contract that
+      // already requires a 200 here, and matches python and ruby, which both
+      // serve /swagger and /swagger/ with no env var set. Excluded from the
+      // generated document by INTERNAL_PREFIXES like /swagger itself.
+      method: "GET",
+      pattern: "/swagger/",
+      handler: serveUi
     },
     {
       method: "GET",
@@ -39629,7 +39668,7 @@ async function configureSwagger(router, ormDir, modelsDir) {
   try {
     const swagger = await Promise.resolve().then(() => (init_src2(), src_exports2));
     enabled = swagger.swaggerEnabled();
-    if (!swaggerAssetsEnabled) {
+    if (!enabled) {
       throw new Error("__swagger_disabled__");
     }
     let modelDefs = [];
@@ -44219,6 +44258,9 @@ function decodeBase64Url(value, name) {
   }
   return Buffer.from(value.replace(/-/g, "+").replace(/_/g, "/"), "base64");
 }
+function pad32(value) {
+  return value.length >= 32 ? value : Buffer.concat([Buffer.alloc(32 - value.length), value]);
+}
 function vapidPrivateKey(rawPrivate, rawPublic) {
   if (rawPublic.length !== 65 || rawPublic[0] !== 4) throw new PushError("P-256 public keys must be 65-byte uncompressed points");
   const x = encodeBase64Url(rawPublic.subarray(1, 33));
@@ -44227,7 +44269,7 @@ function vapidPrivateKey(rawPrivate, rawPublic) {
     key: {
       kty: "EC",
       crv: "P-256",
-      d: encodeBase64Url(rawPrivate),
+      d: encodeBase64Url(pad32(rawPrivate)),
       x,
       y,
       ext: true
@@ -44321,8 +44363,10 @@ function generateVapidKeys() {
   const ecdh = createECDH(CURVE);
   ecdh.generateKeys();
   return {
+    // getPublicKey keeps its 65-byte width; getPrivateKey drops a leading zero
+    // byte, so the scalar must be padded to the fixed field width.
     publicKey: encodeBase64Url(ecdh.getPublicKey(void 0, "uncompressed")),
-    privateKey: encodeBase64Url(ecdh.getPrivateKey())
+    privateKey: encodeBase64Url(pad32(ecdh.getPrivateKey()))
   };
 }
 var CURVE, RECORD_SIZE, MAX_PAYLOAD, PushError, Push;
@@ -44414,10 +44458,11 @@ var init_push = __esm({
               TTL: String(this.options.ttl ?? 60),
               ...this.options.urgency ? { Urgency: this.options.urgency } : {}
             },
-            // Node's fetch accepts Buffer at runtime, while the DOM declaration
-            // used by the published type build narrows BodyInit to ArrayBuffer
-            // backed views. Keep the binary payload intact and make that boundary
-            // explicit rather than converting the encrypted bytes to text.
+            // Node's fetch accepts a Buffer at runtime. The typecheck build
+            // (lib ES2022, no DOM) does not know the global `BodyInit` name, and
+            // the DOM declaration narrows it to ArrayBuffer-backed views — a
+            // `Uint8Array` (which a Buffer is) satisfies both, so cast to that and
+            // keep the encrypted bytes intact rather than converting them to text.
             body
           });
         } catch (error2) {

package/packages/core/public/swagger/index.html

@@ -71,7 +71,7 @@
 
         // Build a system
         const ui = SwaggerUIBundle({
-            url: "{SWAGGER_ROUTE}/swagger.json",
+            url: "/swagger/openapi.json",
             dom_id: '#swagger-ui',
             deepLinking: true,
             presets: [

package/packages/core/src/devAdmin.ts

@@ -2069,24 +2069,48 @@ function handleGalleryDeploy(router: Router): RouteHandler {
 // Version check — proxy to npm registry to avoid browser CORS errors
 // ---------------------------------------------------------------------------
 
-const handleVersionCheck: RouteHandler = async (_req, res) => {
+/**
+ * Version check — a check that did not happen says so.
+ *
+ * This used to fall back to `latest = current` on any failure, and the toolbar
+ * renders that as a green "You are up to date!" — so a developer several
+ * releases behind, on a machine with no route out, was told the opposite of the
+ * truth, and the toolbar's own "Could not check for updates" branch could never
+ * fire because the failure arrived as a success. `latest` is `null` when the
+ * check could not be made, and `error` says why. The registry URL is
+ * `TINA4_VERSION_CHECK_URL` when set (a mirror, or a test's own server), else
+ * npm. Mirrors Python `tina4_python.dev_admin._api_version_check`.
+ */
+export const handleVersionCheck: RouteHandler = async (_req, res) => {
   const current = TINA4_VERSION;
-  let latest = current;
+  const url =
+    process.env.TINA4_VERSION_CHECK_URL ||
+    "https://registry.npmjs.org/tina4-nodejs/latest";
+  const failed = (why: string) => res.json({ current, latest: null, error: why });
+
+  let data: Record<string, unknown>;
   try {
     const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), 5000);
-    const resp = await fetch("https://registry.npmjs.org/tina4-nodejs/latest", {
-      signal: controller.signal,
-    });
-    clearTimeout(timeout);
-    if (resp.ok) {
-      const data = (await resp.json()) as Record<string, unknown>;
-      if (typeof data.version === "string") latest = data.version;
+    const timer = setTimeout(() => controller.abort(), 5000);
+    try {
+      const resp = await fetch(url, {
+        signal: controller.signal,
+        headers: { "User-Agent": `tina4-nodejs/${current}` },
+      });
+      // Reaching the registry is not the same as a 200 with a body.
+      if (!resp.ok) return failed(`npm registry responded ${resp.status}`);
+      data = (await resp.json()) as Record<string, unknown>;
+    } finally {
+      clearTimeout(timer);
     }
-  } catch {
-    // Offline or timeout — return current as latest
+  } catch (exc) {
+    // offline, timeout, DNS, unreadable body
+    return failed(exc instanceof Error && exc.message ? exc.message : String(exc));
   }
-  res.json({ current, latest });
+  // An answer we cannot read a version out of is the same lie by another route.
+  const latest = typeof data.version === "string" ? data.version : "";
+  if (!latest) return failed("npm registry did not report a version");
+  return res.json({ current, latest });
 };
 
 // ---------------------------------------------------------------------------
@@ -3019,7 +3043,7 @@ function toolbarCss(): string {
  * starts when the toolbar's `data-reload` is "1" (reload not suppressed for this
  * request/port). Mirrors PHP DevAdmin::toolbarJs().
  */
-function toolbarJs(): string {
+export function toolbarJs(): string {
   return `(function () {
     var bar = document.getElementById('tina4-dev-toolbar');
     if (!bar) { return; }
@@ -3029,6 +3053,13 @@ function toolbarJs(): string {
         el.className = 't4-ok';
         el.innerHTML = 'Latest: <strong class="t4-ok">v' + latest + '</strong> &mdash; You are up to date!';
     }
+    // A check that did not happen is not a clean bill of health. The server
+    // sends latest: null when it could not reach the registry, and saying so is
+    // the whole point -- "up to date" here would be a guess dressed as a fact.
+    function couldNotCheck(el, why) {
+        el.className = 't4-err';
+        el.textContent = 'Could not check for updates' + (why ? ' (' + why + ')' : '');
+    }
     function checkVersion() {
         if (modal.style.display === 'block') { modal.style.display = 'none'; return; }
         modal.style.display = 'block';
@@ -3037,6 +3068,7 @@ function toolbarJs(): string {
         el.textContent = 'Checking for updates...';
         fetch('/__dev/api/version-check').then(function (r) { return r.json(); }).then(function (d) {
             var latest = d.latest, current = d.current;
+            if (!latest) { couldNotCheck(el, d.error); return; }
             if (latest === current) { upToDate(el, latest); return; }
             var cP = current.split('.').map(Number), lP = latest.split('.').map(Number);
             var isNewer = false, i, c, l;

package/packages/core/src/push.ts

@@ -69,6 +69,15 @@ function decodeBase64Url(value: string, name: string): Buffer {
   return Buffer.from(value.replace(/-/g, "+").replace(/_/g, "/"), "base64");
 }
 
+// Left-pad big-endian EC material to the fixed 32-byte P-256 field width.
+// createECDH().getPrivateKey() and other raw EC outputs drop a leading zero
+// byte, so a scalar whose top byte is zero comes back short (~0.5% of keys);
+// the JWK `d` and the stored VAPID key are fixed-width, so a short value is a
+// malformed key.
+function pad32(value: Buffer): Buffer {
+  return value.length >= 32 ? value : Buffer.concat([Buffer.alloc(32 - value.length), value]);
+}
+
 function vapidPrivateKey(rawPrivate: Buffer, rawPublic: Buffer) {
   if (rawPublic.length !== 65 || rawPublic[0] !== 0x04) throw new PushError("P-256 public keys must be 65-byte uncompressed points");
   const x = encodeBase64Url(rawPublic.subarray(1, 33));
@@ -77,7 +86,7 @@ function vapidPrivateKey(rawPrivate: Buffer, rawPublic: Buffer) {
     key: {
       kty: "EC",
       crv: "P-256",
-      d: encodeBase64Url(rawPrivate),
+      d: encodeBase64Url(pad32(rawPrivate)),
       x,
       y,
       ext: true,
@@ -180,8 +189,10 @@ export function generateVapidKeys(): { publicKey: string; privateKey: string } {
   const ecdh = createECDH(CURVE);
   ecdh.generateKeys();
   return {
+    // getPublicKey keeps its 65-byte width; getPrivateKey drops a leading zero
+    // byte, so the scalar must be padded to the fixed field width.
     publicKey: encodeBase64Url(ecdh.getPublicKey(undefined, "uncompressed")),
-    privateKey: encodeBase64Url(ecdh.getPrivateKey()),
+    privateKey: encodeBase64Url(pad32(ecdh.getPrivateKey())),
   };
 }
 
@@ -259,11 +270,12 @@ export class Push {
           TTL: String(this.options.ttl ?? 60),
           ...(this.options.urgency ? { Urgency: this.options.urgency } : {}),
         },
-        // Node's fetch accepts Buffer at runtime, while the DOM declaration
-        // used by the published type build narrows BodyInit to ArrayBuffer
-        // backed views. Keep the binary payload intact and make that boundary
-        // explicit rather than converting the encrypted bytes to text.
-        body: body as unknown as BodyInit,
+        // Node's fetch accepts a Buffer at runtime. The typecheck build
+        // (lib ES2022, no DOM) does not know the global `BodyInit` name, and
+        // the DOM declaration narrows it to ArrayBuffer-backed views — a
+        // `Uint8Array` (which a Buffer is) satisfies both, so cast to that and
+        // keep the encrypted bytes intact rather than converting them to text.
+        body: body as unknown as Uint8Array,
       });
     } catch (error) {
       throw new PushError(`Web Push request failed: ${String(error)}`);

package/packages/core/src/server.ts

@@ -2598,8 +2598,13 @@ async function configureSwagger(router: Router, ormDir: string, modelsDir: strin
       // Single source of truth for BOTH the gated routes and the bundled
       // public/swagger assets (which static serving would otherwise expose).
       enabled = swagger.swaggerEnabled();
-      if (!swaggerAssetsEnabled) {
-        // Skip the rest of the swagger block when disabled.
+      if (!enabled) {
+        // Skip the rest of the swagger block when disabled. Gate on the LOCAL
+        // `enabled` just read from swaggerEnabled(): the module-level
+        // `swaggerAssetsEnabled` is only assigned from this function's RETURN
+        // (see the call site), so inside here it is still its boot-time false --
+        // reading it skipped the block even when swagger was enabled, so
+        // /swagger/openapi.json 404'd on an enabled server.
         throw new Error("__swagger_disabled__");
       }
 

package/packages/orm/dist/index.js

@@ -23330,6 +23330,13 @@ function toolbarJs() {
         el.className = 't4-ok';
         el.innerHTML = 'Latest: <strong class="t4-ok">v' + latest + '</strong> &mdash; You are up to date!';
     }
+    // A check that did not happen is not a clean bill of health. The server
+    // sends latest: null when it could not reach the registry, and saying so is
+    // the whole point -- "up to date" here would be a guess dressed as a fact.
+    function couldNotCheck(el, why) {
+        el.className = 't4-err';
+        el.textContent = 'Could not check for updates' + (why ? ' (' + why + ')' : '');
+    }
     function checkVersion() {
         if (modal.style.display === 'block') { modal.style.display = 'none'; return; }
         modal.style.display = 'block';
@@ -23338,6 +23345,7 @@ function toolbarJs() {
         el.textContent = 'Checking for updates...';
         fetch('/__dev/api/version-check').then(function (r) { return r.json(); }).then(function (d) {
             var latest = d.latest, current = d.current;
+            if (!latest) { couldNotCheck(el, d.error); return; }
             if (latest === current) { upToDate(el, latest); return; }
             var cP = current.split('.').map(Number), lP = latest.split('.').map(Number);
             var isNewer = false, i, c, l;
@@ -24680,21 +24688,28 @@ var init_devAdmin = __esm({
     };
     handleVersionCheck = async (_req, res) => {
       const current = TINA4_VERSION;
-      let latest = current;
+      const url = process.env.TINA4_VERSION_CHECK_URL || "https://registry.npmjs.org/tina4-nodejs/latest";
+      const failed = (why) => res.json({ current, latest: null, error: why });
+      let data;
       try {
         const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), 5e3);
-        const resp = await fetch("https://registry.npmjs.org/tina4-nodejs/latest", {
-          signal: controller.signal
-        });
-        clearTimeout(timeout);
-        if (resp.ok) {
-          const data = await resp.json();
-          if (typeof data.version === "string") latest = data.version;
+        const timer = setTimeout(() => controller.abort(), 5e3);
+        try {
+          const resp = await fetch(url, {
+            signal: controller.signal,
+            headers: { "User-Agent": `tina4-nodejs/${current}` }
+          });
+          if (!resp.ok) return failed(`npm registry responded ${resp.status}`);
+          data = await resp.json();
+        } finally {
+          clearTimeout(timer);
         }
-      } catch {
+      } catch (exc) {
+        return failed(exc instanceof Error && exc.message ? exc.message : String(exc));
       }
-      res.json({ current, latest });
+      const latest = typeof data.version === "string" ? data.version : "";
+      if (!latest) return failed("npm registry did not report a version");
+      return res.json({ current, latest });
     };
     handleThoughts = (req2, res) => {
       const url = new URL(req2.url ?? "/", "http://localhost");
@@ -26208,13 +26223,37 @@ function swaggerEnabled() {
   return ["true", "1", "yes", "on"].includes(raw);
 }
 function createSwaggerRoutes(getSpec) {
+  const serveUi = async (_req, res) => {
+    res.html(SWAGGER_UI_HTML("/swagger/openapi.json"));
+  };
   return [
     {
       method: "GET",
       pattern: "/swagger",
-      handler: async (_req, res) => {
-        res.html(SWAGGER_UI_HTML("/swagger/openapi.json"));
-      }
+      handler: serveUi
+    },
+    {
+      // The trailing-slash form, registered rather than left to fall through.
+      //
+      // Matching "/foo/" against a "/foo" route is opt-in via
+      // TINA4_TRAILING_SLASH_REDIRECT and OFF by default, so /swagger/ missed
+      // this route and was answered by the framework-bundled
+      // public/swagger/index.html instead. That mattered twice over. It used to
+      // be a 200 carrying a permanently empty UI, because the bundled file asked
+      // for an unsubstituted {SWAGGER_ROUTE}/swagger.json -- fixed in that file.
+      // And it is a SECOND Swagger UI implementation: the bundled one hardcodes
+      // cdnjs, while the page this handler renders loads from
+      // TINA4_SWAGGER_UI_CDN, so an air-gapped deployment pointing that at a
+      // local mirror silently kept reaching cdnjs on this one path.
+      //
+      // Registering it keeps the fix inside swagger rather than changing how
+      // every route treats trailing slashes, satisfies the shared contract that
+      // already requires a 200 here, and matches python and ruby, which both
+      // serve /swagger and /swagger/ with no env var set. Excluded from the
+      // generated document by INTERNAL_PREFIXES like /swagger itself.
+      method: "GET",
+      pattern: "/swagger/",
+      handler: serveUi
     },
     {
       method: "GET",
@@ -27918,7 +27957,7 @@ async function configureSwagger(router, ormDir, modelsDir) {
   try {
     const swagger = await Promise.resolve().then(() => (init_src(), src_exports));
     enabled = swagger.swaggerEnabled();
-    if (!swaggerAssetsEnabled) {
+    if (!enabled) {
       throw new Error("__swagger_disabled__");
     }
     let modelDefs = [];
@@ -33039,6 +33078,9 @@ function decodeBase64Url(value, name) {
   }
   return Buffer.from(value.replace(/-/g, "+").replace(/_/g, "/"), "base64");
 }
+function pad32(value) {
+  return value.length >= 32 ? value : Buffer.concat([Buffer.alloc(32 - value.length), value]);
+}
 function vapidPrivateKey(rawPrivate, rawPublic) {
   if (rawPublic.length !== 65 || rawPublic[0] !== 4) throw new PushError("P-256 public keys must be 65-byte uncompressed points");
   const x = encodeBase64Url(rawPublic.subarray(1, 33));
@@ -33047,7 +33089,7 @@ function vapidPrivateKey(rawPrivate, rawPublic) {
     key: {
       kty: "EC",
       crv: "P-256",
-      d: encodeBase64Url(rawPrivate),
+      d: encodeBase64Url(pad32(rawPrivate)),
       x,
       y,
       ext: true
@@ -33141,8 +33183,10 @@ function generateVapidKeys() {
   const ecdh = createECDH(CURVE);
   ecdh.generateKeys();
   return {
+    // getPublicKey keeps its 65-byte width; getPrivateKey drops a leading zero
+    // byte, so the scalar must be padded to the fixed field width.
     publicKey: encodeBase64Url(ecdh.getPublicKey(void 0, "uncompressed")),
-    privateKey: encodeBase64Url(ecdh.getPrivateKey())
+    privateKey: encodeBase64Url(pad32(ecdh.getPrivateKey()))
   };
 }
 var CURVE, RECORD_SIZE, MAX_PAYLOAD, PushError, Push;
@@ -33234,10 +33278,11 @@ var init_push = __esm({
               TTL: String(this.options.ttl ?? 60),
               ...this.options.urgency ? { Urgency: this.options.urgency } : {}
             },
-            // Node's fetch accepts Buffer at runtime, while the DOM declaration
-            // used by the published type build narrows BodyInit to ArrayBuffer
-            // backed views. Keep the binary payload intact and make that boundary
-            // explicit rather than converting the encrypted bytes to text.
+            // Node's fetch accepts a Buffer at runtime. The typecheck build
+            // (lib ES2022, no DOM) does not know the global `BodyInit` name, and
+            // the DOM declaration narrows it to ArrayBuffer-backed views — a
+            // `Uint8Array` (which a Buffer is) satisfies both, so cast to that and
+            // keep the encrypted bytes intact rather than converting them to text.
             body
           });
         } catch (error2) {

package/packages/swagger/dist/index.js

@@ -521,13 +521,37 @@ function swaggerEnabled() {
   return ["true", "1", "yes", "on"].includes(raw);
 }
 function createSwaggerRoutes(getSpec) {
+  const serveUi = async (_req, res) => {
+    res.html(SWAGGER_UI_HTML("/swagger/openapi.json"));
+  };
   return [
     {
       method: "GET",
       pattern: "/swagger",
-      handler: async (_req, res) => {
-        res.html(SWAGGER_UI_HTML("/swagger/openapi.json"));
-      }
+      handler: serveUi
+    },
+    {
+      // The trailing-slash form, registered rather than left to fall through.
+      //
+      // Matching "/foo/" against a "/foo" route is opt-in via
+      // TINA4_TRAILING_SLASH_REDIRECT and OFF by default, so /swagger/ missed
+      // this route and was answered by the framework-bundled
+      // public/swagger/index.html instead. That mattered twice over. It used to
+      // be a 200 carrying a permanently empty UI, because the bundled file asked
+      // for an unsubstituted {SWAGGER_ROUTE}/swagger.json -- fixed in that file.
+      // And it is a SECOND Swagger UI implementation: the bundled one hardcodes
+      // cdnjs, while the page this handler renders loads from
+      // TINA4_SWAGGER_UI_CDN, so an air-gapped deployment pointing that at a
+      // local mirror silently kept reaching cdnjs on this one path.
+      //
+      // Registering it keeps the fix inside swagger rather than changing how
+      // every route treats trailing slashes, satisfies the shared contract that
+      // already requires a 200 here, and matches python and ruby, which both
+      // serve /swagger and /swagger/ with no env var set. Excluded from the
+      // generated document by INTERNAL_PREFIXES like /swagger itself.
+      method: "GET",
+      pattern: "/swagger/",
+      handler: serveUi
     },
     {
       method: "GET",

package/packages/swagger/src/ui.ts

@@ -56,13 +56,38 @@ export function swaggerEnabled(): boolean {
 export function createSwaggerRoutes(
   getSpec: () => unknown
 ): RouteDefinition[] {
+  const serveUi = async (_req: Tina4Request, res: Tina4Response): Promise<void> => {
+    res.html(SWAGGER_UI_HTML("/swagger/openapi.json"));
+  };
+
   return [
     {
       method: "GET",
       pattern: "/swagger",
-      handler: async (_req: Tina4Request, res: Tina4Response) => {
-        res.html(SWAGGER_UI_HTML("/swagger/openapi.json"));
-      },
+      handler: serveUi,
+    },
+    {
+      // The trailing-slash form, registered rather than left to fall through.
+      //
+      // Matching "/foo/" against a "/foo" route is opt-in via
+      // TINA4_TRAILING_SLASH_REDIRECT and OFF by default, so /swagger/ missed
+      // this route and was answered by the framework-bundled
+      // public/swagger/index.html instead. That mattered twice over. It used to
+      // be a 200 carrying a permanently empty UI, because the bundled file asked
+      // for an unsubstituted {SWAGGER_ROUTE}/swagger.json -- fixed in that file.
+      // And it is a SECOND Swagger UI implementation: the bundled one hardcodes
+      // cdnjs, while the page this handler renders loads from
+      // TINA4_SWAGGER_UI_CDN, so an air-gapped deployment pointing that at a
+      // local mirror silently kept reaching cdnjs on this one path.
+      //
+      // Registering it keeps the fix inside swagger rather than changing how
+      // every route treats trailing slashes, satisfies the shared contract that
+      // already requires a 200 here, and matches python and ruby, which both
+      // serve /swagger and /swagger/ with no env var set. Excluded from the
+      // generated document by INTERNAL_PREFIXES like /swagger itself.
+      method: "GET",
+      pattern: "/swagger/",
+      handler: serveUi,
     },
     {
       method: "GET",

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

@@ -9,7 +9,7 @@
  *   - System info (Node.js version, V8, memory, uptime, platform)
  */
 import type { Router } from "./router.js";
-import type { Tina4Request } from "./types.js";
+import type { RouteHandler, Tina4Request } from "./types.js";
 /** Safe HTTP methods that never carry a state change — they skip the write gate. */
 export declare const DEV_SAFE_METHODS: Set<string>;
 /**
@@ -203,6 +203,19 @@ export declare class DevAdmin {
  *   4. Fallback `http://127.0.0.1:9145` — matches standalone `tina4 agent`.
  */
 export declare function supervisorBaseUrl(): string;
+/**
+ * Version check — a check that did not happen says so.
+ *
+ * This used to fall back to `latest = current` on any failure, and the toolbar
+ * renders that as a green "You are up to date!" — so a developer several
+ * releases behind, on a machine with no route out, was told the opposite of the
+ * truth, and the toolbar's own "Could not check for updates" branch could never
+ * fire because the failure arrived as a success. `latest` is `null` when the
+ * check could not be made, and `error` says why. The registry URL is
+ * `TINA4_VERSION_CHECK_URL` when set (a mirror, or a test's own server), else
+ * npm. Mirrors Python `tina4_python.dev_admin._api_version_check`.
+ */
+export declare const handleVersionCheck: RouteHandler;
 /**
  * Resolve a CodeMirror-friendly language id from a file path's basename.
  *
@@ -212,4 +225,13 @@ export declare function supervisorBaseUrl(): string;
  * - anything unknown → "text"
  */
 export declare function devAdminLanguage(rel: string): string;
+/**
+ * JS for the injected dev toolbar — the version-check modal, the dashboard
+ * overlay, and the WebSocket-primary live reloader. Served as an external
+ * script so the toolbar carries no inline handlers or `<script>` and stays
+ * CSP-clean. Every interaction is wired via addEventListener. The reloader only
+ * starts when the toolbar's `data-reload` is "1" (reload not suppressed for this
+ * request/port). Mirrors PHP DevAdmin::toolbarJs().
+ */
+export declare function toolbarJs(): string;
 export {};