Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
fix: keep this machine's federation identity when restoring another machine's backup (#12596)
[._.]/ Adam Eivyc7da345aeded
diff --git a/client/src/components/BackupWidget.jsx b/client/src/components/BackupWidget.jsxindex ebfd7f22c1..1f8f47a561 100644--- a/client/src/components/BackupWidget.jsx+++ b/client/src/components/BackupWidget.jsx@@ -64,6 +64,12 @@ const snapshotSourceLabel = (snapshot) =>snapshot.sourceLabel || snapshot.source || 'Current machine';const legacyStoreNames = (stores, status) =>stores.filter(store => store.status === status).map(store => store.store).join(', ');+const restoreRequest = (snapshot, filter, adoptIdentity) => ({+ snapshotId: snapshot.id,+ ...(snapshot.source ? { source: snapshot.source } : {}),+ subdirFilter: filter.trim() || null,+ ...(adoptIdentity ? { adoptIdentity: true } : {}),+});// ---------------------------------------------------------------------------// RestorePanel@@ -71,36 +77,45 @@ const legacyStoreNames = (stores, status) =>function RestorePanel({ snapshot, onClose, restoring, onRestoreStateChange }) {const filterId = useId();+ const adoptIdentityId = useId();const [filter, setFilter] = useState('');+ // Kept apart from the accepted preview so the adopt checkbox stays on screen+ // while toggling it invalidates that preview (#12596).+ const [identityMismatch, setIdentityMismatch] = useState(null);+ const [adoptIdentity, setAdoptIdentity] = useState(false);const [acceptedPreview, setAcceptedPreview] = useState(null);const [previewing, setPreviewing] = useState(false);const previewGenerationRef = useRef(0);- const currentRequest = {- snapshotId: snapshot.id,- ...(snapshot.source ? { source: snapshot.source } : {}),- subdirFilter: filter.trim() || null,- };+ const currentRequest = restoreRequest(snapshot, filter, adoptIdentity);const previewMatchesCurrentRequest = acceptedPreview&& acceptedPreview.request.snapshotId === currentRequest.snapshotId&& acceptedPreview.request.source === currentRequest.source- && acceptedPreview.request.subdirFilter === currentRequest.subdirFilter;+ && acceptedPreview.request.subdirFilter === currentRequest.subdirFilter+ && acceptedPreview.request.adoptIdentity === currentRequest.adoptIdentity;- const handleFilterChange = useCallback((event) => {+ const invalidatePreview = useCallback(() => {previewGenerationRef.current += 1;- setFilter(event.target.value);setAcceptedPreview(null);setPreviewing(false);}, []);+ const handleFilterChange = useCallback((event) => {+ invalidatePreview();+ setFilter(event.target.value);+ setIdentityMismatch(null);+ setAdoptIdentity(false);+ }, [invalidatePreview]);++ const handleAdoptIdentityChange = useCallback((event) => {+ invalidatePreview();+ setAdoptIdentity(event.target.checked);+ }, [invalidatePreview]);+const handlePreview = useCallback(async () => {const generation = previewGenerationRef.current + 1;previewGenerationRef.current = generation;- const request = {- snapshotId: snapshot.id,- ...(snapshot.source ? { source: snapshot.source } : {}),- subdirFilter: filter.trim() || null,- };+ const request = restoreRequest(snapshot, filter, adoptIdentity);setPreviewing(true);setAcceptedPreview(null);const outcome = await api.restoreBackup({@@ -117,8 +132,15 @@ function RestorePanel({ snapshot, onClose, restoring, onRestoreStateChange }) {toast.error(`Preview failed: ${outcome.previewError.message}`);return;}- if (outcome.previewResult) setAcceptedPreview({ request, result: outcome.previewResult });- }, [snapshot.id, snapshot.source, filter]);+ if (outcome.previewResult) {+ const { identityPreserved, identityAdopted } = outcome.previewResult;+ const mismatch = identityPreserved ?? identityAdopted ?? null;+ setIdentityMismatch(mismatch);+ // Never send an adoption the operator can no longer see or uncheck.+ if (!mismatch) setAdoptIdentity(false);+ setAcceptedPreview({ request: mismatch ? request : restoreRequest(snapshot, filter, false), result: outcome.previewResult });+ }+ }, [snapshot, filter, adoptIdentity]);const handleRestore = useCallback(async () => {if (!previewMatchesCurrentRequest || restoring) return;@@ -197,6 +219,30 @@ function RestorePanel({ snapshot, onClose, restoring, onRestoreStateChange }) {Preview changes</button>+ {identityMismatch && (+ <div className="space-y-2 rounded border border-port-warning/40 bg-port-warning/10 p-2 text-xs text-port-warning" role="alert">+ <p className="flex items-start gap-1.5">+ <AlertTriangle size={13} className="mt-0.5 shrink-0" />+ <span className="min-w-0 break-words">+ This snapshot belongs to another federation identity ({identityMismatch.snapshotInstanceId ?? 'unreadable'}) than this machine ({identityMismatch.liveInstanceId ?? 'unreadable'}). {adoptIdentity+ ? 'Its instances.json (identity, peers and pair secrets) will replace this machine\'s. If that machine is still running, both will claim the same tasks and sync records.'+ : 'This machine keeps its own instances.json, so it stays a separate peer; every other file restores normally.'}+ </span>+ </p>+ <label htmlFor={adoptIdentityId} className="flex items-start gap-2 text-gray-300">+ <input+ id={adoptIdentityId}+ type="checkbox"+ checked={adoptIdentity}+ onChange={handleAdoptIdentityChange}+ disabled={restoring}+ className="mt-0.5"+ />+ <span>Adopt the snapshot's identity — only if the machine that made it is retired</span>+ </label>+ </div>+ )}+{/* Dry-run results */}{preview && (<div>diff --git a/client/src/components/BackupWidget.test.jsx b/client/src/components/BackupWidget.test.jsxindex 2f770dd251..aca5d3aa46 100644--- a/client/src/components/BackupWidget.test.jsx+++ b/client/src/components/BackupWidget.test.jsx@@ -237,6 +237,64 @@ describe('BackupWidget snapshots', () => {expect(mockToast.success).toHaveBeenCalledWith('File restore complete — 1 file(s) restored');});+ it('keeps the live federation identity unless the operator adopts the snapshot identity (#12596)', async () => {+ const ids = { liveInstanceId: 'live-instance', snapshotInstanceId: 'other-instance' };+ mockRestoreBackup+ .mockResolvedValueOnce({ changedFiles: ['>f+++++++++ brain/example.json'], identityPreserved: ids })+ .mockResolvedValueOnce({ changedFiles: ['>f+++++++++ instances.json'], identityAdopted: ids })+ .mockResolvedValueOnce({ changedFiles: ['>f+++++++++ instances.json'], identityAdopted: ids });+ renderWidget();++ await openRestorePanel();+ fireEvent.click(screen.getByRole('button', { name: 'Preview changes' }));+ expect(await screen.findByText(/This machine keeps its own instances.json/)).toBeInTheDocument();+ const adopt = screen.getByRole('checkbox', { name: /Adopt the snapshot.s identity/ });+ expect(adopt).not.toBeChecked();++ // Adopting changes what execution does, so the old preview cannot authorize it.+ fireEvent.click(adopt);+ expect(screen.queryByRole('button', { name: /^Restore \d/ })).not.toBeInTheDocument();+ expect(screen.getByText(/will replace this machine.s/)).toBeInTheDocument();++ fireEvent.click(screen.getByRole('button', { name: 'Preview changes' }));+ expect(await screen.findByText('>f+++++++++ instances.json')).toBeInTheDocument();+ expect(mockRestoreBackup).toHaveBeenNthCalledWith(2, {+ snapshotId: '2026-08-25T11-00-00',+ subdirFilter: null,+ adoptIdentity: true,+ dryRun: true,+ }, { silent: true });++ fireEvent.click(screen.getByRole('button', { name: 'Restore 1 file(s)' }));+ await waitFor(() => expect(mockRestoreBackup).toHaveBeenNthCalledWith(3, {+ snapshotId: '2026-08-25T11-00-00',+ subdirFilter: null,+ adoptIdentity: true,+ dryRun: false,+ }, { silent: true }));+ });++ it('drops a hidden adoption when a fresh preview shows no identity mismatch (#12596)', async () => {+ mockRestoreBackup+ .mockResolvedValueOnce({ changedFiles: ['>f+++++++++ brain/example.json'], identityPreserved: { liveInstanceId: 'a', snapshotInstanceId: 'b' } })+ .mockResolvedValueOnce({ changedFiles: ['>f+++++++++ brain/example.json'] })+ .mockResolvedValueOnce({ changedFiles: ['>f+++++++++ brain/example.json'] });+ renderWidget();++ await openRestorePanel();+ fireEvent.click(screen.getByRole('button', { name: 'Preview changes' }));+ fireEvent.click(await screen.findByRole('checkbox', { name: /Adopt the snapshot.s identity/ }));+ fireEvent.click(screen.getByRole('button', { name: 'Preview changes' }));++ fireEvent.click(await screen.findByRole('button', { name: 'Restore 1 file(s)' }));+ expect(screen.queryByRole('checkbox')).not.toBeInTheDocument();+ await waitFor(() => expect(mockRestoreBackup).toHaveBeenNthCalledWith(3, {+ snapshotId: '2026-08-25T11-00-00',+ subdirFilter: null,+ dryRun: false,+ }, { silent: true }));+ });+it('describes restore as files-only and never claims all data is up to date', async () => {mockRestoreBackup.mockResolvedValueOnce({ changedFiles: [] });renderWidget();diff --git a/docs/BACKUP.md b/docs/BACKUP.mdindex dd24a12eb9..6ddd748e81 100644--- a/docs/BACKUP.md+++ b/docs/BACKUP.md@@ -521,6 +521,16 @@ A full restore also installs the snapshot's `migrations.applied.json`, so the ne`data/database-authority.json` is backed up as cutover evidence but is never installed by a file restore. It records which database backend a completed cutover retired on the machine that ran it, so restoring it from another machine's snapshot (or from an older snapshot after a reverse cutover) would make PortOS refuse its own healthy database with `DATABASE_RETIRED_BACKEND`, including after a restart. Every file restore therefore excludes it, in preview and execution alike, and the integrity preflight ignores it too. The destination's existing file stays byte-for-byte as it was: an absent record stays absent and a damaged one stays fail-closed. The same preservation covers the other machine-local authority and recovery records — `peer-execution/`, `peer-execution-catalog.json`, `peer-execution-grants.json`, `peer-execution-authority.json`, `peer-execution-recovery.jsonl`, `workflow-maintenance/` (the graceful-maintenance journal and abandoned-run receipts) and `backup-admission/` (which snapshots also skip) — so a snapshot's copy is evidence only (see [STORAGE.md](./STORAGE.md)). Other records in the snapshot restore normally. Selecting any of these paths, including `database-authority.json` itself, is refused with `BACKUP_RESTORE_MACHINE_LOCAL` before anything is transferred. This does not touch an active maintenance journal (`database-maintenance/`): its recovery semantics are unchanged, and another machine's cutover endpoints are never imported. To change which backend is authoritative, run a database cutover.+#### Federation identity is kept unless adopted++`data/instances.json` holds this install's federation identity (`self.instanceId`), its peer list and each peer's pair secret. A shared destination lists every machine's snapshots, so installing another machine's file would give two live installs one identity: both would claim the same CoS tasks, sign pushes with the same pair credentials and advance the same per-peer sync cursors (#12596). Before verification, a restore whose scope reaches `instances.json` (a full restore or `subdirFilter: 'instances.json'`) compares the snapshot's `self.instanceId` with the live file's:++- **Same identity, or no live identity** (this machine's own older snapshot, or a never-federated install): the file restores as before.+- **Different identity:** the live file is kept byte-for-byte. It is excluded from the rsync transfer, the manifest selection and the scope inventory exactly like the machine-local records above, so preview and execution agree, and both report `identityPreserved: { liveInstanceId, snapshotInstanceId }`. Every other file restores normally. An unreadable live file counts as an identity (`liveInstanceId: null`), since its owner cannot be known; an unreadable snapshot file reports `snapshotInstanceId: null`.+- **`adoptIdentity: true`** installs the snapshot's file anyway and reports `identityAdopted`. Use it only to replace a retired machine. The restore panel shows the mismatch with an unchecked "Adopt the snapshot's identity — only if the machine that made it is retired" checkbox; toggling it requires a new preview.++Any restore that does not install the snapshot's `instances.json` (including a snapshot that had none when checked) excludes it from the transfer, so bytes that appear later cannot reach the live file. Because the choice is made before verification, execution re-checks it under the identity writer lock immediately before rsync starts; if the live identity changed in between (a first pairing, for example), the restore is refused with `409 BACKUP_RESTORE_IDENTITY_CHANGED` before any file is written. Whenever a restore installs `instances.json`, the memoized instance id is dropped after the transfer (even a partial one), so `getInstanceId()` and peer request headers follow the restored identity without a restart.+### Database — `restorePostgres()`Replays the snapshot's `portos-db.sql` into the live database via `psql -v ON_ERROR_STOP=1 --single-transaction`, so the **SQL replay is atomic**: a failed replay rolls back.@@ -645,9 +655,9 @@ boundary there rather than nesting another wrapper. Snapshot integrity isverified before any boundary is acquired, and a dry run acquires none of them.The peer-execution identity fence is shorter-lived: it wraps only the rsync-transfer, never reconciliation, and only when the scope can reach-`instances.json` and the snapshot actually contains that file (probed inside the-held boundaries).+transfer, never reconciliation, and only when the restore installs+`instances.json` (see [Federation identity is kept unless adopted](#federation-identity-is-kept-unless-adopted);+decided before verification, so a preview reports the same choice).A restore callback must never call a queued settings write API; cache reload readsdirectly and does not re-enter the queue.diff --git a/server/lib/peerHttpClient.js b/server/lib/peerHttpClient.jsindex 7a5ff8aaef..43ffd94242 100644--- a/server/lib/peerHttpClient.js+++ b/server/lib/peerHttpClient.js@@ -74,6 +74,8 @@ function peerCredentialHeaders(peer, selfInstanceId) {}// Our own federation instance id, memoized after the first successful read.+// A restore that installs instances.json drops it (resetSelfInstanceIdCache,+// #12596), so the restored id applies without a restart.// Resolved through a dynamic import of the identity leaf (#6836): harmless to// static-import now (services/instanceIdentity.js is a leaf with no edge back// to this module — the old cycle ran through services/instances.js, which@@ -91,8 +93,8 @@ async function selfInstanceId() {return cachedSelfInstanceId;}-/** Test-support: drop the memoized instance id. */-export function __resetSelfInstanceIdForTests() {+/** Drop the memoized instance id; the next hop re-reads the identity leaf. */+export function resetSelfInstanceIdCache() {cachedSelfInstanceId = null;}diff --git a/server/lib/peerHttpClient.test.js b/server/lib/peerHttpClient.test.jsindex 28f947f1ca..a50d65db87 100644--- a/server/lib/peerHttpClient.test.js+++ b/server/lib/peerHttpClient.test.js@@ -85,7 +85,7 @@ import {PEER_BODY_IDLE_TIMEOUT,peerAuthHeaders,derivePeerAuthToken,- __resetSelfInstanceIdForTests,+ resetSelfInstanceIdCache,} from './peerHttpClient.js';import { RESPONSE_TOO_LARGE } from './httpClient.js';@@ -107,7 +107,7 @@ describe('peerHttpClient', () => {beforeEach(() => {selfInstanceId = 'self-instance-id';- __resetSelfInstanceIdForTests();+ resetSelfInstanceIdCache();calls = [];globalThis.fetch = async (url, options) => {calls.push({ url, options });@@ -117,7 +117,7 @@ describe('peerHttpClient', () => {afterEach(() => {globalThis.fetch = realFetch;- __resetSelfInstanceIdForTests();+ resetSelfInstanceIdCache();});it('identifies this install with X-PortOS-Instance-Id on every hop', async () => {@@ -221,7 +221,7 @@ describe('peerHttpClient', () => {it('omits the header entirely when this install has no identity yet', async () => {selfInstanceId = 'unknown';- __resetSelfInstanceIdForTests();+ resetSelfInstanceIdCache();await peerFetch('http://peer.example/x');expect(calls[0].options.headers['X-PortOS-Instance-Id']).toBeUndefined();});@@ -246,7 +246,7 @@ describe('peerHttpClient', () => {beforeEach(() => {servers = [];selfInstanceId = 'self-instance-id';- __resetSelfInstanceIdForTests();+ resetSelfInstanceIdCache();});afterEach(async () => {@@ -254,7 +254,7 @@ describe('peerHttpClient', () => {server.close(resolve);server.closeAllConnections();})));- __resetSelfInstanceIdForTests();+ resetSelfInstanceIdCache();});const serve = async (handler) => {@@ -324,13 +324,13 @@ describe('peerHttpClient', () => {beforeEach(() => {selfInstanceId = 'self-instance-id';- __resetSelfInstanceIdForTests();+ resetSelfInstanceIdCache();});afterEach(async () => {if (fixture) await fixture.close();fixture = null;- __resetSelfInstanceIdForTests();+ resetSelfInstanceIdCache();});it('destroys an unbounded response stream after it exceeds maxBytes', async () => {diff --git a/server/lib/validation.js b/server/lib/validation.jsindex 9cb7a33912..30c9cd0665 100644--- a/server/lib/validation.js+++ b/server/lib/validation.js@@ -1178,7 +1178,9 @@ export const restoreRequestSchema = z.object({snapshotId: z.string().min(1),source: snapshotSourceSchema.optional(),subdirFilter: subdirFilterSchema.optional().nullable(),- dryRun: z.boolean().optional().default(true)+ dryRun: z.boolean().optional().default(true),+ // Install a snapshot's different federation identity over this machine's (#12596).+ adoptIdentity: z.boolean().optional().default(false)});export const restoreDbRequestSchema = z.object({diff --git a/server/routes/backup.js b/server/routes/backup.jsindex 0c4a09f98c..88e1877818 100644--- a/server/routes/backup.js+++ b/server/routes/backup.js@@ -87,7 +87,7 @@ router.delete('/snapshots/:snapshotId', asyncHandler(async (req, res) => {// POST /api/backup/restorerouter.post('/restore', asyncHandler(async (req, res) => {- const { snapshotId, source, subdirFilter, dryRun } = validateRequest(restoreRequestSchema, req.body);+ const { snapshotId, source, subdirFilter, dryRun, adoptIdentity } = validateRequest(restoreRequestSchema, req.body);const settings = await getSettings();const destPath = settings.backup?.destPath;if (!destPath) {@@ -96,6 +96,7 @@ router.post('/restore', asyncHandler(async (req, res) => {const result = await backup.restoreSnapshot(destPath, snapshotId, {dryRun,subdirFilter,+ adoptIdentity,...(source ? { source } : {}),});res.json(result);diff --git a/server/routes/backup.test.js b/server/routes/backup.test.jsindex 3f9504f200..2634f36d4c 100644--- a/server/routes/backup.test.js+++ b/server/routes/backup.test.js@@ -368,10 +368,27 @@ describe('backup routes', () => {expect(backup.restoreSnapshot).toHaveBeenCalledWith('/dest','snap-1',- { dryRun: false, subdirFilter: 'data' }+ { dryRun: false, subdirFilter: 'data', adoptIdentity: false });});+ it('forwards an explicit identity adoption and refuses a non-boolean one (#12596)', async () => {+ getSettings.mockResolvedValue({ backup: { destPath: '/dest' } });+ backup.restoreSnapshot.mockResolvedValue({ changedFiles: [] });+ const adopted = await request(buildApp())+ .post('/api/backup/restore')+ .send({ snapshotId: 'snap-1', dryRun: false, adoptIdentity: true });+ expect(adopted.status).toBe(200);+ expect(backup.restoreSnapshot).toHaveBeenCalledWith('/dest', 'snap-1', expect.objectContaining({ adoptIdentity: true }));++ backup.restoreSnapshot.mockClear();+ const refused = await request(buildApp())+ .post('/api/backup/restore')+ .send({ snapshotId: 'snap-1', dryRun: false, adoptIdentity: 'yes' });+ expect(refused.status).toBe(400);+ expect(backup.restoreSnapshot).not.toHaveBeenCalled();+ });+it('refuses a restore of a snapshot whose deletion is in progress with a structured conflict (#10898)', async () => {getSettings.mockResolvedValue({ backup: { destPath: '/dest' } });backup.restoreSnapshot.mockRejectedValueOnce(new ServerError(@@ -398,6 +415,7 @@ describe('backup routes', () => {expect(backup.restoreSnapshot).toHaveBeenCalledWith('/dest', 'snap-1', {dryRun: true,subdirFilter: null,+ adoptIdentity: false,source: '@legacy',});});diff --git a/server/services/backup.js b/server/services/backup.jsindex a2f4e6b126..0f07832c68 100644--- a/server/services/backup.js+++ b/server/services/backup.js@@ -1434,7 +1434,7 @@ async function reconcileLiveFileRestore(subdirFilter) {}}-function manifestDataEntries(manifest, srcDir, subdirFilter) {+function manifestDataEntries(manifest, srcDir, subdirFilter, isSkippedPath = isRestorePreservedPath) {if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)|| !manifest.files || typeof manifest.files !== 'object' || Array.isArray(manifest.files)|| !Number.isInteger(manifest.fileCount) || manifest.fileCount < 0@@ -1469,7 +1469,7 @@ function manifestDataEntries(manifest, srcDir, subdirFilter) {// Still recorded in dataPaths (inventory consistency), but never hashed:// Finder may rewrite a hashed metadata file that restore never transfers.- if (isRestorePreservedPath(normalized) || isOsMetadataFile(segments.at(-1))) continue;+ if (isSkippedPath(normalized) || isOsMetadataFile(segments.at(-1))) continue;if (!subdirFilter || normalized === subdirFilter || normalized.startsWith(`${subdirFilter}/`)) {selected.push({ filePath, expectedHash });}@@ -1532,6 +1532,56 @@ const restoreScopeIsPreservedFile = (subdirFilter) => {return isRestorePreservedPath(normalized);};+/**+ * `instances.json` holds this install's federation identity (`self.instanceId`),+ * its peers and their pair secrets. A shared destination offers every machine's+ * snapshots, so installing another machine's file would give two live installs+ * one identity: each claims the other's CoS tasks and signs pushes with the+ * other's pair credentials (#12596). A restore therefore installs it only when+ * the identities match, the live install has none, or the operator adopts the+ * snapshot's identity (replacing a retired machine). Otherwise it is preserved+ * through the same three places as RESTORE_PRESERVED_FILES.+ */+const IDENTITY_FILE = 'instances.json';+const IDENTITY_RSYNC_EXCLUDE = `--exclude=/${caseInsensitiveGlob(IDENTITY_FILE)}`;+const isIdentityPath = relativePath => typeof relativePath === 'string' && relativePath.toLowerCase() === IDENTITY_FILE;+const IDENTITY_ABSENT = Symbol('identity-absent');++async function readIdentityFile(path) {+ const { ok, value } = await readJSONFileStrict(path, IDENTITY_ABSENT, { logError: false });+ if (ok && value === IDENTITY_ABSENT) return { present: false, readable: true, instanceId: null };+ const instanceId = ok ? value?.self?.instanceId : null;+ return { present: true, readable: ok, instanceId: typeof instanceId === 'string' && instanceId ? instanceId : null };+}++/**+ * Whether this restore installs the snapshot's instances.json. Decided before+ * the integrity preflight so preview and execution exclude the same bytes. An+ * unreadable live file counts as an identity (fail closed): only adoption+ * replaces it, since its owner cannot be known.+ */+async function resolveIdentityRestore(srcDir, subdirFilter, adoptIdentity) {+ const notInstalled = { installs: false, preserved: null, adopted: null };+ if (subdirFilter && !isIdentityPath(subdirFilter)) return notInstalled;+ const snapshot = await readIdentityFile(join(srcDir, IDENTITY_FILE));+ if (!snapshot.present) return notInstalled;+ const live = await readIdentityFile(join(PATHS.data, IDENTITY_FILE));+ const liveHasIdentity = live.present && (live.instanceId !== null || !live.readable);+ if (!liveHasIdentity || (live.instanceId !== null && live.instanceId === snapshot.instanceId)) {+ return { installs: true, preserved: null, adopted: null };+ }+ const ids = { liveInstanceId: live.instanceId, snapshotInstanceId: snapshot.instanceId };+ return adoptIdentity+ ? { installs: true, preserved: null, adopted: ids }+ : { ...notInstalled, preserved: ids };+}++// `beforeTransfer`: nothing was written, so the caller must not report a partial restore.+const identityChangedError = () => Object.assign(new ServerError(+ 'This machine\'s federation identity (instances.json) changed after the restore was checked. Nothing was restored; preview the restore again.',+ { status: 409, code: 'BACKUP_RESTORE_IDENTITY_CHANGED' },+), { beforeTransfer: true });+const snapshotFileIntegrityError = (snapshotId, unmanifestedPath = null) => new ServerError(// Name the offending entry: without it the operator is told their only backup// failed integrity and given nothing to act on.@@ -1546,7 +1596,7 @@ const snapshotFileIntegrityError = (snapshotId, unmanifestedPath = null) => new* (rsync `--checksum` digests only regular files in scope, so the largest one* bounds the longest explainable silence between `-ii` heartbeats).*/-async function snapshotScopeInventory(srcDir, subdirFilter) {+async function snapshotScopeInventory(srcDir, subdirFilter, isSkippedPath = isRestorePreservedPath) {const scopePath = subdirFilter? resolve(srcDir, ...subdirFilter.split('/')): srcDir;@@ -1577,7 +1627,7 @@ async function snapshotScopeInventory(srcDir, subdirFilter) {// not inflate the digest floor either.if (isOsMetadataFile(basename(filePath))) continue;const scopedPath = relative(srcDir, filePath).replaceAll('\\', '/');- if (isRestorePreservedPath(scopedPath)) continue;+ if (isSkippedPath(scopedPath)) continue;if (info.size > largestFileBytes) largestFileBytes = info.size;const normalized = relative(srcDir, filePath).replaceAll('\\', '/');@@ -1620,7 +1670,10 @@ async function assertRestoreStorageCompatible(srcDir, inventory, snapshotId) {}}-async function verifySnapshotFiles(snapshotDir, srcDir, snapshotId, subdirFilter) {+async function verifySnapshotFiles(snapshotDir, srcDir, snapshotId, subdirFilter, { preserveIdentity = false } = {}) {+ const isSkippedPath = preserveIdentity+ ? path => isRestorePreservedPath(path) || isIdentityPath(path)+ : isRestorePreservedPath;// A unique fallback distinguishes a genuinely absent legacy manifest from an// existing file whose parsed value is JSON null.const manifestRead = await readJSONFileStrict(@@ -1639,7 +1692,7 @@ async function verifySnapshotFiles(snapshotDir, srcDir, snapshotId, subdirFilter// still needs the largest in-scope file. PostgreSQL also needs a complete// inventory to reject ignored legacy metadata; only the file escape hatch// can retain the old best-effort behavior when inventory fails.- const legacyInventory = await snapshotScopeInventory(srcDir, subdirFilter).catch(() => null);+ const legacyInventory = await snapshotScopeInventory(srcDir, subdirFilter, isSkippedPath).catch(() => null);await assertRestoreStorageCompatible(srcDir, legacyInventory, snapshotId);return {status: 'unverified',@@ -1649,7 +1702,7 @@ async function verifySnapshotFiles(snapshotDir, srcDir, snapshotId, subdirFilter};}- const manifestEntries = manifestDataEntries(manifestRead.value, srcDir, subdirFilter);+ const manifestEntries = manifestDataEntries(manifestRead.value, srcDir, subdirFilter, isSkippedPath);if (!manifestEntries) {throw new ServerError(`Snapshot integrity manifest is invalid: ${snapshotId}`, {status: 409,@@ -1661,7 +1714,7 @@ async function verifySnapshotFiles(snapshotDir, srcDir, snapshotId, subdirFilter// Hash agreement is insufficient if rsync can also copy files the manifest// never recorded. Rebuild the same regular-file inventory in the selected// scope and reject additions before rsync reads or overwrites anything.- const inventory = await snapshotScopeInventory(srcDir, subdirFilter)+ const inventory = await snapshotScopeInventory(srcDir, subdirFilter, isSkippedPath).catch(() => null);if (!inventory) throw snapshotFileIntegrityError(snapshotId);await assertRestoreStorageCompatible(srcDir, inventory, snapshotId);@@ -1703,8 +1756,11 @@ function restoreIdleTimeoutMs(largestFileBytes = 0) {* @param {object} options* @param {boolean} [options.dryRun=true] - If true, do not write any files* @param {string|null} [options.subdirFilter=null] - Limit restore to a subdirectory+ * @param {boolean} [options.adoptIdentity=false] - Install a snapshot's different+ * federation identity (instances.json) over the live one; only for replacing a+ * retired machine. Without it the live identity is preserved (`identityPreserved`).*/-export async function restoreSnapshot(destPath, snapshotId, { dryRun = true, subdirFilter: requestedFilter = null, source } = {}) {+export async function restoreSnapshot(destPath, snapshotId, { dryRun = true, subdirFilter: requestedFilter = null, source, adoptIdentity = false } = {}) {// Canonicalize once: manifest selection, the inventory and the rsync include// chain each spell the filter differently, so `brain/` or `./brain` would// select nothing yet verify clean. An all-dot/empty filter means no filter.@@ -1736,17 +1792,21 @@ export async function restoreSnapshot(destPath, snapshotId, { dryRun = true, sub// neither explicit deletion nor retention can remove verified bytes while// rsync still reads them (#10898).return withSnapshotRead(resolved.snapshotDir, snapshotId,- () => restoreHeldSnapshot(resolved, snapshotId, { dryRun, subdirFilter }));+ () => restoreHeldSnapshot(resolved, snapshotId, { dryRun, subdirFilter, adoptIdentity: adoptIdentity === true }));}-async function restoreHeldSnapshot({ snapshotDir, currentSource }, snapshotId, { dryRun, subdirFilter }) {+async function restoreHeldSnapshot({ snapshotDir, currentSource }, snapshotId, { dryRun, subdirFilter, adoptIdentity }) {await assertSnapshotRestorable(snapshotDir, snapshotId, currentSource);const srcDir = join(snapshotDir, 'data');+ const identity = await resolveIdentityRestore(srcDir, subdirFilter, adoptIdentity);+ // Keyed on the approval, not on a mismatch: a snapshot instances.json that+ // appears after the check must not reach the live file unfenced.+ const preserveIdentity = !identity.installs;// Run the preflight independently for preview and execution. A preview is an// aid to confirmation, not an integrity lease: snapshot bytes may change// between requests, especially on removable or network-backed destinations.- const verification = await verifySnapshotFiles(snapshotDir, srcDir, snapshotId, subdirFilter);+ const verification = await verifySnapshotFiles(snapshotDir, srcDir, snapshotId, subdirFilter, { preserveIdentity });// A full restore installs the snapshot's ledger too, so the next boot re-runs// whatever it lacks; only a folder restore can leave restored files behind// migrations the live ledger already records.@@ -1757,6 +1817,8 @@ async function restoreHeldSnapshot({ snapshotDir, currentSource }, snapshotId, {const restoreNotes = (restoredLegacyStores) => ({...(ledgerGap !== undefined && { ledgerGap }),...(restoredLegacyStores.length > 0 && { restoredLegacyStores }),+ ...(identity.preserved && { identityPreserved: identity.preserved }),+ ...(identity.adopted && { identityAdopted: identity.adopted }),});// Restore must compare destination bytes even when size and mtime match.@@ -1787,7 +1849,8 @@ async function restoreHeldSnapshot({ snapshotDir, currentSource }, snapshotId, {// Same placement rule: excluded before the include chain, and kept out of the// manifest selection and inventory above, so what rsync may write is exactly// what the preflight verified.- const flags = ['-ii', '--checksum', ...OS_METADATA_RSYNC_EXCLUDES, ...RESTORE_PRESERVED_RSYNC_EXCLUDES];+ const flags = ['-ii', '--checksum', ...OS_METADATA_RSYNC_EXCLUDES, ...RESTORE_PRESERVED_RSYNC_EXCLUDES,+ ...(preserveIdentity ? [IDENTITY_RSYNC_EXCLUDE] : [])];if (dryRun) flags.push('--dry-run');if (subdirFilter) {// Anchored with a leading `/` — rsync matches an unanchored pattern against@@ -1820,7 +1883,14 @@ async function restoreHeldSnapshot({ snapshotDir, currentSource }, snapshotId, {const changedFiles = await withLiveFileRestoreOwners(scope, srcDir, () => transferAndReconcileLiveFiles({subdirFilter,transfer: async () => {- const changed = await transferWithIdentityFence({ scope, srcDir, transferFiles });+ const changed = await transferWithIdentityFence({+ installsIdentity: identity.installs,+ assertIdentityUnchanged: async () => {+ const current = await resolveIdentityRestore(srcDir, subdirFilter, adoptIdentity);+ if (JSON.stringify(current) !== JSON.stringify(identity)) throw identityChangedError();+ },+ transferFiles,+ });restoredLegacyStores = await convertRestoredLegacySplitStores(legacyStores);return changed;},@@ -1955,19 +2025,29 @@ function withLiveFileRestoreOwners(scope, srcDir, operation) {/*** Peer-execution identity fence: shorter-lived than the owners above. It wraps- * ONLY the rsync transfer, never reconciliation, and only when the scope can- * touch instances.json AND the snapshot actually carries that file — probed- * here, inside the already-held owners.+ * ONLY the rsync transfer, never reconciliation, and only when this restore+ * installs instances.json (resolveIdentityRestore). The decision was made+ * before verification, so it is re-checked here under the identity writer lock:+ * a live identity written since then (first pairing, ensureSelf) must not be+ * overwritten without adoption. The memoized instance id is dropped even after+ * a partial transfer, so the process never stamps an id the file no longer holds.*/-async function transferWithIdentityFence({ scope, srcDir, transferFiles }) {- const identityInScope = !scope || scope === 'instances.json';- const snapshotHasIdentity = identityInScope && await stat(join(srcDir, 'instances.json')).then(- info => info.isFile(),- error => { if (error.code === 'ENOENT') return false; throw error; },- );- if (!snapshotHasIdentity) return transferFiles();- const { withPeerExecutionIdentityRestore } = await import('./peerExecutionRuntime.js');- return withPeerExecutionIdentityRestore(transferFiles);+async function transferWithIdentityFence({ installsIdentity, assertIdentityUnchanged, transferFiles }) {+ if (!installsIdentity) return transferFiles();+ const [{ withPeerExecutionIdentityRestore }, { resetInstanceIdCache }, { resetSelfInstanceIdCache }] = await Promise.all([+ import('./peerExecutionRuntime.js'),+ import('./instanceIdentity.js'),+ import('../lib/peerHttpClient.js'),+ ]);+ return withPeerExecutionIdentityRestore(async () => {+ await assertIdentityUnchanged();+ try {+ return await transferFiles();+ } finally {+ resetInstanceIdCache();+ resetSelfInstanceIdCache();+ }+ });}/**@@ -1980,6 +2060,7 @@ async function transferAndReconcileLiveFiles({ subdirFilter, transfer }) {const [result] = await Promise.allSettled([transfer()]);const reconciliationError = await reconcileLiveFileRestore(subdirFilter).then(() => null, error => error);if (result.status === 'rejected') {+ if (result.reason?.beforeTransfer) throw result.reason;const partialRestoreError = new Error(`${result.reason.message}. Some files may already have been overwritten because file restore is not transactional.${reconciliationError ? ` ${reconciliationError.message}` : ''}`,{ cause: result.reason },diff --git a/server/services/backup.test.js b/server/services/backup.test.jsindex a5402760d6..d7b6b78ac5 100644--- a/server/services/backup.test.js+++ b/server/services/backup.test.js@@ -43,7 +43,12 @@ function testDataRoot() {}vi.mock('../lib/fileUtils.js', async (importOriginal) => {const actual = await importOriginal();- return makePathsProxy(actual, { dataRoot: testDataRoot, overrides: { atomicWrite: vi.fn(actual.atomicWrite) } });+ // dataPath is overridden too: instanceIdentity.js resolves instances.json+ // through it, and the restore identity tests read that file (#12596).+ return makePathsProxy(actual, { dataRoot: testDataRoot, overrides: {+ atomicWrite: vi.fn(actual.atomicWrite),+ dataPath: (...segments) => joinPath(testDataRoot(), ...segments),+ } });});afterAll(() => {@@ -2885,20 +2890,150 @@ describe('restoreSnapshot manifest verification', () => {}}- it('invalidates execution grants before restoring instance identity bytes', async context => {+ it.for([+ { name: 'a never-federated install', live: null },+ { name: 'this machine\'s own older snapshot', live: '{"self":{"instanceId":"00000000-0000-4000-8000-000000000001"},"peers":[{"id":"newer-peer"}]}' },+ ])('installs instance identity bytes for $name, invalidating execution grants first', async ({ live }, context) => {await withRealRsync(context, async () => {const { createPeerExecutionAuthority } = await import('../lib/peerExecutionAuthority.js');const path = joinPath(PATHS.data, 'peer-execution-authority.json');+ const identityPath = joinPath(PATHS.data, 'instances.json');await realFs.rm(path, { force: true });- const authority = createPeerExecutionAuthority(PATHS.data);- const before = authority.initialize();- const identity = '{"self":{"instanceId":"00000000-0000-4000-8000-000000000001"},"peers":[]}';- const hash = await writeSnapshotFile('instances.json', identity);- await writeManifest({ 'instances.json': hash });- await restoreSnapshot(tmpRoot, 'snap-1', { dryRun: false, subdirFilter: 'instances.json' });- expect(authority.read().epoch).not.toBe(before.epoch);- expect(await realFs.readFile(joinPath(PATHS.data, 'instances.json'), 'utf8')).toBe(identity);- await realFs.rm(path, { force: true });+ await realFs.rm(identityPath, { force: true });+ if (live) await realFs.writeFile(identityPath, live);+ try {+ const authority = createPeerExecutionAuthority(PATHS.data);+ const before = authority.initialize();+ const identity = '{"self":{"instanceId":"00000000-0000-4000-8000-000000000001"},"peers":[]}';+ const hash = await writeSnapshotFile('instances.json', identity);+ await writeManifest({ 'instances.json': hash });+ const result = await restoreSnapshot(tmpRoot, 'snap-1', { dryRun: false, subdirFilter: 'instances.json' });+ expect(result).not.toHaveProperty('identityPreserved');+ expect(authority.read().epoch).not.toBe(before.epoch);+ expect(await realFs.readFile(identityPath, 'utf8')).toBe(identity);+ } finally {+ await realFs.rm(path, { force: true });+ await realFs.rm(identityPath, { force: true });+ }+ });+ });++ // #12596: a shared destination lists every machine's snapshots. Installing+ // another machine's instances.json would give two live installs one+ // federation identity, so a restore keeps the live one unless adopted.+ describe('federation identity (#12596)', () => {+ const LIVE_ID = '00000000-0000-4000-8000-00000000000a';+ const OTHER_ID = '00000000-0000-4000-8000-00000000000b';+ const LIVE_IDENTITY = JSON.stringify({ self: { instanceId: LIVE_ID }, peers: [{ id: 'live-peer' }] });+ const OTHER_IDENTITY = JSON.stringify({ self: { instanceId: OTHER_ID }, peers: [{ id: 'other-peer' }] });+ const identityPath = () => joinPath(PATHS.data, 'instances.json');++ async function seedOtherMachine({ live = LIVE_IDENTITY } = {}) {+ // A wrong manifest hash for instances.json proves a preserved identity+ // is neither verified nor transferred, like the other preserved files.+ await writeSnapshotFile('instances.json', OTHER_IDENTITY);+ const neighbor = await writeSnapshotFile(RECORD, '{"value":"snapshot"}');+ await writeManifest({ 'instances.json': '0'.repeat(64), [RECORD]: neighbor });+ await realFs.rm(joinPath(PATHS.data, RECORD), { force: true });+ await realFs.writeFile(identityPath(), live);+ }++ afterEach(async () => {+ await realFs.rm(identityPath(), { force: true });+ await realFs.rm(joinPath(PATHS.data, 'peer-execution-authority.json'), { force: true });+ const { resetInstanceIdCache } = await import('./instanceIdentity.js');+ resetInstanceIdCache();+ });++ it.for([+ { name: 'full restore', options: {} },+ { name: 'folder restore of instances.json', options: { subdirFilter: 'instances.json' } },+ ])('a $name keeps a different live identity byte-for-byte and reports it in preview and execution', async ({ options }, context) => {+ await withRealRsync(context, async () => {+ await seedOtherMachine();+ const { getInstanceId } = await import('./instanceIdentity.js');+ expect(await getInstanceId()).toBe(LIVE_ID);+ const identityPreserved = { liveInstanceId: LIVE_ID, snapshotInstanceId: OTHER_ID };++ const preview = await restoreSnapshot(tmpRoot, 'snap-1', { dryRun: true, ...options });+ expect(preview).toMatchObject({ identityPreserved, verification: { status: 'verified' } });+ expect(preview.changedFiles.some(line => line.includes('instances.json'))).toBe(false);++ const result = await restoreSnapshot(tmpRoot, 'snap-1', { dryRun: false, ...options });+ expect(result).toMatchObject({ identityPreserved });+ expect(await realFs.readFile(identityPath(), 'utf8')).toBe(LIVE_IDENTITY);+ expect(await getInstanceId()).toBe(LIVE_ID);+ expect(existsSync(joinPath(PATHS.data, RECORD))).toBe(!options.subdirFilter);+ });+ });++ it('keeps an unreadable live identity rather than guessing whose it was', async context => {+ await withRealRsync(context, async () => {+ await seedOtherMachine({ live: '{ not json' });+ const result = await restoreSnapshot(tmpRoot, 'snap-1', { dryRun: false });+ expect(result.identityPreserved).toEqual({ liveInstanceId: null, snapshotInstanceId: OTHER_ID });+ expect(await realFs.readFile(identityPath(), 'utf8')).toBe('{ not json');+ });+ });++ it('refuses, before writing, when a live identity appears after the restore was checked', async context => {+ await withRealRsync(context, async () => {+ await seedOtherMachine();+ await writeManifest({+ 'instances.json': createHash('sha256').update(OTHER_IDENTITY).digest('hex'),+ [RECORD]: createHash('sha256').update('{"value":"snapshot"}').digest('hex'),+ });+ // Never federated when checked; paired while verification runs.+ await realFs.rm(identityPath(), { force: true });+ fs.readFile.mockImplementation(async (path, ...rest) => {+ if (String(path).endsWith('manifest.json')) await realFs.writeFile(identityPath(), LIVE_IDENTITY);+ return realFs.readFile(path, ...rest);+ });++ await expect(restoreSnapshot(tmpRoot, 'snap-1', { dryRun: false }))+ .rejects.toMatchObject({ status: 409, code: 'BACKUP_RESTORE_IDENTITY_CHANGED' });+ expect(await realFs.readFile(identityPath(), 'utf8')).toBe(LIVE_IDENTITY);+ expect(existsSync(joinPath(PATHS.data, RECORD))).toBe(false);+ });+ });++ it('never installs a snapshot identity that appeared after the check', async context => {+ await withRealRsync(context, async () => {+ // A legacy snapshot (no manifest) without instances.json when checked.+ await writeSnapshotFile(RECORD, '{"value":"snapshot"}');+ await realFs.writeFile(identityPath(), LIVE_IDENTITY);+ fs.readFile.mockImplementation(async (path, ...rest) => {+ if (String(path).endsWith('manifest.json')) await writeSnapshotFile('instances.json', OTHER_IDENTITY);+ return realFs.readFile(path, ...rest);+ });++ await restoreSnapshot(tmpRoot, 'snap-1', { dryRun: false });+ expect(await realFs.readFile(identityPath(), 'utf8')).toBe(LIVE_IDENTITY);+ expect(await realFs.readFile(joinPath(PATHS.data, RECORD), 'utf8')).toBe('{"value":"snapshot"}');+ });+ });++ it('installs an adopted identity and serves it without a restart', async context => {+ await withRealRsync(context, async () => {+ await seedOtherMachine();+ await writeManifest({+ 'instances.json': createHash('sha256').update(OTHER_IDENTITY).digest('hex'),+ [RECORD]: createHash('sha256').update('{"value":"snapshot"}').digest('hex'),+ });+ const { getInstanceId } = await import('./instanceIdentity.js');+ expect(await getInstanceId()).toBe(LIVE_ID);+ const identityAdopted = { liveInstanceId: LIVE_ID, snapshotInstanceId: OTHER_ID };++ const preview = await restoreSnapshot(tmpRoot, 'snap-1', { dryRun: true, adoptIdentity: true });+ expect(preview).toMatchObject({ identityAdopted });+ expect(preview).not.toHaveProperty('identityPreserved');+ expect(preview.changedFiles.some(line => line.includes('instances.json'))).toBe(true);++ const result = await restoreSnapshot(tmpRoot, 'snap-1', { dryRun: false, adoptIdentity: true });+ expect(result).toMatchObject({ identityAdopted });+ expect(await realFs.readFile(identityPath(), 'utf8')).toBe(OTHER_IDENTITY);+ expect(await getInstanceId()).toBe(OTHER_ID);+ });});});@@ -3584,6 +3719,8 @@ describe('restoreSnapshot snapshotId, filter flags, and settings re-sync', () =>'--exclude=/[pP][eE][eE][rR]-[eE][xX][eE][cC][uU][tT][iI][oO][nN]-[rR][eE][cC][oO][vV][eE][rR][yY].[jJ][sS][oO][nN][lL]','--exclude=/[wW][oO][rR][kK][fF][lL][oO][wW]-[mM][aA][iI][nN][tT][eE][nN][aA][nN][cC][eE]','--exclude=/[bB][aA][cC][kK][uU][pP]-[aA][dD][mM][iI][sS][sS][iI][oO][nN]',+ // No snapshot instances.json was approved for install (#12596).+ '--exclude=/[iI][nN][sS][tT][aA][nN][cC][eE][sS].[jJ][sS][oO][nN]','--dry-run',// Leading `/` is load-bearing: rsync matches an unanchored pattern// against the end of every path, so `brain/***` would also restore@@ -3618,6 +3755,8 @@ describe('restoreSnapshot snapshotId, filter flags, and settings re-sync', () =>'--exclude=/[pP][eE][eE][rR]-[eE][xX][eE][cC][uU][tT][iI][oO][nN]-[rR][eE][cC][oO][vV][eE][rR][yY].[jJ][sS][oO][nN][lL]','--exclude=/[wW][oO][rR][kK][fF][lL][oO][wW]-[mM][aA][iI][nN][tT][eE][nN][aA][nN][cC][eE]','--exclude=/[bB][aA][cC][kK][uU][pP]-[aA][dD][mM][iI][sS][sS][iI][oO][nN]',+ // No snapshot instances.json was approved for install (#12596).+ '--exclude=/[iI][nN][sS][tT][aA][nN][cC][eE][sS].[jJ][sS][oO][nN]',]);});diff --git a/server/services/instanceIdentity.js b/server/services/instanceIdentity.jsindex 559e63885e..e3e9536b1b 100644--- a/server/services/instanceIdentity.js+++ b/server/services/instanceIdentity.js@@ -109,6 +109,15 @@ export async function getInstanceId() {return cachedInstanceId;}+/**+ * Drop the memoized id so the next read follows instances.json. A file restore+ * that installs instances.json calls this, or the running process would keep+ * stamping its old id while getSelf() returned the restored one (#12596).+ */+export function resetInstanceIdCache() {+ cachedInstanceId = null;+}+/*** Resolve this machine's real federation instance id, creating the local* identity on the cold path. `getInstanceId()` returns the