From 6e55d2d498332bba8d31c94ef2e35c1df1c197ce Mon Sep 17 00:00:00 2001 From: ryan-wong-coder <61351497+ryan-wong-coder@users.noreply.github.com> Date: Thu, 16 Jul 2026 20:03:32 +0800 Subject: [PATCH] feat(sync): add convergent sync migration (#2254) * feat(sync): add convergent sync migration * fix(sync): address convergent migration review * fix(sync): normalize CRDT payload entities * fix(sync): invalidate stale provider baselines * fix(sync): harden convergent migration recovery * fix(sync): close migration concurrency gaps * fix(sync): guard seeded provider shrink * fix(sync): preserve undefined legacy fields * fix(sync): guard legacy v2 migration shrink * fix(sync): harden migration apply transaction * fix(sync): reject locked migration initialization * fix(sync): block unbased divergent v1 migration --- application/convergentSyncMigration.test.ts | 151 ++++ application/convergentSyncMigration.ts | 159 ++++ application/convergentSyncReplica.test.ts | 73 ++ application/convergentSyncReplica.ts | 46 ++ application/localVaultBackups.test.ts | 80 ++ application/localVaultBackups.ts | 25 +- application/syncPayload.test.ts | 111 +++ application/syncPayload.ts | 33 +- components/settings/tabs/SettingsSyncTab.tsx | 6 +- docs/designs/convergent-sync-crdt.md | 9 +- docs/designs/convergent-sync-protocol-v2.md | 121 +++ domain/convergentSync/index.ts | 3 + domain/convergentSync/json.ts | 13 + domain/convergentSync/legacy.ts | 223 ++++++ domain/convergentSync/migration.ts | 291 ++++++++ domain/convergentSync/payload.ts | 566 ++++++++++++++ .../convergentSync/payloadMigration.test.ts | 701 ++++++++++++++++++ domain/convergentSync/types.ts | 55 ++ domain/sync.ts | 56 ++ infrastructure/config/storageKeys.ts | 2 + infrastructure/services/CloudSyncManager.ts | 47 +- .../EncryptionService.convergentSync.test.ts | 51 ++ infrastructure/services/EncryptionService.ts | 13 +- .../services/cloudSync/authMethods.ts | 24 +- .../convergentSyncStorageMethods.test.ts | 258 +++++++ .../cloudSync/convergentSyncStorageMethods.ts | 191 +++++ .../cloudSync/encryptedLocalStorage.ts | 26 + .../services/cloudSync/providerSyncMethods.ts | 3 + .../cloudSync/stateAndSecurityMethods.ts | 33 +- .../cloudSync/syncAllStorageMethods.test.ts | 78 +- .../cloudSync/syncAllStorageMethods.ts | 65 +- .../services/convergentSyncConfig.test.ts | 39 + .../services/convergentSyncConfig.ts | 55 ++ 33 files changed, 3536 insertions(+), 71 deletions(-) create mode 100644 application/convergentSyncMigration.test.ts create mode 100644 application/convergentSyncMigration.ts create mode 100644 application/convergentSyncReplica.test.ts create mode 100644 application/convergentSyncReplica.ts create mode 100644 application/localVaultBackups.test.ts create mode 100644 docs/designs/convergent-sync-protocol-v2.md create mode 100644 domain/convergentSync/legacy.ts create mode 100644 domain/convergentSync/migration.ts create mode 100644 domain/convergentSync/payload.ts create mode 100644 domain/convergentSync/payloadMigration.test.ts create mode 100644 infrastructure/services/EncryptionService.convergentSync.test.ts create mode 100644 infrastructure/services/cloudSync/convergentSyncStorageMethods.test.ts create mode 100644 infrastructure/services/cloudSync/convergentSyncStorageMethods.ts create mode 100644 infrastructure/services/cloudSync/encryptedLocalStorage.ts create mode 100644 infrastructure/services/convergentSyncConfig.test.ts create mode 100644 infrastructure/services/convergentSyncConfig.ts diff --git a/application/convergentSyncMigration.test.ts b/application/convergentSyncMigration.test.ts new file mode 100644 index 000000000..5d4b6b2f4 --- /dev/null +++ b/application/convergentSyncMigration.test.ts @@ -0,0 +1,151 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; + +import type { SyncPayload } from '../domain/sync.ts'; +import type { CloudSyncManager } from '../infrastructure/services/CloudSyncManager.ts'; + +const NOW = 1_700_000_000_000; +const localStorageValues = new Map(); + +Object.defineProperty(globalThis, 'localStorage', { + configurable: true, + value: { + getItem: (key: string) => localStorageValues.get(key) ?? null, + setItem: (key: string, value: string) => localStorageValues.set(key, value), + removeItem: (key: string) => localStorageValues.delete(key), + clear: () => localStorageValues.clear(), + }, +}); + +const { planConvergentSyncMigration } = await import('../domain/convergentSync/index.ts'); +const { getConvergentSyncLocalConfig } = await import('../infrastructure/services/convergentSyncConfig.ts'); +const { initializePreparedConvergentMigration } = await import('./convergentSyncMigration.ts'); + +function payload(): SyncPayload { + return { + hosts: [], + keys: [], + snippets: [], + customGroups: [], + syncedAt: NOW, + }; +} + +test.beforeEach(() => { + localStorageValues.clear(); +}); + +test('initialization applies the protected preview before persisting and enabling the replica', async () => { + const localPayload = payload(); + const liveLocalPayload = { ...payload(), knownHosts: [] }; + const plan = planConvergentSyncMigration({ + localPayload, + localTrustedBaseline: null, + providers: [], + deviceId: 'device-a', + now: NOW, + }); + assert.equal(plan.preview.canInitialize, true); + const calls: string[] = []; + const manager = { + isUnlocked: () => true, + saveConvergentReplica: async () => { + calls.push('replica'); + }, + saveConvergentProviderBaseline: async () => { + calls.push('baseline'); + }, + } as unknown as CloudSyncManager; + + await initializePreparedConvergentMigration({ + prepared: { plan, providerBaselines: [] }, + manager, + now: NOW, + buildPreApplyPayload: () => { + calls.push('snapshot'); + return liveLocalPayload; + }, + translateProtectiveBackupFailure: (message) => message, + applyPayload: async (incoming) => { + calls.push('apply'); + assert.equal(incoming.convergentSync?.schemaVersion, 2); + }, + runProtectedApply: async (options) => { + calls.push('protect'); + assert.equal(options.buildPreApplyPayload(), liveLocalPayload); + await options.applyPayload(); + }, + }); + + assert.deepEqual(calls, ['protect', 'snapshot', 'apply', 'replica']); + assert.deepEqual(getConvergentSyncLocalConfig(), { enabled: true, initialized: true }); +}); + +test('blocked previews cannot enter the protected initialization transaction', async () => { + const localPayload = payload(); + const plan = planConvergentSyncMigration({ + localPayload, + localTrustedBaseline: null, + providers: [{ provider: 'github', status: 'unavailable', message: 'offline' }], + deviceId: 'device-a', + now: NOW, + }); + let entered = false; + + await assert.rejects( + () => initializePreparedConvergentMigration({ + prepared: { plan, providerBaselines: [] }, + manager: {} as CloudSyncManager, + buildPreApplyPayload: () => localPayload, + translateProtectiveBackupFailure: (message) => message, + applyPayload: () => {}, + runProtectedApply: async () => { + entered = true; + }, + }), + /migration is blocked/, + ); + assert.equal(entered, false); + assert.deepEqual(getConvergentSyncLocalConfig(), { enabled: false, initialized: false }); +}); + +test('a locked manager cannot enter the protected initialization transaction', async () => { + const localPayload = payload(); + const plan = planConvergentSyncMigration({ + localPayload, + localTrustedBaseline: null, + providers: [], + deviceId: 'device-a', + now: NOW, + }); + let entered = false; + let applied = false; + let snapshotBuilt = false; + const manager = { + isUnlocked: () => false, + } as unknown as CloudSyncManager; + + await assert.rejects( + () => initializePreparedConvergentMigration({ + prepared: { plan, providerBaselines: [] }, + manager, + buildPreApplyPayload: () => { + snapshotBuilt = true; + return localPayload; + }, + translateProtectiveBackupFailure: (message) => message, + applyPayload: () => { + applied = true; + }, + runProtectedApply: async () => { + entered = true; + }, + }), + /Unlock cloud sync before initializing convergent migration/, + ); + + assert.equal(entered, false); + assert.equal(snapshotBuilt, false); + assert.equal(applied, false); + assert.deepEqual(getConvergentSyncLocalConfig(), { enabled: false, initialized: false }); +}); diff --git a/application/convergentSyncMigration.ts b/application/convergentSyncMigration.ts new file mode 100644 index 000000000..874ff7230 --- /dev/null +++ b/application/convergentSyncMigration.ts @@ -0,0 +1,159 @@ +import type { + CloudProvider, + ConvergentMigrationPreview, + ConvergentProviderBaselineV2, + SyncPayload, +} from '../domain/sync'; +import { + cloudSyncPayloadsEqual, + materializeSyncPayloadFromConvergentState, + planConvergentSyncMigration, + stripConvergentSyncEnvelope, + validateConvergentSyncPayload, + type ConvergentMigrationPlan, + type ConvergentMigrationProviderInput, +} from '../domain/convergentSync'; +import { isProviderReadyForSync } from '../domain/sync'; +import { getCloudSyncManager, type CloudSyncManager } from '../infrastructure/services/CloudSyncManager'; +import { + clearConvergentSyncLocalConfigAfterDowngrade, + markConvergentSyncInitialized, +} from '../infrastructure/services/convergentSyncConfig'; +import { applyProtectedSyncPayload } from './localVaultBackups'; + +export interface PreparedConvergentMigration { + plan: ConvergentMigrationPlan; + providerBaselines: ConvergentProviderBaselineV2[]; +} + +function selectLocalTrustedBaseline(baselines: SyncPayload[]): SyncPayload | null { + if (baselines.length === 0) return null; + const first = baselines[0]; + return baselines.every((baseline) => cloudSyncPayloadsEqual(first, baseline)) + ? first + : null; +} + +export async function prepareConvergentSyncMigration( + localPayload: SyncPayload, + manager: CloudSyncManager = getCloudSyncManager(), + now = Date.now(), +): Promise { + if (!manager.isUnlocked()) throw new Error('Unlock cloud sync before preparing migration'); + const providers = (Object.entries(manager.getAllProviders()) as Array<[ + CloudProvider, + ReturnType, + ]>) + .filter(([, connection]) => isProviderReadyForSync(connection)) + .map(([provider]) => provider) + .sort(); + const baselineByProvider = new Map(); + const providerBaselines: ConvergentProviderBaselineV2[] = []; + const inputs: ConvergentMigrationProviderInput[] = await Promise.all( + providers.map(async (provider): Promise => { + try { + const convergentBaseline = await manager.loadConvergentProviderBaseline(provider); + const baseline = convergentBaseline?.materializedPayload + ?? await manager.loadSyncBase(provider); + baselineByProvider.set(provider, baseline); + const remote = await manager.downloadFromProvider(provider); + if (!remote) return { provider, status: 'empty' }; + const remoteState = validateConvergentSyncPayload(remote.remoteFile.meta, remote.payload); + if (remoteState) { + providerBaselines.push({ + schemaVersion: 2, + provider, + remoteVersion: remote.remoteFile.meta.version, + remoteUpdatedAt: remote.remoteFile.meta.updatedAt, + remoteDeviceId: remote.remoteFile.meta.deviceId, + materializedPayload: stripConvergentSyncEnvelope(remote.payload), + state: remoteState, + }); + } + return { + provider, + status: 'ready', + meta: remote.remoteFile.meta, + payload: remote.payload, + trustedBaseline: baseline, + }; + } catch (error) { + return { + provider, + status: 'unavailable', + message: error instanceof Error ? error.message : String(error), + }; + } + }), + ); + const localTrustedBaseline = selectLocalTrustedBaseline( + [...baselineByProvider.values()].filter((value): value is SyncPayload => value !== null), + ); + return { + providerBaselines: providerBaselines.sort((left, right) => left.provider.localeCompare(right.provider)), + plan: planConvergentSyncMigration({ + localPayload: stripConvergentSyncEnvelope(localPayload), + localTrustedBaseline, + providers: inputs, + deviceId: manager.getState().deviceId, + now, + }), + }; +} + +export async function initializePreparedConvergentMigration(options: { + prepared: PreparedConvergentMigration; + buildPreApplyPayload: () => SyncPayload; + applyPayload: (payload: SyncPayload) => void | Promise; + translateProtectiveBackupFailure: (message: string) => string; + manager?: CloudSyncManager; + now?: number; + runProtectedApply?: typeof applyProtectedSyncPayload; +}): Promise { + const { prepared } = options; + const manager = options.manager ?? getCloudSyncManager(); + const now = options.now ?? Date.now(); + if (!prepared.plan.preview.canInitialize || !prepared.plan.state || !prepared.plan.payload) { + throw new Error(`Convergent migration is blocked: ${prepared.plan.preview.blockedReasons.join('; ')}`); + } + if (!manager.isUnlocked()) { + throw new Error('Unlock cloud sync before initializing convergent migration'); + } + const runProtectedApply = options.runProtectedApply ?? applyProtectedSyncPayload; + await runProtectedApply({ + buildPreApplyPayload: options.buildPreApplyPayload, + translateProtectiveBackupFailure: options.translateProtectiveBackupFailure, + applyPayload: async () => { + await options.applyPayload(prepared.plan.payload as SyncPayload); + for (const baseline of prepared.providerBaselines) { + await manager.saveConvergentProviderBaseline(baseline); + } + await manager.saveConvergentReplica({ + schemaVersion: 2, + state: prepared.plan.state as NonNullable, + updatedAt: now, + }); + markConvergentSyncInitialized(); + }, + }); + return prepared.plan.preview; +} + +export async function prepareConvergentSyncDowngrade( + manager: CloudSyncManager = getCloudSyncManager(), + now = Date.now(), +): Promise { + const replica = await manager.loadConvergentReplica(); + if (!replica) throw new Error('No convergent sync replica is available to downgrade'); + return materializeSyncPayloadFromConvergentState(replica.state, { syncedAt: now }); +} + +/** Call only after PR3's provider integration has replaced every v2 cloud file with v1. */ +export function completeConvergentSyncDowngrade( + confirmed: boolean, + manager: CloudSyncManager = getCloudSyncManager(), +): void { + if (!confirmed) throw new Error('Explicit confirmation is required to complete downgrade'); + manager.clearConvergentSyncStorage(true); + clearConvergentSyncLocalConfigAfterDowngrade(true); +} diff --git a/application/convergentSyncReplica.test.ts b/application/convergentSyncReplica.test.ts new file mode 100644 index 000000000..2b8175773 --- /dev/null +++ b/application/convergentSyncReplica.test.ts @@ -0,0 +1,73 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; + +import { + createConvergentSyncStateFromPayload, + materializeSyncPayloadFromConvergentState, +} from '../domain/convergentSync/index.ts'; +import type { SyncPayload } from '../domain/sync.ts'; +import type { CloudSyncManager } from '../infrastructure/services/CloudSyncManager.ts'; +import { prepareRestoredPayloadConvergentWrites } from './convergentSyncReplica.ts'; + +const NOW = 1_700_000_000_000; + +function payload(label: string): SyncPayload { + return { + hosts: [{ + id: 'host-1', + label, + hostname: 'example.com', + username: 'root', + tags: [], + os: 'linux', + }], + keys: [], + snippets: [], + customGroups: [], + syncedAt: NOW, + }; +} + +test('local restore is recorded as writes on the active replica instead of replacing it', async () => { + const state = createConvergentSyncStateFromPayload(payload('Before'), 'seed', NOW); + let savedState = state; + let saveCount = 0; + const manager = { + loadConvergentReplica: async () => ({ schemaVersion: 2 as const, state, updatedAt: NOW }), + getState: () => ({ deviceId: 'local-device' }), + saveConvergentReplica: async (record: { state: typeof state }) => { + saveCount += 1; + savedState = record.state; + }, + } as unknown as CloudSyncManager; + + const commit = await prepareRestoredPayloadConvergentWrites( + payload('Restored'), + NOW + 1, + { manager, initialized: true }, + ); + assert.equal(saveCount, 0); + + await commit(); + + const materialized = materializeSyncPayloadFromConvergentState(savedState, { syncedAt: NOW + 1 }); + assert.equal(saveCount, 1); + assert.equal(materialized.hosts[0].label, 'Restored'); + assert.equal(savedState.vector['local-device'] > 0, true); + assert.equal(savedState.vector.seed > 0, true); +}); + +test('an initialized configuration fails closed when its active replica is missing', async () => { + const manager = { + loadConvergentReplica: async () => null, + } as unknown as CloudSyncManager; + + await assert.rejects( + () => prepareRestoredPayloadConvergentWrites( + payload('Restored'), + NOW, + { manager, initialized: true }, + ), + /local replica is missing/, + ); +}); diff --git a/application/convergentSyncReplica.ts b/application/convergentSyncReplica.ts new file mode 100644 index 000000000..6d8f8cdcc --- /dev/null +++ b/application/convergentSyncReplica.ts @@ -0,0 +1,46 @@ +import type { SyncPayload } from '../domain/sync'; +import { + applyLegacySyncPayload, + materializeSyncPayloadFromConvergentState, + stripConvergentSyncEnvelope, +} from '../domain/convergentSync'; +import { getCloudSyncManager } from '../infrastructure/services/CloudSyncManager'; +import type { CloudSyncManager } from '../infrastructure/services/CloudSyncManager'; +import { getConvergentSyncLocalConfig } from '../infrastructure/services/convergentSyncConfig'; + +export type CommitRestoredPayloadConvergentWrites = () => Promise; + +/** + * Local backups intentionally contain no active CRDT replica. Before applying + * a restore, validate the active replica and prepare ordinary local writes. + * The returned commit persists them only after the local import succeeds, so + * the replica never claims a restore that the local import rejected. + */ +export async function prepareRestoredPayloadConvergentWrites( + restoredPayload: SyncPayload, + now = Date.now(), + dependencies: { + manager?: CloudSyncManager; + initialized?: boolean; + } = {}, +): Promise { + const initialized = dependencies.initialized + ?? getConvergentSyncLocalConfig().initialized; + if (!initialized) return async () => {}; + const manager = dependencies.manager ?? getCloudSyncManager(); + const replica = await manager.loadConvergentReplica(); + if (!replica) { + throw new Error('Convergent sync is initialized but its local replica is missing'); + } + const baseline = materializeSyncPayloadFromConvergentState(replica.state, { + syncedAt: replica.updatedAt, + }); + const state = applyLegacySyncPayload( + replica.state, + baseline, + stripConvergentSyncEnvelope(restoredPayload), + manager.getState().deviceId, + now, + ); + return () => manager.saveConvergentReplica({ schemaVersion: 2, state, updatedAt: now }); +} diff --git a/application/localVaultBackups.test.ts b/application/localVaultBackups.test.ts new file mode 100644 index 000000000..3ab06d6c0 --- /dev/null +++ b/application/localVaultBackups.test.ts @@ -0,0 +1,80 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; + +import type { SyncPayload } from '../domain/sync.ts'; + +const localStorageValues = new Map(); + +Object.defineProperty(globalThis, 'localStorage', { + configurable: true, + value: { + getItem: (key: string) => localStorageValues.get(key) ?? null, + setItem: (key: string, value: string) => localStorageValues.set(key, value), + removeItem: (key: string) => localStorageValues.delete(key), + clear: () => localStorageValues.clear(), + }, +}); + +const { + applyProtectedSyncPayload, + readInterruptedVaultApply, +} = await import('./localVaultBackups.ts'); + +function emptyPayload(): SyncPayload { + return { + hosts: [], + keys: [], + snippets: [], + customGroups: [], + syncedAt: 1, + }; +} + +test.beforeEach(() => { + localStorageValues.clear(); +}); + +test('protected apply preparation failure does not leave a partial-apply sentinel', async () => { + let snapshotBuilt = false; + + await assert.rejects( + () => applyProtectedSyncPayload({ + buildPreApplyPayload: () => { + snapshotBuilt = true; + return emptyPayload(); + }, + prepareApply: async () => { + throw new Error('replica unavailable'); + }, + translateProtectiveBackupFailure: (message) => message, + }), + /replica unavailable/, + ); + + assert.equal(snapshotBuilt, false); + assert.equal(readInterruptedVaultApply(), null); +}); + +test('prepared apply callback runs after the snapshot with sentinel protection', async () => { + const calls: string[] = []; + let observedSentinel = false; + + await applyProtectedSyncPayload({ + buildPreApplyPayload: () => { + calls.push('snapshot'); + return emptyPayload(); + }, + prepareApply: async () => { + calls.push('prepare'); + return async () => { + calls.push('apply'); + observedSentinel = readInterruptedVaultApply() !== null; + }; + }, + translateProtectiveBackupFailure: (message) => message, + }); + + assert.deepEqual(calls, ['prepare', 'snapshot', 'apply']); + assert.equal(observedSentinel, true); + assert.equal(readInterruptedVaultApply(), null); +}); diff --git a/application/localVaultBackups.ts b/application/localVaultBackups.ts index 87be4fd43..659677c4f 100644 --- a/application/localVaultBackups.ts +++ b/application/localVaultBackups.ts @@ -387,17 +387,34 @@ function writeApplyInProgressSentinel(record: VaultApplyInProgressRecord): void * current vault. Callers pass their own React-closure builder (hosts, * keys, port-forwarding rules) because the caller owns that state. * + * `prepareApply`, when provided, runs while the restore barrier is held but + * before the protective backup and apply-in-progress sentinel. It must not + * mutate local vault state; it returns the callback that performs the actual + * apply. This lets callers validate external state without leaving a false + * partial-apply sentinel when validation fails. + * * `translateProtectiveBackupFailure` converts the * `ProtectiveBackupUnavailableError` into a user-visible message in the * caller's locale. It runs only on the thrown-and-caught path. */ -export function applyProtectedSyncPayload(options: { +type ProtectedApplyCallback = () => void | Promise; + +export type ApplyProtectedSyncPayloadOptions = { buildPreApplyPayload: () => SyncPayload; - applyPayload: () => void | Promise; translateProtectiveBackupFailure: (message: string) => string; -}): Promise { - const { buildPreApplyPayload, applyPayload, translateProtectiveBackupFailure } = options; +} & ( + | { applyPayload: ProtectedApplyCallback; prepareApply?: never } + | { applyPayload?: never; prepareApply: () => Promise } +); + +export function applyProtectedSyncPayload( + options: ApplyProtectedSyncPayloadOptions, +): Promise { + const { buildPreApplyPayload, translateProtectiveBackupFailure } = options; return withRestoreBarrier(async () => { + const applyPayload = options.prepareApply + ? await options.prepareApply() + : options.applyPayload; const pre = buildPreApplyPayload(); let protectiveBackupId: string | null = null; try { diff --git a/application/syncPayload.test.ts b/application/syncPayload.test.ts index 4661640a7..cf75bc1a4 100644 --- a/application/syncPayload.test.ts +++ b/application/syncPayload.test.ts @@ -38,6 +38,7 @@ function installLocalStorage(): LocalStorageMock { const localStorage = installLocalStorage(); const { applyLocalVaultPayload, + prepareLocalVaultPayloadApply, applySyncPayload, buildLocalVaultPayload, buildCloudSyncPayload, @@ -1141,3 +1142,113 @@ test("applyLocalVaultPayload restores known hosts from local backups", async () assert.ok(imported); assert.deepEqual(imported.knownHosts, [knownHost("kh-backup")]); }); + +test("applyLocalVaultPayload prepares before import and commits after it succeeds", async () => { + const calls: string[] = []; + const payload: SyncPayload = { + hosts: [], + keys: [], + identities: [], + snippets: [], + customGroups: [], + syncedAt: 1, + }; + + await applyLocalVaultPayload(payload, { + importVaultData: () => { + calls.push("import"); + }, + }, { + prepareConvergentRestore: async () => { + calls.push("prepare"); + return async () => { + calls.push("commit"); + }; + }, + }); + + assert.deepEqual(calls, ["prepare", "import", "commit"]); +}); + +test("prepareLocalVaultPayloadApply does not import until the prepared callback runs", async () => { + const calls: string[] = []; + const payload: SyncPayload = { + hosts: [], + keys: [], + identities: [], + snippets: [], + customGroups: [], + syncedAt: 1, + }; + + const applyPreparedPayload = await prepareLocalVaultPayloadApply(payload, { + importVaultData: () => { + calls.push("import"); + }, + }, { + prepareConvergentRestore: async () => { + calls.push("prepare"); + return async () => { + calls.push("commit"); + }; + }, + }); + + assert.deepEqual(calls, ["prepare"]); + await applyPreparedPayload(); + assert.deepEqual(calls, ["prepare", "import", "commit"]); +}); + +test("applyLocalVaultPayload leaves local data untouched when convergent preparation fails", async () => { + let imported = false; + const payload: SyncPayload = { + hosts: [], + keys: [], + identities: [], + snippets: [], + customGroups: [], + syncedAt: 1, + }; + + await assert.rejects( + () => applyLocalVaultPayload(payload, { + importVaultData: () => { + imported = true; + }, + }, { + prepareConvergentRestore: async () => { + throw new Error("replica unavailable"); + }, + }), + /replica unavailable/, + ); + + assert.equal(imported, false); +}); + +test("applyLocalVaultPayload does not commit convergent writes when local import fails", async () => { + let committed = false; + const payload: SyncPayload = { + hosts: [], + keys: [], + identities: [], + snippets: [], + customGroups: [], + syncedAt: 1, + }; + + await assert.rejects( + () => applyLocalVaultPayload(payload, { + importVaultData: async () => { + throw new Error("local import failed"); + }, + }, { + prepareConvergentRestore: async () => async () => { + committed = true; + }, + }), + /local import failed/, + ); + + assert.equal(committed, false); +}); diff --git a/application/syncPayload.ts b/application/syncPayload.ts index 793eefe52..32bfc2ff1 100644 --- a/application/syncPayload.ts +++ b/application/syncPayload.ts @@ -92,6 +92,7 @@ import { STORAGE_KEY_PORT_FORWARDING, } from '../infrastructure/config/storageKeys'; import { isTerminalSidePanelAutoOpenTab } from '../domain/terminalSidePanelAutoOpen'; +import { prepareRestoredPayloadConvergentWrites } from './convergentSyncReplica'; // --------------------------------------------------------------------------- // Input types @@ -947,9 +948,37 @@ export function applySyncPayload( return applyPayload(payload, importers, { includeLocalOnlyData: false }); } -export function applyLocalVaultPayload( +export async function prepareLocalVaultPayloadApply( payload: SyncPayload, importers: SyncPayloadImporters, + dependencies: { + prepareConvergentRestore?: ( + payload: SyncPayload, + ) => Promise<() => Promise>; + } = {}, +): Promise<() => Promise> { + const prepareConvergentRestore = dependencies.prepareConvergentRestore + ?? prepareRestoredPayloadConvergentWrites; + const commitConvergentRestore = await prepareConvergentRestore(payload); + return async () => { + await applyPayload(payload, importers, { includeLocalOnlyData: true }); + await commitConvergentRestore(); + }; +} + +export async function applyLocalVaultPayload( + payload: SyncPayload, + importers: SyncPayloadImporters, + dependencies: { + prepareConvergentRestore?: ( + payload: SyncPayload, + ) => Promise<() => Promise>; + } = {}, ): Promise { - return applyPayload(payload, importers, { includeLocalOnlyData: true }); + const applyPreparedPayload = await prepareLocalVaultPayloadApply( + payload, + importers, + dependencies, + ); + await applyPreparedPayload(); } diff --git a/components/settings/tabs/SettingsSyncTab.tsx b/components/settings/tabs/SettingsSyncTab.tsx index 83260c091..10317bc4b 100644 --- a/components/settings/tabs/SettingsSyncTab.tsx +++ b/components/settings/tabs/SettingsSyncTab.tsx @@ -2,11 +2,11 @@ import React, { useCallback } from "react"; import type { PortForwardingRule } from "../../../domain/models"; import type { SyncPayload } from "../../../domain/sync"; import { - applyLocalVaultPayload, buildCloudSyncPayload, buildLocalVaultPayload, applySyncPayload, getEffectivePortForwardingRulesForSync, + prepareLocalVaultPayloadApply, } from "../../../application/syncPayload"; import { applyProtectedSyncPayload } from "../../../application/localVaultBackups"; import type { SyncableVaultData } from "../../../application/syncPayload"; @@ -70,8 +70,8 @@ export default function SettingsSyncTab(props: { (payload: SyncPayload) => applyProtectedSyncPayload({ buildPreApplyPayload: onBuildLocalPayload, - applyPayload: () => - applyLocalVaultPayload(payload, { + prepareApply: () => + prepareLocalVaultPayloadApply(payload, { importVaultData: importDataFromString, importPortForwardingRules, onSettingsApplied, diff --git a/docs/designs/convergent-sync-crdt.md b/docs/designs/convergent-sync-crdt.md index b2d851f09..fe9b0ead2 100644 --- a/docs/designs/convergent-sync-crdt.md +++ b/docs/designs/convergent-sync-crdt.md @@ -145,7 +145,8 @@ behavior is visible during review. ## Follow-up boundaries -The next change will define the encrypted v2 envelope, legacy baselines, -migration preview, protection snapshots, key rotation, and fail-closed protocol -rules. The final change will integrate provider read-merge-write-verify loops, -multi-window locking, conflict resolution state, and localized settings UI. +The encrypted v2 envelope, legacy baselines, migration preview, protection +snapshots, key rotation, and fail-closed protocol rules are described in +[`convergent-sync-protocol-v2.md`](./convergent-sync-protocol-v2.md). The final +change will integrate provider read-merge-write-verify loops, multi-window +locking, conflict resolution state, and localized settings UI. diff --git a/docs/designs/convergent-sync-protocol-v2.md b/docs/designs/convergent-sync-protocol-v2.md new file mode 100644 index 000000000..9ba6eaea5 --- /dev/null +++ b/docs/designs/convergent-sync-protocol-v2.md @@ -0,0 +1,121 @@ +# Convergent Sync Protocol and Migration + +Status: experimental protocol layer; provider state-machine integration and UI +remain in the final follow-up PR. + +Issue: [#2245](https://github.com/binaricat/Netcatty/issues/2245) + +## Compatibility contract + +A v2 cloud file remains a normal `SyncedFile`. Its plaintext metadata adds only +`syncSchemaVersion: 2`; the complete materialized v1 `SyncPayload`, CRDT +metadata, conflicts, and candidate values remain inside the existing +AES-256-GCM ciphertext. + +The decrypted payload keeps all v1 fields so an older Netcatty client can read +hosts, keys, snippets, settings, and other synchronized collections without a +new parser. The adjacent `convergentSync` envelope records causal metadata and +concurrent alternatives. For a visible entity field or settings leaf, the +selected winner is normally omitted from the envelope and reconstructed from +the materialized v1 field. Structural presence and position values stay inline; +they are CRDT metadata rather than duplicated user records. + +Hydration fails closed when: + +- plaintext metadata advertises an unknown or malformed schema; +- metadata and the encrypted envelope disagree; +- a materialized winner cannot be reconstructed; +- the envelope violates any core dot, context, origin, vector, or HLC + invariant; +- an unknown collection would be discarded by the current materializer. + +## Legacy import + +Initial v1-only migration downloads every connected provider and runs the +existing smart merge against each provider-specific trusted base. A provider +without a trustworthy base may be adopted as a fresh-device seed, or accepted +when it exactly matches the current merge; divergent data without a base blocks +instead of guessing whether an absent entity was deleted. Any unresolved +entity/settings conflict, unavailable provider, or shrink guard blocks +initialization. A successful result becomes one v2 CRDT lineage and is written +back as a full v1 materialized snapshot plus the compact envelope. + +If one or more providers already contain v2, their states are joined with the +CRDT join. A legacy local or provider snapshot may then contribute writes only +when a trusted materialized baseline is available. The baseline-to-snapshot +field diff is applied on an independent branch with a stable synthetic device +ID and then joined, so multiple legacy writers remain concurrent instead of +being ordered by provider iteration. Without a trustworthy baseline, upload is +blocked rather than guessing whether an absent field means deletion. + +Optional top-level collections omitted by an old client, or present only as an +in-memory `undefined` property, are treated as unsupported and left unchanged. +Explicitly present empty collections are real deletions. Arrays inside settings +remain atomic, matching the CRDT core. Every legacy branch also passes the +suspicious-shrink guard before its writes can join an existing v2 state; fields +omitted by that client inherit the trusted baseline for this safety check. +A device with no cloud entities and no trusted local baseline is treated as a +fresh install: v1 and v2 migrations seed from cloud instead of turning local +first-launch settings into edits. With a trusted baseline, an empty local +snapshot remains a causal deletion. A v1 provider selected as the fresh-device +seed still passes the same suspicious-shrink guard before it can initialize v2. + +## Local persistence and key rotation + +The canonical replica and provider-specific v2 baselines are encrypted with the +same master-derived AES-GCM key used for existing sync bases and sync snapshots. +Loading an existing v2 record is strict: corruption and unsupported schemas are +errors, never `null` fallbacks. +Provider-specific v2 baselines are invalidated together with the existing merge +base and remote anchor whenever an account, endpoint, bucket, or connection is +replaced, so a new remote identity can never inherit trust from the old one. + +Master-key rotation prepares replacement ciphertext for all derived-key sync +records before writing anything. It snapshots both existing records and absent +keys, then verifies neither changed during preparation. Only then does it commit +the new ciphertext and publish the new master configuration. A write failure +restores the exact prior ciphertext and configuration. + +The experimental enabled/paused flag is device-local and is intentionally not +part of `SyncPayload.settings`. Disabling an initialized replica pauses it; it +does not delete local or cloud metadata. Clearing v2 storage requires explicit +downgrade confirmation. + +## Backup and restore + +Local vault backups remain materialized snapshots and never carry the active +replica. Migration initialization uses the existing protected-apply transaction: +it snapshots the live vault when the user confirms, creates a required encrypted +safety backup, holds the cross-window restore barrier, applies the previewed +materialized payload, persists the canonical replica, and only then marks v2 +initialized. Edits made while the preview was open are therefore recoverable. +The sync manager must still be unlocked immediately before this transaction; +otherwise initialization fails before any backup, sentinel, or local mutation. +A crash or failure after mutation starts leaves the existing apply sentinel set +so auto-sync cannot publish a partial migration. + +Before a local backup restore mutates local data, the restored snapshot is +diffed against the current materialized replica and prepared as normal device +writes without persisting them. The replica load is therefore validated before +the protective backup and partial-apply sentinel, while the prepared writes are +committed only after every local import step succeeds. A preparation failure +leaves no sentinel because the vault is still untouched. An import failure +leaves the replica unchanged; a later replica commit failure leaves the +protected-apply sentinel set so the partial restore cannot be published. Causal +history and tombstones survive restore instead of being replaced by an unrelated +replica copied from the backup. + +Trusted legacy diffs also compare collection positions. A reorder-only edit is +converted into position-register writes for entity and string collections, +rather than disappearing because the values themselves are unchanged. +In-memory entities are normalized with the same JSON serialization semantics +as encrypted sync payloads before validation, so optional `undefined` model +fields are omitted instead of preventing migration. + +## Follow-up boundary + +This change deliberately does not replace the current provider loop. The final +PR will enable unordered provider joins, Web Locks serialization, local-first +replica persistence, three-round read-merge-write-verify uploads, conflict +resolution UI, secret masking, localized migration controls, and explicit cloud +downgrade propagation. diff --git a/domain/convergentSync/index.ts b/domain/convergentSync/index.ts index 77b6de146..4e9be28d1 100644 --- a/domain/convergentSync/index.ts +++ b/domain/convergentSync/index.ts @@ -1,5 +1,8 @@ export * from './clock'; export * from './json'; +export * from './legacy'; +export * from './migration'; +export * from './payload'; export * from './record'; export * from './register'; export * from './registerId'; diff --git a/domain/convergentSync/json.ts b/domain/convergentSync/json.ts index 33da443ee..64865b819 100644 --- a/domain/convergentSync/json.ts +++ b/domain/convergentSync/json.ts @@ -14,6 +14,19 @@ export function isJsonValue(value: unknown): value is JsonValue { return Object.values(value).every(isJsonValue); } +/** Normalize in-memory model values exactly as the encrypted JSON payload does. */ +export function normalizeJsonValue(value: unknown): JsonValue { + const serialized = JSON.stringify(value); + if (serialized === undefined) { + throw new TypeError('Value cannot be represented as JSON'); + } + const normalized: unknown = JSON.parse(serialized); + if (!isJsonValue(normalized)) { + throw new TypeError('Value cannot be represented as JSON'); + } + return normalized; +} + export function cloneJson(value: T): T { if (Array.isArray(value)) { return value.map((item) => cloneJson(item)) as T; diff --git a/domain/convergentSync/legacy.ts b/domain/convergentSync/legacy.ts new file mode 100644 index 000000000..ac24b4094 --- /dev/null +++ b/domain/convergentSync/legacy.ts @@ -0,0 +1,223 @@ +import type { SyncPayload } from '../sync'; +import { normalizeJsonValue } from './json'; +import { encodeSettingPath } from './serialization'; +import { applyConvergentMutations } from './state'; +import type { + ConvergentMutation, + ConvergentSyncStateV2, + JsonValue, +} from './types'; +import { + CONVERGENT_ENTITY_COLLECTIONS, + CONVERGENT_STRING_COLLECTIONS, +} from './payload'; + +function isRecord(value: unknown): value is Record { + return Boolean(value) && typeof value === 'object' && !Array.isArray(value); +} + +function stableValue(value: unknown): unknown { + if (Array.isArray(value)) return value.map(stableValue); + if (isRecord(value)) { + return Object.fromEntries( + Object.keys(value).sort().map((key) => [key, stableValue(value[key])]), + ); + } + return value; +} + +function fingerprint(value: unknown): string { + return JSON.stringify(stableValue(value)); +} + +function hasDefinedOwnProperty(payload: SyncPayload, property: string): boolean { + const record = payload as unknown as Record; + return Object.prototype.hasOwnProperty.call(record, property) + && record[property] !== undefined; +} + +/** Preserve fields that an older client did not provide for safety checks. */ +export function inheritOmittedLegacySyncFields( + baseline: SyncPayload, + legacy: SyncPayload, +): SyncPayload { + const result = { ...legacy } as SyncPayload; + const resultRecord = result as unknown as Record; + const baselineRecord = baseline as unknown as Record; + for (const property of [ + ...CONVERGENT_ENTITY_COLLECTIONS, + ...CONVERGENT_STRING_COLLECTIONS, + 'settings', + ]) { + if (!hasDefinedOwnProperty(legacy, property)) { + resultRecord[property] = baselineRecord[property]; + } + } + return result; +} + +function normalizedEntityValue( + collection: string, + id: string, + value: Record, +): Extract['value'] { + try { + const normalized = normalizeJsonValue({ ...value, id }); + if (!isRecord(normalized)) throw new TypeError('Entity is not an object'); + return normalized as Extract['value']; + } catch { + throw new Error(`${collection}/${id} contains a value that cannot be represented as JSON`); + } +} + +function entityId(collection: string, value: Record): string | undefined { + const id = collection === 'groupConfigs' ? value.path : value.id; + return typeof id === 'string' && id.length > 0 ? id : undefined; +} + +function entityMap(payload: SyncPayload, collection: string): Map> { + const values = (payload as unknown as Record)[collection]; + const result = new Map>(); + if (!Array.isArray(values)) return result; + for (const value of values) { + if (!isRecord(value)) continue; + const id = entityId(collection, value); + if (id) result.set(id, value); + } + return result; +} + +function stringSet(payload: SyncPayload, collection: string): Set { + const values = (payload as unknown as Record)[collection]; + return new Set(Array.isArray(values) ? values.filter((value): value is string => typeof value === 'string') : []); +} + +function positionMap(values: Iterable): Map { + const positions = new Map(); + let position = 0; + for (const value of values) { + positions.set(value, position); + position += 1; + } + return positions; +} + +function flattenSettings( + value: unknown, + path: string[] = [], + output: Map = new Map(), +): Map { + if (isRecord(value) && Object.keys(value).length > 0) { + for (const key of Object.keys(value).sort()) { + flattenSettings(value[key], [...path, key], output); + } + } else if (path.length > 0 && value !== undefined) { + output.set(encodeSettingPath(path), { path, value: value as JsonValue }); + } + return output; +} + +/** Compare only cloud materialized data; timestamps and reliability metadata are transport details. */ +export function cloudSyncPayloadsEqual(left: SyncPayload, right: SyncPayload): boolean { + const project = (payload: SyncPayload) => ({ + ...Object.fromEntries( + [...CONVERGENT_ENTITY_COLLECTIONS, ...CONVERGENT_STRING_COLLECTIONS] + .map((key) => [key, (payload as unknown as Record)[key] ?? []]), + ), + settings: payload.settings ?? {}, + }); + return fingerprint(project(left)) === fingerprint(project(right)); +} + +/** + * Convert a trusted v1 baseline diff into deterministic CRDT writes. A missing + * or undefined optional top-level collection is treated as "unsupported by + * that client", while an explicitly present empty collection is a real + * deletion. + */ +export function diffLegacySyncPayload( + baseline: SyncPayload, + legacy: SyncPayload, +): ConvergentMutation[] { + const mutations: ConvergentMutation[] = []; + for (const collection of CONVERGENT_ENTITY_COLLECTIONS) { + if (!hasDefinedOwnProperty(legacy, collection)) continue; + const before = entityMap(baseline, collection); + const after = entityMap(legacy, collection); + const beforePositions = positionMap(before.keys()); + const afterPositions = positionMap(after.keys()); + const ids = new Set([...before.keys(), ...after.keys()]); + for (const id of [...ids].sort()) { + const previous = before.get(id); + const next = after.get(id); + if (previous && !next) { + mutations.push({ kind: 'entity-delete', collection, entityId: id }); + } else if ( + next + && ( + !previous + || fingerprint(previous) !== fingerprint(next) + || beforePositions.get(id) !== afterPositions.get(id) + ) + ) { + mutations.push({ + kind: 'entity-upsert', + collection, + entityId: id, + value: normalizedEntityValue(collection, id, next), + position: afterPositions.get(id), + }); + } + } + } + for (const collection of CONVERGENT_STRING_COLLECTIONS) { + if (!hasDefinedOwnProperty(legacy, collection)) continue; + const before = stringSet(baseline, collection); + const after = stringSet(legacy, collection); + const beforePositions = positionMap(before); + const afterPositions = positionMap(after); + for (const value of [...before].sort()) { + if (!after.has(value)) mutations.push({ kind: 'string-entry-delete', collection, value }); + } + for (const value of [...after].sort()) { + if (!before.has(value) || beforePositions.get(value) !== afterPositions.get(value)) { + mutations.push({ + kind: 'string-entry-add', + collection, + value, + position: afterPositions.get(value), + }); + } + } + } + if (hasDefinedOwnProperty(legacy, 'settings')) { + const before = flattenSettings(baseline.settings); + const after = flattenSettings(legacy.settings); + const paths = new Set([...before.keys(), ...after.keys()]); + for (const encodedPath of [...paths].sort()) { + const previous = before.get(encodedPath); + const next = after.get(encodedPath); + if (previous && !next) { + mutations.push({ kind: 'setting-delete', path: previous.path }); + } else if (next && (!previous || fingerprint(previous.value) !== fingerprint(next.value))) { + mutations.push({ kind: 'setting-set', path: next.path, value: next.value }); + } + } + } + return mutations; +} + +export function applyLegacySyncPayload( + state: ConvergentSyncStateV2, + baseline: SyncPayload, + legacy: SyncPayload, + syntheticDeviceId: string, + now: number, +): ConvergentSyncStateV2 { + return applyConvergentMutations( + state, + syntheticDeviceId, + diffLegacySyncPayload(baseline, legacy), + now, + ); +} diff --git a/domain/convergentSync/migration.ts b/domain/convergentSync/migration.ts new file mode 100644 index 000000000..0540d5637 --- /dev/null +++ b/domain/convergentSync/migration.ts @@ -0,0 +1,291 @@ +import { + CLOUD_SYNC_PAYLOAD_ENTITY_KEYS, + hasSyncPayloadEntityData, + type CloudProvider, + type ConvergentMigrationPreview, + type ConvergentProviderMigrationStatus, + type SyncFileMeta, + type SyncPayload, +} from '../sync'; +import { detectSuspiciousShrink } from '../syncGuards'; +import { mergeSyncPayloads } from '../syncMerge'; +import { summarizeSyncChanges } from '../syncReliability'; +import { mergeConvergentSyncStates, materializeConvergentSyncState } from './state'; +import type { ConvergentSyncStateV2 } from './types'; +import { + cloudSyncPayloadsEqual, + applyLegacySyncPayload, + inheritOmittedLegacySyncFields, +} from './legacy'; +import { + CONVERGENT_ENTITY_COLLECTIONS, + CONVERGENT_STRING_COLLECTIONS, + createConvergentSyncStateFromPayload, + hydrateConvergentSyncEnvelope, + materializeSyncPayloadFromConvergentState, + withConvergentSyncEnvelope, +} from './payload'; + +/* + * A local snapshot with no cloud entities and no trusted base is a fresh + * device, not an untrusted deletion. Settings are intentionally ignored here + * because first-launch defaults must not prevent adoption of an existing v2 + * vault. Once a trusted base exists, an empty snapshot remains a real deletion. + */ +function shouldIncludeLegacyLocalSource( + payload: SyncPayload, + trustedBaseline: SyncPayload | null, +): boolean { + return trustedBaseline !== null + || hasSyncPayloadEntityData(payload, CLOUD_SYNC_PAYLOAD_ENTITY_KEYS); +} + +export type ConvergentMigrationProviderInput = + | { provider: CloudProvider; status: 'empty' } + | { provider: CloudProvider; status: 'unavailable'; message: string } + | { + provider: CloudProvider; + status: 'ready'; + meta: SyncFileMeta; + payload: SyncPayload; + trustedBaseline: SyncPayload | null; + }; + +export interface ConvergentMigrationPlan { + preview: ConvergentMigrationPreview; + state: ConvergentSyncStateV2 | null; + payload: SyncPayload | null; +} + +function runtimeSchema(meta: SyncFileMeta): 1 | 2 | 'future' | 'invalid' { + const value = (meta as { syncSchemaVersion?: unknown }).syncSchemaVersion; + if (value === undefined) return 1; + if (value === 2) return 2; + if (typeof value === 'number' && Number.isInteger(value) && value > 2) return 'future'; + return 'invalid'; +} + +function countSettingsLeaves(value: unknown, root = true): number { + if (!value || typeof value !== 'object' || Array.isArray(value)) return value === undefined ? 0 : 1; + const entries = Object.values(value as Record); + if (entries.length === 0) return root ? 0 : 1; + return entries.reduce( + (total, child) => total + countSettingsLeaves(child, false), + 0, + ); +} + +function entityCount(payload: SyncPayload, key: string): number { + const value = (payload as unknown as Record)[key]; + return Array.isArray(value) ? value.length : 0; +} + +function statusFor( + input: ConvergentMigrationProviderInput, + schemaVersion: ConvergentProviderMigrationStatus['schemaVersion'], + status: ConvergentProviderMigrationStatus['status'], + message?: string, +): ConvergentProviderMigrationStatus { + return { + provider: input.provider, + status, + schemaVersion, + entityCount: input.status === 'ready' + ? [...CONVERGENT_ENTITY_COLLECTIONS, ...CONVERGENT_STRING_COLLECTIONS] + .reduce((total, key) => total + entityCount(input.payload, key), 0) + : 0, + hasTrustedBaseline: input.status === 'ready' && input.trustedBaseline !== null, + ...(message ? { message } : {}), + }; +} + +export function planConvergentSyncMigration(options: { + localPayload: SyncPayload; + localTrustedBaseline: SyncPayload | null; + providers: ConvergentMigrationProviderInput[]; + deviceId: string; + now: number; +}): ConvergentMigrationPlan { + const providers = [...options.providers].sort((left, right) => left.provider.localeCompare(right.provider)); + const blockedReasons: string[] = []; + const providerStatuses: ConvergentProviderMigrationStatus[] = []; + const shrinkFindings: ConvergentMigrationPreview['shrinkFindings'] = []; + const v1Inputs: Extract[] = []; + const v2Inputs: Array & { state: ConvergentSyncStateV2 }> = []; + + for (const input of providers) { + if (input.status === 'empty') { + providerStatuses.push(statusFor(input, 1, 'empty')); + continue; + } + if (input.status === 'unavailable') { + blockedReasons.push(`${input.provider}: ${input.message}`); + providerStatuses.push(statusFor(input, 'invalid', 'unavailable', input.message)); + continue; + } + const schema = runtimeSchema(input.meta); + if (schema === 'future' || schema === 'invalid') { + const message = schema === 'future' + ? 'Provider contains a newer sync schema' + : 'Provider contains invalid sync schema metadata'; + blockedReasons.push(`${input.provider}: ${message}`); + providerStatuses.push(statusFor(input, schema, 'blocked', message)); + continue; + } + if (schema === 1) { + if (input.payload.convergentSync) { + const message = 'Provider envelope does not match its plaintext schema metadata'; + blockedReasons.push(`${input.provider}: ${message}`); + providerStatuses.push(statusFor(input, 'invalid', 'blocked', message)); + } else { + v1Inputs.push(input); + providerStatuses.push(statusFor(input, 1, 'ready')); + } + continue; + } + try { + if (!input.payload.convergentSync) throw new Error('missing convergent envelope'); + const state = hydrateConvergentSyncEnvelope(input.payload.convergentSync, input.payload); + v2Inputs.push({ ...input, state }); + providerStatuses.push(statusFor(input, 2, 'ready')); + } catch (error) { + const message = `Damaged convergent envelope: ${error instanceof Error ? error.message : String(error)}`; + blockedReasons.push(`${input.provider}: ${message}`); + providerStatuses.push(statusFor(input, 'invalid', 'blocked', message)); + } + } + + let state: ConvergentSyncStateV2 | null = null; + let materialized: SyncPayload | null = null; + + if (blockedReasons.length === 0 && v2Inputs.length === 0) { + const includeLocalSource = shouldIncludeLegacyLocalSource( + options.localPayload, + options.localTrustedBaseline, + ); + const seedFromProvider = !includeLocalSource && v1Inputs.length > 0; + let merged = seedFromProvider ? v1Inputs[0].payload : options.localPayload; + if (seedFromProvider) { + const seed = v1Inputs[0]; + const shrink = detectSuspiciousShrink( + seed.payload, + seed.trustedBaseline, + seed.payload, + ); + if (shrink.suspicious) { + shrinkFindings.push({ provider: seed.provider, finding: shrink }); + blockedReasons.push(`${seed.provider}: legacy migration would remove too many entities`); + } + } + const remainingInputs = seedFromProvider ? v1Inputs.slice(1) : v1Inputs; + for (const input of remainingInputs) { + if (!input.trustedBaseline) { + if (!cloudSyncPayloadsEqual(merged, input.payload)) { + blockedReasons.push(`${input.provider}: no trusted legacy baseline is available`); + } + continue; + } + const result = mergeSyncPayloads(input.trustedBaseline, merged, input.payload); + const changeSummary = summarizeSyncChanges( + input.trustedBaseline, + merged, + input.payload, + ); + if (result.hadConflicts || changeSummary.hasConflicts) { + blockedReasons.push(`${input.provider}: legacy smart merge has unresolved conflicts`); + } + const shrink = detectSuspiciousShrink(result.payload, input.trustedBaseline, input.payload); + if (shrink.suspicious) { + shrinkFindings.push({ provider: input.provider, finding: shrink }); + blockedReasons.push(`${input.provider}: legacy migration would remove too many entities`); + } + merged = result.payload; + } + if (blockedReasons.length === 0) { + state = createConvergentSyncStateFromPayload(merged, options.deviceId, options.now); + materialized = materializeSyncPayloadFromConvergentState(state, { + syncedAt: options.now, + syncMeta: merged.syncMeta, + }); + } + } else if (blockedReasons.length === 0) { + state = v2Inputs.map((input) => input.state).reduce(mergeConvergentSyncStates); + const joinedPayload = materializeSyncPayloadFromConvergentState(state, { syncedAt: options.now }); + const legacySources: Array<{ + id: string; + payload: SyncPayload; + baseline: SyncPayload | null; + now: number; + provider?: CloudProvider; + }> = [ + ...(shouldIncludeLegacyLocalSource( + options.localPayload, + options.localTrustedBaseline, + ) ? [{ + id: `legacy-local:${options.deviceId}`, + payload: options.localPayload, + baseline: options.localTrustedBaseline, + now: options.now, + }] : []), + ...v1Inputs.map((input) => ({ + id: `legacy-provider:${input.provider}:${input.meta.deviceId}`, + payload: input.payload, + baseline: input.trustedBaseline, + now: input.meta.updatedAt, + provider: input.provider, + })), + ]; + const branches: ConvergentSyncStateV2[] = []; + for (const source of legacySources) { + if (cloudSyncPayloadsEqual(source.payload, joinedPayload)) continue; + if (!source.baseline) { + blockedReasons.push(`${source.id}: no trusted legacy baseline is available`); + continue; + } + const shrink = detectSuspiciousShrink( + inheritOmittedLegacySyncFields(source.baseline, source.payload), + source.baseline, + ); + if (shrink.suspicious) { + if (source.provider) { + shrinkFindings.push({ provider: source.provider, finding: shrink }); + } + blockedReasons.push(`${source.id}: legacy migration would remove too many entities`); + continue; + } + branches.push(applyLegacySyncPayload(state, source.baseline, source.payload, source.id, source.now)); + } + if (blockedReasons.length === 0) { + state = branches.reduce(mergeConvergentSyncStates, state); + materialized = materializeSyncPayloadFromConvergentState(state, { syncedAt: options.now }); + } + } + + const conflicts = state ? materializeConvergentSyncState(state).conflicts : []; + if (conflicts.length > 0) blockedReasons.push('The convergent state contains unresolved field conflicts'); + const canInitialize = blockedReasons.length === 0 && state !== null && materialized !== null; + const payload = canInitialize && state + ? withConvergentSyncEnvelope(state, { syncedAt: options.now, syncMeta: materialized?.syncMeta }) + : null; + const previewPayload = materialized ?? options.localPayload; + const entityCounts = Object.fromEntries( + [...CONVERGENT_ENTITY_COLLECTIONS, ...CONVERGENT_STRING_COLLECTIONS] + .map((key) => [key, entityCount(previewPayload, key)]), + ) as ConvergentMigrationPreview['entityCounts']; + return { + preview: { + schemaVersion: 2, + canInitialize, + entityCounts, + settingsLeafCount: countSettingsLeaves(previewPayload.settings), + conflictCount: conflicts.length, + conflicts, + shrinkFindings, + providers: providerStatuses, + oldClientCompatibility: 'materialized-v1-snapshot', + blockedReasons, + }, + state: canInitialize ? state : null, + payload, + }; +} diff --git a/domain/convergentSync/payload.ts b/domain/convergentSync/payload.ts new file mode 100644 index 000000000..53c07903b --- /dev/null +++ b/domain/convergentSync/payload.ts @@ -0,0 +1,566 @@ +import type { + CloudSyncPayloadEntityKey, + SyncFileMeta, + SyncPayload, + SyncReliabilityMeta, +} from '../sync'; +import { dotKey } from './clock'; +import { + cloneJson, + isJsonValue, + jsonValuesEqual, + normalizeJsonValue, +} from './json'; +import { selectRegisterWinner, isTombstoneCandidate } from './register'; +import { createEmptyRecord, setOwnRecordValue } from './record'; +import { + assertValidConvergentSyncState, + canonicalizeConvergentSyncState, + decodeSettingPath, +} from './serialization'; +import { + applyConvergentMutations, + createConvergentSyncState, + materializeConvergentSyncState, +} from './state'; +import type { + CollectionPosition, + ConvergentEnvelopeCandidate, + ConvergentEnvelopeCollectionState, + ConvergentEnvelopeEntityState, + ConvergentEnvelopeRegister, + ConvergentEnvelopeStateV2, + ConvergentEnvelopeStringCollectionState, + ConvergentEnvelopeStringEntryState, + ConvergentMutation, + ConvergentSyncEnvelopeV2, + ConvergentSyncStateV2, + JsonObject, + JsonValue, + MultiValueRegister, + RegisterCandidate, +} from './types'; + +export const CONVERGENT_ENTITY_COLLECTIONS = [ + 'hosts', + 'keys', + 'identities', + 'proxyProfiles', + 'snippets', + 'notes', + 'portForwardingRules', + 'groupConfigs', +] as const satisfies readonly CloudSyncPayloadEntityKey[]; + +export const CONVERGENT_STRING_COLLECTIONS = [ + 'customGroups', + 'snippetPackages', + 'noteGroups', +] as const satisfies readonly CloudSyncPayloadEntityKey[]; + +type ConvergentEntityCollection = typeof CONVERGENT_ENTITY_COLLECTIONS[number]; +type ConvergentStringCollection = typeof CONVERGENT_STRING_COLLECTIONS[number]; + +const ENTITY_COLLECTION_SET = new Set(CONVERGENT_ENTITY_COLLECTIONS); +const STRING_COLLECTION_SET = new Set(CONVERGENT_STRING_COLLECTIONS); + +function isRecord(value: unknown): value is Record { + return Boolean(value) && typeof value === 'object' && !Array.isArray(value); +} + +function toJsonValue(value: unknown, label: string): JsonValue { + try { + return normalizeJsonValue(value); + } catch { + throw new Error(`${label} contains a value that cannot be represented as JSON`); + } +} + +function entityId(collection: ConvergentEntityCollection, value: Record): string { + const raw = collection === 'groupConfigs' ? value.path : value.id; + if (typeof raw !== 'string' || raw.length === 0) { + throw new Error(`${collection} contains an entity without a stable identifier`); + } + return raw; +} + +function entityJson( + collection: ConvergentEntityCollection, + value: Record, +): JsonObject { + const id = entityId(collection, value); + const json = toJsonValue(value, `${collection}/${id}`); + if (!isRecord(json)) throw new Error(`${collection}/${id} must be a JSON object`); + return { + ...json, + id, + } as JsonObject; +} + +function payloadEntityValues( + payload: SyncPayload, + collection: ConvergentEntityCollection, +): Record[] { + const values = payload[collection]; + return Array.isArray(values) ? values as unknown as Record[] : []; +} + +function payloadStringValues( + payload: SyncPayload, + collection: ConvergentStringCollection, +): string[] { + const values = payload[collection]; + return Array.isArray(values) + ? values.filter((value): value is string => typeof value === 'string') + : []; +} + +function appendSettingMutations( + value: unknown, + path: string[], + mutations: ConvergentMutation[], +): void { + if (isRecord(value) && Object.keys(value).length > 0) { + for (const key of Object.keys(value).sort()) { + appendSettingMutations(value[key], [...path, key], mutations); + } + return; + } + if (path.length === 0 || value === undefined) return; + mutations.push({ + kind: 'setting-set', + path, + value: toJsonValue(value, `settings.${path.join('.')}`), + }); +} + +export function syncPayloadToConvergentMutations(payload: SyncPayload): ConvergentMutation[] { + const mutations: ConvergentMutation[] = []; + for (const collection of CONVERGENT_ENTITY_COLLECTIONS) { + payloadEntityValues(payload, collection).forEach((value, position) => { + const id = entityId(collection, value); + mutations.push({ + kind: 'entity-upsert', + collection, + entityId: id, + value: entityJson(collection, value), + position, + }); + }); + } + for (const collection of CONVERGENT_STRING_COLLECTIONS) { + payloadStringValues(payload, collection).forEach((value, position) => { + mutations.push({ kind: 'string-entry-add', collection, value, position }); + }); + } + appendSettingMutations(payload.settings, [], mutations); + return mutations; +} + +export function createConvergentSyncStateFromPayload( + payload: SyncPayload, + deviceId: string, + now: number, +): ConvergentSyncStateV2 { + return applyConvergentMutations( + createConvergentSyncState(), + deviceId, + syncPayloadToConvergentMutations(payload), + now, + ); +} + +function requireKnownCollections(state: ConvergentSyncStateV2): void { + for (const collection of Object.keys(state.collections)) { + if (!ENTITY_COLLECTION_SET.has(collection)) { + throw new Error(`Unsupported convergent entity collection: ${collection}`); + } + } + for (const collection of Object.keys(state.stringCollections)) { + if (!STRING_COLLECTION_SET.has(collection)) { + throw new Error(`Unsupported convergent string collection: ${collection}`); + } + } +} + +function collectionValues( + collections: Record, + collection: ConvergentEntityCollection, +): JsonObject[] { + return collections[collection] ?? []; +} + +function typedCollection( + collections: Record, + collection: Exclude, +): T[] { + return collectionValues(collections, collection) as unknown as T[]; +} + +export function materializeSyncPayloadFromConvergentState( + state: ConvergentSyncStateV2, + options: { + syncedAt: number; + syncMeta?: SyncReliabilityMeta; + }, +): SyncPayload { + requireKnownCollections(state); + const materialized = materializeConvergentSyncState(state); + const groupConfigs = collectionValues(materialized.collections, 'groupConfigs').map((value) => { + const { id: _id, ...groupConfig } = value; + return groupConfig as unknown as import('../models').GroupConfig; + }); + const settings = Object.keys(materialized.settings).length > 0 + ? materialized.settings as unknown as NonNullable + : undefined; + return { + hosts: typedCollection(materialized.collections, 'hosts'), + keys: typedCollection(materialized.collections, 'keys'), + identities: typedCollection(materialized.collections, 'identities'), + proxyProfiles: typedCollection(materialized.collections, 'proxyProfiles'), + snippets: typedCollection(materialized.collections, 'snippets'), + customGroups: materialized.stringCollections.customGroups ?? [], + snippetPackages: materialized.stringCollections.snippetPackages ?? [], + notes: typedCollection(materialized.collections, 'notes'), + noteGroups: materialized.stringCollections.noteGroups ?? [], + portForwardingRules: typedCollection(materialized.collections, 'portForwardingRules'), + groupConfigs, + settings, + syncedAt: options.syncedAt, + ...(options.syncMeta ? { syncMeta: options.syncMeta } : {}), + }; +} + +function materializedEntity( + payload: SyncPayload, + collection: string, + id: string, +): Record | undefined { + if (!ENTITY_COLLECTION_SET.has(collection)) return undefined; + const values = payloadEntityValues(payload, collection as ConvergentEntityCollection); + return values.find((value) => entityId(collection as ConvergentEntityCollection, value) === id); +} + +function nestedSetting(payload: SyncPayload, path: string[]): unknown { + let value: unknown = payload.settings; + for (const segment of path) { + if (!isRecord(value) || !Object.prototype.hasOwnProperty.call(value, segment)) return undefined; + value = value[segment]; + } + return value; +} + +function stableUnknown(value: unknown): unknown { + if (Array.isArray(value)) return value.map(stableUnknown); + if (isRecord(value)) { + return Object.fromEntries( + Object.keys(value).sort().map((key) => [key, stableUnknown(value[key])]), + ); + } + return value; +} + +function materializedCloudFingerprint(payload: SyncPayload): string { + return JSON.stringify(stableUnknown({ + ...Object.fromEntries( + CONVERGENT_ENTITY_COLLECTIONS.map((collection) => [ + collection, + payloadEntityValues(payload, collection), + ]), + ), + ...Object.fromEntries( + CONVERGENT_STRING_COLLECTIONS.map((collection) => [ + collection, + payloadStringValues(payload, collection), + ]), + ), + settings: payload.settings ?? {}, + })); +} + +function assertMaterializedPayloadMatchesState( + state: ConvergentSyncStateV2, + payload: SyncPayload, +): void { + const expected = materializeSyncPayloadFromConvergentState(state, { syncedAt: 0 }); + if (materializedCloudFingerprint(expected) !== materializedCloudFingerprint(payload)) { + throw new Error('Convergent envelope does not match its materialized v1 snapshot'); + } +} + +function compactRegister( + register: MultiValueRegister, + materializedValue?: unknown, + allowMaterializedValue = false, +): ConvergentEnvelopeRegister { + const winner = selectRegisterWinner(register); + return { + candidates: register.candidates.map((candidate): ConvergentEnvelopeCandidate => { + const base = { + dot: { ...candidate.dot }, + context: candidate.context.map((dot) => ({ ...dot })), + hlc: { ...candidate.hlc }, + }; + if (isTombstoneCandidate(candidate)) return { ...base, tombstone: true }; + if ( + allowMaterializedValue + && winner + && dotKey(candidate.dot) === dotKey(winner.dot) + && isJsonValue(materializedValue) + && jsonValuesEqual(candidate.value, materializedValue) + ) { + return { ...base, materialized: true }; + } + return { ...base, value: cloneJson(candidate.value) }; + }), + }; +} + +export function createConvergentSyncEnvelope( + state: ConvergentSyncStateV2, + materializedPayload: SyncPayload, +): ConvergentSyncEnvelopeV2 { + const canonical = canonicalizeConvergentSyncState(state); + requireKnownCollections(canonical); + assertMaterializedPayloadMatchesState(canonical, materializedPayload); + const collections = createEmptyRecord(); + for (const [collectionName, collection] of Object.entries(canonical.collections)) { + const entities = createEmptyRecord(); + for (const [id, entity] of Object.entries(collection.entities)) { + const materialized = materializedEntity(materializedPayload, collectionName, id); + const fields = createEmptyRecord(); + for (const [field, register] of Object.entries(entity.fields)) { + setOwnRecordValue(fields, field, compactRegister(register, materialized?.[field], true)); + } + setOwnRecordValue(entities, id, { + presence: compactRegister(entity.presence), + ...(entity.position ? { position: compactRegister(entity.position) } : {}), + fields, + }); + } + setOwnRecordValue(collections, collectionName, { entities }); + } + const settings = createEmptyRecord(); + for (const [encodedPath, register] of Object.entries(canonical.settings)) { + setOwnRecordValue(settings, encodedPath, compactRegister( + register, + nestedSetting(materializedPayload, decodeSettingPath(encodedPath)), + true, + )); + } + const stringCollections = createEmptyRecord(); + for (const [collectionName, collection] of Object.entries(canonical.stringCollections)) { + const entries = createEmptyRecord(); + for (const [value, entry] of Object.entries(collection.entries)) { + setOwnRecordValue(entries, value, { + presence: compactRegister(entry.presence), + ...(entry.position ? { position: compactRegister(entry.position) } : {}), + }); + } + setOwnRecordValue(stringCollections, collectionName, { entries }); + } + return { + schemaVersion: 2, + encoding: 'materialized-winner-v1', + state: { + vector: Object.fromEntries(Object.entries(canonical.vector)), + dotOrigins: Object.fromEntries( + Object.entries(canonical.dotOrigins).map(([deviceId, origins]) => [deviceId, { ...origins }]), + ), + hlc: { ...canonical.hlc }, + collections, + settings, + stringCollections, + }, + }; +} + +function hydrateRegister( + register: ConvergentEnvelopeRegister, + materializedValue: unknown, + label: string, +): MultiValueRegister { + if (!register || !Array.isArray(register.candidates) || register.candidates.length === 0) { + throw new Error(`${label} has no candidates`); + } + return { + candidates: register.candidates.map((candidate, index): RegisterCandidate => { + const candidateLabel = `${label}.candidates[${index}]`; + const base = { + dot: { ...candidate.dot }, + context: candidate.context.map((dot) => ({ ...dot })), + hlc: { ...candidate.hlc }, + }; + if ( + candidate.tombstone !== undefined + && candidate.tombstone !== true + && candidate.tombstone !== false + ) { + throw new Error(`${candidateLabel} has an invalid tombstone marker`); + } + if ( + 'materialized' in candidate + && candidate.materialized !== undefined + && candidate.materialized !== true + ) { + throw new Error(`${candidateLabel} has an invalid materialized marker`); + } + if (candidate.tombstone === true) { + if ('materialized' in candidate || 'value' in candidate) { + throw new Error(`${candidateLabel} tombstone contains a value marker`); + } + return { ...base, tombstone: true }; + } + if ('materialized' in candidate && candidate.materialized === true) { + if ('value' in candidate || !isJsonValue(materializedValue)) { + throw new Error(`${candidateLabel} cannot reconstruct its materialized value`); + } + return { ...base, value: cloneJson(materializedValue) as T }; + } + if (!('value' in candidate) || !isJsonValue(candidate.value)) { + throw new Error(`${candidateLabel} is missing a JSON value`); + } + return { ...base, value: cloneJson(candidate.value) as T }; + }), + }; +} + +function envelopeState(value: unknown): ConvergentEnvelopeStateV2 { + if (!isRecord(value)) throw new Error('Convergent sync envelope state is invalid'); + return value as unknown as ConvergentEnvelopeStateV2; +} + +export function hydrateConvergentSyncEnvelope( + envelope: ConvergentSyncEnvelopeV2, + materializedPayload: SyncPayload, +): ConvergentSyncStateV2 { + if ( + !envelope + || envelope.schemaVersion !== 2 + || envelope.encoding !== 'materialized-winner-v1' + ) { + throw new Error('Unsupported convergent sync envelope'); + } + const encoded = envelopeState(envelope.state); + const collections = createEmptyRecord(); + for (const [collectionName, collection] of Object.entries(encoded.collections ?? {})) { + if (!ENTITY_COLLECTION_SET.has(collectionName) || !isRecord(collection?.entities)) { + throw new Error(`Unsupported or invalid convergent collection: ${collectionName}`); + } + const entities = createEmptyRecord(); + for (const [id, entity] of Object.entries(collection.entities)) { + if (!isRecord(entity) || !isRecord(entity.fields)) { + throw new Error(`Invalid convergent entity: ${collectionName}/${id}`); + } + const materialized = materializedEntity(materializedPayload, collectionName, id); + const fields = createEmptyRecord(); + for (const [field, register] of Object.entries(entity.fields)) { + setOwnRecordValue(fields, field, hydrateRegister( + register, + materialized?.[field], + `${collectionName}/${id}/${field}`, + )); + } + setOwnRecordValue(entities, id, { + presence: hydrateRegister(entity.presence, true, `${collectionName}/${id}/presence`), + ...(entity.position + ? { position: hydrateRegister(entity.position, undefined, `${collectionName}/${id}/position`) } + : {}), + fields, + }); + } + setOwnRecordValue(collections, collectionName, { entities }); + } + const settings = createEmptyRecord(); + for (const [path, register] of Object.entries(encoded.settings ?? {})) { + setOwnRecordValue(settings, path, hydrateRegister( + register, + nestedSetting(materializedPayload, decodeSettingPath(path)), + `settings/${path}`, + )); + } + const stringCollections = createEmptyRecord(); + for (const [collectionName, collection] of Object.entries(encoded.stringCollections ?? {})) { + if (!STRING_COLLECTION_SET.has(collectionName) || !isRecord(collection?.entries)) { + throw new Error(`Unsupported or invalid convergent string collection: ${collectionName}`); + } + const entries = createEmptyRecord(); + for (const [value, entry] of Object.entries(collection.entries)) { + if (!isRecord(entry)) throw new Error(`Invalid convergent string entry: ${collectionName}/${value}`); + setOwnRecordValue(entries, value, { + presence: hydrateRegister(entry.presence, true, `${collectionName}/${value}/presence`), + ...(entry.position + ? { position: hydrateRegister(entry.position, undefined, `${collectionName}/${value}/position`) } + : {}), + }); + } + setOwnRecordValue(stringCollections, collectionName, { entries }); + } + const state: ConvergentSyncStateV2 = { + schemaVersion: 2, + vector: encoded.vector, + dotOrigins: encoded.dotOrigins, + hlc: encoded.hlc, + collections, + settings, + stringCollections, + }; + assertValidConvergentSyncState(state); + const canonical = canonicalizeConvergentSyncState(state); + assertMaterializedPayloadMatchesState(canonical, materializedPayload); + return canonical; +} + +export function withConvergentSyncEnvelope( + state: ConvergentSyncStateV2, + options: { syncedAt: number; syncMeta?: SyncReliabilityMeta }, +): SyncPayload { + const payload = materializeSyncPayloadFromConvergentState(state, options); + return { + ...payload, + convergentSync: createConvergentSyncEnvelope(state, payload), + }; +} + +export function validateConvergentSyncPayload( + meta: Pick, + payload: SyncPayload, +): ConvergentSyncStateV2 | null { + const schemaVersion = (meta as { syncSchemaVersion?: unknown }).syncSchemaVersion; + if (schemaVersion === undefined) { + if (payload.convergentSync !== undefined) { + throw new Error('Convergent sync envelope is present without schema metadata'); + } + return null; + } + if (schemaVersion !== 2) { + throw new Error(`Unsupported sync schema version: ${String(schemaVersion)}`); + } + if (!payload.convergentSync) { + throw new Error('Sync schema v2 payload is missing its convergent envelope'); + } + return hydrateConvergentSyncEnvelope(payload.convergentSync, payload); +} + +/** Prevent the legacy snapshot writer from silently erasing v2/future metadata. */ +export function assertConvergentSyncWriteCompatible( + remoteMeta: Pick | null | undefined, + outgoingPayload: SyncPayload, +): void { + if (!remoteMeta) return; + const remoteSchema = (remoteMeta as { syncSchemaVersion?: unknown }).syncSchemaVersion; + if (remoteSchema === undefined) return; + if (remoteSchema !== 2) { + throw new Error(`Cannot overwrite unsupported sync schema version: ${String(remoteSchema)}`); + } + if (!outgoingPayload.convergentSync) { + throw new Error( + 'Cloud data uses convergent sync v2. Enable or migrate convergent sync before uploading.', + ); + } +} + +export function stripConvergentSyncEnvelope(payload: SyncPayload): SyncPayload { + const { convergentSync: _convergentSync, ...legacyPayload } = payload; + return legacyPayload; +} diff --git a/domain/convergentSync/payloadMigration.test.ts b/domain/convergentSync/payloadMigration.test.ts new file mode 100644 index 000000000..b14c4a0b7 --- /dev/null +++ b/domain/convergentSync/payloadMigration.test.ts @@ -0,0 +1,701 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; + +import { sanitizeHost } from '../host.ts'; +import type { SyncFileMeta, SyncPayload } from '../sync.ts'; +import { + applyConvergentMutations, + assertConvergentSyncWriteCompatible, + applyLegacySyncPayload, + cloudSyncPayloadsEqual, + createConvergentSyncEnvelope, + createConvergentSyncStateFromPayload, + diffLegacySyncPayload, + hydrateConvergentSyncEnvelope, + materializeSyncPayloadFromConvergentState, + mergeConvergentSyncStates, + planConvergentSyncMigration, + serializeConvergentSyncState, + validateConvergentSyncPayload, + withConvergentSyncEnvelope, + createConvergentSyncState, +} from './index.ts'; + +const NOW = 1_700_000_000_000; + +function payload(label = 'Production'): SyncPayload { + return { + hosts: [{ + id: 'host-1', + label, + hostname: 'example.com', + username: 'root', + tags: ['prod'], + os: 'linux', + password: 'host-secret', + }], + keys: [{ + id: 'key-1', + label: 'Deploy key', + type: 'ED25519', + privateKey: 'private-secret', + source: 'imported', + category: 'key', + created: NOW, + }], + identities: [], + proxyProfiles: [], + snippets: [], + customGroups: ['prod'], + snippetPackages: [], + notes: [], + noteGroups: [], + portForwardingRules: [], + groupConfigs: [], + settings: { + theme: 'dark', + ai: { providers: [{ id: 'provider-1', apiKey: 'api-secret' }] }, + }, + syncedAt: NOW, + }; +} + +function emptyPayload(settings?: SyncPayload['settings']): SyncPayload { + return { + hosts: [], + keys: [], + identities: [], + proxyProfiles: [], + snippets: [], + customGroups: [], + snippetPackages: [], + notes: [], + noteGroups: [], + portForwardingRules: [], + groupConfigs: [], + settings, + syncedAt: NOW, + }; +} + +function meta(overrides: Partial = {}): SyncFileMeta { + return { + version: 1, + updatedAt: NOW, + deviceId: 'remote-device', + appVersion: '1.0.0', + iv: 'iv', + salt: 'salt', + algorithm: 'AES-256-GCM', + kdf: 'PBKDF2', + ...overrides, + }; +} + +test('encrypted envelope omits materialized winner values and hydrates exactly', () => { + const state = createConvergentSyncStateFromPayload(payload(), 'device-a', NOW); + const materialized = materializeSyncPayloadFromConvergentState(state, { syncedAt: NOW }); + const envelope = createConvergentSyncEnvelope(state, materialized); + const envelopeJson = JSON.stringify(envelope); + + assert.equal(envelopeJson.includes('host-secret'), false); + assert.equal(envelopeJson.includes('private-secret'), false); + assert.equal(envelopeJson.includes('api-secret'), false); + assert.match(JSON.stringify(materialized), /private-secret/); + assert.equal( + serializeConvergentSyncState(hydrateConvergentSyncEnvelope(envelope, materialized)), + serializeConvergentSyncState(state), + ); +}); + +test('envelope creation and hydration reject a materialized snapshot that disagrees with state', () => { + const state = createConvergentSyncStateFromPayload(payload('State value'), 'device-a', NOW); + const mismatched = payload('Different snapshot value'); + assert.throws( + () => createConvergentSyncEnvelope(state, mismatched), + /does not match its materialized v1 snapshot/, + ); + const materialized = materializeSyncPayloadFromConvergentState(state, { syncedAt: NOW }); + const envelope = createConvergentSyncEnvelope(state, materialized); + const damaged = structuredClone(envelope); + const labelRegister = damaged.state.collections.hosts.entities['host-1'].fields.label; + const selected = labelRegister.candidates.find( + (candidate) => 'materialized' in candidate && candidate.materialized === true, + ); + assert.ok(selected); + const damagedCandidate = selected as unknown as { materialized?: true; value?: string }; + delete damagedCandidate.materialized; + damagedCandidate.value = 'Envelope-only value'; + assert.throws( + () => hydrateConvergentSyncEnvelope(damaged, materialized), + /does not match its materialized v1 snapshot/, + ); +}); + +test('envelope maps preserve prototype-like entity, field, setting, and string identifiers', () => { + const specialObject = JSON.parse('{"id":"__proto__","constructor":"safe"}') as { + id: string; + constructor: string; + }; + const state = applyConvergentMutations(createConvergentSyncState(), 'device-a', [ + { + kind: 'entity-upsert', + collection: 'hosts', + entityId: '__proto__', + value: specialObject, + position: 0, + }, + { kind: 'setting-set', path: ['__proto__'], value: 'safe-setting' }, + { kind: 'string-entry-add', collection: 'customGroups', value: '__proto__', position: 0 }, + ], NOW); + const materialized = materializeSyncPayloadFromConvergentState(state, { syncedAt: NOW }); + const envelope = createConvergentSyncEnvelope(state, materialized); + const hydrated = hydrateConvergentSyncEnvelope( + JSON.parse(JSON.stringify(envelope)), + JSON.parse(JSON.stringify(materialized)), + ); + + assert.equal(serializeConvergentSyncState(hydrated), serializeConvergentSyncState(state)); +}); + +test('envelope retains concurrent alternatives while the selected winner remains materialized', () => { + const base = createConvergentSyncStateFromPayload(payload('Base'), 'seed', NOW); + const left = applyConvergentMutations(base, 'device-a', [{ + kind: 'entity-field-set', + collection: 'hosts', + entityId: 'host-1', + field: 'label', + value: 'Left alternative', + }], NOW + 1); + const right = applyConvergentMutations(base, 'device-z', [{ + kind: 'entity-field-set', + collection: 'hosts', + entityId: 'host-1', + field: 'label', + value: 'Right winner', + }], NOW + 1); + const state = mergeConvergentSyncStates(left, right); + const materialized = materializeSyncPayloadFromConvergentState(state, { syncedAt: NOW + 1 }); + const envelopeJson = JSON.stringify(createConvergentSyncEnvelope(state, materialized)); + + assert.match(envelopeJson, /Left alternative/); + assert.equal(envelopeJson.includes('Right winner'), false); +}); + +test('schema validation fails closed for missing, mismatched, future, and damaged envelopes', () => { + const state = createConvergentSyncStateFromPayload(payload(), 'device-a', NOW); + const v2 = withConvergentSyncEnvelope(state, { syncedAt: NOW }); + assert.equal( + serializeConvergentSyncState(validateConvergentSyncPayload(meta({ syncSchemaVersion: 2 }), v2)!), + serializeConvergentSyncState(state), + ); + assert.throws( + () => validateConvergentSyncPayload(meta(), v2), + /without schema metadata/, + ); + assert.throws( + () => validateConvergentSyncPayload(meta({ syncSchemaVersion: 2 }), payload()), + /missing its convergent envelope/, + ); + assert.throws( + () => validateConvergentSyncPayload( + { ...meta(), syncSchemaVersion: 3 } as unknown as SyncFileMeta, + payload(), + ), + /Unsupported sync schema version/, + ); + const damaged = structuredClone(v2); + damaged.convergentSync!.state.vector['device-a'] = 999; + assert.throws( + () => validateConvergentSyncPayload(meta({ syncSchemaVersion: 2 }), damaged), + /not witnessed|cover every counter/, + ); +}); + +test('legacy writers cannot silently overwrite convergent or future cloud schemas', () => { + const state = createConvergentSyncStateFromPayload(payload(), 'device-a', NOW); + const v2 = withConvergentSyncEnvelope(state, { syncedAt: NOW }); + assert.doesNotThrow(() => assertConvergentSyncWriteCompatible(meta(), payload())); + assert.doesNotThrow(() => assertConvergentSyncWriteCompatible( + meta({ syncSchemaVersion: 2 }), + v2, + )); + assert.throws( + () => assertConvergentSyncWriteCompatible(meta({ syncSchemaVersion: 2 }), payload()), + /Enable or migrate convergent sync/, + ); + assert.throws( + () => assertConvergentSyncWriteCompatible( + { syncSchemaVersion: 3 } as unknown as SyncFileMeta, + v2, + ), + /unsupported sync schema/, + ); +}); + +test('trusted legacy diff becomes causal CRDT writes without carrying transport metadata', () => { + const baseline = payload('Before'); + const state = createConvergentSyncStateFromPayload(baseline, 'seed', NOW); + const legacy = { + ...payload('After'), + keys: [], + syncedAt: NOW + 100, + }; + const next = applyLegacySyncPayload( + state, + baseline, + legacy, + 'legacy:github:remote-device', + NOW + 100, + ); + const materialized = materializeSyncPayloadFromConvergentState(next, { syncedAt: NOW + 100 }); + + assert.equal(materialized.hosts[0].label, 'After'); + assert.deepEqual(materialized.keys, []); + assert.equal(cloudSyncPayloadsEqual(materialized, legacy), true); +}); + +test('payload and legacy conversion normalize undefined fields with JSON semantics', () => { + const baseline = payload('Before'); + baseline.hosts = [sanitizeHost({ + ...baseline.hosts[0], + proxyConfig: { + type: 'http', + host: 'proxy.example.com', + port: 8080, + username: undefined, + }, + })]; + assert.equal(Object.hasOwn(baseline.hosts[0], 'iconMode'), true); + assert.equal(Object.hasOwn(baseline.hosts[0].proxyConfig!, 'username'), true); + + const state = createConvergentSyncStateFromPayload(baseline, 'seed', NOW); + const initial = materializeSyncPayloadFromConvergentState(state, { syncedAt: NOW }); + assert.equal(Object.hasOwn(initial.hosts[0], 'iconMode'), false); + assert.equal(Object.hasOwn(initial.hosts[0].proxyConfig!, 'username'), false); + + const legacy: SyncPayload = { + ...baseline, + hosts: [{ ...baseline.hosts[0], label: 'After' }], + syncedAt: NOW + 1, + }; + const next = applyLegacySyncPayload( + state, + baseline, + legacy, + 'legacy:github:remote-device', + NOW + 1, + ); + const materialized = materializeSyncPayloadFromConvergentState(next, { syncedAt: NOW + 1 }); + + assert.equal(materialized.hosts[0].label, 'After'); + assert.equal(Object.hasOwn(materialized.hosts[0], 'iconMode'), false); + assert.equal(Object.hasOwn(materialized.hosts[0].proxyConfig!, 'username'), false); +}); + +test('trusted legacy diff treats own undefined optional fields as omitted', () => { + const baseline = payload(); + baseline.identities = [{ + id: 'identity-1', + label: 'Production identity', + username: 'root', + authMethod: 'password', + password: 'identity-secret', + created: NOW, + }]; + baseline.noteGroups = ['operations']; + const legacy = { + ...baseline, + identities: undefined, + noteGroups: undefined, + settings: undefined, + syncedAt: NOW + 1, + } as unknown as SyncPayload; + + assert.deepEqual(diffLegacySyncPayload(baseline, legacy), []); + + const state = createConvergentSyncStateFromPayload(baseline, 'seed', NOW); + const next = applyLegacySyncPayload( + state, + baseline, + legacy, + 'legacy:github:remote-device', + NOW + 1, + ); + const materialized = materializeSyncPayloadFromConvergentState(next, { syncedAt: NOW + 1 }); + + assert.equal(materialized.identities?.[0]?.id, 'identity-1'); + assert.deepEqual(materialized.noteGroups, ['operations']); + assert.equal(materialized.settings?.theme, 'dark'); +}); + +test('payload conversion still rejects entities that JSON cannot serialize', () => { + const invalid = payload(); + const circular: Record = {}; + circular.self = circular; + (invalid.hosts[0] as unknown as Record).invalid = circular; + + assert.throws( + () => createConvergentSyncStateFromPayload(invalid, 'seed', NOW), + /cannot be represented as JSON/, + ); +}); + +test('trusted legacy diff preserves reorder-only entity and string collection edits', () => { + const baseline = payload(); + baseline.hosts.push({ + ...baseline.hosts[0], + id: 'host-2', + label: 'Staging', + hostname: 'staging.example.com', + }); + baseline.customGroups = ['prod', 'staging']; + const state = createConvergentSyncStateFromPayload(baseline, 'seed', NOW); + const legacy: SyncPayload = { + ...baseline, + hosts: [baseline.hosts[1], baseline.hosts[0]], + customGroups: ['staging', 'prod'], + syncedAt: NOW + 1, + }; + + const next = applyLegacySyncPayload( + state, + baseline, + legacy, + 'legacy:github:remote-device', + NOW + 1, + ); + const materialized = materializeSyncPayloadFromConvergentState(next, { syncedAt: NOW + 1 }); + + assert.deepEqual(materialized.hosts.map((host) => host.id), ['host-2', 'host-1']); + assert.deepEqual(materialized.customGroups, ['staging', 'prod']); + assert.equal(cloudSyncPayloadsEqual(materialized, legacy), true); +}); + +test('v1-only migration previews and creates a backward-compatible v2 payload', () => { + const local = payload(); + const remote = { + ...payload(), + snippets: [{ id: 'snippet-1', label: 'List', command: 'ls' }], + }; + const plan = planConvergentSyncMigration({ + localPayload: local, + localTrustedBaseline: null, + providers: [{ + provider: 'github', + status: 'ready', + meta: meta(), + payload: remote, + trustedBaseline: local, + }], + deviceId: 'local-device', + now: NOW + 1, + }); + + assert.equal(plan.preview.canInitialize, true); + assert.equal(plan.preview.oldClientCompatibility, 'materialized-v1-snapshot'); + assert.equal(plan.payload?.snippets.length, 1); + assert.equal(plan.payload?.convergentSync?.schemaVersion, 2); +}); + +test('a fresh entity-empty device adopts v1 cloud settings instead of merging local defaults', () => { + const remote = payload('Remote'); + remote.settings = { theme: 'dark' }; + const plan = planConvergentSyncMigration({ + localPayload: emptyPayload({ theme: 'light' }), + localTrustedBaseline: null, + providers: [{ + provider: 'github', + status: 'ready', + meta: meta(), + payload: remote, + trustedBaseline: null, + }], + deviceId: 'fresh-device', + now: NOW + 1, + }); + + assert.equal(plan.preview.canInitialize, true); + assert.equal(plan.payload?.hosts[0].label, 'Remote'); + assert.equal(plan.payload?.settings?.theme, 'dark'); +}); + +test('v1-only migration blocks divergent provider data without a trusted baseline', () => { + const local = payload('Stale local host'); + const remote = emptyPayload(); + const plan = planConvergentSyncMigration({ + localPayload: local, + localTrustedBaseline: null, + providers: [{ + provider: 'github', + status: 'ready', + meta: meta(), + payload: remote, + trustedBaseline: null, + }], + deviceId: 'local-device', + now: NOW + 1, + }); + + assert.equal(plan.preview.canInitialize, false); + assert.match(plan.preview.blockedReasons.join(' '), /github: no trusted legacy baseline/); + assert.equal(plan.payload, null); +}); + +test('v1-only migration accepts matching provider data without a trusted baseline', () => { + const local = payload('Matching host'); + const plan = planConvergentSyncMigration({ + localPayload: local, + localTrustedBaseline: null, + providers: [{ + provider: 'github', + status: 'ready', + meta: meta(), + payload: structuredClone(local), + trustedBaseline: null, + }], + deviceId: 'local-device', + now: NOW + 1, + }); + + assert.equal(plan.preview.canInitialize, true); + assert.equal(plan.payload?.hosts[0]?.label, 'Matching host'); +}); + +test('a fresh device still blocks a shrunk v1 provider used as the migration seed', () => { + const baseline = payload('Base'); + baseline.hosts = Array.from({ length: 4 }, (_, index) => ({ + ...baseline.hosts[0], + id: `host-${index + 1}`, + label: `Host ${index + 1}`, + })); + const remote: SyncPayload = { + ...baseline, + hosts: baseline.hosts.slice(0, 1), + syncedAt: NOW + 1, + }; + const plan = planConvergentSyncMigration({ + localPayload: emptyPayload(), + localTrustedBaseline: null, + providers: [{ + provider: 'github', + status: 'ready', + meta: meta(), + payload: remote, + trustedBaseline: baseline, + }], + deviceId: 'fresh-device', + now: NOW + 1, + }); + + assert.equal(plan.preview.canInitialize, false); + assert.equal(plan.preview.shrinkFindings[0]?.provider, 'github'); + assert.equal(plan.preview.shrinkFindings[0]?.finding.lost, 3); + assert.match(plan.preview.blockedReasons.join(' '), /remove too many entities/); +}); + +test('migration blocks unresolved v1 conflicts and future provider schemas', () => { + const baseline = payload('Base'); + const conflict = planConvergentSyncMigration({ + localPayload: payload('Local'), + localTrustedBaseline: baseline, + providers: [{ + provider: 'github', + status: 'ready', + meta: meta(), + payload: payload('Remote'), + trustedBaseline: baseline, + }], + deviceId: 'local-device', + now: NOW + 1, + }); + assert.equal(conflict.preview.canInitialize, false); + assert.match(conflict.preview.blockedReasons.join(' '), /unresolved conflicts/); + + const future = planConvergentSyncMigration({ + localPayload: baseline, + localTrustedBaseline: null, + providers: [{ + provider: 'github', + status: 'ready', + meta: { ...meta(), syncSchemaVersion: 3 } as unknown as SyncFileMeta, + payload: baseline, + trustedBaseline: null, + }], + deviceId: 'local-device', + now: NOW + 1, + }); + assert.equal(future.preview.canInitialize, false); + assert.equal(future.preview.providers[0].schemaVersion, 'future'); +}); + +test('joining existing v2 data blocks changed legacy writers without a trusted baseline', () => { + const remoteState = createConvergentSyncStateFromPayload(payload('Remote'), 'remote', NOW); + const remotePayload = withConvergentSyncEnvelope(remoteState, { syncedAt: NOW }); + const plan = planConvergentSyncMigration({ + localPayload: payload('Unbased local edit'), + localTrustedBaseline: null, + providers: [{ + provider: 'github', + status: 'ready', + meta: meta({ syncSchemaVersion: 2 }), + payload: remotePayload, + trustedBaseline: null, + }], + deviceId: 'local-device', + now: NOW + 1, + }); + + assert.equal(plan.preview.canInitialize, false); + assert.match(plan.preview.blockedReasons.join(' '), /no trusted legacy baseline/); +}); + +test('joining existing v2 data blocks a shrunk legacy local source', () => { + const baseline = payload('Remote'); + baseline.hosts = Array.from({ length: 4 }, (_, index) => ({ + ...baseline.hosts[0], + id: `host-${index + 1}`, + label: `Host ${index + 1}`, + })); + const local: SyncPayload = { + ...baseline, + hosts: baseline.hosts.slice(0, 1), + syncedAt: NOW + 1, + }; + const remoteState = createConvergentSyncStateFromPayload(baseline, 'remote', NOW); + const plan = planConvergentSyncMigration({ + localPayload: local, + localTrustedBaseline: baseline, + providers: [{ + provider: 'github', + status: 'ready', + meta: meta({ syncSchemaVersion: 2 }), + payload: withConvergentSyncEnvelope(remoteState, { syncedAt: NOW }), + trustedBaseline: null, + }], + deviceId: 'local-device', + now: NOW + 1, + }); + + assert.equal(plan.preview.canInitialize, false); + assert.match(plan.preview.blockedReasons.join(' '), /legacy-local:local-device.*remove too many entities/); +}); + +test('joining existing v2 data blocks a shrunk legacy provider source', () => { + const baseline = payload('Remote'); + baseline.hosts = Array.from({ length: 4 }, (_, index) => ({ + ...baseline.hosts[0], + id: `host-${index + 1}`, + label: `Host ${index + 1}`, + })); + const legacy: SyncPayload = { + ...baseline, + hosts: baseline.hosts.slice(0, 1), + syncedAt: NOW + 1, + }; + const remoteState = createConvergentSyncStateFromPayload(baseline, 'remote', NOW); + const plan = planConvergentSyncMigration({ + localPayload: emptyPayload(), + localTrustedBaseline: null, + providers: [ + { + provider: 'github', + status: 'ready', + meta: meta({ syncSchemaVersion: 2 }), + payload: withConvergentSyncEnvelope(remoteState, { syncedAt: NOW }), + trustedBaseline: null, + }, + { + provider: 'webdav', + status: 'ready', + meta: meta({ deviceId: 'legacy-device' }), + payload: legacy, + trustedBaseline: baseline, + }, + ], + deviceId: 'fresh-device', + now: NOW + 1, + }); + + assert.equal(plan.preview.canInitialize, false); + assert.equal(plan.preview.shrinkFindings[0]?.provider, 'webdav'); + assert.equal(plan.preview.shrinkFindings[0]?.finding.lost, 3); +}); + +test('v2 migration shrink checks preserve optional collections omitted by legacy clients', () => { + const baseline = payload('Remote'); + baseline.identities = Array.from({ length: 4 }, (_, index) => ({ + id: `identity-${index + 1}`, + label: `Identity ${index + 1}`, + username: `user-${index + 1}`, + authMethod: 'password' as const, + created: NOW, + })); + const local = { + ...baseline, + identities: undefined, + syncedAt: NOW + 1, + } as unknown as SyncPayload; + const remoteState = createConvergentSyncStateFromPayload(baseline, 'remote', NOW); + const plan = planConvergentSyncMigration({ + localPayload: local, + localTrustedBaseline: baseline, + providers: [{ + provider: 'github', + status: 'ready', + meta: meta({ syncSchemaVersion: 2 }), + payload: withConvergentSyncEnvelope(remoteState, { syncedAt: NOW }), + trustedBaseline: null, + }], + deviceId: 'local-device', + now: NOW + 1, + }); + + assert.equal(plan.preview.canInitialize, true); + assert.equal(plan.preview.shrinkFindings.length, 0); + assert.equal(plan.payload?.identities?.length, 4); +}); + +test('a fresh entity-empty device adopts existing v2 data without a trusted baseline', () => { + const remoteState = createConvergentSyncStateFromPayload(payload('Remote'), 'remote', NOW); + const remotePayload = withConvergentSyncEnvelope(remoteState, { syncedAt: NOW }); + const plan = planConvergentSyncMigration({ + localPayload: emptyPayload({ theme: 'light' }), + localTrustedBaseline: null, + providers: [{ + provider: 'github', + status: 'ready', + meta: meta({ syncSchemaVersion: 2 }), + payload: remotePayload, + trustedBaseline: null, + }], + deviceId: 'fresh-device', + now: NOW + 1, + }); + + assert.equal(plan.preview.canInitialize, true); + assert.equal(plan.payload?.hosts[0].label, 'Remote'); + assert.equal(plan.payload?.settings?.theme, 'dark'); +}); + +test('an empty local snapshot with a trusted baseline remains a real deletion', () => { + const baseline = payload('Remote'); + const remoteState = createConvergentSyncStateFromPayload(baseline, 'remote', NOW); + const remotePayload = withConvergentSyncEnvelope(remoteState, { syncedAt: NOW }); + const plan = planConvergentSyncMigration({ + localPayload: emptyPayload(), + localTrustedBaseline: baseline, + providers: [{ + provider: 'github', + status: 'ready', + meta: meta({ syncSchemaVersion: 2 }), + payload: remotePayload, + trustedBaseline: null, + }], + deviceId: 'legacy-device', + now: NOW + 1, + }); + + assert.equal(plan.preview.canInitialize, true); + assert.deepEqual(plan.payload?.hosts, []); +}); diff --git a/domain/convergentSync/types.ts b/domain/convergentSync/types.ts index 58ca0ca3e..2c5ba48af 100644 --- a/domain/convergentSync/types.ts +++ b/domain/convergentSync/types.ts @@ -86,6 +86,61 @@ export interface ConvergentSyncStateV2 { stringCollections: Record; } +/** + * A register candidate stored in the encrypted cloud envelope. Winner values + * that already exist in the adjacent materialized v1 snapshot may be omitted + * and reconstructed during hydration. Structural values (presence and + * position) remain inline so the envelope is self-describing. + */ +export type ConvergentEnvelopeCandidate = + | RegisterTombstoneCandidate + | (Omit, 'value'> & { + value?: T; + materialized?: true; + }); + +export interface ConvergentEnvelopeRegister { + candidates: ConvergentEnvelopeCandidate[]; +} + +export interface ConvergentEnvelopeEntityState { + presence: ConvergentEnvelopeRegister; + position?: ConvergentEnvelopeRegister; + fields: Record; +} + +export interface ConvergentEnvelopeCollectionState { + entities: Record; +} + +export interface ConvergentEnvelopeStringEntryState { + presence: ConvergentEnvelopeRegister; + position?: ConvergentEnvelopeRegister; +} + +export interface ConvergentEnvelopeStringCollectionState { + entries: Record; +} + +export interface ConvergentEnvelopeStateV2 { + vector: VersionVector; + dotOrigins: DotOriginIndex; + hlc: HybridLogicalClock; + collections: Record; + settings: Record; + stringCollections: Record; +} + +/** + * Stored inside the AES-256-GCM encrypted SyncPayload. Plaintext metadata only + * advertises `syncSchemaVersion: 2`; candidate values never leave ciphertext. + */ +export interface ConvergentSyncEnvelopeV2 { + schemaVersion: 2; + encoding: 'materialized-winner-v1'; + state: ConvergentEnvelopeStateV2; +} + export type RegisterAddress = | { kind: 'entity-presence'; diff --git a/domain/sync.ts b/domain/sync.ts index e896d9432..873f31834 100644 --- a/domain/sync.ts +++ b/domain/sync.ts @@ -6,6 +6,17 @@ */ import type { ShrinkFinding } from './syncGuards'; +import type { + ConvergentFieldConflict, + ConvergentSyncEnvelopeV2, + ConvergentSyncStateV2, +} from './convergentSync'; + +export type { + ConvergentFieldConflict, + ConvergentSyncEnvelopeV2, + ConvergentSyncStateV2, +} from './convergentSync'; // ============================================================================ // Security State Machine @@ -178,6 +189,8 @@ export interface SyncFileMeta { algorithm: 'AES-256-GCM'; // Encryption algorithm identifier kdf: 'PBKDF2' | 'Argon2id'; // Key derivation function kdfIterations?: number; // PBKDF2 iterations (if applicable) + /** Present only for convergent-sync payloads. Unknown future versions fail closed. */ + syncSchemaVersion?: 2; } /** @@ -291,6 +304,9 @@ export interface SyncPayload { // Reliability metadata used to make sync decisions auditable across devices. syncMeta?: SyncReliabilityMeta; + + /** Encrypted convergent-sync metadata. The adjacent fields remain a complete v1 snapshot. */ + convergentSync?: ConvergentSyncEnvelopeV2; } export const SYNC_PAYLOAD_ENTITY_KEYS = [ @@ -374,6 +390,44 @@ export interface SyncSnapshotEntry { payload: SyncPayload; } +export interface ConvergentProviderMigrationStatus { + provider: CloudProvider; + status: 'ready' | 'empty' | 'unavailable' | 'blocked'; + schemaVersion: 1 | 2 | 'future' | 'invalid'; + entityCount: number; + hasTrustedBaseline: boolean; + message?: string; +} + +export interface ConvergentMigrationPreview { + schemaVersion: 2; + canInitialize: boolean; + entityCounts: Partial>; + settingsLeafCount: number; + conflictCount: number; + conflicts: ConvergentFieldConflict[]; + shrinkFindings: Array<{ provider: CloudProvider; finding: Extract }>; + providers: ConvergentProviderMigrationStatus[]; + oldClientCompatibility: 'materialized-v1-snapshot'; + blockedReasons: string[]; +} + +export interface ConvergentReplicaRecordV2 { + schemaVersion: 2; + state: ConvergentSyncStateV2; + updatedAt: number; +} + +export interface ConvergentProviderBaselineV2 { + schemaVersion: 2; + provider: CloudProvider; + remoteVersion: number; + remoteUpdatedAt: number; + remoteDeviceId: string; + materializedPayload: SyncPayload; + state: ConvergentSyncStateV2; +} + export function hasSyncPayloadEntityData( payload: SyncPayload, keys: readonly SyncPayloadEntityKey[] = SYNC_PAYLOAD_ENTITY_KEYS, @@ -566,6 +620,8 @@ export const SYNC_STORAGE_KEYS = { PROVIDER_SMB: 'netcatty_provider_smb_v1', LOCAL_SYNC_META: 'netcatty_local_sync_meta_v1', SYNC_BASE_PAYLOAD: 'netcatty_sync_base_payload_v1', + CONVERGENT_REPLICA: 'netcatty_convergent_sync_replica_v2', + CONVERGENT_PROVIDER_BASELINE: 'netcatty_convergent_sync_provider_baseline_v2', } as const; // ============================================================================ diff --git a/infrastructure/config/storageKeys.ts b/infrastructure/config/storageKeys.ts index 9dbbb7a72..b5a4b6cf0 100644 --- a/infrastructure/config/storageKeys.ts +++ b/infrastructure/config/storageKeys.ts @@ -15,6 +15,8 @@ export const STORAGE_KEY_UI_THEME_LIGHT = 'netcatty_ui_theme_light_v1'; export const STORAGE_KEY_UI_THEME_DARK = 'netcatty_ui_theme_dark_v1'; export const STORAGE_KEY_UI_FONT_FAMILY = 'netcatty_ui_font_family_v1'; export const STORAGE_KEY_SYNC = 'netcatty_sync_v1'; +/** Device-local experimental convergent-sync toggle; never included in SyncPayload settings. */ +export const STORAGE_KEY_CONVERGENT_SYNC_CONFIG = 'netcatty_convergent_sync_config_v2'; export const STORAGE_KEY_TERM_THEME = 'netcatty_term_theme_v1'; export const STORAGE_KEY_TERM_FOLLOW_APP_THEME = 'netcatty_term_follow_app_theme_v1'; export const STORAGE_KEY_TERM_THEME_DARK = 'netcatty_term_theme_dark_v1'; diff --git a/infrastructure/services/CloudSyncManager.ts b/infrastructure/services/CloudSyncManager.ts index 1d119e364..94ddde426 100644 --- a/infrastructure/services/CloudSyncManager.ts +++ b/infrastructure/services/CloudSyncManager.ts @@ -28,6 +28,8 @@ import { type WebDAVConfig, type S3Config, type SyncedFile, + type ConvergentProviderBaselineV2, + type ConvergentReplicaRecordV2, } from '../../domain/sync'; import type { CloudSyncConflictAction, CloudSyncStrategy } from '../../domain/syncStrategy'; import { type CloudAdapter } from './adapters'; @@ -114,6 +116,15 @@ import { verifyPasswordImpl, handleProviderReauthRequiredImpl, } from './cloudSync/stateAndSecurityMethods'; +import { + clearConvergentSyncStorageImpl, + convergentProviderBaselineKeyImpl, + loadConvergentProviderBaselineImpl, + loadConvergentReplicaImpl, + reencryptSyncStorageImpl, + saveConvergentProviderBaselineImpl, + saveConvergentReplicaImpl, +} from './cloudSync/convergentSyncStorageMethods'; // ============================================================================ // Types @@ -251,7 +262,7 @@ export class CloudSyncManager { return loadFromStorageImpl.call(this, key); } - private saveToStorage(key: string, value: unknown): void { + private saveToStorage(key: string, value: unknown): boolean { return saveToStorageImpl.call(this, key, value); } @@ -811,6 +822,10 @@ export class CloudSyncManager { return syncSnapshotsKeyImpl.call(this, provider); } + private convergentProviderBaselineKey(provider: CloudProvider): string { + return convergentProviderBaselineKeyImpl.call(this, provider); + } + private providerAccountIdKey(provider: CloudProvider): string { return providerAccountIdKeyImpl.call(this, provider); } @@ -835,6 +850,36 @@ export class CloudSyncManager { return loadSyncSnapshotsImpl.call(this, provider); } + async saveConvergentReplica(record: ConvergentReplicaRecordV2): Promise { + return saveConvergentReplicaImpl.call(this, record); + } + + async loadConvergentReplica(): Promise { + return loadConvergentReplicaImpl.call(this); + } + + async saveConvergentProviderBaseline(baseline: ConvergentProviderBaselineV2): Promise { + return saveConvergentProviderBaselineImpl.call(this, baseline); + } + + async loadConvergentProviderBaseline( + provider: CloudProvider, + ): Promise { + return loadConvergentProviderBaselineImpl.call(this, provider); + } + + clearConvergentSyncStorage(confirmed = false): void { + return clearConvergentSyncStorageImpl.call(this, confirmed); + } + + private async reencryptSyncStorage( + oldKey: CryptoKey, + newKey: CryptoKey, + newConfig: MasterKeyConfig, + ): Promise { + return reencryptSyncStorageImpl.call(this, oldKey, newKey, newConfig); + } + private clearSyncBase(): void { return clearSyncBaseImpl.call(this); } diff --git a/infrastructure/services/EncryptionService.convergentSync.test.ts b/infrastructure/services/EncryptionService.convergentSync.test.ts new file mode 100644 index 000000000..15a6092dd --- /dev/null +++ b/infrastructure/services/EncryptionService.convergentSync.test.ts @@ -0,0 +1,51 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; + +import { + createConvergentSyncStateFromPayload, + serializeConvergentSyncState, + validateConvergentSyncPayload, + withConvergentSyncEnvelope, +} from '../../domain/convergentSync/index.ts'; +import type { SyncPayload } from '../../domain/sync.ts'; +import { EncryptionService } from './EncryptionService.ts'; + +test('v2 metadata exposes only the schema while the envelope remains encrypted', async () => { + const now = 1_700_000_000_000; + const legacy: SyncPayload = { + hosts: [], + keys: [{ + id: 'key-1', + label: 'Secret key', + type: 'ED25519', + privateKey: 'never-plaintext', + source: 'imported', + category: 'key', + created: now, + }], + snippets: [], + customGroups: [], + syncedAt: now, + }; + const state = createConvergentSyncStateFromPayload(legacy, 'device-a', now); + const payload = withConvergentSyncEnvelope(state, { syncedAt: now }); + const file = await EncryptionService.encryptPayload( + payload, + 'correct horse battery staple', + 'device-a', + 'Device A', + '1.0.0', + ); + + assert.equal(file.meta.syncSchemaVersion, 2); + assert.equal(JSON.stringify(file.meta).includes('never-plaintext'), false); + assert.equal(file.payload.includes('never-plaintext'), false); + const decrypted = await EncryptionService.decryptPayload( + file, + 'correct horse battery staple', + ); + assert.equal( + serializeConvergentSyncState(validateConvergentSyncPayload(file.meta, decrypted)!), + serializeConvergentSyncState(state), + ); +}); diff --git a/infrastructure/services/EncryptionService.ts b/infrastructure/services/EncryptionService.ts index 9a458a509..762123bbf 100644 --- a/infrastructure/services/EncryptionService.ts +++ b/infrastructure/services/EncryptionService.ts @@ -20,6 +20,7 @@ import { type SyncFileMeta, type SyncPayload, } from '../../domain/sync'; +import { validateConvergentSyncPayload } from '../../domain/convergentSync'; // ============================================================================ // Utility Functions @@ -257,6 +258,13 @@ export const encryptPayload = async ( appVersion: string, existingVersion?: number ): Promise => { + const syncSchemaVersion = payload.convergentSync?.schemaVersion; + if (syncSchemaVersion !== undefined) { + validateConvergentSyncPayload( + { syncSchemaVersion }, + payload, + ); + } // Generate new salt for each encryption const salt = generateRandomBytes(SYNC_CONSTANTS.SALT_LENGTH); @@ -279,6 +287,7 @@ export const encryptPayload = async ( algorithm: 'AES-256-GCM', kdf: 'PBKDF2', kdfIterations: SYNC_CONSTANTS.PBKDF2_ITERATIONS, + ...(syncSchemaVersion ? { syncSchemaVersion } : {}), }; return { @@ -318,7 +327,9 @@ export const decryptPayload = async ( key ); - return JSON.parse(decrypted) as SyncPayload; + const parsed = JSON.parse(decrypted) as SyncPayload; + validateConvergentSyncPayload(meta, parsed); + return parsed; }; /** diff --git a/infrastructure/services/cloudSync/authMethods.ts b/infrastructure/services/cloudSync/authMethods.ts index 832f62268..552a1a4fd 100644 --- a/infrastructure/services/cloudSync/authMethods.ts +++ b/infrastructure/services/cloudSync/authMethods.ts @@ -25,6 +25,12 @@ import type { const SYNC_REMOTE_ANCHOR_STORAGE_KEY = 'netcatty_sync_remote_anchor_v1'; +export function clearProviderMergeStateImpl(this: any, provider: CloudProvider): void { + this.removeFromStorage(this.syncBaseKey(provider)); + this.removeFromStorage(this.convergentProviderBaselineKey(provider)); + this.clearSyncAnchor(provider); +} + export async function startProviderAuthImpl(this: any, provider: CloudProvider, redirectUri?: string @@ -145,8 +151,7 @@ export async function completeGitHubAuthImpl(this: any, const previousId = this.loadProviderAccountId('github') ?? previousAccount?.id ?? null; const sameAccount = newId !== null && previousId !== null && newId === previousId; if (!sameAccount) { - this.removeFromStorage(this.syncBaseKey('github')); - this.clearSyncAnchor('github'); + clearProviderMergeStateImpl.call(this, 'github'); } if (newId) { this.saveProviderAccountId('github', newId); @@ -244,8 +249,7 @@ export async function completePKCEAuthImpl(this: any, const previousId = this.loadProviderAccountId(provider) ?? previousAccount?.id ?? null; const sameAccount = newId !== null && previousId !== null && newId === previousId; if (!sameAccount) { - this.removeFromStorage(this.syncBaseKey(provider)); - this.clearSyncAnchor(provider); + clearProviderMergeStateImpl.call(this, provider); } if (newId) { this.saveProviderAccountId(provider, newId); @@ -292,9 +296,8 @@ export async function connectConfigProviderImpl(this: any, }; await this.saveProviderConnection(provider, this.state.providers[provider]); - // Clear merge base when (re)configuring to a different endpoint/bucket - this.removeFromStorage(this.syncBaseKey(provider)); - this.clearSyncAnchor(provider); + // Clear all trusted merge state when changing endpoint or bucket. + clearProviderMergeStateImpl.call(this, provider); this.emit({ type: 'AUTH_COMPLETED', provider, @@ -387,10 +390,9 @@ export async function disconnectProviderImpl(this: any,provider: CloudProvider): }; await this.saveProviderConnection(provider, this.state.providers[provider]); - // Clear the merge base for this provider so reconnecting to a different - // account/resource doesn't reuse an unrelated snapshot - this.removeFromStorage(this.syncBaseKey(provider)); - this.clearSyncAnchor(provider); + // Clear all trusted merge state so a later account/resource cannot reuse + // an unrelated snapshot or convergent baseline. + clearProviderMergeStateImpl.call(this, provider); this.removeFromStorage(this.providerAccountIdKey(provider)); // Reset BLOCKED state if it was present — disconnect implicitly resolves // any pending shrink-block warning since there's no provider to push to. diff --git a/infrastructure/services/cloudSync/convergentSyncStorageMethods.test.ts b/infrastructure/services/cloudSync/convergentSyncStorageMethods.test.ts new file mode 100644 index 000000000..4b8b6095e --- /dev/null +++ b/infrastructure/services/cloudSync/convergentSyncStorageMethods.test.ts @@ -0,0 +1,258 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; + +import { createConvergentSyncStateFromPayload } from '../../../domain/convergentSync/index.ts'; +import { SYNC_STORAGE_KEYS, type MasterKeyConfig, type SyncPayload } from '../../../domain/sync.ts'; +import { + loadConvergentReplicaImpl, + reencryptSyncStorageImpl, + saveConvergentReplicaImpl, +} from './convergentSyncStorageMethods.ts'; +import { + decryptLocalStorageValue, + encryptLocalStorageValue, +} from './encryptedLocalStorage.ts'; +import { EncryptionService } from '../EncryptionService.ts'; +import { changeMasterKeyImpl } from './stateAndSecurityMethods.ts'; + +const NOW = 1_700_000_000_000; + +function payload(): SyncPayload { + return { + hosts: [], + keys: [], + snippets: [], + customGroups: [], + syncedAt: NOW, + }; +} + +async function key(): Promise { + return crypto.subtle.generateKey({ name: 'AES-GCM', length: 256 }, true, ['encrypt', 'decrypt']); +} + +function manager(storage: Map, derivedKey: CryptoKey) { + return { + state: { unlockedKey: { derivedKey } }, + loadFromStorage(storageKey: string) { + return storage.get(storageKey) ?? null; + }, + saveToStorage(storageKey: string, value: unknown) { + storage.set(storageKey, value); + }, + removeFromStorage(storageKey: string) { + storage.delete(storageKey); + }, + syncBaseKey(provider?: string) { + return `${SYNC_STORAGE_KEYS.SYNC_BASE_PAYLOAD}${provider ? `_${provider}` : ''}`; + }, + syncSnapshotsKey(provider?: string) { + return `netcatty_sync_snapshots_v1${provider ? `_${provider}` : ''}`; + }, + convergentProviderBaselineKey(provider: string) { + return `${SYNC_STORAGE_KEYS.CONVERGENT_PROVIDER_BASELINE}_${provider}`; + }, + }; +} + +test('canonical replica records are encrypted and fail closed when corrupted', async () => { + const storage = new Map(); + const encryptionKey = await key(); + const subject = manager(storage, encryptionKey); + const state = createConvergentSyncStateFromPayload(payload(), 'device-a', NOW); + + await saveConvergentReplicaImpl.call(subject, { schemaVersion: 2, state, updatedAt: NOW }); + assert.equal(typeof storage.get(SYNC_STORAGE_KEYS.CONVERGENT_REPLICA), 'string'); + assert.equal((await loadConvergentReplicaImpl.call(subject))?.updatedAt, NOW); + + storage.set(SYNC_STORAGE_KEYS.CONVERGENT_REPLICA, 'not-valid-ciphertext'); + await assert.rejects(() => loadConvergentReplicaImpl.call(subject)); +}); + +test('master key rotation re-encrypts all sync records before committing config', async () => { + const storage = new Map(); + const oldKey = await key(); + const newKey = await key(); + const subject = manager(storage, oldKey); + const baseKey = subject.syncBaseKey('github'); + storage.set(baseKey, await encryptLocalStorageValue({ secret: 'value' }, oldKey)); + const oldConfig: MasterKeyConfig = { + verificationHash: 'old', + salt: 'old-salt', + kdf: 'PBKDF2', + createdAt: NOW, + }; + const newConfig: MasterKeyConfig = { ...oldConfig, verificationHash: 'new', salt: 'new-salt' }; + storage.set(SYNC_STORAGE_KEYS.MASTER_KEY_CONFIG, oldConfig); + + await reencryptSyncStorageImpl.call(subject, oldKey, newKey, newConfig); + const encoded = storage.get(baseKey) as string; + assert.deepEqual(await decryptLocalStorageValue(encoded, newKey), { secret: 'value' }); + await assert.rejects(() => decryptLocalStorageValue(encoded, oldKey)); + assert.deepEqual(storage.get(SYNC_STORAGE_KEYS.MASTER_KEY_CONFIG), newConfig); +}); + +test('master key rotation rolls ciphertext back when the config commit fails', async () => { + const storage = new Map(); + const oldKey = await key(); + const newKey = await key(); + const subject = manager(storage, oldKey); + const baseKey = subject.syncBaseKey('github'); + const original = await encryptLocalStorageValue({ secret: 'value' }, oldKey); + storage.set(baseKey, original); + const oldConfig: MasterKeyConfig = { + verificationHash: 'old', + salt: 'old-salt', + kdf: 'PBKDF2', + createdAt: NOW, + }; + storage.set(SYNC_STORAGE_KEYS.MASTER_KEY_CONFIG, oldConfig); + let failConfigWrite = true; + subject.saveToStorage = (storageKey: string, value: unknown) => { + if (storageKey === SYNC_STORAGE_KEYS.MASTER_KEY_CONFIG && failConfigWrite) { + failConfigWrite = false; + throw new Error('quota'); + } + storage.set(storageKey, value); + }; + + await assert.rejects( + () => reencryptSyncStorageImpl.call(subject, oldKey, newKey, { ...oldConfig, salt: 'new' }), + /quota/, + ); + assert.equal(storage.get(baseKey), original); + assert.deepEqual(storage.get(SYNC_STORAGE_KEYS.MASTER_KEY_CONFIG), oldConfig); + assert.deepEqual(await decryptLocalStorageValue(original, oldKey), { secret: 'value' }); +}); + +test('master key rotation aborts when an initially absent sync record appears', async () => { + const storage = new Map(); + const oldKey = await key(); + const newKey = await key(); + const subject = manager(storage, oldKey); + const oldConfig: MasterKeyConfig = { + verificationHash: 'old', + salt: 'old-salt', + kdf: 'PBKDF2', + createdAt: NOW, + }; + const newConfig: MasterKeyConfig = { ...oldConfig, verificationHash: 'new' }; + const appearedKey = subject.convergentProviderBaselineKey('github'); + const appearedCiphertext = await encryptLocalStorageValue({ created: 'concurrently' }, oldKey); + storage.set(SYNC_STORAGE_KEYS.MASTER_KEY_CONFIG, oldConfig); + const loadFromStorage = subject.loadFromStorage.bind(subject); + let appearedReads = 0; + subject.loadFromStorage = (storageKey: string) => { + if (storageKey === appearedKey) { + appearedReads += 1; + if (appearedReads === 1) return null; + storage.set(appearedKey, appearedCiphertext); + return appearedCiphertext; + } + return loadFromStorage(storageKey); + }; + + await assert.rejects( + () => reencryptSyncStorageImpl.call(subject, oldKey, newKey, newConfig), + /Sync data changed while the master key was being rotated/, + ); + + assert.deepEqual(storage.get(SYNC_STORAGE_KEYS.MASTER_KEY_CONFIG), oldConfig); + assert.equal(storage.get(appearedKey), appearedCiphertext); + assert.deepEqual(await decryptLocalStorageValue(appearedCiphertext, oldKey), { + created: 'concurrently', + }); +}); + +test('master key state changes only after derived-key records are re-encrypted', async () => { + const oldChange = EncryptionService.changeMasterPassword; + const oldUnlock = EncryptionService.unlockMasterKey; + const oldConfig: MasterKeyConfig = { + verificationHash: 'old', + salt: 'old-salt', + kdf: 'PBKDF2', + createdAt: NOW, + }; + const newConfig: MasterKeyConfig = { ...oldConfig, verificationHash: 'new', salt: 'new-salt' }; + const oldKey = await key(); + const newKey = await key(); + const calls: string[] = []; + EncryptionService.changeMasterPassword = async () => newConfig; + EncryptionService.unlockMasterKey = async (password) => ({ + derivedKey: password === 'old-password' ? oldKey : newKey, + salt: new Uint8Array(), + unlockedAt: NOW, + }); + try { + const subject = { + state: { + masterKeyConfig: oldConfig, + securityState: 'UNLOCKED', + unlockedKey: { derivedKey: oldKey }, + autoSyncEnabled: false, + }, + masterPassword: 'old-password', + reencryptSyncStorage: async () => { + calls.push('reencrypt'); + assert.equal(subject.state.masterKeyConfig, oldConfig); + assert.equal(subject.masterPassword, 'old-password'); + }, + bumpSyncSecurityGeneration: () => calls.push('generation'), + emit: () => calls.push('emit'), + }; + + const changed = await changeMasterKeyImpl.call(subject, 'old-password', 'new-password'); + + assert.equal(changed, true); + assert.deepEqual(calls, ['reencrypt', 'generation', 'emit']); + assert.equal(subject.state.masterKeyConfig, newConfig); + assert.equal(subject.state.unlockedKey.derivedKey, newKey); + assert.equal(subject.masterPassword, 'new-password'); + } finally { + EncryptionService.changeMasterPassword = oldChange; + EncryptionService.unlockMasterKey = oldUnlock; + } +}); + +test('failed local re-encryption leaves the active master key unchanged', async () => { + const oldChange = EncryptionService.changeMasterPassword; + const oldUnlock = EncryptionService.unlockMasterKey; + const oldConfig: MasterKeyConfig = { + verificationHash: 'old', + salt: 'old-salt', + kdf: 'PBKDF2', + createdAt: NOW, + }; + const oldKey = await key(); + EncryptionService.changeMasterPassword = async () => ({ ...oldConfig, verificationHash: 'new' }); + EncryptionService.unlockMasterKey = async () => ({ + derivedKey: oldKey, + salt: new Uint8Array(), + unlockedAt: NOW, + }); + try { + const subject = { + state: { + masterKeyConfig: oldConfig, + securityState: 'UNLOCKED', + unlockedKey: { derivedKey: oldKey }, + autoSyncEnabled: false, + }, + masterPassword: 'old-password', + reencryptSyncStorage: async () => { + throw new Error('storage failed'); + }, + }; + + await assert.rejects( + () => changeMasterKeyImpl.call(subject, 'old-password', 'new-password'), + /storage failed/, + ); + assert.equal(subject.state.masterKeyConfig, oldConfig); + assert.equal(subject.masterPassword, 'old-password'); + assert.equal(subject.state.unlockedKey.derivedKey, oldKey); + } finally { + EncryptionService.changeMasterPassword = oldChange; + EncryptionService.unlockMasterKey = oldUnlock; + } +}); diff --git a/infrastructure/services/cloudSync/convergentSyncStorageMethods.ts b/infrastructure/services/cloudSync/convergentSyncStorageMethods.ts new file mode 100644 index 000000000..413998ee8 --- /dev/null +++ b/infrastructure/services/cloudSync/convergentSyncStorageMethods.ts @@ -0,0 +1,191 @@ +/* eslint-disable @typescript-eslint/no-explicit-any */ + +import { + SYNC_STORAGE_KEYS, + type CloudProvider, + type ConvergentProviderBaselineV2, + type ConvergentReplicaRecordV2, + type MasterKeyConfig, +} from '../../../domain/sync'; +import { + assertValidConvergentSyncState, + canonicalizeConvergentSyncState, + stripConvergentSyncEnvelope, +} from '../../../domain/convergentSync'; +import { + decryptLocalStorageValue, + encryptLocalStorageValue, +} from './encryptedLocalStorage'; + +const PROVIDERS: CloudProvider[] = ['github', 'google', 'onedrive', 'webdav', 's3']; + +export function convergentProviderBaselineKeyImpl(this: any, provider: CloudProvider): string { + return `${SYNC_STORAGE_KEYS.CONVERGENT_PROVIDER_BASELINE}_${provider}`; +} + +function requireLocalEncryptionKey(manager: any): CryptoKey { + const key = manager.state.unlockedKey?.derivedKey; + if (!key) throw new Error('Convergent sync encryption key is unavailable'); + return key; +} + +export async function saveConvergentReplicaImpl( + this: any, + record: ConvergentReplicaRecordV2, +): Promise { + if (record.schemaVersion !== 2) throw new Error('Unsupported convergent replica schema'); + assertValidConvergentSyncState(record.state); + const normalized: ConvergentReplicaRecordV2 = { + schemaVersion: 2, + state: canonicalizeConvergentSyncState(record.state), + updatedAt: record.updatedAt, + }; + if (this.saveToStorage( + SYNC_STORAGE_KEYS.CONVERGENT_REPLICA, + await encryptLocalStorageValue(normalized, requireLocalEncryptionKey(this)), + ) === false) throw new Error('Unable to persist convergent sync replica'); +} + +export async function loadConvergentReplicaImpl(this: any): Promise { + const encoded = this.loadFromStorage(SYNC_STORAGE_KEYS.CONVERGENT_REPLICA) as unknown; + if (!encoded) return null; + if (typeof encoded !== 'string') throw new Error('Convergent replica record is invalid'); + const record = await decryptLocalStorageValue( + encoded, + requireLocalEncryptionKey(this), + ); + if (record?.schemaVersion !== 2 || !Number.isFinite(record.updatedAt)) { + throw new Error('Convergent replica record has an unsupported schema'); + } + assertValidConvergentSyncState(record.state); + return { + schemaVersion: 2, + state: canonicalizeConvergentSyncState(record.state), + updatedAt: record.updatedAt, + }; +} + +export async function saveConvergentProviderBaselineImpl( + this: any, + baseline: ConvergentProviderBaselineV2, +): Promise { + if (baseline.schemaVersion !== 2) throw new Error('Unsupported convergent baseline schema'); + assertValidConvergentSyncState(baseline.state); + const normalized: ConvergentProviderBaselineV2 = { + ...baseline, + materializedPayload: stripConvergentSyncEnvelope(baseline.materializedPayload), + state: canonicalizeConvergentSyncState(baseline.state), + }; + if (this.saveToStorage( + this.convergentProviderBaselineKey(baseline.provider), + await encryptLocalStorageValue(normalized, requireLocalEncryptionKey(this)), + ) === false) throw new Error(`Unable to persist convergent baseline for ${baseline.provider}`); +} + +export async function loadConvergentProviderBaselineImpl( + this: any, + provider: CloudProvider, +): Promise { + const encoded = this.loadFromStorage(this.convergentProviderBaselineKey(provider)) as unknown; + if (!encoded) return null; + if (typeof encoded !== 'string') throw new Error(`Convergent baseline for ${provider} is invalid`); + const baseline = await decryptLocalStorageValue( + encoded, + requireLocalEncryptionKey(this), + ); + if (baseline?.schemaVersion !== 2 || baseline.provider !== provider) { + throw new Error(`Convergent baseline for ${provider} has an unsupported schema`); + } + assertValidConvergentSyncState(baseline.state); + return { + ...baseline, + materializedPayload: stripConvergentSyncEnvelope(baseline.materializedPayload), + state: canonicalizeConvergentSyncState(baseline.state), + }; +} + +export function clearConvergentSyncStorageImpl(this: any, confirmed: boolean): void { + if (!confirmed) throw new Error('Explicit confirmation is required to remove convergent sync state'); + this.removeFromStorage(SYNC_STORAGE_KEYS.CONVERGENT_REPLICA); + for (const provider of PROVIDERS) { + this.removeFromStorage(this.convergentProviderBaselineKey(provider)); + } +} + +function encryptedSyncStorageKeys(manager: any): string[] { + const keys = new Set([ + manager.syncBaseKey(), + manager.syncSnapshotsKey(), + SYNC_STORAGE_KEYS.CONVERGENT_REPLICA, + ]); + for (const provider of PROVIDERS) { + keys.add(manager.syncBaseKey(provider)); + keys.add(manager.syncSnapshotsKey(provider)); + keys.add(manager.convergentProviderBaselineKey(provider)); + } + return [...keys]; +} + +/** + * Re-encrypt every derived-key local record before committing the new master + * configuration. Values are prepared first, concurrent changes abort the + * transaction, and any write failure rolls all keys back to their exact prior + * ciphertext. + */ +export async function reencryptSyncStorageImpl( + this: any, + oldKey: CryptoKey, + newKey: CryptoKey, + newConfig: MasterKeyConfig, +): Promise { + const keys = encryptedSyncStorageKeys(this); + const previousConfig = ( + this.loadFromStorage(SYNC_STORAGE_KEYS.MASTER_KEY_CONFIG) + ?? this.state.masterKeyConfig + ) as MasterKeyConfig | null; + const originals = new Map(); + const replacements = new Map(); + for (const key of keys) { + const encoded = this.loadFromStorage(key) as unknown; + if (encoded == null) { + originals.set(key, null); + continue; + } + if (typeof encoded !== 'string') throw new Error(`Encrypted sync record ${key} is invalid`); + originals.set(key, encoded); + const value = await decryptLocalStorageValue(encoded, oldKey); + replacements.set(key, await encryptLocalStorageValue(value, newKey)); + } + for (const [key, original] of originals) { + const current = this.loadFromStorage(key) as unknown; + if ((current ?? null) !== original) { + throw new Error('Sync data changed while the master key was being rotated'); + } + } + const currentConfig = this.loadFromStorage( + SYNC_STORAGE_KEYS.MASTER_KEY_CONFIG, + ) as MasterKeyConfig | null; + if (JSON.stringify(currentConfig) !== JSON.stringify(previousConfig)) { + throw new Error('Master key configuration changed while it was being rotated'); + } + const committed: string[] = []; + try { + for (const [key, replacement] of replacements) { + if (this.saveToStorage(key, replacement) === false) { + throw new Error(`Unable to persist re-encrypted sync record: ${key}`); + } + committed.push(key); + } + if (this.saveToStorage(SYNC_STORAGE_KEYS.MASTER_KEY_CONFIG, newConfig) === false) { + throw new Error('Unable to persist the new master key configuration'); + } + } catch (error) { + for (const key of committed.reverse()) { + const original = originals.get(key); + if (original !== undefined) this.saveToStorage(key, original); + } + if (previousConfig) this.saveToStorage(SYNC_STORAGE_KEYS.MASTER_KEY_CONFIG, previousConfig); + else this.removeFromStorage(SYNC_STORAGE_KEYS.MASTER_KEY_CONFIG); + throw error; + } +} diff --git a/infrastructure/services/cloudSync/encryptedLocalStorage.ts b/infrastructure/services/cloudSync/encryptedLocalStorage.ts new file mode 100644 index 000000000..2ab24edbe --- /dev/null +++ b/infrastructure/services/cloudSync/encryptedLocalStorage.ts @@ -0,0 +1,26 @@ +export async function encryptLocalStorageValue(value: unknown, key: CryptoKey): Promise { + const data = new TextEncoder().encode(JSON.stringify(value)); + const iv = crypto.getRandomValues(new Uint8Array(12)); + const encrypted = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, data); + const combined = new Uint8Array(iv.length + encrypted.byteLength); + combined.set(iv); + combined.set(new Uint8Array(encrypted), iv.length); + let binary = ''; + const chunkSize = 8192; + for (let offset = 0; offset < combined.length; offset += chunkSize) { + binary += String.fromCharCode(...combined.subarray(offset, offset + chunkSize)); + } + return btoa(binary); +} + +export async function decryptLocalStorageValue( + encoded: string, + key: CryptoKey, +): Promise { + const combined = Uint8Array.from(atob(encoded), (character) => character.charCodeAt(0)); + if (combined.length <= 12) throw new Error('Encrypted local sync record is truncated'); + const iv = combined.slice(0, 12); + const ciphertext = combined.slice(12); + const decrypted = await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, key, ciphertext); + return JSON.parse(new TextDecoder().decode(decrypted)) as T; +} diff --git a/infrastructure/services/cloudSync/providerSyncMethods.ts b/infrastructure/services/cloudSync/providerSyncMethods.ts index 9d5c9c146..5771688dc 100644 --- a/infrastructure/services/cloudSync/providerSyncMethods.ts +++ b/infrastructure/services/cloudSync/providerSyncMethods.ts @@ -7,6 +7,7 @@ import { mergeSyncPayloads } from '../../../domain/syncMerge'; import { summarizeSyncChanges, withSyncReliabilityMeta } from '../../../domain/syncReliability'; import { detectSuspiciousShrink, type ShrinkFinding } from '../../../domain/syncGuards'; import { resolveCloudSyncConflictAction } from '../../../domain/syncStrategy'; +import { assertConvergentSyncWriteCompatible } from '../../../domain/convergentSync'; import type { CloudAdapter } from '../adapters'; import type GitHubAdapter from '../adapters/GitHubAdapter'; import type { @@ -56,6 +57,7 @@ async function uploadLocalPayloadImpl(this: any, remoteFile?: SyncedFile | null, syncSecurityGeneration?: number, ): Promise { + assertConvergentSyncWriteCompatible(remoteFile?.meta, payload); const overrideShrinkRequested = opts.overrideShrink === true; const directBase = await this.loadSyncBase(provider); assertSyncSecurityGeneration(this, syncSecurityGeneration); @@ -364,6 +366,7 @@ export async function syncToProviderImpl(this: any, deviceId: this.state.deviceId, now: Date.now(), }); + assertConvergentSyncWriteCompatible(checkResult.remoteFile.meta, mergedPayload); console.info('[CloudSyncManager] Three-way merge completed', mergeResult.summary); diff --git a/infrastructure/services/cloudSync/stateAndSecurityMethods.ts b/infrastructure/services/cloudSync/stateAndSecurityMethods.ts index bef61a79d..b9ab0c4d9 100644 --- a/infrastructure/services/cloudSync/stateAndSecurityMethods.ts +++ b/infrastructure/services/cloudSync/stateAndSecurityMethods.ts @@ -158,8 +158,8 @@ export function loadFromStorageImpl(this: any,key: string): T | null { return localStorageAdapter.read(key); } -export function saveToStorageImpl(this: any,key: string, value: unknown): void { - localStorageAdapter.write(key, value); +export function saveToStorageImpl(this: any,key: string, value: unknown): boolean { + return localStorageAdapter.write(key, value); } export function removeFromStorageImpl(this: any,key: string): void { @@ -565,18 +565,33 @@ export async function changeMasterKeyImpl(this: any,oldPassword: string, newPass return false; } + const oldUnlockedKey = await EncryptionService.unlockMasterKey( + oldPassword, + this.state.masterKeyConfig, + ); + const newUnlockedKey = await EncryptionService.unlockMasterKey( + newPassword, + newConfig, + ); + if (!oldUnlockedKey || !newUnlockedKey) { + throw new Error('Failed to derive keys for master key rotation'); + } + + // Local provider baselines, snapshots and the canonical CRDT replica use + // the master-derived key. Re-encrypt them before publishing the new master + // config so a failed rotation cannot strand records under mismatched keys. + await this.reencryptSyncStorage( + oldUnlockedKey.derivedKey, + newUnlockedKey.derivedKey, + newConfig, + ); + this.bumpSyncSecurityGeneration?.(); this.state.masterKeyConfig = newConfig; this.state.securityState = 'UNLOCKED'; this.masterPassword = newPassword; - // Re-derive key with new password - this.state.unlockedKey = await EncryptionService.unlockMasterKey( - newPassword, - newConfig - ); - - this.saveToStorage(SYNC_STORAGE_KEYS.MASTER_KEY_CONFIG, newConfig); + this.state.unlockedKey = newUnlockedKey; // Notify UI and restart auto-sync (actual re-upload requires a payload from app state) this.emit({ type: 'SECURITY_STATE_CHANGED', state: 'UNLOCKED' }); diff --git a/infrastructure/services/cloudSync/syncAllStorageMethods.test.ts b/infrastructure/services/cloudSync/syncAllStorageMethods.test.ts index f0ec897e9..885916abc 100644 --- a/infrastructure/services/cloudSync/syncAllStorageMethods.test.ts +++ b/infrastructure/services/cloudSync/syncAllStorageMethods.test.ts @@ -2,9 +2,13 @@ import test from "node:test"; import assert from "node:assert/strict"; import { EncryptionService } from "../EncryptionService.ts"; -import { commitRemoteInspectionImpl } from "./authMethods.ts"; +import { + clearProviderMergeStateImpl, + commitRemoteInspectionImpl, +} from "./authMethods.ts"; import { syncToProviderImpl, uploadToProviderImpl } from "./providerSyncMethods.ts"; import { + clearSyncBaseImpl, loadSyncSnapshotsImpl, saveSyncBaseImpl, syncAllProvidersImpl, @@ -57,6 +61,38 @@ function remoteFile(provider: CloudProvider, version: number, updatedAt: number) }; } +test("provider identity changes clear v1 base, v2 baseline, and remote anchor together", () => { + const removed: string[] = []; + const manager = { + syncBaseKey: (provider: CloudProvider) => `base:${provider}`, + convergentProviderBaselineKey: (provider: CloudProvider) => `convergent:${provider}`, + removeFromStorage: (key: string) => removed.push(key), + clearSyncAnchor: (provider: CloudProvider) => removed.push(`anchor:${provider}`), + }; + + clearProviderMergeStateImpl.call(manager, "github"); + + assert.deepEqual(removed, ["base:github", "convergent:github", "anchor:github"]); +}); + +test("clearing all merge bases also removes every convergent provider baseline", () => { + const removed = new Set(); + const providers: CloudProvider[] = ["github", "google", "onedrive", "webdav", "s3"]; + const manager = { + removeFromStorage: (key: string) => removed.add(key), + syncBaseKey: (provider?: CloudProvider) => `base:${provider ?? "default"}`, + syncSnapshotsKey: (provider?: CloudProvider) => `snapshots:${provider ?? "default"}`, + convergentProviderBaselineKey: (provider: CloudProvider) => `convergent:${provider}`, + clearSyncAnchor: () => {}, + }; + + clearSyncBaseImpl.call(manager); + + for (const provider of providers) { + assert.equal(removed.has(`convergent:${provider}`), true); + } +}); + test("syncAllProviders uses the newest cloud payload without merging other remotes when cloud wins", async () => { const originalDecryptPayload = EncryptionService.decryptPayload; const originalEncryptPayload = EncryptionService.encryptPayload; @@ -193,6 +229,46 @@ test("syncToProvider uses the checked remote as metadata base when no stored bas } }); +test("syncToProvider refuses to downgrade a checked convergent remote", async () => { + const checkedRemote = remoteFile("github", 3, 300); + checkedRemote.meta.syncSchemaVersion = 2; + let encrypted = false; + const originalEncryptPayload = EncryptionService.encryptPayload; + EncryptionService.encryptPayload = async () => { + encrypted = true; + return checkedRemote; + }; + try { + const manager = { + masterPassword: "pw", + adapters: new Map(), + state: { + securityState: "UNLOCKED", + providers: { github: { status: "connected" } }, + lastError: null, + syncState: "IDLE", + syncStrategy: "smartMerge", + localVersion: 1, + deviceId: "local-device", + deviceName: "Local", + }, + getConnectedAdapter: async () => ({ provider: "github" }), + updateProviderStatus: () => {}, + emit: () => {}, + checkProviderConflict: async () => ({ conflict: false, remoteFile: checkedRemote }), + addSyncHistoryEntry: () => {}, + }; + + const result = await syncToProviderImpl.call(manager, "github", payload("local")); + + assert.equal(result.success, false); + assert.equal(encrypted, false); + assert.match(result.error ?? "", /Enable or migrate convergent sync/); + } finally { + EncryptionService.encryptPayload = originalEncryptPayload; + } +}); + test("syncToProvider aborts an upload when the master key changes after encryption", async () => { const originalEncryptPayload = EncryptionService.encryptPayload; const localPayload = payload("local"); diff --git a/infrastructure/services/cloudSync/syncAllStorageMethods.ts b/infrastructure/services/cloudSync/syncAllStorageMethods.ts index ffdf21dc5..05f9ae8f0 100644 --- a/infrastructure/services/cloudSync/syncAllStorageMethods.ts +++ b/infrastructure/services/cloudSync/syncAllStorageMethods.ts @@ -14,15 +14,21 @@ import { } from '../../../domain/syncReliability'; import { detectSuspiciousShrink, type ShrinkFinding } from '../../../domain/syncGuards'; import { resolveCloudSyncConflictAction, type CloudSyncConflictAction } from '../../../domain/syncStrategy'; +import { assertConvergentSyncWriteCompatible } from '../../../domain/convergentSync'; import type { CloudAdapter } from '../adapters'; import type { CloudProvider, + ProviderConnection, SyncedFile, SyncHistoryEntry, SyncSnapshotEntry, SyncPayload, SyncResult, } from '../../../domain/sync'; +import { + decryptLocalStorageValue, + encryptLocalStorageValue, +} from './encryptedLocalStorage'; function getSyncSecurityGeneration(manager: any): number | undefined { return typeof manager.getSyncSecurityGeneration === 'function' @@ -61,35 +67,12 @@ async function downloadRemoteForSyncAllImpl(this: any, const SYNC_HISTORY_STORAGE_KEY = 'netcatty_sync_history_v1'; const SYNC_SNAPSHOTS_STORAGE_KEY = 'netcatty_sync_snapshots_v1'; -async function encryptForLocalStorage(payload: unknown, key: CryptoKey): Promise { - const data = new TextEncoder().encode(JSON.stringify(payload)); - const iv = crypto.getRandomValues(new Uint8Array(12)); - const encrypted = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, data); - const combined = new Uint8Array(iv.length + encrypted.byteLength); - combined.set(iv); - combined.set(new Uint8Array(encrypted), iv.length); - let binary = ''; - const CHUNK = 8192; - for (let i = 0; i < combined.length; i += CHUNK) { - binary += String.fromCharCode(...combined.subarray(i, i + CHUNK)); - } - return btoa(binary); -} - -async function decryptFromLocalStorage(encoded: string, key: CryptoKey): Promise { - const combined = Uint8Array.from(atob(encoded), (c) => c.charCodeAt(0)); - const iv = combined.slice(0, 12); - const ciphertext = combined.slice(12); - const decrypted = await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, key, ciphertext); - return JSON.parse(new TextDecoder().decode(decrypted)) as T; -} - async function loadRawSyncBase(this: any, provider?: CloudProvider): Promise { const key = this.state.unlockedKey?.derivedKey; if (!key || typeof this.loadFromStorage !== 'function') return null; const encoded = this.loadFromStorage(this.syncBaseKey(provider)); if (!encoded || typeof encoded !== 'string') return null; - return decryptFromLocalStorage(encoded, key); + return decryptLocalStorageValue(encoded, key); } async function rememberCurrentSyncBaseSnapshot(this: any, provider?: CloudProvider): Promise { @@ -130,7 +113,9 @@ export async function syncAllProvidersImpl(this: any, return results; } - const connectedProviders = Object.entries(this.state.providers) + const connectedProviders = Object.entries( + this.state.providers as Record, + ) .filter(([provider, connection]) => { if (!isProviderReadyForSync(connection)) return false; if (connection.status === 'error') { @@ -515,10 +500,11 @@ export async function syncAllProvidersImpl(this: any, // fresh anchor paired with a stale base. const uploadTasks = validUploads.map(async ({ provider, adapter }) => { try { + const entry = checkResults.find((result) => result.provider === provider); + assertConvergentSyncWriteCompatible(entry?.check?.remoteFile?.meta, payload); const providerBase = await this.loadSyncBase(provider); let providerRemoteRef: SyncPayload | null = null; if (!providerBase) { - const entry = checkResults.find((r) => r.provider === provider); const remoteFile = entry?.check?.remoteFile; if (remoteFile) { assertSyncSecurityGeneration(this, syncSecurityGeneration); @@ -670,7 +656,8 @@ export function providerAccountIdKeyImpl(this: any,provider: CloudProvider): str } export function loadProviderAccountIdImpl(this: any,provider: CloudProvider): string | null { - return this.loadFromStorage(this.providerAccountIdKey(provider)) ?? null; + const stored = this.loadFromStorage(this.providerAccountIdKey(provider)); + return typeof stored === 'string' ? stored : null; } export function saveProviderAccountIdImpl(this: any,provider: CloudProvider, id: string): void { @@ -688,7 +675,14 @@ export async function saveSyncBaseImpl(this: any,payload: SyncPayload, provider? } catch (snapshotError) { console.warn('[CloudSyncManager] Failed to save previous sync snapshot', snapshotError); } - this.saveToStorage(this.syncBaseKey(provider), await encryptForLocalStorage(payload, key)); + if ( + this.saveToStorage( + this.syncBaseKey(provider), + await encryptLocalStorageValue(payload, key), + ) === false + ) { + throw new Error('Unable to persist sync base'); + } } catch (error) { console.warn('[CloudSyncManager] Failed to save sync base', error); throw error; @@ -699,9 +693,9 @@ export async function loadSyncBaseImpl(this: any,provider?: CloudProvider): Prom const key = this.state.unlockedKey?.derivedKey; if (!key) return null; try { - const encoded = this.loadFromStorage(this.syncBaseKey(provider)); + const encoded = this.loadFromStorage(this.syncBaseKey(provider)) as unknown; if (!encoded || typeof encoded !== 'string') return null; - return decryptFromLocalStorage(encoded, key); + return decryptLocalStorageValue(encoded, key); } catch { return null; } @@ -716,9 +710,9 @@ export async function loadSyncSnapshotsImpl(this: any,provider?: CloudProvider): const key = this.state.unlockedKey?.derivedKey; if (!key) return []; try { - const encoded = this.loadFromStorage(this.syncSnapshotsKey(provider)); + const encoded = this.loadFromStorage(this.syncSnapshotsKey(provider)) as unknown; if (!encoded || typeof encoded !== 'string') return []; - const snapshots = await decryptFromLocalStorage(encoded, key); + const snapshots = await decryptLocalStorageValue(encoded, key); return Array.isArray(snapshots) ? snapshots : []; } catch { return []; @@ -730,10 +724,10 @@ export async function saveSyncSnapshotsImpl(this: any,snapshots: SyncSnapshotEnt if (!key) { throw new Error('Sync snapshot encryption key is unavailable'); } - this.saveToStorage( + if (this.saveToStorage( this.syncSnapshotsKey(provider), - await encryptForLocalStorage(snapshots.slice(0, SYNC_SNAPSHOT_LIMIT), key), - ); + await encryptLocalStorageValue(snapshots.slice(0, SYNC_SNAPSHOT_LIMIT), key), + ) === false) throw new Error('Unable to persist sync snapshots'); } export function clearSyncBaseImpl(this: any): void { @@ -743,6 +737,7 @@ export function clearSyncBaseImpl(this: any): void { } for (const p of ['github', 'google', 'onedrive', 'webdav', 's3'] as const) { this.removeFromStorage(this.syncBaseKey(p)); + this.removeFromStorage(this.convergentProviderBaselineKey(p)); if (typeof this.syncSnapshotsKey === 'function') { this.removeFromStorage(this.syncSnapshotsKey(p)); } diff --git a/infrastructure/services/convergentSyncConfig.test.ts b/infrastructure/services/convergentSyncConfig.test.ts new file mode 100644 index 000000000..dd9e49f15 --- /dev/null +++ b/infrastructure/services/convergentSyncConfig.test.ts @@ -0,0 +1,39 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; + +const values = new Map(); +Object.defineProperty(globalThis, 'localStorage', { + configurable: true, + value: { + getItem: (key: string) => values.get(key) ?? null, + setItem: (key: string, value: string) => values.set(key, value), + removeItem: (key: string) => values.delete(key), + clear: () => values.clear(), + }, +}); + +const { + clearConvergentSyncLocalConfigAfterDowngrade, + getConvergentSyncLocalConfig, + markConvergentSyncInitialized, + pauseConvergentSync, +} = await import('./convergentSyncConfig.ts'); + +test.beforeEach(() => values.clear()); + +test('pausing an initialized replica preserves its initialized metadata', () => { + markConvergentSyncInitialized(); + assert.deepEqual(pauseConvergentSync(), { enabled: false, initialized: true }); + assert.deepEqual(getConvergentSyncLocalConfig(), { enabled: false, initialized: true }); +}); + +test('downgrade state cannot be cleared without explicit confirmation', () => { + markConvergentSyncInitialized(); + assert.throws( + () => clearConvergentSyncLocalConfigAfterDowngrade(false), + /Explicit confirmation/, + ); + assert.deepEqual(getConvergentSyncLocalConfig(), { enabled: true, initialized: true }); + clearConvergentSyncLocalConfigAfterDowngrade(true); + assert.deepEqual(getConvergentSyncLocalConfig(), { enabled: false, initialized: false }); +}); diff --git a/infrastructure/services/convergentSyncConfig.ts b/infrastructure/services/convergentSyncConfig.ts new file mode 100644 index 000000000..618a27a9c --- /dev/null +++ b/infrastructure/services/convergentSyncConfig.ts @@ -0,0 +1,55 @@ +import { STORAGE_KEY_CONVERGENT_SYNC_CONFIG } from '../config/storageKeys'; +import { localStorageAdapter } from '../persistence/localStorageAdapter'; + +export interface ConvergentSyncLocalConfig { + enabled: boolean; + initialized: boolean; +} + +const DEFAULT_CONFIG: ConvergentSyncLocalConfig = { + enabled: false, + initialized: false, +}; + +export function getConvergentSyncLocalConfig(): ConvergentSyncLocalConfig { + const stored = localStorageAdapter.read>( + STORAGE_KEY_CONVERGENT_SYNC_CONFIG, + ); + return { + enabled: stored?.enabled === true, + initialized: stored?.initialized === true, + }; +} + +export function setConvergentSyncLocalConfig( + config: ConvergentSyncLocalConfig, +): ConvergentSyncLocalConfig { + const normalized = { + enabled: config.enabled === true, + initialized: config.initialized === true, + }; + if (!localStorageAdapter.write(STORAGE_KEY_CONVERGENT_SYNC_CONFIG, normalized)) { + throw new Error('Unable to persist convergent sync configuration'); + } + return normalized; +} + +/** Disabling after initialization pauses v2; it never removes replica metadata. */ +export function pauseConvergentSync(): ConvergentSyncLocalConfig { + const current = getConvergentSyncLocalConfig(); + return setConvergentSyncLocalConfig({ + enabled: false, + initialized: current.initialized, + }); +} + +export function markConvergentSyncInitialized(): ConvergentSyncLocalConfig { + return setConvergentSyncLocalConfig({ enabled: true, initialized: true }); +} + +export function clearConvergentSyncLocalConfigAfterDowngrade( + confirmed: boolean, +): ConvergentSyncLocalConfig { + if (!confirmed) throw new Error('Explicit confirmation is required to downgrade convergent sync'); + return setConvergentSyncLocalConfig(DEFAULT_CONFIG); +}