@blamejs/blamejs-shop 0.5.12 → 0.5.13

package/lib/vendor/blamejs/test/layer-0-primitives/idempotency-key.test.js

@@ -619,9 +619,500 @@ async function testDbStoreSealRoundTripWithVault() {
   }
 }
 
+function testResealMigrateInMemoryStoreUnsupported() {
+  // Operators on the in-memory store can't bulk-reseal — the helper
+  // reports the reason instead of throwing so a boot script stays quiet.
+  var store = b.middleware.idempotencyKey.memoryStore();
+  var info = b.middleware.idempotencyKey.resealMigrate(store);
+  check("resealMigrate: in-memory store reports store-does-not-support-reseal",
+    info.migrated === 0 && info.skipped === 0 &&
+    info.reason === "store-does-not-support-reseal");
+}
+
+function testResealMigrateSealDisabled() {
+  // A dbStore with sealing off (vault not wired) can't reseal — the
+  // helper delegates and surfaces the aad-or-seal-disabled reason.
+  var db = _mockDb();
+  var store = b.middleware.idempotencyKey.dbStore({
+    db: db, tableName: "_t_reseal_noseal", hashKeys: false, seal: false,
+  });
+  var info = b.middleware.idempotencyKey.resealMigrate(store);
+  check("resealMigrate: seal-disabled dbStore reports aad-or-seal-disabled",
+    info.migrated === 0 && info.skipped === 0 && info.reason === "aad-or-seal-disabled");
+}
+
+async function testResealMigrateAlreadyAadSealed() {
+  // With vault + AAD sealing on, a row written by the store is already
+  // in the vault.aad: envelope. resealMigrate walks the table, detects
+  // it's already migrated, and skips it — succeeding with reason:null.
+  var dataDir = nodeFs.mkdtempSync(nodePath.join(nodeOs.tmpdir(), "idemp-reseal-"));
+  try {
+    if (typeof vault._resetForTest === "function") vault._resetForTest();
+    cryptoField.clearForTest();
+    await vault.init({ dataDir: dataDir, mode: "plaintext" });
+
+    var db = _mockDb();
+    var store = b.middleware.idempotencyKey.dbStore({
+      db: db, tableName: "_t_reseal_aad", hashKeys: false, seal: true, aad: true,
+    });
+    check("resealMigrate: seal + aad enabled when vault ready",
+      store._sealEnabled === true && store._aadOn === true);
+
+    store.set("k1", {
+      fingerprint: "fp",
+      statusCode:  200,
+      headers:     { "x-a": "1" },
+      body:        Buffer.from('{"ok":true}').toString("base64"),
+    }, 60000);
+    check("resealMigrate: fresh row is written in the vault.aad: envelope",
+      typeof db._data.get("k1").headers === "string" &&
+      db._data.get("k1").headers.indexOf("vault.aad:") === 0);
+
+    var info = b.middleware.idempotencyKey.resealMigrate(store);
+    check("resealMigrate: already-AAD row is skipped, migration succeeds",
+      info.migrated === 0 && info.skipped === 1 && info.reason === null);
+
+    // The row still round-trips after the walk (no corruption).
+    var v = store.get("k1");
+    check("resealMigrate: row still readable after the walk",
+      v && v.fingerprint === "fp" && v.headers["x-a"] === "1");
+  } finally {
+    if (typeof vault._resetForTest === "function") vault._resetForTest();
+    cryptoField.clearForTest();
+    try { nodeFs.rmSync(dataDir, { recursive: true, force: true }); } catch (_e) { /* best-effort */ }
+  }
+}
+
+// ---- config-time validation throws (entry-point tier) ----
+
+function testMemoryStoreBadMaxEntries() {
+  function expectCode(label, fn, code) {
+    var threw = null;
+    try { fn(); } catch (e) { threw = e; }
+    check(label, threw && (threw.code || "").indexOf(code) !== -1);
+  }
+  expectCode("memoryStore: negative maxEntries refused",
+    function () { b.middleware.idempotencyKey.memoryStore({ maxEntries: -1 }); },
+    "idempotency/bad-max-entries");
+  expectCode("memoryStore: non-integer maxEntries refused",
+    function () { b.middleware.idempotencyKey.memoryStore({ maxEntries: 1.5 }); },
+    "idempotency/bad-max-entries");
+  expectCode("memoryStore: Infinity maxEntries refused",
+    function () { b.middleware.idempotencyKey.memoryStore({ maxEntries: Infinity }); },
+    "idempotency/bad-max-entries");
+  expectCode("memoryStore: string maxEntries refused",
+    function () { b.middleware.idempotencyKey.memoryStore({ maxEntries: "10" }); },
+    "idempotency/bad-max-entries");
+}
+
+function testCreateBadNumericOpts() {
+  function expectCode(label, fn, code) {
+    var threw = null;
+    try { fn(); } catch (e) { threw = e; }
+    check(label, threw && (threw.code || "").indexOf(code) !== -1);
+  }
+  var store = b.middleware.idempotencyKey.memoryStore();
+  expectCode("create: negative ttlMs refused",
+    function () { b.middleware.idempotencyKey({ store: store, ttlMs: -5 }); },
+    "idempotency/bad-ttl");
+  expectCode("create: Infinity ttlMs refused",
+    function () { b.middleware.idempotencyKey({ store: store, ttlMs: Infinity }); },
+    "idempotency/bad-ttl");
+  expectCode("create: non-integer maxBodyBytes refused",
+    function () { b.middleware.idempotencyKey({ store: store, maxBodyBytes: 1.2 }); },
+    "idempotency/bad-max-body");
+  expectCode("create: bad scopeFn type refused",
+    function () { b.middleware.idempotencyKey({ store: store, scopeFn: "nope" }); },
+    "idempotency/bad-scope-fn");
+  expectCode("create: unknown bodyFingerprintFallback refused",
+    function () { b.middleware.idempotencyKey({ store: store, bodyFingerprintFallback: "sometimes" }); },
+    "idempotency/bad-body-fingerprint-fallback");
+}
+
+// ---- key-shape adversarial branches ----
+
+function testKeyTooLong() {
+  var store = b.middleware.idempotencyKey.memoryStore();
+  var mw = b.middleware.idempotencyKey({ store: store });
+  var longKey = new Array(257).join("a");   // 256 chars, > KEY_MAX_LEN (255)
+  var req = _mockReq("POST", "/x", longKey);
+  req._rawBody = Buffer.from("{}");
+  var res = _mockRes();
+  var nextCalled = false;
+  mw(req, res, function () { nextCalled = true; });
+  check("bad-key over-length → 400, no next()",
+        !nextCalled && res._statusCode() === 400);
+  var body = JSON.parse(res._getBody());
+  check("bad-key over-length problem type",
+        /\/idempotency\/bad-key$/.test(body.type));
+}
+
+function testArrayKeyHeaderUsesFirst() {
+  // A repeated Idempotency-Key header arrives as an array; the
+  // middleware uses the first element as the cache key.
+  var store = b.middleware.idempotencyKey.memoryStore();
+  var mw = b.middleware.idempotencyKey({ store: store, ttlMs: 60000 });
+
+  var req1 = _mockReq("POST", "/x", "placeholder");
+  req1.headers["idempotency-key"] = ["arr-key-1", "arr-key-2"];
+  req1._rawBody = Buffer.from('{"a":1}');
+  var res1 = _mockRes();
+  var next1 = false;
+  mw(req1, res1, function () { next1 = true; });
+  check("array key: first request is a miss (handler runs)", next1 === true);
+  res1.statusCode = 201;
+  res1.end("created");
+
+  // A single-value header equal to the FIRST array element must replay
+  // the cached response — proving key[0] was the slot key.
+  var req2 = _mockReq("POST", "/x", "arr-key-1");
+  req2._rawBody = Buffer.from('{"a":1}');
+  var res2 = _mockRes();
+  var next2 = false;
+  mw(req2, res2, function () { next2 = true; });
+  check("array key: replay keyed on first element",
+        !next2 && res2._statusCode() === 201 && res2._getBody() === "created");
+}
+
+// ---- custom methods / headerName ----
+
+function testCustomMethodsSkipsUnlisted() {
+  var store = b.middleware.idempotencyKey.memoryStore();
+  var mw = b.middleware.idempotencyKey({ store: store, methods: ["post"] });
+  // PUT is NOT in the operator-narrowed method set → pass-through.
+  var req = _mockReq("PUT", "/x", "k-put");
+  req._rawBody = Buffer.from("{}");
+  var res = _mockRes();
+  var nextCalled = false;
+  mw(req, res, function () { nextCalled = true; });
+  check("custom methods: PUT not listed → pass-through next()", nextCalled === true);
+  check("custom methods: nothing cached for unlisted method", store._size() === 0);
+}
+
+function testCustomHeaderName() {
+  var store = b.middleware.idempotencyKey.memoryStore();
+  var mw = b.middleware.idempotencyKey({ store: store, headerName: "X-Idem", ttlMs: 60000 });
+
+  var req1 = _mockReq("POST", "/x");
+  req1.headers["x-idem"] = "custom-hdr-1";
+  req1._rawBody = Buffer.from('{"a":1}');
+  var res1 = _mockRes();
+  var next1 = false;
+  mw(req1, res1, function () { next1 = true; });
+  check("custom headerName: read from operator header (miss)", next1 === true);
+  res1.statusCode = 200;
+  res1.end("via-custom-header");
+
+  var req2 = _mockReq("POST", "/x");
+  req2.headers["x-idem"] = "custom-hdr-1";
+  req2._rawBody = Buffer.from('{"a":1}');
+  var res2 = _mockRes();
+  var next2 = false;
+  mw(req2, res2, function () { next2 = true; });
+  check("custom headerName: replays on the operator header",
+        !next2 && res2._getBody() === "via-custom-header");
+}
+
+// ---- bodyFingerprintFallback branches (real middleware run) ----
+
+function testDenyFallbackRefusesMissingBody() {
+  // Default fallback is "deny": a body-bearing POST that arrives with
+  // neither a parsed body nor a raw-body buffer is refused with HTTP
+  // 400 idempotency/missing-body-fingerprint (draft §4.3 protection —
+  // silent method+path degrade would false-replay different bodies).
+  var store = b.middleware.idempotencyKey.memoryStore();
+  var mw = b.middleware.idempotencyKey({ store: store });
+  var req = _mockReq("POST", "/pay", "k-nobody");   // no body, no _rawBody
+  var res = _mockRes();
+  var nextCalled = false;
+  mw(req, res, function () { nextCalled = true; });
+  check("deny fallback: missing body → 400, no next()",
+        !nextCalled && res._statusCode() === 400);
+  var body = JSON.parse(res._getBody());
+  check("deny fallback: missing-body-fingerprint problem type",
+        /\/idempotency\/missing-body-fingerprint$/.test(body.type));
+  check("deny fallback: nothing cached", store._size() === 0);
+}
+
+function testMethodPathOnlyFallbackAllows() {
+  // Operator opts into the pre-0.9.58 behavior: a bodyless POST is
+  // allowed through (fingerprint degrades to method+path), and a
+  // subsequent identical request replays.
+  var store = b.middleware.idempotencyKey.memoryStore();
+  var mw = b.middleware.idempotencyKey({
+    store: store, ttlMs: 60000, bodyFingerprintFallback: "method-path-only",
+  });
+  var req1 = _mockReq("POST", "/ping", "k-mpo");
+  var res1 = _mockRes();
+  var next1 = false;
+  mw(req1, res1, function () { next1 = true; });
+  check("method-path-only: bodyless POST allowed through (miss)", next1 === true);
+  res1.statusCode = 202;
+  res1.end("accepted");
+
+  var req2 = _mockReq("POST", "/ping", "k-mpo");
+  var res2 = _mockRes();
+  var next2 = false;
+  mw(req2, res2, function () { next2 = true; });
+  check("method-path-only: identical bodyless POST replays",
+        !next2 && res2._statusCode() === 202 && res2._getBody() === "accepted");
+}
+
+// ---- default (non-hook) body extraction branches ----
+
+function testObjectBodyDefaultPath() {
+  // No bodyFingerprint hook: an already-parsed object body is
+  // JSON-stringified for a stable fingerprint.
+  var store = b.middleware.idempotencyKey.memoryStore();
+  var mw = b.middleware.idempotencyKey({ store: store, ttlMs: 60000 });
+
+  var req1 = _mockReq("POST", "/o", "k-obj", { amount: 100 });
+  var res1 = _mockRes();
+  var next1 = false;
+  mw(req1, res1, function () { next1 = true; });
+  check("object body: first request is a miss", next1 === true);
+  res1.end("obj-ok");
+
+  // Same object → replay.
+  var req2 = _mockReq("POST", "/o", "k-obj", { amount: 100 });
+  var res2 = _mockRes();
+  var next2 = false;
+  mw(req2, res2, function () { next2 = true; });
+  check("object body: identical object replays", !next2 && res2._getBody() === "obj-ok");
+
+  // Different object → 422 mismatch.
+  var req3 = _mockReq("POST", "/o", "k-obj", { amount: 999 });
+  var res3 = _mockRes();
+  var next3 = false;
+  mw(req3, res3, function () { next3 = true; });
+  check("object body: different object → 422 mismatch",
+        !next3 && res3._statusCode() === 422);
+}
+
+function testCircularObjectBodyDenied() {
+  // A non-serializable (circular) body cannot be fingerprinted; the
+  // default-path JSON.stringify throws, bodyBytes becomes null, and
+  // the deny fallback refuses with 400.
+  var store = b.middleware.idempotencyKey.memoryStore();
+  var mw = b.middleware.idempotencyKey({ store: store });
+  var circ = {};
+  circ.self = circ;
+  var req = _mockReq("POST", "/c", "k-circ", circ);
+  var res = _mockRes();
+  var nextCalled = false;
+  mw(req, res, function () { nextCalled = true; });
+  check("circular body: unserializable body → 400 deny, no next()",
+        !nextCalled && res._statusCode() === 400);
+}
+
+// ---- bodyFingerprint hook return-type + throw branches ----
+
+function testBodyFingerprintHookReturnTypes() {
+  // Buffer and object hook returns both produce stable fingerprints.
+  var store = b.middleware.idempotencyKey.memoryStore();
+  var bufMw = b.middleware.idempotencyKey({
+    store: store, ttlMs: 60000,
+    bodyFingerprint: function () { return Buffer.from("fixed-buffer-fp"); },
+  });
+  var r1 = _mockReq("POST", "/b", "k-buf");
+  var s1 = _mockRes();
+  bufMw(r1, s1, function () {});
+  s1.end("buf-ok");
+  var r2 = _mockReq("POST", "/b", "k-buf");
+  var s2 = _mockRes();
+  var n2 = false;
+  bufMw(r2, s2, function () { n2 = true; });
+  check("hook Buffer return: replay on stable buffer fingerprint",
+        !n2 && s2._getBody() === "buf-ok");
+
+  var store2 = b.middleware.idempotencyKey.memoryStore();
+  var objMw = b.middleware.idempotencyKey({
+    store: store2, ttlMs: 60000,
+    bodyFingerprint: function (req) { return req.body || null; },
+  });
+  var r3 = _mockReq("POST", "/j", "k-objhook", { k: 1 });
+  var s3 = _mockRes();
+  objMw(r3, s3, function () {});
+  s3.end("objhook-ok");
+  var r4 = _mockReq("POST", "/j", "k-objhook", { k: 1 });
+  var s4 = _mockRes();
+  var n4 = false;
+  objMw(r4, s4, function () { n4 = true; });
+  check("hook object return: replay on JSON-stringified fingerprint",
+        !n4 && s4._getBody() === "objhook-ok");
+}
+
+function testBodyFingerprintHookThrows() {
+  // A throwing hook is caught (audit warning), bodyBytes becomes null.
+  // For DELETE (not in the POST/PUT/PATCH deny check) the request still
+  // proceeds on a method+path fingerprint.
+  var store = b.middleware.idempotencyKey.memoryStore();
+  var mw = b.middleware.idempotencyKey({
+    store: store, ttlMs: 60000,
+    bodyFingerprint: function () { throw new Error("hook boom"); },
+  });
+  var req = _mockReq("DELETE", "/resource/1", "k-hookthrow");
+  var res = _mockRes();
+  var nextCalled = false;
+  mw(req, res, function () { nextCalled = true; });
+  check("hook throws on DELETE: caught, request proceeds (next runs)",
+        nextCalled === true && res._statusCode() !== 400);
+}
+
+function testDeleteMissThenReplay() {
+  // DELETE is a default method but is exempt from the body-fingerprint
+  // deny check; a bodyless DELETE caches + replays on method+path.
+  var store = b.middleware.idempotencyKey.memoryStore();
+  var mw = b.middleware.idempotencyKey({ store: store, ttlMs: 60000 });
+  var req1 = _mockReq("DELETE", "/resource/9", "k-del");
+  var res1 = _mockRes();
+  var next1 = false;
+  mw(req1, res1, function () { next1 = true; });
+  check("DELETE: first request handled (not pass-through)", next1 === true);
+  res1.statusCode = 204;
+  res1.end("");
+  check("DELETE: response cached", store._size() === 1);
+
+  var req2 = _mockReq("DELETE", "/resource/9", "k-del");
+  var res2 = _mockRes();
+  var next2 = false;
+  mw(req2, res2, function () { next2 = true; });
+  check("DELETE: identical request replays cached 204",
+        !next2 && res2._statusCode() === 204);
+}
+
+// ---- store fault-tolerance (get/set throw) ----
+
+function testStoreReadFailureTreatedAsMiss() {
+  var store = {
+    get: function () { throw new Error("read exploded"); },
+    set: function () {},
+    delete: function () {},
+  };
+  var mw = b.middleware.idempotencyKey({ store: store });
+  var req = _mockReq("POST", "/x", "k-readfail");
+  req._rawBody = Buffer.from("{}");
+  var res = _mockRes();
+  var nextCalled = false;
+  var threw = false;
+  try { mw(req, res, function () { nextCalled = true; }); }
+  catch (_e) { threw = true; }
+  check("store read failure: no throw escapes the middleware", threw === false);
+  check("store read failure: treated as miss, handler runs", nextCalled === true);
+}
+
+function testStoreWriteFailureDoesNotBreakResponse() {
+  var store = {
+    get: function () { return null; },
+    set: function () { throw new Error("write exploded"); },
+    delete: function () {},
+  };
+  var mw = b.middleware.idempotencyKey({ store: store });
+  var req = _mockReq("POST", "/x", "k-writefail");
+  req._rawBody = Buffer.from("{}");
+  var res = _mockRes();
+  var threw = false;
+  mw(req, res, function () {});
+  try { res.statusCode = 200; res.end("still works"); }
+  catch (_e) { threw = true; }
+  check("store write failure: response completes without throwing", threw === false);
+  check("store write failure: handler body still written", res._getBody() === "still works");
+  check("store write failure: response ended", res._ended() === true);
+}
+
+// ---- response-capture edge branches ----
+
+function testBodyTooLargeNotCached() {
+  var store = b.middleware.idempotencyKey.memoryStore();
+  var mw = b.middleware.idempotencyKey({ store: store, maxBodyBytes: 4 });
+  var req = _mockReq("POST", "/big", "k-big");
+  req._rawBody = Buffer.from("{}");
+  var res = _mockRes();
+  mw(req, res, function () {});
+  res.statusCode = 200;
+  res.end("abcdefgh");   // 8 bytes > maxBodyBytes (4)
+  check("body-too-large: oversized response NOT cached", store._size() === 0);
+  check("body-too-large: response still delivered to client",
+        res._getBody() === "abcdefgh" && res._ended() === true);
+}
+
+function testStreamingWriteCaptureReplays() {
+  // Handler streams via res.write(...) then res.end() with no final
+  // chunk; the write-wrapper captures the streamed bytes and replays
+  // the concatenation on the retry.
+  var store = b.middleware.idempotencyKey.memoryStore();
+  var mw = b.middleware.idempotencyKey({ store: store, ttlMs: 60000 });
+  var req1 = _mockReq("POST", "/stream", "k-stream");
+  req1._rawBody = Buffer.from("{}");
+  var res1 = _mockRes();
+  mw(req1, res1, function () {
+    res1.statusCode = 200;
+    res1.write("part1-");
+    res1.write("part2");
+    res1.end();
+  });
+  check("streaming capture: full body assembled from writes",
+        res1._getBody() === "part1-part2");
+  check("streaming capture: cached", store._size() === 1);
+
+  var req2 = _mockReq("POST", "/stream", "k-stream");
+  req2._rawBody = Buffer.from("{}");
+  var res2 = _mockRes();
+  var next2 = false;
+  mw(req2, res2, function () { next2 = true; });
+  check("streaming capture: retry replays the concatenated body",
+        !next2 && res2._getBody() === "part1-part2");
+}
+
+function testReplaySkipsThrowingSetHeader() {
+  // On replay, an operator-restricted header whose setHeader() throws is
+  // skipped without aborting the replay — status + body still restored.
+  var store = b.middleware.idempotencyKey.memoryStore();
+  var mw = b.middleware.idempotencyKey({ store: store, ttlMs: 60000 });
+  var req1 = _mockReq("POST", "/h", "k-hdrthrow");
+  req1._rawBody = Buffer.from("{}");
+  var res1 = _mockRes();
+  mw(req1, res1, function () {
+    res1.statusCode = 200;
+    res1.setHeader("X-Test", "v");
+    res1.end("hdr-body");
+  });
+
+  var req2 = _mockReq("POST", "/h", "k-hdrthrow");
+  req2._rawBody = Buffer.from("{}");
+  var res2 = _mockRes();
+  res2.setHeader = function () { throw new Error("restricted header"); };
+  var next2 = false;
+  var threw = false;
+  try { mw(req2, res2, function () { next2 = true; }); }
+  catch (_e) { threw = true; }
+  check("replay setHeader throw: no throw escapes replay", threw === false);
+  check("replay setHeader throw: handler not re-invoked", next2 === false);
+  check("replay setHeader throw: status + body still restored",
+        res2._statusCode() === 200 && res2._getBody() === "hdr-body" && res2._ended() === true);
+}
+
 async function run() {
   testSurface();
   testBadOpts();
+  testMemoryStoreBadMaxEntries();
+  testCreateBadNumericOpts();
+  testKeyTooLong();
+  testArrayKeyHeaderUsesFirst();
+  testCustomMethodsSkipsUnlisted();
+  testCustomHeaderName();
+  testDenyFallbackRefusesMissingBody();
+  testMethodPathOnlyFallbackAllows();
+  testObjectBodyDefaultPath();
+  testCircularObjectBodyDenied();
+  testBodyFingerprintHookReturnTypes();
+  testBodyFingerprintHookThrows();
+  testDeleteMissThenReplay();
+  testStoreReadFailureTreatedAsMiss();
+  testStoreWriteFailureDoesNotBreakResponse();
+  testBodyTooLargeNotCached();
+  testStreamingWriteCaptureReplays();
+  testReplaySkipsThrowingSetHeader();
   testMethodSkipsGet();
   testMissingKeyDefault();
   testMissingKeyRequired();
@@ -646,6 +1137,9 @@ async function run() {
   testDbStoreSealedRowAcrossProcessesNotDeleted();
   testDbStoreCorruptHeadersDeletedWhenNotSealed();
   await testDbStoreSealRoundTripWithVault();
+  testResealMigrateInMemoryStoreUnsupported();
+  testResealMigrateSealDisabled();
+  await testResealMigrateAlreadyAadSealed();
 }
 
 module.exports = { run: run };

package/lib/vendor/blamejs/test/layer-0-primitives/ip-utils.test.js

@@ -66,6 +66,36 @@ function run() {
   check("pre-filter then expandIpv6Hex parses ::1",
     ip.looksLikeIPv6Hex("::1") && ip.expandIpv6Hex("::1") === "00000000000000000000000000000001");
 
+  // ---- RFC 4291 §2.2: '::' abbreviates ONE OR MORE all-zero groups ----
+  // A '::' adjacent to a full 8 explicit groups compresses ZERO groups, which
+  // is malformed IPv6 text — net.isIP rejects all of these. The expander must
+  // too (return null), or it diverges from the kernel/peer parser on a whole
+  // input class. Covers trailing / leading / interior placements.
+  ["1:2:3:4:5:6:7:8::", "::1:2:3:4:5:6:7:8", "1:2:3:4:5:6:7::8",
+   "1:2:3:4::5:6:7:8", "0:0:0:0:0:0:0:0::"]
+    .forEach(function (s) {
+      check("expandIpv6Hex rejects zero-group '::' " + JSON.stringify(s), ip.expandIpv6Hex(s) === null);
+      check("expandIpv6Groups rejects zero-group '::' " + JSON.stringify(s), ip.expandIpv6Groups(s) === null);
+    });
+  // A '::' compressing at least one group stays valid (the fix must not
+  // over-reject the legitimate abbreviation).
+  check("expandIpv6Hex accepts one-group '::' 1:2:3:4:5:6:7::",
+    ip.expandIpv6Hex("1:2:3:4:5:6:7::") === "00010002000300040005000600070000");
+  check("expandIpv6Hex accepts one-group '::' ::1:2:3:4:5:6:7",
+    ip.expandIpv6Hex("::1:2:3:4:5:6:7") === "00000001000200030004000500060007");
+  check("expandIpv6Hex accepts all-zero ::", ip.expandIpv6Hex("::") === "00000000000000000000000000000000");
+
+  // ---- Embedded IPv4 tail is a STRICT dotted-quad (matches net.isIP) ----
+  // A leading-zero octet in the ::ffff: / dual-stack tail is octal-ambiguous
+  // and rejected by net.isIP; the expander reuses the canonical strict isIPv4
+  // so the two validators don't diverge. >255 octets are likewise refused.
+  ["::ffff:01.2.3.4", "::ffff:1.2.3.04", "::ffff:010.0.0.7", "::ffff:256.0.0.1"]
+    .forEach(function (s) {
+      check("expandIpv6Hex rejects loose IPv4 tail " + JSON.stringify(s), ip.expandIpv6Hex(s) === null);
+    });
+  check("expandIpv6Hex accepts strict IPv4-mapped ::ffff:192.0.2.1",
+    ip.expandIpv6Hex("::ffff:192.0.2.1") === "00000000000000000000ffffc0000201");
+
   // ---- regression: existing helpers unchanged ----
   check("isIPv4Shape loose still true for 999.0.0.0", ip.isIPv4Shape("999.0.0.0") === true);
   check("isIPv4Shape false for non-dotted", ip.isIPv4Shape("notip") === false);