@bongos/core 1.19.537 → 1.19.539

package/src/module-api.js

@@ -49,7 +49,7 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.537'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.539'; // 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('dev-box'); log.info('mounted');

package/tests/project_catalog_routes.mjs

@@ -211,3 +211,25 @@ test('a catalog hiccup can never turn a saved change into a failure', async () =
     catalogBridge.publishInstanceToCatalog = saved;
   }
 });
+
+test('mounting the routes registers the `provisioning.projectOwnedBy` port (task 1003580)', async () => {
+  // The OTHER direction of the same seam: the catalog write travels provisioning → hub, and
+  // this ownership read travels hub → provisioning, so the hub's invite door can own-scope a
+  // project without importing this module (ADR 0083) and without treating the hub's own
+  // `owner_github_id` columns as authority (ADR 0238). Registered here at mount, so a hub
+  // running with provisioning enabled always has it.
+  assert.equal(api.hasProvider('provisioning.projectOwnedBy'), true);
+  const ownedBy = api.resolve('provisioning.projectOwnedBy');
+  assert.equal(typeof ownedBy, 'function');
+  // It reaches the module's own read, bound to the module's pool — the caller never supplies
+  // a database handle, so no consumer can point this question at another connection.
+  const seen = [];
+  const saved = provisioning.projectOwnedBy;
+  provisioning.projectOwnedBy = async (_db, target) => { seen.push(target); return true; };
+  try {
+    assert.equal(await ownedBy({ slug: 'spike-harbor', host: 'spike-harbor.cloudbongos.test', builderId: 7 }), true);
+    assert.deepEqual(seen, [{ slug: 'spike-harbor', host: 'spike-harbor.cloudbongos.test', builderId: 7 }]);
+  } finally {
+    provisioning.projectOwnedBy = saved;
+  }
+});

package/tests/project_invite_ownership.mjs

@@ -0,0 +1,366 @@
+// tests/project_invite_ownership.mjs — A PROJECT'S OWNER MAY INVITE INTO THEIR OWN PROJECT
+// (task 1003580, GAP 2; the ADR 0210 owner-or-rank shape applied to POST /projects/invite).
+//
+// Task 1003576 / ADR 0246 gave every control-plane project a catalog row, so the invite route
+// stopped 404ing for a wizard-made project. What was left is WHO may call it: the route is
+// gated `project.curate`, floor metic, and the wizard's audience is any signed-in GitHub user
+// — typically a `xenos` who gets 403 on their OWN project. This file is the proof of the arm
+// that fixes it, and of the four things the arm must NOT do.
+//
+// THE OWNERSHIP PROOF IS THE PROVISIONING ROW. `provisioning_instances.owner_builder_id` is
+// the authority the manage view already trusts; the hub's `owner_github_id` columns are
+// attribution, never authority (ADR 0238). platform-identity may not import provisioning
+// (ADR 0083), so the fact travels on the `provisioning.projectOwnedBy` port — resolved
+// OPTIONALLY, because the hub must boot with no provisioning module at all.
+//
+// DB-free: the real router driven over loopback, data access stubbed on the cached module
+// objects and the port stubbed on the doorway (the catalog_only_client.mjs pattern).
+//
+// Run:  node --test --test-reporter=tap tests/project_invite_ownership.mjs
+
+import assert from 'node:assert/strict';
+import { test, after, beforeEach } from 'node:test';
+import { createRequire } from 'node:module';
+import http from 'node:http';
+
+const require = createRequire(import.meta.url);
+const pi = require('../modules/platform-identity/platform-identity.js');
+const api = require('../src/module-api.js');
+
+// ── the world ────────────────────────────────────────────────────────────────
+
+// A wizard-made standalone project: catalog-only client (no secret), owned by builder 7 whose
+// provisioning row is slug `spike-harbor` at spike-harbor.cloudbongos.test.
+const OWNED = Object.freeze({
+  client_id: 'spike-harbor', secret_hash: '', name: 'spike-harbor',
+  redirect_uris: [], origin: 'https://spike-harbor.cloudbongos.test',
+  owner_github_id: 9001, status: 'active',
+});
+// Someone ELSE's project, and a STEALTH one: the refusal a stranger gets must not tell them
+// this row exists (ADR 0182 D2a — a stealth project is on the map anonymously or not at all).
+const STEALTH = Object.freeze({
+  ...OWNED, client_id: 'quiet-cove', name: 'quiet-cove', origin: 'https://quiet-cove.cloudbongos.test',
+  owner_github_id: 9002,
+});
+// A client the control plane never created — the hand-seeded catalog row shape (ADR 0246's
+// "unclaimable" case). Its slug is squattable in provisioning, which is why the port is asked
+// about the ORIGIN as well as the slug.
+const HAND_SEEDED = Object.freeze({
+  ...OWNED, client_id: 'legacy-port', name: 'legacy-port', origin: 'https://legacy-port.example',
+  secret_hash: 'a'.repeat(64), owner_github_id: 9003,
+});
+const CLIENTS = new Map([OWNED, STEALTH, HAND_SEEDED].map((c) => [c.client_id, c]));
+
+// The provisioning rows the port answers from: (slug, host) → owner builder id.
+const INSTANCES = [
+  { slug: 'spike-harbor', host: 'spike-harbor.cloudbongos.test', owner: 7 },
+  { slug: 'quiet-cove', host: 'quiet-cove.cloudbongos.test', owner: 9 },
+  // The SQUAT: builder 42 registered an instance named after the hand-seeded client, at their
+  // own address. Same slug, different origin — so it is not that project.
+  { slug: 'legacy-port', host: 'legacy-port.squatter.test', owner: 42 },
+];
+
+const OWNER = Object.freeze({ id: 7, github_id: 9001, github_login: 'owner', rank: 'xenos', curate: false });
+const STRANGER = Object.freeze({ id: 42, github_id: 4242, github_login: 'stranger', rank: 'xenos', curate: false });
+const CURATOR = Object.freeze({ id: 3, github_id: 3003, github_login: 'curator', rank: 'metic', curate: true });
+
+let caller = OWNER;
+// 'ok' | 'throws' | 'absent' — the port's health, so the fail-closed paths are executed.
+let portMode = 'ok';
+let invites = [];
+let portCalls = [];
+let clientReads = [];
+
+// ── the doorway, stubbed before the router is required ───────────────────────
+
+// Destructured at route-module load, so these must be in place first.
+api.requireBuilder = (req, _res, next) => { req.builder = caller; next(); };
+// A faithful stand-in for auth.requirePermission: it admits a holder and otherwise sends the
+// SAME 403 body every caller of this route has always received. The arm under test delegates
+// to this untouched middleware, so "the refusal is unchanged" is true by construction — what
+// these tests pin is that the delegation happens, and that it happens identically whether or
+// not the project exists.
+api.requirePermission = (...required) => (req, res, next) => {
+  if (req.builder && req.builder.curate) return next();
+  return res.fail('permission_forbidden', {
+    status: 403,
+    message: `missing permission${required.length === 1 ? '' : 's'}: ${required.join(', ')} (floor: metic)`,
+    details: { required, held: [], floors: { [required[0]]: 'metic' } },
+  });
+};
+// Silenced: the fallback path logs, and a pino line on stdout would land inside the TAP stream.
+api.logger = () => ({ error: () => {}, warn: () => {}, info: () => {} });
+
+const realResolveOptional = api.resolveOptional;
+api.resolveOptional = (name) => {
+  if (name !== 'provisioning.projectOwnedBy') return realResolveOptional(name);
+  if (portMode === 'absent') return null;
+  return async ({ slug, host, builderId }) => {
+    portCalls.push({ slug, host, builderId });
+    if (portMode === 'throws') throw new Error('provisioning is down');
+    return INSTANCES.some((i) => i.slug === slug && i.host === host && String(i.owner) === String(builderId));
+  };
+};
+
+pi.getClient = async (id) => { clientReads.push(id); return CLIENTS.get(id) || null; };
+pi.getAccountByLogin = async (login) => (login === 'ghost' ? null : { github_id: 5150, github_login: login });
+pi.inviteToProject = async ({ clientId, githubId }) => {
+  invites.push({ clientId, githubId });
+  return { invited: true, clientId, githubId };
+};
+
+const express = require('express');
+const projectsRoutes = require('../modules/platform-identity/routes/projects.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;
+    res.status(status).json({ error: { code, ...(typeof opts === 'object' ? opts : {}), ...(details || {}) } });
+  };
+  next();
+});
+app.use('/api/bongos', projectsRoutes());
+
+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`;
+after(() => server.close());
+
+function invite(body) {
+  return new Promise((resolve, reject) => {
+    const payload = JSON.stringify(body === undefined ? {} : body);
+    const req = http.request(`${base}/projects/invite`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) },
+    }, (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 }); });
+    });
+    req.on('error', reject);
+    req.write(payload);
+    req.end();
+  });
+}
+
+beforeEach(() => { caller = OWNER; portMode = 'ok'; invites = []; portCalls = []; clientReads = []; });
+
+// ── the arm ──────────────────────────────────────────────────────────────────
+
+test('the OWNER of a wizard-made project invites into it, holding no permission at all', async () => {
+  // The whole point of the task: the wizard's audience is any signed-in GitHub user, and a
+  // `xenos` owner used to get 403 on their own project before the target was even resolved.
+  caller = OWNER;
+  const res = await invite({ client_id: 'spike-harbor', github_login: 'someone' });
+  assert.equal(res.status, 201);
+  assert.equal(res.body.invited, true);
+  assert.deepEqual(invites, [{ clientId: 'spike-harbor', githubId: 5150 }]);
+  // The ownership question was asked of the provisioning row, keyed on BOTH halves of the
+  // catalog projection (ADR 0246: client_id = slug, origin = https://domain).
+  assert.deepEqual(portCalls, [{ slug: 'spike-harbor', host: 'spike-harbor.cloudbongos.test', builderId: 7 }]);
+  // …and the row the gate resolved to ask it rides forward to the handler: equalising the
+  // lookup across callers must not turn into reading the same row twice.
+  assert.deepEqual(clientReads, ['spike-harbor'], 'the client row is read exactly once per request');
+});
+
+test('a METIC curator still invites into a project they do not own — the old door is untouched', async () => {
+  caller = CURATOR;
+  const res = await invite({ client_id: 'spike-harbor', github_login: 'someone' });
+  assert.equal(res.status, 201);
+  assert.equal(res.body.invited, true);
+  assert.equal(invites.length, 1);
+});
+
+test('a DIFFERENT builder is refused with the unchanged shape, and writes nothing', async () => {
+  caller = STRANGER;
+  const res = await invite({ client_id: 'spike-harbor', github_login: 'someone' });
+  assert.equal(res.status, 403);
+  assert.equal(res.body.error.code, 'permission_forbidden');
+  assert.deepEqual(res.body.error.details.required, ['project.curate']);
+  assert.deepEqual(invites, [], 'a refused invite writes no membership row');
+});
+
+// ── the refusal is not an existence oracle ───────────────────────────────────
+
+test('a stranger cannot tell a STEALTH project from one that does not exist', async () => {
+  // ADR 0182 D2a: a stealth project is anonymous on the map. Turning this route's 403 into a
+  // 404-or-403 split would hand any signed-in stranger a membership oracle over every private
+  // project on the platform — the refusal must be byte-identical.
+  caller = STRANGER;
+  const stealth = await invite({ client_id: 'quiet-cove', github_login: 'someone' });
+  const nothing = await invite({ client_id: 'never-provisioned', github_login: 'someone' });
+  assert.equal(stealth.status, 403);
+  assert.deepEqual(stealth, nothing);
+  assert.deepEqual(invites, []);
+  // The LATENCY half of the same rule: both requests do the same work. A body-identical
+  // refusal that is measurably faster for a client_id nobody has taken is still an oracle, so
+  // the unknown client is asked about anyway — with the empty host, which matches nothing.
+  assert.deepEqual(clientReads, ['quiet-cove', 'never-provisioned']);
+  assert.deepEqual(portCalls, [
+    { slug: 'quiet-cove', host: 'quiet-cove.cloudbongos.test', builderId: 42 },
+    { slug: 'never-provisioned', host: '', builderId: 42 },
+  ], 'the same two lookups on both paths — the refusal is identical in latency, not only in body');
+});
+
+test('a stranger cannot tell a real project from a malformed request either', async () => {
+  // The gate runs BEFORE the body validator, exactly as requirePermission always did, so a
+  // caller who may not invite never learns whether their body was well-formed.
+  caller = STRANGER;
+  const good = await invite({ client_id: 'spike-harbor', github_login: 'someone' });
+  const empty = await invite({});
+  assert.equal(good.status, 403);
+  assert.deepEqual(good, empty);
+});
+
+// ── the arm cannot be widened by squatting a name ────────────────────────────
+
+test('owning an instance that merely SHARES a client_id grants nothing', async () => {
+  // Builder 42 registered `legacy-port` at their own address; the catalog row of that name is
+  // a hand-seeded client at a different origin, which ADR 0246's claim rule already refuses to
+  // overwrite. The ownership arm answers to the same binding: both halves of the projection
+  // (slug AND origin) must be the caller's, or this is simply not their project.
+  caller = STRANGER;
+  const res = await invite({ client_id: 'legacy-port', github_login: 'someone' });
+  assert.equal(res.status, 403);
+  assert.equal(res.body.error.code, 'permission_forbidden');
+  assert.deepEqual(invites, []);
+  assert.deepEqual(portCalls, [{ slug: 'legacy-port', host: 'legacy-port.example', builderId: 42 }],
+    'the port is asked about the CATALOG row\'s origin, never the caller\'s own instance');
+});
+
+// ── fail-closed on the ownership question itself ─────────────────────────────
+
+test('a missing provisioning module leaves the old door, unchanged', async () => {
+  // platform-identity is the hub; provisioning is a separate default-off module. The hub must
+  // boot without it, and an unresolvable port must deny rather than admit (ADR 0016).
+  portMode = 'absent';
+  caller = OWNER;
+  const res = await invite({ client_id: 'spike-harbor', github_login: 'someone' });
+  assert.equal(res.status, 403);
+  assert.deepEqual(invites, []);
+});
+
+test('a THROWING ownership check denies — it never 500s and never admits', async () => {
+  portMode = 'throws';
+  caller = OWNER;
+  const res = await invite({ client_id: 'spike-harbor', github_login: 'someone' });
+  assert.equal(res.status, 403);
+  assert.equal(res.body.error.code, 'permission_forbidden');
+  assert.deepEqual(invites, []);
+  // …while the CURATOR still gets through the same broken path: the failure mode of the new
+  // door is the old door, not an outage.
+  caller = CURATOR;
+  const asCurator = await invite({ client_id: 'spike-harbor', github_login: 'someone' });
+  assert.equal(asCurator.status, 201);
+});
+
+test('a non-string client_id is not an ownership claim', async () => {
+  // The gate runs before the body validator, so it validates its own input rather than
+  // trusting it: only a string names a project, and String(['spike-harbor']) must not.
+  caller = OWNER;
+  for (const client_id of [['spike-harbor'], { toString: () => 'spike-harbor' }, 7, null]) {
+    const res = await invite({ client_id, github_login: 'someone' });
+    assert.equal(res.status, 403, `client_id ${JSON.stringify(client_id)} must not pass the ownership arm`);
+  }
+  assert.deepEqual(portCalls, [], 'a non-string never even reaches the port');
+  assert.deepEqual(clientReads, [], 'nor the client registry — there is no project named here');
+});
+
+// ── the resolved target is still the catalog row's job ───────────────────────
+
+test('an owner asking for a project that has no catalog row still gets the plain 404', async () => {
+  // Ownership admits; it does not conjure a target. `never-provisioned` has no client row, so
+  // the handler's own `unknown_project` is what answers — unchanged from today.
+  caller = CURATOR;
+  const res = await invite({ client_id: 'never-provisioned', github_login: 'someone' });
+  assert.equal(res.status, 404);
+  assert.equal(res.body.error.code, 'unknown_project');
+});
+
+test('SUSPENDING the client still shuts the door on its own owner', async () => {
+  // The operator's revocation lever (`setClientStatus`) is what stops a rogue or compromised
+  // project signing anyone in; a widened door that outlived it would be a widening with no way
+  // back. Ownership admits at the gate, and the handler's own status check answers — the same
+  // `unknown_project` a stranger would get, so suspension is not disclosed either.
+  const suspended = { ...OWNED, status: 'suspended' };
+  CLIENTS.set(suspended.client_id, suspended);
+  try {
+    caller = OWNER;
+    const res = await invite({ client_id: 'spike-harbor', github_login: 'someone' });
+    assert.equal(res.status, 404);
+    assert.equal(res.body.error.code, 'unknown_project');
+    assert.deepEqual(invites, []);
+  } finally {
+    CLIENTS.set(OWNED.client_id, OWNED);
+  }
+});
+
+// ── the authority query itself ───────────────────────────────────────────────
+
+test('projectOwnedBy asks the provisioning row for all three facts at once', async () => {
+  // The authority half of the seam, on the plane that holds the row: slug AND host AND owner
+  // in ONE statement, so there is no read-then-compare window and no consumer ever handles an
+  // ownership id it could mis-compare (ADR 0238 — the hub's own columns are attribution).
+  const provisioning = require('../modules/provisioning/provisioning.js');
+  const seen = [];
+  const db = { query: async (sql, params) => { seen.push({ sql, params }); return { rows: [{ '?column?': 1 }] }; } };
+  assert.equal(await provisioning.projectOwnedBy(db, {
+    slug: 'spike-harbor', host: 'Spike-Harbor.CloudBongos.test', builderId: '7',
+  }), true, 'a bigint id arriving as a string still matches, and the host is compared case-folded');
+  assert.equal(seen.length, 1);
+  assert.match(seen[0].sql, /FROM provisioning_instances/);
+  assert.match(seen[0].sql, /slug = \$1/);
+  assert.match(seen[0].sql, /lower\(domain\) = \$2/);
+  assert.match(seen[0].sql, /owner_builder_id = \$3/);
+  assert.deepEqual(seen[0].params, ['spike-harbor', 'spike-harbor.cloudbongos.test', 7]);
+});
+
+test('projectOwnedBy fails closed before touching the database on anything unidentifiable', async () => {
+  const provisioning = require('../modules/provisioning/provisioning.js');
+  const db = { query: async () => { throw new Error('the query must not run'); } };
+  const bad = [
+    undefined,
+    { slug: '', host: 'h.test', builderId: 7 },
+    { slug: ['s'], host: 'h.test', builderId: 7 },
+    { slug: 's', host: 'h.test', builderId: 'not-a-number' },
+    { slug: 's', host: 'h.test', builderId: 0 },
+    { slug: 's', host: 'h.test', builderId: -1 },
+    { slug: 's', host: 'h.test', builderId: null },
+  ];
+  for (const target of bad) {
+    assert.equal(await provisioning.projectOwnedBy(db, target), false, JSON.stringify(target));
+  }
+});
+
+test('projectOwnedBy QUERIES an empty host rather than short-circuiting it', async () => {
+  // The timing-equalising half, on the plane that runs the statement. An empty host names no
+  // address and matches nothing — `domain` is a hostname or NULL, and `lower(NULL) = ''` is
+  // NULL — so this is a real round-trip with a guaranteed-empty result, not a dummy delay.
+  const provisioning = require('../modules/provisioning/provisioning.js');
+  const seen = [];
+  const db = { query: async (sql, params) => { seen.push(params); return { rows: [] }; } };
+  assert.equal(await provisioning.projectOwnedBy(db, { slug: 's', host: '', builderId: 7 }), false);
+  assert.deepEqual(seen, [['s', '', 7]], 'the query still ran — the caller pays the same cost either way');
+});
+
+test('projectOwnedBy answers false, not a row, when nothing matches', async () => {
+  const provisioning = require('../modules/provisioning/provisioning.js');
+  const db = { query: async () => ({ rows: [] }) };
+  assert.equal(await provisioning.projectOwnedBy(db, { slug: 's', host: 'h.test', builderId: 7 }), false);
+});
+
+// ── the seam ─────────────────────────────────────────────────────────────────
+
+test('provisioning DECLARES the ownership port, and platform-identity does not require it', async () => {
+  // verifyPortsSatisfied reads the manifests at boot, not the registry: an undeclared provider
+  // is invisible to it, and a port named in `consumes` the hub would refuse to boot without.
+  const read = async (rel) => JSON.parse(await (await import('node:fs/promises'))
+    .readFile(new URL(rel, import.meta.url), 'utf8'));
+  const provisioning = await read('../modules/provisioning/module.json');
+  const identity = await read('../modules/platform-identity/module.json');
+  assert.ok(provisioning.provides.includes('provisioning.projectOwnedBy'), 'the port is declared');
+  assert.ok(!(identity.consumes || []).includes('provisioning.projectOwnedBy'),
+    'optional, not required — the hub must boot with no provisioning module at all');
+});