@bongos/core 1.19.533 → 1.19.534

package/tests/project_join_door.mjs

@@ -0,0 +1,166 @@
+// tests/project_join_door.mjs — the composed join/apply door (BV1.R12, task
+// 1002331): every visibility state × every join grant × every joinability, plus
+// the derived dark-matter lock and the fail-closed edges.
+//
+// The matrix is written out rather than sampled because the whole point of ADR
+// 0182 D6 is that two knobs must never negotiate — "the stricter of the two always
+// wins, and neither can widen the other" is a claim about all 27 cells, and the
+// bug it prevents (an owner setting `private` on the map while the public
+// application endpoint keeps taking applications) is invisible in any one of them.
+//
+// ESM `import` on purpose, not createRequire: knip does not credit a CJS module's
+// exports to a test that reaches them through require().
+//
+// Run:  node --test tests/project_join_door.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import {
+  JOIN_DOORS, DOOR_RANK, PROJECT_JOIN_GRANTS,
+  strictestDoor, visibilityCeiling, projectJoinDoor, effectiveJoinDoor,
+} from '../src/bongos/project-door.js';
+
+const VISIBILITIES = ['public', 'private', 'stealth'];
+const JOINABILITIES = ['open', 'apply', 'invite_only'];
+
+const door = (visibility, joinGrant, joinability, publishable) =>
+  projectJoinDoor({ visibility, joinGrant, joinability, publishable });
+
+// ── the vocabulary itself ────────────────────────────────────────────────────
+
+test('the door vocabulary is ordered widest → strictest, and the rank IS that order', () => {
+  assert.deepEqual(JOIN_DOORS, ['open', 'apply', 'invite_only', 'locked']);
+  assert.deepEqual(DOOR_RANK, { open: 0, apply: 1, invite_only: 2, locked: 3 });
+  assert.deepEqual(PROJECT_JOIN_GRANTS, ['view', 'apply', 'full']);
+});
+
+test('strictestDoor never widens, and an unknown door name is the strictest there is', () => {
+  assert.equal(strictestDoor('open', 'apply'), 'apply');
+  assert.equal(strictestDoor('invite_only', 'open'), 'invite_only');
+  assert.equal(strictestDoor('locked', 'open'), 'locked');
+  assert.equal(strictestDoor('open', 'open'), 'open');
+  assert.equal(strictestDoor('open', 'whatever'), 'locked', 'a value the table does not carry cannot widen the door');
+});
+
+// ── the visibility ceiling (ADR 0182 D6's table) ─────────────────────────────
+
+test('visibilityCeiling: public defers to the grant, every other state sets its own', () => {
+  assert.equal(visibilityCeiling('public', 'full'), 'open');
+  assert.equal(visibilityCeiling('public', 'apply'), 'apply');
+  assert.equal(visibilityCeiling('public', 'view'), 'invite_only');
+  assert.equal(visibilityCeiling('private', 'full'), 'apply', 'private accepts applications, never a self-join');
+  assert.equal(visibilityCeiling('stealth', 'full'), 'invite_only', 'stealth refuses the application at the door');
+});
+
+test('visibilityCeiling fails closed on anything it cannot read', () => {
+  assert.equal(visibilityCeiling('unlisted', 'full'), 'invite_only', 'a fourth enum value is never a planet');
+  assert.equal(visibilityCeiling(undefined, 'full'), 'invite_only');
+  assert.equal(visibilityCeiling('public', 'FULL'), 'invite_only', 'a grant this core cannot read is not the wide door');
+  assert.equal(visibilityCeiling('public', undefined), 'invite_only');
+});
+
+// ── the full matrix ──────────────────────────────────────────────────────────
+
+test('public: the join grants exactly what the owner set — until joinability narrows it', () => {
+  // grant `full` is the "does not narrow" value, so a public project runs the
+  // door its joinability already ran: this is what makes the default a no-op.
+  assert.equal(door('public', 'full', 'open'), 'open');
+  assert.equal(door('public', 'full', 'apply'), 'apply');
+  assert.equal(door('public', 'full', 'invite_only'), 'invite_only');
+  // grant `apply`: a self-join is off the table even where enrolment is open.
+  assert.equal(door('public', 'apply', 'open'), 'apply');
+  assert.equal(door('public', 'apply', 'apply'), 'apply');
+  assert.equal(door('public', 'apply', 'invite_only'), 'invite_only');
+  // grant `view`: the project is on the map to be looked at; joining is by invite.
+  assert.equal(door('public', 'view', 'open'), 'invite_only');
+  assert.equal(door('public', 'view', 'apply'), 'invite_only');
+  assert.equal(door('public', 'view', 'invite_only'), 'invite_only');
+});
+
+test('private: invite-only with applications queued — the grant is a PUBLIC join\'s, and does not reach here', () => {
+  for (const grant of PROJECT_JOIN_GRANTS) {
+    assert.equal(door('private', grant, 'open'), 'apply', `grant ${grant} cannot widen private into a self-join`);
+    assert.equal(door('private', grant, 'apply'), 'apply', 'a private project queues the application for its owner');
+    assert.equal(door('private', grant, 'invite_only'), 'invite_only');
+  }
+});
+
+test('stealth: no application is accepted, whatever the other two knobs say', () => {
+  for (const grant of PROJECT_JOIN_GRANTS) {
+    for (const joinability of JOINABILITIES) {
+      assert.equal(door('stealth', grant, joinability), 'invite_only',
+        `stealth + ${grant} + ${joinability} still refuses at the door`);
+    }
+  }
+});
+
+test('ADR 0182 D6, cell by cell: neither knob can widen the other', () => {
+  let cells = 0;
+  for (const visibility of VISIBILITIES) {
+    for (const grant of PROJECT_JOIN_GRANTS) {
+      for (const joinability of JOINABILITIES) {
+        const answer = door(visibility, grant, joinability);
+        const ceiling = visibilityCeiling(visibility, grant);
+        assert.ok(DOOR_RANK[answer] >= DOOR_RANK[ceiling], 'the visibility ceiling is never widened');
+        assert.ok(DOOR_RANK[answer] >= DOOR_RANK[joinability], 'the joinability policy is never widened');
+        assert.equal(answer, strictestDoor(ceiling, joinability), 'the answer IS the stricter of the two');
+        cells++;
+      }
+    }
+  }
+  assert.equal(cells, 27, 'every state × grant × policy cell is asserted');
+});
+
+// ── dark matter ──────────────────────────────────────────────────────────────
+
+test('dark matter locks the door outright — there is nothing to knock on', () => {
+  for (const visibility of VISIBILITIES) {
+    for (const grant of PROJECT_JOIN_GRANTS) {
+      for (const joinability of JOINABILITIES) {
+        assert.equal(door(visibility, grant, joinability, false), 'locked');
+      }
+    }
+  }
+});
+
+test('publishable is a TRI-state: only an explicit false locks, and no verdict decides nothing', () => {
+  assert.equal(door('public', 'full', 'open', true), 'open', 'a met publish bar opens nothing on its own');
+  assert.equal(door('public', 'full', 'open', null), 'open', 'no verdict → the three stored knobs answer alone');
+  assert.equal(door('public', 'full', 'open', undefined), 'open');
+  assert.equal(door('public', 'full', 'open'), 'open', 'an absent argument is no verdict, never a lock');
+});
+
+test('a door surface holding no inputs at all is refused, not opened — and not mis-explained', () => {
+  assert.equal(projectJoinDoor(), 'invite_only');
+  assert.equal(projectJoinDoor({}), 'invite_only');
+  assert.equal(door('public', 'full', 'whenever'), 'invite_only',
+    'an unreadable policy closes to invite-only, never to `locked` — that word claims the project is unpublished');
+});
+
+// ── the live reader ──────────────────────────────────────────────────────────
+
+test('effectiveJoinDoor composes the resolved pack with the admission reader', () => {
+  const pack = (project) => () => ({ project });
+  assert.equal(effectiveJoinDoor({
+    branding: pack({ visibility: 'public', joinGrant: 'full' }), joinabilityMode: () => 'apply',
+  }), 'apply');
+  assert.equal(effectiveJoinDoor({
+    branding: pack({ visibility: 'stealth', joinGrant: 'full' }), joinabilityMode: () => 'open',
+  }), 'invite_only', 'an open stealth project still refuses everything (ADR 0182 D6)');
+  assert.equal(effectiveJoinDoor({
+    branding: pack({ visibility: 'public', joinGrant: 'apply' }), joinabilityMode: () => 'open',
+  }), 'apply', 'a grant narrows a project whose enrolment is open');
+});
+
+test('effectiveJoinDoor fails closed when the pack will not load', () => {
+  const boom = () => { throw new Error('pack unreadable'); };
+  assert.equal(effectiveJoinDoor({ branding: boom, joinabilityMode: () => 'open' }), 'invite_only');
+  assert.equal(effectiveJoinDoor({ branding: () => ({}), joinabilityMode: () => 'open' }), 'invite_only',
+    'a pack with no project block is unknown policy, not an open door');
+});
+
+test('effectiveJoinDoor passes a publish verdict through when its caller holds one', () => {
+  const pack = () => ({ project: { visibility: 'public', joinGrant: 'full' } });
+  assert.equal(effectiveJoinDoor({ branding: pack, joinabilityMode: () => 'open', publishable: false }), 'locked');
+  assert.equal(effectiveJoinDoor({ branding: pack, joinabilityMode: () => 'open', publishable: true }), 'open');
+});

package/tests/project_join_door_route.mjs

@@ -0,0 +1,206 @@
+// tests/project_join_door_route.mjs — the composed door AT THE ROUTE (BV1.R12,
+// task 1002331): every visibility state × every join grant, driven through the
+// real public POST /access-requests against a scripted pool.
+//
+// tests/project_join_door.mjs pins the decision; this pins that the DOOR ACTUALLY
+// RUNS IT — the gap R12 exists to close was a correct policy nothing consulted.
+// So the REAL composer is wired in (only `branding` and the joinability reader are
+// stubbed), and every case asserts the query count too: a refused application must
+// cost no DB work and, per ADR 0182 D6, must never be stored.
+//
+// The doorway is stubbed in require.cache BEFORE the route loads — the route
+// destructures pool/validators at require time (the access_requests_invite pattern).
+//
+// Run:  node --test tests/project_join_door_route.mjs
+
+import assert from 'node:assert/strict';
+import { test, before, after } from 'node:test';
+import http from 'node:http';
+import { createRequire } from 'node:module';
+import { effectiveJoinDoor } from '../src/bongos/project-door.js';
+
+const require = createRequire(import.meta.url);
+const express = require('express');
+
+const apiPath = require.resolve('../src/module-api.js');
+const realApi = require(apiPath);
+
+let calls = [];
+let script = [];
+// The policy this project runs — the three knobs the platform pushes into the
+// instance's branding pack, exactly as src/branding.js resolves them.
+let policy = { visibility: 'public', joinGrant: 'full', joinability: 'apply' };
+let publishable;
+
+const pool = {
+  async query(sql, params) {
+    calls.push({ sql, params });
+    if (!script.length) throw new Error(`unscripted query: ${sql.trim().slice(0, 40)}`);
+    const next = script.shift();
+    if (next instanceof Error) throw next;
+    return next;
+  },
+};
+require.cache[apiPath].exports = {
+  ...realApi,
+  pool,
+  // The REAL composition, over a stubbed pack + admission reader. Nothing about
+  // the decision is faked here — only where its three inputs come from.
+  projectJoinDoor: () => effectiveJoinDoor({
+    branding: () => ({ project: { visibility: policy.visibility, joinGrant: policy.joinGrant } }),
+    joinabilityMode: () => policy.joinability,
+    publishable,
+  }),
+  requireBuilder: (req, _res, next) => { req.builder = { id: 42, github_login: 'archon' }; next(); },
+  requirePermission: () => (_req, _res, next) => next(),
+};
+
+const buildAccessRequestsRouter = require('../modules/onboarding/routes/access-requests.js');
+const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
+
+const app = express();
+app.use(express.json());
+app.use(attachFail);
+app.use('/api/gds', buildAccessRequestsRouter());
+
+let server, port;
+before(async () => {
+  server = http.createServer(app);
+  await new Promise((r) => server.listen(0, '127.0.0.1', r));
+  port = server.address().port;
+});
+after(async () => { await new Promise((r) => server.close(r)); });
+
+function post(pathname, body) {
+  return new Promise((resolve, reject) => {
+    const payload = JSON.stringify(body);
+    const req = http.request({
+      host: '127.0.0.1', port, path: pathname, method: 'POST',
+      headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(payload) },
+    }, (res) => {
+      let data = '';
+      res.on('data', (c) => { data += c; });
+      res.on('end', () => resolve({ status: res.statusCode, json: data ? JSON.parse(data) : null }));
+    });
+    req.on('error', reject);
+    req.write(payload);
+    req.end();
+  });
+}
+
+const none = { rows: [] };
+const filed = [none, none, { rows: [{ id: 9, github_login: 'octocat', status: 'pending' }] }];
+
+// Knock on the door as a stranger under one policy, and say what happened.
+async function knock(next, { publishable: verdict } = {}) {
+  policy = next;
+  publishable = verdict;
+  script = [...filed];
+  calls = [];
+  const r = await post('/api/gds/access-requests', { github_login: 'octocat' });
+  return { status: r.status, code: r.json?.error?.code || null, filed: calls.length > 0, queries: calls.length };
+}
+
+const GRANTS = ['view', 'apply', 'full'];
+const REFUSED = { invite_only: 403, open_enrollment: 409, not_published: 403 };
+
+// ── public: the join grants exactly what the owner set ───────────────────────
+
+test('public + grant full: the door runs whatever joinability runs — the default changes nothing', async () => {
+  assert.deepEqual(await knock({ visibility: 'public', joinGrant: 'full', joinability: 'apply' }),
+    { status: 201, code: null, filed: true, queries: 3 });
+  assert.deepEqual(await knock({ visibility: 'public', joinGrant: 'full', joinability: 'open' }),
+    { status: 409, code: 'open_enrollment', filed: false, queries: 0 });
+  assert.deepEqual(await knock({ visibility: 'public', joinGrant: 'full', joinability: 'invite_only' }),
+    { status: 403, code: 'invite_only', filed: false, queries: 0 });
+});
+
+test('public + grant apply: the application is filed even where enrolment is open', async () => {
+  const r = await knock({ visibility: 'public', joinGrant: 'apply', joinability: 'open' });
+  assert.deepEqual(r, { status: 201, code: null, filed: true, queries: 3 },
+    'the grant narrowed a self-join into a request — the knob nothing used to read');
+});
+
+test('public + grant view: the project is there to be looked at; joining is by invite', async () => {
+  for (const joinability of ['open', 'apply', 'invite_only']) {
+    const r = await knock({ visibility: 'public', joinGrant: 'view', joinability });
+    assert.deepEqual(r, { status: 403, code: 'invite_only', filed: false, queries: 0 }, `joinability ${joinability}`);
+  }
+});
+
+// ── private: invite-only, with applications queued for the owner ─────────────
+
+test('private: the application queues for the owner, and no grant re-opens a self-join', async () => {
+  for (const joinGrant of GRANTS) {
+    assert.deepEqual(await knock({ visibility: 'private', joinGrant, joinability: 'open' }),
+      { status: 201, code: null, filed: true, queries: 3 }, `grant ${joinGrant} on an open-enrolment private project`);
+    assert.deepEqual(await knock({ visibility: 'private', joinGrant, joinability: 'apply' }),
+      { status: 201, code: null, filed: true, queries: 3 }, `grant ${joinGrant}`);
+  }
+});
+
+test('private + invite_only: the stricter knob still wins', async () => {
+  assert.deepEqual(await knock({ visibility: 'private', joinGrant: 'full', joinability: 'invite_only' }),
+    { status: 403, code: 'invite_only', filed: false, queries: 0 });
+});
+
+// ── stealth: no application is accepted, and none is stored ──────────────────
+
+test('stealth: every combination is refused at the door, before any query', async () => {
+  for (const joinGrant of GRANTS) {
+    for (const joinability of ['open', 'apply', 'invite_only']) {
+      const r = await knock({ visibility: 'stealth', joinGrant, joinability });
+      assert.deepEqual(r, { status: 403, code: 'invite_only', filed: false, queries: 0 },
+        `stealth + ${joinGrant} + ${joinability}`);
+    }
+  }
+});
+
+test('the refusal never says WHICH knob closed the door — stealth is indistinguishable from the other two', async () => {
+  const stealth = await knock({ visibility: 'stealth', joinGrant: 'full', joinability: 'apply' });
+  const viewOnly = await knock({ visibility: 'public', joinGrant: 'view', joinability: 'apply' });
+  const inviteOnly = await knock({ visibility: 'public', joinGrant: 'full', joinability: 'invite_only' });
+  assert.deepEqual(stealth, viewOnly, 'a stealth project answers exactly as a look-only public one');
+  assert.deepEqual(stealth, inviteOnly, 'and exactly as an ordinary invite-only one (ADR 0182 D2a)');
+});
+
+// ── dark matter ──────────────────────────────────────────────────────────────
+
+test('dark matter: locked outright, whatever the three stored knobs say', async () => {
+  for (const visibility of ['public', 'private', 'stealth']) {
+    const r = await knock({ visibility, joinGrant: 'full', joinability: 'open' }, { publishable: false });
+    assert.deepEqual(r, { status: 403, code: 'not_published', filed: false, queries: 0 }, visibility);
+  }
+});
+
+test('the locked refusal names the PROJECT\'s state, not the applicant\'s — nothing they can retry', async () => {
+  policy = { visibility: 'public', joinGrant: 'full', joinability: 'apply' };
+  publishable = false;
+  script = [];
+  calls = [];
+  const r = await post('/api/gds/access-requests', { github_login: 'octocat' });
+  assert.equal(r.status, 403);
+  assert.match(r.json.error.message, /isn’t published yet/);
+  assert.doesNotMatch(r.json.error.message, /sign in|invite/i, 'it offers no way in, because there is none yet');
+});
+
+// ── the refusal costs nothing, and reveals nothing ───────────────────────────
+
+test('every refusal answers before the body is even validated — no applicant lookup, no oracle', async () => {
+  for (const [code, status] of Object.entries(REFUSED)) {
+    const closed = code === 'not_published'
+      ? { policy: { visibility: 'public', joinGrant: 'full', joinability: 'apply' }, verdict: false }
+      : code === 'open_enrollment'
+        ? { policy: { visibility: 'public', joinGrant: 'full', joinability: 'open' }, verdict: undefined }
+        : { policy: { visibility: 'stealth', joinGrant: 'full', joinability: 'apply' }, verdict: undefined };
+    policy = closed.policy;
+    publishable = closed.verdict;
+    script = [];
+    calls = [];
+    // A body that would 400 on a working door: the refusal must come first.
+    const r = await post('/api/gds/access-requests', { github_login: 'not a login!' });
+    assert.equal(r.status, status, code);
+    assert.equal(r.json.error.code, code);
+    assert.equal(calls.length, 0, `${code} consulted the database`);
+  }
+});