@bongos/core 1.19.331 → 1.19.333

package/modules/hall-ui/public/index.html

@@ -117,6 +117,12 @@
 <!-- ADR 0112 (task 1954): the home-page goal-membership inbox — invitations to
      accept + join-requests to approve. Self-registers; hidden when empty. -->
 <script src="/builders/goal-inbox.js?v=2026-07-10-goal-inbox" defer></script>
+<!-- task 1003206: the hall RENDERERS, carved out of builders.js when it crossed
+     the 1,500-line ratchet. Must load BEFORE builders.js, which calls
+     window.OTBHallRender(ctx) once during its own setup. The module
+     hall-widget tags the server injects still anchor on builders.js's tag
+     below (it matches by filename), so they land between the two. -->
+<script src="/builders/hall-render.js?v=2026-08-24-hallrender1" defer></script>
 <script src="/builders/builders.js?v=2026-06-27-r75" defer></script>
 <script src="/builders/copy-on-click.js?v=2026-06-01-copy-1" defer></script>
 </body>

package/modules/lifecycle/routes/goal-route-authz.js

@@ -0,0 +1,400 @@
+// modules/lifecycle/routes/goal-route-authz.js — the PURE authorization
+// predicates behind the goal routes: who may create a task in a goal, change a
+// membership kind, transfer ownership, and open/answer a join request or invite.
+//
+// Carved out of modules/lifecycle/routes/goals.js by task 1003206 (goal 1000079,
+// the R03 de-monolith plan) to bring that router under the 1,500-line ratchet,
+// continuing the carve goal-suggest.js / goal-edits.js began. A STRUCTURAL move:
+// the predicates are unchanged and goals.js re-exports each one, so the routes
+// and the tests that call these directly are untouched.
+
+'use strict';
+
+const api = require('../../../src/module-api');
+const db = require('../db');
+const { isModuleKey, scopeIncludesProtected, moduleKeys } = api.moduleScopeMap;
+const goalScopeCheck = api.goalScopeCheck;
+const { isGoalOwner, authorizeGoalManagement } = require('../goal-authz');
+const METIC_PLUS = ['metic', 'archon'];
+
+async function isMemberOrArchon(builder, goalId) {
+  if (builder.rank === 'archon') return true;
+  return db.isGoalMember({ goalId, builderId: builder.id });
+}
+
+// authorizeGoalTaskCreate — the ORDERED, FAIL-CLOSED authorization decision for
+// POST /goals/:id/tasks (BV1.R60 / ADR 0086 §3): the single point that lets a
+// lower-rank builder author their OWN work safely. PURE + exported (the
+// shouldRefuseSessionClaim precedent in claims.js) so every rejection is pinned
+// by a DB-free unit test AND reused by the BV1.R61 abuse matrix — no live route
+// or DB needed.
+//
+// The route fetches goal / version / membership, then calls this; it rejects on
+// the FIRST failure (fail-closed — a missing/ambiguous input denies):
+//   goal_not_found → goal_not_open → not_a_member → version_not_found →
+//   version_closed → (scope-subset + protected-path, via goalScopeCheck.check).
+// The scope+protected wall is goal-scope-check.check() VERBATIM (R59) — itself
+// ordered + fail-closed (empty-scope → empty-touches → unknown-scope →
+// scope-subset → protected-path) — never re-implemented here. `isMember` is the
+// resolved "member OR Archon" boolean the route computes (isMemberOrArchon).
+//
+// This is the CREATE-time filter: it sees only DECLARED touches[] (advisory — git
+// merge is the real collision detector, ADR 0049), so it is deliberately the FIRST
+// filter, NOT the last. The ship-time gates stay authoritative on the REAL diff
+// (grader permission/route-rank pre-passes + serverSideGuards, gate-review
+// ESCALATE floor, post-push main-audit — ADR 0086 §7). Returns { ok:true } or
+// { ok:false, status, body } (the exact HTTP status + JSON the route sends).
+function authorizeGoalTaskCreate({ goal, version, isMember, builderRank, touches }) {
+  if (!goal) {
+    return { ok: false, status: 404, body: { error: 'goal_not_found' } };
+  }
+  if (goal.status !== 'open') {
+    return { ok: false, status: 409, body: {
+      error: 'goal_not_open', status: goal.status,
+      message: 'Tasks can only be authored under an open goal.',
+    } };
+  }
+  if (!isMember) {
+    return { ok: false, status: 403, body: {
+      error: 'not_a_member',
+      message: 'Join the goal (or be an Archon) to author tasks within it.',
+    } };
+  }
+  if (!version) {
+    return { ok: false, status: 404, body: {
+      error: 'version_not_found',
+      message: `The goal's version '${goal.version_id}' no longer exists.`,
+    } };
+  }
+  if (version.status === 'shipped') {
+    return { ok: false, status: 409, body: {
+      error: 'version_closed',
+      message: `Version '${goal.version_id}' has shipped — it is closed history and cannot take new tasks.`,
+    } };
+  }
+  // The wall — scope-subset + protected-path in one pure call (R59). It bounds
+  // EVERYONE by the goal's modules (scope-subset), and additionally blocks a
+  // sub-Metic member from authoring into the protected core (protected-path),
+  // reusing the SINGLE protected roster (permission-path-check) — no drift.
+  const gate = goalScopeCheck.check(goal.scope_modules, touches, builderRank);
+  if (!gate.ok) {
+    return { ok: false, status: 403, body: {
+      error: gate.code, reason: gate.reason, details: gate.details,
+    } };
+  }
+  return { ok: true };
+}
+
+// The goal AUTHORITY MODEL (owner vs manager) now lives in ../goal-authz.js —
+// isGoalOwner + authorizeGoalManagement are imported at the top of this file and
+// re-exported at the bottom (task 1002538 / ADR 0154).
+
+// authorizeMembershipKindChange — the ORDERED, FAIL-CLOSED authorization decision
+// for PATCH /goals/:id/members/:builderId (task 1735). Today the only assignment
+// path is the Archon admission route; this gate lets the goal's own authority
+// manage memberships without an Archon in the loop:
+//
+// THE FIELD IS `membership_kind` (task 1003013, ADR 0177): ADR 0174 reserves the
+// old word for the three crafts — Artist, Ideator, Builder — and a goal membership
+// is a per-goal position, neither a craft nor a rank.
+
+//   - the owner, a manager, or an Archon may promote member→lead(manager);
+//   - ONLY the owner (or an Archon) may demote lead(manager)→member;
+//   - the OWNER's row can never be demoted — owner authority is created_by, not
+//     the membership value, so a demoted owner row would just lie to the list.
+// PURE + exported (the authorizeGoalTaskCreate precedent above) so every
+// rejection is pinned by a DB-free unit test. The route fetches goal /
+// memberships, then calls this; it rejects on the FIRST failure (fail-closed —
+// a missing/ambiguous input denies):
+//   goal_not_found → goal_not_open → not_owner_or_manager → not_a_member
+//   (target) → no-op same-kind → owner_only_demotion → owner_membership_fixed.
+// Authority (not_owner_or_manager) is checked BEFORE the target lookup so an
+// unauthorized actor never learns who is or isn't a member (the O1 no-leak
+// ordering precedent in the abuse matrix). The DB helper (setGoalMembershipKind)
+// re-asserts the owner-demotion guard atomically in the UPDATE itself — this
+// gate is the testable contract, the SQL guard is the backstop.
+// Returns { ok:true }, { ok:true, noop:true } (already as requested), or
+// { ok:false, status, body } (the exact HTTP status + JSON the route sends).
+function authorizeMembershipKindChange({ goal, actorId, actorRank, actorMembership, targetMembership, targetId, membershipKind }) {
+  if (!goal) {
+    return { ok: false, status: 404, body: { error: 'goal_not_found' } };
+  }
+  if (goal.status !== 'open') {
+    return { ok: false, status: 409, body: {
+      error: 'goal_not_open', status: goal.status,
+      message: 'Memberships can only be changed on an open goal.',
+    } };
+  }
+  const actorIsOwner = isGoalOwner(goal, actorId);
+  const actorIsManager = !!actorMembership && actorMembership.membership_kind === 'lead';
+  if (actorRank !== 'archon' && !actorIsOwner && !actorIsManager) {
+    return { ok: false, status: 403, body: {
+      error: 'not_owner_or_manager',
+      message: 'Only this goal\'s owner or a manager (or an Archon) may change memberships.',
+    } };
+  }
+  if (!targetMembership) {
+    return { ok: false, status: 404, body: {
+      error: 'not_a_member',
+      message: 'That builder is not a member of this goal — admit them first.',
+    } };
+  }
+  if (targetMembership.membership_kind === membershipKind) {
+    return { ok: true, noop: true };
+  }
+  if (membershipKind === 'member') {
+    // A demotion. Managers promote; only the owner (or an Archon) demotes.
+    if (actorRank !== 'archon' && !actorIsOwner) {
+      return { ok: false, status: 403, body: {
+        error: 'owner_only_demotion',
+        message: 'Only the goal owner (or an Archon) may demote a manager.',
+      } };
+    }
+    if (isGoalOwner(goal, targetId)) {
+      return { ok: false, status: 409, body: {
+        error: 'owner_membership_fixed',
+        message: 'The goal owner cannot be demoted — transfer ownership first.',
+      } };
+    }
+  }
+  return { ok: true };
+}
+
+// authorizeOwnershipTransfer — the ORDERED, FAIL-CLOSED decision for
+// POST /goals/:id/transfer (task 1735): the owner hands the goal to another
+// builder (the old owner keeps their manager row). Ownership is creator-
+// equivalent authority and goal CREATION is Metic+ — so the transfer target
+// must be Metic+ too (fail-closed; this also keeps the protected-scope
+// membership wall intact, since a protected-scope goal requires Metic+ members).
+// Ordering: goal_not_found → goal_not_open → not_owner → builder_not_found →
+// metic_required_for_ownership → no-op self-transfer.
+function authorizeOwnershipTransfer({ goal, actorId, actorRank, targetBuilder }) {
+  if (!goal) {
+    return { ok: false, status: 404, body: { error: 'goal_not_found' } };
+  }
+  if (goal.status !== 'open') {
+    return { ok: false, status: 409, body: {
+      error: 'goal_not_open', status: goal.status,
+      message: 'Ownership can only be transferred on an open goal.',
+    } };
+  }
+  if (actorRank !== 'archon' && !isGoalOwner(goal, actorId)) {
+    return { ok: false, status: 403, body: {
+      error: 'not_owner',
+      message: 'Only the goal owner (or an Archon) may transfer ownership.',
+    } };
+  }
+  if (!targetBuilder) {
+    return { ok: false, status: 404, body: { error: 'builder_not_found' } };
+  }
+  if (!METIC_PLUS.includes(targetBuilder.rank)) {
+    return { ok: false, status: 403, body: {
+      error: 'metic_required_for_ownership',
+      message: 'Goal ownership is creator-equivalent authority — the new owner must be Metic+.',
+    } };
+  }
+  if (isGoalOwner(goal, targetBuilder.id)) {
+    return { ok: true, noop: true };
+  }
+  return { ok: true };
+}
+
+// -------------------------------------------------------------------------
+// Private goals: the invite / join-request queue (task 1952 / ADR 0112). A
+// private goal is join-GATED (not hidden): a non-member can't self-join — they
+// are INVITED (a consented, pending row they accept) or REQUEST to join (an
+// owner/manager/Archon approves). Both directions live in goal_membership_requests
+// (kind='invite'|'request'); the resolve is atomic (db.resolveMembershipRequest
+// moves only from status='pending', so a re-submit can't double-add a member).
+// -------------------------------------------------------------------------
+
+// protectedScopeAdmissionBlock — the SINGLE protected-scope admission rule reused
+// by BOTH new admission paths (invite-create and join-request-approve) AND the
+// existing POST /goals/:id/members (whose inline checks this generalizes). A
+// protected-scope goal admits members only via an Archon, and only Metic+ builders
+// — sub-Metic membership inside protected scope is deferred to ADR 0086's Phase-5
+// ADR. Centralized so the protected wall can never drift between paths (the SEC
+// #863 single-roster lesson). Returns { status, body } to send, or null to proceed.
+function protectedScopeAdmissionBlock({ scopeProtected, actorRank, targetRank }) {
+  if (!scopeProtected) return null;
+  if (actorRank !== 'archon') {
+    return { status: 403, body: {
+      error: 'archon_required_for_protected_scope',
+      message: 'This goal is scoped to a protected module; only an Archon may admit members.',
+    } };
+  }
+  if (!METIC_PLUS.includes(targetRank)) {
+    return { status: 403, body: {
+      error: 'metic_required_for_protected_scope',
+      message: 'A protected-scope goal requires a Metic+ member; sub-Metic membership is deferred to the Phase-5 ADR.',
+    } };
+  }
+  return null;
+}
+
+// authorizeCreateJoinRequest — the ORDERED, FAIL-CLOSED gate for
+// POST /goals/:id/requests (task 1952): a builder asks to join. A request only
+// makes sense where self-join is gated — a PUBLIC, NON-protected goal is open-join,
+// so a request there is refused with a "just join" hint. Ordering:
+// goal_not_found → goal_not_open → already_a_member → goal_is_open (public+unprotected).
+// isMember is the caller's own membership; scopeProtected is scopeIncludesProtected(goal).
+// PURE + exported (the authorizeGoalTaskCreate precedent).
+function authorizeCreateJoinRequest({ goal, isMember, scopeProtected }) {
+  if (!goal) return { ok: false, status: 404, body: { error: 'goal_not_found' } };
+  if (goal.status !== 'open') {
+    return { ok: false, status: 409, body: {
+      error: 'goal_not_open', status: goal.status,
+      message: 'You can only request to join an open goal.',
+    } };
+  }
+  if (isMember) {
+    return { ok: false, status: 409, body: {
+      error: 'already_a_member', message: 'You are already a member of this goal.',
+    } };
+  }
+  if (goal.visibility !== 'private' && !scopeProtected) {
+    return { ok: false, status: 409, body: {
+      error: 'goal_is_open',
+      message: 'This goal is open — just join it (POST /goals/:id/join); no request needed.',
+    } };
+  }
+  return { ok: true };
+}
+
+// authorizeInvitationResponse — the ORDERED, FAIL-CLOSED gate for
+// POST /goals/:id/invitations/:reqId/respond (task 1952): ONLY the invited builder
+// may accept/decline their OWN pending invite. Containment first — the row must
+// belong to THIS goal and be an 'invite' — so the invitation route can never touch
+// a join-request row. Ordering: request_not_found → wrong_goal → not_an_invitation
+// → not_pending → not_your_invitation. PURE + exported.
+function authorizeInvitationResponse({ request, goalId, actorId }) {
+  if (!request) return { ok: false, status: 404, body: { error: 'request_not_found' } };
+  if (String(request.goal_id) !== String(goalId)) {
+    return { ok: false, status: 404, body: { error: 'request_not_found', message: 'No such invitation on this goal.' } };
+  }
+  if (request.kind !== 'invite') {
+    return { ok: false, status: 400, body: { error: 'not_an_invitation', message: 'That row is a join-request, not an invitation.' } };
+  }
+  if (request.status !== 'pending') {
+    return { ok: false, status: 409, body: { error: 'not_pending', status: request.status } };
+  }
+  if (String(request.builder_id) !== String(actorId)) {
+    return { ok: false, status: 403, body: {
+      error: 'not_your_invitation',
+      message: 'Only the invited builder may accept or decline this invitation.',
+    } };
+  }
+  return { ok: true };
+}
+
+// authorizeInvitationAccept — the ORDERED, FAIL-CLOSED gate for the ACCEPT half of
+// POST /goals/:id/invitations/:reqId/respond, run against the GOAL after
+// authorizeInvitationResponse has cleared the request row (task 1002887).
+//
+// Accepting is an ADMISSION, so it needs the same goal-state floor every other
+// admission path already has: the create side requires an open goal
+// (authorizeGoalManagement) and the join-request approve side inherits that check
+// verbatim — only invitation-accept was missing it, so an invite issued while a
+// goal was open could still add a member AFTER the goal was achieved or archived.
+// DECLINE is deliberately NOT gated here: clearing a stale invitation out of your
+// inbox is cleanup, not admission (the route returns before calling this).
+// Ordering mirrors the sibling routes: goal_not_found → goal_not_open →
+// metic_required_for_protected_scope (the pre-existing protected-scope membership
+// floor, re-asserted against the ACCEPTING builder's current rank because the goal
+// may have been re-scoped since the invite; the actor-is-Archon half of
+// protectedScopeAdmissionBlock does not apply — the invitee is consenting).
+//
+// Unlike its {status, body} siblings this returns a res.fail SPEC ({ code, status,
+// message, details }) because the accept branch already answers through res.fail —
+// routing it through the envelope keeps the existing metic_required_for_protected_scope
+// response byte-identical while still being PURE + exported for DB-free tests.
+function authorizeInvitationAccept({ goal, scopeProtected, actorRank }) {
+  if (!goal) {
+    return { ok: false, code: 'goal_not_found', status: 404,
+      message: 'The goal behind this invitation no longer exists.' };
+  }
+  if (goal.status !== 'open') {
+    return { ok: false, code: 'goal_not_open', status: 409,
+      message: 'This goal is no longer open — an invitation can only be accepted while it is. You can still decline it.',
+      details: { status: goal.status } };
+  }
+  if (scopeProtected && !METIC_PLUS.includes(actorRank)) {
+    return { ok: false, code: 'metic_required_for_protected_scope', status: 403,
+      message: 'This goal is scoped to a protected module and requires a Metic+ member.' };
+  }
+  return { ok: true };
+}
+
+// authorizeJoinRequestResponse — the gate for POST /goals/:id/requests/:reqId/respond
+// (task 1952): an owner|manager|Archon approves/denies a pending join-request. The
+// authority prefix is authorizeGoalManagement VERBATIM (goal exists/open + owner|
+// manager|Archon — checked BEFORE the request lookup so an unauthorized actor never
+// learns whether a request exists, the O1 no-leak ordering). Then request
+// containment + state: request_not_found → wrong_goal → not_a_join_request →
+// not_pending. PURE + exported.
+function authorizeJoinRequestResponse({ goal, actorId, actorRank, actorMembership, request, goalId }) {
+  const mgmt = authorizeGoalManagement({ goal, actorId, actorRank, actorMembership });
+  if (!mgmt.ok) return mgmt;
+  if (!request) return { ok: false, status: 404, body: { error: 'request_not_found' } };
+  if (String(request.goal_id) !== String(goalId)) {
+    return { ok: false, status: 404, body: { error: 'request_not_found', message: 'No such join-request on this goal.' } };
+  }
+  if (request.kind !== 'request') {
+    return { ok: false, status: 400, body: { error: 'not_a_join_request', message: 'That row is an invitation, not a join-request.' } };
+  }
+  if (request.status !== 'pending') {
+    return { ok: false, status: 409, body: { error: 'not_pending', status: request.status } };
+  }
+  return { ok: true };
+}
+
+// authorizeWithdrawJoinRequest — the gate for POST /goals/:id/requests/:reqId/withdraw
+// (task 1953): ONLY the requester may withdraw their OWN pending join-request — a
+// symmetric mirror of authorizeInvitationResponse (the invitee resolves their own
+// invite; here the requester resolves their own request, self-served instead of
+// waiting on an owner/manager deny). Ordering: request_not_found → wrong_goal →
+// not_a_join_request → not_pending → not_your_request. PURE + exported.
+function authorizeWithdrawJoinRequest({ request, goalId, actorId }) {
+  if (!request) return { ok: false, status: 404, body: { error: 'request_not_found' } };
+  if (String(request.goal_id) !== String(goalId)) {
+    return { ok: false, status: 404, body: { error: 'request_not_found', message: 'No such request on this goal.' } };
+  }
+  if (request.kind !== 'request') {
+    return { ok: false, status: 400, body: { error: 'not_a_join_request', message: 'That row is an invitation, not a join-request.' } };
+  }
+  if (request.status !== 'pending') {
+    return { ok: false, status: 409, body: { error: 'not_pending', status: request.status } };
+  }
+  if (String(request.builder_id) !== String(actorId)) {
+    return { ok: false, status: 403, body: {
+      error: 'not_your_request',
+      message: 'Only the requester may withdraw their own join-request.',
+    } };
+  }
+  return { ok: true };
+}
+
+// decorateGoalScope — additive, derived scope_protected flag on goal payloads
+// (task 1002689). A protected-scope goal is join-gated like a private one
+// (Archon-mediated membership, ADR 0086 §3), but the hall cannot re-derive the
+// protected roster client-side (module-scope-map is server-only) — so the
+// list/detail reads carry the boolean and the UI renders the request-to-join
+// path instead of a dead-end Join button. Never persisted; a pure map.
+function decorateGoalScope(goal) {
+  return goal ? { ...goal, scope_protected: scopeIncludesProtected(goal.scope_modules) } : goal;
+}
+
+
+module.exports = {
+  authorizeCreateJoinRequest,
+  authorizeGoalTaskCreate,
+  authorizeInvitationAccept,
+  authorizeInvitationResponse,
+  authorizeJoinRequestResponse,
+  authorizeMembershipKindChange,
+  authorizeOwnershipTransfer,
+  authorizeWithdrawJoinRequest,
+  decorateGoalScope,
+  isMemberOrArchon,
+  protectedScopeAdmissionBlock,
+};