@bongos/core 1.17.1 → 1.17.2

package/modules/provisioning/routes/provisioning.js

@@ -0,0 +1,607 @@
+// modules/provisioning/routes/provisioning.js — the provisioning module's HTTP
+// surface (ADR 0111 §1/§2, task #1942). Instance hosting + domains: the web-tier
+// REQUEST + STATE surface for standing up + operating a Cloud Bongos instance.
+//
+// THE TRUST BOUNDARY (ADR 0111 §2 / ADR 0016 / the dev-box /box precedent). The
+// internet-facing web process NEVER calls a cloud API and holds NO provider tokens.
+// A mutation route only ENQUEUES an intent (provision | teardown) into
+// provisioning_intents and returns; the control-plane runner (scripts/gds/
+// provision.js, task P3) is the sole token-holder that drains the queue and does
+// the real infra work. A stolen builder token can never spin up or tear down
+// infrastructure — it can only ask.
+//
+//   own-scoped (requireBuilder — the caller's OWN instances):
+//     POST   /provisioning/instances               — request a new instance
+//     GET    /provisioning/instances               — list the caller's instances
+//     GET    /provisioning/instances/:id           — read one of the caller's instances
+//     POST   /provisioning/instances/:id/teardown  — request teardown of one's own
+//   Archon-scoped (requireRank('archon') — the fleet, the /boxes precedent):
+//     GET    /provisioning/fleet                    — the full instance roster
+//     GET    /provisioning/fleet/cost-ledger        — per-instance + total cost estimate
+//     POST   /provisioning/instances/:id/force-teardown — tear down ANY instance
+//   public:
+//     GET    /provisioning/health                   — liveness + core version
+//
+// Reaches core ONLY through the doorway src/module-api.js (the one-way rule, ADR
+// 0083); it requires this module's own provisioning.js (same-dir), never a sibling.
+'use strict';
+
+const crypto = require('node:crypto');
+const express = require('express');
+const api = require('../../../src/module-api');
+const auth = api;
+const { pool, validateOrRespond, parseId } = api;
+const provisioning = require('../provisioning');
+const { onboardPlan } = require('../onboard-plan');
+const { makeAskRateLimiter } = require('../rate-limit');
+
+// How long a GitHub-App-Manifest `state` token is valid — the owner must click the
+// pre-filled link + approve on GitHub within this window (task 2080). Comfortably
+// under GitHub's own ~1h conversion-code TTL; long enough for a human round-trip.
+const MANIFEST_STATE_TTL_MS = 30 * 60 * 1000;
+
+// The mothership (control-plane) origin GitHub redirects the browser back to. Prefers a
+// dedicated `provisioningOrigin` (e.g. a `get.cloudbongos.com` front door) so the customer-
+// facing GitHub redirect_url carries the PLATFORM's brand, not the game's — a control plane
+// that co-hosts a game (OTB = customer 0) has a game-branded publicOrigin, which would leak
+// into every new customer's App (task 2101). Falls back to `publicOrigin` when unset, so an
+// instance whose publicOrigin is already the platform (e.g. cloudbongos.com) needs no config.
+// Fail-soft to '' so a mis-branded instance produces an obviously-broken (not silently-wrong) URL.
+function mothershipOrigin() {
+  try {
+    const d = api.branding().domains || {};
+    return d.provisioningOrigin || d.publicOrigin || '';
+  }
+  catch { return ''; }
+}
+
+// The provisioning mothership's product brand (e.g. "Cloud Bongos" on the control plane),
+// used to brand-qualify the auto GitHub App name so a common project slug ("demo") does
+// not collide with an existing GitHub App (task 2093). Portable — reads THIS instance's
+// own branding, never a hardcoded string. Fail-soft to null (→ githubAppName falls back).
+function mothershipBrand() {
+  try { return (api.branding().identity || {}).productName || null; }
+  catch { return null; }
+}
+
+// The org login candidate from an instance's target_ref ('owner/repo' → 'owner').
+// Advisory only: personal vs org changes only WHERE the App is created, never whether
+// sign-in works. Null when unparseable.
+function ownerFromTargetRef(ref) {
+  const m = String(ref || '').trim()
+    .replace(/^git@[^:]+:/, '').replace(/^https?:\/\/[^/]+\//, '')
+    .match(/^([A-Za-z0-9][A-Za-z0-9_.-]*)\//);
+  return m ? m[1] : null;
+}
+
+// Minimal HTML escaper for the callback landing page (no template engine here).
+function esc(s) {
+  return String(s == null ? '' : s).replace(/[&<>"']/g, (c) => (
+    { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]
+  ));
+}
+
+// Cloud Bongos brand styling for the standalone onboarding pages — sunrise palette +
+// Baloo 2 / Quicksand (brand/cloud-bongos/tokens.json). Light + dark aware; no external
+// dependency beyond an optional Google-Fonts link (system fallback if it doesn't load).
+const PAGE_STYLE = `
+:root{color-scheme:light dark;--sun:#f97316;--sun600:#ea580c;--coral:#fb7185;--sky:#38bdf8;--sky600:#0284c7;--ok:#16a34a;--warn:#f59e0b;--ink:#2a1f17;--inkSoft:#6b5d52;--card:#fffdfa;--line:#f0e2cf;--bg1:#fde8c8;--bg2:#fff4e6;--bg3:#fffdfa}
+@media (prefers-color-scheme:dark){:root{--ink:#f5efe6;--inkSoft:#cbbdad;--card:#241b13;--line:#3a2c1e;--bg1:#2a1d10;--bg2:#1b130b;--bg3:#130d07}}
+*{box-sizing:border-box}html,body{height:100%}
+body{margin:0;font-family:"Quicksand",system-ui,-apple-system,"Segoe UI",sans-serif;color:var(--ink);background:linear-gradient(180deg,var(--bg1) 0%,var(--bg2) 45%,var(--bg3) 100%);background-attachment:fixed;display:flex;align-items:center;justify-content:center;padding:1.5rem;-webkit-font-smoothing:antialiased;text-rendering:optimizeLegibility}
+.card{width:100%;max-width:30rem;background:var(--card);border:1px solid var(--line);border-radius:20px;padding:2.4rem 2rem 2rem;text-align:center;box-shadow:0 18px 50px -22px rgba(120,60,10,.4),0 2px 8px rgba(120,60,10,.07)}
+.badge-warn{font-size:2.4rem;line-height:1;margin:0 auto 1rem}
+h1{font-family:"Baloo 2",system-ui,sans-serif;font-weight:700;font-size:1.5rem;line-height:1.15;margin:.2rem 0 .55rem}
+.sub{color:var(--inkSoft);font-size:1.02rem;line-height:1.5;margin:0 auto;max-width:24rem}
+.sub p{margin:.6rem 0}
+code{font-family:"Fira Code",ui-monospace,SFMono-Regular,monospace;background:rgba(56,189,248,.14);color:var(--sky600);padding:.12em .45em;border-radius:6px;font-size:.9em;overflow-wrap:anywhere}
+@media (prefers-color-scheme:dark){code{color:var(--sky)}}
+.steps{display:flex;align-items:flex-start;justify-content:center;margin:1.9rem 0 1.1rem}
+.step{flex:1 1 0;max-width:9rem;position:relative}
+.step::before{content:"";position:absolute;top:16px;left:-50%;width:100%;height:3px;background:var(--line);z-index:0;transition:background .4s ease}
+.step:first-child::before{display:none}
+.dot{width:34px;height:34px;border-radius:50%;margin:0 auto;display:grid;place-items:center;background:var(--bg3);border:2px solid var(--line);color:var(--inkSoft);font-weight:700;font-size:.95rem;position:relative;z-index:1;transition:all .4s ease}
+.lbl{margin-top:.55rem;font-size:.78rem;color:var(--inkSoft);font-weight:600;line-height:1.25;padding:0 .2rem}
+.step.done .dot{background:var(--ok);border-color:var(--ok);color:#fff}
+.step.done::before{background:var(--ok)}
+.step.active .dot{border-color:var(--sun);color:var(--sun600);animation:pulse 1.5s ease-in-out infinite}
+.step.active .lbl{color:var(--ink)}
+.step.active .dot::after{content:"";position:absolute;inset:-3px;border-radius:50%;border:2px solid transparent;border-top-color:var(--sun);animation:spin .8s linear infinite}
+@keyframes spin{to{transform:rotate(360deg)}}
+@keyframes pulse{0%,100%{box-shadow:0 0 0 4px rgba(249,115,22,.15)}50%{box-shadow:0 0 0 9px rgba(249,115,22,.04)}}
+@media (prefers-reduced-motion:reduce){.step.active .dot,.step.active .dot::after{animation:none}}
+.status-line{min-height:1.4em;color:var(--inkSoft);font-size:.94rem;margin:.4rem auto 0;max-width:24rem;line-height:1.45}
+.cta{margin-top:1.4rem}
+.btn{display:inline-block;background:var(--sun);color:#fff;text-decoration:none;font-weight:700;font-family:"Baloo 2",system-ui,sans-serif;padding:.72rem 1.5rem;border-radius:999px;font-size:1.02rem;box-shadow:0 10px 22px -8px rgba(249,115,22,.7);transition:transform .15s ease,box-shadow .15s ease}
+.btn:hover{transform:translateY(-1px);box-shadow:0 14px 28px -8px rgba(249,115,22,.8)}
+.muted{color:var(--inkSoft);opacity:.9;font-size:.85rem;margin:1.1rem auto 0;max-width:24rem;line-height:1.45}
+.hidden{display:none!important}
+`;
+
+// Client script for the PROGRESS variant only (task 2096): poll the public status
+// endpoint, advance the stepper, and auto-open the instance the moment its credentials
+// land. 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
+// written just above it. Fails soft — a poll hiccup just retries; a long wait reveals a
+// manual "open" button rather than ever falsely erroring.
+const CALLBACK_SCRIPT = `
+(function(){
+  var cfg=window.__CB_SETUP__||{};
+  var state=cfg.state||'',domain=cfg.domain||'';
+  if(!state||!domain)return;
+  var target='https://'+domain;
+  var pollUrl=location.pathname.replace('/callback','/status')+'?state='+encodeURIComponent(state);
+  var steps=document.getElementById('steps'),statusEl=document.getElementById('status');
+  var cta=document.getElementById('cta'),go=document.getElementById('go'),foot=document.getElementById('foot');
+  var finished=false,tries=0,manual=false;
+  function dot(n){return steps.querySelector('[data-step="'+n+'"]');}
+  function setActive(n){for(var i=1;i<=3;i++){var el=dot(i);if(!el)continue;el.classList.remove('active','done');if(i<n){el.classList.add('done');el.querySelector('.dot').textContent='\\u2713';}else if(i===n){el.classList.add('active');}}}
+  function allDone(){for(var i=1;i<=3;i++){var el=dot(i);if(!el)continue;el.classList.remove('active');el.classList.add('done');el.querySelector('.dot').textContent='\\u2713';}}
+  function ready(){if(finished)return;finished=true;allDone();statusEl.textContent='Your instance is ready \\u2014 sign in with GitHub to claim it as owner.';cta.classList.remove('hidden');var n=4;(function tick(){if(n<=0){location.href=target;return;}go.textContent='Opening '+domain+' in '+n+'\\u2026';n--;setTimeout(tick,1000);})();}
+  function failed(){if(finished)return;finished=true;statusEl.textContent='Setup didn\\u2019t finish. Open your instance page and start the GitHub sign-in setup again.';cta.classList.remove('hidden');go.textContent='Open '+domain+' \\u2192';}
+  function revealManual(){if(manual||finished)return;manual=true;cta.classList.remove('hidden');go.textContent='Open '+domain+' \\u2192';if(foot)foot.textContent='This is taking a little longer than usual \\u2014 you can open your instance now, or keep waiting.';}
+  function schedule(){if(!finished)setTimeout(poll,3000);}
+  function poll(){tries++;fetch(pollUrl,{headers:{accept:'application/json'},cache:'no-store'}).then(function(r){return r.ok?r.json():null;}).then(function(j){if(!j){schedule();return;}if(j.ready||j.status==='done'){ready();return;}if(j.status==='error'||j.status==='expired'){failed();return;}setActive(2);if(tries===40)revealManual();schedule();}).catch(function(){schedule();});}
+  setActive(2);poll();
+})();
+`;
+
+// The standalone landing page for the public GitHub redirect (the mothership serves it;
+// it is NOT the hall shell). Two variants share the Cloud Bongos brand shell (task 2096):
+//   • progress — ok + state + domain: an animated stepper that polls the status endpoint
+//     and auto-opens the instance when its credentials are placed.
+//   • message — everything else (errors + the no-domain success fallback): a calm badge
+//     + `body` (server-authored, trusted HTML).
+function callbackPage({ ok, title, body, state, domain }) {
+  const progress = !!(ok && state && domain);
+  const cfgJson = JSON.stringify({ state: state || '', domain: domain || '' }).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">
+<title>${esc(title)}</title>
+<link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Baloo+2:wght@600;700;800&family=Quicksand:wght@400;500;600;700&family=Fira+Code&display=swap" rel="stylesheet">
+<style>${PAGE_STYLE}</style></head><body>`;
+  if (progress) {
+    return `${head}
+<main class="card">
+  <h1>${esc(title)}</h1>
+  <p class="sub">Finishing sign-in setup for <code>${esc(domain)}</code>.</p>
+  <div class="steps" id="steps" aria-label="Setup progress">
+    <div class="step done" data-step="1"><div class="dot">✓</div><div class="lbl">GitHub app created</div></div>
+    <div class="step active" data-step="2"><div class="dot">2</div><div class="lbl">Placing credentials</div></div>
+    <div class="step" data-step="3"><div class="dot">3</div><div class="lbl">Ready to sign in</div></div>
+  </div>
+  <p class="status-line" id="status">Hang tight — keep this tab open while we finish.</p>
+  <div class="cta hidden" id="cta"><a class="btn" id="go" href="https://${esc(domain)}">Open ${esc(domain)} →</a></div>
+  <p class="muted" id="foot">This page opens <code>${esc(domain)}</code> for you the moment it’s ready.</p>
+  <noscript><p class="muted">When setup finishes, open <a href="https://${esc(domain)}">${esc(domain)}</a> and sign in with GitHub — that first sign-in makes you the owner.</p></noscript>
+</main>
+<script>window.__CB_SETUP__=${cfgJson};</script>
+<script>${CALLBACK_SCRIPT}</script>
+</body></html>`;
+  }
+  return `${head}
+<main class="card">
+  <div class="badge-warn">${ok ? '✓' : '⚠️'}</div>
+  <h1>${esc(title)}</h1>
+  <div class="sub">${body || ''}</div>
+</main>
+</body></html>`;
+}
+
+// Register this module's kernel seam (ADR 0083 / the registerBoxSeams precedent).
+// Idempotent — the loader calls this factory once at boot, but tests may
+// instantiate the router repeatedly; gating on hasProvider keeps the port
+// single-registered.
+//   • PROVIDES port `provisioning.instanceState` (slug) → { status, … } | null.
+//     Lets other code read an instance's provisioning status via
+//     resolveOptional without importing this module (box.hasEverConnected pattern).
+function registerProvisioningSeams() {
+  if (api.hasProvider('provisioning.instanceState')) return;
+  api.registerProvider('provisioning.instanceState', (slug) => provisioning.instanceStateForSlug(pool, slug));
+}
+
+// Project an instance row for the fleet view — the owner identity + the same
+// allow-listed public projection an owner sees.
+function fleetInstance(row) {
+  return {
+    owner: { id: row.owner_builder_id, github_login: row.github_login, display_name: row.display_name, rank: row.rank },
+    ...provisioning.publicInstance(row),
+  };
+}
+
+module.exports = function provisioningRoutes() {
+  registerProvisioningSeams();
+  const router = express.Router();
+  // Per-IP limiter for the public tls-check `ask` endpoint (SEC review, task 1945).
+  const askRateLimit = makeAskRateLimiter();
+  // A separate, more generous per-IP limiter for the public status-poll endpoint (task
+  // 2096): the onboarding page polls it every ~3s while it waits, so legitimate volume is
+  // higher than tls-check's one-shot ask. 120/min/IP gives comfortable headroom while
+  // still shedding a flood; in-memory, own bucket (does not share tls-check's budget).
+  const statusRateLimit = makeAskRateLimiter({ max: 120 });
+
+  // Route ORDER is deliberate (the box.js precedent): the Archon-gated routes are
+  // declared FIRST, then the any-builder routes. The route-rank auditor
+  // (src/bongos/route-rank-check.js) classifies a route from a 20-line lookahead of
+  // its middleware; declaring an archon route BELOW an any-builder one would bleed
+  // its requireRank('archon') up into the any-builder route's window and mislabel
+  // it. Archon-first keeps every route classifying to its true gate.
+
+  // GET /provisioning/fleet — the full instance roster across all owners.
+  // rank: archon (exposes every owner's instance + cost; the /boxes precedent).
+  router.get('/provisioning/fleet', auth.requireBuilder, auth.requireRank('archon'), async (req, res) => {
+    try {
+      const status = req.query.status || undefined;
+      const rows = await provisioning.listAllInstances(pool, { status });
+      res.json({ instances: rows.map(fleetInstance) });
+    } catch (err) {
+      console.error('[provisioning] GET /provisioning/fleet', err);
+      res.fail('fleet_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // GET /provisioning/fleet/cost-ledger — per-instance monthly estimate + total.
+  // rank: archon — cost oversight across the fleet (the /boxes/cost-ledger precedent).
+  // Declared among the archon routes (archon-first) for correct auditor classification.
+  router.get('/provisioning/fleet/cost-ledger', auth.requireBuilder, auth.requireRank('archon'), async (req, res) => {
+    try {
+      // R14 (#2001 / ADR 0119): shared helper; per-endpoint cap preserved (default 500, max 2000).
+      const { limit } = api.parsePagination(req, { defaultLimit: 500, maxLimit: 2000 });
+      const out = await provisioning.costLedger(pool, { limit });
+      res.json(out);
+    } catch (err) {
+      console.error('[provisioning] GET /provisioning/fleet/cost-ledger', err);
+      res.fail('cost_ledger_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /provisioning/instances/:id/force-teardown — Archon tears down ANY
+  // instance. Trust-safe by the same mechanism as the owner's own teardown: it
+  // ENQUEUES a 'teardown' intent for the control-plane runner; the web tier never
+  // holds cloud tokens. rank: archon (acts on another owner's infrastructure).
+  // Declared among the archon routes (archon-first).
+  router.post('/provisioning/instances/:id/force-teardown', auth.requireBuilder, auth.requireRank('archon'), async (req, res) => {
+    const id = parseId(req, res); // (req, res) — parseId sends 400 bad_id + returns null on failure
+    if (!id) return;
+    try {
+      const inst = await provisioning.getInstanceById(pool, id);
+      if (!inst) return res.fail('instance_not_found', 404);
+      if (!provisioning.TEARDOWN_FROM.has(inst.status)) {
+        return res.fail('not_teardownable', 409, { status: inst.status });
+      }
+      const { created } = await provisioning.enqueueIntent(pool, id, 'teardown', `api:archon:${req.builder.id}`);
+      if (created) {
+        await provisioning.recordEvent(pool, {
+          instanceId: id, ownerBuilderId: inst.owner_builder_id, event: 'teardown',
+          detail: `force-teardown by archon ${req.builder.github_login || req.builder.id}`,
+          actor: `api:archon:${req.builder.id}`,
+        }).catch(() => {});
+      }
+      res.json({ ok: true, queued: created, action: 'teardown', status: inst.status,
+        message: created ? 'The instance will be torn down shortly.' : 'A teardown is already queued for that instance.' });
+    } catch (err) {
+      console.error('[provisioning] POST /provisioning/instances/:id/force-teardown', err);
+      res.fail('teardown_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /provisioning/instances — request a new instance. rank: any authenticated
+  // builder (own resource). ENQUEUES a 'provision' intent + records the request;
+  // the runner (task P3) does the real standup. Idempotent on slug for the SAME
+  // owner (re-request returns the existing row); a slug owned by ANOTHER builder → 409.
+  // Body: { slug (required), target_ref?, hosting_shape? (co-tenant|dedicated),
+  //         domain?, tier? }.
+  router.post('/provisioning/instances', auth.requireBuilder, async (req, res) => {
+    if (validateOrRespond(req, res, {
+      slug: { required: true, type: 'string', maxLength: 40 },
+      target_ref: { type: 'string', maxLength: 200 },
+      hosting_shape: { type: 'string', maxLength: 20 },
+      domain: { type: 'string', maxLength: 253 },
+      tier: { type: 'string', maxLength: 40 },
+    })) return;
+    const body = req.body || {};
+    const slug = String(body.slug || '').trim().toLowerCase();
+    if (!provisioning.isValidSlug(slug)) {
+      return res.fail('bad_slug', 400, { reason: 'lowercase, 2–40 chars of [a-z0-9-], no leading/trailing/double dash' });
+    }
+    const shape = body.hosting_shape || 'co-tenant';
+    if (!provisioning.HOSTING_SHAPES.includes(shape)) {
+      return res.fail('bad_hosting_shape', 400, { valid: provisioning.HOSTING_SHAPES });
+    }
+    try {
+      const { instance, created } = await provisioning.createInstance(pool, {
+        ownerBuilderId: req.builder.id, slug,
+        targetRef: body.target_ref, hostingShape: shape,
+        domain: body.domain, tier: body.tier,
+      });
+      // Slug already taken by ANOTHER builder — refuse (never reassign ownership).
+      if (!created && String(instance.owner_builder_id) !== String(req.builder.id)) {
+        return res.fail('slug_taken', { status: 409, message: 'That instance slug is already in use.' });
+      }
+      // Enqueue the provision intent (idempotent: an already-open intent is returned).
+      const { intent, created: intentCreated } = await provisioning.enqueueIntent(pool, instance.id, 'provision', 'api:self');
+      if (created) {
+        await provisioning.recordEvent(pool, {
+          instanceId: instance.id, ownerBuilderId: req.builder.id, event: 'request',
+          detail: `provision requested (shape=${shape}${body.domain ? `, domain=${body.domain}` : ''})`,
+          actor: 'api:self',
+        }).catch(() => {});
+      }
+      res.status(created ? 201 : 200).json({
+        instance: provisioning.publicInstance(instance),
+        open_intent: intent ? { action: intent.action, state: intent.state } : null,
+        queued: intentCreated,
+        created,
+      });
+    } catch (err) {
+      console.error('[provisioning] POST /provisioning/instances', err);
+      res.fail('request_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // GET /provisioning/instances — the caller's own instances + each open intent.
+  // rank: any authenticated builder (own resource read).
+  router.get('/provisioning/instances', auth.requireBuilder, async (req, res) => {
+    try {
+      const rows = await provisioning.listInstancesForOwner(pool, req.builder.id);
+      const instances = [];
+      for (const row of rows) {
+        const open = await provisioning.getOpenIntent(pool, row.id);
+        instances.push({
+          ...provisioning.publicInstance(row),
+          open_intent: open ? { action: open.action, state: open.state } : null,
+        });
+      }
+      res.json({ instances });
+    } catch (err) {
+      console.error('[provisioning] GET /provisioning/instances', err);
+      res.fail('list_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // GET /provisioning/instances/:id — read one of the caller's own instances.
+  // rank: any authenticated builder (own resource). 404 when the id isn't the
+  // caller's (own-scoped; does not leak another owner's instance existence).
+  router.get('/provisioning/instances/:id', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res); // (req, res) — parseId sends 400 bad_id + returns null on failure
+    if (!id) return;
+    try {
+      const inst = await provisioning.getInstanceById(pool, id);
+      if (!inst || String(inst.owner_builder_id) !== String(req.builder.id)) {
+        return res.fail('instance_not_found', 404);
+      }
+      const open = await provisioning.getOpenIntent(pool, id);
+      res.json({
+        instance: provisioning.publicInstance(inst),
+        open_intent: open ? { action: open.action, state: open.state } : null,
+      });
+    } catch (err) {
+      console.error('[provisioning] GET /provisioning/instances/:id', err);
+      res.fail('read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /provisioning/instances/:id/teardown — request teardown of the caller's
+  // OWN instance. rank: any authenticated builder (own resource). Enqueues a
+  // 'teardown' intent; the runner executes it (web tier holds no tokens). 404 when
+  // the id isn't the caller's; 409 when the instance isn't in a teardownable state.
+  router.post('/provisioning/instances/:id/teardown', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res); // (req, res) — parseId sends 400 bad_id + returns null on failure
+    if (!id) return;
+    try {
+      const inst = await provisioning.getInstanceById(pool, id);
+      if (!inst || String(inst.owner_builder_id) !== String(req.builder.id)) {
+        return res.fail('instance_not_found', 404);
+      }
+      if (!provisioning.TEARDOWN_FROM.has(inst.status)) {
+        return res.fail('not_teardownable', { status: 409, message: `Instance is '${inst.status}' — nothing to tear down right now.`, details: { status: inst.status } });
+      }
+      const { created } = await provisioning.enqueueIntent(pool, id, 'teardown', 'api:self');
+      if (created) {
+        await provisioning.recordEvent(pool, {
+          instanceId: id, ownerBuilderId: req.builder.id, event: 'teardown',
+          detail: 'teardown requested by owner', actor: 'api:self',
+        }).catch(() => {});
+      }
+      res.json({ ok: true, queued: created, action: 'teardown', status: inst.status,
+        message: created ? 'Your instance will be torn down shortly.' : 'A teardown is already queued for that instance.' });
+    } catch (err) {
+      console.error('[provisioning] POST /provisioning/instances/:id/teardown', err);
+      res.fail('teardown_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /provisioning/instances/:id/github-app — mint a GitHub-App-Manifest onboarding
+  // link for the caller's OWN instance (task 2080, ADR 0133). rank: any authenticated
+  // builder (own resource). Returns the pre-filled manifest + the GitHub form-POST target
+  // (personal + org variants) + a one-time `state`; the browser POSTs the manifest to
+  // 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') }.
+  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;
+    try {
+      const inst = await provisioning.getInstanceById(pool, id);
+      if (!inst || String(inst.owner_builder_id) !== String(req.builder.id)) {
+        return res.fail('instance_not_found', 404);
+      }
+      // A domain is required: it is the App's homepage + the sign-in callback host. No
+      // domain ⇒ there is nothing to point "Login with GitHub" at yet.
+      if (!inst.domain) {
+        return res.fail('domain_required', { status: 409, message: 'Set the instance domain before wiring GitHub sign-in — the App needs the real callback host.' });
+      }
+      const origin = mothershipOrigin();
+      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 });
+      await provisioning.recordEvent(pool, {
+        instanceId: id, ownerBuilderId: req.builder.id, event: 'oauth-manifest-start',
+        detail: 'GitHub App Manifest link minted', 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,
+        // The browser POSTs `manifest` (as a form field) to this URL; GitHub echoes state.
+        post_url: provisioning.manifestPostUrl({ account, orgLogin, state }),
+        personal_url: provisioning.manifestPostUrl({ account: 'personal', state }),
+        org_url: orgLogin ? provisioning.manifestPostUrl({ account: 'org', orgLogin, state }) : null,
+        org_login: orgLogin,
+        manifest,
+        redirect_url: manifest.redirect_url,
+        expires_at: expiresAt,
+      });
+    } catch (err) {
+      console.error('[provisioning] POST /provisioning/instances/:id/github-app', err);
+      res.fail('github_app_manifest_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // GET /provisioning/health — liveness + the core version this module mounted
+  // against. rank: public (a plain liveness read; no write, no sensitive data).
+  router.get('/provisioning/health', (req, res) => {
+    res.json({ module: 'provisioning', ok: true, coreVersion: api.CORE_VERSION });
+  });
+
+  // GET /provisioning/onboard-plan?mode=greenfield|adopt — the CANONICAL onboarding
+  // step sequence (task 2085; goal 35 / criterion 165: "the canonical step sequence is
+  // the source of truth; skill/CLI/hall are forms over it"). The branded /create page +
+  // the hall wizard fetch it so their human-steps checklist can't drift from the CLI's
+  // (scripts/gds/onboard.js reads the same modules/provisioning/onboard-plan.js).
+  // rank: public — the signed-out /create landing page reads it; it is the same public
+  // runbook the /new-project skill documents (no write, no secret).
+  router.get('/provisioning/onboard-plan', (req, res) => {
+    const mode = req.query.mode === 'adopt' ? 'adopt' : 'greenfield';
+    res.json({ mode, steps: onboardPlan(mode) });
+  });
+
+  // GET /provisioning/tls-check?domain=<host> — the Caddy on-demand-TLS ALLOW-LIST
+  // (ADR 0111 §4, task P4 #1945). Caddy's global `on_demand_tls { ask … }` calls
+  // this before fetching a Let's Encrypt cert for an SNI it doesn't already have:
+  // HTTP 200 authorizes, any non-200 refuses. We authorize ONLY a hostname this
+  // module actually provisioned + is still serving (provisioning|active), so
+  // on-demand TLS can never be abused to mint certs for arbitrary names (the
+  // cert-flood guard). FAILS CLOSED — any error denies (503). rank: public (Caddy
+  // calls it locally over 127.0.0.1 with no session; a plain read, no mutation, no
+  // secret — it only reveals whether a host is a live provisioned instance).
+  //
+  // RATE-LIMITED (SEC review of task 1945). The route is reachable from the
+  // internet via the apex proxy, and core's global limiter bypasses reads while the
+  // 120/min public-read cap is mounted only under /public — this module mounts
+  // under /api/bongos, so it inherits neither. Without a limiter the endpoint is an
+  // unthrottled enumeration oracle + issuance-load amplifier. Core's limiter isn't
+  // reachable from a module (the one-way import rule; and the kernel doorway may not
+  // re-export it — it's a non-kernel core file, ADR 0091 §1), so we apply a
+  // dedicated, tight in-module limiter (askRateLimit). Caddy's own on_demand_tls
+  // interval/burst throttle is NOT an option (removed in Caddy 2.x — the `ask`
+  // endpoint IS the throttle and must self-limit).
+  router.get('/provisioning/tls-check', askRateLimit, async (req, res) => {
+    try {
+      const ok = await provisioning.isProvisionedHostname(pool, req.query.domain);
+      return res.status(ok ? 200 : 404).json({ ok });
+    } catch (err) {
+      console.error('[provisioning] GET /provisioning/tls-check', err);
+      return res.status(503).json({ ok: false, error: 'check_failed' });
+    }
+  });
+
+  // GET /provisioning/github-app/status?state=<> — the PUBLIC progress read the onboarding
+  // callback page polls (task 2096) to know when setup is done + where to send the owner.
+  // Same public-by-state model as the callback: the unguessable, single-use `state` token
+  // is the only key, and the response reveals only the manifest lifecycle status + the
+  // instance's own (already-public) domain — never a secret. Per-IP rate-limited because
+  // the page polls it every ~3s. `ready` is true iff the manifest reached 'done' (creds
+  // placed + /healthz verified) — the page then auto-redirects to https://<domain>.
+  // rank: public — no session, no mutation, no secret; an unknown state is a 404 no-op.
+  router.get('/provisioning/github-app/status', statusRateLimit, async (req, res) => {
+    try {
+      const state = String(req.query.state || '');
+      if (!state) return res.status(400).json({ ok: false, error: 'missing_state' });
+      const row = await provisioning.getOAuthManifestByState(pool, state);
+      if (!row) return res.status(404).json({ ok: false, error: 'unknown_state' });
+      const inst = await provisioning.getInstanceById(pool, row.instance_id).catch(() => null);
+      const status = row.status;
+      return res.json({
+        ok: true,
+        status,
+        ready: status === 'done',
+        terminal: status === 'done' || status === 'error' || status === 'expired',
+        domain: inst && inst.domain ? inst.domain : null,
+        instance_status: inst ? inst.status : null,
+      });
+    } catch (err) {
+      console.error('[provisioning] GET /provisioning/github-app/status', err);
+      return res.status(500).json({ ok: false, error: 'status_check_failed' });
+    }
+  });
+
+  // GET /provisioning/github-app/callback?code=&state= — GitHub redirects the owner's
+  // BROWSER here after they approve the App Manifest (task 2080, ADR 0133). It is a
+  // browser redirect with no session guaranteed, so it is PUBLIC — the unguessable,
+  // single-use, TTL'd `state` token (minted only for the signed-in owner and matched
+  // against provisioning_oauth_manifests) is the authorization, exactly as GitHub's own
+  // conversion `code` is "the code IS the auth". The web tier ONLY stores the code +
+  // flips status → 'code_received'; the control-plane runner (the sole token-holder)
+  // exchanges it for the client secret and places it in web.env. The secret NEVER
+  // touches the browser or the web tier. rank: public — no session, no mutation of
+  // authority, no secret revealed; a bad/expired/replayed state is a no-op error page.
+  router.get('/provisioning/github-app/callback', async (req, res) => {
+    const code = String(req.query.code || '');
+    const state = String(req.query.state || '');
+    const sendPage = (status, page) => res.status(status).type('html').send(page);
+    try {
+      if (!code || !state) {
+        return sendPage(400, callbackPage({ ok: false, title: 'Missing GitHub response',
+          body: '<p>GitHub didn’t send back a code and state. Start the sign-in setup again from your instance’s page.</p>' }));
+      }
+      const row = await provisioning.getOAuthManifestByState(pool, state);
+      // Unknown state, wrong status, or expired → generic refusal (no oracle about which).
+      if (!row || row.status !== 'pending' || new Date(row.expires_at).getTime() <= Date.now()) {
+        return sendPage(400, callbackPage({ ok: false, title: 'This setup link has expired',
+          body: '<p>The one-time link is no longer valid (it may have already been used, or it timed out). Open your instance’s page and start the GitHub sign-in setup again.</p>' }));
+      }
+      const attached = await provisioning.attachManifestCode(pool, row.id, code);
+      if (!attached) {
+        // Lost a race (another callback consumed it) or it just expired — same message.
+        return sendPage(400, callbackPage({ ok: false, title: 'This setup link has expired',
+          body: '<p>The one-time link is no longer valid. Open your instance’s page and start the GitHub sign-in setup again.</p>' }));
+      }
+      await provisioning.recordEvent(pool, {
+        instanceId: row.instance_id, ownerBuilderId: row.requested_by, event: 'oauth-manifest-code',
+        detail: 'GitHub returned the App Manifest code; awaiting control-plane conversion', actor: 'github',
+      }).catch(() => {});
+      const inst = await provisioning.getInstanceById(pool, row.instance_id).catch(() => null);
+      const domain = inst && inst.domain ? inst.domain : null;
+      // Progress variant (task 2096): the page polls …/github-app/status?state= and
+      // auto-opens the instance the moment its credentials are placed — no "come back
+      // later" dead-end. Falls back to a static success if we have no domain to poll.
+      return sendPage(200, domain
+        ? callbackPage({ ok: true, title: 'Setting up your instance', state, domain })
+        : callbackPage({ ok: true, title: 'GitHub app created',
+          body: '<p>Nice — GitHub created the app. We’re placing its credentials on your instance now; this finishes on its own within a few minutes.</p><p class="muted">You can close this tab.</p>' }));
+    } catch (err) {
+      console.error('[provisioning] GET /provisioning/github-app/callback', err);
+      return sendPage(500, callbackPage({ ok: false, title: 'Something went wrong',
+        body: '<p>We couldn’t record GitHub’s response. Try starting the sign-in setup again from your instance’s page.</p>' }));
+    }
+  });
+
+  return router;
+};
+
+// Re-export the seam registrar for tests that assert the port is registered.
+module.exports.registerProvisioningSeams = registerProvisioningSeams;