vibecarbon 0.9.0 → 0.11.0

package/src/lib/deploy/tier-registry.js

@@ -0,0 +1,30 @@
+/**
+ * Canonical tier taxonomy. Config persists deployMode ('compose' | 'compose-ha'
+ * | 'kubernetes') plus an ha flag ('kubernetes-ha' is normalized away at
+ * prompt time, see prompts.js). Everything downstream should dispatch on the
+ * tier id returned here instead of re-deriving mode+ha combinations.
+ */
+export const TIERS = ['compose', 'compose-ha', 'k8s', 'k8s-ha'];
+
+export function resolveTier(envConfig = {}) {
+  const { deployMode, ha } = envConfig;
+  const haEnabled = typeof ha === 'object' ? !!ha?.enabled : !!ha;
+  switch (deployMode) {
+    case 'compose':
+      return 'compose';
+    case 'compose-ha':
+      return 'compose-ha';
+    case 'kubernetes':
+      return haEnabled ? 'k8s-ha' : 'k8s';
+    default:
+      throw new Error(`Unknown deployMode: ${JSON.stringify(deployMode)}`);
+  }
+}
+
+export const isHATier = (tier) => tier === 'compose-ha' || tier === 'k8s-ha';
+export const isComposeTier = (tier) => tier === 'compose' || tier === 'compose-ha';
+export const isK8sTier = (tier) => tier === 'k8s' || tier === 'k8s-ha';
+
+export function pulumiStackEnvs(tier, environment) {
+  return tier === 'k8s-ha' ? [`${environment}-primary`, `${environment}-standby`] : [environment];
+}

package/src/lib/deploy/utils.js

@@ -16,9 +16,35 @@ import {
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { runCommand, runCommandAsync } from '../command.js';
+import { knownHostsPathForKey } from '../host-keys.js';
 import { getProviderClass } from '../providers/index.js';
 import { escapeDotenv } from '../shell.js';
 
+/**
+ * Build the SSH `-o` options string for compose provisioning, pinned to the
+ * per-env known_hosts file derived from the deploy key. NEVER disables host-key
+ * verification (no `UserKnownHostsFile=/dev/null` + `StrictHostKeyChecking=no`).
+ *
+ * `accept-new` pins the host key on first connect (provisioning is trust-on-
+ * first-use for ephemeral cloud VMs) then strict-checks on reuse;
+ * `GlobalKnownHostsFile=/dev/null` ignores the system-wide file so a recycled
+ * Hetzner IP with a stale entry doesn't spuriously reject. Callers that need a
+ * stronger pin should `seedKnownHosts()` the IP first (compose/ha.js does).
+ *
+ * Paths are UNQUOTED on purpose: callers `.split(' ')` this string and spread it
+ * into a spawn() argv (no shell), so each token is passed literally — wrapping
+ * the path in quotes would make ssh look for a file literally named `"…"` and
+ * silently ignore the key/known_hosts. `.vibecarbon/` paths under the project
+ * root contain no spaces.
+ *
+ * @param {string} sshKeyPath
+ * @returns {string} space-joined ssh/scp option string
+ */
+export function pinnedSshOptsString(sshKeyPath) {
+  const khPath = knownHostsPathForKey(sshKeyPath);
+  return `-i ${sshKeyPath} -o UserKnownHostsFile=${khPath} -o GlobalKnownHostsFile=/dev/null -o StrictHostKeyChecking=accept-new -o BatchMode=yes`;
+}
+
 // Deployment Defaults
 // Cluster-autoscaler is enabled by default with a static floor of 1 and a
 // bounded ceiling of 3 (CA pool spawns 0..(max-min) workers on top of the
@@ -173,7 +199,8 @@ export function readReplPassword(cwd = process.cwd()) {
  * @returns {Promise<boolean>}
  */
 export async function waitForSSH(host, sshKeyPath, maxAttempts = 30) {
-  const sshOpts = `-i "${sshKeyPath}" -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o BatchMode=yes`;
+  // shell-safety-ignore: pinnedSshOptsString() bakes in BatchMode=yes (validated in its definition)
+  const sshOpts = pinnedSshOptsString(sshKeyPath);
   for (let i = 0; i < maxAttempts; i++) {
     try {
       // silent:true → runCommandAsync rejects on failure so the retry loop
@@ -204,7 +231,8 @@ export async function waitForSSH(host, sshKeyPath, maxAttempts = 30) {
 export async function setupServerFiles(host, sshKeyPath, projectName, options = {}) {
   const cwd = process.cwd();
   const remoteDir = `/opt/${projectName}`;
-  const sshOpts = `-i "${sshKeyPath}" -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o BatchMode=yes`;
+  // shell-safety-ignore: pinnedSshOptsString() bakes in BatchMode=yes (validated in its definition)
+  const sshOpts = pinnedSshOptsString(sshKeyPath);
 
   // Create remote directory and required subdirectories
   await runCommandAsync(

package/src/lib/deploy/wireguard.js

@@ -0,0 +1,146 @@
+/**
+ * WireGuard config builders for the primary↔standby replication tunnel.
+ *
+ * Replication used to run over the public internet with app-layer TLS
+ * (verify-ca). That transport is being replaced by a point-to-point WireGuard
+ * tunnel between the two clusters' gateways: the wire is encrypted by
+ * WireGuard itself, so Postgres traffic inside the tunnel runs plaintext
+ * (see replication.js — sslmode=disable, plain `host` pg_hba lines).
+ *
+ * WG_PORT is deliberately NOT 51820 — in k3s that port belongs to
+ * flannel's built-in wireguard backend (flannel-wg), so a distinct port is
+ * required to avoid colliding with cluster networking.
+ */
+
+import { sshRun } from '../ssh.js';
+
+export const WG_PORT = 51821; // NOT 51820 — flannel-wg owns that in k3s
+export const WG_SUBNET_CIDR = '10.99.0.0/30';
+export const WG_PRIMARY_IP = '10.99.0.1';
+export const WG_STANDBY_IP = '10.99.0.2';
+
+// The TCP port the repl-gateway socat relay listens on (both clusters). The
+// standby db pod dials <local-node-private-ip>:REPL_GATEWAY_PORT; the standby
+// gateway relays that into the tunnel to the primary gateway, which relays to
+// the primary's postgres at 127.0.0.1:5433 (the db StatefulSet hostPort).
+// Arbitrary — chosen distinct from postgres 5432/5433 so it never collides on
+// the host.
+export const REPL_GATEWAY_PORT = 15433;
+
+// The on-node WireGuard private key. Generated on each supabase node with
+// umask 077 and NEVER read back into this process — only the derived public
+// key ever crosses the wire.
+const WG_KEY_PATH = '/etc/vibecarbon-wg.key';
+
+const WG_PUBKEY_RE = /^[A-Za-z0-9+/]{43}=$/; // base64 Curve25519 public key
+const ENDPOINT_RE = /^(\d{1,3}\.){3}\d{1,3}:\d{1,5}$/;
+const ALLOWED_IP_RE = /^(\d{1,3}\.){3}\d{1,3}\/\d{1,2}$/;
+
+/**
+ * Argv-safe `wg`/`ip` command sequence bringing up the point-to-point wg0
+ * tunnel. Interpolated values are validated (they reach a remote shell), so a
+ * malformed peer key/endpoint throws rather than injecting.
+ */
+export function buildWireguardInterfaceConfig({
+  selfIp,
+  selfPrivKeyPath,
+  listenPort,
+  peerPubKey,
+  peerEndpoint,
+  peerAllowedIp,
+  keepalive = 25,
+}) {
+  if (!WG_PUBKEY_RE.test(peerPubKey || '')) {
+    throw new Error(`wireguard: invalid peer pubkey '${peerPubKey}'`);
+  }
+  if (!ENDPOINT_RE.test(peerEndpoint || '')) {
+    throw new Error(`wireguard: invalid peer endpoint '${peerEndpoint}'`);
+  }
+  if (!ALLOWED_IP_RE.test(peerAllowedIp || '')) {
+    throw new Error(`wireguard: invalid peer allowed-ip '${peerAllowedIp}'`);
+  }
+  return [
+    'ip link del wg0 2>/dev/null; true',
+    'ip link add wg0 type wireguard',
+    `ip addr add ${selfIp}/30 dev wg0`,
+    `wg set wg0 private-key ${selfPrivKeyPath} listen-port ${listenPort} ` +
+      `peer ${peerPubKey} allowed-ips ${peerAllowedIp} endpoint ${peerEndpoint} ` +
+      `persistent-keepalive ${keepalive}`,
+    'ip link set wg0 up',
+  ];
+}
+
+/**
+ * Generate a WireGuard keypair on each supabase node, cross-distribute the
+ * PUBLIC keys, and bring up the point-to-point wg0 tunnel between the two
+ * clusters' supabase nodes.
+ *
+ * Key-exchange security contract:
+ *   - The private key is generated ON the node (`wg genkey`, umask 077) into
+ *     WG_KEY_PATH and NEVER read back into this process. `wg set` reads it from
+ *     the file (`private-key <path>`), so the secret never transits argv, never
+ *     gets logged, and is never returned.
+ *   - Only the derived public key (`wg pubkey`) crosses the wire, and each node
+ *     is configured with the PEER's public key + the peer's `<public-ip>:WG_PORT`
+ *     endpoint.
+ *
+ * `primaryIp` / `standbyIp` are the two supabase nodes' PUBLIC IPv4 addresses —
+ * they are BOTH the WireGuard endpoints (UDP WG_PORT) AND the SSH targets. All
+ * SSH runs go through `sshRun`, which pins host keys and passes
+ * `-o BatchMode=yes`.
+ *
+ * @param {object} o
+ * @param {string} o.primaryIp - primary supabase node public IP (SSH + WG endpoint)
+ * @param {string} o.standbyIp - standby supabase node public IP (SSH + WG endpoint)
+ * @param {string} o.sshKeyPath - path to the shared HA SSH private key
+ * @returns {Promise<{primaryPubKey: string, standbyPubKey: string}>}
+ */
+export async function exchangeAndBringUpTunnel({ primaryIp, standbyIp, sshKeyPath }) {
+  if (!primaryIp || !standbyIp || !sshKeyPath) {
+    throw new Error('exchangeAndBringUpTunnel requires primaryIp, standbyIp, and sshKeyPath');
+  }
+
+  // 1. Ensure wireguard-tools is installed and a private key exists on each
+  //    node. Idempotent: the install is skipped when `wg` is already present,
+  //    and the key is generated only if absent (so a re-deploy keeps the same
+  //    keypair and does not churn the tunnel).
+  for (const ip of [primaryIp, standbyIp]) {
+    await sshRun(ip, sshKeyPath, [
+      'bash',
+      '-c',
+      'command -v wg >/dev/null 2>&1 || { apt-get update -qq && ' +
+        'DEBIAN_FRONTEND=noninteractive apt-get install -y -qq wireguard-tools; }; ' +
+        `umask 077; [ -f ${WG_KEY_PATH} ] || wg genkey > ${WG_KEY_PATH}`,
+    ]);
+  }
+
+  // 2. Read back ONLY the public key from each node (private key stays on-node).
+  const primaryPubKey = (
+    await sshRun(primaryIp, sshKeyPath, ['bash', '-c', `wg pubkey < ${WG_KEY_PATH}`])
+  ).trim();
+  const standbyPubKey = (
+    await sshRun(standbyIp, sshKeyPath, ['bash', '-c', `wg pubkey < ${WG_KEY_PATH}`])
+  ).trim();
+
+  // 3. Cross-configure + bring up each node with the PEER's pubkey + endpoint.
+  const primaryUp = buildWireguardInterfaceConfig({
+    selfIp: WG_PRIMARY_IP,
+    selfPrivKeyPath: WG_KEY_PATH,
+    listenPort: WG_PORT,
+    peerPubKey: standbyPubKey,
+    peerEndpoint: `${standbyIp}:${WG_PORT}`,
+    peerAllowedIp: `${WG_STANDBY_IP}/32`,
+  });
+  const standbyUp = buildWireguardInterfaceConfig({
+    selfIp: WG_STANDBY_IP,
+    selfPrivKeyPath: WG_KEY_PATH,
+    listenPort: WG_PORT,
+    peerPubKey: primaryPubKey,
+    peerEndpoint: `${primaryIp}:${WG_PORT}`,
+    peerAllowedIp: `${WG_PRIMARY_IP}/32`,
+  });
+  await sshRun(primaryIp, sshKeyPath, ['bash', '-c', primaryUp.join(' && ')]);
+  await sshRun(standbyIp, sshKeyPath, ['bash', '-c', standbyUp.join(' && ')]);
+
+  return { primaryPubKey, standbyPubKey };
+}

package/src/lib/host-keys.js

@@ -1,5 +1,6 @@
-import { chmodSync, mkdirSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { runCommandAsync } from './command.js';
 
 /**
  * Absolute path to the per-environment known_hosts file for SSH strict-checking.
@@ -29,9 +30,123 @@ export function knownHostsPath(env, cwd = process.cwd()) {
  */
 export function pinHostKey(env, hostKeyLines, cwd = process.cwd()) {
   const path = knownHostsPath(env, cwd);
-  const dir = dirname(path);
+  writeKnownHosts(path, hostKeyLines);
+}
+
+/**
+ * Low-level writer shared by pinHostKey / seedKnownHosts: overwrite `khPath`
+ * with the given lines, enforcing `.vibecarbon/` 0o700 and file 0o600 even
+ * when the targets already exist (mkdir/writeFile only apply `mode` on create).
+ *
+ * @param {string} khPath
+ * @param {string[]} hostKeyLines
+ */
+function writeKnownHosts(khPath, hostKeyLines) {
+  const dir = dirname(khPath);
   mkdirSync(dir, { recursive: true, mode: 0o700 });
   chmodSync(dir, 0o700);
-  writeFileSync(path, `${hostKeyLines.join('\n')}\n`, { mode: 0o600 });
-  chmodSync(path, 0o600);
+  writeFileSync(khPath, `${hostKeyLines.join('\n')}\n`, { mode: 0o600 });
+  chmodSync(khPath, 0o600);
+}
+
+/**
+ * Derive the per-environment known_hosts path from an SSH key path.
+ *
+ * Every SSH/SCP caller in the codebase already threads the deploy key path
+ * (`.vibecarbon/deploy_key_<env>` or `.vibecarbon/ssh-<env>`). Placing
+ * `known_hosts_<env>` beside it lets every caller pin host keys per-env
+ * WITHOUT having to thread a separate `env` argument through helpers that
+ * only receive `(ip, sshKeyPath)`. Self-consistent: the same key path always
+ * derives the same known_hosts file, so seeding and verification agree.
+ *
+ * @param {string} sshKeyPath
+ * @returns {string}
+ */
+export function knownHostsPathForKey(sshKeyPath) {
+  const dir = dirname(sshKeyPath);
+  const env = basename(sshKeyPath)
+    .replace(/^deploy_key_/, '')
+    .replace(/^ssh-/, '');
+  return join(dir, `known_hosts_${env}`);
+}
+
+/**
+ * Does a known_hosts line's host field reference `ip`? The first
+ * whitespace-delimited field is `host[,host2,...]` (we scan un-hashed, so it
+ * is the literal IP, not a `|1|…` hash).
+ */
+function hostLineMatchesIp(line, ip) {
+  const host = line.split(/\s+/)[0] || '';
+  return host.split(',').includes(ip);
+}
+
+async function defaultKeyscan(ip) {
+  // argv form via runCommandAsync (spawn, no shell). `-T 10` bounds the
+  // connect; un-hashed output (no `-H`) so seedKnownHosts can strip a stale
+  // line for a recycled IP by exact-match. Best-effort: a freshly-booted VPS
+  // may not answer yet, so we ignore errors and let the retry loop poll.
+  const out = await runCommandAsync(['ssh-keyscan', '-T', '10', ip], {
+    silent: true,
+    returnOutput: true,
+    timeout: 30_000,
+    ignoreError: true,
+  });
+  return typeof out === 'string' ? out : '';
+}
+
+/**
+ * Seed (or re-seed) the per-env known_hosts file at `khPath` with the target
+ * server's real host keys, captured via `ssh-keyscan`. This is the "trusted
+ * source" for the pin, run once per env on fresh (re)provision.
+ *
+ * SECURITY — chosen semantics (documented so the trade-off is auditable):
+ *   - Merge, don't clobber: existing lines for OTHER hosts are preserved (HA
+ *     keeps primary + standby in one per-env file), but any stale line for
+ *     THIS ip is dropped before the fresh scan is appended. That re-pin is why
+ *     a Hetzner-recycled IP (destroy → redeploy, same IP, new host key) does
+ *     NOT spuriously hard-fail: provisioning replaces the stale pin.
+ *   - Only provisioning re-seeds. Every non-provision command (backup, restore,
+ *     scale, status, warm deploy) strict-checks against the pinned file and
+ *     NEVER re-seeds, so a MITM against an already-established env fails.
+ *   - ssh-keyscan itself is trust-on-first-provision (it accepts whatever key
+ *     the freshly-created VPS presents). This is the pragmatic trust anchor for
+ *     ephemeral cloud VMs with no out-of-band key channel.
+ *
+ * Returns true if a scan landed and the file was written; false if the scan
+ * came back empty (caller's SSH opts still `accept-new`-TOFU on first connect).
+ *
+ * @param {string} khPath - per-env known_hosts path (see knownHostsPathForKey)
+ * @param {string} ip
+ * @param {object} [opts]
+ * @param {number} [opts.attempts=5]
+ * @param {number} [opts.delayMs=2000]
+ * @param {(ip: string) => Promise<string>} [opts.keyscan] - injectable for tests
+ * @param {(ms: number) => Promise<void>} [opts.sleep]
+ * @returns {Promise<boolean>}
+ */
+export async function seedKnownHosts(khPath, ip, opts = {}) {
+  const {
+    attempts = 5,
+    delayMs = 2000,
+    keyscan = defaultKeyscan,
+    sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+  } = opts;
+
+  let scanned = '';
+  for (let i = 0; i < attempts; i++) {
+    scanned = (await keyscan(ip)).trim();
+    if (scanned) break;
+    if (i < attempts - 1) await sleep(delayMs);
+  }
+  if (!scanned) return false;
+
+  let kept = [];
+  if (existsSync(khPath)) {
+    kept = readFileSync(khPath, 'utf-8')
+      .split('\n')
+      .filter((line) => line.trim() && !hostLineMatchesIp(line, ip));
+  }
+  const merged = [...kept, ...scanned.split('\n').filter((l) => l.trim())];
+  writeKnownHosts(khPath, merged);
+  return true;
 }

package/src/lib/iac/index.js

@@ -39,15 +39,23 @@ mkdirSync(LOCAL_STATE_DIR, { recursive: true });
  *
  * Hetzner S3 uses path-style URLs via the Hetzner-provided endpoint, so we
  * pass both `endpoint` and `s3ForcePathStyle=true` in the query string.
+ *
+ * State lives in a DEDICATED bucket (`s3Config.stateBucket`), separate from
+ * the app storage bucket, so `destroy` deleting the app bucket can never yank
+ * the Pulumi backend out from under an in-flight destroy. The `?? bucket`
+ * fallback preserves behavior for any un-migrated path (configs persisted
+ * before the dedicated-state-bucket change, whose state still lives in the app
+ * bucket) — the deploy path always sets `stateBucket`.
  */
 export function resolveBackendUrl(s3Config) {
   if (process.env.PULUMI_BACKEND_URL) {
     return process.env.PULUMI_BACKEND_URL;
   }
   if (s3Config?.bucket && s3Config?.endpoint) {
+    const stateBucket = s3Config.stateBucket ?? s3Config.bucket;
     const endpointHost = s3Config.endpoint.replace(/^https?:\/\//, '');
     const region = s3Config.region || 'nbg1';
-    return `s3://${s3Config.bucket}?endpoint=${endpointHost}&region=${region}&s3ForcePathStyle=true`;
+    return `s3://${stateBucket}?endpoint=${endpointHost}&region=${region}&s3ForcePathStyle=true`;
   }
   return `file://${LOCAL_STATE_DIR}`;
 }
@@ -80,20 +88,30 @@ export async function getOrCreateStack(stackName, program, options = {}) {
   const backendUrl = resolveBackendUrl(options.s3Config);
   const envVars = buildEnv(options);
 
-  const stack = await LocalWorkspace.createOrSelectStack(
-    {
-      stackName,
-      projectName: PULUMI_PROJECT,
-      program,
-    },
-    {
-      projectSettings: {
-        name: PULUMI_PROJECT,
-        runtime: 'nodejs',
-        backend: { url: backendUrl },
-      },
-      envVars,
-    },
+  // createOrSelectStack does a `pulumi stack select` that reads
+  // `.pulumi/meta.yaml` from the S3 backend. On a freshly-created dedicated
+  // state bucket, Hetzner Object Storage frequently throttles this first read
+  // with `SlowDown` / an Unknown blob error, which would kill the deploy before
+  // any resource is touched. Wrap it in the same throttle-retry the up/refresh
+  // ops use so the initial select rides out the fresh-bucket throttle.
+  const stack = await withStateBackendRetry(
+    () =>
+      LocalWorkspace.createOrSelectStack(
+        {
+          stackName,
+          projectName: PULUMI_PROJECT,
+          program,
+        },
+        {
+          projectSettings: {
+            name: PULUMI_PROJECT,
+            runtime: 'nodejs',
+            backend: { url: backendUrl },
+          },
+          envVars,
+        },
+      ),
+    `stack-select ${stackName}`,
   );
 
   return stack;
@@ -105,10 +123,12 @@ export async function getOrCreateStack(stackName, program, options = {}) {
  * fails with `could not list bucket: blob (code=NotFound): NoSuchKey`
  * because the backend hasn't laid down its `.pulumi/meta.yaml` yet. When
  * `deployK8sHA` launches primary + standby `deployK3s` in parallel against
- * the SAME bucket, both threads race the bucket-init and both see the
- * NoSuchKey error, killing the deploy in <20s. Calling this once
+ * the SAME (dedicated) state bucket, both threads race the bucket-init and
+ * both see the NoSuchKey error, killing the deploy in <20s. Calling this once
  * sequentially before the parallel block writes the backend metadata so
- * subsequent stack ops succeed.
+ * subsequent stack ops succeed. (Both HA stacks share ONE state bucket, so
+ * this parallel-init race persists even with the dedicated bucket — hence we
+ * keep the pre-init.)
  *
  * Idempotent: if the bucket is already initialized, the no-op stack is
  * created and removed cleanly. If it fails (e.g., bucket access issue),
@@ -142,8 +162,12 @@ export async function initBackend(options = {}) {
 // once). It is also a transient any single deploy can hit. These ops are all
 // idempotent (Pulumi reconciles to desired state), so retrying on a throttle is
 // safe. Non-throttle errors propagate immediately.
+//
+// "stack is currently locked" is included: a SlowDown-interrupted `up` can leave
+// its own lock behind, so a lock error is retryable — the up wrapper cancels the
+// lock before each attempt (safe: e2e/deploys run one operation per stack).
 export const STATE_BACKEND_THROTTLE_PATTERN =
-  /SlowDown|ServiceUnavailable|RequestLimitExceeded|throttl|too many requests|\b503\b/i;
+  /SlowDown|ServiceUnavailable|RequestLimitExceeded|throttl|too many requests|\b503\b|currently locked|lock\(s\)/i;
 
 export async function withStateBackendRetry(fn, desc, options = {}) {
   const attempts = options.attempts ?? 5;
@@ -222,10 +246,20 @@ export async function upStack(stackName, program, options = {}) {
     }
   }
 
-  const result = await withStateBackendRetry(
-    () => stack.up({ onOutput: options.onOutput, color: 'never' }),
-    'up',
-  );
+  const result = await withStateBackendRetry(async () => {
+    // A `up` that failed on an S3 `SlowDown` (common on a freshly-created
+    // dedicated state bucket, especially under the parallel HA primary+standby
+    // deploys) may have already acquired the stack lock before erroring. The
+    // retry would then fail with "stack is currently locked". Clear the lock
+    // before EACH attempt — cancel() is idempotent and per-stack, so it's safe
+    // under the parallel HA deploys (primary/standby are separate stacks).
+    try {
+      await stack.cancel();
+    } catch {
+      /* no lock — ignore */
+    }
+    return stack.up({ onOutput: options.onOutput, color: 'never' });
+  }, 'up');
   // Flatten outputs: { foo: { value: 'bar', secret: false } } → { foo: 'bar' }
   const outputs = {};
   for (const [key, { value }] of Object.entries(result.outputs || {})) {

package/src/lib/licensing/gate.js

@@ -0,0 +1,59 @@
+/**
+ * Central license gate — the single pre-dispatch chokepoint for paid commands.
+ *
+ * cli.js consults COMMAND_GATES before routing to a command module, so a
+ * paid command can never ship unguarded: every command registered in
+ * KNOWN_COMMANDS must have an explicit classification here (enforced by
+ * tests/unit/licensing/command-gates.test.ts).
+ *
+ * Classifications:
+ *   'paid'     — requires an active Diamond/Fullerene license. Gated in
+ *                cli.js after the project guard (assertInProjectDir is the
+ *                documented first action for project-scoped commands — the
+ *                canonical "not in a project" refusal must win over the
+ *                license upsell; see tests/integration/cli/_global/).
+ *   'free'     — never gated. destroy is deliberately free: teardown is
+ *                never held hostage to a license.
+ *   'internal' — the command gates a sub-flow itself. configure only gates
+ *                `configure cicd`, which is also reachable via interactive
+ *                prompt selection, so the gate must live in-flow.
+ */
+
+export const COMMAND_GATES = {
+  create: 'free',
+  add: 'free',
+  remove: 'free',
+  up: 'free',
+  down: 'free',
+  reset: 'free',
+  deploy: 'paid',
+  destroy: 'free',
+  status: 'free',
+  backup: 'paid',
+  restore: 'paid',
+  failover: 'paid',
+  scale: 'paid',
+  upgrade: 'paid',
+  configure: 'internal',
+  activate: 'free',
+  deactivate: 'free',
+  shell: 'free',
+  diagnose: 'free',
+  console: 'free',
+  access: 'free',
+};
+
+/**
+ * Whether this invocation must hold a paid license.
+ * Help/version invocations are always free — every command handles -h/-v
+ * before doing real work, and the upsell must never block reading docs.
+ *
+ * @param {string} command - The subcommand name
+ * @param {string[]} args - The subcommand's argv (without the command itself)
+ * @returns {boolean}
+ */
+export function shouldGate(command, args = []) {
+  if (COMMAND_GATES[command] !== 'paid') return false;
+  if (args.includes('-h') || args.includes('-v')) return false;
+  return true;
+}

package/src/lib/licensing/index.js

@@ -186,7 +186,7 @@ export function requireLicense(commandName) {
     `  ${c.bold('Vibecarbon Diamond')}   — ${c.success('$149 lifetime')} ${c.dim('— deploy to production, indie & startup use')}`,
   );
   console.log(
-    `  ${c.bold('Vibecarbon Fullerene')} — ${c.success('$499 lifetime')} ${c.dim('— deploy for clients & agencies, commercial use rights')}`,
+    `  ${c.bold('Vibecarbon Fullerene')} — ${c.success('$499 lifetime')} ${c.dim('— deploy for clients & agencies, FSL exception')}`,
   );
   console.log('');
   console.log(`  ${c.dim('Purchase:')} ${c.info('https://vibecarbon.com/#pricing')}`);

package/src/lib/licensing/tiers.js

@@ -13,7 +13,7 @@ export const TIERS = {
     features: ['local-dev', 'all-addons'],
     providers: [],
     maxServers: 0,
-    license: 'MIT',
+    license: 'FSL-1.1-MIT',
     deployFlags: [],
     // Pricing
     price: 0,
@@ -25,6 +25,7 @@ export const TIERS = {
       'Local development',
       'Full Vibecarbon stack',
       'All add-ons (observability, n8n, metabase, redis, CI/CD)',
+      'Fair Source — audit, fork, use commercially',
       'Community support',
     ],
   },
@@ -44,7 +45,7 @@ export const TIERS = {
     ],
     providers: ['hetzner'],
     maxServers: Infinity,
-    license: 'AGPL-Exception',
+    license: 'FSL-1.1-MIT',
     deployFlags: ['--ha', '--k8s'],
     // Pricing
     price: 149,
@@ -77,11 +78,11 @@ export const TIERS = {
       'failover',
       'advanced-monitoring',
       'all-addons',
-      'commercial-use',
+      'fsl-exception',
     ],
     providers: ['hetzner'],
     maxServers: Infinity,
-    license: 'AGPL-Exception',
+    license: 'FSL-1.1-MIT + FSL Exception',
     deployFlags: ['--ha', '--k8s'],
     // Pricing
     price: 499,
@@ -90,7 +91,7 @@ export const TIERS = {
     badge: 'Lifetime Access',
     // Marketing
     marketingFeatures: [
-      'Commercial use rights (AGPL exception)',
+      'FSL exception: embed, white-label, or resell Vibecarbon-powered services',
       'Deploy for clients & organizations',
       'All deployment modes (Compose, Compose HA, Kubernetes)',
       'Full Vibecarbon stack',