@bongos/core 1.20.45 → 1.20.47

package/tests/module_store_howto.mjs

@@ -0,0 +1,244 @@
+// tests/module_store_howto.mjs — the store shows each version's how-to as a page
+// (task 1004366, ADR 0347 D1/D3). Drives the real GET
+// /store/modules/:key/versions/:version/howto handler off the real router against
+// REAL packed tarballs in a temp store dir (no port, no real DB — pool.js is replaced
+// in the require cache, the module_store_publish_route.mjs harness). Then the page
+// half: the author's markdown renders through the hall's one escaping reader, the
+// install message links the page, and the Modules list links an installed version.
+//
+// Run:  node tests/module_store_howto.mjs
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const STORE = fs.mkdtempSync(path.join(os.tmpdir(), 'mod-store-howto-'));
+process.env.MODULE_STORE_DIR = STORE;
+
+// The registry and the entitlements, as the fake pool sees them.
+const state = { modules: {}, versions: [], held: new Set() };
+const pool = {
+  async query(sql, params = []) {
+    if (/FROM store_modules WHERE module_key = \$1/.test(sql)) {
+      const m = state.modules[params[0]]; return { rows: m ? [m] : [] };
+    }
+    if (/FROM store_module_versions WHERE module_key = \$1 AND version = \$2/.test(sql)) {
+      return { rows: state.versions.filter((v) => v.module_key === params[0] && v.version === params[1]) };
+    }
+    if (/FROM store_module_versions WHERE module_key = ANY/.test(sql)) {
+      return { rows: state.versions.filter((v) => params[0].includes(v.module_key)) };
+    }
+    if (/FROM module_entitlements/.test(sql)) {
+      const k = `${params[0]}|${params[2]}`;
+      return { rows: state.held.has(k) ? [{ module_key: params[0], holder_kind: params[1], holder_ref: params[2], revoked_at: null }] : [] };
+    }
+    return { rows: [] };
+  },
+};
+const poolPath = require.resolve('../src/bongos/pool.js');
+require.cache[poolPath] = { id: poolPath, filename: poolPath, loaded: true, exports: { pool: { connect: async () => ({ ...pool, release() {} }), query: pool.query } } };
+
+const buildModulesRouter = require('../src/bongos/routes/modules.js');
+const artifact = require('../scripts/gds/module-artifact.js');
+const { cmdInstall } = require('../scripts/gds/module.js');
+
+const sections = (tag) => artifact.HOWTO_SECTIONS.map((h) => `## ${h}\n${tag} — ${h}.\n`).join('\n');
+
+// Pack a real version of "weather" and put it in the store the way publish does.
+function publish(version, { howto, manifest = {}, status = 'listed' } = {}) {
+  const src = fs.mkdtempSync(path.join(os.tmpdir(), 'mod-howto-src-'));
+  const dir = path.join(src, 'weather');
+  fs.mkdirSync(dir);
+  fs.writeFileSync(path.join(dir, 'module.json'), JSON.stringify({
+    key: 'weather', title: 'Weather', description: 'd', version, coreVersion: '^1.0.0', contributes: {}, ...manifest,
+  }));
+  if (howto != null) fs.writeFileSync(path.join(dir, 'HOWTO.md'), howto);
+  const { tgz } = artifact.packModule('weather', { modulesDir: src, modeOf: () => '644' });
+  fs.mkdirSync(path.join(STORE, 'weather'), { recursive: true });
+  fs.writeFileSync(path.join(STORE, 'weather', `weather-${version}.tgz`), tgz);
+  state.modules.weather = { module_key: 'weather', title: 'Weather', author_id: 42, status };
+  state.versions.push({ id: state.versions.length + 1, module_key: 'weather', version, tarball_sha256: require('node:crypto').createHash('sha256').update(tgz).digest('hex'), artifact_path: `weather/weather-${version}.tgz`, published_at: '2026-09-30T00:00:00Z' });
+  return tgz;
+}
+
+function handlerFor(router, method, p) {
+  const layer = router.stack.find((l) => l.route && l.route.path === p && l.route.methods[method]);
+  assert.ok(layer, `no ${method.toUpperCase()} ${p} on the router`);
+  const stack = layer.route.stack;
+  return { handle: stack[stack.length - 1].handle, names: stack.map((s) => s.name) };
+}
+
+async function invoke(handle, req) {
+  const res = {
+    statusCode: 200, body: undefined, headers: {},
+    json(b) { this.body = b; return this; },
+    status(c) { this.statusCode = c; return this; },
+    set(k, v) { this.headers[k] = v; return this; },
+    fail(code, opts) { this.statusCode = opts.status; this.body = { error: code, ...opts }; return this; },
+  };
+  let nextErr = null;
+  await handle(req, res, (err) => { nextErr = err; });
+  if (nextErr) throw nextErr;
+  return res;
+}
+
+const router = buildModulesRouter();
+const howtoRoute = handlerFor(router, 'get', '/store/modules/:key/versions/:version/howto');
+const read = (version, builderId = 7) => invoke(howtoRoute.handle, { params: { key: 'weather', version }, builder: { id: builderId } });
+
+publish('0.9.0', { howto: null }); // published before the gate: no how-to
+publish('1.0.0', { howto: sections('one') });
+publish('2.0.0', { howto: sections('two'), manifest: { howto: { artifactUrl: 'https://claude.ai/artifact/abc' } } });
+
+test('the route is open to any signed-in builder: requireBuilder and no permission gate', () => {
+  assert.deepEqual(howtoRoute.names.slice(0, 1), ['requireBuilder']);
+  assert.equal(howtoRoute.names.length, 2, 'builder gate, then the handler — no entitlement or rank gate for a listed module');
+});
+
+test('the page shows the version asked for, from its own tarball — not the latest', async () => {
+  const one = await read('1.0.0');
+  assert.equal(one.statusCode, 200, JSON.stringify(one.body));
+  assert.match(one.body.markdown, /one — What it does/);
+  assert.doesNotMatch(one.body.markdown, /two —/);
+  assert.equal(one.body.version, '1.0.0');
+  assert.equal(one.body.artifact_url, null);
+  const two = await read('2.0.0');
+  assert.match(two.body.markdown, /two — What it does/);
+  assert.equal(two.body.artifact_url, 'https://claude.ai/artifact/abc', 'the optional Claude page travels with its version');
+  assert.equal(one.headers['Cache-Control'], 'no-store');
+});
+
+test('a version published before the gate answers 404 howto_missing, not an empty page', async () => {
+  const r = await read('0.9.0');
+  assert.equal(r.statusCode, 404);
+  assert.equal(r.body.error, 'howto_missing');
+});
+
+test('an unknown version, a bad key and a loose version are refused', async () => {
+  assert.equal((await read('3.0.0')).body.error, 'version_not_found');
+  assert.equal((await invoke(howtoRoute.handle, { params: { key: 'Bad_Key', version: '1.0.0' }, builder: { id: 7 } })).statusCode, 400);
+  assert.equal((await read('^1.0.0')).statusCode, 400);
+});
+
+test('a checked how-to is cached: the second view reads no file', async () => {
+  const fresh = handlerFor(buildModulesRouter(), 'get', '/store/modules/:key/versions/:version/howto');
+  const view = () => invoke(fresh.handle, { params: { key: 'weather', version: '2.0.0' }, builder: { id: 7 } });
+  assert.equal((await view()).statusCode, 200);
+  const file = path.join(STORE, 'weather', 'weather-2.0.0.tgz');
+  fs.renameSync(file, file + '.away');
+  try {
+    const again = await view();
+    assert.equal(again.statusCode, 200, 'served from the cache, so the moved file is never read');
+    assert.match(again.body.markdown, /two — What it does/);
+  } finally { fs.renameSync(file + '.away', file); }
+});
+
+test('a stored tarball that no longer matches its hashes is never shown', async () => {
+  const file = path.join(STORE, 'weather', 'weather-1.0.0.tgz');
+  const good = fs.readFileSync(file);
+  const { readTar, buildTar } = require('../scripts/gds/artifact-format.js');
+  const entries = readTar(good);
+  entries.find((e) => e.name.endsWith('HOWTO.md')).buf = Buffer.from('## What it does\nswapped\n');
+  fs.writeFileSync(file, buildTar(entries));
+  try {
+    // A fresh router, so nothing is cached yet: the first read of a version checks it.
+    const fresh = handlerFor(buildModulesRouter(), 'get', '/store/modules/:key/versions/:version/howto');
+    const r = await invoke(fresh.handle, { params: { key: 'weather', version: '1.0.0' }, builder: { id: 7 } });
+    assert.equal(r.statusCode, 500);
+    assert.equal(r.body.error, 'artifact_invalid');
+  } finally { fs.writeFileSync(file, good); }
+});
+
+test('a delisted module\'s how-to still reads for people who hold it, and only for them (ADR 0338 D2)', async () => {
+  state.modules.weather.status = 'delisted';
+  try {
+    const stranger = await read('1.0.0', 7);
+    assert.equal(stranger.statusCode, 409);
+    assert.equal(stranger.body.error, 'module_delisted');
+    state.held.add('weather|8');
+    const holder = await read('1.0.0', 8);
+    assert.equal(holder.statusCode, 200, JSON.stringify(holder.body));
+    assert.equal(holder.body.delisted, true);
+    assert.match(holder.body.markdown, /one — What it does/);
+  } finally { state.modules.weather.status = 'listed'; state.held.clear(); }
+});
+
+// ---- the page: the author's markdown is untrusted input ----
+
+function loadReader() {
+  const ctx = { window: {}, location: { href: 'https://builders.example.com/builders/modules', hostname: 'builders.example.com' }, URL };
+  vm.createContext(ctx);
+  vm.runInContext(fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/md-reader.js'), 'utf8'), ctx);
+  return ctx.window.OTBMdReader;
+}
+const MODULES_JS = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/modules.js'), 'utf8');
+// The page's own link rule, lifted out of modules.js so the test runs the real one.
+const linkRule = MODULES_JS.match(/function howtoLinkHref\(href\) \{\n\s*return (.+);\n\s*\}/);
+const howtoLinkHref = new Function('href', `return ${linkRule[1]};`);
+
+test('author HTML renders as text: no tag, no handler and no script link survives', () => {
+  const MD = loadReader();
+  const evil = [
+    '## What it does',
+    '<script>alert(1)</script> <img src=x onerror=alert(2)>',
+    '[click](javascript:alert(3)) [rel](../secrets.md) [ok](https://example.org/a)',
+    '```', '</code><script>alert(4)</script>', '```',
+  ].join('\n');
+  const html = MD.parseMarkdown(evil, howtoLinkHref).html;
+  // Every tag in the output is one the reader writes itself; the author's are text.
+  const tags = html.match(/<\/?([a-z0-9]+)/gi).map((t) => t.replace(/[</]/g, '').toLowerCase());
+  assert.deepEqual([...new Set(tags)].sort(), ['a', 'code', 'h2', 'p', 'pre']);
+  assert.doesNotMatch(html, /href="javascript:/i);
+  assert.match(html, /&lt;script&gt;alert\(1\)&lt;\/script&gt;/);
+  assert.match(html, /<a href="https:\/\/example\.org\/a"/, 'an absolute https link still works');
+  assert.doesNotMatch(html, /href="\.\.\/secrets\.md"/, 'a relative repo path is text, not a link');
+});
+
+test('modules.js renders the how-to only through the escaping reader, and checks the Claude link', () => {
+  assert.match(MODULES_JS, /OTBMdReader\.parseMarkdown\(md, howtoLinkHref\)/);
+  assert.doesNotMatch(MODULES_JS, /innerHTML\s*=\s*[^;]*body\.markdown/, 'the raw markdown is never assigned as HTML');
+  assert.match(MODULES_JS, /isClaudeArtifactUrl\(body\.artifact_url\)/);
+  assert.match(MODULES_JS, /window\.print\(\)/, 'Save as PDF is the browser\'s own print');
+  const html = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/modules.html'), 'utf8');
+  assert.match(html, /md-reader\.js/);
+  assert.match(html, /Also available as a Claude page/);
+  assert.match(fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/modules.css'), 'utf8'), /@media print/);
+});
+
+// ---- the two links to the page ----
+
+test('the Modules list links an on-disk module that is a published store version', async () => {
+  const list = handlerFor(router, 'get', '/modules');
+  const res = await invoke(list.handle, { builder: { id: 7 } });
+  assert.equal(res.statusCode, 200);
+  for (const m of res.body.modules) {
+    assert.equal(m.store_howto, null, `${m.key} is not a store version, so it carries no how-to link`);
+  }
+});
+
+test('install prints the how-to page link when the version ships one, and not otherwise', async () => {
+  const describe = (v) => ({ ok: true, module_key: 'weather', version: v.version, core_version: v.coreVersion, tarball_sha256: v.tarballSha256, tree_sha256: v.treeSha256, tarball_bytes: v.bytes });
+  async function run(version) {
+    const tgz = fs.readFileSync(path.join(STORE, 'weather', `weather-${version}.tgz`));
+    const v = await artifact.verifyModuleArtifact(tgz, { key: 'weather' });
+    const request = async (method, urlPath) => {
+      if (urlPath.endsWith('/acquire')) return { ok: true, status: 200, data: describe(v) };
+      if (urlPath.endsWith('/tarball')) return { ok: true, status: 200, buf: tgz };
+      return { ok: true, status: 200, data: { ok: true } };
+    };
+    request.apiBase = 'https://example.com/';
+    const out = [];
+    const code = await cmdInstall(['weather'], { log: (m) => out.push(m), errlog: (m) => out.push(m), modulesDir: fs.mkdtempSync(path.join(os.tmpdir(), 'mod-howto-dest-')), roots: [], request, core: '1.19.0' });
+    assert.equal(code, 0, out.join('\n'));
+    return out.join('\n');
+  }
+  assert.match(await run('1.0.0'), /How to use it: https:\/\/example\.com\/builders\/modules\?howto=weather&version=1\.0\.0/);
+  assert.doesNotMatch(await run('0.9.0'), /How to use it/);
+});