@remit/mail-oauth-service 0.0.8 → 0.0.10

package/src/mail-oauth-service.ts

@@ -1,211 +0,0 @@
-import {
-	classifyMicrosoftError,
-	type MicrosoftTokenErrorResponse,
-} from "./microsoft-errors.js";
-import { normalizeMicrosoftScopes } from "./microsoft-scopes.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;
-	scope?: 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,
-		grantedScopes: normalizeMicrosoftScopes(raw.scope),
-		...(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,
-				scope: config.scopes.join(" "),
-			};
-			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

@@ -1,86 +0,0 @@
-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/microsoft-scopes.ts

@@ -1,51 +0,0 @@
-import { AccountService } from "@remit/domain-enums";
-
-export type AccountServiceName =
-	(typeof AccountService)[keyof typeof AccountService];
-
-const GRAPH_RESOURCE = "https://graph.microsoft.com/";
-
-const SESSION_SCOPES = ["offline_access", "openid", "email"];
-
-const IDENTITY_SCOPES = new Set([...SESSION_SCOPES, "profile"]);
-
-export const MICROSOFT_SERVICE_SCOPES: Readonly<
-	Record<AccountServiceName, readonly string[]>
-> = {
-	[AccountService.Mail]: [
-		"https://outlook.office.com/IMAP.AccessAsUser.All",
-		"https://outlook.office.com/SMTP.Send",
-	],
-	[AccountService.Calendar]: [`${GRAPH_RESOURCE}Calendars.Read`],
-};
-
-export const orderServices = (
-	services: readonly AccountServiceName[],
-): AccountServiceName[] =>
-	Object.values(AccountService).filter((service) => services.includes(service));
-
-export const microsoftScopes = (
-	services: readonly AccountServiceName[],
-): string[] => [
-	...orderServices(services).flatMap(
-		(service) => MICROSOFT_SERVICE_SCOPES[service],
-	),
-	...SESSION_SCOPES,
-];
-
-export const normalizeMicrosoftScopes = (scope: string | undefined): string[] =>
-	(scope ?? "")
-		.split(" ")
-		.filter((name) => name.length > 0 && !IDENTITY_SCOPES.has(name))
-		.map((name) => (name.includes("://") ? name : `${GRAPH_RESOURCE}${name}`));
-
-export const microsoftServicesGranted = (
-	grantedScopes: readonly string[],
-): AccountServiceName[] => {
-	const granted = new Set(grantedScopes.map((scope) => scope.toLowerCase()));
-	return Object.values(AccountService).filter((service) =>
-		MICROSOFT_SERVICE_SCOPES[service].every((scope) =>
-			granted.has(scope.toLowerCase()),
-		),
-	);
-};

package/src/types.ts

@@ -1,34 +0,0 @@
-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;
-	grantedScopes: 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

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