@remit/mailbox-service 0.0.111 → 0.0.113

package/dist/folder-operations.d.ts

@@ -0,0 +1,39 @@
+import type { AccountItem, IAccountRepository, IMailboxRepository, MailboxItem } from "@remit/data-ports";
+import type { MailboxQueueService } from "./mailbox-queue.js";
+import { type Refusable } from "./refusal.js";
+export interface FolderPathDeps {
+    account: {
+        get(accountId: string): Promise<AccountItem>;
+    };
+    mailbox: {
+        get(accountId: string, mailboxId: string): Promise<MailboxItem>;
+        listAllByAccount(accountId: string): Promise<MailboxItem[]>;
+    };
+    mailboxQueue: Pick<MailboxQueueService, "renameMailbox" | "dismissMailboxIntent">;
+}
+export interface CreateFolderDeps {
+    account: Pick<IAccountRepository, "get">;
+    mailbox: Pick<IMailboxRepository, "findByPath">;
+    mailboxQueue: Pick<MailboxQueueService, "createMailbox">;
+}
+export interface NewFolder {
+    accountId: string;
+    namespaceType: MailboxItem["namespaceType"];
+    fullPath: string;
+}
+export interface FolderPathOutcome {
+    outcome: "Recorded" | "AlreadyRecorded";
+    mailbox: MailboxItem;
+}
+export interface NewFolderOutcome {
+    outcome: "Created" | "Existing";
+    mailbox: MailboxItem;
+}
+export interface FolderPathChange {
+    accountId: string;
+    mailboxId: string;
+    fullPath: string;
+}
+export declare const ownedFolder: (deps: Pick<FolderPathDeps, "account" | "mailbox">, accountConfigId: string, accountId: string, mailboxId: string) => Promise<Refusable<MailboxItem>>;
+export declare const changeFolderPath: (deps: FolderPathDeps, accountConfigId: string, change: FolderPathChange) => Promise<Refusable<FolderPathOutcome>>;
+export declare const createFolder: (deps: CreateFolderDeps, accountConfigId: string, folder: NewFolder) => Promise<Refusable<NewFolderOutcome>>;

package/dist/folder-operations.js

@@ -0,0 +1,112 @@
+import { isReservedFolderName } from "@remit/data-ports/folder-role";
+import { mailboxLeafName } from "@remit/data-ports/mailbox-name";
+import { MailboxSyncStatus } from "@remit/domain-enums";
+import { carriesIntent, folderInFlight } from "./mailbox-intent.js";
+import { folderInAccount, ownedAccount } from "./ownership.js";
+import { accept, invalid, refuse } from "./refusal.js";
+const renameTargetRefusal = async (deps, accountId, before, target) => {
+    // Renaming INBOX leaves an empty INBOX behind, and INBOX is the one name
+    // RFC 3501 reserves.
+    if (before.fullPath.toUpperCase() === "INBOX") {
+        return invalid("The inbox can't be renamed.");
+    }
+    if (target.trim().length === 0) {
+        return invalid("A folder needs a name.");
+    }
+    if (target.toUpperCase() === "INBOX") {
+        return invalid("“INBOX” is reserved for the inbox.");
+    }
+    // The mailbox sweep reads an unflagged folder under a role's conventional
+    // name as a duplicate and reaps it, with its mail, once another folder holds
+    // the flag.
+    const leaf = mailboxLeafName({
+        fullPath: target,
+        hierarchyDelimiter: before.hierarchyDelimiter,
+    });
+    if (isReservedFolderName(leaf)) {
+        return invalid(`“${leaf}” is reserved for a system folder. Pick another name.`);
+    }
+    // A path a pending rename is heading for is as taken as one a folder sits
+    // at. A failed rename keeps its target only so the client can offer a
+    // retry; nothing is coming for it, so it claims nothing.
+    const folders = await deps.mailbox.listAllByAccount(accountId);
+    for (const folder of folders) {
+        if (folder.mailboxId === before.mailboxId)
+            continue;
+        if (folder.fullPath === target) {
+            return invalid(`A folder named “${target}” is already there.`);
+        }
+        if (folder.syncStatus === MailboxSyncStatus.pending &&
+            folder.pendingPath === target) {
+            return invalid(`“${folder.fullPath}” is already being renamed to “${target}”.`);
+        }
+    }
+    return accept(target);
+};
+// A fullPath equal to the confirmed one is not a rename: it dismisses a failed
+// intent, the one route out of `failed` that enqueues nothing. The row keeps
+// the path the server holds until the rename settles.
+export const ownedFolder = async (deps, accountConfigId, accountId, mailboxId) => {
+    const owned = ownedAccount(await deps.account.get(accountId), accountConfigId, "act");
+    if (!owned.ok)
+        return owned;
+    return folderInAccount(await deps.mailbox.get(accountId, mailboxId), accountId, "act");
+};
+export const changeFolderPath = async (deps, accountConfigId, change) => {
+    const { accountId, mailboxId, fullPath } = change;
+    const folder = await ownedFolder(deps, accountConfigId, accountId, mailboxId);
+    if (!folder.ok)
+        return folder;
+    const before = folder.value;
+    if (fullPath === before.fullPath) {
+        return accept({
+            outcome: "Recorded",
+            mailbox: await deps.mailboxQueue.dismissMailboxIntent(mailboxId, accountId),
+        });
+    }
+    const target = await renameTargetRefusal(deps, accountId, before, fullPath);
+    if (!target.ok)
+        return target;
+    if (!carriesIntent(before)) {
+        if (before.syncStatus === MailboxSyncStatus.pending &&
+            before.pendingPath === fullPath) {
+            return accept({ outcome: "AlreadyRecorded", mailbox: before });
+        }
+        return refuse({ kind: "Conflict", message: folderInFlight(before) });
+    }
+    return accept({
+        outcome: "Recorded",
+        mailbox: await deps.mailboxQueue.renameMailbox(mailboxId, fullPath, accountId),
+    });
+};
+export const createFolder = async (deps, accountConfigId, folder) => {
+    const { accountId, namespaceType, fullPath } = folder;
+    const owned = ownedAccount(await deps.account.get(accountId), accountConfigId, "act");
+    if (!owned.ok)
+        return owned;
+    const created = await deps.mailboxQueue.createMailbox({
+        accountId,
+        namespaceType,
+        namespacePrefix: "",
+        hierarchyDelimiter: "/",
+        fullPath,
+        uidValidity: 0,
+        uidNext: 1,
+        highestModseq: "0",
+        messageCount: 0,
+        unseenCount: 0,
+        deletedCount: 0,
+        totalSize: 0,
+        lastSyncUid: 0,
+        highWaterMarkUid: 0,
+        lastMessageSyncAt: 0,
+    }, accountId, true);
+    if (created.outcome === "PathTaken") {
+        const existing = await deps.mailbox.findByPath(accountId, fullPath);
+        if (!existing) {
+            throw new Error(`No folder at "${fullPath}" after its create reported the path taken`);
+        }
+        return accept({ outcome: "Existing", mailbox: existing });
+    }
+    return accept({ outcome: "Created", mailbox: created.mailbox });
+};

package/dist/folder-placement.d.ts

@@ -0,0 +1,13 @@
+import type { IMailboxSpecialUseRepository } from "@remit/data-ports";
+import type { FolderPlacement } from "./heuristics/classifyPlacement.js";
+export type FolderPlacementLookup = Pick<IMailboxSpecialUseRepository, "findJunkMailbox" | "findInboxMailbox">;
+type RoleMailbox = Awaited<ReturnType<IMailboxSpecialUseRepository["findJunkMailbox"]>>;
+export interface FolderRoleMailboxes {
+    junkMailbox: RoleMailbox;
+    inboxMailbox: RoleMailbox;
+}
+export declare const resolveFolderRoleMailboxes: (lookup: FolderPlacementLookup, accountId: string) => Promise<FolderRoleMailboxes>;
+export declare const placementOf: (mailboxId: string, { junkMailbox, inboxMailbox }: FolderRoleMailboxes) => FolderPlacement;
+export declare const resolveFolderPlacement: (lookup: FolderPlacementLookup, accountId: string, mailboxId: string) => Promise<FolderPlacement>;
+export declare const resolveAccountFolderPlacements: (lookup: FolderPlacementLookup, accountIds: readonly string[]) => Promise<ReadonlyMap<string, FolderPlacement>>;
+export {};

package/dist/folder-placement.js

@@ -0,0 +1,23 @@
+export const resolveFolderRoleMailboxes = async (lookup, accountId) => ({
+    junkMailbox: await lookup.findJunkMailbox(accountId),
+    inboxMailbox: await lookup.findInboxMailbox(accountId),
+});
+export const placementOf = (mailboxId, { junkMailbox, inboxMailbox }) => {
+    if (junkMailbox?.mailboxId === mailboxId)
+        return "junk";
+    if (inboxMailbox?.mailboxId === mailboxId)
+        return "inbox";
+    return "other";
+};
+export const resolveFolderPlacement = async (lookup, accountId, mailboxId) => placementOf(mailboxId, await resolveFolderRoleMailboxes(lookup, accountId));
+export const resolveAccountFolderPlacements = async (lookup, accountIds) => {
+    const placements = new Map();
+    for (const accountId of accountIds) {
+        const { junkMailbox, inboxMailbox } = await resolveFolderRoleMailboxes(lookup, accountId);
+        if (inboxMailbox)
+            placements.set(inboxMailbox.mailboxId, "inbox");
+        if (junkMailbox)
+            placements.set(junkMailbox.mailboxId, "junk");
+    }
+    return placements;
+};

package/dist/heuristics/authenticationResults.d.ts

@@ -0,0 +1,10 @@
+export interface AuthenticationResult {
+    method: string;
+    result: string;
+    properties: ReadonlyMap<string, string>;
+}
+export interface AuthenticationResults {
+    authservId: string;
+    results: AuthenticationResult[];
+}
+export declare const parseAuthenticationResults: (value: string) => AuthenticationResults | null;

package/dist/heuristics/authenticationResults.js

@@ -0,0 +1,187 @@
+const DELIMITERS = new Set([";", "=", "(", ")", '"']);
+const KEYWORD = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+const METHOD = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\/[0-9]+)?$/;
+const PROPERTY_KEY = /^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$/;
+const VERSION = /^[0-9]+$/;
+const isWhitespace = (c) => c === " " || c === "\t" || c === "\r" || c === "\n";
+const skipComment = (input, start) => {
+    let depth = 0;
+    for (let i = start; i < input.length; i++) {
+        const c = input[i];
+        if (c === "\\") {
+            i++;
+            continue;
+        }
+        if (c === "(")
+            depth++;
+        if (c === ")")
+            depth--;
+        if (depth === 0)
+            return i + 1;
+    }
+    return null;
+};
+const readQuoted = (input, start) => {
+    let text = "";
+    for (let i = start + 1; i < input.length; i++) {
+        const c = input[i];
+        if (c === "\\") {
+            if (i + 1 >= input.length)
+                return null;
+            text += input[i + 1];
+            i++;
+            continue;
+        }
+        if (c === '"')
+            return { text, end: i + 1 };
+        text += c;
+    }
+    return null;
+};
+const tokenize = (input) => {
+    const tokens = [];
+    let i = 0;
+    while (i < input.length) {
+        const c = input[i];
+        if (isWhitespace(c)) {
+            i++;
+            continue;
+        }
+        if (c === "(") {
+            const end = skipComment(input, i);
+            if (end === null)
+                return null;
+            i = end;
+            continue;
+        }
+        if (c === ")")
+            return null;
+        if (c === ";") {
+            tokens.push({ kind: "semicolon" });
+            i++;
+            continue;
+        }
+        if (c === "=") {
+            tokens.push({ kind: "equals" });
+            i++;
+            continue;
+        }
+        if (c === '"') {
+            const quoted = readQuoted(input, i);
+            if (!quoted)
+                return null;
+            tokens.push({ kind: "quoted", text: quoted.text });
+            i = quoted.end;
+            continue;
+        }
+        let end = i;
+        while (end < input.length &&
+            !isWhitespace(input[end]) &&
+            !DELIMITERS.has(input[end])) {
+            end++;
+        }
+        tokens.push({ kind: "word", text: input.slice(i, end) });
+        i = end;
+    }
+    return tokens;
+};
+const splitStatements = (tokens) => {
+    const statements = [[]];
+    for (const token of tokens) {
+        if (token.kind === "semicolon") {
+            statements.push([]);
+            continue;
+        }
+        statements[statements.length - 1].push(token);
+    }
+    return statements;
+};
+const isValue = (token) => token !== undefined && (token.kind === "word" || token.kind === "quoted");
+const joinsKey = (previous, next) => previous.endsWith(".") ||
+    previous.endsWith("/") ||
+    next.startsWith(".") ||
+    next.startsWith("/");
+const readPairs = (statement) => {
+    const pairs = [];
+    let key = [];
+    for (let i = 0; i < statement.length; i++) {
+        const token = statement[i];
+        if (token.kind === "equals") {
+            const value = statement[i + 1];
+            if (key.length === 0 || !isValue(value))
+                return null;
+            pairs.push([key.join("").toLowerCase(), value]);
+            key = [];
+            i++;
+            continue;
+        }
+        if (token.kind !== "word")
+            return null;
+        const previous = key[key.length - 1];
+        if (previous !== undefined && !joinsKey(previous, token.text))
+            return null;
+        key.push(token.text);
+    }
+    if (key.length > 0)
+        return null;
+    return pairs;
+};
+const parseResult = (statement) => {
+    const pairs = readPairs(statement);
+    if (!pairs || pairs.length === 0)
+        return null;
+    const [[methodKey, resultToken], ...rest] = pairs;
+    if (!METHOD.test(methodKey))
+        return null;
+    if (resultToken.kind !== "word")
+        return null;
+    const result = resultToken.text.toLowerCase();
+    if (!KEYWORD.test(result))
+        return null;
+    const properties = new Map();
+    for (const [key, value] of rest) {
+        if (!PROPERTY_KEY.test(key))
+            return null;
+        if (!properties.has(key))
+            properties.set(key, value.text);
+    }
+    return { method: methodKey.split("/")[0], result, properties };
+};
+const parseAuthservId = (statement) => {
+    const [id, version, ...extra] = statement;
+    if (!isValue(id) || extra.length > 0)
+        return null;
+    if (version !== undefined) {
+        if (version.kind !== "word" || !VERSION.test(version.text))
+            return null;
+    }
+    const authservId = id.text.toLowerCase();
+    return authservId.length > 0 ? authservId : null;
+};
+const isNoResult = (statement) => statement.length === 1 &&
+    statement[0].kind === "word" &&
+    statement[0].text.toLowerCase() === "none";
+export const parseAuthenticationResults = (value) => {
+    const tokens = tokenize(value);
+    if (!tokens)
+        return null;
+    const [head, ...tail] = splitStatements(tokens);
+    const headIsResult = head.some((token) => token.kind === "equals");
+    const authservId = headIsResult ? "" : parseAuthservId(head);
+    if (authservId === null)
+        return null;
+    const statements = (headIsResult ? [head, ...tail] : tail).filter((statement) => statement.length > 0);
+    if (statements.length === 0)
+        return null;
+    if (statements.length === 1 && isNoResult(statements[0])) {
+        return { authservId, results: [] };
+    }
+    const results = [];
+    for (const statement of statements) {
+        const result = parseResult(statement);
+        if (!result)
+            return null;
+        results.push(result);
+    }
+    return { authservId, results };
+};

package/dist/heuristics/classifyByHeaders.d.ts

@@ -0,0 +1,82 @@
+import { AuthResultVerdict, MessageCategory } from "@remit/domain-enums";
+import type { ParsedMail } from "mailparser";
+type Category = (typeof MessageCategory)[keyof typeof MessageCategory];
+type AuthVerdictValue = (typeof AuthResultVerdict)[keyof typeof AuthResultVerdict];
+export interface MessageAuthResult {
+    dmarc?: AuthVerdictValue;
+    spf?: AuthVerdictValue;
+    dkim?: AuthVerdictValue;
+}
+export interface MessageProviderSpam {
+    classified: boolean;
+    score?: string;
+    source?: string;
+}
+/**
+ * Structured sender-authenticity signal extracted from DKIM headers.
+ * Persisted alongside `category` during body-sync so the intelligence
+ * sidebar (#425) can render phishing verdicts without re-parsing.
+ *
+ * Present only when a DKIM-Signature header exists; absent otherwise
+ * (absence means "no signal" — no comparison was possible).
+ */
+export interface MessageAuthenticity {
+    /** Domain of the From header address */
+    fromDomain: string;
+    /** DKIM signing domain (d=) that was compared, when a signature is present */
+    dkimDomain?: string;
+    /** True when none of the DKIM signing domains aligns with the From domain */
+    dkimMismatch: boolean;
+}
+/**
+ * Header-only classification. Pure function. First match wins. Falls through
+ * to `personal` so misclassification stays in the safest bucket.
+ *
+ * Rules are ordered most-specific-signal first. Two properties drive the
+ * order, and both were violated by the original table (issue #45):
+ *
+ * - A signal that identifies WHO sent the mail (calendar part, allow-listed
+ *   domain) outranks a signal that only says the mail was sent in bulk.
+ * - `Precedence` and `Auto-Submitted` say "a machine sent this", which is true
+ *   of nearly every newsletter, marketing blast, and platform notification.
+ *   Ranking them first collapsed `newsletter`, `marketing`, `social` and
+ *   `transactional` into `automated`, leaving those buckets empty.
+ *
+ * 1. `Content-Type: text/calendar` part anywhere → `transactional`
+ * 2. From-domain in TRANSACTIONAL_DOMAINS → `transactional`
+ * 3. From-domain in SOCIAL_DOMAINS → `social`
+ * 4. `List-Unsubscribe` AND `List-Id` → `newsletter`
+ * 5. `List-Unsubscribe` only → `marketing`
+ * 6. `Auto-Submitted: auto-generated|auto-replied` → `automated`
+ * 7. `Precedence: bulk|list|junk` → `automated`
+ * 8. Machine sender (no-reply local-part, `Feedback-ID`,
+ *    `X-Auto-Response-Suppress`) → `automated`
+ * 9. DKIM `d=` differs from From domain → `automated`
+ * 10. fallback → `personal`
+ */
+export declare const classifyByHeaders: (parsed: ParsedMail) => Category;
+/**
+ * Extract the structured authenticity signal from parsed headers.
+ *
+ * Returns a `MessageAuthenticity` when at least one DKIM-Signature header
+ * is present (a comparison was possible). Returns `null` when there are no
+ * DKIM-Signature headers so callers can omit the field entirely — absence
+ * means "no signal", not "mismatch: false".
+ *
+ * The alignment rule exactly mirrors the category heuristic (rule 7) so the
+ * structured `dkimMismatch` boolean and the `automated` category can never
+ * disagree.
+ */
+export declare const extractAuthenticity: (parsed: ParsedMail) => MessageAuthenticity | null;
+export declare const extractAuthResult: (parsed: ParsedMail) => MessageAuthResult | null;
+/**
+ * Extract provider spam-filter signal from X-SpamExperts-Class, X-Spam-Status,
+ * or X-HalOne-Spam-Probability headers. Returns null when none are present.
+ */
+export declare const extractProviderSpam: (parsed: ParsedMail) => MessageProviderSpam | null;
+/**
+ * Returns true when a List-Unsubscribe header is present, indicating a
+ * bulk/mailing-list sender.
+ */
+export declare const extractHasListUnsubscribe: (parsed: ParsedMail) => boolean;
+export {};