brightspace-mcp-server 3.12.3 → 3.13.0

package/README.md

@@ -97,6 +97,7 @@ All optional, set in your AI app's MCP `env` config or your shell. The full list
 |---------|--------------|
 | `D2L_REMEMBER_MFA=true` | Tick Microsoft's "Don't ask again" box so later sign-ins skip the second factor (off by default; not for shared computers). `setup` asks this and saves it as `rememberMfa` in `config.json`; the env var overrides it |
 | `D2L_PASSWORDLESS=true` | Sign in with Microsoft Entra's passwordless phone approval, so no password is saved on the computer (off by default; Entra schools only). Every sign-in, including automatic ones, then waits for you to approve on your phone, so it suits interactive use, not unattended or scheduled jobs. `setup` asks this and saves it as `passwordless` in `config.json`; the env var overrides it ([details](docs/sign-in.md#passwordless-sign-in)) |
+| `D2L_TOTP_SECRET` | An authenticator setup key, so a Microsoft Entra "enter a code" challenge is answered on this computer instead of on your phone (off by default). Prefer `setup`, which keeps the key in your OS keychain; this variable is for CI and containers with no keychain and is weaker, because anything that can read the process environment gets your second factor ([details](docs/sign-in.md#answering-code-challenges-without-your-phone)) |
 | `D2L_HEADLESS=false` | Show the browser window during sign-in, for MFA methods that need a click |
 | `D2L_DUO_PASSCODE=1` | On Duo, type a passcode instead of waiting for a push |
 | `D2L_SESSION_COOKIE` / `D2L_ACCESS_TOKEN` | Skip the browser entirely with a pasted cookie or token ([how](docs/sign-in.md#no-browser-paste-a-session-cookie-or-token)) |
@@ -115,6 +116,14 @@ npx -y brightspace-mcp-server@latest auth
 
 **On a Mac,** sign-in first reads your saved password from Keychain. If you picked a one-time **Allow** at the Keychain prompt, a later sign-in from your AI app or another terminal can fail or hang waiting for an approval nobody sees; pick **Always Allow** instead. That permission only lets the local Brightspace server read its own saved sign-in password, nothing else in your Keychain.
 
+**If your school asks for a 6-digit code** rather than a phone approval, `setup` can save the
+authenticator **setup key** (not a code) you got when you enrolled the app. From then on automatic
+sign-ins generate the code on this computer and finish without you, which is what unattended and
+scheduled use needs. It is optional and off unless you paste a key. The tradeoff is real: the key
+sits beside your password, so on **this** computer your two factors become one. It still stops
+anyone who only has your password, and it changes nothing for your other devices. Full enrollment
+steps: [docs/sign-in.md](docs/sign-in.md#answering-code-challenges-without-your-phone).
+
 How often you're asked is up to your school, not this tool. Everything else about sign-in — Duo, authenticator codes, visible-browser mode, and running without a browser at all (Docker, WSL, hardware keys) — is in [docs/sign-in.md](docs/sign-in.md).
 
 ## Something not working?

package/build/auth/auth-lock.js

@@ -45,7 +45,12 @@ async function renameThroughContention(from, to) {
 export const CHALLENGE_FILE = "challenge.json";
 export class AuthenticationInProgressError extends Error {
     code = "AUTH_IN_PROGRESS";
-    /** The owner's MFA challenge, when the caller looked it up (see BrowserAuth.authenticate). */
+    /**
+     * The owner's MFA challenge, when the caller looked it up (see
+     * BrowserAuth.authenticate). Structurally `PendingChallenge` from
+     * mfa-challenge.ts, spelled out here because that module imports
+     * CHALLENGE_FILE from this one.
+     */
     challenge;
     constructor() {
         super("Authentication already in progress. Retry after the current authentication finishes.");

package/build/auth/auth-runner.js

@@ -11,7 +11,7 @@ import { AuthError } from "../utils/errors.js";
 import { AUTH_COMMAND } from "../utils/commands.js";
 import { devActivity } from "../utils/dev-activity.js";
 import { parsePhaseMarker } from "./auth-phases.js";
-import { authLockPath, challengeRelayedAt } from "./mfa-challenge.js";
+import { AUTOMATIC_PENDING_MARKER, authLockPath, challengeRelayedAt } from "./mfa-challenge.js";
 /**
  * Timeout for the auth process. It has to outlast the child's own MFA wait,
  * which is five minutes: a person has to find their phone, unlock it, and read
@@ -89,6 +89,13 @@ function mfaPendingFailure(numberMatch) {
         ? ["mfaPending", `Open Microsoft Authenticator and enter ${numberMatch} within 5 minutes, then try again.`]
         : ["mfaPending", "An MFA approval was not completed in time. Try again."];
 }
+/**
+ * The child is answering its own verification code from the saved
+ * authenticator enrollment. Deliberately NOT an mfaPending: there is nothing
+ * on anyone's phone to approve, so a caller told "approve the request" would
+ * send the user looking for a prompt that will never arrive.
+ */
+const automaticPendingFailure = () => new AuthProcessError("automaticPending", "Sign-in is entering its own verification code in the background. Try again.");
 export class AuthProcessError extends AuthError {
     kind;
     numberMatch;
@@ -174,9 +181,13 @@ function forwardLines(stream, emit) {
     });
 }
 function dedupeChallenge(error, wave) {
-    if (!(error instanceof AuthProcessError) || error.kind !== "mfaPending" || error.duplicate)
+    // automaticPending repeats across a batch exactly as mfaPending did (#212),
+    // just without digits: one sign-in, N copies of the same paragraph.
+    if (!(error instanceof AuthProcessError) || error.duplicate)
         return error;
-    const key = error.numberMatch ?? "";
+    if (error.kind !== "mfaPending" && error.kind !== "automaticPending")
+        return error;
+    const key = `${error.kind}:${error.numberMatch ?? ""}`;
     if (!wave.delivered.has(key)) {
         wave.delivered.add(key);
         // Once a challenge has gone back to the user, the batch is over: every
@@ -283,15 +294,23 @@ export class AuthRunner {
         }
         catch (error) {
             const childDone = this.childDone;
-            if (!onChallenge || !childDone || !(error instanceof AuthProcessError) || error.kind !== "mfaPending")
+            if (!childDone || !(error instanceof AuthProcessError))
+                throw error;
+            // An mfaPending is only worth waiting on when the caller can relay the
+            // number mid-call. An automaticPending needs no relay at all — nobody is
+            // being asked for anything — so keep waiting on it either way.
+            const joinable = error.kind === "automaticPending" || (Boolean(onChallenge) && error.kind === "mfaPending");
+            if (!joinable)
                 throw error;
             const windowMs = pollWindowMs(Date.now() - startedAt);
             if (windowMs <= 0)
                 throw error;
-            try {
-                onChallenge(error.numberMatch);
+            if (error.kind === "mfaPending") {
+                try {
+                    onChallenge?.(error.numberMatch);
+                }
+                catch { /* Announcing must not interrupt authentication. */ }
             }
-            catch { /* Announcing must not interrupt authentication. */ }
             return this.awaitBackgroundChild(childDone, windowMs);
         }
     }
@@ -354,6 +373,11 @@ export class AuthRunner {
                 if (settled)
                     return;
                 settled = true;
+                const pending = this.pendingChallenge ?? challenge;
+                if (pending?.kind === "automaticPending") {
+                    reject(automaticPendingFailure());
+                    return;
+                }
                 const numberMatch = this.pendingChallenge?.numberMatch ?? challenge?.numberMatch;
                 reject(new AuthProcessError(...mfaPendingFailure(numberMatch), numberMatch));
             }, graceMs);
@@ -405,6 +429,10 @@ export class AuthRunner {
             let childFinished = false;
             let numberMatch;
             let challengeSeen = false;
+            /** The child reported it is answering its own code (see the marker below). */
+            let automaticSeen = false;
+            /** watchAttention is armed once per child; a second timer could kill a live sign-in. */
+            let attentionWatched = false;
             let abandonTimer;
             let killTimer;
             const kill = (signal) => {
@@ -493,15 +521,23 @@ export class AuthRunner {
                 kill("SIGKILL");
                 finishChild(new AuthProcessError("timeout", `The sign-in was stopped because nobody approved its MFA prompt. Try again, or run ${AUTH_COMMAND}.`));
             };
+            const startWatching = () => {
+                if (attentionWatched)
+                    return;
+                attentionWatched = true;
+                watchAttention();
+            };
             const publishChallenge = (matched) => {
                 challengeSeen = true;
-                const firstChallenge = this.pendingChallenge === null;
-                if (firstChallenge)
-                    watchAttention();
+                // An automatic sign-in that later shows a real approval challenge (it
+                // fell back, or Entra changed its mind) must be upgraded, so a joiner
+                // is told the number instead of "still working".
+                const firstChallenge = this.pendingChallenge === null || this.pendingChallenge.kind === "automaticPending";
+                startWatching();
                 if (firstChallenge)
                     devActivity("mfa_observed", { elapsedMs: Date.now() - started });
                 if (firstChallenge || matched) {
-                    this.pendingChallenge = { numberMatch: matched ?? this.pendingChallenge?.numberMatch };
+                    this.pendingChallenge = { kind: "mfaPending", numberMatch: matched ?? this.pendingChallenge?.numberMatch };
                 }
                 if (firstChallenge)
                     resolveChallengeSignal();
@@ -509,6 +545,21 @@ export class AuthRunner {
                     settleCaller(new AuthProcessError(...mfaPendingFailure(this.pendingChallenge?.numberMatch), this.pendingChallenge?.numberMatch));
                 }
             };
+            /**
+             * The child is typing its own verification code. Watched for abandonment
+             * exactly like an approval challenge: a sign-in nobody is waiting on
+             * still holds the cross-process lock, and every caller is told to retry
+             * right away, which keeps it alive (see ABANDON_MS).
+             */
+            const publishAutomaticProgress = () => {
+                automaticSeen = true;
+                if (this.pendingChallenge)
+                    return;
+                this.pendingChallenge = { kind: "automaticPending" };
+                startWatching();
+                resolveChallengeSignal();
+                settleCaller(automaticPendingFailure());
+            };
             // Runs once the child is actually done. Settles the caller too, if an
             // early answer had not already done so; otherwise this is just the
             // background sign-in finishing, which only childDone's joiner sees.
@@ -567,6 +618,9 @@ export class AuthRunner {
                 else if (MFA_PENDING_MARKER.test(line)) {
                     publishChallenge(undefined);
                 }
+                else if (line === AUTOMATIC_PENDING_MARKER) {
+                    publishAutomaticProgress();
+                }
                 else {
                     log("DEBUG", line);
                 }
@@ -602,6 +656,10 @@ export class AuthRunner {
                     // was told what to approve, so answer with that, not "busy".
                     if (code === 2 && challengeSeen)
                         failures[2] = mfaPendingFailure(numberMatch);
+                    // Busy because another process is signing in automatically: there is
+                    // nothing to approve, so say that rather than "busy".
+                    else if (code === 2 && automaticSeen)
+                        failures[2] = ["automaticPending", automaticPendingFailure().message];
                     const [kind, message] = failures[code ?? -1] ?? ["failed", `Authentication failed. Run ${AUTH_COMMAND} to try again.`];
                     kill("SIGKILL");
                     finishChild(new AuthProcessError(kind, message, kind === "mfaPending" ? numberMatch : undefined));

package/build/auth/browser-auth.js

@@ -6,12 +6,12 @@
 import { readFileSync, accessSync } from "node:fs";
 import { BrowserAuthError } from "../utils/errors.js";
 import { log } from "../utils/logger.js";
-import { createSSOFlow, UnsupportedAuthenticationError, MfaApprovalError } from "./sso-flow.js";
+import { createSSOFlow, UnsupportedAuthenticationError, MfaApprovalError, AutomaticCodeAuthenticationError } from "./sso-flow.js";
 import { isDuoPrompt } from "./duo-mfa.js";
 import { BrowserStateStore } from "./browser-state-store.js";
 import { hasNewerEntraState, recordMicrosoftSession } from "./microsoft-session.js";
 import { acquireProcessLock, AuthenticationInProgressError } from "./auth-lock.js";
-import { authLockPath, publishChallenge, relayChallenge } from "./mfa-challenge.js";
+import { authLockPath, publishAutomaticProgress, publishChallenge, relayChallenge } from "./mfa-challenge.js";
 import { AuthCooldown } from "./auth-cooldown.js";
 import { mintAccessToken } from "./token-mint.js";
 import { isMissingBrowserError, PLAYWRIGHT_INSTALL_HINT } from "../utils/browser-install.js";
@@ -65,13 +65,25 @@ export class BrowserAuth {
         this.onPhase = options.onPhase;
         const { onMfaChallenge } = options;
         this.lockPath = authLockPath(config.sessionDir);
+        const { onAutomaticPending } = options;
         this.ssoFlow = createSSOFlow(config, options.requestMfaCode, onMfaChallenge && ((number) => {
             this.challengeSeenAt ??= Date.now();
             // Other server processes sharing this session cannot see our caller's
             // tool response; the lock directory is where they look instead.
             this.publishing = this.publishing.then(() => publishChallenge(this.lockPath, number)).catch(() => { });
             onMfaChallenge(number);
-        }));
+        }), () => {
+            // Published through the same lock-directory file as a number-match
+            // challenge (issue #199), so a contender in another process relays
+            // "automatic sign-in in progress" rather than an approval nobody asked
+            // for — and the relay keeps this sign-in from being abandoned.
+            this.challengeSeenAt ??= Date.now();
+            this.publishing = this.publishing.then(() => publishAutomaticProgress(this.lockPath)).catch(() => { });
+            try {
+                onAutomaticPending?.();
+            }
+            catch { /* Reporting must not interrupt authentication. */ }
+        });
         this.stateStore = new BrowserStateStore(config.sessionDir);
         this.cooldown = new AuthCooldown(config.sessionDir);
     }
@@ -422,8 +434,11 @@ export class BrowserAuth {
             }
         }
         catch (error) {
-            if (error instanceof MfaApprovalError)
+            // An automatic code sign-in that failed gets the same cooldown: retrying
+            // it in a tight loop would walk Entra's attempt limits down for nothing.
+            if (error instanceof MfaApprovalError || error instanceof AutomaticCodeAuthenticationError) {
                 await this.cooldown.recordMfaFailure();
+            }
             throw error;
         }
         finally {

package/build/auth/credential-store.js

@@ -162,6 +162,28 @@ function passwordAccount(baseUrl, username) {
     const identity = JSON.stringify([new URL(baseUrl).origin, username]);
     return `password:${createHash("sha256").update(identity).digest("hex")}`;
 }
+/**
+ * The authenticator enrollment's own account, derived exactly like
+ * passwordAccount (same origin + username, same casing rules) so one account's
+ * two secrets live or die together, under a separate `totp:` prefix so the
+ * seed can never be returned where a password is expected.
+ * Idea from ElliotDrel/brightspace-mcp-server (branch codex/purdue-totp).
+ */
+function totpAccount(baseUrl, username) {
+    const identity = JSON.stringify([new URL(baseUrl).origin, username]);
+    return `totp:${createHash("sha256").update(identity).digest("hex")}`;
+}
+/** The account's saved authenticator enrollment, or null when none was saved. */
+export async function getStoredTotpUri(baseUrl, username, backend = nativeCredentialBackend) {
+    return backend.getPassword(SERVICE, totpAccount(baseUrl, username));
+}
+export async function setStoredTotpUri(baseUrl, username, uri, backend = nativeCredentialBackend) {
+    const account = totpAccount(baseUrl, username);
+    await backend.setPassword(SERVICE, account, uri);
+    if (await backend.getPassword(SERVICE, account) !== uri) {
+        throw new NativeCredentialStoreError("The authenticator enrollment could not be verified in the native credential store. Existing configuration was preserved.");
+    }
+}
 export async function getStoredPassword(baseUrl, username, backend = nativeCredentialBackend) {
     return backend.getPassword(SERVICE, passwordAccount(baseUrl, username));
 }

package/build/auth/mfa-challenge.js

@@ -26,6 +26,17 @@ export async function publishChallenge(lockPath, numberMatch) {
     const challenge = numberMatch && NUMBER_MATCH.test(numberMatch) ? { numberMatch } : {};
     await fs.writeFile(path.join(lockPath, CHALLENGE_FILE), JSON.stringify(challenge), { mode: 0o600 });
 }
+/**
+ * Record that this process's sign-in is answering its own verification code,
+ * so a contender sharing the session can say so instead of announcing an
+ * approval that was never requested. Written through the same file as a
+ * number-match challenge, so it disappears with the lock and a contender
+ * reading it keeps the sign-in from being abandoned.
+ */
+export async function publishAutomaticProgress(lockPath) {
+    const challenge = { kind: "automatic" };
+    await fs.writeFile(path.join(lockPath, CHALLENGE_FILE), JSON.stringify(challenge), { mode: 0o600 });
+}
 /**
  * The challenge the lock owner is showing, or undefined when it has published
  * none. Marks the challenge as just relayed, so the owner keeps waiting.
@@ -44,7 +55,12 @@ export async function relayChallenge(lockPath) {
     const now = new Date();
     await fs.utimes(file, now, now).catch(() => { });
     const numberMatch = challenge.numberMatch;
-    return typeof numberMatch === "string" && NUMBER_MATCH.test(numberMatch) ? { numberMatch } : {};
+    const relayed = {};
+    if (challenge.kind === "automatic")
+        relayed.kind = "automatic";
+    if (typeof numberMatch === "string" && NUMBER_MATCH.test(numberMatch))
+        relayed.numberMatch = numberMatch;
+    return relayed;
 }
 /** When the lock's challenge was last published or relayed, or undefined when there is none. */
 export function challengeRelayedAt(lockPath) {
@@ -55,6 +71,12 @@ export function challengeRelayedAt(lockPath) {
         return undefined;
     }
 }
+/**
+ * The stdout marker for a sign-in that is answering its own verification
+ * code: no digits to carry, and nothing for the user to do but wait. Kept
+ * beside challengeMarker so the child and AuthRunner cannot drift apart.
+ */
+export const AUTOMATIC_PENDING_MARKER = "AUTH_AUTOMATIC_PENDING";
 /** The stdout marker AuthRunner parses for a challenge. */
 export function challengeMarker(numberMatch) {
     return numberMatch ? `MFA_NUMBER:${numberMatch}` : "MFA_PENDING";

package/build/auth/purdue-sso.js

@@ -5,9 +5,11 @@
  */
 import { BrowserAuthError } from "../utils/errors.js";
 import { log } from "../utils/logger.js";
-import { MfaApprovalError, UnsupportedAuthenticationError } from "./sso-flow.js";
+import { devActivity } from "../utils/dev-activity.js";
+import { AutomaticCodeAuthenticationError, MfaApprovalError, UnsupportedAuthenticationError } from "./sso-flow.js";
 import { DuoMfaHandler } from "./duo-mfa.js";
 import { AUTH_COMMAND } from "../utils/commands.js";
+import { generateTotp, secondsUntilFreshCode } from "./totp.js";
 // Entra names its username field type=email/loginfmt; Shibboleth portals (USC's
 // login.usc.edu among them) use the protocol's j_username.
 const EMAIL_SELECTORS = ["input[type=email]", "input[name=loginfmt]", "input[name=j_username]", "input#signinid"];
@@ -27,10 +29,13 @@ const NUMBER_MATCH_SELECTOR = "#idRichContext_DisplaySign";
  * which the tenant shows instead of a password page once the account has
  * registered passwordless sign-in in Authenticator. The "Use your password
  * instead" link is the marker browser-auth.ts already relies on; the
- * RemoteNGC ids are EXPECTED, not verified against a live tenant from here.
+ * RemoteNGC ids were verified live on Purdue's tenant on 2026-10-09 (#idRemoteNGC_DisplaySign,
+ * #idDiv_RemoteNGC_PollingDescription, #idA_PWD_SwitchToPassword).
  * The number shown there is typed into Authenticator like number match.
  */
 const PASSWORDLESS_NUMBER_SELECTOR = "#idRemoteNGC_DisplaySign";
+/** The approval view's "Use your password instead" link (live-verified on Purdue, 2026-10-09). */
+const PASSWORDLESS_SWITCH_SELECTOR = "#idA_PWD_SwitchToPassword";
 const PASSWORDLESS_APPROVAL_SELECTORS = [
     PASSWORDLESS_NUMBER_SELECTOR,
     "#idDiv_RemoteNGC_PollingDescription",
@@ -104,6 +109,41 @@ const RESEND_NOT_FOUND_WARN_MS = 30_000;
  * elapsed time creep past a single interval and defeat the guard.
  */
 const RESEND_CLICK_GUARD_MS = NUMBER_MATCH_POLL_MS * 2;
+/**
+ * Entra's own labels for reaching the verification-code form. Clicked only
+ * when an authenticator enrollment is saved, and each at most once per login,
+ * so this can never loop between method pages. The exact-match code label is
+ * tried first; the vaguer "another way" links only open the method list.
+ * Ported from ElliotDrel/brightspace-mcp-server (branch codex/purdue-totp).
+ */
+const CODE_METHOD_STEPS = [
+    ["code", /^use a verification code$/i],
+    ["other", /^(?:I can.t use my .+ right now|sign in another way|use a different verification option)$/i],
+];
+/** Let Entra re-render the method page before the loop looks at it again. */
+const METHOD_SWITCH_SETTLE_MS = 500;
+/**
+ * Never submit a code with less life than this left: Entra validates a moment
+ * after the click, and a code that rolls over in between is rejected — which
+ * would spend one of the three attempts for nothing.
+ */
+const MIN_CODE_LIFETIME_S = 5;
+/**
+ * How long an automatic code sign-in runs before it tells the caller it is
+ * working. Long enough that a quick sign-in never reports anything, short
+ * enough to answer inside a client's request timeout.
+ */
+const AUTOMATIC_PENDING_NOTICE_MS = 15_000;
+/**
+ * How long Entra gets to offer a way to switch to a verification code before
+ * this flow gives up on typing one and waits for a phone approval like any
+ * other login. A tenant can show a challenge with no code method at all; the
+ * alternative to this fallback is polling a page nothing will ever click for
+ * the full five minutes.
+ */
+const AUTOMATIC_FALLBACK_MS = 30_000;
+/** Where Entra prints the account it believes is signing in. */
+const ACCOUNT_LABEL_SELECTORS = ["#displayName", "#signInName", "#userDisplayName"];
 /** Microsoft expects Purdue's full sign-in name, while setup also accepts a career account. */
 function signInName(username, baseUrl) {
     const isPurdue = baseUrl && new URL(baseUrl).hostname.toLowerCase() === "purdue.brightspace.com";
@@ -112,6 +152,8 @@ function signInName(username, baseUrl) {
 export class PurdueSSOFlow {
     config;
     accountHintSubmitted = false;
+    /** Method-switch controls already clicked this login; each is clicked at most once. */
+    methodClicked = new Set();
     /** Authenticator codes asked for during this login. See submitMfaCode. */
     mfaCodeAttempts = 0;
     /**
@@ -344,8 +386,29 @@ export class PurdueSSOFlow {
         if (!this.config.baseUrl) {
             throw new UnsupportedAuthenticationError("A school URL is required to verify authentication.");
         }
-        const deadline = Date.now() + MFA_TIMEOUT_MS;
+        const startedAt = Date.now();
+        const deadline = startedAt + MFA_TIMEOUT_MS;
         let challenged = false;
+        /**
+         * True once this login has told the user to go approve something. Only
+         * then is a timeout really a missed approval; an automatic code sign-in
+         * that stalls must not be reported as one.
+         */
+        let manualChallenged = false;
+        /** True once automatic code entry applied to a poll of this login. */
+        let automaticEngaged = false;
+        /** True once onAutomaticPending has reported this login. */
+        let automaticAnnounced = false;
+        /**
+         * True once Entra has had AUTOMATIC_FALLBACK_MS to offer a way to switch
+         * to a verification code and offered none. One-way: from then on this
+         * login announces and waits exactly as it would with no enrollment saved.
+         */
+        let methodSwitchExhausted = false;
+        /** "Use your password instead" clicks this login; capped so a page that keeps offering it cannot loop. */
+        let passwordSwitches = 0;
+        /** True once Duo answered a challenge: Duo's codes are not Entra's. */
+        let duoChallengeObserved = false;
         let announced = null;
         /** True once onMfaChallenge has been told about this login, number or not. */
         let announcedToCaller = false;
@@ -371,10 +434,46 @@ export class PurdueSSOFlow {
                     log("INFO", "Login successful - verified Brightspace home");
                     return;
                 }
-                if (await this.duoMfa.handle(page))
+                if (await this.duoMfa.handle(page)) {
                     challenged = true;
-                if (await this.submitMfaCode(page))
+                    manualChallenged = true;
+                    duoChallengeObserved = true;
+                }
+                // Passwordless phone sign-in in place of the password page. Once an
+                // account turns on phone sign-in in Authenticator, Entra answers the
+                // username with its approval view, where automaticCodeApplicable rightly
+                // refuses to type a code: the phone is the FIRST factor there. Only
+                // after the password does Entra ask for a second factor a code can
+                // answer. So with an enrollment AND a password saved, and the
+                // passwordless option off, take "Use your password instead". Without an
+                // enrollment the approval view is left to the phone exactly as before.
+                // Seen live on Purdue's tenant on 2026-10-09 (iclicker-automation#6).
+                if (this.config.totpUri && this.config.password && !this.config.passwordless &&
+                    passwordSwitches < 2 && await this.anyVisible(page, [PASSWORDLESS_SWITCH_SELECTOR])) {
+                    passwordSwitches += 1;
+                    log("INFO", "Microsoft offered passwordless phone sign-in; using the saved password so the authenticator code can answer MFA.");
+                    await this.clickWhenReady(page, [PASSWORDLESS_SWITCH_SELECTOR]);
+                    if (await this.fillWhenReady(page, PASSWORD_SELECTORS, this.config.password)) {
+                        await this.clickWhenReady(page, SUBMIT_SELECTORS);
+                    }
+                    await page.waitForTimeout(METHOD_SWITCH_SETTLE_MS);
+                    continue;
+                }
+                // Whether this poll may answer the challenge itself. Recomputed every
+                // poll, because the page — and so the identity provider and method on
+                // screen — can change under us.
+                const automatic = await this.automaticCodeApplicable(page, duoChallengeObserved, methodSwitchExhausted);
+                if (automatic)
+                    automaticEngaged = true;
+                if (await this.submitMfaCode(page, automatic))
                     challenged = true;
+                const switched = automatic ? await this.selectCodeMethod(page) : "skipped";
+                if (switched === "clicked") {
+                    await page.waitForTimeout(METHOD_SWITCH_SETTLE_MS);
+                    continue;
+                }
+                /** False while this poll is answering the challenge on the user's behalf. */
+                const manualRequired = !automatic;
                 const number = await this.readNumberMatch(page);
                 if (number)
                     sawNumber = true;
@@ -382,6 +481,13 @@ export class PurdueSSOFlow {
                     await page.locator("#idDiv_SAOTCAS_Title").first().isVisible().catch(() => false) ||
                     await page.locator("#idDiv_SAOTCC_Title").first().isVisible().catch(() => false) ||
                     await this.anyVisible(page, PASSWORDLESS_APPROVAL_SELECTORS);
+                // Entra showed a challenge but never a way to type a code. Stop
+                // waiting for one and fall back to the announce-and-approve path this
+                // flow has always used, rather than polling a dead page for 5 minutes.
+                if (switched === "noSwitch" && challengeVisible && Date.now() - startedAt >= AUTOMATIC_FALLBACK_MS) {
+                    methodSwitchExhausted = true;
+                    log("WARN", "Microsoft offered no way to enter a verification code; waiting for approval on your device instead.");
+                }
                 // With no password saved, a password page can only end in a timeout.
                 if (this.config.passwordless && !this.config.password && !challengeVisible && await this.isPasswordOnlyPage(page))
                     this.savedPassword();
@@ -389,14 +495,15 @@ export class PurdueSSOFlow {
                 // the existing poll without delaying the first challenge announcement.
                 if (challengeVisible)
                     await this.rememberMfaDevice(page);
-                if (challengeVisible && !challenged) {
+                if (challengeVisible && !challenged && manualRequired) {
                     challenged = true;
+                    manualChallenged = true;
                     log("WARN", "Waiting up to 5 minutes for Microsoft MFA approval on your device.");
                     this.config.onMfaChallenge?.(number);
                     announcedToCaller = true;
                     lastAnnouncedNumber = number;
                 }
-                if (number && number !== announced) {
+                if (number && number !== announced && manualRequired) {
                     announced = number;
                     log("WARN", `Number match: ${number}. Enter it in Microsoft Authenticator.`);
                     if (!announcedToCaller || number !== lastAnnouncedNumber) {
@@ -415,7 +522,7 @@ export class PurdueSSOFlow {
                 // request until MFA_TIMEOUT_MS; readNumberMatch on the next poll
                 // picks up the fresh number, and the re-announce logic above tells
                 // the caller about it.
-                if (sawNumber && number === null && new URL(page.url()).hostname === "login.microsoftonline.com") {
+                if (manualRequired && sawNumber && number === null && new URL(page.url()).hostname === "login.microsoftonline.com") {
                     if (numberVanishedAt === null)
                         numberVanishedAt = Date.now();
                     resendNotFoundWarned = await this.tryResendNumberMatch(page, {
@@ -429,6 +536,10 @@ export class PurdueSSOFlow {
                         },
                     });
                 }
+                if (automatic && !automaticAnnounced && Date.now() - startedAt >= AUTOMATIC_PENDING_NOTICE_MS) {
+                    automaticAnnounced = true;
+                    this.config.onAutomaticPending?.();
+                }
                 await this.clickProvenKmsi(page);
                 // The federated-domain trust prompt arrives after the IdP succeeds, so
                 // it has to be caught by this loop rather than by enterCredentials.
@@ -439,10 +550,19 @@ export class PurdueSSOFlow {
         catch (error) {
             if (error instanceof BrowserAuthError)
                 throw error;
+            // An automatic sign-in that never asked the user for anything is not a
+            // missed approval, so it must not be reported as one — unless this
+            // login fell back and really did ask (manualChallenged).
+            if (automaticEngaged && !manualChallenged) {
+                throw new AutomaticCodeAuthenticationError("Automatic code sign-in stopped before Brightspace was verified.", error);
+            }
             if (challenged)
                 throw new MfaApprovalError(error, announced ?? undefined);
             throw new UnsupportedAuthenticationError("Automatic sign-in stopped before a supported MFA challenge completed.", error);
         }
+        if (automaticEngaged && !manualChallenged) {
+            throw new AutomaticCodeAuthenticationError("Automatic code sign-in did not reach a verified Brightspace session within 5 minutes.");
+        }
         if (challenged)
             throw new MfaApprovalError(undefined, announced ?? undefined);
         throw new UnsupportedAuthenticationError("Sign-in did not reach a supported MFA challenge or Brightspace within 5 minutes.");
@@ -494,11 +614,19 @@ export class PurdueSSOFlow {
         }
         return null;
     }
-    async submitMfaCode(page) {
+    /**
+     * Submit a verification code, from the saved enrollment when `automatic` is
+     * set and otherwise from the user at the terminal. `automatic` is decided
+     * per poll by automaticCodeApplicable; with no enrollment saved it is always
+     * false and every line below behaves as it did before.
+     */
+    async submitMfaCode(page, automatic = false) {
         const input = await this.firstVisible(page, MFA_CODE_SELECTORS);
         if (!input)
             return false;
-        if (this.config.headless === false)
+        // A visible browser leaves code entry to the user — unless the code can be
+        // generated here, in which case there is nothing for them to type.
+        if (this.config.headless === false && !automatic)
             return false;
         // Ask again only after Entra's rejection message. This runs on every
         // two-second poll, and Microsoft commonly leaves the field on screen while
@@ -523,15 +651,32 @@ export class PurdueSSOFlow {
             if (this.mfaCodeAttempts >= MAX_MFA_CODE_ATTEMPTS) {
                 throw new BrowserAuthError(`Microsoft rejected ${this.mfaCodeAttempts} authenticator codes. Run \`${AUTH_COMMAND}\` to try again.`, "mfa_code");
             }
-            log("WARN", "Microsoft rejected that code. Enter the current one from your authenticator app.");
+            log("WARN", automatic
+                ? "Microsoft rejected the code; waiting for a fresh one before retrying."
+                : "Microsoft rejected that code. Enter the current one from your authenticator app.");
         }
-        if (!this.config.requestMfaCode) {
+        if (!automatic && !this.config.requestMfaCode) {
             throw new UnsupportedAuthenticationError(`This MFA method requires a code. Run \`${AUTH_COMMAND}\` in a terminal to enter it.`);
         }
         await this.rememberMfaDevice(page);
         this.mfaCodeAttempts += 1;
         this.awaitingMfaCodeSettle = isRetry;
-        const code = await this.config.requestMfaCode();
+        let code;
+        if (automatic) {
+            // Refuse to type a code to a page that is not showing this account.
+            await this.assertExpectedMicrosoftAccount(page);
+            // Resubmitting the rejected code would be rejected again, and a code in
+            // its last seconds expires while Entra validates it, so wait out the
+            // rest of the period in both cases. Entra's own form stays on screen
+            // meanwhile, and the 5-minute budget is checked between polls.
+            const remaining = secondsUntilFreshCode(this.config.totpUri);
+            if (isRetry || remaining < MIN_CODE_LIFETIME_S)
+                await page.waitForTimeout(Math.ceil(remaining * 1000) + 100);
+            code = generateTotp(this.config.totpUri);
+        }
+        else {
+            code = await this.config.requestMfaCode();
+        }
         if (!/^\d{6,8}$/.test(code))
             throw new UnsupportedAuthenticationError("The MFA code must contain 6-8 digits.");
         await input.fill(code);
@@ -541,8 +686,82 @@ export class PurdueSSOFlow {
         else
             await input.press("Enter");
         log("INFO", "Authenticator code submitted");
+        // The code itself is never logged, here or anywhere else.
+        if (automatic)
+            devActivity("mfa_code_submitted");
         return true;
     }
+    /**
+     * Whether this poll may answer the challenge from the saved enrollment.
+     *
+     * Gated on the identity provider and the challenge on screen, never on a
+     * school's URL: only Microsoft Entra's verification-code form is driven
+     * here, so the test is whether Entra is the page in front of us.
+     *
+     * - no saved enrollment: always false, and not one extra page query is made
+     * - Duo answered a challenge: Duo codes come from a different enrollment
+     * - Entra's passwordless approval view: the phone IS the first factor there,
+     *   and a code cannot stand in for it (see the passwordless option, #206)
+     * - Entra never offered a code method: fall back to announce-and-approve
+     */
+    async automaticCodeApplicable(page, duoObserved, exhausted) {
+        if (!this.config.totpUri || duoObserved || exhausted)
+            return false;
+        if (new URL(page.url()).hostname !== "login.microsoftonline.com")
+            return false;
+        return !await this.anyVisible(page, PASSWORDLESS_APPROVAL_SELECTORS);
+    }
+    /**
+     * Move Entra from whatever method it defaulted to onto its verification-code
+     * form, one control per login at most.
+     *
+     * - `codeForm`: the form is already up; submitMfaCode owns it
+     * - `spent`: a code has already been submitted, so nothing more to switch to
+     * - `clicked`: a method control was clicked; re-poll the new page
+     * - `noSwitch`: Entra is offering no way to reach a code
+     */
+    async selectCodeMethod(page) {
+        if (await this.firstVisible(page, MFA_CODE_SELECTORS))
+            return "codeForm";
+        if (this.mfaCodeAttempts > 0)
+            return "spent";
+        await this.assertExpectedMicrosoftAccount(page);
+        for (const [step, label] of CODE_METHOD_STEPS) {
+            if (this.methodClicked.has(step))
+                continue;
+            const control = page.getByText(label).first();
+            if (!await control.isVisible().catch(() => false))
+                continue;
+            this.methodClicked.add(step);
+            await control.click();
+            devActivity("mfa_method_selected");
+            return "clicked";
+        }
+        return "noSwitch";
+    }
+    /**
+     * Refuse to drive Entra's method pages, or type a code into them, unless
+     * this really is Microsoft showing the account we are signing in as. A code
+     * typed into someone else's session is a second factor handed to them.
+     */
+    async assertExpectedMicrosoftAccount(page) {
+        if (new URL(page.url()).hostname !== "login.microsoftonline.com" || !this.config.username) {
+            throw new UnsupportedAuthenticationError("Automatic code entry requires Microsoft's own sign-in page and a configured account.");
+        }
+        const expected = signInName(this.config.username, this.config.baseUrl).toLowerCase();
+        for (const selector of ACCOUNT_LABEL_SELECTORS) {
+            const account = page.locator(selector).first();
+            // These are alternative layouts, not required controls, and textContent()
+            // auto-waits a missing element out for 30 seconds on every MFA poll.
+            if (await account.count() === 0)
+                continue;
+            const value = await account.textContent({ timeout: 1000 }).catch(() => null);
+            const shown = value?.match(/[\w.+-]+@[\w.-]+\.[a-z]{2,}/i)?.[0]?.toLowerCase();
+            if (shown && shown !== expected) {
+                throw new UnsupportedAuthenticationError("Microsoft is showing another account. Automatic code entry stopped.");
+            }
+        }
+    }
     /**
      * Tick Entra's "Don't ask again" box once; retry absent controls on later MFA polls.
      * Opt-in: without an explicit true the box is left alone and the outcome

package/build/auth/sso-flow.js

@@ -20,6 +20,15 @@ export class UnsupportedAuthenticationError extends BrowserAuthError {
         this.name = "UnsupportedAuthenticationError";
     }
 }
+/**
+ * An automatic verification-code sign-in that never reached Brightspace.
+ * Distinct from MfaApprovalError because nobody was ever asked to approve
+ * anything: telling the user to check their phone would be a lie, and the
+ * caller-facing guidance has to say "still working" instead.
+ * Idea from ElliotDrel/brightspace-mcp-server (branch codex/purdue-totp).
+ */
+export class AutomaticCodeAuthenticationError extends UnsupportedAuthenticationError {
+}
 export class MfaApprovalError extends BrowserAuthError {
     code = "AUTH_MFA_FAILED";
     /**
@@ -40,16 +49,24 @@ export class MfaApprovalError extends BrowserAuthError {
  * else uses the default flow, which already covers the common Shibboleth,
  * CAS, and Microsoft Entra forms.
  */
-export function createSSOFlow(config, requestMfaCode, onMfaChallenge) {
+export function createSSOFlow(config, requestMfaCode, onMfaChallenge, onAutomaticPending) {
     const credentials = {
         username: config.username,
         password: config.password,
+        // Handed to every flow, gated by none: the enrollment is saved per
+        // account, and the only code that reads it answers Microsoft Entra's
+        // verification-code form on login.microsoftonline.com. Gating on a
+        // school's own URL instead would hard-code one tenant into a
+        // school-agnostic server, and would still be the wrong test — what
+        // matters is the identity provider and the challenge it is showing.
+        totpUri: config.totpUri,
         baseUrl: config.baseUrl,
         headless: config.headless,
         rememberMfa: config.rememberMfa,
         passwordless: config.passwordless,
         requestMfaCode,
         onMfaChallenge,
+        onAutomaticPending,
     };
     if (isTUDelftBrightspace(config.baseUrl)) {
         return new TUDelftSSOFlow(credentials);

package/build/auth/totp.js

@@ -0,0 +1,83 @@
+/**
+ * Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ *
+ * RFC 6238 time-based one-time passwords, generated locally from an
+ * enrollment the user saved themselves. Ported from
+ * ElliotDrel/brightspace-mcp-server (branch codex/purdue-totp, PR #54).
+ *
+ * This is the SECOND factor, so the seed sitting beside the password on one
+ * machine collapses two factors into one THERE: it still defeats a remote
+ * attacker who has only the password, and it defends against nothing already
+ * running as this user. That is why it is opt-in and off by default — nothing
+ * here runs unless the user deliberately saved an enrollment.
+ */
+import { createHmac } from "node:crypto";
+function parseEnrollment(uri) {
+    let url;
+    try {
+        url = new URL(uri);
+    }
+    catch {
+        throw new Error("Invalid authenticator enrollment URI.");
+    }
+    const secret = url.searchParams.get("secret")?.toUpperCase().replace(/\s/g, "") ?? "";
+    const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+    if (url.protocol !== "otpauth:" || url.hostname !== "totp" || !/^[A-Z2-7]+=*$/.test(secret)) {
+        throw new Error("Invalid authenticator enrollment URI.");
+    }
+    const raw = secret.replace(/=+$/, "");
+    let bits = 0, buffer = 0;
+    const bytes = [];
+    for (const char of raw) {
+        buffer = (buffer << 5) | alphabet.indexOf(char);
+        bits += 5;
+        if (bits >= 8) {
+            bits -= 8;
+            bytes.push((buffer >>> bits) & 255);
+            buffer &= (1 << bits) - 1;
+        }
+    }
+    const algorithm = (url.searchParams.get("algorithm") ?? "SHA1").toLowerCase();
+    const digits = Number(url.searchParams.get("digits") ?? "6");
+    const period = Number(url.searchParams.get("period") ?? "30");
+    if (bytes.length < 10 || buffer !== 0 || !["sha1", "sha256", "sha512"].includes(algorithm)
+        || ![6, 7, 8].includes(digits) || !Number.isSafeInteger(period) || period <= 0) {
+        throw new Error("Invalid authenticator enrollment URI.");
+    }
+    return { secret: Buffer.from(bytes), algorithm: algorithm, digits, period };
+}
+/**
+ * Accept either a full `otpauth://` URI (what a QR code encodes) or the bare
+ * base32 setup key Microsoft shows behind "Can't scan image?", and return the
+ * canonical URI to store. A bare key is wrapped under the account's own name:
+ * no school or issuer is baked in, because the enrollment belongs to one
+ * account at one school, not to a particular tenant.
+ */
+export function normalizeTotpEnrollment(input, username) {
+    const trimmed = input.trim();
+    const key = trimmed.toUpperCase().replace(/\s/g, "");
+    const uri = trimmed.startsWith("otpauth://") ? trimmed
+        : `otpauth://totp/${encodeURIComponent(username || "account")}?secret=${key}`;
+    parseEnrollment(uri);
+    return uri;
+}
+/**
+ * Seconds of life left in the code on screen now. A code submitted in its
+ * last moments is rejected by the time Entra validates it, so the caller
+ * waits this out rather than spending one of its three attempts.
+ */
+export function secondsUntilFreshCode(uri, now = Date.now()) {
+    const { period } = parseEnrollment(uri);
+    return period - (now / 1000 % period);
+}
+export function generateTotp(uri, now = Date.now()) {
+    const { secret, algorithm, digits, period } = parseEnrollment(uri);
+    const counter = Buffer.alloc(8);
+    counter.writeBigUInt64BE(BigInt(Math.floor(now / 1000 / period)));
+    const digest = createHmac(algorithm, secret).update(counter).digest();
+    const offset = digest[digest.length - 1] & 15;
+    const value = (digest.readUInt32BE(offset) & 0x7fffffff) % 10 ** digits;
+    return String(value).padStart(digits, "0");
+}

package/build/auth-cli.js

@@ -12,7 +12,8 @@ import { NativeCredentialStoreError } from "./auth/credential-store.js";
 import { retireLegacyProfile } from "./auth/legacy-profile.js";
 import { formatPhaseMarker } from "./auth/auth-phases.js";
 import { AuthenticationInProgressError } from "./auth/auth-lock.js";
-import { challengeMarker } from "./auth/mfa-challenge.js";
+import { AUTOMATIC_PENDING_MARKER, challengeMarker } from "./auth/mfa-challenge.js";
+import { configureDevActivity } from "./utils/dev-activity.js";
 import { AUTH_COMMAND, SETUP_COMMAND } from "./utils/commands.js";
 import { initUpdateChecker, peekUpdateNotice } from "./utils/update-checker.js";
 import { reexecLatestIfStale } from "./utils/self-update.js";
@@ -49,6 +50,9 @@ async function main() {
     const skewCheck = detectSkew(pkg.version);
     try {
         const config = await loadConfig();
+        // The sign-in itself runs here, not in the server, so the dev activity log
+        // only sees its MFA events if this process is configured for them too.
+        configureDevActivity(config.sessionDir);
         console.error(`\n=== Brightspace Authentication v${pkg.version} ===\n`);
         console.error(config.headless
             ? "Authentication runs headlessly. MFA numbers and code prompts appear here."
@@ -70,7 +74,13 @@ async function main() {
         const onPhase = automatic
             ? (phase, elapsedMs) => console.log(formatPhaseMarker(phase, elapsedMs))
             : undefined;
-        await new BrowserAuth(config, { requestMfaCode: codePrompt, onMfaChallenge, onPhase }).authenticate({
+        // No digits and nothing to approve: just "this sign-in is answering its
+        // own verification code", so the parent can say so instead of sending the
+        // user to their phone.
+        const onAutomaticPending = automatic
+            ? () => console.log(AUTOMATIC_PENDING_MARKER)
+            : undefined;
+        await new BrowserAuth(config, { requestMfaCode: codePrompt, onMfaChallenge, onPhase, onAutomaticPending }).authenticate({
             automatic,
             onAuthenticated: async (token) => {
                 await tokenManager.setToken(token);
@@ -95,7 +105,9 @@ async function main() {
         // Another process's sign-in holds the lock and is showing a challenge:
         // pass it on, so this caller can tell its user what to approve.
         if (automatic && error instanceof AuthenticationInProgressError && error.challenge) {
-            console.log(challengeMarker(error.challenge.numberMatch));
+            console.log(error.challenge.kind === "automatic"
+                ? AUTOMATIC_PENDING_MARKER
+                : challengeMarker(error.challenge.numberMatch));
         }
         process.exitCode = error instanceof NativeCredentialStoreError ? 5
             : code === "AUTH_IN_PROGRESS" ? 2

package/build/setup.js

@@ -14,6 +14,7 @@ import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { configStoreExists, getConfigStorePath, loadConfigStore, } from "./utils/config-store.js";
 import { saveSecureConfig } from "./utils/secure-config.js";
+import { normalizeTotpEnrollment } from "./auth/totp.js";
 import { writeFileAtomicSync } from "./utils/atomic-write.js";
 import { AUTH_COMMAND, DOCTOR_COMMAND } from "./utils/commands.js";
 import { classifyRegistration, cliMcpClients, inspectCliMcpClient, isCliAvailable, registerCliMcpClient, serverCommand, } from "./utils/mcp-client-cli.js";
@@ -360,6 +361,10 @@ export function buildConfigToSave(existing, answers) {
         // Always the freshly typed one: a carried v1 plaintext password would
         // otherwise be the value written to the native store.
         password: answers.passwordless ? undefined : answers.password,
+        // Only ever the freshly typed one. Never read back out of `carried`: the
+        // enrollment lives in the credential store, never in config.json, so a
+        // value here could only have come from this run.
+        ...(answers.totpUri ? { totpUri: answers.totpUri } : {}),
         headless: answers.headless,
     };
     if (answers.rememberMfa !== undefined)
@@ -528,6 +533,29 @@ async function main() {
         }
         console.log("");
     }
+    // ── Step 3b: Authenticator enrollment (hidden, optional) ─────────
+    // Opt-in and off by default. Asked without naming a school: whether a code
+    // can be typed depends on the identity provider and the challenge it shows,
+    // which is only known at sign-in time.
+    console.log(dim("  Optional. If your school asks for a 6-digit code from an authenticator app, this computer can generate it"));
+    console.log(dim("  for you, so automatic sign-ins need nothing from your phone. Paste the SETUP KEY (or otpauth:// link) you"));
+    console.log(dim("  got when enrolling the app — a code showing on screen right now will not work."));
+    console.log(dim("  The tradeoff: the key is stored beside your password, so on THIS computer the two factors become one."));
+    console.log(dim("  It still stops anyone who only has your password. Press Enter to skip, or to keep a key you saved before."));
+    let totpUri;
+    while (true) {
+        const input = await askPassword("  Authenticator setup key or otpauth:// link (optional): ");
+        if (!input)
+            break;
+        try {
+            totpUri = normalizeTotpEnrollment(input, username);
+            break;
+        }
+        catch {
+            console.log(yellow("  That is not a setup key or otpauth:// link. Paste the enrollment key, or press Enter to skip."));
+        }
+    }
+    console.log("");
     // Re-open readline for remaining prompts
     let rl2 = readline.createInterface({
         input: process.stdin,
@@ -590,6 +618,7 @@ async function main() {
         baseUrl,
         username,
         password,
+        totpUri,
         headless,
         rememberMfa,
         passwordless,
@@ -599,6 +628,8 @@ async function main() {
     console.log(green(passwordless
         ? "  No password saved: each sign-in will wait for your phone approval."
         : "  Password saved in your operating system credential store."));
+    if (totpUri)
+        console.log(green("  Authenticator enrollment saved in your operating system credential store."));
     console.log(green("  Config saved to: " + getConfigStorePath()));
     console.log("");
     // ── Step 6: Authenticate now? ────────────────────────────────────

package/build/tools/tool-helpers.js

@@ -105,6 +105,10 @@ const AUTH_FAILURE_GUIDANCE = {
         `Run \`${AUTH_COMMAND}\` in a terminal (from your home folder) to complete it with the number visible.`,
     failed: `The sign-in did not complete. Run \`${AUTH_COMMAND}\` in a terminal (from your home folder) to see why, ` +
         "or `brightspace-setup` if your saved school or username is wrong.",
+    automaticPending: "Brightspace sign-in is answering its own verification code from the saved authenticator " +
+        "enrollment. No phone approval is being requested, so don't ask the user to approve anything. " +
+        "Call this tool again right away: the next call joins the same sign-in and returns the result " +
+        "as soon as it completes.",
     mfaPending: "Approve the sign-in request on your phone (Microsoft Authenticator or Duo). " +
         "Tell the user that, then call this tool again right away without waiting for them to " +
         "confirm: each call waits up to 45 seconds for the approval and returns the result as soon " +
@@ -124,12 +128,17 @@ const AUTH_FAILURE_GUIDANCE = {
  */
 const MFA_ALREADY_REPORTED = "Brightspace sign-in is already in progress; another call in this batch has the number to " +
     "approve. Retry this call once the sign-in completes.";
+const AUTOMATIC_ALREADY_REPORTED = "Brightspace sign-in is already in progress, answering its own verification code; another call " +
+    "in this batch has the details. Retry this call once the sign-in completes. Don't ask the user " +
+    "to approve anything.";
 function authFailureMessage(error) {
     // Another call in this parallel batch already carries the number and the
     // instructions (issue #212). Repeating them in every response made a batch
     // unreadable; one short line is enough for this call.
     if (error.kind === "mfaPending" && error.duplicate)
         return MFA_ALREADY_REPORTED;
+    if (error.kind === "automaticPending" && error.duplicate)
+        return AUTOMATIC_ALREADY_REPORTED;
     if (error.kind === "mfaPending" && error.numberMatch) {
         return `Open Microsoft Authenticator and enter ${error.numberMatch} within 5 minutes. ` +
             "Tell the user that number, then call this tool again right away without waiting for them " +

package/build/utils/config-store.js

@@ -17,8 +17,8 @@ export function loadConfigStore() {
     return JSON.parse(raw);
 }
 export function saveConfigStore(config) {
-    if (config.password !== undefined) {
-        throw new Error("Passwords must be saved in the native credential store before saving configuration.");
+    if (config.password !== undefined || config.totpUri !== undefined) {
+        throw new Error("Secrets must be saved in the native credential store before saving configuration.");
     }
     const isWindows = process.platform === "win32";
     if (!fs.existsSync(CONFIG_DIR)) {

package/build/utils/config.js

@@ -9,6 +9,8 @@ import { createHash } from "node:crypto";
 import dotenv from "dotenv";
 import { configStoreExists, getConfigStorePath, loadConfigStore } from "./config-store.js";
 import { resolveStoredPassword } from "./secure-config.js";
+import { getStoredTotpUri } from "../auth/credential-store.js";
+import { normalizeTotpEnrollment } from "../auth/totp.js";
 import { migrateLegacyState } from "../auth/legacy-state.js";
 export async function loadConfig() {
     dotenv.config({ quiet: true });
@@ -94,6 +96,20 @@ export async function loadConfig() {
     const baseUrl = configuredUrl.origin;
     const username = process.env.D2L_USERNAME || store?.username;
     const password = passwordless ? undefined : await resolveStoredPassword(baseUrl, username, store);
+    // Opt-in: only an enrollment the user deliberately saved makes the Entra
+    // sign-in answer a verification-code challenge itself. With none, every MFA
+    // challenge is handled exactly as before. The keyring entry is per account;
+    // D2L_TOTP_SECRET exists for CI and containers, where there is no keyring,
+    // and is deliberately weaker (see .env.example) so it is never the default.
+    const envTotpSecret = readEnvSecret(process.env.D2L_TOTP_SECRET, "D2L_TOTP_SECRET");
+    const totpUri = envTotpSecret
+        ? normalizeTotpEnrollment(envTotpSecret, username ?? "")
+        // A credential store that cannot be read means "no enrollment saved",
+        // which is the default anyway. It must never be a startup failure: this is
+        // an optional extra, and resolveStoredPassword above is already the place
+        // that reports a locked or missing store, loudly, for the credential the
+        // server genuinely cannot work without.
+        : username ? (await getStoredTotpUri(baseUrl, username).catch(() => null)) ?? undefined : undefined;
     // A new account must never inherit another account's cookies, even at the same school.
     const sessionDir = accountSessionDirectory(sessionRoot, baseUrl, username);
     const legacyMigration = sessionDir !== sessionRoot ? await migrateLegacyState(sessionRoot) : undefined;
@@ -108,6 +124,7 @@ export async function loadConfig() {
         passwordless,
         username,
         password,
+        totpUri,
         campus: process.env.D2L_CAMPUS || store?.campus,
         envAccessToken,
         envSessionCookie,

package/build/utils/dev-activity.js

@@ -24,7 +24,8 @@ function write(event, fields, context = calls.getStore(), idleMs, sinceSuccessMs
     if (!directory)
         return;
     if (!["tool_started", "tool_finished", "http_response", "auth_required", "token_mint_started",
-        "token_mint_finished", "recovery_started", "mfa_observed", "recovery_finished", "auth_phase"].includes(event))
+        "token_mint_finished", "recovery_started", "mfa_observed", "recovery_finished", "auth_phase",
+        "mfa_method_selected", "mfa_code_submitted"].includes(event))
         return;
     const at = new Date().toISOString();
     const record = { at, runId, pid: process.pid, event };
@@ -36,7 +37,8 @@ function write(event, fields, context = calls.getStore(), idleMs, sinceSuccessMs
     }
     if (["success", "error", "sessionExpired", "transport"].includes(fields.outcome ?? ""))
         record.outcome = fields.outcome;
-    if (["busy", "cooldown", "unsupported", "secureStorage", "transport", "timeout", "failed", "mfaPending"].includes(fields.reason ?? ""))
+    if (["busy", "cooldown", "unsupported", "secureStorage", "transport", "timeout", "failed", "mfaPending",
+        "automaticPending", "inProgress"].includes(fields.reason ?? ""))
         record.reason = fields.reason;
     if (AUTH_PHASES.includes(fields.phase ?? ""))
         record.phase = fields.phase;

package/build/utils/secure-config.js

@@ -1,6 +1,7 @@
-import { deleteStoredPassword, getStoredPassword, setStoredPassword } from "../auth/credential-store.js";
+import { deleteStoredPassword, getStoredPassword, getStoredTotpUri, setStoredPassword, setStoredTotpUri } from "../auth/credential-store.js";
 import * as path from "node:path";
 import { acquireProcessLock } from "../auth/auth-lock.js";
+import { normalizeTotpEnrollment } from "../auth/totp.js";
 import { configStoreExists, getConfigStorePath, loadConfigStore, saveConfigStore } from "./config-store.js";
 async function withConfigWriteLock(operation) {
     const release = await acquireProcessLock(path.join(path.dirname(getConfigStorePath()), ".config-write.lock"));
@@ -16,7 +17,7 @@ export async function saveSecureConfig(config) {
     await withConfigWriteLock(() => saveSecureConfigUnlocked(config));
 }
 async function saveSecureConfigUnlocked(config) {
-    const { password, ...publicConfig } = config;
+    const { password, totpUri, ...publicConfig } = config;
     if (publicConfig.baseUrl) {
         const url = new URL(publicConfig.baseUrl);
         if (url.protocol !== "https:" || url.username || url.password) {
@@ -24,6 +25,16 @@ async function saveSecureConfigUnlocked(config) {
         }
         publicConfig.baseUrl = url.origin;
     }
+    // Both secrets are validated before EITHER is written, so a mistyped
+    // enrollment cannot replace the saved password and then fail halfway
+    // through setup. The enrollment is keyed to one account at one school, so
+    // it needs both; no school is singled out — the Entra sign-in flow decides
+    // on its own whether a code can be typed.
+    // Idea from ElliotDrel/brightspace-mcp-server (branch codex/purdue-totp).
+    const enrollment = totpUri === undefined ? undefined : normalizeTotpEnrollment(totpUri, config.username ?? "");
+    if (enrollment !== undefined && (!config.baseUrl || !config.username)) {
+        throw new Error("An authenticator enrollment requires a school URL and username.");
+    }
     if (password !== undefined) {
         if (!config.baseUrl || !config.username || !password) {
             throw new Error("A school URL, username, and nonempty password are required.");
@@ -33,6 +44,12 @@ async function saveSecureConfigUnlocked(config) {
             throw new Error("Could not verify the password in the native credential store. Configuration was preserved.");
         }
     }
+    if (enrollment !== undefined) {
+        await setStoredTotpUri(config.baseUrl, config.username, enrollment);
+        if (await getStoredTotpUri(config.baseUrl, config.username) !== enrollment) {
+            throw new Error("Could not verify the authenticator enrollment in the native credential store. Configuration was preserved.");
+        }
+    }
     if (publicConfig.passwordless && config.baseUrl && config.username) {
         await deleteStoredPassword(config.baseUrl, config.username);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brightspace-mcp-server",
-  "version": "3.12.3",
+  "version": "3.13.0",
   "mcpName": "io.github.RohanMuppa/brightspace",
   "description": "MCP server for Brightspace (D2L). Check grades, due dates, assignments, announcements, syllabus, rosters and more via Claude, ChatGPT, Cursor, Windsurf, or any MCP client.",
   "type": "module",