@msout/microsoft-webauth 0.1.1 → 0.1.4

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 enoola/phptr/msout
+Copyright (c) 2026 msout@tuta.io
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/NOTICE.md

@@ -0,0 +1,63 @@
+# NOTICE
+
+## License
+
+This project is released under the **MIT License**. See [LICENSE](LICENSE) for
+the full text.
+
+## Commercial use
+
+The MIT License grants anyone the right to use, copy, modify, merge, publish,
+distribute, sublicense and sell copies of this software, including for
+commercial purposes. **No permission is required, and none is withheld.**
+
+This NOTICE cannot add conditions to the MIT License, and does not attempt to.
+If you are reading this hoping it sets rules, it does not: the terms in
+[LICENSE](LICENSE) are the terms.
+
+**A courtesy request, not a restriction:** if you use this commercially, or build
+on it in a way you make money from, please **let the author know** — an issue or
+a note is welcome. This is a request out of interest in the project, not a
+condition of use. Nobody can enforce it, and no licence condition depends on it.
+
+## Attribution
+
+The copyright notice and the MIT permission notice must be retained in all
+copies or substantial portions of the Software. Keeping the author's name in the
+files is the one real obligation MIT does impose, and the reason the author
+field is populated in `package.json` for every package in this organisation.
+
+## Paid features
+
+If a paid or hosted version of this tool ever appears, it will be paid for as a
+**service** — hosting, support, or convenience — never as a licence condition.
+The code in this repository stays MIT for everyone, permanently. A licence
+cannot be both permissively open and conditional, so the open-source grant is
+not something that will ever be withdrawn or moved behind a paywall.
+
+## Origin
+
+Extracted from [MSOneNote Exporter](https://github.com/enoola/Microsoft-OneNote-Exporter).
+Sibling packages: [microsoft-onenote-list-notebooks](https://github.com/Ms-OneNote-Exporter/microsoft-onenote-list-notebooks),
+[microsoft-onenote-export-notebook](https://github.com/Ms-OneNote-Exporter/microsoft-onenote-export-notebook),
+[microsoft-outlook-list-emails](https://github.com/Ms-OneNote-Exporter/microsoft-outlook-list-emails).
+
+## Why this project exists
+
+Microsoft does not provide a convenient way to export a whole OneNote notebook,
+and the Graph API path is not a usable substitute: it caps page retrieval and
+requires Entra admin rights. This tool produces the authenticated session state
+those other tools consume, using Playwright instead of the Graph API.
+
+It deliberately does **not** rely on Graph, and it deliberately does not ask you
+to hand it your password in a hosted web form. Authentication state is written
+to a local file (`auth-file.json`, mode `600`) that you own, can inspect, and can
+delete at any time.
+
+## Handling of credentials
+
+`auth-file.json` contains a Playwright `storageState` — live session cookies.
+Anyone who reads that file can act as you until the session expires. Treat it
+like a password file: do not commit it, do not upload it to a service you do not
+control, and delete it when you are done. The default path is under
+`~/.microsoft-webauth/`, outside any repository.

package/README.md

@@ -166,5 +166,5 @@ microsoft-webauth-playwright/
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT — see [LICENSE](LICENSE), and read [NOTICE.md](NOTICE.md).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msout/microsoft-webauth",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "Microsoft web authentication module, using playwright to automate the login process and retrieve cookies for authenticated sessions.",
   "main": "src/index.js",
   "bin": {

package/src/auth.js

@@ -116,6 +116,52 @@ function promptUser(query) {
  * @param {import('playwright').Page} page - Playwright page object
  * @param {string} targetUrl - The target URL (ONENOTE_URL or OUTLOOK_URL)
  */
+/**
+ * The authenticated OneNote web app's path. It is not stable: the Microsoft 365
+ * Copilot rebrand moved it from /notebooks to /copilotnotebooks, and
+ * "/copilotnotebooks".includes("/notebooks") is false — so a substring check on
+ * "/notebooks" alone timed out on a login that had in fact fully succeeded, with
+ * the notebooks UI rendered and the account name on screen, and never saved the
+ * auth state.
+ *
+ * Both spellings are listed, and the "notebooks" component is still required so
+ * the unauthenticated marketing page (onenote.cloud.microsoft/en-us) can never
+ * satisfy this. A bare hostname check would, and did: it caused premature
+ * auth saving.
+ */
+const ONENOTE_APP_PATH = /\/copilotnotebooks\b|\/notebooks\b/;
+
+/** UI markers that only render once the session is actually signed in. */
+const ONENOTE_SIGNED_IN_MARKERS = [
+    'text="My notebooks"',
+    'text="Create new notebook"',
+    'text="All Notebooks"',
+    'text="Welcome, "'
+];
+
+/**
+ * Waits for the authenticated app, bounded by `timeoutMs` instead of the full
+ * production timeout. Returns whether it arrived, so it can be asserted on.
+ * @returns {Promise<boolean>}
+ */
+async function waitForAuthSuccessProbe(page, targetUrl, timeoutMs) {
+    const isOutlook = targetUrl && targetUrl.includes('outlook.cloud.microsoft');
+    const attempts = isOutlook
+        ? [
+            page.waitForSelector('[aria-label*="message list"], [role="grid"][aria-label*="mail"], .messageList', { state: 'visible', timeout: timeoutMs }),
+            page.waitForSelector('text=/Inbox|Sent Mail|Drafts/i', { state: 'visible', timeout: timeoutMs }),
+            page.waitForSelector('div[role="row"]', { state: 'visible', timeout: timeoutMs }),
+        ]
+        : [
+            page.waitForURL(url => ONENOTE_APP_PATH.test(url.toString()), { timeout: timeoutMs }),
+            ...ONENOTE_SIGNED_IN_MARKERS.map(marker =>
+                page.waitForSelector(marker, { state: 'visible', timeout: timeoutMs })),
+        ];
+
+    const won = await Promise.any(attempts.map(p => p.then(() => true))).catch(() => false);
+    return won;
+}
+
 async function waitForAuthSuccess(page, targetUrl) {
     const isOutlook = targetUrl && targetUrl.includes('outlook.cloud.microsoft');
 
@@ -131,18 +177,13 @@ async function waitForAuthSuccess(page, targetUrl) {
         ]);
         logger.success('Outlook mail interface detected.');
     } else {
-        // OneNote default behavior — wait for the authenticated notebooks interface.
-        // IMPORTANT: We must require /notebooks in the URL to avoid matching the
-        // unauthenticated marketing landing page (onenote.cloud.microsoft/en-us)
-        // which also matches the old hostname-only check and caused premature auth saving.
         logger.info('Waiting for redirection to authenticated notebooks interface...');
         await Promise.any([
-            // Primary: URL must contain /notebooks (authenticated app)
-            page.waitForURL(url => url.toString().includes('/notebooks'), { timeout: 60000 }),
+            // Primary: the URL must be the authenticated app, not the marketing page
+            page.waitForURL(url => ONENOTE_APP_PATH.test(url.toString()), { timeout: 60000 }),
             // Fallback UI elements that only appear when actually signed in
-            page.waitForSelector('text="My notebooks"', { state: 'visible', timeout: 60000 }),
-            page.waitForSelector('text="Create new notebook"', { state: 'visible', timeout: 60000 }),
-            page.waitForSelector('text="Welcome, "', { state: 'visible', timeout: 60000 }),
+            ...ONENOTE_SIGNED_IN_MARKERS.map(marker =>
+                page.waitForSelector(marker, { state: 'visible', timeout: 60000 })),
         ]);
         logger.success('Authenticated notebooks interface detected.');
     }
@@ -483,10 +524,7 @@ async function clearBlockingScreens(page, options = {}) {
         logger.info(`Blocking screen detected: ${screen.name} (${shortUrl(state.url)}). Accepting it...`);
 
         if (dodump) {
-            const dumpDir = await logger.getDumpDir();
-            const displayPath = logger.getDumpDisplayPath();
-            const debugFile = path.join(dumpDir, `debug_blocking_screen_${i + 1}.html`);
-            await fs.writeFile(debugFile, await page.content().catch(e => `<!-- Error: ${e.message} -->`));
+            const displayPath = await dumpPage(page, `debug_blocking_screen_${i + 1}.html`);
             logger.debug(`[dodump] Blocking screen state dumped to ${displayPath}/debug_blocking_screen_${i + 1}.html`);
         }
 
@@ -514,6 +552,435 @@ async function clearBlockingScreens(page, options = {}) {
     return { handled, reason: 'max_screens' };
 }
 
+/* ------------------------------------------------------------------------- *
+ * "How do you want to sign in?" — the screens between email and password
+ *
+ * For a passwordless-enabled account, Microsoft serves this after the email
+ * step (captured in logs/dumps, PageID i5030):
+ *
+ *     <h1 data-testid="title">Get a code to sign in</h1>
+ *     <button type="submit" data-testid="primaryButton">Send code</button>
+ *     <span role="button" class="fui-Link" tabindex="0">Use your password</span>
+ *
+ * Note what is *not* there: an "Other ways to sign in" link. The password is
+ * only reachable via the "Use your password" link in the footer of that very
+ * screen, and it is a <span role="button">, not an <a>, so it only responds to
+ * real pointer events. The previous implementation assumed "Other ways to sign
+ * in" always came first: it waited 15 s for a link that does not exist, threw
+ * STUCK, swallowed it, and then let the password selector time out 30 s later.
+ * A ~45 s stall ending in a misleading "incorrect credentials" message.
+ *
+ * So instead of racing text selectors and betting on which one wins, the state
+ * is read from the DOM — what is actually on offer — and "Use your password" is
+ * pressed wherever it appears.
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Label patterns for the sign-in-choice screens, as *source strings*: they are
+ * handed into page.evaluate(), where RegExp objects do not survive
+ * serialization and must be rebuilt on the far side.
+ */
+const SIGN_IN_LABELS = {
+    usePassword: 'use your password|use a password instead|use password instead|sign in with a password',
+    otherWays: 'other ways to sign in|sign in another way|look for another way|try another way',
+    // The list of methods, where "Password" is one entry among several.
+    passwordEntry: '^password$|use your password|use a password',
+    methodList: 'select a (?:sign-in |verification )?method|choose (?:a |another )?way to sign in|how do you want to sign in',
+    sendCode: 'send code|get a code to sign in|text me a code|email me a code',
+    approveApp: 'approve a request on my microsoft authenticator app|approve sign in request',
+    otcPrompt: 'enter (?:the )?code|type (?:the )?code|verification code',
+};
+
+/** Compiles a SIGN_IN_LABELS entry into an anchored, case-insensitive RegExp. */
+function signInLabel(key) {
+    return new RegExp(SIGN_IN_LABELS[key], 'i');
+}
+
+/** Selectors for anything on the page that can be clicked, on either UI generation. */
+const CLICKABLE_SELECTOR = 'a[href], button, input[type="submit"], input[type="button"], [role="button"], [role="link"]';
+
+/** The password box, on both the legacy and the Fluent sign-in pages. */
+const PASSWORD_FIELD_SELECTOR = 'input[name="passwd"], input[type="password"]';
+
+/**
+ * Reads what the current sign-in screen actually offers, in a single round trip.
+ *
+ * Everything is answered from one evaluate() so the reading is a consistent
+ * snapshot: seven separate locators would each sample the page at a slightly
+ * different moment, which is how a screen mid-navigation gets misclassified.
+ *
+ * @param {import('playwright').Page} page
+ * @returns {Promise<object|null>} null while the document is being swapped
+ */
+async function readSignInState(page) {
+    try {
+        return await page.evaluate(labels => {
+            const visible = el => {
+                if (!el) return false;
+                // aria-hidden means the element is not exposed to the user, so it
+                // is not something the user can interact with. login.microsoftonline.com
+                // parks its leftover fields in the DOM exactly this way:
+                // <input name="loginfmt" class="moveOffScreen" aria-hidden="true">.
+                // Those are off-screen rather than display:none, so they still have
+                // a non-zero box and pass a pure geometry test — which is how a
+                // work account's password page was mistaken for the email step.
+                if (el.getAttribute('aria-hidden') === 'true') return false;
+                const rect = el.getBoundingClientRect();
+                if (rect.width <= 0 || rect.height <= 0) return false;
+                const style = window.getComputedStyle(el);
+                return style.visibility !== 'hidden' && style.display !== 'none';
+            };
+
+            const labelOf = el => `${el.value || ''} ${el.textContent || ''}`.replace(/\s+/g, ' ').trim();
+
+            // True when a *control* carrying this label is on screen. Deliberately
+            // not a body-text search: prose mentioning "another way" must never
+            // be mistaken for the button that acts on it.
+            const offersAction = key => {
+                const rx = new RegExp(labels[key], 'i');
+                return Array.from(document.querySelectorAll(
+                    'a[href], button, input[type="submit"], input[type="button"], [role="button"], [role="link"]'
+                )).some(el => visible(el) && rx.test(labelOf(el)));
+            };
+
+            const headingEl = document.querySelector('h1, [role="heading"], [data-testid="title"]');
+            const body = document.body ? (document.body.innerText || '').replace(/\s+/g, ' ') : '';
+
+            return {
+                url: location.href,
+                heading: (headingEl ? headingEl.textContent : '').replace(/\s+/g, ' ').trim(),
+                // Still on the email form: the step after it has not rendered yet.
+                emailField: visible(document.querySelector('input[name="loginfmt"]')),
+                passwordField: visible(document.querySelector('input[name="passwd"], input[type="password"]')),
+                otcField: visible(document.querySelector('input[name="otc"], input[type="tel"]')),
+                usePassword: offersAction('usePassword'),
+                otherWays: offersAction('otherWays'),
+                sendCode: offersAction('sendCode') || new RegExp(labels.sendCode, 'i').test(body),
+                // Prose-only screens: read from the page text, nothing to click.
+                methodList: new RegExp(labels.methodList, 'i').test(body),
+                approveApp: new RegExp(labels.approveApp, 'i').test(body),
+                otcPrompt: new RegExp(labels.otcPrompt, 'i').test(body)
+            };
+        }, SIGN_IN_LABELS);
+    } catch (_) {
+        // Execution context destroyed mid-navigation — caller should retry.
+        return null;
+    }
+}
+
+/** True when the screen is one this handler knows how to act on. */
+function isActionableSignInState(state) {
+    if (!state || state.emailField) return false;
+    return !!(state.passwordField || state.usePassword || state.otherWays
+        || state.methodList || state.sendCode || state.approveApp || state.otcPrompt);
+}
+
+/** Identity of a sign-in screen, to tell a real step change from a re-render. */
+function signInStateSignature(state) {
+    if (!state) return null;
+    return [state.url, state.heading, state.passwordField, state.usePassword,
+        state.otherWays, state.methodList, state.sendCode, state.approveApp].join('::');
+}
+
+/**
+ * Polls until `accept` is satisfied or the timeout runs out.
+ * @returns {Promise<object|null>} the accepted state, else the last readable one
+ */
+async function waitForSignInState(page, timeout, accept = isActionableSignInState) {
+    const deadline = Date.now() + timeout;
+    let state = null;
+    do {
+        const read = await readSignInState(page);
+        if (read) {
+            state = read;
+            if (accept(read)) return read;
+        }
+        await page.waitForTimeout(400).catch(() => {});
+    } while (Date.now() < deadline);
+    // The last *readable* state, not whatever a mid-navigation read happened to
+    // return: null would discard the only evidence of why the step is stuck.
+    return state;
+}
+
+/**
+ * Clicks the control carrying a given label.
+ *
+ * The Fluent pages render links as <span role="button">, which only react to a
+ * real pointer event: a .click() on an ancestor wrapper fires nothing. So the
+ * lookup escalates from the most semantic to the most forceful, and the last
+ * step targets the *innermost* match rather than the first in document order.
+ *
+ * @param {import('playwright').Page} page
+ * @param {RegExp} rx
+ * @param {{ timeout?: number }} [options]
+ * @returns {Promise<string|null>} the label clicked, or null if nothing matched
+ */
+async function clickByLabel(page, rx, { timeout = 8000 } = {}) {
+    // Precise strategies first: they match on the accessible name, so they hit
+    // the control the user sees rather than a wrapper.
+    const precise = [
+        page.getByRole('button', { name: rx }),
+        page.getByRole('link', { name: rx })
+    ];
+
+    // Raced, not sequential: a control is a button on one screen generation and a
+    // link on the other, so trying them in turn means paying the full timeout on
+    // whichever role does not apply.
+    const hit = await Promise.any(
+        precise.map((locator, i) => locator.first().waitFor({ state: 'visible', timeout }).then(() => i))
+    ).catch(() => -1);
+
+    // getByText is the fuzzier fallback, and the JS click the forceful one.
+    if (hit < 0) {
+        try {
+            await page.getByText(rx).first().waitFor({ state: 'visible', timeout: Math.min(timeout, 2000) });
+            precise.push(page.getByText(rx));
+            hit = precise.length - 1;
+        } catch (_) { /* fall through to the JS click */ }
+    }
+
+    if (hit >= 0) {
+        const first = precise[hit].first();
+        try {
+            // Read the label *before* clicking. These controls navigate on click,
+            // and textContent() against a locator whose element the navigation just
+            // removed blocks for the full 30 s default timeout before rejecting —
+            // which is exactly the stall this function is meant to avoid.
+            const label = ((await first.textContent({ timeout: 2000 }).catch(() => '')) || '')
+                .replace(/\s+/g, ' ').trim();
+            await first.click({ timeout: Math.min(timeout, 5000) });
+            return label || '(clicked)';
+        } catch (_) {
+            // Found but not clickable — let the JS click have a go.
+        }
+    }
+
+    return await page.evaluate(({ selector, source }) => {
+        const rx = new RegExp(source, 'i');
+        const labelOf = el => `${el.value || ''} ${el.textContent || ''}`.replace(/\s+/g, ' ').trim();
+        const hits = Array.from(document.querySelectorAll(selector)).filter(el => rx.test(labelOf(el)));
+        // Innermost hit: an ancestor's textContent includes the descendant's, so
+        // the first match in document order is usually a wrapper whose click
+        // never reaches the handler the user can see.
+        const target = hits.find(el => !hits.some(other => other !== el && el.contains(other)));
+        if (!target) return null;
+        target.click();
+        return labelOf(target);
+    }, { selector: CLICKABLE_SELECTOR, source: rx.source }).catch(() => null);
+}
+
+/**
+ * Presses the sign-in submit control.
+ *
+ * The legacy pages use <input type="submit" value="Sign in">, where the label
+ * lives in `value` and `filter({ hasText })` can never match it; the Fluent pages
+ * use <button type="submit" data-testid="primaryButton">Sign in</button>. Matching
+ * on the accessible role name covers both.
+ *
+ * @param {import('playwright').Page} page
+ * @returns {Promise<boolean>} true if a submit control was clicked
+ */
+async function submitSignInForm(page) {
+    const strategies = [
+        page.getByRole('button', { name: /^(sign in|next|finish|continue)$/i }),
+        page.locator('input[type="submit"]'),
+        page.locator('button[type="submit"]')
+    ];
+
+    for (const locator of strategies) {
+        const button = locator.first();
+        if (!(await button.isVisible().catch(() => false))) continue;
+        // click() waits for the element to become enabled, which covers the
+        // short window after fill() while the page validates the password.
+        await button.click({ timeout: 10000 });
+        return true;
+    }
+    return false;
+}
+
+/**
+ * Walks the "how do you want to sign in?" screens and lands on the password box.
+ *
+ * Prefers "Use your password" wherever it is offered, because on the
+ * passwordless screen that link is the only route to the password — there is no
+ * "Other ways to sign in" step to go through first. Only falls back to that
+ * step when the screen really does present it, then picks "Password" out of the
+ * resulting method list.
+ *
+ * @param {import('playwright').Page} page
+ * @param {object} [options]
+ * @param {number} [options.maxSteps]
+ * @param {number} [options.stateTimeout]   how long to wait for the first screen
+ * @param {number} [options.transitionTimeout] how long to wait after each click
+ * @param {boolean} [options.dodump]
+ * @param {string} [options.dumpFile]        basename written under the dump dir
+ * @returns {Promise<{ reached: boolean, reason: string, steps: number, state: object|null }>}
+ */
+async function reachPasswordScreen(page, options = {}) {
+    const {
+        maxSteps = 4,
+        stateTimeout = 15000,
+        transitionTimeout = 10000,
+        dodump = false,
+        dumpFile = 'debug_intermediate_screen'
+    } = options;
+
+    let state = await waitForSignInState(page, stateTimeout);
+    let dumped = false;
+
+    for (let steps = 0; steps < maxSteps; steps++) {
+        // The password box is checked FIRST, ahead of the "still on the email
+        // step" gate below. A work/school account signs in on
+        // login.microsoftonline.com, whose password page keeps the username
+        // field in the DOM as <input name="loginfmt" class="moveOffScreen"> —
+        // rendered off-screen, and therefore "visible" by any geometry test.
+        // Gating on emailField first made every such login report "unreadable"
+        // and burn the whole stateTimeout while the password box sat right
+        // there, ready to be filled.
+        if (state && state.passwordField) {
+            logger.debug(`Password field reached after ${steps} step(s).`);
+            return { reached: true, reason: 'password_field', steps, state };
+        }
+
+        if (!state || !isActionableSignInState(state)) {
+            return { reached: false, reason: 'unreadable', steps, state };
+        }
+
+        if (dodump && !dumped) {
+            dumped = true;
+            const displayPath = await dumpPage(page, `${dumpFile}.html`);
+            logger.debug(`[dodump] Intermediate screen state dumped to ${displayPath}/${dumpFile}.html`);
+        }
+
+        const before = signInStateSignature(state);
+        let clicked = null;
+
+        if (state.usePassword) {
+            logger.info('Password is offered on this screen — clicking "Use your password"...');
+            clicked = await clickByLabel(page, signInLabel('usePassword'));
+        } else if (state.otherWays) {
+            logger.info('Opening "Other ways to sign in"...');
+            clicked = await clickByLabel(page, signInLabel('otherWays'));
+        } else if (state.methodList) {
+            logger.info('Choosing "Password" from the sign-in method list...');
+            clicked = await clickByLabel(page, signInLabel('passwordEntry'));
+        }
+
+        if (!clicked) {
+            // No route to a password from here. Say which kind of screen it is,
+            // so a mandatory code/approval is not reported as a bad password.
+            const reason = state.approveApp ? 'approver_prompt'
+                : state.otcPrompt || state.sendCode || state.otcField ? 'code_prompt'
+                    : 'no_password_route';
+            logger.warn(`No way to reach the password screen from "${state.heading || shortUrl(state.url)}" (${reason}).`);
+            return { reached: false, reason, steps, state };
+        }
+
+        logger.debug(`Clicked "${clicked}". Waiting for the next screen...`);
+
+        // Wait for a *different* screen, not just the password box: the method
+        // list is a legitimate hop in the middle of this walk, and waiting only
+        // for the password field would burn the whole timeout on it. The
+        // signature guard keeps the not-yet-navigated pre-click state from
+        // satisfying the wait immediately.
+        state = await waitForSignInState(page, transitionTimeout,
+            s => s.passwordField || (isActionableSignInState(s) && signInStateSignature(s) !== before));
+        if (state && signInStateSignature(state) === before) {
+            logger.warn(`Screen did not change after clicking "${clicked}".`);
+            return { reached: false, reason: 'unchanged', steps, state };
+        }
+    }
+
+    return { reached: false, reason: 'max_steps', steps: maxSteps, state };
+}
+
+/**
+ * Writes the current page to a debug dump, with credentials removed.
+ *
+ * `--dodump` calls page.content(), and that serialises the *live value* of every
+ * form control. On the page where the password is typed that means the user's
+ * actual Microsoft password lands on disk in cleartext:
+ *
+ *     <input type="password" name="passwd" value="the-real-password">
+ *
+ * The dumps are gitignored and never packed, but they land in the working
+ * tree, where backups, sync clients and file-sharing will pick them up, and
+ * they get pasted into issues and chat. Every dump goes through here so the
+ * redaction cannot be forgotten at the next call site.
+ *
+ * The scrubbing happens on a *clone* of the document rather than by rewriting
+ * the HTML string: PPFT and the other flow tokens are the values the login
+ * form is about to POST, so blanking them in the live DOM would break the very
+ * login being debugged. A clone cannot affect the page.
+ *
+ * @param {import('playwright').Page} page
+ * @param {string} fileName  basename, e.g. debug_after_password.html
+ */
+async function dumpPage(page, fileName) {
+    const dumpDir = await logger.getDumpDir();
+    const displayPath = logger.getDumpDisplayPath();
+    await fs.writeFile(path.join(dumpDir, fileName), await redactedPageContent(page));
+    return displayPath;
+}
+
+/** Placeholder written over any redacted value, so a scrubbed dump is obvious. */
+const REDACTED = '[redacted]';
+
+/**
+ * Serialises the page with credential-bearing control values blanked.
+ *
+ * Redacted: every `input[type=password]` whatever it is named, plus any control
+ * whose name or id reads as a credential or a bearer token — PPFT and the other
+ * pre-auth flow tokens, id/access/refresh tokens, secrets, and OTP / one-time
+ * code fields.
+ *
+ * Deliberately *not* redacted: the account identifier (`loginfmt`, `login`).
+ * It is already written in cleartext by the "Attempting automated login for
+ * <email>" line and is on the command line, so hiding it in the HTML would
+ * protect nothing while removing the one field worth having when a login fails
+ * on the wrong account.
+ *
+ * @param {import('playwright').Page} page
+ * @returns {Promise<string>}
+ */
+async function redactedPageContent(page) {
+    return await page.evaluate(REDACTED => {
+        // Any control whose name or id holds a credential or a bearer token
+        // rather than UI state. Substring matching on purpose: these names are
+        // compound in the wild (otc, otcFallback, verificationCode, srfSFT) and
+        // an anchored pattern misses all but the exact spelling. Over-redacting
+        // one extra field costs a debug dump nothing; under-redacting leaks a
+        // credential. PPFT is Microsoft's pre-auth flow token and matches no
+        // generic word, so it is named outright.
+        const SENSITIVE = /ppft|token|canary|secret|passw|credential|otp|otc|code$|pin$/i;
+
+        const isSensitive = el => {
+            if (String(el.type || '').toLowerCase() === 'password') return true;
+            return SENSITIVE.test(`${el.name || ''}`.trim()) || SENSITIVE.test(`${el.id || ''}`.trim());
+        };
+
+        const clone = document.documentElement.cloneNode(true);
+        for (const el of clone.querySelectorAll('input, textarea')) {
+            // Only a value that is actually there needs hiding.
+            if (!el.value || !isSensitive(el)) continue;
+
+            if (el.tagName === 'TEXTAREA') {
+                el.textContent = REDACTED;
+            } else {
+                // setAttribute, never `.value =`. Assigning the IDL property on a
+                // *visible* input puts the element into "dirty value mode": the IDL
+                // value changes but the content attribute is left alone, and
+                // outerHTML serialises the content attribute — so the secret comes
+                // out unchanged. Only type="hidden" inputs are saved by that
+                // accident, and a password field is a visible input, which is
+                // exactly the case that would have leaked.
+                el.setAttribute('value', REDACTED);
+            }
+        }
+        return `<!DOCTYPE html>\n${clone.outerHTML}`;
+    }, REDACTED).catch(e => `<!-- Error redacting or reading page: ${e.message} -->`);
+}
+
 async function login(credentials = {}) {
     const { email, password, targetUrl, authFile } = credentials;
     const isAutomated = !!(email && password);
@@ -609,9 +1076,17 @@ async function login(credentials = {}) {
                 logger.info('Email entered. Clicking "Next"...');
                 await page.click('input[type="submit"]');
 
-                logger.debug('Waiting for email field to disappear...');
-                await page.waitForSelector('input[name="loginfmt"]', { state: 'hidden', timeout: 15000 }).catch(() => {
-                    logger.debug('Email field still present, proceeding with caution.');
+                // Wait for the email form to actually be replaced, but not for the
+                // loginfmt input to vanish: on login.microsoftonline.com it is
+                // parked as <input name="loginfmt" class="moveOffScreen"> and stays
+                // in the DOM for the rest of the login, so "hidden" never happens
+                // and this used to burn the full timeout on every work account.
+                // The next step appearing is the real signal that we have moved on.
+                await Promise.race([
+                    page.waitForSelector(PASSWORD_FIELD_SELECTOR, { state: 'visible', timeout: 15000 }).then(() => 'password'),
+                    page.waitForSelector('input[name="loginfmt"]', { state: 'hidden', timeout: 15000 }).then(() => 'advanced'),
+                ]).catch(() => {
+                    logger.debug('Email form did not visibly change yet; the sign-in method step will wait for the next screen.');
                 });
 
                 logger.info('Will wait 1 seconds to give the UI a moment to settle into the next screen (MFA/Password)');
@@ -625,10 +1100,7 @@ async function login(credentials = {}) {
             } catch (e) {
                 logger.error(`Failed to enter email: ${e.message}`);
                 if (credentials.dodump) {
-                    const dumpDir = await logger.getDumpDir();
-                    const displayPath = logger.getDumpDisplayPath();
-                    const debugFile = path.join(dumpDir, 'debug_login_error_email.html');
-                    await fs.writeFile(debugFile, await page.content().catch(e => `<!-- Error: ${e.message} -->`));
+                    const displayPath = await dumpPage(page, 'debug_login_error_email.html');
                     logger.error(`Email submission failed. HTML dumped to ${displayPath}/debug_login_error_email.html`);
                 }
                 throw e;
@@ -636,145 +1108,61 @@ async function login(credentials = {}) {
 
             // Proactive dump after email step (before MFA detection)
             if (credentials.dodump) {
-                const dumpDir = await logger.getDumpDir();
-                const displayPath = logger.getDumpDisplayPath();
-                const debugFile = path.join(dumpDir, 'debug_after_email.html');
-                await fs.writeFile(debugFile, await page.content().catch(e => `<!-- Error: ${e.message} -->`));
+                const displayPath = await dumpPage(page, 'debug_after_email.html');
                 logger.debug(`[dodump] Post-email state dumped to ${displayPath}/debug_after_email.html`);
             }
 
-            // 1.5. Handle intermediate screens (MFA selection, "Other ways to sign in")
+            // 1.5. Get from the email step to the password box. This screen has
+            // no "Other ways to sign in" step on it — the "Use your password" link
+            // in its footer is the only route to the password — so the state is
+            // read from the DOM rather than guessed from a race between text
+            // selectors. See reachPasswordScreen() above.
             try {
-                const pageTitle = (await page.title()).trim();
-                const pageHeading = (await page.locator('h1, [role="heading"]').first().textContent().catch(() => '')).trim();
-
-                logger.debug(`Settled State: Title="${pageTitle}" | Heading="${pageHeading}"`);
-                logger.debug('Checking for intermediate MFA/Sign-in option screens...');
-
-                const result = await Promise.race([
-                    page.waitForSelector('text=/Other ways to sign in/i', { state: 'visible', timeout: 15000 }).then(() => 'other_ways'),
-                    page.waitForSelector('text=/Get a code to sign in/i', { state: 'visible', timeout: 15000 }).then(() => 'other_ways'),
-                    page.waitForSelector('text=/Verify your identity/i', { state: 'visible', timeout: 15000 }).then(() => 'other_ways'),
-                    page.waitForSelector('text=/Use your password/i', { state: 'visible', timeout: 15000 }).then(() => 'use_password'),
-                    page.waitForSelector('text=/Approve a request on my Microsoft Authenticator app/i', { state: 'visible', timeout: 5000 }).then(() => 'approve_app'),
-                    page.waitForSelector('input[name="passwd"]', { state: 'visible', timeout: 15000 }).then(() => 'password'),
-                    page.waitForFunction(() => {
-                        const h = document.querySelector('h1, [role="heading"]')?.textContent || '';
-                        return h.includes('Get a code') || h.includes('Verify your identity');
-                    }, { timeout: 15000 }).then(() => 'other_ways'),
-                ]).catch((err) => {
-                    logger.debug(`Detection race timed out or failed: ${err.message}`);
-                    return 'timeout';
-                });
-
-                logger.debug(`Intermediate screen detection result: ${result}`);
+                const nav = await reachPasswordScreen(page, { dodump: credentials.dodump });
 
-                if (credentials.dodump) {
-                    const dumpDir = await logger.getDumpDir();
-                    const displayPath = logger.getDumpDisplayPath();
-                    const debugFile = path.join(dumpDir, 'debug_intermediate_screen.html');
-                    await fs.writeFile(debugFile, await page.content().catch(e => `<!-- Error: ${e.message} -->`));
-                    logger.debug(`[dodump] Intermediate screen state dumped to ${displayPath}/debug_intermediate_screen.html`);
+                logger.debug(`Sign-in method step: reached=${nav.reached} (${nav.reason}) after ${nav.steps} step(s)`);
+                if (nav.state) {
+                    logger.debug(`Current screen: ${shortUrl(nav.state.url)} — heading: "${nav.state.heading || '(none)'}"`);
                 }
 
-                if (result === 'other_ways' || pageHeading.includes('Get a code') || pageHeading.includes('Verify your identity')) {
-                    logger.info('Detected MFA/Verification screen. Attempting to locate "Other ways to sign in"...');
-
-                    const otherWays = page.getByRole('button', { name: /Other ways to sign in|Sign in another way/i })
-                        .or(page.getByText(/Other ways to sign in|Sign in another way/i))
-                        .first();
-
-                    try {
-                        logger.debug('Waiting for "Other ways" link to appear in DOM...');
-                        await otherWays.waitFor({ state: 'attached', timeout: 15000 });
-
-                        const isVisible = await otherWays.isVisible();
-                        logger.debug(`"Other ways" link visibility: ${isVisible}`);
-
-                        logger.info('Clicking "Other ways to sign in"...');
-                        try {
-                            await otherWays.click({ timeout: 5000 });
-                        } catch (e) {
-                            logger.debug(`Standard click failed, trying forced: ${e.message}`);
-                            await otherWays.click({ force: true, timeout: 5000 });
-                        }
-                    } catch (e) {
-                        logger.warn(`MFA link interaction failed: ${e.message}`);
-
-                        logger.debug('Attempting final fallback: JavaScript-based click...');
-                        const clicked = await page.evaluate(() => {
-                            const elements = Array.from(document.querySelectorAll('span, a, button'));
-                            const target = elements.find(el =>
-                                el.textContent.toLowerCase().includes('other ways to sign in') ||
-                                el.textContent.toLowerCase().includes('sign in another way')
-                            );
-                            if (target) {
-                                target.click();
-                                return true;
-                            }
-                            return false;
-                        });
-
-                        if (clicked) {
-                            logger.info('Successfully triggered click via JavaScript fallback.');
-                        } else if (pageHeading.includes('Get a code')) {
-                            throw new Error('STUCK: "Other ways to sign in" link not found even via JS scan.');
-                        }
-                    }
-
-                    logger.debug('Waiting for method selection screen ("Use your password")...');
-                    const subResult = await Promise.race([
-                        page.waitForSelector('text=/Use your password/i', { state: 'visible', timeout: 15000 }).then(() => 'use_password'),
-                        page.waitForSelector('#idA_PWD_SwitchToPassword', { state: 'visible', timeout: 15000 }).then(() => 'use_password'),
-                        page.waitForSelector('text=/Select a verification method/i', { state: 'visible', timeout: 15000 }).then(() => 'other_ways_list'),
-                    ]).catch(() => 'timeout');
-
-                    logger.debug(`Sub-screen detection result: ${subResult}`);
-
-                    if (subResult === 'use_password') {
-                        logger.info('Selecting "Use your password" option...');
-                        await page.click('text=/Use your password/i');
-                    } else if (subResult === 'other_ways_list') {
-                        logger.info('Selection list detected. Looking for "Password"...');
-                        await page.click('text=/Password|Use your password/i');
-                    }
-                } else if (result === 'use_password') {
-                    logger.info('Detected "Use your password" option. Clicking...');
-                    await page.click('text="Use your password"');
-                } else if (result === 'approve_app') {
-                    logger.warn('MFA notification already sent. Attempting to switch to password...');
-                    const otherLink = page.locator('text="Other ways to sign in", #signInAnotherWay').first();
-                    if (await otherLink.isVisible()) {
-                        await otherLink.click();
-                        await page.waitForSelector('text="Use your password"', { state: 'visible', timeout: 10000 });
-                        await page.click('text="Use your password"');
-                    }
-                } else if (result === 'password') {
-                    logger.debug('Direct password field detected.');
-                } else if (result === 'timeout') {
-                    logger.debug('No intermediate screen detected within timeout. Proceeding to password entry.');
+                if (!nav.reached && nav.reason === 'code_prompt') {
+                    logger.warn('Microsoft is asking for a verification code instead of a password. This account cannot finish a password-only login.');
                 }
             } catch (e) {
-                logger.debug(`Intermediate screen handler encountered a fatal issue: ${e.message}`);
+                // Never fatal: step 2 still waits for the password box and reports
+                // precisely which screen is in the way if it is not there.
+                logger.debug(`Sign-in method step skipped: ${e.message}`);
             }
 
             // 2. Enter Password
             try {
-                await page.waitForSelector('input[name="passwd"]', { state: 'visible', timeout: 30000 });
-                await page.fill('input[name="passwd"]', password);
+                const passwordField = page.locator(PASSWORD_FIELD_SELECTOR).first();
+                try {
+                    await passwordField.waitFor({ state: 'visible', timeout: 30000 });
+                } catch (e) {
+                    // "page.waitForSelector: Timeout 30000ms exceeded" is the least
+                    // actionable error this tool can emit, and it is what a
+                    // passwordless screen used to produce. Name the screen instead.
+                    const stuck = await readSignInState(page) || await readScreenState(page);
+                    if (stuck) {
+                        const needsCode = stuck.sendCode || stuck.approveApp || stuck.otcPrompt;
+                        throw new Error(
+                            `Password field never appeared. Still on ${shortUrl(stuck.url)} — heading: "${stuck.heading || '(none)'}".` +
+                            (needsCode
+                                ? ' Microsoft is offering a code/phone approval here, not a password.'
+                                : ' This screen does not offer a password sign-in.')
+                        );
+                    }
+                    throw e;
+                }
 
-                const submitButton = page.locator('input[type="submit"], button[type="submit"]').filter({ hasText: /Sign in|Next|Finish/i }).first();
+                await passwordField.fill(password);
 
-                logger.debug('Waiting for submit button to be enabled...');
-                await submitButton.waitFor({ state: 'visible', timeout: 10000 });
-                if (await submitButton.isDisabled()) {
-                    logger.debug('Submit button is disabled. It might be the wrong one or the password field is not considered filled.');
-                    logger.info('Will wait 1 seconds to let the submit button load properly');
-                    await page.waitForTimeout(1000);
+                logger.debug('Submitting the sign-in form...');
+                if (!(await submitSignInForm(page))) {
+                    throw new Error('Password filled but no sign-in submit control was found.');
                 }
 
-                await submitButton.click();
-
                 const passwordError = page.locator('#passwordError');
                 if (await passwordError.isVisible({ timeout: 2000 })) {
                     const errorMsg = await passwordError.textContent();
@@ -782,10 +1170,7 @@ async function login(credentials = {}) {
                 }
             } catch (e) {
                 if (credentials.dodump) {
-                    const dumpDir = await logger.getDumpDir();
-                    const displayPath = logger.getDumpDisplayPath();
-                    const debugFile = path.join(dumpDir, 'debug_login_error_password.html');
-                    await fs.writeFile(debugFile, await page.content().catch(e => `<!-- Error: ${e.message} -->`));
+                    const displayPath = await dumpPage(page, 'debug_login_error_password.html');
                     logger.error(`Password entry failed. HTML dumped to ${displayPath}/debug_login_error_password.html`);
                 }
                 throw e;
@@ -793,10 +1178,7 @@ async function login(credentials = {}) {
 
             // Proactive dump after password submission (before post-password MFA check)
             if (credentials.dodump) {
-                const dumpDir = await logger.getDumpDir();
-                const displayPath = logger.getDumpDisplayPath();
-                const debugFile = path.join(dumpDir, 'debug_after_password.html');
-                await fs.writeFile(debugFile, await page.content().catch(e => `<!-- Error: ${e.message} -->`));
+                const displayPath = await dumpPage(page, 'debug_after_password.html');
                 logger.debug(`[dodump] Post-password state dumped to ${displayPath}/debug_after_password.html`);
             }
 
@@ -816,19 +1198,19 @@ async function login(credentials = {}) {
 
             // 2.5b. Handle post-password MFA/Verification if needed
             try {
+                // ".displaySign" is the legacy number-match element; the Fluent
+                // pages put the same number under a data-testid instead.
+                const NUMBER_MATCH = '.displaySign, [data-testid="displaySign"]';
                 const verificationScreen = await Promise.race([
                     page.waitForSelector('text="Verify your identity"', { timeout: 10000 }).then(() => 'verify'),
                     page.waitForSelector('text="Enter code"', { timeout: 10000 }).then(() => 'enter_code'),
                     page.waitForSelector('input[name="otc"]', { timeout: 10000 }).then(() => 'otc_input'),
                     page.waitForSelector('text=/Approve sign in request/i', { timeout: 10000 }).then(() => 'number_match'),
-                    page.waitForSelector('.displaySign', { timeout: 10000 }).then(() => 'number_match'),
+                    page.waitForSelector(NUMBER_MATCH, { timeout: 10000 }).then(() => 'number_match'),
                 ]).catch(() => null);
 
                 if (credentials.dodump) {
-                    const dumpDir = await logger.getDumpDir();
-                    const displayPath = logger.getDumpDisplayPath();
-                    const debugFile = path.join(dumpDir, 'debug_post_password_mfa.html');
-                    await fs.writeFile(debugFile, await page.content().catch(e => `<!-- Error: ${e.message} -->`));
+                    const displayPath = await dumpPage(page, 'debug_post_password_mfa.html');
                     logger.debug(`[dodump] Post-password MFA screen state dumped to ${displayPath}/debug_post_password_mfa.html`);
                 }
 
@@ -837,20 +1219,20 @@ async function login(credentials = {}) {
 
                     let matchNumber = '??';
                     try {
-                        matchNumber = await page.$eval('.displaySign', el => el.textContent.trim());
+                        matchNumber = await page.locator(NUMBER_MATCH).first().textContent().catch(() => null) || '??';
                     } catch (_) {
-                        logger.debug('Could not extract number from .displaySign — user may still see it if --notheadless is used.');
+                        logger.debug('Could not extract the number-match code — user may still see it if --notheadless is used.');
                     }
 
                     logger.step('══════════════════════════════════════════════════════');
                     logger.step(`  ACTION REQUIRED: Open Microsoft Authenticator on your phone.`);
-                    logger.step(`  Enter the number:  ${matchNumber}`);
+                    logger.step(`  Enter the number:  ${matchNumber.trim()}`);
                     logger.step(`  Then tap "Yes" / "Approve" in the app.`);
                     logger.step('══════════════════════════════════════════════════════');
                     logger.info('Waiting for phone approval (up to 120 seconds)...');
 
                     await Promise.race([
-                        page.waitForSelector('.displaySign', { state: 'hidden', timeout: 120000 }),
+                        page.waitForSelector(NUMBER_MATCH, { state: 'hidden', timeout: 120000 }),
                         page.waitForURL(url => !url.toString().includes('login.microsoftonline.com'), { timeout: 120000 }),
                         page.waitForSelector('text=/Stay signed in/i', { timeout: 120000 }),
                     ]);
@@ -871,7 +1253,9 @@ async function login(credentials = {}) {
                         await page.locator('input[type="text"]:visible, input[type="tel"]:visible').first().fill(code);
                     }
 
-                    await page.click('input[type="submit"]');
+                    if (!(await submitSignInForm(page))) {
+                        logger.debug('No submit control found on the verification screen.');
+                    }
                 }
             } catch (e) {
                 logger.debug(`Post-password verification handling skipped or failed: ${e.message}`);
@@ -914,10 +1298,7 @@ async function login(credentials = {}) {
                     }
                 }
                 if (credentials.dodump) {
-                    const dumpDir = await logger.getDumpDir();
-                    const displayPath = logger.getDumpDisplayPath();
-                    const debugFile = path.join(dumpDir, 'debug_login_error_success.html');
-                    await fs.writeFile(debugFile, await page.content().catch(e => `<!-- Error: ${e.message} -->`));
+                    const displayPath = await dumpPage(page, 'debug_login_error_success.html');
                     logger.error(`Success detection failed. HTML dumped to ${displayPath}/debug_login_error_success.html`);
                 }
                 throw e;
@@ -1019,5 +1400,19 @@ module.exports = {
     logout,
     // Exported for tests: clears the consent/interrupt screens that Microsoft can
     // inject mid-login (e.g. the Terms of Use update at account.live.com/tou/accrue).
-    clearBlockingScreens
+    clearBlockingScreens,
+    // Exported for tests: walks the "how do you want to sign in?" screens
+    // (passwordless "Get a code to sign in", "Other ways to sign in", method
+    // list) and lands on the password box.
+    reachPasswordScreen,
+    // Exported for tests: presses the sign-in submit control on both the legacy
+    // (<input type="submit" value="Sign in">) and Fluent (<button>) pages.
+    submitSignInForm,
+    // Exported for tests: the single path every --dodump write goes through, so
+    // that credentials cannot reach a dump file.
+    dumpPage,
+    // Exported for tests: the same success detection with a caller-supplied
+    // timeout, so "is this the authenticated app?" can be asserted on directly
+    // rather than through a 60 s wait.
+    waitForAuthSuccessProbe
 };