feat(auth): snapshot before destructive actions

Author: ndycode

lib/destructive-actions.ts

@@ -10,6 +10,7 @@ import {
 	loadFlaggedAccounts,
 	saveAccounts,
 	saveFlaggedAccounts,
+	snapshotAccountStorage,
 } from "./storage.js";
 
 export const DESTRUCTIVE_ACTION_COPY = {
@@ -111,6 +112,7 @@ export async function deleteAccountAtIndex(options: {
 	const target = options.storage.accounts.at(options.index);
 	if (!target) return null;
 	const flagged = await loadFlaggedAccounts();
+	await snapshotAccountStorage({ reason: "delete-account" });
 	const nextStorage: AccountStorageV3 = {
 		...options.storage,
 		accounts: options.storage.accounts.map((account) => ({ ...account })),
@@ -172,6 +174,7 @@ export async function deleteAccountAtIndex(options: {
  * Removes the accounts WAL and backups via the underlying storage helper.
  */
 export async function deleteSavedAccounts(): Promise<DestructiveActionResult> {
+	await snapshotAccountStorage({ reason: "delete-saved-accounts" });
 	return {
 		accountsCleared: await clearAccounts(),
 		flaggedCleared: false,
@@ -184,6 +187,7 @@ export async function deleteSavedAccounts(): Promise<DestructiveActionResult> {
  * Keeps unified settings and on-disk Codex CLI sync state; only the in-memory Codex CLI cache is cleared.
  */
 export async function resetLocalState(): Promise<DestructiveActionResult> {
+	await snapshotAccountStorage({ reason: "reset-local-state" });
 	const accountsCleared = await clearAccounts();
 	const flaggedCleared = await clearFlaggedAccounts();
 	const quotaCacheCleared = await clearQuotaCache();

lib/storage.ts

@@ -205,6 +205,22 @@ export interface ActionableNamedBackupRecoveries {
 	totalBackups: number;
 }
 
+export type AccountSnapshotReason =
+	| "delete-account"
+	| "delete-saved-accounts"
+	| "reset-local-state"
+	| "import-accounts";
+
+export type AccountSnapshotFailurePolicy = "warn" | "error";
+
+export interface AccountSnapshotOptions {
+	reason: AccountSnapshotReason;
+	now?: number;
+	force?: boolean;
+	failurePolicy?: AccountSnapshotFailurePolicy;
+	createBackup?: typeof createNamedBackup;
+}
+
 interface LoadedBackupCandidate {
 	normalized: AccountStorageV3 | null;
 	storedVersion: unknown;
@@ -2155,6 +2171,83 @@ export async function createNamedBackup(
 	);
 }
 
+function formatTimestampForSnapshot(timestamp: number): string {
+	const date = new Date(timestamp);
+	const pad = (value: number): string => value.toString().padStart(2, "0");
+	const milliseconds = date.getUTCMilliseconds().toString().padStart(3, "0");
+	const year = date.getUTCFullYear();
+	const month = pad(date.getUTCMonth() + 1);
+	const day = pad(date.getUTCDate());
+	const hours = pad(date.getUTCHours());
+	const minutes = pad(date.getUTCMinutes());
+	const seconds = pad(date.getUTCSeconds());
+	return `${year}-${month}-${day}_${hours}-${minutes}-${seconds}_${milliseconds}`;
+}
+
+function buildAccountSnapshotName(
+	reason: AccountSnapshotReason,
+	timestamp: number,
+): string {
+	return `accounts-${reason}-snapshot-${formatTimestampForSnapshot(timestamp)}`;
+}
+
+function extractPathTail(pathValue: string): string {
+	const segments = pathValue.split(/[\\/]+/).filter(Boolean);
+	return segments.at(-1) ?? pathValue;
+}
+
+function redactFilesystemDetails(value: string): string {
+	return value.replace(
+		/(?:[A-Za-z]:)?[\\/][^"'`\r\n]+(?:[\\/][^"'`\r\n]+)+/g,
+		(pathValue) => extractPathTail(pathValue),
+	);
+}
+
+function formatSnapshotErrorForLog(error: unknown): string {
+	const code =
+		typeof (error as NodeJS.ErrnoException | undefined)?.code === "string"
+			? (error as NodeJS.ErrnoException).code
+			: undefined;
+	const rawMessage =
+		error instanceof Error ? error.message : String(error ?? "unknown error");
+	const redactedMessage = redactFilesystemDetails(rawMessage);
+	if (code && !redactedMessage.includes(code)) {
+		return `${code}: ${redactedMessage}`;
+	}
+	return redactedMessage;
+}
+
+export async function snapshotAccountStorage(
+	options: AccountSnapshotOptions,
+): Promise<NamedBackupMetadata | null> {
+	const {
+		reason,
+		now = Date.now(),
+		force = true,
+		failurePolicy = "warn",
+		createBackup = createNamedBackup,
+	} = options;
+	const currentStorage = await loadAccounts();
+	if (!currentStorage || currentStorage.accounts.length === 0) {
+		return null;
+	}
+
+	const backupName = buildAccountSnapshotName(reason, now);
+	try {
+		return await createBackup(backupName, { force });
+	} catch (error) {
+		if (failurePolicy === "error") {
+			throw error;
+		}
+		log.warn("Failed to create account storage snapshot", {
+			reason,
+			backupName,
+			error: formatSnapshotErrorForLog(error),
+		});
+		return null;
+	}
+}
+
 export async function assessNamedBackupRestore(
 	name: string,
 	options: { currentStorage?: AccountStorageV3 | null } = {},
@@ -3538,6 +3631,10 @@ export async function importAccounts(
 		throw new Error("Invalid account storage format");
 	}
 
+	// Capture the current pool before merge/limit checks so failed imports still
+	// leave a rollback-ready checkpoint for the pre-import state.
+	await snapshotAccountStorage({ reason: "import-accounts" });
+
 	const {
 		imported: importedCount,
 		total,

test/destructive-actions.test.ts

@@ -7,6 +7,7 @@ const clearCodexCliStateCacheMock = vi.fn();
 const loadFlaggedAccountsMock = vi.fn();
 const saveAccountsMock = vi.fn();
 const saveFlaggedAccountsMock = vi.fn();
+const snapshotAccountStorageMock = vi.fn();
 
 vi.mock("../lib/codex-cli/state.js", () => ({
 	clearCodexCliStateCache: clearCodexCliStateCacheMock,
@@ -26,6 +27,7 @@ vi.mock("../lib/storage.js", () => ({
 	loadFlaggedAccounts: loadFlaggedAccountsMock,
 	saveAccounts: saveAccountsMock,
 	saveFlaggedAccounts: saveFlaggedAccountsMock,
+	snapshotAccountStorage: snapshotAccountStorageMock,
 }));
 
 describe("destructive actions", () => {
@@ -38,6 +40,7 @@ describe("destructive actions", () => {
 		loadFlaggedAccountsMock.mockResolvedValue({ version: 1, accounts: [] });
 		saveAccountsMock.mockResolvedValue(undefined);
 		saveFlaggedAccountsMock.mockResolvedValue(undefined);
+		snapshotAccountStorageMock.mockResolvedValue(null);
 	});
 
 	it("returns delete-only results without pretending kept data was cleared", async () => {
@@ -50,7 +53,15 @@ describe("destructive actions", () => {
 			flaggedCleared: false,
 			quotaCacheCleared: false,
 		});
+		expect(snapshotAccountStorageMock).toHaveBeenCalledWith({
+			reason: "delete-saved-accounts",
+		});
 		expect(clearAccountsMock).toHaveBeenCalledTimes(1);
+		expect(
+			snapshotAccountStorageMock.mock.invocationCallOrder[0],
+		).toBeLessThan(
+			clearAccountsMock.mock.invocationCallOrder[0] ?? Number.POSITIVE_INFINITY,
+		);
 		expect(clearFlaggedAccountsMock).not.toHaveBeenCalled();
 		expect(clearQuotaCacheMock).not.toHaveBeenCalled();
 		expect(clearCodexCliStateCacheMock).not.toHaveBeenCalled();
@@ -68,7 +79,15 @@ describe("destructive actions", () => {
 			flaggedCleared: false,
 			quotaCacheCleared: true,
 		});
+		expect(snapshotAccountStorageMock).toHaveBeenCalledWith({
+			reason: "reset-local-state",
+		});
 		expect(clearAccountsMock).toHaveBeenCalledTimes(1);
+		expect(
+			snapshotAccountStorageMock.mock.invocationCallOrder[0],
+		).toBeLessThan(
+			clearAccountsMock.mock.invocationCallOrder[0] ?? Number.POSITIVE_INFINITY,
+		);
 		expect(clearFlaggedAccountsMock).toHaveBeenCalledTimes(1);
 		expect(clearQuotaCacheMock).toHaveBeenCalledTimes(1);
 		expect(clearCodexCliStateCacheMock).toHaveBeenCalledTimes(1);
@@ -120,6 +139,14 @@ describe("destructive actions", () => {
 		const deleted = await deleteAccountAtIndex({ storage, index: 0 });
 
 		expect(deleted).not.toBeNull();
+		expect(snapshotAccountStorageMock).toHaveBeenCalledWith({
+			reason: "delete-account",
+		});
+		expect(
+			snapshotAccountStorageMock.mock.invocationCallOrder[0],
+		).toBeLessThan(
+			saveAccountsMock.mock.invocationCallOrder[0] ?? Number.POSITIVE_INFINITY,
+		);
 		expect(deleted?.storage.accounts.map((account) => account.refreshToken)).toEqual([
 			"refresh-active",
 			"refresh-other",