@remit/storage-service 0.0.12 → 0.0.14

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { type OutboxSweepResult, sweepAbandonedOutboxAttachments, } from "./outbox-sweep.js";
+export { type AuthorizeUploadInput, type AuthorizeUploadResult, authorizeUploadRequest, UPLOAD_ROUTE_PREFIX, UPLOAD_URL_SIGNING_LABEL, UPLOAD_URL_TTL_SECONDS, } from "./outbox-upload-url.js";
+export { type SignedPathFailure, type SignedPathResult, signStoragePath, verifyStoragePath, } from "./signed-path.js";
+export { buildBodyPartKey, buildDeduplicatedKey, buildExportArchiveKey, buildMessageBodyKey, buildOutboxAttachmentKey, buildOutboxAttachmentPrefix, buildParsedBodyKey, type ContentEncodingValue, type CreateOutboxAttachmentUploadUrlParams, computeChecksum, createMockStorageService, isStorageNotFoundError, type OutboxAttachmentListItem, type OutboxAttachmentUploadTarget, type ParsedAttachmentMeta, type ParsedBody, type ParsedContentStorageKey, type ParsedOutboxAttachmentKey, parseContentStorageKey, parseOutboxAttachmentKey, type StorageReference, type StorageService, type StorageTypeValue, type StoreBodyPartParams, type StoreDeduplicatedParams, type StoreMessageBodyParams, type StoreOutboxAttachmentParams, type StoreParsedBodyParams, } from "./storage.js";
+export { buildStorageUri, type ParsedStorageUri, parseStorageUri, } from "./uri.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { sweepAbandonedOutboxAttachments, } from "./outbox-sweep.js";
+export { authorizeUploadRequest, UPLOAD_ROUTE_PREFIX, UPLOAD_URL_SIGNING_LABEL, UPLOAD_URL_TTL_SECONDS, } from "./outbox-upload-url.js";
+export { signStoragePath, verifyStoragePath, } from "./signed-path.js";
+export { buildBodyPartKey, buildDeduplicatedKey, buildExportArchiveKey, buildMessageBodyKey, buildOutboxAttachmentKey, buildOutboxAttachmentPrefix, buildParsedBodyKey, computeChecksum, createMockStorageService, isStorageNotFoundError, parseContentStorageKey, parseOutboxAttachmentKey, } from "./storage.js";
+export { buildStorageUri, parseStorageUri, } from "./uri.js";

package/dist/outbox-sweep.d.ts

@@ -0,0 +1,33 @@
+import type { StorageService } from "./storage.js";
+/**
+ * Collect attachment bytes the database does not know about.
+ *
+ * A presigned upload URL stays valid for its whole window, including after the
+ * draft it was minted for is discarded, and on a deployment where the browser
+ * PUTs straight to block storage there is nothing in that path to consult. So
+ * an object can exist that no row names. That is the only case this exists for,
+ * and the rule is the whole of it: an object survives if the database still has
+ * an attachment row for it.
+ *
+ * Two orderings matter and both are deliberate. Objects are listed *before* the
+ * rows are read, so an attachment reserved between the two reads is seen as a
+ * row and not as an object, and is kept. And a draft whose row lookup fails is
+ * skipped entirely — "I could not find out what is live" must never be acted on
+ * as "nothing is live".
+ */
+export interface OutboxSweepResult {
+    inspected: number;
+    deleted: number;
+    /** Drafts skipped because their attachment rows could not be read. */
+    skipped: number;
+}
+export interface OutboxSweepDeps {
+    storage: StorageService;
+    /**
+     * The attachment ids the database holds for a draft. Throwing is the right
+     * way to say "unknown" — the sweep then leaves that draft alone.
+     */
+    listKnownAttachmentIds: (accountConfigId: string, outboxMessageId: string) => Promise<string[]>;
+    onSkipped: (outboxMessageId: string, error: unknown) => void;
+}
+export declare const sweepAbandonedOutboxAttachments: (deps: OutboxSweepDeps, accountConfigId: string, accountId: string) => Promise<OutboxSweepResult>;

package/dist/outbox-sweep.js

@@ -0,0 +1,37 @@
+export const sweepAbandonedOutboxAttachments = async (deps, accountConfigId, accountId) => {
+    let inspected = 0;
+    let deleted = 0;
+    let skipped = 0;
+    const outboxMessageIds = await deps.storage.listOutboxDraftsWithAttachments(accountConfigId, accountId);
+    for (const outboxMessageId of outboxMessageIds) {
+        const objects = await deps.storage.listOutboxAttachments(accountConfigId, accountId, outboxMessageId);
+        if (objects.length === 0)
+            continue;
+        const known = await deps
+            .listKnownAttachmentIds(accountConfigId, outboxMessageId)
+            .then((ids) => new Set(ids))
+            .catch((error) => {
+            deps.onSkipped(outboxMessageId, error);
+            return null;
+        });
+        if (known === null) {
+            skipped += 1;
+            continue;
+        }
+        inspected += objects.length;
+        const abandoned = objects.filter((object) => !known.has(object.outboxAttachmentId));
+        // A draft whose every object is abandoned is the common case — it was
+        // discarded — and taking the prefix in one call beats one round trip per
+        // object.
+        if (abandoned.length === objects.length) {
+            await deps.storage.deleteOutboxAttachments(accountConfigId, accountId, outboxMessageId);
+            deleted += abandoned.length;
+            continue;
+        }
+        for (const object of abandoned) {
+            await deps.storage.deleteOutboxAttachment(accountConfigId, accountId, outboxMessageId, object.outboxAttachmentId);
+            deleted += 1;
+        }
+    }
+    return { inspected, deleted, skipped };
+};

package/dist/outbox-upload-url.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The self-hosted half of the upload seam: what a minted URL looks like when
+ * there is no block storage to presign against, and how the route that receives
+ * the bytes decides to accept them.
+ *
+ * A hosted deployment mints a presigned PUT instead and none of this runs — the
+ * bytes never reach the deployment at all. Both halves bind the same two
+ * things, an expiry and an exact byte count, so a client sees one contract.
+ */
+/** Domain separation: a read grant must never be presentable as a write grant. */
+export declare const UPLOAD_URL_SIGNING_LABEL = "remit-outbox-upload-url-signing-v1";
+export declare const UPLOAD_ROUTE_PREFIX = "/outbox-upload/";
+/**
+ * How long a mint's URL, and the reservation behind it, stay good. Long enough
+ * for a slow phone to push 25 MB, short enough that a draft abandoned mid-upload
+ * stops holding room within the same session.
+ */
+export declare const UPLOAD_URL_TTL_SECONDS = 900;
+export interface AuthorizeUploadInput {
+    secret: string | undefined;
+    /** Decoded storage key the signature was minted over. */
+    relativePath: string;
+    exp: string | undefined;
+    max: string | undefined;
+    sig: string | undefined;
+    nowSeconds: number;
+}
+export type AuthorizeUploadResult = {
+    authorized: true;
+    maxBytes: number;
+} | {
+    authorized: false;
+    status: number;
+    reason: string;
+};
+/**
+ * Decide whether an upload request may write to the key it names.
+ *
+ * Pure, so the decision is testable without a live server. Mirrors
+ * `authorizeContentRequest` on the read side, with one addition: the byte count
+ * is part of the signed message, so the caller learns from the signature how
+ * much this URL is allowed to carry and can cut the stream off there.
+ */
+export declare const authorizeUploadRequest: (input: AuthorizeUploadInput) => AuthorizeUploadResult;

package/{src/outbox-upload-url.ts → dist/outbox-upload-url.js}

@@ -1,5 +1,4 @@
 import { verifyStoragePath } from "./signed-path.js";
-
 /**
  * The self-hosted half of the upload seam: what a minted URL looks like when
  * there is no block storage to presign against, and how the route that receives
@@ -9,33 +8,15 @@ import { verifyStoragePath } from "./signed-path.js";
  * bytes never reach the deployment at all. Both halves bind the same two
  * things, an expiry and an exact byte count, so a client sees one contract.
  */
-
 /** Domain separation: a read grant must never be presentable as a write grant. */
 export const UPLOAD_URL_SIGNING_LABEL = "remit-outbox-upload-url-signing-v1";
-
 export const UPLOAD_ROUTE_PREFIX = "/outbox-upload/";
-
 /**
  * How long a mint's URL, and the reservation behind it, stay good. Long enough
  * for a slow phone to push 25 MB, short enough that a draft abandoned mid-upload
  * stops holding room within the same session.
  */
 export const UPLOAD_URL_TTL_SECONDS = 900;
-
-export interface AuthorizeUploadInput {
-	secret: string | undefined;
-	/** Decoded storage key the signature was minted over. */
-	relativePath: string;
-	exp: string | undefined;
-	max: string | undefined;
-	sig: string | undefined;
-	nowSeconds: number;
-}
-
-export type AuthorizeUploadResult =
-	| { authorized: true; maxBytes: number }
-	| { authorized: false; status: number; reason: string };
-
 /**
  * Decide whether an upload request may write to the key it names.
  *
@@ -44,35 +25,24 @@ export type AuthorizeUploadResult =
  * is part of the signed message, so the caller learns from the signature how
  * much this URL is allowed to carry and can cut the stream off there.
  */
-export const authorizeUploadRequest = (
-	input: AuthorizeUploadInput,
-): AuthorizeUploadResult => {
-	if (!input.secret || input.secret.length === 0) {
-		// No secret means no upload URL could have been signed, so nothing
-		// presented here can be trusted. Fail closed.
-		return {
-			authorized: false,
-			status: 500,
-			reason: "upload-signing-not-configured",
-		};
-	}
-
-	const exp = Number(input.exp);
-	const maxBytes = Number(input.max);
-	if (!Number.isInteger(exp) || !Number.isInteger(maxBytes)) {
-		return { authorized: false, status: 403, reason: "malformed" };
-	}
-
-	const result = verifyStoragePath(
-		input.secret,
-		UPLOAD_URL_SIGNING_LABEL,
-		input.relativePath,
-		[exp, maxBytes],
-		input.sig,
-		input.nowSeconds,
-	);
-	if (result.valid) return { authorized: true, maxBytes };
-
-	const status = result.reason === "missing" ? 401 : 403;
-	return { authorized: false, status, reason: result.reason };
+export const authorizeUploadRequest = (input) => {
+    if (!input.secret || input.secret.length === 0) {
+        // No secret means no upload URL could have been signed, so nothing
+        // presented here can be trusted. Fail closed.
+        return {
+            authorized: false,
+            status: 500,
+            reason: "upload-signing-not-configured",
+        };
+    }
+    const exp = Number(input.exp);
+    const maxBytes = Number(input.max);
+    if (!Number.isInteger(exp) || !Number.isInteger(maxBytes)) {
+        return { authorized: false, status: 403, reason: "malformed" };
+    }
+    const result = verifyStoragePath(input.secret, UPLOAD_URL_SIGNING_LABEL, input.relativePath, [exp, maxBytes], input.sig, input.nowSeconds);
+    if (result.valid)
+        return { authorized: true, maxBytes };
+    const status = result.reason === "missing" ? 401 : 403;
+    return { authorized: false, status, reason: result.reason };
 };

package/dist/s3.d.ts

@@ -0,0 +1,3 @@
+import type { StorageService } from "./storage.js";
+export { createS3StorageService } from "./backends/s3.js";
+export declare const createStorageService: () => StorageService;

package/dist/s3.js

@@ -0,0 +1,28 @@
+import { S3Client } from "@aws-sdk/client-s3";
+import { createFilesystemStorageService } from "./backends/filesystem.js";
+import { createS3StorageService } from "./backends/s3.js";
+export { createS3StorageService } from "./backends/s3.js";
+export const createStorageService = () => {
+    const bucketName = process.env.S3_BUCKET_NAME;
+    if (bucketName) {
+        const client = new S3Client({
+            endpoint: process.env.S3_ENDPOINT,
+            // The SDK default (WHEN_SUPPORTED) hangs a CRC32 of an empty body off
+            // every presigned PUT as signed query params. Real S3 tolerates it;
+            // MinIO and LocalStack reject the request, and S3_ENDPOINT exists to
+            // point at exactly those.
+            requestChecksumCalculation: "WHEN_REQUIRED",
+        });
+        return createS3StorageService(client, bucketName);
+    }
+    const basePath = process.env.STORAGE_LOCAL_PATH ?? ".remit/storage";
+    // BETTER_AUTH_URL is the deployment's own public base — the value the token
+    // issuer and the JWKS discovery document already agree on — so a minted
+    // upload URL resolves from wherever the browser reached the API. Both it and
+    // the signing secret are required on the self-host stack; without them a
+    // mint fails loud inside the backend rather than handing out a URL that
+    // cannot be verified.
+    const origin = process.env.BETTER_AUTH_URL;
+    const signingSecret = process.env.BETTER_AUTH_SECRET;
+    return createFilesystemStorageService(basePath, origin && signingSecret ? { origin, signingSecret } : undefined);
+};

package/dist/signed-path.d.ts

@@ -0,0 +1,14 @@
+export declare const signStoragePath: (masterSecret: string, label: string, relativePath: string, claims: readonly number[]) => string;
+export type SignedPathFailure = "missing" | "malformed" | "expired" | "bad-signature";
+export type SignedPathResult = {
+    valid: true;
+} | {
+    valid: false;
+    reason: SignedPathFailure;
+};
+/**
+ * Verify a presented signature against the path and claims it must cover. The
+ * first claim is always the expiry, in unix seconds. Pure, so the decision can
+ * be unit-tested without a live server.
+ */
+export declare const verifyStoragePath: (masterSecret: string, label: string, relativePath: string, claims: readonly number[], sig: string | undefined, nowSeconds: number) => SignedPathResult;

package/dist/signed-path.js

@@ -0,0 +1,46 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+/**
+ * The HMAC scheme behind every signed storage URL this stack mints.
+ *
+ * It started as the read side — `/content/*` is served against a signature
+ * because a bearer token cannot ride on an `<img src>` inside email HTML — and
+ * the write side needs exactly the same capability: a URL that grants access to
+ * one path, for a while, and is unforgeable without the key. Rather than a
+ * second scheme, both use this one with a different derivation label, so a
+ * signature minted to read content can never be replayed as permission to
+ * write, and vice versa.
+ *
+ * The signed message is the storage path followed by every claim in a fixed
+ * order. Because the path is part of the message, a signature minted for one
+ * account's object cannot be presented for another's.
+ */
+const deriveSigningKey = (masterSecret, label) => createHmac("sha256", masterSecret).update(label).digest();
+const canonicalMessage = (relativePath, claims) => [relativePath, ...claims].join("\n");
+const computeSignature = (key, relativePath, claims) => createHmac("sha256", key)
+    .update(canonicalMessage(relativePath, claims))
+    .digest("base64url");
+export const signStoragePath = (masterSecret, label, relativePath, claims) => computeSignature(deriveSigningKey(masterSecret, label), relativePath, claims);
+/**
+ * Verify a presented signature against the path and claims it must cover. The
+ * first claim is always the expiry, in unix seconds. Pure, so the decision can
+ * be unit-tested without a live server.
+ */
+export const verifyStoragePath = (masterSecret, label, relativePath, claims, sig, nowSeconds) => {
+    if (!sig || claims.length === 0)
+        return { valid: false, reason: "missing" };
+    const [exp] = claims;
+    if (!claims.every((claim) => Number.isInteger(claim) && claim > 0)) {
+        return { valid: false, reason: "malformed" };
+    }
+    if (exp < nowSeconds)
+        return { valid: false, reason: "expired" };
+    const expected = Buffer.from(signStoragePath(masterSecret, label, relativePath, claims));
+    const presented = Buffer.from(sig);
+    if (expected.length !== presented.length) {
+        return { valid: false, reason: "bad-signature" };
+    }
+    if (!timingSafeEqual(expected, presented)) {
+        return { valid: false, reason: "bad-signature" };
+    }
+    return { valid: true };
+};

package/dist/storage.d.ts

@@ -0,0 +1,241 @@
+import { Readable } from "node:stream";
+import { ContentEncoding, StorageType } from "@remit/domain-enums";
+export type StorageTypeValue = (typeof StorageType)[keyof typeof StorageType];
+export type ContentEncodingValue = (typeof ContentEncoding)[keyof typeof ContentEncoding];
+export interface StorageReference {
+    uri: string;
+    storageType: StorageTypeValue;
+    storageLocation: string;
+    storageKey: string;
+    sizeBytes: number;
+    /**
+     * SHA-256 (hex) of the logical, pre-compression content.
+     * Identifies the content regardless of how it is stored on the backend,
+     * and is used by `buildDeduplicatedKey` for content-addressable storage.
+     * Note: this is NOT the checksum S3 validates against the received bytes —
+     * S3's own transport-level checksum is handled by the SDK on PUT.
+     */
+    checksumSha256: string;
+    contentEncoding: ContentEncodingValue;
+}
+/** Parameters for storing a message body (raw RFC822 content) */
+export interface StoreMessageBodyParams {
+    accountConfigId: string;
+    accountId: string;
+    messageId: string;
+    content: Buffer;
+}
+/** Parameters for storing a body part (attachment, inline content) */
+export interface StoreBodyPartParams {
+    accountConfigId: string;
+    accountId: string;
+    messageId: string;
+    partPath: string;
+    content: Buffer;
+    contentType?: string;
+}
+/**
+ * Parameters for storing a file attached to a draft outbox message.
+ *
+ * Deliberately not the deduplicated path: a content-addressed object belongs to
+ * no single draft, so nothing may delete it when the draft goes. A per-draft key
+ * dies with the draft.
+ */
+export interface StoreOutboxAttachmentParams {
+    accountConfigId: string;
+    accountId: string;
+    outboxMessageId: string;
+    outboxAttachmentId: string;
+    content: Buffer;
+}
+/**
+ * One uploaded object under a draft's attachment prefix. Reservations are not
+ * here — they live in the ledger, which is the only thing that can say whether
+ * an object present in storage is an attachment or garbage.
+ */
+export interface OutboxAttachmentListItem {
+    outboxAttachmentId: string;
+    key: string;
+    sizeBytes: number;
+}
+/** Somewhere for a client to PUT one file, for a while */
+export interface OutboxAttachmentUploadTarget {
+    /**
+     * Absolute URL the client PUTs raw bytes to. Opaque by design: block storage
+     * on one deployment, this deployment's own upload route on another, and a
+     * client cannot tell which it was handed.
+     */
+    uploadUrl: string;
+}
+export interface CreateOutboxAttachmentUploadUrlParams {
+    accountConfigId: string;
+    accountId: string;
+    outboxMessageId: string;
+    outboxAttachmentId: string;
+    /** Exact byte count the upload may carry. */
+    sizeBytes: number;
+    expiresAt: number;
+}
+/** Parameters for storing deduplicated content (attachments shared across messages) */
+export interface StoreDeduplicatedParams {
+    accountConfigId: string;
+    accountId: string;
+    content: Buffer;
+    contentType?: string;
+}
+/** Metadata for a single attachment in a parsed message body. No binary content. */
+export interface ParsedAttachmentMeta {
+    filename: string | null;
+    contentType: string;
+    contentDisposition: string | null;
+    contentId: string | null;
+    size: number;
+}
+/** Pre-parsed message body cached as parsed.json.gz to skip mailparser on warm reads */
+export interface ParsedBody {
+    text: string | null;
+    html: string | null;
+    attachments: ParsedAttachmentMeta[];
+}
+/** Parameters for storing a pre-parsed message body */
+export interface StoreParsedBodyParams {
+    accountConfigId: string;
+    accountId: string;
+    messageId: string;
+    parsed: ParsedBody;
+}
+export interface StorageService {
+    /** Store a message body (raw RFC822 content) */
+    storeMessageBody(params: StoreMessageBodyParams): Promise<StorageReference>;
+    /** Store a body part (attachment, inline content) */
+    storeBodyPart(params: StoreBodyPartParams): Promise<StorageReference>;
+    /**
+     * Check whether a body-part object already exists, keyed exactly as
+     * `storeBodyPart` writes it. Used by the lazy per-part generation path to
+     * skip leaves already materialized on a prior read, so regeneration is
+     * idempotent and re-reads stay cheap.
+     */
+    bodyPartExists(accountConfigId: string, accountId: string, messageId: string, partPath: string): Promise<boolean>;
+    /**
+     * Retrieve a body-part's content (attachment or inline leaf) by
+     * account/message id and IMAP section path; returns null on NoSuchKey.
+     */
+    retrieveBodyPart(accountConfigId: string, accountId: string, messageId: string, partPath: string): Promise<Buffer | null>;
+    /**
+     * Store a file attached to a draft outbox message, uncompressed: the size on
+     * the backend is then the decoded size the per-message cap is expressed in,
+     * and `listOutboxAttachments` can total a draft without opening anything.
+     */
+    storeOutboxAttachment(params: StoreOutboxAttachmentParams): Promise<StorageReference>;
+    /**
+     * Every object stored against a draft, paged to the end. Only the sweep reads
+     * this, and a sweep that stops early leaves exactly the orphan it was called
+     * to collect — so there is no limit to get wrong.
+     */
+    listOutboxAttachments(accountConfigId: string, accountId: string, outboxMessageId: string): Promise<OutboxAttachmentListItem[]>;
+    /**
+     * Remove every file and reservation stored against a draft. Unlike the read
+     * above this takes no limit and pages to the end: a sweep that stops early
+     * leaves exactly the orphan it was called to prevent.
+     */
+    deleteOutboxAttachments(accountConfigId: string, accountId: string, outboxMessageId: string): Promise<void>;
+    /**
+     * Every draft under an account that has attachment objects in storage,
+     * including drafts whose row is long gone. The sweep needs the prefixes that
+     * exist, not the rows that exist — a discarded draft is invisible to the
+     * database and is exactly the case worth collecting.
+     */
+    listOutboxDraftsWithAttachments(accountConfigId: string, accountId: string): Promise<string[]>;
+    /** Remove one attachment object. */
+    deleteOutboxAttachment(accountConfigId: string, accountId: string, outboxMessageId: string, outboxAttachmentId: string): Promise<void>;
+    /**
+     * The size storage actually holds for an attachment, or null when nothing
+     * was uploaded. This is the only number a completion may believe — the
+     * client's word for it is not evidence, and on a deployment where the bytes
+     * went straight to block storage it is the only reading available.
+     */
+    statOutboxAttachment(accountConfigId: string, accountId: string, outboxMessageId: string, outboxAttachmentId: string): Promise<{
+        sizeBytes: number;
+    } | null>;
+    /**
+     * The bytes of one attachment, for building the MIME part it goes out as.
+     * Null when nothing is stored under the key.
+     */
+    retrieveOutboxAttachment(accountConfigId: string, accountId: string, outboxMessageId: string, outboxAttachmentId: string): Promise<Buffer | null>;
+    /**
+     * Mint somewhere to PUT one file. The backend decides what that is — block
+     * storage direct, or this deployment's upload route — and the caller never
+     * branches on which it got. Whatever it returns must bind the size: an
+     * upload that carries more than was reserved has to fail at the thing
+     * receiving it, not afterwards.
+     */
+    createOutboxAttachmentUploadUrl(params: CreateOutboxAttachmentUploadUrlParams): Promise<OutboxAttachmentUploadTarget>;
+    /** Store deduplicated content (content-addressable, for attachments) */
+    storeDeduplicated(params: StoreDeduplicatedParams): Promise<StorageReference>;
+    /** Store a pre-parsed message body as gzipped JSON (parsed-body cache) */
+    storeParsedBody(params: StoreParsedBodyParams): Promise<StorageReference>;
+    /** Retrieve a pre-parsed message body by account/message id; returns null on NoSuchKey */
+    retrieveParsedBody(accountConfigId: string, accountId: string, messageId: string): Promise<ParsedBody | null>;
+    /** Retrieve a raw message body (RFC822 .eml) by account/message id; returns null on NoSuchKey */
+    retrieveMessageBody(accountConfigId: string, accountId: string, messageId: string): Promise<Buffer | null>;
+    /**
+     * Retrieve a raw message body as a readable stream of decompressed .eml
+     * bytes; returns null on NoSuchKey. Use on the export path so a whole
+     * mailbox is never buffered in memory.
+     */
+    retrieveMessageBodyStream(accountConfigId: string, accountId: string, messageId: string): Promise<Readable | null>;
+    /** Retrieve content by URI */
+    retrieve(uri: string): Promise<Buffer>;
+    /** Check if content exists */
+    exists(uri: string): Promise<boolean>;
+    /** Delete content by URI */
+    delete(uri: string): Promise<void>;
+    /**
+     * Stream a finished export archive (already-compressed ZIP) to the export
+     * key for the given config + request, uncompressed at rest. The body is
+     * streamed via a multipart upload and never buffered whole. Returns the raw
+     * storage key, which `getPresignedDownloadUrl` can then sign.
+     */
+    storeExportArchiveStream(accountConfigId: string, exportRequestId: string, body: Readable): Promise<string>;
+    /**
+     * Generate a presigned URL that grants temporary GET access to a raw S3 key.
+     * Use for export archives — the key must already exist in the bucket.
+     * Not supported on filesystem backends; throws if called there.
+     */
+    getPresignedDownloadUrl(key: string, expiresInSeconds: number): Promise<string>;
+}
+export declare const buildMessageBodyKey: (accountConfigId: string, accountId: string, messageId: string) => string;
+export declare const buildParsedBodyKey: (accountConfigId: string, accountId: string, messageId: string) => string;
+export declare const buildBodyPartKey: (accountConfigId: string, accountId: string, messageId: string, partPath: string) => string;
+export declare const buildOutboxAttachmentPrefix: (accountConfigId: string, accountId: string, outboxMessageId: string) => string;
+export declare const buildOutboxAttachmentKey: (accountConfigId: string, accountId: string, outboxMessageId: string, outboxAttachmentId: string) => string;
+export interface ParsedOutboxAttachmentKey {
+    accountConfigId: string;
+    accountId: string;
+    outboxMessageId: string;
+    outboxAttachmentId: string;
+}
+/**
+ * Read the ids back out of an attachment key — the inverse of
+ * `buildOutboxAttachmentKey`, for the upload route, which is handed a path and
+ * has to work out what it addresses. Returns null on anything else, including a
+ * reservation key: bytes are never written to one.
+ */
+export declare const parseOutboxAttachmentKey: (storageKey: string) => ParsedOutboxAttachmentKey | null;
+export declare const buildDeduplicatedKey: (accountConfigId: string, accountId: string, checksumSha256: string) => string;
+export interface ParsedContentStorageKey {
+    accountConfigId: string;
+    accountId: string;
+    messageId: string;
+}
+/**
+ * Parse the account/message ids out of a `/content/*` storage key such as
+ * `accounts/{accountConfigId}/{accountId}/messages/{messageId}/parts/1.2`
+ * (the inverse of `buildMessageBodyKey`/`buildParsedBodyKey`/`buildBodyPartKey`
+ * above). Returns null when the shape doesn't match.
+ */
+export declare const parseContentStorageKey: (storageKey: string) => ParsedContentStorageKey | null;
+export declare const computeChecksum: (content: Buffer) => string;
+export declare const buildExportArchiveKey: (accountConfigId: string, exportRequestId: string) => string;
+export declare const isStorageNotFoundError: (error: unknown) => boolean;
+export declare const createMockStorageService: () => StorageService;