flipstream 0.5.0 → 0.6.1

package/dist/lib/store/keychain-child.js

@@ -0,0 +1,135 @@
+// ONE keychain operation, in a process of its own, printed as JSON on stdout.
+//
+// This exists because a macOS keychain call can park in mach_msg forever (#119):
+// when securityd wants an authorization prompt that no GUI session can show (an
+// SSH shell, a locked console), the call never returns. Nothing inside a Node
+// process can recover from that — an AbortSignal does not interrupt a syscall
+// already in flight, worker.terminate() cannot unwind a thread blocked in the
+// kernel, and even process.exit() and process.reallyExit() hang, because Node's
+// shutdown joins its libuv workers and the wedged one never finishes. All three
+// were measured doing exactly that.
+//
+// A separate PROCESS is the one thing that can be killed. So the parent spawns
+// this, waits with a deadline, and SIGKILLs it if the deadline wins — the wedged
+// thread dies with the child, and the CLI stays free to report the failure and
+// exit with its own code.
+//
+// STDIN IS ALSO THE PARENT'S HEARTBEAT. The request arrives as one line and the
+// parent then holds the pipe open rather than closing it, so losing that pipe
+// means the parent is gone. A wedged helper whose CLI was killed would otherwise
+// be reparented and block forever, and cancelling a slow command repeatedly
+// would quietly accumulate immortal processes — the exact containment failure
+// the subprocess was introduced to prevent. Self-terminating on disconnect
+// covers every way a parent can die, including SIGKILL, which no parent-side
+// signal handler could catch.
+//
+// Nothing is passed as a command-line argument: those are readable by any `ps`
+// on the machine, which would expose the secret on a write and the account name
+// on every read.
+import { AsyncEntry } from '@napi-rs/keyring';
+import { writeSync } from 'node:fs';
+// fs.writeSync rather than process.stdout.write: this is the one place a store
+// module writes to a pipe, and a synchronous write cannot be truncated by the
+// process exiting underneath it.
+function emit(result) {
+    writeSync(1, `${JSON.stringify(result)}\n`);
+}
+// SIGKILL on ourselves rather than process.exit(): if a keychain call is already
+// wedged in the kernel, Node's own shutdown would join its libuv worker and hang
+// exactly like the parent did. Only the signal is certain.
+function dieWithParent() {
+    process.kill(process.pid, 'SIGKILL');
+}
+// ONE liveness handler, installed before anything else and never conditional.
+//
+// An earlier version had two sets — one that ignored EOF while reading the
+// request, and an unconditional pair installed after the request resolved. The
+// gap between them was a real hole: a parent that died immediately after writing
+// the request could deliver EOF into the handoff, have it ignored by the first
+// set and missed by the second, and leave a wedged helper with nothing left to
+// kill it. That is precisely the orphan this design exists to prevent, so the
+// handler is now unconditional for the whole life of the process.
+process.stdin.on('end', dieWithParent);
+process.stdin.on('close', dieWithParent);
+// The first line on stdin. The pipe stays OPEN afterwards, still serving as the
+// heartbeat above.
+function readRequestLine() {
+    return new Promise((resolve, reject) => {
+        // Already gone before we got started — nothing will ever arrive.
+        if (process.stdin.readableEnded) {
+            dieWithParent();
+            return;
+        }
+        let buffered = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => {
+            buffered += chunk;
+            const newline = buffered.indexOf('\n');
+            if (newline !== -1)
+                resolve(buffered.slice(0, newline));
+        });
+        process.stdin.on('error', reject);
+    });
+}
+// Narrow the request at the boundary — the repo's rule for anything parsed, even
+// when the only writer is our own parent.
+function parseRequest(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    const record = parsed;
+    const { account, op, secret, service } = record;
+    if (op !== 'delete' && op !== 'get' && op !== 'set')
+        return undefined;
+    if (typeof service !== 'string' || typeof account !== 'string')
+        return undefined;
+    if (secret !== undefined && typeof secret !== 'string')
+        return undefined;
+    return { account, op, secret, service };
+}
+async function main() {
+    const request = parseRequest(await readRequestLine());
+    if (request === undefined) {
+        emit({ error: 'the keychain helper got no readable request', ok: false });
+        return;
+    }
+    const entry = new AsyncEntry(request.service, request.account);
+    try {
+        switch (request.op) {
+            case 'delete': {
+                await entry.deletePassword();
+                emit({ ok: true, value: null });
+                return;
+            }
+            case 'get': {
+                const value = await entry.getPassword();
+                emit({ ok: true, value: value ?? null });
+                return;
+            }
+            case 'set': {
+                await entry.setPassword(request.secret ?? '');
+                emit({ ok: true, value: null });
+            }
+        }
+    }
+    catch (error) {
+        // The message is the keychain's own ("No matching entry found…"), which the
+        // parent needs verbatim to tell "empty" apart from "unusable". It never
+        // contains the secret — that is the value we did not get.
+        emit({ error: error instanceof Error ? error.message : String(error), ok: false });
+    }
+}
+await main();
+// Explicit, because stdin is deliberately still open as the parent's heartbeat
+// and its listeners would otherwise keep this process alive forever — the answer
+// would be written and the parent would still wait for a close that never came.
+// Safe to exit here: the result left through a synchronous write, and the
+// keychain call is already finished, so there is no libuv worker left to join.
+// eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- the heartbeat pipe keeps the loop alive
+process.exit(0);

package/dist/lib/store/keyring.d.ts

@@ -1,16 +1,33 @@
+import { TimeoutError } from '../errors.js';
 import { type Credentials } from './credentials.js';
+import { type KeychainChildRequest } from './keychain-child.js';
 export declare const KEYRING_SERVICE = "io.flipstream.cli";
+export declare const KEYCHAIN_TIMEOUT_MS = 5000;
+export declare const KEYCHAIN_DEFAULT_TIMEOUT_MS = 30000;
+export declare const KEYCHAIN_INTERACTIVE_TIMEOUT_MS = 120000;
+export declare const KEYCHAIN_NOTICE_AFTER_MS = 10000;
+export declare const KEYCHAIN_TIMEOUT_ENV = "FLIPSTREAM_KEYCHAIN_TIMEOUT_MS";
+export declare const KEYCHAIN_INTERACTIVE_ENV = "FLIPSTREAM_KEYCHAIN_INTERACTIVE";
+export declare const KEYCHAIN_MAX_TIMEOUT_MS = 2147483647;
 export interface TokenStore {
-    accessTokenIfFresh(host: string): null | string;
-    available(): boolean;
-    clear(host: string): void;
-    load(host: string): Credentials | null;
-    save(host: string, creds: Credentials): void;
+    accessTokenIfFresh(host: string): Promise<null | string>;
+    available(): Promise<boolean>;
+    clear(host: string): Promise<void>;
+    load(host: string): Promise<Credentials | null>;
+    reload(host: string): Promise<Credentials | null>;
+    save(host: string, creds: Credentials): Promise<void>;
 }
+export declare function keychainDeadlineMs(env?: NodeJS.ProcessEnv): number;
+export declare function keychainTimeout(operation: string, timeoutMs?: number): TimeoutError;
+export declare function withDeadline<T>(operation: string, run: (signal: AbortSignal) => Promise<T>, timeoutMs?: number): Promise<T>;
+export declare function spawnKeychain(request: KeychainChildRequest, signal: AbortSignal, scriptPath?: string): Promise<null | string>;
 export declare class KeyringStore implements TokenStore {
-    accessTokenIfFresh(host: string): null | string;
-    available(): boolean;
-    clear(host: string): void;
-    load(host: string): Credentials | null;
-    save(host: string, creds: Credentials): void;
+    #private;
+    constructor(scriptPath?: string);
+    accessTokenIfFresh(host: string): Promise<null | string>;
+    available(): Promise<boolean>;
+    clear(host: string): Promise<void>;
+    load(host: string): Promise<Credentials | null>;
+    reload(host: string): Promise<Credentials | null>;
+    save(host: string, creds: Credentials): Promise<void>;
 }

package/dist/lib/store/keyring.js

@@ -1,45 +1,316 @@
-import { Entry } from '@napi-rs/keyring';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { TimeoutError } from '../errors.js';
+import { isCI } from '../output/interactivity.js';
+import { isMachineMode } from '../output/machine-mode.js';
 import { freshAccessToken, keyOf, parseCredentials } from './credentials.js';
 // FROZEN. Tokens are stored in the OS keychain under this service id. Renaming
 // it strands users' tokens (silent logout + orphaned secrets), so any change
 // requires a one-time keyring-only migration (read old id -> write new id ->
 // delete old) — never a plaintext intermediary.
 export const KEYRING_SERVICE = 'io.flipstream.cli';
+// Why a keychain call needs a deadline AT ALL: on macOS it can park in mach_msg
+// forever, and nothing inside this process can recover from that. An AbortSignal
+// does not interrupt a syscall already in flight, and process.exit() and
+// process.reallyExit() both hang too, because Node's shutdown joins its libuv
+// workers and the wedged one never finishes. Hence keychain-child.ts: the work
+// runs in a process we can actually kill.
+//
+// How long to wait was argued over seven review rounds, and the useful outcome
+// was learning that the question cannot be answered by detection. Every signal
+// tried was wrong: stdio says nothing (SecurityAgent draws a GUI dialog, so a
+// desktop-launched CLI has pipes and an answerable prompt), SSH_* says nothing
+// (a tmux session started before an SSH login inherits none), and `launchctl
+// managername` says nothing either — the machine this was found on reported Aqua
+// with SSH_CONNECTION unset while its console sat unattended. Aqua proves a
+// screen exists, not that a person is in front of it. There is no evidence
+// available here that somebody is there to click.
+//
+// So the deadline is a judgement rather than a deduction, and it is split three
+// ways. An unattended machine should not sit for minutes, so the DEFAULT is
+// thirty seconds. Somebody who is there gets told at ten what is happening and
+// has twenty more to answer — and if they want longer they can say so, which is
+// the only statement about presence anybody can actually make. A caller that has
+// declared nothing can answer fails fastest of all.
+export const KEYCHAIN_TIMEOUT_MS = 5000;
+export const KEYCHAIN_DEFAULT_TIMEOUT_MS = 30_000;
+export const KEYCHAIN_INTERACTIVE_TIMEOUT_MS = 120_000;
+// How long a keychain call may take before we explain the wait on stderr.
+export const KEYCHAIN_NOTICE_AFTER_MS = 10_000;
+export const KEYCHAIN_TIMEOUT_ENV = 'FLIPSTREAM_KEYCHAIN_TIMEOUT_MS';
+export const KEYCHAIN_INTERACTIVE_ENV = 'FLIPSTREAM_KEYCHAIN_INTERACTIVE';
+// setTimeout's ceiling. A larger delay is silently clamped to ~1ms, which would
+// turn "wait longer" into "fail immediately" — the opposite of the request.
+export const KEYCHAIN_MAX_TIMEOUT_MS = 2_147_483_647;
+function isTruthy(value) {
+    return value !== undefined && value !== '' && value !== '0' && value !== 'false';
+}
+// How long to wait for the OS on THIS run. Every path is a stated fact — an
+// exact figure, a declared willingness to wait, or a declared inability to
+// answer — because nothing observable about the session is evidence either way.
+export function keychainDeadlineMs(env = process.env) {
+    const override = Number(env[KEYCHAIN_TIMEOUT_ENV]);
+    if (Number.isInteger(override) && override > 0 && override <= KEYCHAIN_MAX_TIMEOUT_MS)
+        return override;
+    if (isTruthy(env[KEYCHAIN_INTERACTIVE_ENV]))
+        return KEYCHAIN_INTERACTIVE_TIMEOUT_MS;
+    if (isCI(env) || isTruthy(env.FLIPSTREAM_NO_INPUT))
+        return KEYCHAIN_TIMEOUT_MS;
+    return KEYCHAIN_DEFAULT_TIMEOUT_MS;
+}
+// A keychain call that ran out of time — exit 8, like any other timeout.
+// DISTINCT from "no credentials" on purpose: reporting a stuck keychain as "not
+// logged in" sends a logged-in user to `auth login`, which needs the same
+// keychain and hangs in the same place.
+export function keychainTimeout(operation, timeoutMs = KEYCHAIN_DEFAULT_TIMEOUT_MS) {
+    return new TimeoutError(`The OS keychain did not respond within ${timeoutMs} ms (${operation}).`, 'keychain_timeout').withDetails({
+        hint: 'A keychain prompt was probably waiting with nobody at that machine to approve it — or the ' +
+            'session cannot show one at all (SSH, a locked console, an unattended box). Over SSH or any ' +
+            'other remote access, use a Flipstream service account from your Flipstream account rather ' +
+            'than an interactive login: it needs no browser and no keychain. Otherwise approve the dialog ' +
+            `on that machine and set ${KEYCHAIN_INTERACTIVE_ENV}=1 (or ${KEYCHAIN_TIMEOUT_ENV}=<ms>) to ` +
+            'allow time for it, or set FLIPSTREAM_NO_KEYRING=1 for an in-memory session that keeps nothing ' +
+            'between commands.',
+        retryable: true,
+    });
+}
+// Say something, once, when a keychain call is taking a human amount of time.
+// This is what stops a deadline long enough to be useful from looking like the
+// original hang: the complaint was never the seconds, it was the silence.
+//
+// SILENT IN MACHINE MODE. Under --json/--ndjson stderr must stay empty (the
+// agent contract, pinned by a test), and an agent has nobody to ask anyway.
+function announceWait() {
+    const timer = setTimeout(() => {
+        if (isMachineMode())
+            return;
+        process.stderr.write("→ Still waiting on the OS keychain. Are you filling in the keychain prompt? If there's " +
+            'nobody at that machine — SSH, or any other remote access — use a Flipstream service ' +
+            'account instead; it needs no browser and no keychain. Ctrl-C to stop waiting.\n');
+    }, KEYCHAIN_NOTICE_AFTER_MS);
+    // Never hold the process open for a notice that may never be due.
+    timer.unref?.();
+    return () => clearTimeout(timer);
+}
+// Run something under a wall-clock deadline, aborting the signal when the
+// deadline wins. Kept separate from the spawning below so the deadline itself is
+// testable without touching a real keychain.
+export async function withDeadline(operation, run, timeoutMs = keychainDeadlineMs()) {
+    const controller = new AbortController();
+    let timer;
+    const deadline = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            controller.abort();
+            reject(keychainTimeout(operation, timeoutMs));
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([run(controller.signal), deadline]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// This module's sibling child script, in whichever form is on disk: dist/*.js
+// for a published run, src/*.ts under the Bun dev entry. Derived from our OWN
+// url rather than guessed, so it cannot point at a build that is not there.
+function childScript() {
+    const self = import.meta.url;
+    return fileURLToPath(new URL(self.endsWith('.ts') ? './keychain-child.ts' : './keychain-child.js', self));
+}
+// Ask the child to do one operation, and KILL it if the deadline passes. SIGKILL
+// rather than SIGTERM: a process wedged in the kernel will not run a handler.
+//
+// The runtime is process.execPath, never a node_modules/.bin shim — a shim
+// encodes an assumption about the machine (a `node` on PATH), while this encodes
+// only what the repo already guarantees. `scriptPath` is injectable so the kill
+// path and the failure paths can be tested against helpers that misbehave on
+// purpose.
+export function spawnKeychain(request, signal, scriptPath = childScript()) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [scriptPath], { stdio: ['pipe', 'pipe', 'pipe'] });
+        signal.addEventListener('abort', () => child.kill('SIGKILL'), { once: true });
+        // One line, and then the pipe STAYS OPEN as the child's heartbeat: losing it
+        // is how the child learns this process died and kills itself, instead of
+        // being reparented and blocking forever. Closing it here would hand that
+        // guarantee away for nothing.
+        child.stdin.on('error', reject);
+        child.stdin.write(`${JSON.stringify(request)}\n`);
+        let out = '';
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => {
+            out += chunk;
+        });
+        child.on('error', reject);
+        child.on('close', () => {
+            // Killed by our own deadline: withDeadline's rejection is already on its
+            // way, so settling here would only race it.
+            if (signal.aborted)
+                return;
+            let parsed;
+            try {
+                parsed = JSON.parse(out.trim());
+            }
+            catch {
+                reject(new Error('the keychain helper returned no readable answer'));
+                return;
+            }
+            if (parsed.ok)
+                resolve(parsed.value ?? null);
+            // The child's message is the keychain's own wording, which the callers
+            // below match on to tell "empty" apart from "unusable".
+            else
+                reject(new Error(parsed.error ?? 'the keychain helper failed'));
+        });
+    });
+}
+async function keychain(call) {
+    const request = {
+        account: call.account,
+        op: call.op,
+        secret: call.secret,
+        service: KEYRING_SERVICE,
+    };
+    const done = announceWait();
+    try {
+        return await withDeadline(call.operation, (signal) => spawnKeychain(request, signal, call.scriptPath));
+    }
+    finally {
+        done();
+    }
+}
+// "Not found" is the keychain working and holding nothing — the ONLY failure
+// that means absence. A helper that could not spawn, crashed loading its native
+// binding, or answered with something unreadable has told us nothing about
+// whether a credential exists, and must never be read as "there isn't one".
+function isNotFound(error) {
+    return /not found|no (matching )?(entry|password|item)|could not be found/i.test(error.message);
+}
 // TokenStore backed by the OS keychain. The whole Credentials JSON is the single
 // secret per host (keyed by host).
+//
+// Reads are CACHED for the life of the process. Without this, one command touches
+// the keychain several times — the auth gate reads it, then every authed request
+// re-reads it through withFreshToken, and a paginated call re-reads it per page.
+// On macOS each read is a separate access, so a user who granted "Allow" rather
+// than "Always Allow" gets prompted once per read: two dialogs for `catalog`,
+// three for `query`, more for anything that paginates or resolves a name. Each
+// read is also a process now, so the cache saves spawns as well as dialogs.
+//
+// This costs nothing in EXPOSURE: the credentials are already in memory the moment
+// they are read — they have to be, to go in an Authorization header — so holding
+// them for the rest of a short-lived CLI process reveals nothing new. Nothing is
+// written to disk, and the cache dies with the process.
+//
+// It does cost COHERENCE, and that is worth stating plainly rather than glossing.
+// Another CLI process can log out or rotate tokens underneath us, and this cache
+// will not notice. Two consequences, handled differently:
+//
+//   Deleting someone else's session — handled. A failed refresh compare-and-deletes
+//   (see auth/refresh.ts): it re-reads past this cache and only clears when the
+//   stored token is still the one it tried. That race predates the cache; caching
+//   only widened the window.
+//
+//   Using a token after a concurrent `auth logout` — accepted. Logout REVOKES
+//   upstream, so a stale cached token gets a 401 from the server rather than data,
+//   surfacing as data_auth_failed. Re-reading before every request would fix it and
+//   would also undo the entire point of caching, for a case that already fails
+//   safely.
 export class KeyringStore {
-    accessTokenIfFresh(host) {
-        return freshAccessToken(this.load(host));
+    // `null` is cached too: "this host has no credentials" is an answer worth
+    // remembering, or a logged-out run re-reads on every check.
+    #cache = new Map();
+    // Injectable purely so the failure paths can be driven by a helper that
+    // misbehaves on purpose; production always uses the sibling script.
+    #scriptPath;
+    constructor(scriptPath) {
+        this.#scriptPath = scriptPath;
     }
-    available() {
+    async accessTokenIfFresh(host) {
+        return freshAccessToken(await this.load(host));
+    }
+    async available() {
         try {
-            new Entry(KEYRING_SERVICE, '__probe__').getPassword();
+            await keychain({
+                account: '__probe__',
+                op: 'get',
+                operation: 'probing the keychain',
+                scriptPath: this.#scriptPath,
+            });
             return true;
         }
         catch (error) {
+            // A wedged keychain is NOT an answer to "is one available" — it is the
+            // timeout this whole change exists to report. Returning false here sent
+            // `auth status` down its unavailable branch and out with exit 7 (network),
+            // for the one condition whose entire point is exit 8 and a message naming
+            // the prompt. It propagates.
+            if (error instanceof TimeoutError)
+                throw error;
             // "not found" means the keychain works but is empty (available); any other
             // failure (e.g. no Secret Service on headless Linux) means it is unavailable.
-            return /not found|no (matching )?(entry|password|item)|could not be found/i.test(error.message);
+            return isNotFound(error);
         }
     }
-    clear(host) {
+    async clear(host) {
         try {
-            new Entry(KEYRING_SERVICE, keyOf(host)).deletePassword();
+            await keychain({
+                account: keyOf(host),
+                op: 'delete',
+                operation: `clearing credentials for ${host}`,
+                scriptPath: this.#scriptPath,
+            });
         }
-        catch {
-            // Nothing stored for this host.
+        catch (error) {
+            // Only a verified "there was nothing to delete" counts as cleared. Anything
+            // else — a timeout, a helper that could not start, an unreadable answer —
+            // leaves the credential possibly intact, and logout must not report success
+            // over it.
+            if (!isNotFound(error))
+                throw error;
         }
+        // Cached only once the deletion is confirmed, so a failed clear cannot leave
+        // this process believing the session is gone.
+        this.#cache.set(host, null);
     }
-    load(host) {
+    async load(host) {
+        const cached = this.#cache.get(host);
+        if (cached !== undefined)
+            return cached;
+        return this.reload(host);
+    }
+    async reload(host) {
+        let creds = null;
         try {
-            const secret = new Entry(KEYRING_SERVICE, keyOf(host)).getPassword();
-            return secret ? parseCredentials(secret) : null;
+            const secret = await keychain({
+                account: keyOf(host),
+                op: 'get',
+                operation: `reading credentials for ${host}`,
+                scriptPath: this.#scriptPath,
+            });
+            creds = secret ? parseCredentials(secret) : null;
         }
-        catch {
-            return null;
+        catch (error) {
+            // Absence is the only thing we may infer. Every other failure propagates:
+            // "we could not read" reported as "nothing stored" turns a spawn failure
+            // into not_logged_in and sends a logged-in user to re-authenticate.
+            if (!isNotFound(error))
+                throw error;
+            creds = null;
         }
+        this.#cache.set(host, creds);
+        return creds;
     }
-    save(host, creds) {
-        new Entry(KEYRING_SERVICE, keyOf(host)).setPassword(JSON.stringify(creds));
+    async save(host, creds) {
+        await keychain({
+            account: keyOf(host),
+            op: 'set',
+            operation: `saving credentials for ${host}`,
+            scriptPath: this.#scriptPath,
+            secret: JSON.stringify(creds),
+        });
+        // Keep the cache authoritative: a refresh saves rotated tokens mid-command,
+        // and a later read must see them rather than the ones it started with.
+        this.#cache.set(host, creds);
     }
 }

package/dist/lib/store/memory-store.d.ts

@@ -2,9 +2,10 @@ import type { TokenStore } from './keyring.js';
 import { type Credentials } from './credentials.js';
 export declare class MemoryStore implements TokenStore {
     private readonly entries;
-    accessTokenIfFresh(host: string): null | string;
-    available(): boolean;
-    clear(host: string): void;
-    load(host: string): Credentials | null;
-    save(host: string, creds: Credentials): void;
+    accessTokenIfFresh(host: string): Promise<null | string>;
+    available(): Promise<boolean>;
+    clear(host: string): Promise<void>;
+    load(host: string): Promise<Credentials | null>;
+    reload(host: string): Promise<Credentials | null>;
+    save(host: string, creds: Credentials): Promise<void>;
 }

package/dist/lib/store/memory-store.js

@@ -3,19 +3,27 @@ import { freshAccessToken, keyOf } from './credentials.js';
 // Interchangeable with KeyringStore via the TokenStore interface.
 export class MemoryStore {
     entries = new Map();
-    accessTokenIfFresh(host) {
-        return freshAccessToken(this.load(host));
+    async accessTokenIfFresh(host) {
+        return freshAccessToken(await this.load(host));
     }
-    available() {
+    // Async to match TokenStore, which is async because a REAL keychain call has
+    // to be cancellable (see keyring.ts). Nothing here can block; the signature
+    // exists so tests drive the same call shape production does.
+    async available() {
         return true;
     }
-    clear(host) {
+    async clear(host) {
         this.entries.delete(keyOf(host));
     }
-    load(host) {
+    async load(host) {
         return this.entries.get(keyOf(host)) ?? null;
     }
-    save(host, creds) {
+    // No cache here, so a forced re-read is the same read. Present so the interface
+    // is honest and tests exercise the same call sites as the real store.
+    async reload(host) {
+        return this.load(host);
+    }
+    async save(host, creds) {
         this.entries.set(keyOf(host), creds);
     }
 }