@bongos/core 1.19.954 → 1.19.956

package/tests/provisioning_env_manifest.mjs

@@ -0,0 +1,435 @@
+// tests/provisioning_env_manifest.mjs
+//
+// The project ENV VAR MANIFEST — names and purposes, never values (task 1004062,
+// ADR 0323 decision 6).
+//
+// THE LOAD-BEARING ASSERTION IS AN ABSENCE. The task's own done-when is "no route in this
+// work accepts, stores, logs or returns a secret value, and a test asserts the value field
+// does not exist", so this file proves the negative three ways rather than once: the
+// migration declares no value column, the row projection carries no value key, and a
+// caller who POSTs one is REFUSED — loudly, with nothing written. The third is the one
+// that matters most: a silent strip would hand the caller a 201 and leave them believing
+// this platform had taken custody of a secret, which is worse than storing it, because
+// they may then delete it from the place that really holds it.
+//
+// The "secret" in these fixtures is a marker word, deliberately NOT credential-shaped:
+// the repo's secret gate refuses a realistic connection string in any path, and a test
+// that needs a real-looking one to be meaningful would be testing the wrong thing. What
+// matters is that the marker never appears in a response body, and a marker proves that
+// as well as a plausible URL would.
+//
+// Also pinned: the name rule with its reason-giving refusals, environment normalisation
+// (absent means everywhere, and an unknown environment is refused rather than filtered),
+// re-declaring a name as an EDIT not a duplicate, and the own-or-archon 404 that keeps a
+// guessed id from confirming another project's manifest.
+//
+// DB-free: the pool is a fake, data access is stubbed on the cached module objects, auth
+// is faked — the tests/provisioning_disconnect.mjs harness.
+//
+// Run:  node tests/provisioning_env_manifest.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import http from 'node:http';
+
+const require = createRequire(import.meta.url);
+const provisioning = require('../modules/provisioning/provisioning.js');
+const envManifest = require('../modules/provisioning/env-manifest.js');
+
+let passed = 0, failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+async function ta(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// The marker a "value" carries in these fixtures. If it ever appears in a response, a
+// value reached a surface it must never reach.
+const MARKER = 'VALUE-MUST-NOT-APPEAR';
+
+const MIGRATION = readFileSync(new URL('../modules/provisioning/migrations/provisioning_023_env_manifest.sql', import.meta.url), 'utf8');
+
+console.log('no value, anywhere — the schema:');
+
+t('the migration declares NO value column, under any spelling', () => {
+  // Read the CREATE TABLE body only, so the header prose (which necessarily talks ABOUT
+  // values) cannot make this pass or fail. Comment lines are dropped for the same reason.
+  const body = /CREATE TABLE IF NOT EXISTS provisioning_env_vars \(([\s\S]*?)\n\);/.exec(MIGRATION);
+  assert.ok(body, 'the table is declared');
+  const columns = body[1]
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l && !l.startsWith('--'))
+    .map((l) => l.split(/\s+/)[0]);
+  assert.ok(columns.includes('name'), `sanity: the columns were parsed (${columns.join(', ')})`);
+  for (const forbidden of envManifest.VALUE_FIELDS) {
+    assert.ok(!columns.includes(forbidden),
+      `provisioning_env_vars must not have a "${forbidden}" column — the deployment platform is the system of record for values (ADR 0323 D6). Columns: ${columns.join(', ')}`);
+  }
+});
+
+t('the migration self-registers and touches no core table', () => {
+  assert.match(MIGRATION, /CREATE TABLE IF NOT EXISTS provisioning_env_vars/, 'additive create');
+  assert.doesNotMatch(MIGRATION, /ALTER TABLE (?!provisioning_)/, 'no non-provisioning table is altered (ADR 0083 §5)');
+  assert.match(MIGRATION, /UNIQUE INDEX IF NOT EXISTS ux_provisioning_env_vars_instance_name/, 'one declaration per name per project');
+});
+
+t('the environments CHECK admits exactly the known set, and the code agrees with it', () => {
+  const m = /CHECK \(environments <@ ARRAY\[([^\]]*)\]/.exec(MIGRATION);
+  assert.ok(m, 'the CHECK is a containment test, so any subset is legal');
+  const inSql = m[1].split(',').map((s) => s.trim().replace(/^'|'$/g, '')).sort();
+  assert.deepEqual(inSql, [...envManifest.ENVIRONMENTS].sort(),
+    'the migration and ENVIRONMENTS carry the same set — a drift here silently refuses a legal row at write time');
+});
+
+console.log('\nno value, anywhere — the projection:');
+
+t('envVarRow returns no value key even when the row it is handed carries one', () => {
+  // The projection NAMES its columns rather than spreading the row, so a value column
+  // that somehow reached the table still could not leave through it. Handing it a poisoned
+  // row is how that is proved rather than asserted.
+  const out = envManifest.envVarRow({
+    id: 1, instance_id: 2, name: 'DATABASE_URL', description: 'the connection string',
+    environments: ['production'], required: true, created_at: 'now', updated_at: 'now',
+    value: MARKER, secret: MARKER,
+  });
+  for (const forbidden of envManifest.VALUE_FIELDS) {
+    assert.ok(!(forbidden in out), `the projection leaked "${forbidden}"`);
+  }
+  assert.equal(JSON.stringify(out).includes(MARKER), false, 'and no value rides along inside another field');
+  assert.deepEqual(Object.keys(out).sort(),
+    ['created_at', 'description', 'environments', 'id', 'instance_id', 'name', 'required', 'updated_at']);
+});
+
+t('rejectsValueField catches every spelling, and is silent on a clean body', () => {
+  assert.equal(envManifest.rejectsValueField({ name: 'PORT', description: 'the port' }), null);
+  assert.equal(envManifest.rejectsValueField(null), null);
+  for (const f of envManifest.VALUE_FIELDS) {
+    const r = envManifest.rejectsValueField({ name: 'PORT', [f]: MARKER });
+    assert.ok(r, `"${f}" must be refused`);
+    assert.equal(r.code, 'value_not_accepted');
+    assert.match(r.message, /never values/i, 'the message says what the platform does instead');
+    assert.ok(!r.message.includes(MARKER), 'and the refusal does not echo the value back');
+  }
+});
+
+console.log('\nthe name rule:');
+
+t('valid names are accepted and the refusals say WHY', () => {
+  for (const ok of ['DATABASE_URL', 'PORT', '_INTERNAL', 'npm_config_registry', 'A1']) {
+    assert.ok(envManifest.isValidEnvName(ok), `${ok} is a legal name`);
+    assert.equal(envManifest.envNameRefusal(ok), null);
+  }
+  assert.match(envManifest.envNameRefusal(''), /needs a name/);
+  assert.match(envManifest.envNameRefusal('MY VAR'), /space/, 'a space is named as the problem');
+  assert.match(envManifest.envNameRefusal('1ST_RUN'), /starts with a digit/);
+  assert.match(envManifest.envNameRefusal('MY-VAR'), /letters, digits and underscores/);
+  assert.match(envManifest.envNameRefusal('X'.repeat(envManifest.ENV_NAME_MAX + 1)), /the limit is/);
+  for (const bad of ['MY VAR', '1ST_RUN', 'MY-VAR', '', 'a'.repeat(129)]) {
+    assert.ok(!envManifest.isValidEnvName(bad), `${JSON.stringify(bad)} is not a legal name`);
+  }
+});
+
+console.log('\nenvironments:');
+
+t('absent or empty means EVERYWHERE, stored explicitly and in canonical order', () => {
+  assert.deepEqual(envManifest.normalizeEnvironments(undefined), ['production', 'preview', 'development']);
+  assert.deepEqual(envManifest.normalizeEnvironments(null), ['production', 'preview', 'development']);
+  assert.deepEqual(envManifest.normalizeEnvironments([]), ['production', 'preview', 'development']);
+  // Canonical order, so two callers naming the same set produce equal rows and a diff of
+  // two manifests is about content rather than ordering.
+  assert.deepEqual(envManifest.normalizeEnvironments(['development', 'production']), ['production', 'development']);
+  assert.deepEqual(envManifest.normalizeEnvironments(['PRODUCTION', ' production ']), ['production'], 'case and whitespace folded, duplicates collapsed');
+  assert.deepEqual(envManifest.normalizeEnvironments('preview'), ['preview'], 'a bare string is accepted as a one-element list');
+});
+
+t('an unknown environment is REPORTED, not quietly filtered', () => {
+  assert.deepEqual(envManifest.unknownEnvironments(['production', 'staging']), ['staging']);
+  assert.deepEqual(envManifest.unknownEnvironments(['production']), []);
+  assert.deepEqual(envManifest.unknownEnvironments(undefined), []);
+  // The two functions disagree on purpose: normalize DROPS the unknown (the backstop) and
+  // the route refuses on unknownEnvironments (the answer). Keeping the remainder silently
+  // would tell an owner their variable applies somewhere it does not.
+  assert.deepEqual(envManifest.normalizeEnvironments(['production', 'staging']), ['production']);
+});
+
+console.log('\nstorage:');
+
+// A fake pool that records the SQL and answers the shapes env-manifest.js expects.
+function fakeDb({ rows = [], rowCount = 1, inserted = true } = {}) {
+  const calls = [];
+  return {
+    calls,
+    query: async (sql, params) => {
+      calls.push({ sql: sql.replace(/\s+/g, ' ').trim(), params });
+      if (/^SELECT \* FROM provisioning_env_vars/.test(sql.trim())) return { rows };
+      if (/INSERT INTO provisioning_env_vars/.test(sql)) {
+        return { rows: [{ id: 5, instance_id: params[0], name: params[1], description: params[2], environments: params[3], required: params[4], created_at: 'c', updated_at: 'u', inserted }] };
+      }
+      if (/UPDATE provisioning_env_vars/.test(sql)) {
+        return { rows: rows.length ? [rows[0]] : [] };
+      }
+      if (/DELETE FROM provisioning_env_vars/.test(sql)) return { rowCount, rows: [] };
+      throw new Error(`unexpected SQL: ${sql}`);
+    },
+  };
+}
+
+await ta('declaring stores the name, the sentence, the environments and required — and nothing else', async () => {
+  const db = fakeDb();
+  const { row, created } = await envManifest.declareEnvVar(db, {
+    instanceId: 40, name: '  DATABASE_URL  ', description: 'Postgres connection string', environments: ['production'],
+  });
+  assert.equal(created, true);
+  assert.equal(row.name, 'DATABASE_URL', 'the name is trimmed');
+  assert.equal(row.required, true, 'required is the default — an omission stays visible on a setup checklist');
+  assert.deepEqual(row.environments, ['production']);
+  assert.equal(db.calls.length, 1);
+  // Five parameters: instance, name, description, environments, required. A sixth would
+  // be the thing this table exists to not have.
+  assert.equal(db.calls[0].params.length, 5, `the insert binds exactly the manifest columns: ${JSON.stringify(db.calls[0].params)}`);
+  assert.match(db.calls[0].sql, /ON CONFLICT \(instance_id, name\) DO UPDATE/, 're-declaring is an edit, not a duplicate row');
+});
+
+await ta('re-declaring an existing name reports created:false — the same declaration, edited', async () => {
+  const db = fakeDb({ inserted: false });
+  const { created } = await envManifest.declareEnvVar(db, { instanceId: 40, name: 'PORT' });
+  assert.equal(created, false);
+});
+
+await ta('a patch touches ONLY the fields it names, and is scoped to the project', async () => {
+  const db = fakeDb({ rows: [{ id: 5, instance_id: 40, name: 'PORT', description: 'new text', environments: ['production'], required: false, created_at: 'c', updated_at: 'u' }] });
+  const row = await envManifest.updateEnvVar(db, 40, '5', { description: 'new text' });
+  assert.equal(row.description, 'new text');
+  const sql = db.calls[0].sql;
+  assert.match(sql, /WHERE instance_id = \$1 AND id = \$2/, 'a guessed id cannot reach another project');
+  assert.match(sql, /SET updated_at = now\(\), description = \$3/, 'environments and required are left alone');
+  assert.doesNotMatch(sql, /required =/);
+});
+
+await ta('an explicit null description erases it; an omitted one does not', async () => {
+  const db = fakeDb({ rows: [{ id: 5, instance_id: 40, name: 'PORT', description: null, environments: [], required: true }] });
+  await envManifest.updateEnvVar(db, 40, '5', { description: null });
+  assert.equal(db.calls[0].params[2], null, 'null is the un-answer, not a dropped field');
+});
+
+await ta('removing is scoped to the project too, and reports whether a row went', async () => {
+  const gone = fakeDb({ rowCount: 1 });
+  assert.equal(await envManifest.removeEnvVar(gone, 40, '5'), true);
+  assert.match(gone.calls[0].sql, /WHERE instance_id = \$1 AND id = \$2/);
+  const missing = fakeDb({ rowCount: 0 });
+  assert.equal(await envManifest.removeEnvVar(missing, 40, '999'), false);
+});
+
+await ta('the list is name-ordered, so two reads of an unchanged manifest are identical', async () => {
+  const db = fakeDb({ rows: [] });
+  await envManifest.listEnvVars(db, 40);
+  assert.match(db.calls[0].sql, /ORDER BY name ASC/);
+});
+
+console.log('\nthe routes:');
+
+let instance = null;
+provisioning.getInstanceById = async (_db, id) => (instance ? { ...instance, id } : null);
+
+const api = require('../src/module-api.js');
+let builder = { id: 7, rank: 'xenos', github_login: 'owner' };
+api.requireBuilder = (req, _res, next) => { req.builder = builder; next(); };
+
+let store = [];
+envManifest.listEnvVars = async () => store;
+envManifest.declareEnvVar = async (_db, d) => {
+  const row = envManifest.envVarRow({
+    id: 5, instance_id: 40, name: String(d.name).trim(), description: d.description ?? null,
+    environments: envManifest.normalizeEnvironments(d.environments), required: d.required !== false,
+    created_at: 'c', updated_at: 'u',
+  });
+  store = [row];
+  return { row, created: true };
+};
+envManifest.updateEnvVar = async (_db, _inst, id) => (id === '5' ? store[0] || null : null);
+envManifest.removeEnvVar = async (_db, _inst, id) => id === '5';
+
+const express = require('express');
+const envRoutes = require('../modules/provisioning/routes/env-manifest.js');
+const app = express();
+app.use(express.json());
+app.use((_req, res, next) => {
+  res.fail = (code, opts, details) => {
+    const status = typeof opts === 'number' ? opts : (opts && opts.status) || 400;
+    const extra = typeof opts === 'object' ? opts : {};
+    res.status(status).json({ error: { code, message: extra.message || code, details: details || extra.details } });
+  };
+  next();
+});
+app.use('/api/bongos', envRoutes());
+const server = app.listen(0);
+await new Promise((r) => server.once('listening', r));
+const base = `http://127.0.0.1:${server.address().port}/api/bongos`;
+
+function call(method, path, body) {
+  return new Promise((resolve, reject) => {
+    const payload = body === undefined ? null : JSON.stringify(body);
+    const headers = payload ? { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) } : {};
+    const req = http.request(`${base}${path}`, { method, headers }, (res) => {
+      let d = '';
+      res.on('data', (c) => { d += c; });
+      res.on('end', () => { let j = null; try { j = JSON.parse(d); } catch { /* non-JSON */ } resolve({ status: res.statusCode, body: j, raw: d }); });
+    });
+    req.on('error', reject);
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
+const URL_ = '/provisioning/instances/40/env-manifest';
+function reset({ inst = { owner_builder_id: 7, slug: 'lantern', status: 'active', hosting_shape: 'byo-host' }, who = { id: 7, rank: 'xenos', github_login: 'owner' } } = {}) {
+  instance = inst; builder = who; store = [];
+}
+
+await ta('the owner declares a variable and reads it back, values_held:false on both', async () => {
+  reset();
+  const created = await call('POST', URL_, { name: 'DATABASE_URL', description: 'Postgres connection string', environments: ['production'] });
+  assert.equal(created.status, 201, created.raw);
+  assert.equal(created.body.env_var.name, 'DATABASE_URL');
+  assert.equal(created.body.values_held, false);
+  const read = await call('GET', URL_);
+  assert.equal(read.status, 200, read.raw);
+  assert.equal(read.body.env_vars.length, 1);
+  assert.equal(read.body.values_held, false, 'a reader must not go looking for a value field and think the API is broken');
+  assert.deepEqual(read.body.environments, envManifest.ENVIRONMENTS, 'the vocabulary ships with the list');
+});
+
+// THE done-when assertion, at the boundary.
+for (const field of ['value', 'secret', 'secret_value']) {
+  await ta(`POSTing a "${field}" is REFUSED with nothing written, and the value is not echoed back`, async () => {
+    reset();
+    const res = await call('POST', URL_, { name: 'DATABASE_URL', [field]: MARKER });
+    assert.equal(res.status, 400, res.raw);
+    assert.equal(res.body.error.code, 'value_not_accepted');
+    assert.ok(!res.raw.includes(MARKER), 'the refusal does not repeat the value into a response body or a log');
+    assert.deepEqual(store, [], 'and nothing was stored — a 201 here would have the caller believe we hold it');
+  });
+}
+
+await ta('a value sent alongside a BAD name is still answered as the value problem first', async () => {
+  reset();
+  const res = await call('POST', URL_, { name: '1BAD NAME', value: MARKER });
+  assert.equal(res.status, 400, res.raw);
+  assert.equal(res.body.error.code, 'value_not_accepted', 'the value is the urgent half of that mistake');
+});
+
+await ta('PATCHing a value is refused the same way', async () => {
+  reset();
+  const res = await call('PATCH', `${URL_}/5`, { value: MARKER });
+  assert.equal(res.status, 400, res.raw);
+  assert.equal(res.body.error.code, 'value_not_accepted');
+});
+
+await ta('an unknown environment is refused and NAMES both sets', async () => {
+  reset();
+  const res = await call('POST', URL_, { name: 'PORT', environments: ['production', 'staging'] });
+  assert.equal(res.status, 400, res.raw);
+  assert.equal(res.body.error.code, 'bad_environment');
+  assert.deepEqual(res.body.error.details.unknown, ['staging']);
+  assert.deepEqual(res.body.error.details.known, envManifest.ENVIRONMENTS);
+});
+
+await ta('a malformed name is refused with the rule, not a generic 400', async () => {
+  reset();
+  const res = await call('POST', URL_, { name: 'MY VAR' });
+  assert.equal(res.status, 400, res.raw);
+  assert.equal(res.body.error.code, 'bad_env_name');
+  assert.match(res.body.error.message, /space/);
+});
+
+await ta("another builder's project is a 404, not a 403 — a guessed id confirms nothing", async () => {
+  reset({ who: { id: 99, rank: 'xenos', github_login: 'stranger' } });
+  for (const [m, p] of [['GET', URL_], ['POST', URL_], ['PATCH', `${URL_}/5`], ['DELETE', `${URL_}/5`]]) {
+    const res = await call(m, p, m === 'GET' || m === 'DELETE' ? undefined : { name: 'PORT' });
+    assert.equal(res.status, 404, `${m} ${p} → ${res.raw}`);
+    assert.equal(res.body.error.code, 'instance_not_found');
+  }
+});
+
+await ta('an archon may read and edit any project (fleet support)', async () => {
+  reset({ who: { id: 99, rank: 'archon', github_login: 'archon' } });
+  const res = await call('GET', URL_);
+  assert.equal(res.status, 200, res.raw);
+});
+
+await ta('a missing project is the same 404', async () => {
+  reset({ inst: null });
+  const res = await call('GET', URL_);
+  assert.equal(res.status, 404, res.raw);
+});
+
+await ta("a declaration id that is not this project's is a 404, and removing says the value was never ours", async () => {
+  reset();
+  const miss = await call('DELETE', `${URL_}/999`);
+  assert.equal(miss.status, 404, miss.raw);
+  assert.equal(miss.body.error.code, 'env_var_not_found');
+  const hit = await call('DELETE', `${URL_}/5`);
+  assert.equal(hit.status, 200, hit.raw);
+  assert.match(hit.body.message, /untouched/, 'removing a name must not read as removing the secret');
+});
+
+await ta('a non-numeric declaration id is a 400 naming the field, not a 404', async () => {
+  reset();
+  const res = await call('DELETE', `${URL_}/abc`);
+  assert.equal(res.status, 400, res.raw);
+  assert.equal(res.body.error.code, 'bad_id');
+});
+
+console.log('\nthe owner-facing card:');
+
+t('the manage card has NO value input, and says why there is nowhere to type one', () => {
+  // The UI is the other place a value field could appear, so the absence is asserted here
+  // too rather than left to the API's refusal. A form about environment variables with no
+  // value box reads as unfinished unless it explains itself, which is why the copy check
+  // is part of the same assertion: removing the explanation to "tidy up" would leave a
+  // card that invites the very question the API refuses.
+  const page = readFileSync(new URL('../modules/public-landing/public/projects.html', import.meta.url), 'utf8');
+  const card = /<div class="card mSec" id="mEnvVars">([\s\S]*?)<\/details>/.exec(page);
+  assert.ok(card, 'the env-var card is on the manage page');
+  assert.match(card[1], /Why there is nowhere to type the value/, 'the fold answers the question the missing field raises');
+  assert.match(card[1], /Vercel|Netlify|Render|your own machine/, 'and names where the value does belong');
+
+  // The card's own client code: no input whose purpose is a value, and no request body
+  // field that could carry one.
+  const code = /Its environment variables \(task 1004062([\s\S]*?)function renderDisconnect/.exec(page);
+  assert.ok(code, 'the card\'s client code is on the page');
+  const inputIds = [...code[1].matchAll(/id="(mEnv[A-Za-z]*)"/g)].map((m) => m[1]);
+  assert.deepEqual(inputIds.sort(), ['mEnvAdd', 'mEnvName', 'mEnvNewDesc'],
+    `the card's only fields are the name and the purpose: ${inputIds.join(', ')}`);
+  for (const forbidden of envManifest.VALUE_FIELDS) {
+    assert.ok(!new RegExp(`\\b${forbidden}:`).test(code[1]),
+      `the card must not put "${forbidden}" in a request body`);
+  }
+});
+
+t('the card is guarded against the once-a-minute manage tick', () => {
+  // renderManage runs on a timer. Every other section there is fetch-free and so is safe
+  // to re-render; this one fetches AND holds a form, so a blind re-render would throw away
+  // what the owner is typing. The guard is the reason loadEnvManifest is called rather
+  // than a renderX, and this pins it.
+  const page = readFileSync(new URL('../modules/public-landing/public/projects.html', import.meta.url), 'utf8');
+  assert.match(page, /loadEnvManifest\(inst\);/, 'renderManage calls the loader');
+  assert.match(page, /if \(mEnvSlug === inst\.slug && mEnvVars && \(mEnvAdding \|\| mEnvEditing\)\) return;/,
+    'a tick during an edit leaves the DOM alone');
+});
+
+await ta('the routes file is DECLARED in module.json, or none of the above is reachable in production', async () => {
+  const mod = JSON.parse(readFileSync(new URL('../modules/provisioning/module.json', import.meta.url), 'utf8'));
+  assert.ok((mod.contributes.routes || []).includes('env-manifest'),
+    'a routes file the manifest does not list is a silent no-op (ADR 0289)');
+});
+
+server.close();
+
+console.log(`\nprovisioning_env_manifest: ${passed} passed, ${failed} failed`);
+if (failed) process.exit(1);