@bongos/core 1.25.19 → 1.25.21

package/modules/provisioning/module.json

@@ -24,7 +24,8 @@
       "render-standup",
       "look",
       "demo",
-      "github-setup"
+      "github-setup",
+      "grants"
     ],
     "migrations": true,
     "pollers": [

package/modules/provisioning/project-refusal.js

@@ -0,0 +1,107 @@
+// modules/provisioning/project-refusal.js — what a person the project gate REFUSED is told
+// (task 1004162, ADR 0407 §6, replacing ADR 0328 decision 3).
+//
+// Called only after requireProjectOwner has already said no. It can never admit: it never
+// calls next() and never sets req.project. It only picks the wording of the refusal, so that
+// someone already connected to the project gets a next step instead of a dead end, while a
+// stranger still learns nothing.
+//
+//   no connection at all                         → 404 instance_not_found (as before)
+//   holds a grant, route not open to grantees    → 403 owner_only
+//   'visitor' (the project knows them)           → 403 project_membership_required + how to apply
+//   'pending' (the project invited them)         → 403 project_membership_required + accept it
+//   'applied' (asked to join inside 30 days)     → 403 project_membership_required + it's with the owner
+//   'member' / 'owner' row, PUBLIC project       → 403 project_access_required (ask the owner)
+//   'member' / 'owner' row, private or stealth   → 404 — a `member` row can be had by anyone who
+//                                                  runs the device flow (ADR 0328 amendment), so
+//                                                  it is no evidence they may learn a closed
+//                                                  project's id belongs to it.
+//
+// Any doubt — the standing port missing, throwing, or answering something unknown, or the
+// grant read failing — is the 404: on doubt, say less.
+'use strict';
+
+const api = require('../../src/module-api');
+const provisioning = require('./provisioning');
+const grants = require('./grants');
+
+const log = api.logger('provisioning');
+
+const STANDING_PORT = 'platform-identity.projectMembershipKind';
+const HOSTING_IS_SEPARATE = 'Managing its hosting is something the project’s owner gives separately.';
+
+function notFound(res) {
+  return res.fail('instance_not_found', 404);
+}
+
+function projectOrigin(inst) {
+  return inst.domain ? `https://${inst.domain}` : null;
+}
+
+// The project's join door, as its owner set it: only a PUBLIC project may confirm itself to a
+// person whose only link is a sign-in.
+function isPublicProject(inst) {
+  try {
+    return provisioning.effectiveSettings(inst).visibility === 'public';
+  } catch {
+    return false;
+  }
+}
+
+async function refuseProject(req, res, inst) {
+  let grant = null;
+  try {
+    grant = await grants.liveGrant(api.pool, inst.id, req.builder.id);
+  } catch (err) {
+    log.error(`[provisioning] ${req.method} ${req.path} — refusal grant read`, err);
+    return notFound(res);
+  }
+  if (grant) {
+    return res.fail('owner_only', { status: 403, message: 'Only the project’s owner can do this.' });
+  }
+
+  const port = api.resolveOptional(STANDING_PORT);
+  if (!port || typeof port.projectMembershipKind !== 'function') return notFound(res);
+  let kind;
+  try {
+    kind = await port.projectMembershipKind(inst.slug, req.builder.github_id);
+  } catch (err) {
+    log.error(`[provisioning] ${req.method} ${req.path} — standing read`, err);
+    return notFound(res);
+  }
+
+  const origin = projectOrigin(inst);
+  switch (kind) {
+    case 'visitor':
+      return res.fail('project_membership_required', {
+        status: 403,
+        message: `You’re not a member of this project yet. Ask to join it, and its owner decides. ${HOSTING_IS_SEPARATE}`,
+        details: { apply: origin
+          ? { state: 'can_apply', method: 'POST', path: '/api/bongos/my-projects/join', body: { origin } }
+          : { state: 'can_apply' } },
+      });
+    case 'pending':
+      return res.fail('project_membership_required', {
+        status: 403,
+        message: `This project has invited you. Sign in to it to accept. ${HOSTING_IS_SEPARATE}`,
+        details: { apply: { state: 'invited', sign_in: origin } },
+      });
+    case 'applied':
+      return res.fail('project_membership_required', {
+        status: 403,
+        message: `You’ve asked to join this project, and its owner decides. ${HOSTING_IS_SEPARATE}`,
+        details: { apply: { state: 'applied' } },
+      });
+    case 'member':
+    case 'owner':
+      if (!isPublicProject(inst)) return notFound(res);
+      return res.fail('project_access_required', {
+        status: 403,
+        message: 'Only the project’s owner, and people the owner has given access, can manage its hosting. Ask the owner to give you access.',
+      });
+    default:
+      return notFound(res);
+  }
+}
+
+module.exports = { refuseProject };

package/modules/provisioning/provisioning.js

@@ -25,7 +25,7 @@ const { normalizeModuleSelection, effectiveModules } = require('./starter-bundle
 const { PLANET_PHYSICS_QUESTIONS, canonicalAnswer } = require('./planet-physics');
 const { softLimitsFor } = require('./soft-limits'); const { demoView } = require('./demo'); const { isTestProject, TEST_COMPANION_ENV } = require('./test-project');   // the demo marker's owner view (task 1004420); the test mark (task 1005036)
 const { dnsResolves, recordDnsResolved, lookupAnswers } = require('./dns-resolves');   // has the platform's lookup seen the address answer (task 1004505)
-const { LOOK_SETTINGS_VOCAB, LOOK_DEFAULTS, LOOK_COMPANION_ENV } = require('./look'); const { BIRTH_COMPANION_ENV } = require('./birth'); // born into genesis (task 1004506)
+const { LOOK_SETTINGS_VOCAB, LOOK_DEFAULTS, LOOK_COMPANION_ENV } = require('./look'); const { BIRTH_COMPANION_ENV } = require('./birth'); const { GUIDE_COMPANION_ENV } = require('./guide-handoff'); // born into genesis (task 1004506); the guide's hand-off (task 1005274)
 
 // ---------------------------------------------------------------------------
 // Constants (mirror the CHECK constraints in provisioning_001_tables.sql)
@@ -66,7 +66,7 @@ const PROJECT_TYPES = ['game', 'research', 'business', 'non-profit', 'not-sure']
 // 'disconnect' (task 1003249, migration provisioning_016): the owner's true delete — ./disconnect.js.
 // 'core-upgrade' (task 1003159, ADR 0293): move this instance's core pin — the owner's
 // deploy door. The web tier only QUEUES it; the control-plane runner performs it.
-const INTENT_ACTIONS = ['provision', 'teardown', 'oauth-manifest', 'domain-attach', 'settings-apply', 'restart', 'disconnect', 'core-upgrade', 'core-upgrade-preflight', 'repo-private', 'render-standup'];
+const INTENT_ACTIONS = ['provision', 'teardown', 'oauth-manifest', 'domain-attach', 'settings-apply', 'restart', 'disconnect', 'core-upgrade', 'core-upgrade-preflight', 'repo-private', 'render-standup', 'render-promote'];
 // Every state a teardown can be asked for — i.e. everything except the one
 // state where there is provably nothing left to release. DERIVED from
 // INSTANCE_STATES on purpose (task 1003042, walk finding N5): the old hand-kept
@@ -513,7 +513,7 @@ function settingsEnvVars(row, prefix) {
 // cutoff and every unresolved review counts, which is the right answer for a
 // project that has been strict since it stood up.
 const SETTINGS_COMPANION_ENV = Object.freeze({
-  ARTIST_GATE_SINCE: (row) => artistGateStrictSince(row) || '', ...LOOK_COMPANION_ENV, ...BIRTH_COMPANION_ENV, ...TEST_COMPANION_ENV, // + accent, logo (look.js); birth, demo box (birth.js); test mark (test-project.js)
+  ARTIST_GATE_SINCE: (row) => artistGateStrictSince(row) || '', ...LOOK_COMPANION_ENV, ...BIRTH_COMPANION_ENV, ...TEST_COMPANION_ENV, ...GUIDE_COMPANION_ENV, // + accent, logo (look.js); birth, demo box (birth.js); test mark (test-project.js); the guide's hand-off (guide-handoff.js)
 });
 
 // The web.env block the runner writes at STANDUP (task 1003139): a comment that
@@ -1192,7 +1192,7 @@ async function enqueueTeardown(db, instanceId, requestedBy) {
     `UPDATE provisioning_intents
         SET state = 'error', last_error = 'superseded: teardown requested', borrowed_key_enc = NULL,
             updated_at = now(), resolved_at = now()
-      WHERE instance_id = $1 AND action IN ('provision', 'settings-apply', 'restart', 'repo-private', 'render-standup') AND state = 'pending'
+      WHERE instance_id = $1 AND action IN ('provision', 'settings-apply', 'restart', 'repo-private', 'render-standup', 'render-promote') AND state = 'pending'
         AND NOT EXISTS (SELECT 1 FROM provisioning_instances WHERE id = $1 AND hosting_shape = 'control-plane') RETURNING id`,
     [instanceId]
   );

package/modules/provisioning/render-lookup.js

@@ -65,4 +65,39 @@ async function lookupRender(key, { ownerId = null, fetchImpl = globalThis.fetch
   return { workspaces, services };
 }
 
-module.exports = { lookupRender, RenderLookupError, RENDER_API };
+// WHAT IS WAITING TO GO LIVE (task 1005290, ADR 0406 §2; the ADR 0406 §11 amendment widens
+// ADR 0348 by exactly this): the owner's two recorded services — their live app and its
+// sandbox — and the deploys of each. GET only, the same key rules as above, every service
+// asserted to carry the workspace. Nothing here can promote; promoting is the runner's
+// (scripts/bongos/provision-render-promote.js), on a key lent with the press.
+const COMMIT_RE = /^[0-9a-f]{7,40}$/;
+const SERVED = ['live', 'deactivated'];
+function shapeDeploy(d) {
+  const c = (d && d.commit) || {};
+  return {
+    deploy_id: d.id,
+    commit_id: COMMIT_RE.test(String(c.id || '')) ? c.id : null,
+    short: String(c.id || '').slice(0, 7),
+    message: String(c.message || '').split('\n')[0].slice(0, 200),
+    at: (c.createdAt || d.createdAt) || null,
+    status: d.status || null,
+  };
+}
+async function lookupPromotion(key, { ownerId, liveServiceId, sandboxServiceId, fetchImpl = globalThis.fetch }) {
+  for (const id of [liveServiceId, sandboxServiceId]) {
+    const s = await get(`/services/${encodeURIComponent(id)}`, key, fetchImpl);
+    if (!s || s.ownerId !== ownerId) throw new RenderLookupError('render_owner_mismatch', 'Render answered from another workspace, so nothing was shown.');
+  }
+  const deploys = async (id, n) => unwrap(await get(`/services/${encodeURIComponent(id)}/deploys?limit=${n}`, key, fetchImpl), 'deploy').map(shapeDeploy);
+  const live = await deploys(liveServiceId, 10);
+  const sandbox = await deploys(sandboxServiceId, 30);
+  const liveNow = live.find((d) => d.status === 'live') || null;
+  // Waiting = what served on the sandbox since the change live runs, newest first. If live's
+  // change is not in the sandbox's list (older than it reaches), everything listed waits.
+  const served = sandbox.filter((d) => SERVED.includes(d.status) && d.commit_id);
+  const at = liveNow ? served.findIndex((d) => d.commit_id === liveNow.commit_id) : -1;
+  const waiting = (at === -1 ? served : served.slice(0, at)).filter((d, i, all) => all.findIndex((x) => x.commit_id === d.commit_id) === i);
+  return { live: liveNow, waiting };
+}
+
+module.exports = { lookupRender, lookupPromotion, RenderLookupError, RENDER_API };

package/modules/provisioning/render-promote.js

@@ -0,0 +1,80 @@
+// modules/provisioning/render-promote.js — the web tier's half of PROMOTE: a person moves
+// what ran on the project's sandbox to its live app (task 1005290; ADR 0406 §2, ADR 0327).
+//
+// WHY. Finished work lands on the sandbox (it follows `main`); the live app moves only
+// when a person presses promote — the project law "Land only. Ask before going live". This
+// file queues that press (a `render-promote` intent holding the owner's encrypted key, and
+// the chosen change on the row, in ONE statement), reads back the record of promotions,
+// and shapes what the owner is told. It never calls Render: the read-only look at what is
+// waiting is render-lookup.js (ADR 0348 as widened by ADR 0406 §11), and the promotion
+// itself is the runner's (scripts/bongos/provision-render-promote.js).
+'use strict';
+
+const COMMIT_RE = /^[0-9a-f]{7,40}$/;
+
+// Why this project cannot promote right now, in the owner's words, or null.
+function noPromoteReason(inst) {
+  const h = (inst && inst.app_host) || {};
+  if (!inst || inst.status === 'torn_down' || inst.status === 'tearing_down') return 'This project has been removed.';
+  if (h.platform !== 'render' || !h.serviceId) return 'Your app is not set up on Render, so there is nothing to promote to.';
+  if (!h.sandbox || !h.sandbox.serviceId || ['removed', 'left', 'failed'].includes(h.sandbox.state)) return 'This project has no sandbox, so there is nothing to promote from. Add one first.';
+  return null;
+}
+
+// Queue a promotion. Returns { intent } or { conflict: 'open_intent', intent }.
+async function enqueuePromote(db, instanceId, { keyEnc, commitId, expectLiveCommit, requestedBy }) {
+  await require('./control-plane-guard').assertIntentAllowed(db, instanceId, 'render-promote');
+  const ask = { state: 'requested', commitId, expectLiveCommit: expectLiveCommit || null, requestedBy: requestedBy == null ? null : String(requestedBy), requestedAt: new Date().toISOString(), error: null };
+  try {
+    const { rows } = await db.query(
+      `WITH i AS (
+         INSERT INTO provisioning_intents (instance_id, action, requested_by, state, borrowed_key_enc)
+         VALUES ($1, 'render-promote', $2, 'pending', $3) RETURNING *
+       ), u AS (
+         UPDATE provisioning_instances SET app_host = app_host || jsonb_build_object('promote', $4::jsonb)
+          WHERE id = $1 RETURNING id
+       )
+       SELECT i.id, i.instance_id, i.action, i.state, i.created_at FROM i`,
+      [instanceId, 'api:self', keyEnc, JSON.stringify(ask)]);
+    return { intent: rows[0] };
+  } catch (e) {
+    if (e && e.code === '23505') {
+      const { rows } = await db.query(
+        `SELECT id, action, state FROM provisioning_intents
+          WHERE instance_id = $1 AND state IN ('pending', 'running') ORDER BY created_at DESC LIMIT 1`, [instanceId]);
+      return { conflict: 'open_intent', intent: rows[0] || { action: 'unknown', state: 'open' } };
+    }
+    throw e;
+  }
+}
+
+// The project's recent promotions, newest first: what went live, when, by whose press.
+async function listPromotions(db, instanceId, limit = 5) {
+  const { rows } = await db.query(
+    `SELECT commit_id, commit_message, from_commit_id, state, error, created_at
+       FROM provisioning_promotions WHERE instance_id = $1 ORDER BY created_at DESC LIMIT $2`, [instanceId, limit]);
+  return (rows || []).filter((r) => r && r.commit_id).map((r) => ({
+    commit: String(r.commit_id).slice(0, 7),
+    message: r.commit_message || null,
+    from: r.from_commit_id ? String(r.from_commit_id).slice(0, 7) : null,
+    state: r.state,
+    error: r.state === 'failed' ? (r.error || 'It did not go through.') : null,
+    at: r.created_at instanceof Date ? r.created_at.toISOString() : r.created_at,
+  }));
+}
+
+// What the owner is told about promoting: whether they can, whether the live app still
+// deploys every merge, and where the last press stands.
+function promoteView(inst) {
+  const h = (inst && inst.app_host) || {};
+  const why = noPromoteReason(inst);
+  const p = h.promote || null;
+  return {
+    can: !why,
+    reason: why,
+    live_follows_main: h.liveAutoDeploy !== 'off',
+    last: p ? { state: p.state, commit: p.commitId ? String(p.commitId).slice(0, 7) : null, error: p.state === 'failed' ? (p.error || null) : null } : null,
+  };
+}
+
+module.exports = { noPromoteReason, enqueuePromote, listPromotions, promoteView, COMMIT_RE };

package/modules/provisioning/route-helpers.js

@@ -1,34 +1,72 @@
-// modules/provisioning/route-helpers.js — the one owner-or-archon gate every own-scoped
+// modules/provisioning/route-helpers.js — the one gate every own-scoped
 // /provisioning/instances/:id route mounts (task 1004159, ADR 0328 decision 2). It replaced
 // three hand-written copies of the same rule, and the three routes that had only the owner
-// half of it (teardown, domain, github-app).
+// half of it (teardown, domain, github-app). Since task 1004161 (ADR 0407) a route may also
+// admit a person the project's OWNER granted access to, by opting in — never by default.
 'use strict';
 
 const api = require('../../src/module-api');
 const { failFrom } = require('./public-refusal');
+const grants = require('./grants');
+const { refuseProject } = require('./project-refusal');
 
 const log = api.logger('provisioning');
 
+// The grant levels a route may opt into. One today (ADR 0407 §3).
+const GRANTEE_LEVELS = Object.freeze(['operate']);
+
 function isProjectOwner(inst, builder) {
   return String(inst.owner_builder_id) === String(builder.id);
 }
 
-// The audit actor for a request the gate admitted: the owner acts as themselves, and an
-// archon on someone else's project is named, so the override never reads as the owner's act.
+// Which door admitted this request: 'owner' · 'grantee' · 'archon'. Set by the gate; for a
+// request the gate did not see, decided from the row the old way (owner, else archon).
+function projectDoor(req) {
+  if (req.projectDoor) return req.projectDoor;
+  return isProjectOwner(req.project, req.builder) ? 'owner' : 'archon';
+}
+
+// The audit actor for a request the gate admitted: the owner acts as themselves, and a grantee
+// or an archon is named, so neither ever reads as the owner's act (ADR 0407 §4).
 function projectActor(req) {
-  return isProjectOwner(req.project, req.builder) ? 'api:self' : `api:archon:${req.builder.id}`;
+  const door = projectDoor(req);
+  if (door === 'owner') return 'api:self';
+  return `api:${door}:${req.builder.id}`;
+}
+
+// The same, in words, for an event's detail line: "owner", "grantee <login>", "archon <login>".
+function projectActorLabel(req) {
+  const door = projectDoor(req);
+  return door === 'owner' ? 'owner' : `${door} ${req.builder.github_login || req.builder.id}`;
+}
+
+// What a grantee is shown of the project read (ADR 0407 §3): everything the owner sees except
+// the owner's own hosting bill and the GitHub App steps, which act on the owner's GitHub
+// account. The owner and an archon get the body unchanged.
+function grantedView(req, body) {
+  if (projectDoor(req) !== 'grantee') return body;
+  const { owner_monthly_usd, github_install, ...instance } = body.instance || {};
+  return { ...body, instance, github_app: null, github_setup: null };
 }
 
-// requireProjectOwner(loadFn, { archonOverride }) — mounted after requireBuilder, and spelled
-// in the route's own middleware list so route-rank-check.js can see it (ADR 0328 §4). Loads
-// the row with the caller's loader (`loadFn(id)`) and admits its owner or, by default, an
-// archon. That is a plain RANK test on purpose: `provisioning.fleet.manage` floors at metic
-// (ADR 0157), so gating on it would widen every route it guards.
+// requireProjectOwner(loadFn, { archonOverride, grantee }) — mounted after requireBuilder, and
+// spelled in the route's own middleware list so route-rank-check.js can see it (ADR 0328 §4).
+// Loads the row with the caller's loader (`loadFn(id)`) and admits, in this order:
+//   1. its owner;
+//   2. when the route opts in with `grantee: 'operate'`, a person holding a LIVE grant of that
+//      level on this project — read from provisioning_project_grants on every request, never a
+//      membership row (ADR 0407 §§1-3);
+//   3. by default, an archon — a plain RANK test on purpose: `provisioning.fleet.manage`
+//      floors at metic (ADR 0157), so gating on it would widen every route it guards.
 //
 // A missing row and someone else's row are the same 404, and the gate runs before the
 // handler's body validator, so a stranger cannot tell a real id from a malformed request.
-// The loaded row rides on `req.project`.
-function requireProjectOwner(loadFn, { archonOverride = true } = {}) {
+// A grant read that fails DENIES (the opaque 500), never falls through to admit.
+// The loaded row rides on `req.project`; the door that admitted it on `req.projectDoor`.
+function requireProjectOwner(loadFn, { archonOverride = true, grantee = null } = {}) {
+  if (grantee !== null && !GRANTEE_LEVELS.includes(grantee)) {
+    throw new Error(`requireProjectOwner: unknown grantee level ${grantee}`);
+  }
   return async function projectOwnerGate(req, res, next) {
     const id = api.parseId(req, res); // sends 400 bad_id + returns null on failure
     if (!id) return;
@@ -39,12 +77,28 @@ function requireProjectOwner(loadFn, { archonOverride = true } = {}) {
       log.error(`[provisioning] ${req.method} ${req.path} — project load`, err);
       return failFrom(res, err, 'instance_read_failed');
     }
-    const admitted = !!inst
-      && (isProjectOwner(inst, req.builder) || (archonOverride && req.builder.rank === 'archon'));
-    if (!admitted) return res.fail('instance_not_found', 404);
+    if (!inst) return res.fail('instance_not_found', 404);
+    let door = null;
+    if (isProjectOwner(inst, req.builder)) door = 'owner';
+    if (!door && grantee) {
+      let grant;
+      try {
+        grant = await grants.liveGrant(api.pool, inst.id, req.builder.id);
+      } catch (err) {
+        log.error(`[provisioning] ${req.method} ${req.path} — grant read`, err);
+        return failFrom(res, err, 'instance_read_failed');
+      }
+      if (grant && grant.level === grantee) door = 'grantee';
+    }
+    if (!door && archonOverride && req.builder.rank === 'archon') door = 'archon';
+    // Refused. The WORDING depends on who is asking (task 1004162, ADR 0407 §6): a stranger
+    // still gets the 404, someone already connected to the project gets a next step. That
+    // file can only refuse — it never calls next() and never sets req.project.
+    if (!door) return refuseProject(req, res, inst);
     req.project = inst;
+    req.projectDoor = door;
     return next();
   };
 }
 
-module.exports = { requireProjectOwner, projectActor, isProjectOwner };
+module.exports = { requireProjectOwner, projectActor, projectActorLabel, grantedView, isProjectOwner };

package/modules/provisioning/routes/env-manifest.js

@@ -25,10 +25,23 @@ const { pool, validateOrRespond } = api;
 const provisioning = require('../provisioning');
 const envManifest = require('../env-manifest');
 const { failFrom } = require('../public-refusal');
-const { requireProjectOwner } = require('../route-helpers');
+const { requireProjectOwner, projectActor, projectActorLabel } = require('../route-helpers');
 
 const log = api.logger('provisioning');
 const loadInstance = (id) => provisioning.getInstanceById(pool, id);
+// All four routes also admit a person the owner granted 'operate' access (task 1004161,
+// ADR 0407 §3): a variable NAME changes no running behaviour, and this list exists for the
+// builder sessions that help run the project to read and keep current.
+const GRANTEE = { grantee: 'operate' };
+
+// Every change to the list is an audit row naming who made it, so a grantee's change never
+// reads as the owner's (ADR 0407 §4). Best-effort: the change is already saved.
+function recordManifestChange(req, what) {
+  return provisioning.recordEvent(pool, {
+    instanceId: req.project.id, ownerBuilderId: req.project.owner_builder_id, event: 'env-manifest',
+    detail: `${what} by ${projectActorLabel(req)}`, actor: projectActor(req),
+  }).catch(() => {});
+}
 
 // The `:varId` path segment. parseId reads `:id`, which is the PROJECT here, so the
 // declaration's id is parsed separately. A non-numeric id is a 400 naming the field
@@ -91,7 +104,7 @@ module.exports = function buildEnvManifestRouter() {
 
   // GET — the declared surface. This is the route a BUILDER SESSION reads to learn which
   // variables a project has, which is the whole reason the manifest exists.
-  router.get('/provisioning/instances/:id/env-manifest', api.requireBuilder, requireProjectOwner(loadInstance), async (req, res) => {
+  router.get('/provisioning/instances/:id/env-manifest', api.requireBuilder, requireProjectOwner(loadInstance, GRANTEE), async (req, res) => {
     try {
       const inst = req.project;
       const vars = await envManifest.listEnvVars(pool, inst.id);
@@ -113,7 +126,7 @@ module.exports = function buildEnvManifestRouter() {
 
   // POST — declare a variable, or re-declare one that exists (an edit, not a duplicate:
   // see ../env-manifest.js's declareEnvVar).
-  router.post('/provisioning/instances/:id/env-manifest', api.requireBuilder, requireProjectOwner(loadInstance), async (req, res) => {
+  router.post('/provisioning/instances/:id/env-manifest', api.requireBuilder, requireProjectOwner(loadInstance, GRANTEE), async (req, res) => {
     if (refusesValue(req, res)) return;   // before the strict validator — see refusesValue
     if (validateOrRespond(req, res, {
       name: { required: true, type: 'string', maxLength: envManifest.ENV_NAME_MAX },
@@ -131,6 +144,7 @@ module.exports = function buildEnvManifestRouter() {
         environments: req.body.environments,
         required: req.body.required,
       });
+      await recordManifestChange(req, `${created ? 'declared' : 're-declared'} ${row.name}`);
       res.status(created ? 201 : 200).json({ ok: true, created, env_var: row, values_held: false });
     } catch (err) {
       log.error('[provisioning] POST /provisioning/instances/:id/env-manifest', err);
@@ -140,7 +154,7 @@ module.exports = function buildEnvManifestRouter() {
 
   // PATCH — edit one declaration. Merge-patch: an omitted field is left alone, so the
   // hall can fix a description without restating the environments.
-  router.patch('/provisioning/instances/:id/env-manifest/:varId', api.requireBuilder, requireProjectOwner(loadInstance), async (req, res) => {
+  router.patch('/provisioning/instances/:id/env-manifest/:varId', api.requireBuilder, requireProjectOwner(loadInstance, GRANTEE), async (req, res) => {
     if (refusesValue(req, res)) return;   // before the strict validator — see refusesValue
     if (validateOrRespond(req, res, {
       name: { type: 'string', maxLength: envManifest.ENV_NAME_MAX },
@@ -157,6 +171,7 @@ module.exports = function buildEnvManifestRouter() {
       // Not that project's declaration → the same 404 a missing one gets, so a guessed id
       // never confirms what another project declares.
       if (!row) return res.fail('env_var_not_found', 404);
+      await recordManifestChange(req, `edited ${row.name}`);
       res.json({ ok: true, env_var: row, values_held: false });
     } catch (err) {
       log.error('[provisioning] PATCH /provisioning/instances/:id/env-manifest/:varId', err);
@@ -167,13 +182,14 @@ module.exports = function buildEnvManifestRouter() {
   // DELETE — remove one declaration. Nothing outside this table is affected: the value,
   // wherever it lives, is untouched, and the response says so rather than letting an
   // owner believe removing the name removed the secret.
-  router.delete('/provisioning/instances/:id/env-manifest/:varId', api.requireBuilder, requireProjectOwner(loadInstance), async (req, res) => {
+  router.delete('/provisioning/instances/:id/env-manifest/:varId', api.requireBuilder, requireProjectOwner(loadInstance, GRANTEE), async (req, res) => {
     try {
       const inst = req.project;
       const varId = parseVarId(req, res);
       if (!varId) return;
       const removed = await envManifest.removeEnvVar(pool, inst.id, varId);
       if (!removed) return res.fail('env_var_not_found', 404);
+      await recordManifestChange(req, `removed declaration ${varId}`);
       res.json({ ok: true, removed: true,
         message: 'Declaration removed. The variable\'s value, wherever you keep it, is untouched — this platform never had it.' });
     } catch (err) {

package/modules/provisioning/routes/grants.js

@@ -0,0 +1,141 @@
+// modules/provisioning/routes/grants.js — "People with access": the owner gives a person access
+// to help run their hosted project, lists it, and takes it back (task 1004161, ADR 0407 §2).
+//
+// The grant itself is provisioning_project_grants, written only by ../grants.js. Who may do
+// what here:
+//   • GIVE — the project's owner only, from their own session. NO archon override: an archon
+//     already reaches the project for fleet support, and a grant would let them hand someone
+//     else's project to a third person without its owner (owner decision, ADR 0407).
+//   • LIST — the owner, or an archon (the ordinary owner-or-archon gate).
+//   • TAKE BACK — the owner, the grantee themselves (leaving), or an archon. A revoke only ever
+//     removes access, so the archon door here is a safety lever, not a widening.
+// Every give and take-back writes a provisioning_events row naming who did it.
+//
+// Its own routes file (declared in module.json) because routes/provisioning.js sits at the
+// size ratchet.
+'use strict';
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const { pool, validateOrRespond, parseId } = api;
+const provisioning = require('../provisioning');
+const grants = require('../grants');
+const { failFrom } = require('../public-refusal');
+const { requireProjectOwner, projectActor, projectActorLabel, isProjectOwner } = require('../route-helpers');
+
+const log = api.logger('provisioning');
+const loadInstance = (id) => provisioning.getInstanceById(pool, id);
+
+const GITHUB_LOGIN = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/;
+
+function publicGrant(g) {
+  return {
+    id: String(g.id),
+    level: g.level,
+    granted_at: g.granted_at,
+    builder: g.github_login === undefined ? { id: String(g.grantee_builder_id) } : {
+      id: String(g.grantee_builder_id), github_login: g.github_login,
+      display_name: g.display_name || null, avatar_url: g.avatar_url || null,
+    },
+  };
+}
+
+module.exports = function buildGrantsRouter() {
+  const router = express.Router();
+
+  // GET /provisioning/instances/:id/grants — the project's live grants.
+  // rank: any authenticated builder, own resource (owner; archon may read any). 404 otherwise.
+  router.get('/provisioning/instances/:id/grants', api.requireBuilder, requireProjectOwner(loadInstance), async (req, res) => {
+    try {
+      const rows = await grants.listLiveGrants(pool, req.project.id);
+      res.json({ grants: rows.map(publicGrant), levels: grants.GRANT_LEVELS, limit: grants.MAX_LIVE_GRANTS });
+    } catch (err) {
+      log.error('[provisioning] GET /provisioning/instances/:id/grants', err);
+      failFrom(res, err, 'grants_read_failed');
+    }
+  });
+
+  // POST /provisioning/instances/:id/grants { github_login } — give a person access.
+  // rank: any authenticated builder, own resource, OWNER ONLY (no archon override). 404 for
+  // anyone else, so a stranger learns nothing about the id.
+  router.post('/provisioning/instances/:id/grants', api.requireBuilder, requireProjectOwner(loadInstance, { archonOverride: false }), async (req, res) => {
+    if (validateOrRespond(req, res, {
+      github_login: { required: true, type: 'string', maxLength: 39 },
+    })) return;
+    const login = String(req.body.github_login).trim().replace(/^@/, '');
+    if (!GITHUB_LOGIN.test(login)) {
+      return res.fail('bad_github_login', { status: 400, message: 'That is not a GitHub username.' });
+    }
+    try {
+      const inst = req.project;
+      const person = await grants.findGranteeByLogin(pool, login);
+      if (!person) {
+        return res.fail('grantee_not_found', { status: 404,
+          message: `Nobody called ${login} has signed in to the hub yet. Ask them to sign in once, then try again.` });
+      }
+      const out = await grants.grantProjectAccess(pool, {
+        instanceId: inst.id, granteeBuilderId: person.id, level: 'operate', grantedByBuilderId: req.builder.id,
+      });
+      if (out.refused === 'grantee_is_owner') {
+        return res.fail('grantee_is_owner', { status: 400, message: 'You own this project already.' });
+      }
+      if (out.refused === 'grant_limit') {
+        return res.fail('grant_limit', { status: 409,
+          message: `A project can give access to at most ${grants.MAX_LIVE_GRANTS} people. Take someone off first.` });
+      }
+      if (out.refused) return res.fail('instance_not_found', 404);
+      if (out.created) {
+        await provisioning.recordEvent(pool, {
+          instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: 'grant-made',
+          detail: `access (${out.grant.level}) given to builder ${person.id} (${person.github_login}) by ${projectActorLabel(req)}`,
+          actor: projectActor(req),
+        }).catch(() => {});
+      }
+      res.status(out.created ? 201 : 200).json({
+        ok: true, created: !!out.created,
+        grant: publicGrant({ ...out.grant, ...person, grantee_builder_id: person.id }),
+      });
+    } catch (err) {
+      log.error('[provisioning] POST /provisioning/instances/:id/grants', err);
+      failFrom(res, err, 'grant_failed');
+    }
+  });
+
+  // DELETE /provisioning/instances/:id/grants/:grantId — take access back.
+  // rank: any authenticated builder: the project's owner, an archon, or the grantee removing
+  // their OWN grant — decided in the handler, because "whose grant is it" is a fact of the row.
+  // Anyone else gets the same 404 a missing project gets.
+  router.delete('/provisioning/instances/:id/grants/:grantId', api.requireBuilder, async (req, res) => {
+    const id = parseId(req, res);
+    if (!id) return;
+    const grantId = Number(req.params.grantId);
+    if (!Number.isSafeInteger(grantId) || grantId <= 0) return res.fail('bad_id', 400);
+    try {
+      const inst = await loadInstance(id);
+      if (!inst) return res.fail('instance_not_found', 404);
+      const grant = await grants.getGrant(pool, inst.id, grantId);
+      const isOwner = isProjectOwner(inst, req.builder);
+      const isArchon = req.builder.rank === 'archon';
+      const isOwnGrant = !!grant && String(grant.grantee_builder_id) === String(req.builder.id);
+      if (!isOwner && !isArchon && !isOwnGrant) return res.fail('instance_not_found', 404);
+      if (!grant || grant.revoked_at) {
+        return res.fail('grant_not_found', { status: 404, message: 'That access was already taken back.' });
+      }
+      const revoked = await grants.revokeProjectAccess(pool, { instanceId: inst.id, grantId, revokedByBuilderId: req.builder.id });
+      if (!revoked) return res.fail('grant_not_found', { status: 404, message: 'That access was already taken back.' });
+      req.project = inst;
+      req.projectDoor = isOwner ? 'owner' : (isOwnGrant ? 'grantee' : 'archon');
+      await provisioning.recordEvent(pool, {
+        instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: 'grant-revoked',
+        detail: `access (${revoked.level}) of builder ${revoked.grantee_builder_id} taken back by ${projectActorLabel(req)}`,
+        actor: projectActor(req),
+      }).catch(() => {});
+      res.json({ ok: true, revoked: true });
+    } catch (err) {
+      log.error('[provisioning] DELETE /provisioning/instances/:id/grants/:grantId', err);
+      failFrom(res, err, 'grant_revoke_failed');
+    }
+  });
+
+  return router;
+};