@cspeach/cli 1.1.33 → 1.1.35

package/dist/auth/azure/sign-in.js

@@ -0,0 +1,219 @@
+/**
+ * Azure tenant mode — the Microsoft sign-in. Browser by default: our own
+ * loopback listener (loopback.ts) + MSAL's getAuthCodeUrl with PKCE +
+ * acquireTokenByCode. Device code behind --device-code (Conditional Access
+ * often blocks it, so it is the fallback). Five minutes, then a plain line.
+ * The listener is closed in a finally on success, error, timeout and abort
+ * (owner decision P5). Never called mid-turn.
+ *
+ * Never logged or printed: the authorization code, the PKCE verifier, the
+ * redirect query, tokens, Microsoft's error description. The authorize URL
+ * is printed only when the browser did not open (the person has to copy it).
+ */
+import { randomBytes } from 'node:crypto';
+import { formatAttention, formatFailure, formatInfo } from '../../renderer/notice-shape.js';
+import { sanitizeControlChars } from '../../renderer/sanitize.js';
+import { AZURE_FACTS, clientIdConfigured } from '../../connection/azure-facts.js';
+import { AzureSignInRequiredError, selectAzureAuth } from '../../connection/azure-auth.js';
+import { azureLog } from './azure-log.js';
+import { msalFor, entraForSelect, accountsForTenant } from './token-provider.js';
+import { startLoopback, LoopbackAuthError, LoopbackCancelledError, LoopbackPortError } from './loopback.js';
+import { tenantOf, AzureWrongTenantError } from './msal-client.js';
+export const SIGN_IN_TIMEOUT_MS = 300_000;
+const WRONG_DIRECTORY = { what: 'This Microsoft account belongs to a different company directory.', next: 'sign in with your work account: cspeach login azure' };
+function explain(text, deviceCode) {
+    if (/AADSTS65001|consent_required/i.test(text))
+        return { what: "Your company's admin has not approved CSPeach in Microsoft Entra yet.", next: 'ask IT to approve CSPeach (the IT guide has the link)' };
+    if (/AADSTS53003|AADSTS530003|AADSTS50097|AADSTS50158|access_denied/i.test(text)) {
+        return { what: "Your company's sign-in rules blocked this sign-in.", next: deviceCode ? 'cspeach login azure (opens your browser)' : 'ask IT which sign-in your company allows' };
+    }
+    if (/AADSTS50020|AADSTS90072/i.test(text))
+        return WRONG_DIRECTORY;
+    return { what: 'Microsoft sign-in failed.', next: 'cspeach login azure' };
+}
+/** Rejects with LoopbackCancelledError as soon as `signal` fires; the work itself is left to the caller to stop. */
+function untilStopped(work, signal) {
+    if (signal.aborted) {
+        work.catch(() => { });
+        return Promise.reject(new LoopbackCancelledError());
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(new LoopbackCancelledError());
+        signal.addEventListener('abort', onAbort, { once: true });
+        work.then((v) => { signal.removeEventListener('abort', onAbort); resolve(v); }, (e) => { signal.removeEventListener('abort', onAbort); reject(e); });
+    });
+}
+/**
+ * A token request still running when the sign-in stopped may finish later, and
+ * MSAL then caches it. The person cancelled, so an account that was NOT here
+ * before this sign-in is removed again. An account that was already signed in
+ * stays (its tokens were only renewed).
+ */
+function discardLate(app, work, before) {
+    work.then(async (r) => {
+        const a = r?.account;
+        if (a && !before.has(a.homeAccountId)) {
+            // Residual (ledger): MSAL has already written this token to the
+            // encrypted cache before removeAccount runs. A failed removal leaves
+            // that account cached on this machine, with one log line; the next
+            // successful sign-in for the company keeps only its own account
+            // (keepOnly), and `cspeach logout` deletes the cache.
+            // Its own catch: a failed removal is not "the late request failed".
+            try {
+                await app.removeAccount(a);
+                azureLog('sign-in: removed an account that finished after the sign-in was stopped');
+            }
+            catch {
+                azureLog('sign-in: could not remove an account that finished after the sign-in was stopped');
+            }
+        }
+    }).catch(() => { });
+}
+/** Runs the token request; a stop (timeout or abort) while it runs, or right after, never keeps a new account. */
+async function finishOrDiscard(app, work, before, signal) {
+    let r;
+    try {
+        r = await untilStopped(work, signal);
+    }
+    catch (e) {
+        if (e instanceof LoopbackCancelledError)
+            discardLate(app, work, before);
+        throw e;
+    }
+    if (signal.aborted) {
+        discardLate(app, work, before);
+        throw new LoopbackCancelledError();
+    }
+    return r;
+}
+async function accountIds(app, signal) {
+    return new Set((await untilStopped(app.getAllAccounts(), signal)).map((a) => a.homeAccountId));
+}
+async function browserSignIn(app, signal, deps) {
+    const scopes = [AZURE_FACTS.entraScope];
+    const before = await accountIds(app, signal);
+    const pkce = await untilStopped(app.generatePkceCodes(), signal);
+    const state = randomBytes(32).toString('base64url');
+    const listener = await (deps.loopback ?? startLoopback)({ state, signal });
+    try {
+        const url = await untilStopped(app.getAuthCodeUrl({ scopes, redirectUri: listener.redirectUri, codeChallenge: pkce.challenge, codeChallengeMethod: 'S256', state, responseMode: 'query' }), signal);
+        // Said here, just before the browser is asked to open: never when the
+        // sign-in refuses first (client id not recorded, no port) or uses a device code.
+        deps.print(formatInfo('Opening your browser to sign in to Microsoft').trimEnd());
+        await untilStopped(deps.open(url).catch(() => {
+            // The address goes on its OWN line, whole: never wrapped into a
+            // Next: row, never shortened (it is often 500+ characters).
+            deps.print(formatAttention({ text: "The browser didn't open", next: 'open the address below in your browser yourself' }).trimEnd());
+            deps.print(url);
+        }), signal);
+        const { code, clientInfo } = await listener.waitForCode();
+        const exchange = app.acquireTokenByCode({ scopes, redirectUri: listener.redirectUri, code, codeVerifier: pkce.verifier, ...(clientInfo ? { clientInfo } : {}) });
+        return await finishOrDiscard(app, exchange, before, signal);
+    }
+    finally {
+        await listener.close();
+    }
+}
+async function deviceCodeSignIn(app, signal, deps) {
+    const before = await accountIds(app, signal);
+    const request = {
+        scopes: [AZURE_FACTS.entraScope],
+        deviceCodeCallback: (i) => deps.print(formatInfo(sanitizeControlChars(i.message)).trimEnd()),
+    };
+    // MSAL stops polling when `cancel` turns true on this same object.
+    const stop = () => { request.cancel = true; };
+    signal.addEventListener('abort', stop, { once: true });
+    try {
+        return await finishOrDiscard(app, app.acquireTokenByDeviceCode(request), before, signal);
+    }
+    finally {
+        signal.removeEventListener('abort', stop);
+    }
+}
+/** After a good sign-in: other accounts for the same tenant would make every request ambiguous. */
+async function keepOnly(app, tenantId, keep) {
+    try {
+        for (const a of await accountsForTenant(app, tenantId))
+            if (a.homeAccountId !== keep)
+                await app.removeAccount(a);
+    }
+    catch {
+        azureLog('sign-in: could not remove an older account for this company');
+    }
+}
+export async function signInAzure(conn, opts, deps) {
+    if (!(deps.clientIdReady ?? clientIdConfigured)()) {
+        return { ok: false, what: 'Microsoft sign-in is not set up in this CSPeach build yet.', next: conn.sign_in.includes('key') ? 'ask IT for an Azure key, then cspeach config set llm.azure_key -' : 'contact us at info@cremencing.com' };
+    }
+    // One signal for both ways a sign-in stops: the five minutes, or the person.
+    const stopper = new AbortController();
+    const timer = setTimeout(() => stopper.abort(), deps.timeoutMs ?? SIGN_IN_TIMEOUT_MS);
+    timer.unref?.();
+    const onUserAbort = () => stopper.abort();
+    if (deps.signal?.aborted)
+        stopper.abort();
+    else
+        deps.signal?.addEventListener('abort', onUserAbort, { once: true });
+    const stopped = () => (deps.signal?.aborted
+        ? { ok: false, what: 'Microsoft sign-in was cancelled.', next: 'cspeach login azure' }
+        : { ok: false, what: 'Microsoft sign-in did not finish.', next: opts.deviceCode ? 'cspeach login azure' : 'cspeach login azure --device-code' });
+    try {
+        const app = await untilStopped((deps.msal ?? (() => msalFor(conn.entra_tenant_id)))(), stopper.signal);
+        const r = opts.deviceCode ? await deviceCodeSignIn(app, stopper.signal, deps) : await browserSignIn(app, stopper.signal, deps);
+        if (!r)
+            return { ok: false, what: 'Microsoft sign-in did not finish.', next: 'cspeach login azure' };
+        if (tenantOf(r) !== conn.entra_tenant_id.toLowerCase()) {
+            if (r.account)
+                await app.removeAccount(r.account).catch(() => { });
+            return { ok: false, ...WRONG_DIRECTORY };
+        }
+        if (r.account)
+            await keepOnly(app, conn.entra_tenant_id, r.account.homeAccountId);
+        return { ok: true, username: r.account?.username ?? 'your account', expiresOn: r.expiresOn };
+    }
+    catch (err) {
+        if (err instanceof LoopbackCancelledError) {
+            azureLog(deps.signal?.aborted ? 'sign-in cancelled by the person' : 'sign-in timed out');
+            return stopped();
+        }
+        if (err instanceof LoopbackPortError) {
+            azureLog('sign-in: no loopback port free on both addresses');
+            return { ok: false, what: 'Could not open a sign-in port on this computer.', next: 'try again, or use cspeach login azure --device-code' };
+        }
+        if (err instanceof LoopbackAuthError) {
+            // Microsoft's description is used to pick the plain line, never logged.
+            azureLog(`sign-in: Microsoft returned error ${err.errorCode}`);
+            return { ok: false, ...explain(`${err.errorCode} ${err.detail}`, opts.deviceCode) };
+        }
+        const e = err;
+        azureLog(`sign-in failed: ${e?.name ?? 'Error'}${e?.errorCode ? ` (${e.errorCode})` : ''}: ${e?.message ?? String(err)}`);
+        return { ok: false, ...explain(`${e?.errorCode ?? ''} ${e?.message ?? ''}`, opts.deviceCode) };
+    }
+    finally {
+        clearTimeout(timer);
+        deps.signal?.removeEventListener('abort', onUserAbort);
+    }
+}
+/** REPL start (asks first) and one-shot (never asks). */
+export async function ensureAzureSignIn(conn, o) {
+    const provider = await (o.select ?? ((c) => selectAzureAuth(c, { entra: entraForSelect })))(conn);
+    try {
+        await provider.getAuth();
+        return { ok: true };
+    }
+    catch (e) {
+        // A token from another directory: the same path as an ended sign-in (describeEntraSignIn says needs-sign-in too).
+        const wrongDirectory = e instanceof AzureWrongTenantError;
+        if (!wrongDirectory && !(e instanceof AzureSignInRequiredError)) {
+            o.print(formatInfo('Could not check your Microsoft sign-in just now · CSPeach will try again on the first request').trimEnd());
+            return { ok: true };
+        }
+        if (!wrongDirectory && e.method === 'key')
+            return { ok: false, message: formatFailure({ what: 'Your Azure key is not set on this machine.', next: 'ask IT for a current key, then cspeach config set llm.azure_key -' }) };
+        if (!o.interactive || !(await o.ask('Sign in to Microsoft now?'))) {
+            return { ok: false, message: formatFailure(wrongDirectory ? WRONG_DIRECTORY : { what: e.message, next: 'cspeach login azure' }) };
+        }
+        const r = await (o.signIn ?? signInAzure)(conn, { deviceCode: false }, { open: o.open, print: o.print, ...(o.signal ? { signal: o.signal } : {}) });
+        return r.ok ? { ok: true } : { ok: false, message: formatFailure({ what: r.what, next: r.next }) };
+    }
+}

package/dist/auth/azure/startup-sign-in.js

@@ -0,0 +1,64 @@
+/**
+ * Azure tenant mode, Task 6b — the Microsoft sign-in that starts with the
+ * REPL. The question comes first (inquirer owns the keyboard then); only
+ * while the sign-in itself runs does Esc or Ctrl+C stop it, through the
+ * SAME signal ensureAzureSignIn hands to signInAzure, so the loopback
+ * listener closes at once (owner decision: the listener is always closed).
+ * The keyboard is handed back exactly as it was found.
+ */
+import { ensureAzureSignIn, signInAzure } from './sign-in.js';
+import { askOrNo } from '../../repl/ask-or-no.js';
+const CTRL_C = 0x03;
+const ESC = 0x1b;
+/** Ctrl+C anywhere in the chunk, or a lone Esc (an arrow key is Esc + more bytes). */
+export function isStopKey(chunk) {
+    const b = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk;
+    return b.includes(CTRL_C) || (b.length === 1 && b[0] === ESC);
+}
+/** Aborts `ac` on Esc / Ctrl+C (raw TTY) or SIGINT until released. */
+export function armStopKeys(ac, input, signals) {
+    const stop = () => { if (!ac.signal.aborted)
+        ac.abort(); };
+    const onData = (chunk) => { if (isStopKey(chunk))
+        stop(); };
+    const raw = input.isTTY === true && typeof input.setRawMode === 'function';
+    const wasRaw = input.isRaw === true;
+    const wasFlowing = input.readableFlowing === true;
+    signals.on('SIGINT', stop);
+    if (raw) {
+        input.setRawMode(true);
+        input.on('data', onData);
+        input.resume();
+    }
+    return () => {
+        signals.removeListener('SIGINT', stop);
+        if (raw) {
+            input.removeListener('data', onData);
+            input.setRawMode(wasRaw);
+            // Hand the keyboard back as found: still flowing if something else was
+            // reading it, paused otherwise (readline / Ink resume it themselves).
+            if (!wasFlowing)
+                input.pause();
+        }
+    };
+}
+export async function azureSignInAtStart(conn, o) {
+    const ac = new AbortController();
+    const input = o.input ?? process.stdin;
+    const signals = o.signals ?? process;
+    const run = o.signIn ?? signInAzure;
+    return (o.ensure ?? ensureAzureSignIn)(conn, {
+        // Ctrl+C at the question (ExitPromptError) is a no.
+        interactive: true, ask: askOrNo(o.ask), print: o.print, open: o.open, signal: ac.signal,
+        // The keys are armed only while the sign-in runs, never during the question.
+        signIn: async (c, opts, deps) => {
+            const release = armStopKeys(ac, input, signals);
+            try {
+                return await run(c, opts, deps);
+            }
+            finally {
+                release();
+            }
+        },
+    });
+}

package/dist/auth/azure/token-provider.js

@@ -0,0 +1,116 @@
+/**
+ * Azure tenant mode — Entra tokens for the Foundry endpoint. Silent before
+ * EVERY request (MSAL serves the cached token, refreshing with the refresh
+ * token near expiry); a token with < 120 s left by this laptop's clock is
+ * force-refreshed (plan D12). Never interactive here: interaction required ⇒
+ * AzureSignInRequiredError ("Your Microsoft sign-in has ended."). A token
+ * from another tenant is refused. No token ever goes into an error or a log.
+ */
+import { AZURE_FACTS } from '../../connection/azure-facts.js';
+import { AzureSignInRequiredError } from '../../connection/azure-auth.js';
+import { cspeachRoot } from '../../config/paths.js';
+import { getAzureKey } from './azure-key.js';
+import { openCacheStore } from './cache-store.js';
+import { azureLog } from './azure-log.js';
+import { createMsal, isInteractionRequired, tenantOf, AzureWrongTenantError } from './msal-client.js';
+export const NEAR_EXPIRY_MS = 120_000;
+const apps = new Map();
+/** One MSAL client per CSPeach home and tenant per process, with that home's encrypted cache. */
+export function msalFor(tenantId, o = {}) {
+    const slot = `${cspeachRoot()}|${tenantId.toLowerCase()}`;
+    let p = apps.get(slot);
+    if (!p) {
+        p = (async () => {
+            const { plugin } = await (o.store ?? (() => openCacheStore({ notice: o.notice })))();
+            return (o.factory ?? createMsal)({ clientId: AZURE_FACTS.clientId, tenantId, cachePlugin: plugin, log: azureLog });
+        })();
+        apps.set(slot, p);
+        p.catch(() => apps.delete(slot));
+    }
+    return p;
+}
+const appFor = (conn, deps) => (deps.msal ?? (() => msalFor(conn.entra_tenant_id)))();
+/** Every cached account for this tenant (MSAL's raw objects). */
+export async function accountsForTenant(app, tenantId) {
+    const t = tenantId.toLowerCase();
+    return (await app.getAllAccounts()).filter((a) => (a.tenantId ?? '').toLowerCase() === t);
+}
+/** More than one account for the company's tenant: never guess which one. A fresh `cspeach login azure` keeps only the one signed in. */
+export class AzureSeveralAccountsError extends AzureSignInRequiredError {
+    constructor() {
+        super('entra');
+        this.message = 'More than one Microsoft account is signed in for your company on this computer.';
+        this.name = 'AzureSeveralAccountsError';
+    }
+}
+async function accountFor(app, tenantId) {
+    const found = await accountsForTenant(app, tenantId);
+    if (found.length > 1)
+        throw new AzureSeveralAccountsError();
+    return found[0] ?? null;
+}
+const scopes = () => [AZURE_FACTS.entraScope];
+async function silent(app, account, forceRefresh) {
+    try {
+        return await app.acquireTokenSilent({ scopes: scopes(), account, ...(forceRefresh ? { forceRefresh: true } : {}) });
+    }
+    catch (e) {
+        if (isInteractionRequired(e))
+            throw new AzureSignInRequiredError('entra');
+        throw e;
+    }
+}
+export function createEntraAuthProvider(conn, deps = {}) {
+    const now = deps.now ?? Date.now;
+    return {
+        method: 'entra',
+        async getAuth(opts = {}) {
+            const a = await appFor(conn, deps);
+            const account = await accountFor(a, conn.entra_tenant_id);
+            if (!account)
+                throw new AzureSignInRequiredError('entra');
+            let r = await silent(a, account, opts.forceRefresh === true);
+            if (!opts.forceRefresh && r.expiresOn && r.expiresOn.getTime() - now() < NEAR_EXPIRY_MS)
+                r = await silent(a, account, true);
+            if (tenantOf(r) !== conn.entra_tenant_id.toLowerCase())
+                throw new AzureWrongTenantError();
+            return { kind: 'entra', token: r.accessToken };
+        },
+    };
+}
+/**
+ * SelectAuthDeps.entra: Entra when this machine has an Entra account (or
+ * several) for the tenant; when it has none and the company allows keys and a key is stored,
+ * null (use the key); otherwise Entra (which asks for sign-in).
+ */
+export async function entraForSelect(conn, deps = {}) {
+    const provider = createEntraAuthProvider(conn, deps);
+    let hasAccount = false;
+    try {
+        hasAccount = (await accountsForTenant(await appFor(conn, deps), conn.entra_tenant_id)).length > 0;
+    }
+    catch {
+        hasAccount = false;
+    }
+    if (hasAccount)
+        return provider;
+    if (conn.sign_in.includes('key') && (await (deps.getKey ?? getAzureKey)().catch(() => null)))
+        return null;
+    return provider;
+}
+/** whoami / doctor: the account and token expiry, silently. */
+export async function describeEntraSignIn(conn, deps = {}) {
+    try {
+        const a = await appFor(conn, deps);
+        const account = await accountFor(a, conn.entra_tenant_id);
+        if (!account)
+            return { state: 'needs-sign-in' };
+        const r = await silent(a, account, false);
+        if (tenantOf(r) !== conn.entra_tenant_id.toLowerCase())
+            return { state: 'needs-sign-in' };
+        return { state: 'signed-in', username: account.username, expiresOn: r.expiresOn };
+    }
+    catch {
+        return { state: 'needs-sign-in' };
+    }
+}

package/dist/auth/key-resolver.js

@@ -0,0 +1,258 @@
+/**
+ * Security batch item 6 — the ONE CSPeach key resolver. Every reader (REPL
+ * requests, banner, whoami, logout, licence check, usage reporter) reaches it
+ * through getStore().get() (api-key.ts).
+ *
+ * Where the key lives:
+ *   - the OS credential store, service `cspeach`, one account per CSPeach
+ *     home: `api-key` for the default ~/.cspeach, `api-key:<12 hex of
+ *     sha256(home)>` for any other CSPEACH_HOME — two homes never share one;
+ *   - auth.json `apiKey` only where no credential store works, or where an
+ *     older CLI left it (moved at start: copy → read back → only then remove).
+ *
+ * When both hold DIFFERENT keys, the newer login wins:
+ *   - auth.json carries `savedAt` (this CLI wrote it while the store was
+ *     unavailable) newer than the last store write → auth.json;
+ *   - auth.json has no `savedAt` (an older CLI wrote it) → auth.json only when
+ *     key-store.json proves our store write came BEFORE the file changed;
+ *   - otherwise the credential store — the key REPL requests already used
+ *     before this batch (managed stays byte-identical) — plus one notice.
+ *
+ * key-store.json (beside auth.json) holds { account, storedAt, legacyChecked }:
+ * no secret.
+ */
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { cspeachRoot, defaultCspeachRoot } from '../config/paths.js';
+import { readAuthFile, writeAuthFile, deleteAuthFile, authFileMtimeMs, authFileDir } from './auth-file.js';
+import { licenceCachePath } from '../licence/paths.js';
+export const KEYCHAIN_SERVICE = 'cspeach';
+export const DEFAULT_ACCOUNT = 'api-key';
+async function defaultIo() {
+    const { default: keychain } = await import('./keychain.js');
+    return {
+        get: (a) => keychain.getPassword(KEYCHAIN_SERVICE, a),
+        set: (a, k) => keychain.setPassword(KEYCHAIN_SERVICE, a, k),
+        del: (a) => keychain.deletePassword(KEYCHAIN_SERVICE, a),
+    };
+}
+function normHome(p) {
+    const r = path.resolve(p).replace(/[\\/]+$/, '');
+    return process.platform === 'win32' ? r.toLowerCase() : r;
+}
+export function keychainAccountForHome(home = cspeachRoot(), defaultHome = defaultCspeachRoot()) {
+    const h = normHome(home);
+    if (h === normHome(defaultHome))
+        return DEFAULT_ACCOUNT;
+    return `${DEFAULT_ACCOUNT}:${crypto.createHash('sha256').update(h).digest('hex').slice(0, 12)}`;
+}
+const metaPath = () => path.join(authFileDir(), 'key-store.json');
+async function readMeta() {
+    try {
+        const m = JSON.parse(await fs.readFile(metaPath(), 'utf-8'));
+        if (typeof m.account !== 'string')
+            return null;
+        return { account: m.account, storedAt: typeof m.storedAt === 'string' ? m.storedAt : null, legacyChecked: m.legacyChecked === true };
+    }
+    catch {
+        return null;
+    }
+}
+async function writeMeta(m) {
+    const p = metaPath();
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    // Unique per write: two writes in one process must never share a temp file.
+    const tmp = `${p}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+    await fs.writeFile(tmp, JSON.stringify(m, null, 2), { encoding: 'utf-8', mode: 0o600 });
+    try {
+        await fs.rename(tmp, p);
+    }
+    finally {
+        await fs.rm(tmp, { force: true }).catch(() => { });
+    }
+}
+/** Note that this CLI just wrote the credential store (drives "newer login wins"). */
+export async function recordStoreWrite(account = keychainAccountForHome(), at = new Date().toISOString()) {
+    const prev = await readMeta();
+    await writeMeta({ account, storedAt: at, legacyChecked: prev?.legacyChecked ?? false });
+}
+export function pickKey(i) {
+    const store = i.store?.trim() || null;
+    const fileKey = i.auth?.apiKey?.trim() || null;
+    if (!store && !fileKey)
+        return { key: null, source: 'none', conflict: false };
+    if (store && !fileKey)
+        return { key: store, source: 'store', conflict: false };
+    if (!store && fileKey)
+        return { key: fileKey, source: 'auth-file', conflict: false };
+    if (store === fileKey)
+        return { key: store, source: 'store', conflict: false };
+    const storedAtMs = i.storedAt ? Date.parse(i.storedAt) : NaN;
+    const fileNewer = i.auth?.savedAt
+        ? !Number.isFinite(storedAtMs) || Date.parse(i.auth.savedAt) > storedAtMs
+        : Number.isFinite(storedAtMs) && i.authMtimeMs !== null && i.authMtimeMs > storedAtMs;
+    return fileNewer
+        ? { key: fileKey, source: 'auth-file', conflict: false }
+        : { key: store, source: 'store', conflict: true };
+}
+export async function resolveApiKey(deps = {}) {
+    let store = null;
+    try {
+        store = await (deps.io ?? (await defaultIo())).get(keychainAccountForHome());
+    }
+    catch {
+        store = null; // no credential store on this machine: auth.json is the fallback
+    }
+    const [auth, authMtimeMs, meta] = await Promise.all([readAuthFile(), authFileMtimeMs(), readMeta()]);
+    return pickKey({ store, auth, authMtimeMs, storedAt: meta?.storedAt ?? null });
+}
+const exists = async (p) => fs.access(p).then(() => true, () => false);
+/**
+ * Run once at start (cli.ts). Idempotent. The common start is one file read
+ * and no keychain call: there is nothing to move.
+ */
+export async function migrateSignIn(deps = {}) {
+    const now = deps.now ?? (() => new Date());
+    const account = keychainAccountForHome();
+    const auth = await readAuthFile();
+    const meta = await readMeta();
+    // (a) A non-default home that predates per-home accounts kept its key in the
+    // shared `api-key` entry. Copy it once — only for a home already in use, so a
+    // brand-new home never inherits another seat's key. Fix round 1 (F1): a home
+    // whose auth.json holds its own key has no claim on the shared key — that
+    // key is this home's sign-in, moved in (b).
+    const needsLegacyCheck = account !== DEFAULT_ACCOUNT && !meta?.legacyChecked && !auth?.apiKey
+        && (auth !== null || await exists(path.join(cspeachRoot(), 'config.toml')));
+    if (!auth?.apiKey && !needsLegacyCheck)
+        return 'none';
+    let io;
+    try {
+        io = deps.io ?? (await defaultIo());
+    }
+    catch {
+        return auth?.apiKey ? 'store-unavailable' : 'none';
+    }
+    let outcome = 'none';
+    try {
+        if (needsLegacyCheck) {
+            if (!(await io.get(account))) {
+                const shared = await io.get(DEFAULT_ACCOUNT);
+                if (shared) {
+                    await io.set(account, shared);
+                    if ((await io.get(account)) !== shared)
+                        return 'copy-verify-failed';
+                    // A copy is not a login: keep the previous storedAt, never "now" (F1).
+                    await writeMeta({ account, storedAt: meta?.storedAt ?? null, legacyChecked: true });
+                    outcome = 'copied-shared';
+                }
+            }
+            if (outcome !== 'copied-shared')
+                await writeMeta({ account, storedAt: meta?.storedAt ?? null, legacyChecked: true });
+        }
+        // (b) A key in auth.json: copy → read back → only then remove.
+        if (!auth?.apiKey)
+            return outcome;
+        const store = await io.get(account);
+        const pick = pickKey({ store, auth, authMtimeMs: await authFileMtimeMs(), storedAt: (await readMeta())?.storedAt ?? null });
+        if (pick.conflict)
+            return 'conflict';
+        const fileKey = auth.apiKey.trim();
+        if (store !== fileKey) {
+            await io.set(account, fileKey);
+            if ((await io.get(account)) !== fileKey)
+                return 'verify-failed'; // never remove the only copy
+            outcome = 'migrated';
+        }
+        else {
+            outcome = 'removed';
+        }
+        // key-store.json is bookkeeping (no secret): its failure never turns a good
+        // store write into a "no credential store" notice (F7).
+        // Final review (Task 4 N1): a non-default home now holds its own key, so
+        // the shared-account check has nothing left to do — mark it done.
+        await (account !== DEFAULT_ACCOUNT
+            ? writeMeta({ account, storedAt: now().toISOString(), legacyChecked: true })
+            : recordStoreWrite(account, now().toISOString())).catch(() => { });
+    }
+    catch {
+        // No key in auth.json (only the shared-account check ran): nothing stays
+        // behind, so no notice — the check simply runs again on the next start.
+        return auth?.apiKey ? 'store-unavailable' : 'none';
+    }
+    try {
+        await writeAuthFile({ customerId: auth.customerId, ...(auth.savedAt ? { savedAt: auth.savedAt } : {}) });
+    }
+    catch {
+        return 'failed'; // the store holds the key; the next start removes the copy ('removed')
+    }
+    return outcome;
+}
+/** The one start-up notice for an outcome the user must know about, else null. */
+export function signInMigrationNotice(o) {
+    switch (o) {
+        case 'conflict':
+            return 'cspeach: auth.json in your CSPeach home holds a different CSPeach key than your OS credential store. CSPeach uses the credential store\'s key. Run cspeach login to sign in again and clear this up.';
+        case 'store-unavailable':
+            return 'cspeach: your OS credential store is not available, so your CSPeach key stays in auth.json in your CSPeach home (on Linux: install and unlock a Secret Service keyring such as gnome-keyring).';
+        case 'verify-failed':
+            return 'cspeach: your CSPeach key could not be confirmed in your OS credential store, so it stays in auth.json for now. CSPeach tries again on the next start.';
+        case 'copy-verify-failed':
+            return 'cspeach: the CSPeach key for this CSPeach home could not be confirmed in your OS credential store. CSPeach tries again on the next start, or run cspeach login to sign in this home.';
+        default:
+            return null;
+    }
+}
+/** `cspeach login`: the store first; auth.json keeps customerId + savedAt. */
+export async function saveSignIn(a, deps = {}) {
+    const account = keychainAccountForHome();
+    const savedAt = (deps.now ?? (() => new Date()))().toISOString();
+    // Fix round 1 (F7): only the store calls decide store vs file.
+    let stored = false;
+    try {
+        const io = deps.io ?? (await defaultIo());
+        await io.set(account, a.apiKey);
+        stored = (await io.get(account)) === a.apiKey;
+    }
+    catch {
+        stored = false;
+    }
+    if (!stored) {
+        await writeAuthFile({ apiKey: a.apiKey, customerId: a.customerId, savedAt });
+        return 'file';
+    }
+    await recordStoreWrite(account, savedAt).catch(() => { }); // bookkeeping only, no secret
+    await writeAuthFile({ customerId: a.customerId, savedAt });
+    return 'store';
+}
+/**
+ * `cspeach logout`: the store entry, auth.json and licence.json. Fix round 1
+ * (F2): verified — `cleared` is false when a delete failed or a key still
+ * resolves afterwards, so logout never says "removed" while a key is left.
+ * (A start running its migration at the same moment can re-store the key it
+ * read before this delete; the verify below catches that too.)
+ */
+export async function clearSignIn(deps = {}) {
+    const account = keychainAccountForHome();
+    const auth = await readAuthFile();
+    let hadStore = false;
+    let storeOk = true;
+    let io = null;
+    try {
+        io = deps.io ?? (await defaultIo());
+        hadStore = (await io.get(account)) !== null;
+        if (hadStore && (await io.del(account)) === false)
+            storeOk = false;
+    }
+    catch {
+        // No credential store: nothing to delete there. A store that held a key
+        // but threw on delete is caught by the verify below.
+    }
+    const fileOk = await deleteAuthFile();
+    await fs.rm(licenceCachePath(), { force: true }).catch(() => { });
+    // Keep legacyChecked so a signed-out non-default home is never re-filled
+    // from the shared account on the next start.
+    await writeMeta({ account, storedAt: null, legacyChecked: true }).catch(() => { });
+    const left = (await resolveApiKey(io ? { io } : {})).key;
+    return { hadSignIn: hadStore || auth !== null, cleared: storeOk && fileOk && left === null };
+}