@wilm-ai/wilma-cli 2.3.2 → 2.5.0

package/dist/secret-store.js

@@ -0,0 +1,487 @@
+/*
+ * Where saved Wilma passwords (and authenticator keys) are kept: in the config
+ * file, scrambled, as always (the default), or in the operating system's
+ * keychain when the user or a program turns that on (`wilma config secrets`,
+ * WILMAI_SECRET_STORE). See docs/secret-store.md.
+ *
+ * One keychain entry per login: service "ai.wilm.wilma-cli", account the
+ * login's random `secretId`, value JSON {password, totpSecret}.
+ *
+ * - macOS: through /usr/bin/security, in a child process with a hard
+ *   timeout. Items trust /usr/bin/security only (-T), so any node binary (a
+ *   Homebrew upgrade, Claude Desktop's own Node) and WilmAI Home read them
+ *   without macOS asking for the Mac password.
+ * - Windows and Linux: @napi-rs/keyring, an optional dependency loaded only
+ *   when needed (Credential Manager; the Secret Service, never the kernel
+ *   keyring, which is empty after a reboot).
+ */
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { access, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+export const KEYCHAIN_SERVICE = "ai.wilm.wilma-cli";
+export const SECRET_STORE_SETTINGS = ["file", "auto", "keychain"];
+/** How long one keychain call may take (a prompt waiting for a person counts as refused). WILMAI_KEYCHAIN_TIMEOUT_MS is a test hook. */
+const CALL_TIMEOUT_MS = Number(process.env.WILMAI_KEYCHAIN_TIMEOUT_MS) || 15_000;
+/** The macOS child process is killed after this. */
+const SECURITY_TIMEOUT_MS = 10_000;
+/** After a refusal, no new read for this long (so several children don't each show a prompt). */
+const REFUSED_PAUSE_MS = 60_000;
+/** A keychain entry couldn't be read, written or deleted; `reason` says what the user can do. */
+export class SecretStoreError extends Error {
+    reason;
+    constructor(reason, message, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = "SecretStoreError";
+        this.reason = reason;
+    }
+}
+/** The message a parent sees for each kind of failure (`wilma` names the Wilma when known). */
+export function secretErrorMessage(reason, wilma) {
+    switch (reason) {
+        case "missing":
+            return `The saved password for ${wilma ?? "this Wilma login"} isn't in the keychain any more. Log in again (\`wilma login\`).`;
+        case "refused":
+            return "The keychain on this computer didn't hand over WilmAI's saved Wilma password. If the computer is locked or asking for a password, unlock it, then try again.";
+        case "unavailable":
+            return "This login's password is saved in the keychain, which this copy of WilmAI can't open here. Update WilmAI, or log in again to save it where it can.";
+    }
+}
+function storeError(reason, detail, cause, wilma) {
+    const message = secretErrorMessage(reason, wilma) + (detail ? ` (${detail})` : "");
+    return new SecretStoreError(reason, message, cause);
+}
+/** The setting in effect: WILMAI_SECRET_STORE for this process, else the saved one, else the file. */
+export function effectiveSecretStore(saved, env = process.env) {
+    const fromEnv = env.WILMAI_SECRET_STORE?.trim();
+    if (fromEnv) {
+        if (SECRET_STORE_SETTINGS.includes(fromEnv))
+            return fromEnv;
+        throw new Error(`WILMAI_SECRET_STORE must be file, auto or keychain (it is "${fromEnv}").`);
+    }
+    return SECRET_STORE_SETTINGS.includes(saved ?? "") ? saved : "file";
+}
+export const newSecretId = () => randomBytes(16).toString("hex");
+export const newCredentialsStamp = () => randomBytes(8).toString("hex");
+const service = () => process.env.WILMAI_KEYCHAIN_SERVICE || KEYCHAIN_SERVICE; // a test hook
+/** A test hook: a keychain file to use on macOS instead of the default (login) keychain. */
+const keychainFile = () => (process.env.WILMAI_KEYCHAIN_PATH ? [process.env.WILMAI_KEYCHAIN_PATH] : []);
+function runSecurity(args, input = "") {
+    return new Promise((resolve) => {
+        let settled = false;
+        const done = (run) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(run);
+        };
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        const child = spawn("/usr/bin/security", args, { stdio: ["pipe", "pipe", "pipe"] });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGKILL");
+        }, SECURITY_TIMEOUT_MS);
+        child.stdout.setEncoding("utf8").on("data", (d) => (stdout += d));
+        child.stderr.setEncoding("utf8").on("data", (d) => (stderr += d));
+        child.on("error", (spawnError) => done({ code: null, stdout, stderr, spawnError, timedOut }));
+        child.on("close", (code) => done({ code, stdout, stderr, timedOut }));
+        child.stdin.on("error", () => { });
+        child.stdin.end(input);
+    });
+}
+/** A failed `security` run as a store error: not runnable = unavailable, anything else = refused. */
+function securityFailure(run, what) {
+    if (run.spawnError)
+        return storeError("unavailable", `${what}: ${run.spawnError.message}`, run.spawnError);
+    if (run.timedOut)
+        return storeError("refused", `${what}: no answer from the keychain in time`);
+    const detail = run.stderr.trim().split("\n").pop() || `exit ${run.code}`;
+    return storeError("refused", `${what}: ${detail}`);
+}
+const macosBackend = {
+    kind: "macos",
+    async check() {
+        if (process.platform !== "darwin" && !process.env.WILMAI_KEYCHAIN_BACKEND)
+            return "not macOS";
+        try {
+            await access("/usr/bin/security");
+            return null;
+        }
+        catch {
+            return "/usr/bin/security isn't there";
+        }
+    },
+    async get(account) {
+        const run = await runSecurity(["find-generic-password", "-s", service(), "-a", account, "-w", ...keychainFile()]);
+        if (run.code === 0)
+            return run.stdout.replace(/\n$/, "");
+        if (run.code === 44)
+            return null; // errSecItemNotFound
+        throw securityFailure(run, "reading");
+    },
+    async set(account, value) {
+        // Never change an item in place (-U): macOS asks for authorization to change an item's content, a dialog
+        // nobody answers in a background run, and the keychain refuses everything else until it's answered.
+        // Deleting and adding again asks nothing. (Parent Recap's ADR 0009 does the same.)
+        const removed = await runSecurity(["delete-generic-password", "-s", service(), "-a", account, ...keychainFile()]);
+        if (removed.code !== 0 && removed.code !== 44)
+            throw securityFailure(removed, "saving");
+        // The command goes in on stdin (never on a command line), the value as hex (nothing to quote).
+        const hex = Buffer.from(value, "utf8").toString("hex");
+        const target = keychainFile().map((path) => ` "${path}"`).join("");
+        const command = `add-generic-password -s ${service()} -a ${account} -l "WilmAI saved login" -T /usr/bin/security -X ${hex}${target}\n`;
+        const run = await runSecurity(["-i"], command);
+        if (run.code !== 0 || /returned -\d+/.test(run.stderr))
+            throw securityFailure(run, "saving");
+    },
+    async delete(account) {
+        const run = await runSecurity(["delete-generic-password", "-s", service(), "-a", account, ...keychainFile()]);
+        if (run.code === 0)
+            return true;
+        if (run.code === 44)
+            return false;
+        throw securityFailure(run, "deleting");
+    },
+};
+let keyringModule = null;
+function loadKeyring() {
+    // A name in a variable: bundlers leave the optional dependency out (it's loaded from node_modules when there).
+    const name = "@napi-rs/keyring";
+    keyringModule ??= import(name).then((mod) => (mod.AsyncEntry ? mod : (mod.default ?? null)), () => null);
+    return keyringModule;
+}
+async function keyringEntry(account) {
+    const mod = await loadKeyring();
+    if (!mod)
+        throw storeError("unavailable", "this copy of WilmAI was installed without keychain support");
+    try {
+        // Linux: the Secret Service only. The library would otherwise fall back to the kernel keyring, which forgets everything at a reboot.
+        return new mod.AsyncEntry(service(), account, process.platform === "linux" ? { linux: { store: "secret-service" } } : undefined);
+    }
+    catch (err) {
+        throw storeError("unavailable", err instanceof Error ? err.message : String(err), err);
+    }
+}
+/** Windows sessions without credentials (an SSH key login) and a missing store are "can't be used", the rest refused. */
+function keyringFailure(err, what) {
+    if (err instanceof SecretStoreError)
+        return err;
+    const message = err instanceof Error ? err.message : String(err);
+    // @napi-rs/keyring 2.1 says "Couldn't access platform storage: ..." when there is no store to use (no Secret
+    // Service, a Windows session without credentials); "Platform failure: ..." covers refusals and the rest.
+    const unusable = /couldn't access platform|platform secure storage|NoStorageAccess|no.such.logon.session|secret service|org\.freedesktop|dbus/i.test(message);
+    return storeError(unusable ? "unavailable" : "refused", `${what}: ${message}`, err);
+}
+const keyringBackend = {
+    kind: "keyring",
+    async check() {
+        if (!(await loadKeyring()))
+            return "installed without keychain support";
+        if (process.platform === "linux" && !process.env.DBUS_SESSION_BUS_ADDRESS)
+            return "no Secret Service here (no desktop session)";
+        try {
+            const entry = await keyringEntry(`probe-${process.pid}`);
+            await withTimeout(entry.getPassword(), CALL_TIMEOUT_MS, "checking");
+            return null;
+        }
+        catch (err) {
+            return keyringFailure(err, "checking").message;
+        }
+    },
+    async get(account) {
+        const entry = await keyringEntry(account);
+        try {
+            return (await entry.getPassword()) ?? null;
+        }
+        catch (err) {
+            throw keyringFailure(err, "reading");
+        }
+    },
+    async set(account, value) {
+        const entry = await keyringEntry(account);
+        try {
+            await entry.setPassword(value);
+        }
+        catch (err) {
+            throw keyringFailure(err, "saving");
+        }
+    },
+    async delete(account) {
+        const entry = await keyringEntry(account);
+        try {
+            return await entry.deletePassword();
+        }
+        catch (err) {
+            const failure = keyringFailure(err, "deleting");
+            if (/no (matching )?entry|not found/i.test(failure.message))
+                return false;
+            throw failure;
+        }
+    },
+};
+/**
+ * For tests: a keychain in a JSON file shared by processes,
+ * WILMAI_KEYCHAIN_BACKEND=fake:/path. `{"entries": {...}}`, plus `"check"`
+ * (why it can't be used), `"fail": {"get"|"set"|"delete": reason}` and
+ * `"hangMs"` to simulate a prompt nobody answers.
+ */
+function fakeBackend(path) {
+    const load = async () => {
+        try {
+            return JSON.parse(await readFile(path, "utf8"));
+        }
+        catch {
+            return {};
+        }
+    };
+    const save = async (fake) => {
+        await mkdir(dirname(path), { recursive: true });
+        const tmp = `${path}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+        await writeFile(tmp, JSON.stringify(fake, null, 2));
+        await rename(tmp, path);
+    };
+    const maybeFail = async (fake, op) => {
+        if (fake.hangMs)
+            await new Promise((r) => setTimeout(r, fake.hangMs));
+        const reason = fake.fail?.[op];
+        if (reason)
+            throw storeError(reason, `fake ${op}`);
+    };
+    return {
+        kind: "fake",
+        async check() {
+            return (await load()).check ?? null;
+        },
+        async get(account) {
+            const fake = await load();
+            await maybeFail(fake, "get");
+            return fake.entries?.[account] ?? null;
+        },
+        async set(account, value) {
+            const fake = await load();
+            await maybeFail(fake, "set");
+            await save({ ...fake, entries: { ...fake.entries, [account]: value } });
+        },
+        async delete(account) {
+            const fake = await load();
+            await maybeFail(fake, "delete");
+            if (!fake.entries || !(account in fake.entries))
+                return false;
+            delete fake.entries[account];
+            await save(fake);
+            return true;
+        },
+    };
+}
+function backend() {
+    const forced = process.env.WILMAI_KEYCHAIN_BACKEND; // a test hook
+    if (forced?.startsWith("fake:"))
+        return fakeBackend(forced.slice(5));
+    if (forced === "keyring")
+        return keyringBackend;
+    if (forced === "macos")
+        return macosBackend;
+    return process.platform === "darwin" ? macosBackend : keyringBackend;
+}
+/**
+ * Keychain calls that timed out but are still running. A native call can't be
+ * cancelled (Windows, Linux) and keeps the process alive, so a CLI command
+ * exits by itself once its output is written (abandonedKeychainCalls).
+ */
+let abandonedCalls = 0;
+function withTimeout(promise, ms, what) {
+    return new Promise((resolve, reject) => {
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            abandonedCalls += 1;
+            reject(storeError("refused", `${what}: no answer from the keychain in time`));
+        }, ms);
+        promise.then((value) => {
+            clearTimeout(timer);
+            if (timedOut)
+                abandonedCalls -= 1;
+            else
+                resolve(value);
+        }, (err) => {
+            clearTimeout(timer);
+            if (timedOut)
+                abandonedCalls -= 1;
+            else
+                reject(err);
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// Using it
+let checked = null;
+/** null when the keychain can be used here (checked once per process); otherwise why not. */
+export function keychainProblem() {
+    checked ??= backend()
+        .check()
+        .catch((err) => (err instanceof Error ? err.message : String(err)));
+    return checked;
+}
+/** Which keychain this process would use, for `wilma config secrets`. */
+export function keychainKind() {
+    const kind = backend().kind;
+    if (kind === "macos")
+        return "macOS Keychain";
+    if (kind === "fake")
+        return "test keychain";
+    return process.platform === "win32" ? "Windows Credential Manager" : process.platform === "darwin" ? "macOS Keychain" : "Secret Service";
+}
+/** JSON with everything past ASCII escaped, so every keychain hands it back unchanged. */
+function encode(secrets) {
+    return JSON.stringify({ password: secrets.password, totpSecret: secrets.totpSecret ?? null }).replace(/[\u007f-￿]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+function decode(raw, wilma) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.password === "string" && parsed.password) {
+            return { password: parsed.password, totpSecret: typeof parsed.totpSecret === "string" && parsed.totpSecret ? parsed.totpSecret : null };
+        }
+    }
+    catch {
+        // fall through
+    }
+    return storeErrorThrow("missing", "the keychain entry is damaged", wilma);
+}
+function storeErrorThrow(reason, detail, wilma) {
+    throw storeError(reason, detail, undefined, wilma);
+}
+const reads = new Map();
+/** A login's password and authenticator key from the keychain: read once per process, only when needed. */
+export function readLoginSecrets(ref) {
+    const key = `${ref.secretId}|${ref.credentialsStamp ?? ""}`;
+    let state = reads.get(key);
+    if (!state) {
+        state = {};
+        reads.set(key, state);
+    }
+    if (state.value)
+        return Promise.resolve(state.value);
+    if (state.pending)
+        return state.pending;
+    if (state.abandoned)
+        return Promise.reject(storeError("refused", "still waiting for the keychain to answer an earlier request"));
+    if (state.error && (state.error.reason !== "refused" || Date.now() < (state.retryAt ?? 0)))
+        return Promise.reject(state.error);
+    const s = state;
+    s.error = undefined;
+    const settle = (outcome) => {
+        if ("value" in outcome)
+            s.value = outcome.value;
+        else {
+            s.error = outcome.error;
+            s.retryAt = Date.now() + REFUSED_PAUSE_MS;
+        }
+    };
+    const call = (async () => {
+        let raw = await backend().get(ref.secretId);
+        if (raw === null) {
+            // Saving deletes the entry and adds it again (macOS): a read in between finds nothing for a moment
+            // (two short `security` runs). Well inside the call's own timeout.
+            await new Promise((r) => setTimeout(r, Math.min(150, CALL_TIMEOUT_MS / 4)));
+            raw = await backend().get(ref.secretId);
+        }
+        if (raw === null)
+            storeErrorThrow("missing", "no keychain entry", ref.wilma);
+        return decode(raw, ref.wilma);
+    })();
+    s.pending = new Promise((resolve, reject) => {
+        let answered = false;
+        const timer = setTimeout(() => {
+            if (answered)
+                return;
+            answered = true;
+            // The call can't be cancelled (Windows, Linux): wait for it, start no new one, keep a late value.
+            s.pending = undefined;
+            s.abandoned = true;
+            abandonedCalls += 1;
+            reject(storeError("refused", "no answer from the keychain in time"));
+        }, CALL_TIMEOUT_MS);
+        const late = () => {
+            s.abandoned = false;
+            abandonedCalls -= 1;
+        };
+        call.then((value) => {
+            settle({ value });
+            if (answered)
+                late();
+            else {
+                answered = true;
+                clearTimeout(timer);
+                s.pending = undefined;
+                resolve(value);
+            }
+        }, (err) => {
+            const error = keyringFailure(err, "reading");
+            settle({ error });
+            if (answered)
+                late();
+            else {
+                answered = true;
+                clearTimeout(timer);
+                s.pending = undefined;
+                reject(error);
+            }
+        });
+    });
+    return s.pending;
+}
+/** Save a login's secrets in its keychain entry (replacing what was there). */
+export async function writeLoginSecrets(secretId, secrets) {
+    try {
+        await withTimeout(backend().set(secretId, encode(secrets)), CALL_TIMEOUT_MS, "saving");
+    }
+    catch (err) {
+        throw keyringFailure(err, "saving");
+    }
+    forgetReads(secretId);
+}
+/** Forget what was read from an entry, except reads still waiting (they must stay counted). */
+function forgetReads(secretId) {
+    for (const [key, state] of [...reads])
+        if (key.startsWith(`${secretId}|`) && !state.pending && !state.abandoned)
+            reads.delete(key);
+}
+/**
+ * Read an entry straight from the keychain (no per-process memory), e.g. to
+ * check what was just written. A Windows read right after a write on another
+ * thread can briefly miss, so a miss is tried once more.
+ */
+export async function readBackLoginSecrets(secretId) {
+    for (let attempt = 0;; attempt++) {
+        const raw = await withTimeout(backend().get(secretId), CALL_TIMEOUT_MS, "reading").catch((err) => {
+            throw keyringFailure(err, "reading");
+        });
+        if (raw !== null)
+            return decode(raw);
+        if (attempt >= 1)
+            return null;
+        await new Promise((r) => setTimeout(r, 200));
+    }
+}
+/** Delete a login's keychain entry; true when there was one. */
+export async function deleteLoginSecrets(secretId) {
+    forgetReads(secretId);
+    try {
+        return await withTimeout(backend().delete(secretId), CALL_TIMEOUT_MS, "deleting");
+    }
+    catch (err) {
+        throw keyringFailure(err, "deleting");
+    }
+}
+/** Whether a keychain call timed out and may still be running (the process should then exit when done). */
+export function abandonedKeychainCalls() {
+    return abandonedCalls > 0;
+}
+/** For tests in one process: forget what was read. */
+export function forgetSecretReads() {
+    reads.clear();
+    checked = null;
+}

package/dist/session-keys.d.ts

@@ -0,0 +1,19 @@
+export declare function sessionKeyV1(baseUrl: string, username: string, password: string): string;
+export declare function sessionKeyV2(baseUrl: string, username: string): string;
+/**
+ * Where a login's session lives: the session-file keys it is saved under (all
+ * of them) and looked up under (the newest entry wins), and the key of its
+ * client in a process's pool.
+ *
+ * The labels overlap while v1 is retired (docs/secret-store.md, the plan):
+ * file and environment logins use v2 and v1, so programs that only know v1
+ * (CLI 2.4.0 and older, an old Claude Desktop extension, Home 0.3.1 and older)
+ * keep sharing their session; keychain logins use v2 only.
+ */
+export interface SessionKeys {
+    sessionKeys: string[];
+    /** In-memory only: v1 for a file login (a new password makes a new client), v2 plus the credentials stamp for a keychain login. */
+    poolKey: string;
+}
+export declare function fileLoginKeys(baseUrl: string, username: string, password: string): SessionKeys;
+export declare function keychainLoginKeys(baseUrl: string, username: string, credentialsStamp: string | null | undefined): SessionKeys;

package/dist/session-keys.js

@@ -0,0 +1,26 @@
+import { createHash } from "node:crypto";
+/*
+ * The key a login's session is saved under in wilmai-sessions.json, shared by
+ * the CLI, the MCP server and WilmAI Home (which computes the same keys).
+ *
+ * - v1, file and environment logins (as always): SHA-256 of the address,
+ *   username and password, so a changed password starts a fresh session.
+ * - v2, every login over time: SHA-256 of "wilmai-session-v2", the address
+ *   and the username. No password: the session is found without reading a
+ *   keychain, and the file holds nothing derived from the password.
+ */
+const address = (baseUrl) => baseUrl.replace(/\/$/, "");
+export function sessionKeyV1(baseUrl, username, password) {
+    return createHash("sha256").update(`${address(baseUrl)}\n${username.toLowerCase()}\n${password}`).digest("hex");
+}
+export function sessionKeyV2(baseUrl, username) {
+    return createHash("sha256").update(`wilmai-session-v2\n${address(baseUrl)}\n${username.toLowerCase()}`).digest("hex");
+}
+export function fileLoginKeys(baseUrl, username, password) {
+    const v1 = sessionKeyV1(baseUrl, username, password);
+    return { sessionKeys: [sessionKeyV2(baseUrl, username), v1], poolKey: v1 };
+}
+export function keychainLoginKeys(baseUrl, username, credentialsStamp) {
+    const v2 = sessionKeyV2(baseUrl, username);
+    return { sessionKeys: [v2], poolKey: `${v2}|${credentialsStamp ?? ""}` };
+}

package/dist/session-store.d.ts

@@ -3,10 +3,26 @@ export interface SessionStore {
     save(key: string, state: string): Promise<void>;
     /** Forget one session (after logging out). */
     remove(key: string): Promise<void>;
+    /** The newest session saved under any of these keys (one login's labels). */
+    loadNewest?(keys: string[]): Promise<string | null>;
+    /** Save one session under all of these keys, in one write. */
+    saveAll?(keys: string[], state: string): Promise<void>;
+    /** Forget a session under all of these keys, in one write. */
+    removeAll?(keys: string[]): Promise<void>;
 }
 /** Name this program in the sessions it saves (the MCP server says "mcp"). */
 export declare function nameSessionOwner(name: string): void;
 export declare const fileSessionStore: SessionStore;
+/**
+ * Make sure a login's newest session is under `to` too (moving a login
+ * between the file and the keychain), keeping when and by whom it was saved,
+ * and tag both entries with the login's id. With the labels overlapping, `to`
+ * usually has it already; an older program may have saved a newer one under
+ * `from` only. Nothing to copy (none, or expired): false.
+ */
+export declare function copySession(from: string, to: string, login: string): Promise<boolean>;
+/** Delete the entries tagged with a login's id except `keep` (what a move interrupted before its last step left). */
+export declare function removeTaggedSessions(login: string, keep: string): Promise<number>;
 /** When one login's session was saved, and by which program (null when there's none to try). */
 export declare function sessionInfo(key: string): Promise<{
     savedAt: number;

package/dist/session-store.js

@@ -61,6 +61,42 @@ export const fileSessionStore = {
         delete all[key];
         await writeAll(all);
     },
+    async loadNewest(keys) {
+        if (process.env.WILMAI_NO_SESSION_CACHE === "1")
+            return null;
+        const all = await readAll();
+        let newest = null;
+        for (const key of keys) {
+            const entry = all[key];
+            if (!entry || typeof entry.state !== "string" || Date.now() - entry.savedAt > SESSION_TTL_MS)
+                continue;
+            if (!newest || entry.savedAt > newest.savedAt)
+                newest = entry;
+        }
+        return newest?.state ?? null;
+    },
+    async saveAll(keys, state) {
+        if (process.env.WILMAI_NO_SESSION_CACHE === "1")
+            return;
+        const all = await readAll();
+        const now = Date.now();
+        for (const [k, entry] of Object.entries(all)) {
+            if (now - entry.savedAt > SESSION_TTL_MS)
+                delete all[k];
+        }
+        for (const key of keys)
+            all[key] = { state, savedAt: now, by: savedBy };
+        await writeAll(all);
+    },
+    async removeAll(keys) {
+        const all = await readAll();
+        const present = keys.filter((key) => key in all);
+        if (!present.length)
+            return;
+        for (const key of present)
+            delete all[key];
+        await writeAll(all);
+    },
 };
 async function writeAll(all) {
     const path = sessionsPath();
@@ -70,6 +106,39 @@ async function writeAll(all) {
     await writeFile(tmp, JSON.stringify(all), { encoding: "utf-8", mode: 0o600 });
     await rename(tmp, path);
 }
+/**
+ * Make sure a login's newest session is under `to` too (moving a login
+ * between the file and the keychain), keeping when and by whom it was saved,
+ * and tag both entries with the login's id. With the labels overlapping, `to`
+ * usually has it already; an older program may have saved a newer one under
+ * `from` only. Nothing to copy (none, or expired): false.
+ */
+export async function copySession(from, to, login) {
+    if (process.env.WILMAI_NO_SESSION_CACHE === "1")
+        return false;
+    const all = await readAll();
+    const valid = (entry) => entry && typeof entry.state === "string" && Date.now() - entry.savedAt <= SESSION_TTL_MS;
+    const source = all[from];
+    const target = all[to];
+    if (!valid(source))
+        return false;
+    const newest = valid(target) && target.savedAt >= source.savedAt ? target : source;
+    all[from] = { ...source, login };
+    all[to] = { ...newest, login };
+    await writeAll(all);
+    return true;
+}
+/** Delete the entries tagged with a login's id except `keep` (what a move interrupted before its last step left). */
+export async function removeTaggedSessions(login, keep) {
+    const all = await readAll();
+    const gone = Object.keys(all).filter((key) => key !== keep && all[key]?.login === login);
+    if (!gone.length)
+        return 0;
+    for (const key of gone)
+        delete all[key];
+    await writeAll(all);
+    return gone.length;
+}
 /** When one login's session was saved, and by which program (null when there's none to try). */
 export async function sessionInfo(key) {
     if (process.env.WILMAI_NO_SESSION_CACHE === "1")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wilm-ai/wilma-cli",
-  "version": "2.3.2",
+  "version": "2.5.0",
   "description": "Read your children's Wilma (Finnish school system) from the terminal or an AI assistant: schedule, homework, exams, messages and news. Students can use their own login too.",
   "mcpName": "ai.wilm/wilma",
   "license": "MIT",
@@ -22,16 +22,18 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "lint": "tsc -p tsconfig.json --noEmit",
-    "test": "pnpm --filter @wilm-ai/wilma-client build && pnpm run build && node test/news-resources.mjs && node test/mcp-login.mjs && node test/mfa.mjs && node test/logout.mjs && node test/shared-session.mjs && node test/audit.mjs && node test/update-notice.mjs && node test/registry.mjs",
+    "test": "pnpm --filter @wilm-ai/wilma-client build && pnpm run build && node test/news-resources.mjs && node test/mcp-login.mjs && node test/mfa.mjs && node test/logout.mjs && node test/shared-session.mjs && node test/secret-store.mjs && node test/audit.mjs && node test/family.mjs && node test/update-notice.mjs && node test/registry.mjs",
     "start": "node dist/index.js",
     "prepack": "pnpm --filter @wilm-ai/wilma-client build && pnpm --filter @wilm-ai/wilma-cli build",
     "test:live": "tsc -p tsconfig.json && node test/live.spec.mjs",
+    "test:keychain": "pnpm run build && node test/keychain-real.mjs --run",
+    "test:keychain:temp": "pnpm run build && node test/keychain-real.mjs --temp",
     "build:mcpb": "pnpm run build && node scripts/build-mcpb.mjs"
   },
   "dependencies": {
     "@inquirer/prompts": "^5.3.8",
     "@modelcontextprotocol/sdk": "^1.32.0",
-    "@wilm-ai/wilma-client": "^1.8.0",
+    "@wilm-ai/wilma-client": "^1.10.0",
     "zod": "^4.6.6"
   },
   "devDependencies": {
@@ -46,5 +48,8 @@
   ],
   "publishConfig": {
     "access": "public"
+  },
+  "optionalDependencies": {
+    "@napi-rs/keyring": "2.1.2"
   }
 }