@bongos/core 1.21.95 → 1.21.97

package/modules/provisioning/github-setup.js

@@ -37,8 +37,27 @@ const SETUP_EVENTS = Object.freeze({
   installReported: 'github-app-install-reported',
   installed: 'github-app-installed',
   deviceFlow: 'github-app-device-flow',
+  // the organisation the founder chose to make the app on (task 1004651); its detail is
+  // the org's login. Written by the mint route; absent = the founder's personal account.
+  appOrg: 'github-app-org',
+  // the founder pressed "Pick up where it stopped" or "Check again" (task 1004652). Like an
+  // install report it re-opens the runner's checking window; it claims nothing itself.
+  checkRequested: 'github-app-check-requested',
 });
 
+const { effectiveManifestStatus } = require('./manifest-truth');
+
+// GitHub's manifest conversion code lasts an hour from GitHub's redirect, and the redirect
+// comes after the link was minted, so an attempt younger than this can still be converted
+// with the code it already holds — no new approval, so no second app (task 1004652).
+const CODE_LIFE_MS = 60 * 60 * 1000;
+
+// A GitHub login (1-39 chars, letters/digits and single inner hyphens). The org name the
+// mint route takes from the page passes this before it reaches a GitHub URL, and the
+// recorded one passes it again before it reaches a link. PURE.
+const GITHUB_LOGIN_RE = /^[A-Za-z0-9](?:[A-Za-z0-9]|-(?=[A-Za-z0-9])){0,38}$/;
+function validGithubLogin(s) { return typeof s === 'string' && GITHUB_LOGIN_RE.test(s); }
+
 // How long after an attempt settles the runner keeps checking for the install and the
 // device-flow tick. Past it the checklist stops promising a self-tick for device flow
 // (the step says "turn it on later"); a fresh install report re-opens the window.
@@ -65,16 +84,24 @@ function targetRepo(inst) {
 // The verified facts for one instance since `since` (the attempt's created_at): when each
 // setup event was first seen, or null. One indexed read (idx_provisioning_events_instance).
 async function githubSetupFacts(db, instanceId, since) {
+  // `detail` is the newest row's, for the one event that carries a value (appOrg)
   const { rows } = await db.query(
-    `SELECT event, min(created_at) AS at FROM provisioning_events
+    `SELECT event, min(created_at) AS at, (array_agg(detail ORDER BY created_at DESC))[1] AS detail
+       FROM provisioning_events
       WHERE instance_id = $1 AND event = ANY($2) AND created_at >= $3
       GROUP BY event`,
     [instanceId, Object.values(SETUP_EVENTS), since || new Date(0).toISOString()]);
+  const find = (name) => rows.find((x) => x.event === name);
   const at = (name) => {
-    const r = rows.find((x) => x.event === name);
+    const r = find(name);
     return r && r.at ? new Date(r.at).toISOString() : null;
   };
-  return { installReportedAt: at(SETUP_EVENTS.installReported), installedAt: at(SETUP_EVENTS.installed), deviceFlowAt: at(SETUP_EVENTS.deviceFlow) };
+  const org = find(SETUP_EVENTS.appOrg);
+  return {
+    installReportedAt: at(SETUP_EVENTS.installReported), installedAt: at(SETUP_EVENTS.installed), deviceFlowAt: at(SETUP_EVENTS.deviceFlow),
+    checkRequestedAt: at(SETUP_EVENTS.checkRequested),
+    appOrg: org && validGithubLogin(org.detail) ? org.detail : null,
+  };
 }
 
 // Each checklist step's state, from the latest attempt's EFFECTIVE status (manifest-truth's
@@ -101,10 +128,65 @@ function githubChecklist(status, appSlug, facts = {}) {
 // device-flow step can still tick itself, so the page keeps polling. PURE.
 function stillVerifying(row, facts = {}, now = Date.now()) {
   const settled = row && (row.resolved_at || row.updated_at);
-  const last = Math.max(settled ? new Date(settled).getTime() : 0, facts.installReportedAt ? new Date(facts.installReportedAt).getTime() : 0);
+  const t = (iso) => (iso ? new Date(iso).getTime() : 0);
+  const last = Math.max(t(settled), t(facts.installReportedAt), t(facts.checkRequestedAt));
   return last > 0 && now - last < VERIFY_WINDOW_MS;
 }
 
+// What "Pick up where it stopped" does for this attempt (task 1004652) — a closed
+// vocabulary, and never "make another app" once GitHub has made one:
+//   'reopen'   — the link is still waiting on GitHub: post the SAME attempt again.
+//   'fresh'    — nothing was made on GitHub (the link lapsed, or the runner never took
+//                it up): a new link is safe.
+//   'convert'  — GitHub approved and the code it gave is still young: convert it again.
+//   'check'    — the app exists with its keys placed, a step is unverified and the runner
+//                has stopped checking: ask it to look again (sign-in, install, device flow).
+//   'operator' — GitHub approved but the app's keys never reached us and its code is
+//                spent or too old: only the platform team can finish it.
+//   null       — nothing to pick up: in flight, still being checked, or all done.
+// PURE.
+function pickUpFor(row, status, checklist, verifying, now = Date.now()) {
+  if (!row) return null;
+  if (status === 'pending') return 'reopen';
+  if (status === 'expired') return 'fresh';
+  if (row.app_slug || row.app_id) {
+    if (checklist && checklist.connected && checklist.device_flow === 'done') return null;
+    return verifying ? null : 'check';
+  }
+  if (status !== 'error') return null;
+  if (!(Number(row.attempts) > 0)) return 'fresh';
+  const age = now - new Date(row.created_at || 0).getTime();
+  return row.github_code && age < CODE_LIFE_MS ? 'convert' : 'operator';
+}
+
+// May the mint route make a new link for this instance, given its latest attempt (task
+// 1004652)? null = yes. { reuse } = the latest link is still waiting on GitHub, so hand
+// back the SAME state (a second click, a reopened tab, another device) instead of a second
+// attempt. { refuse, message } = GitHub has approved an app for this project already, so a
+// new link would make a second one. PURE.
+function mintGuard(row, now = Date.now()) {
+  if (!row) return null;
+  const status = effectiveManifestStatus(row, now);
+  if (status === 'pending') return { reuse: row.state, expiresAt: new Date(row.expires_at).toISOString() };
+  if (status === 'expired' || (status === 'error' && !(Number(row.attempts) > 0) && !row.app_id)) return null;
+  if (status === 'code_received' || status === 'converting') {
+    return { refuse: 'github_in_progress', message: 'GitHub already approved this project’s app, and the platform is finishing it. The checklist ticks itself.' };
+  }
+  return { refuse: 'app_exists', message: 'GitHub already made this project’s app, so we won’t make a second one. Pick up where it stopped instead.' };
+}
+
+// Put an approved attempt whose conversion stopped back in the runner's queue, with the
+// code it still holds (pickUpFor 'convert'). The attempt count restarts so the runner
+// tries it again. Only an attempt still in that shape moves; false otherwise.
+async function requeueConversion(db, id) {
+  const { rows } = await db.query(
+    `UPDATE provisioning_oauth_manifests
+        SET status = 'code_received', attempts = 0, last_error = NULL, resolved_at = NULL, updated_at = now()
+      WHERE id = $1 AND status = 'error' AND app_id IS NULL AND github_code IS NOT NULL
+      RETURNING id`, [id]);
+  return rows.length > 0;
+}
+
 // What the public status poll and the owner's instance read add for this leg: the checklist,
 // the install link (until the install is verified), the repo it belongs on, and whether the
 // runner is still checking. `status` is manifest-truth's EFFECTIVE status. Never the raw row.
@@ -113,17 +195,26 @@ function stillVerifying(row, facts = {}, now = Date.now()) {
 // lands on the setup page, which sends the founder back to their projects.
 // A failed facts read is "nothing verified yet" — the honest 'now' states, never a 500.
 async function githubSetupRead(db, inst, row, status, { now = Date.now(), withState = true } = {}) {
-  if (!row) return { checklist: githubChecklist(null, null), install_url: null, repo: targetRepo(inst), verifying: false };
+  if (!row) return { checklist: githubChecklist(null, null), install_url: null, repo: targetRepo(inst), verifying: false, app_org: null, pick_up: null };
   let facts = {};
   // through module.exports so a route test can stub the one DB read on the cached module
   try { facts = await module.exports.githubSetupFacts(db, row.instance_id, row.created_at); } catch (_) { facts = {}; }
   const checklist = githubChecklist(status, row.app_slug, facts);
+  const verifying = stillVerifying(row, facts, now);
   return {
     checklist,
     install_url: checklist.install === 'done' ? null : installUrlFor({ appSlug: row.app_slug, state: withState ? row.state : null }),
     repo: targetRepo(inst),
-    verifying: stillVerifying(row, facts, now),
+    verifying,
+    // what "Pick up where it stopped" will do (task 1004652); never a secret, never the code
+    pick_up: pickUpFor(row, status, checklist, verifying, now),
+    // the organisation this attempt makes the app on, or null for the founder's account
+    // (task 1004651): the page links the app's settings under the right owner
+    app_org: validGithubLogin(facts.appOrg) ? facts.appOrg : null,
   };
 }
 
-module.exports = { SETUP_EVENTS, VERIFY_WINDOW_MS, installUrlFor, targetRepo, githubSetupFacts, githubChecklist, stillVerifying, githubSetupRead };
+module.exports = {
+  SETUP_EVENTS, VERIFY_WINDOW_MS, installUrlFor, targetRepo, githubSetupFacts, githubChecklist, stillVerifying, githubSetupRead,
+  validGithubLogin, pickUpFor, mintGuard, requeueConversion,
+};

package/modules/provisioning/routes/github-setup.js

@@ -91,7 +91,8 @@ module.exports = function buildGithubSetupRouter() {
         status,
         failure,
         ready: status === 'done',
-        terminal: failed || (setup.checklist.connected && (setup.checklist.device_flow === 'done' || !setup.verifying)),
+        // a stopped sign-in the runner is still re-checking is not the end (task 1004652)
+        terminal: (failed && !setup.verifying) || (setup.checklist.connected && (setup.checklist.device_flow === 'done' || !setup.verifying)),
         domain: inst && inst.domain ? inst.domain : null,
         instance_status: inst ? inst.status : null,
         // The App's public slug (task 1003049) — its GitHub page is public by design.
@@ -100,6 +101,8 @@ module.exports = function buildGithubSetupRouter() {
         install_url: setup.install_url,
         repo: setup.repo,
         verifying: setup.verifying,
+        app_org: setup.app_org,
+        pick_up: setup.pick_up,
       });
     } catch (err) {
       log.error('[provisioning] GET /provisioning/github-app/status', err);
@@ -183,6 +186,46 @@ module.exports = function buildGithubSetupRouter() {
     }
   });
 
+  // POST /provisioning/instances/:id/github-app/pick-up — "Pick up where it stopped" and
+  // "Check again" (task 1004652). It resumes the latest attempt from the step it stopped at,
+  // with the app GitHub already made, and never mints a new link: 'convert' puts an approved
+  // attempt whose code is still young back in the runner's queue; 'check' records a check
+  // request, which re-opens the runner's checking window for sign-in, the install and
+  // device flow. Every other pick-up is the page's own ('reopen' and 'fresh' go through the
+  // mint route, whose guard reuses or refuses; 'operator' files a blocker), so they are a
+  // 409 naming the action. Answers with the fresh read. rank: any authenticated builder
+  // (requireBuilder), the project's OWNER only — no Archon override, as with the mint route;
+  // anyone else gets the same 404 as a missing project.
+  router.post('/provisioning/instances/:id/github-app/pick-up', api.requireBuilder, returnRateLimit, async (req, res) => {
+    const id = /^\d{1,12}$/.test(String(req.params.id)) ? Number(req.params.id) : null;
+    if (!id) return res.fail('bad_id', 400);
+    try {
+      const inst = await provisioning.getInstanceById(pool, id);
+      if (!ownsLanding(inst, req.builder && req.builder.id)) return res.fail('instance_not_found', 404);
+      const row = await provisioning.getLatestOAuthManifestForInstance(pool, id);
+      const read = async (r) => githubSetup.githubSetupRead(pool, inst, r, r ? provisioning.publicGithubApp(r).status : null, { withState: false });
+      const before = await read(row);
+      const action = before.pick_up;
+      if (action === 'convert') {
+        if (!(await githubSetup.requeueConversion(pool, row.id))) return res.fail('nothing_to_pick_up', { status: 409, message: 'This step has already moved on.' });
+      } else if (action === 'check') {
+        await provisioning.recordEvent(pool, {
+          instanceId: id, ownerBuilderId: req.builder.id, event: githubSetup.SETUP_EVENTS.checkRequested,
+          detail: 'the founder asked to pick up the GitHub setup where it stopped', actor: 'api:self',
+        });
+      } else {
+        return res.fail('nothing_to_pick_up', { status: 409, message: 'Nothing to pick up here.', action: action || null });
+      }
+      const after = await provisioning.getLatestOAuthManifestForInstance(pool, id);
+      const pub = provisioning.publicGithubApp(after);
+      const setup = await read(after);
+      return res.json({ ok: true, action, status: pub.status, failure: pub.failure, app_slug: after.app_slug || null, ...setup });
+    } catch (err) {
+      log.error('[provisioning] POST /provisioning/instances/:id/github-app/pick-up', err);
+      return res.status(500).json({ ok: false, error: 'pick_up_failed' });
+    }
+  });
+
   // GET /provisioning/github-app/resume[?id=<n>] — the project page's "which project am I
   // connecting?" read when its tab remembers nothing (task 1004650): a hand-back on another
   // device, a fresh tab, a cleared browser. With an id: that project, if the caller owns it.

package/modules/provisioning/routes/provisioning.js

@@ -1230,11 +1230,22 @@ module.exports = function provisioningRoutes() {
   // GitHub, the owner approves, and GitHub redirects back to the public callback below.
   // The web tier only RECORDS the attempt (state token) — the control-plane runner does
   // the token exchange + cred placement (trust boundary intact, ADR 0111 §2).
-  // Body: { account? ('personal'|'org') }.
+  // Body: { account? ('personal'|'org'), org? (a GitHub organisation login) }.
+  // A personal or an organisation account (task 1004651): account 'org' makes the app on
+  // the organisation the founder chose on the page (`org`), else on the repo's owner. The
+  // org name is checked against GitHub's login rules here, never trusted from the page;
+  // whether the founder may make an app there is GitHub's to enforce on its own page
+  // (this module holds no GitHub token to ask with, ADR 0111 §2). Anything other than
+  // account 'org' is the founder's personal account, exactly as before.
   router.post('/provisioning/instances/:id/github-app', auth.requireBuilder, async (req, res) => {
     const id = parseId(req, res); // (req, res) — parseId sends 400 bad_id + returns null on failure
     if (!id) return;
-    if (validateOrRespond(req, res, { account: { type: 'string', maxLength: 12 } })) return;
+    if (validateOrRespond(req, res, { account: { type: 'string', maxLength: 12 }, org: { type: 'string', maxLength: 39 } })) return;
+    const wantsOrg = !!(req.body && req.body.account === 'org');
+    const typedOrg = wantsOrg && typeof req.body.org === 'string' ? req.body.org.trim() : '';
+    if (typedOrg && !githubSetup.validGithubLogin(typedOrg)) {
+      return res.fail('bad_org', { status: 400, message: 'That isn’t a GitHub organisation name: letters, numbers and single dashes, up to 39.' });
+    }
     try {
       const inst = await provisioning.getInstanceById(pool, id);
       if (!inst || String(inst.owner_builder_id) !== String(req.builder.id)) {
@@ -1249,20 +1260,38 @@ module.exports = function provisioningRoutes() {
       if (!origin) {
         return res.fail('mothership_origin_unset', { status: 500, message: 'This control plane has no publicOrigin configured — cannot build the GitHub redirect URL.' });
       }
-      const state = crypto.randomBytes(32).toString('hex');
-      const expiresAt = new Date(Date.now() + MANIFEST_STATE_TTL_MS).toISOString();
-      await provisioning.createOAuthManifest(pool, { instanceId: id, state, requestedBy: req.builder.id, expiresAt });
+      // the org candidate: the one the founder chose, else the repo's owner (a login only)
+      const repoOwner = ownerFromTargetRef(inst.target_ref);
+      const orgLogin = typedOrg || (githubSetup.validGithubLogin(repoOwner) ? repoOwner : null);
+      // an explicit organisation choice never falls back to the personal account unseen
+      if (wantsOrg && !orgLogin) {
+        return res.fail('org_required', { status: 400, message: 'Name the GitHub organisation to make the app on.' });
+      }
+      const account = wantsOrg ? 'org' : 'personal';
+      // never a second app (task 1004652): a link still waiting on GitHub is handed back,
+      // and once GitHub has approved one for this project no new link is made
+      const guard = githubSetup.mintGuard(await provisioning.getLatestOAuthManifestForInstance(pool, id));
+      if (guard && guard.refuse) return res.fail(guard.refuse, { status: 409, message: guard.message });
+      const state = guard ? guard.reuse : crypto.randomBytes(32).toString('hex');
+      const expiresAt = guard ? guard.expiresAt : new Date(Date.now() + MANIFEST_STATE_TTL_MS).toISOString();
+      if (!guard) await provisioning.createOAuthManifest(pool, { instanceId: id, state, requestedBy: req.builder.id, expiresAt });
       await provisioning.recordEvent(pool, {
         instanceId: id, ownerBuilderId: req.builder.id, event: 'oauth-manifest-start',
-        detail: 'GitHub App Manifest link minted', actor: 'api:self',
+        detail: guard ? 'GitHub App Manifest link reopened (same attempt)' : 'GitHub App Manifest link minted', actor: 'api:self',
       }).catch(() => {});
+      // which account owns this attempt's app, so the page can link its settings there
+      // from any tab or device (github-setup.js reads it back as app_org)
+      if (account === 'org') {
+        await provisioning.recordEvent(pool, {
+          instanceId: id, ownerBuilderId: req.builder.id, event: githubSetup.SETUP_EVENTS.appOrg,
+          detail: orgLogin, actor: 'api:self',
+        }).catch(() => {});
+      }
 
       const manifest = provisioning.buildGithubAppManifest({
         instanceName: inst.slug, slug: inst.slug, instanceDomain: inst.domain,
         mothershipOrigin: origin, brand: mothershipBrand(),
       });
-      const orgLogin = ownerFromTargetRef(inst.target_ref);
-      const account = req.body && req.body.account === 'org' && orgLogin ? 'org' : 'personal';
       res.json({
         state,
         account,