@bongos/core 1.21.175 → 1.21.177

package/scripts/bongos/mirror-redact.js

@@ -0,0 +1,350 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/bongos/mirror-redact.js — the FILE-LEVEL redaction layer for the Cloud Bongos
+// public mirror. GDS-V4 R72 (task 1211), implementing ADR 0098 §6 + ADR 0065 §4.
+//
+// WHAT THIS DOES. The publish manifest (scripts/bongos/publish-manifest.js, task 1210)
+// draws the SUBTREE boundary — which files publish at all. But many PUBLISHED files
+// still contain instance literals *inside* them: docs/architecture.md names the
+// droplet IP (v4 + v6), ~230 published files mention the instance domain, ~50 name the
+// owner login. The 6-month publish delay does NOT scrub those. This module strips them:
+//   • the instance domain + every subdomain  → example.com
+//   • the instance token (repo/db/world name) → example / Example
+//   • the owner login(s) + aliases            → example-owner
+//   • any PUBLIC-ROUTABLE IPv4 or IPv6 (the droplet) → REDACTED_IP  (localhost/private kept)
+//   • + a secret backstop (modules/security/secret-scrub) the export layer composes.
+//
+// SELF-LEAK INVARIANT (load-bearing — tests/mirror_redact.mjs asserts it). This file
+// is itself PUBLISHED (it lives under scripts/). It therefore contains NO instance
+// literal — not the domain, not the owner login, not the droplet IP. Every literal is
+// DERIVED AT RUNTIME from the branding object the caller passes (config/branding.json,
+// which is itself EXCLUDED from the mirror) plus caller-supplied extras. The only
+// literals here are the universal RFC-defined IP ranges (constants, identical on every
+// instance) and the generic neutral replacements (example.com / example-owner /
+// REDACTED_IP). A vanilla clone redacts ITS OWN instance's literals with this same code.
+//
+// GATE IS STRICTER THAN REDACTION (learned the hard way, task 1211). findLeaks() does
+// NOT reuse the redaction regexes — a bounded redaction rule (\bowner\b) silently misses
+// `\bowner` inside a regex-literal string, and if the detector shared that rule the miss
+// would be invisible. So the detector scans for the RAW literal as a case-insensitive
+// SUBSTRING (plus the IP floors). Redaction is smart (avoids over-mangling); the gate is
+// dumb and strict (any raw literal anywhere = fail closed). One derivation feeds both.
+//
+// REUSE. findLeaks() is the shared no-leak primitive: the export pipeline (this task)
+// calls it as a FAIL-CLOSED gate before pushing, and the R73 proof (#1212) calls it to
+// assert the published mirror is clean. One detector, two consumers — no second list.
+
+const { scrubSecrets } = require('../../modules/security/secret-scrub');
+
+const NEUTRAL_DOMAIN = 'example.com';   // RFC 2606 reserved-for-documentation domain
+const NEUTRAL_TOKEN = 'example';        // instance token (repo/db/world name) replacement
+const NEUTRAL_OWNER = 'example-owner';  // owner-login replacement
+const REDACTED_IP = 'REDACTED_IP';      // droplet / public-IP replacement (NOT an IP, so the floor never re-flags it)
+
+// ---------------------------------------------------------------------------
+// IPv4 — redact PUBLIC-ROUTABLE addresses (the droplet's prod IP), keep loopback,
+// RFC-1918 private, link-local, CGNAT, multicast/reserved, and the RFC-5737 doc
+// ranges (those legitimately appear in examples). Decided in a FUNCTION over the
+// parsed octets rather than a monster regex — readable + reused by the detector.
+// ---------------------------------------------------------------------------
+const IPV4_CANDIDATE_RE = /\b(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})\b/g;
+
+// A dotted quad with a LEADING-ZERO octet is not an address in any notation a human
+// or a tool writes: `0` stands alone as one digit, and `07` reads as OCTAL, so no log
+// line, config file or doc spells a host that way. What does produce them is packed
+// numeric data — SVG path coordinates. `…5.47 7.59.4.07.5…` in the committed GitHub
+// logo path contains "7.59.4.07", which the candidate regex happily reads as an IP;
+// that alone accounted for ten phantom public-ip leaks across the design mocks and
+// the landing page. The guard reads the raw octet TEXT because the parsed number has
+// already lost the zero, and it costs zero recall — a real leaked IP never has one.
+function hasLeadingZeroOctet(octets) {
+  return octets.some((o) => o.length > 1 && o[0] === '0');
+}
+
+function isPublicRoutableIPv4(a, b, c, d) {
+  for (const o of [a, b, c, d]) if (o < 0 || o > 255) return false; // not a valid dotted-quad
+  if (a === 0) return false;                       // 0.0.0.0/8 "this network"
+  if (a === 10) return false;                      // 10/8 private
+  if (a === 127) return false;                     // 127/8 loopback
+  if (a === 169 && b === 254) return false;        // 169.254/16 link-local
+  if (a === 172 && b >= 16 && b <= 31) return false; // 172.16/12 private
+  if (a === 192 && b === 168) return false;        // 192.168/16 private
+  if (a === 100 && b >= 64 && b <= 127) return false; // 100.64/10 CGNAT (RFC 6598)
+  if (a >= 224) return false;                      // 224/4 multicast + 240/4 reserved + 255.* (netmasks/broadcast)
+  if (a === 192 && b === 0 && c === 2) return false;     // 192.0.2.0/24 TEST-NET-1 (RFC 5737)
+  if (a === 198 && b === 51 && c === 100) return false;  // 198.51.100.0/24 TEST-NET-2
+  if (a === 203 && b === 0 && c === 113) return false;   // 203.0.113.0/24 TEST-NET-3
+  if (a === 198 && (b === 18 || b === 19)) return false;  // 198.18.0.0/15 benchmarking (RFC 2544)
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// IPv6 — same idea. Parse the candidate into 8 hextets (handling "::" compression),
+// reject non-addresses (e.g. a "12:34:56" timestamp), then redact only global-unicast.
+// The candidate requires a leading hex group, so "::"/"::1" (loopback/unspecified) are
+// never matched — which is correct, we would keep them anyway. BOUNDARY GUARD
+// (task 1688): the candidate must NOT be glued to an ASCII letter or `$` on either
+// side, so a code cast like `$9::bigint` (a Postgres positional-param cast) or
+// `beef::int` (a scope operator) is not misread as the address 9:: / beef:: — a real
+// address is delimited by space/quote/brackets/,;=/ and slashes, never by letters.
+// Zero recall loss on a genuinely leaked IPv6 (it ends in hex + a delimiter). This
+// const drives BOTH redactPublicIPs (the redactor) and firstPublicIP (the leak gate),
+// so the guard fixes the redactor corrupting `$9::bigint` → `$REDACTED_IPbigint` too.
+// ---------------------------------------------------------------------------
+const IPV6_CANDIDATE_RE = /(?<![0-9A-Za-z$:])[0-9a-fA-F]{1,4}(?::[0-9a-fA-F]{0,4}){2,7}(?![0-9A-Za-z:])/g;
+
+function parseIPv6(s) {
+  if (typeof s !== 'string' || !s.includes(':')) return null;
+  const dbl = s.split('::');
+  if (dbl.length > 2) return null; // more than one "::" is invalid
+  let groups;
+  if (dbl.length === 2) {
+    const head = dbl[0] ? dbl[0].split(':') : [];
+    const tail = dbl[1] ? dbl[1].split(':') : [];
+    if (head.length + tail.length > 7) return null; // "::" must compress >= 1 zero group
+    groups = [...head, ...Array(8 - head.length - tail.length).fill('0'), ...tail];
+  } else {
+    groups = s.split(':');
+  }
+  if (groups.length !== 8) return null;
+  const nums = [];
+  for (const g of groups) {
+    if (!/^[0-9a-fA-F]{1,4}$/.test(g)) return null;
+    nums.push(parseInt(g, 16));
+  }
+  return nums;
+}
+
+function isPublicRoutableIPv6(s) {
+  const g = parseIPv6(s);
+  if (!g) return false;
+  if (g.slice(0, 7).every((x) => x === 0)) return false; // :: (unspecified) and ::1 (loopback)
+  const h = g[0];
+  // ::/8 is IETF-RESERVED (RFC 4291 §2.4) — no host is reachable there, so an address
+  // in it is never a real leak. Excluding it is what stops degenerate shorthand like
+  // `5::` / `c9::` from matching: those are 2-3 chars that random BINARY bytes hit
+  // constantly, which flagged 7 phantom "public-ip" leaks across committed .png/.webp
+  // assets and left the C9 full-tree mirror gate permanently red (task 1002470).
+  if (h < 0x0100) return false;                 // reserved ::/8
+  if (h >= 0xfe80 && h <= 0xfebf) return false; // link-local fe80::/10
+  if (h === 0x2001 && g[1] === 0x0db8) return false; // 2001:db8::/32 documentation (RFC 3849)
+  if (h >= 0xfc00 && h <= 0xfdff) return false; // ULA fc00::/7
+  if (h >= 0xff00) return false;                // multicast ff00::/8
+  return true;                                  // global unicast (2000::/3, etc.)
+}
+
+function redactPublicIPs(text) {
+  let out = text.replace(IPV4_CANDIDATE_RE, (m, a, b, c, d) =>
+    (!hasLeadingZeroOctet([a, b, c, d]) && isPublicRoutableIPv4(+a, +b, +c, +d)) ? REDACTED_IP : m);
+  out = out.replace(IPV6_CANDIDATE_RE, (m) => (isPublicRoutableIPv6(m) ? REDACTED_IP : m));
+  return out;
+}
+
+function firstPublicIP(text) {
+  IPV4_CANDIDATE_RE.lastIndex = 0;
+  let m;
+  while ((m = IPV4_CANDIDATE_RE.exec(text))) {
+    if (!hasLeadingZeroOctet([m[1], m[2], m[3], m[4]]) && isPublicRoutableIPv4(+m[1], +m[2], +m[3], +m[4])) { IPV4_CANDIDATE_RE.lastIndex = 0; return m[0]; }
+  }
+  IPV6_CANDIDATE_RE.lastIndex = 0;
+  while ((m = IPV6_CANDIDATE_RE.exec(text))) {
+    if (isPublicRoutableIPv6(m[0])) { IPV6_CANDIDATE_RE.lastIndex = 0; return m[0]; }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Deriving the instance literals from branding (config/branding.json). Pure.
+// ---------------------------------------------------------------------------
+function escapeRegExp(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// hostname → its registrable second-level label, e.g. "status.acme.com" → "acme".
+function registrableLabel(host) {
+  const h = String(host || '').replace(/^https?:\/\//, '').replace(/[:/].*$/, '').replace(/^\./, '').trim().toLowerCase();
+  if (!h || !h.includes('.')) return null;
+  const parts = h.split('.').filter(Boolean);
+  if (parts.length < 2) return null;
+  return parts[parts.length - 2]; // the SLD label (handles arbitrary subdomain depth)
+}
+
+// Collect the instance-identifying literals from a branding object. Returns
+// { tokens:Set, owners:Set, literals:string[] } — tokens are coined identity words
+// (domain SLD label, repo/db name, world name); owners are login handles + aliases;
+// literals are caller-supplied exact strings (e.g. the droplet IP). Defensive against
+// a partial/empty branding (a vanilla instance). Tokens/owners match case-INSENSITIVELY
+// so they dedup on lowercase — "acme"/"Acme" collapse to one.
+function deriveInstanceLiterals(branding = {}, extra = {}) {
+  const tokens = new Set();
+  const owners = new Set();
+  const add = (set, v) => { if (typeof v === 'string' && v.trim()) set.add(v.trim().toLowerCase()); };
+
+  for (const v of Object.values(branding.domains || {})) {
+    const label = registrableLabel(v);
+    if (label) add(tokens, label);
+  }
+  const repo = branding.repo || {};
+  add(tokens, repo.name);
+  add(owners, repo.owner);
+  add(owners, branding.firstAdmin);
+  const identity = branding.identity || {};
+  add(tokens, identity.worldName);
+  // The PRODUCT name is instance identity too. It was leaking into the published core (the
+  // onboarding primer described this instance's product as the reader's own project) because
+  // only worldName was derived — the redactor never saw it AND findLeaks couldn't gate it.
+  // Deriving it here closes both in one place. (task 2153)
+  add(tokens, identity.productName);
+  // The reward-currency label is per-instance identity as well; a vanilla core must not ship
+  // another instance's currency name (the currency/karma onboarding doc carried it verbatim).
+  add(tokens, (branding.currency || {}).label);
+  // The fulfillment/parent company is instance identity too (a coined single word like
+  // "Acme"); redact its name + its site's registrable label.
+  const company = identity.company || {};
+  add(tokens, company.name);
+  { const label = registrableLabel(company.site); if (label) add(tokens, label); }
+
+  // `extra` also carries a caller-supplied FIXED FLOOR: the package-core neutral-floor gate
+  // (task 1002217 / audit H4) injects prior-instance tokens/owners here so published DOCS de-brand
+  // against them and the fail-closed gate fires EVEN WITH NO branding.json. Those floor literals
+  // live with the CALLER (package-core), never hardcoded in this file — so this redactor's self-leak
+  // invariant (tests/mirror_redact.mjs) keeps holding while the floor is still enforced.
+  for (const t of extra.tokens || []) add(tokens, t);
+  for (const o of extra.owners || []) add(owners, o);
+
+  // A token that is ALSO an owner would double-rule; owners win their own rule.
+  for (const o of owners) tokens.delete(o);
+  const literals = (extra.literals || []).filter((s) => typeof s === 'string' && s.length >= 3);
+  return { tokens, owners, literals };
+}
+
+// The FLAT list of raw sensitive strings the detector substring-scans for. (IPs are
+// handled by the floors, not this list — but caller-supplied exact IP literals are
+// included so the gate asserts that specific value is gone too.)
+function collectSensitiveLiterals(branding = {}, extra = {}) {
+  const { tokens, owners, literals } = deriveInstanceLiterals(branding, extra);
+  return [...tokens, ...owners, ...literals];
+}
+
+// Build the ordered redaction rules. Each rule: { label, pattern:RegExp(global), replace }.
+// Replacements never re-match any rule, so redaction is fixed-point (idempotent) and the
+// detector stays clean on redacted output.
+function buildRedactionRules(branding = {}, extra = {}) {
+  const { tokens, owners, literals } = deriveInstanceLiterals(branding, extra);
+  const rules = [];
+
+  // Instance tokens: case-insensitive, case-preserving substring redaction. A coined
+  // identity word ("acme") is safe to replace everywhere — including inside "acme.com",
+  // "acme-status", and the bare DB name.
+  for (const tok of [...tokens].sort((a, b) => b.length - a.length)) {
+    rules.push({
+      label: `token:${tok}`,
+      pattern: new RegExp(escapeRegExp(tok), 'gi'),
+      replace: (m) => (/^[A-Z]/.test(m) ? NEUTRAL_TOKEN[0].toUpperCase() + NEUTRAL_TOKEN.slice(1) : NEUTRAL_TOKEN),
+    });
+  }
+  // Owner logins/aliases: UNBOUNDED case-insensitive substring (NOT \b-bounded). A login
+  // is unique enough that full substring replacement is safe, and it catches the login
+  // inside a regex literal ("\blars\b"-style) or a path ("/Users/<login>") — the exact
+  // gap a word-bounded rule left. Longest-first so an alias that contains a shorter one
+  // is handled before it.
+  for (const o of [...owners].sort((a, b) => b.length - a.length)) {
+    rules.push({
+      label: `owner:${o}`,
+      pattern: new RegExp(escapeRegExp(o), 'gi'),
+      replace: NEUTRAL_OWNER,
+    });
+  }
+  // Extra exact literals (e.g. a droplet IP sourced from env at publish time, so it need
+  // not appear in this published file). IP-shaped → REDACTED_IP; else → <redacted>.
+  for (const lit of literals) {
+    rules.push({
+      label: `literal:${lit.length}c`,
+      pattern: new RegExp(escapeRegExp(lit), 'g'),
+      replace: /^\d{1,3}(\.\d{1,3}){3}$/.test(lit) ? REDACTED_IP : '<redacted>',
+    });
+  }
+  return rules;
+}
+
+// Apply instance-literal + public-IP redaction to a string. PURE (no env, no secret
+// scrubbing — the export layer composes scrubSecrets around this).
+function redactText(text, rules) {
+  if (typeof text !== 'string' || text.length === 0) return text;
+  let out = text;
+  for (const r of rules || []) out = out.replace(r.pattern, r.replace);
+  out = redactPublicIPs(out);
+  return out;
+}
+
+// findLeaks — the FAIL-CLOSED no-leak detector, STRICTER than redaction. Scans for each
+// raw sensitive literal as a case-insensitive SUBSTRING + any public IPv4/IPv6. Returns
+// [] when clean, else [{ label, sample }]. `sensitiveLiterals` is the flat list from
+// collectSensitiveLiterals(); passing the derived literals (not the redaction rules)
+// is what makes the detector immune to a bounded-rule blind spot. Does NOT scan for
+// generic secrets — that is scrubSecrets' job (see findSecretLeak).
+function findLeaks(text, sensitiveLiterals) {
+  const leaks = [];
+  if (typeof text !== 'string' || text.length === 0) return leaks;
+  const lower = text.toLowerCase();
+  for (const lit of sensitiveLiterals || []) {
+    if (typeof lit !== 'string' || !lit) continue;
+    if (lower.includes(lit.toLowerCase())) leaks.push({ label: `literal:${lit.slice(0, 24)}`, sample: lit });
+  }
+  const ip = firstPublicIP(text);
+  if (ip) leaks.push({ label: 'public-ip', sample: ip });
+  return leaks;
+}
+
+// findSecretLeak — true if the generic secret scrubber WOULD change this text, i.e. a
+// secret shape is present. The export gate runs this in addition to findLeaks so a
+// stray credential in an old commit fails the publish closed rather than leaking.
+//
+// `opts` MUST be whatever the scrub being audited was given (task 1003873). Unlike
+// findLeaks — which is deliberately STRICTER than redaction, and independent of it by
+// design — this one is DIFFERENTIAL: it re-scrubs and asks "did anything change?". An
+// option the audit does not share therefore makes it disagree with its own subject by
+// construction, and reads that disagreement as a leak. That is not a safety margin, it
+// is a false positive: task 1002460's knownDocNames allowlist spares a long ADR
+// filename from the entropy sweep, an audit without the allowlist re-redacts it, the
+// text differs, and EVERY published doc reports a phantom secret shape. Because the
+// gate is fail-closed the packager then produces nothing — it took the publish lane
+// down for seven consecutive core releases before anyone read past the symptom.
+function findSecretLeak(text, extraSecrets = [], opts = undefined) {
+  if (typeof text !== 'string' || text.length === 0) return false;
+  return scrubSecrets(text, extraSecrets, opts) !== text;
+}
+
+module.exports = {
+  NEUTRAL_DOMAIN, NEUTRAL_TOKEN, NEUTRAL_OWNER, REDACTED_IP,
+  isPublicRoutableIPv4, isPublicRoutableIPv6, parseIPv6, redactPublicIPs, firstPublicIP,
+  hasLeadingZeroOctet,
+  registrableLabel, escapeRegExp, deriveInstanceLiterals, collectSensitiveLiterals,
+  buildRedactionRules, redactText, findLeaks, findSecretLeak,
+};
+
+// CLI: `node scripts/bongos/mirror-redact.js --rules` prints the rule labels derived from
+// THIS instance's config/branding.json (no secret values). Handy for a human to eyeball
+// the boundary; the pipeline imports the functions directly.
+if (require.main === module) {
+  const fs = require('node:fs');
+  const path = require('node:path');
+  const argv = process.argv.slice(2);
+  let branding = {};
+  try {
+    branding = JSON.parse(fs.readFileSync(path.resolve(__dirname, '../../config/branding.json'), 'utf8'));
+  } catch { /* vanilla instance / no branding — derive nothing */ }
+  const rules = buildRedactionRules(branding);
+  if (argv[0] === '--rules' || argv.length === 0) {
+    console.log(`mirror-redact: ${rules.length} instance-literal rule(s) derived from config/branding.json + the public-IPv4/IPv6 floor`);
+    for (const r of rules) console.log(`  ${r.label}`);
+    process.exit(0);
+  }
+  try {
+    process.stdout.write(redactText(fs.readFileSync(argv[0], 'utf8'), rules));
+  } catch (e) {
+    console.error(`cannot read ${argv[0]}: ${e.message}`);
+    process.exit(2);
+  }
+}

package/scripts/bongos/module-artifact.js

@@ -0,0 +1,289 @@
+// scripts/bongos/module-artifact.js — pack and verify ONE module version for the
+// Bongos-hosted module store (task 1004271, ADR 0338 D1).
+//
+// ADR 0338 settled "no second packaging format": a module version is a tarball plus a
+// hash manifest in exactly the shape package-core.js emits for the core — per-file
+// sha256, a compression-independent tree_sha256, a deterministic ustar+gzip — so the
+// tar writer, reader and tree pin all come from artifact-format.js, the file the core
+// release builds with. What differs is only WHAT is packed and what the manifest names:
+//
+//   tarball   package/<path inside modules/<key>/>   (module.json at package/module.json)
+//             package/.bongos-module.json            the inner manifest (below)
+//   manifest  { artifact: 'bongos-module', manifest_schema, generator, module_key,
+//               module_version, core_version, built_at, file_count, tree_sha256,
+//               files: [{ path, mode, sha256 }] }
+//   side-car  the same manifest + { tarball: { name, sha256, bytes } } (withTarballInfo)
+//
+// THE GATE. The core's isPublishable() is default-deny: a path ships only if the
+// allowlist names it and the denylist does not. The allowlist names the CORE's own
+// modules, so for a store module the allow side is "inside this module's own
+// modules/<key>/ directory" and the deny side is the SAME repo-wide denylist
+// (matchesDeny — game content, pixel art, copyrighted references, instance topology,
+// secrets), plus credential-named files anywhere in the module (SECRET_FILE_RE). Anything the denylist catches refuses the whole publish rather than being
+// silently dropped: a module that ships without a file it expected is a broken module.
+//
+// THE HOW-TO GATE (ADR 0347 D4, task 1004365). A store version must carry HOWTO.md
+// with the five required sections, each with some text. checkHowto is the ONE checker:
+// `bongos module publish` runs it before uploading and the store's upload route runs
+// it again through verifyModuleArtifact({ requireHowto: true }), so a hand-built upload
+// can't skip it. It is opt-in there because install and update verify with the same
+// function, and a version published before the gate existed must still install.
+//
+// Both halves live here so the CLI (packModule) and the store route
+// (verifyModuleArtifact) cannot disagree about the format. Pure apart from reading the
+// module directory in packModule; never touches the network or the database.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { sha256hex, canonicalTreeHash, normalizeMode, buildTar, readTarAsync } = require('./artifact-format');
+const { matchesDeny } = require('./publish-manifest');
+const { validateManifest } = require('../../src/module-loader/manifest-schema');
+
+const ARTIFACT_NAME = 'bongos-module';
+const MANIFEST_SCHEMA = 1;
+const TAR_ROOT = 'package/';
+const INNER_MANIFEST_PATH = '.bongos-module.json';
+const INNER_MANIFEST = TAR_ROOT + INNER_MANIFEST_PATH;
+// Local-only files a module dir may hold that are never part of the module itself.
+const NEVER_PACKED = new Set(['.upstream-signoff.json', INNER_MANIFEST_PATH]);
+// The store's caps. A real feature module is tens of KB (the biggest bundled one packs
+// to ~90 KB), so these are generous headroom — and deliberately small, because the
+// store verifies an upload inside the web process: every byte is inflated and hashed
+// there. 5 MB on the wire matches the upstreaming queue's SUBMISSION_MAX_BYTES; the
+// unpacked cap bounds a gzip bomb.
+const MAX_TARBALL_BYTES = 5 * 1024 * 1024;
+const READ_LIMITS = { maxUnpackedBytes: 16 * 1024 * 1024, maxFiles: 2000 };
+
+const HOWTO_FILE = 'HOWTO.md';
+// ADR 0347 D2 — level-2 headings, matched case-insensitively, in any order.
+const HOWTO_SECTIONS = ['What it does', 'Install and enable', 'How to use it', 'Configuration', 'Limits and known issues'];
+
+// Judge HOWTO.md's text (null = the file is absent). Reads headings only, never the
+// writing: a section counts as filled when it holds any text once HTML comments (the
+// scaffold's prompts) are removed. A heading inside a fenced code block doesn't count.
+// Returns { ok, problems: [a plain sentence naming the file or the section] }.
+function checkHowto(text) {
+  if (text == null) return { ok: false, problems: [`${HOWTO_FILE} is missing — every store module ships one (ADR 0347)`] };
+  const bodies = new Map();
+  let current = null;
+  let fence = null;
+  for (const line of String(text).replace(/<!--[\s\S]*?-->/g, '').split(/\r?\n/)) {
+    const f = line.match(/^\s*(```|~~~)/);
+    if (f) fence = fence === f[1] ? null : (fence || f[1]);
+    const h = !fence && !f && line.match(/^(#{1,6})\s+(.*?)\s*#*\s*$/);
+    if (h) {
+      // A level-1/2 heading starts a new section; a deeper one is structure, not text.
+      if (h[1].length <= 2) {
+        current = h[1].length === 2 ? h[2].toLowerCase() : null;
+        if (current !== null && !bodies.has(current)) bodies.set(current, '');
+      }
+      continue;
+    }
+    if (current !== null) bodies.set(current, bodies.get(current) + line.trim());
+  }
+  const problems = [];
+  for (const name of HOWTO_SECTIONS) {
+    const body = bodies.get(name.toLowerCase());
+    if (body === undefined) problems.push(`${HOWTO_FILE}: section "${name}" is missing`);
+    else if (!body) problems.push(`${HOWTO_FILE}: section "${name}" is empty`);
+  }
+  return { ok: problems.length === 0, problems };
+}
+
+function tarballName(key, version) { return `${ARTIFACT_NAME}-${key}-${version}.tgz`; }
+
+// Every file under dir, as module-relative forward-slash paths, sorted. Skips
+// VCS/dependency noise the way listModuleFiles (module.js) does.
+function listFiles(dir, rel = '') {
+  const out = [];
+  for (const entry of fs.readdirSync(path.join(dir, rel), { withFileTypes: true })) {
+    if (entry.name === 'node_modules' || entry.name === '.git') continue;
+    const r = rel ? `${rel}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) out.push(...listFiles(dir, r));
+    else if (entry.isFile()) out.push(r);
+  }
+  return out.sort();
+}
+
+// A module-relative path is safe to unpack only if it stays inside the module.
+function isSafeRelPath(p) {
+  return typeof p === 'string' && p.length > 0 && !p.startsWith('/') && !p.includes('\\')
+    && !/^[A-Za-z]:/.test(p) && !p.split('/').some((seg) => seg === '' || seg === '.' || seg === '..');
+}
+
+// The repo denylist anchors its secret entries at the root (`.env`, not
+// `modules/x/.env`), which is right for the core tree and wrong for a module that
+// travels on its own. So a store module is also refused any file whose NAME marks it
+// as a credential, wherever it sits in the module.
+const SECRET_FILE_RE = /^(?:\.env(?:\..*)?|\.npmrc|\.netrc|\.pgpass|id_(?:rsa|dsa|ecdsa|ed25519)(?:\.pub)?|.*\.(?:pem|key|p12|pfx|jks|keystore))$/i;
+
+// The files the gate refuses, named at their canonical modules/<key>/ path.
+function deniedFiles(key, relPaths) {
+  return relPaths
+    .filter((p) => matchesDeny(`modules/${key}/${p}`) || SECRET_FILE_RE.test(p.split('/').pop()))
+    .map((p) => `modules/${key}/${p}`);
+}
+
+function buildModuleManifest({ key, version, coreVersion, builtAtIso, files, treeHash }) {
+  return {
+    artifact: ARTIFACT_NAME,
+    manifest_schema: MANIFEST_SCHEMA,
+    generator: 'scripts/bongos/module-artifact.js',
+    module_key: key,
+    module_version: version,
+    core_version: coreVersion,
+    built_at: builtAtIso,
+    file_count: files.length,
+    tree_sha256: treeHash,
+    files: files.map((f) => ({ path: f.path, mode: normalizeMode(f.mode), sha256: f.sha256 })),
+  };
+}
+
+// Pack modules/<key>/ into { tgz, manifest, sidecar } or throw with a plain reason.
+// `modeOf` is injectable because Windows reports no executable bit.
+function packModule(key, { modulesDir, now = () => new Date(), modeOf } = {}) {
+  const dir = path.join(modulesDir, key);
+  if (!fs.existsSync(dir)) throw new Error(`modules/${key} does not exist`);
+  let moduleJson;
+  try { moduleJson = JSON.parse(fs.readFileSync(path.join(dir, 'module.json'), 'utf8')); }
+  catch { throw new Error(`modules/${key}/module.json is missing or is not valid JSON`); }
+  const { valid, errors } = validateManifest(moduleJson);
+  if (!valid) throw new Error(`modules/${key}/module.json is invalid: ${errors.join('; ')}`);
+  if (moduleJson.key !== key) throw new Error(`modules/${key}/module.json names key "${moduleJson.key}"`);
+
+  const rel = listFiles(dir).filter((p) => !NEVER_PACKED.has(p));
+  const denied = deniedFiles(key, rel);
+  if (denied.length) {
+    throw new Error(`the publish denylist refuses: ${denied.join(', ')} — remove them from the module (ADR 0098)`);
+  }
+  const unsafe = rel.filter((p) => !isSafeRelPath(p));
+  if (unsafe.length) throw new Error(`unpackable file name(s): ${unsafe.join(', ')}`);
+
+  const files = [];
+  const entries = [];
+  for (const p of rel) {
+    const abs = path.join(dir, ...p.split('/'));
+    const buf = fs.readFileSync(abs);
+    const mode = normalizeMode(modeOf ? modeOf(abs) : (fs.statSync(abs).mode & 0o777).toString(8));
+    files.push({ path: p, mode, sha256: sha256hex(buf) });
+    entries.push({ name: TAR_ROOT + p, mode: parseInt(mode, 8), buf });
+  }
+  const manifest = buildModuleManifest({
+    key, version: moduleJson.version, coreVersion: moduleJson.coreVersion,
+    builtAtIso: now().toISOString(), files, treeHash: canonicalTreeHash(files),
+  });
+  entries.push({ name: INNER_MANIFEST, mode: 0o644, buf: Buffer.from(JSON.stringify(manifest, null, 2) + '\n') });
+  const tgz = buildTar(entries);
+  const sidecar = { ...manifest, tarball: { name: tarballName(key, manifest.module_version), sha256: sha256hex(tgz), bytes: tgz.length } };
+  return { tgz, manifest, sidecar, moduleJson };
+}
+
+// The store's check on an upload. Trusts NOTHING the client says beyond the bytes:
+// every hash is recomputed, the inner manifest must describe exactly the files the
+// tarball holds, module.json must validate and name the route's key, and the
+// denylist runs again. Resolves { ok: true, ... } or { ok: false, code, message }.
+// Async so the inflate runs off the event loop (readTarAsync); the rest is one pass
+// over at most READ_LIMITS.maxUnpackedBytes.
+// `includeFiles: true` (install, task 1003785) also returns `files`: the module's own
+// files — [{ path, mode, buf }], the inner manifest left out — from the SAME parse the
+// hashes were checked against, so a caller that places them never re-reads the bytes.
+// `requireHowto: true` (the store's upload route, ADR 0347 D4) also refuses a version
+// whose HOWTO.md fails checkHowto.
+async function verifyModuleArtifact(tgz, { key, maxBytes = MAX_TARBALL_BYTES, includeFiles = false, requireHowto = false } = {}) {
+  const fail = (code, message) => ({ ok: false, code, message });
+  if (!Buffer.isBuffer(tgz) || tgz.length === 0) return fail('empty_artifact', 'the upload is empty');
+  if (tgz.length > maxBytes) return fail('artifact_too_large', `the tarball is over ${maxBytes} bytes`);
+
+  let entries;
+  try { entries = await readTarAsync(tgz, READ_LIMITS); }
+  catch (e) { return fail('bad_tarball', e.message); }
+
+  const byName = new Map();
+  for (const e of entries) {
+    if (!e.name.startsWith(TAR_ROOT)) return fail('bad_tarball', `"${e.name}" is outside ${TAR_ROOT}`);
+    const rel = e.name.slice(TAR_ROOT.length);
+    if (!isSafeRelPath(rel)) return fail('bad_tarball', `"${e.name}" is not a safe path`);
+    if (byName.has(rel)) return fail('bad_tarball', `"${e.name}" appears twice`);
+    byName.set(rel, e);
+  }
+  const inner = byName.get(INNER_MANIFEST_PATH);
+  if (!inner) return fail('no_manifest', `the tarball carries no ${INNER_MANIFEST}`);
+  let manifest;
+  try { manifest = JSON.parse(inner.buf.toString('utf8')); }
+  catch { return fail('no_manifest', `${INNER_MANIFEST} is not valid JSON`); }
+  if (manifest.artifact !== ARTIFACT_NAME || manifest.manifest_schema !== MANIFEST_SCHEMA || !Array.isArray(manifest.files)) {
+    return fail('bad_manifest', `${INNER_MANIFEST} is not a ${ARTIFACT_NAME} schema ${MANIFEST_SCHEMA} manifest`);
+  }
+
+  // Recompute the pin from the bytes and hold the manifest to it, file by file.
+  byName.delete(INNER_MANIFEST_PATH);
+  const actual = [...byName.entries()]
+    .map(([p, e]) => ({ path: p, mode: normalizeMode(e.mode.toString(8)), sha256: sha256hex(e.buf) }))
+    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  const declared = [...manifest.files].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  if (declared.length !== actual.length || manifest.file_count !== actual.length) {
+    return fail('hash_mismatch', `the manifest lists ${declared.length} file(s) but the tarball holds ${actual.length}`);
+  }
+  for (let i = 0; i < actual.length; i++) {
+    const a = actual[i]; const d = declared[i];
+    if (d.path !== a.path || normalizeMode(d.mode) !== a.mode || d.sha256 !== a.sha256) {
+      return fail('hash_mismatch', `"${a.path}" does not match its manifest entry`);
+    }
+  }
+  const treeSha = canonicalTreeHash(actual);
+  if (manifest.tree_sha256 !== treeSha) return fail('hash_mismatch', 'tree_sha256 does not match the files');
+
+  const denied = deniedFiles(key, actual.map((f) => f.path));
+  if (denied.length) return fail('denied_content', `the publish denylist refuses: ${denied.join(', ')}`);
+
+  const mj = byName.get('module.json');
+  if (!mj) return fail('bad_module', 'the tarball has no module.json');
+  let moduleJson;
+  try { moduleJson = JSON.parse(mj.buf.toString('utf8')); }
+  catch { return fail('bad_module', 'module.json is not valid JSON'); }
+  const v = validateManifest(moduleJson);
+  if (!v.valid) return fail('bad_module', `module.json is invalid: ${v.errors.join('; ')}`);
+  if (moduleJson.key !== key || manifest.module_key !== key) {
+    return fail('key_mismatch', `the tarball is module "${moduleJson.key}", not "${key}"`);
+  }
+  if (manifest.module_version !== moduleJson.version || manifest.core_version !== moduleJson.coreVersion) {
+    return fail('bad_manifest', 'the manifest version does not match module.json');
+  }
+  if (requireHowto) {
+    const howto = byName.get(HOWTO_FILE);
+    const h = checkHowto(howto ? howto.buf.toString('utf8') : null);
+    if (!h.ok) return fail('howto_incomplete', h.problems.join('; '));
+  }
+
+  const out = {
+    ok: true, manifest, moduleJson,
+    version: moduleJson.version, coreVersion: moduleJson.coreVersion,
+    treeSha256: treeSha, tarballSha256: sha256hex(tgz), bytes: tgz.length,
+  };
+  if (includeFiles) {
+    out.files = [...byName.entries()].map(([p, e]) => ({ path: p, mode: normalizeMode(e.mode.toString(8)), buf: e.buf }));
+  }
+  return out;
+}
+
+// The how-to a published version shipped with (task 1004366): read from the version's
+// own tarball, after the same hash check install runs, so the page always shows the
+// exact file that version was published with. A version from before the gate may have
+// none (text null). Text only — nothing in the module is run or rendered here.
+// Returns { ok, text, artifactUrl, title, version, tarballSha256 } or verifyModuleArtifact's failure.
+async function readHowto(tgz, { key }) {
+  const v = await verifyModuleArtifact(tgz, { key, includeFiles: true });
+  if (!v.ok) return v;
+  const file = v.files.find((f) => f.path === HOWTO_FILE);
+  const extra = v.moduleJson.howto || {};
+  return {
+    ok: true,
+    text: file ? file.buf.toString('utf8') : null,
+    artifactUrl: extra.artifactUrl || null,
+    title: v.moduleJson.title || key,
+    version: v.version,
+    tarballSha256: v.tarballSha256,
+  };
+}
+
+module.exports = { MAX_TARBALL_BYTES, HOWTO_FILE, HOWTO_SECTIONS, packModule, verifyModuleArtifact, deniedFiles, checkHowto, readHowto };