@bongos/core 1.21.94 → 1.21.96

package/modules/provisioning/github-setup.js

@@ -37,8 +37,17 @@ 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',
 });
 
+// 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 +74,23 @@ 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),
+    appOrg: org && validGithubLogin(org.detail) ? org.detail : null,
+  };
 }
 
 // Each checklist step's state, from the latest attempt's EFFECTIVE status (manifest-truth's
@@ -113,7 +129,7 @@ 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 };
   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 = {}; }
@@ -123,7 +139,13 @@ async function githubSetupRead(db, inst, row, status, { now = Date.now(), withSt
     install_url: checklist.install === 'done' ? null : installUrlFor({ appSlug: row.app_slug, state: withState ? row.state : null }),
     repo: targetRepo(inst),
     verifying: stillVerifying(row, facts, 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,
+};

package/modules/provisioning/routes/callback-page.js

@@ -27,6 +27,16 @@ function esc(s) {
   ));
 }
 
+// The way back to the project (task 1004650): the hub's return route, keyed on the attempt's
+// one-time state. The SERVER resolves that state to the project it was minted for and lands
+// its signed-in owner on that project's part 03 (routes/github-setup.js), so the hand-back no
+// longer depends on what the starting tab kept in sessionStorage — approving on a phone or in
+// another window lands on the right project. No state names no project: the projects list.
+const RETURN_PATH = '/api/bongos/provisioning/github-app/return';
+function returnHref(state) {
+  return state ? `${RETURN_PATH}?state=${encodeURIComponent(state)}` : '/projects?view=mine';
+}
+
 // Accent pair resolved from the instance's own branding — the pack is the palette
 // authority (task 1002810); the literal fallbacks are the neutral pack's values, so
 // a branding validation error still paints the current family, never a stale one.
@@ -65,15 +75,15 @@ code{font-family:"Fira Code",ui-monospace,SFMono-Regular,monospace;background:rg
 // page hands them straight back: as the wizard's pop-up it closes itself so the checklist
 // tab is in front again (that tab is already polling the same status and shows the wait);
 // if the browser refuses the close, or this was a same-tab return (pop-up blocked), this
-// tab becomes the checklist. The one-time state rides the URL FRAGMENT — never sent to a
-// server — so a checklist opened here can keep watching the same attempt.
+// tab becomes the checklist. The way back is the return route (returnHref above): the
+// server names the project for the state, so the checklist opened here is the right one
+// whatever this browser remembers (task 1004650).
 // Deliberately contains NO backticks and NO ${...} so it survives the outer template
 // literal verbatim; the only server data it reads is the JSON config block above it.
 const HANDBACK_SCRIPT = `
 (function(){
   var cfg=window.__CB_SETUP__||{};
-  var back=cfg.back||'/projects?view=new';
-  if(cfg.state)back+='#ghstate='+encodeURIComponent(cfg.state);
+  var back=cfg.back||'/projects?view=mine';
   var link=document.getElementById('back');if(link)link.href=back;
   var popup=false;
   try{popup=!!window.opener&&!window.opener.closed;}catch(e){}
@@ -94,8 +104,7 @@ const HANDBACK_SCRIPT = `
 const INSTALL_SCRIPT = `
 (function(){
   var cfg=window.__CB_SETUP__||{};
-  var back=cfg.back||'/projects?view=new';
-  if(cfg.state)back+='#ghstate='+encodeURIComponent(cfg.state);
+  var back=cfg.back||'/projects?view=mine';
   var link=document.getElementById('back');if(link)link.href=back;
   var note=document.getElementById('note');
   var say=function(t){if(note)note.textContent=t;};
@@ -142,7 +151,8 @@ const INSTALL_SCRIPT = `
 //     + `body` (server-authored, trusted HTML).
 function callbackPage({ ok, title, body, state, domain, next }) {
   const handback = !!(ok && state && domain);
-  const cfgJson = JSON.stringify({ state: state || '', domain: domain || '', back: '/projects?view=new' }).replace(/</g, '\\u003c');
+  const back = returnHref(state);
+  const cfgJson = JSON.stringify({ state: state || '', domain: domain || '', back }).replace(/</g, '\\u003c');
   const head = `<!doctype html><html lang="en"><head><meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <meta name="color-scheme" content="light dark">
@@ -157,7 +167,7 @@ function callbackPage({ ok, title, body, state, domain, next }) {
   <h1>${esc(title)}</h1>
   <p class="sub">Next, install it on your repo. Taking you there now.</p>
   <p class="muted" id="note" role="status" aria-live="polite">Waiting for GitHub to hand over the app…</p>
-  <div class="cta"><a class="btn" id="back" href="/projects?view=new">Back to my project</a></div>
+  <div class="cta"><a class="btn" id="back" href="${esc(back)}">Back to my project</a></div>
 </main>
 <script>window.__CB_SETUP__=${cfgJson};</script>
 <script>${INSTALL_SCRIPT}</script>
@@ -169,7 +179,7 @@ function callbackPage({ ok, title, body, state, domain, next }) {
   <div class="badge-warn">✓</div>
   <h1>${esc(title)}</h1>
   <p class="sub">Taking you back to your setup checklist — it finishes setting up <code>${esc(domain)}</code> there.</p>
-  <div class="cta"><a class="btn" id="back" href="/projects?view=new">Back to my checklist →</a></div>
+  <div class="cta"><a class="btn" id="back" href="${esc(back)}">Back to my checklist →</a></div>
 </main>
 <script>window.__CB_SETUP__=${cfgJson};</script>
 <script>${HANDBACK_SCRIPT}</script>
@@ -184,4 +194,4 @@ function callbackPage({ ok, title, body, state, domain, next }) {
 </body></html>`;
 }
 
-module.exports = { esc, callbackPage };
+module.exports = { esc, callbackPage, returnHref, RETURN_PATH };

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

@@ -9,6 +9,12 @@
 // single-use `state` minted for the signed-in owner is the only key, and neither route
 // reveals a secret or changes authority. The checklist they report is derived in
 // ../github-setup.js from what the control-plane runner has VERIFIED.
+//
+// Two signed-in routes join them (task 1004650 — the hand-back from any tab or device):
+// the RETURN route the callback and setup pages send the founder to, which lands the state's
+// own project for its owner and nobody else, and the RESUME read the project page asks when
+// its tab remembers nothing — so a phone, a second window or a fresh tab picks up part 03 of
+// the right project from what the server knows, never from sessionStorage.
 'use strict';
 
 const express = require('express');
@@ -17,10 +23,38 @@ const { pool } = api;
 const provisioning = require('../provisioning');
 const githubSetup = require('../github-setup');
 const { makeAskRateLimiter } = require('../rate-limit');
-const { callbackPage } = require('./callback-page');
+const { callbackPage, returnHref } = require('./callback-page');
 
 const log = api.logger('provisioning');
 
+// The state tokens this leg mints are hex (provisioning.js); anything else is not one of ours.
+const STATE_RE = /^[0-9a-f]{16,128}$/i;
+
+// An attempt or a project older than this is not "in progress" for the resume read: a
+// founder who walked away a week ago and opens the create page gets a fresh page.
+const RESUME_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+
+// Is this instance one the hand-back may land on for this builder? Strictly the OWNER —
+// no Archon override: the return route names a project to whoever holds the state, and a
+// project page is where its owner, and only its owner, connects GitHub. A gone project is
+// no landing either. PURE.
+function ownsLanding(inst, builderId) {
+  return !!(inst && builderId != null && String(inst.owner_builder_id) === String(builderId)
+    && !inst.torn_down_at && inst.status !== 'torn_down');
+}
+
+// The project page's resume record: just what part 03 needs to name and watch the project
+// (the page reads the rest from the owner's instance read). Never the state token. PURE.
+function resumeRecord(inst) {
+  return { id: inst.id, slug: inst.slug, domain: inst.domain || null, onboard_mode: inst.onboard_mode || 'greenfield', repo: githubSetup.targetRepo(inst) };
+}
+
+// The project page to land on: part 03 of that project, by id. The state rides the
+// FRAGMENT (never sent to a server) so the page can keep watching that attempt. PURE.
+function landingHref(instanceId, state) {
+  return `/projects?view=new&id=${encodeURIComponent(String(instanceId))}${state ? `#ghstate=${encodeURIComponent(state)}` : ''}`;
+}
+
 // GitHub's installation id is digits; anything else is dropped before it reaches a log line.
 function installationIdOf(q) {
   const s = String((q && q.installation_id) || '');
@@ -32,6 +66,7 @@ module.exports = function buildGithubSetupRouter() {
   // the page polls every few seconds, the callback page every two — per-IP, in-module
   const statusRateLimit = makeAskRateLimiter({ max: 120 });
   const setupRateLimit = makeAskRateLimiter({ max: 30 });
+  const returnRateLimit = makeAskRateLimiter({ max: 30 });
 
   // GET /provisioning/github-app/status?state=<> — the PUBLIC progress read (task 1004548;
   // the checklist since task 1004649). Reveals the manifest lifecycle status, the
@@ -65,6 +100,7 @@ module.exports = function buildGithubSetupRouter() {
         install_url: setup.install_url,
         repo: setup.repo,
         verifying: setup.verifying,
+        app_org: setup.app_org,
       });
     } catch (err) {
       log.error('[provisioning] GET /provisioning/github-app/status', err);
@@ -85,7 +121,7 @@ module.exports = function buildGithubSetupRouter() {
     const sendPage = (status, page) => res.status(status).type('html').send(page);
     try {
       const state = String(req.query.state || '');
-      const row = /^[0-9a-f]{16,128}$/i.test(state) ? await provisioning.getOAuthManifestByState(pool, state) : null;
+      const row = STATE_RE.test(state) ? await provisioning.getOAuthManifestByState(pool, state) : null;
       if (!row) {
         return sendPage(200, callbackPage({ ok: true, title: 'Installed on GitHub',
           body: '<p>GitHub has installed the app. Go back to your project’s page: it checks the install itself.</p><p><a class="btn" href="/projects?view=mine">Back to my projects →</a></p>' }));
@@ -109,5 +145,78 @@ module.exports = function buildGithubSetupRouter() {
     }
   });
 
+  // GET /provisioning/github-app/return?state=<> — where the callback and setup pages send
+  // the founder back (task 1004650). The SERVER resolves the one-time state to the project
+  // it was minted for and 302s that project's signed-in OWNER to its part 03
+  // (/projects?view=new&id=<id>), so the hand-back works from any tab, window or device —
+  // nothing in browser storage is read. Not signed in → through the web sign-in and back
+  // here. Signed in as anyone else, an unknown or malformed state, or a gone project → one
+  // refusal page that names no project (no oracle about which). The state stays single-use
+  // where it matters: only the manifest callback's code exchange consumes it, and this route
+  // changes nothing — it reveals a project's page only to the person who already owns it.
+  // rank: public — as a GATE: it is a browser redirect, so no middleware 401s a signed-out
+  // visitor (they are sent through sign-in instead). WHO lands is decided in-handler from
+  // the live session: the project's own owner, no Archon override, and nobody else ever
+  // learns which project the state names. It reveals no secret and writes nothing.
+  router.get('/provisioning/github-app/return', returnRateLimit, async (req, res) => {
+    res.set('Cache-Control', 'no-store');
+    res.set('Referrer-Policy', 'no-referrer');
+    const refuse = () => res.status(404).type('html').send(callbackPage({ ok: false, title: 'This isn’t your project',
+      body: '<p>This link is for a project on another account, or it has expired — sign in with the account that started the project, or open your own projects.</p><p><a class="btn" href="/projects?view=mine">My projects →</a></p>' }));
+    try {
+      const state = String(req.query.state || '');
+      if (!STATE_RE.test(state)) return refuse();
+      const session = await api.resolveSession(req);
+      if (!session) {
+        // the relative return passes the web flow's open-redirect guard (safeReturnTo);
+        // the repo scope rides every hub sign-in door (ADR 0364)
+        return res.redirect(302, `/api/bongos/auth/web/start?return=${encodeURIComponent(returnHref(state))}&repos=1`);
+      }
+      if (session.status === 'inactive') return refuse();
+      const row = await provisioning.getOAuthManifestByState(pool, state);
+      const inst = row ? await provisioning.getInstanceById(pool, row.instance_id).catch(() => null) : null;
+      if (!ownsLanding(inst, session.builder_id)) return refuse();
+      return res.redirect(302, landingHref(inst.id, state));
+    } catch (err) {
+      log.error('[provisioning] GET /provisioning/github-app/return', err);
+      return res.status(500).type('html').send(callbackPage({ ok: false, title: 'Something went wrong',
+        body: '<p>We couldn’t find your project just now — it is on your projects page.</p><p><a class="btn" href="/projects?view=mine">My projects →</a></p>' }));
+    }
+  });
+
+  // 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.
+  // Without: the caller's newest project whose GitHub checklist is not connected yet, made or
+  // last tried within a week — so opening the create page later resumes part 03 from the
+  // server's view. Either way { project: null } when there is none; never the state token.
+  // rank: any authenticated builder (requireBuilder), own projects only — no Archon override.
+  router.get('/provisioning/github-app/resume', api.requireBuilder, async (req, res) => {
+    try {
+      const me = req.builder && req.builder.id;
+      const asked = String(req.query.id || '');
+      if (asked) {
+        if (!/^\d{1,12}$/.test(asked)) return res.json({ ok: true, project: null });
+        const inst = await provisioning.getInstanceById(pool, Number(asked)).catch(() => null);
+        return res.json({ ok: true, project: ownsLanding(inst, me) ? resumeRecord(inst) : null });
+      }
+      const now = Date.now();
+      const owned = (await provisioning.listInstancesForOwner(pool, me)).filter((i) => ownsLanding(i, me)).slice(0, 5);
+      // the (at most five) candidates are read together; the newest unfinished one wins
+      const open = await Promise.all(owned.map(async (inst) => {
+        const row = await provisioning.getLatestOAuthManifestForInstance(pool, inst.id);
+        const touched = Math.max(Date.parse(inst.created_at) || 0, row ? Date.parse(row.created_at) || 0 : 0);
+        if (now - touched > RESUME_WINDOW_MS) return false;
+        const setup = await githubSetup.githubSetupRead(pool, inst, row, row ? provisioning.publicGithubApp(row).status : null, { withState: false });
+        return !setup.checklist.connected;
+      }));
+      const found = owned.find((_inst, i) => open[i]);
+      return res.json({ ok: true, project: found ? resumeRecord(found) : null });
+    } catch (err) {
+      log.error('[provisioning] GET /provisioning/github-app/resume', err);
+      return res.status(500).json({ ok: false, error: 'resume_read_failed' });
+    }
+  });
+
   return router;
 };

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,6 +1260,14 @@ 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.' });
       }
+      // 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';
       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 });
@@ -1256,13 +1275,19 @@ module.exports = function provisioningRoutes() {
         instanceId: id, ownerBuilderId: req.builder.id, event: 'oauth-manifest-start',
         detail: '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,