@cspeach/cli 1.1.32 → 1.1.34

package/dist/auth/azure/cache-store.js

@@ -0,0 +1,171 @@
+/**
+ * Azure tenant mode — MSAL's token cache (3–6 KB) is too big for one Windows
+ * credential (2,560-byte blob cap), so it lives in
+ * <CSPEACH_HOME>/azure/msal-cache.enc, AES-256-GCM. The 32-byte key lives in
+ * the OS credential store: service cspeach.azure, account cache-key[:<home hash>].
+ * Two homes never share a file or a key. No credential store ⇒ no persisted
+ * cache (sign in each session), never plaintext.
+ *
+ * File format: [1 byte version=1][12 bytes IV][16 bytes tag][ciphertext].
+ * Every write draws a fresh IV, goes to a temp file in the same folder and is
+ * renamed over the old file (atomic). POSIX: folder 0700, file 0600. Windows
+ * ignores those modes; the file sits in the person's own profile folder.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+import { cspeachRoot } from '../../config/paths.js';
+import { AZURE_SERVICE, azureAccountForHome } from './azure-key.js';
+import { azureLog } from './azure-log.js';
+const VERSION = 1;
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+const HEADER = 1 + IV_BYTES + TAG_BYTES;
+const KEY_BYTES = 32;
+export const NO_STORE_NOTICE = 'Your Microsoft sign-in is kept for this session only: no OS credential store is available on this machine.';
+export function azureCachePath() {
+    return path.join(cspeachRoot(), 'azure', 'msal-cache.enc');
+}
+export function encryptCache(plain, key, iv = randomBytes(IV_BYTES)) {
+    const c = createCipheriv('aes-256-gcm', key, iv);
+    const ct = Buffer.concat([c.update(plain, 'utf8'), c.final()]);
+    return Buffer.concat([Buffer.from([VERSION]), iv, c.getAuthTag(), ct]);
+}
+export function decryptCache(blob, key) {
+    if (blob.length < HEADER || blob[0] !== VERSION)
+        throw new Error('unreadable cache');
+    const d = createDecipheriv('aes-256-gcm', key, blob.subarray(1, 1 + IV_BYTES));
+    d.setAuthTag(blob.subarray(1 + IV_BYTES, HEADER));
+    return Buffer.concat([d.update(blob.subarray(HEADER)), d.final()]).toString('utf8');
+}
+async function defaultKeychain() {
+    return (await import('../keychain.js')).default;
+}
+async function writeAtomic(file, data) {
+    const dir = path.dirname(file);
+    await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+    // mkdir's mode only applies to a NEW folder; tighten one that already existed.
+    // A failure (a folder owned by someone else, a file system without modes)
+    // is logged and never fails the cache write: the file itself is still 0600.
+    if (process.platform !== 'win32') {
+        try {
+            await fs.chmod(dir, 0o700);
+        }
+        catch {
+            azureLog('cache: could not tighten the sign-in cache folder permissions');
+        }
+    }
+    const tmp = `${file}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
+    try {
+        await fs.writeFile(tmp, data, { mode: 0o600, flag: 'wx' });
+        await fs.rename(tmp, file);
+    }
+    catch (e) {
+        await fs.rm(tmp, { force: true }).catch(() => { });
+        throw e;
+    }
+}
+function asKey(stored) {
+    const decoded = stored ? Buffer.from(stored, 'base64') : null;
+    return decoded && decoded.length === KEY_BYTES ? decoded : null;
+}
+/**
+ * Two processes can start on the same home at once. Rules that keep them on
+ * ONE key without deleting each other's file:
+ * - first use: store a new key, then read it back and adopt what is stored
+ *   (another process may have written last);
+ * - before each write: re-read the stored key and adopt it if it changed;
+ * - a read that fails to decrypt: re-read the stored key once and retry
+ *   before treating the file as damaged.
+ */
+export async function openCacheStore(deps = {}) {
+    const account = azureAccountForHome('cache-key');
+    let kc;
+    let key;
+    try {
+        kc = deps.keychain ?? (await defaultKeychain());
+        const existing = asKey(await kc.getPassword(AZURE_SERVICE, account));
+        if (existing)
+            key = existing;
+        else {
+            const fresh = (deps.random ?? randomBytes)(KEY_BYTES);
+            await kc.setPassword(AZURE_SERVICE, account, fresh.toString('base64'));
+            key = asKey(await kc.getPassword(AZURE_SERVICE, account)) ?? fresh;
+        }
+    }
+    catch {
+        deps.notice?.(NO_STORE_NOTICE);
+        return { plugin: null, persisted: false };
+    }
+    /** The stored key when it is readable and different from ours; otherwise null. */
+    const storedIfChanged = async () => {
+        try {
+            const stored = asKey(await kc.getPassword(AZURE_SERVICE, account));
+            return stored && !stored.equals(key) ? stored : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const file = azureCachePath();
+    const plugin = {
+        async beforeCacheAccess(ctx) {
+            let blob;
+            try {
+                blob = await fs.readFile(file);
+            }
+            catch {
+                return;
+            }
+            let plain = null;
+            try {
+                plain = decryptCache(blob, key);
+            }
+            catch {
+                const stored = await storedIfChanged();
+                if (stored) {
+                    try {
+                        plain = decryptCache(blob, stored);
+                        key = stored;
+                    }
+                    catch {
+                        plain = null;
+                    }
+                }
+            }
+            try {
+                if (plain === null)
+                    throw new Error('unreadable');
+                ctx.tokenCache.deserialize(plain);
+            }
+            catch {
+                // Damaged, written under a key no longer stored, or unreadable to MSAL: start empty and drop it.
+                await fs.rm(file, { force: true }).catch(() => { });
+            }
+        },
+        async afterCacheAccess(ctx) {
+            if (!ctx.cacheHasChanged)
+                return;
+            const stored = await storedIfChanged();
+            if (stored)
+                key = stored;
+            await writeAtomic(file, encryptCache(ctx.tokenCache.serialize(), key));
+        },
+    };
+    return { plugin, persisted: true };
+}
+/** Logout: the cache file and its key for THIS home. True when either existed. */
+export async function clearAzureCache(deps = {}) {
+    const kc = deps.keychain ?? (await defaultKeychain());
+    let file = false;
+    try {
+        await fs.unlink(azureCachePath());
+        file = true;
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+    const key = await kc.deletePassword(AZURE_SERVICE, azureAccountForHome('cache-key'));
+    return file || key;
+}

package/dist/auth/azure/clear.js

@@ -0,0 +1,28 @@
+/**
+ * Azure tenant mode — what `cspeach logout` removes on top of today's
+ * entries: the company settings (Task 4), the Azure key (Task 5), the
+ * Microsoft sign-in cache file and its key (Task 6), and this home's local
+ * limit count, azure-usage-local.json (final fix wave E). Reports in plain words
+ * what it removed and what it could not.
+ */
+import { deleteConnectionCache } from '../../connection/cache.js';
+import { deleteAzureKey } from './azure-key.js';
+import { clearAzureCache } from './cache-store.js';
+import { deleteLocalUsage } from '../../connection/local-usage.js';
+export async function clearAzureSignIn(deps = {}) {
+    const out = { removed: [], failed: [] };
+    const step = async (label, run) => {
+        try {
+            if (await run())
+                out.removed.push(label);
+        }
+        catch {
+            out.failed.push(label);
+        }
+    };
+    await step("your company's Azure settings", deps.deleteConnection ?? deleteConnectionCache);
+    await step('your Azure key', deps.deleteKey ?? deleteAzureKey);
+    await step('your Microsoft sign-in', deps.clearCache ?? (() => clearAzureCache()));
+    await step('your Azure usage count on this machine', deps.deleteLocalCount ?? deleteLocalUsage);
+    return out;
+}

package/dist/auth/azure/loopback.js

@@ -0,0 +1,192 @@
+/**
+ * Azure tenant mode — our own loopback listener for the browser sign-in
+ * (owner decision P5: it is ALWAYS closed when sign-in ends — success,
+ * error, timeout or abort). MSAL Node 6.0.1 gives no way to supply or close
+ * its own listener, so sign-in.ts uses this one with MSAL's public
+ * getAuthCodeUrl + acquireTokenByCode.
+ *
+ * - Loopback only: 127.0.0.1, plus ::1 on the SAME port when IPv6 is there
+ *   (a browser may resolve localhost either way). Never 0.0.0.0 or '::'.
+ *   IPv4 alone only when this machine has no IPv6 loopback; when the port is
+ *   busy on ::1, up to 20 new ports, then LoopbackPortError (a plain line).
+ * - Redirect URI http://localhost:<port> (Entra matches any port for localhost).
+ * - Exactly one completing GET on "/": the state must match (single use) and
+ *   the Host must be localhost / 127.0.0.1 / [::1] on our port. Anything else
+ *   gets a 4xx and does not end the sign-in.
+ * - The page is short fixed HTML: no code, state, token or Microsoft text.
+ * - Nothing here logs. The code, state and redirect query never leave this
+ *   module except as the resolved value.
+ */
+import http from 'node:http';
+import { timingSafeEqual } from 'node:crypto';
+/** The signal fired (timeout or abort) before the browser came back. */
+export class LoopbackCancelledError extends Error {
+    constructor() { super('The sign-in was stopped before the browser came back.'); this.name = 'LoopbackCancelledError'; }
+}
+/** Microsoft sent the browser back with `error`. `detail` is for classifying only — never log or print it. */
+export class LoopbackAuthError extends Error {
+    errorCode;
+    detail;
+    constructor(errorCode, detail) {
+        super('Microsoft sent the sign-in back with an error.');
+        this.name = 'LoopbackAuthError';
+        this.errorCode = errorCode;
+        this.detail = detail;
+    }
+}
+/** No port was free on both 127.0.0.1 and ::1 after every try. */
+export class LoopbackPortError extends Error {
+    constructor() { super('Could not open a sign-in port on this computer. Try again, or use cspeach login azure --device-code.'); this.name = 'LoopbackPortError'; }
+}
+const IPV4 = '127.0.0.1';
+const IPV6 = '::1';
+/** ::1 cannot be used on this machine: no IPv6 loopback. */
+const IPV6_UNAVAILABLE = new Set(['EADDRNOTAVAIL', 'EAFNOSUPPORT', 'EINVAL', 'EPROTONOSUPPORT']);
+const page = (text) => `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>CSPeach sign-in</title></head><body><p>${text}</p></body></html>`;
+const PAGE_OK = page('Signed in. You can close this tab and go back to CSPeach.');
+const PAGE_FAILED = page('Sign-in did not finish. You can close this tab and go back to CSPeach for the next step.');
+const PAGE_NOT_OURS = page('This page is not part of the CSPeach sign-in. You can close this tab.');
+function listen(server, port, host) {
+    return new Promise((resolve, reject) => {
+        const onError = (e) => { server.off('listening', onListening); reject(e); };
+        const onListening = () => { server.off('error', onError); resolve(); };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        server.listen({ port, host, exclusive: true });
+    });
+}
+function closeServer(server) {
+    return new Promise((resolve) => {
+        if (!server.listening) {
+            server.closeAllConnections?.();
+            resolve();
+            return;
+        }
+        server.close(() => resolve());
+        server.closeAllConnections?.();
+    });
+}
+function sameSecret(a, b) {
+    const x = Buffer.from(a, 'utf8');
+    const y = Buffer.from(b, 'utf8');
+    return x.length === y.length && timingSafeEqual(x, y);
+}
+/** Microsoft error codes are short snake_case words; anything else is reduced to a fixed word. */
+function errorCodeOf(raw) {
+    return /^[a-z_]{1,64}$/.test(raw) ? raw : 'unknown_error';
+}
+async function bind(make, attempts) {
+    for (let i = 0; i < attempts; i += 1) {
+        const v4 = make(IPV4);
+        await listen(v4, 0, IPV4);
+        const port = v4.address().port;
+        const v6 = make(IPV6);
+        try {
+            await listen(v6, port, IPV6);
+            return [v4, v6];
+        }
+        catch (e) {
+            const code = e.code ?? '';
+            // IPv4 alone ONLY when this machine has no IPv6 loopback at all.
+            if (IPV6_UNAVAILABLE.has(code))
+                return [v4];
+            await closeServer(v4);
+            if (code !== 'EADDRINUSE')
+                throw e;
+        }
+    }
+    // ::1 exists but no port was free on both: a browser that resolves
+    // localhost to ::1 would never reach an IPv4-only listener. Stop plainly.
+    throw new LoopbackPortError();
+}
+export async function startLoopback(o) {
+    if (o.signal?.aborted)
+        throw new LoopbackCancelledError();
+    const make = o.makeServer ?? (() => http.createServer());
+    const servers = await bind(make, o.maxAttempts ?? 20);
+    const port = servers[0].address().port;
+    const hosts = servers.map((s) => s.address().address);
+    const allowedHosts = new Set([`localhost:${port}`, `127.0.0.1:${port}`, `[::1]:${port}`]);
+    let settle;
+    const result = new Promise((resolve, reject) => { settle = { resolve, reject }; });
+    result.catch(() => { });
+    let done = false;
+    let closing = null;
+    const onAbort = () => {
+        if (done)
+            return;
+        done = true;
+        void close();
+        settle.reject(new LoopbackCancelledError());
+    };
+    const close = () => {
+        if (!closing) {
+            o.signal?.removeEventListener('abort', onAbort);
+            closing = Promise.all(servers.map(closeServer)).then(() => undefined);
+            if (!done) {
+                done = true;
+                settle.reject(new LoopbackCancelledError());
+            }
+        }
+        return closing;
+    };
+    const handler = (req, res) => {
+        const send = (status, body) => {
+            res.writeHead(status, {
+                'Content-Type': 'text/html; charset=utf-8',
+                'Cache-Control': 'no-store',
+                'Referrer-Policy': 'no-referrer',
+                'Content-Security-Policy': "default-src 'none'",
+                'X-Content-Type-Options': 'nosniff',
+                Connection: 'close',
+            });
+            res.end(body);
+        };
+        if (done)
+            return send(400, PAGE_NOT_OURS);
+        if (req.method !== 'GET')
+            return send(405, PAGE_NOT_OURS);
+        if (!allowedHosts.has((req.headers.host ?? '').toLowerCase()))
+            return send(400, PAGE_NOT_OURS);
+        let url;
+        try {
+            url = new URL(req.url ?? '', 'http://localhost');
+        }
+        catch {
+            return send(400, PAGE_NOT_OURS);
+        }
+        if (url.pathname !== '/')
+            return send(404, PAGE_NOT_OURS);
+        const states = url.searchParams.getAll('state');
+        if (states.length !== 1 || !sameSecret(states[0], o.state))
+            return send(400, PAGE_NOT_OURS);
+        const error = url.searchParams.get('error');
+        if (error) {
+            done = true;
+            send(200, PAGE_FAILED);
+            settle.reject(new LoopbackAuthError(errorCodeOf(error), (url.searchParams.get('error_description') ?? '').slice(0, 500)));
+            return;
+        }
+        const codes = url.searchParams.getAll('code');
+        if (codes.length !== 1 || !codes[0])
+            return send(400, PAGE_NOT_OURS);
+        done = true;
+        send(200, PAGE_OK);
+        const clientInfo = url.searchParams.get('client_info');
+        settle.resolve({ code: codes[0], ...(clientInfo ? { clientInfo } : {}) });
+    };
+    for (const s of servers)
+        s.on('request', handler);
+    o.signal?.addEventListener('abort', onAbort, { once: true });
+    if (o.signal?.aborted)
+        onAbort();
+    return {
+        redirectUri: `http://localhost:${port}`,
+        port,
+        hosts,
+        boundAddresses: () => servers.filter((s) => s.listening).map((s) => s.address()),
+        isListening: () => servers.some((s) => s.listening),
+        waitForCode: () => result,
+        close,
+    };
+}

package/dist/auth/azure/msal-client.js

@@ -0,0 +1,41 @@
+export const createMsal = async (o) => {
+    const msal = await import('@azure/msal-node');
+    const pca = new msal.PublicClientApplication({
+        auth: { clientId: o.clientId, authority: `https://login.microsoftonline.com/${o.tenantId}` },
+        ...(o.cachePlugin ? { cache: { cachePlugin: o.cachePlugin } } : {}),
+        system: {
+            loggerOptions: {
+                logLevel: msal.LogLevel.Error,
+                piiLoggingEnabled: false,
+                loggerCallback: (_level, message, containsPii) => { if (!containsPii)
+                    o.log(message); },
+            },
+        },
+    });
+    const crypto = new msal.CryptoProvider();
+    const app = {
+        generatePkceCodes: () => crypto.generatePkceCodes(),
+        getAuthCodeUrl: (r) => pca.getAuthCodeUrl(r),
+        acquireTokenByCode: async (r) => (await pca.acquireTokenByCode(r)),
+        acquireTokenByDeviceCode: async (r) => (await pca.acquireTokenByDeviceCode(r)),
+        acquireTokenSilent: async (r) => (await pca.acquireTokenSilent(r)),
+        getAllAccounts: async () => (await pca.getAllAccounts()),
+        removeAccount: (a) => pca.getTokenCache().removeAccount(a),
+    };
+    return app;
+};
+const INTERACTION_CODES = new Set([
+    'interaction_required', 'invalid_grant', 'login_required', 'consent_required',
+    'no_tokens_found', 'no_account_in_silent_request', 'token_refresh_required',
+]);
+export function isInteractionRequired(err) {
+    const e = err;
+    return e?.name === 'InteractionRequiredAuthError' || (typeof e?.errorCode === 'string' && INTERACTION_CODES.has(e.errorCode));
+}
+export function tenantOf(r) {
+    const t = r.tenantId ?? (typeof r.idTokenClaims?.tid === 'string' ? r.idTokenClaims.tid : undefined) ?? r.account?.tenantId;
+    return typeof t === 'string' && t ? t.toLowerCase() : null;
+}
+export class AzureWrongTenantError extends Error {
+    constructor() { super('This Microsoft account belongs to a different company directory.'); this.name = 'AzureWrongTenantError'; }
+}

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 }) };
+    }
+}