s3-adaptor 0.2.0

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Kevin Foster
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,101 @@
+# s3-adaptor
+
+Unified adapter-pattern interface for AWS S3 and local filesystem storage. Switch backends via config — same API in dev and production. Includes signed URL generation and Express middleware for local dev serving.
+
+## Install
+
+```bash
+pnpm add s3-adaptor
+# peer dep for middleware:
+pnpm add express
+```
+
+## Quick Start
+
+**Local (dev)**
+
+```typescript
+import { S3Adaptor } from 's3-adaptor'
+
+const storage = new S3Adaptor({
+  defaultType: 'local',
+  local: {
+    storagePath: '/tmp/storage',
+    baseUrl: 'http://localhost:3000/files',
+    secretKey: 'supersecretkey-atleast-32-chars!',
+    buckets: {
+      avatars: { public: true },  // no token required to read
+      docs:    { public: false }, // token required (default)
+    },
+  },
+})
+```
+
+**S3 (production)**
+
+```typescript
+const storage = new S3Adaptor({
+  defaultType: 's3',
+  s3: { region: 'us-east-1' }, // uses AWS SDK default credential chain
+})
+```
+
+## API
+
+```typescript
+// Upload
+await storage.putObject({ Bucket, Key, Body, ContentType?, Metadata? })
+
+// Download — returns { Body: ReadableStream, ContentType?, ContentLength?, ETag?, Metadata? }
+const result = await storage.getObject({ Bucket, Key })
+
+// Delete
+await storage.deleteObject({ Bucket, Key })
+
+// List — returns { Contents: [{ Key, Size, LastModified, ETag? }], IsTruncated }
+const list = await storage.listObjects({ Bucket, Prefix?, MaxKeys? })
+
+// Signed URL — public bucket → plain URL; protected → ?token=<signed> (local); S3 → pre-signed
+const url = await storage.getSignedUrl({ Bucket, Key, Expires? })
+```
+
+## Express Middleware (local only)
+
+```typescript
+import { createLocalFileMiddleware } from 's3-adaptor'
+
+// Mount as: GET /files/:bucket/*key (Express 5) or /files/:bucket/* (Express 4)
+app.get('/files/:bucket/*key', createLocalFileMiddleware(config.local))
+```
+
+Access control is based on bucket policy:
+- Public bucket: serves file without token
+- Protected bucket: requires `?token=<signed>` obtained from `getSignedUrl`
+
+## Bucket Access Modes
+
+| Mode      | `BucketPolicy.public` | `getSignedUrl` result   | Middleware            |
+|-----------|-----------------------|-------------------------|-----------------------|
+| Public    | `true`                | plain URL, no token     | serves without token  |
+| Protected | `false` (default)     | URL with `?token=<...>` | requires valid token  |
+
+## Error Classes
+
+All errors extend `S3AdaptorError` with a `code` property.
+
+| Class                | `code`           | When                          |
+|----------------------|------------------|-------------------------------|
+| `NotFoundError`      | `NOT_FOUND`      | Object missing                |
+| `AccessDeniedError`  | `ACCESS_DENIED`  | No token on protected bucket  |
+| `InvalidTokenError`  | `INVALID_TOKEN`  | Tampered or wrong-scope token |
+| `TokenExpiredError`  | `TOKEN_EXPIRED`  | Token past expiry             |
+| `InvalidConfigError` | `INVALID_CONFIG` | Bad constructor config        |
+
+## Scripts
+
+```bash
+pnpm build    # tsc → dist/
+pnpm test     # jest
+pnpm format   # prettier --write ./src
+pnpm lint     # eslint src
+```

package/dist/S3Adaptor.d.ts

@@ -0,0 +1,13 @@
+import type { CopyObjectParams, DeleteObjectParams, GetObjectParams, GetObjectResult, GetSignedUrlParams, ListObjectsParams, ListObjectsResult, PutObjectParams, S3AdaptorConfig, UploadObjectParams } from './types';
+export declare class S3Adaptor {
+    private readonly adapter;
+    constructor(config: S3AdaptorConfig);
+    putObject(params: PutObjectParams): Promise<void>;
+    uploadObject(params: UploadObjectParams): Promise<void>;
+    getObject(params: GetObjectParams): Promise<GetObjectResult>;
+    deleteObject(params: DeleteObjectParams): Promise<void>;
+    copyObject(params: CopyObjectParams): Promise<void>;
+    listObjects(params: ListObjectsParams): Promise<ListObjectsResult>;
+    getSignedUrl(params: GetSignedUrlParams): Promise<string>;
+    pruneEmptyDirs(bucket: string, prefix?: string): Promise<void>;
+}

package/dist/S3Adaptor.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.S3Adaptor = void 0;
+const errors_1 = require("./errors");
+const LocalAdapter_1 = require("./adapters/LocalAdapter");
+const S3Adapter_1 = require("./adapters/S3Adapter");
+function validateConfig(config) {
+    if (config.defaultType === 's3' && !config.s3) {
+        throw new errors_1.InvalidConfigError("s3 config required when defaultType is 's3'");
+    }
+    if (config.defaultType === 'local' && !config.local) {
+        throw new errors_1.InvalidConfigError("local config required when defaultType is 'local'");
+    }
+    if (config.local && config.local.secretKey.length < 32) {
+        throw new errors_1.InvalidConfigError('secretKey must be at least 32 characters');
+    }
+}
+class S3Adaptor {
+    constructor(config) {
+        validateConfig(config);
+        this.adapter =
+            config.defaultType === 's3' ? new S3Adapter_1.S3Adapter(config.s3) : new LocalAdapter_1.LocalAdapter(config.local);
+    }
+    putObject(params) {
+        return this.adapter.putObject(params);
+    }
+    uploadObject(params) {
+        return this.adapter.uploadObject(params);
+    }
+    getObject(params) {
+        return this.adapter.getObject(params);
+    }
+    deleteObject(params) {
+        return this.adapter.deleteObject(params);
+    }
+    copyObject(params) {
+        return this.adapter.copyObject(params);
+    }
+    listObjects(params) {
+        return this.adapter.listObjects(params);
+    }
+    getSignedUrl(params) {
+        return this.adapter.getSignedUrl(params);
+    }
+    pruneEmptyDirs(bucket, prefix) {
+        return this.adapter.pruneEmptyDirs(bucket, prefix);
+    }
+}
+exports.S3Adaptor = S3Adaptor;

package/dist/adapters/BaseAdapter.d.ts

@@ -0,0 +1,11 @@
+import type { CopyObjectParams, DeleteObjectParams, GetObjectParams, GetObjectResult, GetSignedUrlParams, ListObjectsParams, ListObjectsResult, PutObjectParams, UploadObjectParams } from '../types';
+export declare abstract class BaseAdapter {
+    abstract putObject(params: PutObjectParams): Promise<void>;
+    abstract uploadObject(params: UploadObjectParams): Promise<void>;
+    abstract getObject(params: GetObjectParams): Promise<GetObjectResult>;
+    abstract deleteObject(params: DeleteObjectParams): Promise<void>;
+    abstract copyObject(params: CopyObjectParams): Promise<void>;
+    abstract listObjects(params: ListObjectsParams): Promise<ListObjectsResult>;
+    abstract getSignedUrl(params: GetSignedUrlParams): Promise<string>;
+    pruneEmptyDirs(_bucket: string, _prefix?: string): Promise<void>;
+}

package/dist/adapters/BaseAdapter.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseAdapter = void 0;
+class BaseAdapter {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    pruneEmptyDirs(_bucket, _prefix) {
+        return Promise.resolve();
+    }
+}
+exports.BaseAdapter = BaseAdapter;

package/dist/adapters/LocalAdapter.d.ts

@@ -0,0 +1,21 @@
+import * as realFs from 'fs';
+import type { CopyObjectParams, DeleteObjectParams, GetObjectParams, GetObjectResult, GetSignedUrlParams, ListObjectsParams, ListObjectsResult, LocalConfig, PutObjectParams, UploadObjectParams } from '../types';
+import { BaseAdapter } from './BaseAdapter';
+type FsModule = typeof realFs;
+export declare class LocalAdapter extends BaseAdapter {
+    private readonly config;
+    private readonly fs;
+    private readonly signer;
+    constructor(config: LocalConfig, fs?: FsModule);
+    private isPublicBucket;
+    private resolveFilePath;
+    uploadObject(params: UploadObjectParams): Promise<void>;
+    putObject(params: PutObjectParams): Promise<void>;
+    getObject(params: GetObjectParams): Promise<GetObjectResult>;
+    copyObject(params: CopyObjectParams): Promise<void>;
+    deleteObject(params: DeleteObjectParams): Promise<void>;
+    listObjects(params: ListObjectsParams): Promise<ListObjectsResult>;
+    pruneEmptyDirs(bucket: string, prefix?: string): Promise<void>;
+    getSignedUrl(params: GetSignedUrlParams): Promise<string>;
+}
+export {};

package/dist/adapters/LocalAdapter.js

@@ -0,0 +1,292 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalAdapter = void 0;
+const crypto_1 = require("crypto");
+const path = __importStar(require("path"));
+const realFs = __importStar(require("fs"));
+const stream_1 = require("stream");
+const errors_1 = require("../errors");
+const TokenSigner_1 = require("../signing/TokenSigner");
+const BaseAdapter_1 = require("./BaseAdapter");
+function validateKey(key) {
+    if (key.startsWith('/') || key.includes('..')) {
+        throw new errors_1.S3AdaptorError('Forbidden key path', 'FORBIDDEN');
+    }
+}
+function validateBucket(bucket) {
+    if (bucket.startsWith('/') || bucket.includes('..') || bucket.includes('/')) {
+        throw new errors_1.S3AdaptorError('Forbidden bucket name', 'FORBIDDEN');
+    }
+}
+function metaPath(filePath) {
+    const dir = path.dirname(filePath);
+    const base = path.basename(filePath);
+    return path.join(dir, `.${base}.meta.json`);
+}
+class LocalAdapter extends BaseAdapter_1.BaseAdapter {
+    constructor(config, fs = realFs) {
+        super();
+        this.config = config;
+        this.fs = fs;
+        this.signer = new TokenSigner_1.TokenSigner(config.secretKey);
+    }
+    isPublicBucket(bucket) {
+        return this.config.buckets?.[bucket]?.public ?? false;
+    }
+    resolveFilePath(bucket, key) {
+        validateBucket(bucket);
+        validateKey(key);
+        return path.join(this.config.storagePath, bucket, key);
+    }
+    uploadObject(params) {
+        return this.putObject(params);
+    }
+    async putObject(params) {
+        const { Bucket, Key, Body, ContentType, Metadata } = params;
+        const filePath = this.resolveFilePath(Bucket, Key);
+        const dir = path.dirname(filePath);
+        await this.fs.promises.mkdir(dir, { recursive: true });
+        const bodyBuffer = typeof Body === 'string'
+            ? Buffer.from(Body)
+            : Body instanceof Buffer
+                ? Body
+                : await streamToBuffer(Body);
+        await this.fs.promises.writeFile(filePath, bodyBuffer);
+        const etag = (0, crypto_1.createHash)('md5').update(bodyBuffer).digest('hex');
+        const meta = {
+            ContentType,
+            Metadata,
+            ETag: etag,
+            Size: bodyBuffer.length,
+            LastModified: new Date().toISOString(),
+        };
+        await this.fs.promises.writeFile(metaPath(filePath), JSON.stringify(meta));
+    }
+    async getObject(params) {
+        const { Bucket, Key } = params;
+        const filePath = this.resolveFilePath(Bucket, Key);
+        try {
+            await this.fs.promises.access(filePath);
+        }
+        catch {
+            throw new errors_1.NotFoundError(Bucket, Key);
+        }
+        let meta;
+        try {
+            const raw = await this.fs.promises.readFile(metaPath(filePath), 'utf-8');
+            meta = JSON.parse(raw);
+        }
+        catch {
+            // metadata optional
+        }
+        const fileBuffer = await this.fs.promises.readFile(filePath);
+        const body = stream_1.Readable.from(fileBuffer);
+        return {
+            Body: body,
+            ContentType: meta?.ContentType,
+            ContentLength: meta?.Size,
+            Metadata: meta?.Metadata,
+            ETag: meta?.ETag,
+        };
+    }
+    async copyObject(params) {
+        const { Bucket, Key, CopySource, ContentType, Metadata } = params;
+        // CopySource format: '{sourceBucket}/{sourceKey}'
+        const slashIdx = CopySource.indexOf('/');
+        const srcBucket = CopySource.slice(0, slashIdx);
+        const srcKey = CopySource.slice(slashIdx + 1);
+        const srcPath = this.resolveFilePath(srcBucket, srcKey);
+        const dstPath = this.resolveFilePath(Bucket, Key);
+        await this.fs.promises.mkdir(path.dirname(dstPath), { recursive: true });
+        await this.fs.promises.copyFile(srcPath, dstPath);
+        let srcMeta;
+        try {
+            const raw = await this.fs.promises.readFile(metaPath(srcPath), 'utf-8');
+            srcMeta = JSON.parse(raw);
+        }
+        catch {
+            // sidecar optional
+        }
+        const newMeta = {
+            ContentType: ContentType ?? srcMeta?.ContentType,
+            Metadata: Metadata ?? srcMeta?.Metadata,
+            ETag: srcMeta?.ETag ?? '',
+            Size: srcMeta?.Size ?? 0,
+            LastModified: new Date().toISOString(),
+        };
+        await this.fs.promises.writeFile(metaPath(dstPath), JSON.stringify(newMeta));
+    }
+    async deleteObject(params) {
+        const { Bucket, Key } = params;
+        const filePath = this.resolveFilePath(Bucket, Key);
+        try {
+            await this.fs.promises.unlink(filePath);
+        }
+        catch {
+            throw new errors_1.NotFoundError(Bucket, Key);
+        }
+        try {
+            await this.fs.promises.unlink(metaPath(filePath));
+        }
+        catch {
+            // sidecar may not exist
+        }
+    }
+    async listObjects(params) {
+        const { Bucket, Prefix = '', MaxKeys } = params;
+        validateBucket(Bucket);
+        const bucketDir = path.join(this.config.storagePath, Bucket);
+        let allFiles;
+        try {
+            allFiles = await readdirRecursive(bucketDir, this.fs);
+        }
+        catch {
+            return { Contents: [], IsTruncated: false };
+        }
+        const metaSuffix = '.meta.json';
+        const filtered = allFiles.filter((f) => {
+            const rel = path.relative(bucketDir, f).replace(/\\/g, '/');
+            const base = path.basename(f);
+            return !base.startsWith('.') && !base.endsWith(metaSuffix) && rel.startsWith(Prefix);
+        });
+        const limited = MaxKeys !== undefined ? filtered.slice(0, MaxKeys) : filtered;
+        const isTruncated = MaxKeys !== undefined && filtered.length > MaxKeys;
+        const contents = await Promise.all(limited.map(async (f) => {
+            const rel = path.relative(bucketDir, f).replace(/\\/g, '/');
+            const stat = await this.fs.promises.stat(f);
+            let etag;
+            try {
+                const raw = await this.fs.promises.readFile(metaPath(f), 'utf-8');
+                const meta = JSON.parse(raw);
+                etag = meta.ETag;
+            }
+            catch {
+                // no sidecar
+            }
+            return {
+                Key: rel,
+                Size: stat.size,
+                LastModified: stat.mtime,
+                ETag: etag,
+            };
+        }));
+        return { Contents: contents, IsTruncated: isTruncated };
+    }
+    async pruneEmptyDirs(bucket, prefix) {
+        validateBucket(bucket);
+        const bucketDir = path.join(this.config.storagePath, bucket);
+        const targetDir = prefix ? path.join(bucketDir, prefix) : bucketDir;
+        try {
+            await this.fs.promises.access(targetDir);
+        }
+        catch {
+            return;
+        }
+        await pruneEmptyDirsRecursive(targetDir, bucketDir, this.fs);
+    }
+    async getSignedUrl(params) {
+        const { Bucket, Key, Expires, ResponseContentDisposition } = params;
+        const base = `${this.config.baseUrl}/${Bucket}/${Key}`;
+        if (this.isPublicBucket(Bucket)) {
+            // Public buckets have no token to bind a disposition into - anyone can
+            // already request any key in a public bucket under any disposition,
+            // signed or not, so this remains a bare query param.
+            const dispositionParam = ResponseContentDisposition
+                ? `disposition=${encodeURIComponent(ResponseContentDisposition)}`
+                : null;
+            return dispositionParam ? `${base}?${dispositionParam}` : base;
+        }
+        const exp = Math.floor(Date.now() / 1000) + (Expires ?? this.config.defaultExpiry ?? 3600);
+        // Bind the disposition into the signature itself, so it can't be changed
+        // by editing the query string after the URL is issued.
+        const token = this.signer.sign({
+            bucket: Bucket,
+            key: Key,
+            exp,
+            disposition: ResponseContentDisposition,
+        });
+        return `${base}?token=${token}`;
+    }
+}
+exports.LocalAdapter = LocalAdapter;
+async function streamToBuffer(stream) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        stream.on('data', (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+        stream.on('end', () => resolve(Buffer.concat(chunks)));
+        stream.on('error', reject);
+    });
+}
+async function pruneEmptyDirsRecursive(dir, stopAt, fs) {
+    let entries;
+    try {
+        entries = await fs.promises.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            await pruneEmptyDirsRecursive(path.join(dir, entry.name), stopAt, fs);
+        }
+    }
+    if (dir === stopAt)
+        return;
+    const remaining = await fs.promises.readdir(dir);
+    if (remaining.length === 0) {
+        try {
+            await fs.promises.rmdir(dir);
+        }
+        catch {
+            // non-empty or concurrent write — leave it
+        }
+    }
+}
+async function readdirRecursive(dir, fs) {
+    const entries = await fs.promises.readdir(dir, { withFileTypes: true });
+    const results = [];
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            const sub = await readdirRecursive(full, fs);
+            results.push(...sub);
+        }
+        else {
+            results.push(full);
+        }
+    }
+    return results;
+}

package/dist/adapters/S3Adapter.d.ts

@@ -0,0 +1,23 @@
+import type { CopyObjectParams, DeleteObjectParams, GetObjectParams, GetObjectResult, GetSignedUrlParams, ListObjectsParams, ListObjectsResult, PutObjectParams, UploadObjectParams } from '../types';
+import { BaseAdapter } from './BaseAdapter';
+interface S3Config {
+    region: string;
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+    };
+    endpoint?: string;
+    forcePathStyle?: boolean;
+}
+export declare class S3Adapter extends BaseAdapter {
+    private readonly client;
+    constructor(config: S3Config);
+    putObject(params: PutObjectParams): Promise<void>;
+    uploadObject(params: UploadObjectParams): Promise<void>;
+    getObject(params: GetObjectParams): Promise<GetObjectResult>;
+    deleteObject(params: DeleteObjectParams): Promise<void>;
+    copyObject(params: CopyObjectParams): Promise<void>;
+    listObjects(params: ListObjectsParams): Promise<ListObjectsResult>;
+    getSignedUrl(params: GetSignedUrlParams): Promise<string>;
+}
+export {};

package/dist/adapters/S3Adapter.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.S3Adapter = void 0;
+const client_s3_1 = require("@aws-sdk/client-s3");
+const lib_storage_1 = require("@aws-sdk/lib-storage");
+const s3_request_presigner_1 = require("@aws-sdk/s3-request-presigner");
+const errors_1 = require("../errors");
+const BaseAdapter_1 = require("./BaseAdapter");
+class S3Adapter extends BaseAdapter_1.BaseAdapter {
+    constructor(config) {
+        super();
+        this.client = new client_s3_1.S3Client({
+            region: config.region,
+            credentials: config.credentials,
+            endpoint: config.endpoint,
+            forcePathStyle: config.forcePathStyle,
+            requestChecksumCalculation: 'WHEN_REQUIRED',
+        });
+    }
+    async putObject(params) {
+        try {
+            await this.client.send(new client_s3_1.PutObjectCommand({
+                Bucket: params.Bucket,
+                Key: params.Key,
+                Body: params.Body,
+                ContentType: params.ContentType,
+                Metadata: params.Metadata,
+            }));
+        }
+        catch (err) {
+            throw wrapError(err);
+        }
+    }
+    async uploadObject(params) {
+        try {
+            const upload = new lib_storage_1.Upload({
+                client: this.client,
+                params: {
+                    Bucket: params.Bucket,
+                    Key: params.Key,
+                    Body: params.Body,
+                    ContentType: params.ContentType,
+                },
+            });
+            await upload.done();
+        }
+        catch (err) {
+            throw wrapError(err);
+        }
+    }
+    async getObject(params) {
+        try {
+            const result = await this.client.send(new client_s3_1.GetObjectCommand(params));
+            const body = result.Body;
+            if (!body)
+                throw new errors_1.S3AdaptorError('Empty response body', 'EMPTY_BODY');
+            return {
+                Body: body,
+                ContentType: result.ContentType,
+                ContentLength: result.ContentLength,
+                Metadata: result.Metadata,
+                ETag: result.ETag,
+            };
+        }
+        catch (err) {
+            if (err instanceof client_s3_1.NoSuchKey)
+                throw new errors_1.NotFoundError(params.Bucket, params.Key);
+            throw wrapError(err);
+        }
+    }
+    async deleteObject(params) {
+        try {
+            await this.client.send(new client_s3_1.DeleteObjectCommand(params));
+        }
+        catch (err) {
+            throw wrapError(err);
+        }
+    }
+    async copyObject(params) {
+        try {
+            await this.client.send(new client_s3_1.CopyObjectCommand({
+                Bucket: params.Bucket,
+                Key: params.Key,
+                CopySource: params.CopySource,
+                ContentType: params.ContentType,
+                Metadata: params.Metadata,
+                MetadataDirective: params.Metadata ? 'REPLACE' : 'COPY',
+            }));
+        }
+        catch (err) {
+            throw wrapError(err);
+        }
+    }
+    async listObjects(params) {
+        try {
+            const result = await this.client.send(new client_s3_1.ListObjectsV2Command({
+                Bucket: params.Bucket,
+                Prefix: params.Prefix,
+                MaxKeys: params.MaxKeys,
+            }));
+            return {
+                Contents: (result.Contents ?? []).map((item) => ({
+                    Key: item.Key ?? '',
+                    Size: item.Size ?? 0,
+                    LastModified: item.LastModified ?? new Date(),
+                    ETag: item.ETag,
+                })),
+                IsTruncated: result.IsTruncated ?? false,
+            };
+        }
+        catch (err) {
+            throw wrapError(err);
+        }
+    }
+    async getSignedUrl(params) {
+        const expiresIn = params.Expires ?? 3600;
+        if (params.operation === 'put') {
+            const cmd = new client_s3_1.PutObjectCommand({
+                Bucket: params.Bucket,
+                Key: params.Key,
+                ContentType: params.ContentType,
+            });
+            return (0, s3_request_presigner_1.getSignedUrl)(this.client, cmd, { expiresIn });
+        }
+        const cmd = new client_s3_1.GetObjectCommand({
+            Bucket: params.Bucket,
+            Key: params.Key,
+            ResponseContentDisposition: params.ResponseContentDisposition,
+        });
+        return (0, s3_request_presigner_1.getSignedUrl)(this.client, cmd, { expiresIn });
+    }
+}
+exports.S3Adapter = S3Adapter;
+function wrapError(err) {
+    if (err instanceof errors_1.S3AdaptorError)
+        return err;
+    if (err instanceof Error)
+        return new errors_1.S3AdaptorError(err.message, 'S3_ERROR');
+    return new errors_1.S3AdaptorError(String(err), 'S3_ERROR');
+}

package/dist/errors.d.ts

@@ -0,0 +1,19 @@
+export declare class S3AdaptorError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+export declare class NotFoundError extends S3AdaptorError {
+    constructor(bucket: string, key: string);
+}
+export declare class InvalidConfigError extends S3AdaptorError {
+    constructor(message: string);
+}
+export declare class TokenExpiredError extends S3AdaptorError {
+    constructor();
+}
+export declare class InvalidTokenError extends S3AdaptorError {
+    constructor();
+}
+export declare class AccessDeniedError extends S3AdaptorError {
+    constructor();
+}

package/dist/errors.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccessDeniedError = exports.InvalidTokenError = exports.TokenExpiredError = exports.InvalidConfigError = exports.NotFoundError = exports.S3AdaptorError = void 0;
+class S3AdaptorError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'S3AdaptorError';
+    }
+}
+exports.S3AdaptorError = S3AdaptorError;
+class NotFoundError extends S3AdaptorError {
+    constructor(bucket, key) {
+        super(`Object not found: ${bucket}/${key}`, 'NOT_FOUND');
+        this.name = 'NotFoundError';
+    }
+}
+exports.NotFoundError = NotFoundError;
+class InvalidConfigError extends S3AdaptorError {
+    constructor(message) {
+        super(message, 'INVALID_CONFIG');
+        this.name = 'InvalidConfigError';
+    }
+}
+exports.InvalidConfigError = InvalidConfigError;
+class TokenExpiredError extends S3AdaptorError {
+    constructor() {
+        super('Token has expired', 'TOKEN_EXPIRED');
+        this.name = 'TokenExpiredError';
+    }
+}
+exports.TokenExpiredError = TokenExpiredError;
+class InvalidTokenError extends S3AdaptorError {
+    constructor() {
+        super('Invalid token', 'INVALID_TOKEN');
+        this.name = 'InvalidTokenError';
+    }
+}
+exports.InvalidTokenError = InvalidTokenError;
+class AccessDeniedError extends S3AdaptorError {
+    constructor() {
+        super('Access denied', 'ACCESS_DENIED');
+        this.name = 'AccessDeniedError';
+    }
+}
+exports.AccessDeniedError = AccessDeniedError;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { S3Adaptor } from './S3Adaptor';
+export { createLocalFileMiddleware } from './middleware/localFileMiddleware';
+export type { S3AdaptorConfig, LocalConfig, BucketPolicy, PutObjectParams, UploadObjectParams, GetObjectParams, DeleteObjectParams, CopyObjectParams, ListObjectsParams, GetSignedUrlParams, GetObjectResult, ListObjectsResult, } from './types';
+export { S3AdaptorError, NotFoundError, TokenExpiredError, InvalidTokenError, InvalidConfigError, AccessDeniedError, } from './errors';

package/dist/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccessDeniedError = exports.InvalidConfigError = exports.InvalidTokenError = exports.TokenExpiredError = exports.NotFoundError = exports.S3AdaptorError = exports.createLocalFileMiddleware = exports.S3Adaptor = void 0;
+var S3Adaptor_1 = require("./S3Adaptor");
+Object.defineProperty(exports, "S3Adaptor", { enumerable: true, get: function () { return S3Adaptor_1.S3Adaptor; } });
+var localFileMiddleware_1 = require("./middleware/localFileMiddleware");
+Object.defineProperty(exports, "createLocalFileMiddleware", { enumerable: true, get: function () { return localFileMiddleware_1.createLocalFileMiddleware; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "S3AdaptorError", { enumerable: true, get: function () { return errors_1.S3AdaptorError; } });
+Object.defineProperty(exports, "NotFoundError", { enumerable: true, get: function () { return errors_1.NotFoundError; } });
+Object.defineProperty(exports, "TokenExpiredError", { enumerable: true, get: function () { return errors_1.TokenExpiredError; } });
+Object.defineProperty(exports, "InvalidTokenError", { enumerable: true, get: function () { return errors_1.InvalidTokenError; } });
+Object.defineProperty(exports, "InvalidConfigError", { enumerable: true, get: function () { return errors_1.InvalidConfigError; } });
+Object.defineProperty(exports, "AccessDeniedError", { enumerable: true, get: function () { return errors_1.AccessDeniedError; } });

package/dist/middleware/localFileMiddleware.d.ts

@@ -0,0 +1,3 @@
+import type { RequestHandler } from 'express';
+import type { LocalConfig } from '../types';
+export declare function createLocalFileMiddleware(config: LocalConfig): RequestHandler;

package/dist/middleware/localFileMiddleware.js

@@ -0,0 +1,142 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLocalFileMiddleware = createLocalFileMiddleware;
+const fs_1 = require("fs");
+const fs_2 = require("fs");
+const path = __importStar(require("path"));
+const errors_1 = require("../errors");
+const TokenSigner_1 = require("../signing/TokenSigner");
+function validateKey(key) {
+    if (key.startsWith('/') || key.includes('..')) {
+        throw new errors_1.S3AdaptorError('Forbidden key path', 'FORBIDDEN');
+    }
+}
+function validateBucket(bucket) {
+    if (bucket.startsWith('/') || bucket.includes('..') || bucket.includes('/')) {
+        throw new errors_1.S3AdaptorError('Forbidden bucket name', 'FORBIDDEN');
+    }
+}
+function resolveFilePath(storagePath, bucket, key) {
+    validateBucket(bucket);
+    validateKey(key);
+    return path.join(storagePath, bucket, key);
+}
+function metaPath(filePath) {
+    const dir = path.dirname(filePath);
+    const base = path.basename(filePath);
+    return path.join(dir, `.${base}.meta.json`);
+}
+async function readMetadata(filePath) {
+    try {
+        const raw = await fs_2.promises.readFile(metaPath(filePath), 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Object key from the route wildcard. Express 5 mounts as `/:bucket/*key` and
+ * yields the path segments as an array; Express 4 mounts as `/:bucket/*` and
+ * yields the remainder as `params[0]`.
+ */
+function extractKey(params) {
+    const wildcard = params['key'] ?? params['0'] ?? '';
+    return Array.isArray(wildcard) ? wildcard.join('/') : wildcard;
+}
+function createLocalFileMiddleware(config) {
+    const signer = new TokenSigner_1.TokenSigner(config.secretKey);
+    return async (req, res, next) => {
+        try {
+            const bucket = req.params['bucket'];
+            const key = extractKey(req.params);
+            if (typeof bucket !== 'string' || !bucket) {
+                res.status(400).json({ error: 'Missing bucket' });
+                return;
+            }
+            const isPublic = config.buckets?.[bucket]?.public ?? false;
+            // Signed (private-bucket) disposition comes from the verified token,
+            // never the raw query string - otherwise a caller could edit the
+            // query string to override the disposition the URL was signed with
+            // (e.g. turning a deliberately-forced "attachment" into "inline"),
+            // since the query string carries no signature of its own. Public
+            // buckets have no token to bind it to, so they keep the bare param.
+            let disposition;
+            if (!isPublic) {
+                const token = req.query['token'];
+                if (!token)
+                    throw new errors_1.AccessDeniedError();
+                const claims = signer.verify(token);
+                if (claims.bucket !== bucket || claims.key !== key)
+                    throw new errors_1.InvalidTokenError();
+                disposition = claims.disposition;
+            }
+            else {
+                const queryDisposition = req.query['disposition'];
+                disposition = typeof queryDisposition === 'string' ? queryDisposition : undefined;
+            }
+            const filePath = resolveFilePath(config.storagePath, bucket, key);
+            try {
+                await fs_2.promises.access(filePath);
+            }
+            catch {
+                throw new errors_1.NotFoundError(bucket, key);
+            }
+            const meta = await readMetadata(filePath);
+            res.setHeader('Content-Type', meta?.ContentType ?? 'application/octet-stream');
+            if (meta?.Size !== undefined)
+                res.setHeader('Content-Length', meta.Size);
+            if (meta?.ETag)
+                res.setHeader('ETag', meta.ETag);
+            if (disposition)
+                res.setHeader('Content-Disposition', disposition);
+            (0, fs_1.createReadStream)(filePath).pipe(res);
+        }
+        catch (err) {
+            if (err instanceof errors_1.AccessDeniedError ||
+                err instanceof errors_1.TokenExpiredError ||
+                err instanceof errors_1.InvalidTokenError) {
+                res.status(403).json({ error: err.message });
+            }
+            else if (err instanceof errors_1.NotFoundError) {
+                res.status(404).json({ error: err.message });
+            }
+            else {
+                next(err);
+            }
+        }
+    };
+}

package/dist/signing/TokenSigner.d.ts

@@ -0,0 +1,12 @@
+export interface TokenPayload {
+    bucket: string;
+    key: string;
+    exp: number;
+    disposition?: string;
+}
+export declare class TokenSigner {
+    private readonly secretKey;
+    constructor(secretKey: string);
+    sign(payload: TokenPayload): string;
+    verify(token: string): TokenPayload;
+}

package/dist/signing/TokenSigner.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenSigner = void 0;
+const crypto_1 = require("crypto");
+const errors_1 = require("../errors");
+class TokenSigner {
+    constructor(secretKey) {
+        this.secretKey = secretKey;
+    }
+    sign(payload) {
+        const data = Buffer.from(JSON.stringify(payload)).toString('base64url');
+        const sig = (0, crypto_1.createHmac)('sha256', this.secretKey).update(data).digest('base64url');
+        return `${data}.${sig}`;
+    }
+    verify(token) {
+        const dotIndex = token.lastIndexOf('.');
+        if (dotIndex === -1)
+            throw new errors_1.InvalidTokenError();
+        const data = token.slice(0, dotIndex);
+        const sig = token.slice(dotIndex + 1);
+        const expected = (0, crypto_1.createHmac)('sha256', this.secretKey).update(data).digest('base64url');
+        const sigBuf = Buffer.from(sig);
+        const expectedBuf = Buffer.from(expected);
+        if (sigBuf.length !== expectedBuf.length || !(0, crypto_1.timingSafeEqual)(sigBuf, expectedBuf)) {
+            throw new errors_1.InvalidTokenError();
+        }
+        let payload;
+        try {
+            payload = JSON.parse(Buffer.from(data, 'base64url').toString());
+        }
+        catch {
+            throw new errors_1.InvalidTokenError();
+        }
+        if (Date.now() > payload.exp * 1000)
+            throw new errors_1.TokenExpiredError();
+        return payload;
+    }
+}
+exports.TokenSigner = TokenSigner;

package/dist/types.d.ts

@@ -0,0 +1,87 @@
+export interface BucketPolicy {
+    public: boolean;
+}
+export interface LocalConfig {
+    storagePath: string;
+    baseUrl: string;
+    secretKey: string;
+    defaultExpiry?: number;
+    buckets?: Record<string, BucketPolicy>;
+}
+export interface S3AdaptorConfig {
+    defaultType: 's3' | 'local';
+    s3?: {
+        region: string;
+        credentials?: {
+            accessKeyId: string;
+            secretAccessKey: string;
+        };
+        endpoint?: string;
+        forcePathStyle?: boolean;
+    };
+    local?: LocalConfig;
+}
+export interface PutObjectParams {
+    Bucket: string;
+    Key: string;
+    Body: Buffer | NodeJS.ReadableStream | string;
+    ContentType?: string;
+    Metadata?: Record<string, string>;
+}
+export interface UploadObjectParams {
+    Bucket: string;
+    Key: string;
+    Body: Buffer | NodeJS.ReadableStream | string;
+    ContentType?: string;
+}
+export interface GetObjectParams {
+    Bucket: string;
+    Key: string;
+}
+export interface DeleteObjectParams {
+    Bucket: string;
+    Key: string;
+}
+export interface ListObjectsParams {
+    Bucket: string;
+    Prefix?: string;
+    MaxKeys?: number;
+}
+export interface CopyObjectParams {
+    Bucket: string;
+    Key: string;
+    CopySource: string;
+    ContentType?: string;
+    Metadata?: Record<string, string>;
+}
+export interface GetSignedUrlParams {
+    Bucket: string;
+    Key: string;
+    Expires?: number;
+    ResponseContentDisposition?: string;
+    operation?: 'get' | 'put';
+    ContentType?: string;
+}
+export interface GetObjectResult {
+    Body: NodeJS.ReadableStream;
+    ContentType?: string;
+    ContentLength?: number;
+    Metadata?: Record<string, string>;
+    ETag?: string;
+}
+export interface ListObjectsResult {
+    Contents: Array<{
+        Key: string;
+        Size: number;
+        LastModified: Date;
+        ETag?: string;
+    }>;
+    IsTruncated: boolean;
+}
+export interface StoredMetadata {
+    ContentType?: string;
+    Metadata?: Record<string, string>;
+    ETag: string;
+    Size: number;
+    LastModified: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "s3-adaptor",
+  "version": "0.2.0",
+  "description": "Adapter-pattern interface for AWS S3 and local filesystem storage, with signed URLs and Express middleware",
+  "license": "BSD-3-Clause",
+  "author": "Kevin Foster <kevin.foster.uk@gmail.com>",
+  "homepage": "https://github.com/kevin-foster-uk/s3-adaptor#readme",
+  "bugs": {
+    "url": "https://github.com/kevin-foster-uk/s3-adaptor/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kevin-foster-uk/s3-adaptor.git"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "/dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "config": {
+    "commitizen": {
+      "path": "cz-customizable"
+    }
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.1142.0",
+    "@aws-sdk/lib-storage": "^3.1142.0",
+    "@aws-sdk/s3-request-presigner": "^3.1142.0"
+  },
+  "peerDependencies": {
+    "express": "^4.0.0 || ^5.0.0"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^3.0.3",
+    "@cspell/dict-node": "^5.0.9",
+    "@cspell/dict-npm": "^5.2.50",
+    "@cspell/dict-typescript": "^3.2.3",
+    "@types/express": "^5.0.6",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.19.43",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "commitizen": "^4.3.2",
+    "cspell": "^9.8.0",
+    "cz-customizable": "^7.5.4",
+    "eslint": "^8.57.1",
+    "jest": "^29.7.0",
+    "memfs": "^4.79.0",
+    "prettier": "^3.9.9",
+    "ts-jest": "^29.4.14",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "pnpm -r typecheck",
+    "test": "jest",
+    "compile": "pnpm format && pnpm build && pnpm typecheck && pnpm test",
+    "test:watch": "jest --watch",
+    "format": "prettier --write ./src",
+    "lint": "eslint src --ext .ts",
+    "commit": "cz",
+    "changeset": "changeset"
+  }
+}