@agentback/files-s3 0.3.0

package/LICENSE

@@ -0,0 +1,33 @@
+Copyright (c) Ninemind.ai 2026.
+Node module: AgentBack
+This project is licensed under the MIT License, full text below.
+
+--------
+
+MIT License
+
+Copyright (c) Ninemind.ai 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and
+associated documentation files (the "Software"), to deal in the Software without
+restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished
+to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE
+AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# @agentback/files-s3
+
+> S3-backed `FileStore` adapter for [`@agentback/files`](../files).
+
+Implements the `FileStore` port against any S3-compatible backend (AWS S3,
+localstack, MinIO, R2) using AWS SDK v3. Uploads stream through
+`@aws-sdk/lib-storage`'s `Upload` (no full-file buffering); downloads stream
+from `GetObject`. Ports the proven dapp5 `s3.service` recipe onto the port.
+
+## Usage
+
+```ts
+import {S3FileStore} from '@agentback/files-s3';
+import {FILE_STORE} from '@agentback/files';
+
+const store = new S3FileStore({
+  bucket: 'my-uploads',
+  keyPrefix: 'files/',                 // optional namespacing
+  clientConfig: {region: 'us-east-1'}, // or pass an existing {client}
+});
+
+app.bind(FILE_STORE).to(store);        // the REST file recipe now uses S3
+```
+
+- **`put`** streams the body to S3, recording `filename` in object metadata and
+  `contentType` as `Content-Type`; returns size + ETag (via a follow-up HEAD).
+- **`get`** returns the object stream + metadata; a missing key throws
+  `FileNotFoundError` (→ 404 at the REST layer).
+- **`exists`/`delete`** map to HeadObject/DeleteObject.
+- **`presignedPut`/`presignedGet`** issue time-limited URLs for a
+  direct-to-S3 flow (default 15 min).
+
+## Testing
+
+The conformance suite from `@agentback/files/testing` runs against a real
+endpoint, gated on env (skipped otherwise — same pattern as the BullMQ/Redis
+tests):
+
+```bash
+S3_TEST_ENDPOINT=http://localhost:4566 S3_TEST_BUCKET=test \
+AWS_ACCESS_KEY_ID=test AWS_SECRET_ACCESS_KEY=test \
+  pnpm -F @agentback/files-s3 test
+```

package/dist/__tests__/integration/s3-file-store.integration.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=s3-file-store.integration.d.ts.map

package/dist/__tests__/integration/s3-file-store.integration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3-file-store.integration.d.ts","sourceRoot":"","sources":["../../../src/__tests__/integration/s3-file-store.integration.ts"],"names":[],"mappings":""}

package/dist/__tests__/integration/s3-file-store.integration.js

@@ -0,0 +1,35 @@
+// Copyright Ninemind.ai 2026. All Rights Reserved.
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/license/mit/
+import { describe, it } from 'vitest';
+import { runFileStoreConformance } from '@agentback/files/testing';
+import { S3FileStore } from '../../index.js';
+// Gated like the BullMQ/Redis tests: runs only against a real S3-compatible
+// endpoint (localstack/minio/AWS). Set S3_TEST_ENDPOINT + S3_TEST_BUCKET
+// (and AWS creds) to exercise it; otherwise it is skipped.
+const endpoint = process.env.S3_TEST_ENDPOINT;
+const bucket = process.env.S3_TEST_BUCKET;
+if (endpoint && bucket) {
+    runFileStoreConformance('S3FileStore', () => new S3FileStore({
+        bucket,
+        keyPrefix: 'files-s3-test/',
+        clientConfig: {
+            endpoint,
+            region: process.env.AWS_REGION ?? 'us-east-1',
+            forcePathStyle: true, // localstack/minio path-style addressing
+            credentials: {
+                accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? 'test',
+                secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? 'test',
+            },
+        },
+    }));
+}
+else {
+    // eslint-disable-next-line no-console
+    console.log('[files-s3] S3_TEST_ENDPOINT / S3_TEST_BUCKET not set — skipping S3 ' +
+        'conformance (point them at localstack/minio/AWS to run)');
+    describe.skip('S3FileStore conformance (needs S3_TEST_ENDPOINT + S3_TEST_BUCKET)', () => {
+        it('skipped — no S3 endpoint configured', () => { });
+    });
+}
+//# sourceMappingURL=s3-file-store.integration.js.map

package/dist/__tests__/integration/s3-file-store.integration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3-file-store.integration.js","sourceRoot":"","sources":["../../../src/__tests__/integration/s3-file-store.integration.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,+CAA+C;AAC/C,gEAAgE;AAEhE,OAAO,EAAC,QAAQ,EAAE,EAAE,EAAC,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAC,uBAAuB,EAAC,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAE3C,4EAA4E;AAC5E,yEAAyE;AACzE,2DAA2D;AAC3D,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;AAC9C,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;AAE1C,IAAI,QAAQ,IAAI,MAAM,EAAE,CAAC;IACvB,uBAAuB,CACrB,aAAa,EACb,GAAG,EAAE,CACH,IAAI,WAAW,CAAC;QACd,MAAM;QACN,SAAS,EAAE,gBAAgB;QAC3B,YAAY,EAAE;YACZ,QAAQ;YACR,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,WAAW;YAC7C,cAAc,EAAE,IAAI,EAAE,yCAAyC;YAC/D,WAAW,EAAE;gBACX,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,MAAM;gBACpD,eAAe,EAAE,OAAO,CAAC,GAAG,CAAC,qBAAqB,IAAI,MAAM;aAC7D;SACF;KACF,CAAC,CACL,CAAC;AACJ,CAAC;KAAM,CAAC;IACN,sCAAsC;IACtC,OAAO,CAAC,GAAG,CACT,qEAAqE;QACnE,yDAAyD,CAC5D,CAAC;IACF,QAAQ,CAAC,IAAI,CAAC,mEAAmE,EAAE,GAAG,EAAE;QACtF,EAAE,CAAC,qCAAqC,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACtD,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { S3FileStore, type S3FileStoreOptions } from './s3-file-store.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAC,WAAW,EAAE,KAAK,kBAAkB,EAAC,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+// Copyright Ninemind.ai 2026. All Rights Reserved.
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/license/mit/
+export { S3FileStore } from './s3-file-store.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,+CAA+C;AAC/C,gEAAgE;AAEhE,OAAO,EAAC,WAAW,EAA0B,MAAM,oBAAoB,CAAC"}

package/dist/s3-file-store.d.ts

@@ -0,0 +1,34 @@
+import type { Readable } from 'node:stream';
+import { S3Client, type S3ClientConfig } from '@aws-sdk/client-s3';
+import { type FileStore, type PresignOptions, type PutOptions, type RetrievedFile, type StoredFile } from '@agentback/files';
+export interface S3FileStoreOptions {
+    /** Target bucket. */
+    bucket: string;
+    /** Reuse an existing client, or… */
+    client?: S3Client;
+    /** …construct one from this config (region, endpoint, credentials, …). */
+    clientConfig?: S3ClientConfig;
+    /** Optional key prefix namespacing every object (e.g. `'uploads/'`). */
+    keyPrefix?: string;
+}
+/**
+ * S3-backed {@link FileStore}. Streams uploads via `@aws-sdk/lib-storage`'s
+ * `Upload` (no full-file buffering) and streams downloads from `GetObject`,
+ * recording `filename` in object metadata. Ports the dapp5 `s3.service`
+ * recipe onto the framework port. Also implements the optional presigned-URL
+ * hooks for a direct-to-S3 flow.
+ */
+export declare class S3FileStore implements FileStore {
+    private readonly client;
+    private readonly bucket;
+    private readonly prefix;
+    constructor(opts: S3FileStoreOptions);
+    private k;
+    put(key: string, body: Readable | Buffer, opts?: PutOptions): Promise<StoredFile>;
+    get(key: string): Promise<RetrievedFile>;
+    exists(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    presignedPut(key: string, opts?: PutOptions & PresignOptions): Promise<string>;
+    presignedGet(key: string, opts?: PresignOptions): Promise<string>;
+}
+//# sourceMappingURL=s3-file-store.d.ts.map

package/dist/s3-file-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3-file-store.d.ts","sourceRoot":"","sources":["../src/s3-file-store.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,aAAa,CAAC;AAC1C,OAAO,EAKL,QAAQ,EACR,KAAK,cAAc,EACpB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAEL,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,UAAU,EAChB,MAAM,kBAAkB,CAAC;AAE1B,MAAM,WAAW,kBAAkB;IACjC,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,0EAA0E;IAC1E,YAAY,CAAC,EAAE,cAAc,CAAC;IAC9B,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,qBAAa,WAAY,YAAW,SAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,IAAI,EAAE,kBAAkB;IAMpC,OAAO,CAAC,CAAC;IAIH,GAAG,CACP,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,QAAQ,GAAG,MAAM,EACvB,IAAI,GAAE,UAAe,GACpB,OAAO,CAAC,UAAU,CAAC;IA2BhB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAmBxC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAYrC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMlC,YAAY,CAChB,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,UAAU,GAAG,cAAmB,GACrC,OAAO,CAAC,MAAM,CAAC;IAYZ,YAAY,CAChB,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,MAAM,CAAC;CAOnB"}

package/dist/s3-file-store.js

@@ -0,0 +1,98 @@
+// Copyright Ninemind.ai 2026. All Rights Reserved.
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/license/mit/
+import { DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, PutObjectCommand, S3Client, } from '@aws-sdk/client-s3';
+import { Upload } from '@aws-sdk/lib-storage';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+import { FileNotFoundError, } from '@agentback/files';
+/**
+ * S3-backed {@link FileStore}. Streams uploads via `@aws-sdk/lib-storage`'s
+ * `Upload` (no full-file buffering) and streams downloads from `GetObject`,
+ * recording `filename` in object metadata. Ports the dapp5 `s3.service`
+ * recipe onto the framework port. Also implements the optional presigned-URL
+ * hooks for a direct-to-S3 flow.
+ */
+export class S3FileStore {
+    constructor(opts) {
+        this.client = opts.client ?? new S3Client(opts.clientConfig ?? {});
+        this.bucket = opts.bucket;
+        this.prefix = opts.keyPrefix ?? '';
+    }
+    k(key) {
+        return this.prefix + key;
+    }
+    async put(key, body, opts = {}) {
+        const upload = new Upload({
+            client: this.client,
+            params: {
+                Bucket: this.bucket,
+                Key: this.k(key),
+                Body: body,
+                ...(opts.contentType ? { ContentType: opts.contentType } : {}),
+                Metadata: {
+                    ...(opts.filename ? { filename: opts.filename } : {}),
+                    ...(opts.metadata ?? {}),
+                },
+            },
+        });
+        const res = await upload.done();
+        // lib-storage doesn't return the stored size; a HEAD is the reliable source.
+        const head = await this.client.send(new HeadObjectCommand({ Bucket: this.bucket, Key: this.k(key) }));
+        return {
+            key,
+            size: head.ContentLength ?? 0,
+            contentType: head.ContentType,
+            etag: res.ETag ?? head.ETag,
+        };
+    }
+    async get(key) {
+        try {
+            const res = await this.client.send(new GetObjectCommand({ Bucket: this.bucket, Key: this.k(key) }));
+            return {
+                key,
+                stream: res.Body,
+                size: res.ContentLength ?? 0,
+                contentType: res.ContentType,
+                filename: res.Metadata?.filename,
+                metadata: res.Metadata,
+            };
+        }
+        catch (err) {
+            if (isNotFound(err))
+                throw new FileNotFoundError(key);
+            throw err;
+        }
+    }
+    async exists(key) {
+        try {
+            await this.client.send(new HeadObjectCommand({ Bucket: this.bucket, Key: this.k(key) }));
+            return true;
+        }
+        catch (err) {
+            if (isNotFound(err))
+                return false;
+            throw err;
+        }
+    }
+    async delete(key) {
+        await this.client.send(new DeleteObjectCommand({ Bucket: this.bucket, Key: this.k(key) }));
+    }
+    async presignedPut(key, opts = {}) {
+        return getSignedUrl(this.client, new PutObjectCommand({
+            Bucket: this.bucket,
+            Key: this.k(key),
+            ...(opts.contentType ? { ContentType: opts.contentType } : {}),
+        }), { expiresIn: opts.expiresInSec ?? 900 });
+    }
+    async presignedGet(key, opts = {}) {
+        return getSignedUrl(this.client, new GetObjectCommand({ Bucket: this.bucket, Key: this.k(key) }), { expiresIn: opts.expiresInSec ?? 900 });
+    }
+}
+/** S3 "not found" across GetObject (NoSuchKey) and HeadObject (NotFound/404). */
+function isNotFound(err) {
+    const e = err;
+    return (e?.name === 'NoSuchKey' ||
+        e?.name === 'NotFound' ||
+        e?.$metadata?.httpStatusCode === 404);
+}
+//# sourceMappingURL=s3-file-store.js.map

package/dist/s3-file-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3-file-store.js","sourceRoot":"","sources":["../src/s3-file-store.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@agentback/files-s3",
+  "version": "0.3.0",
+  "description": "S3-backed FileStore adapter for @agentback/files (AWS SDK v3 + lib-storage streaming)",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.658.0",
+    "@aws-sdk/lib-storage": "^3.658.0",
+    "@aws-sdk/s3-request-presigner": "^3.658.0",
+    "tslib": "^2.8.1",
+    "@agentback/files": "~0.3.0"
+  },
+  "devDependencies": {
+    "vitest": "~4.1.8"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}

package/src/__tests__/integration/s3-file-store.integration.ts

@@ -0,0 +1,42 @@
+// Copyright Ninemind.ai 2026. All Rights Reserved.
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/license/mit/
+
+import {describe, it} from 'vitest';
+import {runFileStoreConformance} from '@agentback/files/testing';
+import {S3FileStore} from '../../index.js';
+
+// Gated like the BullMQ/Redis tests: runs only against a real S3-compatible
+// endpoint (localstack/minio/AWS). Set S3_TEST_ENDPOINT + S3_TEST_BUCKET
+// (and AWS creds) to exercise it; otherwise it is skipped.
+const endpoint = process.env.S3_TEST_ENDPOINT;
+const bucket = process.env.S3_TEST_BUCKET;
+
+if (endpoint && bucket) {
+  runFileStoreConformance(
+    'S3FileStore',
+    () =>
+      new S3FileStore({
+        bucket,
+        keyPrefix: 'files-s3-test/',
+        clientConfig: {
+          endpoint,
+          region: process.env.AWS_REGION ?? 'us-east-1',
+          forcePathStyle: true, // localstack/minio path-style addressing
+          credentials: {
+            accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? 'test',
+            secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? 'test',
+          },
+        },
+      }),
+  );
+} else {
+  // eslint-disable-next-line no-console
+  console.log(
+    '[files-s3] S3_TEST_ENDPOINT / S3_TEST_BUCKET not set — skipping S3 ' +
+      'conformance (point them at localstack/minio/AWS to run)',
+  );
+  describe.skip('S3FileStore conformance (needs S3_TEST_ENDPOINT + S3_TEST_BUCKET)', () => {
+    it('skipped — no S3 endpoint configured', () => {});
+  });
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+// Copyright Ninemind.ai 2026. All Rights Reserved.
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/license/mit/
+
+export {S3FileStore, type S3FileStoreOptions} from './s3-file-store.js';

package/src/s3-file-store.ts

@@ -0,0 +1,161 @@
+// Copyright Ninemind.ai 2026. All Rights Reserved.
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/license/mit/
+
+import type {Readable} from 'node:stream';
+import {
+  DeleteObjectCommand,
+  GetObjectCommand,
+  HeadObjectCommand,
+  PutObjectCommand,
+  S3Client,
+  type S3ClientConfig,
+} from '@aws-sdk/client-s3';
+import {Upload} from '@aws-sdk/lib-storage';
+import {getSignedUrl} from '@aws-sdk/s3-request-presigner';
+import {
+  FileNotFoundError,
+  type FileStore,
+  type PresignOptions,
+  type PutOptions,
+  type RetrievedFile,
+  type StoredFile,
+} from '@agentback/files';
+
+export interface S3FileStoreOptions {
+  /** Target bucket. */
+  bucket: string;
+  /** Reuse an existing client, or… */
+  client?: S3Client;
+  /** …construct one from this config (region, endpoint, credentials, …). */
+  clientConfig?: S3ClientConfig;
+  /** Optional key prefix namespacing every object (e.g. `'uploads/'`). */
+  keyPrefix?: string;
+}
+
+/**
+ * S3-backed {@link FileStore}. Streams uploads via `@aws-sdk/lib-storage`'s
+ * `Upload` (no full-file buffering) and streams downloads from `GetObject`,
+ * recording `filename` in object metadata. Ports the dapp5 `s3.service`
+ * recipe onto the framework port. Also implements the optional presigned-URL
+ * hooks for a direct-to-S3 flow.
+ */
+export class S3FileStore implements FileStore {
+  private readonly client: S3Client;
+  private readonly bucket: string;
+  private readonly prefix: string;
+
+  constructor(opts: S3FileStoreOptions) {
+    this.client = opts.client ?? new S3Client(opts.clientConfig ?? {});
+    this.bucket = opts.bucket;
+    this.prefix = opts.keyPrefix ?? '';
+  }
+
+  private k(key: string): string {
+    return this.prefix + key;
+  }
+
+  async put(
+    key: string,
+    body: Readable | Buffer,
+    opts: PutOptions = {},
+  ): Promise<StoredFile> {
+    const upload = new Upload({
+      client: this.client,
+      params: {
+        Bucket: this.bucket,
+        Key: this.k(key),
+        Body: body,
+        ...(opts.contentType ? {ContentType: opts.contentType} : {}),
+        Metadata: {
+          ...(opts.filename ? {filename: opts.filename} : {}),
+          ...(opts.metadata ?? {}),
+        },
+      },
+    });
+    const res = await upload.done();
+    // lib-storage doesn't return the stored size; a HEAD is the reliable source.
+    const head = await this.client.send(
+      new HeadObjectCommand({Bucket: this.bucket, Key: this.k(key)}),
+    );
+    return {
+      key,
+      size: head.ContentLength ?? 0,
+      contentType: head.ContentType,
+      etag: (res as {ETag?: string}).ETag ?? head.ETag,
+    };
+  }
+
+  async get(key: string): Promise<RetrievedFile> {
+    try {
+      const res = await this.client.send(
+        new GetObjectCommand({Bucket: this.bucket, Key: this.k(key)}),
+      );
+      return {
+        key,
+        stream: res.Body as Readable,
+        size: res.ContentLength ?? 0,
+        contentType: res.ContentType,
+        filename: res.Metadata?.filename,
+        metadata: res.Metadata,
+      };
+    } catch (err) {
+      if (isNotFound(err)) throw new FileNotFoundError(key);
+      throw err;
+    }
+  }
+
+  async exists(key: string): Promise<boolean> {
+    try {
+      await this.client.send(
+        new HeadObjectCommand({Bucket: this.bucket, Key: this.k(key)}),
+      );
+      return true;
+    } catch (err) {
+      if (isNotFound(err)) return false;
+      throw err;
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.client.send(
+      new DeleteObjectCommand({Bucket: this.bucket, Key: this.k(key)}),
+    );
+  }
+
+  async presignedPut(
+    key: string,
+    opts: PutOptions & PresignOptions = {},
+  ): Promise<string> {
+    return getSignedUrl(
+      this.client,
+      new PutObjectCommand({
+        Bucket: this.bucket,
+        Key: this.k(key),
+        ...(opts.contentType ? {ContentType: opts.contentType} : {}),
+      }),
+      {expiresIn: opts.expiresInSec ?? 900},
+    );
+  }
+
+  async presignedGet(
+    key: string,
+    opts: PresignOptions = {},
+  ): Promise<string> {
+    return getSignedUrl(
+      this.client,
+      new GetObjectCommand({Bucket: this.bucket, Key: this.k(key)}),
+      {expiresIn: opts.expiresInSec ?? 900},
+    );
+  }
+}
+
+/** S3 "not found" across GetObject (NoSuchKey) and HeadObject (NotFound/404). */
+function isNotFound(err: unknown): boolean {
+  const e = err as {name?: string; $metadata?: {httpStatusCode?: number}};
+  return (
+    e?.name === 'NoSuchKey' ||
+    e?.name === 'NotFound' ||
+    e?.$metadata?.httpStatusCode === 404
+  );
+}