@blamejs/blamejs-shop 0.0.44

package/lib/vendor/blamejs/scripts/sha3-digest.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * Workflow-side helper: compute classical (SHA-256) AND PQC-first
+ * (SHA3-512) digests of a release artifact (typically the npm
+ * tarball) and write each to a sidecar file in `sha256sum` /
+ * `sha3sum -a 512` compatible format:
+ *
+ *   <artifact>.sha256     — `<hex>  <filename>` (one line)
+ *   <artifact>.sha3-512   — `<hex>  <filename>` (one line)
+ *
+ * SHA-256 is the conventional release-checksum operators expect to
+ * find on a release page; verify via:
+ *
+ *   sha256sum -c @blamejs-core-X.Y.Z.tgz.sha256
+ *
+ * SHA3-512 is the framework's PQC-first hash choice — same
+ * algorithm the audit chain, CMS SignedData encoder, and vault-
+ * wrap envelope hash with. Operators with a strict PQC-only
+ * verification posture use this sidecar to verify the tarball
+ * BYTES at ~256-bit pre-Grover / ~128-bit post-Grover collision
+ * security — twice the post-quantum margin of SHA-256. Verify via:
+ *
+ *   openssl dgst -sha3-512 @blamejs-core-X.Y.Z.tgz
+ *   (compare against the .sha3-512 sidecar)
+ *
+ * Invoked from `.github/workflows/npm-publish.yml`'s pack step:
+ *
+ *   node scripts/sha3-digest.js dist/blamejs-core-X.Y.Z.tgz
+ */
+
+var fs     = require("node:fs");
+var path   = require("node:path");
+var crypto = require("node:crypto");
+
+function fail(msg) {
+  process.stderr.write("[release-digests] " + msg + "\n");
+  process.exit(1);
+}
+
+function _writeDigest(artifactPath, algorithm, sidecarExt) {
+  var bytes;
+  try { bytes = fs.readFileSync(artifactPath); }
+  catch (e) { fail("cannot read " + artifactPath + ": " + (e && e.message || e)); }
+  var digest = crypto.createHash(algorithm).update(bytes).digest("hex");
+  var base = path.basename(artifactPath);
+  var sidecarPath = artifactPath + "." + sidecarExt;
+  fs.writeFileSync(sidecarPath, digest + "  " + base + "\n");
+  process.stderr.write("[release-digests] OK — wrote " + sidecarPath + "\n");
+  process.stderr.write("[release-digests] " + algorithm + ":  " + digest + "  " + base + "\n");
+}
+
+function main() {
+  var artifactPath = process.argv[2];
+  if (!artifactPath) fail("usage: node scripts/sha3-digest.js <artifact-path>");
+  // Emit BOTH sidecars in one pass so the workflow only has to
+  // invoke one script per artifact.
+  _writeDigest(artifactPath, "sha256",   "sha256");
+  _writeDigest(artifactPath, "sha3-512", "sha3-512");
+}
+
+main();

package/lib/vendor/blamejs/scripts/sign-release-artifact.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * Workflow-side helper: sign a release artifact (typically the npm
+ * tarball) with the framework's ML-DSA-65 release-signing key, then
+ * write the signature alongside as `<artifact>.mldsa.sig`.
+ *
+ * Invoked from `.github/workflows/npm-publish.yml`'s pack step:
+ *
+ *   node scripts/sign-release-artifact.js dist/blamejs-core-X.Y.Z.tgz
+ *
+ * Reads the private key from `RELEASE_PQC_SIGNING_KEY` (base64url-
+ * encoded). The pubkey lives in `keys/release-pqc-pub.json` (in-tree)
+ * and the script cross-checks: after signing, it verifies the
+ * signature against the in-tree pubkey before writing the .sig file.
+ * If verify fails, the script refuses to write (defends against a
+ * stale / wrong env secret silently producing un-verifiable
+ * signatures).
+ */
+
+var b      = require("..");
+var fs     = require("node:fs");
+var path   = require("node:path");
+
+function fail(msg) {
+  process.stderr.write("[sign-release-artifact] " + msg + "\n");
+  process.exit(1);
+}
+
+function readPubKey() {
+  var pubPath = path.resolve(__dirname, "..", "keys", "release-pqc-pub.json");
+  var raw;
+  try { raw = fs.readFileSync(pubPath, "utf8"); }
+  catch (e) { fail("cannot read " + pubPath + ": " + (e && e.message || e)); }
+  var doc;
+  try { doc = JSON.parse(raw); }
+  catch (e) { fail("malformed " + pubPath + ": " + (e && e.message || e)); }
+  if (doc.algorithm !== "ml-dsa-65") {
+    fail("unexpected algorithm in pubkey: " + JSON.stringify(doc.algorithm) +
+      " (expected ml-dsa-65); re-run scripts/generate-release-signing-key.js to migrate");
+  }
+  if (typeof doc.publicKey !== "string" || doc.publicKey.length === 0) {
+    fail("publicKey missing/empty in " + pubPath);
+  }
+  return new Uint8Array(Buffer.from(doc.publicKey, "base64url"));
+}
+
+function main() {
+  var artifactPath = process.argv[2];
+  if (!artifactPath) fail("usage: node scripts/sign-release-artifact.js <artifact-path>");
+
+  var secB64 = process.env.RELEASE_PQC_SIGNING_KEY;
+  if (!secB64 || secB64.length === 0) {
+    fail("RELEASE_PQC_SIGNING_KEY env not set. Run scripts/generate-release-signing-key.js once + set the secret in the npm-publish env.");
+  }
+
+  var secretKey = new Uint8Array(Buffer.from(secB64, "base64url"));
+  if (secretKey.length !== 4032) {                                                    // allow:raw-byte-literal — FIPS 204 ML-DSA-65 secret-key byte length
+    fail("RELEASE_PQC_SIGNING_KEY decodes to " + secretKey.length +
+      " bytes; expected 4032 (FIPS 204 ML-DSA-65). Key may be corrupted.");
+  }
+  var publicKey = readPubKey();
+  if (publicKey.length !== 1952) {                                                    // allow:raw-byte-literal — FIPS 204 ML-DSA-65 public-key byte length
+    fail("in-tree publicKey decodes to " + publicKey.length +
+      " bytes; expected 1952 (FIPS 204 ML-DSA-65). keys/release-pqc-pub.json corrupted.");
+  }
+
+  var artifactBytes = new Uint8Array(fs.readFileSync(artifactPath));
+  process.stderr.write("[sign-release-artifact] signing " + artifactPath +
+    " (" + artifactBytes.length + " bytes) with ml-dsa-65...\n");
+
+  var sigBytes = b.pqcSoftware.ml_dsa_65.sign(artifactBytes, secretKey);
+
+  // Self-verify against the in-tree pubkey before writing — defends
+  // against an env secret that doesn't match the published pubkey.
+  // If verify fails, refuse to write — the operator-side verification
+  // path would also fail, and the workflow's downstream `gh release
+  // create` step would attach a signature that no one can verify.
+  var ok = b.pqcSoftware.ml_dsa_65.verify(sigBytes, artifactBytes, publicKey);
+  if (!ok) {
+    fail("self-verify FAILED — RELEASE_PQC_SIGNING_KEY does NOT match keys/release-pqc-pub.json. " +
+      "Either the env secret is stale (re-run scripts/generate-release-signing-key.js + update secret) " +
+      "or keys/release-pqc-pub.json was committed without the matching secret update. Refusing to write a non-verifiable .sig.");
+  }
+
+  var sigPath = artifactPath + ".mldsa.sig";
+  fs.writeFileSync(sigPath, Buffer.from(sigBytes));
+  process.stderr.write("[sign-release-artifact] OK — wrote " + sigPath +
+    " (" + sigBytes.length + " bytes); self-verified against in-tree pubkey\n");
+}
+
+main();

package/lib/vendor/blamejs/scripts/test-integration.js

@@ -0,0 +1,181 @@
+"use strict";
+/**
+ * scripts/test-integration.js
+ *
+ * Integration test runner. Validates the docker-compose.test.yml stack
+ * is reachable, exports the test CA out of the docker volume, then
+ * spawns each test in test/integration/ as its own node process with
+ * NODE_EXTRA_CA_CERTS set so every TLS handshake the framework does
+ * during the test trusts the CA — no rejectUnauthorized=false bypass
+ * anywhere in the test surface.
+ *
+ * Distinct from `test/smoke.js` because the smoke gate must remain
+ * pure — runs in CI, in prepack-guard, on a developer laptop with no
+ * docker stack — and a "skip silently when service is down" branch in
+ * a layer-N test makes that gate's pass count misleading and masks
+ * bugs that only surface against a live backend.
+ *
+ * Exit codes:
+ *   0 — every integration test passed
+ *   1 — one or more services unreachable (rerun after `docker compose up`)
+ *   2 — at least one test file threw / returned non-zero
+ *   3 — script-level error (no test files found, CA export failed, etc.)
+ *
+ * Usage:
+ *   node scripts/test-integration.js
+ *   node scripts/test-integration.js queue-redis           — single test
+ *   node scripts/test-integration.js --skip-service-check  — assume up
+ */
+var fs   = require("node:fs");
+var os   = require("node:os");
+var path = require("node:path");
+var spawn = require("node:child_process").spawn;
+
+var INTEGRATION_DIR = path.join(__dirname, "..", "test", "integration");
+var CHECK_SERVICES  = path.join(__dirname, "check-services.js");
+var CA_EXPORT_PATH  = path.join(os.tmpdir(), "blamejs-test-ca.crt");
+
+function _padRight(s, n) {
+  s = String(s);
+  return s.length >= n ? s : s + " ".repeat(n - s.length);
+}
+
+function _spawn(cmd, args, opts) {
+  return new Promise(function (resolve, reject) {
+    var child = spawn(cmd, args, Object.assign({ stdio: "inherit" }, opts || {}));
+    child.once("exit", function (code, signal) {
+      resolve({ code: code, signal: signal });
+    });
+    child.once("error", reject);
+  });
+}
+
+function _spawnCapturing(cmd, args, env) {
+  return new Promise(function (resolve, reject) {
+    var child = spawn(cmd, args, { env: env, stdio: ["ignore", "pipe", "pipe"] });
+    var stdout = "";
+    var stderr = "";
+    child.stdout.on("data", function (b) { stdout += b.toString(); });
+    child.stderr.on("data", function (b) { stderr += b.toString(); });
+    child.once("exit", function (code, signal) {
+      resolve({ code: code, signal: signal, stdout: stdout, stderr: stderr });
+    });
+    child.once("error", reject);
+  });
+}
+
+async function _exportCaCert() {
+  // The pki-init container exits after generating certs, so we copy
+  // from any container that mounts the certs volume — redis is always
+  // up and has /certs read-only.
+  var rv = await _spawnCapturing("docker", ["cp", "blamejs-test-redis:/certs/ca.crt", CA_EXPORT_PATH], process.env);
+  if (rv.code !== 0) {
+    throw new Error("docker cp ca.crt failed: " + (rv.stderr || rv.stdout || "").trim());
+  }
+  if (!fs.existsSync(CA_EXPORT_PATH)) {
+    throw new Error("ca.crt not present at " + CA_EXPORT_PATH + " after docker cp");
+  }
+  var pem = fs.readFileSync(CA_EXPORT_PATH, "utf8");
+  if (pem.indexOf("-----BEGIN CERTIFICATE-----") !== 0) {
+    throw new Error("exported ca.crt does not look like a PEM cert");
+  }
+  return CA_EXPORT_PATH;
+}
+
+(async function main() {
+  var args = process.argv.slice(2);
+  var skipCheck = args.indexOf("--skip-service-check") !== -1;
+  var named = args.filter(function (a) { return a.charAt(0) !== "-"; });
+
+  if (!fs.existsSync(INTEGRATION_DIR)) {
+    console.error("[test-integration] missing dir: " + INTEGRATION_DIR);
+    process.exit(3);
+  }
+
+  var files = fs.readdirSync(INTEGRATION_DIR)
+    .filter(function (f) { return f.endsWith(".test.js"); })
+    .filter(function (f) {
+      if (named.length === 0) return true;
+      return named.some(function (n) { return f === n || f === n + ".test.js"; });
+    })
+    .sort();
+
+  if (files.length === 0) {
+    console.error("[test-integration] no test files matched " +
+      (named.length === 0 ? "test/integration/*.test.js" : named.join(", ")));
+    process.exit(3);
+  }
+
+  if (!skipCheck) {
+    console.log("[test-integration] running scripts/check-services.js gate...");
+    var checkExit = await _spawn(process.execPath, [CHECK_SERVICES]);
+    if (checkExit.code !== 0) {
+      console.error("[test-integration] service-check gate failed (exit " + checkExit.code + ")");
+      console.error("[test-integration] bring the stack up: docker compose -f docker-compose.test.yml up -d --wait");
+      console.error("[test-integration] OR re-run with --skip-service-check to bypass");
+      process.exit(1);
+    }
+  }
+
+  // Export the test CA so each test process trusts it at startup. This
+  // is the cleanest way to test against private TLS endpoints without
+  // weakening the framework's verification — operators in production
+  // do exactly the same thing (set NODE_EXTRA_CA_CERTS or trust the
+  // CA at the OS level).
+  var caPath;
+  try {
+    caPath = await _exportCaCert();
+    console.log("[test-integration] CA exported: " + caPath);
+  } catch (e) {
+    console.error("[test-integration] CA export failed: " + e.message);
+    process.exit(3);
+  }
+
+  var childEnv = Object.assign({}, process.env, {
+    NODE_EXTRA_CA_CERTS:           caPath,
+    BLAMEJS_TEST_CA_PATH:          caPath,
+    BLAMEJS_INTEGRATION_RUNNER:    "1",
+  });
+
+  console.log("");
+  console.log("[test-integration] running " + files.length + " integration test file" +
+    (files.length === 1 ? "" : "s") + " (each in a fresh node process)...");
+  var suiteStart = Date.now();
+  var failed = 0;
+  for (var i = 0; i < files.length; i++) {
+    var fullPath = path.join(INTEGRATION_DIR, files[i]);
+    var fileStart = Date.now();
+    var rv;
+    try {
+      rv = await _spawnCapturing(process.execPath, [fullPath], childEnv);
+    } catch (err) {
+      failed += 1;
+      console.error("  " + _padRight(files[i], 40) + " SPAWN FAILED");
+      console.error("    " + (err.message || String(err)));
+      continue;
+    }
+    var ms = Date.now() - fileStart;
+    if (rv.code === 0) {
+      // Success line: pull the trailing OK line out of stdout so the
+      // runner output stays consistent with smoke's format.
+      var okLine = (rv.stdout.match(/OK — \d+ checks? passed/g) || []).pop() || "";
+      console.log("  " + _padRight(files[i], 40) + " (" + ms + "ms) " + okLine);
+    } else {
+      failed += 1;
+      console.error("  " + _padRight(files[i], 40) + " FAILED (exit " + rv.code + ")");
+      var lines = (rv.stderr || rv.stdout || "").split(/\r?\n/).filter(Boolean).slice(-12);
+      lines.forEach(function (l) { console.error("    " + l); });
+    }
+  }
+  console.log("");
+  if (failed === 0) {
+    console.log("[test-integration] OK — " + files.length + " files in " +
+      (Date.now() - suiteStart) + "ms");
+    process.exit(0);
+  }
+  console.error("[test-integration] " + failed + " of " + files.length + " files failed");
+  process.exit(2);
+})().catch(function (err) {
+  console.error("[test-integration] runner error: " + ((err && err.stack) || err));
+  process.exit(3);
+});

package/lib/vendor/blamejs/scripts/test-wiki-integration.js

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * scripts/test-wiki-integration.js
+ *
+ * Wiki-app integration runner. Validates the docker-compose.test.yml
+ * stack, exports the test CA, then boots the wiki app against the live
+ * backends and runs examples/wiki/test/integration.js — the wiki's
+ * end-to-end "real app against real services" gate.
+ *
+ * Distinct from `test/smoke.js` and `examples/wiki/test/e2e.js` (both
+ * pure, no docker dependency, run in CI / on a developer laptop /
+ * inside prepack-guard) and complementary to `scripts/test-integration.js`
+ * (per-primitive integration tests). This runner exercises the wiki's
+ * actual operational wiring — proving framework primitives work
+ * end-to-end through the same boot path operators run in production.
+ *
+ * Exit codes:
+ *   0 — wiki integration passed
+ *   1 — service stack unreachable (rerun after `docker compose up`)
+ *   2 — wiki integration failed
+ *   3 — runner error (CA export failed, no test files found, etc.)
+ */
+var fs    = require("node:fs");
+var os    = require("node:os");
+var path  = require("node:path");
+var spawn = require("node:child_process").spawn;
+
+var WIKI_DIR        = path.join(__dirname, "..", "examples", "wiki");
+var WIKI_TEST_FILE  = path.join(WIKI_DIR, "test", "integration.js");
+var CHECK_SERVICES  = path.join(__dirname, "check-services.js");
+var CA_EXPORT_PATH  = path.join(os.tmpdir(), "blamejs-test-ca.crt");
+
+function _spawn(cmd, args, opts) {
+  return new Promise(function (resolve, reject) {
+    var child = spawn(cmd, args, Object.assign({ stdio: "inherit" }, opts || {}));
+    child.once("exit", function (code, signal) { resolve({ code: code, signal: signal }); });
+    child.once("error", reject);
+  });
+}
+
+function _spawnCapturing(cmd, args, env) {
+  return new Promise(function (resolve, reject) {
+    var child = spawn(cmd, args, { env: env, stdio: ["ignore", "pipe", "pipe"] });
+    var stdout = "";
+    var stderr = "";
+    child.stdout.on("data", function (b) { stdout += b.toString(); });
+    child.stderr.on("data", function (b) { stderr += b.toString(); });
+    child.once("exit", function (code, signal) {
+      resolve({ code: code, signal: signal, stdout: stdout, stderr: stderr });
+    });
+    child.once("error", reject);
+  });
+}
+
+async function _exportCaCert() {
+  var rv = await _spawnCapturing("docker",
+    ["cp", "blamejs-test-redis:/certs/ca.crt", CA_EXPORT_PATH],
+    process.env);
+  if (rv.code !== 0) {
+    throw new Error("docker cp ca.crt failed: " + (rv.stderr || rv.stdout || "").trim());
+  }
+  if (!fs.existsSync(CA_EXPORT_PATH)) {
+    throw new Error("ca.crt not present at " + CA_EXPORT_PATH);
+  }
+  return CA_EXPORT_PATH;
+}
+
+(async function main() {
+  var args = process.argv.slice(2);
+  var skipCheck = args.indexOf("--skip-service-check") !== -1;
+
+  if (!fs.existsSync(WIKI_TEST_FILE)) {
+    console.error("[test-wiki-integration] missing test file: " + WIKI_TEST_FILE);
+    process.exit(3);
+  }
+
+  if (!skipCheck) {
+    console.log("[test-wiki-integration] running scripts/check-services.js gate...");
+    var checkExit = await _spawn(process.execPath, [CHECK_SERVICES]);
+    if (checkExit.code !== 0) {
+      console.error("[test-wiki-integration] service-check gate failed (exit " + checkExit.code + ")");
+      console.error("[test-wiki-integration] bring the stack up: docker compose -f docker-compose.test.yml up -d --wait");
+      console.error("[test-wiki-integration] OR re-run with --skip-service-check to bypass");
+      process.exit(1);
+    }
+  }
+
+  // Export the CA so the wiki app's TLS handshakes (mailpit STARTTLS,
+  // outbound HTTPS, redis-tls if exercised) trust the test CA without
+  // a rejectUnauthorized:false bypass anywhere in the wiki surface.
+  var caPath;
+  try {
+    caPath = await _exportCaCert();
+    console.log("[test-wiki-integration] CA exported: " + caPath);
+  } catch (e) {
+    console.error("[test-wiki-integration] CA export failed: " + e.message);
+    process.exit(3);
+  }
+
+  var childEnv = Object.assign({}, process.env, {
+    NODE_EXTRA_CA_CERTS:        caPath,
+    BLAMEJS_TEST_CA_PATH:       caPath,
+    BLAMEJS_INTEGRATION_RUNNER: "1",
+  });
+
+  console.log("");
+  console.log("[test-wiki-integration] booting wiki + running integration suite...");
+  var start = Date.now();
+  var rv = await _spawnCapturing(process.execPath, [WIKI_TEST_FILE], childEnv);
+  var ms = Date.now() - start;
+
+  // Stream child output so the operator sees progress + assertions.
+  process.stdout.write(rv.stdout);
+  if (rv.stderr) process.stderr.write(rv.stderr);
+
+  console.log("");
+  if (rv.code === 0) {
+    console.log("[test-wiki-integration] OK — wiki integration green in " + ms + "ms");
+    process.exit(0);
+  }
+  console.error("[test-wiki-integration] FAIL — wiki integration failed (exit " + rv.code + ", " + ms + "ms)");
+  process.exit(2);
+})().catch(function (err) {
+  console.error("[test-wiki-integration] runner error: " + ((err && err.stack) || err));
+  process.exit(3);
+});

package/lib/vendor/blamejs/scripts/validate-source-comment-blocks.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+"use strict";
+// scripts/validate-source-comment-blocks — framework-level static gate
+// that runs the source-driven wiki's @module + @primitive comment-
+// block validator from a clean checkout.
+//
+// Why: the same validator nit class (`@related namespace-not-primitive`,
+// missing @primitive blocks, prose-too-short) was rediscovered in CI
+// across three consecutive release PRs because the only path that
+// surfaced it was the wiki-e2e gate — which requires
+// `cd examples/wiki && npm install` and runs ~90s into the smoke
+// matrix. Moving the engine into a script that runs in the cheap
+// static-gates step (alongside eslint / shellcheck /
+// codebase-patterns) catches the same drift pre-push, in <5s.
+//
+// Pure script — no side effects, no network, no DB. Imports:
+//   - examples/wiki/lib/source-comment-block-validator (the engine)
+//   - examples/wiki/lib/source-doc-parser              (the parser)
+//   - examples/wiki/wiki.config                        (curation pages)
+//
+// opts-resolver is intentionally NOT imported here. It loads
+// @blamejs/core to probe runtime opt allow-lists; the framework's lib/
+// itself isn't an npm package at this layer, and the wiki's
+// node_modules symlinks aren't guaranteed present in a fresh checkout.
+// The opts-undocumented check (#9b) is wiki-e2e exclusive — the
+// `examples/wiki/test/validate-source-comment-blocks.js` entry still
+// runs it. Every other check fires here.
+//
+// Exit codes:
+//   0 — no findings
+//   1 — findings present (CLI prints each finding, file path, and
+//       primitive identifier in the same format the wiki-e2e gate
+//       emits, so downstream operator muscle memory keeps working)
+
+var path = require("node:path");
+
+var ROOT    = path.resolve(__dirname, "..");
+var LIB_DIR = path.join(ROOT, "lib");
+var WIKI    = path.join(ROOT, "examples", "wiki");
+
+var engine = require(path.join(WIKI, "lib", "source-comment-block-validator"));
+var parser = require(path.join(WIKI, "lib", "source-doc-parser"));
+
+// wiki.config requires site.config → lib/auto-site-entries → source-doc-parser
+// — every link is pure (no @blamejs/core, no DB, no vault). When the
+// curation can't load for any reason (shouldn't happen on a clean
+// checkout), fall back to an empty list — the per-namespace coverage
+// check (#8) just goes quiet, the rest of the engine still fires.
+var curationPages = [];
+try {
+  var curation = require(path.join(WIKI, "wiki.config"));
+  if (curation && Array.isArray(curation.pages)) curationPages = curation.pages;
+} catch (e) {
+  console.warn("[validate-source-comment-blocks] wiki.config not loadable: " + (e && e.message) + " — skipping curation cross-check.");
+}
+
+function _report(findings) {
+  if (findings.length === 0) {
+    console.log("[validate-source-comment-blocks] OK - no findings");
+    return 0;
+  }
+  console.log("[validate-source-comment-blocks] " + findings.length + " finding(s):");
+  findings.forEach(function (f, i) {
+    console.log("  " + (i + 1) + ". [" + f.kind + "] " + f.file + (f.primitive ? " :: " + f.primitive : ""));
+    console.log("     " + f.msg);
+  });
+  return 1;
+}
+
+var findings = engine.validate({
+  libDir:        LIB_DIR,
+  curationPages: curationPages,
+  parser:        parser,
+  // optsResolver intentionally omitted — see comment block above.
+});
+
+process.exit(_report(findings));