@chidchanun/bcp 0.1.24 → 0.1.26

package/packages/server/src/storage.ts

@@ -0,0 +1,1515 @@
+import {
+    createHash,
+    randomUUID,
+} from "node:crypto";
+import {
+    mkdir,
+    open,
+    readFile,
+    rm,
+    stat,
+    unlink,
+    writeFile,
+} from "node:fs/promises";
+import path from "node:path";
+
+import {
+    validateUploadedFile,
+    type UploadConstraints,
+} from "./upload.js";
+
+const METADATA_DIRECTORY =
+    ".bcp-storage-meta";
+const STREAM_CHUNK_BYTES =
+    64 * 1024;
+
+export type StorageErrorCode =
+    | "INVALID_KEY"
+    | "OBJECT_NOT_FOUND"
+    | "OBJECT_EXISTS"
+    | "RANGE_NOT_SATISFIABLE"
+    | "STREAM_TOO_LARGE";
+
+export class StorageError extends Error {
+    readonly code:
+        StorageErrorCode;
+    readonly status:
+        number;
+
+    constructor(
+        code: StorageErrorCode,
+        message: string,
+        status: number
+    ) {
+        super(message);
+        this.name =
+            "StorageError";
+        this.code =
+            code;
+        this.status =
+            status;
+    }
+}
+
+export interface StorageObjectMetadata {
+    key: string;
+    size: number;
+    contentType: string;
+    lastModified: Date;
+    etag: string;
+    checksumSha256?: string;
+}
+
+export interface StoragePutOptions {
+    contentType?: string;
+    overwrite?: boolean;
+}
+
+export interface StoragePutStreamOptions
+extends StoragePutOptions {
+    maxBytes?: number;
+    signal?: AbortSignal;
+}
+
+export interface StorageReadOptions {
+    start?: number;
+    end?: number;
+}
+
+export interface StorageAdapterCapabilities {
+    streamingRead: boolean;
+    streamingWrite: boolean;
+    ranges: boolean;
+    signedUrls: boolean;
+    listing: boolean;
+}
+
+export type StorageReadableStream =
+    ReadableStream<
+        Uint8Array<ArrayBuffer>
+    >;
+
+export interface StorageAdapter {
+    capabilities?:
+        Partial<
+            StorageAdapterCapabilities
+        >;
+
+    put(
+        key: string,
+        value: StorageWriteValue,
+        options?: StoragePutOptions
+    ): Promise<StorageObjectMetadata>;
+
+    putStream?(
+        key: string,
+        stream:
+            ReadableStream<Uint8Array>,
+        options?: StoragePutStreamOptions
+    ): Promise<StorageObjectMetadata>;
+
+    stat(
+        key: string
+    ): Promise<StorageObjectMetadata | null>;
+
+    read(
+        key: string,
+        options?: StorageReadOptions
+    ): Promise<Uint8Array>;
+
+    readStream?(
+        key: string,
+        options?: StorageReadOptions
+    ): Promise<StorageReadableStream>;
+
+    exists(
+        key: string
+    ): Promise<boolean>;
+
+    delete(
+        key: string
+    ): Promise<boolean>;
+}
+
+export type StorageWriteValue =
+    | string
+    | Blob
+    | ArrayBuffer
+    | ArrayBufferView;
+
+export interface LocalStorageOptions {
+    directory: string;
+}
+
+export interface StoreUploadedFileOptions {
+    storage: StorageAdapter;
+    key?: string;
+    overwrite?: boolean;
+    constraints?: UploadConstraints;
+}
+
+export interface StoredUploadedObject
+extends StorageObjectMetadata {
+    originalName: string;
+}
+
+interface LocalMetadataRecord {
+    version: 1;
+    key: string;
+    contentType: string;
+    checksumSha256: string;
+}
+
+export function createLocalStorage(
+    options: LocalStorageOptions
+): StorageAdapter {
+    const rootDirectory =
+        path.resolve(
+            assertNonEmptyString(
+                options.directory,
+                "directory"
+            )
+        );
+    const metadataDirectory =
+        path.join(
+            rootDirectory,
+            METADATA_DIRECTORY
+        );
+
+    const statObject =
+        async (
+            key: string
+        ): Promise<StorageObjectMetadata | null> => {
+            const normalizedKey =
+                normalizeStorageKey(
+                    key
+                );
+            const destination =
+                resolveStoragePath(
+                    rootDirectory,
+                    normalizedKey
+                );
+
+            let fileStat;
+
+            try {
+                fileStat =
+                    await stat(
+                        destination
+                    );
+            } catch (error) {
+                if (
+                    isNodeErrorCode(
+                        error,
+                        "ENOENT"
+                    )
+                ) {
+                    return null;
+                }
+
+                throw error;
+            }
+
+            if (!fileStat.isFile()) {
+                return null;
+            }
+
+            const record =
+                await readMetadataRecord(
+                    metadataDirectory,
+                    normalizedKey
+                );
+
+            return createObjectMetadata(
+                normalizedKey,
+                fileStat.size,
+                fileStat.mtime,
+                record?.contentType ??
+                    "application/octet-stream",
+                record?.checksumSha256
+            );
+        };
+
+    const putStream =
+        async (
+            key: string,
+            stream:
+                ReadableStream<Uint8Array>,
+            putOptions:
+                StoragePutStreamOptions = {}
+        ): Promise<StorageObjectMetadata> => {
+            const normalizedKey =
+                normalizeStorageKey(
+                    key
+                );
+            const destination =
+                resolveStoragePath(
+                    rootDirectory,
+                    normalizedKey
+                );
+            const contentType =
+                normalizeContentType(
+                    putOptions.contentType ??
+                    ""
+                );
+            const maxBytes =
+                normalizeOptionalByteLimit(
+                    putOptions.maxBytes,
+                    "stream maxBytes"
+                );
+
+            await mkdir(
+                path.dirname(
+                    destination
+                ),
+                {
+                    recursive: true,
+                }
+            );
+
+            const reader =
+                stream.getReader();
+            let handle:
+                Awaited<
+                    ReturnType<typeof open>
+                > | null =
+                null;
+            let destinationOpened =
+                false;
+            let completed =
+                false;
+
+            try {
+                putOptions.signal
+                    ?.throwIfAborted();
+
+                try {
+                    handle =
+                        await open(
+                            destination,
+                            putOptions.overwrite
+                                ? "w"
+                                : "wx"
+                        );
+                    destinationOpened =
+                        true;
+                } catch (error) {
+                    if (
+                        isNodeErrorCode(
+                            error,
+                            "EEXIST"
+                        )
+                    ) {
+                        throw new StorageError(
+                            "OBJECT_EXISTS",
+                            `BCP Framework: storage object "${normalizedKey}" already exists.`,
+                            409
+                        );
+                    }
+
+                    throw error;
+                }
+
+                const hash =
+                    createHash(
+                        "sha256"
+                    );
+                let totalBytes =
+                    0;
+
+                while (true) {
+                    putOptions.signal
+                        ?.throwIfAborted();
+
+                    const result =
+                        await reader.read();
+
+                    if (result.done) {
+                        break;
+                    }
+
+                    const chunk =
+                        result.value;
+
+                    if (
+                        !(chunk instanceof
+                            Uint8Array)
+                    ) {
+                        throw new TypeError(
+                            "BCP Framework: storage streams must emit Uint8Array chunks."
+                        );
+                    }
+
+                    const nextTotal =
+                        totalBytes +
+                        chunk.byteLength;
+
+                    if (
+                        maxBytes !== undefined &&
+                        nextTotal > maxBytes
+                    ) {
+                        throw new StorageError(
+                            "STREAM_TOO_LARGE",
+                            `BCP Framework: storage stream exceeded ${maxBytes} bytes.`,
+                            413
+                        );
+                    }
+
+                    await writeAll(
+                        handle,
+                        chunk
+                    );
+                    hash.update(
+                        chunk
+                    );
+                    totalBytes =
+                        nextTotal;
+                }
+
+                await handle.close();
+                handle =
+                    null;
+
+                const checksumSha256 =
+                    hash.digest(
+                        "hex"
+                    );
+
+                await writeMetadataRecord(
+                    metadataDirectory,
+                    {
+                        version: 1,
+                        key:
+                            normalizedKey,
+                        contentType,
+                        checksumSha256,
+                    }
+                );
+
+                const fileStat =
+                    await stat(
+                        destination
+                    );
+
+                completed =
+                    true;
+
+                return createObjectMetadata(
+                    normalizedKey,
+                    fileStat.size,
+                    fileStat.mtime,
+                    contentType,
+                    checksumSha256
+                );
+            } catch (error) {
+                try {
+                    await reader.cancel(
+                        error
+                    );
+                } catch {
+                    // Ignore source cancellation failures.
+                }
+
+                throw error;
+            } finally {
+                reader.releaseLock();
+
+                if (handle) {
+                    try {
+                        await handle.close();
+                    } catch {
+                        // Preserve the original failure.
+                    }
+                }
+
+                if (
+                    destinationOpened &&
+                    !completed
+                ) {
+                    await rm(
+                        destination,
+                        {
+                            force: true,
+                        }
+                    );
+                }
+            }
+        };
+
+    const readStream =
+        async (
+            key: string,
+            readOptions:
+                StorageReadOptions = {}
+        ): Promise<StorageReadableStream> => {
+            const normalizedKey =
+                normalizeStorageKey(
+                    key
+                );
+            const destination =
+                resolveStoragePath(
+                    rootDirectory,
+                    normalizedKey
+                );
+            const metadata =
+                await statObject(
+                    normalizedKey
+                );
+
+            if (!metadata) {
+                throw new StorageError(
+                    "OBJECT_NOT_FOUND",
+                    `BCP Framework: storage object "${normalizedKey}" was not found.`,
+                    404
+                );
+            }
+
+            const range =
+                normalizeReadRange(
+                    metadata.size,
+                    readOptions
+                );
+
+            if (
+                metadata.size === 0 &&
+                range === null
+            ) {
+                return new ReadableStream<
+                    Uint8Array<ArrayBuffer>
+                >({
+                    start(controller) {
+                        controller.close();
+                    },
+                });
+            }
+
+            const start =
+                range?.start ??
+                0;
+            const end =
+                range?.end ??
+                metadata.size - 1;
+            const handle =
+                await open(
+                    destination,
+                    "r"
+                );
+            let position =
+                start;
+            let closed =
+                false;
+
+            const closeHandle =
+                async () => {
+                    if (closed) {
+                        return;
+                    }
+
+                    closed =
+                        true;
+                    await handle.close();
+                };
+
+            return new ReadableStream<
+                Uint8Array<ArrayBuffer>
+            >({
+                async pull(controller) {
+                    try {
+                        if (
+                            position > end
+                        ) {
+                            await closeHandle();
+                            controller.close();
+                            return;
+                        }
+
+                        const remaining =
+                            end -
+                            position +
+                            1;
+                        const requested =
+                            Math.min(
+                                STREAM_CHUNK_BYTES,
+                                remaining
+                            );
+                        const buffer =
+                            Buffer.allocUnsafe(
+                                requested
+                            );
+                        const result =
+                            await handle.read(
+                                buffer,
+                                0,
+                                requested,
+                                position
+                            );
+
+                        if (
+                            result.bytesRead === 0
+                        ) {
+                            await closeHandle();
+                            controller.close();
+                            return;
+                        }
+
+                        const chunk =
+                            new Uint8Array(
+                                result.bytesRead
+                            );
+                        chunk.set(
+                            buffer.subarray(
+                                0,
+                                result.bytesRead
+                            )
+                        );
+                        position +=
+                            result.bytesRead;
+
+                        controller.enqueue(
+                            chunk
+                        );
+
+                        if (
+                            position > end
+                        ) {
+                            await closeHandle();
+                            controller.close();
+                        }
+                    } catch (error) {
+                        try {
+                            await closeHandle();
+                        } catch {
+                            // Preserve the read failure.
+                        }
+
+                        controller.error(
+                            error
+                        );
+                    }
+                },
+
+                async cancel() {
+                    await closeHandle();
+                },
+            });
+        };
+
+    return {
+        capabilities: {
+            streamingRead: true,
+            streamingWrite: true,
+            ranges: true,
+            signedUrls: false,
+            listing: false,
+        },
+
+        async put(
+            key,
+            value,
+            putOptions = {}
+        ) {
+            const normalizedKey =
+                normalizeStorageKey(
+                    key
+                );
+            const destination =
+                resolveStoragePath(
+                    rootDirectory,
+                    normalizedKey
+                );
+            const bytes =
+                await toStorageBytes(
+                    value
+                );
+            const checksumSha256 =
+                createHash(
+                    "sha256"
+                )
+                    .update(bytes)
+                    .digest("hex");
+            const contentType =
+                normalizeContentType(
+                    putOptions.contentType ??
+                    (
+                        value instanceof Blob
+                            ? value.type
+                            : ""
+                    )
+                );
+
+            await mkdir(
+                path.dirname(
+                    destination
+                ),
+                {
+                    recursive: true,
+                }
+            );
+
+            try {
+                await writeFile(
+                    destination,
+                    bytes,
+                    {
+                        flag:
+                            putOptions.overwrite
+                                ? "w"
+                                : "wx",
+                    }
+                );
+            } catch (error) {
+                if (
+                    isNodeErrorCode(
+                        error,
+                        "EEXIST"
+                    )
+                ) {
+                    throw new StorageError(
+                        "OBJECT_EXISTS",
+                        `BCP Framework: storage object "${normalizedKey}" already exists.`,
+                        409
+                    );
+                }
+
+                throw error;
+            }
+
+            await writeMetadataRecord(
+                metadataDirectory,
+                {
+                    version: 1,
+                    key:
+                        normalizedKey,
+                    contentType,
+                    checksumSha256,
+                }
+            );
+
+            const fileStat =
+                await stat(
+                    destination
+                );
+
+            return createObjectMetadata(
+                normalizedKey,
+                fileStat.size,
+                fileStat.mtime,
+                contentType,
+                checksumSha256
+            );
+        },
+
+        putStream,
+
+        stat:
+            statObject,
+
+        async read(
+            key,
+            readOptions = {}
+        ) {
+            const normalizedKey =
+                normalizeStorageKey(
+                    key
+                );
+            const destination =
+                resolveStoragePath(
+                    rootDirectory,
+                    normalizedKey
+                );
+            const metadata =
+                await statObject(
+                    normalizedKey
+                );
+
+            if (!metadata) {
+                throw new StorageError(
+                    "OBJECT_NOT_FOUND",
+                    `BCP Framework: storage object "${normalizedKey}" was not found.`,
+                    404
+                );
+            }
+
+            const range =
+                normalizeReadRange(
+                    metadata.size,
+                    readOptions
+                );
+
+            if (!range) {
+                return Uint8Array.from(
+                    await readFile(
+                        destination
+                    )
+                );
+            }
+
+            const length =
+                range.end -
+                range.start +
+                1;
+            const handle =
+                await open(
+                    destination,
+                    "r"
+                );
+
+            try {
+                const buffer =
+                    Buffer.allocUnsafe(
+                        length
+                    );
+                const result =
+                    await handle.read(
+                        buffer,
+                        0,
+                        length,
+                        range.start
+                    );
+
+                return Uint8Array.from(
+                    buffer.subarray(
+                        0,
+                        result.bytesRead
+                    )
+                );
+            } finally {
+                await handle.close();
+            }
+        },
+
+        readStream,
+
+        async exists(key) {
+            return (
+                await statObject(
+                    key
+                )
+            ) !== null;
+        },
+
+        async delete(key) {
+            const normalizedKey =
+                normalizeStorageKey(
+                    key
+                );
+            const destination =
+                resolveStoragePath(
+                    rootDirectory,
+                    normalizedKey
+                );
+
+            try {
+                await unlink(
+                    destination
+                );
+            } catch (error) {
+                if (
+                    isNodeErrorCode(
+                        error,
+                        "ENOENT"
+                    )
+                ) {
+                    return false;
+                }
+
+                throw error;
+            }
+
+            await rm(
+                metadataFilePath(
+                    metadataDirectory,
+                    normalizedKey
+                ),
+                {
+                    force: true,
+                }
+            );
+
+            return true;
+        },
+    };
+}
+
+export function getStorageCapabilities(
+    storage: StorageAdapter
+): StorageAdapterCapabilities {
+    return {
+        streamingRead:
+            storage.capabilities
+                ?.streamingRead ??
+            typeof storage.readStream ===
+                "function",
+        streamingWrite:
+            storage.capabilities
+                ?.streamingWrite ??
+            typeof storage.putStream ===
+                "function",
+        ranges:
+            storage.capabilities
+                ?.ranges ??
+            true,
+        signedUrls:
+            storage.capabilities
+                ?.signedUrls ??
+            false,
+        listing:
+            storage.capabilities
+                ?.listing ??
+            false,
+    };
+}
+
+export async function putStorageStream(
+    storage: StorageAdapter,
+    key: string,
+    stream:
+        ReadableStream<Uint8Array>,
+    options:
+        StoragePutStreamOptions = {}
+): Promise<StorageObjectMetadata> {
+    if (storage.putStream) {
+        return storage.putStream(
+            key,
+            stream,
+            options
+        );
+    }
+
+    const bytes =
+        await collectStorageStream(
+            stream,
+            options
+        );
+
+    return storage.put(
+        key,
+        bytes,
+        {
+            contentType:
+                options.contentType,
+            overwrite:
+                options.overwrite,
+        }
+    );
+}
+
+export async function readStorageStream(
+    storage: StorageAdapter,
+    key: string,
+    options:
+        StorageReadOptions = {}
+): Promise<StorageReadableStream> {
+    if (storage.readStream) {
+        return storage.readStream(
+            key,
+            options
+        );
+    }
+
+    const bytes =
+        await storage.read(
+            key,
+            options
+        );
+    const chunk =
+        new Uint8Array(
+            bytes.byteLength
+        );
+
+    chunk.set(
+        bytes
+    );
+
+    return new ReadableStream<
+        Uint8Array<ArrayBuffer>
+    >({
+        start(controller) {
+            if (
+                chunk.byteLength > 0
+            ) {
+                controller.enqueue(
+                    chunk
+                );
+            }
+
+            controller.close();
+        },
+    });
+}
+
+export async function storeUploadedFile(
+    file: File,
+    options: StoreUploadedFileOptions
+): Promise<StoredUploadedObject> {
+    validateUploadedFile(
+        file,
+        options.constraints
+    );
+
+    const key =
+        options.key === undefined
+            ? createUploadStorageKey(
+                file.name
+            )
+            : normalizeStorageKey(
+                options.key
+            );
+    const metadata =
+        await putStorageStream(
+            options.storage,
+            key,
+            file.stream(),
+            {
+                overwrite:
+                    options.overwrite,
+                contentType:
+                    file.type ||
+                    "application/octet-stream",
+                maxBytes:
+                    options.constraints
+                        ?.maxBytes,
+            }
+        );
+
+    return {
+        ...metadata,
+        originalName:
+            file.name,
+    };
+}
+
+export function normalizeStorageKey(
+    value: string
+): string {
+    if (
+        typeof value !== "string" ||
+        value.trim().length === 0
+    ) {
+        throw new StorageError(
+            "INVALID_KEY",
+            "BCP Framework: storage key must be a non-empty relative path.",
+            400
+        );
+    }
+
+    const normalized =
+        value
+            .replace(
+                /\\/g,
+                "/"
+            )
+            .replace(
+                /^\/+|\/+$/g,
+                ""
+            );
+    const segments =
+        normalized.split("/");
+
+    if (
+        normalized.length === 0 ||
+        path.isAbsolute(
+            value
+        ) ||
+        segments.some(
+            (segment) =>
+                segment.length === 0 ||
+                segment === "." ||
+                segment === ".." ||
+                /[\u0000-\u001F\u007F]/.test(
+                    segment
+                )
+        ) ||
+        segments[0] ===
+            METADATA_DIRECTORY
+    ) {
+        throw new StorageError(
+            "INVALID_KEY",
+            `BCP Framework: invalid storage key "${value}".`,
+            400
+        );
+    }
+
+    return segments.join("/");
+}
+
+function resolveStoragePath(
+    rootDirectory: string,
+    key: string
+): string {
+    const destination =
+        path.resolve(
+            rootDirectory,
+            ...key.split("/")
+        );
+    const relative =
+        path.relative(
+            rootDirectory,
+            destination
+        );
+
+    if (
+        relative === "" ||
+        relative.startsWith("..") ||
+        path.isAbsolute(
+            relative
+        )
+    ) {
+        throw new StorageError(
+            "INVALID_KEY",
+            `BCP Framework: storage key "${key}" escapes the configured storage directory.`,
+            400
+        );
+    }
+
+    return destination;
+}
+
+async function toStorageBytes(
+    value: StorageWriteValue
+): Promise<Uint8Array> {
+    if (
+        typeof value ===
+        "string"
+    ) {
+        return Uint8Array.from(
+            Buffer.from(
+                value,
+                "utf8"
+            )
+        );
+    }
+
+    if (
+        value instanceof Blob
+    ) {
+        return new Uint8Array(
+            await value.arrayBuffer()
+        );
+    }
+
+    if (
+        value instanceof ArrayBuffer
+    ) {
+        return new Uint8Array(
+            value
+        );
+    }
+
+    if (
+        ArrayBuffer.isView(
+            value
+        )
+    ) {
+        return Uint8Array.from(
+            new Uint8Array(
+                value.buffer,
+                value.byteOffset,
+                value.byteLength
+            )
+        );
+    }
+
+    throw new TypeError(
+        "BCP Framework: unsupported storage write value."
+    );
+}
+
+async function collectStorageStream(
+    stream:
+        ReadableStream<Uint8Array>,
+    options:
+        Pick<
+            StoragePutStreamOptions,
+            "maxBytes" |
+            "signal"
+        >
+): Promise<Uint8Array<ArrayBuffer>> {
+    const maxBytes =
+        normalizeOptionalByteLimit(
+            options.maxBytes,
+            "stream maxBytes"
+        );
+    const chunks:
+        Uint8Array<ArrayBuffer>[] = [];
+    let totalBytes =
+        0;
+    const reader =
+        stream.getReader();
+
+    try {
+        while (true) {
+            options.signal
+                ?.throwIfAborted();
+
+            const result =
+                await reader.read();
+
+            if (result.done) {
+                break;
+            }
+
+            const chunk =
+                result.value;
+            const nextTotal =
+                totalBytes +
+                chunk.byteLength;
+
+            if (
+                maxBytes !== undefined &&
+                nextTotal > maxBytes
+            ) {
+                throw new StorageError(
+                    "STREAM_TOO_LARGE",
+                    `BCP Framework: storage stream exceeded ${maxBytes} bytes.`,
+                    413
+                );
+            }
+
+            const ownedChunk =
+                new Uint8Array(
+                    chunk.byteLength
+                );
+            ownedChunk.set(
+                chunk
+            );
+            chunks.push(
+                ownedChunk
+            );
+            totalBytes =
+                nextTotal;
+        }
+    } catch (error) {
+        try {
+            await reader.cancel(
+                error
+            );
+        } catch {
+            // Ignore source cancellation failures.
+        }
+
+        throw error;
+    } finally {
+        reader.releaseLock();
+    }
+
+    const bytes =
+        new Uint8Array(
+            totalBytes
+        );
+    let offset =
+        0;
+
+    for (const chunk of chunks) {
+        bytes.set(
+            chunk,
+            offset
+        );
+        offset +=
+            chunk.byteLength;
+    }
+
+    return bytes;
+}
+
+async function writeAll(
+    handle:
+        Awaited<
+            ReturnType<typeof open>
+        >,
+    bytes: Uint8Array
+): Promise<void> {
+    let offset =
+        0;
+
+    while (
+        offset < bytes.byteLength
+    ) {
+        const result =
+            await handle.write(
+                bytes,
+                offset,
+                bytes.byteLength -
+                    offset,
+                null
+            );
+
+        if (
+            result.bytesWritten <= 0
+        ) {
+            throw new Error(
+                "BCP Framework: storage stream write made no progress."
+            );
+        }
+
+        offset +=
+            result.bytesWritten;
+    }
+}
+
+function normalizeOptionalByteLimit(
+    value: number | undefined,
+    label: string
+): number | undefined {
+    if (value === undefined) {
+        return undefined;
+    }
+
+    if (
+        !Number.isSafeInteger(
+            value
+        ) ||
+        value < 0
+    ) {
+        throw new TypeError(
+            `BCP Framework: storage ${label} must be a non-negative safe integer.`
+        );
+    }
+
+    return value;
+}
+
+function normalizeReadRange(
+    size: number,
+    options: StorageReadOptions
+): {
+    start: number;
+    end: number;
+} | null {
+    if (
+        options.start === undefined &&
+        options.end === undefined
+    ) {
+        return null;
+    }
+
+    const start =
+        options.start ??
+        0;
+    const end =
+        options.end ??
+        size - 1;
+
+    if (
+        !Number.isSafeInteger(start) ||
+        !Number.isSafeInteger(end) ||
+        start < 0 ||
+        end < start ||
+        start >= size ||
+        end >= size
+    ) {
+        throw new StorageError(
+            "RANGE_NOT_SATISFIABLE",
+            `BCP Framework: requested storage range ${start}-${end} is invalid for ${size} bytes.`,
+            416
+        );
+    }
+
+    return {
+        start,
+        end,
+    };
+}
+
+function createObjectMetadata(
+    key: string,
+    size: number,
+    lastModified: Date,
+    contentType: string,
+    checksumSha256?: string
+): StorageObjectMetadata {
+    const etag =
+        checksumSha256
+            ? `"sha256-${checksumSha256}"`
+            : `W/"${size}-${Math.trunc(
+                lastModified.getTime()
+            )}"`;
+
+    return {
+        key,
+        size,
+        contentType:
+            normalizeContentType(
+                contentType
+            ),
+        lastModified:
+            new Date(
+                lastModified.getTime()
+            ),
+        etag,
+        ...(checksumSha256
+            ? {
+                checksumSha256,
+            }
+            : {}),
+    };
+}
+
+async function writeMetadataRecord(
+    metadataDirectory: string,
+    record: LocalMetadataRecord
+): Promise<void> {
+    await mkdir(
+        metadataDirectory,
+        {
+            recursive: true,
+        }
+    );
+
+    await writeFile(
+        metadataFilePath(
+            metadataDirectory,
+            record.key
+        ),
+        JSON.stringify(
+            record
+        ),
+        "utf8"
+    );
+}
+
+async function readMetadataRecord(
+    metadataDirectory: string,
+    key: string
+): Promise<LocalMetadataRecord | null> {
+    try {
+        const raw =
+            await readFile(
+                metadataFilePath(
+                    metadataDirectory,
+                    key
+                ),
+                "utf8"
+            );
+        const parsed =
+            JSON.parse(
+                raw
+            ) as Partial<
+                LocalMetadataRecord
+            >;
+
+        if (
+            parsed.version !== 1 ||
+            parsed.key !== key ||
+            typeof parsed.contentType !==
+                "string" ||
+            typeof parsed.checksumSha256 !==
+                "string"
+        ) {
+            return null;
+        }
+
+        return {
+            version: 1,
+            key,
+            contentType:
+                parsed.contentType,
+            checksumSha256:
+                parsed.checksumSha256,
+        };
+    } catch (error) {
+        if (
+            isNodeErrorCode(
+                error,
+                "ENOENT"
+            ) ||
+            error instanceof SyntaxError
+        ) {
+            return null;
+        }
+
+        throw error;
+    }
+}
+
+function metadataFilePath(
+    metadataDirectory: string,
+    key: string
+): string {
+    const digest =
+        createHash(
+            "sha256"
+        )
+            .update(
+                key
+            )
+            .digest(
+                "hex"
+            );
+
+    return path.join(
+        metadataDirectory,
+        `${digest}.json`
+    );
+}
+
+function createUploadStorageKey(
+    originalName: string
+): string {
+    const extension =
+        path.extname(
+            originalName
+        )
+            .toLowerCase()
+            .replace(
+                /[^.a-z0-9]/g,
+                ""
+            )
+            .slice(
+                0,
+                16
+            );
+
+    return `${randomUUID()}${extension}`;
+}
+
+function normalizeContentType(
+    value: string
+): string {
+    const normalized =
+        value
+            .trim()
+            .toLowerCase();
+
+    if (
+        normalized.length === 0 ||
+        /[\r\n]/.test(
+            normalized
+        )
+    ) {
+        return "application/octet-stream";
+    }
+
+    return normalized;
+}
+
+function assertNonEmptyString(
+    value: string,
+    label: string
+): string {
+    if (
+        typeof value !== "string" ||
+        value.trim().length === 0
+    ) {
+        throw new TypeError(
+            `BCP Framework: storage ${label} must be a non-empty string.`
+        );
+    }
+
+    return value;
+}
+
+function isNodeErrorCode(
+    error: unknown,
+    code: string
+): boolean {
+    return (
+        error instanceof Error &&
+        "code" in error &&
+        (
+            error as Error & {
+                code?: string;
+            }
+        ).code === code
+    );
+}