@hienlh/ppm 0.18.13 → 0.18.15

package/src/services/db-backup/db-backup-restore.ts

@@ -0,0 +1,105 @@
+import { copyFileSync, existsSync, renameSync, rmSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { formatBackupStamp } from "./db-backup-paths.ts";
+import { verifyBackupFile } from "./db-backup-sync.ts";
+import { readStatus } from "../supervisor-state.ts";
+
+/**
+ * Restore a verified snapshot over the live database.
+ *
+ * Three properties this must not get wrong:
+ *
+ * 1. **Verify before overwriting.** The snapshot is integrity-checked first,
+ *    so a rotted backup can never destroy a database that still had a chance.
+ * 2. **Never destroy the file being replaced.** The current database is moved
+ *    aside, not deleted — even a corrupt file is forensic evidence, and during
+ *    the incident that motivated this module the only reason the cause could be
+ *    established was that the broken file had been preserved.
+ * 3. **Delete the stale write-ahead log.** A `-wal`/`-shm` pair left beside a
+ *    freshly restored database gets replayed onto it on the next open, which
+ *    silently reintroduces the very corruption being recovered from. This is
+ *    the single easiest way to turn a good restore into a second outage.
+ */
+
+export interface RestoreResult {
+  restoredFrom: string;
+  dbPath: string;
+  archivedTo: string | null;
+  bytes: number;
+}
+
+/** Sidecar files SQLite keeps beside a database; they must not survive a swap. */
+function sidecars(dbPath: string): string[] {
+  return [`${dbPath}-wal`, `${dbPath}-shm`];
+}
+
+/**
+ * PID of a live supervisor from `status.json`, or null. Restoring under a
+ * running server would have it writing into a file that is being replaced.
+ */
+export function liveSupervisorPid(): number | null {
+  try {
+    const pid = readStatus().supervisorPid;
+    if (typeof pid !== "number" || pid <= 0) return null;
+    process.kill(pid, 0); // throws when the PID is gone
+    return pid;
+  } catch {
+    return null;
+  }
+}
+
+export function restoreDb(
+  backupPath: string,
+  opts: { dbPath: string; force?: boolean; now?: Date },
+): RestoreResult {
+  const { dbPath } = opts;
+  if (!existsSync(backupPath)) throw new Error(`Backup not found: ${backupPath}`);
+
+  const check = verifyBackupFile(backupPath);
+  if (!check.ok) {
+    throw new Error(`Refusing to restore: backup failed integrity_check (${check.detail})`);
+  }
+
+  if (!opts.force) {
+    const pid = liveSupervisorPid();
+    if (pid !== null) {
+      throw new Error(
+        `PPM is running (supervisor PID ${pid}). Run \`ppm stop\` first, or pass --force to restore anyway.`,
+      );
+    }
+  }
+
+  const stamp = formatBackupStamp(opts.now ?? new Date());
+  let archivedTo: string | null = null;
+  if (existsSync(dbPath)) {
+    archivedTo = `${dbPath}.replaced-${stamp}`;
+    renameSync(dbPath, archivedTo);
+    // Move the sidecars alongside the file they belong to, so the archived
+    // database stays inspectable and cannot be replayed onto the new one.
+    for (const side of sidecars(dbPath)) {
+      if (existsSync(side)) {
+        try { renameSync(side, `${side.replace(dbPath, archivedTo)}`); } catch { rmSync(side, { force: true }); }
+      }
+    }
+  }
+  for (const side of sidecars(dbPath)) rmSync(side, { force: true });
+
+  copyFileSync(backupPath, dbPath);
+
+  const after = verifyBackupFile(dbPath);
+  if (!after.ok) {
+    throw new Error(
+      `Restored file failed integrity_check (${after.detail}). Previous database preserved at ${archivedTo ?? "(none)"}.`,
+    );
+  }
+
+  return { restoredFrom: backupPath, dbPath, archivedTo, bytes: statSync(dbPath).size };
+}
+
+/** Resolve a user-supplied backup argument: absolute/relative path, or a bare snapshot filename. */
+export function resolveBackupArg(arg: string, backupsDir: string): string {
+  if (existsSync(arg)) return resolve(arg);
+  const inDir = resolve(backupsDir, arg);
+  if (existsSync(inDir)) return inDir;
+  throw new Error(`Backup not found: ${arg}`);
+}

package/src/services/db-backup/db-backup-retention.ts

@@ -0,0 +1,96 @@
+import { parseBackupName, type ParsedBackupName } from "./db-backup-paths.ts";
+
+/**
+ * Grandfather-father-son retention. Three tiers, unioned:
+ *
+ * - `recent`: the N newest snapshots regardless of age — the "what did I break
+ *   in the last few hours" tier.
+ * - `daily`: newest snapshot of each of the last N distinct calendar days (UTC).
+ * - `weekly`: newest snapshot of each of the last N distinct ISO weeks.
+ *
+ * The daily/weekly depth is what catches slow, silent damage — the failure
+ * mode that actually happened here: a database corrupted at 23:08 and not
+ * noticed until the next morning's restart. A recent-only window would have
+ * already rotated the last good copy away.
+ */
+export interface RetentionPolicy {
+  recent: number;
+  daily: number;
+  weekly: number;
+}
+
+export const DEFAULT_RETENTION: RetentionPolicy = { recent: 6, daily: 7, weekly: 4 };
+
+/** UTC calendar day key, e.g. `2026-09-06`. */
+function dayKey(d: Date): string {
+  return d.toISOString().slice(0, 10);
+}
+
+/**
+ * ISO-week key, e.g. `2026-W37`. Uses the ISO rule (week belongs to the year
+ * containing its Thursday) so the last days of December group correctly
+ * instead of splitting a week across two year buckets.
+ */
+function weekKey(d: Date): string {
+  const t = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
+  const dayNum = t.getUTCDay() || 7; // Mon=1..Sun=7
+  t.setUTCDate(t.getUTCDate() + 4 - dayNum); // shift to that week's Thursday
+  const yearStart = new Date(Date.UTC(t.getUTCFullYear(), 0, 1));
+  const week = Math.ceil(((t.getTime() - yearStart.getTime()) / 86_400_000 + 1) / 7);
+  return `${t.getUTCFullYear()}-W${String(week).padStart(2, "0")}`;
+}
+
+/** Newest-first, keeping only names this module wrote for the given database stem. */
+function parseAndSort(names: string[], dbStem: string): Array<ParsedBackupName & { name: string }> {
+  return names
+    .map((name) => {
+      const parsed = parseBackupName(name);
+      return parsed && parsed.dbStem === dbStem ? { ...parsed, name } : null;
+    })
+    .filter((x): x is ParsedBackupName & { name: string } => x !== null)
+    .sort((a, b) => b.date.getTime() - a.date.getTime());
+}
+
+/** The snapshots the policy keeps, newest-first. */
+export function selectBackupsToKeep(
+  names: string[],
+  dbStem: string,
+  policy: RetentionPolicy = DEFAULT_RETENTION,
+): string[] {
+  const sorted = parseAndSort(names, dbStem);
+  const keep = new Set<string>();
+
+  for (const entry of sorted.slice(0, policy.recent)) keep.add(entry.name);
+
+  // Snapshots are newest-first, so the first one seen for a bucket is that
+  // bucket's newest — take it and skip the rest of the bucket.
+  const takeNewestPerBucket = (key: (d: Date) => string, limit: number) => {
+    const seen = new Set<string>();
+    for (const entry of sorted) {
+      if (seen.size >= limit && !seen.has(key(entry.date))) continue;
+      if (seen.has(key(entry.date))) continue;
+      seen.add(key(entry.date));
+      keep.add(entry.name);
+    }
+  };
+  takeNewestPerBucket(dayKey, policy.daily);
+  takeNewestPerBucket(weekKey, policy.weekly);
+
+  return sorted.filter((e) => keep.has(e.name)).map((e) => e.name);
+}
+
+/**
+ * The snapshots the policy discards. Anything unparseable is left strictly
+ * alone: this function only ever proposes deleting files it can prove it
+ * wrote itself.
+ */
+export function selectBackupsToDelete(
+  names: string[],
+  dbStem: string,
+  policy: RetentionPolicy = DEFAULT_RETENTION,
+): string[] {
+  const keep = new Set(selectBackupsToKeep(names, dbStem, policy));
+  return parseAndSort(names, dbStem)
+    .filter((e) => !keep.has(e.name))
+    .map((e) => e.name);
+}

package/src/services/db-backup/db-backup-sync.ts

@@ -0,0 +1,113 @@
+import { Database } from "bun:sqlite";
+import { existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { getBackupsDir, backupFileName, type BackupReason } from "./db-backup-paths.ts";
+import { selectBackupsToDelete, DEFAULT_RETENTION, type RetentionPolicy } from "./db-backup-retention.ts";
+
+/**
+ * Synchronous core of the snapshot mechanism.
+ *
+ * Split from `db-backup.service.ts` for one structural reason: `db.service`
+ * takes a snapshot before running migrations, from inside the synchronous
+ * `getDb()` path, so that call cannot await. Keeping this core free of any
+ * import of `db.service` also means the caller passes the database path in,
+ * which removes what would otherwise be an import cycle.
+ *
+ * VACUUM INTO is SQLite's own online-backup statement: a transactionally
+ * consistent, compacted copy taken while the server keeps reading and writing.
+ * A plain file copy is NOT equivalent — it can catch the main database and its
+ * write-ahead log out of step and produce exactly the unopenable file this
+ * mechanism exists to recover from.
+ */
+
+export interface BackupResult {
+  path: string;
+  bytes: number;
+  ms: number;
+  pruned: string[];
+}
+
+export interface BackupOptions {
+  /** Reuse an already-open connection — required when snapshotting state that same handle is about to migrate. */
+  sourceDb?: Database;
+  /** Source database file. */
+  dbPath: string;
+  retention?: RetentionPolicy;
+  now?: Date;
+}
+
+function ensureBackupsDir(dir: string): void {
+  // Only mkdir when actually missing: recursive mkdir throws EEXIST against
+  // some Windows folders carrying the ReadOnly attribute.
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+/**
+ * Open a snapshot and run a full integrity_check.
+ *
+ * Called right after writing a snapshot and again before restoring one. An
+ * unverified backup is not a backup: during the incident that motivated this
+ * module, two copies that looked present (a VSS shadow, a WAL rebuild) both
+ * turned out to be unusable only at the moment they were needed.
+ */
+export function verifyBackupFile(path: string): { ok: boolean; detail: string } {
+  let db: Database | null = null;
+  try {
+    db = new Database(path, { readonly: true });
+    const row = db.query("PRAGMA integrity_check").get() as { integrity_check?: string } | null;
+    const detail = row?.integrity_check ?? "no result";
+    return { ok: detail === "ok", detail };
+  } catch (e: any) {
+    return { ok: false, detail: e?.message ?? String(e) };
+  } finally {
+    try { db?.close(); } catch { /* already closed */ }
+  }
+}
+
+/** Write one verified snapshot, then apply retention. Throws if the snapshot cannot be verified. */
+export function backupDbSync(reason: BackupReason, opts: BackupOptions): BackupResult {
+  const { dbPath } = opts;
+  if (!existsSync(dbPath)) throw new Error(`No database to back up at ${dbPath}`);
+
+  const dir = getBackupsDir();
+  ensureBackupsDir(dir);
+
+  const dbFile = basename(dbPath);
+  const finalPath = resolve(dir, backupFileName(dbFile, opts.now ?? new Date(), reason));
+  // Snapshot under a .partial name so an interrupted run leaves nothing
+  // parseBackupName would ever offer as a restore candidate.
+  const partialPath = `${finalPath}.partial`;
+  rmSync(partialPath, { force: true });
+
+  const started = Date.now();
+  // Read-write (not readonly) on purpose: a readonly connection cannot recover
+  // a hot write-ahead log when it is the only connection, which is exactly the
+  // case for a manual backup while the server is stopped. VACUUM INTO never
+  // modifies the source either way.
+  const source = opts.sourceDb ?? new Database(dbPath);
+  try {
+    // The path is ours, but a home directory can legitimately contain an apostrophe.
+    source.exec(`VACUUM INTO '${partialPath.replace(/'/g, "''")}'`);
+  } finally {
+    if (!opts.sourceDb) source.close();
+  }
+
+  const check = verifyBackupFile(partialPath);
+  if (!check.ok) {
+    rmSync(partialPath, { force: true });
+    throw new Error(`Snapshot failed integrity_check (${check.detail}) — discarded, no backup written`);
+  }
+
+  renameSync(partialPath, finalPath);
+  const ms = Date.now() - started;
+
+  const pruned: string[] = [];
+  const stem = dbFile.replace(/\.db$/, "");
+  for (const name of selectBackupsToDelete(readdirSync(dir), stem, opts.retention ?? DEFAULT_RETENTION)) {
+    // A locked or vanished snapshot is a pruning hiccup, not a backup failure —
+    // the new snapshot is already written and verified by this point.
+    try { rmSync(resolve(dir, name), { force: true }); pruned.push(name); } catch { /* keep going */ }
+  }
+
+  return { path: finalPath, bytes: statSync(finalPath).size, ms, pruned };
+}

package/src/services/db-backup/db-backup.service.ts

@@ -0,0 +1,61 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { getBackupsDir, parseBackupName, type BackupReason } from "./db-backup-paths.ts";
+import { backupDbSync, type BackupOptions, type BackupResult } from "./db-backup-sync.ts";
+
+/**
+ * Async-friendly facade over the synchronous snapshot core, for callers that
+ * do not already hold the database open: the supervisor's hourly tick, the
+ * start-up snapshot, and the `ppm backup` command. It resolves the active
+ * database path lazily, so importing this module never opens a database.
+ */
+
+export type { BackupResult, BackupOptions };
+export { verifyBackupFile } from "./db-backup-sync.ts";
+
+export interface BackupEntry {
+  name: string;
+  path: string;
+  bytes: number;
+  date: Date;
+  reason: BackupReason;
+}
+
+/** Snapshot files present for a database stem (`ppm`, `ppm.dev`), newest-first. */
+export function listBackups(dbStem?: string): BackupEntry[] {
+  const dir = getBackupsDir();
+  if (!existsSync(dir)) return [];
+  const out: BackupEntry[] = [];
+  for (const name of readdirSync(dir)) {
+    const parsed = parseBackupName(name);
+    if (!parsed) continue;
+    if (dbStem && parsed.dbStem !== dbStem) continue;
+    const path = resolve(dir, name);
+    let bytes = 0;
+    // A file that vanished between readdir and stat is simply not a candidate.
+    try { bytes = statSync(path).size; } catch { continue; }
+    out.push({ name, path, bytes, date: parsed.date, reason: parsed.reason });
+  }
+  return out.sort((a, b) => b.date.getTime() - a.date.getTime());
+}
+
+/** Basename-derived stem of the active database, e.g. `ppm` or `ppm.dev`. */
+export async function activeDbStem(): Promise<string> {
+  const { getDbPath } = await import("../db.service.ts");
+  return basename(getDbPath()).replace(/\.db$/, "");
+}
+
+/** Age of the newest snapshot for the active database in ms, or null when there is none. */
+export async function newestBackupAgeMs(now: Date = new Date()): Promise<number | null> {
+  const newest = listBackups(await activeDbStem())[0];
+  return newest ? now.getTime() - newest.date.getTime() : null;
+}
+
+/** Take one verified snapshot of the active database. */
+export async function backupDb(
+  reason: BackupReason,
+  opts: Partial<Omit<BackupOptions, "dbPath">> & { dbPath?: string } = {},
+): Promise<BackupResult> {
+  const { getDbPath } = await import("../db.service.ts");
+  return backupDbSync(reason, { ...opts, dbPath: opts.dbPath ?? getDbPath() });
+}

package/src/services/db.service.ts

@@ -3,6 +3,7 @@ import { resolve } from "node:path";
 import { mkdirSync, existsSync } from "node:fs";
 import { encrypt, decrypt } from "../lib/account-crypto.ts";
 import { getPpmDir } from "./ppm-dir.ts";
+import { backupDbSync } from "./db-backup/db-backup-sync.ts";
 export const CURRENT_SCHEMA_VERSION = 42;
 
 let db: Database | null = null;
@@ -14,7 +15,8 @@ export function setDbProfile(profile: string | null): void {
   dbProfile = profile;
 }
 
-function getDbPath(): string {
+/** Absolute path of the active database file, honouring the dev profile. */
+export function getDbPath(): string {
   if (dbProfile) return resolve(getPpmDir(), `ppm.${dbProfile}.db`);
   return resolve(getPpmDir(), "ppm.db");
 }
@@ -27,10 +29,36 @@ export function getDb(): Database {
   db = new Database(getDbPath());
   db.exec("PRAGMA journal_mode = WAL");
   db.exec("PRAGMA foreign_keys = ON");
+  backupBeforeMigrations(db);
   runMigrations(db);
   return db;
 }
 
+/**
+ * Snapshot the database before a schema migration rewrites it.
+ *
+ * Migrations are the riskiest write PPM makes to its own store: they run
+ * automatically on every open, and a crash partway through — or an older
+ * binary opening a newer schema — leaves a file no later version can read.
+ * The hourly snapshot is not enough on its own, because a migration can land
+ * within the same hour as the last one.
+ *
+ * Deliberately synchronous and best-effort: a failure to snapshot must never
+ * stop the server from booting, and must never mask the migration error that
+ * follows it.
+ */
+function backupBeforeMigrations(database: Database): void {
+  const row = database.query("PRAGMA user_version").get() as { user_version: number };
+  if (row.user_version >= CURRENT_SCHEMA_VERSION) return;
+  if (row.user_version === 0) return; // brand-new database — nothing to lose yet
+  try {
+    const result = backupDbSync("premigrate", { sourceDb: database, dbPath: getDbPath() });
+    console.log(`[db] Pre-migration snapshot: ${result.path} (${(result.bytes / 1_048_576).toFixed(1)} MB)`);
+  } catch (e: any) {
+    console.error(`[db] Pre-migration snapshot FAILED (continuing): ${e?.message ?? e}`);
+  }
+}
+
 /** Close the DB (for graceful shutdown or tests) */
 export function closeDb(): void {
   if (db) { db.close(); db = null; }

package/src/services/fs-credential-path-guard.ts

@@ -2,6 +2,7 @@ import { resolve, sep } from "node:path";
 import { homedir } from "node:os";
 import { getPpmDir } from "./ppm-dir.ts";
 import { getUploadsDir } from "./chat-upload-storage.service.ts";
+import { getBackupsDir } from "./db-backup/db-backup-paths.ts";
 import { realPathOrSelf } from "./fs-ops/fs-real-path.ts";
 
 /**
@@ -11,6 +12,9 @@ import { realPathOrSelf } from "./fs-ops/fs-real-path.ts";
  * cert). Split out of `fs-path-guard.service.ts` so this one seam — "is this
  * a credential path" — stays a single file instead of growing alongside the
  * platform-allowlist and protected-root logic that lives there.
+ *
+ * Three roots, not two: the PPM config DB, `~/.cloudflared`, and the database
+ * snapshot directory, which holds full copies of the first one.
  */
 
 /** Case-insensitive prefix test on Windows/macOS-style paths. */
@@ -50,9 +54,23 @@ export function isCloudflaredDirPath(resolved: string): boolean {
   return isInside(resolved, resolve(homedir(), ".cloudflared"));
 }
 
+/**
+ * True when the path is the database-snapshot directory or anything inside it.
+ *
+ * A snapshot is a byte-for-byte copy of the config database, so it carries the
+ * same provider keys, encrypted accounts, and auth token. In production that
+ * directory deliberately sits OUTSIDE `~/.ppm` (so it survives a wipe of the
+ * PPM directory), which means `isPpmDirPath` does not cover it — without this
+ * branch, moving snapshots out of the PPM directory would have quietly opened
+ * a credential-read hole through the generic file routes.
+ */
+export function isDbBackupsDirPath(resolved: string): boolean {
+  return isInside(resolved, getBackupsDir());
+}
+
 /** True when the path holds credential material a generic file route must never serve or relocate. */
 export function isCredentialPath(resolved: string): boolean {
-  return isPpmDirPath(resolved) || isCloudflaredDirPath(resolved);
+  return isPpmDirPath(resolved) || isCloudflaredDirPath(resolved) || isDbBackupsDirPath(resolved);
 }
 
 /**

package/src/services/named-tunnel/cloudflared-login.service.ts

@@ -98,7 +98,7 @@ export async function startLogin(opts: { relogin?: boolean } = {}): Promise<Logi
       // itself failed to run, so cert.pem is left untouched and the user
       // gets a clear, retryable error instead of an unwanted fresh login.
       if (liveCheck === "unreachable") {
-        setTerminal("error", "không kết nối được Cloudflare để kiểm tra đăng nhập — thử lại");
+        setTerminal("error", "could not reach Cloudflare to check the sign-in — try again");
         return getLoginSnapshot();
       }
 
@@ -117,7 +117,7 @@ export async function startLogin(opts: { relogin?: boolean } = {}): Promise<Logi
       renameCertAside();
     }
   } else {
-    // Explicit ?relogin=1 — the user deliberately pressed "Đăng nhập lại",
+    // Explicit ?relogin=1 — the user deliberately pressed "Sign in again",
     // so this renames unconditionally regardless of network reachability.
     renameCertAside();
   }