Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

### Added

- **Restore a node identity backup from the app.** Settings > Restore from a backup takes a `.cpbackup` file made with a passphrase and puts Mysterium, ProxyBase or Anyone back on this machine, with the web app's rules. It only creates: the service must not be here in any state and its identity volume must not exist. A file sealed to a key stays on `cpbackup`. A file this app did not export needs the service name typed, and is refused while the machine named inside it still runs the service. The container is created without starting, the backup is written into its new volume, read back and compared file by file, and only then does it start; Mysterium only behind the LAN fence. Any failure removes what the restore made. A restore that did not finish holds the service, so Deploy and Start refuse it until the partial restore is deleted. Exports now record each file's SHA-256 so the app knows its own files (docs/backup.md).

### Changed

- **1.0.0 is the first stable release.** Nothing breaks: config, database, saved credentials and deployed services carry over. An install from before v0.37.0 keeps its earners on Docker's default bridge until Turn on isolation is pressed, and a proxied copy from before v0.39.1 keeps its tunnel there until it is deployed again. `wails.json`, `package.json` and `frontend/package.json` now say 1.0.0; release builds still take the version from the tag. What 1.0 covers, upgrade notes and known limits: docs/whats-new-1.0.md.
Expand Down
8 changes: 8 additions & 0 deletions app.go
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,14 @@ type App struct {
// it is a field so the export path can be driven in a test, which has no window
// for a native dialog to open in.
saveDialog func(wailsruntime.SaveDialogOptions) (string, error)
// openDialog is saveDialog's twin for choosing a file to read (a backup to
// restore). Zero value means the real Wails dialog.
openDialog func(wailsruntime.OpenDialogOptions) (string, error)
// restoreFiles are the backup files the restore preview checked, by token, until
// one is restored or restoreFileTTL passes (restore_binding.go). Guarded by
// restoreMu.
restoreMu sync.Mutex
restoreFiles map[string]restoreFile
// importMu serializes ApplyImport's read-merge-write of stored credentials.
importMu sync.Mutex
// fleetKey is the fleet bearer token held in memory for the per-request auth
Expand Down
53 changes: 52 additions & 1 deletion docs/backup.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,58 @@ scheduled backup: a timer would need a stored key.
The file format is the CashPilot web app's, so either app's tool opens either
app's backups.

## Restore a backup
## Restore from the app

**Settings > Restore from a backup** puts a node identity or wallet back on this
machine from a `.cpbackup` file. It covers Mysterium, ProxyBase and Anyone, whose
identity sits on a named Docker volume. Choose the file, read what the restore
would create, type the passphrase and confirm. The rules:

- **It only creates.** This machine must not have the service in any state (no
container, no copy, nothing set aside), and its identity volume must not exist.
The restore never writes over anything. To replace a running identity, download
its backup first, remove the service and say yes to deleting its data, then
restore.
- **Passphrase files only.** A file sealed to a key is refused before anything
secret is asked for: its private key never goes through the app. Use the
command line steps below for it.
- **Files the app did not make need the name typed.** The app keeps the SHA-256 of
every file it exports. For any other file you type the service name, because
nobody can tell from the file whose identity is inside. A file exported before
this record existed is one of these.
- **One identity, one machine.** For a file the app did not make, the restore is
refused while the machine named inside the file still runs the service, as far
as this app's fleet list shows. For any file, the preview names the fleet
machines that run the service now. A file the app made needs the name typed
while one of them runs it: the record says the app wrote the file, not where its
identity went since. When the app cannot read its fleet list, the restore is
refused. Two machines on one identity look like one node to the provider, which
may merge or ban them.
- **Checked before it starts.** The app creates the volumes, each with a random
`cashpilot.restore` label, and the container without starting it. It writes the
backup into the volume, reads the folder back and compares every file, link,
owner and permission with the backup. Only then does the container start.
Mysterium starts only behind the LAN fence; until the fence holds it waits, and
the fence guard never starts it before its data is checked. On any failure the
container and the volumes the restore made are removed. A volume under the same
name without the restore's label belongs to another program and stays.
- **A restore that did not finish holds the service.** Before it makes anything,
the app records that a restore is under way. The record goes once the data reads
back as the backup, or once the undo removed everything. If the app stops
mid-restore, or the undo cannot remove something (also after a start that
failed), the record stays: Deploy,
Start and Restore refuse the service, and the Restore card lists it. **Delete
the partial restore** removes its container and the volumes the restore made,
then the service is free again.
- **Nothing kept.** The app reads the file where it is and keeps only its path and
SHA-256 for 15 minutes; the restore reads it again and refuses a file that
changed. The passphrase is used once and never stored or logged. The service's
saved settings are used, so fill them in on its deploy form first.

Storj and Sia keep their state in host folders, and Storj's is over the export
cap: restore those with the command line steps.

## Restore a backup from the command line

**1. Open the file** on a machine you trust (needs Go and git). Run `cpbackup` from
a checkout of the release that made the backup:
Expand Down
2 changes: 1 addition & 1 deletion frontend/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
"build": "tsc && vite build",
"preview": "vite preview",
"harness:build": "tsc -p tsconfig.harness.json",
"test": "npm run harness:build && node scripts/fleet_render_check.mjs && node scripts/earnings_render_check.mjs && node scripts/status_render_check.mjs && node scripts/total_render_check.mjs && node scripts/fields_check.mjs && node scripts/removal_check.mjs && node scripts/preflight_render_check.mjs && node scripts/producer_render_check.mjs && node scripts/details_check.mjs && node scripts/wizard_render_check.mjs && node scripts/image_check.mjs && node scripts/instances_check.mjs && node scripts/console_render_check.mjs && node scripts/topbar_render_check.mjs && node scripts/drift_render_check.mjs && node scripts/usage_render_check.mjs && node scripts/backups_render_check.mjs && node scripts/activity_check.mjs && node scripts/custom_check.mjs && node scripts/importer_check.mjs && node scripts/rating_check.mjs && node scripts/isolation_render_check.mjs && node scripts/proxies_check.mjs && node scripts/route_check.mjs"
"test": "npm run harness:build && node scripts/fleet_render_check.mjs && node scripts/earnings_render_check.mjs && node scripts/status_render_check.mjs && node scripts/total_render_check.mjs && node scripts/fields_check.mjs && node scripts/removal_check.mjs && node scripts/preflight_render_check.mjs && node scripts/producer_render_check.mjs && node scripts/details_check.mjs && node scripts/wizard_render_check.mjs && node scripts/image_check.mjs && node scripts/instances_check.mjs && node scripts/console_render_check.mjs && node scripts/topbar_render_check.mjs && node scripts/drift_render_check.mjs && node scripts/usage_render_check.mjs && node scripts/backups_render_check.mjs && node scripts/restore_render_check.mjs && node scripts/activity_check.mjs && node scripts/custom_check.mjs && node scripts/importer_check.mjs && node scripts/rating_check.mjs && node scripts/isolation_render_check.mjs && node scripts/proxies_check.mjs && node scripts/route_check.mjs"
},
"dependencies": {},
"devDependencies": {
Expand Down
1 change: 1 addition & 0 deletions frontend/scripts/backups_render_check.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@ check("changed says to back it up again", backupStatusText(row({state: "changed"
check("expired says six months", backupStatusText(row({state: "expired", confirmedAt: "2026-01-01T00:00:00Z"})).includes("more than six months ago"));
check("recheck asks once more", backupStatusText(row({state: "recheck", confirmedAt: "2026-01-01T00:00:00Z"})).includes("Confirm it once more"));
check("an export says it was saved from here", backupStatusText(row({state: "confirmed", confirmedAt: "2026-10-01T09:00:00Z", method: "export"})).includes("(saved from here)"));
check("a restore says it came from that file", backupStatusText(row({state: "confirmed", confirmedAt: "2026-10-01T09:00:00Z", method: "restore"})).includes("(restored from that file)"));
check("an untracked confirmation says only the time limit applies",
backupStatusText(row({state: "confirmed", confirmedAt: "2026-10-01T09:00:00Z", tracksChanges: false})).includes("only the six-month limit applies"));

Expand Down
94 changes: 94 additions & 0 deletions frontend/scripts/restore_render_check.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
#!/usr/bin/env node
// Browser-free checks on Settings > Restore from a backup.
//
// THE RULE: the preview says what the restore creates, never offers Restore when this
// machine refuses it, asks for the service name for a file this app did not make,
// and names the unfinished restores that hold a service.
//
// node scripts/restore_render_check.mjs # against ./.harness-build

import { renderRestoreCard, renderRestorePreview, restoreResultText } from "../.harness-build/render/restore.js";

let failures = 0;
let checks = 0;

function check(name, condition, detail = "") {
checks++;
if (condition) return;
failures++;
console.error(`FAIL ${name}${detail ? `\n ${detail}` : ""}`);
}

function preview(overrides = {}) {
return {
token: "tok123",
file: "cashpilot-mysterium-box-20261101.cpbackup",
slug: "mysterium",
service: "Mysterium",
bytes: 2048,
sha256: "ab".repeat(32),
known: true,
madeOn: "box",
container: "cashpilot-mysterium",
creates: [{target: "/var/lib/mysterium-node", volume: "mysterium-data"}],
ok: true,
why: "",
runsOn: [],
needsName: false,
...overrides,
};
}

const card = renderRestoreCard([]);
check("the card has the file button", card.includes('id="restore-choose"'), card);
check("the card says it only creates", card.includes("only creates a new container"));
check("the card points key-sealed files to the command line", card.includes("Files sealed to a key") && card.includes("docs/backup.md#restore-a-backup-from-the-command-line"));
check("no unfinished restore, no list", !card.includes("did not finish"));

const stuck = renderRestoreCard([{slug: "mysterium", service: "Mysterium", volumes: ["mysterium-data"], startedAt: "2026-11-16T10:20:30Z"}]);
check("an unfinished restore is listed by name", stuck.includes("<strong>Mysterium</strong>") && stuck.includes("did not finish"), stuck);
check("it says Deploy and Start refuse it", stuck.includes("Deploy and Start refuse it"));
check("it names the volumes the restore made", stuck.includes("<code>mysterium-data</code>"));
check("it offers to delete the partial restore", stuck.includes('data-restore-discard="mysterium"'));

const known = renderRestorePreview(preview());
check("the preview names the container and the volume", known.includes("cashpilot-mysterium") && known.includes("<code>mysterium-data</code> at <code>/var/lib/mysterium-node</code>"), known);
check("the preview carries the token", known.includes('data-token="tok123"'));
check("a known file asks for no name", !known.includes('name="confirm_name"') && known.includes("This app made this file"));
check("the passphrase is a password field", known.includes('type="password" name="passphrase"'));
check("Restore is offered when this machine accepts it", /<button type="submit"[^>]*>Restore<\/button>/.test(known) && !/<button type="submit"[^>]*disabled/.test(known));

const foreign = renderRestorePreview(preview({known: false, madeOn: "other-box", runsOn: ["other-box"]}));
check("a foreign file asks for the name typed", foreign.includes('name="confirm_name"') && foreign.includes("type <strong>Mysterium</strong>"), foreign);
check("a foreign file says where it claims to come from", foreign.includes("it says it came from other-box"));
check("a foreign file warns about machines running the service", foreign.includes("runs now on other-box"));

const foreignNeedsName = renderRestorePreview(preview({known: false, madeOn: "other-box", runsOn: ["other-box"], needsName: true}));
check("a foreign file asks for the name once", (foreignNeedsName.match(/name="confirm_name"/g) || []).length === 1, foreignNeedsName);
check("a foreign file with no machine running it still asks for the name", renderRestorePreview(preview({known: false, needsName: true})).includes('name="confirm_name"'));

// The app's own export, while a fleet machine runs the service: the identity may have
// moved there, so the preview says so and asks for the name.
const movedAway = renderRestorePreview(preview({known: true, runsOn: ["worker-b"], needsName: true}));
check("a known file warns about machines running the service", movedAway.includes("runs now on worker-b") && movedAway.includes("cannot tell whether that node came from it"), movedAway);
check("a known file the fleet may run asks for the name typed", (movedAway.match(/name="confirm_name"/g) || []).length === 1 && movedAway.includes("type <strong>Mysterium</strong>"), movedAway);
check("a refused preview does not add the warning", !renderRestorePreview(preview({known: true, runsOn: ["worker-b"], needsName: true, ok: false, why: "x"})).includes("runs now on"));

const refused = renderRestorePreview(preview({ok: false, why: "the volume mysterium-data already exists on this machine"}));
check("a refusal is shown", refused.includes("cannot restore it now: the volume mysterium-data already exists"), refused);
check("a refusal disables Restore", /<button type="submit"[^>]*disabled>Restore<\/button>/.test(refused), refused);

const hostile = renderRestorePreview(preview({service: "<img src=x onerror=alert(1)>", file: "<script>.cpbackup", why: "<b>", ok: false, known: false, madeOn: "<i>"}));
check("names, file and reasons are escaped", !hostile.includes("<img") && !hostile.includes("<script>") && !hostile.includes("<b>") && !hostile.includes("<i>"), hostile);
const hostileCard = renderRestoreCard([{slug: '"><img src=x>', service: "<img>", volumes: ["<v>"], startedAt: ""}]);
check("the unfinished list is escaped", !hostileCard.includes("<img") && !hostileCard.includes("<v>"), hostileCard);

check("a started restore says so", restoreResultText("Mysterium", {files: 3, started: true}).includes("3 files, checked against the backup) and started"));
check("one file is singular", restoreResultText("Mysterium", {files: 1, started: true}).includes("(1 file,"));
check("a node waiting for the fence says so", restoreResultText("Mysterium", {files: 2, started: false, waiting: "the fence is not applied"}).includes("waits for the LAN fence and starts once it holds: the fence is not applied"));

if (failures > 0) {
console.error(`\n${failures} of ${checks} restore checks FAILED`);
process.exit(1);
}
console.log(`restore_render_check: ${checks} checks passed`);
Loading
Loading