@remit/mail-oauth-service 0.0.7 → 0.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/mail-oauth-service",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -15,6 +15,9 @@
     "test:run": "node $NODE_TEST_FLAGS --import tsx --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-exclude='src/**/*.test.ts' --test-coverage-exclude='src/**/*.test.tsx' --test-coverage-lines=96 --test 'src/**/*.test.ts'",
     "test": "npm run test:typecheck && npm run test:run"
   },
+  "dependencies": {
+    "@remit/domain-enums": "*"
+  },
   "license": "MIT",
   "publishConfig": {
     "access": "public"

package/src/__tests__/microsoft-scopes.test.ts

@@ -0,0 +1,153 @@
+import assert from "node:assert/strict";
+import { after, before, describe, test } from "node:test";
+import { AccountService } from "@remit/domain-enums";
+import {
+	createMailOAuthService,
+	MICROSOFT_SERVICE_SCOPES,
+	microsoftProviderConfig,
+	microsoftScopes,
+	microsoftServicesGranted,
+	normalizeMicrosoftScopes,
+} from "../index.js";
+
+const IMAP = "https://outlook.office.com/IMAP.AccessAsUser.All";
+const SMTP = "https://outlook.office.com/SMTP.Send";
+const CALENDAR = "https://graph.microsoft.com/Calendars.Read";
+const SESSION = ["offline_access", "openid", "email"];
+
+describe("the Microsoft scopes a service selection asks for", () => {
+	test("mail asks for IMAP and SMTP and never the calendar", () => {
+		assert.deepEqual(microsoftScopes([AccountService.Mail]), [
+			IMAP,
+			SMTP,
+			...SESSION,
+		]);
+	});
+
+	test("calendar asks for the Graph calendar scope and no mailbox access", () => {
+		assert.deepEqual(microsoftScopes([AccountService.Calendar]), [
+			CALENDAR,
+			...SESSION,
+		]);
+	});
+
+	test("both put mail first whatever order they arrive in", () => {
+		assert.deepEqual(
+			microsoftScopes([
+				AccountService.Calendar,
+				AccountService.Mail,
+				AccountService.Calendar,
+			]),
+			[IMAP, SMTP, CALENDAR, ...SESSION],
+		);
+	});
+
+	test("a provider config with no selection asks for mail, as before", () => {
+		const config = microsoftProviderConfig({
+			clientId: "client-id",
+			clientSecret: "client-secret",
+		});
+
+		assert.deepEqual(config.scopes, [IMAP, SMTP, ...SESSION]);
+	});
+
+	test("the authorization URL carries the scopes of the selection", () => {
+		const service = createMailOAuthService(
+			microsoftProviderConfig({
+				clientId: "client-id",
+				clientSecret: "client-secret",
+				services: [AccountService.Calendar],
+			}),
+		);
+
+		const url = new URL(
+			service.buildAuthorizationUrl({
+				redirectUri: "https://app.example.com/callback",
+				state: "state",
+			}),
+		);
+
+		assert.equal(
+			url.searchParams.get("scope"),
+			[CALENDAR, ...SESSION].join(" "),
+		);
+	});
+});
+
+describe("the scopes Microsoft reports as granted", () => {
+	test("bare Graph names become full scope URIs and identity scopes drop out", () => {
+		assert.deepEqual(
+			normalizeMicrosoftScopes(
+				"Calendars.Read openid profile email offline_access",
+			),
+			[CALENDAR],
+		);
+	});
+
+	test("Outlook scopes keep their resource", () => {
+		assert.deepEqual(normalizeMicrosoftScopes(`${IMAP} ${SMTP}`), [IMAP, SMTP]);
+	});
+
+	test("an absent scope field grants nothing", () => {
+		assert.deepEqual(normalizeMicrosoftScopes(undefined), []);
+	});
+
+	test("a service counts as granted only when every one of its scopes is", () => {
+		assert.deepEqual(microsoftServicesGranted([IMAP]), []);
+		assert.deepEqual(microsoftServicesGranted([IMAP, SMTP]), [
+			AccountService.Mail,
+		]);
+		assert.deepEqual(
+			microsoftServicesGranted([
+				CALENDAR.toLowerCase(),
+				...MICROSOFT_SERVICE_SCOPES[AccountService.Mail],
+			]),
+			[AccountService.Mail, AccountService.Calendar],
+		);
+	});
+});
+
+describe("the code exchange", () => {
+	let originalFetch: typeof globalThis.fetch;
+	let sentScope: string | null;
+
+	before(() => {
+		originalFetch = globalThis.fetch;
+		globalThis.fetch = (async (_url: unknown, init?: RequestInit) => {
+			sentScope = new URLSearchParams(String(init?.body)).get("scope");
+			return {
+				ok: true,
+				status: 200,
+				json: async () => ({
+					access_token: "access",
+					expires_in: 3600,
+					refresh_token: "refresh",
+					scope: "Calendars.Read openid email",
+				}),
+			} as Response;
+		}) as typeof globalThis.fetch;
+	});
+
+	after(() => {
+		globalThis.fetch = originalFetch;
+	});
+
+	test("redeems the code for the selection's scopes and reports what was granted", async () => {
+		const service = createMailOAuthService(
+			microsoftProviderConfig({
+				clientId: "client-id",
+				clientSecret: "client-secret",
+				services: [AccountService.Calendar],
+				overrides: { tokenEndpoint: "https://example.com/token" },
+			}),
+		);
+
+		const tokenSet = await service.exchangeCode(
+			"code",
+			"https://app.example.com/callback",
+		);
+
+		assert.equal(sentScope, [CALENDAR, ...SESSION].join(" "));
+		assert.deepEqual(tokenSet.grantedScopes, [CALENDAR]);
+	});
+});

package/src/index.ts

@@ -1,24 +1,24 @@
 export * from "./mail-oauth-service.js";
 export * from "./microsoft-errors.js";
+export * from "./microsoft-scopes.js";
 export * from "./types.js";
 
+import { AccountService } from "@remit/domain-enums";
+import {
+	type AccountServiceName,
+	microsoftScopes,
+} from "./microsoft-scopes.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;
+	services?: readonly AccountServiceName[];
 	overrides?: Partial<
 		Pick<
 			OAuthProviderConfig,
@@ -33,6 +33,8 @@ export function microsoftProviderConfig(opts: {
 		tokenEndpoint: opts.overrides?.tokenEndpoint ?? MICROSOFT_TOKEN_ENDPOINT,
 		authorizationEndpoint:
 			opts.overrides?.authorizationEndpoint ?? MICROSOFT_AUTHORIZATION_ENDPOINT,
-		scopes: opts.overrides?.scopes ?? MICROSOFT_DEFAULT_SCOPES,
+		scopes:
+			opts.overrides?.scopes ??
+			microsoftScopes(opts.services ?? [AccountService.Mail]),
 	};
 }

package/src/mail-oauth-service.ts

@@ -2,6 +2,7 @@ import {
 	classifyMicrosoftError,
 	type MicrosoftTokenErrorResponse,
 } from "./microsoft-errors.js";
+import { normalizeMicrosoftScopes } from "./microsoft-scopes.js";
 import {
 	type OAuthProviderConfig,
 	RefreshTokenError,
@@ -50,6 +51,7 @@ interface RawTokenResponse {
 	expires_in: number;
 	refresh_token?: string;
 	id_token?: string;
+	scope?: string;
 	error?: string;
 	error_codes?: number[];
 	error_description?: string;
@@ -70,6 +72,7 @@ function parseTokenResponse(
 	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 } : {}),
 	};
@@ -147,6 +150,7 @@ export function createMailOAuthService(
 				redirect_uri: redirectUri,
 				client_id: config.clientId,
 				client_secret: config.clientSecret,
+				scope: config.scopes.join(" "),
 			};
 			if (codeVerifier) {
 				params.code_verifier = codeVerifier;

package/src/microsoft-scopes.ts

@@ -0,0 +1,51 @@
+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

@@ -18,6 +18,7 @@ export interface TokenSet {
 	/** 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 =