@bongos/core 1.19.532 → 1.19.534

package/src/bongos/project-door.js

@@ -0,0 +1,138 @@
+// src/bongos/project-door.js — THE project's join/apply door, composed from every
+// knob that can close it (BV1.R12, task 1002331; ADR 0182 D6, ADR 0247).
+//
+// WHAT IT ANSWERS: "a stranger has arrived at this project's door — what happens?"
+// One value, so no two surfaces can answer it differently:
+//
+//   open         no request needed; signing in is the way in
+//   apply        an application is accepted and queued for the owner
+//   invite_only  no application is taken; an invite is the only way in
+//   locked       nothing — the project is not published, so there is no door
+//
+// WHY IT EXISTS. Three separate owner-set knobs each narrow the same door, and
+// before this file only one of them (`joinability`) was read at the door — so an
+// owner could set their project `private` or `stealth` on the platform's map and
+// still have its public application endpoint behave exactly as before. ADR 0182 D6
+// wrote the composition rule down ("visibility sets the ceiling; join policy may
+// only narrow it; the stricter of the two always wins, and neither can widen the
+// other") and left it unimplemented. This is that rule, as code, in one place.
+//
+// THE THREE KNOBS (all owner-set on the platform, pushed into this instance's
+// branding pack by the provisioning runner, applied by a restart):
+//
+//   visibility   public | private | stealth   how the project stands on the map
+//   joinGrant    view | apply | full          what a PUBLIC join grants (R12)
+//   joinability  open | apply | invite_only   how someone becomes a member (ADR 0194)
+//
+// 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 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
+// D2a makes stealth's anonymity a privacy primitive, and a door that said "this
+// project is stealth" would hand back exactly what the feed redaction protects.
+// A refused application is also never STORED, so a closed project accumulates no
+// queue to leak (D6).
+//
+// FAIL CLOSED. An unreadable value — a truncated env write, a fourth enum value a
+// future release adds, a pack this core cannot parse — is never the wider door.
+// Same rule ADR 0194 D2 applies to `joinability` alone, and the same direction R06
+// took for the feed (an unrecognised visibility draws as a black hole, not a planet).
+
+'use strict';
+
+// 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']);
+const DOOR_RANK = Object.freeze(Object.fromEntries(JOIN_DOORS.map((d, i) => [d, i])));
+
+// What a join of a PUBLIC project grants — the owner's own words from the project
+// interview (BV1.R12). It is a CEILING on the visibility axis, not a second
+// admission policy: `full` means "this axis does not narrow anything", which is
+// why it is the default (DEFAULT_SETTINGS must be today's behaviour).
+const PROJECT_JOIN_GRANTS = Object.freeze(['view', 'apply', 'full']);
+const DOOR_BY_GRANT = Object.freeze({ full: 'open', apply: 'apply', view: 'invite_only' });
+
+// The ceiling each stored visibility state sets (ADR 0182 D6's table). `public` is
+// absent on purpose — it is the one state that defers to the grant.
+const DOOR_BY_VISIBILITY = Object.freeze({ private: 'apply', stealth: 'invite_only' });
+
+// The joinability policies this core can read (ADR 0194). Its own reader is already
+// fail-closed, so this is the guard against a caller that bypassed it.
+const JOINABILITY_DOOR = Object.freeze({ open: 'open', apply: 'apply', invite_only: 'invite_only' });
+
+// The strictest of two doors. PURE. An unknown name is treated as the strictest
+// door there is rather than ignored, so a caller can never widen this by passing
+// a value the table does not carry.
+function strictestDoor(a, b) {
+  const ra = DOOR_RANK[a] === undefined ? DOOR_RANK.locked : DOOR_RANK[a];
+  const rb = DOOR_RANK[b] === undefined ? DOOR_RANK.locked : DOOR_RANK[b];
+  return JOIN_DOORS[Math.max(ra, rb)];
+}
+
+// The ceiling the project's place on the map sets, before `joinability` narrows it
+// (ADR 0182 D6). PURE. `public` hands the answer to the grant; every other value —
+// including one this core does not recognise — is at most `invite_only`.
+function visibilityCeiling(visibility, joinGrant) {
+  if (visibility === 'public') {
+    return DOOR_BY_GRANT[joinGrant] || 'invite_only';
+  }
+  return DOOR_BY_VISIBILITY[visibility] || 'invite_only';
+}
+
+// projectJoinDoor — the whole decision, PURE, from the four inputs a door surface
+// holds. This is the function every join/apply surface must call instead of reading
+// any single knob, so the public application endpoint, the hall's landing form, the
+// CLI and the hub's join relay cannot disagree about which door this project runs.
+//
+// `publishable` is a TRI-STATE and the third value matters: `false` locks the door
+// (dark matter — ADR 0182 D6: "refused — there is no door to knock on"), `true`
+// does not open anything on its own, and `null`/undefined means NO VERDICT — the
+// caller does not hold a publish gate and must not invent one (the same word
+// `provisioning.publishVerdict` uses when the `project.publishGate` port is absent).
+// A caller with no verdict is answered on the three stored knobs alone.
+function projectJoinDoor({ visibility, joinGrant, joinability, publishable = null } = {}) {
+  if (publishable === false) return 'locked';
+  const ceiling = visibilityCeiling(visibility, joinGrant);
+  // An unreadable `joinability` closes to `invite_only`, not to `locked`: its own
+  // reader already chose that value for this failure (ADR 0194 D2), and `locked`
+  // is a specific CLAIM — "this project is not published" — that an unknown policy
+  // is no evidence for. Refusing honestly matters more than refusing hardest.
+  return strictestDoor(ceiling, JOINABILITY_DOOR[joinability] || '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 pack that will not load leaves BOTH visibility and the grant unknown, and
+// `visibilityCeiling` answers that with `invite_only` — the same fail-closed door
+// ADR 0194 D2 chose for the same failure, so this composition never reopens
+// 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
+  let project = {};
+  try { project = readBranding().project || {}; } catch { project = {}; }
+  return projectJoinDoor({
+    visibility: project.visibility,
+    joinGrant: project.joinGrant,
+    joinability: readJoinability(),
+    publishable: deps.publishable === undefined ? null : deps.publishable,
+  });
+}
+
+module.exports = {
+  JOIN_DOORS,
+  DOOR_RANK,
+  PROJECT_JOIN_GRANTS,
+  strictestDoor,
+  visibilityCeiling,
+  projectJoinDoor,
+  effectiveJoinDoor,
+};

package/src/branding.js

@@ -65,6 +65,10 @@ const ENV_OVERRIDES = [
   // this instance's own sign-in door; this one is how the project stands on the
   // platform's map, and D6 makes it the ceiling JOINABILITY may only narrow.
   ['VISIBILITY', ['project', 'visibility']],
+  // What a join of this project grants while it is PUBLIC (BV1.R12, task 1002331) —
+  // view | apply | full. The ceiling on the visibility axis that JOINABILITY may
+  // only narrow; composed into one door by src/bongos/project-door.js.
+  ['JOIN_GRANT', ['project', 'joinGrant']],
 ];
 
 const isObj = (v) => v && typeof v === 'object' && !Array.isArray(v);
@@ -224,6 +228,10 @@ function clientBranding(b = branding()) {
       // two neighbours: it is how the project asks to be seen on the map, and it is
       // the READ-BACK a manage page needs to tell a saved choice from a live one.
       visibility: b.project?.visibility || 'public',
+      // What a public join grants (task 1002331). Public for the same reason: a
+      // stranger's client should be able to say what THIS door does before knocking.
+      // `full` = this axis narrows nothing, so an un-pushed instance is unchanged.
+      joinGrant: b.project?.joinGrant || 'full',
     },
   };
 }

package/src/module-api.js

@@ -15,6 +15,7 @@ const util = require('node:util');
 const { logger: coreLogger } = require('./bongos/logger');
 const { pool, instanceDbName } = require('./bongos/pool');
 const branding = require('./branding');
+const projectDoor = require('./bongos/project-door');
 const instanceConfig = require('./instance-config');
 const staleTimer = require('./stale-timer');
 // Destructured, not namespaced, deliberately — the same form src/bongos/routes/
@@ -45,7 +46,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.532'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.534'; // 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');
@@ -242,6 +243,16 @@ module.exports = {
   //     reader, and the sign-in flows and the public access-request route
   //     must answer with the same door (SR-19).
   joinabilityMode: auth.joinabilityMode,
+  // projectJoinDoor() — the project's COMPOSED join/apply door: 'open' | 'apply' |
+  //     'invite_only' | 'locked' (BV1.R12, task 1002331; ADR 0182 D6, ADR 0247).
+  //     `joinabilityMode` above answers one knob; this answers the whole door,
+  //     because the project's place on the platform's map (`visibility`) and what a
+  //     public join grants (`joinGrant`) each narrow it too, and "the stricter of
+  //     the two always wins" is only true if one function says so. Every join/apply
+  //     surface calls THIS; a module that read a single knob would re-open a door
+  //     the other two had closed. Optional `{ publishable }` for a caller that
+  //     holds a publish verdict — see src/bongos/project-door.js.
+  projectJoinDoor: (opts) => projectDoor.effectiveJoinDoor(opts),
   // userAgent — the instance's HTTP User-Agent string (branding-derived). The
   // carved lifecycle module's github-push.js stamps every GitHub API request with
   // it instead of reaching into src/branding.js directly (BV1.R86).

package/tests/access_requests_invite.mjs

@@ -9,7 +9,7 @@
 // The doorway is stubbed in require.cache BEFORE the route loads (the route
 // destructures pool/validators at require time — the web_admission_status
 // pattern): the session gates admit a fixed Archon, the pool replays a script
-// of results and records every query, and joinabilityMode is a switch.
+// of results and records every query, and projectJoinDoor is a switch.
 //
 // Run:  node --test tests/access_requests_invite.mjs
 
@@ -39,7 +39,7 @@ const pool = {
 require.cache[apiPath].exports = {
   ...realApi,
   pool,
-  joinabilityMode: () => mode,
+  projectJoinDoor: () => mode,
   requireBuilder: (req, _res, next) => { req.builder = { id: 42, github_login: 'archon' }; next(); },
   requirePermission: () => (_req, _res, next) => next(),
 };

package/tests/application_lifecycle.mjs

@@ -252,6 +252,7 @@ require.cache[apiPath].exports = {
   ...realApi,
   pool,
   joinabilityMode: () => 'apply',
+  projectJoinDoor: () => 'apply',
   logger: () => ({ error() {}, warn() {}, info() {}, debug() {} }),
   requireBuilder: (req, _res, next) => { req.builder = { id: 42, github_login: 'owner' }; next(); },
   // requirePermission is NOT stubbed: realApi's own gate is used, so the denial

package/tests/catalog_only_client.mjs

@@ -0,0 +1,242 @@
+// tests/catalog_only_client.mjs — A CATALOG-ONLY CLIENT IS AN IDENTITY, NEVER A CREDENTIAL
+// (task 1003576, ADR 0246). The security half of the catalog bridge.
+//
+// The bridge mints an `platform_identity_sso_clients` row for EVERY control-plane project so
+// the map, the membership directory and `POST /projects/invite` have something to name — a
+// large increase in the number of registered clients. This file is the proof that the row it
+// mints can do nothing but be named: it carries an EMPTY secret_hash and an EMPTY
+// redirect-URI allow-list, and every SSO leg refuses it.
+//
+// Four of the five legs already fail closed on machinery that predates this task —
+// clientSecretValid() on a secretless client, redirectUriAllowed() on an empty allow-list —
+// and that is exactly why those are asserted here rather than assumed: they are load-bearing
+// for a decision made after they were written. The fifth, /sso/device/start, resolved a
+// client from a typed origin and checked NEITHER, so it grew an explicit guard.
+//
+// Also pinned: the invite route stops 404ing for a wizard-made project (task 1003580's
+// GAP 1). Its `project.curate` gate is untouched and is 1003580's own work.
+//
+// DB-free: the real routers driven over loopback, with the data-access functions stubbed on
+// the cached module objects (the provisioning_settings.mjs pattern).
+//
+// Run:  node --test --test-reporter=tap tests/catalog_only_client.mjs
+
+import assert from 'node:assert/strict';
+import { test, after } 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 catalog = require('../modules/platform-identity/project-catalog.js');
+const hubKeys = require('../modules/platform-identity/hub-keys.js');
+const hubDevice = require('../modules/platform-identity/hub-device.js');
+const api = require('../src/module-api.js');
+
+// The row the bridge writes: named, active, and holding nothing it could authenticate with.
+const CATALOG_ONLY = 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',
+});
+// A real federated client, for the contrast — the same shape with a credential.
+const FEDERATED = Object.freeze({
+  ...CATALOG_ONLY, client_id: 'mercury', secret_hash: 'a'.repeat(64),
+  redirect_uris: ['https://mercury.test/api/gds/auth/web/callback'], origin: 'https://mercury.test',
+});
+
+// ── the predicate itself ─────────────────────────────────────────────────────
+
+test('clientIsCredentialed separates "the hub can name it" from "it may sign people in"', () => {
+  assert.equal(catalog.clientIsCredentialed(FEDERATED), true);
+  assert.equal(catalog.clientIsCredentialed(CATALOG_ONLY), false);
+  for (const secret_hash of [null, undefined, '']) {
+    assert.equal(catalog.clientIsCredentialed({ ...FEDERATED, secret_hash }), false);
+  }
+  assert.equal(catalog.clientIsCredentialed(null), false, 'no client is not a credentialed one');
+});
+
+test('clientSecretValid fails closed on a secretless client, whatever is presented', () => {
+  // The load-bearing pre-existing guard: it hashes and constant-time-compares against a decoy
+  // when there is no real secret, then refuses because there was none. So the empty string,
+  // the literal decoy input and a lucky guess all lose.
+  for (const presented of ['', 'anything', 'a'.repeat(64), 'spike-harbor']) {
+    assert.equal(pi.clientSecretValid(CATALOG_ONLY, presented), false);
+  }
+  assert.equal(pi.clientSecretValid(FEDERATED, 'wrong'), false, 'and a real client still needs the real secret');
+});
+
+test('redirectUriAllowed fails closed on an empty allow-list', () => {
+  assert.equal(pi.redirectUriAllowed(CATALOG_ONLY, 'https://spike-harbor.cloudbongos.test/api/gds/auth/web/callback'), false);
+  assert.equal(pi.redirectUriAllowed(CATALOG_ONLY, ''), false);
+  assert.equal(pi.redirectUriAllowed(FEDERATED, FEDERATED.redirect_uris[0]), true);
+});
+
+// ── the routes, executed ─────────────────────────────────────────────────────
+
+// The auth middleware is DESTRUCTURED off the doorway at route-module load, so these stubs
+// have to be in place before the routers are required.
+api.requireBuilder = (req, _res, next) => { req.builder = { id: 7, github_login: 'curator', rank: 'metic' }; next(); };
+api.requirePermission = () => (_req, _res, next) => next();
+
+const express = require('express');
+const ssoRoutes = require('../modules/platform-identity/routes/sso.js');
+const projectsRoutes = require('../modules/platform-identity/routes/projects.js');
+
+// The routes read the hub's own config through these; the SSO legs 503 without them, which
+// would hide the refusals under test.
+hubKeys.hubSigningConfigured = () => true;
+hubKeys.hubPublicKeyB64 = () => 'stub-public-key';
+hubDevice.hubDeviceConfigured = () => true;
+let deviceStarts = 0;
+hubDevice.startHubGithubDevice = async () => { deviceStarts++; return { device_code: 'd', user_code: 'U' }; };
+
+// The client registry, stubbed on the cached module object.
+const CLIENTS = new Map([[CATALOG_ONLY.client_id, CATALOG_ONLY], [FEDERATED.client_id, FEDERATED]]);
+pi.getClient = async (id) => CLIENTS.get(id) || null;
+pi.getClientByOrigin = async (origin) => {
+  const norm = String(origin || '').replace(/\/+$/, '');
+  return [...CLIENTS.values()].find((c) => c.origin === norm && c.status === 'active') || null;
+};
+// The invite leg's two other reads — the point is which refusal the route reaches, not what
+// a real membership write does.
+pi.getAccountByLogin = async (login) => (login === 'ghost' ? null : { github_id: 5150, github_login: login });
+pi.inviteToProject = async ({ clientId, githubId }) => ({ invited: true, clientId, githubId });
+
+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', ssoRoutes());
+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 call(method, path, body) {
+  return new Promise((resolve, reject) => {
+    const payload = body === undefined ? null : JSON.stringify(body);
+    const req = http.request(`${base}${path}`, {
+      method,
+      headers: payload ? { '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 { /* html */ } resolve({ status: res.statusCode, body: j, raw: d }); });
+    });
+    req.on('error', reject);
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
+test('/sso/authorize REFUSES a catalog-only client — no redirect_uri is registered for it', async () => {
+  // The open-redirect guard doing double duty: an empty allow-list means every candidate
+  // callback fails exact match, so the browser leg never mints a code and never redirects.
+  const uri = 'https://spike-harbor.cloudbongos.test/api/gds/auth/web/callback';
+  const res = await call('GET', `/sso/authorize?client_id=spike-harbor&redirect_uri=${encodeURIComponent(uri)}`);
+  assert.equal(res.status, 400);
+  assert.match(res.raw, /redirect_uri is not registered/);
+  assert.doesNotMatch(res.raw, /code=/, 'no authorization code may appear on any refusal path');
+});
+
+test('/sso/token REFUSES a catalog-only client for every secret it could be handed', async () => {
+  for (const client_secret of ['', 'guess', 'spike-harbor', 'a'.repeat(64)]) {
+    const res = await call('POST', '/sso/token', {
+      client_id: 'spike-harbor', client_secret: client_secret || 'x',
+      code: 'c', redirect_uri: 'https://spike-harbor.cloudbongos.test/api/gds/auth/web/callback',
+    });
+    assert.equal(res.status, 401, `secret "${client_secret}" must not exchange`);
+    assert.equal(res.body.error.code, 'invalid_client');
+  }
+});
+
+test('/sso/device/start REFUSES a catalog-only origin — the leg that checked neither guard', async () => {
+  // This is the ONE that needed new code. It resolves the client from the USER-TYPED origin
+  // and checked only `status`, so without the guard every catalogued project would have had a
+  // device flow nobody registered a credential for.
+  deviceStarts = 0;
+  const res = await call('POST', '/sso/device/start', { origin: 'https://spike-harbor.cloudbongos.test' });
+  assert.equal(res.status, 401);
+  assert.equal(res.body.error.code, 'invalid_client');
+  assert.equal(deviceStarts, 0, 'and the GitHub device flow is never even started');
+});
+
+test('/sso/device/start still serves a real federated client', async () => {
+  // The guard must refuse the new row shape and nothing else.
+  deviceStarts = 0;
+  const res = await call('POST', '/sso/device/start', { origin: 'https://mercury.test' });
+  assert.equal(res.status, 200);
+  assert.equal(res.body.user_code, 'U');
+  assert.equal(deviceStarts, 1);
+});
+
+test('/sso/membership/check-in REFUSES a catalog-only client', async () => {
+  const res = await call('POST', '/sso/membership/check-in', {
+    client_id: 'spike-harbor', client_secret: 'x', github_id: 5150, github_login: 'someone',
+  });
+  assert.equal(res.status, 401);
+  assert.equal(res.body.error.code, 'invalid_client');
+});
+
+test('/sso/activity/rollup REFUSES a catalog-only client', async () => {
+  const res = await call('POST', '/sso/activity/rollup', {
+    client_id: 'spike-harbor', client_secret: 'x', github_id: 5150, credits: 999, rank: 'archon',
+  });
+  assert.equal(res.status, 401);
+  assert.equal(res.body.error.code, 'invalid_client');
+});
+
+// ── what the catalog row DOES buy: a resolvable invite target (task 1003580) ──
+
+test('POST /projects/invite no longer 404s for a wizard-made project', async () => {
+  // GAP 1 of task 1003580: the route resolves its target with getClient() and refused
+  // `unknown_project` because a standalone project was never an sso_clients row at all. It
+  // now is. The route's `project.curate` gate is deliberately untouched — widening it to the
+  // project's own owner is 1003580's job, and this test stubs the permission middleware so
+  // the assertion is about the TARGET resolving, not about who may call it.
+  const res = await call('POST', '/projects/invite', { client_id: 'spike-harbor', github_login: 'someone' });
+  assert.notEqual(res.status, 404);
+  assert.equal(res.status, 201);
+  assert.equal(res.body.invited, true);
+  assert.equal(res.body.clientId, 'spike-harbor');
+});
+
+test('an unknown project still 404s — the catalog row is what resolves, not the route', async () => {
+  const res = await call('POST', '/projects/invite', { client_id: 'never-provisioned', github_login: 'someone' });
+  assert.equal(res.status, 404);
+  assert.equal(res.body.error.code, 'unknown_project');
+});
+
+// ── the seam the write half travels on ───────────────────────────────────────
+
+test('mounting the projects routes registers the `project.catalog` port', async () => {
+  // The write half of the same seam `project.publishGate` is the read half of. provisioning
+  // owns these projects and may not import this module (ADR 0083), so the switchboard is how
+  // the projection reaches the tables that hold the map.
+  assert.equal(api.hasProvider('project.catalog'), true);
+  assert.equal(api.resolve('project.catalog'), catalog.projectCatalogPort);
+  assert.equal(typeof api.resolve('project.catalog').publish, 'function');
+  assert.ok(Object.isFrozen(catalog.projectCatalogPort), 'a consumer must not be able to re-point the port');
+});
+
+test('the port declares the catalog write and nothing else', () => {
+  // One verb. A consumer maps its own row onto the entry shape, so the catalog never learns
+  // another module’s schema and no module gets a general-purpose handle on these tables.
+  assert.deepEqual(Object.keys(catalog.projectCatalogPort), ['publish']);
+});
+
+test('the module manifest DECLARES the port it registers', async () => {
+  // verifyPortsSatisfied reads the manifests at boot, not the registry — an undeclared
+  // provider is invisible to it.
+  const manifest = JSON.parse(await (await import('node:fs/promises')).readFile(
+    new URL('../modules/platform-identity/module.json', import.meta.url), 'utf8'));
+  assert.ok(manifest.provides.includes('project.catalog'));
+});

package/tests/currency_label.mjs

@@ -48,11 +48,14 @@ test('R57: clientBranding exposes theme.ui (web), NOT theme.palette (server-only
 });
 
 test('clientBranding exposes project policy — the settings read-back (task 1003140), defaulting to today\'s behavior', () => {
-  // `visibility` — the join door — joined the block in task 1002324 (ADR 0182 D1)
-  assert.deepEqual(clientBranding({}).project, { platformVisibility: 'public', joinability: 'apply', visibility: 'public' });
+  // `visibility` — the join door — joined the block in task 1002324 (ADR 0182 D1);
+  // `joinGrant` — what a PUBLIC join grants — in task 1002331 (ADR 0247), defaulting
+  // to `full`, the value that narrows nothing, so an un-pushed instance is unchanged
+  assert.deepEqual(clientBranding({}).project,
+    { platformVisibility: 'public', joinability: 'apply', visibility: 'public', joinGrant: 'full' });
   assert.deepEqual(
-    clientBranding({ project: { platformVisibility: 'gated', joinability: 'invite_only', visibility: 'stealth' } }).project,
-    { platformVisibility: 'gated', joinability: 'invite_only', visibility: 'stealth' },
+    clientBranding({ project: { platformVisibility: 'gated', joinability: 'invite_only', visibility: 'stealth', joinGrant: 'view' } }).project,
+    { platformVisibility: 'gated', joinability: 'invite_only', visibility: 'stealth', joinGrant: 'view' },
     'what the instance actually resolved (env override included) is what it publishes');
 });
 
@@ -71,7 +74,7 @@ test('clientBranding is a SMALL allow-list — no server-only field leaks to the
   // `project` joined the allow-list in task 1003140: the per-project policy is public
   // by nature and is the settings read-back a manage page needs (see clientBranding).
   assert.deepEqual(Object.keys(projected).sort(), ['copy', 'currency', 'identity', 'project', 'rankLabels', 'reward', 'theme']);
-  assert.deepEqual(Object.keys(projected.project).sort(), ['joinability', 'platformVisibility', 'visibility']);
+  assert.deepEqual(Object.keys(projected.project).sort(), ['joinGrant', 'joinability', 'platformVisibility', 'visibility']);
   for (const leak of ['domains', 'repo', 'db', 'envPrefix', 'llmProjectName']) {
     assert.equal(projected[leak], undefined, `${leak} must not reach the client`);
   }

package/tests/module_api.mjs

@@ -36,6 +36,7 @@ const PUBLISHED_SURFACE = [
   'resolveStaleClaimHours', 'staleClaimMinutes', // added by task 1003476 (ADR 0226; goal 1000072): the PROJECT's stale-claim timer — the sweep that releases a silent claim and the Archon roster that reports one read the same number through here, after eighteen hours of disagreeing (6 vs 24)
   'resolveRotDays', 'projectSettings', // added by task 1003279 (ADR 0232; goal 1000072): the ROT timer + the live knob store behind it. A DIFFERENT question from the stale-claim timer above — days not hours, DB not env, work nobody picked up rather than a builder who went quiet, and it only ever ASKS a human where that one ACTS. Both ride the doorway so no module hardcodes either.
   'joinabilityMode', // added by task 1003044 (ADR 0194; the carrier after 1.19.374): the project's membership door, one reader for the sign-in gate AND the onboarding module's public POST
+  'projectJoinDoor', // added by task 1002331 (ADR 0182 D6 / ADR 0247): the COMPOSED join/apply door — visibility × join grant × joinability, one answer, so a module reading a single knob cannot re-open a door the other two closed
   'enabledDisciplines', // BV1.R81: instance offered-disciplines (1.9.0; onboarding restock backstop)
   'registerProvider', 'hasProvider', 'resolve', 'resolveOptional', 'listPorts', 'verifyPortsSatisfied',
   'on', 'emit', 'emitAsync', 'listEvents', 'seamSnapshot',