@remit/mailbox-service 0.0.111 → 0.0.113

package/dist/mime-walker.d.ts

@@ -0,0 +1,102 @@
+/**
+ * MIME structure walker.
+ *
+ * Flattens an IMAP BODYSTRUCTURE tree (as produced by ImapFlow's
+ * `MessageStructureObject`) into a list of `BodyPartRecord`s ready to be
+ * persisted to the BodyPart / BodyPartParameter tables.
+ *
+ * Inputs are intentionally typed against a structural subset rather than
+ * pulling the imapflow types directly so the walker can be unit-tested
+ * without spinning up an IMAP connection.
+ */
+import { ROOT_PART_PATH } from "@remit/data-ports/id";
+import { ContentDisposition, MediaType, MultipartSubtype, TransferEncoding } from "@remit/domain-enums";
+export { ROOT_PART_PATH };
+export type MediaTypeValue = (typeof MediaType)[keyof typeof MediaType];
+export type TransferEncodingValue = (typeof TransferEncoding)[keyof typeof TransferEncoding];
+export type ContentDispositionValue = (typeof ContentDisposition)[keyof typeof ContentDisposition];
+export type MultipartSubtypeValue = (typeof MultipartSubtype)[keyof typeof MultipartSubtype];
+/**
+ * Structural shape of an IMAP BODYSTRUCTURE node. Mirrors imapflow's
+ * `MessageStructureObject` minus the fields we don't read so this module
+ * stays free of an imapflow dependency.
+ */
+export interface MimeNode {
+    /**
+     * Dot-numbered MIME path (e.g., "1", "1.1", "2"). Empty/undefined for
+     * the root node — the walker assigns "0" to it for storage stability.
+     */
+    part?: string;
+    /** Full Content-Type (e.g., "text/plain", "multipart/mixed"). */
+    type: string;
+    /** Content-Type parameters (charset, boundary, name, ...). */
+    parameters?: Record<string, string>;
+    /** Content-ID header value (without angle brackets). */
+    id?: string;
+    /** Content-Description header value. */
+    description?: string;
+    /** Transfer encoding (7bit, 8bit, base64, quoted-printable, binary). */
+    encoding?: string;
+    /** Encoded byte size of this part. */
+    size?: number;
+    /** Line count for text/* parts. */
+    lineCount?: number;
+    /** MD5 hash. */
+    md5?: string;
+    /** Content-Disposition (inline | attachment). */
+    disposition?: string;
+    /** Content-Disposition parameters (filename, ...). */
+    dispositionParameters?: Record<string, string>;
+    /** Content-Language values. */
+    language?: string[];
+    /** Content-Location URI. */
+    location?: string;
+    /** Children for multipart nodes. */
+    childNodes?: MimeNode[];
+}
+export interface BodyPartParameterRecord {
+    parameterName: string;
+    parameterValue: string;
+}
+/**
+ * Flattened MIME node ready to upsert. `parentPartPath` is the parent
+ * node's `partPath` (or null for the root) so the caller can map paths to
+ * the deterministic `bodyPartId`s without re-walking the tree.
+ */
+export interface BodyPartRecord {
+    partPath: string;
+    parentPartPath: string | null;
+    mediaType: MediaTypeValue;
+    mediaSubtype: string;
+    contentId?: string;
+    contentDescription?: string;
+    transferEncoding: TransferEncodingValue;
+    sizeOctets: number;
+    lineCount?: number;
+    md5Hash?: string;
+    disposition?: ContentDispositionValue;
+    dispositionFilename?: string;
+    language?: string;
+    location?: string;
+    isMultipart: boolean;
+    multipartSubtype?: MultipartSubtypeValue;
+    parameters: BodyPartParameterRecord[];
+}
+/**
+ * Walk an IMAP BODYSTRUCTURE tree depth-first and return a flat list of
+ * `BodyPartRecord`s. The root node uses `ROOT_PART_PATH` ("0"); all other
+ * nodes use the dot-numbered IMAP path that ImapFlow assigns (e.g., "1",
+ * "1.2", "2.1.3"). Every field comes from an untrusted BODYSTRUCTURE, so an
+ * unrecognized MIME type, transfer encoding, or Content-Disposition maps to a
+ * safe default rather than throwing — one malformed part must never drop the
+ * whole message.
+ *
+ * **Part-path uniqueness**: imapflow gives the root of a message/rfc822
+ * node's encapsulated message the same `part` as the node itself, and some
+ * servers give it none. That root is stored as `<messagePath>.0` — the
+ * encapsulated message's own ROOT_PART_PATH — so it can neither overwrite the
+ * message/rfc822 row nor collide with its children (`<messagePath>.1`, ...).
+ * Any other non-root node without a `part` receives a synthetic path
+ * `<parentPath>.<siblingIndex>` that is stable across repeated syncs.
+ */
+export declare const walkMimeStructure: (root: MimeNode) => BodyPartRecord[];

package/dist/mime-walker.js

@@ -0,0 +1,198 @@
+/**
+ * MIME structure walker.
+ *
+ * Flattens an IMAP BODYSTRUCTURE tree (as produced by ImapFlow's
+ * `MessageStructureObject`) into a list of `BodyPartRecord`s ready to be
+ * persisted to the BodyPart / BodyPartParameter tables.
+ *
+ * Inputs are intentionally typed against a structural subset rather than
+ * pulling the imapflow types directly so the walker can be unit-tested
+ * without spinning up an IMAP connection.
+ */
+import { ROOT_PART_PATH } from "@remit/data-ports/id";
+import { ContentDisposition, MediaType, MultipartSubtype, TransferEncoding, } from "@remit/domain-enums";
+export { ROOT_PART_PATH };
+const MEDIA_TYPE_BY_TOP_LEVEL = {
+    text: MediaType.Text,
+    image: MediaType.Image,
+    audio: MediaType.Audio,
+    video: MediaType.Video,
+    application: MediaType.Application,
+    multipart: MediaType.Multipart,
+    message: MediaType.Message,
+};
+const MULTIPART_SUBTYPE_BY_VALUE = {
+    mixed: MultipartSubtype.Mixed,
+    alternative: MultipartSubtype.Alternative,
+    digest: MultipartSubtype.Digest,
+    parallel: MultipartSubtype.Parallel,
+    related: MultipartSubtype.Related,
+    signed: MultipartSubtype.Signed,
+    encrypted: MultipartSubtype.Encrypted,
+    "form-data": MultipartSubtype.FormData,
+    report: MultipartSubtype.Report,
+};
+const TRANSFER_ENCODING_BY_VALUE = {
+    "7bit": TransferEncoding.SevenBit,
+    "8bit": TransferEncoding.EightBit,
+    binary: TransferEncoding.Binary,
+    base64: TransferEncoding.Base64,
+    "quoted-printable": TransferEncoding.QuotedPrintable,
+};
+const DISPOSITION_BY_VALUE = {
+    inline: ContentDisposition.Inline,
+    attachment: ContentDisposition.Attachment,
+};
+const FALLBACK_MEDIA_SUBTYPE = "octet-stream";
+/**
+ * Split a Content-Type into a known media type and its subtype, tolerating
+ * malformed values. The Content-Type is copied from an untrusted header, so a
+ * missing "/", an unknown top-level type, or an empty subtype must not throw
+ * (that would drop the whole message). RFC 2046 §4.5.3 makes
+ * `application/octet-stream` the defined default for an unrecognized type, so
+ * that is the fallback; the raw subtype is preserved where present.
+ */
+const splitContentType = (type) => {
+    const slashIndex = type.indexOf("/");
+    if (slashIndex < 0) {
+        return {
+            mediaType: MediaType.Application,
+            mediaSubtype: FALLBACK_MEDIA_SUBTYPE,
+        };
+    }
+    const topRaw = type.slice(0, slashIndex);
+    const subRaw = type.slice(slashIndex + 1);
+    const top = topRaw.toLowerCase();
+    const mediaType = MEDIA_TYPE_BY_TOP_LEVEL[top] ?? MediaType.Application;
+    const subLower = subRaw.toLowerCase();
+    const mediaSubtype = subLower.length > 0 ? subLower : FALLBACK_MEDIA_SUBTYPE;
+    return { mediaType, mediaSubtype };
+};
+/**
+ * An absent Content-Transfer-Encoding means 7bit (RFC 2045 §6.1); an
+ * unrecognized token is treated as opaque bytes rather than throwing, so a
+ * message carrying an exotic encoding still syncs.
+ */
+const mapTransferEncoding = (encoding) => {
+    if (!encoding)
+        return TransferEncoding.SevenBit;
+    return (TRANSFER_ENCODING_BY_VALUE[encoding.toLowerCase()] ??
+        TransferEncoding.Binary);
+};
+/**
+ * An unknown Content-Disposition is treated as absent (undefined) rather than
+ * throwing, so a message with a malformed disposition still syncs.
+ */
+const mapDisposition = (disposition) => {
+    if (!disposition)
+        return undefined;
+    return DISPOSITION_BY_VALUE[disposition.toLowerCase()];
+};
+const mapMultipartSubtype = (subtype) => {
+    const mapped = MULTIPART_SUBTYPE_BY_VALUE[subtype.toLowerCase()];
+    if (!mapped)
+        return undefined;
+    return mapped;
+};
+const stripAngles = (value) => value.replace(/^<+|>+$/g, "");
+const flattenParameters = (params) => {
+    if (!params)
+        return [];
+    const entries = Object.entries(params).filter(([name, value]) => {
+        if (typeof name !== "string" || name.length === 0)
+            return false;
+        if (typeof value !== "string")
+            return false;
+        return true;
+    });
+    entries.sort((a, b) => a[0].localeCompare(b[0]));
+    return entries.map(([parameterName, parameterValue]) => ({
+        parameterName,
+        parameterValue,
+    }));
+};
+const toRecord = (node, partPath, parentPartPath) => {
+    const { mediaType, mediaSubtype } = splitContentType(node.type);
+    const isMultipart = mediaType === MediaType.Multipart;
+    const multipartSubtype = isMultipart
+        ? mapMultipartSubtype(mediaSubtype)
+        : undefined;
+    const dispositionFilename = node.dispositionParameters?.filename ?? node.parameters?.name ?? undefined;
+    const language = node.language?.[0];
+    const record = {
+        partPath,
+        parentPartPath,
+        mediaType,
+        mediaSubtype,
+        transferEncoding: mapTransferEncoding(node.encoding),
+        sizeOctets: typeof node.size === "number" ? node.size : 0,
+        isMultipart,
+        parameters: flattenParameters(node.parameters),
+    };
+    if (node.id)
+        record.contentId = stripAngles(node.id);
+    if (node.description)
+        record.contentDescription = node.description;
+    if (typeof node.lineCount === "number")
+        record.lineCount = node.lineCount;
+    if (node.md5)
+        record.md5Hash = node.md5;
+    const mappedDisposition = mapDisposition(node.disposition);
+    if (mappedDisposition)
+        record.disposition = mappedDisposition;
+    if (dispositionFilename)
+        record.dispositionFilename = dispositionFilename;
+    if (language)
+        record.language = language;
+    if (node.location)
+        record.location = node.location;
+    if (multipartSubtype)
+        record.multipartSubtype = multipartSubtype;
+    return record;
+};
+/**
+ * Walk an IMAP BODYSTRUCTURE tree depth-first and return a flat list of
+ * `BodyPartRecord`s. The root node uses `ROOT_PART_PATH` ("0"); all other
+ * nodes use the dot-numbered IMAP path that ImapFlow assigns (e.g., "1",
+ * "1.2", "2.1.3"). Every field comes from an untrusted BODYSTRUCTURE, so an
+ * unrecognized MIME type, transfer encoding, or Content-Disposition maps to a
+ * safe default rather than throwing — one malformed part must never drop the
+ * whole message.
+ *
+ * **Part-path uniqueness**: imapflow gives the root of a message/rfc822
+ * node's encapsulated message the same `part` as the node itself, and some
+ * servers give it none. That root is stored as `<messagePath>.0` — the
+ * encapsulated message's own ROOT_PART_PATH — so it can neither overwrite the
+ * message/rfc822 row nor collide with its children (`<messagePath>.1`, ...).
+ * Any other non-root node without a `part` receives a synthetic path
+ * `<parentPath>.<siblingIndex>` that is stable across repeated syncs.
+ */
+export const walkMimeStructure = (root) => {
+    const out = [];
+    const visit = (node, parentPath, parentIsMessage, siblingIndex) => {
+        let partPath;
+        if (parentIsMessage && parentPath !== null) {
+            partPath = `${parentPath}.${ROOT_PART_PATH}`;
+        }
+        else if (node.part && node.part.length > 0) {
+            partPath = node.part;
+        }
+        else if (parentPath === null) {
+            // True root of the BODYSTRUCTURE tree.
+            partPath = ROOT_PART_PATH;
+        }
+        else {
+            partPath = `${parentPath}.${siblingIndex}`;
+        }
+        const record = toRecord(node, partPath, parentPath);
+        out.push(record);
+        const isMessage = record.mediaType === MediaType.Message;
+        const children = node.childNodes ?? [];
+        for (let i = 0; i < children.length; i++) {
+            // biome-ignore lint/style/noNonNullAssertion: value is guaranteed by caller contract
+            visit(children[i], partPath, isMessage, i + 1);
+        }
+    };
+    visit(root, null, false, 0);
+    return out;
+};

package/dist/organize-job.d.ts

@@ -0,0 +1,20 @@
+import type { CreateOrganizeJobRequestInput, IOrganizeJobRequestRepository, OrganizeJobEvent, OrganizeJobRequestItem, QueueProducer } from "@remit/data-ports";
+export interface OrganizeJobOwner {
+    accountConfigId: string;
+    userId: string;
+}
+export type OrganizeJobPredicate = Pick<CreateOrganizeJobRequestInput, "matchOperator" | "literalClauses" | "actionLabelId" | "actionMailboxId">;
+export type OrganizeJobRequest = OrganizeJobOwner & ({
+    predicate: OrganizeJobPredicate;
+} | {
+    filterId: string;
+});
+export interface OrganizeJobLogger {
+    info(obj: Record<string, unknown>, msg: string): void;
+}
+export interface OrganizeJobDeps {
+    organizeJobRequest: Pick<IOrganizeJobRequestRepository, "create">;
+    queue: QueueProducer<OrganizeJobEvent>;
+    logger: OrganizeJobLogger;
+}
+export declare const queueOrganizeJob: (deps: OrganizeJobDeps, request: OrganizeJobRequest) => Promise<OrganizeJobRequestItem>;

package/dist/organize-job.js

@@ -0,0 +1,37 @@
+import { FilterMatchOperator } from "@remit/domain-enums";
+import { NO_ACTION } from "./filters/match.js";
+const ORGANIZE_JOB_TTL_SECONDS = 7 * 24 * 60 * 60;
+const jobColumns = (request) => {
+    if ("filterId" in request) {
+        return {
+            filterId: request.filterId,
+            matchOperator: FilterMatchOperator.And,
+            literalClauses: [],
+            actionLabelId: NO_ACTION,
+            actionMailboxId: NO_ACTION,
+        };
+    }
+    return { filterId: NO_ACTION, ...request.predicate };
+};
+// A filter job names only the filter; the worker reads it when it runs.
+export const queueOrganizeJob = async (deps, request) => {
+    const job = await deps.organizeJobRequest.create({
+        accountConfigId: request.accountConfigId,
+        userId: request.userId,
+        ...jobColumns(request),
+        ttl: Math.floor(Date.now() / 1000) + ORGANIZE_JOB_TTL_SECONDS,
+    });
+    await deps.queue.send({
+        body: {
+            type: "OrganizeJob",
+            accountConfigId: job.accountConfigId,
+            organizeJobId: job.organizeJobId,
+        },
+    });
+    deps.logger.info({
+        accountConfigId: job.accountConfigId,
+        organizeJobId: job.organizeJobId,
+        filterId: job.filterId,
+    }, "Organize back-apply job initiated");
+    return job;
+};

package/dist/outbox-attachment-content.d.ts

@@ -0,0 +1,37 @@
+import type { IOutboxAttachmentRepository } from "@remit/data-ports";
+import type { StorageService } from "@remit/storage-service";
+export interface OutboxAttachmentContent {
+    filename: string;
+    contentType: string;
+    content: Buffer;
+    cid: string;
+}
+export declare const outboxAttachmentContentId: (outboxAttachmentId: string) => string;
+/**
+ * A file on a message that cannot be put into it. Carries the file's name so
+ * whoever settles the message can tell the sender which file to fix.
+ */
+export declare class OutboxAttachmentUnavailableError extends Error {
+    readonly filename: string;
+    readonly detail: string;
+    constructor(filename: string, detail: string, options?: {
+        cause: unknown;
+    });
+}
+export interface OutboxAttachmentContentDeps {
+    attachments: Pick<IOutboxAttachmentRepository, "listByOutboxMessage">;
+    storage: Pick<StorageService, "retrieveOutboxAttachment">;
+}
+export interface OutboxAttachmentOwner {
+    accountConfigId: string;
+    accountId: string;
+    outboxMessageId: string;
+}
+/**
+ * Every file a message goes out with, bytes included, in the order they were
+ * attached. The send op refuses a draft with an upload still open, so a live
+ * `Pending` row here, or a `Stored` row with nothing behind it, is a message
+ * that cannot be built as the sender saw it — and sending it without the file
+ * would be worse than not sending it.
+ */
+export declare const loadOutboxAttachmentContents: (deps: OutboxAttachmentContentDeps, owner: OutboxAttachmentOwner, nowSeconds: number) => Promise<OutboxAttachmentContent[]>;

package/dist/outbox-attachment-content.js

@@ -0,0 +1,50 @@
+import { holdsRoom } from "@remit/data-ports";
+export const outboxAttachmentContentId = (outboxAttachmentId) => `${outboxAttachmentId}@remit`;
+/**
+ * A file on a message that cannot be put into it. Carries the file's name so
+ * whoever settles the message can tell the sender which file to fix.
+ */
+export class OutboxAttachmentUnavailableError extends Error {
+    filename;
+    detail;
+    constructor(filename, detail, options) {
+        super(`"${filename}" could not be read: ${detail}`, options);
+        this.filename = filename;
+        this.detail = detail;
+        this.name = "OutboxAttachmentUnavailableError";
+    }
+}
+const describeCause = (error) => error instanceof Error ? error.message : String(error);
+/**
+ * Every file a message goes out with, bytes included, in the order they were
+ * attached. The send op refuses a draft with an upload still open, so a live
+ * `Pending` row here, or a `Stored` row with nothing behind it, is a message
+ * that cannot be built as the sender saw it — and sending it without the file
+ * would be worse than not sending it.
+ */
+export const loadOutboxAttachmentContents = async (deps, owner, nowSeconds) => {
+    const held = await deps.attachments.listByOutboxMessage(owner.accountConfigId, owner.outboxMessageId);
+    const live = held
+        .filter((item) => holdsRoom(item, nowSeconds))
+        .sort((a, b) => a.createdAt - b.createdAt);
+    const unfinished = live.find((item) => item.state !== "Stored");
+    if (unfinished) {
+        throw new OutboxAttachmentUnavailableError(unfinished.filename, `attachment ${unfinished.outboxAttachmentId} never finished uploading`);
+    }
+    return Promise.all(live.map(async (item) => {
+        const content = await Promise.resolve()
+            .then(() => deps.storage.retrieveOutboxAttachment(owner.accountConfigId, owner.accountId, owner.outboxMessageId, item.outboxAttachmentId))
+            .catch((error) => {
+            throw new OutboxAttachmentUnavailableError(item.filename, `storage failed (${describeCause(error)})`, { cause: error });
+        });
+        if (content === null) {
+            throw new OutboxAttachmentUnavailableError(item.filename, `nothing is stored at ${item.storageKey}`);
+        }
+        return {
+            filename: item.filename,
+            contentType: item.contentType,
+            content,
+            cid: outboxAttachmentContentId(item.outboxAttachmentId),
+        };
+    }));
+};

package/dist/outbox-attachment-filename.d.ts

@@ -0,0 +1,19 @@
+/**
+ * A filename arrives from a browser's `File.name` and reaches a
+ * `Content-Disposition` header on a message a stranger opens. Nothing in the
+ * middle re-derives it, and the storage key never contains it — the key is a
+ * generated id — so this is the one place the value is made safe.
+ */
+/**
+ * The filename to record, or null when nothing usable survives — a name made
+ * only of separators, dots or control characters is refused rather than
+ * replaced with something invented.
+ */
+export declare const sanitizeAttachmentFilename: (raw: string) => string | null;
+export declare const FALLBACK_CONTENT_TYPE = "application/octet-stream";
+/**
+ * The media type to record. Parameters (`; charset=…`) are dropped and anything
+ * that is not a bare type/subtype becomes the fallback: the value is recorded
+ * for the outgoing MIME part, never trusted for rendering.
+ */
+export declare const normalizeAttachmentContentType: (raw: string) => string;

package/dist/outbox-attachment-filename.js

@@ -0,0 +1,64 @@
+/**
+ * A filename arrives from a browser's `File.name` and reaches a
+ * `Content-Disposition` header on a message a stranger opens. Nothing in the
+ * middle re-derives it, and the storage key never contains it — the key is a
+ * generated id — so this is the one place the value is made safe.
+ */
+const PATH_SEPARATORS = /^.*[\\/]/;
+// C0/C1 controls and DEL, then the bidi and directional-isolate formatting
+// characters that let a name ending in "exe" render as if it ended in "png".
+const UNSAFE_CHARACTERS = 
+// biome-ignore lint/suspicious/noControlCharactersInRegex: stripping control characters is the point
+/[\u0000-\u001F\u007F-\u009F\u200E\u200F\u202A-\u202E\u2066-\u2069]/g;
+const MAX_FILENAME_LENGTH = 200;
+// By code point, never by UTF-16 unit: cutting mid-surrogate leaves a lone half
+// that a Content-Disposition encoder can only render as U+FFFD.
+const truncateCodePoints = (value, limit) => Array.from(value).slice(0, limit).join("");
+const truncateKeepingExtension = (filename) => {
+    const codePoints = Array.from(filename);
+    if (codePoints.length <= MAX_FILENAME_LENGTH)
+        return filename;
+    const dot = filename.lastIndexOf(".");
+    const extension = dot > 0 ? Array.from(filename.slice(dot)) : [];
+    if (extension.length === 0 || extension.length > 16) {
+        return truncateCodePoints(filename, MAX_FILENAME_LENGTH);
+    }
+    return (truncateCodePoints(filename, MAX_FILENAME_LENGTH - extension.length) +
+        extension.join(""));
+};
+/**
+ * The filename to record, or null when nothing usable survives — a name made
+ * only of separators, dots or control characters is refused rather than
+ * replaced with something invented.
+ */
+export const sanitizeAttachmentFilename = (raw) => {
+    // Strip first, then take the basename. The other order is bypassable: `.`
+    // does not match a newline, so `PATH_SEPARATORS` stops at one and leaves
+    // every separator after it — "report\r\n/../../.bashrc" survives with its
+    // slashes intact.
+    const stripped = raw.replace(UNSAFE_CHARACTERS, "");
+    const basename = stripped.replace(PATH_SEPARATORS, "").trim();
+    const trimmed = basename.replace(/^\.+/, "").trim();
+    if (trimmed.length === 0)
+        return null;
+    return truncateKeepingExtension(trimmed);
+};
+// RFC 9110 token characters, on both sides of the one slash.
+const MEDIA_TYPE = /^[A-Za-z0-9!#$%&'*+.^_`|~-]+\/[A-Za-z0-9!#$%&'*+.^_`|~-]+$/;
+export const FALLBACK_CONTENT_TYPE = "application/octet-stream";
+// The longest registered media type is well under this. A token run past it is
+// a client inventing one, and it would overflow the response field it lands in.
+const MAX_CONTENT_TYPE_LENGTH = 127;
+/**
+ * The media type to record. Parameters (`; charset=…`) are dropped and anything
+ * that is not a bare type/subtype becomes the fallback: the value is recorded
+ * for the outgoing MIME part, never trusted for rendering.
+ */
+export const normalizeAttachmentContentType = (raw) => {
+    const bare = raw.split(";")[0].trim().toLowerCase();
+    if (bare.length > MAX_CONTENT_TYPE_LENGTH)
+        return FALLBACK_CONTENT_TYPE;
+    if (!MEDIA_TYPE.test(bare))
+        return FALLBACK_CONTENT_TYPE;
+    return bare;
+};

package/dist/outbox-attachment.d.ts

@@ -0,0 +1,148 @@
+import type { IOutboxAttachmentRepository, IOutboxMessageRepository, OutboxAttachmentItem } from "@remit/data-ports";
+import { OutboxAttachmentRejectionReason } from "@remit/domain-enums";
+import type { StorageService } from "@remit/storage-service";
+import { type OutboxAttachmentContent } from "./outbox-attachment-content.js";
+/**
+ * 25 MB is what most receiving servers accept, and base64 inflates it to roughly
+ * 34 MB on the wire. The same number caps one file and the sum of a draft's
+ * files, so a single file can fill a message.
+ */
+export declare const OUTBOX_ATTACHMENT_MAX_TOTAL_BYTES: number;
+/**
+ * A ceiling on how many files one draft can accumulate. The byte cap does not
+ * bound the count — a thousand one-byte files stay far under it.
+ */
+export declare const OUTBOX_ATTACHMENT_MAX_COUNT = 25;
+export type OutboxAttachmentRejectionReasonValue = (typeof OutboxAttachmentRejectionReason)[keyof typeof OutboxAttachmentRejectionReason];
+export interface OutboxAttachmentReservation {
+    outboxAttachmentId: string;
+    outboxMessageId: string;
+    filename: string;
+    contentType: string;
+    sizeBytes: number;
+    contentId: string;
+    uploadUrl: string;
+    uploadExpiresAt: number;
+}
+export interface OutboxAttachmentRejectionDetail {
+    reason: OutboxAttachmentRejectionReasonValue;
+    message: string;
+    limitBytes: number;
+    usedBytes: number;
+}
+type Refused = {
+    readonly outcome: "Rejected";
+    readonly rejection: OutboxAttachmentRejectionDetail;
+};
+export type MintOutboxAttachmentOutcome = {
+    readonly outcome: "Minted";
+    readonly reservation: OutboxAttachmentReservation;
+} | Refused;
+export type CompleteOutboxAttachmentOutcome = {
+    readonly outcome: "Completed";
+    readonly attachment: OutboxAttachmentItem;
+} | Refused;
+export interface MintOutboxAttachmentInput {
+    accountConfigId: string;
+    outboxMessageId: string;
+    filename: string;
+    contentType: string;
+    sizeBytes: number;
+}
+export interface CompleteOutboxAttachmentInput {
+    accountConfigId: string;
+    outboxMessageId: string;
+    outboxAttachmentId: string;
+}
+export interface OutboxAttachmentConfig {
+    outboxMessageService: IOutboxMessageRepository;
+    outboxAttachmentService: IOutboxAttachmentRepository;
+    storage: StorageService;
+    now?: () => number;
+}
+export declare class OutboxAttachmentService {
+    private readonly outboxMessageService;
+    private readonly attachments;
+    private readonly storage;
+    private readonly now;
+    constructor(config: OutboxAttachmentConfig);
+    /**
+     * Resolve a draft the caller is entitled to act on.
+     *
+     * Mode "act": the caller has named the draft, so a foreign one is denied with
+     * 403 rather than feigned as a 404. An entry the user can no longer work on
+     * is a conflict. Both abort the request — only the file itself comes back as
+     * a result the composer can render next to the row it refused.
+     *
+     * Same predicate the composer's other two writes use. A `failed` message is
+     * editable and sendable again (#933), and an attachment is part of what the
+     * correction may be — a message refused for the wrong file would otherwise
+     * still be stuck.
+     */
+    private getWritableDraft;
+    private usedBytesOn;
+    private reject;
+    /**
+     * Room on a draft for one file, and somewhere to put it.
+     *
+     * The row is written before the URL is handed out, and writing it is what
+     * claims the room — the count and the insert are one database transaction, so
+     * two requests arriving together cannot both be told there was space. That is
+     * the whole of the cap; nothing above this layer needs to serialize anything.
+     */
+    mint: (input: MintOutboxAttachmentInput) => Promise<MintOutboxAttachmentOutcome>;
+    /**
+     * Turn an upload into an attachment, on storage's word rather than the
+     * client's.
+     *
+     * On a hosted deployment the bytes went straight to block storage and this is
+     * the first the API hears of them, so the size is read back before the row is
+     * moved to Stored. An object that is absent, or not the size reserved for it,
+     * does not become an attachment — phase 4 sends these bytes, and an
+     * attachment recorded over nothing is a message that cannot be built.
+     */
+    complete: (input: CompleteOutboxAttachmentInput) => Promise<CompleteOutboxAttachmentOutcome>;
+    /**
+     * Whether an attachment is still owed its bytes. The self-hosted upload route
+     * asks before it writes, so a URL minted before a discard cannot put bytes
+     * back under a draft that is gone.
+     */
+    hasLiveReservation: (accountConfigId: string, outboxAttachmentId: string) => Promise<boolean>;
+    /**
+     * What a draft holds, as the composer should see it: reservations that have
+     * lapsed are not files, and showing one with no way to tell it apart is worse
+     * than not showing it.
+     */
+    listFor: (accountConfigId: string, outboxMessageId: string) => Promise<OutboxAttachmentItem[]>;
+    /**
+     * The files a message goes out with, bytes included. The Sent copy is built
+     * from the same rows the wire copy was, so the two carry the same parts.
+     */
+    contentsFor: (accountConfigId: string, accountId: string, outboxMessageId: string) => Promise<OutboxAttachmentContent[]>;
+    /**
+     * The file that stops a send, if any: one still uploading, or one whose
+     * upload never finished. A message must not leave without a file its sender
+     * can see in the composer.
+     */
+    unfinishedUpload: (accountConfigId: string, outboxMessageId: string) => Promise<OutboxAttachmentItem | undefined>;
+    /**
+     * Drop the draft's lapsed reservations and answer with the ids that are still
+     * good. The sweep runs this before it decides what to collect: a lapsed row
+     * would otherwise keep vouching for bytes nothing will ever send, and the
+     * object would never be collected while the row that names it survives.
+     */
+    reapAndListLive: (accountConfigId: string, outboxMessageId: string) => Promise<string[]>;
+    /**
+     * Keep only the named attachments, deleting the rest with their bytes. This
+     * is how a composer removes a file: the update states what the draft keeps.
+     */
+    retainOnly: (accountConfigId: string, accountId: string, outboxMessageId: string, keepIds: readonly string[]) => Promise<void>;
+    /**
+     * Drop every file a draft holds, rows and bytes, as the draft is retired —
+     * a discard, or the APPEND to Sent that removes the row once the message has
+     * left. Rows go last: while they exist the objects are accounted for, and a
+     * failure part-way leaves the sweep able to finish the job.
+     */
+    discardAll: (accountConfigId: string, accountId: string, outboxMessageId: string) => Promise<void>;
+}
+export {};