@superfunctions/storage-local 0.1.0

package/dist/adapter.d.ts

@@ -0,0 +1,5 @@
+import type { StorageAdapter } from '@superfunctions/storage';
+export interface LocalStorageConfig {
+    rootDir: string;
+}
+export declare function createLocalStorageAdapter(config: LocalStorageConfig): StorageAdapter;

package/dist/adapter.js

@@ -0,0 +1,246 @@
+import { createReadStream, createWriteStream } from 'node:fs';
+import { mkdir, lstat, stat, unlink, realpath } from 'node:fs/promises';
+import { dirname, join, normalize, resolve, isAbsolute, relative } from 'node:path';
+import { createNotFoundError } from '@superfunctions/storage/internal/errors';
+export function createLocalStorageAdapter(config) {
+    const { rootDir } = config;
+    const normalizedRoot = resolve(normalize(rootDir));
+    let resolvedRoot = null;
+    async function getResolvedRoot() {
+        if (resolvedRoot === null) {
+            try {
+                resolvedRoot = await realpath(normalizedRoot);
+            }
+            catch {
+                resolvedRoot = normalizedRoot;
+            }
+        }
+        return resolvedRoot;
+    }
+    const capabilities = {
+        signedUploadUrls: false,
+        signedDownloadUrls: false,
+        multipart: false,
+        proxyStreamingUpload: true,
+        proxyStreamingDownload: true,
+    };
+    function isWithinRoot(root, candidate) {
+        const rel = relative(root, candidate);
+        return rel !== '..' && !rel.startsWith(`..${'/'}`) && !rel.startsWith(`..${'\\'}`) && !isAbsolute(rel);
+    }
+    function validateKey(key) {
+        if (!key || key.length === 0) {
+            throw new Error('Invalid key: key cannot be empty');
+        }
+        if (isAbsolute(key)) {
+            throw new Error('Invalid key: absolute paths are not allowed');
+        }
+        const normalizedKey = normalize(key);
+        if (normalizedKey.startsWith('..') || normalizedKey.includes('/..') || normalizedKey.includes('\\..')) {
+            throw new Error('Invalid key: path traversal detected');
+        }
+        const forbidden = ['\0', ':', '*', '?', '"', '<', '>', '|'];
+        for (const char of forbidden) {
+            if (key.includes(char)) {
+                throw new Error(`Invalid key: forbidden character '${char}'`);
+            }
+        }
+    }
+    function resolvePath(key) {
+        validateKey(key);
+        const resolved = join(normalizedRoot, normalize(key));
+        if (!isWithinRoot(normalizedRoot, resolved)) {
+            throw new Error('Invalid key: path traversal detected');
+        }
+        return resolved;
+    }
+    async function validateResolvedPath(filePath) {
+        try {
+            const real = await realpath(filePath);
+            const root = await getResolvedRoot();
+            if (!isWithinRoot(root, real)) {
+                throw new Error('Invalid key: path traversal detected via symlink');
+            }
+        }
+        catch (err) {
+            if (err instanceof Error && 'code' in err && err.code === 'ENOENT') {
+                return;
+            }
+            throw err;
+        }
+    }
+    return {
+        name: 'local',
+        capabilities,
+        async statObject(input) {
+            const filePath = resolvePath(input.key);
+            try {
+                await validateResolvedPath(filePath);
+                const stats = await stat(filePath);
+                if (!stats.isFile()) {
+                    throw createNotFoundError();
+                }
+                return {
+                    key: input.key,
+                    size: stats.size,
+                    lastModifiedAt: stats.mtime.toISOString(),
+                };
+            }
+            catch (err) {
+                if (err instanceof Error && 'code' in err && err.code === 'ENOENT') {
+                    throw createNotFoundError();
+                }
+                throw err;
+            }
+        },
+        async deleteObject(input) {
+            const filePath = resolvePath(input.key);
+            try {
+                await validateResolvedPath(filePath);
+                await unlink(filePath);
+            }
+            catch (err) {
+                if (err instanceof Error && 'code' in err && err.code === 'ENOENT') {
+                    return;
+                }
+                throw err;
+            }
+        },
+        async openUploadStream(input) {
+            const filePath = resolvePath(input.key);
+            const dir = dirname(filePath);
+            await mkdir(dir, { recursive: true });
+            const dirRealPath = await realpath(dir);
+            const root = await getResolvedRoot();
+            if (!isWithinRoot(root, dirRealPath)) {
+                throw new Error('Invalid key: path traversal detected via symlink');
+            }
+            try {
+                const fileStats = await lstat(filePath);
+                if (fileStats.isSymbolicLink()) {
+                    throw new Error('Invalid key: upload target cannot be a symlink');
+                }
+            }
+            catch (err) {
+                if (!(err instanceof Error && 'code' in err && err.code === 'ENOENT')) {
+                    throw err;
+                }
+            }
+            const nodeStream = createWriteStream(filePath);
+            let streamError = null;
+            nodeStream.on('error', (err) => {
+                streamError = err;
+            });
+            return new WritableStream({
+                write(chunk) {
+                    return new Promise((resolve, reject) => {
+                        if (streamError) {
+                            reject(streamError);
+                            return;
+                        }
+                        const buffer = chunk instanceof Uint8Array ? Buffer.from(chunk) : chunk;
+                        const ok = nodeStream.write(buffer);
+                        if (ok) {
+                            resolve();
+                        }
+                        else {
+                            const cleanup = () => {
+                                nodeStream.off('drain', onDrain);
+                                nodeStream.off('error', onError);
+                            };
+                            const onDrain = () => {
+                                cleanup();
+                                resolve();
+                            };
+                            const onError = (err) => {
+                                cleanup();
+                                reject(err);
+                            };
+                            nodeStream.once('drain', onDrain);
+                            nodeStream.once('error', onError);
+                        }
+                    });
+                },
+                close() {
+                    return new Promise((resolve, reject) => {
+                        if (streamError) {
+                            reject(streamError);
+                            return;
+                        }
+                        const cleanup = () => {
+                            nodeStream.off('finish', onFinish);
+                            nodeStream.off('error', onError);
+                        };
+                        const onFinish = () => {
+                            cleanup();
+                            resolve(undefined);
+                        };
+                        const onError = (err) => {
+                            cleanup();
+                            reject(err);
+                        };
+                        nodeStream.once('finish', onFinish);
+                        nodeStream.once('error', onError);
+                        nodeStream.end();
+                    });
+                },
+                abort(reason) {
+                    nodeStream.destroy(reason instanceof Error ? reason : new Error(String(reason)));
+                },
+            });
+        },
+        async openDownloadStream(input) {
+            const filePath = resolvePath(input.key);
+            try {
+                await validateResolvedPath(filePath);
+                const stats = await stat(filePath);
+                if (!stats.isFile()) {
+                    throw createNotFoundError();
+                }
+                if (input.range) {
+                    if (input.range.start < 0) {
+                        throw new Error('Invalid range: start must be non-negative');
+                    }
+                    if (input.range.endInclusive < input.range.start) {
+                        throw new Error('Invalid range: end must be >= start');
+                    }
+                    if (input.range.start >= stats.size) {
+                        throw new Error('Invalid range: start beyond file size');
+                    }
+                }
+            }
+            catch (err) {
+                if (err instanceof Error && 'code' in err && err.code === 'ENOENT') {
+                    throw createNotFoundError();
+                }
+                throw err;
+            }
+            const options = input.range
+                ? { start: input.range.start, end: input.range.endInclusive }
+                : undefined;
+            const nodeStream = createReadStream(filePath, options);
+            nodeStream.pause();
+            return new ReadableStream({
+                start(controller) {
+                    nodeStream.on('data', (chunk) => {
+                        const buffer = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
+                        controller.enqueue(new Uint8Array(buffer));
+                        nodeStream.pause();
+                    });
+                    nodeStream.on('end', () => {
+                        controller.close();
+                    });
+                    nodeStream.on('error', (err) => {
+                        controller.error(err);
+                    });
+                },
+                pull() {
+                    nodeStream.resume();
+                },
+                cancel() {
+                    nodeStream.destroy();
+                },
+            });
+        },
+    };
+}

package/dist/adapter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adapter.test.js

@@ -0,0 +1,257 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdir, rm, writeFile, readFile, symlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createLocalStorageAdapter } from './adapter.js';
+import { runConformanceTests, validateCapabilities } from '@superfunctions/storage';
+describe('@superfunctions/storage-local', () => {
+    let testDir;
+    beforeEach(async () => {
+        testDir = join(tmpdir(), `storage-local-test-${Date.now()}`);
+        await mkdir(testDir, { recursive: true });
+    });
+    afterEach(async () => {
+        await rm(testDir, { recursive: true, force: true });
+    });
+    describe('Adapter instantiation (STORAGE-001)', () => {
+        it('should create adapter with correct name', () => {
+            const adapter = createLocalStorageAdapter({ rootDir: testDir });
+            expect(adapter.name).toBe('local');
+        });
+        it('should be stateless - factory returns immutable instance', () => {
+            const adapter1 = createLocalStorageAdapter({ rootDir: testDir });
+            const adapter2 = createLocalStorageAdapter({ rootDir: testDir });
+            expect(adapter1).not.toBe(adapter2);
+        });
+    });
+    describe('Capabilities (STORAGE-002)', () => {
+        it('should declare accurate capabilities for local storage', () => {
+            const adapter = createLocalStorageAdapter({ rootDir: testDir });
+            expect(adapter.capabilities).toEqual({
+                signedUploadUrls: false,
+                signedDownloadUrls: false,
+                multipart: false,
+                proxyStreamingUpload: true,
+                proxyStreamingDownload: true,
+            });
+        });
+        it('should pass capability validation', () => {
+            const adapter = createLocalStorageAdapter({ rootDir: testDir });
+            const result = validateCapabilities(adapter.capabilities);
+            expect(result.ok).toBe(true);
+        });
+    });
+    describe('Conformance tests', () => {
+        it('should pass all conformance tests', async () => {
+            const adapter = createLocalStorageAdapter({ rootDir: testDir });
+            const result = await runConformanceTests(adapter);
+            expect(result.ok).toBe(true);
+            expect(result.failed).toHaveLength(0);
+        });
+    });
+    describe('statObject (STORAGE-003)', () => {
+        it('should return file stats for existing file', async () => {
+            const adapter = createLocalStorageAdapter({ rootDir: testDir });
+            const testFile = join(testDir, 'test.txt');
+            await writeFile(testFile, 'hello world');
+            const stat = await adapter.statObject({ key: 'test.txt' });
+            expect(stat.key).toBe('test.txt');
+            expect(stat.size).toBe(11);
+            expect(stat.lastModifiedAt).toBeDefined();
+        });
+        it('should throw STORAGE_NOT_FOUND for missing file', async () => {
+            const adapter = createLocalStorageAdapter({ rootDir: testDir });
+            await expect(adapter.statObject({ key: 'missing.txt' })).rejects.toMatchObject({
+                code: 'STORAGE_NOT_FOUND',
+            });
+        });
+        it('should throw STORAGE_NOT_FOUND for directories', async () => {
+            const adapter = createLocalStorageAdapter({ rootDir: testDir });
+            await mkdir(join(testDir, 'subdir'));
+            await expect(adapter.statObject({ key: 'subdir' })).rejects.toMatchObject({
+                code: 'STORAGE_NOT_FOUND',
+            });
+        });
+    });
+    describe('deleteObject (STORAGE-003)', () => {
+        it('should delete existing file', async () => {
+            const adapter = createLocalStorageAdapter({ rootDir: testDir });
+            const testFile = join(testDir, 'test.txt');
+            await writeFile(testFile, 'hello');
+            await adapter.deleteObject({ key: 'test.txt' });
+            await expect(adapter.statObject({ key: 'test.txt' })).rejects.toMatchObject({
+                code: 'STORAGE_NOT_FOUND',
+            });
+        });
+        it('should be idempotent - not throw for missing file', async () => {
+            const adapter = createLocalStorageAdapter({ rootDir: testDir });
+            await expect(adapter.deleteObject({ key: 'missing.txt' })).resolves.toBeUndefined();
+            await expect(adapter.deleteObject({ key: 'missing.txt' })).resolves.toBeUndefined();
+        });
+    });
+    describe('openUploadStream', () => {
+        it('should write data to file', async () => {
+            const adapter = createLocalStorageAdapter({ rootDir: testDir });
+            const stream = await adapter.openUploadStream({ key: 'upload.txt' });
+            const writer = stream.getWriter();
+            await writer.write(new TextEncoder().encode('hello '));
+            await writer.write(new TextEncoder().encode('world'));
+            await writer.close();
+            const content = await readFile(join(testDir, 'upload.txt'), 'utf-8');
+            expect(content).toBe('hello world');
+        });
+        it('should create nested directories', async () => {
+            const adapter = createLocalStorageAdapter({ rootDir: testDir });
+            const stream = await adapter.openUploadStream({ key: 'a/b/c/file.txt' });
+            const writer = stream.getWriter();
+            await writer.write(new TextEncoder().encode('nested'));
+            await writer.close();
+            const content = await readFile(join(testDir, 'a/b/c/file.txt'), 'utf-8');
+            expect(content).toBe('nested');
+        });
+    });
+    describe('openDownloadStream', () => {
+        it('should read data from file', async () => {
+            const adapter = createLocalStorageAdapter({ rootDir: testDir });
+            await writeFile(join(testDir, 'download.txt'), 'hello world');
+            const stream = await adapter.openDownloadStream({ key: 'download.txt' });
+            const reader = stream.getReader();
+            const chunks = [];
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                chunks.push(value);
+            }
+            const content = new TextDecoder().decode(Buffer.concat(chunks));
+            expect(content).toBe('hello world');
+        });
+        it('should support range requests - middle of file', async () => {
+            const adapter = createLocalStorageAdapter({ rootDir: testDir });
+            await writeFile(join(testDir, 'range.txt'), '0123456789');
+            const stream = await adapter.openDownloadStream({
+                key: 'range.txt',
+                range: { start: 2, endInclusive: 5 },
+            });
+            const reader = stream.getReader();
+            const chunks = [];
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                chunks.push(value);
+            }
+            const content = new TextDecoder().decode(Buffer.concat(chunks));
+            expect(content).toBe('2345');
+        });
+        it('should support range requests - from start', async () => {
+            const adapter = createLocalStorageAdapter({ rootDir: testDir });
+            await writeFile(join(testDir, 'range.txt'), 'ABCDEFGHIJ');
+            const stream = await adapter.openDownloadStream({
+                key: 'range.txt',
+                range: { start: 0, endInclusive: 4 },
+            });
+            const reader = stream.getReader();
+            const chunks = [];
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                chunks.push(value);
+            }
+            const content = new TextDecoder().decode(Buffer.concat(chunks));
+            expect(content).toBe('ABCDE');
+        });
+        it('should support range requests - to end', async () => {
+            const adapter = createLocalStorageAdapter({ rootDir: testDir });
+            await writeFile(join(testDir, 'range.txt'), 'ABCDEFGHIJ');
+            const stream = await adapter.openDownloadStream({
+                key: 'range.txt',
+                range: { start: 5, endInclusive: 9 },
+            });
+            const reader = stream.getReader();
+            const chunks = [];
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                chunks.push(value);
+            }
+            const content = new TextDecoder().decode(Buffer.concat(chunks));
+            expect(content).toBe('FGHIJ');
+        });
+        it('should throw STORAGE_NOT_FOUND for missing file', async () => {
+            const adapter = createLocalStorageAdapter({ rootDir: testDir });
+            await expect(adapter.openDownloadStream({ key: 'missing.txt' })).rejects.toMatchObject({
+                code: 'STORAGE_NOT_FOUND',
+            });
+        });
+        it('should reject invalid range - negative start', async () => {
+            const adapter = createLocalStorageAdapter({ rootDir: testDir });
+            await writeFile(join(testDir, 'range.txt'), '0123456789');
+            await expect(adapter.openDownloadStream({
+                key: 'range.txt',
+                range: { start: -1, endInclusive: 5 },
+            })).rejects.toThrow('Invalid range');
+        });
+        it('should reject invalid range - end before start', async () => {
+            const adapter = createLocalStorageAdapter({ rootDir: testDir });
+            await writeFile(join(testDir, 'range.txt'), '0123456789');
+            await expect(adapter.openDownloadStream({
+                key: 'range.txt',
+                range: { start: 5, endInclusive: 2 },
+            })).rejects.toThrow('Invalid range');
+        });
+        it('should reject invalid range - start beyond file size', async () => {
+            const adapter = createLocalStorageAdapter({ rootDir: testDir });
+            await writeFile(join(testDir, 'range.txt'), '0123456789');
+            await expect(adapter.openDownloadStream({
+                key: 'range.txt',
+                range: { start: 100, endInclusive: 200 },
+            })).rejects.toThrow('Invalid range');
+        });
+    });
+    describe('Security - Path traversal prevention', () => {
+        it('should prevent path traversal with ../', async () => {
+            const adapter = createLocalStorageAdapter({ rootDir: testDir });
+            await expect(adapter.statObject({ key: '../../../etc/passwd' })).rejects.toThrow('path traversal');
+        });
+        it('should prevent path traversal with ..\\', async () => {
+            const adapter = createLocalStorageAdapter({ rootDir: testDir });
+            await expect(adapter.statObject({ key: '..\\..\\etc\\passwd' })).rejects.toThrow('path traversal');
+        });
+        it('should prevent absolute paths', async () => {
+            const adapter = createLocalStorageAdapter({ rootDir: testDir });
+            await expect(adapter.statObject({ key: '/etc/passwd' })).rejects.toThrow('absolute paths');
+        });
+        it('should prevent empty keys', async () => {
+            const adapter = createLocalStorageAdapter({ rootDir: testDir });
+            await expect(adapter.statObject({ key: '' })).rejects.toThrow('cannot be empty');
+        });
+        it('should prevent null bytes in key', async () => {
+            const adapter = createLocalStorageAdapter({ rootDir: testDir });
+            await expect(adapter.statObject({ key: 'test\0.txt' })).rejects.toThrow('forbidden character');
+        });
+        it('should prevent traversal via symlink', async () => {
+            const adapter = createLocalStorageAdapter({ rootDir: testDir });
+            const outsideDir = join(tmpdir(), `outside-${Date.now()}`);
+            await mkdir(outsideDir, { recursive: true });
+            await writeFile(join(outsideDir, 'secret.txt'), 'secret data');
+            try {
+                await symlink(outsideDir, join(testDir, 'link'));
+                await expect(adapter.statObject({ key: 'link/secret.txt' })).rejects.toThrow('path traversal');
+            }
+            finally {
+                await rm(outsideDir, { recursive: true, force: true });
+            }
+        });
+        it('should allow safe nested paths', async () => {
+            const adapter = createLocalStorageAdapter({ rootDir: testDir });
+            const nestedPath = join(testDir, 'a', 'b', 'c');
+            await mkdir(nestedPath, { recursive: true });
+            await writeFile(join(nestedPath, 'file.txt'), 'content');
+            const stat = await adapter.statObject({ key: 'a/b/c/file.txt' });
+            expect(stat.key).toBe('a/b/c/file.txt');
+        });
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { createLocalStorageAdapter, createLocalStorageAdapter as createLocalStorage } from './adapter.js';
+export type { LocalStorageConfig } from './adapter.js';

package/dist/index.js

@@ -0,0 +1 @@
+export { createLocalStorageAdapter, createLocalStorageAdapter as createLocalStorage } from './adapter.js';

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@superfunctions/storage-local",
+  "version": "0.1.0",
+  "description": "Local filesystem storage adapter for @superfunctions/storage",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "keywords": ["storage", "local", "filesystem", "superfunctions"],
+  "author": "21n",
+  "license": "MIT",
+  "bugs": { "url": "https://github.com/21nCo/super-functions/issues" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/21nCo/super-functions.git",
+    "directory": "packages/storage-local"
+  },
+  "publishConfig": { "access": "public" },
+  "dependencies": {
+    "@superfunctions/storage": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.2.4"
+  }
+}