@bongos/core 1.25.20 → 1.25.22

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;
+};

package/modules/provisioning/routes/provisioning.js

@@ -68,7 +68,8 @@ const { callbackPage } = require('./callback-page'); const githubSetup = require
 const { badProjectDetail, badModuleSelection, badProjectType, screenedOut } = require('./body-validators'); const demo = require('../demo'); const birth = require('../birth'); const testProject = require('../test-project'); const guideHandoff = require('../guide-handoff');
 const { failFrom } = require('../public-refusal');   // every catch: a declared refusal reaches the owner, anything else stays opaque (task 1004126)
 const { settingsPush, failPushConflict } = require('../settings-push');   // a settings save's push + receipt, shared with routes/look.js (task 1004421)
-const { requireProjectOwner, projectActor, isProjectOwner } = require('../route-helpers');   // the owner-or-archon gate (task 1004159, ADR 0328)
+const { requireProjectOwner, projectActor, projectActorLabel, isProjectOwner, grantedView } = require('../route-helpers');
+const GRANTEE = { grantee: 'operate' };   // the three routes here a granted helper may use (task 1004161, ADR 0407 §3)   // the owner-or-archon gate (task 1004159, ADR 0328)
 // the kernel ports this module provides (moved out at the size ratchet, task 1003578)
 const { registerProvisioningSeams } = require('../seams');
 // task 1003208: structured logging (pino via the doorway) — was console.*.
@@ -658,7 +659,7 @@ module.exports = function provisioningRoutes() {
   // GET /provisioning/instances/:id — read one instance (the manage page's read).
   // rank: any authenticated builder (own resource; archon may read any — task
   // 1003041). 404 otherwise — does not leak another owner's instance existence.
-  router.get('/provisioning/instances/:id', auth.requireBuilder, requireProjectOwner(loadInstance), async (req, res) => {
+  router.get('/provisioning/instances/:id', auth.requireBuilder, requireProjectOwner(loadInstance, GRANTEE), async (req, res) => {
     const id = parseId(req, res); // (req, res) — parseId sends 400 bad_id + returns null on failure
     if (!id) return;
     try {
@@ -676,7 +677,7 @@ module.exports = function provisioningRoutes() {
       // panel recovers it from server state after a reload — not from sessionStorage.
       const manifest = await provisioning.getLatestOAuthManifestForInstance(pool, id);
       const githubSetupNow = await githubSetup.githubSetupRead(pool, inst, manifest, manifest ? provisioning.publicGithubApp(manifest).status : null, { withState: false });
-      res.json({
+      res.json(grantedView(req, {
         // the standing install nudge rides the instance, as on the list read (task 1004763)
         instance: { ...ownerInstance(inst), github_install: githubSetup.installNudge(githubSetupNow) },
         open_intent: open ? { action: open.action, state: open.state } : null,
@@ -684,7 +685,7 @@ module.exports = function provisioningRoutes() {
         // the four-step checklist from what the runner verified (task 1004649) — the
         // install link rides WITHOUT the state token this read never carries
         github_setup: githubSetupNow,
-      });
+      }));
     } catch (err) {
       log.error('[provisioning] GET /provisioning/instances/:id', err);
       failFrom(res, err, 'read_failed');
@@ -874,7 +875,7 @@ module.exports = function provisioningRoutes() {
   // GET /provisioning/instances/:id/settings — read a project's effective
   // settings + the allowed values (so a form can render its choices).
   // rank: any authenticated builder (own resource; archon may read any).
-  router.get('/provisioning/instances/:id/settings', auth.requireBuilder, requireProjectOwner(loadInstance), async (req, res) => {
+  router.get('/provisioning/instances/:id/settings', auth.requireBuilder, requireProjectOwner(loadInstance, GRANTEE), async (req, res) => {
     try {
       const inst = req.project;
       // `planet` rides beside `settings` (task 1003347): the same row, read by a
@@ -1038,7 +1039,7 @@ module.exports = function provisioningRoutes() {
   // Every refusal names the action that IS available in that state rather than
   // hiding behind a code, and no branch promises a duration — a restart's downtime
   // is exactly what this route cannot know (the F16 rule, ADR 0190 §7).
-  router.post('/provisioning/instances/:id/restart', auth.requireBuilder, requireProjectOwner(loadInstance), async (req, res) => {
+  router.post('/provisioning/instances/:id/restart', auth.requireBuilder, requireProjectOwner(loadInstance, GRANTEE), async (req, res) => {
     const id = parseId(req, res); // (req, res) — parseId sends 400 bad_id + returns null on failure
     if (!id) return;
     try {
@@ -1069,7 +1070,7 @@ module.exports = function provisioningRoutes() {
       if (r.created) {
         await provisioning.recordEvent(pool, {
           instanceId: id, ownerBuilderId: inst.owner_builder_id, event: 'restart',
-          detail: 'restart requested by owner', actor,
+          detail: `restart requested by ${projectActorLabel(req)}`, actor,
         }).catch(() => {});
       }
       res.json({ ok: true, queued: r.created, action: 'restart', status: inst.status, message: r.created

package/modules/provisioning/routes/render-standup.js

@@ -23,7 +23,8 @@ const { pool, validateOrRespond, parseId } = api;
 const provisioning = require('../provisioning');
 const renderStandup = require('../render-standup');
 const { failFrom } = require('../public-refusal');
-const { lookupRender, RenderLookupError } = require('../render-lookup');
+const { lookupRender, lookupPromotion, RenderLookupError } = require('../render-lookup');
+const renderPromote = require('../render-promote');
 const { appStatus } = require('../app-status');
 const renderSandbox = require('../render-sandbox');
 const envManifest = require('../env-manifest');
@@ -46,6 +47,10 @@ const LOOKUP_STATUS = { render_key_refused: 422, render_workspace_unreachable: 4
 // OWNER ONLY, no archon override, for every Render route: the key and the account it acts
 // in are the owner's. A missing project and someone else's answer the same 404, so an id is
 // never confirmed.
+// One sentence for "another run holds this project, so the key was dropped" — the sandbox
+// and promote routes say it the same way (voice.md V1: one fixed sentence per concept).
+const BUSY_KEY_NOT_KEPT = 'Something else is being done to this project right now, so your key was not kept. Try again in a minute.';
+
 function ownedBy(inst, builder) { return !!(inst && builder && String(inst.owner_builder_id) === String(builder.id)); }
 
 module.exports = function buildRenderStandupRouter({ fetchImpl } = {}) {
@@ -105,7 +110,9 @@ module.exports = function buildRenderStandupRouter({ fetchImpl } = {}) {
         : [];
       // The sandbox beside it (ADR 0406, task 1005289), in the same shape.
       const sandbox = renderSandbox.sandboxStatus(inst);
-      res.json({ ok: true, app, sandbox, env_vars: envVars, values_held: false });
+      // Promoting from it (ADR 0406 §2, task 1005290): whether the owner can, and the record.
+      const promote = { ...renderPromote.promoteView(inst), recent: await renderPromote.listPromotions(pool, id) };
+      res.json({ ok: true, app, sandbox, promote, env_vars: envVars, values_held: false });
     } catch (err) {
       log.error('[provisioning] GET /provisioning/instances/:id/render', err && err.message);
       failFrom(res, err, 'render_status_failed');
@@ -139,7 +146,7 @@ module.exports = function buildRenderStandupRouter({ fetchImpl } = {}) {
       const r = await renderSandbox.enqueueSandboxAdd(pool, id, { keyEnc: api.secretBox.encrypt(req.body.key), requestedBy: 'api:self' });
       if (r.conflict) {
         return res.fail('intent_conflict', { status: 409,
-          message: `A '${r.intent.action}' run is ${r.intent.state} for this project, so your key was not kept. Try again once it has finished.`,
+          message: BUSY_KEY_NOT_KEPT,
           details: { action: r.intent.action, state: r.intent.state } });
       }
       await provisioning.recordEvent(pool, {
@@ -155,6 +162,78 @@ module.exports = function buildRenderStandupRouter({ fetchImpl } = {}) {
     }
   });
 
+  // POST /provisioning/instances/:id/render/promote/look — rank: any authenticated builder,
+  // and OWNER ONLY. What is waiting on the sandbox to go live (ADR 0406 §2, task 1005290):
+  // the change the live app runs, and every change that has run on the sandbox since, newest
+  // first. A read-only look at Render on the owner's key held for this one request (ADR 0348
+  // as widened by ADR 0406 §11): GET only, never stored, logged or sent back.
+  router.post('/provisioning/instances/:id/render/promote/look', api.requireBuilder, lookupLimit, async (req, res) => {
+    const id = parseId(req, res, { positiveInt: true });
+    if (!id) return;
+    if (validateOrRespond(req, res, { key: { required: true, type: 'string', maxLength: 200 } })) return;
+    try {
+      const inst = await provisioning.getInstanceById(pool, id);
+      if (!ownedBy(inst, req.builder)) return res.fail('instance_not_found', 404);
+      if (!renderStandup.KEY_RE.test(req.body.key)) return res.fail('render_request_invalid', { status: 400, message: 'That doesn’t look like a Render API key. It starts with “rnd_”.' });
+      const why = renderPromote.noPromoteReason(inst);
+      if (why) return res.fail('promote_unavailable', { status: 409, message: why });
+      const h = inst.app_host;
+      const out = await lookupPromotion(req.body.key, { ownerId: h.ownerId, liveServiceId: h.serviceId, sandboxServiceId: h.sandbox.serviceId, fetchImpl: fetchImpl || globalThis.fetch });
+      res.json({ ok: true, ...out });
+    } catch (err) {
+      if (err instanceof RenderLookupError) return res.fail(err.code, { status: LOOKUP_STATUS[err.code] || 502, message: err.message });
+      log.error('[provisioning] POST /provisioning/instances/:id/render/promote/look', err && err.message);
+      failFrom(res, err, 'render_lookup_failed');
+    }
+  });
+
+  // POST /provisioning/instances/:id/render/promote — rank: any authenticated builder, and
+  // OWNER ONLY: the key and the live app are the owner's, so the server decides only the
+  // owner may move it (an archon on someone else's project gets the stranger's 404). Takes
+  // the change the owner chose (`commit_id`) and the change live ran when they looked
+  // (`expect_live_commit`); the runner refuses if either moved. This is the ONLY way Bongos
+  // moves a live app that has a sandbox, and the reply is a receipt: nothing is live yet.
+  router.post('/provisioning/instances/:id/render/promote', api.requireBuilder, sandboxLimit, async (req, res) => {
+    const id = parseId(req, res, { positiveInt: true });
+    if (!id) return;
+    if (validateOrRespond(req, res, {
+      key: { required: true, type: 'string', maxLength: 200 },
+      commit_id: { required: true, type: 'string', maxLength: 64 },
+      expect_live_commit: { type: 'string', maxLength: 64 },
+    })) return;
+    try {
+      const inst = await provisioning.getInstanceById(pool, id);
+      if (!ownedBy(inst, req.builder)) return res.fail('instance_not_found', 404);
+      if (!renderStandup.KEY_RE.test(req.body.key)) return res.fail('render_request_invalid', { status: 400, message: 'That doesn’t look like a Render API key. It starts with “rnd_”.' });
+      const commit = String(req.body.commit_id).trim().toLowerCase();
+      const expect = req.body.expect_live_commit == null ? null : String(req.body.expect_live_commit).trim().toLowerCase();
+      if (!renderPromote.COMMIT_RE.test(commit) || (expect !== null && !renderPromote.COMMIT_RE.test(expect))) {
+        return res.fail('promote_request_invalid', { status: 400, message: 'Choose one of the changes waiting on your sandbox.' });
+      }
+      const why = renderPromote.noPromoteReason(inst);
+      if (why) return res.fail('promote_unavailable', { status: 409, message: why });
+      if (!api.secretBox.isConfigured()) {
+        return res.fail('render_unavailable', { status: 503, message: 'The platform can’t take a key safely right now, so nothing was sent. Try again later.' });
+      }
+      const r = await renderPromote.enqueuePromote(pool, id, { keyEnc: api.secretBox.encrypt(req.body.key), commitId: commit, expectLiveCommit: expect, requestedBy: req.builder.id });
+      if (r.conflict) {
+        return res.fail('intent_conflict', { status: 409,
+          message: BUSY_KEY_NOT_KEPT,
+          details: { action: r.intent.action, state: r.intent.state } });
+      }
+      await provisioning.recordEvent(pool, {
+        instanceId: id, ownerBuilderId: inst.owner_builder_id, event: 'render-promote',
+        detail: `promote of ${commit.slice(0, 7)} to the live app requested by owner`, actor: 'api:self',
+      }).catch(() => {});
+      res.json({ ok: true, queued: true, action: 'render-promote',
+        message: 'Queued. That change goes to your live app in a moment; Render then builds it, which usually takes a few minutes. Your key is used once and then thrown away.' });
+    } catch (err) {
+      // Never log the request: it carries the key.
+      log.error('[provisioning] POST /provisioning/instances/:id/render/promote', err && err.message);
+      failFrom(res, err, 'render_promote_failed');
+    }
+  });
+
   // POST /provisioning/instances/:id/render — rank: any authenticated builder, and OWNER
   // ONLY: the key is the owner's and so is the account it acts in, so an archon on
   // someone else's project gets the same 404 as a stranger. The reply is a receipt;