@bongos/core 1.25.20 → 1.25.22

package/tests/provisioning_project_grants.mjs

@@ -0,0 +1,458 @@
+// tests/provisioning_project_grants.mjs
+//
+// The owner-made grant (task 1004161, ADR 0407): a hosted project's provisioning routes admit
+// its owner, an archon where they already did, and — on exactly seven routes — a person the
+// OWNER granted 'operate' access. A sign-in grants nothing.
+//
+// Covers:
+//   • THE ATTACK: a GitHub user who only ran the device flow (a hub session and a witnessed
+//     `member` membership row, no grant) is refused on EVERY /provisioning/instances/:id route
+//     the module declares, found by reading the route files, so a route added later is covered
+//     too; nothing is written for them.
+//   • a grantee is admitted on the seven routes and refused (404) on every other one; their
+//     restart is recorded as api:grantee:<id>; their project read carries no owner bill and no
+//     GitHub steps
+//   • taking access back binds on the very next request
+//   • giving access is the owner's alone: an archon or the grantee cannot; the owner cannot
+//     grant themselves; an unknown login is named
+//   • a grant read that throws DENIES (500), never admits
+//   • grants.js: the data rules hold whoever calls (owner refusal, the limit, one live grant)
+//   • the structure: exactly the seven routes opt in, only grants.js writes the table, and the
+//     gate never reads a membership row
+//
+// DB-free: the real routers and the real error envelope over stubbed data access (the
+// provisioning_project_owner_gate.mjs pattern). Every query that reaches the pool is recorded,
+// and a membership query answers `member` — so a gate that ever consulted membership to admit
+// would let the attacker in and turn this file red.
+//
+// Run:  node --test tests/provisioning_project_grants.mjs
+
+import assert from 'node:assert/strict';
+import { test, before, after } from 'node:test';
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+const api = require(path.join(ROOT, 'src/module-api.js'));
+const provisioning = require(path.join(ROOT, 'modules/provisioning/provisioning.js'));
+const grants = require(path.join(ROOT, 'modules/provisioning/grants.js'));
+const envManifest = require(path.join(ROOT, 'modules/provisioning/env-manifest.js'));
+const githubSetup = require(path.join(ROOT, 'modules/provisioning/github-setup.js'));
+const catalogBridge = require(path.join(ROOT, 'modules/provisioning/catalog-bridge.js'));
+
+const OWNER = { id: 7, github_login: 'owner', rank: 'thetes' };
+const ATTACKER = { id: 66, github_login: 'device-flow-only', rank: 'xenos' };
+const GRANTEE = { id: 44, github_login: 'helper', rank: 'xenos' };
+const ARCHON = { id: 999, github_login: 'fleet-support', rank: 'archon' };
+const ROW = {
+  id: 18, owner_builder_id: 7, slug: 'mercury', status: 'active', hosting_shape: 'cloud-host',
+  domain: 'mercury.example.com', target_ref: 'owner/mercury', settings: {}, detail: {}, tier: null,
+};
+
+// ── the world the routes see ────────────────────────────────────────────────────────
+let builder = OWNER;
+const writes = [];            // every write any stubbed data function or the pool saw
+const sql = [];               // every query that reached the pool
+const live = new Map();       // `${instanceId}:${builderId}` → grant
+let grantReadThrows = false;
+const grantRow = (b) => ({ id: 3, instance_id: 18, grantee_builder_id: b.id, level: 'operate',
+  granted_by_builder_id: OWNER.id, granted_at: 't', revoked_at: null, revoked_by_builder_id: null });
+
+api.requireBuilder = (req, _res, next) => { req.builder = { ...builder }; next(); };
+// Nobody in this file holds a system permission: the fleet-wide routes refuse everyone.
+api.requirePermission = () => (_req, res) => res.fail('permission_forbidden', 403);
+api.branding = () => ({ domains: { publicOrigin: 'https://cb.test', instanceBase: 'cb.test' }, identity: { productName: 'Cloud Bongos' } });
+
+// A pool that records everything. A membership read answers `member` with the hub's witness —
+// exactly what a device-flow sign-in leaves behind.
+api.pool.query = async (text, params) => {
+  const q = String(text).replace(/\s+/g, ' ').trim();
+  sql.push(q);
+  if (/^(INSERT|UPDATE|DELETE)/i.test(q)) writes.push(q);
+  if (/platform_identity_project_memberships/.test(q)) {
+    return { rows: [{ client_id: 'mercury', github_id: '6600', membership_kind: 'member', signin_verified_at: 'now' }], rowCount: 1 };
+  }
+  return { rows: [], rowCount: 0 };
+};
+api.pool.connect = async () => ({ query: api.pool.query, release() {} });
+
+grants.liveGrant = async (_db, instanceId, builderId) => {
+  if (grantReadThrows) throw new Error('relation "provisioning_project_grants" does not exist');
+  return live.get(`${instanceId}:${builderId}`) || null;
+};
+grants.listLiveGrants = async (_db, instanceId) => [...live.values()].filter((g) => g.instance_id === instanceId)
+  .map((g) => ({ ...g, github_login: GRANTEE.github_login, display_name: null, avatar_url: null }));
+grants.findGranteeByLogin = async (_db, login) => (
+  [GRANTEE, OWNER, ATTACKER].find((b) => b.github_login === login) || null);
+grants.grantProjectAccess = async (_db, g) => {
+  writes.push(`grant ${g.granteeBuilderId}`);
+  if (String(g.granteeBuilderId) === String(ROW.owner_builder_id)) return { refused: 'grantee_is_owner' };
+  const row = { ...grantRow({ id: g.granteeBuilderId }), granted_by_builder_id: g.grantedByBuilderId };
+  live.set(`${g.instanceId}:${g.granteeBuilderId}`, row);
+  return { grant: row, created: true };
+};
+grants.getGrant = async (_db, instanceId, grantId) => (
+  [...live.values()].find((g) => g.instance_id === instanceId && g.id === grantId) || null);
+grants.revokeProjectAccess = async (_db, { instanceId, grantId }) => {
+  writes.push(`revoke ${grantId}`);
+  for (const [k, g] of live) if (g.instance_id === instanceId && g.id === grantId) { live.delete(k); return { ...g, revoked_at: 'now' }; }
+  return null;
+};
+
+const events = [];
+const enqueues = [];
+provisioning.getInstanceById = async (_db, id) => (String(id) === String(ROW.id) ? { ...ROW } : null);
+provisioning.recordEvent = async (_db, e) => { events.push(e); writes.push(`event ${e.event}`); };
+for (const fn of ['enqueueRestart', 'enqueueTeardown', 'enqueueIntent', 'enqueueRepoPrivate', 'enqueueRenderStandup',
+  'updateInstanceSettings', 'updateInstanceDetail', 'updateInstanceDomain', 'createOAuthManifest']) {
+  provisioning[fn] = async (_db, id, actor) => { enqueues.push({ fn, id, actor }); writes.push(fn); return { created: true, intent: { action: fn, state: 'pending' } }; };
+}
+provisioning.getOpenIntent = async () => null;
+provisioning.getLatestOAuthManifestForInstance = async () => null;
+githubSetup.githubSetupRead = async () => ({ steps: [], install_url: 'https://github.com/apps/x/installations/new' });
+githubSetup.installNudge = () => ({ install_url: 'https://github.com/apps/x/installations/new', repo: 'owner/mercury' });
+catalogBridge.healInstanceCatalog = async () => {};
+envManifest.listEnvVars = async () => [];
+envManifest.declareEnvVar = async (_db, d) => { writes.push('declare'); return { row: { id: 5, name: d.name }, created: true }; };
+envManifest.updateEnvVar = async () => { writes.push('update-var'); return { id: 5, name: 'PORT' }; };
+envManifest.removeEnvVar = async () => { writes.push('remove-var'); return true; };
+
+// ── every route the module declares on a project id ─────────────────────────────────
+const MODULE = path.join(ROOT, 'modules/provisioning');
+const routeFiles = JSON.parse(fs.readFileSync(path.join(MODULE, 'module.json'), 'utf8')).contributes.routes;
+const read = (f) => fs.readFileSync(f, 'utf8').replace(/\r\n/g, '\n');
+const DECLARED = [];
+for (const name of routeFiles) {
+  const src = read(path.join(MODULE, 'routes', `${name}.js`));
+  const re = /router\.(get|post|patch|put|delete)\(\s*'(\/provisioning\/instances\/:id[^']*)'/g;
+  let m;
+  while ((m = re.exec(src))) DECLARED.push({ method: m[1], route: m[2], file: name });
+}
+const concrete = (r) => r.replace(':id', '18').replace(':varId', '5').replace(':grantId', '3');
+
+// The seven routes a grantee may use (ADR 0407 §3) — and nothing else.
+const GRANTEE_ROUTES = new Set([
+  'get /provisioning/instances/:id',
+  'get /provisioning/instances/:id/settings',
+  'post /provisioning/instances/:id/restart',
+  'get /provisioning/instances/:id/env-manifest',
+  'post /provisioning/instances/:id/env-manifest',
+  'patch /provisioning/instances/:id/env-manifest/:varId',
+  'delete /provisioning/instances/:id/env-manifest/:varId',
+]);
+const BODIES = {
+  'post /provisioning/instances/:id/env-manifest': { name: 'PORT' },
+  'patch /provisioning/instances/:id/env-manifest/:varId': { description: 'the port' },
+  'post /provisioning/instances/:id/grants': { github_login: 'helper' },
+};
+
+const express = require('express');
+const { attachFail } = require(path.join(ROOT, 'src/bongos/middleware/error-envelope.js'));
+let server, base;
+before(async () => {
+  const app = express();
+  app.use(express.json());
+  app.use(attachFail);
+  for (const name of routeFiles) app.use('/api/bongos', require(path.join(MODULE, 'routes', `${name}.js`))());
+  server = app.listen(0);
+  await new Promise((r) => server.once('listening', r));
+  base = `http://127.0.0.1:${server.address().port}/api/bongos`;
+});
+after(() => { server.closeAllConnections(); server.close(); });
+
+async function call(method, route, body) {
+  const key = `${method} ${route}`;
+  const payload = body === undefined ? BODIES[key] || {} : body;
+  const res = await fetch(`${base}${concrete(route)}`, {
+    method: method.toUpperCase(),
+    headers: { 'content-type': 'application/json', connection: 'close' },
+    body: method === 'get' ? undefined : JSON.stringify(payload),
+  });
+  const raw = await res.text();
+  let json = null;
+  try { json = JSON.parse(raw); } catch { /* an HTML page, e.g. a redirect target */ }
+  return { status: res.status, body: json, raw };
+}
+function as(who) {
+  builder = who;
+  writes.length = 0; sql.length = 0; events.length = 0; enqueues.length = 0;
+  grantReadThrows = false;
+}
+
+// ── THE ATTACK ──────────────────────────────────────────────────────────────────────
+test('the module declares the routes this file walks (a sanity floor, not a fixed count)', () => {
+  assert.ok(DECLARED.length >= 30, `found ${DECLARED.length}: ${DECLARED.map((d) => `${d.method} ${d.route}`).join(' · ')}`);
+  for (const k of GRANTEE_ROUTES) assert.ok(DECLARED.some((d) => `${d.method} ${d.route}` === k), `${k} is declared`);
+});
+
+test('a GitHub user who only signed in (device flow, witnessed member row, no grant) is refused on EVERY project route, and nothing is written', async () => {
+  for (const d of DECLARED) {
+    as(ATTACKER);
+    const r = await call(d.method, d.route);
+    assert.ok(r.status >= 400 && r.status < 500, `${d.method} ${d.route} → ${r.status} ${r.raw.slice(0, 200)}`);
+    assert.deepEqual(writes, [], `${d.method} ${d.route} wrote ${JSON.stringify(writes)}`);
+    assert.deepEqual(enqueues, [], `${d.method} ${d.route} queued work`);
+  }
+});
+
+test('the seven grantee routes and the grant routes answer the attacker with the stranger’s 404 — the id is not confirmed', async () => {
+  for (const d of DECLARED.filter((x) => GRANTEE_ROUTES.has(`${x.method} ${x.route}`) || x.file === 'grants')) {
+    as(ATTACKER);
+    const r = await call(d.method, d.route);
+    assert.equal(r.status, 404, `${d.method} ${d.route}: ${r.raw}`);
+    assert.equal(r.body.error.code, 'instance_not_found', `${d.method} ${d.route}`);
+  }
+});
+
+test('the attacker cannot give themselves access', async () => {
+  as(ATTACKER);
+  const r = await call('post', '/provisioning/instances/:id/grants', { github_login: 'device-flow-only' });
+  assert.equal(r.status, 404, r.raw);
+  assert.equal(live.size, 0);
+});
+
+// ── a person the owner granted ──────────────────────────────────────────────────────
+test('the owner gives the helper access: 201, a live grant, and an audit row naming the owner', async () => {
+  as(OWNER);
+  const r = await call('post', '/provisioning/instances/:id/grants', { github_login: '@helper' });
+  assert.equal(r.status, 201, r.raw);
+  assert.equal(r.body.grant.builder.github_login, 'helper', 'the reply names the person found');
+  assert.ok(live.get('18:44'));
+  assert.equal(events[0].event, 'grant-made');
+  assert.equal(events[0].actor, 'api:self');
+});
+
+test('the grantee is admitted on exactly the seven routes, and refused (404) on every other', async () => {
+  live.set('18:44', grantRow(GRANTEE));
+  for (const d of DECLARED) {
+    as(GRANTEE);
+    const key = `${d.method} ${d.route}`;
+    const r = await call(d.method, d.route);
+    if (GRANTEE_ROUTES.has(key)) {
+      assert.ok(r.status >= 200 && r.status < 300, `${key} should admit the grantee: ${r.status} ${r.raw.slice(0, 200)}`);
+    } else if (key === 'delete /provisioning/instances/:id/grants/:grantId') {
+      continue; // taking their OWN grant back is allowed — its own test below
+    } else {
+      assert.ok(r.status >= 400 && r.status < 500, `${key} must refuse the grantee: ${r.status} ${r.raw.slice(0, 200)}`);
+      assert.deepEqual(enqueues, [], `${key} queued work for the grantee`);
+    }
+  }
+});
+
+test('a grantee’s restart is recorded as theirs, never as the owner’s', async () => {
+  live.set('18:44', grantRow(GRANTEE));
+  as(GRANTEE);
+  const r = await call('post', '/provisioning/instances/:id/restart');
+  assert.equal(r.status, 200, r.raw);
+  assert.deepEqual(enqueues, [{ fn: 'enqueueRestart', id: 18, actor: 'api:grantee:44' }]);
+  assert.equal(events[0].actor, 'api:grantee:44');
+  assert.match(events[0].detail, /restart requested by grantee helper/);
+  assert.doesNotMatch(events[0].detail, /by owner/);
+});
+
+test('a grantee’s change to the variable list is audited as theirs', async () => {
+  live.set('18:44', grantRow(GRANTEE));
+  as(GRANTEE);
+  const r = await call('post', '/provisioning/instances/:id/env-manifest', { name: 'PORT' });
+  assert.equal(r.status, 201, r.raw);
+  assert.equal(events[0].event, 'env-manifest');
+  assert.equal(events[0].actor, 'api:grantee:44');
+});
+
+test('the grantee’s project read carries no owner bill and no GitHub steps; the owner’s carries both', async () => {
+  live.set('18:44', grantRow(GRANTEE));
+  as(GRANTEE);
+  const g = await call('get', '/provisioning/instances/:id');
+  assert.equal(g.status, 200, g.raw);
+  assert.equal('owner_monthly_usd' in g.body.instance, false);
+  assert.equal('github_install' in g.body.instance, false);
+  assert.equal(g.body.github_app, null);
+  assert.equal(g.body.github_setup, null);
+  as(OWNER);
+  const o = await call('get', '/provisioning/instances/:id');
+  assert.ok('owner_monthly_usd' in o.body.instance);
+  assert.ok(o.body.instance.github_install);
+  assert.ok(o.body.github_setup);
+});
+
+// ── taking access back ──────────────────────────────────────────────────────────────
+test('the owner takes access back and the grantee is refused on the very next request', async () => {
+  live.set('18:44', grantRow(GRANTEE));
+  as(GRANTEE);
+  assert.equal((await call('post', '/provisioning/instances/:id/restart')).status, 200);
+  as(OWNER);
+  const r = await call('delete', '/provisioning/instances/:id/grants/:grantId');
+  assert.equal(r.status, 200, r.raw);
+  assert.equal(events[0].event, 'grant-revoked');
+  assert.equal(events[0].actor, 'api:self');
+  as(GRANTEE);
+  const after = await call('post', '/provisioning/instances/:id/restart');
+  assert.equal(after.status, 404, after.raw);
+  assert.deepEqual(enqueues, []);
+});
+
+test('a grantee may take their own access back; an archon may take anyone’s; a stranger may not', async () => {
+  live.set('18:44', grantRow(GRANTEE));
+  as(ATTACKER);
+  assert.equal((await call('delete', '/provisioning/instances/:id/grants/:grantId')).status, 404);
+  assert.ok(live.get('18:44'), 'a stranger removed nothing');
+  as(GRANTEE);
+  const own = await call('delete', '/provisioning/instances/:id/grants/:grantId');
+  assert.equal(own.status, 200, own.raw);
+  assert.equal(events[0].actor, 'api:grantee:44');
+  live.set('18:44', grantRow(GRANTEE));
+  as(ARCHON);
+  const a = await call('delete', '/provisioning/instances/:id/grants/:grantId');
+  assert.equal(a.status, 200, a.raw);
+  assert.equal(events[0].actor, 'api:archon:999');
+});
+
+// ── who may give access ─────────────────────────────────────────────────────────────
+test('an archon cannot give access on someone else’s project, and a grantee cannot pass it on', async () => {
+  live.clear();
+  as(ARCHON);
+  const a = await call('post', '/provisioning/instances/:id/grants', { github_login: 'helper' });
+  assert.equal(a.status, 404, a.raw);
+  assert.equal(live.size, 0);
+  live.set('18:44', grantRow(GRANTEE));
+  as(GRANTEE);
+  try {
+    const g = await call('post', '/provisioning/instances/:id/grants', { github_login: 'device-flow-only' });
+    // A grantee already knows the project, so the refusal says why (task 1004162, ADR 0407 §6).
+    assert.equal(g.status, 403, g.raw);
+    assert.equal(g.body.error.code, 'owner_only');
+    assert.equal(live.has('18:66'), false);
+  } finally {
+    live.clear();
+  }
+});
+
+test('the owner cannot grant themselves, and an unknown login is named, not guessed', async () => {
+  as(OWNER);
+  const self = await call('post', '/provisioning/instances/:id/grants', { github_login: 'owner' });
+  assert.equal(self.status, 400, self.raw);
+  assert.equal(self.body.error.code, 'grantee_is_owner');
+  const nobody = await call('post', '/provisioning/instances/:id/grants', { github_login: 'nobody-here' });
+  assert.equal(nobody.status, 404, nobody.raw);
+  assert.equal(nobody.body.error.code, 'grantee_not_found');
+  const bad = await call('post', '/provisioning/instances/:id/grants', { github_login: 'not a login' });
+  assert.equal(bad.status, 400, bad.raw);
+  assert.equal(live.size, 0);
+});
+
+// ── failure shapes ──────────────────────────────────────────────────────────────────
+test('a grant read that throws DENIES with the opaque 500 — the route body never runs', async () => {
+  live.set('18:44', grantRow(GRANTEE));
+  as(GRANTEE);
+  grantReadThrows = true;
+  const r = await call('post', '/provisioning/instances/:id/restart');
+  assert.equal(r.status, 500, r.raw);
+  assert.deepEqual(r.body.error, { code: 'instance_read_failed', message: 'internal error' });
+  assert.deepEqual(enqueues, []);
+  live.clear();
+});
+
+test('the owner never needs the grant read, so a broken grants table cannot lock the owner out', async () => {
+  as(OWNER);
+  grantReadThrows = true;
+  const r = await call('post', '/provisioning/instances/:id/restart');
+  assert.equal(r.status, 200, r.raw);
+  assert.equal(enqueues[0].actor, 'api:self');
+});
+
+test('an unknown grantee level is a programming error at mount time, never a silent widening', () => {
+  const { requireProjectOwner } = require(path.join(MODULE, 'route-helpers.js'));
+  assert.throws(() => requireProjectOwner(async () => null, { grantee: 'admin' }), /unknown grantee level/);
+});
+
+// ── grants.js: the data rules hold whoever calls ────────────────────────────────────
+function scriptedDb({ owner = 7, live: liveRows = [], count = 0 }) {
+  const seen = [];
+  const q = async (text, params) => {
+    const s = String(text).replace(/\s+/g, ' ').trim();
+    seen.push(s);
+    if (/FOR UPDATE/.test(s)) return { rows: [{ id: params[0], owner_builder_id: owner }] };
+    if (/revoked_at IS NULL LIMIT 1/.test(s)) return { rows: liveRows };
+    if (/count\(\*\)/.test(s)) return { rows: [{ n: count }] };
+    if (/^INSERT INTO provisioning_project_grants/.test(s)) return { rows: [{ id: 9, instance_id: params[0], grantee_builder_id: params[1], level: params[2] }] };
+    return { rows: [] };
+  };
+  return { seen, connect: async () => ({ query: q, release() {} }) };
+}
+const realGrants = (() => {
+  const p = require.resolve(path.join(MODULE, 'grants.js'));
+  const saved = require.cache[p];
+  delete require.cache[p];
+  const fresh = require(p);
+  require.cache[p] = saved;
+  return fresh;
+})();
+
+test('grants.js refuses the owner, an unknown level and a full project, and returns an existing live grant', async () => {
+  let db = scriptedDb({});
+  assert.deepEqual(await realGrants.grantProjectAccess(db, { instanceId: 18, granteeBuilderId: 7, grantedByBuilderId: 7 }), { refused: 'grantee_is_owner' });
+  assert.ok(!db.seen.some((s) => /^INSERT/.test(s)));
+  assert.deepEqual(await realGrants.grantProjectAccess(scriptedDb({}), { instanceId: 18, granteeBuilderId: 44, level: 'admin', grantedByBuilderId: 7 }), { refused: 'bad_level' });
+  db = scriptedDb({ count: realGrants.MAX_LIVE_GRANTS });
+  assert.deepEqual(await realGrants.grantProjectAccess(db, { instanceId: 18, granteeBuilderId: 44, grantedByBuilderId: 7 }), { refused: 'grant_limit' });
+  assert.ok(!db.seen.some((s) => /^INSERT/.test(s)));
+  db = scriptedDb({ live: [{ id: 3, level: 'operate' }] });
+  const again = await realGrants.grantProjectAccess(db, { instanceId: 18, granteeBuilderId: 44, grantedByBuilderId: 7 });
+  assert.equal(again.created, false);
+  assert.ok(!db.seen.some((s) => /^INSERT/.test(s)), 'one live grant per person');
+  db = scriptedDb({});
+  const made = await realGrants.grantProjectAccess(db, { instanceId: 18, granteeBuilderId: 44, grantedByBuilderId: 7 });
+  assert.equal(made.created, true);
+  assert.ok(db.seen.indexOf(db.seen.find((s) => /FOR UPDATE/.test(s))) < db.seen.indexOf(db.seen.find((s) => /^INSERT/.test(s))), 'the count runs under the project lock');
+});
+
+test('a revoke is a stamp scoped to the project, and the live read only ever sees unrevoked rows', async () => {
+  const seen = [];
+  const db = { query: async (t, p) => { seen.push({ s: String(t).replace(/\s+/g, ' '), p }); return { rows: [] }; } };
+  assert.equal(await realGrants.revokeProjectAccess(db, { instanceId: 18, grantId: 3, revokedByBuilderId: 7 }), null);
+  assert.match(seen[0].s, /UPDATE provisioning_project_grants SET revoked_at = now\(\)/);
+  assert.match(seen[0].s, /WHERE id = \$1 AND instance_id = \$2 AND revoked_at IS NULL/);
+  assert.doesNotMatch(seen[0].s, /DELETE/);
+  await realGrants.liveGrant(db, 18, 44);
+  assert.match(seen[1].s, /instance_id = \$1 AND g\.grantee_builder_id = \$2 AND g\.revoked_at IS NULL/);
+});
+
+// ── the structure ───────────────────────────────────────────────────────────────────
+test('exactly the seven routes opt in to grantee access', () => {
+  const optedIn = [];
+  for (const name of routeFiles) {
+    for (const line of read(path.join(MODULE, 'routes', `${name}.js`)).split('\n')) {
+      const m = /router\.(get|post|patch|put|delete)\('(\/provisioning\/instances\/:id[^']*)'/.exec(line);
+      if (m && /requireProjectOwner\(loadInstance, GRANTEE\)/.test(line)) optedIn.push(`${m[1]} ${m[2]}`);
+    }
+  }
+  assert.deepEqual(optedIn.sort(), [...GRANTEE_ROUTES].sort());
+  for (const name of routeFiles) {
+    const src = read(path.join(MODULE, 'routes', `${name}.js`));
+    assert.doesNotMatch(src, /grantee:\s*'(?!operate')/, `${name}.js names an unknown level`);
+    const defs = src.match(/const GRANTEE = \{[^}]*\}/g) || [];
+    for (const d of defs) assert.equal(d.replace(/\s+/g, ' '), "const GRANTEE = { grantee: 'operate' }", `${name}.js`);
+  }
+});
+
+test('only grants.js writes the grants table, and the gate never reads a membership row', () => {
+  const files = [];
+  const walk = (dir) => {
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (e.name === 'node_modules' || e.name.startsWith('.')) continue;
+      const p = path.join(dir, e.name);
+      if (e.isDirectory()) walk(p); else if (e.name.endsWith('.js')) files.push(p);
+    }
+  };
+  for (const d of ['modules', 'src', 'scripts']) walk(path.join(ROOT, d));
+  const writers = files.filter((f) => /(INSERT INTO|UPDATE|DELETE FROM)\s+provisioning_project_grants/.test(read(f)))
+    .map((f) => path.relative(ROOT, f).replace(/\\/g, '/'));
+  assert.deepEqual(writers, ['modules/provisioning/grants.js']);
+  // code only — the comments are allowed to explain why membership is never read
+  const gate = read(path.join(MODULE, 'route-helpers.js')).replace(/\/\/.*$/gm, '');
+  assert.doesNotMatch(gate, /membership|platform-identity|platform_identity|resolveOptional/i);
+});

package/tests/provisioning_project_owner_gate.mjs

@@ -251,7 +251,9 @@ test('every /provisioning/instances/:id route in the three files mounts the gate
       const m = /router\.(get|post|patch|put|delete)\('(\/provisioning\/instances\/:id[^']*)'/.exec(line);
       if (!m || m[2].endsWith('/force-teardown')) continue;
       declared.push(`${m[1]} ${m[2]}`);
-      assert.match(line, /requireBuilder, (?:\w+, )?requireProjectOwner\(loadInstance\), async \(req, res\) =>/, `${m[1]} ${m[2]}`);
+      // The grantee opt-in (task 1004161, ADR 0407 §3) is the only argument a route may add;
+      // which routes carry it is pinned in tests/provisioning_project_grants.mjs.
+      assert.match(line, /requireBuilder, (?:\w+, )?requireProjectOwner\(loadInstance(?:, GRANTEE)?\), async \(req, res\) =>/, `${m[1]} ${m[2]}`);
     }
   }
   assert.equal(declared.length, 14, `the 14 own-scoped routes, found: ${declared.join(' · ')}`);