cartethyia 2.3.4 → 2.4.0

package/scripts/cli/wordmark.ts

@@ -0,0 +1,58 @@
+/**
+ * The console wordmark.
+ *
+ * Rendered with half-block characters so each letter is two pixel rows tall in
+ * one character cell, and coloured with a horizontal gradient across the
+ * Cartethyia blue-grey range. The caller decides whether to print it: a
+ * non-colour terminal, or one narrower than the wordmark, should skip it.
+ */
+
+const WORDMARK: readonly string[] = [
+  " ██████╗ █████╗ ██████╗ ████████╗███████╗████████╗██╗  ██╗██╗   ██╗██╗ █████╗ ",
+  "██╔════╝██╔══██╗██╔══██╗╚══██╔══╝██╔════╝╚══██╔══╝██║  ██║╚██╗ ██╔╝██║██╔══██╗",
+  "██║     ███████║██████╔╝   ██║   █████╗     ██║   ███████║ ╚████╔╝ ██║███████║",
+  "██║     ██╔══██║██╔══██╗   ██║   ██╔══╝     ██║   ██╔══██║  ╚██╔╝  ██║██╔══██║",
+  "╚██████╗██║  ██║██║  ██║   ██║   ███████╗   ██║   ██║  ██║   ██║   ██║██║  ██║",
+  " ╚═════╝╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝   ╚══════╝   ╚═╝   ╚═╝  ╚═╝   ╚═╝   ╚═╝╚═╝  ╚═╝",
+];
+
+/** Blue-grey gradient: dim at the edges, brighter through the middle. */
+const GRADIENT: readonly [number, number, number][] = [
+  [90, 120, 150],
+  [120, 160, 200],
+  [150, 200, 240],
+  [120, 160, 200],
+  [90, 120, 150],
+];
+
+const RESET = "\u001b[0m";
+
+/**
+ * Returns the wordmark lines with per-column colour, or an empty array when the
+ * terminal is too narrow or colour is disabled.
+ */
+export function renderWordmark(columns = process.stdout.columns ?? 80): string[] {
+  if (process.env.NO_COLOR !== undefined) return [];
+  const width = WORDMARK[0]!.length;
+  if (columns < width) return [];
+
+  const coloured: string[] = [];
+  for (const row of WORDMARK) {
+    let line = "";
+    let current = -1;
+    for (let column = 0; column < row.length; column += 1) {
+      const band = Math.min(
+        GRADIENT.length - 1,
+        Math.floor((column / width) * GRADIENT.length),
+      );
+      const [r, g, b] = GRADIENT[band]!;
+      if (band !== current) {
+        line += `\u001b[38;2;${r};${g};${b}m`;
+        current = band;
+      }
+      line += row[column];
+    }
+    coloured.push(`${line}${RESET}`);
+  }
+  return coloured;
+}

package/src/boot/app.ts

@@ -39,6 +39,9 @@ import { createTokenCountHandler } from "../transport/dispatch/token-count";
 
 import { createTransportPipeline } from "../transport/guards/pipeline";
 import { createDrainHandler, isLoopbackPeer, tokenMatches } from "../transport/drain-endpoint";
+import { createConsoleAccountResetHandler } from "../console/auth/account-reset";
+import { createBackupExportHandler } from "../console/backup/export-endpoint";
+import { consoleUsers, tenants } from "../persistence/schema";
 import { PublicModelCatalogStore, type AllowedModelEntry } from "../console/providers/catalog/public-model-store";
 import type { IpAbuseProtectionService } from "../security/abuse";
 import type { ReadinessCheckResult } from "../persistence/readiness";
@@ -549,6 +552,42 @@ export function createGatewayApp(deps: GatewayAppDeps) {
       app.post("/admin/drain", drainHandler);
     }
 
+    // Operator backup export. Same double gate as drain and reset, and no
+    // console password: the CLI already runs as the OS user who owns the
+    // database, and a forgotten password must not block the backup that is
+    // meant to rescue the install.
+    if (deps.drainToken) {
+      app.post(
+        "/admin/export-backup",
+        createBackupExportHandler({
+          db: deps.db,
+          token: deps.drainToken,
+          resolvePeerAddress: (request) => peerAddresses.get(request) ?? null,
+          resolveTenantId: async () => {
+            const [row] = await deps.db.select({ id: tenants.id }).from(tenants).limit(1);
+            return row?.id ?? null;
+          },
+        }),
+      );
+    }
+
+    // Console account reset. Same double gate as drain — loopback plus the
+    // token — because it deletes every operator credential on the install.
+    // Only authentication state goes; providers, keys, and routing stay.
+    if (deps.drainToken) {
+      app.post(
+        "/admin/reset-console-account",
+        createConsoleAccountResetHandler({
+          token: deps.drainToken,
+          resolvePeerAddress: (request) => peerAddresses.get(request) ?? null,
+          resetConsoleAccount: async () => {
+            const users = await deps.db.delete(consoleUsers);
+            return users.rowCount ?? 0;
+          },
+        }),
+      );
+    }
+
     // Manual task trigger. Same gate as drain: loopback plus the drain token,
     // so a leaked token still cannot reach it from outside the host. 202 once
     // the run has started; 409 when that task is already mid-run, because the

package/src/console/auth/account-reset.ts

@@ -0,0 +1,67 @@
+/**
+ * Console account reset: `POST /admin/reset-console-account`.
+ *
+ * Why this exists. A forgotten console password had no recovery path at all:
+ * `/console/api/auth/change-password` requires the current password, and
+ * first-boot setup only runs when no console user exists. The only documented
+ * escape was deleting the database by hand. This endpoint removes every console
+ * user, which puts `requiresSetup()` back to true so the next visit to
+ * `/console` runs the create-an-account wizard again.
+ *
+ * What it does not touch: providers, provider accounts, API keys, routing,
+ * combos, aliases, usage, and telemetry. Those are not authentication state and
+ * an operator resetting a password has no reason to lose them.
+ *
+ * Gated exactly like the drain endpoint — loopback peer plus a constant-time
+ * token comparison — because it destroys every operator credential on the
+ * install. The two gates are independent, so a leaked token alone cannot reach
+ * it from another host.
+ *
+ * The caller must send the literal confirmation `RESET` in the body. That is a
+ * deliberate speed bump: this is destructive and irreversible, and the TUI asks
+ * the operator to type it rather than press Enter on a menu row.
+ */
+import { GatewayError } from "../../protocol/gateway-error";
+import { isLoopbackPeer, tokenMatches } from "../../transport/drain-endpoint";
+
+export interface ConsoleAccountResetDeps {
+  /** Shared secret; the route is registered only when this is set. */
+  readonly token: string;
+  /** Removes every console user and session. Resolves to the number removed. */
+  readonly resetConsoleAccount: () => Promise<number>;
+  /** Peer address of the request, resolved by the composition root. */
+  readonly resolvePeerAddress: (request: Request) => string | null;
+}
+
+const CONFIRMATION = "RESET";
+
+export function createConsoleAccountResetHandler(
+  deps: ConsoleAccountResetDeps,
+): (context: { request: Request; body: unknown }) => Promise<Response> {
+  return async ({ request, body }) => {
+    if (!isLoopbackPeer(deps.resolvePeerAddress(request)))
+      throw new GatewayError(
+        "invalid_request",
+        403,
+        "console account reset is only available from loopback",
+      );
+    if (!tokenMatches(request.headers.get("x-drain-token"), deps.token))
+      throw new GatewayError("invalid_request", 401, "invalid reset token");
+    const confirm =
+      body !== null && typeof body === "object" && "confirm" in body
+        ? body.confirm
+        : undefined;
+    if (confirm !== CONFIRMATION)
+      throw new GatewayError(
+        "invalid_request",
+        400,
+        `send {"confirm":"${CONFIRMATION}"} to confirm; this deletes every console account`,
+      );
+
+    const removed = await deps.resetConsoleAccount();
+    return new Response(
+      JSON.stringify({ status: "reset", removed }),
+      { status: 200, headers: { "content-type": "application/json", "cache-control": "no-store" } },
+    );
+  };
+}

package/src/console/backup/export-endpoint.ts

@@ -0,0 +1,111 @@
+/**
+ * Operator backup export: `POST /admin/export-backup`.
+ *
+ * Why an endpoint instead of the console page. The dashboard export requires
+ * the operator's console password, because the browser session is the only
+ * proof of identity it has. The CLI is already running as the OS user who owns
+ * the config directory and the database, so requiring a password there only
+ * means a forgotten password blocks the backup that is supposed to rescue the
+ * install. This route is gated like the drain and reset routes — loopback peer
+ * plus the constant-time token — and needs no password.
+ *
+ * What it writes: a gzipped JSON backup of the `config` section only.
+ * `telemetry_events`, `telemetry_usage_totals`, and `telemetry_payloads` are
+ * deliberately excluded: they are per-request history, not configuration, they
+ * are the bulk of the file, and restoring them is not part of what an operator
+ * is trying to recover.
+ *
+ * Where it lands: the directory the caller names, defaulting to the OS download
+ * directory. The CLI passes that path; the route refuses to write outside it.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { GatewayError } from "../../protocol/gateway-error";
+import { isLoopbackPeer, tokenMatches } from "../../transport/drain-endpoint";
+import { BACKUP_SECTIONS, tablesForSection } from "./contracts";
+import { exportBackup } from "./store";
+import type { CartethyiaDatabase } from "../../persistence/db-handle";
+
+export interface BackupExportDeps {
+  readonly db: CartethyiaDatabase;
+  /** Shared secret; the route is registered only when this is set. */
+  readonly token: string;
+  /** The tenant whose rows are exported. */
+  readonly resolveTenantId: () => Promise<string | null>;
+  /** Peer address of the request, resolved by the composition root. */
+  readonly resolvePeerAddress: (request: Request) => string | null;
+}
+
+export interface BackupExportResult {
+  readonly path: string;
+  readonly bytes: number;
+  readonly counts: Record<string, number>;
+}
+
+export function createBackupExportHandler(
+  deps: BackupExportDeps,
+): (context: { request: Request; body: unknown }) => Promise<Response> {
+  return async ({ request, body }) => {
+    if (!isLoopbackPeer(deps.resolvePeerAddress(request)))
+      throw new GatewayError("invalid_request", 403, "backup export is only available from loopback");
+    if (!tokenMatches(request.headers.get("x-drain-token"), deps.token))
+      throw new GatewayError("invalid_request", 401, "invalid export token");
+
+    const directory =
+      body !== null && typeof body === "object" && "directory" in body
+        ? body.directory
+        : undefined;
+    if (directory !== undefined && typeof directory !== "string")
+      throw new GatewayError("invalid_request", 400, "directory must be a string");
+
+    const tenantId = await deps.resolveTenantId();
+    if (tenantId === null)
+      throw new GatewayError("invalid_request", 409, "no tenant exists; run setup first");
+
+    const { payload, counts } = await exportBackup(
+      deps.db,
+      tablesForSection("config"),
+      tenantId,
+    );
+
+    // gzipSync matches what the console writes, so a CLI backup and a dashboard
+    // backup are the same file format and either can be restored by the other.
+    const json = JSON.stringify(payload);
+    const gzipped = Bun.gzipSync(new TextEncoder().encode(json));
+    const target = directory ?? downloadDirectory();
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const path = join(target, `cartethyia-backup-${stamp}.json.gz`);
+
+    try {
+      mkdirSync(target, { recursive: true });
+      writeFileSync(path, gzipped);
+    } catch (error) {
+      throw new GatewayError(
+        "invalid_request",
+        500,
+        `could not write ${path}: ${error instanceof Error ? error.message : "unknown error"}`,
+      );
+    }
+
+    const result: BackupExportResult = { path, bytes: gzipped.byteLength, counts };
+    return new Response(JSON.stringify(result), {
+      status: 200,
+      headers: { "content-type": "application/json", "cache-control": "no-store" },
+    });
+  };
+}
+
+/** The OS download directory, falling back to the home directory. */
+function downloadDirectory(): string {
+  const home = homedir();
+  const candidate =
+    process.platform === "win32"
+      ? join(home, "Downloads")
+      : process.platform === "darwin"
+        ? join(home, "Downloads")
+        : join(process.env.XDG_DOWNLOAD_DIR ?? join(home, "Downloads"));
+  return candidate;
+}
+
+export { BACKUP_SECTIONS };