@bongos/core 1.19.567 → 1.19.569

package/src/bongos/project-door.js

@@ -27,6 +27,15 @@
 // plus `publishable`, which is DERIVED and never stored (ADR 0182 D1/D4: a project
 // with no name or no description is "dark matter" — off the map and un-joinable).
 //
+// THE KNOB READERS LIVE HERE TOO. `joinabilityMode()` moved in from
+// src/bongos/auth-admission.js (task 1003579, ADR 0256). It was born in the
+// admission gate (ADR 0194) because the gate was its only caller; once the gate
+// started reading the COMPOSED door instead of that one knob, leaving the reader
+// on the far side would have made this file require the whole admission gate back
+// to answer one question — the two files pointing at each other. The composer owns
+// its inputs and the gate reads the answer, so the dependency runs one way.
+// auth-admission re-exports the name, so every existing import still resolves.
+//
 // THE REFUSAL NEVER NAMES THE STATE. `stealth`, `public`+`view`, and an explicit
 // `invite_only` all answer with the SAME door, so a refusal can never be read
 // backwards to learn which state a project is in. That is not a nicety: ADR 0182
@@ -42,6 +51,12 @@
 
 'use strict';
 
+// The ONE non-lazy require in this file. logger.js pulls in pino and node
+// built-ins and nothing else — no branding pack, no env, no database — so it does
+// not cost the pure half its "importable with nothing behind it" property, which
+// is why every OTHER require here is still deferred to call time.
+const log = require('./logger').logger.child({ src: 'project-door' });
+
 // The door vocabulary, ORDERED widest → strictest. The order IS the composition
 // rule: two knobs never negotiate, the higher index simply wins.
 const JOIN_DOORS = Object.freeze(['open', 'apply', 'invite_only', 'locked']);
@@ -102,13 +117,70 @@ function projectJoinDoor({ visibility, joinGrant, joinability, publishable = nul
   return strictestDoor(ceiling, JOINABILITY_DOOR[joinability] || 'invite_only');
 }
 
+// The legacy OPEN_XENOS_ENROLLMENT escape hatch (ADR 0050). It still opens an
+// *apply* project, so a self-hosted instance that set it keeps its open door
+// across the upgrade — but it never reopens an explicit `invite_only`: the
+// stricter, newer choice wins.
+function legacyOpenEnrollmentFlag() {
+  const ic = require('../instance-config'); // eslint-disable-line global-require
+  const v = ic.resolveEnv('OPEN_XENOS_ENROLLMENT');
+  return v === '1' || v === 'true';
+}
+
+// joinabilityMode — the project's stored membership door policy, and ONLY that:
+// 'open' | 'apply' | 'invite_only' (ADR 0194). The one reader for the knob, so
+// the manifest's read-back, the hall's door copy and the refusal pages cannot
+// disagree about what the owner set:
+//
+//   open         a first-time GitHub sign-in self-enrols at xenos — no request,
+//                no invite (what OTB_OPEN_XENOS_ENROLLMENT used to switch on)
+//   apply        (the default — today's behaviour) a stranger files an access
+//                request and an Archon marks it 'invited'; then sign-in admits
+//   invite_only  the public application endpoint refuses; only an access request
+//                an Archon CREATED at 'invited' admits a first-timer
+//
+// IT IS NOT THE DOOR. `projectJoinDoor` below may narrow this further, and since
+// task 1003579 every surface that DECIDES whether someone gets in — the public
+// application endpoint and the sign-in gate both — reads that composed answer
+// instead. Read this one only where the question really is "what did the owner
+// set?"; reading it to admit someone is the drift ADR 0247 was written against.
+//
+// An unreadable pack, or a value this core cannot read, fails CLOSED to
+// `invite_only`: when the door's policy is unknown the widest door is never the
+// fallback (ADR 0192). The `[auth]` log prefix is kept verbatim across the move —
+// operators grep sign-in refusals by it, and the child logger's `src` already
+// says which file emitted the line. `read` is injectable for the unit tests only
+// (the pack is memoized for the process).
+let warnedUnknownJoinability = false;
+function joinabilityMode(read) {
+  const readPack = read || require('../branding').branding; // eslint-disable-line global-require
+  let v;
+  try { v = readPack().project?.joinability; } catch (err) {
+    log.error('[auth] joinability: branding pack unreadable — treating the project as invite-only:', err.message);
+    return 'invite_only';
+  }
+  if (v === 'open' || v === 'invite_only') return v;
+  if (v === undefined || v === null || v === '' || v === 'apply') {
+    return legacyOpenEnrollmentFlag() ? 'open' : 'apply';
+  }
+  // A value this core cannot read ('invite-only' with a hyphen, a truncated
+  // write) is a policy it does not know — never the wider door.
+  if (!warnedUnknownJoinability) {
+    warnedUnknownJoinability = true;
+    log.error(`[auth] joinability: unrecognised value ${JSON.stringify(v)} — treating the project as invite-only`);
+  }
+  return 'invite_only';
+}
+
 // effectiveJoinDoor — this project's LIVE door: projectJoinDoor() over the policy
 // this instance actually resolved. The one call a door surface makes; published
 // through the module doorway as `api.projectJoinDoor()` so a module never
 // re-derives the composition (the drift `joinabilityMode` exists to prevent).
 //
 // The requires are deliberately lazy: this file's pure half must stay importable by
-// a test with no branding pack, no env and no database behind it.
+// a test with no branding pack, no env and no database behind it. The joinability
+// reader is now a local function rather than a require of the admission gate, which
+// is what lets the gate read this door without the two files forming a cycle.
 //
 // A pack that will not load leaves BOTH visibility and the grant unknown, and
 // `visibilityCeiling` answers that with `invite_only` — the same fail-closed door
@@ -116,7 +188,7 @@ function projectJoinDoor({ visibility, joinGrant, joinability, publishable = nul
 // something that reader had already closed.
 function effectiveJoinDoor(deps = {}) {
   const readBranding = deps.branding || require('../branding').branding; // eslint-disable-line global-require
-  const readJoinability = deps.joinabilityMode || require('./auth-admission').joinabilityMode; // eslint-disable-line global-require
+  const readJoinability = deps.joinabilityMode || joinabilityMode;
   let project = {};
   try { project = readBranding().project || {}; } catch { project = {}; }
   return projectJoinDoor({
@@ -133,6 +205,7 @@ module.exports = {
   PROJECT_JOIN_GRANTS,
   strictestDoor,
   visibilityCeiling,
+  joinabilityMode,
   projectJoinDoor,
   effectiveJoinDoor,
 };

package/src/bongos/routes/auth.js

@@ -31,6 +31,10 @@ const crypto = require('node:crypto');
 
 const auth = require('../auth');
 const { reportActivityRollupForShippedTask } = require('../auth-admission.js');
+// task 1003579: the sign-in refusal page names the door the project actually
+// runs, so it cannot offer an application form to a project whose application
+// endpoint refuses. Same composed answer the gate itself reads.
+const { effectiveJoinDoor } = require('../project-door.js');
 const db = require('../db');
 const { pairStore } = require('../app-pair');
 const { publicOrigin, parseCookie, validateOrRespond } = require('./_helpers');
@@ -705,10 +709,19 @@ module.exports = function buildAuthRouter() {
         // approval brings them back to it — the return cookie says where.
         const founderReturn = safeReturnTo(parseCookie(req, RETURN_COOKIE)) || '';
         const onWayToProject = founderReturn.startsWith('/projects');
-        // An invite-only project (task 1003044) takes no applications: say so,
-        // and name the one way in — an invite from the admitter — instead of
-        // sending a stranger to a request form the project refuses.
-        if (auth.joinabilityMode() === 'invite_only') {
+        // A project that takes no applications says so, and names the one way in
+        // — an invite from the admitter — instead of sending a stranger to a
+        // request form the project will refuse (task 1003044).
+        //
+        // The test is the COMPOSED door, not the `joinability` knob (task 1003579):
+        // `apply` is the only door that accepts an application, so `stealth` and a
+        // `view` grant must land on this page too, or the refusal hands a stranger
+        // a form the application endpoint 403s. Both closed doors show the SAME
+        // sentence, which is the point — a refusal that distinguished them would
+        // be the state read-out ADR 0247 D3 forbids. `open` cannot reach here (the
+        // gate would have admitted) and `locked` cannot fire at all (no publish
+        // verdict is passed, ADR 0247 D4), so this is `invite_only` in practice.
+        if (effectiveJoinDoor() !== 'apply') {
           return res.status(403).type('text/html').send(renderAuthErrorPage(
             'This project is invite-only',
             `Signing in with GitHub is only for builders the ${admitterLabel()} has invited. This project doesn’t take applications, so there is nothing to request here. If you know the ${admitterLabel()}, ask them for an invite — once you’re invited, this sign-in lets you in.`,

package/src/bongos/routes/instance.js

@@ -124,6 +124,13 @@ module.exports = function buildInstanceRouter() {
       rankTier: RANK_TIER,
       repo: loadRepoInfo(),
       authConfigured: authConfigured(),
+      // The COMPOSED join door, not the raw `joinability` knob (task 1003579):
+      // `admission.policy` says whether a stranger can actually sign themselves
+      // in, so a project that is off the map reports 'invite-only' even while its
+      // `joinability` reads back 'open' under brand.project. The two fields answer
+      // different questions on purpose — one is the owner's setting, the other is
+      // what the gate will do — and 'invite-only' already covers every non-open
+      // door, so narrowing it names no state (ADR 0247 D3).
       openEnrollment: openEnrollmentEnabled(),
       devBoxEnabled: isModuleEnabled('dev-box'),
       // Project OUT the client secret — the manifest is public; only origin +

package/src/branding.js

@@ -220,7 +220,8 @@ function clientBranding(b = branding()) {
     // the honest place to learn what it RESOLVED from its environment is its own
     // GET /instance manifest. Enforced on the instance by the platform-visibility
     // gate (task 1003043, ADR 0192) and the admission machinery (task 1003044,
-    // ADR 0194 — joinabilityMode() in auth-admission.js).
+    // ADR 0194 — joinabilityMode() in project-door.js, which composes it with
+    // visibility + joinGrant into the one door every admission surface reads).
     project: {
       platformVisibility: b.project?.platformVisibility || 'public',
       joinability: b.project?.joinability || 'apply',

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.567'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.569'; // 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/admission_ceiling_gate.mjs

@@ -0,0 +1,203 @@
+// tests/admission_ceiling_gate.mjs — the visibility ceiling reaches the SIGN-IN
+// gate, not only the application door (task 1003579, goal 1000046; ADR 0256).
+//
+// THE BUG THIS PINS. ADR 0247 composed the project's join door — visibility ×
+// joinGrant × joinability — and enforced it at the public application endpoint,
+// but left `openEnrollmentEnabled()` reading the `joinability` knob alone. So an
+// owner who took their project off the map (`visibility: private`, or `stealth`,
+// or `joinGrant: view`) while leaving `joinability: open` got a door that queued
+// applications for review and a sign-in that still handed any first-time GitHub
+// account a xenos account. Half of ADR 0182 D6's table — its whole "Self-join"
+// column — was unenforced wherever the owner had explicitly opened enrolment.
+//
+// The boot half sets the knobs the way production does: <PREFIX>_VISIBILITY and
+// <PREFIX>_JOINABILITY in the environment, read once through the memoized
+// branding pack, which is exactly what the provisioning runner writes into
+// web.env before restarting the service (ADR 0190). `private` + `open` is the
+// precise pair ADR 0247's "KNOWN LIMIT" paragraph named.
+//
+// The sweep half drives effectiveJoinDoor's injection seam across every knob
+// combination and asserts the gate is the door EVERYWHERE, not just at the one
+// booted point — the property that makes this a fix rather than a special case.
+//
+// DB-free: every decision under test answers from the pack and the pure
+// composition, before any lookup. Run:  node --test tests/admission_ceiling_gate.mjs
+
+import assert from 'node:assert/strict';
+import { test, before, after } from 'node:test';
+import http from 'node:http';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+// Set BEFORE the first require that could read branding(): the pack is memoized
+// and deep-frozen for the process lifetime, which is why a real instance applies
+// one of these with a restart rather than a re-read.
+process.env.CLOUDBONGOS_VISIBILITY = 'private';
+process.env.CLOUDBONGOS_JOINABILITY = 'open';
+// The bootstrap owner, so the test can prove the ceiling does not gate them out
+// of their own instance. The neutral pack ships firstAdmin: "" (an unclaimed
+// instance has no owner yet), so it is configured through the documented env
+// override rather than a pack edit.
+const FIRST_ADMIN = 'configured-owner';
+process.env.CLOUDBONGOS_FIRST_ADMIN = FIRST_ADMIN;
+
+const {
+  joinabilityMode, openEnrollmentEnabled, firstTimeAdmissionBlocked, firstAdminLogin,
+} = require('../src/bongos/auth-admission.js');
+const { effectiveJoinDoor, projectJoinDoor } = require('../src/bongos/project-door.js');
+const platformMod = require('../src/platform-server.js');
+
+// ---------------------------------------------------------------------------
+// The booted instance: private on the map, enrolment explicitly open.
+
+test('the stored knob still reads back exactly what the owner set', () => {
+  // The composition may narrow what the door DOES; it may never rewrite what the
+  // owner chose, or the manage page's "did my save take effect?" read-back lies
+  // (ADR 0194 D1 — the reason the ceiling is composed on the instance instead of
+  // folded into the pushed value at the platform).
+  assert.equal(joinabilityMode(), 'open');
+  assert.equal(firstAdminLogin(), FIRST_ADMIN);
+});
+
+test('the application door still queues — private accepts applications', () => {
+  // private's ceiling is `apply`, and `open` cannot widen it back. The door and
+  // the gate are allowed to differ; what they may not do is disagree about the
+  // ceiling, which is the whole bug.
+  assert.equal(effectiveJoinDoor(), 'apply');
+});
+
+test('THE FIX: the sign-in gate obeys the ceiling — a stranger no longer self-enrols', () => {
+  assert.equal(openEnrollmentEnabled(), false, 'private + joinability:open must not self-enrol');
+  assert.equal(
+    firstTimeAdmissionBlocked({ existing: null, approved: false, login: 'stranger' }), true,
+    'a first-time GitHub account is blocked at the gate, not admitted at xenos',
+  );
+});
+
+test('the ceiling narrows SELF-enrolment only — invited, existing and the owner still get in', () => {
+  // An owner taking their project off the map is closing the front door, not
+  // evicting the people they let in. If this ever flips, a `private` project
+  // locks out its own members and its own founder.
+  assert.equal(firstTimeAdmissionBlocked({ existing: null, approved: true, login: 'invited' }), false);
+  assert.equal(firstTimeAdmissionBlocked({ existing: { id: 42 }, approved: false, login: 'member' }), false);
+  assert.equal(firstTimeAdmissionBlocked({ existing: null, approved: false, login: FIRST_ADMIN }), false);
+  assert.equal(firstTimeAdmissionBlocked({ existing: null, approved: false, login: FIRST_ADMIN.toUpperCase() }), false);
+});
+
+test('the gate IS the door — one decision, not two that happen to agree', () => {
+  assert.equal(openEnrollmentEnabled(), effectiveJoinDoor() === 'open');
+});
+
+// ---------------------------------------------------------------------------
+// The manifest, from the real booted app.
+
+let server;
+let port;
+before(async () => {
+  server = http.createServer(platformMod.buildPlatformApp());
+  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 request(pathname) {
+  return new Promise((resolve, reject) => {
+    const req = http.request({ host: '127.0.0.1', port, path: pathname, method: 'GET' }, (res) => {
+      let data = '';
+      res.on('data', (c) => { data += c; });
+      res.on('end', () => resolve({ status: res.statusCode, body: data }));
+    });
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+test('booted: the manifest reports the GATE, while the brand block reports the SETTING', async () => {
+  const res = await request('/api/bongos/instance');
+  assert.equal(res.status, 200);
+  const m = JSON.parse(res.body);
+  // The owner's settings, unchanged — a client can still say what the owner chose.
+  assert.equal(m.brand.project.visibility, 'private');
+  assert.equal(m.brand.project.joinability, 'open');
+  // ...and admission.policy now answers the different question it always claimed
+  // to: can a stranger sign themselves in? Before this task it said 'open' here
+  // and the CLI believed it.
+  assert.equal(m.admission.policy, 'invite-only');
+});
+
+test('booted: the refusal names no state — every closed door reports the same word', async () => {
+  // 'invite-only' is what an `apply` project has always reported, so narrowing a
+  // private project into it adds no way to tell private, stealth, a `view` grant
+  // and a plain invite-only project apart from the manifest (ADR 0247 D3 —
+  // stealth's anonymity is a privacy primitive, not a nicety).
+  const m = JSON.parse((await request('/api/bongos/instance')).body);
+  const closed = ['apply', 'invite_only'].map((j) => (effectiveJoinDoor({
+    branding: () => ({ project: { visibility: 'public', joinGrant: 'full' } }),
+    joinabilityMode: () => j,
+  }) === 'open' ? 'open' : 'invite-only'));
+  assert.deepEqual([...new Set([...closed, m.admission.policy])], ['invite-only']);
+});
+
+// ---------------------------------------------------------------------------
+// The sweep: the gate equals the door across the whole knob space.
+
+const VISIBILITIES = ['public', 'private', 'stealth', 'unlisted', undefined];
+const GRANTS = ['full', 'apply', 'view', 'FULL', undefined];
+const JOINABILITIES = ['open', 'apply', 'invite_only'];
+
+const packOf = (visibility, joinGrant) => () => ({ project: { visibility, joinGrant } });
+
+test('every knob combination: openEnrollmentEnabled === (the composed door is open)', () => {
+  let checked = 0;
+  for (const visibility of VISIBILITIES) {
+    for (const joinGrant of GRANTS) {
+      for (const joinability of JOINABILITIES) {
+        const gate = openEnrollmentEnabled({
+          branding: packOf(visibility, joinGrant), joinabilityMode: () => joinability,
+        });
+        const door = projectJoinDoor({ visibility, joinGrant, joinability });
+        assert.equal(
+          gate, door === 'open',
+          `drift: visibility=${visibility} grant=${joinGrant} joinability=${joinability} → gate=${gate} door=${door}`,
+        );
+        checked++;
+      }
+    }
+  }
+  assert.equal(checked, VISIBILITIES.length * GRANTS.length * JOINABILITIES.length);
+});
+
+test('exactly ONE combination self-enrols: on the map, granting membership, open', () => {
+  // The inverse statement of the sweep, written out so a future widening of any
+  // one knob's table fails here loudly instead of quietly admitting strangers.
+  const opened = [];
+  for (const visibility of VISIBILITIES) {
+    for (const joinGrant of GRANTS) {
+      for (const joinability of JOINABILITIES) {
+        if (openEnrollmentEnabled({ branding: packOf(visibility, joinGrant), joinabilityMode: () => joinability })) {
+          opened.push([visibility, joinGrant, joinability].join('/'));
+        }
+      }
+    }
+  }
+  assert.deepEqual(opened, ['public/full/open']);
+});
+
+test('a pack that will not load fails CLOSED at the gate, exactly as it does at the door', () => {
+  const boom = () => { throw new Error('pack unreadable'); };
+  assert.equal(openEnrollmentEnabled({ branding: boom, joinabilityMode: () => 'open' }), false);
+  assert.equal(openEnrollmentEnabled({ branding: () => ({}), joinabilityMode: () => 'open' }), false,
+    'a pack with no project block is not a public project by default');
+});
+
+test('the gate forwards a publish verdict when its caller holds one', () => {
+  // Nothing in the sign-in path passes one today — this plane holds no
+  // trustworthy dark-matter verdict yet (ADR 0247 D4) — but the seam is the
+  // door's own, so wiring the verdict later is one argument, not a redesign.
+  const pack = packOf('public', 'full');
+  assert.equal(openEnrollmentEnabled({ branding: pack, joinabilityMode: () => 'open', publishable: false }), false);
+  assert.equal(openEnrollmentEnabled({ branding: pack, joinabilityMode: () => 'open', publishable: true }), true);
+});

package/tests/joinability_invite_only.mjs

@@ -158,7 +158,13 @@ const src = (rel) => fs.readFileSync(path.join(ROOT, rel), 'utf8');
 
 test('the web sign-in refusal names the invite-only door instead of sending a stranger to a request form', () => {
   const auth = src('src/bongos/routes/auth.js');
-  assert.match(auth, /auth\.joinabilityMode\(\) === 'invite_only'/);
+  // task 1003579: the branch tests the COMPOSED door, not the `joinability` knob.
+  // `apply` is the only door that accepts an application, so a project closed by
+  // its VISIBILITY ceiling (stealth, or a `view` grant, with `joinability` still
+  // reading `apply`) lands on this page too instead of being handed a request form
+  // the application endpoint refuses. Both closed doors show the same sentence,
+  // which is ADR 0247 D3 — a refusal may not be read backwards into a state.
+  assert.match(auth, /effectiveJoinDoor\(\) !== 'apply'/);
   assert.match(auth, /'This project is invite-only'/);
   assert.match(auth, /doesn’t take applications/);
 });