@bongos/core 1.17.0 → 1.17.2

package/modules/provisioning/provisioning.js

@@ -0,0 +1,539 @@
+// modules/provisioning/provisioning.js — the provisioning module's domain slice
+// (ADR 0111, task #1942). Pure helpers + data access for instance hosting.
+//
+// DESIGN — the trust boundary (ADR 0111 §2 / ADR 0016). This file NEVER calls a
+// cloud provider (no DigitalOcean, no Cloudflare, no registrar) and holds NO
+// tokens. It only reads/writes the module's own provisioning_* tables and ENQUEUES
+// intents. The control-plane runner (scripts/gds/provision.js, task P3) is the sole
+// token-holder that drains provisioning_intents and does the real infra work.
+//
+// `db` is dependency-INJECTED (passed in as the first arg), exactly like
+// modules/dev-box/boxes.js — so this file has NO core require and is trivially
+// unit-testable with a fake `{ query }`. The route factory passes the doorway pool.
+'use strict';
+
+// ---------------------------------------------------------------------------
+// Constants (mirror the CHECK constraints in provisioning_001_tables.sql)
+// ---------------------------------------------------------------------------
+const INSTANCE_STATES = ['requested', 'provisioning', 'active', 'tearing_down', 'torn_down', 'error'];
+// co-tenant  — a process + DB on THIS control-plane checkout (shared box, $0)
+// dedicated  — its own DigitalOcean droplet (priced by tier)
+// standalone — its OWN repo checkout + pinned @cloudbongos/core npm dep, co-located on
+//              the box (ADR 0108 destination model; owner-hosted, $0). See provision.js.
+const HOSTING_SHAPES = ['co-tenant', 'dedicated', 'standalone'];
+// 'oauth-manifest' (task 2080) is queueable too — the GitHub-App-Manifest onboarding
+// conversion. Today the runner drains it by scanning provisioning_oauth_manifests
+// (drainOAuthManifests), not the intent queue, but it stays a valid action so the
+// widened CHECK (migration provisioning_003) and this list never drift.
+const INTENT_ACTIONS = ['provision', 'teardown', 'oauth-manifest'];
+// The states from which a teardown is meaningful (there is something to reclaim).
+// Mirrors dev-box canTransition('deprovision', …): a requested/torn_down/error
+// instance has nothing running to tear down via the happy path.
+const TEARDOWN_FROM = new Set(['provisioning', 'active', 'tearing_down']);
+
+// Monthly cost estimate (USD) for a dedicated droplet tier — VISIBILITY only
+// (ADR 0111 §6), never a bill. A small local table so this module needs no
+// sibling-module import; P2 (shared control-plane client extraction) is where a
+// unified SIZE_CATALOG can later back this. Co-tenant is always $0 (it shares an
+// existing box). Unknown tier → 0 (unpriced rather than wrong).
+const TIER_MONTHLY_USD = {
+  's-1vcpu-1gb': 6,
+  's-1vcpu-2gb': 12,
+  's-2vcpu-2gb': 18,
+  's-2vcpu-4gb': 24,
+  's-4vcpu-8gb': 48,
+};
+
+// ---------------------------------------------------------------------------
+// Pure helpers (no I/O — exported for unit tests)
+// ---------------------------------------------------------------------------
+
+// A DNS/db-safe instance slug: lowercase, starts alnum, 2–40 of [a-z0-9-], no
+// trailing/leading/double dash. This becomes a subdomain label + a DB-name base,
+// so it must be conservative. Returns true/false.
+function isValidSlug(slug) {
+  const s = String(slug == null ? '' : slug);
+  if (s.length < 2 || s.length > 40) return false;
+  if (!/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(s)) return false;
+  if (s.includes('--')) return false;
+  return true;
+}
+
+// Monthly USD estimate for a shape+tier. Co-tenant + standalone are free (they share
+// the box / run on the owner's own infra); only a dedicated droplet costs its tier's
+// rate (0 if the tier is unknown/unset). PURE.
+function costEstimateUsd({ hostingShape, tier } = {}) {
+  if (hostingShape !== 'dedicated') return 0;
+  return TIER_MONTHLY_USD[tier] || 0;
+}
+
+// Normalize an SNI/hostname for an EXACT allow-list match: lowercase, trim, drop a
+// trailing dot and any :port, and reject anything that can't be a real DNS name.
+// Returns '' when the input isn't a plausible hostname (→ the caller denies). Backs
+// the Caddy on-demand-TLS allow-list, so it errs strict: a bare TLD or malformed
+// name is rejected. PURE (no I/O).
+function normalizeHostname(h) {
+  let s = String(h == null ? '' : h).trim().toLowerCase();
+  if (!s) return '';
+  s = s.replace(/:\d+$/, '');     // drop a :port suffix FIRST …
+  s = s.replace(/\.$/, '');       // … then an FQDN trailing dot (handles host.:port order)
+  if (s.length < 1 || s.length > 253) return '';
+  // ≥2 labels (no bare TLD); each label [a-z0-9-], no leading/trailing dash.
+  if (!/^([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(s)) return '';
+  return s;
+}
+
+// The instance lifecycle states for which an on-demand TLS cert may be minted: a
+// host mid-standup ('provisioning' — Caddy's first handshake can land here, while
+// the snippet is written + reloaded) or live ('active'). NOT 'requested' (nothing
+// stood up yet), 'tearing_down', 'torn_down', or 'error'.
+const CERT_ELIGIBLE_STATES = new Set(['provisioning', 'active']);
+
+// Is `hostname` a domain this module ACTUALLY provisioned + is still serving? Backs
+// the Caddy on-demand-TLS `ask` allow-list (ADR 0111 §4): true → Caddy may fetch a
+// Let's Encrypt cert for it; false → refuse (no cert-minting for arbitrary SNIs, the
+// cert-flood guard). Exact match on the normalized host against a cert-eligible
+// instance. NEVER interpolates the host into SQL (parameterized). db-injected.
+async function isProvisionedHostname(db, hostname) {
+  const host = normalizeHostname(hostname);
+  if (!host) return false;
+  const { rows } = await db.query(
+    `SELECT status FROM provisioning_instances WHERE lower(domain) = $1 LIMIT 1`,
+    [host]
+  );
+  return !!(rows[0] && CERT_ELIGIBLE_STATES.has(rows[0].status));
+}
+
+// What we surface for an instance — an explicit allow-list projection (the
+// publicBox pattern). There is nothing secret in a row today, but projecting
+// explicitly means a future sensitive column is never leaked by accident.
+function publicInstance(row) {
+  if (!row) return { state: 'none' };
+  return {
+    id: row.id,
+    slug: row.slug,
+    status: row.status,
+    hosting_shape: row.hosting_shape,
+    domain: row.domain,
+    db_name: row.db_name,
+    port: row.port,
+    tier: row.tier,
+    target_ref: row.target_ref,
+    cost_estimate_usd: Number(row.cost_estimate_usd || 0),
+    error_note: row.error_note || null,
+    created_at: row.created_at,
+    updated_at: row.updated_at,
+    provisioned_at: row.provisioned_at,
+    torn_down_at: row.torn_down_at,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// GitHub App Manifest flow — PURE builders (task 2080, ADR 0133).
+// GitHub has no create-an-OAuth-App API, but the App *Manifest* flow lets the owner
+// click ONE pre-filled link, approve on GitHub, and have GitHub hand us the client
+// creds automatically. These build the manifest + the POST target; the web route
+// mints the state + persists the row, the control-plane runner does the exchange.
+// ---------------------------------------------------------------------------
+
+// The auto GitHub App name. A GitHub App name is GLOBALLY unique across ALL of GitHub and
+// capped at 34 chars, and it is shown prominently on the sign-in consent screen as
+// "<name> by <owner> … will redirect to https://<domain>".
+//
+// PREFER THE INSTANCE DOMAIN (e.g. "demo.cloudbongos.com"): a domain is inherently unique
+// (so it never collides — the whole problem with a bare "demo"), and it reads perfectly on
+// that consent screen because the name IS the destination. GitHub keeps the dots in the
+// DISPLAY name (only the internal slug is transformed), so a domain is a valid name.
+//
+// FALLBACK (no domain, or a domain over 34 chars): brand-qualify the project —
+// "<brand> - <project>" (e.g. "Cloud Bongos - demo") — still far less collision-prone than
+// a bare slug. Either way it is only a DEFAULT the owner can rename on GitHub's screen.
+// PURE.
+function githubAppName({ domain, brand, project } = {}) {
+  const MAX = 34;
+  // Domain-first: normalizeHostname lowercases + strips port/trailing-dot + validates a
+  // real multi-label host (returns '' otherwise). Dots are fine in a GitHub App display name.
+  const host = normalizeHostname(domain);
+  if (host && host.length <= MAX) return host;
+  // Fallback: brand-qualified project. GitHub App display names accept more, but keeping
+  // this to alphanumerics/spaces/hyphens stays clean and predictable.
+  const clean = (s) => String(s == null ? '' : s)
+    .trim()
+    .replace(/[^A-Za-z0-9 -]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .replace(/^[\s-]+|[\s-]+$/g, '')
+    .trim();
+  const b = clean(brand);
+  const p = clean(project);
+  if (b && p) {
+    const sep = ' - ';
+    const room = MAX - b.length - sep.length;
+    // Keep the WHOLE brand (the collision-dodging qualifier) + as much of the project as
+    // fits; if the brand alone already fills the budget, the brand is the useful name.
+    return room >= 1 ? clean(`${b}${sep}${p.slice(0, room)}`) : b.slice(0, MAX);
+  }
+  return (b || p || 'Cloud Bongos').slice(0, MAX);
+}
+
+// The GitHub App Manifest JSON (docs: apps/sharing-github-apps/registering-a-github-app-
+// from-a-manifest). Two origins matter and MUST differ:
+//   • redirect_url  — where GitHub sends the browser (with ?code=) AFTER the owner
+//     approves. This is the MOTHERSHIP (control plane) callback — the instance itself
+//     can't do the token exchange (no tokens, and its own auth may not be live yet).
+//   • callback_urls — where "Login with GitHub" on the INSTANCE redirects during real
+//     sign-in. Both /api/gds/... (what auth.js actually builds) and the /api/bongos/...
+//     alias are registered so sign-in works regardless of which prefix a build emits.
+// Minimal for sign-in: no repo permissions, no webhook (active:false), not public. PURE.
+function buildGithubAppManifest({ instanceName, slug, instanceDomain, mothershipOrigin, brand }) {
+  const instOrigin = `https://${instanceDomain}`;
+  const redirectUrl = `${String(mothershipOrigin || '').replace(/\/+$/, '')}/api/bongos/provisioning/github-app/callback`;
+  return {
+    name: githubAppName({ domain: instanceDomain, brand, project: instanceName || slug }),
+    url: instOrigin,
+    // Sign-in only ever calls GET /user with the user-to-server token — no repo/account
+    // permissions are needed, so request none (least privilege).
+    default_permissions: {},
+    default_events: [],
+    // No webhook: active:false. A url is still supplied (GitHub validates the shape) but
+    // is never called while inactive; point it at the mothership so it's a real host.
+    hook_attributes: { url: `${String(mothershipOrigin || '').replace(/\/+$/, '')}/api/bongos/provisioning/github-app/webhook`, active: false },
+    redirect_url: redirectUrl,
+    callback_urls: [
+      `${instOrigin}/api/gds/auth/web/callback`,
+      `${instOrigin}/api/bongos/auth/web/callback`,
+    ],
+    public: false,
+  };
+}
+
+// The GitHub form-POST target for creating an App from a manifest. Personal account
+// vs org differ only in the URL; the App works for sign-in either way (ADR 0133). The
+// one-time `state` rides the query string (GitHub echoes it back on redirect). PURE.
+function manifestPostUrl({ account = 'personal', orgLogin, state } = {}) {
+  const q = state ? `?state=${encodeURIComponent(state)}` : '';
+  if (account === 'org' && orgLogin) {
+    return `https://github.com/organizations/${encodeURIComponent(orgLogin)}/settings/apps/new${q}`;
+  }
+  return `https://github.com/settings/apps/new${q}`;
+}
+
+// ---------------------------------------------------------------------------
+// Data access (db injected; owns only the provisioning_* tables)
+// ---------------------------------------------------------------------------
+
+async function getInstanceById(db, id) {
+  const { rows } = await db.query(
+    `SELECT * FROM provisioning_instances WHERE id = $1`, [id]
+  );
+  return rows[0] || null;
+}
+
+async function getInstanceBySlug(db, slug) {
+  const { rows } = await db.query(
+    `SELECT * FROM provisioning_instances WHERE slug = $1`, [slug]
+  );
+  return rows[0] || null;
+}
+
+// The caller's own instances, newest first.
+async function listInstancesForOwner(db, ownerBuilderId) {
+  const { rows } = await db.query(
+    `SELECT * FROM provisioning_instances
+      WHERE owner_builder_id = $1
+      ORDER BY updated_at DESC
+      LIMIT 500`,
+    [ownerBuilderId]
+  );
+  return rows;
+}
+
+// The full fleet across all owners (Archon), joined to the owner identity.
+async function listAllInstances(db, { status } = {}) {
+  const params = [];
+  let where = '';
+  if (status) { params.push(status); where = `WHERE pi.status = $1`; }
+  const { rows } = await db.query(
+    `SELECT pi.*, b.github_login, b.display_name, b.rank
+       FROM provisioning_instances pi
+       JOIN builders b ON b.id = pi.owner_builder_id
+       ${where}
+      ORDER BY pi.updated_at DESC
+      LIMIT 1000`,
+    params
+  );
+  return rows;
+}
+
+// Create an instance row (status 'requested'). Idempotent on slug: a slug clash
+// re-fetches the existing row and returns { created:false } so the ROUTE can
+// decide (same owner → idempotent re-request; different owner → 409). Never
+// silently reassigns ownership.
+async function createInstance(db, { ownerBuilderId, slug, targetRef, hostingShape, domain, dbName, port, tier }) {
+  const shape = HOSTING_SHAPES.includes(hostingShape) ? hostingShape : 'co-tenant';
+  const cost = costEstimateUsd({ hostingShape: shape, tier });
+  try {
+    const { rows } = await db.query(
+      `INSERT INTO provisioning_instances
+         (owner_builder_id, slug, target_ref, hosting_shape, domain, db_name, port, tier, cost_estimate_usd)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+       RETURNING *`,
+      [ownerBuilderId, slug, targetRef ?? null, shape, domain ?? null,
+       dbName ?? null, port ?? null, tier ?? null, cost]
+    );
+    return { instance: rows[0], created: true };
+  } catch (e) {
+    // 23505 = unique_violation on the slug UNIQUE constraint.
+    if (e && e.code === '23505') {
+      const existing = await getInstanceBySlug(db, slug);
+      if (existing) return { instance: existing, created: false };
+    }
+    throw e;
+  }
+}
+
+// Advance an instance's lifecycle status (+ optional column patch). Whitelisted
+// patch columns only, so a caller can never write an arbitrary column.
+async function setInstanceStatus(db, id, status, patch = {}) {
+  const sets = [`status = $2`, `updated_at = now()`];
+  const params = [id, status];
+  const COLS = {
+    domain: 'domain', db_name: 'db_name', port: 'port', tier: 'tier',
+    target_ref: 'target_ref', error_note: 'error_note',
+    cost_estimate_usd: 'cost_estimate_usd',
+    provisioned_at: 'provisioned_at', torn_down_at: 'torn_down_at',
+  };
+  for (const [k, col] of Object.entries(COLS)) {
+    if (k in patch) { params.push(patch[k]); sets.push(`${col} = $${params.length}`); }
+  }
+  const { rows } = await db.query(
+    `UPDATE provisioning_instances SET ${sets.join(', ')} WHERE id = $1 RETURNING *`,
+    params
+  );
+  return rows[0] || null;
+}
+
+// Enqueue a provision/teardown intent. Idempotent: the partial unique index
+// ux_provisioning_intents_open makes a second open enqueue collide (23505); we
+// then return the already-open intent with created:false (mirrors boxes.enqueueIntent).
+async function enqueueIntent(db, instanceId, action, requestedBy) {
+  try {
+    const { rows } = await db.query(
+      `INSERT INTO provisioning_intents (instance_id, action, requested_by, state)
+       VALUES ($1, $2, $3, 'pending') RETURNING *`,
+      [instanceId, action, requestedBy ?? null]
+    );
+    return { intent: rows[0], created: true };
+  } catch (e) {
+    if (e && e.code === '23505') {
+      const existing = await getOpenIntent(db, instanceId);
+      if (existing) return { intent: existing, created: false };
+    }
+    throw e;
+  }
+}
+
+// The instance's currently-open (pending|running) intent, if any.
+async function getOpenIntent(db, instanceId) {
+  const { rows } = await db.query(
+    `SELECT * FROM provisioning_intents
+      WHERE instance_id = $1 AND state IN ('pending', 'running')
+      ORDER BY created_at DESC LIMIT 1`,
+    [instanceId]
+  );
+  return rows[0] || null;
+}
+
+// Atomically claim the oldest pending intent for the runner (task P3): flip it to
+// 'running', bump attempts. FOR UPDATE SKIP LOCKED so concurrent runner ticks never
+// grab the same row. Returns the claimed row or null. (Provided now so the P3 runner
+// reuses this module's data slice rather than re-implementing the queue drain.)
+async function claimNextIntent(db) {
+  const { rows } = await db.query(
+    `UPDATE provisioning_intents
+        SET state = 'running', attempts = attempts + 1, updated_at = now()
+      WHERE id = (
+        SELECT id FROM provisioning_intents
+         WHERE state = 'pending'
+         ORDER BY created_at
+         FOR UPDATE SKIP LOCKED
+         LIMIT 1
+      )
+      RETURNING *`
+  );
+  return rows[0] || null;
+}
+
+// Resolve a claimed intent to its terminal state ('done' | 'error').
+async function resolveIntent(db, id, state, lastError) {
+  await db.query(
+    `UPDATE provisioning_intents
+        SET state = $2, last_error = $3, updated_at = now(), resolved_at = now()
+      WHERE id = $1`,
+    [id, state, lastError ?? null]
+  );
+}
+
+// ── GitHub App Manifest attempts (task 2080, ADR 0133) ─────────────────────
+
+// Record a fresh manifest onboarding attempt (status 'pending') with its one-time
+// `state` token + TTL. The web route mints the state; the runner never writes here.
+async function createOAuthManifest(db, { instanceId, state, requestedBy, expiresAt }) {
+  const { rows } = await db.query(
+    `INSERT INTO provisioning_oauth_manifests (instance_id, state, requested_by, expires_at)
+     VALUES ($1, $2, $3, $4) RETURNING *`,
+    [instanceId, state, requestedBy ?? null, expiresAt]
+  );
+  return rows[0];
+}
+
+// Look up an attempt by its `state` token (the public callback's only key).
+async function getOAuthManifestByState(db, state) {
+  if (!state) return null;
+  const { rows } = await db.query(
+    `SELECT * FROM provisioning_oauth_manifests WHERE state = $1`, [String(state)]
+  );
+  return rows[0] || null;
+}
+
+// Attach GitHub's returned conversion `code` and flip 'pending' → 'code_received'.
+// SINGLE-USE + TTL-guarded IN SQL: only a still-pending, un-expired row advances, so a
+// replayed or stale callback is a no-op (returns null). Returns the updated row or null.
+async function attachManifestCode(db, id, code) {
+  const { rows } = await db.query(
+    `UPDATE provisioning_oauth_manifests
+        SET github_code = $2, status = 'code_received', updated_at = now()
+      WHERE id = $1 AND status = 'pending' AND expires_at > now()
+      RETURNING *`,
+    [id, code]
+  );
+  return rows[0] || null;
+}
+
+// The most recent manifest attempt for an instance (any status) — for the web read
+// surface + audit. `statuses` optionally filters (e.g. ['code_received','converting']).
+async function getLatestOAuthManifestForInstance(db, instanceId, { statuses } = {}) {
+  const params = [instanceId];
+  let filter = '';
+  if (Array.isArray(statuses) && statuses.length) {
+    params.push(statuses);
+    filter = `AND status = ANY($2)`;
+  }
+  const { rows } = await db.query(
+    `SELECT * FROM provisioning_oauth_manifests
+      WHERE instance_id = $1 ${filter}
+      ORDER BY created_at DESC LIMIT 1`,
+    params
+  );
+  return rows[0] || null;
+}
+
+// Atomically claim the oldest attempt awaiting conversion for the runner: flip
+// 'code_received' → 'converting', bump attempts. FOR UPDATE SKIP LOCKED so overlapping
+// runner ticks never grab the same row (the claimNextIntent pattern). Null when none.
+//
+// Only claims a row whose INSTANCE is already 'active' — cred placement rewrites
+// web.env + restarts the unit, which only exists once provisioning finished. A code
+// that arrives mid-provision therefore WAITS (no attempt burned, no error) until the
+// instance goes active, instead of failing against a not-yet-created unit. `OF m` locks
+// only the manifest row, never the joined instance row.
+async function claimNextOAuthManifest(db) {
+  const { rows } = await db.query(
+    `UPDATE provisioning_oauth_manifests
+        SET status = 'converting', attempts = attempts + 1, updated_at = now()
+      WHERE id = (
+        SELECT m.id FROM provisioning_oauth_manifests m
+          JOIN provisioning_instances i ON i.id = m.instance_id
+         WHERE m.status = 'code_received' AND i.status = 'active'
+         ORDER BY m.created_at
+         FOR UPDATE OF m SKIP LOCKED
+         LIMIT 1
+      )
+      RETURNING *`
+  );
+  return rows[0] || null;
+}
+
+// Resolve a claimed attempt to a terminal-ish status ('done' | 'error' | 'code_received'
+// on a retry). Whitelisted patch columns only (last_error, app_id, app_slug).
+async function resolveOAuthManifest(db, id, status, patch = {}) {
+  const sets = [`status = $2`, `updated_at = now()`];
+  const params = [id, status];
+  const terminal = status === 'done' || status === 'error' || status === 'expired';
+  if (terminal) sets.push(`resolved_at = now()`);
+  const COLS = { last_error: 'last_error', app_id: 'app_id', app_slug: 'app_slug', github_code: 'github_code' };
+  for (const [k, col] of Object.entries(COLS)) {
+    if (k in patch) { params.push(patch[k]); sets.push(`${col} = $${params.length}`); }
+  }
+  const { rows } = await db.query(
+    `UPDATE provisioning_oauth_manifests SET ${sets.join(', ')} WHERE id = $1 RETURNING *`,
+    params
+  );
+  return rows[0] || null;
+}
+
+// Append an audit event to provisioning_events.
+async function recordEvent(db, { instanceId, ownerBuilderId, event, detail, costUsd, actor }) {
+  await db.query(
+    `INSERT INTO provisioning_events (instance_id, owner_builder_id, event, detail, cost_usd, actor)
+     VALUES ($1, $2, $3, $4, $5, $6)`,
+    [instanceId, ownerBuilderId ?? null, event, detail ?? null, costUsd ?? null, actor ?? null]
+  );
+}
+
+// The `provisioning.instanceState` port implementation: given an instance slug,
+// return a small state summary (or null if unknown). Lets OTHER code read an
+// instance's provisioning status via seams.resolveOptional without importing this
+// module (the box.hasEverConnected precedent).
+async function instanceStateForSlug(db, slug) {
+  const row = await getInstanceBySlug(db, slug);
+  if (!row) return null;
+  return {
+    slug: row.slug,
+    status: row.status,
+    hosting_shape: row.hosting_shape,
+    domain: row.domain || null,
+  };
+}
+
+// Fleet cost ledger (Archon): per-instance monthly estimate + a total, over the
+// instances that still cost something (not torn_down). VISIBILITY only (ADR 0111 §6).
+async function costLedger(db, { limit = 500 } = {}) {
+  const { rows } = await db.query(
+    `SELECT pi.id, pi.slug, pi.hosting_shape, pi.tier, pi.status,
+            pi.cost_estimate_usd, b.github_login
+       FROM provisioning_instances pi
+       JOIN builders b ON b.id = pi.owner_builder_id
+      WHERE pi.status <> 'torn_down'
+      ORDER BY pi.cost_estimate_usd DESC, pi.updated_at DESC
+      LIMIT $1`,
+    [Math.min(Math.max(Number(limit) || 500, 1), 2000)]
+  );
+  const totalMonthlyUsd = rows.reduce((a, r) => a + Number(r.cost_estimate_usd || 0), 0);
+  return {
+    instances: rows.map((r) => ({
+      id: r.id, slug: r.slug, owner: r.github_login,
+      hosting_shape: r.hosting_shape, tier: r.tier, status: r.status,
+      cost_estimate_usd: Number(r.cost_estimate_usd || 0),
+    })),
+    total_monthly_usd: Number(totalMonthlyUsd.toFixed(4)),
+  };
+}
+
+module.exports = {
+  // constants
+  INSTANCE_STATES, HOSTING_SHAPES, INTENT_ACTIONS, TEARDOWN_FROM, TIER_MONTHLY_USD,
+  CERT_ELIGIBLE_STATES,
+  // pure
+  isValidSlug, costEstimateUsd, publicInstance, normalizeHostname,
+  // pure — GitHub App Manifest flow (task 2080)
+  githubAppName, buildGithubAppManifest, manifestPostUrl,
+  // data access
+  isProvisionedHostname,
+  getInstanceById, getInstanceBySlug, listInstancesForOwner, listAllInstances,
+  createInstance, setInstanceStatus,
+  enqueueIntent, getOpenIntent, claimNextIntent, resolveIntent,
+  recordEvent, instanceStateForSlug, costLedger,
+  // data access — GitHub App Manifest attempts (task 2080)
+  createOAuthManifest, getOAuthManifestByState, attachManifestCode,
+  getLatestOAuthManifestForInstance, claimNextOAuthManifest, resolveOAuthManifest,
+};

package/modules/provisioning/rate-limit.js

@@ -0,0 +1,35 @@
+// modules/provisioning/rate-limit.js — a small per-IP sliding-window rate limiter
+// for the module's PUBLIC tls-check `ask` endpoint (SEC review of task 1945).
+//
+// WHY THIS LIVES HERE (not core reuse). Core has publicReadRateLimitMiddleware
+// (src/bongos/middleware/rate-limit.js), but a module may not import it: the one-way
+// rule forbids a deep core require (ADR 0083), and the kernel doorway may not
+// re-export it because rate-limit.js is a non-kernel core file (ADR 0091 §1). So we
+// carry a dedicated limiter, mirroring core's shape. It is deliberately TIGHT: Caddy
+// calls the on-demand-TLS `ask` endpoint at most once per new SNI, so legitimate
+// volume is tiny — a low per-IP cap sheds an enumeration/issuance flood without ever
+// throttling a real TLS handshake.
+//
+// In-memory + per-process (the core limiter's model too). `now` is injectable so the
+// window logic is unit-testable without a real clock.
+'use strict';
+
+function makeAskRateLimiter({ windowMs = 60_000, max = 60, now = Date.now } = {}) {
+  const buckets = new Map(); // ip -> array of recent hit timestamps within the window
+  return function askRateLimit(req, res, next) {
+    const t = now();
+    const ip = req.ip || (req.socket && req.socket.remoteAddress) || 'unknown';
+    // Prune this IP's bucket to the window, then decide.
+    const hits = (buckets.get(ip) || []).filter((ts) => ts > t - windowMs);
+    if (hits.length >= max) {
+      const retryAfter = Math.max(1, Math.ceil((hits[0] + windowMs - t) / 1000));
+      res.set('Retry-After', String(retryAfter));
+      return res.status(429).json({ ok: false, error: 'rate_limited', retry_after_seconds: retryAfter });
+    }
+    hits.push(t);
+    buckets.set(ip, hits);
+    return next();
+  };
+}
+
+module.exports = { makeAskRateLimiter };