@chidchanun/bcp 0.1.26 → 0.1.28

package/packages/server/src/storage-ecosystem.ts

@@ -0,0 +1,1326 @@
+import {
+    createHash,
+} from "node:crypto";
+import {
+    mkdir,
+    readFile,
+    readdir,
+    rm,
+    writeFile,
+} from "node:fs/promises";
+import path from "node:path";
+
+import {
+    createLocalStorage as createBaseLocalStorage,
+    getStorageCapabilities,
+    normalizeStorageKey,
+    putStorageStream,
+    readStorageStream,
+    StorageError,
+    type LocalStorageOptions,
+    type StorageAdapter,
+    type StorageAdapterCapabilities,
+    type StorageObjectMetadata,
+    type StoragePutOptions,
+    type StoragePutStreamOptions,
+    type StorageWriteValue,
+} from "./storage.js";
+
+const LOCAL_METADATA_DIRECTORY =
+    ".bcp-storage-meta";
+const USER_METADATA_PREFIX =
+    "user-";
+const DEFAULT_LIST_LIMIT =
+    100;
+const MAX_LIST_LIMIT =
+    1000;
+
+export type StorageUserMetadata =
+    Record<string, string>;
+
+export interface StorageEcosystemPutOptions
+extends StoragePutOptions {
+    metadata?: StorageUserMetadata;
+}
+
+export interface StorageEcosystemPutStreamOptions
+extends StoragePutStreamOptions {
+    metadata?: StorageUserMetadata;
+}
+
+export interface StorageListOptions {
+    prefix?: string;
+    limit?: number;
+    cursor?: string;
+}
+
+export interface StorageListResult {
+    objects: StorageObjectMetadata[];
+    cursor?: string;
+}
+
+export interface StorageCopyOptions {
+    overwrite?: boolean;
+}
+
+export interface StorageSignedUrlOptions {
+    expiresIn?: number;
+}
+
+export interface StorageSignedWriteUrlOptions
+extends StorageSignedUrlOptions {
+    contentType?: string;
+    metadata?: StorageUserMetadata;
+}
+
+export interface StorageDeleteManyFailure {
+    key: string;
+    message: string;
+}
+
+export interface StorageDeleteManyResult {
+    deleted: string[];
+    missing: string[];
+    failed: StorageDeleteManyFailure[];
+}
+
+export interface StorageEcosystemCapabilities
+extends StorageAdapterCapabilities {
+    signedReadUrls: boolean;
+    signedWriteUrls: boolean;
+    copy: boolean;
+    move: boolean;
+    metadata: boolean;
+    bulkDelete: boolean;
+}
+
+export interface StorageEcosystemAdapter
+extends StorageAdapter {
+    put(
+        key: string,
+        value: StorageWriteValue,
+        options?: StorageEcosystemPutOptions
+    ): Promise<StorageObjectMetadata>;
+
+    putStream?(
+        key: string,
+        stream: ReadableStream<Uint8Array>,
+        options?: StorageEcosystemPutStreamOptions
+    ): Promise<StorageObjectMetadata>;
+
+    list?(
+        options?: StorageListOptions
+    ): Promise<StorageListResult>;
+
+    copy?(
+        sourceKey: string,
+        destinationKey: string,
+        options?: StorageCopyOptions
+    ): Promise<StorageObjectMetadata>;
+
+    move?(
+        sourceKey: string,
+        destinationKey: string,
+        options?: StorageCopyOptions
+    ): Promise<StorageObjectMetadata>;
+
+    deleteMany?(
+        keys: readonly string[]
+    ): Promise<StorageDeleteManyResult>;
+
+    getMetadata?(
+        key: string
+    ): Promise<StorageUserMetadata>;
+
+    setMetadata?(
+        key: string,
+        metadata: StorageUserMetadata
+    ): Promise<StorageUserMetadata>;
+
+    createSignedReadUrl?(
+        key: string,
+        options?: StorageSignedUrlOptions
+    ): Promise<string>;
+
+    createSignedWriteUrl?(
+        key: string,
+        options?: StorageSignedWriteUrlOptions
+    ): Promise<string>;
+}
+
+export type StorageEcosystemErrorCode =
+    "UNSUPPORTED_OPERATION" |
+    "INVALID_CURSOR" |
+    "INVALID_METADATA";
+
+export class StorageEcosystemError
+extends Error {
+    readonly code:
+        StorageEcosystemErrorCode;
+    readonly status:
+        number;
+
+    constructor(
+        code: StorageEcosystemErrorCode,
+        message: string,
+        status = 400
+    ) {
+        super(message);
+        this.name =
+            "StorageEcosystemError";
+        this.code =
+            code;
+        this.status =
+            status;
+    }
+}
+
+interface LocalUserMetadataRecord {
+    version: 1;
+    key: string;
+    metadata: StorageUserMetadata;
+}
+
+export function createLocalStorage(
+    options: LocalStorageOptions
+): StorageEcosystemAdapter {
+    const rootDirectory =
+        path.resolve(
+            assertNonEmptyString(
+                options.directory,
+                "directory"
+            )
+        );
+    const metadataDirectory =
+        path.join(
+            rootDirectory,
+            LOCAL_METADATA_DIRECTORY
+        );
+    const base =
+        createBaseLocalStorage(
+            options
+        );
+    const basePut =
+        base.put.bind(
+            base
+        );
+    const basePutStream =
+        base.putStream?.bind(
+            base
+        );
+    const baseDelete =
+        base.delete.bind(
+            base
+        );
+
+    const adapter =
+        base as StorageEcosystemAdapter;
+
+    adapter.capabilities = {
+        ...base.capabilities,
+        listing: true,
+        signedUrls: false,
+    };
+
+    adapter.put =
+        async (
+            key,
+            value,
+            putOptions = {}
+        ) => {
+            const normalizedKey =
+                normalizeStorageKey(
+                    key
+                );
+            const stored =
+                await basePut(
+                    normalizedKey,
+                    value,
+                    putOptions
+                );
+
+            await replaceLocalUserMetadata(
+                metadataDirectory,
+                normalizedKey,
+                putOptions.metadata
+            );
+
+            return stored;
+        };
+
+    if (basePutStream) {
+        adapter.putStream =
+            async (
+                key,
+                stream,
+                putOptions = {}
+            ) => {
+                const normalizedKey =
+                    normalizeStorageKey(
+                        key
+                    );
+                const stored =
+                    await basePutStream(
+                        normalizedKey,
+                        stream,
+                        putOptions
+                    );
+
+                await replaceLocalUserMetadata(
+                    metadataDirectory,
+                    normalizedKey,
+                    putOptions.metadata
+                );
+
+                return stored;
+            };
+    }
+
+    adapter.getMetadata =
+        async (key) => {
+            const normalizedKey =
+                normalizeStorageKey(
+                    key
+                );
+
+            await requireStorageObject(
+                adapter,
+                normalizedKey
+            );
+
+            return readLocalUserMetadata(
+                metadataDirectory,
+                normalizedKey
+            );
+        };
+
+    adapter.setMetadata =
+        async (
+            key,
+            metadata
+        ) => {
+            const normalizedKey =
+                normalizeStorageKey(
+                    key
+                );
+
+            await requireStorageObject(
+                adapter,
+                normalizedKey
+            );
+
+            const normalizedMetadata =
+                normalizeStorageUserMetadata(
+                    metadata
+                );
+
+            await writeLocalUserMetadata(
+                metadataDirectory,
+                normalizedKey,
+                normalizedMetadata
+            );
+
+            return {
+                ...normalizedMetadata,
+            };
+        };
+
+    adapter.list =
+        async (
+            listOptions = {}
+        ) => {
+            const prefix =
+                normalizeStorageListPrefix(
+                    listOptions.prefix
+                );
+            const limit =
+                normalizeStorageListLimit(
+                    listOptions.limit
+                );
+            const afterKey =
+                decodeLocalCursor(
+                    listOptions.cursor
+                );
+            const keys =
+                await collectLocalObjectKeys(
+                    rootDirectory
+                );
+            const matching =
+                keys
+                    .filter(
+                        (key) =>
+                            prefix.length === 0 ||
+                            key.startsWith(
+                                prefix
+                            )
+                    )
+                    .filter(
+                        (key) =>
+                            afterKey === null ||
+                            key > afterKey
+                    )
+                    .sort();
+            const selected =
+                matching.slice(
+                    0,
+                    limit
+                );
+            const objects =
+                (
+                    await Promise.all(
+                        selected.map(
+                            (key) =>
+                                adapter.stat(
+                                    key
+                                )
+                        )
+                    )
+                ).filter(
+                    (
+                        value
+                    ): value is StorageObjectMetadata =>
+                        value !== null
+                );
+
+            return {
+                objects,
+                ...(matching.length > selected.length &&
+                selected.length > 0
+                    ? {
+                        cursor:
+                            encodeLocalCursor(
+                                selected[
+                                    selected.length - 1
+                                ]!
+                            ),
+                    }
+                    : {}),
+            };
+        };
+
+    adapter.copy =
+        async (
+            sourceKey,
+            destinationKey,
+            copyOptions = {}
+        ) =>
+            copyStorageObjectFallback(
+                adapter,
+                sourceKey,
+                destinationKey,
+                copyOptions
+            );
+
+    adapter.move =
+        async (
+            sourceKey,
+            destinationKey,
+            copyOptions = {}
+        ) => {
+            const source =
+                normalizeStorageKey(
+                    sourceKey
+                );
+            const destination =
+                normalizeStorageKey(
+                    destinationKey
+                );
+
+            if (source === destination) {
+                return requireStorageObject(
+                    adapter,
+                    source
+                );
+            }
+
+            const stored =
+                await copyStorageObjectFallback(
+                    adapter,
+                    source,
+                    destination,
+                    copyOptions
+                );
+
+            await adapter.delete(
+                source
+            );
+
+            return stored;
+        };
+
+    adapter.delete =
+        async (key) => {
+            const normalizedKey =
+                normalizeStorageKey(
+                    key
+                );
+            const deleted =
+                await baseDelete(
+                    normalizedKey
+                );
+
+            if (deleted) {
+                await rm(
+                    localUserMetadataFile(
+                        metadataDirectory,
+                        normalizedKey
+                    ),
+                    {
+                        force: true,
+                    }
+                );
+            }
+
+            return deleted;
+        };
+
+    adapter.deleteMany =
+        async (keys) =>
+            deleteStorageObjectsFallback(
+                adapter,
+                keys
+            );
+
+    return adapter;
+}
+
+export function getStorageEcosystemCapabilities(
+    storage: StorageAdapter
+): StorageEcosystemCapabilities {
+    const base =
+        getStorageCapabilities(
+            storage
+        );
+    const ecosystem =
+        storage as StorageEcosystemAdapter;
+
+    return {
+        ...base,
+        signedUrls:
+            base.signedUrls ||
+            typeof ecosystem.createSignedReadUrl ===
+                "function" ||
+            typeof ecosystem.createSignedWriteUrl ===
+                "function",
+        listing:
+            base.listing ||
+            typeof ecosystem.list ===
+                "function",
+        signedReadUrls:
+            typeof ecosystem.createSignedReadUrl ===
+                "function",
+        signedWriteUrls:
+            typeof ecosystem.createSignedWriteUrl ===
+                "function",
+        copy:
+            typeof ecosystem.copy ===
+                "function",
+        move:
+            typeof ecosystem.move ===
+                "function",
+        metadata:
+            typeof ecosystem.getMetadata ===
+                "function" &&
+            typeof ecosystem.setMetadata ===
+                "function",
+        bulkDelete:
+            typeof ecosystem.deleteMany ===
+                "function",
+    };
+}
+
+export async function listStorageObjects(
+    storage: StorageAdapter,
+    options: StorageListOptions = {}
+): Promise<StorageListResult> {
+    const ecosystem =
+        storage as StorageEcosystemAdapter;
+
+    if (!ecosystem.list) {
+        throw unsupportedOperation(
+            "listing"
+        );
+    }
+
+    return ecosystem.list(
+        options
+    );
+}
+
+export async function copyStorageObject(
+    storage: StorageAdapter,
+    sourceKey: string,
+    destinationKey: string,
+    options: StorageCopyOptions = {}
+): Promise<StorageObjectMetadata> {
+    const ecosystem =
+        storage as StorageEcosystemAdapter;
+
+    if (ecosystem.copy) {
+        return ecosystem.copy(
+            sourceKey,
+            destinationKey,
+            options
+        );
+    }
+
+    return copyStorageObjectFallback(
+        ecosystem,
+        sourceKey,
+        destinationKey,
+        options
+    );
+}
+
+export async function moveStorageObject(
+    storage: StorageAdapter,
+    sourceKey: string,
+    destinationKey: string,
+    options: StorageCopyOptions = {}
+): Promise<StorageObjectMetadata> {
+    const ecosystem =
+        storage as StorageEcosystemAdapter;
+
+    if (ecosystem.move) {
+        return ecosystem.move(
+            sourceKey,
+            destinationKey,
+            options
+        );
+    }
+
+    const source =
+        normalizeStorageKey(
+            sourceKey
+        );
+    const destination =
+        normalizeStorageKey(
+            destinationKey
+        );
+
+    if (source === destination) {
+        return requireStorageObject(
+            storage,
+            source
+        );
+    }
+
+    const stored =
+        await copyStorageObjectFallback(
+            ecosystem,
+            source,
+            destination,
+            options
+        );
+
+    await storage.delete(
+        source
+    );
+
+    return stored;
+}
+
+export async function deleteStorageObjects(
+    storage: StorageAdapter,
+    keys: readonly string[]
+): Promise<StorageDeleteManyResult> {
+    const ecosystem =
+        storage as StorageEcosystemAdapter;
+
+    if (ecosystem.deleteMany) {
+        return ecosystem.deleteMany(
+            keys
+        );
+    }
+
+    return deleteStorageObjectsFallback(
+        ecosystem,
+        keys
+    );
+}
+
+export async function getStorageMetadata(
+    storage: StorageAdapter,
+    key: string
+): Promise<StorageUserMetadata> {
+    const ecosystem =
+        storage as StorageEcosystemAdapter;
+
+    if (!ecosystem.getMetadata) {
+        throw unsupportedOperation(
+            "metadata reads"
+        );
+    }
+
+    return ecosystem.getMetadata(
+        key
+    );
+}
+
+export async function setStorageMetadata(
+    storage: StorageAdapter,
+    key: string,
+    metadata: StorageUserMetadata
+): Promise<StorageUserMetadata> {
+    const ecosystem =
+        storage as StorageEcosystemAdapter;
+
+    if (!ecosystem.setMetadata) {
+        throw unsupportedOperation(
+            "metadata writes"
+        );
+    }
+
+    return ecosystem.setMetadata(
+        key,
+        metadata
+    );
+}
+
+export async function createStorageSignedReadUrl(
+    storage: StorageAdapter,
+    key: string,
+    options: StorageSignedUrlOptions = {}
+): Promise<string> {
+    const ecosystem =
+        storage as StorageEcosystemAdapter;
+
+    if (!ecosystem.createSignedReadUrl) {
+        throw unsupportedOperation(
+            "signed read URLs"
+        );
+    }
+
+    return ecosystem.createSignedReadUrl(
+        key,
+        options
+    );
+}
+
+export async function createStorageSignedWriteUrl(
+    storage: StorageAdapter,
+    key: string,
+    options: StorageSignedWriteUrlOptions = {}
+): Promise<string> {
+    const ecosystem =
+        storage as StorageEcosystemAdapter;
+
+    if (!ecosystem.createSignedWriteUrl) {
+        throw unsupportedOperation(
+            "signed write URLs"
+        );
+    }
+
+    return ecosystem.createSignedWriteUrl(
+        key,
+        options
+    );
+}
+
+export function normalizeStorageUserMetadata(
+    metadata:
+        StorageUserMetadata |
+        undefined
+): StorageUserMetadata {
+    if (metadata === undefined) {
+        return {};
+    }
+
+    if (
+        metadata === null ||
+        typeof metadata !==
+            "object" ||
+        Array.isArray(
+            metadata
+        )
+    ) {
+        throw new StorageEcosystemError(
+            "INVALID_METADATA",
+            "BCP Framework: storage metadata must be a string-to-string object."
+        );
+    }
+
+    const normalized:
+        StorageUserMetadata = {};
+
+    for (
+        const [rawKey, rawValue]
+        of Object.entries(
+            metadata
+        )
+    ) {
+        if (
+            typeof rawValue !==
+                "string"
+        ) {
+            throw new StorageEcosystemError(
+                "INVALID_METADATA",
+                `BCP Framework: storage metadata value for "${rawKey}" must be a string.`
+            );
+        }
+
+        const key =
+            rawKey
+                .trim()
+                .toLowerCase();
+        const value =
+            rawValue.trim();
+
+        if (
+            key.length === 0 ||
+            !/^[a-z0-9][a-z0-9_.-]{0,127}$/.test(
+                key
+            ) ||
+            key === "bcp_sha256" ||
+            /[\r\n\u0000]/.test(
+                value
+            )
+        ) {
+            throw new StorageEcosystemError(
+                "INVALID_METADATA",
+                `BCP Framework: invalid storage metadata entry "${rawKey}".`
+            );
+        }
+
+        normalized[
+            key
+        ] = value;
+    }
+
+    return normalized;
+}
+
+export function normalizeStorageListPrefix(
+    value: string | undefined
+): string {
+    if (value === undefined) {
+        return "";
+    }
+
+    const normalized =
+        value
+            .trim()
+            .replace(
+                /\\/g,
+                "/"
+            )
+            .replace(
+                /^\/+/,
+                ""
+            );
+
+    if (normalized.length === 0) {
+        return "";
+    }
+
+    const hasTrailingSlash =
+        normalized.endsWith(
+            "/"
+        );
+    const withoutTrailingSlash =
+        normalized.replace(
+            /\/+$/,
+            ""
+        );
+    const safe =
+        normalizeStorageKey(
+            withoutTrailingSlash
+        );
+
+    return hasTrailingSlash
+        ? `${safe}/`
+        : safe;
+}
+
+export function normalizeStorageListLimit(
+    value: number | undefined
+): number {
+    if (value === undefined) {
+        return DEFAULT_LIST_LIMIT;
+    }
+
+    if (
+        !Number.isSafeInteger(
+            value
+        ) ||
+        value < 1 ||
+        value > MAX_LIST_LIMIT
+    ) {
+        throw new TypeError(
+            `BCP Framework: storage list limit must be an integer between 1 and ${MAX_LIST_LIMIT}.`
+        );
+    }
+
+    return value;
+}
+
+export function normalizeStorageSignedUrlExpiry(
+    value: number | undefined
+): number {
+    if (value === undefined) {
+        return 15 * 60;
+    }
+
+    if (
+        !Number.isSafeInteger(
+            value
+        ) ||
+        value < 1 ||
+        value > 7 * 24 * 60 * 60
+    ) {
+        throw new TypeError(
+            "BCP Framework: signed URL expiresIn must be an integer between 1 and 604800 seconds."
+        );
+    }
+
+    return value;
+}
+
+async function copyStorageObjectFallback(
+    storage: StorageEcosystemAdapter,
+    sourceKey: string,
+    destinationKey: string,
+    options: StorageCopyOptions
+): Promise<StorageObjectMetadata> {
+    const source =
+        normalizeStorageKey(
+            sourceKey
+        );
+    const destination =
+        normalizeStorageKey(
+            destinationKey
+        );
+    const sourceMetadata =
+        await requireStorageObject(
+            storage,
+            source
+        );
+
+    if (source === destination) {
+        return sourceMetadata;
+    }
+
+    if (
+        !options.overwrite &&
+        await storage.exists(
+            destination
+        )
+    ) {
+        throw new StorageError(
+            "OBJECT_EXISTS",
+            `BCP Framework: storage object "${destination}" already exists.`,
+            409
+        );
+    }
+
+    const userMetadata =
+        storage.getMetadata
+            ? await storage.getMetadata(
+                source
+            )
+            : {};
+    const stream =
+        await readStorageStream(
+            storage,
+            source
+        );
+    const stored =
+        await putStorageStream(
+            storage,
+            destination,
+            stream,
+            {
+                overwrite:
+                    options.overwrite,
+                contentType:
+                    sourceMetadata.contentType,
+            }
+        );
+
+    if (
+        storage.setMetadata &&
+        Object.keys(
+            userMetadata
+        ).length > 0
+    ) {
+        await storage.setMetadata(
+            destination,
+            userMetadata
+        );
+    }
+
+    return stored;
+}
+
+async function deleteStorageObjectsFallback(
+    storage: StorageAdapter,
+    keys: readonly string[]
+): Promise<StorageDeleteManyResult> {
+    const deleted:
+        string[] = [];
+    const missing:
+        string[] = [];
+    const failed:
+        StorageDeleteManyFailure[] = [];
+    const uniqueKeys =
+        [
+            ...new Set(
+                keys.map(
+                    (key) =>
+                        normalizeStorageKey(
+                            key
+                        )
+                )
+            ),
+        ];
+
+    for (const key of uniqueKeys) {
+        try {
+            if (
+                await storage.delete(
+                    key
+                )
+            ) {
+                deleted.push(
+                    key
+                );
+            } else {
+                missing.push(
+                    key
+                );
+            }
+        } catch (error) {
+            failed.push({
+                key,
+                message:
+                    error instanceof Error
+                        ? error.message
+                        : String(
+                            error
+                        ),
+            });
+        }
+    }
+
+    return {
+        deleted,
+        missing,
+        failed,
+    };
+}
+
+async function requireStorageObject(
+    storage: StorageAdapter,
+    key: string
+): Promise<StorageObjectMetadata> {
+    const metadata =
+        await storage.stat(
+            key
+        );
+
+    if (!metadata) {
+        throw new StorageError(
+            "OBJECT_NOT_FOUND",
+            `BCP Framework: storage object "${key}" was not found.`,
+            404
+        );
+    }
+
+    return metadata;
+}
+
+async function collectLocalObjectKeys(
+    rootDirectory: string
+): Promise<string[]> {
+    const keys:
+        string[] = [];
+
+    const visit =
+        async (
+            directory: string,
+            prefix: string
+        ): Promise<void> => {
+            let entries;
+
+            try {
+                entries =
+                    await readdir(
+                        directory,
+                        {
+                            withFileTypes: true,
+                        }
+                    );
+            } catch (error) {
+                if (
+                    isNodeErrorCode(
+                        error,
+                        "ENOENT"
+                    )
+                ) {
+                    return;
+                }
+
+                throw error;
+            }
+
+            for (const entry of entries) {
+                if (
+                    prefix.length === 0 &&
+                    entry.name ===
+                        LOCAL_METADATA_DIRECTORY
+                ) {
+                    continue;
+                }
+
+                const relative =
+                    prefix.length === 0
+                        ? entry.name
+                        : `${prefix}/${entry.name}`;
+                const fullPath =
+                    path.join(
+                        directory,
+                        entry.name
+                    );
+
+                if (entry.isDirectory()) {
+                    await visit(
+                        fullPath,
+                        relative
+                    );
+                    continue;
+                }
+
+                if (entry.isFile()) {
+                    keys.push(
+                        normalizeStorageKey(
+                            relative
+                        )
+                    );
+                }
+            }
+        };
+
+    await visit(
+        rootDirectory,
+        ""
+    );
+
+    return keys;
+}
+
+async function replaceLocalUserMetadata(
+    metadataDirectory: string,
+    key: string,
+    metadata:
+        StorageUserMetadata |
+        undefined
+): Promise<void> {
+    if (metadata === undefined) {
+        await rm(
+            localUserMetadataFile(
+                metadataDirectory,
+                key
+            ),
+            {
+                force: true,
+            }
+        );
+        return;
+    }
+
+    await writeLocalUserMetadata(
+        metadataDirectory,
+        key,
+        normalizeStorageUserMetadata(
+            metadata
+        )
+    );
+}
+
+async function writeLocalUserMetadata(
+    metadataDirectory: string,
+    key: string,
+    metadata: StorageUserMetadata
+): Promise<void> {
+    await mkdir(
+        metadataDirectory,
+        {
+            recursive: true,
+        }
+    );
+
+    const record:
+        LocalUserMetadataRecord = {
+        version: 1,
+        key,
+        metadata,
+    };
+
+    await writeFile(
+        localUserMetadataFile(
+            metadataDirectory,
+            key
+        ),
+        JSON.stringify(
+            record
+        ),
+        "utf8"
+    );
+}
+
+async function readLocalUserMetadata(
+    metadataDirectory: string,
+    key: string
+): Promise<StorageUserMetadata> {
+    try {
+        const raw =
+            await readFile(
+                localUserMetadataFile(
+                    metadataDirectory,
+                    key
+                ),
+                "utf8"
+            );
+        const parsed =
+            JSON.parse(
+                raw
+            ) as Partial<
+                LocalUserMetadataRecord
+            >;
+
+        if (
+            parsed.version !== 1 ||
+            parsed.key !== key ||
+            parsed.metadata === undefined
+        ) {
+            return {};
+        }
+
+        return normalizeStorageUserMetadata(
+            parsed.metadata
+        );
+    } catch (error) {
+        if (
+            isNodeErrorCode(
+                error,
+                "ENOENT"
+            ) ||
+            error instanceof SyntaxError
+        ) {
+            return {};
+        }
+
+        throw error;
+    }
+}
+
+function localUserMetadataFile(
+    metadataDirectory: string,
+    key: string
+): string {
+    const digest =
+        createHash(
+            "sha256"
+        )
+            .update(
+                key
+            )
+            .digest(
+                "hex"
+            );
+
+    return path.join(
+        metadataDirectory,
+        `${USER_METADATA_PREFIX}${digest}.json`
+    );
+}
+
+function encodeLocalCursor(
+    key: string
+): string {
+    return Buffer.from(
+        key,
+        "utf8"
+    ).toString(
+        "base64url"
+    );
+}
+
+function decodeLocalCursor(
+    cursor: string | undefined
+): string | null {
+    if (cursor === undefined) {
+        return null;
+    }
+
+    try {
+        const key =
+            Buffer.from(
+                cursor,
+                "base64url"
+            ).toString(
+                "utf8"
+            );
+
+        if (
+            key.length === 0 ||
+            encodeLocalCursor(
+                key
+            ) !== cursor
+        ) {
+            throw new Error(
+                "invalid cursor"
+            );
+        }
+
+        return normalizeStorageKey(
+            key
+        );
+    } catch {
+        throw new StorageEcosystemError(
+            "INVALID_CURSOR",
+            "BCP Framework: invalid storage listing cursor."
+        );
+    }
+}
+
+function unsupportedOperation(
+    operation: string
+): StorageEcosystemError {
+    return new StorageEcosystemError(
+        "UNSUPPORTED_OPERATION",
+        `BCP Framework: this storage adapter does not support ${operation}.`,
+        501
+    );
+}
+
+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.trim();
+}
+
+function isNodeErrorCode(
+    error: unknown,
+    code: string
+): boolean {
+    return (
+        error instanceof Error &&
+        "code" in error &&
+        (
+            error as Error & {
+                code?: string;
+            }
+        ).code === code
+    );
+}