@remit/backend 0.0.142 → 0.0.144

package/dist/src/derive/pendingMoveCounts.js

@@ -0,0 +1,53 @@
+/**
+ * Adjusts `messageCount` and `unseenCount` on a set of mailboxes to reflect
+ * every pending placement move (issue #1271) and pending `\Seen` flag push
+ * (issue #1273): a prediction applied at READ TIME, never written back to
+ * storage (epic #1281 invariant 4). Stored counts are refreshed only by
+ * mailbox-sync re-reading IMAP.
+ *
+ * - A pending move has already relocated the message locally
+ *   (`ThreadMessage.mailboxId`), so its destination folder's live listing
+ *   outnumbers the stored `messageCount` by one until the marker confirms
+ *   and a resync catches up.
+ * - A pending `\Seen` push has already flipped `ThreadMessage.isRead`
+ *   locally: `add` (marked read) means the stored `unseenCount` is one HIGH
+ *   until the push confirms; `remove` (marked unread) means it is one LOW.
+ *   Only `\Seen` markers carry read/unread state — a pending `\Flagged`
+ *   (star) marker never adjusts either count, same reasoning the placement
+ *   move prediction already applies to its own scope.
+ *
+ * Pure: takes the mailboxes and the pending markers as plain input, returns a
+ * new array. Never mutates its arguments.
+ */
+export const applyPendingMoveCountPrediction = (mailboxes, pendingMoves, pendingUnseenFlagPushes = []) => {
+    if (pendingMoves.length === 0 && pendingUnseenFlagPushes.length === 0) {
+        return [...mailboxes];
+    }
+    const messageCountDelta = new Map();
+    for (const move of pendingMoves) {
+        if (move.sourceMailboxId === move.destinationMailboxId)
+            continue;
+        messageCountDelta.set(move.sourceMailboxId, (messageCountDelta.get(move.sourceMailboxId) ?? 0) - 1);
+        messageCountDelta.set(move.destinationMailboxId, (messageCountDelta.get(move.destinationMailboxId) ?? 0) + 1);
+    }
+    const unseenCountDelta = new Map();
+    for (const push of pendingUnseenFlagPushes) {
+        const adjustment = push.operation === "add" ? -1 : 1;
+        unseenCountDelta.set(push.mailboxId, (unseenCountDelta.get(push.mailboxId) ?? 0) + adjustment);
+    }
+    return mailboxes.map((mailbox) => {
+        const messageAdjustment = messageCountDelta.get(mailbox.mailboxId);
+        const unseenAdjustment = unseenCountDelta.get(mailbox.mailboxId);
+        if (!messageAdjustment && !unseenAdjustment)
+            return mailbox;
+        return {
+            ...mailbox,
+            messageCount: messageAdjustment
+                ? Math.max(0, mailbox.messageCount + messageAdjustment)
+                : mailbox.messageCount,
+            unseenCount: unseenAdjustment
+                ? Math.max(0, mailbox.unseenCount + unseenAdjustment)
+                : mailbox.unseenCount,
+        };
+    });
+};

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,14 @@
+import type { AccountService as AccountServiceName } from "@remit/api-openapi-types";
+import type { MicrosoftOAuthOperationIds, OperationHandler } 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(): string;
+export declare const MicrosoftOAuthOperations: Record<MicrosoftOAuthOperationIds, OperationHandler<MicrosoftOAuthOperationIds>>;