@bongos/core 1.20.41 → 1.20.42

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.20.41",
-  "core_contract": "1.20.41",
-  "source_commit": "e537f265c1269c76691d50bf25c111080be455f1",
+  "core_version": "1.20.42",
+  "core_contract": "1.20.42",
+  "source_commit": "5453ba448339c4d1ba0bfbf24b8efee9121377a6",
   "source_ref": "HEAD",
-  "built_at": "2026-10-01T00:59:19.394Z",
+  "built_at": "2026-10-01T01:33:09.710Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 563,
     "agent_docs_stubbed": 27,
-    "functional_verbatim": 2687,
+    "functional_verbatim": 2689,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3278,
-  "tree_sha256": "0c3d1503ca07445b27ce4fbdd31fa8b9e6706bc6a6643335cfc75b9f0eae9425",
+  "file_count": 3280,
+  "tree_sha256": "b8cd8e728744399dbc32d6496698b9979b49fd393057e0ea691cdf10d7f05135",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2257,7 +2257,7 @@
     {
       "path": "docs/architecture.md",
       "mode": "0000644",
-      "sha256": "e73b5883090da09febf6fcbb3b23ccc6582623eb864b385b759687c061ea4cd3"
+      "sha256": "345ab85b3665ae561a435cf1eccfa5ddb0464176153a12d85c84ddbc9f5cfc82"
     },
     {
       "path": "docs/branding-contract.md",
@@ -2787,7 +2787,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "08ec9b35f24c0267ab6b9f3f39c7eb3cefbb5e62b96ada2505e24f8928438881"
+      "sha256": "24c164c2f2b3c3adc7677b762593b08616e649824d6b08a99c588fef468433a6"
     },
     {
       "path": "docs/modules-contract.md",
@@ -9037,12 +9037,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "afc9f33e08cf7b0347f62d5ce0bc85b4368dbb0d90df1f1ef1c815a82b61521f"
+      "sha256": "892ffba9754d3e54ec9ed9a7ae0b2cfbe81719c5cef44076b0a4a226a102bd42"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "ac656023e65736d012cfa9f7dbbad627dbb4d42758ba832ffd3167a8b30a5b03"
+      "sha256": "8583d2e551ed1df355c051cf4f13e14c8d299391699e244d8a707f66008bd42b"
     },
     {
       "path": "public-docs/index.html",
@@ -9062,7 +9062,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "9eb3a2a173030074171bb3b7187b16296ad7198b79050772a690e319dd9c7d06"
+      "sha256": "a726d78b6bc53a7cbf9c94205499975b751f9ffb271162881c1966983a1c00ea"
     },
     {
       "path": "scripts/bongos-mcp.js",
@@ -9907,7 +9907,12 @@
     {
       "path": "scripts/gds/module-artifact.js",
       "mode": "0000644",
-      "sha256": "09211dcd5bae4b935b5f80a2c021a1c10a376236b1c7ea7ebc1f53b84d1ead40"
+      "sha256": "a16e9cee3135bcd14ae99f58dfbd17657610c2fc5b5c126ed052ccca49297428"
+    },
+    {
+      "path": "scripts/gds/module-assess-security.js",
+      "mode": "0000644",
+      "sha256": "0dad366dcabf453ae276e074aafa6bd71223853a31cfe005dac6f3d713e12e4a"
     },
     {
       "path": "scripts/gds/module-assess-tests.js",
@@ -11217,7 +11222,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "b1e5fefed87830633778aef9a1076002ee2e0067b8868789a2411be6b453c366"
+      "sha256": "8a5db5a4ee82ff0f0ef9f8ec1986995f6ffee351161d85320f2f91656900bb06"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -14194,6 +14199,11 @@
       "mode": "0000644",
       "sha256": "9183d78e4d195428afbee8c71746e12db2455f8529ac1223d690a7b8f7ded538"
     },
+    {
+      "path": "tests/module_assess_security.mjs",
+      "mode": "0000644",
+      "sha256": "6868f5c8ba6fbef96eab63b0726f8d3d2261aa146a0a4566c1c1929e6134a245"
+    },
     {
       "path": "tests/module_assess_tests.mjs",
       "mode": "0000644",

package/docs/architecture.md

@@ -272,7 +272,7 @@ module_assessment_scores(id, version_id, kind IN (computed|override), overall 0-
               -- and is a new row on the computed history, never an edit (D6)
 ```
 
-Signals that fill it: **Tests** — `scripts/gds/module-assess-tests.js <version id>` (task 1003791) unpacks the published tarball to `<core root>/.module-assess-<run>/<key>/` (gitignored, removed after), runs each `tests/*.mjs` in its own node process with a timeout and a credential-free environment — regardless of `isModuleEnabled`, which skips every default-off catalog module in the unit gate — and appends one `tests` row: `scored` = % of test files passing (sample_size = files), `no_data` = declares no tests, `not_scored` = tarball unreadable. The store path **refuses unless `MODULE_TEST_SANDBOX=1`** — a published module's tests run only in a separate testing environment with no secrets on disk, never on the control plane (owner, 2026-09-30). `--dir modules/<key>` is a DB-free dry run on your own checkout. Nothing calls it on publish yet (task 1003794 wires that).
+Signals that fill it: **Tests** — `scripts/gds/module-assess-tests.js <version id>` (task 1003791) unpacks the published tarball to `<core root>/.module-assess-<run>/<key>/` (gitignored, removed after), runs each `tests/*.mjs` in its own node process with a timeout and a credential-free environment — regardless of `isModuleEnabled`, which skips every default-off catalog module in the unit gate — and appends one `tests` row: `scored` = % of test files passing (sample_size = files), `no_data` = declares no tests, `not_scored` = tarball unreadable. The store path **refuses unless `MODULE_TEST_SANDBOX=1`** — a published module's tests run only in a separate testing environment with no secrets on disk, never on the control plane (owner, 2026-09-30). `--dir modules/<key>` is a DB-free dry run on your own checkout. Nothing calls it on publish yet (task 1003794 wires that). **Security** — `scripts/gds/module-assess-security.js <version id>` (task 1003792, ADR 0343 D2 gate) appends one `security` row, `passed`/`failed` only: fails on a publish-denylist file, a `module.json` dependency fetched outside the registry (an allowlist: a plain npm name with a plain semver range or dist-tag, anything else fails and is never handed to npm), or a high/critical `npm audit` advisory (resolved metadata-only with `--ignore-scripts`; nothing of the module runs, so it is control-plane safe). An audit that cannot run is `not_scored` — the gate stays shut. Floating ranges and the `maintenance` posture (ADR 0166) are noted in `detail`, never failed on.
 
 Code: `src/bongos/module-entitlements.js` (`grantEntitlement`, `recordAcquired`, `revokeEntitlement`, `checkEntitlement`, `listEntitlements`). Read routes (own-scoped, `requireBuilder`): `GET /store/entitlements`, `GET /store/modules/:key/entitlement`. Install (task 1003785) grants a free module through `POST /store/modules/:key/acquire`; the buy action (area 8) will grant a paid one.
 

package/docs/module-api-changelog.md

@@ -2739,5 +2739,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.20.39 with no explicit bump. run 36797045221. (task 1002620)
   1.20.41 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.20.40 with no explicit bump. run 36798842066. (task 1002620)
+  1.20.42 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.20.41 with no explicit bump. run 36801585300. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.20.41",
+  "version": "1.20.42",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.20.41",
+      "version": "1.20.42",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.20.41",
+  "version": "1.20.42",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -8355,5 +8355,11 @@
       "id": "1004470",
       "text": "Projects that don't do pixel art or design styling no longer carry 18 unused AI commands in every session (about a third less to load); projects that want them turn them on with one setting."
     }
+  ],
+  "1.20.42": [
+    {
+      "id": "1003792",
+      "text": "The module store can now run a security check on each module version: it fails a version that ships a secret file, pulls code from outside the official package registry, or depends on a package with a known serious vulnerabili"
+    }
   ]
 }

package/scripts/gds/module-artifact.js

@@ -216,4 +216,4 @@ async function verifyModuleArtifact(tgz, { key, maxBytes = MAX_TARBALL_BYTES, in
   return out;
 }
 
-module.exports = { MAX_TARBALL_BYTES, packModule, verifyModuleArtifact };
+module.exports = { MAX_TARBALL_BYTES, packModule, verifyModuleArtifact, deniedFiles };

package/scripts/gds/module-assess-security.js

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+// scripts/gds/module-assess-security.js — the Security part of a module's
+// assessment: a pass/fail GATE over one published store version, recorded as a
+// module_assessment_signals row (task 1003792; ADR 0343 D2; table from core_265).
+//
+// WHY a gate and not a score. ADR 0343 D2: a version that fails the security
+// check is not listed, whatever else it scores, and security is never averaged
+// in — so a module cannot buy back a vulnerability with good tests. The outcome
+// is therefore only ever passed / failed, or not_scored when the check could not
+// be completed (which is NOT a pass: a gate that cannot run must not open).
+//
+// The check reuses what the project already enforces rather than re-typing it:
+//   1. the publish denylist — module-artifact.js deniedFiles (the repo-wide
+//      matchesDeny list + credential-named files; ADR 0107 §4). Publish already
+//      refuses these; re-checking here means a rule added later still reaches
+//      versions published before it.
+//   2. dependency SOURCES — every entry in module.json `dependencies` (ADR 0138)
+//      must be a plain registry package name with a plain semver range or dist-
+//      tag. That is an ALLOWLIST (registrySpec below), deliberately stricter than
+//      a list of bad protocols: a git/http/file, aliased or GitHub-shorthand spec
+//      — or anything else unrecognised — installs code from somewhere nobody
+//      vetted, and fails the gate. (It mirrors the artifact-scan floor's grading,
+//      but a core script may not require a module's files, so it is its own
+//      small rule.) Floating ranges and wildcards are only noted.
+//   3. KNOWN VULNERABILITIES in those dependencies — only when every spec passed
+//      check 2, so nothing a module names is ever fetched from a place of its
+//      choosing and no `file:` path is ever resolved on this host. npm resolves the ranges in a
+//      throwaway directory (--package-lock-only --ignore-scripts: registry
+//      metadata only, no package code downloaded or run), then `npm audit`; any
+//      high or critical advisory fails the gate (the threshold scripts/security/
+//      dep-audit.js uses for the core, whose parser this reuses).
+// And one input that is reported, never failed on: the `maintenance` posture
+// (ADR 0166). "Undeclared", "deprecated" or "orphaned" is something a buyer
+// should see, but it is upkeep, not a vulnerability — that call is recorded in
+// the row's detail so the hall (task 1003799) can surface it.
+//
+// Nothing here executes the module's own code, so unlike module-assess-tests.js
+// this is safe to run on the control plane.
+//
+//   node scripts/gds/module-assess-security.js <store_module_versions.id>   run + record
+//   node scripts/gds/module-assess-security.js --dir modules/<key>          dry run (prints; no DB)
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFile } = require('node:child_process');
+const { deniedFiles, verifyModuleArtifact } = require('./module-artifact');
+const { extractNpmFindings } = require('../security/dep-audit');
+
+const AUDIT_TIMEOUT_MS = 120_000;
+// npm is a .cmd shim on Windows, which execFile cannot start without a shell; go
+// through cmd.exe explicitly rather than shell:true (the args are fixed constants).
+const npmCommand = (args) => (process.platform === 'win32'
+  ? ['cmd.exe', ['/d', '/s', '/c', 'npm', ...args]]
+  : ['npm', args]);
+
+// Run one npm command in `cwd`; resolve { ok, stdout, stderr, error }. Never rejects.
+function npmRun(args, cwd, { exec = execFile, timeoutMs = AUDIT_TIMEOUT_MS } = {}) {
+  return new Promise((resolve) => {
+    const [cmd, argv] = npmCommand(args);
+    exec(cmd, argv, { cwd, timeout: timeoutMs, maxBuffer: 32 * 1024 * 1024, windowsHide: true },
+      (err, stdout, stderr) => resolve({ err, stdout: String(stdout || ''), stderr: String(stderr || '') }));
+  });
+}
+
+// Audit a dependency map { name: range } for known high/critical advisories.
+// Resolves { ok: true, findings } or { ok: false, reason } when npm could not
+// resolve or audit (offline, unknown package, npm missing) — the caller treats
+// that as not_scored, never as a pass.
+async function auditDependencies(deps, { exec, timeoutMs } = {}) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'module-assess-security-'));
+  try {
+    fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ name: 'module-assess-audit', private: true, version: '0.0.0', dependencies: deps }));
+    const lock = await npmRun(['install', '--package-lock-only', '--ignore-scripts', '--no-audit', '--no-fund'], dir, { exec, timeoutMs });
+    if (lock.err || !fs.existsSync(path.join(dir, 'package-lock.json'))) {
+      return { ok: false, reason: 'npm could not resolve the declared dependencies' };
+    }
+    // npm audit exits 1 when it finds anything; the JSON on stdout is the answer either way.
+    const audit = await npmRun(['audit', '--json'], dir, { exec, timeoutMs });
+    let parsed;
+    try { parsed = JSON.parse(audit.stdout || ''); } catch { return { ok: false, reason: 'npm audit produced no readable report' }; }
+    if (parsed && parsed.error) return { ok: false, reason: 'npm audit could not reach the advisory database' };
+    return { ok: true, findings: extractNpmFindings(parsed) };
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+// npm's package-name rule (scoped or not, lowercase, no path segments).
+const NPM_NAME_RE = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+// A semver range: versions, x/* wildcards, ^ ~ comparators, hyphen and || unions,
+// prerelease/build suffixes. No ':' '/' '#' '@' — so no protocol, path, alias or ref.
+const RANGE_RE = /^[0-9A-Za-z.*^~<>=|\s+-]+$/;
+const DIST_TAGS = new Set(['latest', 'next']);
+
+// Grade one declared dependency. { ok: false } means it would install from
+// somewhere other than the public registry (or cannot be read as a registry
+// spec): the gate fails and it is never handed to npm. { ok: true, kind } is a
+// registry spec; kind names how much the registry decides at install time.
+function registrySpec(name, spec) {
+  const s = String(spec).trim();
+  if (!NPM_NAME_RE.test(name)) return { ok: false, kind: 'invalid package name' };
+  if (DIST_TAGS.has(s) || s === '*' || s === '' || /^[xX]$/.test(s)) return { ok: true, kind: 'wildcard' };
+  if (/^[a-z+]+:/i.test(s)) return { ok: false, kind: 'non-registry source' };
+  // Every whitespace/||-separated token must start with a comparator or a digit/x.
+  const tokens = s.split(/\s*\|\|\s*|\s+/).filter(Boolean);
+  if (!RANGE_RE.test(s) || !tokens.every((t) => t === '-' || /^(?:[\^~]|[<>]=?|=)?\s*[0-9xX*]/.test(t))) {
+    return { ok: false, kind: 'not a registry range' };
+  }
+  if (/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(s)) return { ok: true, kind: 'pinned' };
+  return { ok: true, kind: 'floating range' };
+}
+
+// The maintenance posture as a buyer would read it (ADR 0166).
+function maintenancePosture(moduleJson) {
+  const m = moduleJson && moduleJson.maintenance;
+  return m && typeof m.status === 'string' ? m.status : 'undeclared';
+}
+
+// The gate over one version's files ([{ path, buf }], module-relative) and its
+// parsed module.json. Returns the signal fields { outcome, score, sample_size,
+// reason, detail }. `audit` is injectable so tests need no network.
+async function assessSecurity(key, files, moduleJson, { audit = auditDependencies } = {}) {
+  const failures = [];
+  const notes = [];
+
+  const denied = deniedFiles(key, files.map((f) => f.path));
+  if (denied.length) failures.push({ check: 'denylist', files: denied });
+
+  const deps = (moduleJson && moduleJson.dependencies) || {};
+  const names = Object.keys(deps).sort();
+  const sources = [];
+  for (const name of names) {
+    const graded = registrySpec(name, deps[name]);
+    const entry = { package: name.slice(0, 214), spec: String(deps[name]).slice(0, 200), kind: graded.kind };
+    if (!graded.ok) sources.push(entry);
+    else if (graded.kind === 'wildcard') notes.push({ check: 'dependency_wildcard', ...entry });
+    else if (graded.kind === 'floating range') notes.push({ check: 'dependency_range', ...entry });
+  }
+  if (sources.length) failures.push({ check: 'dependency_source', dependencies: sources });
+
+  // Audit only an all-registry list: a failed source already fails the gate, and
+  // handing it to npm would make this host fetch (or resolve a file: path) of the
+  // module's choosing.
+  let advisories = [];
+  if (names.length && !sources.length) {
+    const a = await audit(deps);
+    if (!a.ok) {
+      return {
+        outcome: 'not_scored', score: null, sample_size: names.length,
+        reason: `the dependency audit could not run: ${a.reason}`,
+        detail: { failures, notes, maintenance: maintenancePosture(moduleJson) },
+      };
+    }
+    advisories = a.findings.map((f) => ({ package: f.package, severity: f.severity, id: f.id, summary: f.summary, fix: f.fix }));
+    if (advisories.length) failures.push({ check: 'vulnerable_dependency', advisories });
+  }
+
+  const maintenance = maintenancePosture(moduleJson);
+  if (maintenance !== 'maintained' && maintenance !== 'core-maintained') {
+    notes.push({ check: 'maintenance', status: maintenance });
+  }
+
+  const detail = { failures, notes, maintenance, dependencies_checked: names.length };
+  if (failures.length) {
+    return { outcome: 'failed', score: null, sample_size: names.length, reason: `failed: ${failures.map((f) => f.check).join(', ')}`, detail };
+  }
+  return {
+    outcome: 'passed', score: null, sample_size: names.length,
+    reason: names.length ? `passed: ${names.length} dependency(ies) from the registry, no high or critical advisory` : 'passed: no denied files and no dependencies',
+    detail,
+  };
+}
+
+// Append one Security row. Never UPDATEs (core_265 is append-only).
+async function insertSecuritySignal(versionId, s, { db }) {
+  const { rows: [row] } = await db.query(
+    `INSERT INTO module_assessment_signals (version_id, part, outcome, score, sample_size, reason, detail)
+     VALUES ($1, 'security', $2, $3, $4, $5, $6)
+     RETURNING id, version_id, part, outcome, score, sample_size, reason, measured_at`,
+    [versionId, s.outcome, s.score, s.sample_size, s.reason, JSON.stringify(s.detail || {})]);
+  return row;
+}
+
+// Read and verify one published version, run the gate, record the result. A
+// tarball that is missing or fails verification is not_scored — the gate could
+// not be run, so it stays closed.
+async function recordSecuritySignal(versionId, { db, storeDir, audit } = {}) {
+  const pool = db || require('../../src/bongos/pool').pool;
+  const { versionArtifactFile } = require('../../src/bongos/module-store');
+  const { rows: [ver] } = await pool.query(
+    'SELECT id, module_key, version, artifact_path FROM store_module_versions WHERE id = $1', [versionId]);
+  if (!ver) return { ok: false, code: 'version_not_found', message: `no store_module_versions row ${versionId}` };
+
+  let signal;
+  try {
+    const tgz = await fs.promises.readFile(versionArtifactFile(ver, storeDir ? { dir: storeDir } : {}));
+    const v = await verifyModuleArtifact(tgz, { key: ver.module_key, includeFiles: true });
+    if (v.ok) {
+      signal = await assessSecurity(ver.module_key, v.files, v.moduleJson, { audit });
+    } else if (v.code === 'denied_content') {
+      signal = { outcome: 'failed', score: null, sample_size: null, reason: 'failed: denylist', detail: { failures: [{ check: 'denylist' }] } };
+    } else {
+      signal = { outcome: 'not_scored', score: null, sample_size: null, reason: `the tarball failed verification (${v.code})`, detail: {} };
+    }
+  } catch (e) {
+    signal = { outcome: 'not_scored', score: null, sample_size: null, reason: `the check could not run (${e.code || 'error'})`, detail: {} };
+  }
+  const row = await insertSecuritySignal(ver.id, signal, { db: pool });
+  return { ok: true, version: ver, signal: row };
+}
+
+function readModuleDir(dir) {
+  const out = [];
+  const walk = (rel) => {
+    for (const e of fs.readdirSync(path.join(dir, rel), { withFileTypes: true })) {
+      if (e.name === 'node_modules' || e.name === '.git') continue;
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(r);
+      else if (e.isFile()) out.push({ path: r, buf: fs.readFileSync(path.join(dir, r)) });
+    }
+  };
+  walk('');
+  return out;
+}
+
+async function main(argv) {
+  const i = argv.indexOf('--dir');
+  if (i !== -1) {
+    const dir = path.resolve(argv[i + 1] || '');
+    const moduleJson = JSON.parse(fs.readFileSync(path.join(dir, 'module.json'), 'utf8'));
+    console.log(JSON.stringify(await assessSecurity(moduleJson.key, readModuleDir(dir), moduleJson), null, 2));
+    return 0;
+  }
+  const id = argv[0];
+  if (!/^\d+$/.test(String(id || ''))) {
+    console.error('usage: node scripts/gds/module-assess-security.js <store_module_versions.id> | --dir modules/<key>');
+    return 2;
+  }
+  const res = await recordSecuritySignal(id);
+  if (!res.ok) { console.error(res.message); return 1; }
+  const s = res.signal;
+  console.log(`${res.version.module_key} ${res.version.version}: security ${s.outcome} — ${s.reason} (signal ${s.id})`);
+  return 0;
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2)).then((code) => process.exit(code), (e) => { console.error(e.stack || e.message); process.exit(1); });
+}
+
+module.exports = { assessSecurity, auditDependencies, recordSecuritySignal, insertSecuritySignal, maintenancePosture, registrySpec };

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.20.41'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.20.42'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/tests/module_assess_security.mjs

@@ -0,0 +1,216 @@
+// tests/module_assess_security.mjs — the Security assessment gate (task 1003792, ADR 0343 D2).
+// No database and no network: the dependency audit is injected (and auditDependencies
+// is driven with a fake npm), the store row goes to a fake pg client, and the tarball
+// is a REAL packed + verified one. Pinned:
+//   - the outcome is only ever passed / failed / not_scored — never a number (D2 gate)
+//   - denied files, a non-registry dependency source and a high/critical advisory fail
+//   - an audit that cannot run is not_scored, never a pass (a gate that cannot run stays shut)
+//   - floating ranges and the maintenance posture are reported, never failed on
+//
+// Run:  node tests/module_assess_security.mjs
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+const { assessSecurity, auditDependencies, recordSecuritySignal, insertSecuritySignal, maintenancePosture, registrySpec } = require('../scripts/gds/module-assess-security.js');
+const { packModule } = require('../scripts/gds/module-artifact.js');
+const { relativeArtifactPath } = require('../src/bongos/module-store.js');
+
+const file = (p, text = '') => ({ path: p, buf: Buffer.from(text) });
+const MJ = (over = {}) => ({ key: 'weather', title: 'Weather', description: 'x', version: '1.2.0', coreVersion: '^1.0.0', contributes: {}, ...over });
+const clean = async () => ({ ok: true, findings: [] });
+const noAudit = async () => { throw new Error('the audit must not run for a module with no dependencies'); };
+
+test('no dependencies and no denied files passes, with no number and no audit', async () => {
+  const s = await assessSecurity('weather', [file('module.json'), file('index.js')], MJ(), { audit: noAudit });
+  assert.equal(s.outcome, 'passed');
+  assert.equal(s.score, null, 'the gate never carries a score (core_265: security is pass/fail only)');
+  assert.equal(s.sample_size, 0);
+});
+
+test('a credential-named file fails the gate on the publish denylist', async () => {
+  const s = await assessSecurity('weather', [file('module.json'), file('.env', 'X=1')], MJ(), { audit: noAudit });
+  assert.equal(s.outcome, 'failed');
+  assert.deepEqual(s.detail.failures.map((f) => f.check), ['denylist']);
+  assert.deepEqual(s.detail.failures[0].files, ['modules/weather/.env']);
+});
+
+test('a dependency fetched from outside the registry fails, and is never handed to npm', async () => {
+  const specs = ['git+https://example.invalid/x.git', 'https://example.invalid/x.tgz', 'github:someone/thing', 'someone/thing',
+    'npm:other@1.0.0', 'file:../../../../etc', 'link:../x', 'workspace:*', '1.0.0 || file:../x', 'git@github.com:a/b', 'rm -rf /', 'a#b'];
+  for (const spec of specs) {
+    const s = await assessSecurity('weather', [file('module.json')],
+      MJ({ dependencies: { lodash: '^4.17.21', thing: spec } }), { audit: noAudit });
+    assert.equal(s.outcome, 'failed', spec);
+    assert.equal(s.detail.failures[0].check, 'dependency_source', spec);
+    assert.deepEqual(s.detail.failures[0].dependencies.map((d) => d.package), ['thing'], spec);
+  }
+  const badName = await assessSecurity('weather', [file('module.json')], MJ({ dependencies: { '../evil': '1.0.0' } }), { audit: noAudit });
+  assert.equal(badName.outcome, 'failed');
+});
+
+test('registry specs: pinned, ranges and wildcards are allowed and told apart', () => {
+  const cases = [['1.2.3', 'pinned'], ['1.2.3-beta.1', 'pinned'], ['^14.26.4', 'floating range'], ['~1.2', 'floating range'],
+    ['>=1.0.0 <2.0.0', 'floating range'], ['1.x', 'floating range'], ['1.0.0 - 2.0.0', 'floating range'], ['^1 || ^2', 'floating range'],
+    ['*', 'wildcard'], ['latest', 'wildcard'], ['', 'wildcard']];
+  for (const [spec, kind] of cases) assert.deepEqual(registrySpec('lodash', spec), { ok: true, kind }, spec);
+  assert.equal(registrySpec('@scope/pkg', '^1.0.0').ok, true);
+});
+
+test('a wildcard is noted separately from a floating range', async () => {
+  const s = await assessSecurity('weather', [file('module.json')], MJ({ dependencies: { a: '*', b: '^1.0.0', c: '1.0.0' } }), { audit: clean });
+  assert.equal(s.outcome, 'passed');
+  assert.deepEqual(s.detail.notes.filter((n) => n.check.startsWith('dependency')).map((n) => [n.check, n.package]),
+    [['dependency_wildcard', 'a'], ['dependency_range', 'b']]);
+});
+
+test('a floating range is only noted', async () => {
+  const ok = await assessSecurity('weather', [file('module.json')], MJ({ dependencies: { lodash: '^4.17.21' } }), { audit: clean });
+  assert.equal(ok.outcome, 'passed');
+  assert.equal(ok.sample_size, 1);
+  assert.equal(ok.detail.notes.find((n) => n.check === 'dependency_range').package, 'lodash');
+});
+
+test('a high or critical advisory in a dependency fails the gate and names it', async () => {
+  const audit = async (deps) => {
+    assert.deepEqual(deps, { lodash: '^4.0.0' }, 'the audit sees exactly the declared dependencies');
+    return { ok: true, findings: [{ package: 'lodash', severity: 'critical', id: 'GHSA-x', summary: 'Prototype pollution', fix: 'lodash@4.17.21' }] };
+  };
+  const s = await assessSecurity('weather', [file('module.json')], MJ({ dependencies: { lodash: '^4.0.0' } }), { audit });
+  assert.equal(s.outcome, 'failed');
+  const v = s.detail.failures.find((f) => f.check === 'vulnerable_dependency');
+  assert.equal(v.advisories[0].id, 'GHSA-x');
+});
+
+test('an audit that cannot run is not_scored — never a pass', async () => {
+  const s = await assessSecurity('weather', [file('module.json')], MJ({ dependencies: { lodash: '^4.0.0' } }),
+    { audit: async () => ({ ok: false, reason: 'offline' }) });
+  assert.equal(s.outcome, 'not_scored');
+  assert.match(s.reason, /could not run/);
+});
+
+test('the maintenance posture is reported, never failed on', async () => {
+  assert.equal(maintenancePosture(MJ()), 'undeclared');
+  assert.equal(maintenancePosture(MJ({ maintenance: { status: 'orphaned' } })), 'orphaned');
+  for (const status of [undefined, 'deprecated', 'orphaned']) {
+    const mj = status ? MJ({ maintenance: { status, note: 'n' } }) : MJ();
+    const s = await assessSecurity('weather', [file('module.json')], mj, { audit: noAudit });
+    assert.equal(s.outcome, 'passed', String(status));
+    assert.equal(s.detail.notes.find((n) => n.check === 'maintenance').status, status || 'undeclared');
+  }
+  const kept = await assessSecurity('weather', [file('module.json')], MJ({ maintainer: 'a', maintenance: { status: 'maintained' } }), { audit: noAudit });
+  assert.equal(kept.detail.notes.length, 0, 'a maintained module has nothing to note');
+});
+
+// ---- auditDependencies: npm driven through a fake exec ----
+
+function fakeNpm({ lockOk = true, auditOut }) {
+  const calls = [];
+  const exec = (cmd, argv, opts, cb) => {
+    const args = cmd === 'cmd.exe' ? argv.slice(argv.indexOf('npm') + 1) : argv;
+    calls.push({ args, pkg: JSON.parse(fs.readFileSync(path.join(opts.cwd, 'package.json'), 'utf8')) });
+    if (args[0] === 'install') {
+      if (lockOk) fs.writeFileSync(path.join(opts.cwd, 'package-lock.json'), '{}');
+      return cb(lockOk ? null : new Error('E404'), '', '');
+    }
+    return cb(new Error('exit 1'), auditOut, '');
+  };
+  return { calls, exec };
+}
+
+test('the audit resolves metadata only (no install scripts) and reads npm audit\'s JSON', async () => {
+  const auditOut = JSON.stringify({ vulnerabilities: { lodash: { severity: 'high', via: [{ source: 1, title: 'Bad', severity: 'high', url: 'u' }], fixAvailable: true }, tiny: { severity: 'low', via: [] } } });
+  const npm = fakeNpm({ auditOut });
+  const a = await auditDependencies({ lodash: '^4.0.0' }, { exec: npm.exec });
+  assert.equal(a.ok, true);
+  assert.deepEqual(a.findings.map((f) => f.package), ['lodash'], 'only high and critical count');
+  const install = npm.calls[0].args;
+  assert.equal(install[0], 'install');
+  assert.ok(install.includes('--package-lock-only') && install.includes('--ignore-scripts'), 'no package code is downloaded or run');
+  assert.deepEqual(npm.calls[0].pkg.dependencies, { lodash: '^4.0.0' });
+});
+
+test('an unresolvable dependency or an unreadable audit is a failed audit run, not a clean one', async () => {
+  assert.equal((await auditDependencies({ nope: '^1.0.0' }, { exec: fakeNpm({ lockOk: false }).exec })).ok, false);
+  assert.equal((await auditDependencies({ a: '^1.0.0' }, { exec: fakeNpm({ auditOut: 'not json' }).exec })).ok, false);
+  assert.equal((await auditDependencies({ a: '^1.0.0' }, { exec: fakeNpm({ auditOut: JSON.stringify({ error: { code: 'ENOAUDIT' } }) }).exec })).ok, false);
+});
+
+// ---- recordSecuritySignal: tarball in, one appended row out ----
+
+function fakeDb(versionRow) {
+  const inserts = [];
+  return {
+    inserts,
+    async query(sql, params) {
+      if (/FROM store_module_versions/.test(sql)) return { rows: versionRow ? [versionRow] : [] };
+      if (/INSERT INTO module_assessment_signals/.test(sql)) {
+        assert.match(sql, /'security'/);
+        assert.doesNotMatch(sql, /UPDATE/i);
+        inserts.push(params);
+        return { rows: [{ id: 3, version_id: params[0], part: 'security', outcome: params[1] }] };
+      }
+      throw new Error(`unexpected query: ${sql}`);
+    },
+  };
+}
+
+function published(mj = MJ()) {
+  const src = fs.mkdtempSync(path.join(os.tmpdir(), 'mod-sec-src-'));
+  fs.mkdirSync(path.join(src, 'weather'), { recursive: true });
+  fs.writeFileSync(path.join(src, 'weather', 'module.json'), JSON.stringify(mj));
+  fs.writeFileSync(path.join(src, 'weather', 'index.js'), 'module.exports = {};\n');
+  const { tgz } = packModule('weather', { modulesDir: src, now: () => new Date('2026-09-30T00:00:00Z'), modeOf: () => '644' });
+  const storeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mod-sec-store-'));
+  const final = path.join(storeDir, 'weather', 'weather-1.2.0.tgz');
+  fs.mkdirSync(path.dirname(final), { recursive: true });
+  fs.writeFileSync(final, tgz);
+  return { storeDir, final, row: { id: 42, module_key: 'weather', version: '1.2.0', artifact_path: relativeArtifactPath(final, { dir: storeDir }) } };
+}
+
+test('a published version is checked from its tarball and one security row is appended', async () => {
+  const { storeDir, row } = published(MJ({ dependencies: { lodash: '^4.17.21' } }));
+  const db = fakeDb(row);
+  let audited = null;
+  const res = await recordSecuritySignal(42, { db, storeDir, audit: async (d) => { audited = d; return { ok: true, findings: [] }; } });
+  assert.equal(res.ok, true);
+  assert.deepEqual(audited, { lodash: '^4.17.21' }, 'the dependencies come from the published module.json');
+  const [versionId, outcome, score, sample] = db.inserts[0];
+  assert.deepEqual([versionId, outcome, score, sample], [42, 'passed', null, 1]);
+});
+
+test('a missing or tampered tarball is not_scored, and an unknown version writes nothing', async () => {
+  const { storeDir, final, row } = published();
+  fs.writeFileSync(final, 'junk');
+  const db = fakeDb(row);
+  await recordSecuritySignal(42, { db, storeDir, audit: noAudit });
+  assert.equal(db.inserts[0][1], 'not_scored');
+  assert.doesNotMatch(db.inserts[0][4], /[\\/]/, 'no local path in the stored reason');
+
+  const none = fakeDb(null);
+  const res = await recordSecuritySignal(9, { db: none, audit: noAudit });
+  assert.equal(res.code, 'version_not_found');
+  assert.equal(none.inserts.length, 0);
+});
+
+test('insertSecuritySignal writes the security part with no score', async () => {
+  const seen = [];
+  await insertSecuritySignal(5, { outcome: 'failed', score: null, sample_size: 2, reason: 'r', detail: { failures: [] } },
+    { db: { async query(sql, params) { seen.push(params); return { rows: [{}] }; } } });
+  assert.deepEqual(seen[0], [5, 'failed', null, 2, 'r', '{"failures":[]}']);
+});
+
+test('a core script never requires a module file (the one-way rule)', () => {
+  const src = fs.readFileSync(new URL('../scripts/gds/module-assess-security.js', import.meta.url), 'utf8').replace(/\/\/.*$/gm, '');
+  assert.doesNotMatch(src, /require\([^)]*modules\//);
+});
+
+test('the gate never runs the module\'s own code', () => {
+  const src = fs.readFileSync(new URL('../scripts/gds/module-assess-security.js', import.meta.url), 'utf8').replace(/\/\/.*$/gm, '');
+  assert.doesNotMatch(src, /process\.execPath|require\(\s*path\.join|import\(/, 'no node process or require over module files');
+});