dsh-webdav-sync 1.0.3 → 1.0.5

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,12 @@ async function syncOnce(engine, state, force) {
         }
         state.blind = undefined;
     }
-    const snapshot = await take(paths, config);
+    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
@@ -174,7 +180,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
@@ -184,6 +194,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.
@@ -205,10 +219,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;
@@ -217,7 +231,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,
@@ -326,11 +341,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), 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
@@ -350,6 +366,7 @@ async function syncOnce(engine, state, force) {
             ...(saved === undefined ? {} : { saved }),
             pushed: false,
             reloadNeeded: written.reloadNeeded,
+            ...keyProblems([...snapshot.keysProblems, ...written.keysProblems]),
             ...(await pendings(engine, applied.plugins)),
         };
     }
@@ -411,7 +428,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 +444,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,11 +571,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), 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
@@ -566,6 +594,7 @@ async function push(engine, state, snapshot, merged) {
         ...(merged.saved === undefined ? {} : { saved: merged.saved }),
         pushed: true,
         reloadNeeded: applied.reloadNeeded,
+        ...keyProblems([...snapshot.keysProblems, ...applied.keysProblems]),
         ...(await pendings(engine, merged.merged.plugins)),
     };
 }
@@ -608,13 +637,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 +663,53 @@ 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 };
+}
+/** 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.
+ *
+ * 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 +826,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 +856,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 +876,7 @@ export async function restore(engine) {
             ...(kept === undefined ? {} : { saved: keptDir(paths) }),
             pushed: false,
             reloadNeeded: written.reloadNeeded,
+            ...keyProblems([...snapshot.keysProblems, ...written.keysProblems]),
             ...(await pendings(engine, applied.plugins)),
         };
     });
@@ -842,7 +917,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 +951,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 +977,7 @@ export async function undo(engine) {
             there: [],
             pushed: false,
             reloadNeeded: written.reloadNeeded,
+            ...keyProblems([...snapshot.keysProblems, ...written.keysProblems]),
             ...(await pendings(engine, merged.plugins)),
         };
     });
@@ -922,7 +998,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 +1059,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 +1110,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 +1183,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 +1197,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 +1217,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 +1225,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 +1263,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
@@ -329,7 +348,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) {
@@ -349,7 +368,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 () => {
@@ -357,11 +376,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/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[]>;