slidemind 0.2.4 → 0.3.0

package/src/bridge/graph-auth.mjs

@@ -0,0 +1,859 @@
+// Delegated Microsoft Graph sign-in for the pane-free CLI (`slidemind login`).
+//
+// The engine routes answer discovery, search and blob-backed bytes off the CLI
+// session alone — but SharePoint-backed BYTES are the user's own content, and
+// only the user's own identity may fetch them. The CLI session token is minted
+// by the add-in at claim redemption, not by Entra, so the backend cannot
+// exchange it for a Graph token either. Until now the only identity that could
+// was the task pane's browser, which is why those two failures
+// (`asset_needs_host`, "Failed to connect to sharepoint provider") demanded an
+// open PowerPoint window. This module mints that identity from the terminal
+// instead: auth-code + PKCE through the system browser with a loopback
+// redirect, the `az login` / `gh auth login` shape.
+//
+// The CLI never calls Graph itself. The token rides the existing bridge wire to
+// the backend exactly as the pane's does (client.mjs attaches it to the
+// pane-free engine ops and nothing else).
+//
+// Nothing about the app registration is hardcoded, per the connect doctrine:
+// `GET <backend>/env/config` is unauthenticated and already serves the CLIENT_ID
+// and TENANT_ID the pane itself uses, so `login` works against whichever
+// deployment the session already names. Same app registration → the tenant's
+// existing admin consent for its delegated Graph scopes carries over and
+// `.default` resolves to the same grant set the pane gets.
+//
+// The refresh token is stored per backend in the session file (0600, already
+// holding a bearer credential) and rotated on every refresh — AAD hands back a
+// new one each time. Public-client refresh tokens live on a ~90-day sliding
+// window, so an occasional re-login is expected, not a bug.
+
+import crypto from "node:crypto";
+import http from "node:http";
+
+import {
+  deriveEnvLabel,
+  envPhrase,
+  getGraphRefreshToken,
+  getSessionFor,
+  setGraphRefreshToken,
+} from "./config.mjs";
+import { FAVICON_LINK } from "../builders/gate-server.mjs";
+import { httpJson } from "./http-json.mjs";
+import { register as registerSecret } from "./secrets.mjs";
+
+// `.default` (rather than a scope list) is what makes this the SAME grant the
+// pane holds: the tenant's admin consent for the app registration decides, so
+// signing in from a terminal can never widen what the user already had.
+// `openid` alone mints a MINIMAL id_token — no `oid`, no username — and the
+// identity binding below needs `oid` while the closing line wants the name, so
+// `profile` is required, not cosmetic. Combining openid/profile/offline_access
+// with `.default` is explicitly allowed; only two RESOURCE scopes may not mix.
+const GRAPH_SCOPE =
+  "https://graph.microsoft.com/.default offline_access openid profile";
+
+// The SharePoint-resource scope for one deployment's tenant. A single sign-in
+// covers BOTH resources: an Entra refresh token is multi-resource, so the
+// interactive flow runs once against Graph and the SharePoint access token is
+// redeemed from the same refresh token with this scope. The backend needs both
+// — resolving `sg:` site-group membership takes Graph AND SharePoint REST
+// (sp-dev-docs#5694), and the corpus routes refuse without them.
+function sharePointScope(resource) {
+  return `${resource}/.default offline_access openid profile`;
+}
+
+const DEFAULT_AUTHORITY = "https://login.microsoftonline.com";
+
+// How long the loopback listener waits for the browser to come back. Long
+// enough for an MFA prompt and a password manager; short enough that a login
+// the user abandoned doesn't hold a terminal forever.
+const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+
+// Refresh this long before the access token actually expires, so a token handed
+// to a long download doesn't die mid-transfer.
+const EXPIRY_SKEW_MS = 5 * 60 * 1000;
+
+// The Entra authority. Overridable the way AZURE_AUTHORITY_HOST is — sovereign
+// clouds, and the test suite pointing the flow at a local mock endpoint. Held
+// to the same transport rule as the setup claim: HTTPS, or plain HTTP only on
+// loopback.
+function authorityBase() {
+  const override = String(process.env.SLIDEMIND_GRAPH_AUTHORITY || "").trim();
+  if (!override) return DEFAULT_AUTHORITY;
+  let url;
+  try {
+    url = new URL(override);
+  } catch {
+    throw new Error(
+      "SLIDEMIND_GRAPH_AUTHORITY is not a valid URL — unset it to use the default Microsoft sign-in endpoint.",
+    );
+  }
+  const loopback = ["localhost", "127.0.0.1", "::1"].includes(url.hostname);
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) {
+    throw new Error(
+      "SLIDEMIND_GRAPH_AUTHORITY must be HTTPS (HTTP is allowed only for loopback development).",
+    );
+  }
+  return url.toString().replace(/\/$/, "");
+}
+
+function authorizeEndpoint(tenantId) {
+  return `${authorityBase()}/${encodeURIComponent(tenantId)}/oauth2/v2.0/authorize`;
+}
+
+function tokenEndpoint(tenantId) {
+  return `${authorityBase()}/${encodeURIComponent(tenantId)}/oauth2/v2.0/token`;
+}
+
+// One /env/config read per backend per process — the app registration doesn't
+// change under a running command.
+const appRegistrationCache = new Map();
+
+// Which app registration this deployment signs in with. Unauthenticated on
+// purpose: it is the same public configuration the add-in's own browser reads.
+async function discoverAppRegistration(backendURL) {
+  const cached = appRegistrationCache.get(backendURL);
+  if (cached) return cached;
+  const env = deriveEnvLabel(backendURL);
+  let res;
+  try {
+    res = await httpJson("GET", `${backendURL}/env/config`);
+  } catch (err) {
+    throw new Error(
+      `could not reach slidemind${envPhrase(env, "on")} to start sign-in: ${err?.message || err}`,
+    );
+  }
+  const clientId = typeof res.json?.CLIENT_ID === "string" ? res.json.CLIENT_ID : "";
+  const tenantId = typeof res.json?.TENANT_ID === "string" ? res.json.TENANT_ID : "";
+  if (res.status !== 200 || !clientId || !tenantId) {
+    // An older deployment serves no sign-in details at all, so there is nothing
+    // to authorize against — this is an add-in-side update, not a user error.
+    throw new Error(
+      `the slidemind add-in${envPhrase(env, "on")} does not publish the sign-in details this command needs — ` +
+        "it needs an add-in update before `slidemind login` can work.",
+    );
+  }
+  // The deployment's SharePoint tenant root (e.g. https://tenant.sharepoint.com)
+  // — the RESOURCE the second token is minted for. Null on a deployment without
+  // SharePoint, where the site-group half of corpus identity is empty anyway.
+  let sharePointResource = null;
+  if (typeof res.json?.SHAREPOINT_SITE_URL === "string" && res.json.SHAREPOINT_SITE_URL) {
+    try {
+      sharePointResource = new URL(res.json.SHAREPOINT_SITE_URL).origin;
+    } catch {
+      sharePointResource = null;
+    }
+  }
+  const app = { clientId, tenantId, sharePointResource };
+  appRegistrationCache.set(backendURL, app);
+  return app;
+}
+
+function base64url(buf) {
+  return buf.toString("base64url");
+}
+
+// RFC 7636 S256: the verifier never leaves this process until the code is
+// redeemed, so an authorization code intercepted on the loopback hop is useless
+// on its own.
+function pkcePair() {
+  const verifier = base64url(crypto.randomBytes(32));
+  const challenge = base64url(
+    crypto.createHash("sha256").update(verifier).digest(),
+  );
+  return { verifier, challenge };
+}
+
+// ---------------------------------------------------------------------------
+// The browser pages.
+//
+// `slidemind login` is routinely typed by an AI agent, so the human at the
+// keyboard can meet a Microsoft sign-in prompt they never asked for — and an
+// unexpected sign-in prompt is exactly what a phishing page looks like. Entra
+// cannot carry the reassurance: its sign-in page is tenant-branded, not
+// per-app, and with admin-consented `.default` scopes the consent screen that
+// WOULD name the app is skipped entirely. So slidemind says it in its own page,
+// on its own loopback origin, and the user clicks through deliberately.
+//
+// Styled as the review/plan gates are — the same product identity a user has
+// already seen from this CLI: the embossed "raised slide" mark, the drifting
+// slide/mind wordmark, the dark product palette. Recognition is the security
+// feature here, so this page must keep looking like the gates.
+
+const LOGO_SVG =
+  '<svg xmlns="http://www.w3.org/2000/svg" viewBox="160 160 960 540" preserveAspectRatio="none">' +
+  "<defs>" +
+  '<linearGradient id="rimTop" gradientUnits="userSpaceOnUse" x1="160" y1="0" x2="1120" y2="0">' +
+  '<stop offset="0%" stop-color="#d0e4ff" stop-opacity="0.85"/>' +
+  '<stop offset="35%" stop-color="#fff" stop-opacity="0.5"/>' +
+  '<stop offset="100%" stop-color="#fff" stop-opacity="0"/></linearGradient>' +
+  '<linearGradient id="rimLeft" gradientUnits="userSpaceOnUse" x1="0" y1="160" x2="0" y2="700">' +
+  '<stop offset="0%" stop-color="#d0e4ff" stop-opacity="0.6"/>' +
+  '<stop offset="40%" stop-color="#fff" stop-opacity="0.28"/>' +
+  '<stop offset="100%" stop-color="#fff" stop-opacity="0"/></linearGradient>' +
+  '<linearGradient id="rimBottom" gradientUnits="userSpaceOnUse" x1="1120" y1="0" x2="160" y2="0">' +
+  '<stop offset="0%" stop-color="#000" stop-opacity="0.55"/>' +
+  '<stop offset="60%" stop-color="#000" stop-opacity="0.2"/>' +
+  '<stop offset="100%" stop-color="#000" stop-opacity="0"/></linearGradient>' +
+  '<linearGradient id="rimRight" gradientUnits="userSpaceOnUse" x1="0" y1="700" x2="0" y2="160">' +
+  '<stop offset="0%" stop-color="#000" stop-opacity="0.45"/>' +
+  '<stop offset="60%" stop-color="#000" stop-opacity="0.16"/>' +
+  '<stop offset="100%" stop-color="#000" stop-opacity="0"/></linearGradient>' +
+  '<linearGradient id="faceFill" gradientUnits="userSpaceOnUse" x1="160" y1="160" x2="1120" y2="700">' +
+  '<stop offset="0%" stop-color="#fff" stop-opacity="0.08"/>' +
+  '<stop offset="50%" stop-color="#808080" stop-opacity="0.02"/>' +
+  '<stop offset="100%" stop-color="#000" stop-opacity="0.10"/></linearGradient>' +
+  "</defs>" +
+  '<rect x="160" y="160" width="960" height="540" rx="40" ry="40" fill="url(#faceFill)"/>' +
+  '<path d="M 160,200 A 40,40 0 0 1 200,160 L 1080,160 A 40,40 0 0 1 1120,200" fill="none" stroke="url(#rimTop)" stroke-width="3" stroke-linecap="round"/>' +
+  '<path d="M 160,200 L 160,660 A 40,40 0 0 0 200,700" fill="none" stroke="url(#rimLeft)" stroke-width="2.4" stroke-linecap="round"/>' +
+  '<path d="M 1120,660 A 40,40 0 0 1 1080,700 L 200,700 A 40,40 0 0 1 160,660" fill="none" stroke="url(#rimBottom)" stroke-width="3" stroke-linecap="round"/>' +
+  '<path d="M 1120,660 L 1120,200 A 40,40 0 0 0 1080,160" fill="none" stroke="url(#rimRight)" stroke-width="2.4" stroke-linecap="round"/>' +
+  '<rect x="160" y="160" width="960" height="540" rx="40" ry="40" fill="none" stroke="#fff" stroke-opacity="0.14" stroke-width="1.4"/>' +
+  "</svg>";
+
+function escapeHtml(value) {
+  return String(value).replace(/[<&"]/g, (c) =>
+    c === "<" ? "&lt;" : c === "&" ? "&amp;" : "&quot;",
+  );
+}
+
+const PAGE_CSS = `
+:root{--bg:#111113;--surface:#161618;--border:#2b2b30;--fg:#ededed;--dim:#9a9aa0;
+--accent:#a9c2ff;--success:#2ecc71;--font:'Poppins',ui-sans-serif,system-ui,sans-serif;
+--word:'Urbanist',var(--font);--mono:ui-monospace,SFMono-Regular,Menlo,monospace;}
+*{box-sizing:border-box}
+body{margin:0;min-height:100vh;display:flex;flex-direction:column;align-items:center;
+justify-content:center;gap:20px;padding:40px 20px;font-family:var(--font);color:var(--fg);
+background:radial-gradient(ellipse at center,#141416,#050507 78%);}
+@keyframes drift-a{0%,100%{transform:translateX(-5px)}50%{transform:translateX(5px)}}
+@keyframes drift-b{0%,100%{transform:translateX(5px)}50%{transform:translateX(-5px)}}
+@keyframes rise{from{opacity:0;transform:translateY(14px)}to{opacity:1;transform:none}}
+.logo{width:132px;height:74px;border-radius:11px;overflow:hidden;
+background:linear-gradient(155deg,#262d3d,#0b0e14 76%);
+box-shadow:0 10px 30px rgba(0,0,0,.6),inset 0 1px 0 rgba(255,255,255,.07),
+0 0 0 1px rgba(255,255,255,.05);animation:rise .6s cubic-bezier(.2,.7,.2,1) both;}
+.logo svg{width:100%;height:100%;display:block}
+.word{display:flex;flex-direction:column;gap:6px;font-family:var(--word);font-weight:300;
+font-size:29px;letter-spacing:.58em;line-height:.98;text-align:center;
+animation:rise .6s .06s cubic-bezier(.2,.7,.2,1) both;}
+.word b{font-weight:300;will-change:transform}
+.word .top{animation:drift-a 18s ease-in-out infinite}
+.word .bot{animation:drift-b 18s ease-in-out infinite}
+.tag{display:inline-flex;align-items:center;gap:8px;padding:5px 9px 5px 11px;border-radius:8px;
+border:1px solid #2f3350;background:rgba(153,153,255,.07);font-family:var(--mono);font-size:11.5px;
+font-weight:500;letter-spacing:.24em;text-transform:uppercase;color:#b4b4ff;
+animation:rise .6s .1s cubic-bezier(.2,.7,.2,1) both;}
+.tag .caret{color:#99f;opacity:.75;letter-spacing:0}
+.tag .cur{display:inline-block;width:6px;height:12px;margin-left:-4px;background:#99f;
+animation:blink 1.15s steps(1,end) infinite}
+@keyframes blink{0%,49%{opacity:1}50%,100%{opacity:0}}
+.card{width:min(430px,100%);padding:26px 28px;border-radius:16px;background:var(--surface);
+border:1px solid var(--border);box-shadow:0 24px 60px rgba(0,0,0,.5);text-align:center;
+animation:rise .6s .16s cubic-bezier(.2,.7,.2,1) both;}
+.card h1{margin:0 0 6px;font-size:16.5px;font-weight:600;line-height:1.35}
+.ask{margin:0 0 20px;font-size:12.5px;line-height:1.5;color:var(--dim)}
+.ask b{color:#e4e4e8;font-weight:600}
+.btn{display:inline-flex;align-items:center;justify-content:center;gap:9px;width:100%;
+padding:12px 18px;border-radius:10px;background:#f4f4f5;color:#0f0f0f;text-decoration:none;
+font-weight:600;font-size:13.5px;transition:transform .14s ease,box-shadow .14s ease,background .14s ease}
+.btn:hover{background:#fff;transform:translateY(-1px);box-shadow:0 10px 26px rgba(0,0,0,.5)}
+.btn svg{width:16px;height:16px}
+.foot{margin:16px 0 0;font-size:11.5px;line-height:1.5;color:var(--dim)}
+.foot b{color:#d4d4d8;font-weight:600}
+.state{display:flex;align-items:center;justify-content:center;gap:10px;font-size:16px;font-weight:600}
+.state svg{width:22px;height:22px;color:var(--success)}
+.state.bad svg{color:#f87171}
+code{font-family:var(--mono);font-size:11.5px;color:#d4d4d8;word-break:break-word}
+`;
+
+const CHECK_SVG =
+  '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" ' +
+  'stroke-linecap="round" stroke-linejoin="round"><path d="M20 6 9 17l-5-5"/></svg>';
+const MS_SVG =
+  '<svg viewBox="0 0 24 24"><rect x="2" y="2" width="9.5" height="9.5" fill="#f25022"/>' +
+  '<rect x="12.5" y="2" width="9.5" height="9.5" fill="#7fba00"/>' +
+  '<rect x="2" y="12.5" width="9.5" height="9.5" fill="#00a4ef"/>' +
+  '<rect x="12.5" y="12.5" width="9.5" height="9.5" fill="#ffb900"/></svg>';
+
+// One shell for all three pages, so the sign-in the user is asked to trust and
+// the pages that close it out are visibly the same application.
+function page(title, cardHtml) {
+  return (
+    "<!doctype html><html><head><meta charset=utf-8>" +
+    `<title>${escapeHtml(title)}</title>` +
+    FAVICON_LINK +
+    '<link rel="preconnect" href="https://fonts.googleapis.com">' +
+    '<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>' +
+    '<link rel="stylesheet" href="https://fonts.googleapis.com/css2?' +
+    'family=Poppins:wght@300;400;500;600&family=Urbanist:wght@300&display=swap">' +
+    `<style>${PAGE_CSS}</style></head><body>` +
+    `<div class="logo">${LOGO_SVG}</div>` +
+    '<div class="word"><b class="top">slide</b><b class="bot">mind</b></div>' +
+    '<div class="tag"><span class="caret">&#10095;</span>cli<span class="cur"></span></div>' +
+    `<div class="card">${cardHtml}</div>` +
+    "</body></html>"
+  );
+}
+
+function consentHtml({ env, authorizeUrl }) {
+  // `env` is deliberately NOT shown: which deployment this is tells the user
+  // nothing about whether to trust the prompt, and a URL-ish token next to a
+  // sign-in button reads as noise. WHO is asking, and WHY, is the whole message.
+  void env;
+  return page(
+    "slidemind sign-in",
+    "<h1>Sign in to Microsoft 365</h1>" +
+      '<p class="ask">An <b>AI agent</b> asked slidemind to sign you in, so it can read ' +
+      "content <b>on your behalf</b>.</p>" +
+      `<a class="btn" href="${escapeHtml(authorizeUrl)}">${MS_SVG}Continue with Microsoft</a>` +
+      '<p class="foot">Only what you can already open.<br>' +
+      "Not running a slidemind agent? Close this tab.</p>",
+  );
+}
+
+const SUCCESS_HTML = page(
+  "slidemind signed in",
+  `<div class="state">${CHECK_SVG}<span>Signed in</span></div>` +
+    '<p class="foot">Return to your terminal — slidemind is ready.</p>' +
+    // Best-effort: browsers only honour close() for tabs an external app
+    // opened (which this one is); if refused, the foot line still stands.
+    "<script>setTimeout(function(){window.close()},1500)</script>",
+);
+
+function failureHtml(detail) {
+  return page(
+    "slidemind sign-in failed",
+    '<div class="state bad"><span>Sign-in did not finish</span></div>' +
+      `<p class="foot"><code>${escapeHtml(detail)}</code></p>` +
+      '<p class="foot">Run <code>slidemind login</code> again to retry.</p>',
+  );
+}
+
+// Start the loopback listener and hand back its redirect URI plus a promise for
+// the authorization code. Bound to 127.0.0.1 (never a routable interface) on an
+// ephemeral port; `http://localhost` is registered as a Mobile-and-desktop
+// redirect, which Entra matches on any port.
+function startLoopback({ state, timeoutMs, env }) {
+  return new Promise((resolveStart, rejectStart) => {
+    let settle;
+    // Set once the authorize URL exists (it needs this listener's port first).
+    let authorizeUrl = null;
+    const code = new Promise((resolve, reject) => {
+      settle = { resolve, reject };
+    });
+    const server = http.createServer((req, res) => {
+      const url = new URL(req.url, "http://localhost");
+      if (url.pathname !== "/") {
+        // The browser also asks for /favicon.ico; only the redirect counts.
+        res.statusCode = 404;
+        res.end();
+        return;
+      }
+      res.setHeader("content-type", "text/html; charset=utf-8");
+      res.setHeader("connection", "close");
+      // No `code`/`error` means this is the browser arriving at the start page,
+      // not Entra returning — show slidemind's own explanation and stop. The
+      // listener keeps waiting; the real callback comes back to this same URL.
+      if (!url.searchParams.has("code") && !url.searchParams.has("error")) {
+        res.end(authorizeUrl ? consentHtml({ env, authorizeUrl }) : failureHtml("this sign-in is no longer waiting."));
+        return;
+      }
+      // Settling shuts the listener down and DESTROYS its sockets, so every
+      // branch waits for its page to flush first — otherwise the browser can be
+      // left staring at a blank tab after a perfectly good sign-in.
+      const answer = (html, done) => res.end(html, done);
+      const error = url.searchParams.get("error");
+      const detail = url.searchParams.get("error_description") || error;
+      if (error) {
+        // Conditional Access and consent refusals arrive here as AADSTS codes.
+        // Surfaced verbatim: retrying changes nothing, and the code is what a
+        // tenant admin needs to see.
+        answer(failureHtml(detail), () =>
+          settle.reject(new Error(`Microsoft sign-in was refused: ${detail}`)),
+        );
+        return;
+      }
+      if (url.searchParams.get("state") !== state) {
+        answer(failureHtml("the sign-in response did not match this request."), () =>
+          settle.reject(
+            new Error(
+              "the Microsoft sign-in response did not match this request (state mismatch) — run `slidemind login` again.",
+            ),
+          ),
+        );
+        return;
+      }
+      const received = url.searchParams.get("code");
+      if (!received) {
+        answer(failureHtml("the sign-in response carried no authorization code."), () =>
+          settle.reject(new Error("Microsoft sign-in returned no authorization code.")),
+        );
+        return;
+      }
+      answer(SUCCESS_HTML, () => settle.resolve(received));
+    });
+    const timer = setTimeout(() => {
+      settle.reject(
+        new Error(
+          "timed out waiting for the Microsoft sign-in to finish in the browser. Run `slidemind login` again.",
+        ),
+      );
+    }, timeoutMs);
+    if (timer.unref) timer.unref();
+    server.on("error", (err) => {
+      clearTimeout(timer);
+      rejectStart(err);
+    });
+    const shutdown = () => {
+      clearTimeout(timer);
+      server.close();
+      // The success page's socket is still open (keep-alive); without this the
+      // command would sit on it until the browser gave up.
+      server.closeAllConnections?.();
+    };
+    server.listen(0, "127.0.0.1", () => {
+      const { port } = server.address();
+      const settled = code.finally(shutdown);
+      // Marks the rejection handled without consuming it — a caller that never
+      // reaches `await code` (the opener blew up) must not crash the process
+      // when the wait later times out.
+      settled.catch(() => {});
+      resolveStart({
+        redirectUri: `http://localhost:${port}`,
+        startUrl: `http://localhost:${port}/`,
+        setAuthorizeUrl: (value) => {
+          authorizeUrl = value;
+        },
+        code: settled,
+        // Every abandoned listener holds the event loop open; the caller's
+        // error paths close it.
+        cancel: () => {
+          settle.reject(new Error("sign-in cancelled"));
+        },
+      });
+    });
+  });
+}
+
+// POST the token endpoint. Failures here carry `oauth: true` so callers can tell
+// "Entra rejected this credential" (the refresh token is dead — drop it) from
+// "the network was down" (keep it and try again later).
+async function requestToken(tenantId, form) {
+  let res;
+  try {
+    res = await httpJson("POST", tokenEndpoint(tenantId), { form });
+  } catch (err) {
+    throw new Error(`could not reach Microsoft sign-in: ${err?.message || err}`);
+  }
+  if (res.status === 200 && res.json?.access_token) {
+    // Every mint and every refresh lands here, before any caller can act on the
+    // response or throw with it in scope — so this is where the bearer-shaped
+    // values get registered for output scrubbing. The id_token counts: it is a
+    // credential, not just claims.
+    registerSecret(res.json.access_token);
+    registerSecret(res.json.refresh_token);
+    registerSecret(res.json.id_token);
+    return res.json;
+  }
+  const detail =
+    res.json?.error_description || res.json?.error || res.text || `HTTP ${res.status}`;
+  const err = new Error(String(detail).split("\n")[0]);
+  err.oauth = true;
+  err.code = res.json?.error ?? null;
+  throw err;
+}
+
+// Display-only decode of an id_token payload. NOT a verification: the token
+// arrived over TLS from the endpoint we asked, and nothing here is authorized
+// on its contents — it only names the account in one printed line.
+export function decodeJwtPayload(jwt) {
+  try {
+    const part = String(jwt).split(".")[1];
+    if (!part) return null;
+    return JSON.parse(Buffer.from(part, "base64url").toString("utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function accountName(claims) {
+  if (!claims) return null;
+  for (const key of ["preferred_username", "upn", "email", "unique_name", "name"]) {
+    if (typeof claims[key] === "string" && claims[key]) return claims[key];
+  }
+  return null;
+}
+
+// The paired CLI session's identity, as the backend sees it. Called at login
+// time only, to bind the browser sign-in to the session that will spend it.
+async function sessionIdentity(backendURL, sessionToken) {
+  const res = await httpJson("GET", `${backendURL}/api/cli/whoami`, {
+    token: sessionToken,
+  });
+  if (res.status !== 200 || !res.json?.oid) {
+    throw new Error(
+      `could not confirm who this CLI is paired as${envPhrase(deriveEnvLabel(backendURL), "on")} — ` +
+        "run `slidemind doctor` and sign in again once the connection is healthy.",
+    );
+  }
+  return { oid: String(res.json.oid), tid: res.json.tid ? String(res.json.tid) : null };
+}
+
+// Refuse a sign-in that is not the paired session's own identity. The authority
+// is tenant-pinned, so a foreign-tenant account already dies at Microsoft — but
+// a same-tenant COLLEAGUE would pass, and then every SharePoint byte would be
+// fetched as them for a session authorized as someone else. The id_token here is
+// not signature-verified: it arrived over TLS from the token endpoint we chose,
+// and this is a self-protection binding, not an authentication decision.
+function assertTokenIdentity({ claims, tenantId, session, env }) {
+  if (!claims?.tid || claims.tid !== tenantId) {
+    throw new Error(
+      `Microsoft sign-in came back from the wrong tenant (expected this deployment's tenant${envPhrase(env, "on")}). ` +
+        "Sign in with the account you use in PowerPoint there.",
+    );
+  }
+  if (!claims?.oid) {
+    // No account id in the id_token at all — nothing to bind against. That is a
+    // sign-in CONFIGURATION fault (a missing `profile` scope, an app that
+    // suppresses the claim), not the user picking the wrong account, so say so
+    // rather than sending them round the picker again.
+    throw new Error(
+      "the Microsoft sign-in returned no account id, so slidemind cannot confirm it is " +
+        `the user this CLI is paired as${envPhrase(env, "on")}. This is a sign-in configuration ` +
+        "problem — report it rather than retrying.",
+    );
+  }
+  if (claims.oid !== session.oid) {
+    // Name the account that came back: the picker often holds several, and
+    // "wrong account" is unactionable until you know which one you picked.
+    const who = accountName(claims);
+    throw new Error(
+      `${who ? `'${who}'` : "that Microsoft account"} is not the user this CLI is ` +
+        `paired as${envPhrase(env, "on")}. Sign in with the same account you used when connecting ` +
+        "the CLI (the one you use in PowerPoint), or re-run setup from that account's add-in.",
+    );
+  }
+}
+
+// Whether this backend holds a stored Graph sign-in. Storage only — no network,
+// so remediation text can ask it for free.
+export function hasGraphSession(backendURL) {
+  return Boolean(backendURL) && Boolean(getGraphRefreshToken(backendURL));
+}
+
+// ---------------------------------------------------------------------------
+// Auto sign-in: login happens where it is needed, not as a separate ritual.
+//
+// Any command that reaches the engine surface needs the user's own delegated
+// tokens; instead of failing with "run `slidemind login`", the CLI runs that
+// sign-in ITSELF — opens the browser, prints what it is waiting for, and blocks
+// until the human finishes (or the 5-minute window closes). With a stored
+// refresh token this is a no-op, so a signed-in user never sees it; the browser
+// appears exactly once per machine per ~90 days.
+//
+// One attempt per backend per process: an abandoned or refused sign-in must not
+// reopen the browser on every retry of a loop — the command then proceeds
+// token-less and meets the backend's typed `login_required`, which names the
+// manual `slidemind login` for whenever the user is ready.
+
+const autoLoginPending = new Map();
+const autoLoginFailed = new Set();
+
+/**
+ * Make sure this backend has a Microsoft 365 sign-in, interactively if needed.
+ * Returns true when a sign-in is stored afterwards. Never throws.
+ * `open` is a test seam only — production callers pass nothing and get the
+ * same hardened opener `slidemind login` uses.
+ */
+export async function ensureSignedIn(backendURL, { open = null } = {}) {
+  if (!backendURL) return false;
+  if (getGraphRefreshToken(backendURL)) return true;
+  if (autoLoginFailed.has(backendURL)) return false;
+  let pending = autoLoginPending.get(backendURL);
+  if (!pending) {
+    pending = (async () => {
+      const env = deriveEnvLabel(backendURL);
+      process.stderr.write(
+        `Microsoft 365 sign-in needed${envPhrase(env, "for")} — opening your browser. ` +
+          "Finish the sign-in there; this command waits for it.\n",
+      );
+      const result = await loginGraph({
+        backendURL,
+        open,
+        onUrl: (url) =>
+          process.stderr.write(`  if no browser opened, open: ${url}\n`),
+      });
+      process.stderr.write(
+        `Signed in${result.username ? ` as ${result.username}` : ""}${envPhrase(env, "for")}.\n`,
+      );
+    })().finally(() => {
+      autoLoginPending.delete(backendURL);
+    });
+    autoLoginPending.set(backendURL, pending);
+  }
+  try {
+    await pending;
+    return true;
+  } catch (err) {
+    autoLoginFailed.add(backendURL);
+    process.stderr.write(
+      `Microsoft 365 sign-in did not finish: ${err?.message ?? err}\n` +
+        "Continuing without it — corpus search will answer `login_required` until " +
+        "`slidemind login` succeeds.\n",
+    );
+    return false;
+  }
+}
+
+// Drop a backend's Microsoft 365 sign-in (a revoked token, or `slidemind
+// logout`) — both resource tokens go with the refresh token they came from.
+export function clearGraphSession(backendURL) {
+  accessTokenCache.delete(cacheKey(backendURL, "graph"));
+  accessTokenCache.delete(cacheKey(backendURL, "sharepoint"));
+  return setGraphRefreshToken(backendURL, null);
+}
+
+/**
+ * Run the interactive sign-in for one backend and persist the refresh token.
+ * Returns { username, tenantId, env }.
+ *
+ * `open` is injected so this module stays free of the builders' browser chain
+ * in tests; the default is the same hardened opener the review/plan gates use.
+ * `onUrl` receives slidemind's local start URL before the browser is launched —
+ * the CLI prints it so a machine where no opener works is still recoverable by
+ * hand (that page then links on to Microsoft).
+ */
+export async function loginGraph({
+  backendURL,
+  open = null,
+  onUrl = null,
+  timeoutMs = LOGIN_TIMEOUT_MS,
+} = {}) {
+  if (!backendURL) throw new Error("loginGraph: backendURL is required");
+  const session = getSessionFor(backendURL);
+  if (!session) {
+    throw new Error(
+      `slidemind is not connected to '${deriveEnvLabel(backendURL)}'.`,
+    );
+  }
+  const { clientId, tenantId } = await discoverAppRegistration(backendURL);
+  // Fetched BEFORE the browser opens: if the session is dead the user learns it
+  // now, not after completing an MFA dance whose result would be thrown away.
+  const paired = await sessionIdentity(backendURL, session.sessionToken);
+  const { verifier, challenge } = pkcePair();
+  const state = base64url(crypto.randomBytes(16));
+  const { redirectUri, startUrl, setAuthorizeUrl, code, cancel } = await startLoopback({
+    state,
+    timeoutMs,
+    env: deriveEnvLabel(backendURL),
+  });
+
+  const authorizeUrl = new URL(authorizeEndpoint(tenantId));
+  authorizeUrl.search = new URLSearchParams({
+    client_id: clientId,
+    response_type: "code",
+    redirect_uri: redirectUri,
+    scope: GRAPH_SCOPE,
+    code_challenge: challenge,
+    code_challenge_method: "S256",
+    state,
+    // The CLI may be signing in as a different account than the browser's
+    // default — never silently reuse whoever the browser happens to hold.
+    prompt: "select_account",
+  }).toString();
+
+  // The browser is sent to slidemind's own page first, which then links on to
+  // Microsoft. The user must see WHO asked before a sign-in prompt appears —
+  // an agent may have started this without them.
+  setAuthorizeUrl(authorizeUrl.toString());
+
+  let tokens;
+  try {
+    if (onUrl) onUrl(startUrl);
+    const opener = open ?? (await import("../builders/build.mjs")).openInBrowser;
+    await opener(startUrl, { quiet: true });
+
+    const authCode = await code;
+    tokens = await requestToken(tenantId, {
+      client_id: clientId,
+      grant_type: "authorization_code",
+      code: authCode,
+      redirect_uri: redirectUri,
+      code_verifier: verifier,
+      scope: GRAPH_SCOPE,
+    });
+  } catch (err) {
+    cancel();
+    throw err;
+  }
+  if (!tokens.refresh_token) {
+    throw new Error(
+      "Microsoft sign-in returned no refresh token — the app registration is missing the offline_access grant.",
+    );
+  }
+  const claims = decodeJwtPayload(tokens.id_token);
+  assertTokenIdentity({
+    claims,
+    tenantId,
+    session: paired,
+    env: deriveEnvLabel(backendURL),
+  });
+  if (!setGraphRefreshToken(backendURL, tokens.refresh_token)) {
+    throw new Error(
+      `slidemind is not connected to '${deriveEnvLabel(backendURL)}'.`,
+    );
+  }
+  cacheAccessToken(backendURL, tokens);
+  // Mint the SharePoint-resource sibling right away (same refresh token) so a
+  // missing SharePoint consent surfaces HERE, at sign-in, with a human present
+  // — not as a silent login_required in the middle of an agent run. Best-effort:
+  // the sign-in itself already succeeded.
+  const { sharePointResource } = await discoverAppRegistration(backendURL);
+  if (sharePointResource) {
+    const spToken = await getSharePointToken(backendURL);
+    if (!spToken) {
+      process.stderr.write(
+        `signed in, but no SharePoint access token could be minted${envPhrase(deriveEnvLabel(backendURL), "for")} — ` +
+          "corpus search against SharePoint content will stay unavailable. " +
+          "This is an app-registration/consent problem to report, not a retry.\n",
+      );
+    }
+  }
+  return {
+    username: accountName(claims),
+    tenantId,
+    env: deriveEnvLabel(backendURL),
+  };
+}
+
+// Access tokens live in memory only — they are minutes-long and re-mintable
+// from the stored refresh token, so writing them to disk would add exposure for
+// nothing. Keyed by backend + resource: two connected environments are two
+// sign-ins, and each sign-in mints one Graph and (where the deployment has
+// SharePoint) one SharePoint token from the SAME refresh token.
+const accessTokenCache = new Map(); // `${backendURL}${resource}` → { token, expiresAt }
+const cacheKey = (backendURL, resource) => `${backendURL}${resource}`;
+
+// Every refresh SPENDS the stored refresh token (AAD rotates it), and the two
+// resources share it — so all mints for one backend are serialized on a single
+// chain. Two concurrent Graph picks join the same promise; a Graph and a
+// SharePoint mint run one after the other, each persisting the rotation before
+// the next redeems it.
+const refreshChain = new Map();
+
+function withRefreshLock(backendURL, fn) {
+  const tail = refreshChain.get(backendURL) ?? Promise.resolve();
+  const next = tail.then(fn, fn);
+  refreshChain.set(
+    backendURL,
+    next.catch(() => {}),
+  );
+  return next;
+}
+
+function cacheAccessToken(backendURL, tokens, resource = "graph") {
+  const lifetimeMs = (Number(tokens.expires_in) || 3600) * 1000;
+  accessTokenCache.set(cacheKey(backendURL, resource), {
+    token: tokens.access_token,
+    expiresAt: Date.now() + lifetimeMs,
+  });
+}
+
+/**
+ * A usable Graph access token for one backend, or null.
+ *
+ * Null is the ordinary answer — not logged in, or the sign-in has aged out —
+ * and it means "carry on without one": the caller then meets the backend's
+ * typed `login_required` answer, which is the remediation. So this NEVER
+ * throws.
+ */
+export async function getGraphToken(backendURL) {
+  return resourceToken(backendURL, "graph");
+}
+
+/**
+ * A usable SharePoint-resource access token for one backend, or null.
+ *
+ * Null when not signed in, when the deployment has no SharePoint configured
+ * (nothing to mint a token FOR), or when Entra refuses the mint. Redeemed from
+ * the same refresh token as the Graph token — one sign-in, two resources.
+ */
+export async function getSharePointToken(backendURL) {
+  return resourceToken(backendURL, "sharepoint");
+}
+
+async function resourceToken(backendURL, resource) {
+  if (!backendURL) return null;
+  if (!getGraphRefreshToken(backendURL)) return null; // not logged in: no network, no cost
+  const cached = accessTokenCache.get(cacheKey(backendURL, resource));
+  if (cached && cached.expiresAt - EXPIRY_SKEW_MS > Date.now()) return cached.token;
+  // Serialized per backend (see withRefreshLock): concurrent picks must not
+  // each spend a rotation, and the sibling resource's mint must see the
+  // rotation this one persists.
+  return withRefreshLock(backendURL, async () => {
+    // Re-check under the lock — the mint that just finished may have been ours.
+    const fresh = accessTokenCache.get(cacheKey(backendURL, resource));
+    if (fresh && fresh.expiresAt - EXPIRY_SKEW_MS > Date.now()) return fresh.token;
+    const stored = getGraphRefreshToken(backendURL);
+    if (!stored) return null;
+    return refreshResourceToken(backendURL, resource, stored);
+  });
+}
+
+// One expiry note per backend per process: parallel picks would otherwise print
+// it once per download, burying the one line the agent needs to relay.
+const expiryNoted = new Set();
+
+async function refreshResourceToken(backendURL, resource, storedRefreshToken) {
+  let tokens;
+  let scope;
+  try {
+    const { clientId, tenantId, sharePointResource } =
+      await discoverAppRegistration(backendURL);
+    if (resource === "sharepoint") {
+      // No SharePoint on this deployment — there is no resource to mint for,
+      // and that is a resolved answer, not a failure.
+      if (!sharePointResource) return null;
+      scope = sharePointScope(sharePointResource);
+    } else {
+      scope = GRAPH_SCOPE;
+    }
+    tokens = await requestToken(tenantId, {
+      client_id: clientId,
+      grant_type: "refresh_token",
+      refresh_token: storedRefreshToken,
+      scope,
+    });
+  } catch (err) {
+    // Only Entra REFUSING the credential proves it is dead (revoked, expired
+    // past the sliding window, consent withdrawn). A backend that was
+    // unreachable for a moment must not cost the user their sign-in — and a
+    // SharePoint-scope consent refusal must not kill the Graph half either, so
+    // only the errors that name the CREDENTIAL clear the session.
+    const credentialDead =
+      err?.oauth &&
+      ["invalid_grant", "interaction_required", "unauthorized_client"].includes(
+        String(err?.code ?? ""),
+      );
+    if (credentialDead) {
+      clearGraphSession(backendURL);
+      // Said HERE, at the moment the sign-in dies, so the agent driving this
+      // command can tell the difference between "never signed in" (silent —
+      // nothing changed) and "was signed in, needs the human again" — otherwise
+      // all it sees is a downstream login_required with no cause.
+      if (!expiryNoted.has(backendURL)) {
+        expiryNoted.add(backendURL);
+        process.stderr.write(
+          `Microsoft 365 sign-in expired${envPhrase(deriveEnvLabel(backendURL), "for")} — ` +
+            "corpus search and SharePoint content need the user to run `slidemind login` again.\n",
+        );
+      }
+    }
+    return null;
+  }
+  // Rotation: AAD issues a new refresh token on every refresh and the old one
+  // is spent. Persisting it is what keeps the ~90-day window sliding.
+  if (tokens.refresh_token) setGraphRefreshToken(backendURL, tokens.refresh_token);
+  cacheAccessToken(backendURL, tokens, resource);
+  return tokens.access_token;
+}