@wilm-ai/wilma-cli 2.4.0 → 2.5.0

package/README.md

@@ -14,7 +14,7 @@ pnpm add -g @wilm-ai/wilma-cli
 ```bash
 wilma login
 ```
-Opens a one-time login page in your browser: pick your school's Wilma and log in. The login is saved to `~/.config/wilmai/config.json`.
+Opens a one-time login page in your browser: pick your school's Wilma and log in. The login is saved to `~/.config/wilmai/config.json` (the password can go to the keychain instead: see Config).
 
 Without a browser: `wilma login --tenant <url|city> --username <name>` with the password in `WILMA_PASSWORD` or piped via `--password-stdin`. Or set `WILMA_TENANT`, `WILMA_USERNAME`, `WILMA_PASSWORD` (and `WILMA_TOTP_SECRET`) and skip the saved login.
 
@@ -79,6 +79,7 @@ wilma find-school <city or school>
 ## Other
 ```bash
 wilma update                       # when a newer version is out, a command says so on stderr, at most once a day (WILMAI_NO_UPDATE_CHECK=1 turns it off)
+wilma config secrets               # where saved passwords are kept; `wilma config secrets auto` moves them to the keychain
 wilma config clear                 # deletes every saved login and session
 wilma home                         # where to download WilmAI Home, the Wilma app for Mac and Windows
 wilma --version
@@ -95,6 +96,22 @@ If your Wilma account has MFA/TOTP enabled:
 ## Config
 Logins are saved in `~/.config/wilmai/config.json` (or `$XDG_CONFIG_HOME/wilmai/config.json`; override with `WILMAI_CONFIG_PATH`) and the current Wilma sessions in `wilmai-sessions.json` next to it, both readable only by you. `wilma logout` ends the sessions and deletes them, keeping the logins; `wilma config clear` deletes both.
 
+### Passwords in the keychain (optional)
+By default the password and authenticator key are in that file too, scrambled (not encrypted), like aws, npm or kubectl keep theirs. To keep them in the operating system's keychain instead:
+
+```bash
+wilma config secrets auto       # the keychain where there is one, the file where there isn't
+wilma config secrets keychain   # the keychain only; saving fails where there is none
+wilma config secrets file       # back to the file
+wilma config secrets            # where each login's password is now
+```
+
+The file stays the default, and stays available: on a server or anything unattended (cron, CI, an agent such as OpenClaw) there's no logged-in user to unlock a keychain, so keep the file there (`auto` does that by itself). Changing the setting moves the saved logins without logging in again. The keychain is the macOS Keychain (through `/usr/bin/security`, so no prompts after a Node.js upgrade), Windows Credential Manager, or a Linux desktop's Secret Service (headless Linux has none: `auto` keeps the file there). `WILMAI_SECRET_STORE=file|auto|keychain` decides where new logins go for one process, for tools that run the CLI; it never moves saved logins.
+
+What stays in files: the rest of the login (Wilma, username, children) and the current Wilma sessions, which give the same access as the password while they last (Wilma ends them after a few hours). The keychain keeps the password out of backups, synced dotfiles and anything that reads files; it doesn't protect against a program running as you, which can ask the keychain too. On Windows, saved credentials roam with a roaming profile. Older copies of the config (backups, synced dotfiles) still hold the password; changing the Wilma password makes them useless. A keychain entry left behind by a config deleted by hand is named `ai.wilm.wilma-cli` in Keychain Access or Credential Manager.
+
+Errors: `secret_missing` (the entry is gone: `wilma login`), `secret_refused` (the keychain is locked or said no), `secret_unavailable` (no keychain this copy can use), all with exit code 4. The Linux binaries of the optional `@napi-rs/keyring` dependency statically link libdbus (`AFL-2.1 OR GPL-2.0-or-later`).
+
 ## Troubleshooting: TLS errors on a managed laptop
 
 A TLS certificate error means the network is intercepting TLS and re-signing with a
@@ -125,6 +142,6 @@ In JSON, transport failures have the code `network`, with the underlying `cause`
 ```
 
 ## Notes
-- Credentials and TOTP secrets are stored with lightweight obfuscation (not encryption) in a file only your user can read.
+- Credentials and TOTP secrets are stored with lightweight obfuscation (not encryption) in a file only your user can read, or in the OS keychain with `wilma config secrets auto` (see Config).
 - Bulletin links are fetched only from public websites (never local or private network addresses), without your Wilma login.
 - Commands cover every child; `--student <number|name>` narrows to one.

package/dist/access.d.ts

@@ -1,6 +1,7 @@
+import type { StudentInfo, WilmaClient } from "@wilm-ai/wilma-client";
 import { WilmaAccess } from "./agent-data.js";
 import { type StoredProfile } from "./config.js";
-import { type ActiveAccount } from "./credentials.js";
+import { type ActiveAccount, type StoreChoice } from "./credentials.js";
 /**
  * Wilma access for the saved (or environment) logins — the same for CLI
  * commands and the local MCP server. Refreshed child lists are written back
@@ -25,11 +26,14 @@ export declare function logoutAccounts(accounts: ActiveAccount[]): Promise<{
     }[];
     hint: string;
 }>;
-export type RemovedSession = {
+export type RemovedSession = ({
     session: "ended" | "none";
 } | {
     session: "not_ended";
     message: string;
+}) & {
+    /** Its keychain entry couldn't be deleted (it stays recorded, so `wilma config clear` can try again). */
+    keychainEntryLeft?: string;
 };
 /**
  * Remove a saved login (`wilma accounts remove`, the login page's Remove) and
@@ -42,3 +46,20 @@ export declare function removeLogin(id: string): Promise<{
 } & RemovedSession>;
 /** Which of a login's children aren't read (unticked on the login page); only children the login lists count. */
 export declare function setHiddenChildren(id: string, hidden: string[]): Promise<void>;
+/**
+ * After Wilma accepted a login: save it where `choice` (chooseSecretStore,
+ * decided before contacting Wilma) says, and only then keep the verified
+ * session, under the saved login's keys, so the next command or tool call
+ * needs no second login (or code). A login that couldn't be saved leaves no
+ * session behind.
+ */
+export declare function saveVerifiedLogin(input: {
+    tenantUrl: string;
+    tenantName?: string | null;
+    username: string;
+    password: string;
+    totpSecret?: string | null;
+    students: StudentInfo[];
+}, client: WilmaClient, choice: StoreChoice): Promise<StoredProfile & {
+    note?: string;
+}>;

package/dist/access.js

@@ -1,6 +1,32 @@
-import { WilmaAccess, WilmaAiError, forgetSession, logoutSession } from "./agent-data.js";
-import { loadConfig, revealSecret, saveConfig, savedStudent } from "./config.js";
-import { mfaCallbackFor } from "./credentials.js";
+import { WilmaAccess, WilmaAiError, adoptSession, forgetSession, logoutSession } from "./agent-data.js";
+import { editConfig, loadConfig, saveConfig, savedStudent } from "./config.js";
+import { accountFor, mfaCallbackFor, saveLogin } from "./credentials.js";
+import { deleteLoginSecrets } from "./secret-store.js";
+/**
+ * Codes from the saved authenticator key. A keychain login's key comes from
+ * the same single read as its password (no second keychain access), and one
+ * code generator serves the whole process, so a rejected code waits for the
+ * next one instead of repeating it.
+ */
+function mfaFor(account) {
+    if (!account.secrets)
+        return mfaCallbackFor(account.totpSecret);
+    if (!account.hasTotp)
+        return undefined;
+    const read = account.secrets;
+    let generator = null;
+    return async (formkey) => {
+        const pending = (generator ??= read().then((secrets) => mfaCallbackFor(secrets.totpSecret)));
+        pending.catch(() => {
+            if (generator === pending)
+                generator = null;
+        });
+        const callback = await pending;
+        if (!callback)
+            throw new WilmaAiError("mfa_required", "Wilma asks for a two-step verification code, and no authenticator key is saved for this login. Run `wilma login`.");
+        return callback(formkey);
+    };
+}
 /**
  * Wilma access for the saved (or environment) logins — the same for CLI
  * commands and the local MCP server. Refreshed child lists are written back
@@ -10,8 +36,10 @@ import { mfaCallbackFor } from "./credentials.js";
 export function createAccess(accounts, opts = {}) {
     return new WilmaAccess(accounts.map((account, index) => ({
         profile: { ...account.profile, debug: opts.debug ?? account.profile.debug },
+        password: account.secrets ? async () => (await account.secrets()).password : undefined,
+        keys: account.keys,
         // A --totp-secret given on the command line belongs to the first (active) login.
-        mfa: mfaCallbackFor(index === 0 && opts.totpSecret ? opts.totpSecret : account.totpSecret),
+        mfa: index === 0 && opts.totpSecret ? mfaCallbackFor(opts.totpSecret) : mfaFor(account),
         label: account.stored?.tenantName ?? account.profile.baseUrl,
         knownStudents: account.stored?.students,
         hidden: account.stored?.hidden,
@@ -38,7 +66,7 @@ export function createAccess(accounts, opts = {}) {
  * (different Wilmas don't affect each other), then throws the first failure.
  */
 export async function logoutAccounts(accounts) {
-    const results = await Promise.allSettled(accounts.map((account) => logoutSession(account.profile)));
+    const results = await Promise.allSettled(accounts.map((account) => logoutSession(account.profile, account.keys)));
     const failed = results.find((result) => result.status === "rejected");
     if (failed)
         throw failed.reason;
@@ -69,19 +97,33 @@ export async function removeLogin(id) {
     config.profiles = config.profiles.filter((p) => p.id !== id);
     if (config.lastProfileId === id)
         config.lastProfileId = config.profiles[0]?.id ?? null;
+    const entry = removed.secretId ?? config.keychainLogins?.[id];
     await saveConfig(config);
-    return { removed, ...(await endSession(removed)) };
+    // The session first (it needs no password), then the keychain entry; its record goes only once it's deleted.
+    const session = await endSession(removed);
+    if (!entry)
+        return { removed, ...session };
+    try {
+        await deleteLoginSecrets(entry);
+    }
+    catch (err) {
+        return { removed, ...session, keychainEntryLeft: err instanceof Error ? err.message : String(err) };
+    }
+    await editConfig((fresh) => {
+        if (fresh.keychainLogins?.[id] !== entry)
+            return false;
+        const { [id]: _gone, ...rest } = fresh.keychainLogins;
+        fresh.keychainLogins = rest;
+    });
+    return { removed, ...session };
 }
 async function endSession(removed) {
-    const password = revealSecret(removed.passwordObfuscated);
-    if (!password)
-        return { session: "none" };
-    const profile = { baseUrl: removed.tenantUrl, username: removed.username, password };
+    const { profile, keys } = accountFor(removed);
     try {
-        return { session: (await logoutSession(profile)) ? "ended" : "none" };
+        return { session: (await logoutSession(profile, keys)) ? "ended" : "none" };
     }
     catch (err) {
-        await forgetSession(profile);
+        await forgetSession(profile, keys);
         return { session: "not_ended", message: err instanceof Error ? err.message : String(err) };
     }
 }
@@ -99,3 +141,15 @@ export async function setHiddenChildren(id, hidden) {
         delete target.hidden;
     await saveConfig(config);
 }
+/**
+ * After Wilma accepted a login: save it where `choice` (chooseSecretStore,
+ * decided before contacting Wilma) says, and only then keep the verified
+ * session, under the saved login's keys, so the next command or tool call
+ * needs no second login (or code). A login that couldn't be saved leaves no
+ * session behind.
+ */
+export async function saveVerifiedLogin(input, client, choice) {
+    const stored = await saveLogin(await loadConfig(), input, choice);
+    adoptSession(accountFor(stored).keys, client);
+    return stored;
+}

package/dist/agent-data.d.ts

@@ -1,5 +1,6 @@
 import { WilmaClient, type LessonNote, type Message, type MessageFolder, type MfaCallback, type NewsItem, type NewsResource, type OverviewData, type ScheduleLesson, type StudentInfo, type WilmaProfile } from "@wilm-ai/wilma-client";
 import type { SessionStore } from "./session-store.js";
+import { type SessionKeys } from "./session-keys.js";
 /**
  * An error with a stable code for agents and scripts (the CLI's JSON errors
  * and exit codes use it): e.g. "unknown_student", "invalid_argument".
@@ -46,7 +47,12 @@ export type StudentRef = {
 };
 /** One Wilma login. A family can have several (children on different Wilmas). */
 export interface AccessAccount {
+    /** For a keychain login the password is empty here and `password` gives it. */
     profile: WilmaProfile;
+    /** The password when Wilma needs a new login (a keychain read), never while a saved session works. */
+    password?: () => Promise<string>;
+    /** Where its session is saved and pooled; by default today's key (address, username and password). */
+    keys?: SessionKeys;
     mfa?: MfaCallback;
     /** The Wilma's name, shown to tell children apart when there are several logins. */
     label?: string | null;
@@ -84,26 +90,29 @@ export declare function useSessionStore(store: SessionStore | undefined): void;
 /**
  * Keep a session that is already logged in — e.g. the one the login page just
  * verified — so the first tool call needs no second login (and, with two-step
- * verification, no second code).
+ * verification, no second code). `keys` are the saved login's (v2 for a
+ * keychain login); without them, today's keys from the profile.
  */
-export declare function adoptSession(profile: WilmaProfile, client: WilmaClient): void;
+export declare function adoptSession(profileOrKeys: WilmaProfile | SessionKeys, client: WilmaClient): void;
 /**
  * Finish saving sessions (call before a short-lived process exits). Only
  * logins made here are saved, never an older session over a newer one
  * another process saved meanwhile.
  */
 export declare function flushSessions(): Promise<void>;
+/** Drop this process's client for a login (after its secrets moved, so the next use starts from its new keys). */
+export declare function dropPooledSession(keys: SessionKeys): void;
 /**
  * End WilmAI's Wilma session for one login (Wilma's own "Log out") and forget
  * it, in this process and in the session store, so nothing continues it. The
  * login itself stays saved; the next command or tool call logs in again.
- * Never logs in. Returns true when a live session was ended, false when there
- * was none. If Wilma can't be reached, throws and keeps the saved session, so
- * logging out can be tried again.
+ * Never logs in (so it needs no password). Returns true when a live session
+ * was ended, false when there was none. If Wilma can't be reached, throws and
+ * keeps the saved session, so logging out can be tried again.
  */
-export declare function logoutSession(profile: WilmaProfile): Promise<boolean>;
+export declare function logoutSession(profile: WilmaProfile, keys?: SessionKeys): Promise<boolean>;
 /** Forget one login's session without ending it in Wilma (when the login itself is removed). */
-export declare function forgetSession(profile: WilmaProfile): Promise<void>;
+export declare function forgetSession(profile: WilmaProfile, keys?: SessionKeys): Promise<void>;
 /**
  * Read-only Wilma access for agent tools (MCP). Covers every Wilma login the
  * family has saved; every method defaults to all children, and a student

package/dist/agent-data.js

@@ -1,6 +1,6 @@
 import { NetworkError, WilmaClient, addExamTimes, } from "@wilm-ai/wilma-client";
-import { createHash } from "node:crypto";
 import { fileNameFromResponse, readResponseCapped } from "./downloads.js";
+import { fileLoginKeys } from "./session-keys.js";
 /**
  * An error with a stable code for agents and scripts (the CLI's JSON errors
  * and exit codes use it): e.g. "unknown_student", "invalid_argument".
@@ -304,39 +304,59 @@ export function useSessionStore(store) {
  * in only when that one has ended too. Each login ends the others, so this
  * keeps WilmAI's programs from logging each other out.
  */
-function rememberSession(key, client, opts) {
+function rememberSession(keys, client, opts) {
     const store = sessionStore;
     if (!store)
         return;
     const save = (state) => {
-        const saving = store.save(key, state).catch(() => { });
+        const saving = saveUnder(store, keys, state).catch(() => { });
         pendingSaves.add(saving);
         void saving.finally(() => pendingSaves.delete(saving));
         return saving;
     };
-    client.useSharedSession({ load: () => store.load(key), save });
+    client.useSharedSession({ load: () => loadNewest(store, keys), save });
     // A resumed session is already saved (and another process may have saved a newer one since).
     if (opts.fresh)
         void save(client.exportSession());
 }
+/** A login's session under any of its labels, the newest (a store without that falls back to the first found). */
+async function loadNewest(store, keys) {
+    if (store.loadNewest)
+        return store.loadNewest(keys);
+    for (const key of keys) {
+        const state = await store.load(key);
+        if (state)
+            return state;
+    }
+    return null;
+}
+async function saveUnder(store, keys, state) {
+    if (store.saveAll)
+        return store.saveAll(keys, state);
+    for (const key of keys)
+        await store.save(key, state);
+}
+async function removeUnder(store, keys) {
+    if (store.removeAll)
+        return store.removeAll(keys);
+    for (const key of keys)
+        await store.remove(key);
+}
 const pendingSaves = new Set();
-/** Identifies one Wilma account and password (a changed password starts fresh). */
-function poolKey(profile) {
-    const { baseUrl, username, password } = profile;
-    // The password is part of the key, so a changed password starts a fresh session.
-    return createHash("sha256")
-        .update(`${baseUrl.replace(/\/$/, "")}\n${username.toLowerCase()}\n${password}`)
-        .digest("hex");
+/** The keys of a login known by its password (file and environment logins): both labels, v1 in the pool. */
+function defaultKeys(profile) {
+    return fileLoginKeys(profile.baseUrl, profile.username, profile.password);
 }
 /**
  * Keep a session that is already logged in — e.g. the one the login page just
  * verified — so the first tool call needs no second login (and, with two-step
- * verification, no second code).
+ * verification, no second code). `keys` are the saved login's (v2 for a
+ * keychain login); without them, today's keys from the profile.
  */
-export function adoptSession(profile, client) {
-    const key = poolKey(profile);
-    pool.set(key, { client: Promise.resolve(client), lastUsed: Date.now() });
-    rememberSession(key, client, { fresh: true });
+export function adoptSession(profileOrKeys, client) {
+    const keys = "sessionKeys" in profileOrKeys ? profileOrKeys : defaultKeys(profileOrKeys);
+    pool.set(keys.poolKey, { client: Promise.resolve(client), lastUsed: Date.now() });
+    rememberSession(keys.sessionKeys, client, { fresh: true });
 }
 /**
  * Finish saving sessions (call before a short-lived process exits). Only
@@ -348,38 +368,42 @@ export async function flushSessions() {
         await entry.client.catch(() => null);
     await Promise.all([...pendingSaves]);
 }
+/** Drop this process's client for a login (after its secrets moved, so the next use starts from its new keys). */
+export function dropPooledSession(keys) {
+    pool.delete(keys.poolKey);
+}
 /**
  * End WilmAI's Wilma session for one login (Wilma's own "Log out") and forget
  * it, in this process and in the session store, so nothing continues it. The
  * login itself stays saved; the next command or tool call logs in again.
- * Never logs in. Returns true when a live session was ended, false when there
- * was none. If Wilma can't be reached, throws and keeps the saved session, so
- * logging out can be tried again.
+ * Never logs in (so it needs no password). Returns true when a live session
+ * was ended, false when there was none. If Wilma can't be reached, throws and
+ * keeps the saved session, so logging out can be tried again.
  */
-export async function logoutSession(profile) {
-    const key = poolKey(profile);
-    const entry = pool.get(key);
+export async function logoutSession(profile, keys = defaultKeys(profile)) {
+    const entry = pool.get(keys.poolKey);
     // The session in use here (a login in progress finishes first) and the saved
     // one, which another process may have replaced since. At most one is live.
     const pooled = entry ? await entry.client.catch(() => null) : null;
     const pooledState = pooled?.exportSession();
-    const saved = sessionStore ? await sessionStore.load(key).catch(() => null) : null;
+    const saved = sessionStore ? await loadNewest(sessionStore, keys.sessionKeys).catch(() => null) : null;
     let ended = pooled ? await pooled.logout() : false;
-    if (pool.get(key) === entry)
-        pool.delete(key);
+    if (pool.get(keys.poolKey) === entry)
+        pool.delete(keys.poolKey);
     if (saved && saved !== pooledState) {
         const resumed = WilmaClient.resume({ ...profile, studentNumber: null }, saved);
         if (resumed && (await resumed.logout()))
             ended = true;
     }
-    await sessionStore?.remove(key);
+    if (sessionStore)
+        await removeUnder(sessionStore, keys.sessionKeys);
     return ended;
 }
 /** Forget one login's session without ending it in Wilma (when the login itself is removed). */
-export async function forgetSession(profile) {
-    const key = poolKey(profile);
-    pool.delete(key);
-    await sessionStore?.remove(key);
+export async function forgetSession(profile, keys = defaultKeys(profile)) {
+    pool.delete(keys.poolKey);
+    if (sessionStore)
+        await removeUnder(sessionStore, keys.sessionKeys);
 }
 function pooledSession(account) {
     const now = Date.now();
@@ -387,24 +411,26 @@ function pooledSession(account) {
         if (now - entry.lastUsed > POOL_IDLE_MS)
             pool.delete(key);
     }
-    const key = poolKey(account.profile);
-    let entry = pool.get(key);
+    const keys = account.keys ?? defaultKeys(account.profile);
+    let entry = pool.get(keys.poolKey);
     if (!entry) {
         const profile = { ...account.profile, studentNumber: null };
+        const lazy = account.password;
         const client = (async () => {
-            // A saved session first; it logs in again by itself if Wilma has ended it.
-            const saved = sessionStore ? await sessionStore.load(key).catch(() => null) : null;
-            const resumed = saved ? WilmaClient.resume(profile, saved, account.mfa) : null;
-            const client = resumed ?? (await WilmaClient.login(profile, account.mfa));
-            rememberSession(key, client, { fresh: !resumed });
+            // A saved session first; it logs in again by itself if Wilma has ended it
+            // (reading a keychain login's password only then).
+            const saved = sessionStore ? await loadNewest(sessionStore, keys.sessionKeys).catch(() => null) : null;
+            const resumed = saved ? WilmaClient.resume({ ...profile, password: lazy ?? profile.password }, saved, account.mfa) : null;
+            const client = resumed ?? (await WilmaClient.login({ ...profile, password: lazy ? await lazy() : profile.password }, account.mfa));
+            rememberSession(keys.sessionKeys, client, { fresh: !resumed });
             return client;
         })();
         const created = { client, lastUsed: now };
         entry = created;
-        pool.set(key, created);
+        pool.set(keys.poolKey, created);
         client.catch(() => {
-            if (pool.get(key) === created)
-                pool.delete(key);
+            if (pool.get(keys.poolKey) === created)
+                pool.delete(keys.poolKey);
         });
     }
     entry.lastUsed = now;

package/dist/cli-args.js

@@ -230,9 +230,17 @@ export function parseCliArgs(argv) {
         case "logout":
             return parsed(null, args);
         case "config":
-            if (args[0] !== "clear" || args.length > 1)
-                throw usage('Expected "wilma config clear".');
-            return parsed("clear");
+            if (args[0] === "clear" && args.length === 1)
+                return parsed("clear");
+            if (args[0] === "secrets") {
+                const [, setting, ...extra] = args;
+                noMore(extra);
+                if (setting !== undefined && !["file", "auto", "keychain"].includes(setting)) {
+                    throw usage('Expected "wilma config secrets [file|auto|keychain]".');
+                }
+                return parsed("secrets", setting === undefined ? [] : [setting]);
+            }
+            throw usage('Expected "wilma config clear" or "wilma config secrets [file|auto|keychain]".');
         case "find-school":
             if (!args.length)
                 throw usage('Expected "wilma find-school <city or school>".');

package/dist/cli-help.js

@@ -104,7 +104,12 @@ const COMMAND_HELP = {
         examples: ["npx -y @wilm-ai/wilma-cli@2 mcp"],
     },
     update: { usage: ["wilma update"], about: "Update the CLI with npm.", examples: ["wilma update"] },
-    config: { usage: ["wilma config clear"], about: "Delete every saved login and session on this computer.", examples: ["wilma config clear"] },
+    config: {
+        usage: ["wilma config clear", "wilma config secrets [file|auto|keychain]"],
+        about: "`clear` deletes every saved login and session on this computer (and their keychain entries). `secrets` shows where saved passwords are kept, or changes it: `file` (the default, WilmAI's own file readable only by you), `keychain` (the macOS Keychain, Windows Credential Manager or a Linux desktop's Secret Service; refuses to save anywhere else) or `auto` (the keychain where there is one, the file where there isn't). Changing it moves the saved logins without logging in again. WILMAI_SECRET_STORE sets where new logins go for one process.",
+        examples: ["wilma config secrets", "wilma config secrets auto", "wilma config secrets file", "wilma config clear"],
+        output: "secrets: { setting, envOverride, keychain: { kind, usable, problem }, logins: [{ wilma, username, store: \"file\" | \"keychain\", hasTotp }], moved? }",
+    },
 };
 const OVERVIEW = [
     ["summary", "daily briefing for every child (start here)"],

package/dist/config.d.ts

@@ -3,8 +3,19 @@ export interface StoredProfile {
     tenantUrl: string;
     tenantName?: string | null;
     username: string;
-    passwordObfuscated: string;
+    /** Scrambled password: a login kept in this file (absent for a keychain login). */
+    passwordObfuscated?: string;
     totpSecretObfuscated?: string | null;
+    /** "keychain": the password and authenticator key are in the OS keychain, entry `secretId`. Absent: in this file. */
+    secrets?: "keychain" | string;
+    /** The login's keychain entry (random; also kept in CliConfig.keychainLogins). */
+    secretId?: string;
+    /** Random, new whenever the login's secrets change; not secret. Part of a keychain login's pool key. */
+    credentialsStamp?: string;
+    /** Whether an authenticator key is saved (so listings don't read the keychain). */
+    hasTotp?: boolean;
+    /** When moving the login to the keychain last failed (background moves wait a day). */
+    moveFailedAt?: string;
     /** The children the login lists; `role` says whose login it is for each (a guardian's, or the student's own). */
     students?: SavedStudent[];
     /** Student numbers of children unticked on the login page (a profile Wilma lists twice): not read. */
@@ -23,10 +34,22 @@ export declare function savedStudent(s: SavedStudent): SavedStudent;
 export interface CliConfig {
     profiles: StoredProfile[];
     lastProfileId?: string | null;
+    /** Where new secrets go: "file" (default), "auto" or "keychain" (`wilma config secrets`). */
+    secretStore?: string;
+    /** Every keychain entry this config made, by login id, written before the entry itself. */
+    keychainLogins?: Record<string, string>;
 }
 export declare function getConfigPath(): string;
 export declare function loadConfig(): Promise<CliConfig>;
 export declare function saveConfig(config: CliConfig): Promise<void>;
+/**
+ * Change the saved config from a fresh read, so a save never overwrites what
+ * another process wrote meanwhile (moves, logins, refreshed child lists).
+ * `edit` returns false to leave the file as it is.
+ */
+export declare function editConfig(edit: (config: CliConfig) => boolean | void | Promise<boolean | void>): Promise<CliConfig>;
+/** The config as far as it can be read, or null (for `wilma config clear`, the way out of a damaged file). */
+export declare function loadConfigLenient(): Promise<CliConfig | null>;
 export declare function clearConfig(): Promise<void>;
 export declare function obfuscateSecret(value: string): string;
-export declare function revealSecret(value: string): string | null;
+export declare function revealSecret(value: string | null | undefined): string | null;

package/dist/config.js

@@ -89,6 +89,26 @@ export async function saveConfig(config) {
     await writeFile(tmp, JSON.stringify(config, null, 2) + "\n", { encoding: "utf-8", mode: 0o600 });
     await rename(tmp, path);
 }
+/**
+ * Change the saved config from a fresh read, so a save never overwrites what
+ * another process wrote meanwhile (moves, logins, refreshed child lists).
+ * `edit` returns false to leave the file as it is.
+ */
+export async function editConfig(edit) {
+    const config = await loadConfig();
+    if ((await edit(config)) !== false)
+        await saveConfig(config);
+    return config;
+}
+/** The config as far as it can be read, or null (for `wilma config clear`, the way out of a damaged file). */
+export async function loadConfigLenient() {
+    try {
+        return await loadConfig();
+    }
+    catch {
+        return null;
+    }
+}
 export async function clearConfig() {
     const path = getConfigPath();
     await rm(path, { force: true });
@@ -97,6 +117,8 @@ export function obfuscateSecret(value) {
     return Buffer.from(SALT + value, "utf-8").toString("base64");
 }
 export function revealSecret(value) {
+    if (!value)
+        return null;
     try {
         const decoded = Buffer.from(value, "base64").toString("utf-8");
         if (!decoded.startsWith(SALT)) {