@patimweb/pi-teams 1.0.0 → 1.1.0

package/src/auth/index.ts

@@ -1,19 +1,79 @@
 /**
  * Auth resolver — hands the Graph layer a valid bearer token.
  *
- * Order of preference for a delegated connection:
- *   1. a cached access token that is still fresh
- *   2. a refresh of the cached refresh token
- *   3. nothing — the caller must run `teams_login`
+ * Built on MSAL, so the flows that matter are one call each:
  *
- * App-only connections skip the cache-refresh dance; a new token is cheap and
- * there is no user to interrupt.
+ *   - **interactive**: `acquireTokenInteractive` opens the system browser at
+ *     the Microsoft sign-in page, listens on a loopback port for the redirect,
+ *     and does PKCE. The default whenever a browser is actually reachable.
+ *   - **device code**: `acquireTokenByDeviceCode` for SSH, containers and
+ *     anything headless — the user types a short code on another device.
+ *   - **client credentials**: app-only, no user. Cannot post as a person; the
+ *     safety layer refuses those tools rather than letting Graph reject them.
+ *
+ * Silent renewal is MSAL's `acquireTokenSilent`, which uses the cached refresh
+ * token and rotates it. The cache lives on disk (see ./cache-plugin.ts), so a
+ * sign-in survives across pi sessions.
  */
 
+import {
+	InteractionRequiredAuthError,
+	type AccountInfo,
+	type AuthenticationResult,
+} from "@azure/msal-node";
 import type { TeamsConnection } from "../config/index.ts";
-import { AuthError, refreshAccessToken } from "./device-code.ts";
-import { acquireAppToken } from "./client-credentials.ts";
-import { getToken, saveToken, isFresh, type CachedToken } from "./token-store.ts";
+import { removeAllCaches, removeCache, readCacheSummary } from "./cache-plugin.ts";
+import {
+	ERROR_TEMPLATE,
+	SUCCESS_TEMPLATE,
+	browserUnavailableReason,
+	canOpenBrowser,
+	getConfidentialApp,
+	getPublicApp,
+	openBrowser,
+	requestScopes,
+	resetApps,
+} from "./msal.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A usable bearer token plus who it belongs to. */
+export interface TokenInfo {
+	accessToken: string;
+	expiresOn?: Date;
+	scopes: string[];
+	account?: SignedInAccount;
+}
+
+export interface SignedInAccount {
+	homeAccountId: string;
+	username: string;
+	name?: string;
+	tenantId: string;
+}
+
+/** How a sign-in was performed, or should be. */
+export type SignInMode = "interactive" | "device-code";
+
+/** What the user must do to complete a device code sign-in. */
+export interface DeviceCodeInfo {
+	userCode: string;
+	verificationUri: string;
+	message: string;
+	expiresIn: number;
+}
+
+/** A failure from the identity provider. */
+export class AuthError extends Error {
+	readonly code: string;
+	constructor(code: string, message: string) {
+		super(message);
+		this.name = "AuthError";
+		this.code = code;
+	}
+}
 
 /** Raised when there is no usable token and only the user can fix it. */
 export class NotSignedInError extends Error {
@@ -30,76 +90,263 @@ export class NotSignedInError extends Error {
 	}
 }
 
-/** In-process cache so a burst of Graph calls does not re-read the token file. */
-const memoryCache = new Map<string, CachedToken>();
+// ---------------------------------------------------------------------------
+// Shaping
+// ---------------------------------------------------------------------------
+
+function toAccount(account: AccountInfo | null): SignedInAccount | undefined {
+	if (!account) return undefined;
+	return {
+		homeAccountId: account.homeAccountId,
+		username: account.username,
+		name: account.name,
+		tenantId: account.tenantId,
+	};
+}
+
+function toTokenInfo(result: AuthenticationResult): TokenInfo {
+	return {
+		accessToken: result.accessToken,
+		expiresOn: result.expiresOn ?? undefined,
+		scopes: result.scopes ?? [],
+		account: toAccount(result.account),
+	};
+}
+
+function wrapError(err: unknown): never {
+	if (err instanceof AuthError || err instanceof NotSignedInError) throw err;
+	const error = err as { errorCode?: string; errorMessage?: string; message?: string };
+	throw new AuthError(
+		error.errorCode ?? "auth_failed",
+		error.errorMessage ?? error.message ?? String(err),
+	);
+}
+
+// ---------------------------------------------------------------------------
+// Account lookup
+// ---------------------------------------------------------------------------
+
+/** The cached account for a connection, if the user has signed in before. */
+export async function cachedAccount(conn: TeamsConnection): Promise<SignedInAccount | undefined> {
+	const accounts = await getPublicApp(conn).getTokenCache().getAllAccounts();
+	if (accounts.length === 0) return undefined;
+
+	// One cache file per account+tenant, so there is normally exactly one. When
+	// a user has signed in as more than one identity, prefer this tenant's.
+	const match =
+		accounts.find((account) => account.tenantId?.toLowerCase() === conn.tenantId.toLowerCase()) ??
+		accounts[0];
+	return toAccount(match ?? null);
+}
 
-function memKey(conn: TeamsConnection): string {
-	return `${conn.account.toLowerCase()}::${conn.tenantId.toLowerCase()}`;
+/** Cheap, synchronous "has this connection ever signed in" — for status output. */
+export function hasCachedSession(conn: TeamsConnection): boolean {
+	return readCacheSummary(conn.account, conn.tenantId).present;
 }
 
+// ---------------------------------------------------------------------------
+// Silent acquisition
+// ---------------------------------------------------------------------------
+
 /**
- * Get a bearer token for this connection, refreshing it when needed.
+ * Get a token for this connection, renewing it silently when needed.
  *
- * @throws {NotSignedInError} when a delegated sign-in is required
+ * @throws {NotSignedInError} when only an interactive sign-in can help
  * @throws {AuthError} when the identity provider refuses
  */
 export async function getAccessToken(
 	conn: TeamsConnection,
-	signal?: AbortSignal,
-): Promise<CachedToken> {
-	const key = memKey(conn);
+	_signal?: AbortSignal,
+): Promise<TokenInfo> {
+	if (conn.authMode === "client-credentials") {
+		if (!conn.clientSecret) {
+			throw new AuthError(
+				"missing_client_secret",
+				`Account "${conn.account}" uses client-credentials but has no clientSecret.`,
+			);
+		}
+		try {
+			const result = await getConfidentialApp(conn).acquireTokenByClientCredential({
+				scopes: ["https://graph.microsoft.com/.default"],
+			});
+			if (!result) throw new AuthError("no_token", "Microsoft returned no app-only token.");
+			return toTokenInfo(result);
+		} catch (err) {
+			wrapError(err);
+		}
+	}
 
-	const inMemory = memoryCache.get(key);
-	if (isFresh(inMemory)) return inMemory!;
+	const app = getPublicApp(conn);
+	const accounts = await app.getTokenCache().getAllAccounts();
+	const account =
+		accounts.find((entry) => entry.tenantId?.toLowerCase() === conn.tenantId.toLowerCase()) ??
+		accounts[0];
 
-	if (conn.authMode === "client-credentials") {
-		const token = await acquireAppToken(conn, signal);
-		memoryCache.set(key, token);
-		saveToken(conn.account, conn.tenantId, token);
-		return token;
+	if (!account) throw new NotSignedInError(conn.account, conn.tenant);
+
+	try {
+		const result = await app.acquireTokenSilent({
+			account,
+			scopes: requestScopes(conn),
+		});
+		if (!result) throw new NotSignedInError(conn.account, conn.tenant);
+		return toTokenInfo(result);
+	} catch (err) {
+		// Password change, revoked session, conditional access, a new scope the
+		// cached refresh token was never granted — all need the user back.
+		if (err instanceof InteractionRequiredAuthError) {
+			throw new NotSignedInError(
+				conn.account,
+				conn.tenant,
+				"the saved sign-in expired or needs to be renewed",
+			);
+		}
+		wrapError(err);
 	}
+}
+
+// ---------------------------------------------------------------------------
+// Sign-in
+// ---------------------------------------------------------------------------
+
+export interface SignInOptions {
+	/** Force a flow instead of letting the environment decide */
+	mode?: SignInMode;
+	/** Called once with the code and URL when the device code flow is used */
+	onDeviceCode?: (info: DeviceCodeInfo) => void;
+	/** Called just before the browser opens */
+	onBrowser?: (url: string) => void;
+	/** Fixed loopback port, for tenants that require an exact redirect URI */
+	loopbackPort?: number;
+	/** How long to wait for the user, in milliseconds (default 5 minutes) */
+	timeoutMs?: number;
+	signal?: AbortSignal;
+}
+
+export interface SignInResult extends TokenInfo {
+	/** Which flow actually ran */
+	mode: SignInMode;
+}
 
-	const cached = getToken(conn.account, conn.tenantId);
+/** Pick a flow for this environment. */
+export function defaultSignInMode(): SignInMode {
+	return canOpenBrowser() ? "interactive" : "device-code";
+}
 
-	if (isFresh(cached)) {
-		memoryCache.set(key, cached!);
-		return cached!;
+export { browserUnavailableReason, canOpenBrowser };
+
+function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
+	return new Promise<T>((resolve, reject) => {
+		const timer = setTimeout(() => {
+			reject(new AuthError("timeout", `${label} timed out after ${Math.round(ms / 1000)}s.`));
+		}, ms);
+		promise.then(
+			(value) => {
+				clearTimeout(timer);
+				resolve(value);
+			},
+			(err) => {
+				clearTimeout(timer);
+				reject(err);
+			},
+		);
+	});
+}
+
+/**
+ * Sign in as the user.
+ *
+ * Interactive by default: the browser opens, the user signs in with their own
+ * credentials and MFA, and MSAL catches the redirect on a loopback port. On a
+ * machine where that cannot work, the device code flow takes over.
+ */
+export async function signIn(
+	conn: TeamsConnection,
+	options: SignInOptions = {},
+): Promise<SignInResult> {
+	if (conn.authMode === "client-credentials") {
+		const token = await getAccessToken(conn, options.signal);
+		return { ...token, mode: "device-code" };
 	}
 
-	if (cached?.refreshToken) {
+	const mode = options.mode ?? (conn.authMode === "device-code" ? "device-code" : defaultSignInMode());
+	const app = getPublicApp(conn);
+	const scopes = requestScopes(conn);
+	const timeoutMs = options.timeoutMs ?? 5 * 60 * 1000;
+
+	if (mode === "interactive") {
 		try {
-			const refreshed = await refreshAccessToken(conn, cached.refreshToken, signal);
-			// Keep the identity we already know; a refresh response carries no id_token
-			// unless openid was requested again.
-			const merged: CachedToken = { ...refreshed, user: refreshed.user ?? cached.user };
-			memoryCache.set(key, merged);
-			saveToken(conn.account, conn.tenantId, merged);
-			return merged;
+			const result = await withTimeout(
+				app.acquireTokenInteractive({
+					scopes,
+					openBrowser: async (url: string) => {
+						options.onBrowser?.(url);
+						await openBrowser(url);
+					},
+					successTemplate: SUCCESS_TEMPLATE,
+					errorTemplate: ERROR_TEMPLATE,
+					...(options.loopbackPort ? { preferredPort: options.loopbackPort } : {}),
+				}),
+				timeoutMs,
+				"Browser sign-in",
+			);
+			if (!result) throw new AuthError("no_token", "Microsoft returned no token.");
+			return { ...toTokenInfo(result), mode: "interactive" };
 		} catch (err) {
-			if (err instanceof AuthError && err.code === "invalid_grant") {
-				throw new NotSignedInError(conn.account, conn.tenant, "the saved sign-in expired or was revoked");
-			}
-			throw err;
+			wrapError(err);
 		}
 	}
 
-	throw new NotSignedInError(conn.account, conn.tenant);
+	try {
+		const result = await withTimeout(
+			app.acquireTokenByDeviceCode({
+				scopes,
+				deviceCodeCallback: (response) => {
+					options.onDeviceCode?.({
+						userCode: response.userCode,
+						verificationUri: response.verificationUri,
+						message: response.message,
+						expiresIn: response.expiresIn,
+					});
+				},
+			}),
+			timeoutMs,
+			"Device code sign-in",
+		);
+		if (!result) throw new AuthError("no_token", "Microsoft returned no token.");
+		return { ...toTokenInfo(result), mode: "device-code" };
+	} catch (err) {
+		wrapError(err);
+	}
 }
 
-/** Store a freshly acquired token (used by `teams_login`). */
-export function storeToken(conn: TeamsConnection, token: CachedToken): void {
-	memoryCache.set(memKey(conn), token);
-	saveToken(conn.account, conn.tenantId, token);
-}
+// ---------------------------------------------------------------------------
+// Sign-out
+// ---------------------------------------------------------------------------
+
+/** Remove one cached session. Returns true when something was removed. */
+export async function signOut(conn: TeamsConnection): Promise<boolean> {
+	// Ask MSAL to forget the account first so its in-memory copy goes too;
+	// removing only the file would leave this process still holding tokens.
+	try {
+		const cache = getPublicApp(conn).getTokenCache();
+		for (const account of await cache.getAllAccounts()) {
+			await cache.removeAccount(account);
+		}
+	} catch {
+		/* the file removal below is what actually matters */
+	}
 
-/** Forget the in-process token — the file cache is handled by token-store. */
-export function forgetToken(conn: TeamsConnection): void {
-	memoryCache.delete(memKey(conn));
+	const removed = removeCache(conn.account, conn.tenantId);
+	resetApps();
+	return removed;
 }
 
-/** Drop every in-process token. */
-export function clearMemoryCache(): void {
-	memoryCache.clear();
+/** Remove every cached session. Returns how many were removed. */
+export function signOutAll(): number {
+	const removed = removeAllCaches();
+	resetApps();
+	return removed;
 }
 
-export { AuthError };
+export { resetApps };

package/src/auth/msal.ts

@@ -0,0 +1,168 @@
+/**
+ * MSAL application factory and the browser plumbing around it.
+ *
+ * MSAL handles the parts of OAuth that are tedious to get right — PKCE, the
+ * loopback listener, refresh-token rotation, cross-tenant authorities — so
+ * this module's job is narrow: build one application per connection, decide
+ * whether a browser is actually reachable, and open it.
+ */
+
+import { spawn } from "node:child_process";
+import {
+	ConfidentialClientApplication,
+	LogLevel,
+	PublicClientApplication,
+	type Configuration,
+} from "@azure/msal-node";
+import type { TeamsConnection } from "../config/index.ts";
+import { browserUnavailableReason, canOpenBrowser } from "../utils/environment.ts";
+import { createCachePlugin } from "./cache-plugin.ts";
+
+export { browserUnavailableReason, canOpenBrowser };
+
+// ---------------------------------------------------------------------------
+// Reserved scopes
+// ---------------------------------------------------------------------------
+
+/**
+ * MSAL adds these itself and rejects them in a request's scope list.
+ * They stay in the documented defaults because the doctor reports on them.
+ */
+const RESERVED_SCOPES = new Set(["openid", "profile", "offline_access", "email"]);
+
+export function requestScopes(conn: TeamsConnection): string[] {
+	return conn.scopes.filter((scope) => !RESERVED_SCOPES.has(scope.toLowerCase()));
+}
+
+// ---------------------------------------------------------------------------
+// Application factory
+// ---------------------------------------------------------------------------
+
+const publicApps = new Map<string, PublicClientApplication>();
+const confidentialApps = new Map<string, ConfidentialClientApplication>();
+
+function appKey(conn: TeamsConnection): string {
+	return `${conn.account.toLowerCase()}::${conn.tenantId.toLowerCase()}::${conn.clientId}`;
+}
+
+function baseConfig(conn: TeamsConnection): Configuration {
+	return {
+		auth: {
+			clientId: conn.clientId,
+			authority: `${conn.authorityHost}/${conn.tenantId}`,
+		},
+		cache: {
+			cachePlugin: createCachePlugin(conn.account, conn.tenantId),
+		},
+		system: {
+			loggerOptions: {
+				// MSAL logs to stdout by default, which would scribble over the TUI.
+				loggerCallback: () => {},
+				piiLoggingEnabled: false,
+				logLevel: LogLevel.Error,
+			},
+		},
+	};
+}
+
+/** The public client — used for every delegated (act-as-the-user) flow. */
+export function getPublicApp(conn: TeamsConnection): PublicClientApplication {
+	const key = appKey(conn);
+	const existing = publicApps.get(key);
+	if (existing) return existing;
+
+	const app = new PublicClientApplication(baseConfig(conn));
+	publicApps.set(key, app);
+	return app;
+}
+
+/** The confidential client — app-only tokens. */
+export function getConfidentialApp(conn: TeamsConnection): ConfidentialClientApplication {
+	const key = appKey(conn);
+	const existing = confidentialApps.get(key);
+	if (existing) return existing;
+
+	const config = baseConfig(conn);
+	const app = new ConfidentialClientApplication({
+		...config,
+		auth: { ...config.auth, clientSecret: conn.clientSecret },
+	});
+	confidentialApps.set(key, app);
+	return app;
+}
+
+/** Drop the cached applications (after a sign-out or a config change). */
+export function resetApps(): void {
+	publicApps.clear();
+	confidentialApps.clear();
+}
+
+// ---------------------------------------------------------------------------
+// Browser
+// ---------------------------------------------------------------------------
+
+/** Open a URL in the user's default browser, detached from this process. */
+export function openBrowser(url: string): Promise<void> {
+	return new Promise((resolve, reject) => {
+		const [command, args] =
+			process.platform === "darwin"
+				? ["open", [url]]
+				: process.platform === "win32"
+					? // `start` is a shell builtin, and the empty string is the window
+						// title cmd.exe would otherwise take the URL for.
+						["cmd.exe", ["/c", "start", "", url]]
+					: ["xdg-open", [url]];
+
+		try {
+			const child = spawn(command as string, args as string[], {
+				detached: true,
+				stdio: "ignore",
+			});
+			child.on("error", reject);
+			child.unref();
+			resolve();
+		} catch (err) {
+			reject(err instanceof Error ? err : new Error(String(err)));
+		}
+	});
+}
+
+// ---------------------------------------------------------------------------
+// Browser response pages
+// ---------------------------------------------------------------------------
+
+function page(title: string, message: string, accent: string): string {
+	return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<title>${title}</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { margin: 0; min-height: 100vh; display: grid; place-items: center;
+         font: 16px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif;
+         background: #fbfbfa; color: #1a1a18; }
+  @media (prefers-color-scheme: dark) { body { background: #1a1a18; color: #f5f4ef; } }
+  .card { max-width: 28rem; padding: 2.5rem; text-align: center; }
+  .mark { width: 3rem; height: 3rem; margin: 0 auto 1.25rem; border-radius: 50%;
+          background: ${accent}; display: grid; place-items: center;
+          color: #fff; font-size: 1.5rem; }
+  h1 { font-size: 1.25rem; margin: 0 0 .5rem; }
+  p { margin: 0; opacity: .7; }
+</style></head>
+<body><div class="card">
+  <div class="mark">${accent === "#2f7d4f" ? "&check;" : "!"}</div>
+  <h1>${title}</h1>
+  <p>${message}</p>
+</div></body></html>`;
+}
+
+export const SUCCESS_TEMPLATE = page(
+	"Signed in to Teams",
+	"pi can now act as you in Microsoft Teams. You can close this tab and go back to your terminal.",
+	"#2f7d4f",
+);
+
+export const ERROR_TEMPLATE = page(
+	"Sign-in failed",
+	"Microsoft rejected the sign-in. Close this tab and check the error in your terminal.",
+	"#b03a2e",
+);