voroa-cli 0.0.0-stage → 0.3.0

package/src/api.js

@@ -0,0 +1,552 @@
+// The CLI's only HTTP layer. Every request to Voroa goes through `request` below.
+//
+// THIS FILE IS THE ONE PLACE ALLOWED TO TOUCH A `.status` PROPERTY, and that is enforced by
+// `backend/tests/cliGuards.test.js`. Two unrelated things are called `status` on the wire and
+// confusing them is known bug #24:
+//
+//   app status payload  .status  = the CONTAINER's "state:health" string ("running:healthy").
+//                                  Legitimate - it is `classify`'s first argument.
+//   deployment row      .status  = the RAW BUILD status ('building'|'live'|'failed'). This one
+//                                  LIES about the runtime: 'live' means the image built and the
+//                                  start job returned, not that the service came up. The honest
+//                                  answer is the separate `verdict` field.
+//
+// So the rename happens here, once, at the boundary: `.status` becomes `containerStatus` on a
+// status payload and `buildStatus` on a deployment row. Past this file the ambiguous name does not
+// exist, and no command can pick the wrong one by accident.
+//
+// Golden rule 3: the server already returns a generic `clientMessage` for anything upstream. We
+// surface that string and never invent detail from a transport error - a raw fetch error can carry
+// an internal hostname.
+import { DEFAULT_API_URL } from './config.js';
+
+export class ApiError extends Error {
+  // `httpStatus`, deliberately not `status` - see the header. Callers branch on this.
+  constructor(message, { httpStatus = 0, code = null } = {}) {
+    super(message);
+    this.name = 'ApiError';
+    this.httpStatus = httpStatus;
+    this.code = code;
+  }
+}
+
+export const SESSION_EXPIRED = 'Your session has expired. Run `voroa login`.';
+
+// Batch-status cap. Mirrors MAX_BATCH in backend/src/routes/apps/statusBatch.js, which dedupes and
+// then SLICES - anything past the cap is dropped silently. So we chunk instead of hoping.
+export const MAX_BATCH = 100;
+
+// TWO CREDENTIALS, TWO DOORS. A session (from `voroa login`) goes to /api/*. An API token - the scoped,
+// revocable, workspace-pinned `voroa_cat_` kind minted in the dashboard - is accepted ONLY on
+// /api/ext/customer/*, which re-mounts the same routes behind the token's scopes and a capability
+// allow-list (backend/src/lib/customerMcpCapabilities.js). Same paths after the prefix, same response
+// shapes, so the switch happens here once and no command knows which door it used. This is the CI path:
+// a session in a CI secret is a full-power login; a token is scoped, expiring and audited.
+const API_TOKEN_PREFIX = 'voroa_cat_';
+const SESSION_BASE = '/api';
+const TOKEN_BASE = '/api/ext/customer';
+
+export function isApiToken(token) {
+  return typeof token === 'string' && token.startsWith(API_TOKEN_PREFIX);
+}
+
+function pathFor(ctx, pathname) {
+  if (!isApiToken(ctx.token) || !pathname.startsWith(`${SESSION_BASE}/`)) return pathname;
+  return TOKEN_BASE + pathname.slice(SESSION_BASE.length);
+}
+
+function joinUrl(base, pathname) {
+  return `${String(base).replace(/\/+$/, '')}${pathname}`;
+}
+
+async function readJson(res) {
+  try {
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+
+export const TOKEN_REJECTED = 'VOROA_TOKEN was rejected. It may be revoked or expired - create a new one in the dashboard.';
+
+function messageFor(httpStatus, body, viaToken = false) {
+  // A token has no session to expire and nothing `voroa login` could fix - say what is actually wrong.
+  if (httpStatus === 401) return viaToken ? TOKEN_REJECTED : SESSION_EXPIRED;
+  if (httpStatus === 403) return viaToken ? "This token's scopes do not allow that." : 'You do not have access to that.';
+  // On the token door an action outside the allow-list answers 404, exactly like a missing service.
+  if (httpStatus === 404) return viaToken ? 'Not found - or not available to an API token.' : 'Not found.';
+  if (httpStatus === 429) return 'Too many requests. Wait a moment and try again.';
+  // The server's own message is already customer-safe (golden rule 3). Anything else is generic.
+  if (body && typeof body.error === 'string' && body.error) return body.error;
+  return `The request failed (HTTP ${httpStatus}).`;
+}
+
+export function contextFrom(settings) {
+  const apiUrl = settings.apiUrl || DEFAULT_API_URL;
+  return {
+    apiUrl,
+    token: settings.token || null,
+    workspaceId: settings.workspaceId || null,
+    // Why there is no token, in the words the caller needs. A session withheld because it belongs to
+    // a different endpoint is a different problem from never having signed in, and "you are not
+    // signed in" would send someone to `voroa login` without explaining what happened to the session
+    // they know they have.
+    noTokenMessage: settings.tokenWithheldFrom
+      ? `You are signed in to ${settings.tokenWithheldFrom}, not ${apiUrl}. That session is not sent to another endpoint. ` +
+        `Run \`voroa login --api-url ${apiUrl}\`, or set VOROA_TOKEN.`
+      : 'You are not signed in. Run `voroa login`.',
+  };
+}
+
+// Headers for an authenticated call. The token goes here and NOWHERE else (rule 13).
+function authHeaders(ctx) {
+  const headers = { Accept: 'application/json' };
+  if (ctx.token) headers.Authorization = `Bearer ${ctx.token}`;
+  // No stored workspace -> no header -> the server picks the caller's default. We never guess an id.
+  // An API token is pinned to ONE workspace server-side, so the header is not sent with it: a stored
+  // workspace from a different login must not look like it had any say.
+  if (ctx.workspaceId && !isApiToken(ctx.token)) headers['X-Workspace-Id'] = ctx.workspaceId;
+  return headers;
+}
+
+async function request(ctx, pathname, { method = 'GET', body, auth = true } = {}) {
+  if (auth && !ctx.token) {
+    throw new ApiError(ctx.noTokenMessage || 'You are not signed in. Run `voroa login`.', { httpStatus: 401 });
+  }
+  const headers = auth ? authHeaders(ctx) : { Accept: 'application/json' };
+  if (body !== undefined) headers['Content-Type'] = 'application/json';
+
+  let res;
+  try {
+    res = await fetch(joinUrl(ctx.apiUrl, auth ? pathFor(ctx, pathname) : pathname), {
+      method,
+      headers,
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+  } catch {
+    // The transport error object is dropped on purpose: it can carry resolved hosts and, on some
+    // runtimes, the request headers. We say what we know.
+    throw new ApiError(`Could not reach Voroa at ${ctx.apiUrl}.`, { httpStatus: 0 });
+  }
+
+  const data = await readJson(res);
+  if (!res.ok) throw new ApiError(messageFor(res.status, data, auth && isApiToken(ctx.token)), { httpStatus: res.status, code: data && data.code });
+  return data || {};
+}
+
+// --- auth -------------------------------------------------------------------------------------
+
+// Is the code path usable? A transport failure is RETHROWN rather than answered "no": telling
+// someone sign-in codes are unavailable and to try --password, when the real problem is that the
+// endpoint cannot be reached at all, sends them down a path that fails the same way for a reason
+// they were not told. Only a real answer (or an older backend that has no such route) falls through
+// to the password suggestion.
+export async function otpAvailable(ctx) {
+  try {
+    const d = await request(ctx, '/api/auth/otp/available', { auth: false });
+    return !!(d && d.enabled);
+  } catch (e) {
+    if (e instanceof ApiError && e.httpStatus === 0) throw e;
+    return false;
+  }
+}
+
+// Always 200 for a well-formed address, whether or not the account exists and whether or not the
+// send was throttled (the endpoint is enumeration-safe on purpose). So a success here means "we
+// asked", not "an email is on its way" - the login copy says exactly that.
+export async function requestOtp(ctx, email) {
+  return request(ctx, '/api/auth/otp/request', { method: 'POST', body: { email }, auth: false });
+}
+
+export async function verifyOtp(ctx, email, code) {
+  return request(ctx, '/api/auth/otp/verify', { method: 'POST', body: { email, code }, auth: false });
+}
+
+export async function passwordLogin(ctx, email, password) {
+  return request(ctx, '/api/auth/login', { method: 'POST', body: { email, password }, auth: false });
+}
+
+// --- workspaces -------------------------------------------------------------------------------
+
+export async function listWorkspaces(ctx) {
+  const d = await request(ctx, '/api/workspaces');
+  return Array.isArray(d.workspaces) ? d.workspaces : [];
+}
+
+// --- services ---------------------------------------------------------------------------------
+
+// GET /api/apps is already scoped to the caller AND the active workspace by the server. It is the
+// ONLY candidate set for name resolution - a name is never looked up anywhere wider (golden rule 2,
+// bug #14).
+export async function listApps(ctx) {
+  const d = await request(ctx, '/api/apps');
+  const rows = Array.isArray(d.apps) ? d.apps : [];
+  return rows.map((r) => ({
+    uuid: r.uuid,
+    name: r.name,
+    branch: r.git_branch || null,
+    repository: r.git_repository || null,
+    serviceType: r.serviceType || null,
+    createdAt: r.created_at ?? null,
+    raw: r,
+  }));
+}
+
+function foldStatus(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  return {
+    uuid: raw.uuid || null,
+    containerStatus: raw.status ?? null, // renamed at the boundary - see the file header
+    deploymentStatus: raw.deploymentStatus ?? null,
+    verdict: raw.verdict ?? null,
+    fqdn: raw.fqdn ?? null,
+    branch: raw.branch ?? null,
+    raw,
+  };
+}
+
+export async function appStatus(ctx, uuid) {
+  return foldStatus(await request(ctx, `/api/apps/${encodeURIComponent(uuid)}/status`));
+}
+
+// Batch status, chunked to MAX_BATCH. Returns a Map so a caller can tell "this service was not in
+// the answer" apart from "this service has no status" - the server drops unknown uuids silently,
+// and rendering that as a blank cell would be a quiet lie.
+export async function batchStatus(ctx, uuids) {
+  const out = new Map();
+  const unique = [...new Set(uuids.filter(Boolean))];
+  // The batch endpoint is not on the token door, so ask per service, a few at a time. A failure leaves
+  // that uuid out of the map - the same honest gap as a dropped batch chunk below.
+  if (isApiToken(ctx.token)) {
+    for (let i = 0; i < unique.length; i += 5) {
+      await Promise.all(
+        unique.slice(i, i + 5).map(async (uuid) => {
+          try {
+            const st = await appStatus(ctx, uuid);
+            if (st) out.set(uuid, st);
+          } catch {
+            /* left out -> "Status unavailable" */
+          }
+        })
+      );
+    }
+    return out;
+  }
+  for (let i = 0; i < unique.length; i += MAX_BATCH) {
+    const chunk = unique.slice(i, i + MAX_BATCH);
+    let d;
+    try {
+      d = await request(ctx, `/api/apps/status?uuids=${chunk.map(encodeURIComponent).join(',')}`);
+    } catch {
+      // One failed chunk leaves ITS uuids out of the map, and the caller renders them "Status
+      // unavailable" - which is true, and is the same thing it already says for a uuid the server
+      // dropped. Throwing instead would take the whole listing away over a partial failure, which
+      // is a worse answer than an honest gap in one column.
+      continue;
+    }
+    const statuses = d && d.statuses && typeof d.statuses === 'object' ? d.statuses : {};
+    for (const [uuid, value] of Object.entries(statuses)) {
+      const folded = foldStatus(value);
+      if (folded) out.set(uuid, folded);
+    }
+  }
+  return out;
+}
+
+// --- deployments ------------------------------------------------------------------------------
+
+export async function deployHistory(ctx, uuid) {
+  const d = await request(ctx, `/api/apps/${encodeURIComponent(uuid)}/deployments`);
+  const rows = Array.isArray(d.deployments) ? d.deployments : [];
+  return rows.map((r) => ({
+    deploymentUuid: r.deploymentUuid,
+    buildStatus: r.status ?? null, // renamed: raw BUILD state, never a runtime answer (bug #24)
+    verdict: r.verdict ?? null,
+    commit: r.commit || null,
+    commitMessage: r.commitMessage || null,
+    createdAt: r.createdAt ?? null,
+    finishedAt: r.finishedAt ?? null,
+    authorName: r.authorName || null,
+  }));
+}
+
+export async function redeploy(ctx, uuid) {
+  return request(ctx, `/api/apps/${encodeURIComponent(uuid)}/redeploy`, { method: 'POST' });
+}
+
+// The deployment uuid a trigger response carries, or null (an isolated deploy learns its uuid later).
+export function triggeredDeploymentUuid(resp) {
+  const rows = resp && resp.deployment && Array.isArray(resp.deployment.deployments) ? resp.deployment.deployments : [];
+  return (rows[0] && rows[0].deployment_uuid) || null;
+}
+
+// --- lifecycle --------------------------------------------------------------------------------
+
+const LIFECYCLE = new Set(['restart', 'stop', 'start']);
+
+export async function lifecycle(ctx, uuid, action) {
+  if (!LIFECYCLE.has(action)) throw new Error(`unknown lifecycle action ${action}`);
+  return request(ctx, `/api/apps/${encodeURIComponent(uuid)}/${action}`, { method: 'POST' });
+}
+
+// No id -> the server's one-step "previous version". The artifact is resolved server-side from the row.
+export async function rollback(ctx, uuid, deploymentId) {
+  return request(ctx, `/api/apps/${encodeURIComponent(uuid)}/rollback`, {
+    method: 'POST',
+    body: deploymentId ? { deploymentId } : {},
+  });
+}
+
+// --- environment variables ----------------------------------------------------------------------
+
+// NAMES ONLY. Golden rule 4: a stored value is write-only and no read path returns it, so there is no
+// value field to map - and no `env pull` can exist.
+export async function listEnv(ctx, uuid) {
+  const d = await request(ctx, `/api/apps/${encodeURIComponent(uuid)}/env`);
+  const rows = Array.isArray(d.env) ? d.env : [];
+  return rows
+    .filter((r) => r && typeof r.key === 'string')
+    .map((r) => ({ id: r.uuid || r.key, key: r.key, buildTime: !!r.isBuildTime, platformManaged: !!r.isBuildpackControl }));
+}
+
+// Upserts exactly the keys given, then the server redeploys. `overwrite: true` is what the API-token
+// door requires to replace an existing key (ADR-0164); the session door ignores the field, so the
+// command enforces the same rule itself before calling.
+export async function setEnv(ctx, uuid, entries, { overwrite = false } = {}) {
+  return request(ctx, `/api/apps/${encodeURIComponent(uuid)}/env`, {
+    method: 'PUT',
+    body: { envVars: entries, ...(overwrite ? { overwrite: true } : {}) },
+  });
+}
+
+export async function deleteEnv(ctx, uuid, envId) {
+  return request(ctx, `/api/apps/${encodeURIComponent(uuid)}/env/${encodeURIComponent(envId)}`, { method: 'DELETE' });
+}
+
+// --- two-step verification & step-up -------------------------------------------------------------
+
+// Second half of a 2FA sign-in: the challenge from login + one factor -> { token, user }.
+export async function mfaVerify(ctx, challengeToken, method, code) {
+  return request(ctx, '/api/auth/mfa/verify', { method: 'POST', body: { challengeToken, method, code }, auth: false });
+}
+
+// { mfa: { enabled, hasPassword, ... }, stepUpFresh } - never a secret or a code.
+export async function securityState(ctx) {
+  return request(ctx, '/api/security');
+}
+
+// Re-confirm identity on THIS session for ten minutes. body: { method, code? , password? }.
+export async function reauth(ctx, body) {
+  return request(ctx, '/api/security/reauth', { method: 'POST', body });
+}
+
+export async function reauthEmailCode(ctx) {
+  return request(ctx, '/api/security/reauth/email-code', { method: 'POST' });
+}
+
+// --- databases --------------------------------------------------------------------------------
+
+export async function listDatabases(ctx) {
+  const d = await request(ctx, '/api/databases');
+  const rows = Array.isArray(d.databases) ? d.databases : [];
+  return rows.map((r) => ({ uuid: r.uuid, name: r.name, type: r.type || null, state: r.status || null })); // status renamed at the boundary (bug #24)
+}
+
+// Host/port/user/database name. Never a password - the urlTemplate carries '***'.
+export async function databaseConnection(ctx, uuid) {
+  return request(ctx, `/api/databases/${encodeURIComponent(uuid)}/connection`);
+}
+
+// ADR-0182: the one route that decrypts a stored secret. Needs a fresh step-up; every attempt is logged
+// server-side. The caller holds the value only long enough to hand it to psql, and never prints it
+// unless explicitly asked.
+export async function revealDatabasePassword(ctx, uuid) {
+  return request(ctx, `/api/databases/${encodeURIComponent(uuid)}/password/reveal`, { method: 'POST' });
+}
+
+// --- API tokens (the dashboard calls these "MCP tokens"; they are also the CI credential) ----------
+
+export async function listApiTokens(ctx) {
+  return request(ctx, '/api/mcp-tokens');
+}
+
+// The raw value exists in this response and nowhere else, ever.
+export async function mintApiToken(ctx, name, scopes) {
+  return request(ctx, '/api/mcp-tokens', { method: 'POST', body: { name, scopes } });
+}
+
+// --- domains & ssh --------------------------------------------------------------------------------
+
+// A domain's routing state gets its OWN words at the boundary. The server calls a served domain `live`,
+// the same word a deployment uses - and the CLI keeps deploy vocabulary out of every file but status.js
+// (backend/tests/cliStatusParity.test.js). Unquoted keys: a lookup, not a decision on a raw token.
+const DOMAIN_ROUTING = { pending: 'dns_pending', unrouted: 'unrouted', live: 'serving' };
+
+function foldDomain(r) {
+  const routing = DOMAIN_ROUTING[r.status] || null;
+  return {
+    id: r.id,
+    domain: r.domain,
+    verified: r.verifiedStatus === 'verified',
+    certificate: r.certificateStatus || null,
+    serving: routing === 'serving',
+    // `status` renamed at the boundary (bug #24): pending (DNS not here) | unrouted (DNS here, not served) | live
+    routing,
+    // ADR-0268: a wildcard says so; `ownership: 'pending'` means its id is a CLAIM id (not a domain id),
+    // and `dns` is then an ARRAY of two records rather than one record.
+    wildcard: r.wildcard === true,
+    ownership: r.ownership || null,
+    dns: r.dns && typeof r.dns === 'object' ? r.dns : null,
+    // ADR-0264: the domain's own edge state { state, reason }; absent until the edge network is in play.
+    edgeProtection: r.edgeProtection && typeof r.edgeProtection === 'object' ? r.edgeProtection : null,
+  };
+}
+
+export async function listDomains(ctx, uuid) {
+  const d = await request(ctx, `/api/apps/${encodeURIComponent(uuid)}/domains`);
+  return {
+    defaultDomain: d.defaultDomain || null,
+    custom: (Array.isArray(d.custom) ? d.custom : []).map(foldDomain),
+    quota: d.quota || null,
+  };
+}
+
+export async function addDomain(ctx, uuid, domain) {
+  return foldDomain(await request(ctx, `/api/apps/${encodeURIComponent(uuid)}/domains`, { method: 'POST', body: { domain } }));
+}
+
+export async function reprovisionDomain(ctx, uuid, id) {
+  return request(ctx, `/api/apps/${encodeURIComponent(uuid)}/domains/${encodeURIComponent(id)}/reprovision`, { method: 'POST' });
+}
+
+// { entitled, host, port, username, keys, running, hostKeyFingerprint } or { entitled:false, requiredPlans }.
+export async function sshAccess(ctx, uuid) {
+  return request(ctx, `/api/apps/${encodeURIComponent(uuid)}/ssh`);
+}
+
+export async function revokeApiToken(ctx, id) {
+  return request(ctx, `/api/mcp-tokens/${encodeURIComponent(id)}`, { method: 'DELETE' });
+}
+
+// --- logs -------------------------------------------------------------------------------------
+
+// Runtime container tail. `lines` is ALWAYS sent (known bug #8: without it the endpoint can return
+// an enormous payload; the server clamps 1-1000). backend/tests/cliGuards.test.js greps for it.
+// `search` (ADR-0370): only lines containing the text, matched by the server over the last 24 hours.
+export async function runtimeLogs(ctx, uuid, lines, search = '') {
+  const n = Math.max(1, Math.min(1000, Number(lines) || 100));
+  const q = search ? `&q=${encodeURIComponent(search)}` : '';
+  const d = await request(ctx, `/api/apps/${encodeURIComponent(uuid)}/logs?lines=${n}${q}`);
+  return typeof d.logs === 'string' ? d.logs : '';
+}
+
+// Build-log snapshot (also the fallback when the stream is unavailable). Lines arrive
+// server-redacted and are printed as-is - re-parsing or re-filtering them here would be a second,
+// weaker white-label filter (golden rules 3 and 6).
+export async function buildLog(ctx, uuid, deploymentUuid) {
+  const d = await request(
+    ctx,
+    `/api/apps/${encodeURIComponent(uuid)}/deployments/${encodeURIComponent(deploymentUuid)}/log`
+  );
+  return {
+    available: !!d.available,
+    reason: d.reason || null,
+    buildStatus: d.status ?? null, // renamed at the boundary
+    lines: Array.isArray(d.lines) ? d.lines : [],
+    buildMs: d.buildMs ?? null,
+  };
+}
+
+// SSE build-log stream. The pre-flight contract is the server's, not ours (routes/apps/deployments.js):
+//   * 200 with application/json  -> { available:false }: the store is off or the live-stream cap is
+//                                   full. NOT an error - the caller polls instead.
+//   * 401 / 403 / 404            -> also JSON, also "no stream": fall back so the caller still gets
+//                                   a snapshot (or an honest refusal) rather than a hang.
+//   * text/event-stream          -> named events: `log` { lines:[{ts,text}] }, `phase`, and `status`
+//                                   which is TERMINAL (the server closes after it).
+// Returns a stop() that aborts the read.
+export function streamBuildLog(ctx, uuid, deploymentUuid, { onLog, onPhase, onDone, onUnavailable, onError } = {}) {
+  const controller = new AbortController();
+  let stopped = false;
+  let terminal = false;
+
+  function handleFrame(frame) {
+    let event = 'message';
+    const dataParts = [];
+    for (const line of frame.split('\n')) {
+      if (!line || line.startsWith(':')) continue; // comment / keepalive
+      if (line.startsWith('event:')) event = line.slice(6).trim();
+      else if (line.startsWith('data:')) dataParts.push(line.slice(5).trim());
+    }
+    if (!dataParts.length) return;
+    let data;
+    try {
+      data = JSON.parse(dataParts.join('\n'));
+    } catch {
+      return;
+    }
+    if (event === 'log') onLog && onLog(data);
+    else if (event === 'phase') onPhase && onPhase(data);
+    else if (event === 'status') {
+      terminal = true;
+      // Hand the caller the honest field only. The raw build state in this event is the thing the
+      // verdict exists to correct, so it is not forwarded.
+      onDone && onDone({ verdict: data.verdict ?? null, buildMs: data.buildMs ?? null });
+    }
+  }
+
+  (async () => {
+    let res;
+    try {
+      res = await fetch(
+        joinUrl(
+          ctx.apiUrl,
+          // Not on the token door's allow-list -> 404 -> onUnavailable -> the caller polls. Correct, not broken.
+          pathFor(ctx, `/api/apps/${encodeURIComponent(uuid)}/deployments/${encodeURIComponent(deploymentUuid)}/logs/stream?from=0`)
+        ),
+        { headers: authHeaders(ctx), signal: controller.signal }
+      );
+    } catch {
+      if (!stopped) onError && onError(new ApiError(`Could not reach Voroa at ${ctx.apiUrl}.`, { httpStatus: 0 }));
+      return;
+    }
+    const ct = res.headers.get('content-type') || '';
+    if (res.status === 404 || res.status === 401 || res.status === 403 || ct.includes('application/json')) {
+      const body = await readJson(res);
+      if (!stopped) onUnavailable && onUnavailable({ httpStatus: res.status, body });
+      return;
+    }
+    if (!res.ok || !res.body) {
+      if (!stopped) onUnavailable && onUnavailable({ httpStatus: res.status, body: null });
+      return;
+    }
+    const decoder = new TextDecoder();
+    let buf = '';
+    try {
+      for await (const chunk of res.body) {
+        // CRLF -> LF so a proxy rewriting line endings cannot break the blank-line frame split.
+        buf += decoder.decode(chunk, { stream: true }).replace(/\r\n/g, '\n');
+        let idx;
+        while ((idx = buf.indexOf('\n\n')) >= 0) {
+          handleFrame(buf.slice(0, idx));
+          buf = buf.slice(idx + 2);
+        }
+      }
+    } catch {
+      if (!stopped && !terminal) onError && onError(new Error('The log stream dropped.'));
+      return;
+    }
+    // Closed without a terminal event -> the caller falls back to a snapshot, which is what makes
+    // the poll path the correctness guarantee and the stream only a speed-up.
+    if (!stopped && !terminal) onError && onError(new Error('The log stream closed early.'));
+  })();
+
+  return () => {
+    stopped = true;
+    try {
+      controller.abort();
+    } catch {
+      /* already gone */
+    }
+  };
+}

package/src/commands/db.js

@@ -0,0 +1,99 @@
+// `voroa db list` / `voroa db connect <database> [--show-url] [--recovery]`
+//
+// `connect` is the one command that handles a live database password. The rules, in order:
+//   * it is fetched through the reveal route, which needs a fresh step-up and logs every attempt
+//     (ADR-0182) - there is no other way to get it, and this command does not look for one.
+//   * it goes to psql in the ENVIRONMENT (PGPASSWORD), never argv: argv is visible to every user on
+//     the machine through the process list.
+//   * it is printed only with --show-url, with a warning, because a printed URL ends up in terminal
+//     scrollback, screen shares and pasted tickets (golden rule 13).
+import { listDatabases, databaseConnection, revealDatabasePassword, isApiToken } from '../api.js';
+import { pickByNameOrId, ambiguityList } from '../resolve.js';
+import { runInteractive } from '../interactive.js';
+import { withStepUp } from '../stepup.js';
+import { renderTable, out, err, json } from '../output.js';
+import { CliError } from '../errors.js';
+
+// Same tenancy rule as services: the candidate set is the server's scoped listing and nothing wider.
+async function resolveDatabase(ctx, needle) {
+  if (!needle) throw new CliError('Which database? Run `voroa db list` to see them.');
+  const rows = await listDatabases(ctx);
+  const found = pickByNameOrId(rows, needle);
+  if (found.match) return found.match;
+  if (found.ambiguous) throw new CliError(`Multiple databases match "${needle}", use the id:\n${ambiguityList(found.ambiguous)}`);
+  throw new CliError(`No database called "${needle}" in this workspace. Run \`voroa db list\` to see them.`);
+}
+
+export async function db(ctx, { positionals, flags }) {
+  const sub = positionals[0];
+
+  if (!sub || sub === 'list') {
+    const rows = await listDatabases(ctx);
+    if (flags.json) {
+      json({ databases: rows });
+      return 0;
+    }
+    if (!rows.length) {
+      out('No databases in this workspace.');
+      return 0;
+    }
+    out(renderTable(['NAME', 'TYPE', 'STATUS', 'ID'], rows.map((r) => [r.name, r.type, r.state, r.uuid])));
+    return 0;
+  }
+
+  if (sub === 'connect') {
+    if (isApiToken(ctx.token)) throw new CliError('Connecting needs a signed-in session, not an API token. Run `voroa login`.');
+    const target = await resolveDatabase(ctx, positionals[1]);
+    if (target.type && target.type !== 'postgres' && target.type !== 'postgresql') {
+      throw new CliError(`voroa db connect supports PostgreSQL. ${target.name} is ${target.type} - find its connection details in the dashboard.`);
+    }
+    const conn = await databaseConnection(ctx, target.uuid);
+    const ext = conn && conn.external;
+    if (!ext || !ext.host || !ext.port) {
+      throw new CliError(`${target.name} is not reachable from outside Voroa. Turn on external access for it in the dashboard first.`);
+    }
+
+    const revealed = await withStepUp(ctx, () => revealDatabasePassword(ctx, target.uuid), { recovery: !!flags.recovery });
+    if (!revealed || !revealed.password) {
+      throw new CliError(`${target.name}'s password was not kept, so it cannot be shown. Reset it in the dashboard, then try again.`);
+    }
+
+    if (ext.pooled) err('Note: this endpoint is pooled - LISTEN/NOTIFY, session advisory locks and temporary tables do not behave as on a direct connection.');
+
+    // A clean environment for psql: no VOROA_* (the CLI's own token must not reach psql or a shell it
+    // opens with \!), and no inherited PG* - PGHOSTADDR or PGSERVICE would override PGHOST and send the
+    // password to a different host.
+    const base = {};
+    for (const [k, v] of Object.entries(process.env)) {
+      if (!/^(VOROA_|PG)/i.test(k)) base[k] = v;
+    }
+    const env = {
+      ...base,
+      PGHOST: ext.host,
+      PGPORT: String(ext.port),
+      // The revealed password belongs to the built-in `postgres` user (it is what create and rotate
+      // store), NOT to the connection page's designated default role - pairing it with that role fails.
+      PGUSER: 'postgres',
+      PGDATABASE: conn.dbName || 'postgres',
+      PGPASSWORD: revealed.password,
+      PGSSLMODE: 'require',
+    };
+
+    if (flags.showUrl) {
+      err('Warning: the line below contains your database password. Do not paste it anywhere shared.');
+      const u = new URL('postgresql://placeholder');
+      u.hostname = ext.host;
+      u.port = String(ext.port);
+      u.username = env.PGUSER;
+      u.password = revealed.password;
+      u.pathname = `/${env.PGDATABASE}`;
+      u.searchParams.set('sslmode', 'require');
+      out(u.toString());
+      return 0;
+    }
+
+    return runInteractive('psql', [], { env, notFound: 'psql was not found. Install the PostgreSQL client, or use --show-url with another tool.' });
+  }
+
+  throw new CliError(`Unknown db command "${sub}". Try \`voroa db list\` or \`voroa db connect <database>\`.`);
+}