@remit/backend 0.0.151 → 0.0.153

package/dist/src/config/msoauth.d.ts

@@ -1,12 +1,23 @@
-import type { OAuthProviderConfig } from "@remit/mail-oauth-service";
+import { type MailOAuthService, type OAuthProviderConfig } from "@remit/mail-oauth-service";
 export interface MsOAuthCredentials {
     clientId: string;
     clientSecret: string;
 }
+/** Where a connected Outlook account's mail server is reached instead of Microsoft's. */
+export interface MailServerOverride {
+    host: string;
+    port: number;
+    tls: boolean;
+    startTls: boolean;
+}
+export interface MsOAuthOverrides extends Partial<Pick<OAuthProviderConfig, "tokenEndpoint">> {
+    imapServer?: MailServerOverride;
+    smtpServer?: MailServerOverride;
+}
 export interface MsOAuthEnabled {
     mode: "Enabled";
     redirectUri: string;
-    overrides: Partial<Pick<OAuthProviderConfig, "tokenEndpoint">>;
+    overrides: MsOAuthOverrides;
     credentials: () => Promise<MsOAuthCredentials>;
 }
 export type MsOAuthConfig = {
@@ -17,3 +28,10 @@ export interface LoadedMsOAuth {
     credentials: MsOAuthCredentials;
 }
 export declare const loadMsOAuth: (config: MsOAuthConfig) => Promise<LoadedMsOAuth>;
+export type MicrosoftTokenService = Pick<MailOAuthService, "getAccessToken">;
+/**
+ * The access-token minting a connected Outlook account syncs and sends with.
+ * The app's credentials load on the first token asked for, and once loaded the
+ * service keeps its token cache for every account after it.
+ */
+export declare const microsoftTokenService: (msOAuth: MsOAuthConfig) => MicrosoftTokenService;

package/dist/src/config/msoauth.js

@@ -1,6 +1,29 @@
+import { createMailOAuthService, microsoftProviderConfig, } from "@remit/mail-oauth-service";
 export const loadMsOAuth = async (config) => {
     if (config.mode === "Disabled") {
         throw new Error("No Microsoft OAuth credentials are configured on this instance: set MSOAUTH_CLIENT_ID and MSOAUTH_CLIENT_SECRET, or MSOAUTH_SECRET_ARN");
     }
     return { config, credentials: await config.credentials() };
 };
+/**
+ * The access-token minting a connected Outlook account syncs and sends with.
+ * The app's credentials load on the first token asked for, and once loaded the
+ * service keeps its token cache for every account after it.
+ */
+export const microsoftTokenService = (msOAuth) => {
+    let service;
+    const load = () => loadMsOAuth(msOAuth).then(({ config, credentials }) => createMailOAuthService(microsoftProviderConfig({
+        clientId: credentials.clientId,
+        clientSecret: credentials.clientSecret,
+        overrides: config.overrides,
+    })));
+    return {
+        getAccessToken: (cacheKey, refreshToken) => {
+            service ??= load().catch((error) => {
+                service = undefined;
+                throw error;
+            });
+            return service.then((loaded) => loaded.getAccessToken(cacheKey, refreshToken));
+        },
+    };
+};

package/dist/src/handlers/account-oauth.d.ts

@@ -1,20 +1,17 @@
-import type { AccountService as AccountServiceName } from "@remit/api-openapi-types";
 import type { Context } from "openapi-backend";
 import type { HandlerContext, PublicOperationHandler } from "../types.js";
-export interface OAuthState {
-    accountConfigId: string;
-    nonce: string;
-    timestamp: number;
-    services: AccountServiceName[];
-}
-export declare const STATE_TTL_MS: number;
-export declare function signState(payload: OAuthState, clientSecret: string): Promise<string>;
-export declare function verifyState(state: string, clientSecret: string): Promise<OAuthState>;
 export declare function parseJwtClaims(token: string): Promise<Record<string, unknown> | null>;
 export declare function getWebOrigin(origins: readonly string[]): string;
 export declare const microsoftOAuthCallback: PublicOperationHandler<"sync">;
+export interface SignInNotConfigured {
+    statusCode: 501;
+    body: {
+        code: "not_configured";
+        message: string;
+    };
+}
 export declare const MicrosoftOAuthOperations: {
     MicrosoftOAuthOperations_microsoftOAuthStart: (context: Context, ctx: HandlerContext) => Promise<{
         authorizationUrl: string;
-    }>;
+    } | SignInNotConfigured>;
 };

package/dist/src/handlers/account-oauth.js

@@ -1,4 +1,4 @@
-import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { randomBytes } from "node:crypto";
 import { ensureAccountConfig } from "@remit/data-ports/account-config";
 import { AccountAuthType, AccountService, ConnectionState, } from "@remit/domain-enums";
 import { logger } from "@remit/logger";
@@ -6,63 +6,22 @@ import { createMailOAuthService, microsoftProviderConfig, microsoftServicesGrant
 import { serializeEncryptedPayload } from "@remit/secrets-service";
 import { loadMsOAuth } from "../config/msoauth.js";
 import { safeJsonParse } from "../json.js";
+import { ACCOUNT_SETTINGS_ROUTE, oauthRefusalUrl, signState, verifyState, } from "../oauth-state.js";
 import { rawApiResponse } from "../response.js";
 import { triggerAccountSyncSafe } from "./account.js";
 import { findActiveDuplicateMailbox } from "./account-guards.js";
-const OUTLOOK_IMAP_HOST = "outlook.office365.com";
-const ACCOUNT_SERVICES = Object.values(AccountService);
-const isServiceList = (value) => Array.isArray(value) &&
-    value.length > 0 &&
-    value.every((service) => typeof service === "string" && ACCOUNT_SERVICES.includes(service));
-export const STATE_TTL_MS = 10 * 60 * 1000; // 10 minutes
-/**
- * Derive a signing key from the client secret, namespaced to avoid reuse.
- * The key is HMAC-SHA256("oauth-state-signing:" + clientSecret).
- */
-function deriveSigningKey(clientSecret) {
-    return createHmac("sha256", `oauth-state-signing:${clientSecret}`)
-        .update("")
-        .digest();
-}
-function base64urlEncode(buf) {
-    return buf.toString("base64url");
-}
-function base64urlDecode(str) {
-    return Buffer.from(str, "base64url");
-}
-export async function signState(payload, clientSecret) {
-    const key = deriveSigningKey(clientSecret);
-    const payloadBuf = Buffer.from(JSON.stringify(payload), "utf8");
-    const payloadEncoded = base64urlEncode(payloadBuf);
-    const sig = createHmac("sha256", key).update(payloadEncoded).digest();
-    const sigEncoded = base64urlEncode(sig);
-    return `${payloadEncoded}.${sigEncoded}`;
-}
-export async function verifyState(state, clientSecret) {
-    const dotIndex = state.lastIndexOf(".");
-    if (dotIndex < 0)
-        throw new Error("Malformed state: missing dot separator");
-    const payloadEncoded = state.slice(0, dotIndex);
-    const sigEncoded = state.slice(dotIndex + 1);
-    const key = deriveSigningKey(clientSecret);
-    const expectedSig = createHmac("sha256", key).update(payloadEncoded).digest();
-    const actualSig = base64urlDecode(sigEncoded);
-    if (actualSig.length !== expectedSig.length ||
-        !timingSafeEqual(actualSig, expectedSig)) {
-        throw new Error("State signature verification failed");
-    }
-    const payload = JSON.parse(base64urlDecode(payloadEncoded).toString("utf8"));
-    if (Date.now() - payload.timestamp > STATE_TTL_MS) {
-        throw new Error("State has expired");
-    }
-    if (payload.services === undefined) {
-        return { ...payload, services: [AccountService.Mail] };
-    }
-    if (!isServiceList(payload.services)) {
-        throw new Error("State names no requested services");
-    }
-    return payload;
-}
+const OUTLOOK_IMAP = {
+    host: "outlook.office365.com",
+    port: 993,
+    tls: true,
+    startTls: false,
+};
+const OUTLOOK_SMTP = {
+    host: "smtp.office365.com",
+    port: 587,
+    tls: false,
+    startTls: true,
+};
 // ─── JWT claims parsing ──────────────────────────────────────────────────────
 export async function parseJwtClaims(token) {
     const parts = token.split(".");
@@ -77,7 +36,7 @@ export function getWebOrigin(origins) {
     return httpsOrigin ?? origins[0] ?? "https://localhost:3000";
 }
 const scopeRefusalUrl = (webOrigin, email, missingServices) => {
-    const url = new URL(`${webOrigin}/settings/accounts`);
+    const url = new URL(`${webOrigin}${ACCOUNT_SETTINGS_ROUTE}`);
     url.searchParams.set("oauthError", "scope_not_granted");
     url.searchParams.set("oauthEmail", email);
     url.searchParams.set("missingServices", missingServices.join(","));
@@ -125,13 +84,12 @@ export const microsoftOAuthCallback = async (context, ctx) => {
     });
     // If Microsoft returned an error, pass it through to the frontend
     if (qs.error) {
-        const errorCode = encodeURIComponent(qs.error);
-        return redirect(`${webOrigin}/settings/accounts?oauthError=${errorCode}`);
+        return redirect(oauthRefusalUrl(webOrigin, qs.error));
     }
     const code = qs.code;
     const state = qs.state;
     if (!code || !state) {
-        return redirect(`${webOrigin}/settings/accounts?oauthError=missing_params`);
+        return redirect(oauthRefusalUrl(webOrigin, "missing_params"));
     }
     const loaded = await loadMsOAuth(ctx.config.msOAuth).catch((err) => {
         logger.error({
@@ -144,7 +102,7 @@ export const microsoftOAuthCallback = async (context, ctx) => {
         return null;
     });
     if (loaded === null)
-        return redirect(`${webOrigin}/settings/accounts?oauthError=config_error`);
+        return redirect(oauthRefusalUrl(webOrigin, "config_error"));
     const { config, credentials } = loaded;
     // Verify the HMAC-signed state
     // A bad/expired/forged state is a security-relevant signal (CSRF
@@ -160,7 +118,7 @@ export const microsoftOAuthCallback = async (context, ctx) => {
         return null;
     });
     if (statePayload === null)
-        return redirect(`${webOrigin}/settings/accounts?oauthError=invalid_state`);
+        return redirect(oauthRefusalUrl(webOrigin, "invalid_state"));
     const { accountConfigId } = statePayload;
     const [firstService] = orderServices(statePayload.services);
     const serviceFor = (service) => createMailOAuthService(microsoftProviderConfig({
@@ -177,10 +135,10 @@ export const microsoftOAuthCallback = async (context, ctx) => {
         return null;
     });
     if (tokenSet === null)
-        return redirect(`${webOrigin}/settings/accounts?oauthError=exchange_failed`);
+        return redirect(oauthRefusalUrl(webOrigin, "exchange_failed"));
     if (!tokenSet.refreshToken) {
         logger.error({ accountConfigId }, "MS OAuth token exchange returned no refresh_token");
-        return redirect(`${webOrigin}/settings/accounts?oauthError=exchange_failed`);
+        return redirect(oauthRefusalUrl(webOrigin, "exchange_failed"));
     }
     // Extract the user's email from the ID token returned alongside the access
     // token when openid+email scopes are requested.
@@ -212,7 +170,7 @@ export const microsoftOAuthCallback = async (context, ctx) => {
         : undefined;
     if (!email) {
         logger.error({ accountConfigId }, "MS OAuth: could not extract email from token claims");
-        return redirect(`${webOrigin}/settings/accounts?oauthError=missing_email`);
+        return redirect(oauthRefusalUrl(webOrigin, "missing_email"));
     }
     const { account, accountConfig, secrets } = ctx.client;
     // Reconnect when an active OAuth account already onboards this mailbox.
@@ -220,8 +178,10 @@ export const microsoftOAuthCallback = async (context, ctx) => {
     // the existing account (token refresh) rather than rejecting, because a
     // re-auth is the expected, idempotent path for OAuth.
     const existingAccounts = (await account.listAllByAccountConfig(accountConfigId)).filter((a) => a.authType === AccountAuthType.OauthMicrosoft);
+    const imapServer = config.overrides.imapServer ?? OUTLOOK_IMAP;
+    const smtpServer = config.overrides.smtpServer ?? OUTLOOK_SMTP;
     const existing = findActiveDuplicateMailbox(existingAccounts, {
-        imapHost: OUTLOOK_IMAP_HOST,
+        imapHost: imapServer.host,
         username: email,
     });
     const services = orderServices([
@@ -233,7 +193,7 @@ export const microsoftOAuthCallback = async (context, ctx) => {
         redemption.reason === "scope_not_granted")
         return redirect(scopeRefusalUrl(webOrigin, email, [redemption.service]));
     if (redemption.kind === "refused")
-        return redirect(`${webOrigin}/settings/accounts?oauthError=${redemption.reason}`);
+        return redirect(oauthRefusalUrl(webOrigin, redemption.reason));
     const grantedScopes = [
         ...new Set([...tokenSet.grantedScopes, ...redemption.grantedScopes]),
     ];
@@ -280,15 +240,15 @@ export const microsoftOAuthCallback = async (context, ctx) => {
             grantedScopes,
             oauthRefreshTokenHash,
             oauthTokenUpdatedAt,
-            imapHost: OUTLOOK_IMAP_HOST,
-            imapPort: 993,
-            imapTls: true,
-            imapStartTls: false,
+            imapHost: imapServer.host,
+            imapPort: imapServer.port,
+            imapTls: imapServer.tls,
+            imapStartTls: imapServer.startTls,
             smtpEnabled: true,
-            smtpHost: "smtp.office365.com",
-            smtpPort: 587,
-            smtpTls: false,
-            smtpStartTls: true,
+            smtpHost: smtpServer.host,
+            smtpPort: smtpServer.port,
+            smtpTls: smtpServer.tls,
+            smtpStartTls: smtpServer.startTls,
             isActive: true,
             connectionState: ConnectionState.NotAuthenticated,
         });
@@ -299,10 +259,24 @@ export const microsoftOAuthCallback = async (context, ctx) => {
     if (services.includes(AccountService.Mail)) {
         await triggerAccountSyncSafe(ctx.client, accountId);
     }
-    return redirect(`${webOrigin}/settings/accounts?connected=${encodeURIComponent(accountId)}`);
+    return redirect(`${webOrigin}${ACCOUNT_SETTINGS_ROUTE}?connected=${encodeURIComponent(accountId)}`);
 };
+/**
+ * An instance with no Microsoft app answers the start of a sign-in with a
+ * refusal the onboarding wizard can show, rather than the 500 the config load
+ * would otherwise throw.
+ */
+const signInNotConfigured = () => ({
+    statusCode: 501,
+    body: {
+        code: "not_configured",
+        message: "Microsoft sign-in is not configured on this instance; connect the account with an app password instead.",
+    },
+});
 export const MicrosoftOAuthOperations = {
     MicrosoftOAuthOperations_microsoftOAuthStart: async (context, ctx) => {
+        if (ctx.config.msOAuth.mode === "Disabled")
+            return signInNotConfigured();
         const accountConfigId = ctx.identity.accountConfigId;
         const input = context.request.requestBody;
         const email = typeof input.email === "string" ? input.email : undefined;

package/dist/src/handlers/index.d.ts

@@ -162,7 +162,7 @@ export declare const handlers: {
     MailboxOperations_createMailbox: (context: import("openapi-backend").Context<any, any, any, any, any, import("openapi-backend").Document>, ctx: import("../types.js").HandlerContext<"sync">) => Promise<import("@remit/api-openapi-types").Components.Schemas.MailboxResponse>;
     MicrosoftOAuthOperations_microsoftOAuthStart: (context: import("openapi-backend").Context, ctx: import("../types.js").HandlerContext) => Promise<{
         authorizationUrl: string;
-    }>;
+    } | import("./account-oauth.js").SignInNotConfigured>;
     AccountDetailOperations_updateAccount: (context: import("openapi-backend").Context, ctx: import("../types.js").HandlerContext) => Promise<import("@remit/api-openapi-types").AccountResponse>;
     AccountDetailOperations_deleteAccount: (context: import("openapi-backend").Context, ctx: import("../types.js").HandlerContext<"accountFanout">) => Promise<import("@remit/api-openapi-types").DeleteAccountResponse>;
     AccountOperations_createAccount: (context: import("openapi-backend").Context, ctx: import("../types.js").HandlerContext<"sync">) => Promise<import("@remit/api-openapi-types").AccountResponse>;

package/dist/src/oauth-state.d.ts

@@ -0,0 +1,14 @@
+import type { AccountService as AccountServiceName } from "@remit/api-openapi-types";
+export interface OAuthState {
+    accountConfigId: string;
+    nonce: string;
+    timestamp: number;
+    services: AccountServiceName[];
+}
+export declare const STATE_TTL_MS: number;
+export declare function signState(payload: OAuthState, clientSecret: string): Promise<string>;
+export declare function verifyState(state: string, clientSecret: string): Promise<OAuthState>;
+/** The web client's account settings, where every Microsoft sign-in lands. */
+export declare const ACCOUNT_SETTINGS_ROUTE = "/settings/accounts";
+/** Where a refused Microsoft sign-in sends the browser back to, carrying why. */
+export declare const oauthRefusalUrl: (webOrigin: string, oauthError: string) => string;

package/dist/src/oauth-state.js

@@ -0,0 +1,63 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { AccountService } from "@remit/domain-enums";
+const ACCOUNT_SERVICES = Object.values(AccountService);
+const isServiceList = (value) => Array.isArray(value) &&
+    value.length > 0 &&
+    value.every((service) => typeof service === "string" && ACCOUNT_SERVICES.includes(service));
+export const STATE_TTL_MS = 10 * 60 * 1000; // 10 minutes
+/**
+ * Derive a signing key from the client secret, namespaced to avoid reuse.
+ * The key is HMAC-SHA256("oauth-state-signing:" + clientSecret).
+ */
+function deriveSigningKey(clientSecret) {
+    return createHmac("sha256", `oauth-state-signing:${clientSecret}`)
+        .update("")
+        .digest();
+}
+function base64urlEncode(buf) {
+    return buf.toString("base64url");
+}
+function base64urlDecode(str) {
+    return Buffer.from(str, "base64url");
+}
+export async function signState(payload, clientSecret) {
+    const key = deriveSigningKey(clientSecret);
+    const payloadBuf = Buffer.from(JSON.stringify(payload), "utf8");
+    const payloadEncoded = base64urlEncode(payloadBuf);
+    const sig = createHmac("sha256", key).update(payloadEncoded).digest();
+    const sigEncoded = base64urlEncode(sig);
+    return `${payloadEncoded}.${sigEncoded}`;
+}
+export async function verifyState(state, clientSecret) {
+    const dotIndex = state.lastIndexOf(".");
+    if (dotIndex < 0)
+        throw new Error("Malformed state: missing dot separator");
+    const payloadEncoded = state.slice(0, dotIndex);
+    const sigEncoded = state.slice(dotIndex + 1);
+    const key = deriveSigningKey(clientSecret);
+    const expectedSig = createHmac("sha256", key).update(payloadEncoded).digest();
+    const actualSig = base64urlDecode(sigEncoded);
+    if (actualSig.length !== expectedSig.length ||
+        !timingSafeEqual(actualSig, expectedSig)) {
+        throw new Error("State signature verification failed");
+    }
+    const payload = JSON.parse(base64urlDecode(payloadEncoded).toString("utf8"));
+    if (Date.now() - payload.timestamp > STATE_TTL_MS) {
+        throw new Error("State has expired");
+    }
+    if (payload.services === undefined) {
+        return { ...payload, services: [AccountService.Mail] };
+    }
+    if (!isServiceList(payload.services)) {
+        throw new Error("State names no requested services");
+    }
+    return payload;
+}
+/** The web client's account settings, where every Microsoft sign-in lands. */
+export const ACCOUNT_SETTINGS_ROUTE = "/settings/accounts";
+/** Where a refused Microsoft sign-in sends the browser back to, carrying why. */
+export const oauthRefusalUrl = (webOrigin, oauthError) => {
+    const url = new URL(`${webOrigin}${ACCOUNT_SETTINGS_ROUTE}`);
+    url.searchParams.set("oauthError", oauthError);
+    return url.toString();
+};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@remit/backend",
-	"version": "0.0.151",
+	"version": "0.0.153",
 	"description": "Remit Mail Inspector API backend",
 	"license": "MIT",
 	"author": "",
@@ -63,6 +63,14 @@
 			"types": "./dist/src/service/trigger-sync.d.ts",
 			"default": "./dist/src/service/trigger-sync.js"
 		},
+		"./oauth-state": {
+			"types": "./dist/src/oauth-state.d.ts",
+			"default": "./dist/src/oauth-state.js"
+		},
+		"./msoauth": {
+			"types": "./dist/src/config/msoauth.d.ts",
+			"default": "./dist/src/config/msoauth.js"
+		},
 		"./content-handler": {
 			"types": "./dist/dev-server/content-handler.d.ts",
 			"default": "./dist/dev-server/content-handler.js"