dsh-webdav-sync 1.0.4 → 1.0.6

package/lib/engine.d.ts

@@ -13,7 +13,7 @@
  * with 409, a write that went out without the server checking its version, a body
  * a relay cut in half.
  */
-import { type Bundle, type CheckResult, type ConfigView, type Part, type PartHashes, type KeyProblem, type PreviewResult, type StatusResult, type SyncConfig, type SyncResult } from './wire.js';
+import { type Bundle, type CheckResult, type ConfigView, type ExportBody, type ExportResult, type ImportBody, type ImportResult, type Part, type PartHashes, type KeyProblem, type PreviewResult, type StatusResult, type SyncConfig, type SyncResult } from './wire.js';
 import { type DirsRead } from './dirs.js';
 import { missingPlugins, type Collected, type ManifestFile, type PatchFile } from './store.js';
 import { loadConfig, sameAccount, saveConfig, usable } from './state.js';
@@ -77,6 +77,33 @@ export declare function restore(engine: Engine): Promise<SyncResult>;
  * server held is kept under `sync/` before anything is written.
  */
 export declare function upload(engine: Engine): Promise<SyncResult>;
+/**
+ * Write this computer's setup into one passphrase-sealed file the person can carry.
+ *
+ * The file is the same sealed bundle the server holds, so a manual backup and a
+ * sync backup are one format and either can be opened by the other. What goes in
+ * is what the configuration syncs — the five parts behind the switches — because
+ * "打包上面这些" means the section above the button, and a part that is switched
+ * off is one this person already said they do not want travelling.
+ *
+ * The passphrase is asked for here rather than taken from the configuration: this
+ * file leaves the computer, and the sync passphrase is the one that also opens the
+ * copy on the server. A file sealed with its own passphrase opens nothing else.
+ */
+export declare function exportBackup(engine: Engine, body?: ExportBody): Promise<ExportResult>;
+/**
+ * Put what a picked backup file holds onto this computer.
+ *
+ * This is the one action that must work on a computer that has never synced: the
+ * whole point of the file is to arrive somewhere new. So nothing here asks the
+ * configuration to be usable, and nothing is compared with the server.
+ *
+ * What it does *not* do is touch the sync baseline. The parts change here, the
+ * stored hashes still describe the setup from before, so the next sync sees the
+ * difference and pushes it — which is what someone who imported a setup on a new
+ * computer wants to happen.
+ */
+export declare function importBackup(engine: Engine, body?: ImportBody): Promise<ImportResult>;
 /** Put back the setup the last restore replaced. */
 export declare function undo(engine: Engine): Promise<SyncResult>;
 /**

package/lib/engine.js

@@ -13,9 +13,10 @@
  * with 409, a write that went out without the server checking its version, a body
  * a relay cut in half.
  */
-import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { BUNDLE_APP, BUNDLE_FORMAT, BUNDLE_VERSION, PARTS, REMOTE_FILE, } from './wire.js';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, extname, isAbsolute, join, resolve } from 'node:path';
+import { BACKUP_EXT, BUNDLE_APP, BUNDLE_FORMAT, BUNDLE_VERSION, PARTS, REMOTE_FILE, } from './wire.js';
 import { CorruptError, NotBackupError, PassphraseError, hashJson, open, seal, sum } from './crypto.js';
 import { Dav, LoginError, RateLimitedError, parseHeaders } from './dav.js';
 import { dirsDiffer, dirsPartOf, readDirs, writeDirs } from './dirs.js';
@@ -164,6 +165,11 @@ async function syncOnce(engine, state, force) {
         state.blind = undefined;
     }
     const snapshot = await take(paths, config, engine.credentials);
+    if (snapshot.keysProblems.length === 0 && state.local?.keys !== undefined) {
+        // Older state files predate the explicit marker; an existing keys hash is
+        // already a trustworthy baseline, even before this run measures it again.
+        state.keysBaseline = true;
+    }
     let remote = await openRemote(engine, state, read);
     const first = state.local === undefined;
     // A directory could not be read this run: its part stands in for the server's
@@ -175,7 +181,11 @@ async function syncOnce(engine, state, force) {
         && sameHashes(hashesOf(partsOf(snapshot, remote.part('dirs'))), state.local)
         && !force) {
         // Neither side moved: the last sync is still the state of the world.
-        return { here: [], there: [], pushed: false, reloadNeeded: false, ...(await pendings(engine, snapshot.parts.plugins)) };
+        return {
+            here: [], there: [], pushed: false, reloadNeeded: false,
+            ...keyProblems(snapshot.keysProblems),
+            ...(await pendings(engine, snapshot.parts.plugins)),
+        };
     }
     if (remote.notModified) {
         // The server said the file is the one last read, which was worth knowing for
@@ -185,6 +195,10 @@ async function syncOnce(engine, state, force) {
     }
     const carried = remote.part('dirs');
     const localParts = partsOf(snapshot, carried);
+    // A failed credential read is unknown, not a deletion or a partial replacement.
+    // Defer this part while the other parts sync, carrying the server's copy below.
+    if (snapshot.keysProblems.length > 0)
+        delete localParts.keys;
     const local = hashesOf(localParts);
     // The server holds no file of ours. This computer's setup becomes the first
     // version, which is what joining an empty folder means.
@@ -206,10 +220,10 @@ async function syncOnce(engine, state, force) {
     for (const part of PARTS) {
         const remoteHas = remote.hashes[part] !== undefined;
         const remotePart = () => remote.part(part);
-        if (!syncsPart(config, part)) {
-            // Not carried with this configuration. The server's copy is carried through
-            // the upload untouched — turning a part off must never delete it for the
-            // computers that still sync it — and nothing is written here from it.
+        if (!syncsPart(config, part) || (part === 'keys' && snapshot.keysProblems.length > 0)) {
+            // Disabled or unreadable: carry the server's copy untouched. In particular,
+            // a missing/locked credential service must not look like local key deletion
+            // and erase the keys already uploaded by a successful manual sync.
             if (remoteHas)
                 merged[part] = remotePart();
             continue;
@@ -218,7 +232,8 @@ async function syncOnce(engine, state, force) {
         // the last sync — not merely when its presence changed. Comparing presence
         // would read an edit made only on the other computer as "unchanged" and
         // quietly keep this computer's older copy.
-        const changedHere = !first && local[part] !== state.local?.[part];
+        const missingKeyBaseline = !first && state.keysBaseline !== true && part === 'keys';
+        const changedHere = !first && !missingKeyBaseline && local[part] !== state.local?.[part];
         const changedThere = first || remote.hashes[part] !== state.remote?.[part];
         // A part the other computer took away is taken away here too — but never the
         // plugin list, which is what loads the shell, and never on a first sync,
@@ -327,11 +342,12 @@ async function syncOnce(engine, state, force) {
     const pushNeeded = force || remote.rebuilt === true || !sameHashes(mergedHashes, remote.hashes);
     if (!pushNeeded) {
         const written = await applyMerged(engine, snapshot, applied);
-        state.remote = remote.hashes;
         // Read back rather than assume: a directory whose file was just written — or
         // removed — has to be hashed as it now is, or the next sync would see an edit
-        // that this one made itself and call it a conflict.
-        state.local = hashesOf(partsOf(await take(paths, config, engine.credentials), undefined));
+        // that this one made itself and call it a conflict. Keep the key baselines if
+        // this read could not measure them, so recovery still sees pending edits.
+        const after = await take(paths, config, engine.credentials);
+        recordHashes(state, hashesOf(partsOf(after, undefined)), remote.hashes, snapshot.keysProblems.length === 0 && after.keysProblems.length === 0);
         // A part can come in without the file needing to be written: when only the
         // server moved, the merge agrees with it. The person still has to be told
         // what changed here, so the notice is recorded on this path too — clearing
@@ -351,7 +367,7 @@ async function syncOnce(engine, state, force) {
             ...(saved === undefined ? {} : { saved }),
             pushed: false,
             reloadNeeded: written.reloadNeeded,
-            ...keyProblems(written.keysProblems),
+            ...keyProblems([...snapshot.keysProblems, ...written.keysProblems]),
             ...(await pendings(engine, applied.plugins)),
         };
     }
@@ -556,11 +572,11 @@ async function push(engine, state, snapshot, merged) {
     // failed upload never leaves this computer holding another computer's setup
     // with nothing to say where its own went.
     const applied = await applyMerged(engine, snapshot, merged.applied);
-    const now = hashesOf(partsOf(await take(paths, config, engine.credentials), undefined));
+    const after = await take(paths, config, engine.credentials);
+    const now = hashesOf(partsOf(after, undefined));
     state.server = written;
     state.sum = sum(sealed);
-    state.remote = hashesOf(bundle);
-    state.local = now;
+    recordHashes(state, now, hashesOf(bundle), snapshot.keysProblems.length === 0 && after.keysProblems.length === 0);
     state.blind = written.etag === undefined || written.etag === '' ? { ...before } : undefined;
     state.undo = undefined;
     const notice = merged.here.length > 0 || merged.there.length > 0
@@ -579,7 +595,7 @@ async function push(engine, state, snapshot, merged) {
         ...(merged.saved === undefined ? {} : { saved: merged.saved }),
         pushed: true,
         reloadNeeded: applied.reloadNeeded,
-        ...keyProblems(applied.keysProblems),
+        ...keyProblems([...snapshot.keysProblems, ...applied.keysProblems]),
         ...(await pendings(engine, merged.merged.plugins)),
     };
 }
@@ -664,6 +680,29 @@ async function applyMerged(engine, snapshot, applied) {
     }
     return { reloadNeeded, keysProblems };
 }
+/** Record measured parts without turning an unreadable key store into a baseline. */
+function recordHashes(state, local, remote, keysReadable) {
+    if (keysReadable)
+        state.keysBaseline = true;
+    if (!keysReadable) {
+        // Keep both comparison points: when the service returns, local and remote
+        // key edits still need to be merged rather than accepted as already applied.
+        if (state.local?.keys === undefined)
+            delete local.keys;
+        else
+            local.keys = state.local.keys;
+        remote = { ...remote };
+        if (state.remote?.keys === undefined)
+            delete remote.keys;
+        else
+            remote.keys = state.remote.keys;
+        // The server may have changed keys during this attempt. A conditional 304
+        // would hide its body on recovery even though those keys are still pending.
+        state.server = undefined;
+    }
+    state.local = local;
+    state.remote = remote;
+}
 /**
  * The `keysProblems` field of a result, present only when there is one.
  *
@@ -838,7 +877,7 @@ export async function restore(engine) {
             ...(kept === undefined ? {} : { saved: keptDir(paths) }),
             pushed: false,
             reloadNeeded: written.reloadNeeded,
-            ...keyProblems(written.keysProblems),
+            ...keyProblems([...snapshot.keysProblems, ...written.keysProblems]),
             ...(await pendings(engine, applied.plugins)),
         };
     });
@@ -897,6 +936,179 @@ export async function upload(engine) {
         return result;
     });
 }
+/**
+ * Write this computer's setup into one passphrase-sealed file the person can carry.
+ *
+ * The file is the same sealed bundle the server holds, so a manual backup and a
+ * sync backup are one format and either can be opened by the other. What goes in
+ * is what the configuration syncs — the five parts behind the switches — because
+ * "打包上面这些" means the section above the button, and a part that is switched
+ * off is one this person already said they do not want travelling.
+ *
+ * The passphrase is asked for here rather than taken from the configuration: this
+ * file leaves the computer, and the sync passphrase is the one that also opens the
+ * copy on the server. A file sealed with its own passphrase opens nothing else.
+ */
+export async function exportBackup(engine, body = {}) {
+    return guarded(engine, async () => {
+        const { paths, config } = engine;
+        const passphrase = (body.passphrase ?? '').trim();
+        if (passphrase === '')
+            throw new Error('导出需要一个口令来加密这个文件');
+        await ensureStateDir(paths);
+        const snapshot = await take(paths, config, engine.credentials);
+        const whole = partsOf(snapshot, undefined);
+        const parts = {};
+        for (const part of PARTS) {
+            if (!syncsPart(config, part))
+                continue;
+            const value = whole[part];
+            if (value !== undefined)
+                parts[part] = value;
+        }
+        const carried = Object.keys(parts);
+        if (carried.length === 0)
+            throw new Error('这份配置没有可以导出的内容：请先在上面打开要同步的项');
+        const bundle = {
+            format: BUNDLE_FORMAT,
+            version: BUNDLE_VERSION,
+            created: new Date().toISOString(),
+            app: BUNDLE_APP,
+            ...parts,
+        };
+        const sealed = await seal(bundle, passphrase);
+        const file = exportTarget(body.dir);
+        await mkdir(dirname(file), { recursive: true });
+        await writeFile(file, sealed);
+        return { file, size: sealed.byteLength, parts: carried };
+    });
+}
+/** The file an export writes: the folder that was picked, or a full path. */
+function exportTarget(dir) {
+    const asked = (dir ?? '').trim();
+    // `dsh-webdav-20261021-180935.prop`: the timestamp is the same minute-precision
+    // form the kept copies use, so two exports in one session never collide and the
+    // folder sorts in the order they were taken.
+    const name = `dsh-webdav-${new Date().toISOString().replace(/[-:]/g, '').replace(/\..+$/, '').replace('T', '-')}${BACKUP_EXT}`;
+    if (asked === '')
+        return join(homedir(), name);
+    if (!isAbsolute(asked)) {
+        // A relative path means something different to the person typing it than to
+        // this process, so guessing a base would put the file somewhere they will not
+        // look for it. The folder picker always answers an absolute path.
+        throw new Error(`导出位置必须是绝对路径，收到的是「${asked}」`);
+    }
+    // A path that already names a file is taken as one; a folder gets the generated
+    // name inside it. The extension is what tells the two apart.
+    return extname(asked) === '' ? join(resolve(asked), name) : resolve(asked);
+}
+/**
+ * Put what a picked backup file holds onto this computer.
+ *
+ * This is the one action that must work on a computer that has never synced: the
+ * whole point of the file is to arrive somewhere new. So nothing here asks the
+ * configuration to be usable, and nothing is compared with the server.
+ *
+ * What it does *not* do is touch the sync baseline. The parts change here, the
+ * stored hashes still describe the setup from before, so the next sync sees the
+ * difference and pushes it — which is what someone who imported a setup on a new
+ * computer wants to happen.
+ */
+export async function importBackup(engine, body = {}) {
+    return guarded(engine, async () => {
+        const { paths, config } = engine;
+        const passphrase = (body.passphrase ?? '').trim();
+        if (passphrase === '')
+            throw new Error('导入需要这个文件的口令');
+        const text = body.text ?? '';
+        if (text.trim() === '')
+            throw new Error('没有读到文件内容：请重新选择那个备份文件');
+        const bundle = await openBackupFile(text, passphrase);
+        const unreadable = unreadablePart(bundle);
+        if (unreadable !== undefined) {
+            throw new Error(`这个文件里「${unreadable}」这一份的形状不是本插件写出来的：它可能来自另一个版本的插件`);
+        }
+        await ensureStateDir(paths);
+        const snapshot = await take(paths, config, engine.credentials);
+        const local = hashesOf(partsOf(snapshot, undefined));
+        const remote = hashesOf(bundle);
+        const merged = {};
+        const applied = {};
+        const here = [];
+        const same = [];
+        for (const part of PARTS) {
+            const value = bundle[part];
+            if (value === undefined)
+                continue;
+            // Applied whatever the switches say: a file that was picked and opened is an
+            // explicit instruction about this one moment, not a standing arrangement.
+            merged[part] = value;
+            applied[part] = value;
+            if (local[part] === remote[part])
+                same.push(part);
+            else
+                here.push(part);
+        }
+        if (here.length === 0) {
+            // Nothing differs, so nothing is written: a no-op import that still rewrote
+            // every file would only make the reload prompt meaningless.
+            return {
+                here: [],
+                same,
+                reloadNeeded: false,
+                pendingInstall: false,
+                created: bundle.created,
+            };
+        }
+        // A copy is kept only when there is a passphrase to seal it with. On a fresh
+        // computer there is none, and `keepBefore` answers `undefined` — the setup
+        // being replaced there is the empty one anyway.
+        const kept = await keepBefore(engine, snapshot, true);
+        const written = await applyMerged(engine, snapshot, applied);
+        const state = await freshState(paths, config);
+        const at = new Date().toISOString();
+        if (kept !== undefined)
+            state.undo = kept;
+        state.last = at;
+        state.error = '';
+        state.moved = at;
+        await saveState(paths, state);
+        return {
+            here,
+            same,
+            ...(kept === undefined ? {} : { saved: keptDir(paths) }),
+            reloadNeeded: written.reloadNeeded,
+            ...(await pendings(engine, applied.plugins)),
+            ...keyProblems([...snapshot.keysProblems, ...written.keysProblems]),
+            created: bundle.created,
+        };
+    });
+}
+/** Open a picked file's text as a bundle of ours, with messages a person can act on. */
+async function openBackupFile(text, passphrase) {
+    const data = Buffer.from(text, 'utf8');
+    let opened;
+    try {
+        opened = await open(data, passphrase);
+    }
+    catch (cause) {
+        if (cause instanceof PassphraseError) {
+            throw new Error('口令打不开这个文件：请用导出它时用的那个口令');
+        }
+        if (cause instanceof CorruptError) {
+            throw new Error(`${cause.message}——这个文件可能没有拷全，请重新导出一次`);
+        }
+        if (cause instanceof NotBackupError) {
+            throw new Error('这个文件不是 dsh-webdav-sync 导出的备份：请选另一个文件');
+        }
+        throw cause;
+    }
+    if (opened === null || typeof opened !== 'object' || opened.format !== BUNDLE_FORMAT) {
+        throw new Error('这个文件不是 dsh-webdav-sync 导出的备份：请选另一个文件');
+    }
+    const bundle = opened;
+    return { ...bundle, created: typeof bundle.created === 'string' ? bundle.created : new Date(0).toISOString() };
+}
 /** Put back the setup the last restore replaced. */
 export async function undo(engine) {
     return guarded(engine, async () => {
@@ -939,7 +1151,7 @@ export async function undo(engine) {
             there: [],
             pushed: false,
             reloadNeeded: written.reloadNeeded,
-            ...keyProblems(written.keysProblems),
+            ...keyProblems([...snapshot.keysProblems, ...written.keysProblems]),
             ...(await pendings(engine, merged.plugins)),
         };
     });

package/lib/index.js

@@ -15,10 +15,10 @@
  */
 import { isAbsolute } from 'node:path';
 import z from '@deepseek-ai/schemastery';
-import { AUTO_CHOICES, DIRS_MAX, ROUTE_CHECK, ROUTE_CONFIG, ROUTE_DISMISS, ROUTE_INSTALL, ROUTE_OFF, ROUTE_PREVIEW, ROUTE_RESTORE, ROUTE_STATUS, ROUTE_SYNC, ROUTE_UNDO, ROUTE_UPLOAD, } from './wire.js';
+import { AUTO_CHOICES, DIRS_MAX, ROUTE_CHECK, ROUTE_CONFIG, ROUTE_DISMISS, ROUTE_EXPORT, ROUTE_IMPORT, ROUTE_INSTALL, ROUTE_OFF, ROUTE_PREVIEW, ROUTE_RESTORE, ROUTE_STATUS, ROUTE_SYNC, ROUTE_UNDO, ROUTE_UPLOAD, } from './wire.js';
 import { validateProfileDir, resolveFromEnv } from './paths.js';
 import { RelayServer, makeRelayPassword, makeRelayUser } from './relay.js';
-import { check, dismiss, engineFor, loadConfig, preview, restore, sameAccount, status, sync, turnOff, undo, upload, usable, } from './engine.js';
+import { check, dismiss, engineFor, exportBackup, importBackup, loadConfig, preview, restore, sameAccount, status, sync, turnOff, undo, upload, usable, } from './engine.js';
 import { installPlugins } from './install.js';
 import { keysPort } from './keys.js';
 import { sameSecret } from './crypto.js';
@@ -29,6 +29,15 @@ export const name = 'dsh-webdav-sync';
 export const inject = [];
 /** Largest accepted request body (bytes) — these payloads are a few strings. */
 const BODY_LIMIT = 64 * 1024;
+/**
+ * Largest body the import route accepts: a whole sealed backup file, as text.
+ *
+ * The other routes carry a handful of form fields; this one carries a file, and a
+ * backup that includes directories carries their files as base64 inside it. The
+ * ceiling is the same 32 MiB the kept copies are bounded by, so a file this plugin
+ * would have written is a file it will read back.
+ */
+const IMPORT_LIMIT = 32 * 1024 * 1024;
 /** How long the auto-sync timer waits before its first attempt. */
 const FIRST_DELAY_MS = 20_000;
 function readVolatile(value) {
@@ -244,12 +253,12 @@ export function apply(ctx, config = {}) {
             res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
             res.end(JSON.stringify(body));
         };
-        const readJson = (req) => new Promise((resolvePromise, rejectPromise) => {
+        const readJson = (req, limit = BODY_LIMIT) => new Promise((resolvePromise, rejectPromise) => {
             const chunks = [];
             let size = 0;
             req.on('data', (chunk) => {
                 size += chunk.length;
-                if (size > BODY_LIMIT) {
+                if (size > limit) {
                     req.destroy();
                     rejectPromise(new Error('请求内容过大'));
                     return;
@@ -276,13 +285,13 @@ export function apply(ctx, config = {}) {
          * a person ("服务器上没有目录 … 请先在那边建好"), not to be mapped
          * onto status codes.
          */
-        const route = (path, label, handle) => {
+        const route = (path, label, handle, limit = BODY_LIMIT) => {
             webCtx.effect(() => webCtx.webServer.register({
                 kind: 'exact',
                 path,
                 handler: async (req, res) => {
                     try {
-                        await handle(req, res, req.method === 'GET' ? {} : await readJson(req));
+                        await handle(req, res, req.method === 'GET' ? {} : await readJson(req, limit));
                     }
                     catch (error) {
                         const text = error instanceof Error ? error.message : String(error);
@@ -330,6 +339,17 @@ export function apply(ctx, config = {}) {
         route(ROUTE_UNDO, 'undo', async (_req, res) => {
             send(res, 200, await undo(await engine()));
         });
+        // The two manual-backup routes are the one pair that works with the filesystem
+        // on this side of the wire. The card cannot save a file — the desktop shell
+        // cancels browser downloads and exposes no save dialog — and cannot read one
+        // either, so the export is written here and the import arrives as the file's
+        // own text. See `docs/decisions/0060-manual-backup.md`.
+        route(ROUTE_EXPORT, 'export', async (_req, res, body) => {
+            send(res, 200, await exportBackup(await engine(), (body ?? {})));
+        });
+        route(ROUTE_IMPORT, 'import', async (_req, res, body) => {
+            send(res, 200, await importBackup(await engine(), (body ?? {})));
+        }, IMPORT_LIMIT);
         route(ROUTE_UPLOAD, 'upload', async (_req, res) => {
             send(res, 200, await upload(await engine()));
         });
@@ -348,7 +368,7 @@ export function apply(ctx, config = {}) {
             send(res, 200, await installPlugins(current.paths));
         });
     });
-    startTimer(ctx, currentConfig);
+    startTimer(ctx, engine);
 }
 /** Make sure the state directory exists, so the first sync has somewhere to write. */
 async function saveStateIfUsable(engine) {
@@ -368,7 +388,7 @@ async function saveStateIfUsable(engine) {
  * A failure is recorded in the state by `sync` itself and changes nothing here:
  * the next tick tries again, which is the whole point of a timer.
  */
-function startTimer(ctx, currentConfig) {
+function startTimer(ctx, currentEngine) {
     let timer;
     let stopped = false;
     const tick = async () => {
@@ -376,11 +396,12 @@ function startTimer(ctx, currentConfig) {
             return;
         let wait = 0;
         try {
-            const paths = resolveFromEnv(readVolatile(currentConfig().profileDir));
-            const { config: stored } = await loadConfig(paths);
-            const minutes = stored.autoEvery;
-            if (usable(stored) && minutes > 0) {
-                await sync(engineFor(paths, stored)).catch(() => undefined);
+            // Use the same fresh engine as the routes: reading only sync.json would
+            // drop both the host credential service and a session-only WebDAV password.
+            const current = await currentEngine();
+            const minutes = current.config.autoEvery;
+            if (usable(current.config) && minutes > 0) {
+                await sync(current).catch(() => undefined);
                 wait = minutes * 60_000;
             }
         }

package/lib/wire.d.ts

@@ -31,6 +31,10 @@ export declare const ROUTE_INSTALL = "/plugin/webdav-sync/install";
 export declare const ROUTE_PREVIEW = "/plugin/webdav-sync/preview";
 /** POST: put back the copies a restore replaced. */
 export declare const ROUTE_UNDO = "/plugin/webdav-sync/undo";
+/** POST: write one passphrase-sealed backup file into a folder the person picked. */
+export declare const ROUTE_EXPORT = "/plugin/webdav-sync/export";
+/** POST: open a picked backup file and put what it holds on this computer. */
+export declare const ROUTE_IMPORT = "/plugin/webdav-sync/import";
 /** Error envelope shared by every route. */
 export interface RouteError {
     error: string;
@@ -292,6 +296,8 @@ export interface StoredState extends SyncRecord {
     key?: string | undefined;
     /** Last sync attempt, ISO-8601. */
     last?: string | undefined;
+    /** True once keys have a trustworthy local comparison baseline. */
+    keysBaseline?: boolean | undefined;
     /**
      * Last attempt that actually moved something, ISO-8601: a push, a part taken
      * from the server, or a restore. Absent until one has. This is the difference
@@ -567,6 +573,67 @@ export interface InstallResult {
 export interface MessageResult {
     message: string;
 }
+/** POST {@link ROUTE_EXPORT} body. */
+export interface ExportBody {
+    /**
+     * The passphrase this file is sealed with.
+     *
+     * It is asked for on every export rather than taken from the configuration:
+     * the file leaves this computer, and the sync passphrase is the one thing that
+     * also opens the copy on the server. Typing a second one for the file means a
+     * file that leaks opens nothing else.
+     */
+    passphrase?: string;
+    /**
+     * Where to write it: a folder, or a full path ending in `.prop`.
+     *
+     * Blank means the home folder. A folder is asked for rather than fixed because
+     * the point of the file is to be carried somewhere — a removable disk, a shared
+     * folder — and only the person knows which one.
+     */
+    dir?: string;
+}
+/** POST {@link ROUTE_EXPORT} result. */
+export interface ExportResult {
+    /** Absolute path of the file that was written. */
+    file: string;
+    /** How many bytes it is. */
+    size: number;
+    /** Which parts of the setup the file carries. */
+    parts: Part[];
+}
+/** POST {@link ROUTE_IMPORT} body. */
+export interface ImportBody {
+    /** The passphrase the file was sealed with. */
+    passphrase?: string;
+    /**
+     * The file's own text, as the browser read it.
+     *
+     * It travels as text rather than as a path because the browser half cannot see
+     * the filesystem: a picked file is a `File` whose bytes only that half holds.
+     * The sealed backup is indented JSON, so its text is its bytes.
+     */
+    text?: string;
+}
+/** POST {@link ROUTE_IMPORT} result. */
+export interface ImportResult {
+    /** Parts the file put on this computer. */
+    here: Part[];
+    /** Parts the file carried that this computer already held unchanged. */
+    same: Part[];
+    /** Folder the replaced copies were kept in, when any were. */
+    saved?: string;
+    /** The profile has to be reloaded for the applied configuration to take effect. */
+    reloadNeeded: boolean;
+    /** The profile now declares plugins that are not installed; run the install action. */
+    pendingInstall: boolean;
+    /** Which plugins those are, present exactly when {@link pendingInstall} is true. */
+    pendingNames?: string[];
+    /** Keys the file brought that this computer's credential store would not take. */
+    keysProblems?: KeyProblem[];
+    /** When the exporting computer wrote the file, ISO-8601. */
+    created: string;
+}
 /** Which of a part's two sides a preview call would take. */
 export interface PreviewChange {
     part: Part;

package/lib/wire.js

@@ -31,6 +31,10 @@ export const ROUTE_INSTALL = `${ROUTE_PREFIX}/install`;
 export const ROUTE_PREVIEW = `${ROUTE_PREFIX}/preview`;
 /** POST: put back the copies a restore replaced. */
 export const ROUTE_UNDO = `${ROUTE_PREFIX}/undo`;
+/** POST: write one passphrase-sealed backup file into a folder the person picked. */
+export const ROUTE_EXPORT = `${ROUTE_PREFIX}/export`;
+/** POST: open a picked backup file and put what it holds on this computer. */
+export const ROUTE_IMPORT = `${ROUTE_PREFIX}/import`;
 // ---------------------------------------------------------------------------
 // Remote folder layout
 // ---------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-webdav-sync",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "用 WebDAV 在多台电脑之间同步 DSH 的配置：模型供应商与模型、已安装插件、其余 profile 配置、附加目录与 API 密钥。整个备份在离开本机前用口令加密（AES-256-GCM + PBKDF2），以分片三方合并的方式在服务端保留一个加密文件。",
   "keywords": [
     "dsh",