@remit/backend 0.0.143 → 0.0.145

package/{src/derive/senderTrust.ts → dist/src/derive/senderTrust.d.ts}

@@ -1,8 +1,6 @@
 import type { AddressFlags } from "@remit/api-openapi-types";
 import { SenderTrust } from "@remit/domain-enums";
-
 export type SenderTrustValue = (typeof SenderTrust)[keyof typeof SenderTrust];
-
 /**
  * Derive the SenderTrust discriminator from an Address's flags map.
  *
@@ -14,10 +12,4 @@ export type SenderTrustValue = (typeof SenderTrust)[keyof typeof SenderTrust];
  * Pure function, no I/O. Frontend never derives this — single source of
  * truth for the UI badge state.
  */
-export const deriveSenderTrust = (
-	flags: AddressFlags | undefined,
-): SenderTrustValue => {
-	if (flags?.vip?.value === true) return SenderTrust.Vip;
-	if (flags?.wellknown?.value === true) return SenderTrust.Wellknown;
-	return SenderTrust.Unknown;
-};
+export declare const deriveSenderTrust: (flags: AddressFlags | undefined) => SenderTrustValue;

package/dist/src/derive/senderTrust.js

@@ -0,0 +1,19 @@
+import { SenderTrust } from "@remit/domain-enums";
+/**
+ * Derive the SenderTrust discriminator from an Address's flags map.
+ *
+ * Precedence (per EDD #232):
+ *   flags.vip.value === true       → "vip"
+ *   flags.wellknown.value === true → "wellknown"
+ *   otherwise                      → "unknown"
+ *
+ * Pure function, no I/O. Frontend never derives this — single source of
+ * truth for the UI badge state.
+ */
+export const deriveSenderTrust = (flags) => {
+    if (flags?.vip?.value === true)
+        return SenderTrust.Vip;
+    if (flags?.wellknown?.value === true)
+        return SenderTrust.Wellknown;
+    return SenderTrust.Unknown;
+};

package/dist/src/error.d.ts

@@ -0,0 +1,21 @@
+import type { APIGatewayProxyResult } from "aws-lambda";
+/**
+ * The `code` a refusal carries when it does not name its own. Every error body
+ * the API emits is flat `{ code, message }` (issue #371), and `code` is the
+ * only field a client may branch on — a message is a sentence for a person and
+ * is free to change.
+ *
+ * A 5xx always answers `internal_error`, whatever the throw site said: a coded
+ * 5xx is a mistake at the throw site, not a contract, and a fixed token cannot
+ * carry anything about the failure out of the process.
+ */
+export declare const INTERNAL_ERROR_CODE = "internal_error";
+/**
+ * The one sentence any 5xx answers with. A thrown message is written for a log
+ * line, not for a stranger — it names hosts, queries and ids — so it is
+ * replaced rather than trusted. The real message is already on the error log
+ * beside the correlation id the response carries.
+ */
+export declare const INTERNAL_ERROR_MESSAGE = "Internal server error";
+export declare const defaultErrorCode: (statusCode: number) => string;
+export declare const handleError: (error: unknown) => Promise<APIGatewayProxyResult>;

package/dist/src/error.js

@@ -0,0 +1,85 @@
+import { isPublicApiError } from "@remit/data-ports/errors";
+import { logger } from "@remit/logger";
+import { formatResponse } from "./response.js";
+/**
+ * The `code` a refusal carries when it does not name its own. Every error body
+ * the API emits is flat `{ code, message }` (issue #371), and `code` is the
+ * only field a client may branch on — a message is a sentence for a person and
+ * is free to change.
+ *
+ * A 5xx always answers `internal_error`, whatever the throw site said: a coded
+ * 5xx is a mistake at the throw site, not a contract, and a fixed token cannot
+ * carry anything about the failure out of the process.
+ */
+export const INTERNAL_ERROR_CODE = "internal_error";
+/**
+ * The one sentence any 5xx answers with. A thrown message is written for a log
+ * line, not for a stranger — it names hosts, queries and ids — so it is
+ * replaced rather than trusted. The real message is already on the error log
+ * beside the correlation id the response carries.
+ */
+export const INTERNAL_ERROR_MESSAGE = "Internal server error";
+const CODE_BY_STATUS = {
+    400: "invalid_request",
+    401: "unauthorized",
+    403: "forbidden",
+    404: "not_found",
+    409: "conflict",
+    412: "precondition_failed",
+    413: "payload_too_large",
+    422: "unprocessable_entity",
+};
+export const defaultErrorCode = (statusCode) => {
+    if (statusCode >= 500)
+        return INTERNAL_ERROR_CODE;
+    return CODE_BY_STATUS[statusCode] ?? "request_refused";
+};
+export const handleError = async (error) => {
+    if (error instanceof Error) {
+        if ("statusCode" in error) {
+            logger.error({
+                error: error.message,
+                statusCode: error.statusCode,
+                stack: error.stack,
+            }, "Error with statusCode");
+            // An error that opted in names its own code and details, and only below
+            // 500: the status bound keeps a coded 5xx from reaching a client rather
+            // than trusting every future thrower to leave `publicApiError` alone.
+            // Everything else takes the status class's code, so no response goes out
+            // without one. A 5xx keeps neither the thrower's code nor its message —
+            // one status, one code, one sentence, whatever failed.
+            const statusCode = typeof error.statusCode === "number" ? error.statusCode : 500;
+            if (statusCode >= 500) {
+                return formatResponse({ code: INTERNAL_ERROR_CODE, message: INTERNAL_ERROR_MESSAGE }, statusCode);
+            }
+            const publicApiError = "publicApiError" in error && isPublicApiError(error.publicApiError)
+                ? error.publicApiError
+                : undefined;
+            return formatResponse({
+                code: defaultErrorCode(statusCode),
+                message: error.message,
+                ...publicApiError,
+            }, statusCode);
+        }
+        if (error.name === "ElectroError") {
+            // DynamoDB client/infrastructure errors should be 500
+            // These contain "aws-error" in the message or reference URL
+            const isInfrastructureError = error.message.includes("aws-error") ||
+                error.message.includes("DynamoDB client");
+            const statusCode = isInfrastructureError ? 500 : 400;
+            const logMessage = isInfrastructureError
+                ? "DynamoDB infrastructure error"
+                : "ElectroError";
+            logger.error({ error: error.message, stack: error.stack }, logMessage);
+            // Don't expose internal details for infrastructure errors
+            const responseMessage = isInfrastructureError
+                ? "Database temporarily unavailable"
+                : error.message;
+            return formatResponse({ code: defaultErrorCode(statusCode), message: responseMessage }, statusCode);
+        }
+        logger.error({ error: error.message, name: error.name, stack: error.stack }, "Unhandled Error");
+        return formatResponse({ code: INTERNAL_ERROR_CODE, message: INTERNAL_ERROR_MESSAGE }, 500);
+    }
+    logger.error({ error: JSON.stringify(error) }, "Unknown error type");
+    return formatResponse({ code: INTERNAL_ERROR_CODE, message: INTERNAL_ERROR_MESSAGE }, 500);
+};

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

@@ -0,0 +1,36 @@
+import type { AccountResponse, AccountService as AccountServiceName, FolderAppointment } from "@remit/api-openapi-types";
+import type { AccountItem } from "@remit/data-ports";
+import type { AccountOverrides } from "./account-overrides.js";
+import type { AccountSignature } from "./account-signature.js";
+/**
+ * Natural key identifying "the same mailbox in the same place" within an
+ * account config. IMAP host and login username are both case-insensitive, so we
+ * fold to lowercase before comparing. Used as the explicit server-side
+ * uniqueness key now that message identity is account-scoped (entropy per
+ * onboard) and no longer incidentally dedups duplicate onboards (#633/#635).
+ */
+export interface MailboxNaturalKey {
+    imapHost: string;
+    username: string;
+}
+/**
+ * Find an existing ACTIVE (non-deleted) account that occupies the same
+ * mailbox-in-the-same-place as `key`. Soft-deleted accounts are ignored so a
+ * re-onboard after delete still succeeds.
+ *
+ * Callers pass the accounts already scoped to one account config (the natural
+ * key's accountConfigId component), so this only matches on host + username.
+ */
+export declare const findActiveDuplicateMailbox: (existing: AccountItem[], key: MailboxNaturalKey) => AccountItem | undefined;
+/**
+ * Reject the create when an active account already onboards the same mailbox in
+ * the same place. Surfaces as a typed 409 ConflictError so the web-client can
+ * show a "already added" message instead of silently creating a duplicate.
+ */
+export declare const assertNoDuplicateMailbox: (existing: AccountItem[], key: MailboxNaturalKey) => void;
+/** Rejects OAuth accounts that must go through the dedicated connect flow. */
+export declare const assertNotOAuthCreate: (authType: string | undefined) => void;
+/** Rejects password-auth account creation when no password is supplied. */
+export declare const assertPasswordProvided: (authType: string | undefined, password: string | undefined) => void;
+export declare const resolveSyncedServices: (account: Pick<AccountItem, "authType" | "grantedScopes">, requested: readonly AccountServiceName[]) => AccountServiceName[];
+export declare const toAccountResponse: (account: AccountItem, signature?: AccountSignature, overrides?: AccountOverrides, folderAppointments?: FolderAppointment[]) => AccountResponse;

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

@@ -0,0 +1,107 @@
+import { BadRequestError, ConflictError } from "@remit/data-ports/errors";
+import { AccountAuthType, AccountService } from "@remit/domain-enums";
+import { microsoftServicesGranted, orderServices, } from "@remit/mail-oauth-service";
+const mailboxKeyOf = (key) => `${key.imapHost.toLowerCase()}\u0000${key.username.toLowerCase()}`;
+/**
+ * Find an existing ACTIVE (non-deleted) account that occupies the same
+ * mailbox-in-the-same-place as `key`. Soft-deleted accounts are ignored so a
+ * re-onboard after delete still succeeds.
+ *
+ * Callers pass the accounts already scoped to one account config (the natural
+ * key's accountConfigId component), so this only matches on host + username.
+ */
+export const findActiveDuplicateMailbox = (existing, key) => {
+    const target = mailboxKeyOf(key);
+    return existing.find((account) => !account.deletedAt &&
+        mailboxKeyOf({
+            imapHost: account.imapHost,
+            username: account.username,
+        }) === target);
+};
+/**
+ * Reject the create when an active account already onboards the same mailbox in
+ * the same place. Surfaces as a typed 409 ConflictError so the web-client can
+ * show a "already added" message instead of silently creating a duplicate.
+ */
+export const assertNoDuplicateMailbox = (existing, key) => {
+    const duplicate = findActiveDuplicateMailbox(existing, key);
+    if (!duplicate)
+        return;
+    throw new ConflictError(`An account for ${key.username} on ${key.imapHost} already exists`);
+};
+/** Rejects OAuth accounts that must go through the dedicated connect flow. */
+export const assertNotOAuthCreate = (authType) => {
+    if (authType === AccountAuthType.OauthMicrosoft) {
+        throw new BadRequestError("OAuth accounts must be created via the OAuth connect flow (POST /accounts/oauth/microsoft/start)");
+    }
+};
+/** Rejects password-auth account creation when no password is supplied. */
+export const assertPasswordProvided = (authType, password) => {
+    const isPasswordAuth = authType === AccountAuthType.Password || !authType;
+    if (isPasswordAuth && !password) {
+        throw new BadRequestError("password is required when authType is 'password' (or when authType is omitted)");
+    }
+};
+export const resolveSyncedServices = (account, requested) => {
+    const services = orderServices(requested);
+    if (services.length === 0) {
+        throw new BadRequestError("syncedServices must name at least one service. To stop syncing an account entirely, delete it with DELETE /accounts/{accountId}.");
+    }
+    if (account.authType !== AccountAuthType.OauthMicrosoft) {
+        if (services.some((service) => service !== AccountService.Mail)) {
+            throw new BadRequestError(`A password account syncs mail only, so syncedServices must be ["${AccountService.Mail}"].`);
+        }
+        return services;
+    }
+    const granted = microsoftServicesGranted(account.grantedScopes);
+    const uncovered = services.filter((service) => !granted.includes(service));
+    if (uncovered.length > 0) {
+        throw new BadRequestError(`This account's granted scopes lack ${uncovered.join(", ")}. Consent to them through POST /accounts/oauth/microsoft/start with services ${JSON.stringify(services)}, then sign in to Microsoft again.`);
+    }
+    return services;
+};
+// SECURITY: passwordHash, oauthRefreshTokenHash, and smtpPasswordHash are
+// intentionally omitted — never expose token material in API responses.
+// Display name, mute flag, and signatures live in per-account AccountSetting
+// rows (RFC 032); the caller resolves them and passes them in. Absent means the
+// override is unset. `folderAppointments` (RFC 032 exclusive-folder-appointment,
+// #976) is resolved the same way — persisted rows merged with server-proposed
+// defaults for any unfilled role — via `resolveFolderAppointments`.
+export const toAccountResponse = (account, signature = {}, overrides = {}, folderAppointments = []) => ({
+    accountId: account.accountId,
+    accountConfigId: account.accountConfigId,
+    displayName: overrides.displayName,
+    username: account.username,
+    email: account.email,
+    authType: account.authType ?? AccountAuthType.Password,
+    syncedServices: account.syncedServices,
+    grantedScopes: account.grantedScopes,
+    imapHost: account.imapHost,
+    imapPort: account.imapPort,
+    imapTls: account.imapTls,
+    imapStartTls: account.imapStartTls,
+    // RFC 032 Tier 2: SMTP config is total. ElectroDB `default` applies on write
+    // only, so rows written before this change still lack these attributes —
+    // coalesce to the schema defaults on read so the response is always complete.
+    smtpEnabled: account.smtpEnabled ?? false,
+    smtpHost: account.smtpHost ?? "",
+    smtpPort: account.smtpPort ?? 587,
+    smtpTls: account.smtpTls ?? false,
+    smtpStartTls: account.smtpStartTls ?? true,
+    smtpUsername: account.smtpUsername ?? "",
+    signaturePlainText: signature.plainText,
+    signatureHtml: signature.html,
+    composeLanguages: overrides.composeLanguages,
+    isActive: account.isActive,
+    connectionState: account.connectionState,
+    lastConnectedAt: account.lastConnectedAt,
+    lastSyncAt: account.lastSyncAt,
+    lastError: account.lastError,
+    syncPhase: account.syncPhase,
+    mailboxCountTotal: account.mailboxCountTotal,
+    mailboxCountSynced: account.mailboxCountSynced,
+    muted: overrides.muted,
+    createdAt: account.createdAt,
+    updatedAt: account.updatedAt,
+    folderAppointments,
+});

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

@@ -0,0 +1,15 @@
+import type { AccountService as AccountServiceName } from "@remit/api-openapi-types";
+import type { MicrosoftOAuthOperationIds, OperationHandler, PublicOperationHandler, PublicOperationIds } 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 declare const MicrosoftOAuthOperations: Record<Exclude<MicrosoftOAuthOperationIds, PublicOperationIds>, OperationHandler<MicrosoftOAuthOperationIds, "sync">>;

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

@@ -0,0 +1,334 @@
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { AccountAuthType, AccountService, ConnectionState, } from "@remit/domain-enums";
+import { logger } from "@remit/logger";
+import { createMailOAuthService, microsoftProviderConfig, microsoftServicesGranted, orderServices, RefreshTokenError, } from "@remit/mail-oauth-service";
+import { serializeEncryptedPayload } from "@remit/secrets-service";
+import { loadMsOAuth } from "../config/msoauth.js";
+import { safeJsonParse } from "../json.js";
+import { rawApiResponse } from "../response.js";
+import { triggerAccountSyncSafe } from "./account.js";
+import { findActiveDuplicateMailbox } from "./account-guards.js";
+import { ensureAccountConfig } from "./ensure-account-config.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;
+}
+// ─── JWT claims parsing ──────────────────────────────────────────────────────
+export async function parseJwtClaims(token) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        return null;
+    return safeJsonParse(Buffer.from(parts[1], "base64url").toString("utf8")).catch(() => null);
+}
+// ─── Web origin helper ───────────────────────────────────────────────────────
+export function getWebOrigin(origins) {
+    // Prefer the first HTTPS origin (production frontend)
+    const httpsOrigin = origins.find((o) => o.startsWith("https://"));
+    return httpsOrigin ?? origins[0] ?? "https://localhost:3000";
+}
+const scopeRefusalUrl = (webOrigin, email, missingServices) => {
+    const url = new URL(`${webOrigin}/settings/accounts`);
+    url.searchParams.set("oauthError", "scope_not_granted");
+    url.searchParams.set("oauthEmail", email);
+    url.searchParams.set("missingServices", missingServices.join(","));
+    return url.toString();
+};
+const redeemEachService = async (serviceFor, initialToken, services, accountConfigId) => {
+    let token = initialToken;
+    const grantedScopes = [];
+    for (const service of services) {
+        const redeemed = await serviceFor(service)
+            .refresh(token)
+            .catch((err) => {
+            logger.warn({
+                alert: "oauth_callback_failed",
+                reason: "scope_redemption_failed",
+                accountConfigId,
+                service,
+                error: err,
+            }, "MS OAuth callback: the consent did not cover a requested service");
+            return err instanceof RefreshTokenError &&
+                err.error.kind === "transient"
+                ? "exchange_failed"
+                : "scope_not_granted";
+        });
+        if (redeemed === "exchange_failed")
+            return { kind: "refused", reason: redeemed };
+        if (redeemed === "scope_not_granted")
+            return { kind: "refused", reason: redeemed, service };
+        grantedScopes.push(...redeemed.grantedScopes);
+        token = redeemed.refreshToken ?? token;
+    }
+    return { kind: "granted", refreshToken: token, grantedScopes };
+};
+// ─── Handlers ────────────────────────────────────────────────────────────────
+export const microsoftOAuthCallback = async (context, ctx) => {
+    const webOrigin = getWebOrigin(ctx.config.corsAllowedOrigins);
+    const qs = context.request.query;
+    // Marked raw so the response formatter forwards the Location header
+    // instead of serializing this object as a JSON body. Microsoft's browser
+    // redirect lands here, so a dropped Location is a blank page.
+    const redirect = (url) => rawApiResponse({
+        statusCode: 302,
+        headers: { Location: url },
+        body: "",
+    });
+    // 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}`);
+    }
+    const code = qs.code;
+    const state = qs.state;
+    if (!code || !state) {
+        return redirect(`${webOrigin}/settings/accounts?oauthError=missing_params`);
+    }
+    const loaded = await loadMsOAuth(ctx.config.msOAuth).catch((err) => {
+        logger.error({
+            alert: "oauth_callback_failed",
+            reason: "config_error",
+            errorName: err?.name,
+            errorCode: err?.Code ?? err?.code,
+            error: err,
+        }, "MS OAuth callback: failed to load OAuth config");
+        return null;
+    });
+    if (loaded === null)
+        return redirect(`${webOrigin}/settings/accounts?oauthError=config_error`);
+    const { config, credentials } = loaded;
+    // Verify the HMAC-signed state
+    // A bad/expired/forged state is a security-relevant signal (CSRF
+    // attempt, clock skew, or a stale callback) — must not be swallowed
+    // silently. Warn so it's observable; still redirect the user cleanly.
+    const statePayload = await verifyState(state, credentials.clientSecret).catch((err) => {
+        logger.warn({
+            alert: "oauth_callback_failed",
+            reason: "invalid_state",
+            errorName: err?.name,
+            error: err,
+        }, "MS OAuth callback: state verification failed");
+        return null;
+    });
+    if (statePayload === null)
+        return redirect(`${webOrigin}/settings/accounts?oauthError=invalid_state`);
+    const { accountConfigId } = statePayload;
+    const [firstService] = orderServices(statePayload.services);
+    const serviceFor = (service) => createMailOAuthService(microsoftProviderConfig({
+        clientId: credentials.clientId,
+        clientSecret: credentials.clientSecret,
+        services: [service],
+        overrides: config.overrides,
+    }));
+    // Exchange the authorization code for tokens
+    const tokenSet = await serviceFor(firstService)
+        .exchangeCode(code, config.redirectUri)
+        .catch((err) => {
+        logger.error({ accountConfigId, error: err }, "MS OAuth code exchange failed");
+        return null;
+    });
+    if (tokenSet === null)
+        return redirect(`${webOrigin}/settings/accounts?oauthError=exchange_failed`);
+    if (!tokenSet.refreshToken) {
+        logger.error({ accountConfigId }, "MS OAuth token exchange returned no refresh_token");
+        return redirect(`${webOrigin}/settings/accounts?oauthError=exchange_failed`);
+    }
+    // Extract the user's email from the ID token returned alongside the access
+    // token when openid+email scopes are requested.
+    //
+    // We prefer the ID token (idToken) because Outlook resource access tokens
+    // (IMAP.AccessAsUser.All, SMTP.Send) are opaque/non-JWT and cannot be
+    // decoded. The ID token is a standard OIDC token that always contains
+    // identity claims (preferred_username / email).
+    //
+    // Falls back to parsing the access token only in test/dev environments where
+    // idToken may not be present (e.g. custom token endpoints that don't issue
+    // OIDC tokens).
+    const tokenToParse = tokenSet.idToken ?? tokenSet.accessToken;
+    const claims = await parseJwtClaims(tokenToParse);
+    if (!claims) {
+        // A non-JWT or unparseable token. The empty-email guard below turns
+        // this into a user-facing missing_email redirect; log here so the parse
+        // failure itself is observable (e.g. an unexpected token shape).
+        logger.warn({
+            alert: "oauth_callback_failed",
+            reason: "jwt_parse_failed",
+            accountConfigId,
+        }, "MS OAuth callback: failed to parse identity token claims");
+    }
+    const email = claims
+        ? (claims.preferred_username ??
+            claims.email ??
+            claims.upn)
+        : undefined;
+    if (!email) {
+        logger.error({ accountConfigId }, "MS OAuth: could not extract email from token claims");
+        return redirect(`${webOrigin}/settings/accounts?oauthError=missing_email`);
+    }
+    const { account, accountConfig, secrets } = ctx.client;
+    // Reconnect when an active OAuth account already onboards this mailbox.
+    // Same natural key as the IMAP create guard (#635); the OAuth flow returns
+    // 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 existing = findActiveDuplicateMailbox(existingAccounts, {
+        imapHost: OUTLOOK_IMAP_HOST,
+        username: email,
+    });
+    const services = orderServices([
+        ...statePayload.services,
+        ...(existing?.syncedServices ?? []),
+    ]);
+    const redemption = await redeemEachService(serviceFor, tokenSet.refreshToken, services.filter((service) => service !== firstService), accountConfigId);
+    if (redemption.kind === "refused" &&
+        redemption.reason === "scope_not_granted")
+        return redirect(scopeRefusalUrl(webOrigin, email, [redemption.service]));
+    if (redemption.kind === "refused")
+        return redirect(`${webOrigin}/settings/accounts?oauthError=${redemption.reason}`);
+    const grantedScopes = [
+        ...new Set([...tokenSet.grantedScopes, ...redemption.grantedScopes]),
+    ];
+    const grantedServices = microsoftServicesGranted(grantedScopes);
+    const missingServices = services.filter((service) => !grantedServices.includes(service));
+    if (missingServices.length > 0) {
+        logger.warn({
+            alert: "oauth_callback_failed",
+            reason: "scope_not_granted",
+            accountConfigId,
+            missingServices,
+            grantedScopes,
+        }, "MS OAuth callback: granted scopes lack a requested service");
+        return redirect(scopeRefusalUrl(webOrigin, email, missingServices));
+    }
+    // Ensure the account config row exists for this user
+    await ensureAccountConfig(accountConfig, accountConfigId);
+    // Encrypt the refresh token
+    const tokenPayload = await secrets.encrypt(redemption.refreshToken);
+    const oauthRefreshTokenHash = JSON.stringify(serializeEncryptedPayload(tokenPayload));
+    const oauthTokenUpdatedAt = Date.now();
+    let accountId;
+    if (existing) {
+        // Reconnect: update the stored token and clear any reauth_required state
+        const updated = await account.update(existing.accountId, {
+            oauthRefreshTokenHash,
+            oauthTokenUpdatedAt,
+            syncedServices: services,
+            grantedScopes,
+            connectionState: ConnectionState.NotAuthenticated,
+        }, ["lastError"]);
+        accountId = updated.accountId;
+        // biome-ignore lint/plugin/no-logger-info: OAuth reconnect is an audit-grade signal
+        logger.info({ accountConfigId, accountId }, "MS OAuth reconnect: refresh token updated");
+    }
+    else {
+        // First connect: create a new account
+        const newAccount = await account.create({
+            accountConfigId,
+            email,
+            username: email,
+            authType: AccountAuthType.OauthMicrosoft,
+            syncedServices: services,
+            grantedScopes,
+            oauthRefreshTokenHash,
+            oauthTokenUpdatedAt,
+            imapHost: OUTLOOK_IMAP_HOST,
+            imapPort: 993,
+            imapTls: true,
+            imapStartTls: false,
+            smtpEnabled: true,
+            smtpHost: "smtp.office365.com",
+            smtpPort: 587,
+            smtpTls: false,
+            smtpStartTls: true,
+            isActive: true,
+            connectionState: ConnectionState.NotAuthenticated,
+        });
+        accountId = newAccount.accountId;
+        // biome-ignore lint/plugin/no-logger-info: OAuth account creation is an audit-grade signal
+        logger.info({ accountConfigId, accountId }, "MS OAuth: new account created");
+    }
+    if (services.includes(AccountService.Mail)) {
+        await triggerAccountSyncSafe(ctx.client, accountId);
+    }
+    return redirect(`${webOrigin}/settings/accounts?connected=${encodeURIComponent(accountId)}`);
+};
+export const MicrosoftOAuthOperations = {
+    MicrosoftOAuthOperations_microsoftOAuthStart: async (context, ctx) => {
+        const accountConfigId = ctx.identity.accountConfigId;
+        const input = context.request.requestBody;
+        const email = typeof input.email === "string" ? input.email : undefined;
+        const services = orderServices(input.services ?? [AccountService.Mail]);
+        const { config, credentials } = await loadMsOAuth(ctx.config.msOAuth);
+        const oauthService = createMailOAuthService(microsoftProviderConfig({
+            clientId: credentials.clientId,
+            clientSecret: credentials.clientSecret,
+            services,
+            overrides: config.overrides,
+        }));
+        const nonce = randomBytes(16).toString("hex");
+        const statePayload = {
+            accountConfigId,
+            nonce,
+            timestamp: Date.now(),
+            services,
+        };
+        const state = await signState(statePayload, credentials.clientSecret);
+        const authorizationUrl = oauthService.buildAuthorizationUrl({
+            redirectUri: config.redirectUri,
+            state,
+            loginHint: email,
+        });
+        // biome-ignore lint/plugin/no-logger-info: OAuth initiation is an audit-grade signal
+        logger.info({ accountConfigId, services }, "Microsoft OAuth start initiated");
+        return { authorizationUrl };
+    },
+};