Files
Netcatty/electron/bridges/vaultBackupBridge.cjs
T
陈大猫andClaude Sonnet 4.6 54b26511a1 Cloud sync data-loss prevention (4-layer defense) (#742)
* feat(sync-guard): extend SyncState with BLOCKED + add shrink event variants

* feat(sync-guard): add detectSuspiciousShrink pure function with 12 unit tests

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* polish(sync-guard): drop unnecessary cast, sharpen test naming, pin priority invariant

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(test): include domain/*.test.ts in npm test glob

* feat(sync-guard): gate syncToProvider with shrink detection + force-push override

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(sync-guard): reset overrideShrinkOnce before early return for invariant strictness

* fix(sync-guard): extend shrink guard to syncAllProviders (the actual sync entry point)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(sync-guard): apply empty-vault guard uniformly to auto and manual sync

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(sync-guard): preserve merge base on same-account re-auth

Adds providerAccountId persistence; completePKCEAuth and completeGitHubAuth
now only clear syncBase/anchor when the authenticated account id differs from
the previously stored one, preventing zombie-entry resurrection on token
refresh. disconnectProvider clears the stored id so a reconnect starts fresh.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(sync-guard): add i18n strings for sync-blocked banner + force-push modal

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(sync-guard): add SyncBlockedBanner showing shrink findings with restore/force-push actions

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(sync-guard): stable subscribeToEvents reference + type-safe finding narrowing

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(sync-guard): force-push confirmation modal + scroll restore button into view

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* ux(local-backups): show version as title, demote reason+timestamp to meta line

* feat(local-backups): record + display sync data version (v5/v6...) on each backup

Each backup now captures the live CloudSyncManager.localVersion at creation
time. UI shows it as title (v5, v6, ...) with timestamp + reason demoted to
the meta line. Backups created before this field existed (or before any
successful cloud sync) fall back to timestamp as title.

Replaces the earlier app-version-transition title which conflated app
version with sync data version.

* fix(sync-guard): consume override flag at sync entry + restore provider status on block

- Snapshot+clear overrideShrinkOnce at top of syncToProvider and
  syncAllProviders so an early-return cannot leak the flag to a later
  unrelated sync (Codex P1).
- Restore provider status to 'connected' when shrink-block returns from
  syncToProvider; previously left provider stuck on 'syncing' in the
  UI (Codex P2).
- Process pre-existing check errors before returning from the
  shouldBlockAll branch in syncAllProviders so a check-failed provider
  isn't dropped from results (Codex P2).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(sync-guard): refactor force-push to parameter passing + add credential-availability guard

The previous design used a one-shot boolean flag on CloudSyncManager set
by forcePushOverrideShrink(). Even with snapshot+clear at sync entry
points, the renderer wrapper's await ensureUnlocked() could throw before
the flag was consumed, leaving it armed for the next unrelated sync.

Fix: pass overrideShrink as a call-time parameter through the chain.
Eliminates the persistent flag and its leak surface.

Also: force-push now runs the same ensureSyncablePayload(...) guard the
other manual sync entry points use, so a vault with encrypted-credential
placeholders won't be uploaded via the force path either.

Addresses the latest two Codex P1/P2 findings on #742.

* fix(sync-guard): backfill account id from in-memory state for upgrade-path re-auth

Users upgrading to this PR have no netcatty.sync.accountId.* persisted yet.
On their first re-auth the guard saw previousId=null and cleared the
merge base anyway, defeating the point of the same-account preservation.

Snapshot the in-memory account id BEFORE overwriting providers[provider]
and use it as a fallback when the persisted id is missing. New users
(no prior connection at all) still get the clear-on-first-auth path.

Addresses Codex P1 on #742.

* fix(sync-guard): inspect force-push results + mark blocked single-provider as error

- Force-push handler now inspects syncNow result entries: applies any
  mergedPayload to local state, only clears the banner when all providers
  report success, surfaces a toast error otherwise. Previously the banner
  cleared unconditionally regardless of network/auth failures (Codex P1).

- syncToProvider shrink-block branches now mark provider status as
  'error' with a 'Sync blocked: would delete too much' message instead
  of 'connected'. Status aggregators treat 'connected' as healthy, so
  the blocked upload was surfacing as 'synced' in the UI (Codex P2).
  syncAllProviders already used this pattern; this brings the
  single-provider path in line.

* fix(sync-guard): exempt USE_LOCAL conflict + clear post-merge BLOCKED + expose 'blocked' status

- USE_LOCAL conflict resolution now passes { overrideShrink: true }: the
  conflict modal already served as user confirmation, and shrink-blocking
  it left users with a closed modal and an opaque banner (Review C-1).

- Post-merge round-trip in useAutoSync now detects shrink-blocked results
  and resets syncState to IDLE via new manager.clearShrinkBlockedState().
  The merged data is already applied locally; the next user-triggered
  sync will re-check, and we don't wedge the manager in BLOCKED with no
  visible banner outside the Settings tab (Review I-1).

- overallSyncStatus now reports 'blocked' as a distinct value from
  'error', so downstream UI (status icon, future badges) can offer
  shrink-block-specific affordances (Review I-2).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(sync-guard): stabilize banner subscription dep + map 'blocked' status to error indicator

- The SyncBlockedBanner subscription useEffect depended on [sync] (the
  whole hook return object), which gets a new reference every render.
  This caused the listener to be unsubscribed+resubscribed on every
  render, opening a tiny race window where a SYNC_BLOCKED_SHRINK event
  could be missed and the banner would never appear. Destructure
  subscribeToEvents (already useCallback-stable) and depend on it
  directly, so the effect runs exactly once on mount.

- SyncStatusButton's status mapping had no arm for the new 'blocked'
  value, falling through to 'none' (idle). The global status indicator
  said healthy while the in-page banner said paused. Map 'blocked' to
  the same error indicator used for 'conflict' so the UI is consistent.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(sync-guard): only clear banner on actual success + hydrate from manager state

- Banner subscription now clears only on SYNC_COMPLETED with result.success.
  SYNC_STARTED (auto-sync timer ticks) and SYNC_FORCED (fires BEFORE upload)
  could clear the banner prematurely, removing the user's recovery affordance
  while the underlying issue was unresolved (Codex P2).

- Manager now persists the last shrink finding in state.lastShrinkFinding
  alongside the SYNC_BLOCKED_SHRINK emission. New public getter
  getShrinkBlockedFinding() returns it when syncState is BLOCKED. Renderer
  hydrates the banner on mount so a block that happened off-screen
  (auto-sync while user was on another tab) is still visible when they
  open Sync Settings (Codex P2).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(sync-guard): unified BLOCKED-cleared event + USE_LOCAL inspects results

- USE_LOCAL conflict resolution now inspects syncNow() results, applies
  any mergedPayload to local state, surfaces a toast error and KEEPS the
  modal open on failure (so user can switch to USE_REMOTE). Mirrors the
  force-push handler pattern. Without this, USE_LOCAL silently 'succeeded'
  even when providers failed (Codex CLI P1).

- New SYNC_BLOCKED_CLEARED event emitted on every BLOCKED -> non-BLOCKED
  transition via a private exitBlockedState() helper. Banner subscribes to
  this single signal instead of guessing from per-provider SYNC_COMPLETED
  events. Fixes:
    - Multi-provider scenarios where first SYNC_COMPLETED clears the banner
      while a later provider was still going to fail (Codex CLI P1).
    - clearShrinkBlockedState() (post-merge self-heal) silently leaving
      the banner stuck because no event was emitted (Codex CLI P2).

- disconnectProvider() now also exits BLOCKED state. Disconnecting
  implicitly resolves any pending shrink-block warning, otherwise the
  stale alert carried over to the next-account reconnect (Codex CLI P2).

- All BLOCKED -> non-BLOCKED transitions consolidated through
  exitBlockedState() so lastShrinkFinding cleanup + event emission are
  always paired (Codex CLI P3 #6 covered).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(sync-guard): only clear BLOCKED on actual success, not on transient ERROR/SYNCING/CONFLICT

Previous patch called exitBlockedState() at every BLOCKED -> non-BLOCKED
transition, but this clears the banner on transitions that don't actually
resolve the shrink concern:

- SYNCING (sync just started — about to try, may fail)
- ERROR (transient transport failure, shrink concern still real)
- CONFLICT (separate concern; doesn't resolve the shrink)

If a user was in BLOCKED then triggered a sync that failed for an unrelated
reason (network, auth), the banner cleared and they lost the warning.

Restrict exitBlockedState() to terminal-success transitions:
- IDLE on successful upload (data made it to cloud — concern resolved)
- explicit clears (disconnectProvider, clearShrinkBlockedState)
- conflict resolution (USE_REMOTE/USE_LOCAL also end in IDLE)

Found by Codex CLI review of commit 12d7fa7b.

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-16 22:43:19 +08:00

596 lines
22 KiB
JavaScript

const fs = require("node:fs");
const path = require("node:path");
const crypto = require("node:crypto");
const BACKUP_DIR_NAME = "vault-backups";
const BACKUP_FILE_PREFIX = "vault-backup-";
const BACKUP_FILE_EXT = ".json";
// The renderer is the untrusted input boundary for this bridge, so every
// piece of user-controlled data is validated before it reaches disk or
// propagates back into the UI. Keep these limits in sync with the
// renderer's `sanitizeLocalVaultBackupMaxCount` constants.
const MIN_MAX_COUNT = 1;
const MAX_MAX_COUNT = 100;
const DEFAULT_MAX_COUNT = 20;
// 25 MiB — two orders of magnitude above any realistic vault. A payload
// exceeding this is either a runaway test harness or a misbehaving/compromised
// renderer; refusing here prevents disk-fill DoS. The vault proper is capped
// at a much smaller size elsewhere in the app, so legitimate users never hit
// this limit.
const MAX_PAYLOAD_BYTES = 25 * 1024 * 1024;
const ALLOWED_REASONS = new Set(["app_version_change", "before_restore"]);
// Version strings are persisted and surfaced in the Settings UI, so they
// must not carry control chars that would break logs, parsing, or
// display. Keep alphanumerics + a handful of punctuation that covers
// SemVer-ish and prerelease tags.
const VERSION_STRING_PATTERN = /^[A-Za-z0-9._+\-]{1,64}$/;
function isPlainObject(value) {
return Boolean(value) && typeof value === "object" && !Array.isArray(value);
}
// Normalize a payload into a form that hashes stably across runs:
// - object keys sorted so JSON.stringify output is deterministic
// - undefined values dropped (they'd stringify as gaps anyway)
// - the TOP-LEVEL `syncedAt` timestamp is zeroed so semantically-equal
// payloads produced seconds apart still dedupe. Nested `syncedAt`
// fields (e.g. a future per-record mtime) are preserved — zeroing
// them would silently collide two semantically-different payloads
// into the same fingerprint and cause the version-change / protective
// backup dedupe to drop a backup that should have been written.
//
// INVARIANT: array order is treated as semantically meaningful and is
// NOT canonicalized. Every domain array that flows through SyncPayload
// (hosts, keys, snippets, identities, portForwardingRules, …) is
// produced by a store that iterates its internal `Map`/`Set` in a
// stable, insertion-ordered way, so two semantically-equal payloads
// built in the same renderer session produce identical orderings. If a
// future refactor introduces a non-deterministic iteration source,
// fingerprints will flap and the dedupe will miss — sort at the
// producer, not here. Sorting inside the hash function would require
// choosing a stable key per array type and would silently hide
// intentionally-reordered payloads (user dragged a host in the list)
// as "the same backup," which would be a safety regression.
function normalizePayloadForHash(value, isRoot = true) {
if (Array.isArray(value)) {
return value.map((item) => normalizePayloadForHash(item, false));
}
if (isPlainObject(value)) {
const entries = Object.entries(value)
.filter(([, item]) => item !== undefined)
.sort(([a], [b]) => a.localeCompare(b));
return entries.reduce((acc, [entryKey, entryValue]) => {
acc[entryKey] =
isRoot && entryKey === "syncedAt"
? 0
: normalizePayloadForHash(entryValue, false);
return acc;
}, {});
}
return value;
}
function stableStringify(value) {
return JSON.stringify(normalizePayloadForHash(value));
}
function computePayloadFingerprint(payload) {
return crypto
.createHash("sha256")
.update(stableStringify(payload))
.digest("hex");
}
function buildPreview(payload) {
return {
hostCount: Array.isArray(payload?.hosts) ? payload.hosts.length : 0,
keyCount: Array.isArray(payload?.keys) ? payload.keys.length : 0,
snippetCount: Array.isArray(payload?.snippets) ? payload.snippets.length : 0,
identityCount: Array.isArray(payload?.identities) ? payload.identities.length : 0,
portForwardingRuleCount: Array.isArray(payload?.portForwardingRules) ? payload.portForwardingRules.length : 0,
};
}
function toBackupSummary(record) {
return {
id: record.id,
createdAt: record.createdAt,
reason: record.reason,
syncDataVersion: record.syncDataVersion,
sourceAppVersion: record.sourceAppVersion,
targetAppVersion: record.targetAppVersion,
preview: record.preview,
fingerprint: record.fingerprint,
};
}
// Clamp an unvalidated maxCount to the supported range. Returns
// DEFAULT_MAX_COUNT for anything non-finite or non-numeric so callers
// without a configured retention still get a sane cap.
function sanitizeMaxCount(rawMaxCount) {
const numeric = Number(rawMaxCount);
if (!Number.isFinite(numeric) || numeric <= 0) return DEFAULT_MAX_COUNT;
return Math.max(MIN_MAX_COUNT, Math.min(MAX_MAX_COUNT, Math.floor(numeric)));
}
function sanitizeReason(rawReason) {
// Fall back to the "before_restore" default rather than throwing — the
// default is the safer label for an unknown-cause backup, since it
// implies "this was taken defensively" in the UI.
if (typeof rawReason === "string" && ALLOWED_REASONS.has(rawReason)) {
return rawReason;
}
return "before_restore";
}
function sanitizeOptionalVersionString(value) {
if (typeof value !== "string") return undefined;
const trimmed = value.trim();
if (!trimmed) return undefined;
if (!VERSION_STRING_PATTERN.test(trimmed)) return undefined;
return trimmed;
}
// Sync data version is the integer that the CloudSyncManager increments
// on each successful cloud sync. Reject anything non-finite, non-positive,
// or non-integer so the persisted record only carries meaningful values.
function sanitizeOptionalSyncDataVersion(value) {
if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
if (value < 1) return undefined;
return Math.floor(value);
}
// UTF-8 byte length of a payload's JSON serialization. Earlier revisions
// returned `JSON.stringify(payload).length` (UTF-16 code units), which
// under-counted by ~3x for non-ASCII vaults — a deck full of CJK snippet
// labels would report ~12.5 MiB against the 25 MiB cap when the on-wire
// size was actually 25+ MiB. `Buffer.byteLength(..., 'utf8')` gives the
// true bytes-on-disk figure.
function estimatePayloadSize(payload) {
try {
return Buffer.byteLength(JSON.stringify(payload), "utf8");
} catch {
return Infinity;
}
}
// Error thrown when the platform has no secure storage available. Backups
// would contain plaintext credentials (passwords, private keys, passphrases)
// in fields that SyncPayload carries unencrypted, so falling back to a
// plain-json file on disk would regress the vault's security posture below
// what the normal encrypted localStorage vault provides. We refuse rather
// than silently weaken the user's protection.
class VaultBackupEncryptionUnavailableError extends Error {
constructor() {
super(
"Secure storage is unavailable on this platform; vault backups cannot be created or read safely.",
);
this.name = "VaultBackupEncryptionUnavailableError";
this.code = "VAULT_BACKUP_ENCRYPTION_UNAVAILABLE";
}
}
class VaultBackupTooLargeError extends Error {
constructor(size) {
super(
`Vault backup payload exceeds maximum allowed size (${size} > ${MAX_PAYLOAD_BYTES}).`,
);
this.name = "VaultBackupTooLargeError";
this.code = "VAULT_BACKUP_TOO_LARGE";
}
}
function isSafeStorageAvailable(safeStorage) {
return Boolean(safeStorage?.isEncryptionAvailable?.());
}
function encodePayload(payload, safeStorage) {
if (!isSafeStorageAvailable(safeStorage)) {
throw new VaultBackupEncryptionUnavailableError();
}
const raw = JSON.stringify(payload);
return {
encoding: "safeStorage-v1",
data: safeStorage.encryptString(raw).toString("base64"),
};
}
function decodePayload(record, safeStorage) {
if (record.payloadEncoding === "safeStorage-v1") {
if (!safeStorage?.decryptString || !isSafeStorageAvailable(safeStorage)) {
throw new VaultBackupEncryptionUnavailableError();
}
const decrypted = safeStorage.decryptString(Buffer.from(record.payloadData, "base64"));
return JSON.parse(decrypted);
}
// Legacy "plain-json-v1" records may exist from an earlier build; read
// them once so users can migrate their data, but never write new ones.
if (record.payloadEncoding === "plain-json-v1") {
return JSON.parse(record.payloadData);
}
throw new Error(`Unsupported vault backup encoding: ${record.payloadEncoding}`);
}
// Upper bound for a backup file on disk. The plaintext payload is capped
// at MAX_PAYLOAD_BYTES on write; the encrypted-and-base64-encoded record
// plus JSON envelope inflates that by ~2x worst case (base64 adds ~33%,
// JSON formatting adds some, and the record metadata rounds up). A 2x
// multiplier leaves comfortable headroom for legitimate backups while
// still rejecting a 100+ MiB file that a user (or attacker) dropped
// into the backup directory manually.
const MAX_BACKUP_FILE_BYTES = MAX_PAYLOAD_BYTES * 2;
async function readBackupRecord(filePath) {
// Refuse oversized files BEFORE readFile. `fs.readFile` buffers the
// whole file into memory, so an attacker (or a corrupted state) that
// places a huge file in the backup dir could OOM the renderer during
// listBackups enumeration. Stat-then-read keeps the failure mode to
// a cheap rejection.
let stat;
try {
stat = await fs.promises.stat(filePath);
} catch (error) {
throw new Error(`Unable to stat vault backup ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
}
if (stat.size > MAX_BACKUP_FILE_BYTES) {
throw new VaultBackupTooLargeError(stat.size);
}
const raw = await fs.promises.readFile(filePath, "utf8");
const parsed = JSON.parse(raw);
if (!parsed || typeof parsed !== "object" || typeof parsed.id !== "string") {
throw new Error(`Invalid vault backup record: ${filePath}`);
}
return parsed;
}
async function listBackupRecords(dirPath) {
await fs.promises.mkdir(dirPath, { recursive: true, mode: 0o700 });
const entries = await fs.promises.readdir(dirPath, { withFileTypes: true });
const records = [];
for (const entry of entries) {
if (!entry.isFile()) continue;
if (!entry.name.startsWith(BACKUP_FILE_PREFIX) || !entry.name.endsWith(BACKUP_FILE_EXT)) continue;
const fullPath = path.join(dirPath, entry.name);
try {
const record = await readBackupRecord(fullPath);
records.push({ record, filePath: fullPath });
} catch (error) {
console.warn("[vaultBackupBridge] Failed to parse backup:", fullPath, error);
}
}
records.sort((a, b) => {
const aTime = Number(a.record.createdAt || 0);
const bTime = Number(b.record.createdAt || 0);
if (aTime !== bTime) return bTime - aTime;
// Stable, deterministic tiebreak when two backups share a millisecond
// (rapid successive creates, clock quantization). Without this the
// retention trimmer's "delete the oldest" pass is order-dependent and
// can drop a different record across list() → prune() passes.
const aId = String(a.record.id || '');
const bId = String(b.record.id || '');
return bId.localeCompare(aId);
});
return records;
}
// Delete old backups, trusting the caller-provided `records` list when
// supplied to avoid a redundant directory scan. `createBackup` has just
// scanned + written, so it passes its freshly-enumerated records through
// here. External callers (retention-change UI, trim IPC) rescan.
async function pruneBackupRecords(dirPath, maxCount, records = null) {
const sanitizedMaxCount = sanitizeMaxCount(maxCount);
const sourceRecords = records ?? (await listBackupRecords(dirPath));
const toDelete = sourceRecords.slice(sanitizedMaxCount);
let deletedCount = 0;
for (const entry of toDelete) {
try {
await fs.promises.unlink(entry.filePath);
deletedCount += 1;
} catch (error) {
console.warn("[vaultBackupBridge] Failed to delete old backup:", entry.filePath, error);
}
}
return {
deletedCount,
keptCount: Math.min(sourceRecords.length, sanitizedMaxCount),
};
}
function createVaultBackupService({ app, safeStorage, shell }) {
if (!app?.getPath) {
throw new Error("Electron app is unavailable.");
}
const getBackupDir = () => path.join(app.getPath("userData"), BACKUP_DIR_NAME);
// Serialize createBackup so two concurrent calls (version-change backup
// running at startup + an explicit protective-before-restore triggered
// by the user's click, etc.) observe each other's writes. Without this,
// both observers would see an empty directory, compute the same
// fingerprint, skip the dedupe, and write two identical files.
let createBackupLock = Promise.resolve();
// Monotonically increasing `createdAt` per service instance. `Date.now()`
// has 1ms resolution and back-to-back async calls (version-change backup
// followed immediately by a protective backup) can land in the same
// millisecond, producing ties that `listBackupRecords` cannot resolve
// (the sort has no tiebreaker). Bumping ensures strict ordering so
// callers always see the true newest record first.
let lastCreatedAt = 0;
return {
isEncryptionAvailable() {
return isSafeStorageAvailable(safeStorage);
},
async createBackup(options = {}) {
const next = createBackupLock.then(() => doCreateBackup(options));
// Swallow the rejection on the lock chain so one caller's error
// does not poison subsequent calls; each individual await sees its
// own rejection via the `next` return.
createBackupLock = next.catch(() => undefined);
return next;
},
async listBackups() {
const records = await listBackupRecords(getBackupDir());
return records.map(({ record }) => toBackupSummary(record));
},
async readBackup(options = {}) {
const backupId = typeof options.id === "string" ? options.id : "";
if (!backupId) {
throw new Error("Missing vault backup id.");
}
const records = await listBackupRecords(getBackupDir());
const match = records.find(({ record }) => record.id === backupId);
if (!match) {
throw new Error("Vault backup not found.");
}
return {
backup: toBackupSummary(match.record),
payload: decodePayload(match.record, safeStorage),
};
},
async trimBackups(options = {}) {
return pruneBackupRecords(getBackupDir(), options.maxCount);
},
async openBackupDir() {
const dirPath = getBackupDir();
await fs.promises.mkdir(dirPath, { recursive: true, mode: 0o700 });
if (shell?.openPath) {
const errorMessage = await shell.openPath(dirPath);
if (errorMessage) {
throw new Error(errorMessage);
}
}
return {
success: true,
path: dirPath,
};
},
};
async function doCreateBackup(options) {
const payload = options.payload;
if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
throw new Error("Missing vault backup payload.");
}
// Refuse early when the payload is too large to prevent a
// misbehaving or compromised renderer from filling the disk. The
// check runs before any side effect so callers see a deterministic
// failure rather than a partial write.
const estimatedSize = estimatePayloadSize(payload);
if (estimatedSize > MAX_PAYLOAD_BYTES) {
throw new VaultBackupTooLargeError(estimatedSize);
}
// Refuse before doing anything side-effectful so callers get a clear
// error rather than a silently-weakened plaintext backup.
if (!isSafeStorageAvailable(safeStorage)) {
throw new VaultBackupEncryptionUnavailableError();
}
const dirPath = getBackupDir();
const existingRecords = await listBackupRecords(dirPath);
const fingerprint = computePayloadFingerprint(payload);
const latest = existingRecords[0]?.record ?? null;
if (latest?.fingerprint === fingerprint) {
return {
created: false,
backup: toBackupSummary(latest),
};
}
let createdAt = Date.now();
if (createdAt <= lastCreatedAt) createdAt = lastCreatedAt + 1;
lastCreatedAt = createdAt;
const id = crypto.randomUUID();
const preview = buildPreview(payload);
const encoded = encodePayload(payload, safeStorage);
const record = {
formatVersion: 1,
id,
createdAt,
reason: sanitizeReason(options.reason),
syncDataVersion: sanitizeOptionalSyncDataVersion(options.syncDataVersion),
sourceAppVersion: sanitizeOptionalVersionString(options.sourceAppVersion),
targetAppVersion: sanitizeOptionalVersionString(options.targetAppVersion),
fingerprint,
preview,
payloadEncoding: encoded.encoding,
payloadData: encoded.data,
};
const filePath = path.join(
dirPath,
`${BACKUP_FILE_PREFIX}${createdAt}-${id}${BACKUP_FILE_EXT}`,
);
// Durable atomic write: serialize to a sibling tmp file, fsync the
// file's data+metadata to stable storage, rename into place, then
// fsync the directory entry itself. Without the file fsync a system
// crash between writeFile and rename can leave the OS with a
// successfully-renamed entry whose data blocks are still only in
// page cache — the file is visible but reads back as zeros or torn
// content. Without the directory fsync the rename itself may not be
// durable: on recovery listBackups sees an empty directory even
// though the file's blocks made it to disk. Both matter for the
// protective-before-restore case, where the user is about to
// overwrite their vault and the safety net MUST survive a crash
// between backup and restore.
const tmpPath = `${filePath}.tmp-${crypto.randomUUID()}`;
let tmpHandle;
try {
tmpHandle = await fs.promises.open(tmpPath, 'w', 0o600);
await tmpHandle.writeFile(`${JSON.stringify(record, null, 2)}\n`);
await tmpHandle.sync();
} finally {
if (tmpHandle) {
try {
await tmpHandle.close();
} catch {
/* ignore — close failure after successful sync still leaves
data durable on disk */
}
}
}
try {
await fs.promises.rename(tmpPath, filePath);
} catch (renameError) {
// Best-effort cleanup; swallow unlink errors so the rename error
// surfaces to the caller.
try {
await fs.promises.unlink(tmpPath);
} catch {
/* ignore */
}
throw renameError;
}
// fsync the directory so the rename itself is durably recorded.
// On Linux this is required; on macOS it is a no-op at the FS
// layer but still safe and portable. On Windows fs.open on a
// directory is not supported — the rename is durable as part of
// NTFS's journal, so skip the sync there.
if (process.platform !== 'win32') {
let dirHandle;
try {
dirHandle = await fs.promises.open(dirPath, 'r');
await dirHandle.sync();
} catch (dirSyncError) {
// Directory fsync is a defense-in-depth hardening step — if
// the filesystem refuses (tmpfs, some network mounts) the
// rename already happened and the file is reachable, so a
// failure here should not abort the backup. Log so a
// systematic issue is diagnosable.
console.warn('[vaultBackupBridge] Directory fsync failed:', dirSyncError);
} finally {
if (dirHandle) {
try {
await dirHandle.close();
} catch {
/* ignore */
}
}
}
}
// Reuse the enumeration we already did for dedupe, prepending the
// newly-written record so pruneBackupRecords can trim without
// re-scanning the directory. Records are ordered newest-first.
const nextRecords = [{ record, filePath }, ...existingRecords];
await pruneBackupRecords(dirPath, options.maxCount, nextRecords);
return {
created: true,
backup: toBackupSummary(record),
};
}
}
function registerHandlers(ipcMain, electronModule) {
const service = createVaultBackupService({
app: electronModule?.app,
safeStorage: electronModule?.safeStorage,
shell: electronModule?.shell,
});
const BrowserWindow = electronModule?.BrowserWindow;
// Broadcast a backup-changed event to every renderer so other windows
// (notably the Settings window's backup list) can refresh without the
// user manually navigating. Any successful create / trim path calls
// this. Failures fall through silently — a dropped notification is
// recoverable on the next manual refresh, while re-throwing here
// would turn a harmless broadcast failure into a user-visible error.
const broadcastBackupsChanged = () => {
if (!BrowserWindow?.getAllWindows) return;
try {
for (const win of BrowserWindow.getAllWindows()) {
if (win.isDestroyed?.()) continue;
try {
win.webContents?.send?.("netcatty:vaultBackups:changed");
} catch (error) {
console.warn("[vaultBackupBridge] Failed to notify window:", error);
}
}
} catch (error) {
console.warn("[vaultBackupBridge] Broadcast failed:", error);
}
};
ipcMain.handle("netcatty:vaultBackups:capabilities", async () => {
return { encryptionAvailable: service.isEncryptionAvailable() };
});
ipcMain.handle("netcatty:vaultBackups:create", async (_event, payload) => {
const result = await service.createBackup(payload || {});
// Only broadcast when a new record was actually written; a
// deduped (created=false) return means the on-disk state did not
// change, so other windows already show the latest backup.
if (result?.created) {
broadcastBackupsChanged();
}
return result;
});
ipcMain.handle("netcatty:vaultBackups:list", async () => {
return service.listBackups();
});
ipcMain.handle("netcatty:vaultBackups:read", async (_event, payload) => {
return service.readBackup(payload || {});
});
ipcMain.handle("netcatty:vaultBackups:trim", async (_event, payload) => {
const result = await service.trimBackups(payload || {});
if (result?.deletedCount) {
broadcastBackupsChanged();
}
return result;
});
ipcMain.handle("netcatty:vaultBackups:openDir", async () => {
return service.openBackupDir();
});
}
module.exports = {
BACKUP_DIR_NAME,
BACKUP_FILE_EXT,
BACKUP_FILE_PREFIX,
MAX_PAYLOAD_BYTES,
VaultBackupEncryptionUnavailableError,
VaultBackupTooLargeError,
buildPreview,
computePayloadFingerprint,
createVaultBackupService,
registerHandlers,
};