dsh-webdav-sync 1.0.5 → 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';
@@ -935,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 () => {

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()));
         });

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