dsh-webdav-sync 1.0.0 → 1.0.2

package/lib/engine.js

@@ -17,10 +17,27 @@ 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 { CorruptError, NotBackupError, PassphraseError, hashJson, open, seal, sum } from './crypto.js';
-import { Dav, LoginError, RateLimitedError } from './dav.js';
+import { Dav, LoginError, RateLimitedError, parseHeaders } from './dav.js';
+import { dirsDiffer, dirsPartOf, readDirs, writeDirs } from './dirs.js';
 import { applyManifest, applyPatch, collect, isMissing, keepAside, message, missingPlugins, readManifest, readPatch, writeIfChanged, } from './store.js';
 import { cached, ensureStateDir, keptDir, loadConfig, loadState, normaliseUrl, releasePassword, remember, sameAccount, saveConfig, saveState, stateKey, syncsPart, usable, } from './state.js';
 import { resolvePaths } from './paths.js';
+/**
+ * This computer's whole setup, as parts.
+ *
+ * The four profile parts are read once; the extra directories have to be walked,
+ * so they arrive separately and are put back together here. `carried` is the
+ * server's `dirs` part, and it is used for the directories this computer could not
+ * read — see {@link dirsPartOf} for why carrying those beats reading them as
+ * empty ones.
+ */
+function partsOf(snapshot, carried) {
+    const dirs = dirsPartOf(snapshot.dirs, carried);
+    // No directories named and none carried: the part is left out entirely rather
+    // than sent as an empty one, so a computer that syncs none of them can never be
+    // the one that empties the part for the computers that do.
+    return dirs === undefined ? { ...snapshot.parts } : { ...snapshot.parts, dirs };
+}
 /**
  * One operation at a time, per process.
  *
@@ -58,8 +75,15 @@ export async function sync(engine, options = {}) {
         await ensureStateDir(paths);
         const state = await freshState(paths, config);
         const outcome = await syncOnce(engine, state, options.force === true);
-        state.last = new Date().toISOString();
+        const at = new Date().toISOString();
+        state.last = at;
         state.error = '';
+        // `here` and `there` name the parts that moved, and `pushed` says the sealed
+        // file went up: any of the three means this attempt moved bytes. An attempt
+        // that only looked leaves `moved` where it was, which is what tells a check
+        // apart from a sync on the card. See docs/decisions/0039-the-card-says-check-and-sync-apart.md.
+        if (outcome.pushed || outcome.here.length > 0 || outcome.there.length > 0)
+            state.moved = at;
         await saveState(paths, state);
         return outcome;
     });
@@ -114,7 +138,7 @@ async function recordFailure(engine, cause) {
 }
 async function syncOnce(engine, state, force) {
     const { paths, config } = engine;
-    const dav = new Dav({ url: config.url, user: config.user, password: config.password });
+    const dav = davOf(config);
     const read = await dav.get(state.server);
     // A write that went out without the server checking its version may have
     // overlapped another computer's, and which of the two landed cannot be told
@@ -138,11 +162,17 @@ async function syncOnce(engine, state, force) {
         }
         state.blind = undefined;
     }
-    const snapshot = await take(paths);
-    const local = hashesOf(snapshot.parts);
+    const snapshot = await take(paths, config);
     let remote = await openRemote(engine, state, read);
     const first = state.local === undefined;
-    if (remote.notModified && sameHashes(local, state.local) && !force) {
+    // A directory could not be read this run: its part stands in for the server's
+    // copy of it, and the server's copy cannot be known from a `notModified` answer
+    // — so the comparison below is made without it and comes out false, which takes
+    // this sync the long way round and reads the file. That is the right price for
+    // not confusing "could not measure" with "measured, and it is empty".
+    if (remote.notModified
+        && 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)) };
     }
@@ -152,12 +182,15 @@ async function syncOnce(engine, state, force) {
         // needed to merge against and it is read again, this time in full.
         remote = await openRemote(engine, state, await dav.get());
     }
+    const carried = remote.part('dirs');
+    const localParts = partsOf(snapshot, carried);
+    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.
     if (remote.empty) {
         return await push(engine, state, snapshot, {
-            merged: { ...snapshot.parts },
-            applied: { ...snapshot.parts },
+            merged: { ...localParts },
+            applied: { ...localParts },
             remote: remote.hashes,
             version: remote.version,
             here: [],
@@ -198,8 +231,8 @@ async function syncOnce(engine, state, force) {
             const ours = localChangedAt(snapshot, part);
             if (!Number.isFinite(serverAt) || ours >= serverAt) {
                 if (local[part] !== undefined) {
-                    merged[part] = snapshot.parts[part];
-                    applied[part] = snapshot.parts[part];
+                    merged[part] = localParts[part];
+                    applied[part] = localParts[part];
                     there.push(part);
                 }
             }
@@ -226,6 +259,15 @@ async function syncOnce(engine, state, force) {
                 applied[part] = remotePart();
                 here.push(part);
             }
+            else if (part === 'dirs' && local[part] !== undefined) {
+                // The one removal this computer does not take. Its own directories are still
+                // named here, and the part does nothing but say which paths travel: taking it
+                // away would leave them unsynced for no gain, so the copy here is what goes
+                // back up.
+                merged[part] = localParts[part];
+                applied[part] = localParts[part];
+                there.push(part);
+            }
             else if (removable) {
                 applied[part] = null;
                 here.push(part);
@@ -235,26 +277,39 @@ async function syncOnce(engine, state, force) {
         if (changedHere) {
             // Only this computer moved: the part goes up.
             if (local[part] !== undefined) {
-                merged[part] = snapshot.parts[part];
-                applied[part] = snapshot.parts[part];
+                merged[part] = localParts[part];
+                applied[part] = localParts[part];
                 there.push(part);
             }
+            else if (part === 'dirs' && remoteHas) {
+                // The list of directories was emptied here. That means "stop syncing these
+                // on this computer", not "everybody delete them": the part is carried
+                // through as the server has it, so the computers that still name a
+                // directory keep syncing it between themselves and no file anywhere is
+                // removed for it.
+                merged[part] = remotePart();
+            }
             continue;
         }
         // Neither side moved. This computer's copy is taken when it has one, so a
         // part that is present on only one side is never dropped by accident.
         if (local[part] !== undefined) {
-            merged[part] = snapshot.parts[part];
-            applied[part] = snapshot.parts[part];
+            merged[part] = localParts[part];
+            applied[part] = localParts[part];
         }
         else if (remoteHas) {
             merged[part] = remotePart();
-            applied[part] = remotePart();
+            // A computer that names no directories leaves its disk alone here: writing
+            // the server's list back would put files into a folder the user has just
+            // taken off that list. Restore is the action that lands in such a folder,
+            // and it says so on the card; an ordinary sync has nothing to write.
+            if (part !== 'dirs' || config.dirs.length > 0)
+                applied[part] = remotePart();
         }
     }
     let saved;
     if (conflicted)
-        saved = await keepConflict(engine, snapshot, remote);
+        saved = await keepConflict(engine, snapshot, remote, here.includes('dirs') || there.includes('dirs'));
     else if (first && here.length > 0 && !sameHashes(local, remote.hashes)) {
         // The server's setup is being taken over one this computer had, with no
         // baseline to weigh them: a join, or a state file that was lost. Either way
@@ -272,7 +327,10 @@ async function syncOnce(engine, state, force) {
     if (!pushNeeded) {
         const written = await applyMerged(engine, snapshot, applied);
         state.remote = remote.hashes;
-        state.local = hashesOf((await take(paths)).parts);
+        // 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), undefined));
         // 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
@@ -317,7 +375,7 @@ async function syncOnce(engine, state, force) {
  * version does not understand. The shapes are checked here instead, before
  * anything is decided on.
  *
- * Absent parts are fine: a bundle may carry any of the four.
+ * Absent parts are fine: a bundle may carry any of the five.
  */
 function unreadablePart(bundle) {
     const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -325,6 +383,31 @@ function unreadablePart(bundle) {
         const value = bundle[part];
         if (value === undefined)
             continue;
+        // The extra directories are an object holding the list, and an empty list is a
+        // setup with none rather than a part that cannot be read.
+        if (part === 'dirs') {
+            if (!isObject(value))
+                return part;
+            const record = value;
+            if (!Array.isArray(record.dirs))
+                return part;
+            const readable = (one) => {
+                if (!isObject(one))
+                    return false;
+                const dir = one;
+                if (typeof dir.path !== 'string' || !Array.isArray(dir.files))
+                    return false;
+                return dir.files.every((file) => {
+                    if (!isObject(file))
+                        return false;
+                    const inner = file;
+                    return typeof inner.path === 'string' && typeof inner.data === 'string';
+                });
+            };
+            if (!record.dirs.every(readable))
+                return part;
+            continue;
+        }
         if (!isObject(value))
             return part;
         const record = value;
@@ -454,13 +537,13 @@ async function push(engine, state, snapshot, merged) {
     // the one that was there before: the guard is asking, next time, whether the
     // bytes on the server are still the ones it wrote.
     const before = { sum: sum(sealed), local: state.local, remote: state.remote };
-    const dav = new Dav({ url: config.url, user: config.user, password: config.password });
+    const dav = davOf(config);
     const written = await dav.put(sealed, merged.version.etag ?? '');
     // The parts are written here only after the write to the server succeeded, so a
     // 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((await take(paths)).parts);
+    const now = hashesOf(partsOf(await take(paths, config), undefined));
     state.server = written;
     state.sum = sum(sealed);
     state.remote = hashesOf(bundle);
@@ -496,9 +579,35 @@ async function push(engine, state, snapshot, merged) {
  * profile.
  */
 async function applyMerged(engine, snapshot, applied) {
-    const { paths, config } = engine;
+    const { paths } = engine;
     let reloadNeeded = false;
     let kept = false;
+    // The directories are written first so that, when they are written at all, the
+    // copy kept for the way back is the one that carries them ({@link keepBefore}).
+    // `null` is "the other computer took this part away" — the instruction the other
+    // parts obey by deleting a row. Here it means nothing at all on disk: a sync
+    // never removes a file from somebody's own directory, so a removed part leaves
+    // what is there exactly as it is.
+    if (applied.dirs !== undefined && applied.dirs !== null) {
+        const part = applied.dirs;
+        // A directory this run could not read is not written into: what is there now
+        // was never read, so replacing it would be writing blind. A directory that is
+        // merely absent is not in this set — creating it is what a restore is for. See
+        // {@link writeDirs}.
+        const skip = new Set(snapshot.dirs.problems.filter((problem) => problem.missing !== true).map((problem) => problem.path));
+        // Compared with the disk rather than with the configured list, so that a
+        // computer which syncs no directories of its own — but is sent somebody's, which
+        // is how a restore lands in the same folder — does not seal a copy before a write
+        // that changes nothing. The copy is what Undo puts back, so it has to carry the
+        // directories whenever they really are about to be written to.
+        if (await dirsDiffer(part, skip)) {
+            kept = true;
+            await keepBefore(engine, snapshot, true);
+            const wrote = await writeDirs(part, skip);
+            if (wrote.changed)
+                reloadNeeded = true;
+        }
+    }
     if (applied.models !== undefined || applied.defaults !== undefined || applied.patch !== undefined) {
         // `null` means "take this away", which is how a removal made on another
         // computer reaches this one. The patch part has no row of its own to remove,
@@ -528,15 +637,23 @@ async function applyMerged(engine, snapshot, applied) {
     }
     return { reloadNeeded };
 }
-/** Seal this computer's setup into `sync/before-apply` before a merge writes. */
-async function keepBefore(engine, snapshot) {
+/**
+ * Seal this computer's setup into `sync/before-apply` before a merge writes.
+ *
+ * `withDirs` is on when the write about to happen touches the extra directories,
+ * because that copy is what Undo puts back and a directory left out of it could not
+ * be put back. It is off otherwise: a directory tree can run to megabytes, and a
+ * copy taken so that one patch row can be undone has no business carrying it.
+ */
+async function keepBefore(engine, snapshot, withDirs = false) {
     try {
+        const parts = withDirs ? partsOf(snapshot, undefined) : { ...snapshot.parts };
         const bundle = {
             format: BUNDLE_FORMAT,
             version: BUNDLE_VERSION,
             created: new Date().toISOString(),
             app: BUNDLE_APP,
-            ...snapshot.parts,
+            ...parts,
         };
         const sealed = await seal(bundle, engine.config.passphrase);
         return await keepAside(keptDir(engine.paths), 'before-apply', sealed);
@@ -547,15 +664,16 @@ async function keepBefore(engine, snapshot) {
     }
 }
 /** Keep both sides of a conflict, so the one that lost is still readable. */
-async function keepConflict(engine, snapshot, remote) {
+async function keepConflict(engine, snapshot, remote, withDirs = false) {
     const { paths, config } = engine;
     const dir = keptDir(paths);
+    const parts = withDirs ? partsOf(snapshot, undefined) : { ...snapshot.parts };
     const ours = {
         format: BUNDLE_FORMAT,
         version: BUNDLE_VERSION,
         created: new Date().toISOString(),
         app: BUNDLE_APP,
-        ...snapshot.parts,
+        ...parts,
     };
     await keepAside(dir, 'this-computer', await seal(ours, config.passphrase)).catch(() => undefined);
     if (remote.body !== undefined) {
@@ -586,7 +704,7 @@ async function keepConflict(engine, snapshot, remote) {
  * nothing.
  */
 async function keepUnmerged(engine, snapshot) {
-    const kept = await keepBefore(engine, snapshot);
+    const kept = await keepBefore(engine, snapshot, true);
     return kept === undefined ? undefined : keptDir(engine.paths);
 }
 /**
@@ -625,7 +743,7 @@ export async function restore(engine) {
             throw new Error('同步还没有配置好：请先填写地址和口令');
         await ensureStateDir(paths);
         const state = await freshState(paths, config);
-        const dav = new Dav({ url: config.url, user: config.user, password: config.password });
+        const dav = davOf(config);
         const read = await dav.get();
         if (read.notModified || read.data === undefined) {
             if (read.data === undefined)
@@ -634,8 +752,13 @@ export async function restore(engine) {
         const remote = await openRemote(engine, state, { ...read, notModified: false });
         if (remote.empty)
             throw new Error('服务器上还没有 dsh 配置：没有可恢复的内容');
-        const snapshot = await take(paths);
-        const local = hashesOf(snapshot.parts);
+        const snapshot = await take(paths, config);
+        // What is here *on disk* is what the notice is about, so the directories are
+        // hashed without standing in the server's copy for the ones this computer could
+        // not read: a folder that is merely absent reads as nothing here, differs from
+        // the server's copy, and is therefore named as brought in — which is what a
+        // restore that creates it has just done.
+        const local = hashesOf(partsOf(snapshot, undefined));
         const here = [];
         const merged = {};
         const applied = {};
@@ -655,16 +778,20 @@ export async function restore(engine) {
             if (local[part] !== remote.hashes[part])
                 here.push(part);
         }
-        const kept = await keepBefore(engine, snapshot);
+        const kept = await keepBefore(engine, snapshot, true);
         const written = await applyMerged(engine, snapshot, applied);
         state.undo = kept ?? '';
         state.remote = remote.hashes;
-        state.local = hashesOf((await take(paths)).parts);
+        state.local = hashesOf(partsOf(await take(paths, config), undefined));
         state.sum = read.data === undefined ? state.sum : sum(read.data);
         state.server = read.version;
         state.blind = undefined;
         state.last = new Date().toISOString();
         state.error = '';
+        // Every part named in `here` was written over this computer's copy, or was
+        // taken away for Undo; a restore that named none found the two sides alike.
+        if (here.length > 0)
+            state.moved = state.last;
         state.notice = { at: new Date().toISOString(), here, there: [], ...(kept === undefined ? {} : { saved: keptDir(paths) }), restored: true };
         if (read.data !== undefined)
             await remember(paths, read.data);
@@ -694,7 +821,7 @@ export async function upload(engine) {
             throw new Error('同步还没有配置好：请先填写地址和口令');
         await ensureStateDir(paths);
         const state = await freshState(paths, config);
-        const dav = new Dav({ url: config.url, user: config.user, password: config.password });
+        const dav = davOf(config);
         const read = await dav.get();
         if (read.data !== undefined) {
             let readable = true;
@@ -715,9 +842,9 @@ export async function upload(engine) {
             }
             await keepAside(keptDir(paths), 'server-replaced', read.data);
         }
-        const snapshot = await take(paths);
+        const snapshot = await take(paths, config);
         const result = await push(engine, state, snapshot, {
-            merged: { ...snapshot.parts },
+            merged: { ...partsOf(snapshot, undefined) },
             applied: {},
             remote: {},
             version: read.version,
@@ -726,6 +853,9 @@ export async function upload(engine) {
         });
         state.last = new Date().toISOString();
         state.error = '';
+        // An upload is this computer's setup going up wholesale, whatever the server
+        // held before: it moved something even when it was asked for as a rescue.
+        state.moved = state.last;
         await saveState(paths, state);
         return result;
     });
@@ -746,7 +876,7 @@ export async function undo(engine) {
             throw new Error('恢复之前留下的那份副本已经不在了，没有东西可以放回去');
         }
         const bundle = (await open(new Uint8Array(data), config.passphrase));
-        const snapshot = await take(paths);
+        const snapshot = await take(paths, config);
         const merged = {};
         const applied = {};
         const back = [];
@@ -792,8 +922,8 @@ export async function status(engine) {
     const { paths, config } = engine;
     const state = await loadState(paths);
     const fresh = state.key === stateKey(config);
-    const snapshot = await take(paths).catch(() => undefined);
-    const local = snapshot === undefined ? {} : hashesOf(snapshot.parts);
+    const snapshot = await take(paths, config).catch(() => undefined);
+    const local = snapshot === undefined ? {} : hashesOf(partsOf(snapshot, undefined));
     const parts = [];
     const known = fresh ? state.local : undefined;
     const knownRemote = fresh ? state.remote : undefined;
@@ -842,11 +972,17 @@ export async function status(engine) {
             packageFile: paths.packageFile,
         },
         ...(fresh && state.last !== undefined && state.last !== '' ? { last: state.last } : {}),
+        ...(fresh && state.moved !== undefined && state.moved !== '' ? { moved: state.moved } : {}),
         error: errorApplies && typeof state.error === 'string' ? state.error : '',
         ...(fresh && state.notice !== undefined ? { notice: state.notice } : {}),
         parts,
         pendingInstall: missing.length > 0,
         ...(missing.length > 0 ? { pendingNames: missing } : {}),
+        // A directory that could not be read is said here rather than kept quiet: it
+        // is the one thing about this feature the person has to act on.
+        ...(snapshot === undefined || snapshot.dirs.problems.length === 0
+            ? {}
+            : { dirProblems: snapshot.dirs.problems }),
         undoable: fresh && state.undo !== undefined && state.undo !== '',
     };
 }
@@ -872,6 +1008,19 @@ export async function turnOff(engine) {
     // host would send, and turning sync off is the way to clear one.
     releasePassword(engine.paths);
 }
+/**
+ * The client one configuration reaches: its address, its account, and the extra
+ * headers the card configured. Parsed once here rather than at every call, so a
+ * malformed configured line is refused before the first request goes out.
+ */
+function davOf(config) {
+    return new Dav({
+        url: config.url,
+        user: config.user,
+        password: config.password,
+        headers: parseHeaders(config.headers),
+    });
+}
 /** The configuration as the card sees it: never a secret, only whether one is set. */
 export function viewOf(config) {
     return {
@@ -884,7 +1033,12 @@ export function viewOf(config) {
         defaults: config.defaults,
         plugins: config.plugins,
         patch: config.patch,
+        dirs: [...config.dirs],
+        dirsEnabled: config.dirsEnabled,
         rememberPassword: config.rememberPassword,
+        headers: config.headers,
+        relayEnabled: config.relayEnabled,
+        relayPort: config.relayPort,
     };
 }
 // ---------------------------------------------------------------------------
@@ -895,7 +1049,7 @@ export async function check(engine) {
     const { config } = engine;
     if (normaliseUrl(config.url) === '')
         throw new Error('请先填写同步地址');
-    const dav = new Dav({ url: config.url, user: config.user, password: config.password });
+    const dav = davOf(config);
     try {
         await dav.check();
     }
@@ -946,11 +1100,11 @@ export async function preview(engine) {
     if (!usable(config))
         throw new Error('同步还没有配置好：请先填写地址和口令');
     const state = await freshState(paths, config);
-    const dav = new Dav({ url: config.url, user: config.user, password: config.password });
+    const dav = davOf(config);
     const read = await dav.get(state.server);
     const remote = await openRemote(engine, state, read);
-    const snapshot = await take(paths);
-    const local = hashesOf(snapshot.parts);
+    const snapshot = await take(paths, config);
+    const local = hashesOf(partsOf(snapshot, remote.part('dirs')));
     const first = state.local === undefined;
     const changes = [];
     for (const part of PARTS) {
@@ -976,10 +1130,15 @@ export async function preview(engine) {
 // Small helpers
 // ---------------------------------------------------------------------------
 /** Read this computer's setup and the files it came from, in one pass. */
-export async function take(paths) {
+export async function take(paths, config) {
     const patch = await readPatch(paths);
     const manifest = await readManifest(paths);
-    return { patch, manifest, parts: collect(patch, manifest) };
+    // Switched off, the directories are not walked at all: reading them is the one
+    // part of a snapshot that can cost a great deal, and a part this configuration
+    // does not carry has nothing to say. An empty read still tells the merge there is
+    // nothing here to compare, which is exactly true.
+    const dirs = await readDirs(config.dirsEnabled ? config.dirs : []);
+    return { patch, manifest, parts: collect(patch, manifest), dirs };
 }
 /** Per-part hashes of a setup; a part that is not there has none. */
 export function hashesOf(parts) {
@@ -1006,6 +1165,10 @@ export function sameHashes(a, b) {
 export function localChangedAt(snapshot, part) {
     if (part === 'plugins')
         return snapshot.manifest.mtimeMs;
+    // The extra directories have no file of their own to point at, so the newest
+    // file inside any of them stands for the whole part.
+    if (part === 'dirs')
+        return snapshot.dirs.mtimeMs;
     return snapshot.patch.mtimeMs;
 }
 /** The top-level packages present in the profile's node_modules. */

package/lib/index.d.ts

@@ -20,8 +20,6 @@ import { sameAccount, usable, type Engine } from './engine.js';
 import { defaultConfig, normaliseConfig } from './state.js';
 export declare const name = "dsh-webdav-sync";
 export declare const inject: never[];
-/** The settings namespace this plugin serves; its browser card spells the same string. */
-export declare const WEBDAV_SYNC_NS = "dsh-webdav-sync";
 export interface Config {
     /** Profile directory to sync; absent selects the running profile. */
     profileDir?: Volatile<string | undefined> | string;
@@ -36,13 +34,6 @@ export interface Config {
 export declare const Config: z;
 /** Reject stale or misspelled config keys before defaults can hide them. */
 export declare function validateConfig(config: Config): void;
-/** The settings-facing subset of the config. */
-export interface SectionConfig {
-    profileDir?: string;
-    autoEvery: number;
-}
-/** The section-shaped view of a config: absent keys stay absent. */
-export declare function sectionOf(config: Config): SectionConfig;
 /**
  * Apply one configuration change from the card.
  *
@@ -59,16 +50,14 @@ export declare function configure(engine: Engine, body: ConfigureBody): Promise<
 /**
  * Plugin apply: mount the settings presentation policy, the HTTP routes and the
  * auto-sync timer on any webServer that comes and goes.
- */
-/**
- * Passwords that are in use but deliberately not on disk.
  *
- * "Remember the password" off means it must not be written to `sync.json`, and
- * it does not mean it should stop working: every route rebuilds its engine from
- * that file, so a password emptied there would be one no request could carry and
- * sync would be unable to sign in until the process restarted. It is held for as
- * long as the host runs, keyed by the state directory so two profiles do not
- * share one, and put back into the configuration each time it is read.
+ * Passwords that are in use but deliberately not on disk are read back here:
+ * "remember the password" off means it must not be written to `sync.json`, and it
+ * does not mean it should stop working. Every route rebuilds its engine from that
+ * file, so a password emptied there would be one no request could carry and sync
+ * would be unable to sign in until the process restarted. It is held for as long
+ * as the host runs, keyed by the state directory so two profiles do not share
+ * one, and put back into the configuration each time it is read.
  */
 export declare function apply(ctx: Context, config?: Config): void;
 export { defaultConfig, normaliseConfig, sameAccount, usable };