@mycadet/gateway 0.12.11 → 0.13.0

package/src/backup/offsite-writer.ts

@@ -1,182 +0,0 @@
-/**
- * Offsite snapshot writer with per-destination encryption.
- *
- * "Offsite" destinations are any location outside the local backup directory
- * where the user wants a redundant copy. Canonical examples: iCloud Drive,
- * an external SSD, a network share.
- *
- * Per-destination `encrypt` flag:
- * - `encrypt: true`  → AES-256-GCM stream-encrypt into `.vbundle.enc`.
- * - `encrypt: false` → plaintext copy into `.vbundle`.
- *
- * Each destination is written independently and sequentially.
- */
-
-import { copyFile, mkdir, rename, stat, unlink } from "node:fs/promises";
-import { dirname, join } from "node:path";
-
-import type { SnapshotEntry } from "./list-snapshots.js";
-import { pruneDir } from "./list-snapshots.js";
-import { formatBackupFilename } from "./paths.js";
-import { encryptFile } from "./stream-crypt.js";
-
-export interface BackupDestination {
-  path: string;
-  encrypt: boolean;
-}
-
-export interface OffsiteWriteResult {
-  destination: BackupDestination;
-  entry: SnapshotEntry | null;
-  skipped?: "parent-missing";
-  error?: string;
-}
-
-/**
- * Derive the "safe ancestor" for an offsite destination — a directory that
- * must already exist on disk before we create intermediate directories
- * under it.
- */
-function deriveSafeAncestor(destinationPath: string): string {
-  // iCloud Drive subtrees anchor on the iCloud root
-  const home = process.env.HOME || "";
-  if (home) {
-    const iCloudRoot = join(home, "Library", "Mobile Documents", "com~apple~CloudDocs");
-    if (
-      destinationPath === iCloudRoot ||
-      destinationPath.startsWith(`${iCloudRoot}/`)
-    ) {
-      return iCloudRoot;
-    }
-  }
-  // /Volumes/<name>/... paths anchor on the volume mount point
-  const volumesPrefix = "/Volumes/";
-  if (destinationPath.startsWith(volumesPrefix)) {
-    const rest = destinationPath.slice(volumesPrefix.length);
-    const slash = rest.indexOf("/");
-    const volumeName = slash === -1 ? rest : rest.slice(0, slash);
-    if (volumeName.length > 0) {
-      return `${volumesPrefix}${volumeName}`;
-    }
-  }
-  return dirname(destinationPath);
-}
-
-/**
- * Write a local snapshot to a single offsite destination.
- */
-export async function writeOffsiteSnapshotToOne(
-  localSnapshotPath: string,
-  destination: BackupDestination,
-  key: Buffer | null,
-  now: Date,
-): Promise<OffsiteWriteResult> {
-  try {
-    try {
-      await stat(deriveSafeAncestor(destination.path));
-    } catch (err) {
-      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
-        return { destination, entry: null, skipped: "parent-missing" };
-      }
-      throw err;
-    }
-
-    await mkdir(destination.path, { recursive: true, mode: 0o700 });
-
-    const filename = formatBackupFilename(now, {
-      encrypted: destination.encrypt,
-    });
-    const outputPath = join(destination.path, filename);
-
-    if (destination.encrypt) {
-      if (key == null) {
-        throw new Error(
-          "Offsite destination requires encryption but no key was provided",
-        );
-      }
-      await encryptFile(localSnapshotPath, outputPath, key);
-    } else {
-      const tempPath = `${outputPath}.tmp`;
-      await copyFile(localSnapshotPath, tempPath);
-      try {
-        await rename(tempPath, outputPath);
-      } catch (err) {
-        if ((err as NodeJS.ErrnoException).code === "EXDEV") {
-          await copyFile(tempPath, outputPath);
-          await unlink(tempPath);
-        } else {
-          throw err;
-        }
-      }
-    }
-
-    const stats = await stat(outputPath);
-    return {
-      destination,
-      entry: {
-        path: outputPath,
-        filename,
-        createdAt: now,
-        sizeBytes: stats.size,
-        encrypted: destination.encrypt,
-      },
-    };
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return { destination, entry: null, error: message };
-  }
-}
-
-/**
- * Write a local snapshot to every configured offsite destination.
- */
-export async function writeOffsiteSnapshotToAll(
-  localSnapshotPath: string,
-  destinations: BackupDestination[],
-  key: Buffer | null,
-  now: Date,
-): Promise<OffsiteWriteResult[]> {
-  if (destinations.length === 0) return [];
-
-  const results: OffsiteWriteResult[] = [];
-  for (const destination of destinations) {
-    const result = await writeOffsiteSnapshotToOne(
-      localSnapshotPath,
-      destination,
-      key,
-      now,
-    );
-    results.push(result);
-  }
-  return results;
-}
-
-/**
- * Apply retention to every configured offsite destination.
- */
-export async function pruneOffsiteSnapshotsInAll(
-  destinations: BackupDestination[],
-  retention: number,
-): Promise<
-  Array<{
-    destination: BackupDestination;
-    kept: SnapshotEntry[];
-    deleted: SnapshotEntry[];
-    skipped?: boolean;
-  }>
-> {
-  const results: Array<{
-    destination: BackupDestination;
-    kept: SnapshotEntry[];
-    deleted: SnapshotEntry[];
-    skipped?: boolean;
-  }> = [];
-  for (const destination of destinations) {
-    const { kept, deleted, skipped } = await pruneDir(
-      destination.path,
-      retention,
-    );
-    results.push({ destination, kept, deleted, skipped });
-  }
-  return results;
-}

package/src/backup/paths.ts

@@ -1,113 +0,0 @@
-/**
- * Path and filename helpers for the gateway backup module.
- *
- * The backup key lives in GATEWAY_SECURITY_DIR — outside the workspace
- * and outside the assistant sandbox boundary. The assistant process never
- * has access to this file.
- */
-
-import { join } from "node:path";
-
-import { getGatewaySecurityDir } from "../paths.js";
-
-// ---------------------------------------------------------------------------
-// Key path
-// ---------------------------------------------------------------------------
-
-/** Filename for the backup encryption key inside GATEWAY_SECURITY_DIR. */
-const BACKUP_KEY_FILENAME = "backup.key";
-
-/**
- * Returns the path to the backup encryption key file.
- *
- * The key lives in the gateway security directory, which is:
- * - In Docker: a dedicated volume at /gateway-security (GATEWAY_SECURITY_DIR)
- * - Locally: the XDG data home (`$XDG_DATA_HOME/cadet/gateway-security`)
- *
- * This keeps the key outside the workspace — the assistant's sandbox
- * boundary — so model-driven tools (file_read, shell) cannot access it.
- */
-export function getBackupKeyPath(): string {
-  return join(getGatewaySecurityDir(), BACKUP_KEY_FILENAME);
-}
-
-// ---------------------------------------------------------------------------
-// Backup root + local directory
-// ---------------------------------------------------------------------------
-
-/**
- * Returns the backup root directory. Respects the `CADET_BACKUP_DIR`
- * environment variable override (used in containerized deployments where
- * backups must be on a persistent volume); falls back to `<cwd>/backups`
- * (the spawner picks the cwd — the XDG data home for CLI-hatched instances).
- */
-export function getBackupRootDir(): string {
-  return process.env.CADET_BACKUP_DIR?.trim() || join(process.cwd(), "backups");
-}
-
-// ---------------------------------------------------------------------------
-// Backup filenames
-// ---------------------------------------------------------------------------
-
-/**
- * Formats a backup filename from a date. Encrypted backups get a `.vbundle.enc`
- * suffix; plaintext backups get `.vbundle`. Timestamp components are in UTC to
- * avoid timezone-induced filename collisions across devices. Milliseconds are
- * included so two backups started in the same UTC second produce distinct
- * filenames rather than silently overwriting each other.
- *
- * Example: `backup-20260411-153045-123.vbundle`
- */
-export function formatBackupFilename(
-  date: Date,
-  { encrypted }: { encrypted: boolean },
-): string {
-  const year = date.getUTCFullYear().toString().padStart(4, "0");
-  const month = (date.getUTCMonth() + 1).toString().padStart(2, "0");
-  const day = date.getUTCDate().toString().padStart(2, "0");
-  const hour = date.getUTCHours().toString().padStart(2, "0");
-  const minute = date.getUTCMinutes().toString().padStart(2, "0");
-  const second = date.getUTCSeconds().toString().padStart(2, "0");
-  const millis = date.getUTCMilliseconds().toString().padStart(3, "0");
-  const ext = encrypted ? ".vbundle.enc" : ".vbundle";
-  return `backup-${year}${month}${day}-${hour}${minute}${second}-${millis}${ext}`;
-}
-
-// Matches `backup-YYYYMMDD-HHMMSS` with an optional `-SSS` milliseconds
-// segment (legacy backups written before ms precision was added omit it) and
-// an optional `-<hex>` collision suffix that `writeLocalSnapshot` appends when
-// the canonical name is already taken. Followed by `.vbundle` or
-// `.vbundle.enc`. Kept as a module-level constant so repeated parsing doesn't
-// rebuild the RegExp.
-const BACKUP_FILENAME_RE =
-  /^backup-(\d{4})(\d{2})(\d{2})-(\d{2})(\d{2})(\d{2})(?:-(\d{3})(?:-[0-9a-f]+)?)?\.vbundle(?:\.enc)?$/;
-
-/**
- * Inverse of `formatBackupFilename`. Parses a backup filename (with either
- * `.vbundle` or `.vbundle.enc` suffix) and returns the encoded UTC timestamp.
- * Accepts legacy filenames without the `-SSS` milliseconds segment (treated
- * as `.000`). Returns `null` when the filename doesn't match the expected
- * pattern, when a component is out of range, or when the parsed date is
- * invalid.
- */
-export function parseBackupTimestamp(filename: string): Date | null {
-  const match = BACKUP_FILENAME_RE.exec(filename);
-  if (!match) return null;
-  const [, year, month, day, hour, minute, second, millis] = match;
-  const ms = millis ?? "000";
-  const iso = `${year}-${month}-${day}T${hour}:${minute}:${second}.${ms}Z`;
-  const date = new Date(iso);
-  if (Number.isNaN(date.getTime())) return null;
-  if (
-    date.getUTCFullYear() !== Number(year) ||
-    date.getUTCMonth() !== Number(month) - 1 ||
-    date.getUTCDate() !== Number(day) ||
-    date.getUTCHours() !== Number(hour) ||
-    date.getUTCMinutes() !== Number(minute) ||
-    date.getUTCSeconds() !== Number(second) ||
-    date.getUTCMilliseconds() !== Number(ms)
-  ) {
-    return null;
-  }
-  return date;
-}

package/src/backup/stream-crypt.ts

@@ -1,258 +0,0 @@
-/**
- * Streaming AES-256-GCM file encryption/decryption for backup bundles.
- *
- * The on-disk format is:
- *
- *   [12-byte IV][ciphertext...][16-byte GCM auth tag]
- *
- * Both encrypt and decrypt use Node streams so peak memory stays bounded
- * regardless of input size. This is important for backup archives which may
- * run to many gigabytes on larger workspaces.
- *
- * The key must be exactly 32 bytes (AES-256). The IV is randomly generated
- * per call, which is required for GCM semantic security — never reuse an
- * IV with the same key.
- */
-
-import {
-  createCipheriv,
-  createDecipheriv,
-  randomBytes,
-} from "node:crypto";
-import {
-  createReadStream,
-  createWriteStream,
-} from "node:fs";
-import { open, rename, stat, unlink } from "node:fs/promises";
-import { Readable, Writable } from "node:stream";
-import { pipeline } from "node:stream/promises";
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-/** Size of the AES-GCM initialization vector prefix, in bytes. */
-export const ENCRYPTED_HEADER_SIZE = 12;
-
-/** Size of the AES-GCM authentication tag suffix, in bytes. */
-export const GCM_TAG_SIZE = 16;
-
-const ALGORITHM = "aes-256-gcm";
-const KEY_LENGTH = 32;
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-function assertKey(key: Buffer): void {
-  if (key.length !== KEY_LENGTH) {
-    throw new Error("Backup encryption key must be 32 bytes");
-  }
-}
-
-async function safeUnlink(path: string): Promise<void> {
-  try {
-    await unlink(path);
-  } catch {
-    // best-effort cleanup — swallow ENOENT and other errors
-  }
-}
-
-function tempPath(outputPath: string): string {
-  return `${outputPath}.tmp.${process.pid}.${randomBytes(4).toString("hex")}`;
-}
-
-// ---------------------------------------------------------------------------
-// Encrypt
-// ---------------------------------------------------------------------------
-
-/**
- * Stream-encrypt `inputPath` to `outputPath` using AES-256-GCM.
- *
- * Produces `[IV (12 bytes)][ciphertext][auth tag (16 bytes)]` in the output.
- * Writes to a temp file and atomically renames on success; unlinks the temp
- * file on any error so failed writes don't leave partial bundles behind.
- */
-export async function encryptFile(
-  inputPath: string,
-  outputPath: string,
-  key: Buffer,
-): Promise<void> {
-  assertKey(key);
-
-  const iv = randomBytes(ENCRYPTED_HEADER_SIZE);
-  const cipher = createCipheriv(ALGORITHM, key, iv);
-
-  const tmp = tempPath(outputPath);
-  const writeStream = createWriteStream(tmp);
-
-  try {
-    // Write IV first so decrypt can read it without knowing the ciphertext size.
-    await new Promise<void>((resolve, reject) => {
-      writeStream.write(iv, (err) => (err ? reject(err) : resolve()));
-    });
-
-    // Stream plaintext through the cipher into the output.
-    const readStream = createReadStream(inputPath);
-    await pipeline(readStream, cipher, writeStream, { end: false });
-
-    // Append the auth tag after the ciphertext body.
-    const tag = cipher.getAuthTag();
-    await new Promise<void>((resolve, reject) => {
-      writeStream.write(tag, (err) => (err ? reject(err) : resolve()));
-    });
-
-    await new Promise<void>((resolve, reject) => {
-      writeStream.end((err?: Error | null) => (err ? reject(err) : resolve()));
-    });
-
-    await rename(tmp, outputPath);
-  } catch (err) {
-    // Make sure the write stream is closed before we try to unlink the temp file.
-    writeStream.destroy();
-    await safeUnlink(tmp);
-    throw err;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Decrypt
-// ---------------------------------------------------------------------------
-
-/**
- * Stream-decrypt `inputPath` to `outputPath`. Expects the on-disk format
- * produced by `encryptFile`: `[IV][ciphertext][auth tag]`.
- *
- * Reads the IV and auth tag via positional reads, then streams only the
- * ciphertext body through the decipher. Atomic tmp + rename semantics.
- */
-export async function decryptFile(
-  inputPath: string,
-  outputPath: string,
-  key: Buffer,
-): Promise<void> {
-  assertKey(key);
-
-  const info = await stat(inputPath);
-  const totalSize = info.size;
-  const minSize = ENCRYPTED_HEADER_SIZE + GCM_TAG_SIZE;
-  if (totalSize < minSize) {
-    throw new Error(
-      `Encrypted file is too small: ${totalSize} bytes (need at least ${minSize})`,
-    );
-  }
-
-  // Read IV (first 12 bytes) and auth tag (last 16 bytes) via positional reads.
-  const iv = Buffer.alloc(ENCRYPTED_HEADER_SIZE);
-  const tag = Buffer.alloc(GCM_TAG_SIZE);
-  const fh = await open(inputPath, "r");
-  try {
-    await fh.read(iv, 0, ENCRYPTED_HEADER_SIZE, 0);
-    await fh.read(tag, 0, GCM_TAG_SIZE, totalSize - GCM_TAG_SIZE);
-  } finally {
-    await fh.close();
-  }
-
-  const decipher = createDecipheriv(ALGORITHM, key, iv);
-  decipher.setAuthTag(tag);
-
-  const ciphertextStart = ENCRYPTED_HEADER_SIZE;
-  const ciphertextEnd = totalSize - GCM_TAG_SIZE - 1; // createReadStream end is inclusive
-  const hasCiphertext = ciphertextEnd >= ciphertextStart;
-
-  const tmp = tempPath(outputPath);
-  const writeStream = createWriteStream(tmp);
-
-  try {
-    const ciphertextStream = hasCiphertext
-      ? createReadStream(inputPath, {
-          start: ciphertextStart,
-          end: ciphertextEnd,
-        })
-      : Readable.from([]);
-
-    // pipeline consumes the ciphertext, pushes it through the decipher, and
-    // calls decipher.final() at the end — which is where auth tag verification
-    // happens. A bad tag surfaces here as a thrown error.
-    await pipeline(ciphertextStream, decipher, writeStream);
-
-    await rename(tmp, outputPath);
-  } catch (err) {
-    writeStream.destroy();
-    await safeUnlink(tmp);
-    throw err;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Verify
-// ---------------------------------------------------------------------------
-
-/**
- * Verify that `path` is a valid AES-256-GCM encrypted bundle for `key`.
- *
- * Streams the ciphertext through the decipher into a null sink and relies on
- * `decipher.final()` to either succeed (tag matches) or throw (tamper / wrong
- * key). No scratch file is written, so a full or read-only tmpdir cannot
- * cause a healthy backup to be reported as invalid.
- *
- * Returns `true` if the bundle authenticates, `false` on a cryptographic
- * failure (bad auth tag, wrong key, truncated/short input). Filesystem errors
- * on the *source* file (ENOENT, EACCES, EIO, …) are rethrown so callers can
- * distinguish tamper from transient I/O.
- */
-export async function verifyEncryptedFile(
-  path: string,
-  key: Buffer,
-): Promise<boolean> {
-  assertKey(key);
-
-  const info = await stat(path);
-  const totalSize = info.size;
-  const minSize = ENCRYPTED_HEADER_SIZE + GCM_TAG_SIZE;
-  if (totalSize < minSize) {
-    return false;
-  }
-
-  const iv = Buffer.alloc(ENCRYPTED_HEADER_SIZE);
-  const tag = Buffer.alloc(GCM_TAG_SIZE);
-  const fh = await open(path, "r");
-  try {
-    await fh.read(iv, 0, ENCRYPTED_HEADER_SIZE, 0);
-    await fh.read(tag, 0, GCM_TAG_SIZE, totalSize - GCM_TAG_SIZE);
-  } finally {
-    await fh.close();
-  }
-
-  const decipher = createDecipheriv(ALGORITHM, key, iv);
-  decipher.setAuthTag(tag);
-
-  const ciphertextStart = ENCRYPTED_HEADER_SIZE;
-  const ciphertextEnd = totalSize - GCM_TAG_SIZE - 1;
-  const hasCiphertext = ciphertextEnd >= ciphertextStart;
-  const ciphertextStream = hasCiphertext
-    ? createReadStream(path, { start: ciphertextStart, end: ciphertextEnd })
-    : Readable.from([]);
-
-  const nullSink = new Writable({
-    write(_chunk, _encoding, cb) {
-      cb();
-    },
-  });
-
-  try {
-    await pipeline(ciphertextStream, decipher, nullSink);
-    return true;
-  } catch (err) {
-    if (isFilesystemError(err)) {
-      throw err;
-    }
-    return false;
-  }
-}
-
-function isFilesystemError(err: unknown): boolean {
-  if (!err || typeof err !== "object") return false;
-  const code = (err as { code?: unknown }).code;
-  return typeof code === "string" && /^E[A-Z]+$/.test(code);
-}

package/src/device-id.ts

@@ -1,18 +0,0 @@
-let cached: string | null = null;
-
-/**
- * Read the device ID from the CADET_DEVICE_ID env var. The CLI always
- * injects it when spawning the gateway (local and containerized alike);
- * without it there is no device identity.
- */
-export function getDeviceId(): string | null {
-  if (cached !== null) return cached;
-
-  const envDeviceId = process.env.CADET_DEVICE_ID?.trim();
-  if (envDeviceId) {
-    cached = envDeviceId;
-    return cached;
-  }
-
-  return null;
-}