@syncular/server-storage-s3 0.0.0

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@syncular/server-storage-s3",
+  "version": "0.0.0",
+  "description": "S3-compatible blob storage adapter for Syncular server",
+  "license": "MIT",
+  "author": "Benjamin Kniffler",
+  "homepage": "https://syncular.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/syncular/syncular.git",
+    "directory": "packages/server-storage-s3"
+  },
+  "bugs": {
+    "url": "https://github.com/syncular/syncular/issues"
+  },
+  "keywords": [
+    "sync",
+    "offline-first",
+    "blob",
+    "storage",
+    "s3"
+  ],
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "scripts": {
+    "test": "bun test --pass-with-no-tests",
+    "tsgo": "tsgo --noEmit",
+    "build": "tsgo",
+    "release": "bunx syncular-publish"
+  },
+  "dependencies": {
+    "@syncular/core": "0.0.0"
+  },
+  "devDependencies": {
+    "@syncular/config": "0.0.0"
+  },
+  "files": [
+    "dist",
+    "src"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,522 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  createS3BlobStorageAdapter,
+  type GetSignedUrlFn,
+  type S3ClientLike,
+  type S3Commands,
+} from './index';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const TEST_BUCKET = 'test-bucket';
+const TEST_HASH =
+  'sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890';
+const TEST_HEX =
+  'abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890';
+
+/** Compute the expected base64 of a hex hash (used in checksum headers). */
+function hexToBase64(hex: string): string {
+  return Buffer.from(hex, 'hex').toString('base64');
+}
+
+// ---------------------------------------------------------------------------
+// Tag types so the mock client can identify which command was sent
+// ---------------------------------------------------------------------------
+
+const PUT_TAG = Symbol('PutObjectCommand');
+const GET_TAG = Symbol('GetObjectCommand');
+const HEAD_TAG = Symbol('HeadObjectCommand');
+const DELETE_TAG = Symbol('DeleteObjectCommand');
+
+interface MockCommand {
+  __tag: symbol;
+  input: Record<string, unknown>;
+}
+
+function createMockCommands(): S3Commands {
+  return {
+    PutObjectCommand: class {
+      __tag = PUT_TAG;
+      input: Record<string, unknown>;
+      constructor(input: Record<string, unknown>) {
+        this.input = input;
+      }
+    } as unknown as S3Commands['PutObjectCommand'],
+
+    GetObjectCommand: class {
+      __tag = GET_TAG;
+      input: Record<string, unknown>;
+      constructor(input: Record<string, unknown>) {
+        this.input = input;
+      }
+    } as unknown as S3Commands['GetObjectCommand'],
+
+    HeadObjectCommand: class {
+      __tag = HEAD_TAG;
+      input: Record<string, unknown>;
+      constructor(input: Record<string, unknown>) {
+        this.input = input;
+      }
+    } as unknown as S3Commands['HeadObjectCommand'],
+
+    DeleteObjectCommand: class {
+      __tag = DELETE_TAG;
+      input: Record<string, unknown>;
+      constructor(input: Record<string, unknown>) {
+        this.input = input;
+      }
+    } as unknown as S3Commands['DeleteObjectCommand'],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Mock S3 client
+// ---------------------------------------------------------------------------
+
+interface SendCall {
+  tag: symbol;
+  input: Record<string, unknown>;
+}
+
+function createMockS3Client(options?: {
+  /** Value returned by send(). Can be a function of the command tag. */
+  response?:
+    | Record<string, unknown>
+    | ((tag: symbol) => Record<string, unknown>);
+  /** When true, send() rejects with a NotFound-style error. */
+  notFound?: boolean;
+}) {
+  const calls: SendCall[] = [];
+
+  const client: S3ClientLike = {
+    async send(command: unknown) {
+      const cmd = command as MockCommand;
+      calls.push({ tag: cmd.__tag, input: cmd.input });
+
+      if (options?.notFound) {
+        const err = new Error('NotFound') as Error & {
+          name: string;
+          $metadata: { httpStatusCode: number };
+        };
+        err.name = 'NotFound';
+        err.$metadata = { httpStatusCode: 404 };
+        throw err;
+      }
+
+      if (typeof options?.response === 'function') {
+        return options.response(cmd.__tag);
+      }
+      return options?.response ?? {};
+    },
+  };
+
+  return { client, calls };
+}
+
+// ---------------------------------------------------------------------------
+// Mock getSignedUrl
+// ---------------------------------------------------------------------------
+
+interface SignedUrlCall {
+  command: MockCommand;
+  options: { expiresIn: number };
+}
+
+function createMockGetSignedUrl(): {
+  fn: GetSignedUrlFn;
+  calls: SignedUrlCall[];
+} {
+  const calls: SignedUrlCall[] = [];
+  const fn: GetSignedUrlFn = async (_client, command, options) => {
+    const cmd = command as MockCommand;
+    calls.push({ command: cmd, options });
+    return `https://s3.example.com/presigned/${cmd.input.Key as string}`;
+  };
+  return { fn, calls };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('createS3BlobStorageAdapter', () => {
+  // ---- signUpload ----
+  describe('signUpload', () => {
+    test('returns presigned URL with correct method and headers', async () => {
+      const commands = createMockCommands();
+      const { client } = createMockS3Client();
+      const { fn: getSignedUrl, calls: signCalls } = createMockGetSignedUrl();
+
+      const adapter = createS3BlobStorageAdapter({
+        client,
+        bucket: TEST_BUCKET,
+        commands,
+        getSignedUrl,
+        requireChecksum: false,
+      });
+
+      const result = await adapter.signUpload({
+        hash: TEST_HASH,
+        size: 1024,
+        mimeType: 'image/png',
+        expiresIn: 300,
+      });
+
+      expect(result.method).toBe('PUT');
+      expect(result.url).toContain(TEST_HEX);
+      expect(result.headers).toBeDefined();
+      expect(result.headers!['Content-Type']).toBe('image/png');
+      expect(result.headers!['Content-Length']).toBe('1024');
+      // No checksum header when requireChecksum=false
+      expect(result.headers!['x-amz-checksum-sha256']).toBeUndefined();
+
+      // Verify the presigner was called with the right expiresIn
+      expect(signCalls).toHaveLength(1);
+      expect(signCalls[0]!.options.expiresIn).toBe(300);
+
+      // Verify PutObjectCommand was constructed with correct bucket/key
+      const cmdInput = signCalls[0]!.command.input;
+      expect(cmdInput.Bucket).toBe(TEST_BUCKET);
+      expect(cmdInput.Key).toBe(TEST_HEX);
+    });
+
+    test('includes checksum header when requireChecksum=true', async () => {
+      const commands = createMockCommands();
+      const { client } = createMockS3Client();
+      const { fn: getSignedUrl } = createMockGetSignedUrl();
+
+      const adapter = createS3BlobStorageAdapter({
+        client,
+        bucket: TEST_BUCKET,
+        commands,
+        getSignedUrl,
+        requireChecksum: true,
+      });
+
+      const result = await adapter.signUpload({
+        hash: TEST_HASH,
+        size: 512,
+        mimeType: 'application/octet-stream',
+        expiresIn: 60,
+      });
+
+      const expectedBase64 = hexToBase64(TEST_HEX);
+      expect(result.headers!['x-amz-checksum-sha256']).toBe(expectedBase64);
+    });
+  });
+
+  // ---- signDownload ----
+  describe('signDownload', () => {
+    test('returns presigned URL', async () => {
+      const commands = createMockCommands();
+      const { client } = createMockS3Client();
+      const { fn: getSignedUrl, calls: signCalls } = createMockGetSignedUrl();
+
+      const adapter = createS3BlobStorageAdapter({
+        client,
+        bucket: TEST_BUCKET,
+        commands,
+        getSignedUrl,
+      });
+
+      const url = await adapter.signDownload({
+        hash: TEST_HASH,
+        expiresIn: 120,
+      });
+
+      expect(url).toContain(TEST_HEX);
+      expect(signCalls).toHaveLength(1);
+      expect(signCalls[0]!.options.expiresIn).toBe(120);
+
+      // Verify GetObjectCommand was used
+      expect(signCalls[0]!.command.__tag).toBe(GET_TAG);
+      expect(signCalls[0]!.command.input.Bucket).toBe(TEST_BUCKET);
+      expect(signCalls[0]!.command.input.Key).toBe(TEST_HEX);
+    });
+  });
+
+  // ---- exists ----
+  describe('exists', () => {
+    test('returns true when HeadObject succeeds', async () => {
+      const commands = createMockCommands();
+      const { client } = createMockS3Client();
+      const { fn: getSignedUrl } = createMockGetSignedUrl();
+
+      const adapter = createS3BlobStorageAdapter({
+        client,
+        bucket: TEST_BUCKET,
+        commands,
+        getSignedUrl,
+      });
+
+      expect(await adapter.exists(TEST_HASH)).toBe(true);
+    });
+
+    test('returns false on NotFound error', async () => {
+      const commands = createMockCommands();
+      const { client } = createMockS3Client({ notFound: true });
+      const { fn: getSignedUrl } = createMockGetSignedUrl();
+
+      const adapter = createS3BlobStorageAdapter({
+        client,
+        bucket: TEST_BUCKET,
+        commands,
+        getSignedUrl,
+      });
+
+      expect(await adapter.exists(TEST_HASH)).toBe(false);
+    });
+  });
+
+  // ---- delete ----
+  describe('delete', () => {
+    test('calls DeleteObjectCommand with correct bucket and key', async () => {
+      const commands = createMockCommands();
+      const { client, calls } = createMockS3Client();
+      const { fn: getSignedUrl } = createMockGetSignedUrl();
+
+      const adapter = createS3BlobStorageAdapter({
+        client,
+        bucket: TEST_BUCKET,
+        commands,
+        getSignedUrl,
+      });
+
+      await adapter.delete(TEST_HASH);
+
+      expect(calls).toHaveLength(1);
+      expect(calls[0]!.tag).toBe(DELETE_TAG);
+      expect(calls[0]!.input.Bucket).toBe(TEST_BUCKET);
+      expect(calls[0]!.input.Key).toBe(TEST_HEX);
+    });
+  });
+
+  // ---- getMetadata ----
+  describe('getMetadata', () => {
+    test('returns size and mimeType from HeadObject', async () => {
+      const commands = createMockCommands();
+      const { client } = createMockS3Client({
+        response: { ContentLength: 2048, ContentType: 'image/jpeg' },
+      });
+      const { fn: getSignedUrl } = createMockGetSignedUrl();
+
+      const adapter = createS3BlobStorageAdapter({
+        client,
+        bucket: TEST_BUCKET,
+        commands,
+        getSignedUrl,
+      });
+
+      const meta = await adapter.getMetadata!(TEST_HASH);
+      expect(meta).toEqual({ size: 2048, mimeType: 'image/jpeg' });
+    });
+
+    test('returns null on NotFound', async () => {
+      const commands = createMockCommands();
+      const { client } = createMockS3Client({ notFound: true });
+      const { fn: getSignedUrl } = createMockGetSignedUrl();
+
+      const adapter = createS3BlobStorageAdapter({
+        client,
+        bucket: TEST_BUCKET,
+        commands,
+        getSignedUrl,
+      });
+
+      const meta = await adapter.getMetadata!(TEST_HASH);
+      expect(meta).toBeNull();
+    });
+  });
+
+  // ---- put ----
+  describe('put', () => {
+    test('calls PutObjectCommand with Body and correct key', async () => {
+      const commands = createMockCommands();
+      const { client, calls } = createMockS3Client();
+      const { fn: getSignedUrl } = createMockGetSignedUrl();
+
+      const adapter = createS3BlobStorageAdapter({
+        client,
+        bucket: TEST_BUCKET,
+        commands,
+        getSignedUrl,
+      });
+
+      const data = new Uint8Array([1, 2, 3, 4]);
+      await adapter.put!(TEST_HASH, data);
+
+      expect(calls).toHaveLength(1);
+      expect(calls[0]!.tag).toBe(PUT_TAG);
+      expect(calls[0]!.input.Bucket).toBe(TEST_BUCKET);
+      expect(calls[0]!.input.Key).toBe(TEST_HEX);
+      expect(calls[0]!.input.Body).toBe(data);
+      expect(calls[0]!.input.ContentLength).toBe(4);
+      expect(calls[0]!.input.ContentType).toBe('application/octet-stream');
+    });
+  });
+
+  // ---- get ----
+  describe('get', () => {
+    test('returns Uint8Array from transformToByteArray', async () => {
+      const expectedBytes = new Uint8Array([10, 20, 30]);
+      const commands = createMockCommands();
+      const { client } = createMockS3Client({
+        response: {
+          Body: {
+            transformToByteArray: async () => expectedBytes,
+          },
+        },
+      });
+      const { fn: getSignedUrl } = createMockGetSignedUrl();
+
+      const adapter = createS3BlobStorageAdapter({
+        client,
+        bucket: TEST_BUCKET,
+        commands,
+        getSignedUrl,
+      });
+
+      const result = await adapter.get!(TEST_HASH);
+      expect(result).toBe(expectedBytes);
+    });
+
+    test('returns null on NotFound', async () => {
+      const commands = createMockCommands();
+      const { client } = createMockS3Client({ notFound: true });
+      const { fn: getSignedUrl } = createMockGetSignedUrl();
+
+      const adapter = createS3BlobStorageAdapter({
+        client,
+        bucket: TEST_BUCKET,
+        commands,
+        getSignedUrl,
+      });
+
+      const result = await adapter.get!(TEST_HASH);
+      expect(result).toBeNull();
+    });
+  });
+
+  // ---- getStream ----
+  describe('getStream', () => {
+    test('returns ReadableStream from transformToWebStream', async () => {
+      const mockStream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          controller.enqueue(new Uint8Array([5, 6, 7]));
+          controller.close();
+        },
+      });
+
+      const commands = createMockCommands();
+      const { client } = createMockS3Client({
+        response: {
+          Body: {
+            transformToWebStream: () => mockStream,
+          },
+        },
+      });
+      const { fn: getSignedUrl } = createMockGetSignedUrl();
+
+      const adapter = createS3BlobStorageAdapter({
+        client,
+        bucket: TEST_BUCKET,
+        commands,
+        getSignedUrl,
+      });
+
+      const result = await adapter.getStream!(TEST_HASH);
+      expect(result).toBe(mockStream);
+    });
+
+    test('returns null on NotFound', async () => {
+      const commands = createMockCommands();
+      const { client } = createMockS3Client({ notFound: true });
+      const { fn: getSignedUrl } = createMockGetSignedUrl();
+
+      const adapter = createS3BlobStorageAdapter({
+        client,
+        bucket: TEST_BUCKET,
+        commands,
+        getSignedUrl,
+      });
+
+      const result = await adapter.getStream!(TEST_HASH);
+      expect(result).toBeNull();
+    });
+  });
+
+  // ---- key prefix ----
+  describe('key prefix', () => {
+    test('prepends keyPrefix to all keys', async () => {
+      const commands = createMockCommands();
+      const { client, calls } = createMockS3Client();
+      const { fn: getSignedUrl, calls: signCalls } = createMockGetSignedUrl();
+
+      const adapter = createS3BlobStorageAdapter({
+        client,
+        bucket: TEST_BUCKET,
+        keyPrefix: 'blobs/',
+        commands,
+        getSignedUrl,
+      });
+
+      // exists -> HeadObjectCommand
+      await adapter.exists(TEST_HASH);
+      expect(calls[0]!.input.Key).toBe(`blobs/${TEST_HEX}`);
+
+      // delete -> DeleteObjectCommand
+      await adapter.delete(TEST_HASH);
+      expect(calls[1]!.input.Key).toBe(`blobs/${TEST_HEX}`);
+
+      // signUpload -> PutObjectCommand via presigner
+      await adapter.signUpload({
+        hash: TEST_HASH,
+        size: 100,
+        mimeType: 'text/plain',
+        expiresIn: 60,
+      });
+      expect(signCalls[0]!.command.input.Key).toBe(`blobs/${TEST_HEX}`);
+
+      // signDownload -> GetObjectCommand via presigner
+      await adapter.signDownload({ hash: TEST_HASH, expiresIn: 60 });
+      expect(signCalls[1]!.command.input.Key).toBe(`blobs/${TEST_HEX}`);
+    });
+  });
+
+  // ---- hash stripping ----
+  describe('hash stripping', () => {
+    test('strips "sha256:" prefix from hash to form the key', async () => {
+      const commands = createMockCommands();
+      const { client, calls } = createMockS3Client();
+      const { fn: getSignedUrl } = createMockGetSignedUrl();
+
+      const adapter = createS3BlobStorageAdapter({
+        client,
+        bucket: TEST_BUCKET,
+        commands,
+        getSignedUrl,
+      });
+
+      await adapter.exists('sha256:deadbeef');
+      expect(calls[0]!.input.Key).toBe('deadbeef');
+    });
+
+    test('leaves hashes without "sha256:" prefix unchanged', async () => {
+      const commands = createMockCommands();
+      const { client, calls } = createMockS3Client();
+      const { fn: getSignedUrl } = createMockGetSignedUrl();
+
+      const adapter = createS3BlobStorageAdapter({
+        client,
+        bucket: TEST_BUCKET,
+        commands,
+        getSignedUrl,
+      });
+
+      await adapter.exists('deadbeef');
+      expect(calls[0]!.input.Key).toBe('deadbeef');
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,324 @@
+/**
+ * S3-compatible blob storage adapter.
+ *
+ * Works with AWS S3, Cloudflare R2, MinIO, and other S3-compatible services.
+ * Requires @aws-sdk/client-s3 and @aws-sdk/s3-request-presigner as peer dependencies.
+ */
+
+import type {
+  BlobSignDownloadOptions,
+  BlobSignedUpload,
+  BlobSignUploadOptions,
+  BlobStorageAdapter,
+} from '@syncular/core';
+
+/**
+ * S3 client interface (minimal subset of @aws-sdk/client-s3).
+ * This allows users to pass in their own configured S3 client.
+ */
+export interface S3ClientLike {
+  send(command: unknown): Promise<unknown>;
+}
+
+/**
+ * Function to create presigned URLs.
+ * This should be getSignedUrl from @aws-sdk/s3-request-presigner.
+ */
+export type GetSignedUrlFn = (
+  client: S3ClientLike,
+  command: unknown,
+  options: { expiresIn: number }
+) => Promise<string>;
+
+/**
+ * S3 command constructors.
+ * These should be imported from @aws-sdk/client-s3.
+ */
+export interface S3Commands {
+  PutObjectCommand: new (input: {
+    Bucket: string;
+    Key: string;
+    ContentLength?: number;
+    ContentType?: string;
+    ChecksumSHA256?: string;
+    Body?: Uint8Array | ReadableStream<Uint8Array>;
+  }) => unknown;
+  GetObjectCommand: new (input: { Bucket: string; Key: string }) => unknown;
+  HeadObjectCommand: new (input: { Bucket: string; Key: string }) => unknown;
+  DeleteObjectCommand: new (input: { Bucket: string; Key: string }) => unknown;
+}
+
+export interface S3BlobStorageAdapterOptions {
+  /** S3 client instance */
+  client: S3ClientLike;
+  /** S3 bucket name */
+  bucket: string;
+  /** Optional key prefix for all blobs */
+  keyPrefix?: string;
+  /** S3 command constructors */
+  commands: S3Commands;
+  /** getSignedUrl function from @aws-sdk/s3-request-presigner */
+  getSignedUrl: GetSignedUrlFn;
+  /**
+   * Whether to require SHA-256 checksum validation on upload.
+   * Supported by S3 and R2. Default: true.
+   */
+  requireChecksum?: boolean;
+}
+
+/**
+ * Create an S3-compatible blob storage adapter.
+ *
+ * @example
+ * ```typescript
+ * import { S3Client, PutObjectCommand, GetObjectCommand, HeadObjectCommand, DeleteObjectCommand } from '@aws-sdk/client-s3';
+ * import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+ *
+ * const adapter = createS3BlobStorageAdapter({
+ *   client: new S3Client({ region: 'us-east-1' }),
+ *   bucket: 'my-bucket',
+ *   keyPrefix: 'blobs/',
+ *   commands: { PutObjectCommand, GetObjectCommand, HeadObjectCommand, DeleteObjectCommand },
+ *   getSignedUrl,
+ * });
+ * ```
+ */
+export function createS3BlobStorageAdapter(
+  options: S3BlobStorageAdapterOptions
+): BlobStorageAdapter {
+  const {
+    client,
+    bucket,
+    keyPrefix = '',
+    commands,
+    getSignedUrl,
+    requireChecksum = true,
+  } = options;
+
+  function getKey(hash: string): string {
+    // Remove "sha256:" prefix and use hex as key
+    const hex = hash.startsWith('sha256:') ? hash.slice(7) : hash;
+    return `${keyPrefix}${hex}`;
+  }
+
+  return {
+    name: 's3',
+
+    async signUpload(opts: BlobSignUploadOptions): Promise<BlobSignedUpload> {
+      const key = getKey(opts.hash);
+
+      // Extract hex hash for checksum (S3 expects base64-encoded SHA-256)
+      const hexHash = opts.hash.startsWith('sha256:')
+        ? opts.hash.slice(7)
+        : opts.hash;
+
+      // Convert hex to base64 for S3 checksum header
+      const checksumBase64 = hexToBase64(hexHash);
+
+      const commandInput: {
+        Bucket: string;
+        Key: string;
+        ContentLength: number;
+        ContentType: string;
+        ChecksumSHA256?: string;
+      } = {
+        Bucket: bucket,
+        Key: key,
+        ContentLength: opts.size,
+        ContentType: opts.mimeType,
+      };
+
+      if (requireChecksum) {
+        commandInput.ChecksumSHA256 = checksumBase64;
+      }
+
+      const command = new commands.PutObjectCommand(commandInput);
+      const url = await getSignedUrl(client, command, {
+        expiresIn: opts.expiresIn,
+      });
+
+      const headers: Record<string, string> = {
+        'Content-Type': opts.mimeType,
+        'Content-Length': String(opts.size),
+      };
+
+      if (requireChecksum) {
+        headers['x-amz-checksum-sha256'] = checksumBase64;
+      }
+
+      return {
+        url,
+        method: 'PUT',
+        headers,
+      };
+    },
+
+    async signDownload(opts: BlobSignDownloadOptions): Promise<string> {
+      const key = getKey(opts.hash);
+      const command = new commands.GetObjectCommand({
+        Bucket: bucket,
+        Key: key,
+      });
+      return getSignedUrl(client, command, { expiresIn: opts.expiresIn });
+    },
+
+    async exists(hash: string): Promise<boolean> {
+      const key = getKey(hash);
+      try {
+        const command = new commands.HeadObjectCommand({
+          Bucket: bucket,
+          Key: key,
+        });
+        await client.send(command);
+        return true;
+      } catch (err) {
+        // Check for NotFound error
+        if (isNotFoundError(err)) {
+          return false;
+        }
+        throw err;
+      }
+    },
+
+    async delete(hash: string): Promise<void> {
+      const key = getKey(hash);
+      const command = new commands.DeleteObjectCommand({
+        Bucket: bucket,
+        Key: key,
+      });
+      await client.send(command);
+    },
+
+    async getMetadata(
+      hash: string
+    ): Promise<{ size: number; mimeType?: string } | null> {
+      const key = getKey(hash);
+      try {
+        const command = new commands.HeadObjectCommand({
+          Bucket: bucket,
+          Key: key,
+        });
+        const response = (await client.send(command)) as {
+          ContentLength?: number;
+          ContentType?: string;
+        };
+        return {
+          size: response.ContentLength ?? 0,
+          mimeType: response.ContentType,
+        };
+      } catch (err) {
+        if (isNotFoundError(err)) {
+          return null;
+        }
+        throw err;
+      }
+    },
+
+    async put(hash: string, data: Uint8Array): Promise<void> {
+      const key = getKey(hash);
+      const command = new commands.PutObjectCommand({
+        Bucket: bucket,
+        Key: key,
+        Body: data,
+        ContentLength: data.length,
+        ContentType: 'application/octet-stream',
+      });
+      await client.send(command);
+    },
+
+    async get(hash: string): Promise<Uint8Array | null> {
+      const key = getKey(hash);
+      try {
+        const command = new commands.GetObjectCommand({
+          Bucket: bucket,
+          Key: key,
+        });
+        const response = (await client.send(command)) as {
+          Body?: { transformToByteArray(): Promise<Uint8Array> };
+        };
+        if (!response.Body) return null;
+        return response.Body.transformToByteArray();
+      } catch (err) {
+        if (isNotFoundError(err)) {
+          return null;
+        }
+        throw err;
+      }
+    },
+
+    async getStream(hash: string): Promise<ReadableStream<Uint8Array> | null> {
+      const key = getKey(hash);
+      try {
+        const command = new commands.GetObjectCommand({
+          Bucket: bucket,
+          Key: key,
+        });
+        const response = (await client.send(command)) as {
+          Body?: { transformToWebStream(): ReadableStream<Uint8Array> };
+        };
+        if (!response.Body) return null;
+        return response.Body.transformToWebStream();
+      } catch (err) {
+        if (isNotFoundError(err)) {
+          return null;
+        }
+        throw err;
+      }
+    },
+  };
+}
+
+function isNotFoundError(err: unknown): boolean {
+  if (typeof err !== 'object' || err === null) return false;
+  const e = err as { name?: string; $metadata?: { httpStatusCode?: number } };
+  return (
+    e.name === 'NotFound' ||
+    e.name === 'NoSuchKey' ||
+    e.$metadata?.httpStatusCode === 404
+  );
+}
+
+function hexToBase64(hex: string): string {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+
+  // Use Buffer if available (Node/Bun), otherwise manual base64
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(bytes).toString('base64');
+  }
+
+  // Manual base64 encoding
+  const chars =
+    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+  let result = '';
+  const len = bytes.length;
+  const remainder = len % 3;
+
+  for (let i = 0; i < len - remainder; i += 3) {
+    const a = bytes[i]!;
+    const b = bytes[i + 1]!;
+    const c = bytes[i + 2]!;
+    result +=
+      chars.charAt((a >> 2) & 0x3f) +
+      chars.charAt(((a << 4) | (b >> 4)) & 0x3f) +
+      chars.charAt(((b << 2) | (c >> 6)) & 0x3f) +
+      chars.charAt(c & 0x3f);
+  }
+
+  if (remainder === 1) {
+    const a = bytes[len - 1]!;
+    result += `${chars.charAt((a >> 2) & 0x3f) + chars.charAt((a << 4) & 0x3f)}==`;
+  } else if (remainder === 2) {
+    const a = bytes[len - 2]!;
+    const b = bytes[len - 1]!;
+    result +=
+      chars.charAt((a >> 2) & 0x3f) +
+      chars.charAt(((a << 4) | (b >> 4)) & 0x3f) +
+      chars.charAt((b << 2) & 0x3f) +
+      '=';
+  }
+
+  return result;
+}