@remit/mail-oauth-service 0.0.8 → 0.0.9

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export * from "./mail-oauth-service.js";
+export * from "./microsoft-errors.js";
+export * from "./microsoft-scopes.js";
+export * from "./types.js";
+import { type AccountServiceName } from "./microsoft-scopes.js";
+import type { OAuthProviderConfig } from "./types.js";
+export declare function microsoftProviderConfig(opts: {
+    clientId: string;
+    clientSecret: string;
+    services?: readonly AccountServiceName[];
+    overrides?: Partial<Pick<OAuthProviderConfig, "tokenEndpoint" | "authorizationEndpoint" | "scopes">>;
+}): OAuthProviderConfig;

package/dist/index.js

@@ -0,0 +1,19 @@
+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 { microsoftScopes, } from "./microsoft-scopes.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";
+export function microsoftProviderConfig(opts) {
+    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 ??
+            microsoftScopes(opts.services ?? [AccountService.Mail]),
+    };
+}

package/dist/mail-oauth-service.d.ts

@@ -0,0 +1,23 @@
+import { type OAuthProviderConfig, 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>;
+}
+export declare function createMailOAuthService(config: OAuthProviderConfig): MailOAuthService;

package/dist/mail-oauth-service.js

@@ -0,0 +1,128 @@
+import { classifyMicrosoftError, } from "./microsoft-errors.js";
+import { normalizeMicrosoftScopes } from "./microsoft-scopes.js";
+import { RefreshTokenError, } from "./types.js";
+/** Tokens are refreshed 5 minutes before expiry. */
+const EXPIRY_BUFFER_SECS = 5 * 60;
+function parseTokenResponse(httpStatus, raw) {
+    if (raw.error) {
+        const classified = classifyMicrosoftError(httpStatus, raw);
+        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, params) {
+    const body = new URLSearchParams(params).toString();
+    let 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;
+    try {
+        raw = (await response.json());
+    }
+    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) {
+    const nowSecs = Math.floor(Date.now() / 1000);
+    return tokenSet.expiresAt - nowSecs < EXPIRY_BUFFER_SECS;
+}
+export function createMailOAuthService(config) {
+    const cache = new Map();
+    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 = {
+                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/dist/microsoft-errors.d.ts

@@ -0,0 +1,15 @@
+import type { RefreshError } from "./types.js";
+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 declare function classifyMicrosoftError(httpStatus: number, body: MicrosoftTokenErrorResponse): RefreshError;

package/dist/microsoft-errors.js

@@ -0,0 +1,63 @@
+/**
+ * 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
+]);
+/**
+ * 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, body) {
+    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/dist/microsoft-scopes.d.ts

@@ -0,0 +1,7 @@
+import { AccountService } from "@remit/domain-enums";
+export type AccountServiceName = (typeof AccountService)[keyof typeof AccountService];
+export declare const MICROSOFT_SERVICE_SCOPES: Readonly<Record<AccountServiceName, readonly string[]>>;
+export declare const orderServices: (services: readonly AccountServiceName[]) => AccountServiceName[];
+export declare const microsoftScopes: (services: readonly AccountServiceName[]) => string[];
+export declare const normalizeMicrosoftScopes: (scope: string | undefined) => string[];
+export declare const microsoftServicesGranted: (grantedScopes: readonly string[]) => AccountServiceName[];

package/dist/microsoft-scopes.js

@@ -0,0 +1,24 @@
+import { AccountService } from "@remit/domain-enums";
+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 = {
+    [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) => Object.values(AccountService).filter((service) => services.includes(service));
+export const microsoftScopes = (services) => [
+    ...orderServices(services).flatMap((service) => MICROSOFT_SERVICE_SCOPES[service]),
+    ...SESSION_SCOPES,
+];
+export const normalizeMicrosoftScopes = (scope) => (scope ?? "")
+    .split(" ")
+    .filter((name) => name.length > 0 && !IDENTITY_SCOPES.has(name))
+    .map((name) => (name.includes("://") ? name : `${GRAPH_RESOURCE}${name}`));
+export const microsoftServicesGranted = (grantedScopes) => {
+    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/dist/types.d.ts

@@ -0,0 +1,35 @@
+export interface OAuthProviderConfig {
+    provider: "microsoft";
+    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;
+} | {
+    kind: "transient";
+    code: string;
+} | {
+    kind: "config";
+    code: string;
+};
+export declare class RefreshTokenError extends Error {
+    readonly error: RefreshError;
+    constructor(error: RefreshError);
+}

package/dist/types.js

@@ -0,0 +1,8 @@
+export class RefreshTokenError extends Error {
+    error;
+    constructor(error) {
+        super(`OAuth refresh failed: ${error.kind} (${error.code})`);
+        this.error = error;
+        this.name = "RefreshTokenError";
+    }
+}

package/package.json

@@ -1,30 +1,35 @@
 {
-  "name": "@remit/mail-oauth-service",
-  "version": "0.0.8",
-  "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 $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"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/remit-mail/reader.git",
-    "directory": "packages/mail-oauth-service"
-  }
+	"name": "@remit/mail-oauth-service",
+	"version": "0.0.9",
+	"type": "module",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"scripts": {
+		"prepack": "node ../../npm-scripts/pack-dist.mjs prepack",
+		"postpack": "node ../../npm-scripts/pack-dist.mjs postpack",
+		"test:typecheck": "tsgo --noEmit",
+		"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"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/remit-mail/reader.git",
+		"directory": "packages/mail-oauth-service"
+	},
+	"files": [
+		"dist"
+	]
 }