@remit/storage-service 0.0.11 → 0.0.13

package/dist/backends/s3.js

@@ -0,0 +1,413 @@
+import { createHash } from "node:crypto";
+import { PassThrough } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { createGunzip, createGzip, gunzipSync, gzipSync } from "node:zlib";
+import { DeleteObjectCommand, DeleteObjectsCommand, GetObjectCommand, HeadObjectCommand, ListObjectsV2Command, PutObjectCommand, } from "@aws-sdk/client-s3";
+import { Upload } from "@aws-sdk/lib-storage";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import { ContentEncoding, StorageType } from "@remit/domain-enums";
+import { buildBodyPartKey, buildDeduplicatedKey, buildExportArchiveKey, buildMessageBodyKey, buildOutboxAttachmentKey, buildOutboxAttachmentPrefix, buildParsedBodyKey, computeChecksum, isStorageNotFoundError, } from "../storage.js";
+import { parseStorageUri } from "../uri.js";
+export const createS3StorageService = (client, bucketName) => {
+    const storeInternal = async (params) => {
+        const { key, content, contentType, compress = true } = params;
+        const contentChecksumSha256 = computeChecksum(content);
+        const contentEncoding = compress
+            ? ContentEncoding.Gzip
+            : ContentEncoding.None;
+        const body = compress ? gzipSync(content) : content;
+        await client.send(new PutObjectCommand({
+            Bucket: bucketName,
+            Key: key,
+            Body: body,
+            ContentType: contentType,
+            ContentEncoding: compress ? "gzip" : undefined,
+        }));
+        return {
+            uri: `s3://${bucketName}/${key}`,
+            storageType: StorageType.S3,
+            storageLocation: bucketName,
+            storageKey: key,
+            sizeBytes: body.length,
+            checksumSha256: contentChecksumSha256,
+            contentEncoding,
+        };
+    };
+    const storeMessageBody = (params) => {
+        const { accountConfigId, accountId, messageId, content } = params;
+        return storeInternal({
+            key: buildMessageBodyKey(accountConfigId, accountId, messageId),
+            content,
+            contentType: "message/rfc822",
+        });
+    };
+    const storeMessageBodyStream = async (params) => {
+        const { accountConfigId, accountId, messageId, content } = params;
+        const key = buildMessageBodyKey(accountConfigId, accountId, messageId);
+        // Hash the logical (pre-gzip) bytes as they flow, gzip them, and feed
+        // the gzipped stream to a multipart Upload — the whole body is never
+        // held in memory. `Upload` buffers only one part at a time.
+        const hash = createHash("sha256");
+        const hashTap = new PassThrough();
+        hashTap.on("data", (chunk) => hash.update(chunk));
+        const gzip = createGzip();
+        const uploadBody = new PassThrough();
+        let storedBytes = 0;
+        uploadBody.on("data", (chunk) => {
+            storedBytes += chunk.length;
+        });
+        const upload = new Upload({
+            client,
+            params: {
+                Bucket: bucketName,
+                Key: key,
+                Body: uploadBody,
+                ContentType: "message/rfc822",
+                ContentEncoding: "gzip",
+            },
+        });
+        const pumped = pipeline(content, hashTap, gzip, uploadBody);
+        await Promise.all([upload.done(), pumped]).catch(async (error) => {
+            // Abort the multipart upload so a failed pump doesn't leak parts.
+            await upload.abort().catch(() => { });
+            throw error;
+        });
+        return {
+            uri: `s3://${bucketName}/${key}`,
+            storageType: StorageType.S3,
+            storageLocation: bucketName,
+            storageKey: key,
+            sizeBytes: storedBytes,
+            checksumSha256: hash.digest("hex"),
+            contentEncoding: ContentEncoding.Gzip,
+        };
+    };
+    const storeBodyPart = (params) => {
+        const { accountConfigId, accountId, messageId, partPath, content, contentType, } = params;
+        return storeInternal({
+            key: buildBodyPartKey(accountConfigId, accountId, messageId, partPath),
+            content,
+            contentType,
+        });
+    };
+    const bodyPartExists = (accountConfigId, accountId, messageId, partPath) => {
+        const key = buildBodyPartKey(accountConfigId, accountId, messageId, partPath);
+        return client
+            .send(new HeadObjectCommand({ Bucket: bucketName, Key: key }))
+            .then(() => true)
+            .catch(() => false);
+    };
+    const retrieveBodyPart = async (accountConfigId, accountId, messageId, partPath) => {
+        const key = buildBodyPartKey(accountConfigId, accountId, messageId, partPath);
+        const response = await client
+            .send(new GetObjectCommand({ Bucket: bucketName, Key: key }))
+            .catch((error) => {
+            if (isStorageNotFoundError(error))
+                return null;
+            throw error;
+        });
+        if (!response)
+            return null;
+        if (!response.Body) {
+            throw new Error(`Empty response body for body part: ${key}`);
+        }
+        const body = await response.Body.transformToByteArray();
+        const buffer = Buffer.from(body);
+        return response.ContentEncoding === "gzip" ? gunzipSync(buffer) : buffer;
+    };
+    const storeOutboxAttachment = (params) => {
+        const { accountConfigId, accountId, outboxMessageId, outboxAttachmentId, content, } = params;
+        // `application/octet-stream` rather than the uploader's declared type:
+        // the object is only ever read back to build a MIME part, and a stored
+        // `text/html` would be a type any future signed-URL read path could be
+        // tricked into serving from the content origin.
+        return storeInternal({
+            key: buildOutboxAttachmentKey(accountConfigId, accountId, outboxMessageId, outboxAttachmentId),
+            content,
+            contentType: "application/octet-stream",
+            compress: false,
+        });
+    };
+    const listOutboxAttachments = async (accountConfigId, accountId, outboxMessageId) => {
+        const prefix = buildOutboxAttachmentPrefix(accountConfigId, accountId, outboxMessageId);
+        const items = [];
+        let continuationToken;
+        do {
+            const response = await client.send(new ListObjectsV2Command({
+                Bucket: bucketName,
+                Prefix: prefix,
+                ContinuationToken: continuationToken,
+            }));
+            for (const object of response.Contents ?? []) {
+                if (!object.Key)
+                    continue;
+                items.push({
+                    outboxAttachmentId: object.Key.slice(prefix.length),
+                    key: object.Key,
+                    sizeBytes: object.Size ?? 0,
+                });
+            }
+            continuationToken = response.IsTruncated
+                ? response.NextContinuationToken
+                : undefined;
+        } while (continuationToken);
+        return items;
+    };
+    const listOutboxDraftsWithAttachments = async (accountConfigId, accountId) => {
+        const root = `accounts/${accountConfigId}/${accountId}/outbox/`;
+        const drafts = new Set();
+        let continuationToken;
+        // Delimited listing: S3 answers with the directory-like prefixes rather
+        // than every object under them, so this stays one call per page of
+        // drafts instead of one per object.
+        do {
+            const response = await client.send(new ListObjectsV2Command({
+                Bucket: bucketName,
+                Prefix: root,
+                Delimiter: "/",
+                ContinuationToken: continuationToken,
+            }));
+            for (const entry of response.CommonPrefixes ?? []) {
+                if (!entry.Prefix)
+                    continue;
+                drafts.add(entry.Prefix.slice(root.length).replace(/\/$/, ""));
+            }
+            continuationToken = response.IsTruncated
+                ? response.NextContinuationToken
+                : undefined;
+        } while (continuationToken);
+        return [...drafts];
+    };
+    const deleteOutboxAttachment = async (accountConfigId, accountId, outboxMessageId, outboxAttachmentId) => {
+        const prefix = buildOutboxAttachmentPrefix(accountConfigId, accountId, outboxMessageId);
+        await client.send(new DeleteObjectCommand({
+            Bucket: bucketName,
+            Key: `${prefix}${outboxAttachmentId}`,
+        }));
+    };
+    const statOutboxAttachment = async (accountConfigId, accountId, outboxMessageId, outboxAttachmentId) => {
+        const head = await client
+            .send(new HeadObjectCommand({
+            Bucket: bucketName,
+            Key: buildOutboxAttachmentKey(accountConfigId, accountId, outboxMessageId, outboxAttachmentId),
+        }))
+            .catch((error) => {
+            if (isStorageNotFoundError(error))
+                return null;
+            // A HEAD on a missing key answers 404 with no NoSuchKey code, so the
+            // SDK's NotFound is the same absence.
+            if (error?.name === "NotFound")
+                return null;
+            throw error;
+        });
+        if (!head)
+            return null;
+        return { sizeBytes: head.ContentLength ?? 0 };
+    };
+    const retrieveOutboxAttachment = async (accountConfigId, accountId, outboxMessageId, outboxAttachmentId) => {
+        const key = buildOutboxAttachmentKey(accountConfigId, accountId, outboxMessageId, outboxAttachmentId);
+        const response = await client
+            .send(new GetObjectCommand({ Bucket: bucketName, Key: key }))
+            .catch((error) => {
+            if (isStorageNotFoundError(error))
+                return null;
+            throw error;
+        });
+        if (!response)
+            return null;
+        if (!response.Body) {
+            throw new Error(`Empty response body for outbox attachment: ${key}`);
+        }
+        const bytes = await response.Body.transformToByteArray();
+        return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    };
+    // The browser PUTs straight to the bucket and these bytes never touch the
+    // API. `ContentLength` on the command hoists `content-length` into
+    // X-Amz-SignedHeaders, so S3 recomputes the signature over the length it was
+    // sent: a request declaring any other size fails the signature check, and a
+    // PUT is read for exactly that many bytes. The size is bound by S3 itself,
+    // not by anything downstream trusting the client.
+    const createOutboxAttachmentUploadUrl = async (params) => {
+        const expiresIn = Math.max(1, params.expiresAt - Math.floor(Date.now() / 1000));
+        const uploadUrl = await getSignedUrl(client, new PutObjectCommand({
+            Bucket: bucketName,
+            Key: buildOutboxAttachmentKey(params.accountConfigId, params.accountId, params.outboxMessageId, params.outboxAttachmentId),
+            ContentLength: params.sizeBytes,
+        }), { expiresIn });
+        return { uploadUrl };
+    };
+    const deleteOutboxAttachments = async (accountConfigId, accountId, outboxMessageId) => {
+        const prefix = buildOutboxAttachmentPrefix(accountConfigId, accountId, outboxMessageId);
+        let continuationToken;
+        do {
+            const response = await client.send(new ListObjectsV2Command({
+                Bucket: bucketName,
+                Prefix: prefix,
+                ContinuationToken: continuationToken,
+            }));
+            const keys = (response.Contents ?? [])
+                .map((object) => object.Key)
+                .filter((key) => typeof key === "string");
+            if (keys.length > 0) {
+                await client.send(new DeleteObjectsCommand({
+                    Bucket: bucketName,
+                    Delete: { Objects: keys.map((Key) => ({ Key })) },
+                }));
+            }
+            continuationToken = response.IsTruncated
+                ? response.NextContinuationToken
+                : undefined;
+        } while (continuationToken);
+    };
+    const storeDeduplicated = (params) => {
+        const { accountConfigId, accountId, content, contentType } = params;
+        const checksumSha256 = computeChecksum(content);
+        return storeInternal({
+            key: buildDeduplicatedKey(accountConfigId, accountId, checksumSha256),
+            content,
+            contentType,
+        });
+    };
+    const storeParsedBody = (params) => {
+        const { accountConfigId, accountId, messageId, parsed } = params;
+        const content = Buffer.from(JSON.stringify(parsed), "utf8");
+        return storeInternal({
+            key: buildParsedBodyKey(accountConfigId, accountId, messageId),
+            content,
+            contentType: "application/json",
+        });
+    };
+    const retrieveParsedBody = async (accountConfigId, accountId, messageId) => {
+        const key = buildParsedBodyKey(accountConfigId, accountId, messageId);
+        const response = await client
+            .send(new GetObjectCommand({ Bucket: bucketName, Key: key }))
+            .catch((error) => {
+            if (isStorageNotFoundError(error))
+                return null;
+            throw error;
+        });
+        if (!response)
+            return null;
+        if (!response.Body) {
+            throw new Error(`Empty response body for parsed body: ${key}`);
+        }
+        const body = await response.Body.transformToByteArray();
+        const buffer = Buffer.from(body);
+        const decoded = response.ContentEncoding === "gzip" ? gunzipSync(buffer) : buffer;
+        return JSON.parse(decoded.toString("utf8"));
+    };
+    const retrieve = async (uri) => {
+        const { storageKey } = parseStorageUri(uri);
+        const response = await client.send(new GetObjectCommand({
+            Bucket: bucketName,
+            Key: storageKey,
+        }));
+        if (!response.Body) {
+            throw new Error(`Empty response body for: ${uri}`);
+        }
+        const body = await response.Body.transformToByteArray();
+        const buffer = Buffer.from(body);
+        if (response.ContentEncoding === "gzip") {
+            return gunzipSync(buffer);
+        }
+        return buffer;
+    };
+    const retrieveMessageBody = async (accountConfigId, accountId, messageId) => {
+        const key = buildMessageBodyKey(accountConfigId, accountId, messageId);
+        const response = await client
+            .send(new GetObjectCommand({ Bucket: bucketName, Key: key }))
+            .catch((error) => {
+            if (isStorageNotFoundError(error))
+                return null;
+            throw error;
+        });
+        if (!response)
+            return null;
+        if (!response.Body) {
+            throw new Error(`Empty response body for message body: ${key}`);
+        }
+        const body = await response.Body.transformToByteArray();
+        const buffer = Buffer.from(body);
+        return response.ContentEncoding === "gzip" ? gunzipSync(buffer) : buffer;
+    };
+    const retrieveMessageBodyStream = async (accountConfigId, accountId, messageId) => {
+        const key = buildMessageBodyKey(accountConfigId, accountId, messageId);
+        const response = await client
+            .send(new GetObjectCommand({ Bucket: bucketName, Key: key }))
+            .catch((error) => {
+            if (isStorageNotFoundError(error))
+                return null;
+            throw error;
+        });
+        if (!response)
+            return null;
+        if (!response.Body) {
+            throw new Error(`Empty response body for message body: ${key}`);
+        }
+        const source = response.Body;
+        if (response.ContentEncoding === "gzip") {
+            return source.pipe(createGunzip());
+        }
+        return source;
+    };
+    const exists = async (uri) => {
+        const { storageKey } = parseStorageUri(uri);
+        return client
+            .send(new HeadObjectCommand({
+            Bucket: bucketName,
+            Key: storageKey,
+        }))
+            .then(() => true)
+            .catch(() => false);
+    };
+    const del = async (uri) => {
+        const { storageKey } = parseStorageUri(uri);
+        await client.send(new DeleteObjectCommand({
+            Bucket: bucketName,
+            Key: storageKey,
+        }));
+    };
+    const storeExportArchiveStream = async (accountConfigId, exportRequestId, body) => {
+        const key = buildExportArchiveKey(accountConfigId, exportRequestId);
+        const upload = new Upload({
+            client,
+            params: {
+                Bucket: bucketName,
+                Key: key,
+                Body: body,
+                ContentType: "application/zip",
+            },
+        });
+        await upload.done().catch(async (error) => {
+            await upload.abort().catch(() => { });
+            throw error;
+        });
+        return key;
+    };
+    const getPresignedDownloadUrl = (key, expiresInSeconds) => getSignedUrl(client, new GetObjectCommand({ Bucket: bucketName, Key: key }), { expiresIn: expiresInSeconds });
+    return {
+        storeMessageBody,
+        storeMessageBodyStream,
+        storeBodyPart,
+        bodyPartExists,
+        retrieveBodyPart,
+        storeOutboxAttachment,
+        listOutboxAttachments,
+        listOutboxDraftsWithAttachments,
+        deleteOutboxAttachments,
+        deleteOutboxAttachment,
+        statOutboxAttachment,
+        retrieveOutboxAttachment,
+        createOutboxAttachmentUploadUrl,
+        storeDeduplicated,
+        storeParsedBody,
+        retrieveParsedBody,
+        retrieveMessageBody,
+        retrieveMessageBodyStream,
+        retrieve,
+        exists,
+        delete: del,
+        storeExportArchiveStream,
+        getPresignedDownloadUrl,
+    };
+};

package/dist/filesystem.js

@@ -0,0 +1 @@
+export { createFilesystemStorageService } from "./backends/filesystem.js";

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);
+};