@mycadet/gateway 0.12.10 → 0.13.0

package/src/auth-fallback-count-tracker.ts

@@ -1,113 +0,0 @@
-// Accumulates counts of requests served via the legacy loopback auth fallback,
-// keyed by (guard, path, failureKind). The auth hot path calls `increment`
-// (an O(1) Map bump, no I/O); a background reporter periodically `drain`s the
-// accumulated counts and ships them to the daemon telemetry route. This is the
-// data complement to AuthFallbackLogThrottle's throttled log line: the log is a
-// sampled human signal, these counts are the exact volume.
-
-import { getLogger } from "./logger.js";
-
-const log = getLogger("auth-fallback-tracker");
-
-// Bounds memory if a caller floods distinct paths. Cardinality is normally
-// tiny (edge routes × failure kinds), so this only trips under abuse.
-const MAX_TRACKED_KEYS = 10_000;
-
-// Composite-key separator, mirroring AuthFallbackLogThrottle's `${guard} ${path}`
-// key. Safe because guard values are fixed slugs, URL pathnames percent-encode
-// spaces, and failureKind values are underscore tokens — none contain a space.
-const SEP = " ";
-
-/** One aggregated count for a single (guard, path, failureKind). */
-export interface AuthFallbackCount {
-  guard: string;
-  path: string;
-  failureKind: string;
-  count: number;
-}
-
-/** A drained window of counts, ready to ship. */
-export interface AuthFallbackBatch {
-  windowStart: number;
-  windowEnd: number;
-  counts: AuthFallbackCount[];
-}
-
-export class AuthFallbackCountTracker {
-  private counts = new Map<string, AuthFallbackCount>();
-  private windowStartedAt: number;
-  private warnedAtCap = false;
-
-  constructor(now: number = Date.now()) {
-    this.windowStartedAt = now;
-  }
-
-  /** Record one fallback. O(1), no I/O — safe on the auth hot path. */
-  increment(guard: string, path: string, failureKind: string): void {
-    this.add(guard, path, failureKind, 1);
-  }
-
-  /**
-   * Drain and reset the accumulated counts. Returns the window covered and the
-   * per-key counts. When nothing was tracked the window start is left anchored
-   * (an empty drain doesn't shift the accumulation window).
-   */
-  drain(now: number = Date.now()): AuthFallbackBatch {
-    const counts = [...this.counts.values()];
-    const windowStart = this.windowStartedAt;
-    if (counts.length === 0) {
-      return { windowStart, windowEnd: now, counts };
-    }
-    this.counts = new Map();
-    this.windowStartedAt = now;
-    this.warnedAtCap = false;
-    return { windowStart, windowEnd: now, counts };
-  }
-
-  /**
-   * Fold a previously-drained batch back in — used by the reporter to avoid
-   * losing a window when the daemon POST fails. Subject to the same key cap.
-   */
-  merge(counts: AuthFallbackCount[]): void {
-    for (const c of counts) {
-      this.add(c.guard, c.path, c.failureKind, c.count);
-    }
-  }
-
-  /** Read-only view of the current counts (for tests/inspection). */
-  snapshot(): AuthFallbackCount[] {
-    return [...this.counts.values()].map((c) => ({ ...c }));
-  }
-
-  /** Clear all state (for test isolation). */
-  reset(now: number = Date.now()): void {
-    this.counts = new Map();
-    this.windowStartedAt = now;
-    this.warnedAtCap = false;
-  }
-
-  private add(
-    guard: string,
-    path: string,
-    failureKind: string,
-    delta: number,
-  ): void {
-    const key = `${guard}${SEP}${path}${SEP}${failureKind}`;
-    const existing = this.counts.get(key);
-    if (existing) {
-      existing.count += delta;
-      return;
-    }
-    if (this.counts.size >= MAX_TRACKED_KEYS) {
-      if (!this.warnedAtCap) {
-        this.warnedAtCap = true;
-        log.warn(
-          { maxKeys: MAX_TRACKED_KEYS },
-          "Auth-fallback tracker at key cap — new (guard, path, failureKind) keys dropped until next flush",
-        );
-      }
-      return;
-    }
-    this.counts.set(key, { guard, path, failureKind, count: delta });
-  }
-}

package/src/auth-fallback-reporter.ts

@@ -1,127 +0,0 @@
-// Periodically drains AuthFallbackCountTracker and ships the accumulated counts
-// to the daemon's internal telemetry route, which persists them and forwards
-// them to the cloud. Best-effort background work: failures are logged and the
-// drained counts are merged back so a transient daemon blip doesn't lose a
-// window. Deliberately does NOT touch the runtime circuit breaker — this is
-// non-critical traffic and must never affect chat routing.
-
-import type {
-  AuthFallbackCount,
-  AuthFallbackCountTracker,
-} from "./auth-fallback-count-tracker.js";
-import type { fetchImpl } from "./fetch.js";
-import { postInternalTelemetry } from "./internal-telemetry-client.js";
-import { getLogger } from "./logger.js";
-
-const log = getLogger("auth-fallback-reporter");
-
-const ROUTE_PATH = "/v1/internal/telemetry/auth-fallback";
-const DEFAULT_FLUSH_INTERVAL_MS = 60_000;
-
-function getFlushIntervalMs(): number {
-  const raw = process.env.AUTH_FALLBACK_FLUSH_INTERVAL_MS;
-  if (raw) {
-    const parsed = parseInt(raw, 10);
-    if (!isNaN(parsed) && parsed > 0) return parsed;
-  }
-  return DEFAULT_FLUSH_INTERVAL_MS;
-}
-
-export type AuthFallbackReporterConfig = {
-  tracker: AuthFallbackCountTracker;
-  /** Daemon runtime base URL (`config.assistantRuntimeBaseUrl`). */
-  baseUrl: string;
-  /** Flush cadence; defaults to AUTH_FALLBACK_FLUSH_INTERVAL_MS or 60s. */
-  intervalMs?: number;
-  /** Injectable for tests. Defaults to the shared fetch wrapper. */
-  fetchImpl?: typeof fetchImpl;
-  /** Injectable for tests. Defaults to minting a real service token. */
-  mintToken?: () => string;
-};
-
-/** Shape the daemon route expects (`failure_kind` is snake_case on the wire). */
-type WireCount = {
-  guard: string;
-  path: string;
-  failure_kind: string;
-  count: number;
-};
-
-export class AuthFallbackReporter {
-  private readonly tracker: AuthFallbackCountTracker;
-  private readonly baseUrl: string;
-  private readonly intervalMs: number;
-  private readonly doFetch: typeof fetchImpl | undefined;
-  private readonly mintToken: (() => string) | undefined;
-  private timer: ReturnType<typeof setInterval> | null = null;
-
-  constructor(config: AuthFallbackReporterConfig) {
-    this.tracker = config.tracker;
-    this.baseUrl = config.baseUrl;
-    this.intervalMs = config.intervalMs ?? getFlushIntervalMs();
-    this.doFetch = config.fetchImpl;
-    this.mintToken = config.mintToken;
-  }
-
-  start(): void {
-    if (this.timer) return;
-    this.timer = setInterval(() => {
-      void this.flush();
-    }, this.intervalMs);
-    log.info({ intervalMs: this.intervalMs }, "Auth-fallback reporter started");
-  }
-
-  /** Stop the timer and flush whatever is buffered one last time. */
-  async stop(): Promise<void> {
-    if (this.timer) {
-      clearInterval(this.timer);
-      this.timer = null;
-    }
-    await this.flush();
-  }
-
-  /**
-   * Drain the tracker and POST the counts to the daemon. On any failure the
-   * drained counts are merged back so they retry on the next flush.
-   */
-  async flush(): Promise<void> {
-    const batch = this.tracker.drain();
-    if (batch.counts.length === 0) return;
-
-    const body = {
-      window_start: batch.windowStart,
-      window_end: batch.windowEnd,
-      counts: batch.counts.map(
-        (c: AuthFallbackCount): WireCount => ({
-          guard: c.guard,
-          path: c.path,
-          failure_kind: c.failureKind,
-          count: c.count,
-        }),
-      ),
-    };
-
-    try {
-      const resp = await postInternalTelemetry({
-        baseUrl: this.baseUrl,
-        path: ROUTE_PATH,
-        body,
-        fetchImpl: this.doFetch,
-        mintToken: this.mintToken,
-      });
-      if (!resp.ok) {
-        log.warn(
-          { status: resp.status, keys: batch.counts.length },
-          "Auth-fallback flush rejected — re-queueing counts for next flush",
-        );
-        this.tracker.merge(batch.counts);
-      }
-    } catch (err) {
-      log.warn(
-        { err, keys: batch.counts.length },
-        "Auth-fallback flush failed — re-queueing counts for next flush",
-      );
-      this.tracker.merge(batch.counts);
-    }
-  }
-}

package/src/backup/backup-key.ts

@@ -1,138 +0,0 @@
-/**
- * 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

@@ -1,161 +0,0 @@
-/**
- * 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 { join } from "node:path";
-
-import { readConfigFileOrEmpty } from "../config-file-utils.js";
-import { getLogger } from "../logger.js";
-import { listSnapshotsInDir, type SnapshotEntry } from "./list-snapshots.js";
-import { getBackupRootDir } 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 = localDirectory ?? join(getBackupRootDir(), "local");
-
-  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 },
-      );
-    }
-  };
-}