@remit/backend 0.0.143 → 0.0.145

package/dist/src/handlers/system-update.js

@@ -0,0 +1,159 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { ConflictError, HTTPError } from "@remit/data-ports/errors";
+import { defaultErrorCode } from "../error.js";
+class TargetVersionMismatchError extends HTTPError {
+    name = "TargetVersionMismatchError";
+    statusCode = 422;
+}
+/**
+ * The running version is a fact the updater owns: it reads the tag from `.env`
+ * and writes it into `state.json`, which is the only honest source across an
+ * update that rewrites that tag underneath a long-lived backend process. When no
+ * state file exists yet the backend has nothing authoritative to report, so it
+ * reports the version as unknown rather than fabricating one from its own
+ * process environment — a value captured at container start that drifts from the
+ * real running tag the moment an update lands. The first updater check writes a
+ * real `currentVersion` within seconds of the stack coming up.
+ */
+const UNKNOWN_VERSION = "unknown";
+/**
+ * A refusal in the shape `formatResponse` unwraps: the status, and the body as
+ * an object it serializes. Handing it an already-serialized `body` string
+ * instead publishes the whole envelope — `{"statusCode":…,"headers":…}` with
+ * the real body escaped inside it — which is not an `ApiError` at all.
+ */
+const refuse = (statusCode, message) => ({
+    statusCode,
+    body: { code: defaultErrorCode(statusCode), message },
+});
+const notFound = () => refuse(404, "Not found");
+/**
+ * The self-update seam is off unless a manifest URL is configured (RFC 037 D8),
+ * which the hosted deployment leaves unset. Both endpoints answer 404 in that
+ * case. Where it is on, any authenticated caller may use it — the account list
+ * is the trust boundary of a self-hosted instance.
+ */
+const guardManifestConfigured = (config) => config.selfUpdate === "Enabled" ? null : notFound();
+/**
+ * Read `state.json` off the control volume. A missing file is an instance that
+ * has never checked or updated (RFC 037 D8), not an error, so it reads as
+ * `null`; the caller renders the disabled/empty resource. Any other read or
+ * parse failure propagates.
+ */
+const readState = (controlDir) => {
+    let raw;
+    try {
+        raw = readFileSync(join(controlDir, "state.json"), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    return JSON.parse(raw);
+};
+const emptyResource = () => ({
+    currentVersion: UNKNOWN_VERSION,
+    check: { status: "disabled" },
+    run: null,
+});
+const isRunInFlight = (run) => run != null && run.outcome === null;
+/**
+ * The version the caller may install is the one the last check reported. It
+ * exists only on a successful check; a disabled or failed check offers nothing
+ * to match, so any target is a mismatch.
+ */
+const checkedVersion = (state) => state?.check.status === "ok" ? state.check.latestVersion : undefined;
+/**
+ * Write `request.json` atomically with exactly the four fields the seam accepts
+ * (#133). The updater resolves the registry and every image reference from the
+ * manifest it fetches itself; a request naming any of those is rejected whole,
+ * so the backend never writes one. The temp file sits in the same directory as
+ * the target for the rename to be atomic on one filesystem.
+ */
+const writeRequest = (dir, request) => {
+    const tmp = join(dir, `.request.json.${request.runId}.tmp`);
+    writeFileSync(tmp, JSON.stringify(request), { mode: 0o644 });
+    renameSync(tmp, join(dir, "request.json"));
+};
+/**
+ * Record a check request on the control seam (#599). The updater consumes it on
+ * its watch loop and runs a manifest check immediately, so a press of check in
+ * the panel — not just the updater's own cadence — moves `lastCheckedAt`. Like
+ * request.json it is written atomically and carries no authority: its presence
+ * is the whole message, so it is empty.
+ */
+const writeCheckRequest = (dir) => {
+    const tmp = join(dir, `.check-request.json.tmp`);
+    writeFileSync(tmp, JSON.stringify({}), { mode: 0o644 });
+    renameSync(tmp, join(dir, "check-request.json"));
+};
+/**
+ * The resource returned by the POST. The updater has not yet written the
+ * authoritative run — it polls the seam — so this bootstraps the run block with
+ * the id just requested and the first phase, giving the client a `runId` to poll
+ * for (RFC 037 D9). The updater's own `state.json` supersedes it on the next
+ * read.
+ */
+const requestedResource = (state, runId, targetVersion, requestedAt) => {
+    const from = state?.currentVersion ?? UNKNOWN_VERSION;
+    return {
+        currentVersion: from,
+        check: state?.check ?? { status: "disabled" },
+        run: {
+            runId,
+            fromVersion: from,
+            targetVersion,
+            phase: "checking",
+            outcome: null,
+            startedAt: requestedAt,
+            updatedAt: requestedAt,
+            message: "The update has been requested.",
+            logCommand: "remit logs updater",
+        },
+    };
+};
+export const SystemOperations = {
+    SystemOperations_getSystemUpdate: async (context, ctx) => {
+        const offSurface = guardManifestConfigured(ctx.config);
+        if (offSurface)
+            return offSurface;
+        // A refresh asks for a fresh answer, and only the updater can fetch one, so
+        // the request goes on the control seam for its watch loop to pick up (#599).
+        // The answer is the stored state as it stands, `lastCheckedAt` included: the
+        // caller holds its own press and watches that timestamp move, so the
+        // response never has to claim a verdict the updater has not reached.
+        const { refresh } = context.request.query;
+        if (refresh === true)
+            writeCheckRequest(ctx.config.updateControlDir);
+        return readState(ctx.config.updateControlDir) ?? emptyResource();
+    },
+    SystemOperations_applySystemUpdate: async (context, ctx) => {
+        const offSurface = guardManifestConfigured(ctx.config);
+        if (offSurface)
+            return offSurface;
+        const sub = ctx.identity.sub;
+        const { targetVersion } = context.request.requestBody;
+        const state = readState(ctx.config.updateControlDir);
+        if (isRunInFlight(state?.run)) {
+            throw new ConflictError("An update is already in progress.");
+        }
+        if (targetVersion !== checkedVersion(state)) {
+            throw new TargetVersionMismatchError("targetVersion does not match the latest checked release.");
+        }
+        const runId = randomUUID();
+        const requestedAt = new Date().toISOString();
+        writeRequest(ctx.config.updateControlDir, {
+            runId,
+            targetVersion,
+            requestedAt,
+            requestedBy: sub,
+        });
+        return {
+            statusCode: 202,
+            body: requestedResource(state, runId, targetVersion, requestedAt),
+        };
+    },
+};

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

@@ -0,0 +1,148 @@
+import type { MessageCategory, SenderTrust, ThreadSearchResponse } from "@remit/api-openapi-types";
+import type { ResultList, ThreadMessageItem } from "@remit/data-ports";
+import { type EnrichClient } from "../derive/enrichThreadRows.js";
+import type { OperationHandler, ThreadDetailOperationIds, ThreadOperationIds } from "../types.js";
+/**
+ * Build the `listByMailbox` options for the thread list handler.
+ *
+ * Exposed as a pure helper so the `excludeDeleted: true` default — which is
+ * the entire point of the #212 fix on the handler side — is testable without
+ * standing up DynamoDB. The defaults must stay opt-out from the user (a
+ * future Trash / All-Mail view can flip the flag) and opt-in at the
+ * service layer.
+ */
+export declare const buildListThreadsOptions: (query: {
+    continuationToken?: string;
+    order?: "asc" | "desc";
+}) => {
+    order: "asc" | "desc";
+    continuationToken: string | undefined;
+    limit: number;
+    attributes: ("mailboxId" | "messageId" | "referenceOrder" | "createdAt" | "updatedAt" | "accountConfigId" | "uid" | "category" | "subject" | "internalDate" | "inReplyTo" | "fromName" | "threadMessageId" | "star" | "threadId" | "sentDate" | "isRead" | "hasAttachment" | "hasStars" | "isDeleted" | "messageIdHeader" | "fromEmail" | "listId" | "snippet")[];
+    excludeDeleted: boolean;
+};
+/**
+ * Build the `searchByMailboxWindow` options for the thread search handler.
+ * Same #212 `excludeDeleted` default as `buildListThreadsOptions`. The caller's
+ * `limit` is forwarded raw and clamped server-side (THREAD_SEARCH_MAX_LIMIT).
+ */
+export declare const buildSearchThreadsOptions: (query: {
+    continuationToken?: string;
+    order?: "asc" | "desc";
+    limit?: number;
+}) => {
+    order: "asc" | "desc";
+    continuationToken: string | undefined;
+    limit: number | undefined;
+    attributes: ("mailboxId" | "messageId" | "referenceOrder" | "createdAt" | "updatedAt" | "accountConfigId" | "uid" | "category" | "subject" | "internalDate" | "inReplyTo" | "fromName" | "threadMessageId" | "star" | "threadId" | "sentDate" | "isRead" | "hasAttachment" | "hasStars" | "isDeleted" | "messageIdHeader" | "fromEmail" | "listId" | "snippet")[];
+    excludeDeleted: boolean;
+};
+type WindowOptions = {
+    order?: "asc" | "desc";
+    limit?: number;
+    continuationToken?: string;
+    attributes?: Array<keyof ThreadMessageItem>;
+    excludeDeleted?: boolean;
+};
+type ThreadSearch = {
+    query?: string;
+    subject?: string;
+    from?: string;
+    unread?: boolean;
+    starred?: boolean;
+    attachments?: boolean;
+    category?: MessageCategory[];
+};
+/**
+ * Minimal client surface `executeThreadSearch` needs. Declared structurally
+ * (like `EnrichClient`) so the orchestration — index/window read, count, and
+ * the off-row enrich/filter — is testable with an in-memory fake.
+ */
+export interface ThreadSearchClient extends EnrichClient {
+    threadMessage: {
+        searchByMailboxWindow(accountConfigId: string, mailboxId: string, search: ThreadSearch, options?: WindowOptions): Promise<ResultList<ThreadMessageItem>>;
+        countByMailbox(accountConfigId: string, mailboxId: string, search: ThreadSearch, options?: {
+            excludeDeleted?: boolean;
+            order?: "asc" | "desc";
+        }): Promise<number>;
+    };
+}
+export type ThreadSearchParams = {
+    continuationToken?: string;
+    order?: "asc" | "desc";
+    query?: string;
+    subject?: string;
+    from?: string;
+    unread?: boolean;
+    starred?: boolean;
+    attachments?: boolean;
+    senderTrust?: SenderTrust[];
+    category?: MessageCategory[];
+    dkimMismatch?: boolean;
+    count?: boolean;
+    results?: boolean;
+    limit?: number;
+};
+/**
+ * Run a per-mailbox thread search: select the index/window read, optionally
+ * count, and resolve off-row criteria by enriching+filtering the window. The
+ * `results` toggle omits `items` (count-only) and `count` adds the match count.
+ *
+ * `count` names the whole match, never the page: a page size bounds the rows a
+ * response carries and has no bearing on how many messages match (#509).
+ *
+ * An off-row criterion is the one shape that has no such number. `senderTrust`
+ * and `dkimMismatch` are resolved by enriching a window, so counting them means
+ * enriching every candidate row in the mailbox. `count` is therefore absent
+ * (#305) — a page's post-filter length labelled `count` is a page length
+ * presented as a total, which is the defect the field exists to avoid. Absence
+ * is the same answer the response already gives for a count nobody asked for,
+ * so no caller needs a second shape to read it. A count-only request under an
+ * off-row criterion therefore reads nothing at all.
+ */
+export declare const executeThreadSearch: (client: ThreadSearchClient, accountConfigId: string, mailboxId: string, params: ThreadSearchParams) => Promise<ThreadSearchResponse>;
+/**
+ * Build the `listByThread` options for the thread-messages handler. Same
+ * #212 default as the listing handlers — a soft-deleted message inside a
+ * conversation should not surface in the conversation pane either.
+ *
+ * A conversation is never scoped to one mailbox: the user's own replies live
+ * in Sent, filed messages live in their folder, and all of them belong to the
+ * same thread (#46).
+ *
+ * The default order is `asc`: a conversation is read in the order it happened,
+ * so a reply follows the message it answers (#81). The ordering is the query's,
+ * not the handler's — `listByThread` sorts on sentDate with `threadMessageId`
+ * breaking ties, so it holds across pages rather than within one response.
+ */
+export declare const buildListThreadMessagesOptions: (query: {
+    order?: "asc" | "desc";
+}) => {
+    order: "asc" | "desc";
+    excludeDeleted: boolean;
+};
+/**
+ * Collapse rows that are the same piece of mail to one entry.
+ *
+ * A ThreadMessage row is keyed by (threadId, messageId), and a messageId is
+ * derived from the account plus the RFC 5322 Message-ID, so the same mail
+ * synced from two folders is one row — the mailbox a thread spans is not what
+ * duplicates it. `MessageMoveService.copyMessage` is the exception: a copy is a
+ * per-folder placement with its own derived id (`deriveCopyMessageId`), so a
+ * copied message is a second row in the same thread carrying the same
+ * `messageIdHeader`. Reading the whole thread rather than one mailbox of it
+ * (#46) is what makes both rows visible at once, and two entries for one message
+ * is never what a conversation should show.
+ *
+ * The oldest row wins, so the original outlives the copy, with `threadMessageId`
+ * breaking ties. Both are independent of sort order, so `asc` and `desc` keep
+ * the same message rather than each keeping a different copy of it.
+ *
+ * A row without a usable `messageIdHeader` is never merged: the fallback
+ * identity for headerless mail is per-row by construction, so two such rows are
+ * two distinct messages.
+ */
+export declare const dedupeThreadMessages: <T extends Pick<ThreadMessageItem, "threadMessageId" | "messageIdHeader" | "createdAt">>(rows: T[]) => T[];
+export declare const ThreadOperations: Record<ThreadOperationIds, OperationHandler<ThreadOperationIds>>;
+export declare const ThreadDetailOperations: Record<ThreadDetailOperationIds, OperationHandler<ThreadDetailOperationIds>>;
+export {};

package/dist/src/handlers/thread.js

@@ -0,0 +1,228 @@
+import { NotFoundError } from "@remit/data-ports/errors";
+import { isValidMessageId } from "@remit/data-ports/id";
+import { enrichThreadRows, } from "../derive/enrichThreadRows.js";
+import { filterByOffRowCriteria, hasOffRowCriteria, } from "../derive/filterThreadCriteria.js";
+const DEFAULT_THREADS_PAGE_SIZE = 50;
+// Project to fields used by ListThreadsResponse — keep in sync with handler mapping.
+// Includes ThreadMessage table key fields (accountConfigId, threadMessageId) and
+// the lsi2 index components (mailboxId, sentDate) so ElectroDB can materialize
+// entities and pagination cursors from projected reads. accountConfigId +
+// fromEmail are required at read time to derive the From Address row for
+// senderTrust enrichment (see enrichThreadRows).
+const THREAD_LIST_ATTRIBUTES = [
+    "threadMessageId",
+    "threadId",
+    "messageId",
+    "accountConfigId",
+    "mailboxId",
+    "fromEmail",
+    "fromName",
+    "subject",
+    "sentDate",
+    "isRead",
+    "hasAttachment",
+    "star",
+    "hasStars",
+    "isDeleted",
+    "snippet",
+    "category",
+    "createdAt",
+    "updatedAt",
+];
+/**
+ * Build the `listByMailbox` options for the thread list handler.
+ *
+ * Exposed as a pure helper so the `excludeDeleted: true` default — which is
+ * the entire point of the #212 fix on the handler side — is testable without
+ * standing up DynamoDB. The defaults must stay opt-out from the user (a
+ * future Trash / All-Mail view can flip the flag) and opt-in at the
+ * service layer.
+ */
+export const buildListThreadsOptions = (query) => ({
+    order: query.order ?? "desc",
+    continuationToken: query.continuationToken,
+    limit: DEFAULT_THREADS_PAGE_SIZE,
+    attributes: [...THREAD_LIST_ATTRIBUTES],
+    excludeDeleted: true,
+});
+/**
+ * Build the `searchByMailboxWindow` options for the thread search handler.
+ * Same #212 `excludeDeleted` default as `buildListThreadsOptions`. The caller's
+ * `limit` is forwarded raw and clamped server-side (THREAD_SEARCH_MAX_LIMIT).
+ */
+export const buildSearchThreadsOptions = (query) => ({
+    order: query.order ?? "desc",
+    continuationToken: query.continuationToken,
+    limit: query.limit,
+    attributes: [...THREAD_LIST_ATTRIBUTES],
+    excludeDeleted: true,
+});
+const toArray = (value) => {
+    if (value === undefined)
+        return undefined;
+    return Array.isArray(value) ? value : [value];
+};
+/**
+ * Run a per-mailbox thread search: select the index/window read, optionally
+ * count, and resolve off-row criteria by enriching+filtering the window. The
+ * `results` toggle omits `items` (count-only) and `count` adds the match count.
+ *
+ * `count` names the whole match, never the page: a page size bounds the rows a
+ * response carries and has no bearing on how many messages match (#509).
+ *
+ * An off-row criterion is the one shape that has no such number. `senderTrust`
+ * and `dkimMismatch` are resolved by enriching a window, so counting them means
+ * enriching every candidate row in the mailbox. `count` is therefore absent
+ * (#305) — a page's post-filter length labelled `count` is a page length
+ * presented as a total, which is the defect the field exists to avoid. Absence
+ * is the same answer the response already gives for a count nobody asked for,
+ * so no caller needs a second shape to read it. A count-only request under an
+ * off-row criterion therefore reads nothing at all.
+ */
+export const executeThreadSearch = async (client, accountConfigId, mailboxId, params) => {
+    const search = {
+        query: params.query,
+        subject: params.subject,
+        from: params.from,
+        unread: params.unread,
+        starred: params.starred,
+        attachments: params.attachments,
+        category: params.category,
+    };
+    const offRow = {
+        senderTrust: params.senderTrust,
+        dkimMismatch: params.dkimMismatch,
+    };
+    const wantCount = params.count === true;
+    const wantResults = params.results !== false;
+    const options = buildSearchThreadsOptions({
+        continuationToken: params.continuationToken,
+        order: params.order,
+        limit: params.limit,
+    });
+    if (hasOffRowCriteria(offRow)) {
+        if (!wantResults)
+            return {};
+        const window = await client.threadMessage.searchByMailboxWindow(accountConfigId, mailboxId, search, options);
+        const enriched = await enrichThreadRows(window.items, client, accountConfigId);
+        return {
+            items: filterByOffRowCriteria(enriched, offRow),
+            continuationToken: window.continuationToken,
+        };
+    }
+    const response = {};
+    if (wantResults) {
+        const window = await client.threadMessage.searchByMailboxWindow(accountConfigId, mailboxId, search, options);
+        response.items = await enrichThreadRows(window.items, client, accountConfigId);
+        response.continuationToken = window.continuationToken;
+    }
+    if (wantCount) {
+        response.count = await client.threadMessage.countByMailbox(accountConfigId, mailboxId, search, { excludeDeleted: true, order: params.order });
+    }
+    return response;
+};
+/**
+ * Build the `listByThread` options for the thread-messages handler. Same
+ * #212 default as the listing handlers — a soft-deleted message inside a
+ * conversation should not surface in the conversation pane either.
+ *
+ * A conversation is never scoped to one mailbox: the user's own replies live
+ * in Sent, filed messages live in their folder, and all of them belong to the
+ * same thread (#46).
+ *
+ * The default order is `asc`: a conversation is read in the order it happened,
+ * so a reply follows the message it answers (#81). The ordering is the query's,
+ * not the handler's — `listByThread` sorts on sentDate with `threadMessageId`
+ * breaking ties, so it holds across pages rather than within one response.
+ */
+export const buildListThreadMessagesOptions = (query) => ({
+    order: query.order ?? "asc",
+    excludeDeleted: true,
+});
+/**
+ * Collapse rows that are the same piece of mail to one entry.
+ *
+ * A ThreadMessage row is keyed by (threadId, messageId), and a messageId is
+ * derived from the account plus the RFC 5322 Message-ID, so the same mail
+ * synced from two folders is one row — the mailbox a thread spans is not what
+ * duplicates it. `MessageMoveService.copyMessage` is the exception: a copy is a
+ * per-folder placement with its own derived id (`deriveCopyMessageId`), so a
+ * copied message is a second row in the same thread carrying the same
+ * `messageIdHeader`. Reading the whole thread rather than one mailbox of it
+ * (#46) is what makes both rows visible at once, and two entries for one message
+ * is never what a conversation should show.
+ *
+ * The oldest row wins, so the original outlives the copy, with `threadMessageId`
+ * breaking ties. Both are independent of sort order, so `asc` and `desc` keep
+ * the same message rather than each keeping a different copy of it.
+ *
+ * A row without a usable `messageIdHeader` is never merged: the fallback
+ * identity for headerless mail is per-row by construction, so two such rows are
+ * two distinct messages.
+ */
+export const dedupeThreadMessages = (rows) => {
+    const winners = new Map();
+    for (const row of rows) {
+        if (!isValidMessageId(row.messageIdHeader))
+            continue;
+        const header = row.messageIdHeader.trim();
+        const held = winners.get(header);
+        if (!held ||
+            row.createdAt < held.createdAt ||
+            (row.createdAt === held.createdAt &&
+                row.threadMessageId < held.threadMessageId)) {
+            winners.set(header, row);
+        }
+    }
+    return rows.filter((row) => {
+        if (!isValidMessageId(row.messageIdHeader))
+            return true;
+        return winners.get(row.messageIdHeader.trim()) === row;
+    });
+};
+export const ThreadOperations = {
+    ThreadOperations_listThreads: async (context, ctx) => {
+        const accountConfigId = ctx.identity.accountConfigId;
+        const { mailboxId } = context.request.params;
+        const { continuationToken, order } = context.request.query;
+        const client = ctx.client;
+        const result = await client.threadMessage.listByMailbox(accountConfigId, mailboxId, buildListThreadsOptions({ continuationToken, order }));
+        const items = await enrichThreadRows(result.items, client, accountConfigId);
+        return {
+            items,
+            continuationToken: result.continuationToken,
+        };
+    },
+    ThreadOperations_searchThreads: async (context, ctx) => {
+        const accountConfigId = ctx.identity.accountConfigId;
+        const { mailboxId } = context.request.params;
+        const raw = context.request.query;
+        return executeThreadSearch(ctx.client, accountConfigId, mailboxId, {
+            ...raw,
+            senderTrust: toArray(raw.senderTrust),
+            category: toArray(raw.category),
+        });
+    },
+};
+export const ThreadDetailOperations = {
+    ThreadDetailOperations_listThreadMessages: async (context, ctx) => {
+        const accountConfigId = ctx.identity.accountConfigId;
+        const { threadId } = context.request.params;
+        const { order } = context.request.query;
+        const client = ctx.client;
+        const result = await client.threadMessage.listByThread(threadId, accountConfigId, buildListThreadMessagesOptions({ order }));
+        // Defense-in-depth: the query is already scoped to accountConfigId; assert
+        // no foreign row slips into the response. `read`-class → 404, no existence
+        // leak, consistent with the mailbox/message guards.
+        for (const row of result.items) {
+            if (row.accountConfigId !== accountConfigId) {
+                throw new NotFoundError(`Thread not found: ${threadId}`);
+            }
+        }
+        const items = await enrichThreadRows(dedupeThreadMessages(result.items), client, accountConfigId);
+        return {
+            items,
+            continuationToken: result.continuationToken,
+        };
+    },
+};