@remit/backend 0.0.143 → 0.0.144

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

@@ -0,0 +1,28 @@
+import type { AccountSettingItem, IAccountSettingRepository } from "@remit/data-ports";
+export interface AccountSignature {
+    plainText?: string;
+    html?: string;
+}
+/**
+ * Build a per-account signature lookup from the whole settings set of one
+ * account configuration. Signatures are stored as composite-named rows
+ * (`AccountSignaturePlainText#<accountId>` / `AccountSignatureHtml#<accountId>`),
+ * so one `listByAccountConfig` query yields every account's signature; this
+ * groups them by the `#<accountId>` suffix.
+ */
+export declare const groupSignaturesByAccount: (settings: AccountSettingItem[]) => Map<string, AccountSignature>;
+/**
+ * Resolve the signature for a single account by reading just its two composite
+ * rows. Used by the account create/update handlers, which act on one account.
+ */
+export declare const loadSignatureForAccount: (accountSetting: IAccountSettingRepository, accountConfigId: string, accountId: string) => Promise<AccountSignature>;
+/**
+ * Idempotent upsert of an account's signature fields. Only writes the parts the
+ * caller supplied — an empty string is a valid stored value (it clears the
+ * displayed signature without removing the row), matching the prior PATCH
+ * semantics where setting `""` stored `""`.
+ */
+export declare const upsertAccountSignature: (accountSetting: IAccountSettingRepository, accountConfigId: string, accountId: string, signature: {
+    plainText?: string;
+    html?: string;
+}) => Promise<void>;

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

@@ -0,0 +1,85 @@
+import { baseSettingName, composeSettingName, SETTING_NAME_SEPARATOR, } from "@remit/data-ports/account-settings";
+const SIGNATURE_NAMES = {
+    plainText: "AccountSignaturePlainText",
+    html: "AccountSignatureHtml",
+};
+const stringValueOf = (item) => {
+    const { value } = item;
+    if (value.kind === "String")
+        return value.value;
+    return undefined;
+};
+const accountIdOf = (name) => {
+    const idx = name.indexOf(SETTING_NAME_SEPARATOR);
+    if (idx === -1)
+        return undefined;
+    return name.slice(idx + SETTING_NAME_SEPARATOR.length) || undefined;
+};
+/**
+ * Build a per-account signature lookup from the whole settings set of one
+ * account configuration. Signatures are stored as composite-named rows
+ * (`AccountSignaturePlainText#<accountId>` / `AccountSignatureHtml#<accountId>`),
+ * so one `listByAccountConfig` query yields every account's signature; this
+ * groups them by the `#<accountId>` suffix.
+ */
+export const groupSignaturesByAccount = (settings) => {
+    const byAccount = new Map();
+    for (const setting of settings) {
+        const accountId = accountIdOf(setting.name);
+        if (!accountId)
+            continue;
+        const base = baseSettingName(setting.name);
+        const text = stringValueOf(setting);
+        if (text === undefined)
+            continue;
+        const current = byAccount.get(accountId) ?? {};
+        if (base === SIGNATURE_NAMES.plainText)
+            current.plainText = text;
+        if (base === SIGNATURE_NAMES.html)
+            current.html = text;
+        byAccount.set(accountId, current);
+    }
+    return byAccount;
+};
+/**
+ * Resolve the signature for a single account by reading just its two composite
+ * rows. Used by the account create/update handlers, which act on one account.
+ */
+export const loadSignatureForAccount = async (accountSetting, accountConfigId, accountId) => {
+    const [plain, html] = await Promise.all([
+        accountSetting.get(accountConfigId, composeSettingName(SIGNATURE_NAMES.plainText, accountId)),
+        accountSetting.get(accountConfigId, composeSettingName(SIGNATURE_NAMES.html, accountId)),
+    ]);
+    const signature = {};
+    const plainText = plain ? stringValueOf(plain) : undefined;
+    const htmlText = html ? stringValueOf(html) : undefined;
+    if (plainText !== undefined)
+        signature.plainText = plainText;
+    if (htmlText !== undefined)
+        signature.html = htmlText;
+    return signature;
+};
+/**
+ * Idempotent upsert of an account's signature fields. Only writes the parts the
+ * caller supplied — an empty string is a valid stored value (it clears the
+ * displayed signature without removing the row), matching the prior PATCH
+ * semantics where setting `""` stored `""`.
+ */
+export const upsertAccountSignature = async (accountSetting, accountConfigId, accountId, signature) => {
+    const writes = [];
+    if (signature.plainText !== undefined) {
+        writes.push(accountSetting.upsert({
+            accountConfigId,
+            name: composeSettingName(SIGNATURE_NAMES.plainText, accountId),
+            value: { kind: "String", value: signature.plainText },
+        }));
+    }
+    if (signature.html !== undefined) {
+        writes.push(accountSetting.upsert({
+            accountConfigId,
+            name: composeSettingName(SIGNATURE_NAMES.html, accountId),
+            value: { kind: "String", value: signature.html },
+        }));
+    }
+    await Promise.all(writes);
+};

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

@@ -0,0 +1,6 @@
+import type { AccountDetailOperationIds, AccountOperationIds, OperationHandler } from "../types.js";
+import { assertNotOAuthCreate, assertPasswordProvided, toAccountResponse } from "./account-guards.js";
+export { assertNotOAuthCreate, assertPasswordProvided, toAccountResponse };
+export declare const triggerAccountSyncSafe: (accountId: string) => Promise<void>;
+export declare const AccountOperations: Record<AccountOperationIds, OperationHandler<AccountOperationIds>>;
+export declare const AccountDetailOperations: Record<AccountDetailOperationIds, OperationHandler<AccountDetailOperationIds>>;

package/dist/src/handlers/account.js

@@ -0,0 +1,350 @@
+import { AccountAuthType, AccountService, ConnectionState, } from "@remit/domain-enums";
+import { logger } from "@remit/logger";
+import { createMailOAuthService, microsoftProviderConfig, RefreshTokenError, } from "@remit/mail-oauth-service";
+import { ownedAccount, resolveConnectionCredentials, testImapConnection, testSmtpConnection, } from "@remit/mailbox-service";
+import { deserializeEncryptedPayload, serializeEncryptedPayload, } from "@remit/secrets-service";
+import { env } from "expect-env";
+import { getAccountConfigIdFromEvent } from "../auth.js";
+import { deleteAccount } from "../service/account-deletion.js";
+import { getClient } from "../service/data-client.js";
+import { fireAndForget } from "../service/fire-and-forget.js";
+import { unwrap } from "../service/refusal.js";
+import { sqsClient } from "../service/sqs.js";
+import { triggerAccountSync } from "../service/trigger-sync.js";
+import { assertNoDuplicateMailbox, assertNotOAuthCreate, assertPasswordProvided, resolveSyncedServices, toAccountResponse, } from "./account-guards.js";
+import { loadAccountOverrides, upsertAccountDisplayName, writeAccountComposeLanguages, writeAccountMuted, } from "./account-overrides.js";
+import { loadSignatureForAccount, upsertAccountSignature, } from "./account-signature.js";
+import { ensureAccountConfig } from "./ensure-account-config.js";
+import { resolveAccountFolderAppointments } from "./folder-role-appointments.js";
+export { assertNotOAuthCreate, assertPasswordProvided, toAccountResponse };
+export const triggerAccountSyncSafe = async (accountId) => {
+    const queueUrl = env.SQS_QUEUE_URL;
+    // Best-effort: account creation must still return 200 even if the sync
+    // enqueue fails. fireAndForget catches and logs every rejection loudly with
+    // the alertable structured fields and never rejects, so a failure here (SQS
+    // unreachable in smoke/e2e, an IAM/SQS misconfig in prod) cannot leak an
+    // unhandled rejection onto an unrelated in-flight request.
+    await fireAndForget(async () => {
+        const { eventId } = await triggerAccountSync({
+            sqsClient,
+            queueUrl,
+            accountId,
+        });
+        // biome-ignore lint/plugin/no-logger-info: sync-triggered-for-new-account is an audit-grade signal
+        logger.info({ accountId, eventId }, "Sync triggered for new account");
+    }, {
+        source: "account_create",
+        message: "Failed to enqueue SYNC_MAILBOXES for new account (best-effort)",
+        ids: { accountId },
+    });
+};
+/**
+ * Test connectivity for an OAuth (Microsoft) account.
+ *
+ * Mints an access token from the stored refresh token via
+ * resolveConnectionCredentials (the single authType branch), then runs the
+ * IMAP — and, when configured, SMTP — connection tests with those credentials.
+ *
+ * A revoked / expired refresh token surfaces as RefreshTokenError; the
+ * reauth-required case is mapped to the distinct `reauth_required` error code
+ * so the UI can route the user into the OAuth re-auth flow.
+ *
+ * MSOAUTH_* env vars are only present in deployed Lambdas; fall back to "".
+ */
+const testOAuthConnection = async (existingAccount, account, secrets) => {
+    const tokenService = createMailOAuthService(microsoftProviderConfig({
+        clientId: process.env.MSOAUTH_CLIENT_ID ?? "",
+        clientSecret: process.env.MSOAUTH_CLIENT_SECRET ?? "",
+        overrides: process.env.MSOAUTH_TOKEN_ENDPOINT
+            ? { tokenEndpoint: process.env.MSOAUTH_TOKEN_ENDPOINT }
+            : undefined,
+    }));
+    let resolution;
+    try {
+        resolution = await resolveConnectionCredentials(existingAccount, {
+            secrets,
+            tokenService,
+            persistRotatedToken: async (id, encryptedHash, updatedAt) => {
+                await account.update(id, {
+                    oauthRefreshTokenHash: encryptedHash,
+                    oauthTokenUpdatedAt: updatedAt,
+                });
+            },
+        });
+    }
+    catch (err) {
+        if (err instanceof RefreshTokenError &&
+            err.error.kind === "reauth-required") {
+            return {
+                imapSuccess: false,
+                imapError: "reauth_required",
+                smtpSuccess: undefined,
+            };
+        }
+        throw err;
+    }
+    if (resolution.status === "missing") {
+        return {
+            imapSuccess: false,
+            imapError: "oauth_not_configured",
+            smtpSuccess: undefined,
+        };
+    }
+    const credentials = resolution.credentials;
+    const result = {
+        imapSuccess: false,
+        smtpSuccess: undefined,
+    };
+    const imapResult = await testImapConnection({
+        host: existingAccount.imapHost,
+        port: existingAccount.imapPort,
+        secure: existingAccount.imapTls,
+        user: existingAccount.username,
+        credentials,
+    });
+    result.imapSuccess = imapResult.success;
+    if (!imapResult.success) {
+        result.imapError = imapResult.error;
+    }
+    // OAuth accounts share the same access token for IMAP and SMTP.
+    if (existingAccount.smtpEnabled) {
+        const smtpResult = await testSmtpConnection({
+            host: existingAccount.smtpHost ?? "",
+            port: existingAccount.smtpPort ?? 587,
+            secure: existingAccount.smtpTls ?? false,
+            user: existingAccount.smtpUsername || existingAccount.username,
+            credentials,
+        });
+        result.smtpSuccess = smtpResult.success;
+        if (!smtpResult.success) {
+            result.smtpError = smtpResult.error;
+        }
+    }
+    return result;
+};
+export const AccountOperations = {
+    AccountOperations_createAccount: async (_context, ...args) => {
+        const event = args[0];
+        const accountConfigId = getAccountConfigIdFromEvent(event);
+        const input = JSON.parse(event.body ?? "{}");
+        // OAuth accounts must be created via the dedicated connect flow
+        assertNotOAuthCreate(input.authType);
+        // Password accounts require a non-empty password
+        assertPasswordProvided(input.authType, input.password);
+        const syncedServices = resolveSyncedServices({ authType: AccountAuthType.Password, grantedScopes: [] }, input.syncedServices ?? [AccountService.Mail]);
+        const { account, accountConfig, accountSetting, mailbox, secrets } = await getClient();
+        await ensureAccountConfig(accountConfig, accountConfigId);
+        // Reject re-onboarding the same mailbox-in-the-same-place. Message
+        // identity is account-scoped (#633), so duplicate onboards are no longer
+        // incidentally deduped — this is the explicit replacement (#635).
+        const existingAccounts = await account.listAllByAccountConfig(accountConfigId);
+        assertNoDuplicateMailbox(existingAccounts, {
+            imapHost: input.imapHost,
+            username: input.username ?? input.email,
+        });
+        // biome-ignore lint/style/noNonNullAssertion: guard above ensures password is set for password-auth accounts
+        const passwordPayload = await secrets.encrypt(input.password);
+        const passwordHash = JSON.stringify(serializeEncryptedPayload(passwordPayload));
+        let smtpPasswordHash;
+        if (input.smtpPassword) {
+            const smtpPayload = await secrets.encrypt(input.smtpPassword);
+            smtpPasswordHash = JSON.stringify(serializeEncryptedPayload(smtpPayload));
+        }
+        const newAccount = await account.create({
+            accountConfigId,
+            email: input.email,
+            username: input.username ?? input.email,
+            authType: AccountAuthType.Password,
+            syncedServices,
+            passwordHash,
+            imapHost: input.imapHost,
+            imapPort: input.imapPort,
+            imapTls: input.imapTls,
+            imapStartTls: input.imapStartTls,
+            // RFC 032 Tier 2: smtpEnabled is the explicit send-capability marker.
+            // Honour an explicit flag from the client; otherwise enable sending when
+            // an SMTP host was supplied (the prior implicit behaviour).
+            smtpEnabled: input.smtpEnabled ?? Boolean(input.smtpHost),
+            smtpHost: input.smtpHost,
+            smtpPort: input.smtpPort,
+            smtpTls: input.smtpTls,
+            smtpStartTls: input.smtpStartTls,
+            smtpUsername: input.smtpUsername,
+            smtpPasswordHash,
+            isActive: true,
+            connectionState: ConnectionState.NotAuthenticated,
+        });
+        // Display name lives in a per-account AccountSetting row (RFC 032), not on
+        // the entity. Persist it when supplied so the response and later reads
+        // surface it unchanged.
+        if (input.displayName !== undefined) {
+            await upsertAccountDisplayName(accountSetting, accountConfigId, newAccount.accountId, input.displayName);
+        }
+        await triggerAccountSyncSafe(newAccount.accountId);
+        const [overrides, folderAppointments] = await Promise.all([
+            loadAccountOverrides(accountSetting, accountConfigId, newAccount.accountId),
+            resolveAccountFolderAppointments({ mailbox, accountSetting }, accountConfigId, newAccount.accountId),
+        ]);
+        return toAccountResponse(newAccount, {}, overrides, folderAppointments);
+    },
+    AccountOperations_testConnection: async (_context, ...args) => {
+        const event = args[0];
+        const accountConfigId = getAccountConfigIdFromEvent(event);
+        const input = JSON.parse(event.body ?? "{}");
+        const { account, secrets } = await getClient();
+        // Resolve password - use provided password or decrypt stored password
+        let imapPassword = input.password;
+        let smtpPassword = input.smtpPassword;
+        if (!imapPassword && input.accountId) {
+            const existingAccount = await account.get(input.accountId);
+            unwrap(ownedAccount(existingAccount, accountConfigId, "read"));
+            const authType = existingAccount.authType ?? "password";
+            if (authType === "oauthMicrosoft") {
+                return testOAuthConnection(existingAccount, account, secrets);
+            }
+            if (existingAccount.passwordHash) {
+                const payload = deserializeEncryptedPayload(JSON.parse(existingAccount.passwordHash));
+                imapPassword = await secrets.decrypt(payload);
+            }
+            // Also get SMTP password if needed and available
+            if (!smtpPassword && existingAccount.smtpPasswordHash) {
+                const smtpPayload = deserializeEncryptedPayload(JSON.parse(existingAccount.smtpPasswordHash));
+                smtpPassword = await secrets.decrypt(smtpPayload);
+            }
+        }
+        if (!imapPassword) {
+            return {
+                imapSuccess: false,
+                imapError: "Password required",
+                smtpSuccess: undefined,
+            };
+        }
+        const result = {
+            imapSuccess: false,
+            smtpSuccess: undefined,
+        };
+        // Test IMAP connection
+        const imapResult = await testImapConnection({
+            host: input.imapHost,
+            port: input.imapPort,
+            secure: input.imapTls,
+            startTls: input.imapStartTls,
+            user: input.username,
+            credentials: { kind: "password", password: imapPassword },
+        });
+        result.imapSuccess = imapResult.success;
+        if (!imapResult.success) {
+            result.imapError = imapResult.error;
+        }
+        // Test SMTP connection if configured
+        if (input.smtpHost) {
+            const smtpResult = await testSmtpConnection({
+                host: input.smtpHost,
+                port: input.smtpPort ?? 587,
+                secure: input.smtpTls ?? false,
+                user: input.smtpUsername ?? input.username,
+                credentials: {
+                    kind: "password",
+                    password: smtpPassword ?? imapPassword,
+                },
+            });
+            result.smtpSuccess = smtpResult.success;
+            if (!smtpResult.success) {
+                result.smtpError = smtpResult.error;
+            }
+        }
+        return result;
+    },
+};
+const encryptedSecret = async (secrets, plaintext) => plaintext
+    ? JSON.stringify(serializeEncryptedPayload(await secrets.encrypt(plaintext)))
+    : undefined;
+export const AccountDetailOperations = {
+    AccountDetailOperations_updateAccount: async (context, ...args) => {
+        const event = args[0];
+        const accountConfigId = getAccountConfigIdFromEvent(event);
+        const { accountId } = context.request.params;
+        const input = JSON.parse(event.body ?? "{}");
+        const { account, accountSetting, mailbox, secrets } = await getClient();
+        const existing = await account.get(accountId);
+        unwrap(ownedAccount(existing, accountConfigId, "act"));
+        const entityFields = {
+            imapHost: input.imapHost,
+            imapPort: input.imapPort,
+            imapTls: input.imapTls,
+            imapStartTls: input.imapStartTls,
+            // RFC 032 Tier 2: keep the explicit send-capability marker in sync. When a
+            // caller changes the SMTP host without passing smtpEnabled, derive it from
+            // host presence so the marker can't drift from the config.
+            smtpEnabled: input.smtpEnabled ??
+                (input.smtpHost === undefined ? undefined : Boolean(input.smtpHost)),
+            smtpHost: input.smtpHost,
+            smtpPort: input.smtpPort,
+            smtpTls: input.smtpTls,
+            smtpStartTls: input.smtpStartTls,
+            smtpUsername: input.smtpUsername,
+            isActive: input.isActive,
+            syncedServices: input.syncedServices === undefined
+                ? undefined
+                : resolveSyncedServices(existing, input.syncedServices),
+        };
+        const updates = {
+            ...entityFields,
+            passwordHash: await encryptedSecret(secrets, input.password),
+            smtpPasswordHash: await encryptedSecret(secrets, input.smtpPassword),
+        };
+        // Display name and the mute flag live in per-account AccountSetting rows
+        // (RFC 032), not on the account entity. Display name upserts when supplied;
+        // the mute flag follows the address-flag null→remove, object→set semantics
+        // (the client populates setAt).
+        if (input.displayName !== undefined) {
+            await upsertAccountDisplayName(accountSetting, accountConfigId, accountId, input.displayName);
+        }
+        if (input.composeLanguages !== undefined) {
+            await writeAccountComposeLanguages(accountSetting, accountConfigId, accountId, input.composeLanguages);
+        }
+        if (Object.hasOwn(input, "muted")) {
+            if (input.muted !== undefined) {
+                await writeAccountMuted(accountSetting, accountConfigId, accountId, input.muted);
+            }
+        }
+        // Signatures live in per-account AccountSetting rows (RFC 032), not on the
+        // account entity. Persist each supplied part as a composite-named setting;
+        // an empty string is a valid stored value (preserves the prior "set ''
+        // stores ''" semantics — it does not delete the row).
+        if (input.signaturePlainText !== undefined ||
+            input.signatureHtml !== undefined) {
+            await upsertAccountSignature(accountSetting, accountConfigId, accountId, {
+                plainText: input.signaturePlainText,
+                html: input.signatureHtml,
+            });
+        }
+        const updated = await account.update(accountId, updates);
+        const [signature, overrides, folderAppointments] = await Promise.all([
+            loadSignatureForAccount(accountSetting, accountConfigId, accountId),
+            loadAccountOverrides(accountSetting, accountConfigId, accountId),
+            resolveAccountFolderAppointments({ mailbox, accountSetting }, accountConfigId, accountId),
+        ]);
+        return toAccountResponse(updated, signature, overrides, folderAppointments);
+    },
+    AccountDetailOperations_deleteAccount: async (context, ...args) => {
+        const event = args[0];
+        const accountConfigId = getAccountConfigIdFromEvent(event);
+        const { accountId } = context.request.params;
+        const { account } = await getClient();
+        const existing = await account.get(accountId);
+        unwrap(ownedAccount(existing, accountConfigId, "act"));
+        const deletedAt = Date.now();
+        await deleteAccount({
+            account,
+            sqsClient,
+            accountFanoutQueueUrl: env.SQS_QUEUE_URL_ACCOUNT_FANOUT,
+            log: logger,
+        }, existing, deletedAt);
+        return {
+            accountId,
+            deletedAt,
+            message: "Account marked for deletion. Data cleanup will complete shortly.",
+        };
+    },
+};

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

@@ -0,0 +1,35 @@
+import type { AddressResponse, UpdateAddressInput } from "@remit/api-openapi-types";
+import type { AddressFlags, AddressItem, FlagsMergePatch } from "@remit/data-ports";
+import type { AddressDetailOperationIds, AddressOperationIds, OperationHandler } from "../types.js";
+export declare const toAddressResponse: (item: AddressItem) => AddressResponse;
+/**
+ * Translate the wire-format `UpdateAddressInput` into a service-level
+ * `FlagsMergePatch`. Only known flag keys are forwarded; unknown keys are
+ * silently dropped (a TypeSpec-only schema means unknown keys are a client
+ * bug, not a security risk).
+ *
+ * `clearFlags` is the removal form for every flag whatever its value type, and
+ * is applied after `flags`, so a key named in both ends up removed. The `null`
+ * alternative on a flag key stays honoured for callers that can express it,
+ * but it is unreachable over OAS 3.0: TypeSpec emits a nullable `$ref` as
+ * `allOf`, and the request validator drops the `nullable` there.
+ */
+export declare const buildFlagsPatch: (input: UpdateAddressInput | undefined) => FlagsMergePatch;
+/**
+ * The category flag a back-apply should be enqueued for, or `undefined` when
+ * this patch asks for none (issue #415).
+ *
+ * A SET fires one; a CLEAR — `null` in the patch, whether it came from
+ * `clearFlags` or from the nullable flag value — never does. Reverting a sender
+ * to auto-classification says nothing about what the classifier would have
+ * answered on mail already filed, and re-deriving that would need every
+ * message's body back; the revert takes effect on the sender's next message,
+ * exactly as the override itself did before this.
+ *
+ * The whole flag, not just its value: `setAt` identifies WHICH set the job was
+ * fired for, and the worker refuses to apply a job whose set is no longer the
+ * one standing on the Address.
+ */
+export declare const backApplyCategoryFlag: (patch: FlagsMergePatch) => NonNullable<AddressFlags["category"]> | undefined;
+export declare const AddressOperations: Record<AddressOperationIds, OperationHandler<AddressOperationIds>>;
+export declare const AddressDetailOperations: Record<AddressDetailOperationIds, OperationHandler<AddressDetailOperationIds>>;

package/dist/src/handlers/address.js

@@ -0,0 +1,141 @@
+import { SendMessageCommand } from "@aws-sdk/client-sqs";
+import { ForbiddenError } from "@remit/data-ports/errors";
+import { AddressFlagKey } from "@remit/domain-enums";
+import { env } from "expect-env";
+import { getAccountConfigIdFromEvent } from "../auth.js";
+import { getClient } from "../service/data-client.js";
+import { sqsClient } from "../service/sqs.js";
+export const toAddressResponse = (item) => ({
+    addressId: item.addressId,
+    accountConfigId: item.accountConfigId,
+    displayName: item.displayName,
+    localPart: item.localPart,
+    domain: item.domain,
+    normalizedEmail: item.normalizedEmail,
+    flags: item.flags ?? {},
+    inboundCount: item.inboundCount ?? 0,
+    outboundCount: item.outboundCount ?? 0,
+    replyCount: item.replyCount ?? 0,
+    lastInboundAt: item.lastInboundAt ?? 0,
+    lastReplyAt: item.lastReplyAt ?? 0,
+    createdAt: item.createdAt,
+    updatedAt: item.updatedAt,
+});
+const FLAG_KEYS = Object.values(AddressFlagKey);
+/**
+ * Translate the wire-format `UpdateAddressInput` into a service-level
+ * `FlagsMergePatch`. Only known flag keys are forwarded; unknown keys are
+ * silently dropped (a TypeSpec-only schema means unknown keys are a client
+ * bug, not a security risk).
+ *
+ * `clearFlags` is the removal form for every flag whatever its value type, and
+ * is applied after `flags`, so a key named in both ends up removed. The `null`
+ * alternative on a flag key stays honoured for callers that can express it,
+ * but it is unreachable over OAS 3.0: TypeSpec emits a nullable `$ref` as
+ * `allOf`, and the request validator drops the `nullable` there.
+ */
+export const buildFlagsPatch = (input) => {
+    if (!input)
+        return {};
+    const patch = {};
+    const flags = input.flags;
+    if (flags) {
+        for (const key of FLAG_KEYS) {
+            if (!(key in flags))
+                continue;
+            const value = flags[key];
+            if (value === null) {
+                patch[key] = null;
+                continue;
+            }
+            if (value === undefined)
+                continue;
+            patch[key] = value;
+        }
+    }
+    for (const key of input.clearFlags ?? []) {
+        if (!FLAG_KEYS.includes(key))
+            continue;
+        patch[key] = null;
+    }
+    return patch;
+};
+/**
+ * The category flag a back-apply should be enqueued for, or `undefined` when
+ * this patch asks for none (issue #415).
+ *
+ * A SET fires one; a CLEAR — `null` in the patch, whether it came from
+ * `clearFlags` or from the nullable flag value — never does. Reverting a sender
+ * to auto-classification says nothing about what the classifier would have
+ * answered on mail already filed, and re-deriving that would need every
+ * message's body back; the revert takes effect on the sender's next message,
+ * exactly as the override itself did before this.
+ *
+ * The whole flag, not just its value: `setAt` identifies WHICH set the job was
+ * fired for, and the worker refuses to apply a job whose set is no longer the
+ * one standing on the Address.
+ */
+export const backApplyCategoryFlag = (patch) => {
+    const flag = patch.category;
+    if (flag === null || flag === undefined)
+        return undefined;
+    return flag;
+};
+export const AddressOperations = {
+    AddressOperations_searchAddresses: async (context, ...args) => {
+        const event = args[0];
+        const accountConfigId = getAccountConfigIdFromEvent(event);
+        const { q, limit } = context.request.query;
+        const client = await getClient();
+        const result = await client.address.listByAccountConfig({
+            accountConfigId,
+            search: q.toLowerCase(),
+            limit: limit ?? 10,
+        });
+        return {
+            items: result.items.map(toAddressResponse),
+            continuationToken: result.continuationToken,
+        };
+    },
+};
+export const AddressDetailOperations = {
+    AddressDetailOperations_updateAddress: async (context, ...args) => {
+        const event = args[0];
+        const accountConfigId = getAccountConfigIdFromEvent(event);
+        const { addressId } = context.request.params;
+        const body = (context.request.requestBody ?? {});
+        const client = await getClient();
+        // Authorize: address must belong to the caller's accountConfig
+        const existing = await client.address.getAddress(accountConfigId, addressId);
+        if (existing.accountConfigId !== accountConfigId) {
+            throw new ForbiddenError(`Address ${addressId} not in account config`);
+        }
+        const patch = buildFlagsPatch(body);
+        if (Object.keys(patch).length === 0) {
+            return toAddressResponse(existing);
+        }
+        const updated = await client.address.mergeFlags(accountConfigId, addressId, patch);
+        const flag = backApplyCategoryFlag(patch);
+        if (flag) {
+            // The flag itself is already durable. A queue failure here costs the
+            // user the retroactive pass and nothing else, so the 500 says so and
+            // names the retry — re-sending the same category enqueues a fresh job.
+            await sqsClient
+                .send(new SendMessageCommand({
+                QueueUrl: env.SQS_QUEUE_URL_ACCOUNT_FANOUT,
+                MessageBody: JSON.stringify({
+                    type: "SenderCategoryBackApply",
+                    accountConfigId,
+                    addressId,
+                    normalizedEmail: updated.normalizedEmail,
+                    category: flag.value,
+                    categorySetAt: flag.setAt,
+                }),
+            }))
+                .catch((cause) => {
+                throw new Error(`The ${flag.value} override is saved and applies to this sender's next message, but the pass over their existing mail could not be started. Setting the same category again retries it.`, { cause });
+            });
+        }
+        return toAddressResponse(updated);
+    },
+};