@remit/backend 0.0.143 → 0.0.144

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

@@ -0,0 +1,387 @@
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { inspect } from "node:util";
+import { GetSecretValueCommand, SecretsManagerClient, } from "@aws-sdk/client-secrets-manager";
+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 { getAccountConfigIdFromEvent } from "../auth.js";
+import { getMsOAuthConfig } from "../config/msoauth.js";
+import { safeJsonParse } from "../json.js";
+import { rawApiResponse } from "../response.js";
+import { getClient } from "../service/data-client.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);
+}
+let smClient = null;
+function getSecretsManagerClient() {
+    if (!smClient)
+        smClient = new SecretsManagerClient({});
+    return smClient;
+}
+function credentialFailure(name, message) {
+    const error = new Error(message);
+    error.name = name;
+    return error;
+}
+async function getMsOAuthCredentials() {
+    const config = getMsOAuthConfig();
+    // Local dev: use env vars directly
+    if (config.clientId && config.clientSecret) {
+        return { clientId: config.clientId, clientSecret: config.clientSecret };
+    }
+    // Production: fetch from Secrets Manager
+    if (!config.secretArn) {
+        throw credentialFailure("MicrosoftOAuthNotConfigured", "No Microsoft OAuth credentials are configured on this instance: set MSOAUTH_CLIENT_ID and MSOAUTH_CLIENT_SECRET, or MSOAUTH_SECRET_ARN");
+    }
+    const sm = getSecretsManagerClient();
+    const result = await sm.send(new GetSecretValueCommand({ SecretId: config.secretArn }));
+    if (!result.SecretString) {
+        throw credentialFailure("MicrosoftOAuthSecretEmpty", "The Microsoft OAuth secret named by MSOAUTH_SECRET_ARN holds no SecretString");
+    }
+    const parsed = await safeJsonParse(result.SecretString).catch(() => null);
+    if (!parsed) {
+        throw credentialFailure("MicrosoftOAuthSecretUnparseable", "The Microsoft OAuth secret named by MSOAUTH_SECRET_ARN does not hold a JSON object");
+    }
+    const absent = ["clientId", "clientSecret"].filter((field) => !parsed[field]);
+    if (absent.length > 0) {
+        throw credentialFailure("MicrosoftOAuthSecretIncomplete", `The Microsoft OAuth secret named by MSOAUTH_SECRET_ARN is missing ${absent.join(" and ")}`);
+    }
+    return parsed;
+}
+// ─── Web origin helper ───────────────────────────────────────────────────────
+export function getWebOrigin() {
+    const raw = process.env.CORS_ALLOWED_ORIGINS ?? "";
+    const origins = raw
+        .split(",")
+        .map((o) => o.trim())
+        .filter(Boolean);
+    // 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: inspect(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 MicrosoftOAuthOperations = {
+    MicrosoftOAuthOperations_microsoftOAuthStart: async (_context, ...args) => {
+        const event = args[0];
+        const accountConfigId = getAccountConfigIdFromEvent(event);
+        const input = JSON.parse(event.body ?? "{}");
+        const email = typeof input.email === "string" ? input.email : undefined;
+        const services = orderServices(input.services ?? [AccountService.Mail]);
+        const config = getMsOAuthConfig();
+        const credentials = await getMsOAuthCredentials();
+        const oauthService = createMailOAuthService(microsoftProviderConfig({
+            clientId: credentials.clientId,
+            clientSecret: credentials.clientSecret,
+            services,
+            overrides: config.tokenEndpoint
+                ? { tokenEndpoint: config.tokenEndpoint }
+                : undefined,
+        }));
+        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 };
+    },
+    MicrosoftOAuthOperations_microsoftOAuthCallback: async (_context, ...args) => {
+        const event = args[0];
+        const webOrigin = getWebOrigin();
+        const qs = event.queryStringParameters ?? {};
+        // 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 credentials = await getMsOAuthCredentials().catch((err) => {
+            logger.error({
+                alert: "oauth_callback_failed",
+                reason: "config_error",
+                errorName: err?.name,
+                errorCode: err?.Code ??
+                    err?.code,
+                error: inspect(err),
+            }, "MS OAuth callback: failed to load OAuth config");
+            return null;
+        });
+        if (credentials === null)
+            return redirect(`${webOrigin}/settings/accounts?oauthError=config_error`);
+        // 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: inspect(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 config = getMsOAuthConfig();
+        const serviceFor = (service) => createMailOAuthService(microsoftProviderConfig({
+            clientId: credentials.clientId,
+            clientSecret: credentials.clientSecret,
+            services: [service],
+            overrides: config.tokenEndpoint
+                ? { tokenEndpoint: config.tokenEndpoint }
+                : undefined,
+        }));
+        // Exchange the authorization code for tokens
+        const tokenSet = await serviceFor(firstService)
+            .exchangeCode(code, config.redirectUri)
+            .catch((err) => {
+            logger.error({ accountConfigId, error: inspect(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 } = await getClient();
+        // 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(accountId);
+        }
+        return redirect(`${webOrigin}/settings/accounts?connected=${encodeURIComponent(accountId)}`);
+    },
+};

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

@@ -0,0 +1,53 @@
+import type { MutedFlag } from "@remit/api-openapi-types";
+import type { AccountSettingItem, IAccountSettingRepository } from "@remit/data-ports";
+export interface AccountOverrides {
+    displayName?: string;
+    muted?: MutedFlag;
+    composeLanguages?: string[];
+}
+export interface MailboxOverrides {
+    displayNameOverride?: string;
+    muted?: MutedFlag;
+}
+export declare const groupAccountOverrides: (settings: AccountSettingItem[]) => Map<string, AccountOverrides>;
+/**
+ * Resolve one account's display-name/mute overrides by reading just its two
+ * composite rows. Used by the account create/update handlers.
+ */
+export declare const loadAccountOverrides: (accountSetting: IAccountSettingRepository, accountConfigId: string, accountId: string) => Promise<AccountOverrides>;
+export declare const upsertAccountDisplayName: (accountSetting: IAccountSettingRepository, accountConfigId: string, accountId: string, displayName: string) => Promise<unknown>;
+/**
+ * Replace the account's compose-language list. An empty array deletes the row:
+ * the client falls back to the browser's own languages when the setting is
+ * absent, and an account that offers no language at all has nothing to pick
+ * from (RFC 032: absence is "unset").
+ */
+export declare const writeAccountComposeLanguages: (accountSetting: IAccountSettingRepository, accountConfigId: string, accountId: string, languages: string[]) => Promise<unknown>;
+/**
+ * Set or clear the account mute flag. A `MutedFlag` upserts the row; `null`
+ * deletes it (RFC 032: absence is "unset"). Mirrors the address-flag
+ * null→remove, object→set semantics.
+ */
+export declare const writeAccountMuted: (accountSetting: IAccountSettingRepository, accountConfigId: string, accountId: string, muted: MutedFlag | null) => Promise<unknown>;
+export declare const groupMailboxOverrides: (settings: AccountSettingItem[]) => Map<string, MailboxOverrides>;
+/**
+ * Load every mailbox's overrides for an account configuration in one query,
+ * grouped by mailboxId. listMailboxes uses this once to avoid an N+1 per mailbox.
+ */
+export declare const loadMailboxOverridesForConfig: (accountSetting: IAccountSettingRepository, accountConfigId: string) => Promise<Map<string, MailboxOverrides>>;
+/**
+ * Resolve one mailbox's overrides by reading just its two composite rows.
+ * Used by getMailbox and the rename/PATCH handler.
+ */
+export declare const loadMailboxOverrides: (accountSetting: IAccountSettingRepository, accountConfigId: string, mailboxId: string) => Promise<MailboxOverrides>;
+/**
+ * Apply a mailbox PATCH's override changes (displayNameOverride / muted) to
+ * AccountSetting rows. For each field: `null` deletes the row, a value upserts
+ * it, `undefined`/absent is a no-op — the same semantics the entity-backed
+ * version used. The canonical role a folder fills is written separately via
+ * `writeFolderRoleAppointment` (RFC 032 exclusive-folder-appointment, #976).
+ */
+export declare const applyMailboxOverrideChanges: (accountSetting: Pick<IAccountSettingRepository, "upsert" | "delete">, accountConfigId: string, mailboxId: string, changes: {
+    displayNameOverride?: string | null;
+    muted?: MutedFlag | null;
+}) => Promise<void>;

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

@@ -0,0 +1,233 @@
+import { baseSettingName, composeSettingName, SETTING_NAME_SEPARATOR, } from "@remit/data-ports/account-settings";
+/**
+ * RFC 032 Tier 1: the per-account display name and mute flag, and the
+ * per-mailbox display-name override and mute flag, live in AccountSetting
+ * rows — not on the Account/Mailbox entities. They are stored as composite-named
+ * rows keyed by the target id (`AccountDisplayName#<accountId>`,
+ * `MailboxMuted#<mailboxId>`, …), so one `listByAccountConfig` query yields every
+ * target's overrides; readers group them by the `#<targetId>` suffix. This mirrors
+ * the signature helper (`account-signature.ts`). The per-folder role override
+ * this module used to carry is superseded by the per-account role map — see
+ * `folder-role-appointments.ts` (RFC 032 exclusive-folder-appointment, #976).
+ */
+const ACCOUNT_OVERRIDE_NAMES = {
+    displayName: "AccountDisplayName",
+    muted: "AccountMuted",
+    composeLanguages: "AccountComposeLanguages",
+};
+const MAILBOX_OVERRIDE_NAMES = {
+    displayName: "MailboxDisplayName",
+    muted: "MailboxMuted",
+};
+const stringValueOf = (item) => {
+    const { value } = item;
+    if (value.kind === "String")
+        return value.value;
+    return undefined;
+};
+const mutedValueOf = (item) => {
+    const { value } = item;
+    if (value.kind === "MutedFlag")
+        return value.value;
+    return undefined;
+};
+const stringListValueOf = (item) => {
+    const { value } = item;
+    if (value.kind === "StringList")
+        return value.value;
+    return undefined;
+};
+const targetIdOf = (name) => {
+    const idx = name.indexOf(SETTING_NAME_SEPARATOR);
+    if (idx === -1)
+        return undefined;
+    return name.slice(idx + SETTING_NAME_SEPARATOR.length) || undefined;
+};
+// ============================================
+// Account overrides (displayName + muted)
+// ============================================
+export const groupAccountOverrides = (settings) => {
+    const byAccount = new Map();
+    for (const setting of settings) {
+        const accountId = targetIdOf(setting.name);
+        if (!accountId)
+            continue;
+        const base = baseSettingName(setting.name);
+        if (base === ACCOUNT_OVERRIDE_NAMES.displayName) {
+            const displayName = stringValueOf(setting);
+            if (displayName === undefined)
+                continue;
+            const current = byAccount.get(accountId) ?? {};
+            current.displayName = displayName;
+            byAccount.set(accountId, current);
+            continue;
+        }
+        if (base === ACCOUNT_OVERRIDE_NAMES.muted) {
+            const muted = mutedValueOf(setting);
+            if (muted === undefined)
+                continue;
+            const current = byAccount.get(accountId) ?? {};
+            current.muted = muted;
+            byAccount.set(accountId, current);
+            continue;
+        }
+        if (base === ACCOUNT_OVERRIDE_NAMES.composeLanguages) {
+            const composeLanguages = stringListValueOf(setting);
+            if (composeLanguages === undefined)
+                continue;
+            const current = byAccount.get(accountId) ?? {};
+            current.composeLanguages = composeLanguages;
+            byAccount.set(accountId, current);
+        }
+    }
+    return byAccount;
+};
+/**
+ * Resolve one account's display-name/mute overrides by reading just its two
+ * composite rows. Used by the account create/update handlers.
+ */
+export const loadAccountOverrides = async (accountSetting, accountConfigId, accountId) => {
+    const [displayName, muted, composeLanguages] = await Promise.all([
+        accountSetting.get(accountConfigId, composeSettingName(ACCOUNT_OVERRIDE_NAMES.displayName, accountId)),
+        accountSetting.get(accountConfigId, composeSettingName(ACCOUNT_OVERRIDE_NAMES.muted, accountId)),
+        accountSetting.get(accountConfigId, composeSettingName(ACCOUNT_OVERRIDE_NAMES.composeLanguages, accountId)),
+    ]);
+    const overrides = {};
+    const displayNameValue = displayName ? stringValueOf(displayName) : undefined;
+    const mutedValue = muted ? mutedValueOf(muted) : undefined;
+    const languagesValue = composeLanguages
+        ? stringListValueOf(composeLanguages)
+        : undefined;
+    if (displayNameValue !== undefined)
+        overrides.displayName = displayNameValue;
+    if (mutedValue !== undefined)
+        overrides.muted = mutedValue;
+    if (languagesValue !== undefined)
+        overrides.composeLanguages = languagesValue;
+    return overrides;
+};
+export const upsertAccountDisplayName = (accountSetting, accountConfigId, accountId, displayName) => accountSetting.upsert({
+    accountConfigId,
+    name: composeSettingName(ACCOUNT_OVERRIDE_NAMES.displayName, accountId),
+    value: { kind: "String", value: displayName },
+});
+/**
+ * Replace the account's compose-language list. An empty array deletes the row:
+ * the client falls back to the browser's own languages when the setting is
+ * absent, and an account that offers no language at all has nothing to pick
+ * from (RFC 032: absence is "unset").
+ */
+export const writeAccountComposeLanguages = (accountSetting, accountConfigId, accountId, languages) => {
+    const name = composeSettingName(ACCOUNT_OVERRIDE_NAMES.composeLanguages, accountId);
+    if (languages.length === 0) {
+        return accountSetting.delete(accountConfigId, name);
+    }
+    return accountSetting.upsert({
+        accountConfigId,
+        name,
+        value: { kind: "StringList", value: languages },
+    });
+};
+/**
+ * Set or clear the account mute flag. A `MutedFlag` upserts the row; `null`
+ * deletes it (RFC 032: absence is "unset"). Mirrors the address-flag
+ * null→remove, object→set semantics.
+ */
+export const writeAccountMuted = (accountSetting, accountConfigId, accountId, muted) => {
+    const name = composeSettingName(ACCOUNT_OVERRIDE_NAMES.muted, accountId);
+    if (muted === null) {
+        return accountSetting.delete(accountConfigId, name);
+    }
+    return accountSetting.upsert({
+        accountConfigId,
+        name,
+        value: { kind: "MutedFlag", value: muted },
+    });
+};
+// ============================================
+// Mailbox overrides (displayNameOverride + muted)
+// ============================================
+export const groupMailboxOverrides = (settings) => {
+    const byMailbox = new Map();
+    for (const setting of settings) {
+        const mailboxId = targetIdOf(setting.name);
+        if (!mailboxId)
+            continue;
+        const base = baseSettingName(setting.name);
+        if (base === MAILBOX_OVERRIDE_NAMES.displayName) {
+            const displayName = stringValueOf(setting);
+            if (displayName === undefined)
+                continue;
+            const current = byMailbox.get(mailboxId) ?? {};
+            current.displayNameOverride = displayName;
+            byMailbox.set(mailboxId, current);
+            continue;
+        }
+        if (base === MAILBOX_OVERRIDE_NAMES.muted) {
+            const muted = mutedValueOf(setting);
+            if (muted === undefined)
+                continue;
+            const current = byMailbox.get(mailboxId) ?? {};
+            current.muted = muted;
+            byMailbox.set(mailboxId, current);
+        }
+    }
+    return byMailbox;
+};
+/**
+ * Load every mailbox's overrides for an account configuration in one query,
+ * grouped by mailboxId. listMailboxes uses this once to avoid an N+1 per mailbox.
+ */
+export const loadMailboxOverridesForConfig = async (accountSetting, accountConfigId) => {
+    const settings = await accountSetting.listByAccountConfig(accountConfigId);
+    return groupMailboxOverrides(settings);
+};
+/**
+ * Resolve one mailbox's overrides by reading just its two composite rows.
+ * Used by getMailbox and the rename/PATCH handler.
+ */
+export const loadMailboxOverrides = async (accountSetting, accountConfigId, mailboxId) => {
+    const [displayName, muted] = await Promise.all([
+        accountSetting.get(accountConfigId, composeSettingName(MAILBOX_OVERRIDE_NAMES.displayName, mailboxId)),
+        accountSetting.get(accountConfigId, composeSettingName(MAILBOX_OVERRIDE_NAMES.muted, mailboxId)),
+    ]);
+    const overrides = {};
+    const displayNameValue = displayName ? stringValueOf(displayName) : undefined;
+    const mutedValue = muted ? mutedValueOf(muted) : undefined;
+    if (displayNameValue !== undefined)
+        overrides.displayNameOverride = displayNameValue;
+    if (mutedValue !== undefined)
+        overrides.muted = mutedValue;
+    return overrides;
+};
+/**
+ * Apply a mailbox PATCH's override changes (displayNameOverride / muted) to
+ * AccountSetting rows. For each field: `null` deletes the row, a value upserts
+ * it, `undefined`/absent is a no-op — the same semantics the entity-backed
+ * version used. The canonical role a folder fills is written separately via
+ * `writeFolderRoleAppointment` (RFC 032 exclusive-folder-appointment, #976).
+ */
+export const applyMailboxOverrideChanges = async (accountSetting, accountConfigId, mailboxId, changes) => {
+    const writes = [];
+    if (changes.displayNameOverride !== undefined) {
+        const name = composeSettingName(MAILBOX_OVERRIDE_NAMES.displayName, mailboxId);
+        writes.push(changes.displayNameOverride === null
+            ? accountSetting.delete(accountConfigId, name)
+            : accountSetting.upsert({
+                accountConfigId,
+                name,
+                value: { kind: "String", value: changes.displayNameOverride },
+            }));
+    }
+    if (changes.muted !== undefined) {
+        const name = composeSettingName(MAILBOX_OVERRIDE_NAMES.muted, mailboxId);
+        writes.push(changes.muted === null
+            ? accountSetting.delete(accountConfigId, name)
+            : accountSetting.upsert({
+                accountConfigId,
+                name,
+                value: { kind: "MutedFlag", value: changes.muted },
+            }));
+    }
+    await Promise.all(writes);
+};