@vellumai/vellum-gateway 0.7.0 → 0.7.2

package/src/auth/ipc-route-policy.ts

@@ -0,0 +1,217 @@
+/**
+ * Policy enforcement for IPC-proxied routes.
+ *
+ * The gateway owns scope and principal-type enforcement for requests
+ * routed through the IPC proxy. Each protected route is registered by
+ * operationId — the same identifier the route schema cache uses for
+ * matching. Unregistered operationIds have no policy (open access once
+ * past JWT validation).
+ *
+ * This registry mirrors the daemon's route-policy.ts but is keyed by
+ * operationId rather than endpoint, and lives gateway-side so policy
+ * enforcement doesn't depend on the daemon.
+ */
+
+import type { PrincipalType, Scope } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface IpcRoutePolicy {
+  requiredScopes: readonly Scope[];
+  allowedPrincipalTypes: readonly PrincipalType[];
+}
+
+// ---------------------------------------------------------------------------
+// Default principal types — most routes allow all four.
+// ---------------------------------------------------------------------------
+
+const ALL_PRINCIPALS: readonly PrincipalType[] = [
+  "actor",
+  "svc_gateway",
+  "svc_daemon",
+  "local",
+];
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+type PolicyEntry =
+  | [operationId: string, scopes: Scope[]]
+  | [operationId: string, scopes: Scope[], principals: PrincipalType[]];
+
+/**
+ * Compact policy table. Two-element tuples use ALL_PRINCIPALS;
+ * three-element tuples specify restricted principal types.
+ */
+const POLICY_TABLE: PolicyEntry[] = [
+  // Admin / internal
+  ["admin_rollbackmigrations_post", ["internal.write"], ["svc_gateway"]],
+
+  // Calls
+  ["calls_answer", ["calls.write"]],
+  ["calls_cancel", ["calls.write"]],
+  ["calls_get", ["calls.read"]],
+  ["calls_instruction", ["calls.write"]],
+  ["calls_start", ["calls.write"]],
+
+  // Channel readiness
+  ["channels_readiness_get", ["settings.read"]],
+  ["channels_readiness_refresh_post", ["settings.write"]],
+
+  // Config / platform
+  ["config_platform_get", ["settings.read"]],
+  ["config_platform_put", ["settings.write"]],
+
+  // Diagnostics
+  ["diagnostics_envvars_get", ["settings.read"]],
+
+  // Dictation / STT / TTS
+  ["dictation_post", ["chat.write"]],
+  ["messages_tts", ["chat.read"]],
+  ["stt_providers", ["settings.read"]],
+  ["stt_transcribe", ["chat.write"]],
+  ["tts_synthesize", ["chat.read"]],
+
+  // Documents
+  ["getDocument", ["settings.read"]],
+  ["listDocuments", ["settings.read"]],
+  ["saveDocument", ["settings.write"]],
+
+  // Filing / heartbeat
+  ["getFilingConfig", ["settings.read"]],
+  ["getHeartbeatConfig", ["settings.read"]],
+  ["runFilingNow", ["settings.write"]],
+  ["runHeartbeatNow", ["settings.write"]],
+  ["updateHeartbeatConfig", ["settings.write"]],
+
+  // Integrations / ingress
+  ["integrations_ingress_config_get", ["settings.read"]],
+  ["integrations_ingress_config_put", ["settings.write"]],
+  ["integrations_oauth_start_post", ["settings.write"]],
+
+  // Integrations / Slack channel
+  ["integrations_slack_channel_config_get", ["settings.read"]],
+  ["integrations_slack_channel_config_post", ["settings.write"]],
+  ["integrations_slack_channel_config_delete", ["settings.write"]],
+
+  // Integrations / Telegram
+  ["integrations_telegram_config_get", ["settings.read"]],
+  ["integrations_telegram_config_post", ["settings.write"]],
+  ["integrations_telegram_config_delete", ["settings.write"]],
+  ["integrations_telegram_commands_post", ["settings.write"]],
+  ["integrations_telegram_setup_post", ["settings.write"]],
+
+  // Integrations / Twilio
+  ["integrations_twilio_config_get", ["settings.read"]],
+  ["integrations_twilio_credentials_post", ["settings.write"]],
+  ["integrations_twilio_credentials_delete", ["settings.write"]],
+  ["integrations_twilio_numbers_get", ["settings.read"]],
+  ["integrations_twilio_numbers_provision_post", ["settings.write"]],
+  ["integrations_twilio_numbers_assign_post", ["settings.write"]],
+  ["integrations_twilio_numbers_release_post", ["settings.write"]],
+
+  // Integrations / Vercel
+  ["integrations_vercel_config_get", ["settings.read"]],
+  ["integrations_vercel_config_post", ["settings.write"]],
+  ["integrations_vercel_config_delete", ["settings.write"]],
+
+  // Slack share
+  ["slack_channels_get", ["settings.read"]],
+  ["slack_share_post", ["settings.write"]],
+
+  // Memory items
+  ["createMemoryItem", ["settings.write"]],
+  ["deleteMemoryItem", ["settings.write"]],
+  ["getMemoryItem", ["settings.read"]],
+  ["listMemoryItems", ["settings.read"]],
+  ["updateMemoryItem", ["settings.write"]],
+
+  // Notification intent
+  ["notificationintentresult_post", ["settings.write"]],
+
+  // OAuth
+  ["oauth_apps_connect_post", ["settings.write"]],
+  ["oauth_apps_connections_get", ["settings.read"]],
+  ["oauth_apps_delete", ["settings.write"]],
+  ["oauth_apps_get", ["settings.read"]],
+  ["oauth_apps_post", ["settings.write"]],
+  ["oauth_connections_delete", ["settings.write"]],
+  ["oauth_providers_by_providerKey_get", ["settings.read"]],
+  ["oauth_providers_get", ["settings.read"]],
+  ["oauth_start_post", ["settings.write"]],
+
+  // Profiler (gateway-only)
+  ["profiler_runs_by_runId_delete", ["internal.write"], ["svc_gateway"]],
+  ["profiler_runs_by_runId_export_post", ["internal.write"], ["svc_gateway"]],
+  ["profiler_runs_by_runId_get", ["internal.write"], ["svc_gateway"]],
+  ["profiler_runs_get", ["internal.write"], ["svc_gateway"]],
+
+  // Recordings
+  ["recordings_pause", ["settings.write"]],
+  ["recordings_resume", ["settings.write"]],
+  ["recordings_start", ["settings.write"]],
+  ["recordings_status_get", ["settings.read"]],
+  ["recordings_status_post", ["settings.write"]],
+  ["recordings_stop", ["settings.write"]],
+
+  // Settings
+  ["settings_avatar_generate_post", ["settings.write"]],
+  ["settings_client_put", ["settings.write"]],
+  ["settings_voice_put", ["settings.write"]],
+
+  // Skills
+  ["checkSkillUpdates", ["settings.write"]],
+  ["configureSkill", ["settings.write"]],
+  ["createSkill", ["settings.write"]],
+  ["deleteSkill", ["settings.write"]],
+  ["disableSkill", ["settings.write"]],
+  ["draftSkill", ["settings.write"]],
+  ["enableSkill", ["settings.write"]],
+  ["getSkill", ["settings.read"]],
+  ["getSkillFileContent", ["settings.read"]],
+  ["getSkillFiles", ["settings.read"]],
+  ["inspectSkill", ["settings.read"]],
+  ["installSkill", ["settings.write"]],
+  ["listSkills", ["settings.read"]],
+  ["searchSkills", ["settings.read"]],
+  ["updateSkill", ["settings.write"]],
+
+  // Tools
+  ["tools_get", ["settings.read"]],
+  ["tools_simulate_permission_post", ["settings.read"]],
+
+  // Workspace files
+  ["workspacefiles_get", ["settings.read"]],
+  ["workspacefiles_read_get", ["settings.read"]],
+];
+
+// ---------------------------------------------------------------------------
+// Build the lookup map
+// ---------------------------------------------------------------------------
+
+const policyMap = new Map<string, IpcRoutePolicy>();
+
+for (const entry of POLICY_TABLE) {
+  const [operationId, scopes, principals] = entry;
+  policyMap.set(operationId, {
+    requiredScopes: scopes,
+    allowedPrincipalTypes: principals ?? ALL_PRINCIPALS,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Look up the IPC route policy for an operationId.
+ * Returns undefined for unregistered (unprotected) operations.
+ */
+export function getIpcRoutePolicy(
+  operationId: string,
+): IpcRoutePolicy | undefined {
+  return policyMap.get(operationId);
+}

package/src/backup/backup-key.ts

@@ -0,0 +1,138 @@
+/**
+ * Backup key management.
+ *
+ * The backup key is a 32-byte random secret used to authenticate / encrypt
+ * workspace backups. It is generated once per install and persisted to disk
+ * in the gateway security directory — outside the workspace and outside the
+ * assistant sandbox boundary.
+ *
+ * This module is intentionally pure: callers pass the full `keyPath` rather
+ * than resolving a default location. That keeps the helpers trivially
+ * testable against temp directories and avoids any coupling to gateway
+ * startup, workspace layout, or global path helpers.
+ *
+ * On-disk invariants:
+ * - Parent directory is created with mode `0o700`.
+ * - Key file is written atomically (temp + `link`) with mode `0o600`, so
+ *   concurrent callers converge on the first winner's bytes.
+ * - Key file is exactly 32 bytes; any other size is treated as corruption.
+ */
+
+import { randomBytes } from "node:crypto";
+import {
+  chmod,
+  link,
+  mkdir,
+  readFile,
+  stat,
+  unlink,
+  writeFile,
+} from "node:fs/promises";
+import { dirname } from "node:path";
+
+/** Required length of the backup key file, in bytes. */
+const BACKUP_KEY_LENGTH = 32;
+
+/**
+ * Check whether a filesystem path exists without throwing.
+ *
+ * Only `ENOENT` is treated as "missing". Any other errno (EIO, ESTALE,
+ * EACCES, ...) is rethrown — we must not silently treat a transient I/O
+ * failure as "file is absent" because that can cause an existing backup
+ * key to be rotated away under the caller's feet, breaking decryption of
+ * data encrypted with the prior key.
+ */
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException)?.code === "ENOENT") return false;
+    throw err;
+  }
+}
+
+/**
+ * Read the backup key from disk if it exists.
+ *
+ * Returns the raw 32-byte buffer, or `null` if the file is missing. Intended
+ * for read-only callers (e.g. restore paths) that should not create a new
+ * key as a side effect.
+ *
+ * Throws if the file exists but is not exactly 32 bytes — callers should
+ * treat that as a corruption signal rather than silently regenerating.
+ */
+export async function readBackupKey(keyPath: string): Promise<Buffer | null> {
+  if (!(await pathExists(keyPath))) return null;
+  const buf = await readFile(keyPath);
+  if (buf.length !== BACKUP_KEY_LENGTH) {
+    throw new Error(
+      `Backup key at ${keyPath} has invalid length ${buf.length} (expected ${BACKUP_KEY_LENGTH})`,
+    );
+  }
+  return buf;
+}
+
+/**
+ * Ensure a backup key exists at `keyPath`, returning its bytes.
+ *
+ * - If the file exists, it is read and validated. A wrong-size file throws,
+ *   so a corrupt key is never silently replaced.
+ * - Otherwise, the parent directory is created (mode `0o700`), a fresh
+ *   32-byte random key is generated, written to a unique tmp file, and
+ *   atomically published to `keyPath` via `link()`.
+ *
+ * Concurrency: callers that race here must all converge on the same bytes
+ * — otherwise one caller encrypts data with bytes that will never be
+ * persisted and can never be decrypted.
+ *
+ * We use the canonical Unix atomic-create idiom: write full contents to
+ * a per-call tmp file, then `link(tmp, keyPath)`. `link` fails with
+ * `EEXIST` if `keyPath` already exists, which makes exactly one racing
+ * caller the winner; the rest read the winner's bytes. `rename(2)` by
+ * contrast overwrites the destination and is not race-safe here — two
+ * renames can leave either caller's bytes on disk regardless of who
+ * generated them, so a lost caller would return bytes that don't match
+ * what's persisted. `link` avoids that entirely.
+ */
+export async function ensureBackupKey(keyPath: string): Promise<Buffer> {
+  const existing = await readBackupKey(keyPath);
+  if (existing) return existing;
+
+  const parent = dirname(keyPath);
+  await mkdir(parent, { recursive: true, mode: 0o700 });
+
+  const key = randomBytes(BACKUP_KEY_LENGTH);
+  const tmpPath = `${keyPath}.tmp.${process.pid}.${randomBytes(8).toString("hex")}`;
+  try {
+    // `wx` fails if tmpPath somehow exists (stale orphan or collision) so
+    // we never silently overwrite another writer's in-flight tmp file.
+    await writeFile(tmpPath, key, { flag: "wx", mode: 0o600 });
+    // Some platforms / umasks ignore the `mode` option on writeFile, so
+    // enforce 0o600 explicitly before publishing.
+    await chmod(tmpPath, 0o600);
+    try {
+      // Atomic publish: only one racing caller's link() succeeds.
+      await link(tmpPath, keyPath);
+      return key;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException)?.code !== "EEXIST") throw err;
+      // Another caller won the race. Return their bytes, not ours.
+      const winner = await readBackupKey(keyPath);
+      if (!winner) {
+        throw new Error(
+          `link() reported EEXIST but ${keyPath} is unreadable`,
+        );
+      }
+      return winner;
+    }
+  } finally {
+    // Remove our tmp file whether we won (tmp is a hard link to keyPath,
+    // safe to unlink), lost, or errored. Best-effort.
+    try {
+      await unlink(tmpPath);
+    } catch {
+      // ignore
+    }
+  }
+}

package/src/backup/backup-routes.ts

@@ -0,0 +1,159 @@
+/**
+ * Gateway HTTP routes for backup operations.
+ *
+ * These routes are the guardian-facing API for backup management. The
+ * assistant daemon has no backup CLI or routes — all backup operations
+ * go through the gateway, which owns the encryption key and performs
+ * the encrypt/decrypt operations.
+ *
+ * Routes:
+ *   GET  /v1/backups        — list local + offsite snapshots
+ *   POST /v1/backups/create — manual snapshot trigger
+ */
+
+import { readConfigFileOrEmpty } from "../config-file-utils.js";
+import { getLogger } from "../logger.js";
+import { listSnapshotsInDir, type SnapshotEntry } from "./list-snapshots.js";
+import { getLocalBackupsDir } from "./paths.js";
+import { createSnapshotNow } from "./backup-worker.js";
+
+const log = getLogger("backup-routes");
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+interface BackupDestination {
+  path: string;
+  encrypt: boolean;
+}
+
+function readBackupDestinations(): {
+  localDir: string;
+  offsiteDestinations: BackupDestination[];
+} {
+  const raw = readConfigFileOrEmpty();
+  const backup = (raw.backup ?? {}) as Record<string, unknown>;
+
+  const localDirectory =
+    typeof backup.localDirectory === "string" ? backup.localDirectory : null;
+  const localDir = getLocalBackupsDir(localDirectory);
+
+  const offsiteRaw = (backup.offsite ?? {}) as Record<string, unknown>;
+  const offsiteEnabled = offsiteRaw.enabled !== false;
+  let offsiteDestinations: BackupDestination[] = [];
+
+  if (offsiteEnabled) {
+    if (Array.isArray(offsiteRaw.destinations)) {
+      offsiteDestinations = offsiteRaw.destinations
+        .filter(
+          (d): d is { path: string; encrypt?: boolean } =>
+            d &&
+            typeof d === "object" &&
+            typeof (d as Record<string, unknown>).path === "string",
+        )
+        .map((d) => ({ path: d.path, encrypt: d.encrypt !== false }));
+    }
+    // null destinations = iCloud default, but we don't list those unless
+    // they already have snapshots on disk.
+  }
+
+  return { localDir, offsiteDestinations };
+}
+
+function snapshotToJson(entry: SnapshotEntry): Record<string, unknown> {
+  return {
+    path: entry.path,
+    filename: entry.filename,
+    created_at: entry.createdAt.toISOString(),
+    size_bytes: entry.sizeBytes,
+    encrypted: entry.encrypted,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Route handlers
+// ---------------------------------------------------------------------------
+
+interface BackupRouteDeps {
+  assistantRuntimeBaseUrl: string;
+}
+
+/**
+ * GET /v1/backups — list local and offsite snapshots.
+ */
+export function createListBackupsHandler(_deps: BackupRouteDeps) {
+  return async function handleListBackups(_req: Request): Promise<Response> {
+    try {
+      const { localDir, offsiteDestinations } = readBackupDestinations();
+
+      const localSnapshots = await listSnapshotsInDir(localDir);
+      const offsitePools: Array<{
+        destination: BackupDestination;
+        snapshots: SnapshotEntry[];
+      }> = [];
+
+      for (const dest of offsiteDestinations) {
+        const snapshots = await listSnapshotsInDir(dest.path);
+        offsitePools.push({ destination: dest, snapshots });
+      }
+
+      return Response.json({
+        local: {
+          directory: localDir,
+          snapshots: localSnapshots.map(snapshotToJson),
+        },
+        offsite: offsitePools.map((pool) => ({
+          directory: pool.destination.path,
+          encrypted: pool.destination.encrypt,
+          snapshots: pool.snapshots.map(snapshotToJson),
+        })),
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      log.error({ err }, "Failed to list backups");
+      return Response.json(
+        { error: "Internal Server Error", message },
+        { status: 500 },
+      );
+    }
+  };
+}
+
+/**
+ * POST /v1/backups/create — manual snapshot trigger.
+ */
+export function createBackupSnapshotHandler(deps: BackupRouteDeps) {
+  return async function handleCreateBackup(_req: Request): Promise<Response> {
+    try {
+      const result = await createSnapshotNow(deps);
+
+      return Response.json({
+        success: true,
+        local: snapshotToJson(result.local),
+        offsite: result.offsite.map((r) => ({
+          destination: r.destination.path,
+          status: r.entry ? "ok" : r.skipped ? "skipped" : "error",
+          entry: r.entry ? snapshotToJson(r.entry) : null,
+          error: r.error ?? null,
+        })),
+        duration_ms: result.durationMs,
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      log.error({ err }, "Manual backup snapshot failed");
+
+      if (message.includes("already in progress")) {
+        return Response.json(
+          { error: "Conflict", message: "A backup snapshot is already in progress" },
+          { status: 409 },
+        );
+      }
+
+      return Response.json(
+        { error: "Internal Server Error", message },
+        { status: 500 },
+      );
+    }
+  };
+}