@remit/mailbox-service 0.0.111 → 0.0.113

package/dist/account-credentials.d.ts

@@ -0,0 +1,83 @@
+/**
+ * account-credentials.ts
+ *
+ * Single place in the codebase that branches on account.authType.
+ * All sync handlers (IMAP, SMTP) must call resolveConnectionCredentials
+ * rather than duplicating credential logic.
+ *
+ * Grep-verifiable constraint: `account.authType` must only appear here.
+ */
+import type { AccountItem } from "@remit/data-ports";
+import { ConnectionState } from "@remit/domain-enums";
+import type { MailOAuthService } from "@remit/mail-oauth-service";
+import { RefreshTokenError } from "@remit/mail-oauth-service";
+import { type SecretsService } from "@remit/secrets-service";
+import type { MailCredentials } from "./types.js";
+/** ConnectionState is a const object (not a TS enum); this is its value type. */
+export type ConnectionStateValue = (typeof ConnectionState)[keyof typeof ConnectionState];
+/**
+ * The fields that say whether an account holds a credential at all. Narrower
+ * than AccountItem so a caller holding only an account summary can ask.
+ */
+export type StoredCredentialFields = Partial<Pick<AccountItem, "authType" | "passwordHash" | "oauthRefreshTokenHash">>;
+/**
+ * No credential of the kind this account's authType needs is stored. An
+ * imported account holds none by design until its owner types one, so this is
+ * a normal state of the world rather than a fault: no retry can change it, and
+ * it is distinct from a credential the mail server rejected.
+ *
+ * `terminalState` is the connectionState that describes the account while it
+ * stays this way, decided here so nothing downstream branches on authType.
+ */
+export interface MissingCredential {
+    readonly status: "missing";
+    readonly terminalState: ConnectionStateValue;
+    readonly reason: string;
+}
+export type CredentialResolution = {
+    readonly status: "resolved";
+    readonly credentials: MailCredentials;
+} | MissingCredential;
+/**
+ * Whether the account holds the credential its authType requires.
+ *
+ * Keyed on the stored credential, never on `connectionState`: PATCH
+ * /accounts/{id} writes a password without clearing `credentials_missing` —
+ * only a successful connect clears it, via markAuthenticated — so a
+ * state-based check would go on skipping an account that can sync perfectly
+ * well.
+ */
+export declare const hasStoredCredential: (account: StoredCredentialFields) => boolean;
+export interface AccountCredentialsDeps {
+    secrets: Pick<SecretsService, "decrypt" | "encrypt">;
+    tokenService: Pick<MailOAuthService, "getAccessToken">;
+    /**
+     * Called when the OAuth provider rotated the refresh token.
+     * Must be awaited BEFORE the credentials are returned so the new token
+     * is persisted before any IMAP command is issued.
+     */
+    persistRotatedToken: (accountId: string, encryptedHash: string, updatedAt: number) => Promise<void>;
+}
+/**
+ * Resolve IMAP credentials for an account.
+ *
+ * - Password accounts: decrypt passwordHash → return password credential.
+ * - OAuth accounts: decrypt oauthRefreshTokenHash → mint access token via
+ *   tokenService.  If the provider rotated the refresh token, persist the
+ *   new token via `deps.persistRotatedToken` BEFORE returning credentials.
+ *
+ * Returns `{ status: "missing" }` when the account stores no credential —
+ * an expected outcome every caller settles terminally, never retries.
+ *
+ * Throws `RefreshTokenError` on OAuth failures; callers should handle:
+ * - `kind === "reauth-required"` → set connectionState to reauth_required, ACK
+ * - `kind === "transient"` → rethrow (SQS retry)
+ * - `kind === "config"` → rethrow (SQS retry / alert)
+ */
+export declare const resolveConnectionCredentials: (account: AccountItem, deps: AccountCredentialsDeps) => Promise<CredentialResolution>;
+/**
+ * Build the encrypted hash string for an OAuth refresh token.
+ * Helper used when first storing an OAuth token (e.g. after OAuth callback).
+ */
+export declare const encryptRefreshToken: (refreshToken: string, secrets: Pick<SecretsService, "encrypt">) => Promise<string>;
+export { ConnectionState, RefreshTokenError };

package/dist/account-credentials.js

@@ -0,0 +1,104 @@
+/**
+ * account-credentials.ts
+ *
+ * Single place in the codebase that branches on account.authType.
+ * All sync handlers (IMAP, SMTP) must call resolveConnectionCredentials
+ * rather than duplicating credential logic.
+ *
+ * Grep-verifiable constraint: `account.authType` must only appear here.
+ */
+import { AccountAuthType, ConnectionState } from "@remit/domain-enums";
+import { RefreshTokenError } from "@remit/mail-oauth-service";
+import { deserializeEncryptedPayload, serializeEncryptedPayload, } from "@remit/secrets-service";
+const readStoredCredential = (account) => {
+    const authType = account.authType ?? AccountAuthType.Password;
+    if (authType === AccountAuthType.OauthMicrosoft) {
+        if (!account.oauthRefreshTokenHash) {
+            return {
+                status: "missing",
+                terminalState: ConnectionState.ReauthRequired,
+                reason: "authType=oauthMicrosoft but no oauthRefreshTokenHash",
+            };
+        }
+        return {
+            status: "oauthMicrosoft",
+            refreshTokenHash: account.oauthRefreshTokenHash,
+        };
+    }
+    if (!account.passwordHash) {
+        return {
+            status: "missing",
+            terminalState: ConnectionState.CredentialsMissing,
+            reason: "authType=password but no passwordHash",
+        };
+    }
+    return { status: "password", passwordHash: account.passwordHash };
+};
+/**
+ * Whether the account holds the credential its authType requires.
+ *
+ * Keyed on the stored credential, never on `connectionState`: PATCH
+ * /accounts/{id} writes a password without clearing `credentials_missing` —
+ * only a successful connect clears it, via markAuthenticated — so a
+ * state-based check would go on skipping an account that can sync perfectly
+ * well.
+ */
+export const hasStoredCredential = (account) => readStoredCredential(account).status !== "missing";
+/**
+ * Resolve IMAP credentials for an account.
+ *
+ * - Password accounts: decrypt passwordHash → return password credential.
+ * - OAuth accounts: decrypt oauthRefreshTokenHash → mint access token via
+ *   tokenService.  If the provider rotated the refresh token, persist the
+ *   new token via `deps.persistRotatedToken` BEFORE returning credentials.
+ *
+ * Returns `{ status: "missing" }` when the account stores no credential —
+ * an expected outcome every caller settles terminally, never retries.
+ *
+ * Throws `RefreshTokenError` on OAuth failures; callers should handle:
+ * - `kind === "reauth-required"` → set connectionState to reauth_required, ACK
+ * - `kind === "transient"` → rethrow (SQS retry)
+ * - `kind === "config"` → rethrow (SQS retry / alert)
+ */
+export const resolveConnectionCredentials = async (account, deps) => {
+    const stored = readStoredCredential(account);
+    if (stored.status === "missing") {
+        return stored;
+    }
+    if (stored.status === "oauthMicrosoft") {
+        return {
+            status: "resolved",
+            credentials: await resolveOauthCredentials(account.accountId, stored.refreshTokenHash, deps),
+        };
+    }
+    return {
+        status: "resolved",
+        credentials: await resolvePasswordCredentials(stored.passwordHash, deps.secrets),
+    };
+};
+const resolvePasswordCredentials = async (passwordHash, secrets) => {
+    const password = await secrets.decrypt(deserializeEncryptedPayload(JSON.parse(passwordHash)));
+    return { kind: "password", password };
+};
+const resolveOauthCredentials = async (accountId, refreshTokenHash, deps) => {
+    const refreshToken = await deps.secrets.decrypt(deserializeEncryptedPayload(JSON.parse(refreshTokenHash)));
+    // getAccessToken throws RefreshTokenError on failure
+    const tokenSet = await deps.tokenService.getAccessToken(accountId, refreshToken);
+    // If the provider rotated the refresh token, persist it BEFORE returning.
+    // This guarantees the new token is stored even if a subsequent error occurs.
+    if (tokenSet.refreshToken) {
+        const encryptedPayload = await deps.secrets.encrypt(tokenSet.refreshToken);
+        const encryptedHash = JSON.stringify(serializeEncryptedPayload(encryptedPayload));
+        await deps.persistRotatedToken(accountId, encryptedHash, Date.now());
+    }
+    return { kind: "accessToken", accessToken: tokenSet.accessToken };
+};
+/**
+ * Build the encrypted hash string for an OAuth refresh token.
+ * Helper used when first storing an OAuth token (e.g. after OAuth callback).
+ */
+export const encryptRefreshToken = async (refreshToken, secrets) => {
+    const payload = await secrets.encrypt(refreshToken);
+    return JSON.stringify(serializeEncryptedPayload(payload));
+};
+export { ConnectionState, RefreshTokenError };

package/dist/attribute-mapper.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Maps IMAP mailbox attributes to entity enum values
+ */
+import { MailboxAttribute, MailboxSpecialUse } from "@remit/domain-enums";
+type MailboxAttributeValue = (typeof MailboxAttribute)[keyof typeof MailboxAttribute];
+type MailboxSpecialUseValue = (typeof MailboxSpecialUse)[keyof typeof MailboxSpecialUse];
+/**
+ * Result of parsing IMAP attributes
+ */
+export interface ParsedAttributes {
+    /** Standard mailbox attributes */
+    attributes: MailboxAttributeValue[];
+    /** Special-use designations */
+    specialUse: MailboxSpecialUseValue[];
+    /** Unknown attributes that couldn't be mapped */
+    unknown: string[];
+}
+/**
+ * Parse IMAP mailbox attributes into our enum types
+ *
+ * IMAP attributes come as strings like "\\Noselect", "\\Drafts", etc.
+ * This function categorizes them into:
+ * - Standard attributes (MailboxAttribute)
+ * - Special-use attributes (MailboxSpecialUse)
+ * - Unknown attributes
+ */
+export declare const parseImapAttributes: (attribs: string[]) => ParsedAttributes;
+/**
+ * Check if an attribute indicates the mailbox cannot be selected
+ */
+export declare const isNoSelect: (attribs: string[]) => boolean;
+/**
+ * Check if an attribute indicates the mailbox has children
+ */
+export declare const hasChildren: (attribs: string[]) => boolean;
+export {};

package/dist/attribute-mapper.js

@@ -0,0 +1,119 @@
+/**
+ * Maps IMAP mailbox attributes to entity enum values
+ */
+import { MailboxAttribute, MailboxSpecialUse } from "@remit/domain-enums";
+/**
+ * Map from IMAP attribute strings to MailboxAttribute enum values.
+ * MailboxAttribute keeps the RFC 9051 backslash prefix; MailboxSpecialUse
+ * below is a canonical bare designation, so only that map strips it.
+ */
+const ATTRIBUTE_MAP = {
+    "\\NonExistent": MailboxAttribute.NonExistent,
+    "\\Noinferiors": MailboxAttribute.NoInferiors,
+    "\\Noselect": MailboxAttribute.NoSelect,
+    "\\HasChildren": MailboxAttribute.HasChildren,
+    "\\HasNoChildren": MailboxAttribute.HasNoChildren,
+    "\\Marked": MailboxAttribute.Marked,
+    "\\Unmarked": MailboxAttribute.Unmarked,
+    "\\Subscribed": MailboxAttribute.Subscribed,
+    "\\Remote": MailboxAttribute.Remote,
+};
+/**
+ * Map from IMAP special-use attribute strings to MailboxSpecialUse enum values
+ */
+const SPECIAL_USE_MAP = {
+    "\\All": MailboxSpecialUse.All,
+    "\\Archive": MailboxSpecialUse.Archive,
+    "\\Drafts": MailboxSpecialUse.Drafts,
+    "\\Flagged": MailboxSpecialUse.Flagged,
+    "\\Junk": MailboxSpecialUse.Junk,
+    "\\Sent": MailboxSpecialUse.Sent,
+    "\\Trash": MailboxSpecialUse.Trash,
+    "\\Important": MailboxSpecialUse.Important,
+};
+/**
+ * Set of all known special-use attributes for quick lookup
+ */
+const SPECIAL_USE_ATTRS = new Set(Object.keys(SPECIAL_USE_MAP));
+/**
+ * Parse IMAP mailbox attributes into our enum types
+ *
+ * IMAP attributes come as strings like "\\Noselect", "\\Drafts", etc.
+ * This function categorizes them into:
+ * - Standard attributes (MailboxAttribute)
+ * - Special-use attributes (MailboxSpecialUse)
+ * - Unknown attributes
+ */
+export const parseImapAttributes = (attribs) => {
+    const result = {
+        attributes: [],
+        specialUse: [],
+        unknown: [],
+    };
+    for (const attr of attribs) {
+        // Normalize attribute (IMAP attributes are case-insensitive)
+        const normalized = normalizeAttribute(attr);
+        if (SPECIAL_USE_ATTRS.has(normalized)) {
+            const specialUse = SPECIAL_USE_MAP[normalized];
+            if (specialUse) {
+                result.specialUse.push(specialUse);
+            }
+        }
+        else if (ATTRIBUTE_MAP[normalized]) {
+            result.attributes.push(ATTRIBUTE_MAP[normalized]);
+        }
+        else {
+            result.unknown.push(attr);
+        }
+    }
+    return result;
+};
+/**
+ * Normalize an IMAP attribute to canonical form
+ *
+ * IMAP attributes are case-insensitive per RFC 9051.
+ * We normalize to the canonical form used in the RFCs.
+ */
+const normalizeAttribute = (attr) => {
+    // Handle common variations
+    const lower = attr.toLowerCase();
+    // Map common case variations to canonical form
+    const canonicalMap = {
+        "\\nonexistent": "\\NonExistent",
+        "\\noinferiors": "\\Noinferiors",
+        "\\noselect": "\\Noselect",
+        "\\haschildren": "\\HasChildren",
+        "\\hasnochildren": "\\HasNoChildren",
+        "\\marked": "\\Marked",
+        "\\unmarked": "\\Unmarked",
+        "\\subscribed": "\\Subscribed",
+        "\\remote": "\\Remote",
+        "\\all": "\\All",
+        "\\archive": "\\Archive",
+        "\\drafts": "\\Drafts",
+        "\\flagged": "\\Flagged",
+        "\\junk": "\\Junk",
+        "\\sent": "\\Sent",
+        "\\trash": "\\Trash",
+        "\\important": "\\Important",
+    };
+    return canonicalMap[lower] ?? attr;
+};
+/**
+ * Check if an attribute indicates the mailbox cannot be selected
+ */
+export const isNoSelect = (attribs) => {
+    return attribs.some((attr) => {
+        const normalized = normalizeAttribute(attr);
+        return normalized === "\\Noselect" || normalized === "\\NonExistent";
+    });
+};
+/**
+ * Check if an attribute indicates the mailbox has children
+ */
+export const hasChildren = (attribs) => {
+    return attribs.some((attr) => {
+        const normalized = normalizeAttribute(attr);
+        return normalized === "\\HasChildren";
+    });
+};

package/dist/body-parse.d.ts

@@ -0,0 +1,28 @@
+import type { QuarantineItem } from "@remit/data-ports";
+import { type ParsedMail } from "mailparser";
+type FailureCode = QuarantineItem["failureCode"];
+/**
+ * The message body could not be parsed.
+ *
+ * This type is the whole reason the sync path can quarantine anything. Before
+ * it, every catch site on the body path saw one undifferentiated `unknown`
+ * covering mailparser, S3, the database and SQS alike, so "the message is built in
+ * a way Remit could not read" was indistinguishable from "S3 returned a 503".
+ * Recording the second as the first advances the cursor past mail that is
+ * perfectly fine and never fetches it again.
+ *
+ * Only {@link parseMessageBody} constructs one, and its try block contains the
+ * parse call and nothing else — so an instance of this type is proof that the
+ * message, not the infrastructure, is what failed. Everything else propagates.
+ */
+export declare class BodyParseError extends Error {
+    readonly failureCode: FailureCode;
+    constructor(cause: unknown);
+}
+/**
+ * Parse a raw RFC822 body, distinguishing a message defect from everything
+ * else. The try block is the parse call alone; nothing that touches storage,
+ * the queue or the database may be moved inside it.
+ */
+export declare const parseMessageBody: (body: Buffer) => Promise<ParsedMail>;
+export {};

package/{src/body-parse.ts → dist/body-parse.js}

@@ -1,9 +1,5 @@
-import type { QuarantineItem } from "@remit/data-ports";
 import { QuarantineFailureCode } from "@remit/domain-enums";
-import { type ParsedMail, simpleParser } from "mailparser";
-
-type FailureCode = QuarantineItem["failureCode"];
-
+import { simpleParser } from "mailparser";
 /**
  * The message body could not be parsed.
  *
@@ -19,16 +15,14 @@ type FailureCode = QuarantineItem["failureCode"];
  * message, not the infrastructure, is what failed. Everything else propagates.
  */
 export class BodyParseError extends Error {
-	readonly failureCode: FailureCode;
-
-	constructor(cause: unknown) {
-		const message = cause instanceof Error ? cause.message : String(cause);
-		super(message, { cause });
-		this.name = "BodyParseError";
-		this.failureCode = classifyBodyParseFailure(message);
-	}
+    failureCode;
+    constructor(cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        super(message, { cause });
+        this.name = "BodyParseError";
+        this.failureCode = classifyBodyParseFailure(message);
+    }
 }
-
 /**
  * mailparser reports its refusals as free text with no stable type, code or
  * class, so the closed failure vocabulary can only name a defect it can
@@ -41,21 +35,19 @@ export class BodyParseError extends Error {
  * title of an issue filed under the user's own account.
  */
 const UNKNOWN_CHARSET = /unknown charset|unsupported charset|invalid encoding/i;
-
-const classifyBodyParseFailure = (message: string): FailureCode =>
-	UNKNOWN_CHARSET.test(message)
-		? QuarantineFailureCode.UnknownCharset
-		: QuarantineFailureCode.UnreadableBody;
-
+const classifyBodyParseFailure = (message) => UNKNOWN_CHARSET.test(message)
+    ? QuarantineFailureCode.UnknownCharset
+    : QuarantineFailureCode.UnreadableBody;
 /**
  * Parse a raw RFC822 body, distinguishing a message defect from everything
  * else. The try block is the parse call alone; nothing that touches storage,
  * the queue or the database may be moved inside it.
  */
-export const parseMessageBody = async (body: Buffer): Promise<ParsedMail> => {
-	try {
-		return await simpleParser(body);
-	} catch (error) {
-		throw new BodyParseError(error);
-	}
+export const parseMessageBody = async (body) => {
+    try {
+        return await simpleParser(body);
+    }
+    catch (error) {
+        throw new BodyParseError(error);
+    }
 };

package/dist/body-part-mapper.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Pair every persisted `BodyPart` row with the decoded bytes mailparser
+ * produced for the same MIME node. Total function: returns one
+ * `BodyPartContentPair` per non-multipart leaf, never undefined, never
+ * throws on well-formed input.
+ *
+ * Source of truth (per issue #395):
+ *   - `partPath`, `contentType`, `contentId`, `dispositionFilename`,
+ *     `sizeOctets` — owned by BODYSTRUCTURE (the `BodyPart` row).
+ *   - Decoded bytes — owned by mailparser (`parsed.text`, `parsed.html`,
+ *     `parsed.attachments[i].content`).
+ *   - `parsed.attachments[i].partId` is also dot-numbered (set at runtime
+ *     in `mail-parser.js:860`; missing from `@types/mailparser`; surfaced
+ *     here via `./types/mailparser-augment.d.ts`). Structural pairing on
+ *     `partId === partPath` is the dominant strategy for non-text leaves.
+ *
+ * Pipeline (per leaf in declaration order; each step consumes one
+ * attachment when it pairs, subsequent steps work on the residual set):
+ *   1. text/plain → first leaf gets `parsed.text` (empty Buffer if
+ *      `sizeOctets === 0`); subsequent text/plain leaves get empty.
+ *   2. text/html → first leaf gets `parsed.html` (empty Buffer if
+ *      `sizeOctets === 0`); subsequent text/html leaves get empty.
+ *   3. Non-text leaves with `sizeOctets === 0` short-circuit to an empty
+ *      Buffer without consuming an attachment — symmetric with the text
+ *      path, so the positional fallback can't hand a zero-sized leaf real
+ *      bytes that belong to another leaf.
+ *   4. Remaining non-text leaves try, in order:
+ *      a. `attachment.partId === bodyPart.partPath`
+ *      b. contentId match (case + angle-insensitive)
+ *      c. dispositionFilename match (case-insensitive)
+ *      d. content-type compatibility class: exact → binary-family
+ *         (any non-text/*) → text-family
+ *      e. positional fallback: next unconsumed attachment in declaration
+ *         order. Logs at `debug` so operators can see "we guessed"
+ *         pairings without spamming higher levels.
+ *   5. Anything still unpaired → zero-byte Buffer + structured `warn` log.
+ *
+ * The mapper assumes well-formed input — malformed MIME is rejected
+ * upstream in `mime-walker.ts`. If a leaf truly has no source bytes
+ * available (e.g. mailparser tolerated a malformed message that
+ * BODYSTRUCTURE disagrees with on leaf count), it gets the empty-Buffer
+ * fallback rather than a throw, so the call site stays simple.
+ */
+import { Buffer } from "node:buffer";
+import type { BodyPartItem } from "@remit/data-ports";
+import { type ParsedMail } from "mailparser";
+export interface BodyPartContentPair {
+    partPath: string;
+    contentType: string;
+    content: Buffer;
+}
+export type MapperInput = Pick<BodyPartItem, "partPath" | "isMultipart" | "mediaType" | "mediaSubtype" | "contentId" | "dispositionFilename" | "disposition"> & {
+    /**
+     * Bytes the BODYSTRUCTURE leaf declares. Optional so hand-built test
+     * inputs don't have to fabricate it — in production every BodyPart row
+     * carries this field. `sizeOctets === 0` is the explicit empty-leaf
+     * signal that text-leaf routing uses to produce a zero-byte Buffer
+     * (see fixture 15-empty-text-part).
+     */
+    sizeOctets?: number;
+};
+export interface MapperLogger {
+    warn(obj: Record<string, unknown>, msg: string): void;
+    debug?(obj: Record<string, unknown>, msg: string): void;
+}
+export interface MapperContext {
+    messageId?: string;
+    logger?: MapperLogger;
+}
+/**
+ * Pair body-part rows with mailparser bytes. Returns one pair per
+ * non-multipart leaf, in the order the leaves appear in `bodyParts`.
+ *
+ * Never throws on well-formed input. Leaves with no source bytes get an
+ * empty Buffer; the call site does not need a try/catch.
+ */
+export declare const mapBodyPartsToContent: (bodyParts: readonly MapperInput[], parsed: ParsedMail, context?: MapperContext) => BodyPartContentPair[];
+/**
+ * The parse every part's bytes are paired against. A message/rfc822 part stays
+ * one leaf holding the raw forwarded message whatever its disposition, so the
+ * forwarded message's own parts come only from parsing it in turn.
+ */
+export declare const parsePartSource: (source: Buffer) => Promise<ParsedMail>;
+/**
+ * `mapBodyPartsToContent`, extended to forwarded messages. mailparser hands a
+ * message/rfc822 part over as one attachment holding the raw forwarded
+ * message, so the parts inside it have no bytes in `parsed`. Each forwarded
+ * message is parsed on its own and its parts are paired against that parse,
+ * with their paths rebased so `<messagePath>.0` is the forwarded message's
+ * root — the shape `walkMimeStructure` stores.
+ */
+export declare const mapMessagePartsToContent: (bodyParts: readonly MapperInput[], parsed: ParsedMail, context?: MapperContext) => Promise<BodyPartContentPair[]>;