@remit/mail-oauth-service 0.0.1

package/package.json

@@ -0,0 +1,27 @@
+{
+	"name": "@remit/mail-oauth-service",
+	"version": "0.0.1",
+	"type": "module",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"default": "./src/index.ts"
+		}
+	},
+	"scripts": {
+		"test:typecheck": "tsgo --noEmit",
+		"test:run": "node --import tsx --test 'src/**/*.test.ts'",
+		"test": "npm run test:typecheck && npm run test:run"
+	},
+	"license": "MIT",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/remit-mail/remit.git",
+		"directory": "packages/mail-oauth-service"
+	}
+}

package/src/__tests__/mail-oauth-service.test.ts

@@ -0,0 +1,398 @@
+import assert from "node:assert/strict";
+import { after, before, describe, test } from "node:test";
+
+import {
+	createMailOAuthService,
+	microsoftProviderConfig,
+	RefreshTokenError,
+} from "../index.js";
+import type { OAuthProviderConfig } from "../types.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeConfig(
+	overrides?: Partial<OAuthProviderConfig>,
+): OAuthProviderConfig {
+	return microsoftProviderConfig({
+		clientId: "test-client-id",
+		clientSecret: "test-client-secret",
+		overrides: {
+			tokenEndpoint: "https://example.com/token",
+			authorizationEndpoint: "https://example.com/authorize",
+			...overrides,
+		},
+	});
+}
+
+function nowSecs(): number {
+	return Math.floor(Date.now() / 1000);
+}
+
+/** Build a fake fetch that returns the given JSON body with the given HTTP status. */
+function makeFetch(status: number, body: unknown): typeof globalThis.fetch {
+	return async (_url, _init) => {
+		return {
+			ok: status >= 200 && status < 300,
+			status,
+			json: async () => body,
+		} as Response;
+	};
+}
+
+/** Counts how many times fetch was called. */
+function countingFetch(
+	status: number,
+	body: unknown,
+): { fetch: typeof globalThis.fetch; count: () => number } {
+	let n = 0;
+	return {
+		fetch: async (url, init) => {
+			n++;
+			return makeFetch(status, body)(url, init);
+		},
+		count: () => n,
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Test suite
+// ---------------------------------------------------------------------------
+
+describe("mail-oauth-service", () => {
+	let originalFetch: typeof globalThis.fetch;
+
+	before(() => {
+		originalFetch = globalThis.fetch;
+	});
+
+	after(() => {
+		globalThis.fetch = originalFetch;
+	});
+
+	// 1. Happy refresh
+	test("refresh: 200 response produces correct TokenSet", async () => {
+		const expiresIn = 3600;
+		globalThis.fetch = makeFetch(200, {
+			access_token: "new-access-token",
+			expires_in: expiresIn,
+		});
+
+		const svc = createMailOAuthService(makeConfig());
+		const before = nowSecs();
+		const result = await svc.refresh("some-refresh-token");
+		const after = nowSecs();
+
+		assert.equal(result.accessToken, "new-access-token");
+		assert.ok(
+			result.expiresAt >= before + expiresIn,
+			"expiresAt should be ~now + expires_in",
+		);
+		assert.ok(
+			result.expiresAt <= after + expiresIn + 1,
+			"expiresAt should not be too far in the future",
+		);
+		assert.equal(result.refreshToken, undefined);
+	});
+
+	// 2. Token rotation
+	test("refresh: rotated refresh_token is surfaced in TokenSet", async () => {
+		globalThis.fetch = makeFetch(200, {
+			access_token: "access",
+			expires_in: 3600,
+			refresh_token: "new-refresh-token",
+		});
+
+		const svc = createMailOAuthService(makeConfig());
+		const result = await svc.refresh("old-refresh-token");
+
+		assert.equal(result.refreshToken, "new-refresh-token");
+	});
+
+	// 3. Cache hit
+	test("getAccessToken: two calls within expiry window make only 1 fetch", async () => {
+		const { fetch, count } = countingFetch(200, {
+			access_token: "cached-token",
+			expires_in: 3600,
+		});
+		globalThis.fetch = fetch;
+
+		const svc = createMailOAuthService(makeConfig());
+		const r1 = await svc.getAccessToken("user-1", "rt");
+		const r2 = await svc.getAccessToken("user-1", "rt");
+
+		assert.equal(count(), 1, "should only fetch once");
+		assert.equal(r1.accessToken, "cached-token");
+		assert.equal(r2.accessToken, "cached-token");
+	});
+
+	// 4. Cache miss at T-5min
+	test("getAccessToken: token expiring in 4 minutes triggers refresh", async () => {
+		// First call returns a token that expires in 4 minutes (< 5-min buffer)
+		let callCount = 0;
+		globalThis.fetch = async () => {
+			callCount++;
+			return {
+				ok: true,
+				status: 200,
+				json: async () => ({
+					access_token: `token-${callCount}`,
+					expires_in: callCount === 1 ? 4 * 60 : 3600,
+				}),
+			} as Response;
+		};
+
+		const svc = createMailOAuthService(makeConfig());
+		// Prime the cache with a soon-expiring token
+		const r1 = await svc.getAccessToken("user-2", "rt");
+		assert.equal(r1.accessToken, "token-1");
+
+		// Second call should refresh because the token is within the 5-min buffer
+		const r2 = await svc.getAccessToken("user-2", "rt");
+		assert.equal(callCount, 2, "should have refreshed");
+		assert.equal(r2.accessToken, "token-2");
+	});
+
+	// 5. Single-flight
+	test("getAccessToken: 10 concurrent callers produce exactly 1 fetch", async () => {
+		const { fetch, count } = countingFetch(200, {
+			access_token: "shared-token",
+			expires_in: 3600,
+		});
+		globalThis.fetch = fetch;
+
+		const svc = createMailOAuthService(makeConfig());
+		const results = await Promise.all(
+			Array.from({ length: 10 }, () => svc.getAccessToken("user-3", "rt")),
+		);
+
+		assert.equal(
+			count(),
+			1,
+			"should only fetch once despite 10 concurrent callers",
+		);
+		for (const r of results) {
+			assert.equal(r.accessToken, "shared-token");
+		}
+	});
+
+	// 6a. Error mapping: invalid_grant → reauth-required
+	describe("error mapping", () => {
+		test("invalid_grant → reauth-required", async () => {
+			globalThis.fetch = makeFetch(400, {
+				error: "invalid_grant",
+				error_description: "AADSTS70008: Refresh token expired.",
+				error_codes: [70008],
+			});
+
+			const svc = createMailOAuthService(makeConfig());
+			await assert.rejects(
+				() => svc.refresh("bad-rt"),
+				(err: unknown) => {
+					assert.ok(err instanceof RefreshTokenError);
+					assert.equal(err.error.kind, "reauth-required");
+					assert.equal(err.error.code, "invalid_grant");
+					return true;
+				},
+			);
+		});
+
+		// 6b. error_codes array containing reauth code
+		test("error_codes [70008] → reauth-required", async () => {
+			globalThis.fetch = makeFetch(400, {
+				error: "some_error",
+				error_codes: [70008],
+			});
+
+			const svc = createMailOAuthService(makeConfig());
+			await assert.rejects(
+				() => svc.refresh("bad-rt"),
+				(err: unknown) => {
+					assert.ok(err instanceof RefreshTokenError);
+					assert.equal(err.error.kind, "reauth-required");
+					return true;
+				},
+			);
+		});
+
+		// 6c. 503 → transient
+		test("503 → transient", async () => {
+			globalThis.fetch = makeFetch(503, {
+				error: "server_error",
+				error_description: "Service unavailable",
+			});
+
+			const svc = createMailOAuthService(makeConfig());
+			await assert.rejects(
+				() => svc.refresh("rt"),
+				(err: unknown) => {
+					assert.ok(err instanceof RefreshTokenError);
+					assert.equal(err.error.kind, "transient");
+					return true;
+				},
+			);
+		});
+
+		// 6d. 429 → transient
+		test("429 → transient", async () => {
+			globalThis.fetch = makeFetch(429, {
+				error: "too_many_requests",
+			});
+
+			const svc = createMailOAuthService(makeConfig());
+			await assert.rejects(
+				() => svc.refresh("rt"),
+				(err: unknown) => {
+					assert.ok(err instanceof RefreshTokenError);
+					assert.equal(err.error.kind, "transient");
+					return true;
+				},
+			);
+		});
+
+		// 6e. invalid_client → config
+		test("invalid_client → config", async () => {
+			globalThis.fetch = makeFetch(401, {
+				error: "invalid_client",
+				error_description: "Client secret is invalid.",
+			});
+
+			const svc = createMailOAuthService(makeConfig());
+			await assert.rejects(
+				() => svc.refresh("rt"),
+				(err: unknown) => {
+					assert.ok(err instanceof RefreshTokenError);
+					assert.equal(err.error.kind, "config");
+					assert.equal(err.error.code, "invalid_client");
+					return true;
+				},
+			);
+		});
+
+		// 6f. network error → transient
+		test("network error → transient", async () => {
+			globalThis.fetch = async () => {
+				throw new Error("ECONNREFUSED");
+			};
+
+			const svc = createMailOAuthService(makeConfig());
+			await assert.rejects(
+				() => svc.refresh("rt"),
+				(err: unknown) => {
+					assert.ok(err instanceof RefreshTokenError);
+					assert.equal(err.error.kind, "transient");
+					assert.equal(err.error.code, "network_error");
+					return true;
+				},
+			);
+		});
+	});
+
+	// 7. No token leak in error
+	test("RefreshTokenError does not leak token values", async () => {
+		const sensitiveRefreshToken = "super-secret-refresh-token-abc123";
+
+		globalThis.fetch = makeFetch(400, {
+			error: "invalid_grant",
+			error_codes: [70008],
+		});
+
+		const svc = createMailOAuthService(makeConfig());
+
+		await assert.rejects(
+			() => svc.refresh(sensitiveRefreshToken),
+			(err: unknown) => {
+				assert.ok(err instanceof RefreshTokenError);
+
+				const serialized = JSON.stringify(err.error);
+				assert.ok(
+					!serialized.includes(sensitiveRefreshToken),
+					"serialized error must not contain the refresh token",
+				);
+
+				assert.ok(
+					!err.message.includes(sensitiveRefreshToken),
+					"error message must not contain the refresh token",
+				);
+				return true;
+			},
+		);
+	});
+
+	// 8a. exchangeCode happy path
+	test("exchangeCode: success returns TokenSet", async () => {
+		globalThis.fetch = makeFetch(200, {
+			access_token: "access-from-code",
+			expires_in: 3600,
+			refresh_token: "refresh-from-code",
+			id_token:
+				"header.eyJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhbGljZUBvdXRsb29rLmNvbSJ9.sig",
+		});
+
+		const svc = createMailOAuthService(makeConfig());
+		const result = await svc.exchangeCode(
+			"auth-code",
+			"https://app.example.com/callback",
+		);
+
+		assert.equal(result.accessToken, "access-from-code");
+		assert.equal(result.refreshToken, "refresh-from-code");
+		assert.equal(
+			result.idToken,
+			"header.eyJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhbGljZUBvdXRsb29rLmNvbSJ9.sig",
+		);
+	});
+
+	// 8b. exchangeCode error mapping
+	test("exchangeCode: invalid_grant → RefreshTokenError reauth-required", async () => {
+		globalThis.fetch = makeFetch(400, {
+			error: "invalid_grant",
+			error_codes: [70011],
+		});
+
+		const svc = createMailOAuthService(makeConfig());
+		await assert.rejects(
+			() => svc.exchangeCode("bad-code", "https://app.example.com/callback"),
+			(err: unknown) => {
+				assert.ok(err instanceof RefreshTokenError);
+				assert.equal(err.error.kind, "reauth-required");
+				return true;
+			},
+		);
+	});
+
+	// buildAuthorizationUrl
+	test("buildAuthorizationUrl includes required params", () => {
+		const svc = createMailOAuthService(makeConfig());
+		const url = new URL(
+			svc.buildAuthorizationUrl({
+				redirectUri: "https://app.example.com/callback",
+				state: "random-state",
+				loginHint: "user@example.com",
+			}),
+		);
+
+		assert.equal(url.searchParams.get("client_id"), "test-client-id");
+		assert.equal(url.searchParams.get("response_type"), "code");
+		assert.equal(
+			url.searchParams.get("redirect_uri"),
+			"https://app.example.com/callback",
+		);
+		assert.equal(url.searchParams.get("state"), "random-state");
+		assert.equal(url.searchParams.get("access_type"), "offline");
+		assert.equal(url.searchParams.get("prompt"), "consent");
+		assert.equal(url.searchParams.get("login_hint"), "user@example.com");
+	});
+
+	test("buildAuthorizationUrl omits login_hint when not provided", () => {
+		const svc = createMailOAuthService(makeConfig());
+		const url = new URL(
+			svc.buildAuthorizationUrl({
+				redirectUri: "https://app.example.com/callback",
+				state: "s",
+			}),
+		);
+		assert.equal(url.searchParams.get("login_hint"), null);
+	});
+});

package/src/index.ts

@@ -0,0 +1,38 @@
+export * from "./mail-oauth-service.js";
+export * from "./microsoft-errors.js";
+export * from "./types.js";
+
+import type { OAuthProviderConfig } from "./types.js";
+
+const MICROSOFT_TOKEN_ENDPOINT =
+	"https://login.microsoftonline.com/common/oauth2/v2.0/token";
+const MICROSOFT_AUTHORIZATION_ENDPOINT =
+	"https://login.microsoftonline.com/common/oauth2/v2.0/authorize";
+const MICROSOFT_DEFAULT_SCOPES = [
+	"https://outlook.office.com/IMAP.AccessAsUser.All",
+	"https://outlook.office.com/SMTP.Send",
+	"offline_access",
+	"openid",
+	"email",
+];
+
+export function microsoftProviderConfig(opts: {
+	clientId: string;
+	clientSecret: string;
+	overrides?: Partial<
+		Pick<
+			OAuthProviderConfig,
+			"tokenEndpoint" | "authorizationEndpoint" | "scopes"
+		>
+	>;
+}): OAuthProviderConfig {
+	return {
+		provider: "microsoft",
+		clientId: opts.clientId,
+		clientSecret: opts.clientSecret,
+		tokenEndpoint: opts.overrides?.tokenEndpoint ?? MICROSOFT_TOKEN_ENDPOINT,
+		authorizationEndpoint:
+			opts.overrides?.authorizationEndpoint ?? MICROSOFT_AUTHORIZATION_ENDPOINT,
+		scopes: opts.overrides?.scopes ?? MICROSOFT_DEFAULT_SCOPES,
+	};
+}

package/src/mail-oauth-service.ts

@@ -0,0 +1,207 @@
+import {
+	classifyMicrosoftError,
+	type MicrosoftTokenErrorResponse,
+} from "./microsoft-errors.js";
+import {
+	type OAuthProviderConfig,
+	RefreshTokenError,
+	type TokenSet,
+} from "./types.js";
+
+export interface MailOAuthService {
+	/** Exchange an authorization code for a token set. */
+	exchangeCode(
+		code: string,
+		redirectUri: string,
+		codeVerifier?: string,
+	): Promise<TokenSet>;
+
+	/** Refresh an access token using a refresh token. Throws RefreshTokenError on failure. */
+	refresh(refreshToken: string): Promise<TokenSet>;
+
+	/** Build the OAuth2 authorization URL to redirect the user to. */
+	buildAuthorizationUrl(opts: {
+		redirectUri: string;
+		state: string;
+		loginHint?: string;
+	}): string;
+
+	/**
+	 * Return a valid access token for the given cache key, refreshing if needed.
+	 * Concurrent callers for the same key share a single in-flight refresh (single-flight).
+	 *
+	 * Rotation contract: if the provider rotates the refresh token, the new value is
+	 * surfaced in the returned `TokenSet.refreshToken`. The caller is responsible for
+	 * persisting it — this service never persists tokens.
+	 */
+	getAccessToken(cacheKey: string, refreshToken: string): Promise<TokenSet>;
+}
+
+/** Tokens are refreshed 5 minutes before expiry. */
+const EXPIRY_BUFFER_SECS = 5 * 60;
+
+interface CacheEntry {
+	tokenSet?: TokenSet;
+	promise?: Promise<TokenSet>;
+}
+
+interface RawTokenResponse {
+	access_token: string;
+	expires_in: number;
+	refresh_token?: string;
+	id_token?: string;
+	error?: string;
+	error_codes?: number[];
+	error_description?: string;
+}
+
+function parseTokenResponse(
+	httpStatus: number,
+	raw: RawTokenResponse,
+): TokenSet {
+	if (raw.error) {
+		const classified = classifyMicrosoftError(
+			httpStatus,
+			raw as MicrosoftTokenErrorResponse,
+		);
+		throw new RefreshTokenError(classified);
+	}
+
+	return {
+		accessToken: raw.access_token,
+		expiresAt: Math.floor(Date.now() / 1000) + raw.expires_in,
+		...(raw.refresh_token ? { refreshToken: raw.refresh_token } : {}),
+		...(raw.id_token ? { idToken: raw.id_token } : {}),
+	};
+}
+
+async function postForm(
+	url: string,
+	params: Record<string, string>,
+): Promise<TokenSet> {
+	const body = new URLSearchParams(params).toString();
+
+	let response: Response;
+	try {
+		response = await fetch(url, {
+			method: "POST",
+			headers: { "Content-Type": "application/x-www-form-urlencoded" },
+			body,
+		});
+	} catch (_cause) {
+		// network error → transient
+		throw new RefreshTokenError({ kind: "transient", code: "network_error" });
+	}
+
+	let raw: RawTokenResponse;
+	try {
+		raw = (await response.json()) as RawTokenResponse;
+	} catch {
+		throw new RefreshTokenError({
+			kind: "transient",
+			code: "invalid_response",
+		});
+	}
+
+	if (!response.ok && !raw.error) {
+		// Non-OK HTTP with no error body → treat as transient
+		throw new RefreshTokenError({
+			kind: "transient",
+			code: `http_${response.status}`,
+		});
+	}
+
+	return parseTokenResponse(response.status, raw);
+}
+
+function isExpiringSoon(tokenSet: TokenSet): boolean {
+	const nowSecs = Math.floor(Date.now() / 1000);
+	return tokenSet.expiresAt - nowSecs < EXPIRY_BUFFER_SECS;
+}
+
+export function createMailOAuthService(
+	config: OAuthProviderConfig,
+): MailOAuthService {
+	const cache = new Map<string, CacheEntry>();
+
+	return {
+		buildAuthorizationUrl({ redirectUri, state, loginHint }) {
+			const url = new URL(config.authorizationEndpoint);
+			url.searchParams.set("client_id", config.clientId);
+			url.searchParams.set("response_type", "code");
+			url.searchParams.set("scope", config.scopes.join(" "));
+			url.searchParams.set("redirect_uri", redirectUri);
+			url.searchParams.set("state", state);
+			url.searchParams.set("access_type", "offline"); // Google compat
+			url.searchParams.set("prompt", "consent"); // reliably get refresh token
+			if (loginHint) {
+				url.searchParams.set("login_hint", loginHint);
+			}
+			return url.toString();
+		},
+
+		async exchangeCode(code, redirectUri, codeVerifier) {
+			const params: Record<string, string> = {
+				grant_type: "authorization_code",
+				code,
+				redirect_uri: redirectUri,
+				client_id: config.clientId,
+				client_secret: config.clientSecret,
+			};
+			if (codeVerifier) {
+				params.code_verifier = codeVerifier;
+			}
+			return postForm(config.tokenEndpoint, params);
+		},
+
+		async refresh(refreshToken) {
+			return postForm(config.tokenEndpoint, {
+				grant_type: "refresh_token",
+				refresh_token: refreshToken,
+				client_id: config.clientId,
+				client_secret: config.clientSecret,
+				scope: config.scopes.join(" "),
+			});
+		},
+
+		async getAccessToken(cacheKey, refreshToken) {
+			const entry = cache.get(cacheKey);
+
+			// Return cached token if still valid
+			if (entry?.tokenSet && !isExpiringSoon(entry.tokenSet)) {
+				return entry.tokenSet;
+			}
+
+			// Single-flight: if a refresh is already in-flight for this key, await it
+			if (entry?.promise) {
+				return entry.promise;
+			}
+
+			// Start a new refresh
+			const promise = postForm(config.tokenEndpoint, {
+				grant_type: "refresh_token",
+				refresh_token: refreshToken,
+				client_id: config.clientId,
+				client_secret: config.clientSecret,
+				scope: config.scopes.join(" "),
+			}).then(
+				(tokenSet) => {
+					cache.set(cacheKey, { tokenSet });
+					return tokenSet;
+				},
+				(err) => {
+					// Clear the promise so next caller tries again
+					const current = cache.get(cacheKey);
+					if (current?.promise === promise) {
+						cache.delete(cacheKey);
+					}
+					throw err;
+				},
+			);
+
+			cache.set(cacheKey, { tokenSet: entry?.tokenSet, promise });
+
+			return promise;
+		},
+	};
+}

package/src/microsoft-errors.ts

@@ -0,0 +1,86 @@
+import type { RefreshError } from "./types.js";
+
+/**
+ * AAD error codes that require the user to re-authenticate (invalid_grant family).
+ *
+ * 70000 — General invalid_grant
+ * 70008 — Refresh token has expired or is invalid
+ * 700082 — Refresh token has expired due to inactivity (90-day policy)
+ * 50173 — Fresh auth required; credential or token has expired
+ * 50057 — User account is disabled
+ * 65001 — The user or administrator has not consented to use the application
+ * 50076 — MFA required (interactive re-auth needed)
+ * 50079 — User is required to use MFA
+ * 50158 — External security challenge was not satisfied
+ * 53003 — Access blocked by Conditional Access
+ */
+const REAUTH_CODES = new Set([
+	70000, // General invalid_grant
+	70008, // Refresh token expired or invalid
+	700082, // Refresh token expired due to inactivity
+	50173, // Credential or token expired, fresh auth required
+	50057, // Account disabled
+	65001, // No consent granted
+	50076, // MFA required
+	50079, // MFA required (stronger auth)
+	50158, // External security challenge not satisfied
+	53003, // Access blocked by Conditional Access
+]);
+
+/**
+ * AAD error codes that indicate a configuration problem (bad scopes, bad client).
+ *
+ * 70011 — The requested scope is invalid, unknown, or malformed. This is a
+ *         deployment/configuration error, not an end-user reauth situation — the
+ *         registered application's scope list must be corrected before retrying.
+ */
+const CONFIG_CODES = new Set([
+	70011, // Invalid, unknown, or malformed scope
+]);
+
+export interface MicrosoftTokenErrorResponse {
+	error: string;
+	error_description?: string;
+	error_codes?: number[];
+	correlation_id?: string;
+	trace_id?: string;
+}
+
+/**
+ * Classifies a Microsoft OAuth error response into one of three kinds:
+ * - reauth-required: user must re-authenticate (invalid_grant family)
+ * - transient: network/server error, safe to retry
+ * - config: bad client credentials or revoked consent
+ */
+export function classifyMicrosoftError(
+	httpStatus: number,
+	body: MicrosoftTokenErrorResponse,
+): RefreshError {
+	const errorCode = body.error ?? "unknown";
+	const errorCodes = body.error_codes ?? [];
+
+	// 1. explicit invalid_grant or known reauth error codes
+	if (
+		errorCode === "invalid_grant" ||
+		errorCodes.some((c) => REAUTH_CODES.has(c))
+	) {
+		return { kind: "reauth-required", code: errorCode };
+	}
+
+	// 2. bad client credentials, revoked app consent, or misconfigured scopes
+	if (
+		errorCode === "invalid_client" ||
+		errorCode === "unauthorized_client" ||
+		errorCodes.some((c) => CONFIG_CODES.has(c))
+	) {
+		return { kind: "config", code: errorCode };
+	}
+
+	// 3. HTTP 5xx or 429 (rate-limited) → transient
+	if (httpStatus >= 500 || httpStatus === 429) {
+		return { kind: "transient", code: errorCode };
+	}
+
+	// 4. unknown → transient (retry-safe default)
+	return { kind: "transient", code: errorCode };
+}

package/src/types.ts

@@ -0,0 +1,33 @@
+export interface OAuthProviderConfig {
+	provider: "microsoft"; // union grows later
+	clientId: string;
+	clientSecret: string;
+	/** Default: https://login.microsoftonline.com/common/oauth2/v2.0/token */
+	tokenEndpoint: string;
+	/** Default: https://login.microsoftonline.com/common/oauth2/v2.0/authorize */
+	authorizationEndpoint: string;
+	scopes: string[];
+}
+
+export interface TokenSet {
+	accessToken: string;
+	/** Epoch seconds */
+	expiresAt: number;
+	/** Present when provider rotated the refresh token — caller MUST persist */
+	refreshToken?: string;
+	/** Present when the provider returns an OpenID Connect ID token (e.g. Microsoft
+	 *  when openid+email scopes are requested). Contains user identity claims. */
+	idToken?: string;
+}
+
+export type RefreshError =
+	| { kind: "reauth-required"; code: string } // invalid_grant family
+	| { kind: "transient"; code: string } // network, 5xx, 429
+	| { kind: "config"; code: string }; // bad client secret, consent revoked
+
+export class RefreshTokenError extends Error {
+	constructor(public readonly error: RefreshError) {
+		super(`OAuth refresh failed: ${error.kind} (${error.code})`);
+		this.name = "RefreshTokenError";
+	}
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+	"extends": "../../tsconfig.json",
+	"compilerOptions": {
+		"outDir": "dist",
+		"rootDir": "src"
+	},
+	"include": ["src/**/*.ts"]
+}