@nestm/storage 0.1.0-alpha.0 → 0.1.0-alpha.10

package/dist/files-sdk/fs/index.js

@@ -0,0 +1,1117 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants as fsConstants } from 'node:fs';
+import * as fsp from 'node:fs/promises';
+import path from 'node:path';
+import { Readable } from 'node:stream';
+import { createStoredFile, } from 'files-sdk';
+import { fs } from 'files-sdk/fs';
+import { StorageError, StorageErrorCode } from '../../storage.error.js';
+import { isCanonicalStorageEtag, normalizeProviderStorageEtag, } from '../../storage-etag.js';
+import { createFilesSdkDriver, mapStorageErrorToFilesSdkError, } from '../files-sdk.driver.js';
+const SIDECAR_SUFFIX = '.meta.json';
+const TEMP_SUFFIX = '.fls-part';
+const MAX_SIDECAR_BYTES = 1024 * 1024;
+function storedFileOfStorageObject(object) {
+    return createStoredFile({
+        ...(object.etag !== undefined && { etag: object.etag }),
+        key: object.key,
+        ...(object.lastModified !== undefined && {
+            lastModified: object.lastModified.getTime(),
+        }),
+        ...(object.metadata !== undefined && {
+            metadata: { ...object.metadata },
+        }),
+        size: object.size,
+        type: object.contentType,
+    }, { factory: () => object.body, kind: 'stream' });
+}
+function conditionalUploadResultOf(result) {
+    if (!isCanonicalStorageEtag(result.etag)) {
+        throw new StorageError('A conditional filesystem upload committed without a canonical ETag.', {
+            applied: true,
+            code: StorageErrorCode.PROVIDER,
+            operation: 'upload',
+            permanent: true,
+        });
+    }
+    return {
+        contentType: result.contentType,
+        etag: result.etag,
+        key: result.key,
+        ...(result.lastModified !== undefined && {
+            lastModified: result.lastModified.getTime(),
+        }),
+        size: result.size,
+    };
+}
+function fsErrorCode(error) {
+    if (typeof error === 'object' && error !== null && 'code' in error) {
+        return typeof error.code === 'string' ? error.code : undefined;
+    }
+    return undefined;
+}
+function storageFsError(error, key, operation) {
+    if (error instanceof StorageError) {
+        return error;
+    }
+    const systemCode = fsErrorCode(error);
+    const code = systemCode === 'ENOENT' || systemCode === 'ENOTDIR'
+        ? StorageErrorCode.NOT_FOUND
+        : systemCode === 'EEXIST'
+            ? StorageErrorCode.CONFLICT
+            : systemCode === 'EACCES' || systemCode === 'EPERM'
+                ? StorageErrorCode.UNAUTHORIZED
+                : StorageErrorCode.PROVIDER;
+    return new StorageError(`Filesystem ${operation} failed for "${key}".`, {
+        code,
+        key,
+        operation,
+        permanent: code === StorageErrorCode.NOT_FOUND ||
+            code === StorageErrorCode.CONFLICT ||
+            code === StorageErrorCode.UNAUTHORIZED,
+    });
+}
+function appliedStorageFsError(error, key, operation, appliedEtag) {
+    const mapped = storageFsError(error, key, operation);
+    return new StorageError(mapped.message, {
+        aborted: mapped.aborted,
+        applied: true,
+        ...(appliedEtag !== undefined && { appliedEtag }),
+        code: mapped.code,
+        key: mapped.key ?? key,
+        operation: mapped.operation ?? operation,
+        permanent: true,
+        timedOut: mapped.timedOut,
+    });
+}
+function invalidFsPath(key, message) {
+    throw new StorageError(`Invalid filesystem storage key: ${message}.`, {
+        code: StorageErrorCode.INVALID_ARGUMENT,
+        key,
+        permanent: true,
+    });
+}
+function strictSegments(key) {
+    if (key.length === 0 || key.includes('\0')) {
+        invalidFsPath(key, 'the key is empty or contains a null byte');
+    }
+    if (path.isAbsolute(key) || key.includes('\\')) {
+        invalidFsPath(key, 'only relative POSIX paths are accepted');
+    }
+    const segments = key.split('/');
+    if (segments.some((segment) => segment.length === 0 || segment === '.' || segment === '..')) {
+        invalidFsPath(key, 'empty, dot, and parent segments are not accepted');
+    }
+    if (segments.some((segment) => /[. ]$/u.test(segment))) {
+        invalidFsPath(key, 'segments ending in a dot or space are not accepted');
+    }
+    const leaf = segments.at(-1)?.toLowerCase() ?? '';
+    if (leaf.endsWith(SIDECAR_SUFFIX) || leaf.endsWith(TEMP_SUFFIX)) {
+        invalidFsPath(key, 'the final segment uses a reserved adapter suffix');
+    }
+    return segments;
+}
+function symlinkError(key) {
+    return new StorageError(`Filesystem storage key "${key}" crosses a symbolic link.`, {
+        code: StorageErrorCode.INVALID_ARGUMENT,
+        key,
+        permanent: true,
+    });
+}
+function unsupportedUpload(key, message) {
+    throw new StorageError(message, {
+        code: StorageErrorCode.NOT_SUPPORTED,
+        key,
+        operation: 'upload',
+        permanent: true,
+    });
+}
+function conflict(key) {
+    throw new StorageError(`Conditional mutation conflicted for "${key}".`, {
+        code: StorageErrorCode.CONFLICT,
+        key,
+        permanent: true,
+    });
+}
+function notFound(key) {
+    throw new StorageError(`Storage object "${key}" was not found.`, {
+        code: StorageErrorCode.NOT_FOUND,
+        key,
+        permanent: true,
+    });
+}
+function runtimeOf(options) {
+    const timeoutSignal = options.timeout === undefined || options.timeout <= 0
+        ? undefined
+        : AbortSignal.timeout(options.timeout);
+    return {
+        callerSignal: options.signal,
+        signal: options.signal === undefined
+            ? timeoutSignal
+            : timeoutSignal === undefined
+                ? options.signal
+                : AbortSignal.any([options.signal, timeoutSignal]),
+        timeoutSignal,
+    };
+}
+function assertActive(runtime, key) {
+    if (runtime.signal?.aborted !== true) {
+        return;
+    }
+    const timedOut = runtime.timeoutSignal?.aborted === true &&
+        runtime.callerSignal?.aborted !== true;
+    throw new StorageError(timedOut
+        ? `Filesystem mutation timed out for "${key}".`
+        : `Filesystem mutation was aborted for "${key}".`, {
+        aborted: true,
+        code: timedOut ? StorageErrorCode.TIMEOUT : StorageErrorCode.ABORTED,
+        key,
+        permanent: true,
+        timedOut,
+    });
+}
+async function ensureRoot(root, key) {
+    await fsp.mkdir(root, { mode: 0o700, recursive: true });
+    const stat = await fsp.lstat(root);
+    if (stat.isSymbolicLink()) {
+        throw symlinkError(key);
+    }
+    if (!stat.isDirectory()) {
+        invalidFsPath(key, 'the configured root is not a directory');
+    }
+}
+async function ensureParents(root, segments, key, create, runtime) {
+    await ensureRoot(root, key);
+    let current = root;
+    for (const segment of segments.slice(0, -1)) {
+        assertActive(runtime, key);
+        current = path.join(current, segment);
+        let stat;
+        try {
+            stat = await fsp.lstat(current);
+        }
+        catch (error) {
+            if (fsErrorCode(error) !== 'ENOENT') {
+                throw error;
+            }
+            if (!create) {
+                notFound(key);
+            }
+            try {
+                await fsp.mkdir(current, { mode: 0o700 });
+            }
+            catch (mkdirError) {
+                if (fsErrorCode(mkdirError) !== 'EEXIST') {
+                    throw mkdirError;
+                }
+            }
+            stat = await fsp.lstat(current);
+        }
+        if (stat.isSymbolicLink()) {
+            throw symlinkError(key);
+        }
+        if (!stat.isDirectory()) {
+            invalidFsPath(key, 'a parent segment is not a directory');
+        }
+    }
+    return path.join(root, ...segments);
+}
+async function regularFileOrMissing(target, key) {
+    try {
+        const stat = await fsp.lstat(target);
+        if (stat.isSymbolicLink()) {
+            throw symlinkError(key);
+        }
+        if (!stat.isFile()) {
+            invalidFsPath(key, 'an object path is not a regular file');
+        }
+        if (stat.nlink !== 1) {
+            invalidFsPath(key, 'hard-linked object files are not accepted');
+        }
+        return stat;
+    }
+    catch (error) {
+        if (fsErrorCode(error) === 'ENOENT') {
+            return undefined;
+        }
+        throw error;
+    }
+}
+async function assertSymlinkFreeReadPath(root, key) {
+    const segments = strictSegments(key);
+    let rootStat;
+    try {
+        rootStat = await fsp.lstat(root);
+    }
+    catch (error) {
+        if (fsErrorCode(error) === 'ENOENT') {
+            return;
+        }
+        throw error;
+    }
+    if (rootStat.isSymbolicLink()) {
+        throw symlinkError(key);
+    }
+    if (!rootStat.isDirectory()) {
+        invalidFsPath(key, 'the configured root is not a directory');
+    }
+    let current = root;
+    for (const [index, segment] of segments.entries()) {
+        current = path.join(current, segment);
+        let stat;
+        try {
+            stat = await fsp.lstat(current);
+        }
+        catch (error) {
+            if (fsErrorCode(error) === 'ENOENT') {
+                return;
+            }
+            throw error;
+        }
+        if (stat.isSymbolicLink()) {
+            throw symlinkError(key);
+        }
+        const leaf = index === segments.length - 1;
+        if ((!leaf && !stat.isDirectory()) || (leaf && !stat.isFile())) {
+            invalidFsPath(key, leaf
+                ? 'an object path is not a regular file'
+                : 'a parent segment is not a directory');
+        }
+        if (leaf && stat.nlink !== 1) {
+            invalidFsPath(key, 'hard-linked object files are not accepted');
+        }
+    }
+    const sidecar = await regularFileOrMissing(current + SIDECAR_SUFFIX, key);
+    if (sidecar?.isSymbolicLink()) {
+        throw symlinkError(key);
+    }
+}
+async function readSidecar(target, key) {
+    const handle = await fsp.open(target, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.size > MAX_SIDECAR_BYTES) {
+            throw new StorageError(`Filesystem metadata is invalid for "${key}".`, {
+                code: StorageErrorCode.PROVIDER,
+                key,
+                permanent: true,
+            });
+        }
+        const parsed = JSON.parse(await handle.readFile('utf8'));
+        if (typeof parsed !== 'object' ||
+            parsed === null ||
+            !('etag' in parsed) ||
+            typeof parsed.etag !== 'string' ||
+            !('contentType' in parsed) ||
+            typeof parsed.contentType !== 'string' ||
+            !('lastModified' in parsed) ||
+            typeof parsed.lastModified !== 'number') {
+            throw new StorageError(`Filesystem metadata is invalid for "${key}".`, {
+                code: StorageErrorCode.PROVIDER,
+                key,
+                permanent: true,
+            });
+        }
+        const sidecar = parsed;
+        const etag = normalizeProviderStorageEtag(sidecar.etag);
+        if (etag === undefined) {
+            throw new StorageError(`Filesystem metadata is invalid for "${key}".`, {
+                code: StorageErrorCode.PROVIDER,
+                key,
+                permanent: true,
+            });
+        }
+        return { ...sidecar, etag };
+    }
+    finally {
+        await handle.close();
+    }
+}
+function bodyBytes(body) {
+    if (typeof body === 'string') {
+        return new TextEncoder().encode(body);
+    }
+    if (body instanceof Uint8Array) {
+        return body;
+    }
+    if (body instanceof ArrayBuffer) {
+        return new Uint8Array(body);
+    }
+    if (ArrayBuffer.isView(body)) {
+        return new Uint8Array(body.buffer, body.byteOffset, body.byteLength);
+    }
+    return undefined;
+}
+function defaultContentType(body, override) {
+    if (override !== undefined) {
+        return override;
+    }
+    if (typeof body === 'string') {
+        return 'text/plain; charset=utf-8';
+    }
+    if (body instanceof Blob && body.type.length > 0) {
+        return body.type;
+    }
+    return 'application/octet-stream';
+}
+async function writeAll(handle, bytes) {
+    let offset = 0;
+    while (offset < bytes.byteLength) {
+        const { bytesWritten } = await handle.write(bytes, offset, bytes.byteLength - offset);
+        offset += bytesWritten;
+    }
+}
+function tempPath(directory) {
+    return path.join(directory, `.nestm-${randomUUID()}${TEMP_SUFFIX}`);
+}
+async function openTemp(directory) {
+    const target = tempPath(directory);
+    const handle = await fsp.open(target, fsConstants.O_CREAT |
+        fsConstants.O_EXCL |
+        fsConstants.O_WRONLY |
+        fsConstants.O_NOFOLLOW, 0o600);
+    return { handle, path: target };
+}
+async function removeTemp(target) {
+    if (target === undefined) {
+        return;
+    }
+    try {
+        await fsp.unlink(target);
+    }
+    catch (error) {
+        if (fsErrorCode(error) !== 'ENOENT') {
+            throw error;
+        }
+    }
+}
+async function stageBody(directory, key, body, options, runtime) {
+    const staged = await openTemp(directory);
+    const hash = createHash('sha256');
+    let size = 0;
+    const knownBytes = bodyBytes(body);
+    const knownSize = knownBytes?.byteLength ?? (body instanceof Blob ? body.size : undefined);
+    options.onProgress?.({
+        loaded: 0,
+        ...(knownSize !== undefined && { total: knownSize }),
+    });
+    try {
+        if (knownBytes !== undefined) {
+            assertActive(runtime, key);
+            await writeAll(staged.handle, knownBytes);
+            hash.update(knownBytes);
+            size = knownBytes.byteLength;
+            options.onProgress?.({ loaded: size, total: size });
+        }
+        else if (body instanceof Blob) {
+            const bytes = new Uint8Array(await body.arrayBuffer());
+            assertActive(runtime, key);
+            await writeAll(staged.handle, bytes);
+            hash.update(bytes);
+            size = bytes.byteLength;
+            options.onProgress?.({ loaded: size, total: size });
+        }
+        else {
+            const reader = body.getReader();
+            try {
+                while (true) {
+                    assertActive(runtime, key);
+                    const chunk = await reader.read();
+                    if (chunk.done) {
+                        break;
+                    }
+                    await writeAll(staged.handle, chunk.value);
+                    hash.update(chunk.value);
+                    size += chunk.value.byteLength;
+                    options.onProgress?.({ loaded: size });
+                }
+            }
+            catch (error) {
+                await reader.cancel(error).catch(() => undefined);
+                throw error;
+            }
+            finally {
+                reader.releaseLock();
+            }
+        }
+        await staged.handle.sync();
+        await staged.handle.close();
+        return {
+            etag: hash.digest('hex'),
+            path: staged.path,
+            size,
+        };
+    }
+    catch (error) {
+        await staged.handle.close().catch(() => undefined);
+        await removeTemp(staged.path).catch(() => undefined);
+        throw error;
+    }
+}
+async function stageSidecar(directory, sidecar) {
+    const staged = await openTemp(directory);
+    try {
+        await writeAll(staged.handle, new TextEncoder().encode(JSON.stringify(sidecar)));
+        await staged.handle.sync();
+        await staged.handle.close();
+        return staged.path;
+    }
+    catch (error) {
+        await staged.handle.close().catch(() => undefined);
+        await removeTemp(staged.path).catch(() => undefined);
+        throw error;
+    }
+}
+const CONDITIONAL_FS_TAILS = new Map();
+async function serializeFsKey(lockKey, operation, wait) {
+    const previous = CONDITIONAL_FS_TAILS.get(lockKey) ?? Promise.resolve();
+    let release = () => undefined;
+    const gate = new Promise((resolve) => {
+        release = resolve;
+    });
+    const tail = previous.then(() => gate);
+    CONDITIONAL_FS_TAILS.set(lockKey, tail);
+    let acquired = false;
+    try {
+        if (wait === undefined || wait.runtime.signal === undefined) {
+            await previous;
+        }
+        else {
+            const signal = wait.runtime.signal;
+            await new Promise((resolve, reject) => {
+                const cleanup = () => signal.removeEventListener('abort', abort);
+                const abort = () => {
+                    cleanup();
+                    try {
+                        assertActive(wait.runtime, wait.key);
+                    }
+                    catch (error) {
+                        reject(error);
+                    }
+                };
+                signal.addEventListener('abort', abort, { once: true });
+                if (signal.aborted) {
+                    abort();
+                    return;
+                }
+                void previous.then(() => {
+                    cleanup();
+                    resolve();
+                }, (error) => {
+                    cleanup();
+                    reject(error);
+                });
+            });
+        }
+        acquired = true;
+        return await operation();
+    }
+    finally {
+        release();
+        if (acquired) {
+            if (CONDITIONAL_FS_TAILS.get(lockKey) === tail) {
+                CONDITIONAL_FS_TAILS.delete(lockKey);
+            }
+        }
+        else {
+            void tail.then(() => {
+                if (CONDITIONAL_FS_TAILS.get(lockKey) === tail) {
+                    CONDITIONAL_FS_TAILS.delete(lockKey);
+                }
+            });
+        }
+    }
+}
+/**
+ * Adds symlink-defended reads and process-local exact conditional operations
+ * to a files-sdk fs adapter.
+ *
+ * The configured root must be dedicated to this decorated adapter: no other
+ * process, unwrapped adapter, or direct filesystem writer may mutate it
+ * concurrently. Ordinary adapter mutations and conditional operations share
+ * one process-local lock domain. Each call rejects symlinks in the existing key
+ * path and uses exclusive same-directory temporary files plus atomic renames,
+ * but Node has no portable `openat2` equivalent that could make those checks
+ * safe against a hostile concurrent tree rewrite. This is a CAS implementation
+ * for an exclusively-owned local workspace, not a host-filesystem sandbox.
+ * Body and metadata sidecars are two files, so a process crash between their
+ * renames can still require cleanup.
+ */
+export function withFsConditionalMutation(base) {
+    const root = path.resolve(base.root);
+    const copy = base.copy.bind(base);
+    const deleteObject = base.delete.bind(base);
+    const download = base.download.bind(base);
+    const exists = base.exists.bind(base);
+    const head = base.head.bind(base);
+    const list = base.list.bind(base);
+    const move = base.move?.bind(base);
+    const resumableUpload = base.resumableUpload?.bind(base);
+    const upload = base.upload.bind(base);
+    const identity = (key) => path.resolve(root, key).normalize('NFC').toLowerCase();
+    const serialize = (key, operation, runtime) => serializeFsKey(identity(key), operation, runtime === undefined ? undefined : { key, runtime });
+    const serializeMutationPair = (first, second, operation, runtime) => {
+        const firstIdentity = identity(first);
+        const secondIdentity = identity(second);
+        if (firstIdentity === secondIdentity) {
+            return serialize(first, operation, runtime);
+        }
+        const [headKey, tailKey] = firstIdentity < secondIdentity ? [first, second] : [second, first];
+        return serialize(headKey, () => serialize(tailKey, operation, runtime), runtime);
+    };
+    const serializePair = (first, second, operation, runtime) => {
+        if (identity(first) === identity(second)) {
+            throw new StorageError('Conditional filesystem copy requires distinct source and destination keys.', {
+                code: StorageErrorCode.INVALID_ARGUMENT,
+                key: first,
+                operation: 'copy',
+                permanent: true,
+            });
+        }
+        return serializeMutationPair(first, second, operation, runtime);
+    };
+    const serializeFilesMutation = async (key, options, operation) => {
+        const runtime = runtimeOf(options ?? {});
+        try {
+            return await serialize(key, operation, runtime);
+        }
+        catch (error) {
+            throw mapStorageErrorToFilesSdkError(error);
+        }
+    };
+    const serializeFilesMutationPair = async (first, second, options, operation) => {
+        const runtime = runtimeOf(options ?? {});
+        try {
+            return await serializeMutationPair(first, second, operation, runtime);
+        }
+        catch (error) {
+            throw mapStorageErrorToFilesSdkError(error);
+        }
+    };
+    const assertEtag = (value, label, key, operation) => {
+        if (!isCanonicalStorageEtag(value)) {
+            throw new StorageError(`${label} must be a canonical storage ETag.`, {
+                code: StorageErrorCode.INVALID_ARGUMENT,
+                key,
+                operation,
+                permanent: true,
+            });
+        }
+    };
+    const adapter = Object.assign(base, {
+        conditionalCreate: Object.freeze({ resultEtag: true }),
+        conditionalReplace: Object.freeze({ resultEtag: true }),
+        conditionalDelete: Object.freeze({ etag: true }),
+        conditionalRead: Object.freeze({ etag: true, version: false }),
+        conditionalCopySource: Object.freeze({ etag: true, version: false }),
+        conditionalCopyDestination: Object.freeze({
+            atomicWithSource: true,
+            create: true,
+            replace: true,
+        }),
+        physicalKey: Object.freeze({ maxBytes: 4096 }),
+        async copy(from, to, options) {
+            return serializeFilesMutationPair(from, to, options, () => copy(from, to, options));
+        },
+        async delete(key, options) {
+            return serializeFilesMutation(key, options, () => deleteObject(key, options));
+        },
+        async download(key, options) {
+            await assertSymlinkFreeReadPath(root, key);
+            return download(key, options);
+        },
+        async downloadConditional(key, options) {
+            if (typeof options !== 'object' ||
+                options === null ||
+                typeof options.condition !== 'object' ||
+                options.condition === null ||
+                (options.condition.etag === undefined &&
+                    options.condition.version === undefined)) {
+                throw new StorageError('A conditional filesystem read requires an ETag or version.', {
+                    code: StorageErrorCode.INVALID_ARGUMENT,
+                    key,
+                    operation: 'download',
+                    permanent: true,
+                });
+            }
+            if (options.condition.etag !== undefined) {
+                assertEtag(options.condition.etag, 'condition.etag', key, 'download');
+            }
+            if (options.condition.version !== undefined) {
+                throw new StorageError('The filesystem provider has no immutable object versions.', {
+                    code: StorageErrorCode.NOT_SUPPORTED,
+                    key,
+                    operation: 'download',
+                    permanent: true,
+                });
+            }
+            const runtime = runtimeOf(options);
+            return serialize(key, async () => {
+                let handle;
+                try {
+                    const segments = strictSegments(key);
+                    const bodyPath = await ensureParents(root, segments, key, false, runtime);
+                    const sidecarPath = bodyPath + SIDECAR_SUFFIX;
+                    if ((await regularFileOrMissing(bodyPath, key)) === undefined ||
+                        (await regularFileOrMissing(sidecarPath, key)) === undefined) {
+                        notFound(key);
+                    }
+                    const sidecar = await readSidecar(sidecarPath, key);
+                    if (options.condition.etag !== undefined &&
+                        sidecar.etag !== options.condition.etag) {
+                        conflict(key);
+                    }
+                    assertActive(runtime, key);
+                    handle = await fsp.open(bodyPath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+                    const stat = await handle.stat();
+                    if (!stat.isFile() || stat.nlink !== 1) {
+                        invalidFsPath(key, 'an object path is not a regular file');
+                    }
+                    const start = options.range?.start ?? 0;
+                    const requestedEnd = options.range?.end ?? Math.max(0, stat.size - 1);
+                    const end = Math.min(requestedEnd, Math.max(0, stat.size - 1));
+                    const size = start >= stat.size ? 0 : Math.max(0, end - start + 1);
+                    if (size === 0) {
+                        await handle.close();
+                        handle = undefined;
+                        return {
+                            body: new ReadableStream({
+                                start(controller) {
+                                    controller.close();
+                                },
+                            }),
+                            contentType: sidecar.contentType,
+                            etag: sidecar.etag,
+                            key,
+                            lastModified: new Date(sidecar.lastModified),
+                            ...(sidecar.metadata !== undefined && {
+                                metadata: { ...sidecar.metadata },
+                            }),
+                            name: path.basename(key),
+                            size: 0,
+                        };
+                    }
+                    const nodeStream = handle.createReadStream({
+                        autoClose: true,
+                        ...(options.range !== undefined && { end, start }),
+                    });
+                    handle = undefined;
+                    return {
+                        body: Readable.toWeb(nodeStream),
+                        contentType: sidecar.contentType,
+                        etag: sidecar.etag,
+                        key,
+                        lastModified: new Date(sidecar.lastModified),
+                        ...(sidecar.metadata !== undefined && {
+                            metadata: { ...sidecar.metadata },
+                        }),
+                        name: path.basename(key),
+                        size,
+                    };
+                }
+                catch (error) {
+                    await handle?.close().catch(() => undefined);
+                    throw storageFsError(error, key, 'download');
+                }
+            }, runtime);
+        },
+        async exists(key, options) {
+            await assertSymlinkFreeReadPath(root, key);
+            return exists(key, options);
+        },
+        async head(key, options) {
+            await assertSymlinkFreeReadPath(root, key);
+            return head(key, options);
+        },
+        async list(options) {
+            const result = await list(options);
+            for (const item of result.items) {
+                await assertSymlinkFreeReadPath(root, item.key);
+            }
+            return result;
+        },
+        async move(from, to, options) {
+            return serializeFilesMutationPair(from, to, options, async () => {
+                if (move !== undefined) {
+                    return move(from, to, options);
+                }
+                await copy(from, to, options);
+                await deleteObject(from, options);
+            });
+        },
+        async deleteConditional(key, options) {
+            if (typeof options !== 'object' ||
+                options === null ||
+                typeof options.condition !== 'object' ||
+                options.condition === null) {
+                throw new StorageError('A conditional filesystem delete requires an ETag.', {
+                    code: StorageErrorCode.INVALID_ARGUMENT,
+                    key,
+                    operation: 'delete',
+                    permanent: true,
+                });
+            }
+            assertEtag(options.condition.etag, 'condition.etag', key, 'delete');
+            const runtime = runtimeOf(options);
+            return serialize(key, async () => {
+                let applied = false;
+                try {
+                    const segments = strictSegments(key);
+                    const bodyPath = await ensureParents(root, segments, key, false, runtime);
+                    const sidecarPath = bodyPath + SIDECAR_SUFFIX;
+                    if ((await regularFileOrMissing(bodyPath, key)) === undefined ||
+                        (await regularFileOrMissing(sidecarPath, key)) === undefined) {
+                        notFound(key);
+                    }
+                    const sidecar = await readSidecar(sidecarPath, key);
+                    if (sidecar.etag !== options.condition.etag) {
+                        conflict(key);
+                    }
+                    assertActive(runtime, key);
+                    await ensureParents(root, segments, key, false, runtime);
+                    if ((await regularFileOrMissing(bodyPath, key)) === undefined ||
+                        (await regularFileOrMissing(sidecarPath, key)) === undefined ||
+                        (await readSidecar(sidecarPath, key)).etag !==
+                            options.condition.etag) {
+                        conflict(key);
+                    }
+                    await fsp.unlink(bodyPath);
+                    applied = true;
+                    await fsp.unlink(sidecarPath);
+                }
+                catch (error) {
+                    throw applied
+                        ? appliedStorageFsError(error, key, 'delete')
+                        : storageFsError(error, key, 'delete');
+                }
+            }, runtime);
+        },
+        async promote(sourceKey, destinationKey, options) {
+            if (typeof options !== 'object' || options === null) {
+                throw new StorageError('A conditional filesystem copy requires a predicate.', {
+                    code: StorageErrorCode.INVALID_ARGUMENT,
+                    key: sourceKey,
+                    operation: 'copy',
+                    permanent: true,
+                });
+            }
+            const destination = options.destination;
+            if (destination !== undefined &&
+                (typeof destination !== 'object' ||
+                    destination === null ||
+                    (destination.type !== 'create' && destination.type !== 'replace'))) {
+                throw new StorageError('destination.type must be "create" or "replace".', {
+                    code: StorageErrorCode.INVALID_ARGUMENT,
+                    key: destinationKey,
+                    operation: 'copy',
+                    permanent: true,
+                });
+            }
+            if (options.sourceEtag === undefined &&
+                options.sourceVersion === undefined &&
+                destination === undefined) {
+                throw new StorageError('A conditional filesystem copy requires a source or destination predicate.', {
+                    code: StorageErrorCode.INVALID_ARGUMENT,
+                    key: sourceKey,
+                    operation: 'copy',
+                    permanent: true,
+                });
+            }
+            if (options.sourceEtag !== undefined) {
+                assertEtag(options.sourceEtag, 'sourceEtag', sourceKey, 'copy');
+            }
+            if (destination?.type === 'replace') {
+                assertEtag(destination.etag, 'destination.etag', destinationKey, 'copy');
+            }
+            if (options.sourceVersion !== undefined) {
+                throw new StorageError('The filesystem provider has no immutable object versions.', {
+                    code: StorageErrorCode.NOT_SUPPORTED,
+                    key: sourceKey,
+                    operation: 'copy',
+                    permanent: true,
+                });
+            }
+            const runtime = runtimeOf(options);
+            return serializePair(sourceKey, destinationKey, async () => {
+                let applied = false;
+                let bodyTemp;
+                let sidecarTemp;
+                try {
+                    const sourceSegments = strictSegments(sourceKey);
+                    const destinationSegments = strictSegments(destinationKey);
+                    const sourcePath = await ensureParents(root, sourceSegments, sourceKey, false, runtime);
+                    const sourceSidecarPath = sourcePath + SIDECAR_SUFFIX;
+                    if ((await regularFileOrMissing(sourcePath, sourceKey)) ===
+                        undefined ||
+                        (await regularFileOrMissing(sourceSidecarPath, sourceKey)) ===
+                            undefined) {
+                        notFound(sourceKey);
+                    }
+                    const sourceSidecar = await readSidecar(sourceSidecarPath, sourceKey);
+                    if (options.sourceEtag !== undefined &&
+                        sourceSidecar.etag !== options.sourceEtag) {
+                        conflict(sourceKey);
+                    }
+                    const destinationPath = await ensureParents(root, destinationSegments, destinationKey, true, runtime);
+                    const destinationSidecarPath = destinationPath + SIDECAR_SUFFIX;
+                    const assertDestination = async () => {
+                        const body = await regularFileOrMissing(destinationPath, destinationKey);
+                        const sidecar = await regularFileOrMissing(destinationSidecarPath, destinationKey);
+                        if (options.destination?.type === 'create') {
+                            if (body !== undefined || sidecar !== undefined) {
+                                conflict(destinationKey);
+                            }
+                            return;
+                        }
+                        if (options.destination?.type === 'replace') {
+                            if (body === undefined || sidecar === undefined) {
+                                notFound(destinationKey);
+                            }
+                            if ((await readSidecar(destinationSidecarPath, destinationKey))
+                                .etag !== options.destination.etag) {
+                                conflict(destinationKey);
+                            }
+                        }
+                    };
+                    await assertDestination();
+                    const staged = await openTemp(path.dirname(destinationPath));
+                    await staged.handle.close();
+                    bodyTemp = staged.path;
+                    await fsp.copyFile(sourcePath, bodyTemp);
+                    const lastModified = Date.now();
+                    sidecarTemp = await stageSidecar(path.dirname(destinationPath), {
+                        ...sourceSidecar,
+                        lastModified,
+                    });
+                    assertActive(runtime, sourceKey);
+                    if ((await regularFileOrMissing(sourcePath, sourceKey)) ===
+                        undefined ||
+                        (await regularFileOrMissing(sourceSidecarPath, sourceKey)) ===
+                            undefined ||
+                        (options.sourceEtag !== undefined &&
+                            (await readSidecar(sourceSidecarPath, sourceKey)).etag !==
+                                options.sourceEtag)) {
+                        conflict(sourceKey);
+                    }
+                    await assertDestination();
+                    await fsp.rename(bodyTemp, destinationPath);
+                    applied = true;
+                    bodyTemp = undefined;
+                    await fsp.rename(sidecarTemp, destinationSidecarPath);
+                    sidecarTemp = undefined;
+                }
+                catch (error) {
+                    throw applied
+                        ? appliedStorageFsError(error, destinationKey, 'copy')
+                        : storageFsError(error, sourceKey, 'copy');
+                }
+                finally {
+                    await removeTemp(bodyTemp).catch(() => undefined);
+                    await removeTemp(sidecarTemp).catch(() => undefined);
+                }
+            }, runtime);
+        },
+        async uploadConditional(key, body, options) {
+            if (typeof options !== 'object' ||
+                options === null ||
+                typeof options.condition !== 'object' ||
+                options.condition === null ||
+                (options.condition.type !== 'create' &&
+                    options.condition.type !== 'replace')) {
+                throw new StorageError('A conditional filesystem upload requires a create or replace predicate.', {
+                    code: StorageErrorCode.INVALID_ARGUMENT,
+                    key,
+                    operation: 'upload',
+                    permanent: true,
+                });
+            }
+            if (options.condition.type === 'replace') {
+                assertEtag(options.condition.etag, 'condition.etag', key, 'upload');
+            }
+            const runtime = runtimeOf(options);
+            return serialize(key, async () => {
+                let applied = false;
+                let appliedEtag;
+                let bodyTemp;
+                let sidecarTemp;
+                try {
+                    if (options.multipart !== undefined &&
+                        options.multipart !== false) {
+                        unsupportedUpload(key, 'Conditional filesystem uploads do not support multipart mode.');
+                    }
+                    if (options.control !== undefined) {
+                        unsupportedUpload(key, 'Conditional filesystem uploads do not support resumable control.');
+                    }
+                    const segments = strictSegments(key);
+                    const bodyPath = await ensureParents(root, segments, key, true, runtime);
+                    const sidecarPath = bodyPath + SIDECAR_SUFFIX;
+                    const existingBody = await regularFileOrMissing(bodyPath, key);
+                    const existingSidecar = await regularFileOrMissing(sidecarPath, key);
+                    if (options.condition.type === 'create') {
+                        if (existingBody !== undefined || existingSidecar !== undefined) {
+                            conflict(key);
+                        }
+                    }
+                    else {
+                        if (existingBody === undefined || existingSidecar === undefined) {
+                            notFound(key);
+                        }
+                        if ((await readSidecar(sidecarPath, key)).etag !==
+                            options.condition.etag) {
+                            conflict(key);
+                        }
+                    }
+                    const staged = await stageBody(path.dirname(bodyPath), key, body, options, runtime);
+                    bodyTemp = staged.path;
+                    const lastModified = Date.now();
+                    const contentType = defaultContentType(body, options.contentType);
+                    sidecarTemp = await stageSidecar(path.dirname(bodyPath), {
+                        contentType,
+                        etag: staged.etag,
+                        lastModified,
+                        ...(options.cacheControl !== undefined && {
+                            cacheControl: options.cacheControl,
+                        }),
+                        ...(options.metadata !== undefined && {
+                            metadata: options.metadata,
+                        }),
+                    });
+                    assertActive(runtime, key);
+                    await ensureParents(root, segments, key, false, runtime);
+                    const currentBody = await regularFileOrMissing(bodyPath, key);
+                    const currentSidecar = await regularFileOrMissing(sidecarPath, key);
+                    if (options.condition.type === 'create') {
+                        if (currentBody !== undefined || currentSidecar !== undefined) {
+                            conflict(key);
+                        }
+                    }
+                    else if (currentBody === undefined ||
+                        currentSidecar === undefined ||
+                        (await readSidecar(sidecarPath, key)).etag !==
+                            options.condition.etag) {
+                        conflict(key);
+                    }
+                    await fsp.rename(bodyTemp, bodyPath);
+                    applied = true;
+                    appliedEtag = staged.etag;
+                    bodyTemp = undefined;
+                    await fsp.rename(sidecarTemp, sidecarPath);
+                    sidecarTemp = undefined;
+                    return {
+                        contentType,
+                        etag: staged.etag,
+                        key,
+                        lastModified: new Date(lastModified),
+                        size: staged.size,
+                    };
+                }
+                catch (error) {
+                    throw applied
+                        ? appliedStorageFsError(error, key, 'upload', appliedEtag)
+                        : storageFsError(error, key, 'upload');
+                }
+                finally {
+                    await removeTemp(bodyTemp).catch(() => undefined);
+                    await removeTemp(sidecarTemp).catch(() => undefined);
+                }
+            }, runtime);
+        },
+        async upload(key, body, options) {
+            return serializeFilesMutation(key, options, () => upload(key, body, options));
+        },
+    });
+    if (resumableUpload !== undefined) {
+        adapter.resumableUpload = (key, options) => {
+            const resumable = resumableUpload(key, options);
+            const complete = resumable.complete.bind(resumable);
+            resumable.complete = (parts) => serialize(key, () => complete(parts));
+            return resumable;
+        };
+    }
+    const operationOptions = (options) => ({
+        ...(options?.signal !== undefined && { signal: options.signal }),
+        ...(options?.timeout !== undefined && { timeout: options.timeout }),
+    });
+    const uploadOptions = (options) => ({
+        ...operationOptions(options),
+        ...(options?.cacheControl !== undefined && {
+            cacheControl: options.cacheControl,
+        }),
+        ...(options?.contentType !== undefined && {
+            contentType: options.contentType,
+        }),
+        ...(options?.metadata !== undefined && {
+            metadata: { ...options.metadata },
+        }),
+        ...(options?.onProgress !== undefined && {
+            onProgress: options.onProgress,
+        }),
+    });
+    const downloadOptions = (options) => ({
+        ...operationOptions(options),
+        ...(options?.range !== undefined && { range: { ...options.range } }),
+    });
+    const runConditional = async (operation) => {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            throw mapStorageErrorToFilesSdkError(error);
+        }
+    };
+    const conditional = Object.freeze({
+        copy: Object.freeze({
+            atomicSourceDestination: true,
+            destinationCreate: true,
+            destinationReplace: true,
+            run: (sourceKey, destinationKey, condition, options) => runConditional(() => adapter.promote(sourceKey, destinationKey, {
+                ...operationOptions(options),
+                destination: condition.destination,
+                sourceEtag: condition.source.etag,
+            })),
+            sourceEtag: true,
+        }),
+        create: (key, body, options) => runConditional(async () => conditionalUploadResultOf(await adapter.uploadConditional(key, body, {
+            ...uploadOptions(options),
+            condition: { type: 'create' },
+        }))),
+        delete: (key, etag, options) => runConditional(() => adapter.deleteConditional(key, {
+            ...operationOptions(options),
+            condition: { etag },
+        })),
+        exactRead: (key, etag, options) => runConditional(async () => storedFileOfStorageObject(await adapter.downloadConditional(key, {
+            ...downloadOptions(options),
+            condition: { etag },
+        }))),
+        replace: (key, body, etag, options) => runConditional(async () => conditionalUploadResultOf(await adapter.uploadConditional(key, body, {
+            ...uploadOptions(options),
+            condition: { etag, type: 'replace' },
+        }))),
+    });
+    return Object.assign(adapter, { conditional });
+}
+/**
+ * Creates the files-sdk filesystem driver from the storage package's own
+ * dependency context. The adapter reaches only `node:fs`, so this entry point
+ * adds no native SDK to the install — unlike every object-store provider, it is
+ * always available.
+ *
+ * The adapter keeps a `<key>.meta.json` sidecar beside each body to carry the
+ * content type, ETag, and custom metadata that a filesystem has nowhere else to
+ * put. Sidecars never surface as keys: `list` and `search` skip them, and
+ * uploading a key that ends in `.meta.json` fails closed rather than colliding
+ * with one.
+ *
+ * Conditional mutations additionally require an exclusively-owned root. See
+ * {@link withFsConditionalMutation}; use an OS sandbox as well when running an
+ * agent that has direct shell or filesystem tools.
+ */
+export function createFsStorageDriver(options) {
+    const { adapter: adapterOptions, ...filesOptions } = options;
+    return createFilesSdkDriver({
+        ...filesOptions,
+        adapter: withFsConditionalMutation(fs(adapterOptions)),
+    });
+}
+export { fs, mapFsError } from 'files-sdk/fs';
+//# sourceMappingURL=index.js.map