@blamejs/blamejs-shop 0.3.55 → 0.3.57

package/lib/vendor/blamejs/test/00-primitives.js

@@ -2356,6 +2356,28 @@ function testRenderJson() {
   check("render.json: extra headers merged",         c2.headers["x-custom"] === "v");
 }
 
+function testRenderJsonReplacer() {
+  // Function replacer serializes a BigInt that bare JSON.stringify throws on.
+  var res = _captureRes();
+  b.render.json(res, { total: 9007199254740993n }, {
+    replacer: function (k, v) { return typeof v === "bigint" ? v.toString() : v; },
+  });
+  var c = res._captured();
+  check("render.json: replacer fn serializes BigInt",  c.body === '{"total":"9007199254740993"}');
+  check("render.json: replacer Content-Length matches", Number(c.headers["content-length"]) === Buffer.byteLength(c.body));
+
+  // Array replacer acts as a key allowlist.
+  var res2 = _captureRes();
+  b.render.json(res2, { keep: 1, drop: 2 }, { replacer: ["keep"] });
+  check("render.json: array replacer filters keys",    res2._captured().body === '{"keep":1}');
+
+  // Bad replacer shape throws at call time (config typo).
+  var threw = false;
+  try { b.render.json(_captureRes(), { a: 1 }, { replacer: "nope" }); }
+  catch (e) { threw = e instanceof TypeError; }
+  check("render.json: non-fn/array replacer throws",   threw);
+}
+
 function testRenderText() {
   var res = _captureRes();
   b.render.text(res, "hello");
@@ -12303,6 +12325,99 @@ function testErrorsPageModeAutoDetectsFromNodeEnv() {
   }
 }
 
+function testErrorsPageProblemDetailsEnvelope() {
+  var handler = b.errorPage.create({ mode: "prod", audit: false, problemDetails: true });
+  var req = { method: "POST", url: "/api/x", headers: { accept: "application/json" } };
+  var res = _makeFakeRes();
+  handler(Object.assign(new Error("bad input"), {
+    isAppError: true, statusCode: 400, code: "VALIDATION_ERROR",
+  }), req, res);
+  check("problemDetails: 400 status",              res.statusCode === 400);
+  check("problemDetails: application/problem+json content type",
+        /application\/problem\+json/.test(res.headers["Content-Type"]));
+  var doc = JSON.parse(res.body);
+  check("problemDetails: status field set",        doc.status === 400);
+  check("problemDetails: title from reason phrase", doc.title === "Bad Request");
+  check("problemDetails: detail carries 4xx message", doc.detail === "bad input");
+  check("problemDetails: code extension preserved", doc.code === "VALIDATION_ERROR");
+  // 500 generic still hides operator-private message under problem+json.
+  var res2 = _makeFakeRes();
+  handler(new Error("DB pwd: hunter2"), req, res2);
+  var doc2 = JSON.parse(res2.body);
+  check("problemDetails: 500 hides operator message",
+        doc2.status === 500 && doc2.detail.indexOf("hunter2") === -1 &&
+        doc2.detail === "Internal Server Error");
+}
+
+function testErrorsPageJsonFormatterTakesOverBody() {
+  var seen = [];
+  var handler = b.errorPage.create({
+    mode: "prod", audit: false,
+    jsonFormatter: function (info, req) {
+      seen.push({ status: info.status, code: info.code, url: req && req.url });
+      return { contentType: "application/vnd.api+json", body: JSON.stringify({ errors: [{ status: String(info.status) }] }) };
+    },
+  });
+  var req = { method: "POST", url: "/api/x", headers: { accept: "application/json" } };
+  var res = _makeFakeRes();
+  handler(Object.assign(new Error("nope"), { isAppError: true, statusCode: 422, code: "X" }), req, res);
+  check("jsonFormatter: hook ran with classified info",
+        seen.length === 1 && seen[0].status === 422 && seen[0].url === "/api/x");
+  check("jsonFormatter: status preserved",         res.statusCode === 422);
+  check("jsonFormatter: custom content type honored",
+        res.headers["Content-Type"] === "application/vnd.api+json");
+  check("jsonFormatter: custom body written verbatim",
+        res.body === '{"errors":[{"status":"422"}]}');
+
+  // A throwing formatter falls back to the default envelope, never masks
+  // the original error.
+  var fallbackHandler = b.errorPage.create({
+    mode: "prod", audit: false,
+    jsonFormatter: function () { throw new Error("formatter broke"); },
+  });
+  var res2 = _makeFakeRes();
+  fallbackHandler(Object.assign(new Error("bad"), { isAppError: true, statusCode: 400, code: "VALIDATION_ERROR" }), req, res2);
+  var payload = JSON.parse(res2.body);
+  check("jsonFormatter: throw falls back to default envelope",
+        res2.statusCode === 400 && payload.error.code === "VALIDATION_ERROR" &&
+        /application\/json/.test(res2.headers["Content-Type"]));
+}
+
+function testErrorsPageRenderHtmlHook() {
+  var handler = b.errorPage.create({
+    mode: "prod", audit: false,
+    renderHtml: function (info) { return "<custom>" + info.status + "</custom>"; },
+  });
+  var req = { method: "GET", url: "/x", headers: { accept: "text/html" } };
+  var res = _makeFakeRes();
+  handler(new Error("boom"), req, res);
+  check("renderHtml: status preserved",            res.statusCode === 500);
+  check("renderHtml: still text/html",             /text\/html/.test(res.headers["Content-Type"]));
+  check("renderHtml: custom body written",         res.body === "<custom>500</custom>");
+
+  // A throwing hook falls back to the built-in prod page.
+  var fallbackHandler = b.errorPage.create({
+    mode: "prod", audit: false,
+    renderHtml: function () { throw new Error("render broke"); },
+  });
+  var res2 = _makeFakeRes();
+  fallbackHandler(new Error("boom"), req, res2);
+  check("renderHtml: throw falls back to built-in page",
+        res2.statusCode === 500 && res2.body.indexOf("Internal Server Error") !== -1);
+}
+
+function testErrorsPageHookOptsRejectNonFunction() {
+  var threwJson = false;
+  try { b.errorPage.create({ jsonFormatter: "nope" }); }
+  catch (e) { threwJson = e instanceof TypeError; }
+  check("jsonFormatter non-function throws at config time", threwJson);
+
+  var threwHtml = false;
+  try { b.errorPage.create({ renderHtml: 42 }); }
+  catch (e) { threwHtml = e instanceof TypeError; }
+  check("renderHtml non-function throws at config time", threwHtml);
+}
+
 // ---- log ----
 //
 // Each test creates an instance with a captured-buffer destination so
@@ -14136,6 +14251,30 @@ function testBufferSafeBoundedChunkCollector() {
   _expectBadArg("null",              { maxBytes: null });
 }
 
+async function testBufferSafeCollectStream() {
+  var bs = b.safeBuffer;
+  var Readable = require("stream").Readable;
+  check("safeBuffer.collectStream is a function", typeof bs.collectStream === "function");
+
+  // Happy path — pump a Readable fully into one Buffer.
+  var buf = await bs.collectStream(
+    Readable.from([Buffer.from("hello "), Buffer.from("world")]), { maxBytes: 100 });
+  check("collectStream: joins chunks",
+        Buffer.isBuffer(buf) && buf.toString("utf8") === "hello world");
+
+  // Cap enforced — a stream over maxBytes rejects instead of buffering it all.
+  var overflowed = false;
+  try { await bs.collectStream(Readable.from([Buffer.alloc(8), Buffer.alloc(5)]), { maxBytes: 10 }); }
+  catch (e) { overflowed = e.code === "buffer/too-large"; }
+  check("collectStream: rejects when stream exceeds maxBytes", overflowed);
+
+  // Bad maxBytes rejects (not a synchronous throw, so callers can rely on .catch).
+  var badArg = false;
+  try { await bs.collectStream(Readable.from([Buffer.from("x")]), { maxBytes: Infinity }); }
+  catch (e) { badArg = e.code === "buffer/bad-arg"; }
+  check("collectStream: bad maxBytes rejects", badArg);
+}
+
 // ---- url-safe ----
 
 function testUrlSafeDefaultIsHttpsOnly() {
@@ -17773,6 +17912,7 @@ async function run() {
   // render — response helpers paired with the template engine
   testRenderSurface();
   testRenderJson();
+  testRenderJsonReplacer();
   testRenderText();
   testRenderHtmlString();
   testRenderRedirect();
@@ -18203,6 +18343,10 @@ async function run() {
   testErrorsPageLogsViaInjectedLogger();
   testErrorsPageDevEnvVarsHonorOptIn();
   testErrorsPageModeAutoDetectsFromNodeEnv();
+  testErrorsPageProblemDetailsEnvelope();
+  testErrorsPageJsonFormatterTakesOverBody();
+  testErrorsPageRenderHtmlHook();
+  testErrorsPageHookOptsRejectNonFunction();
   // log — structured JSON logging with request-id correlation
   testLogSurface();
   testLogEmitsJsonLineToStdout();
@@ -18294,6 +18438,7 @@ async function run() {
   testBufferSafeNormalizeText();
   testBufferSafeToBuffer();
   testBufferSafeBoundedChunkCollector();
+  await testBufferSafeCollectStream();
   testBufferSafeSecureZero();
   // logger primitive (per-module log channel)
   testLogger();
@@ -18549,6 +18694,7 @@ module.exports = {
   testTemplateMissingViewsDir:               testTemplateMissingViewsDir,
   testRenderSurface:                         testRenderSurface,
   testRenderJson:                            testRenderJson,
+  testRenderJsonReplacer:                    testRenderJsonReplacer,
   testRenderText:                            testRenderText,
   testRenderHtmlString:                      testRenderHtmlString,
   testRenderRedirect:                        testRenderRedirect,
@@ -18898,6 +19044,10 @@ module.exports = {
   testErrorsPageLogsViaInjectedLogger:       testErrorsPageLogsViaInjectedLogger,
   testErrorsPageDevEnvVarsHonorOptIn:        testErrorsPageDevEnvVarsHonorOptIn,
   testErrorsPageModeAutoDetectsFromNodeEnv:  testErrorsPageModeAutoDetectsFromNodeEnv,
+  testErrorsPageProblemDetailsEnvelope:      testErrorsPageProblemDetailsEnvelope,
+  testErrorsPageJsonFormatterTakesOverBody:  testErrorsPageJsonFormatterTakesOverBody,
+  testErrorsPageRenderHtmlHook:              testErrorsPageRenderHtmlHook,
+  testErrorsPageHookOptsRejectNonFunction:   testErrorsPageHookOptsRejectNonFunction,
   testLogSurface:                            testLogSurface,
   testLogEmitsJsonLineToStdout:              testLogEmitsJsonLineToStdout,
   testLogRoutesErrorAndFatalToStderr:        testLogRoutesErrorAndFatalToStderr,
@@ -18947,6 +19097,7 @@ module.exports = {
   testBufferSafeNormalizeText:               testBufferSafeNormalizeText,
   testBufferSafeToBuffer:                    testBufferSafeToBuffer,
   testBufferSafeBoundedChunkCollector:       testBufferSafeBoundedChunkCollector,
+  testBufferSafeCollectStream:               testBufferSafeCollectStream,
   testBufferSafeSecureZero:                  testBufferSafeSecureZero,
   testLogger:                                testLogger,
   testConstantsReferenceIntegrity:           testConstantsReferenceIntegrity,

package/lib/vendor/blamejs/test/layer-0-primitives/agent-orchestrator.test.js

@@ -377,6 +377,23 @@ async function testDrainQuiesce() {
   consumers[0].stop = orig;
 }
 
+async function testDrainPhaseRegistersWithAppShutdown() {
+  // The orchestrator wires its drain into b.appShutdown via addPhase
+  // ({ name, run }) — the handle exposes addPhase, not registerPhase, so a
+  // registerPhase call silently never registered the phase. Assert the
+  // phase is registered AND actually runs (sets ctx.draining) on shutdown.
+  var shut = b.appShutdown.create({ graceMs: 1000 });
+  var orch = b.agent.orchestrator.create({ appShutdown: shut });
+  check("appShutdown wiring: not draining before shutdown", orch._ctx.draining !== true);
+
+  var result = await shut.shutdown();
+  var drainPhase = result.phases.filter(function (p) { return p.name === "agent.orchestrator.drain"; });
+  check("appShutdown wiring: drain phase registered", drainPhase.length === 1);
+  check("appShutdown wiring: drain phase ran ok",     drainPhase.length === 1 && drainPhase[0].ok === true);
+  check("appShutdown wiring: drain set ctx.draining", orch._ctx.draining === true);
+  shut._resetForTest();
+}
+
 async function testShardForSaltedFnv() {
   // SUBSTRATE-20 — salted FNV: vault-less fallback still distributes
   // reasonably. Doesn't assert randomness — just that the same inputs
@@ -538,6 +555,7 @@ async function run() {
   await testShardForSaltedFnv();
   await testDrain();
   await testDrainQuiesce();
+  await testDrainPhaseRegistersWithAppShutdown();
   await testHealth();
   await testStreamRegistry();
   await testPermissions();

package/lib/vendor/blamejs/test/layer-0-primitives/api-encrypt.test.js

@@ -722,6 +722,91 @@ async function testApiEncryptClientRejectsBadResponse() {
   check("client rejects response missing _ct",    threw && threw.code === "CLIENT_RESPONSE_SHAPE");
 }
 
+async function testApiEncryptEncryptedErrorReadback() {
+  // An in-session error must ship in the same { _ct } envelope a success uses
+  // (via req.apiEncryptEncode), and the encrypted client in responseMode
+  // "passthrough" must read a non-2xx instead of throwing on the shape: an
+  // encrypted error decrypts; a plaintext (pre-session-style) error returns
+  // verbatim; the default "reject" mode still throws on non-2xx.
+  var tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "blamejs-aee-"));
+  try {
+    await setupTestDb(tmpDir);
+    var http = require("http");
+    var keypair = _serverKeypair();
+    var mw = b.middleware.apiEncrypt({ keypair: keypair, audit: false });
+
+    var server = http.createServer(function (req, res) {
+      res.json = function (data) {
+        res.writeHead(res.statusCode || 200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(data));
+      };
+      req.pathname = req.url.split("?")[0];
+      var chunks = [];
+      req.on("data", function (c) { chunks.push(c); });
+      req.on("end", function () {
+        try { req.body = JSON.parse(Buffer.concat(chunks).toString("utf8")); }
+        catch (_e) { req.body = null; }
+        mw(req, res, function () {
+          var want = req.body && req.body.want;
+          if (want === "encrypted-error") {
+            // Terminal writer bypassing res.json — seal via the request encoder
+            // the way error-page / problem-details / deny-response now do.
+            check("server: req.apiEncryptEncode set after a valid session",
+                  typeof req.apiEncryptEncode === "function");
+            res.writeHead(403, { "Content-Type": "application/json" });
+            res.end(JSON.stringify(req.apiEncryptEncode({ error: "forbidden-detail" })));
+            return;
+          }
+          if (want === "plaintext-error") {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "bad-request-plain" }));
+            return;
+          }
+          res.json({ ok: true });
+        });
+      });
+    });
+    var port = await helpers.listenOnRandomPort(server);
+    var common = { allowedProtocols: b.safeUrl.ALLOW_HTTP_ALL, allowInternal: true };
+
+    var pass = b.httpClient.encrypted({
+      pubkey: keypair, baseUrl: "http://127.0.0.1:" + port, method: "POST",
+      responseMode: "passthrough",
+    });
+
+    var enc = await pass.request(Object.assign({ path: "/x", body: { want: "encrypted-error" } }, common));
+    check("passthrough: non-2xx status surfaced",        enc.statusCode === 403);
+    check("passthrough: ok flag false on non-2xx",       enc.ok === false);
+    check("passthrough: in-session error body decrypts", enc.body && enc.body.error === "forbidden-detail");
+
+    var plain = await pass.request(Object.assign({ path: "/x", body: { want: "plaintext-error" } }, common));
+    check("passthrough: plaintext error status surfaced",   plain.statusCode === 400);
+    check("passthrough: plaintext error returned verbatim", plain.body && plain.body.error === "bad-request-plain");
+
+    var ok2xx = await pass.request(Object.assign({ path: "/x", body: { want: "ok" } }, common));
+    check("passthrough: 2xx still decrypts + ok true",
+          ok2xx.statusCode === 200 && ok2xx.ok === true && ok2xx.body && ok2xx.body.ok === true);
+
+    var rej = b.httpClient.encrypted({
+      pubkey: keypair, baseUrl: "http://127.0.0.1:" + port, method: "POST",
+    });
+    var threw = null;
+    try { await rej.request(Object.assign({ path: "/x", body: { want: "plaintext-error" } }, common)); }
+    catch (e) { threw = e; }
+    check("default reject: non-2xx still throws (back-compat)", threw !== null);
+
+    var oneOff = await rej.request(Object.assign(
+      { path: "/x", body: { want: "plaintext-error" }, responseMode: "passthrough" }, common));
+    check("per-call passthrough override resolves the non-2xx",
+          oneOff.statusCode === 400 && oneOff.body && oneOff.body.error === "bad-request-plain");
+
+    server.close();
+    mw.close();
+  } finally {
+    await teardownTestDb(tmpDir);
+  }
+}
+
 // ---- per-session keying mode (v0.7.3) ----
 
 async function testApiEncryptPerSessionDefaultIsPerRequest() {
@@ -1088,6 +1173,7 @@ async function run() {
   await testApiEncryptDerivedPruneInterval();
   await testApiEncryptHttpClientHelperShape();
   await testApiEncryptHttpClientRoundTrip();
+  await testApiEncryptEncryptedErrorReadback();
 
   // v0.7.3 — per-session keying mode
   await testApiEncryptPerSessionDefaultIsPerRequest();

package/lib/vendor/blamejs/test/layer-0-primitives/app-shutdown.test.js

@@ -350,6 +350,62 @@ async function testAppShutdownWatchdogForcesExitOnHang() {
         exited && exited.signal === null && typeof exited.code === "number");
 }
 
+function testAppShutdownExitAfterPhasesValidation() {
+  var threw = null;
+  try { b.appShutdown.create({ exitAfterPhases: "yes" }); }
+  catch (e) { threw = e; }
+  check("exitAfterPhases: non-boolean → AppShutdownError",
+        threw && threw.code === "app-shutdown/bad-exit-after-phases");
+  // Default (unset) does NOT exit — a plain shutdown() resolves without
+  // terminating the process (the surrounding suite proves this: every
+  // prior shutdown() returned to the runner without exiting).
+  var o = b.appShutdown.create({ phases: [], exitAfterPhases: false });
+  check("exitAfterPhases:false accepted", typeof o.shutdown === "function");
+  o._resetForTest();
+}
+
+async function testAppShutdownExitAfterPhasesExits() {
+  // A non-signal shutdown() with exitAfterPhases:true must terminate the
+  // process once phases complete, with an exit code reflecting phase
+  // success. Verified in a child process — process.exit would kill the
+  // runner. No signal is sent: the child calls shutdown() directly, which
+  // distinguishes this from the signal-handler watchdog path.
+  var cp = require("node:child_process");
+  var repoRoot = require("node:path").resolve(__dirname, "..", "..");
+  function _spawnAndExit(phaseBody, label, expectCode) {
+    var script =
+      "var b = require(" + JSON.stringify(repoRoot) + ");" +
+      "var o = b.appShutdown.create({ graceMs: 2000, exitAfterPhases: true," +
+      "  phases: [{ name: 'p', run: " + phaseBody + " }] });" +
+      "o.shutdown().then(function (r) { process.stdout.write('RESOLVED:' + r.ok + '\\n'); });";
+    return new Promise(function (resolve) {
+      var child = cp.spawn(process.execPath, ["-e", script], { stdio: ["ignore", "pipe", "pipe"] });
+      var out = "";
+      var done = null;
+      child.stdout.on("data", function (d) { out += d.toString(); });
+      child.on("exit", function (code, signal) { done = { code: code, signal: signal, out: out }; });
+      helpers.waitUntil(function () { return done !== null; },
+        { timeoutMs: 30000, label: "app-shutdown exitAfterPhases: " + label })
+        .then(function () { resolve(done); }, function () {
+          try { child.kill("SIGKILL"); } catch (_e) { /* gone */ }
+          resolve(done || { code: -1, signal: null, out: out });
+        });
+    });
+  }
+
+  var okRun = await _spawnAndExit("function () { return; }", "clean phase", 0);
+  check("exitAfterPhases: clean phase resolved before exit",
+        okRun && okRun.out.indexOf("RESOLVED:true") !== -1);
+  check("exitAfterPhases: clean phase → process.exit(0) (no kill signal)",
+        okRun && okRun.code === 0 && okRun.signal === null);
+
+  var failRun = await _spawnAndExit("function () { throw new Error('boom'); }", "failed phase", 1);
+  check("exitAfterPhases: failed phase resolved with ok=false",
+        failRun && failRun.out.indexOf("RESOLVED:false") !== -1);
+  check("exitAfterPhases: failed phase → process.exit(1)",
+        failRun && failRun.code === 1 && failRun.signal === null);
+}
+
 async function run() {
   testAppShutdownSurface();
   await testAppShutdownEmpty();
@@ -368,6 +424,8 @@ async function run() {
   await testAppShutdownSignalHandlersInstall();
   await testAppShutdownConfigValidation();
   await testAppShutdownWatchdogForcesExitOnHang();
+  testAppShutdownExitAfterPhasesValidation();
+  await testAppShutdownExitAfterPhasesExits();
 }
 
 module.exports = { run: run };

package/lib/vendor/blamejs/test/layer-0-primitives/archive-read.test.js

@@ -484,7 +484,208 @@ async function testSignalAbort() {
   check("zip extractEntries with no signal still yields entries", n === 2);
 }
 
+// ---- ZIP64 read support ---------------------------------------------------
+// The write side does not emit ZIP64, so we hand-build minimal ZIP64-form
+// archives (infozip / Go archive/zip layout) and assert they decode to the
+// same entry shape a classic reader yields, with bomb/name refusals intact.
+// APPNOTE 6.3.10 §4.3.14 (EOCD64) / §4.3.15 (locator) / §4.5.3 (extra field).
+
+var METHOD_STORE = 0;
+var U32_SENTINEL = 0xffffffff;
+var U16_SENTINEL = 0xffff;
+
+// Build a single STORE-method ZIP64 archive whose CD entry carries the
+// 0xFFFFFFFF uncompressed/compressed-size sentinels resolved by a §4.5.3
+// extra field, fronted by a real ZIP64 EOCD record + locator and a classic
+// EOCD with sentinel size/offset fields. `crc` comes from the classic
+// archive the framework produced for the same bytes (CRC must agree so the
+// LFH/CD skew check passes). `entryCountSentinel` exercises the EOCD64
+// totalEntries path.
+function buildZip64Store(name, data, crc, opts) {
+  opts = opts || {};
+  var nameBuf = Buffer.from(name, "utf8");
+  var size = data.length;
+
+  // ZIP64 extra field for the LFH: uncompressedSize(8) + compressedSize(8).
+  var lfhExtra = Buffer.alloc(4 + 16);
+  lfhExtra.writeUInt16LE(0x0001, 0);
+  lfhExtra.writeUInt16LE(16, 2);
+  lfhExtra.writeBigUInt64LE(BigInt(size), 4);
+  lfhExtra.writeBigUInt64LE(BigInt(size), 12);
+
+  // Local file header (30 bytes) with sentinel sizes.
+  var lfh = Buffer.alloc(30);
+  lfh.writeUInt32LE(0x04034b50, 0);    // sig
+  lfh.writeUInt16LE(45, 4);            // version needed = 4.5 (ZIP64)
+  lfh.writeUInt16LE(0, 6);             // flags
+  lfh.writeUInt16LE(METHOD_STORE, 8);  // method
+  lfh.writeUInt16LE(0, 10);            // mod time
+  lfh.writeUInt16LE(0x21, 12);         // mod date (1980-01-01)
+  lfh.writeUInt32LE(crc >>> 0, 14);    // crc32
+  lfh.writeUInt32LE(U32_SENTINEL, 18); // csize sentinel
+  lfh.writeUInt32LE(U32_SENTINEL, 22); // usize sentinel
+  lfh.writeUInt16LE(nameBuf.length, 26);
+  lfh.writeUInt16LE(lfhExtra.length, 28);
+
+  var lfhOffset = 0;
+
+  // ZIP64 extra field for the CD: uncompressedSize(8) + compressedSize(8)
+  // (+ localHeaderOffset(8) when opted in).
+  var includeOffset = opts.offsetSentinel === true;
+  var cdExtraDataLen = includeOffset ? 24 : 16;
+  var cdExtra = Buffer.alloc(4 + cdExtraDataLen);
+  cdExtra.writeUInt16LE(0x0001, 0);
+  cdExtra.writeUInt16LE(cdExtraDataLen, 2);
+  cdExtra.writeBigUInt64LE(BigInt(size), 4);
+  cdExtra.writeBigUInt64LE(BigInt(size), 12);
+  if (includeOffset) cdExtra.writeBigUInt64LE(BigInt(lfhOffset), 20);
+
+  // Central directory header (46 bytes) with sentinel sizes.
+  var cd = Buffer.alloc(46);
+  cd.writeUInt32LE(0x02014b50, 0);     // sig
+  cd.writeUInt16LE(45, 4);             // version made by
+  cd.writeUInt16LE(45, 6);             // version needed
+  cd.writeUInt16LE(0, 8);              // flags
+  cd.writeUInt16LE(METHOD_STORE, 10);  // method
+  cd.writeUInt16LE(0, 12);             // mod time
+  cd.writeUInt16LE(0x21, 14);          // mod date
+  cd.writeUInt32LE(crc >>> 0, 16);     // crc32
+  cd.writeUInt32LE(U32_SENTINEL, 20);  // csize sentinel
+  cd.writeUInt32LE(U32_SENTINEL, 24);  // usize sentinel
+  cd.writeUInt16LE(nameBuf.length, 28);
+  cd.writeUInt16LE(cdExtra.length, 30);
+  cd.writeUInt16LE(0, 32);             // comment len
+  cd.writeUInt16LE(0, 34);             // disk start
+  cd.writeUInt16LE(0, 36);             // internal attrs
+  cd.writeUInt32LE(0, 38);             // external attrs
+  cd.writeUInt32LE(includeOffset ? U32_SENTINEL : lfhOffset, 42);  // lfh offset (sentinel when opted in)
+
+  var cdBytesBefore = Buffer.concat([lfh, nameBuf, lfhExtra, data]);
+  var cdOffset = cdBytesBefore.length;
+  var cdRecord = Buffer.concat([cd, nameBuf, cdExtra]);
+  var cdSize = cdRecord.length;
+
+  // ZIP64 EOCD record (56 bytes through cdOffset).
+  var eocd64 = Buffer.alloc(56);
+  eocd64.writeUInt32LE(0x06064b50, 0);          // sig
+  eocd64.writeBigUInt64LE(BigInt(56 - 12), 4);  // size of remaining record
+  eocd64.writeUInt16LE(45, 12);                 // version made by
+  eocd64.writeUInt16LE(45, 14);                 // version needed
+  eocd64.writeUInt32LE(0, 16);                  // disk number
+  eocd64.writeUInt32LE(0, 20);                  // cd start disk
+  eocd64.writeBigUInt64LE(1n, 24);              // entries this disk
+  eocd64.writeBigUInt64LE(1n, 32);              // total entries
+  eocd64.writeBigUInt64LE(BigInt(cdSize), 40);  // cd size
+  eocd64.writeBigUInt64LE(BigInt(cdOffset), 48);// cd offset
+
+  var eocd64Offset = cdOffset + cdSize;
+
+  // ZIP64 EOCD locator (20 bytes).
+  var locator = Buffer.alloc(20);
+  locator.writeUInt32LE(0x07064b50, 0);             // sig
+  locator.writeUInt32LE(0, 4);                      // disk with eocd64
+  locator.writeBigUInt64LE(BigInt(eocd64Offset), 8);// eocd64 offset
+  locator.writeUInt32LE(1, 16);                     // total disks
+
+  // Classic EOCD (22 bytes) with sentinels.
+  var entryCountSentinel = opts.entryCountSentinel === true;
+  var eocd = Buffer.alloc(22);
+  eocd.writeUInt32LE(0x06054b50, 0);   // sig
+  eocd.writeUInt16LE(0, 4);            // disk number
+  eocd.writeUInt16LE(0, 6);            // cd disk
+  eocd.writeUInt16LE(entryCountSentinel ? U16_SENTINEL : 1, 8);   // entries this disk
+  eocd.writeUInt16LE(entryCountSentinel ? U16_SENTINEL : 1, 10);  // total entries
+  eocd.writeUInt32LE(U32_SENTINEL, 12);// cd size sentinel
+  eocd.writeUInt32LE(U32_SENTINEL, 16);// cd offset sentinel
+  eocd.writeUInt16LE(0, 20);          // comment len
+
+  return Buffer.concat([cdBytesBefore, cdRecord, eocd64, locator, eocd]);
+}
+
+async function testZip64Read() {
+  var payload = Buffer.from("ZIP64 round-trip payload — same bytes a classic reader yields.\n", "utf8");
+
+  // Get a real CRC32 for the payload by reading it back through a classic
+  // STORE archive the framework produced.
+  var z = b.archive.zip();
+  z.addFile("z64.txt", payload);
+  var classicBytes = z.toBuffer();
+  var classicReader = b.archive.read.zip(b.archive.adapters.buffer(classicBytes));
+  var classicEntries = await classicReader.inspect();
+  var crc = classicEntries[0].crc;
+
+  // Size-sentinel ZIP64 form decodes to the same entry shape.
+  var z64 = buildZip64Store("z64.txt", payload, crc);
+  var reader = b.archive.read.zip(b.archive.adapters.buffer(z64));
+  var entries = await reader.inspect();
+  check("zip64: inspect sees 1 entry",          entries.length === 1);
+  check("zip64: name round-trips",              entries[0].name === "z64.txt");
+  check("zip64: resolved size matches payload", entries[0].size === payload.length);
+
+  // extractEntries recovers byte-identical content (LFH/CD ZIP64 skew check
+  // passes against resolved sizes).
+  var got = null;
+  for await (var ent of reader.extractEntries()) { got = ent; }
+  check("zip64: extractEntries recovers exact bytes", got && got.bytes.equals(payload));
+
+  // localHeaderOffset sentinel + ZIP64 extra resolution.
+  var z64Off = buildZip64Store("z64.txt", payload, crc, { offsetSentinel: true });
+  var readerOff = b.archive.read.zip(b.archive.adapters.buffer(z64Off));
+  var gotOff = null;
+  for await (var entO of readerOff.extractEntries()) { gotOff = entO; }
+  check("zip64: lfhOffset sentinel resolved + bytes recovered",
+    gotOff && gotOff.bytes.equals(payload));
+
+  // EOCD64 totalEntries path — classic EOCD entry-count is the 0xFFFF
+  // sentinel; the true count comes from the ZIP64 EOCD record.
+  var z64Count = buildZip64Store("z64.txt", payload, crc, { entryCountSentinel: true });
+  var readerCount = b.archive.read.zip(b.archive.adapters.buffer(z64Count));
+  var entriesCount = await readerCount.inspect();
+  check("zip64: EOCD64 totalEntries resolved from sentinel", entriesCount.length === 1);
+
+  // Bomb cap still fires on the resolved 64-bit size.
+  var bombErr = null;
+  try {
+    var bombReader = b.archive.read.zip(b.archive.adapters.buffer(z64), {
+      bombPolicy: { maxEntryDecompressedBytes: 4 },
+    });
+    await bombReader.inspect();
+  } catch (e) { bombErr = e; }
+  check("zip64: bomb cap fires on resolved size",
+    bombErr && /entry-too-large|total-too-large/.test(bombErr.code || bombErr.message));
+
+  // Zip-Slip name refusal still fires on a ZIP64-form archive.
+  var slip = buildZip64Store("../../etc/passwd", payload, crc);
+  var slipDest = fs.mkdtempSync(path.join(os.tmpdir(), "blamejs-zip64-slip-"));
+  var slipErr = null;
+  try {
+    var slipReader = b.archive.read.zip(b.archive.adapters.buffer(slip));
+    await slipReader.extract({ destination: slipDest });
+  } catch (e) { slipErr = e; }
+  finally { fs.rmSync(slipDest, { recursive: true, force: true }); }
+  check("zip64: zip-slip name still refused", slipErr !== null);
+
+  // A classic EOCD claiming ZIP64 (sentinel) but missing the ZIP64 trailer
+  // is refused, not read with a sentinel taken literally.
+  var truncated = z64.slice(0, z64.length - 20 - 56 - 22);  // drop eocd64 + locator + classic eocd
+  var orphanEocd = Buffer.alloc(22);
+  orphanEocd.writeUInt32LE(0x06054b50, 0);
+  orphanEocd.writeUInt16LE(U16_SENTINEL, 8);
+  orphanEocd.writeUInt16LE(U16_SENTINEL, 10);
+  orphanEocd.writeUInt32LE(U32_SENTINEL, 12);
+  orphanEocd.writeUInt32LE(U32_SENTINEL, 16);
+  var orphan = Buffer.concat([truncated, orphanEocd]);
+  var orphanErr = null;
+  try {
+    var orphanReader = b.archive.read.zip(b.archive.adapters.buffer(orphan));
+    await orphanReader.inspect();
+  } catch (e) { orphanErr = e; }
+  check("zip64: missing ZIP64 trailer refused (no literal-sentinel read)",
+    orphanErr && /zip64/.test(orphanErr.code || orphanErr.message));
+}
+
 async function run() {
+  await testZip64Read();
   await testRoundTripExtract();
   await testExtractEntriesInMemory();
   await testExtractToMemoryOrchestrator();