dsh-webdav-sync 1.0.3 → 1.0.4

package/lib/engine.js

@@ -22,14 +22,15 @@ 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';
+import { applyKeys, readKeys } from './keys.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.
+ * The profile parts are read once, and the keys with them; 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);
@@ -54,9 +55,9 @@ function serially(work) {
     queue = next.then(() => undefined, () => undefined);
     return next;
 }
-/** The engine for a profile directory and a configuration. */
-export function engineFor(paths, config) {
-    return { paths, config };
+/** The engine for a profile directory, a configuration, and the host's credential store. */
+export function engineFor(paths, config, credentials) {
+    return { paths, config, credentials };
 }
 // ---------------------------------------------------------------------------
 // Sync
@@ -162,7 +163,7 @@ async function syncOnce(engine, state, force) {
         }
         state.blind = undefined;
     }
-    const snapshot = await take(paths, config);
+    const snapshot = await take(paths, config, engine.credentials);
     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
@@ -330,7 +331,7 @@ async function syncOnce(engine, state, force) {
         // 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));
+        state.local = hashesOf(partsOf(await take(paths, config, engine.credentials), 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
@@ -350,6 +351,7 @@ async function syncOnce(engine, state, force) {
             ...(saved === undefined ? {} : { saved }),
             pushed: false,
             reloadNeeded: written.reloadNeeded,
+            ...keyProblems(written.keysProblems),
             ...(await pendings(engine, applied.plugins)),
         };
     }
@@ -411,7 +413,7 @@ function unreadablePart(bundle) {
         if (!isObject(value))
             return part;
         const record = value;
-        if (part === 'models' || part === 'defaults') {
+        if (part === 'models') {
             if (!isObject(record.config))
                 return part;
             continue;
@@ -427,6 +429,17 @@ function unreadablePart(bundle) {
                 return part;
             continue;
         }
+        if (part === 'keys') {
+            // Ref names and their values, both strings: anything else is a file this
+            // plugin did not write, and reading it as empty would be a lie about what
+            // this computer holds.
+            const refs = record.refs;
+            if (!isObject(refs))
+                return part;
+            if (!Object.entries(refs).every(([ref, value]) => ref !== '' && typeof value === 'string'))
+                return part;
+            continue;
+        }
         // The remaining part is the leftover patch rows.
         if (!Array.isArray(record.entries))
             return part;
@@ -543,7 +556,7 @@ 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), undefined));
+    const now = hashesOf(partsOf(await take(paths, config, engine.credentials), undefined));
     state.server = written;
     state.sum = sum(sealed);
     state.remote = hashesOf(bundle);
@@ -566,6 +579,7 @@ async function push(engine, state, snapshot, merged) {
         ...(merged.saved === undefined ? {} : { saved: merged.saved }),
         pushed: true,
         reloadNeeded: applied.reloadNeeded,
+        ...keyProblems(applied.keysProblems),
         ...(await pendings(engine, merged.merged.plugins)),
     };
 }
@@ -608,13 +622,12 @@ async function applyMerged(engine, snapshot, applied) {
                 reloadNeeded = true;
         }
     }
-    if (applied.models !== undefined || applied.defaults !== undefined || applied.patch !== undefined) {
+    if (applied.models !== 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,
         // so it is emptied instead.
         const next = applyPatch(snapshot.patch, {
             models: applied.models,
-            defaults: applied.defaults,
             ...(applied.patch === null ? { patch: { entries: [] } } : { patch: applied.patch }),
         });
         if (next !== snapshot.patch.text) {
@@ -635,7 +648,30 @@ async function applyMerged(engine, snapshot, applied) {
                 reloadNeeded = true;
         }
     }
-    return { reloadNeeded };
+    // The keys go last and through the host's credential service rather than a file
+    // of this plugin's own ({@link applyKeys}): each one is a call on a store another
+    // package owns, so a refusal there leaves the profile's files written and the key
+    // reported. Nothing here reloads, either — DSH resolves a credential per call, so
+    // the next provider request already sees the new value.
+    let keysProblems = [];
+    if (applied.keys !== undefined) {
+        keysProblems = await applyKeys(engine.credentials, applied.keys, async () => {
+            if (kept)
+                return;
+            kept = true;
+            await keepBefore(engine, snapshot);
+        });
+    }
+    return { reloadNeeded, keysProblems };
+}
+/**
+ * The `keysProblems` field of a result, present only when there is one.
+ *
+ * The card reads an absent field as "every key went in", so an empty list is left
+ * off rather than sent as an empty one to be filtered on the other side.
+ */
+function keyProblems(problems) {
+    return problems.length === 0 ? {} : { keysProblems: problems };
 }
 /**
  * Seal this computer's setup into `sync/before-apply` before a merge writes.
@@ -752,7 +788,7 @@ 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, config);
+        const snapshot = await take(paths, config, engine.credentials);
         // 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
@@ -782,7 +818,7 @@ export async function restore(engine) {
         const written = await applyMerged(engine, snapshot, applied);
         state.undo = kept ?? '';
         state.remote = remote.hashes;
-        state.local = hashesOf(partsOf(await take(paths, config), undefined));
+        state.local = hashesOf(partsOf(await take(paths, config, engine.credentials), undefined));
         state.sum = read.data === undefined ? state.sum : sum(read.data);
         state.server = read.version;
         state.blind = undefined;
@@ -802,6 +838,7 @@ export async function restore(engine) {
             ...(kept === undefined ? {} : { saved: keptDir(paths) }),
             pushed: false,
             reloadNeeded: written.reloadNeeded,
+            ...keyProblems(written.keysProblems),
             ...(await pendings(engine, applied.plugins)),
         };
     });
@@ -842,7 +879,7 @@ export async function upload(engine) {
             }
             await keepAside(keptDir(paths), 'server-replaced', read.data);
         }
-        const snapshot = await take(paths, config);
+        const snapshot = await take(paths, config, engine.credentials);
         const result = await push(engine, state, snapshot, {
             merged: { ...partsOf(snapshot, undefined) },
             applied: {},
@@ -876,7 +913,7 @@ export async function undo(engine) {
             throw new Error('恢复之前留下的那份副本已经不在了，没有东西可以放回去');
         }
         const bundle = (await open(new Uint8Array(data), config.passphrase));
-        const snapshot = await take(paths, config);
+        const snapshot = await take(paths, config, engine.credentials);
         const merged = {};
         const applied = {};
         const back = [];
@@ -902,6 +939,7 @@ export async function undo(engine) {
             there: [],
             pushed: false,
             reloadNeeded: written.reloadNeeded,
+            ...keyProblems(written.keysProblems),
             ...(await pendings(engine, merged.plugins)),
         };
     });
@@ -922,7 +960,7 @@ 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, config).catch(() => undefined);
+    const snapshot = await take(paths, config, engine.credentials).catch(() => undefined);
     const local = snapshot === undefined ? {} : hashesOf(partsOf(snapshot, undefined));
     const parts = [];
     const known = fresh ? state.local : undefined;
@@ -983,6 +1021,10 @@ export async function status(engine) {
         ...(snapshot === undefined || snapshot.dirs.problems.length === 0
             ? {}
             : { dirProblems: snapshot.dirs.problems }),
+        // The same, for a key that could not be read: a store that cannot be read must
+        // not look like a store with nothing in it, or this computer would look like
+        // one with no keys and the next sync would believe it.
+        ...(snapshot === undefined ? {} : keyProblems(snapshot.keysProblems)),
         undoable: fresh && state.undo !== undefined && state.undo !== '',
     };
 }
@@ -1030,9 +1072,9 @@ export function viewOf(config) {
         passphraseSet: config.passphrase !== '',
         autoEvery: config.autoEvery,
         models: config.models,
-        defaults: config.defaults,
         plugins: config.plugins,
         patch: config.patch,
+        keys: config.keys,
         dirs: [...config.dirs],
         dirsEnabled: config.dirsEnabled,
         rememberPassword: config.rememberPassword,
@@ -1103,7 +1145,7 @@ export async function preview(engine) {
     const dav = davOf(config);
     const read = await dav.get(state.server);
     const remote = await openRemote(engine, state, read);
-    const snapshot = await take(paths, config);
+    const snapshot = await take(paths, config, engine.credentials);
     const local = hashesOf(partsOf(snapshot, remote.part('dirs')));
     const first = state.local === undefined;
     const changes = [];
@@ -1117,6 +1159,13 @@ export async function preview(engine) {
         if (!changedHere && !changedThere)
             continue;
         if (changedHere && changedThere) {
+            // A credential is the one part whose own copy the merge takes outright, since
+            // there is no local time to weigh against the server's stamp — the same rule
+            // {@link localChangedAt} states for it, said here as the answer the card shows.
+            if (part === 'keys') {
+                changes.push({ part, take: 'local' });
+                continue;
+            }
             const serverAt = Date.parse(remote.created);
             const ours = localChangedAt(snapshot, part);
             changes.push({ part, take: !Number.isFinite(serverAt) || ours >= serverAt ? 'newer-local' : 'newer-remote' });
@@ -1130,7 +1179,7 @@ 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, config) {
+export async function take(paths, config, credentials) {
     const patch = await readPatch(paths);
     const manifest = await readManifest(paths);
     // Switched off, the directories are not walked at all: reading them is the one
@@ -1138,7 +1187,14 @@ export async function take(paths, config) {
     // 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 };
+    const parts = collect(patch, manifest);
+    // The keys, read from the names the parts above just named. Switched off, they
+    // are not read at all — the same "nothing to say" the directories get — and a
+    // host with no credential store resolves nothing rather than reading as empty.
+    const keys = config.keys ? await readKeys(credentials, parts) : { problems: [] };
+    if (keys.part !== undefined)
+        parts.keys = keys.part;
+    return { patch, manifest, parts, dirs, keysProblems: keys.problems };
 }
 /** Per-part hashes of a setup; a part that is not there has none. */
 export function hashesOf(parts) {
@@ -1169,6 +1225,14 @@ export function localChangedAt(snapshot, part) {
     // file inside any of them stands for the whole part.
     if (part === 'dirs')
         return snapshot.dirs.mtimeMs;
+    // A credential has neither a file of this plugin's own nor a time the host's
+    // store reports, so there is nothing to weigh the server's stamp against. This
+    // computer's copy wins instead — it is the one that authenticates the requests
+    // made here, and it may have been stored a moment ago through the Models page,
+    // which touches no profile file at all. The copy that loses is archived by
+    // {@link keepConflict} like any other. See `docs/decisions/0054-sync-api-keys.md`.
+    if (part === 'keys')
+        return Number.POSITIVE_INFINITY;
     return snapshot.patch.mtimeMs;
 }
 /** The top-level packages present in the profile's node_modules. */

package/lib/index.js

@@ -20,6 +20,7 @@ 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 { installPlugins } from './install.js';
+import { keysPort } from './keys.js';
 import { sameSecret } from './crypto.js';
 import { normaliseDirs } from './dirs.js';
 import { parseHeaders } from './dav.js';
@@ -90,12 +91,12 @@ export async function configure(engine, body) {
         next.passphrase = body.passphrase;
     if (typeof body.models === 'boolean')
         next.models = body.models;
-    if (typeof body.defaults === 'boolean')
-        next.defaults = body.defaults;
     if (typeof body.plugins === 'boolean')
         next.plugins = body.plugins;
     if (typeof body.patch === 'boolean')
         next.patch = body.patch;
+    if (typeof body.keys === 'boolean')
+        next.keys = body.keys;
     if (typeof body.rememberPassword === 'boolean')
         next.rememberPassword = body.rememberPassword;
     if (typeof body.headers === 'string') {
@@ -176,6 +177,23 @@ export async function configure(engine, body) {
     await persistConfig(engine.paths, next);
     engine.config = next;
 }
+/**
+ * The host's credential service, in the shape the sync uses it, or `undefined` on
+ * a host that has none.
+ *
+ * A lookup rather than an injected dependency: a host without the service is a
+ * working state — the `keys` part then reads nothing, writes nothing and says so —
+ * and, like every other service here, it can come and go while the plugin is
+ * mounted. `ctx.get` is the untyped accessor, so the shape is checked rather than
+ * trusted from a type this plugin cannot import (it depends on no DSH package).
+ */
+function credentialPort(ctx) {
+    const service = ctx.get('credentials');
+    if (service === undefined || typeof service.resolve !== 'function' || typeof service.set !== 'function') {
+        return undefined;
+    }
+    return keysPort(service);
+}
 /**
  * Plugin apply: mount the settings presentation policy, the HTTP routes and the
  * auto-sync timer on any webServer that comes and goes.
@@ -196,7 +214,8 @@ export function apply(ctx, config = {}) {
         const paths = resolveFromEnv(readVolatile(currentConfig().profileDir));
         const { config: stored } = await loadConfig(paths);
         const secret = stored.rememberPassword ? undefined : heldPassword(paths);
-        return engineFor(paths, secret === undefined || secret === '' ? stored : { ...stored, password: secret });
+        const config = secret === undefined || secret === '' ? stored : { ...stored, password: secret };
+        return engineFor(paths, config, credentialPort(ctx));
     };
     // In dsh 0.1.7+, the settings service projects volatile Config fields into
     // forms. auto: false tells the host this plugin ships its own card, which the

package/lib/keys.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The `keys` part: the API keys this computer stores for the providers its
+ * profile names, and putting back the ones a merge brings.
+ *
+ * A DSH profile never holds a key. It holds the *name* of one — `apiKeyEnv` on a
+ * provider route, `secretEnv` on a webhook — and DSH resolves that name through
+ * its credential service, which layers the launch environment over this
+ * computer's own store (`$DSH_HOME/.credentials.yaml`). So a synced setup travels
+ * complete and still cannot reach a single provider: the names arrive, and on the
+ * other computer they resolve to nothing. That is the whole of this part.
+ *
+ * Two things follow from where the values live, and they are the two rules of
+ * this module:
+ *
+ * - The names come from the synced configuration, not from the store. The
+ *   credential service has no way to enumerate references — a configuration
+ *   surface learns which ones exist from its own schema — so this plugin reads the
+ *   names out of the very parts it is about to send, and asks the service for each
+ *   one. That also keeps the two in step for free: a key travels exactly when the
+ *   part that names it travels.
+ * - Nothing here deletes. A key removed on one computer stays on the others, and a
+ *   key that cannot be written is reported rather than skipped silently. See
+ *   `docs/decisions/0054-sync-api-keys.md`.
+ */
+import type { KeyProblem, KeysPart, Part } from './wire.js';
+/**
+ * The configuration field names DSH resolves as a credential reference.
+ *
+ * Taken from the schemas the shipped plugins declare: `apiKeyEnv` on the
+ * `llm-pi-ai` provider routes, on `llm-deepseek-api-key` and on
+ * `web-search-deepseek`; `secretEnv` on `webhook-github`. A plugin outside this
+ * list names its credential some other way and its key does not travel — which is
+ * why the list is here, in one place, rather than inline.
+ */
+export declare const CREDENTIAL_FIELDS: readonly string[];
+/** One reference's value as the credential service resolved it. */
+export interface ResolvedKey {
+    /** The non-empty secret. */
+    value: string;
+    /**
+     * Which layer supplied it: `env`, `file`, `project-env` or `user-env`.
+     *
+     * Only `file` — the provider-managed store, the one layer `set` writes to —
+     * travels. See {@link readKeys}.
+     */
+    source: string;
+}
+/**
+ * DSH's credential service, as far as this plugin uses it.
+ *
+ * Structural on purpose: the service belongs to another package, and this plugin
+ * neither depends on it nor requires it to be there. The two methods are `resolve`
+ * and `set` on `CredentialProvider`; `store` is the name this module gives the
+ * write, so a reader of the engine never has to know which word DSH picked.
+ */
+export interface CredentialService {
+    resolve(ref: string): Promise<ResolvedKey | undefined>;
+    set(ref: string, value: string): Promise<void>;
+}
+/** The two operations the sync needs: what is behind a name, and how to store one. */
+export interface KeysPort {
+    resolve(ref: string): Promise<ResolvedKey | undefined>;
+    store(ref: string, value: string): Promise<void>;
+}
+/** What one read of this computer's keys produced. */
+export interface KeysRead {
+    /** What travels, absent when this computer has no value for any name it knows. */
+    part?: KeysPart;
+    /** References that could not be read, with the reason. */
+    problems: KeyProblem[];
+}
+/**
+ * The credential service in the shape this plugin uses it.
+ *
+ * `set` rejects while a read-only layer shadows the reference, which is exactly
+ * the fact that matters here: a value that would not take effect is not one to
+ * report as stored. {@link applyKeys} therefore asks first and writes second.
+ */
+export declare function keysPort(service: CredentialService): KeysPort;
+/**
+ * Every credential-reference name the given parts name, deduplicated and sorted.
+ *
+ * Walks the parts as they are — no schema, no interpretation — because the value
+ * of a reference field is a name wherever it sits, and the shape of a provider
+ * config is the provider plugin's to decide, not this one's.
+ */
+export declare function credentialRefs(parts: Partial<Record<Part, unknown>>): string[];
+/**
+ * Read the keys this computer holds for the names in hand.
+ *
+ * Only the managed store travels: a name the launching environment supplies is
+ * left out, and so is one that falls through to a `.env`. Two reasons, and they
+ * agree — the store is the one layer this plugin can write back to, and an
+ * environment export belongs to whoever started DSH, not to this computer's
+ * stored setup. The environment-wins rule is the service's own
+ * (`resolve().source` is `'env'` whenever the inherited environment has the name,
+ * and a write is refused while it does), so a name that is both exported and
+ * stored is read as an export and left here; unsetting it in the shell is what
+ * makes the stored value the one in force, and the one that travels.
+ *
+ * A name with no stored value is skipped, not reported: plenty of profiles name a
+ * provider nobody has signed in to, and "this key is not here either" is not a
+ * failure of the sync. A name that cannot be resolved *at all* is different, and
+ * is reported — a store that cannot be read must not look like a store with
+ * nothing in it, or a sync would read it as "this computer has no keys".
+ */
+export declare function readKeys(port: KeysPort | undefined, parts: Partial<Record<Part, unknown>>): Promise<KeysRead>;
+/**
+ * Put the merged keys part into this computer's store, and report what would not
+ * go in.
+ *
+ * A value already in force here is left alone. That is not an optimisation: the
+ * service refuses a write while a read-only layer shadows the reference, and a
+ * value that is already the one in force — the same key, exported and stored —
+ * would be reported as a failure for saying so twice.
+ *
+ * `beforeWrite` is called at most once, just before the first value that really
+ * replaces something. A credential has no copy kept by the caller any other way,
+ * so it is the callback's job to seal one: overwriting a key without keeping the
+ * value it had would leave undo with nothing to put back.
+ *
+ * `null` — the merge's way of saying the part was taken away — writes nothing. No
+ * credential is ever removed by a sync.
+ */
+export declare function applyKeys(port: KeysPort | undefined, part: KeysPart | null | undefined, beforeWrite?: () => Promise<void>): Promise<KeyProblem[]>;

package/lib/keys.js

@@ -0,0 +1,168 @@
+/**
+ * The `keys` part: the API keys this computer stores for the providers its
+ * profile names, and putting back the ones a merge brings.
+ *
+ * A DSH profile never holds a key. It holds the *name* of one — `apiKeyEnv` on a
+ * provider route, `secretEnv` on a webhook — and DSH resolves that name through
+ * its credential service, which layers the launch environment over this
+ * computer's own store (`$DSH_HOME/.credentials.yaml`). So a synced setup travels
+ * complete and still cannot reach a single provider: the names arrive, and on the
+ * other computer they resolve to nothing. That is the whole of this part.
+ *
+ * Two things follow from where the values live, and they are the two rules of
+ * this module:
+ *
+ * - The names come from the synced configuration, not from the store. The
+ *   credential service has no way to enumerate references — a configuration
+ *   surface learns which ones exist from its own schema — so this plugin reads the
+ *   names out of the very parts it is about to send, and asks the service for each
+ *   one. That also keeps the two in step for free: a key travels exactly when the
+ *   part that names it travels.
+ * - Nothing here deletes. A key removed on one computer stays on the others, and a
+ *   key that cannot be written is reported rather than skipped silently. See
+ *   `docs/decisions/0054-sync-api-keys.md`.
+ */
+import { message } from './store.js';
+/**
+ * The configuration field names DSH resolves as a credential reference.
+ *
+ * Taken from the schemas the shipped plugins declare: `apiKeyEnv` on the
+ * `llm-pi-ai` provider routes, on `llm-deepseek-api-key` and on
+ * `web-search-deepseek`; `secretEnv` on `webhook-github`. A plugin outside this
+ * list names its credential some other way and its key does not travel — which is
+ * why the list is here, in one place, rather than inline.
+ */
+export const CREDENTIAL_FIELDS = ['apiKeyEnv', 'secretEnv'];
+/**
+ * The credential service in the shape this plugin uses it.
+ *
+ * `set` rejects while a read-only layer shadows the reference, which is exactly
+ * the fact that matters here: a value that would not take effect is not one to
+ * report as stored. {@link applyKeys} therefore asks first and writes second.
+ */
+export function keysPort(service) {
+    return {
+        resolve: (ref) => service.resolve(ref),
+        store: (ref, value) => service.set(ref, value),
+    };
+}
+/**
+ * Every credential-reference name the given parts name, deduplicated and sorted.
+ *
+ * Walks the parts as they are — no schema, no interpretation — because the value
+ * of a reference field is a name wherever it sits, and the shape of a provider
+ * config is the provider plugin's to decide, not this one's.
+ */
+export function credentialRefs(parts) {
+    const found = new Set();
+    for (const part of Object.values(parts))
+        walk(part, found);
+    return [...found].sort();
+}
+function walk(value, into) {
+    if (value === null || typeof value !== 'object')
+        return;
+    if (Array.isArray(value)) {
+        for (const item of value)
+            walk(item, into);
+        return;
+    }
+    for (const [key, held] of Object.entries(value)) {
+        if (CREDENTIAL_FIELDS.includes(key)) {
+            const ref = typeof held === 'string' ? held.trim() : '';
+            if (ref !== '')
+                into.add(ref);
+            continue;
+        }
+        walk(held, into);
+    }
+}
+/**
+ * Read the keys this computer holds for the names in hand.
+ *
+ * Only the managed store travels: a name the launching environment supplies is
+ * left out, and so is one that falls through to a `.env`. Two reasons, and they
+ * agree — the store is the one layer this plugin can write back to, and an
+ * environment export belongs to whoever started DSH, not to this computer's
+ * stored setup. The environment-wins rule is the service's own
+ * (`resolve().source` is `'env'` whenever the inherited environment has the name,
+ * and a write is refused while it does), so a name that is both exported and
+ * stored is read as an export and left here; unsetting it in the shell is what
+ * makes the stored value the one in force, and the one that travels.
+ *
+ * A name with no stored value is skipped, not reported: plenty of profiles name a
+ * provider nobody has signed in to, and "this key is not here either" is not a
+ * failure of the sync. A name that cannot be resolved *at all* is different, and
+ * is reported — a store that cannot be read must not look like a store with
+ * nothing in it, or a sync would read it as "this computer has no keys".
+ */
+export async function readKeys(port, parts) {
+    const refs = credentialRefs(parts);
+    if (refs.length === 0)
+        return { problems: [] };
+    if (port === undefined)
+        return { problems: [{ ref: '', message: NO_SERVICE }] };
+    const found = {};
+    const problems = [];
+    for (const ref of refs) {
+        try {
+            const resolved = await port.resolve(ref);
+            if (resolved !== undefined && resolved.source === 'file' && resolved.value !== '')
+                found[ref] = resolved.value;
+        }
+        catch (cause) {
+            problems.push({ ref, message: message(cause) });
+        }
+    }
+    if (Object.keys(found).length === 0)
+        return { problems };
+    return { part: { refs: found }, problems };
+}
+/**
+ * Put the merged keys part into this computer's store, and report what would not
+ * go in.
+ *
+ * A value already in force here is left alone. That is not an optimisation: the
+ * service refuses a write while a read-only layer shadows the reference, and a
+ * value that is already the one in force — the same key, exported and stored —
+ * would be reported as a failure for saying so twice.
+ *
+ * `beforeWrite` is called at most once, just before the first value that really
+ * replaces something. A credential has no copy kept by the caller any other way,
+ * so it is the callback's job to seal one: overwriting a key without keeping the
+ * value it had would leave undo with nothing to put back.
+ *
+ * `null` — the merge's way of saying the part was taken away — writes nothing. No
+ * credential is ever removed by a sync.
+ */
+export async function applyKeys(port, part, beforeWrite = async () => undefined) {
+    if (part === null || part === undefined)
+        return [];
+    const entries = Object.entries(part.refs ?? {}).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    if (entries.length === 0)
+        return [];
+    if (port === undefined)
+        return [{ ref: '', message: NO_SERVICE }];
+    const problems = [];
+    let kept = false;
+    for (const [ref, value] of entries) {
+        if (typeof value !== 'string' || value === '')
+            continue;
+        try {
+            const current = await port.resolve(ref);
+            if (current !== undefined && current.value === value)
+                continue;
+            if (!kept) {
+                kept = true;
+                await beforeWrite();
+            }
+            await port.store(ref, value);
+        }
+        catch (cause) {
+            problems.push({ ref, message: message(cause) });
+        }
+    }
+    return problems;
+}
+/** Said whenever the host has no credential service to read or write at all. */
+const NO_SERVICE = '这台电脑没有 DSH 的凭据服务，API 密钥不在这里读写';