feat(media): S3/MinIO storage adapter (StoragePort)

Drop-in S3-compatible backend for object storage (media + email attachments) —
the swap the StoragePort seam was designed for. MinIO/self-hosted/R2/Supabase all
work via endpoint + path-style.

- S3Storage implements StoragePort (put/get/remove); sha256 computed locally on put
  (matches LocalDiskStorage); a missing object reads back as null, not an error.
- Env-driven binding in MediaModule: IIOS_S3_BUCKET + keys set → S3Storage, else
  LocalDiskStorage. forcePathStyle defaults true (MinIO); endpoint omitted → AWS.
- S3 client is injectable so tests run with no live server.

6 unit tests (config parse, put size/sha, get round-trip, NoSuchKey→null, remove).
Full suite 300/300, boundary + build clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

packages/iios-service/.env.example

@@ -59,3 +59,12 @@ IIOS_ATTESTATION_AUDIENCE=iios-core
 # When '1', every guarded request MUST carry a valid X-Context-Attestation (else 403).
 # Leave OFF until callers (AppShell/be-crm) forward attestations. Verified-if-present regardless.
 IIOS_REQUIRE_ATTESTATION=0
+
+# ─── Object storage (media + email attachments) ───────────────────
+# Unset → local disk (MEDIA_DIR). Set these → S3-compatible (AWS S3 / MinIO / R2 / Supabase).
+# IIOS_S3_ENDPOINT=https://minio.your-server:9000   # omit for AWS S3
+# IIOS_S3_BUCKET=iios-media
+# IIOS_S3_ACCESS_KEY=...
+# IIOS_S3_SECRET_KEY=...
+# IIOS_S3_REGION=us-east-1                            # any value for MinIO
+# IIOS_S3_FORCE_PATH_STYLE=true                       # true for MinIO/self-hosted

packages/iios-service/package.json

@@ -12,6 +12,7 @@
     "prisma:studio": "prisma studio"
   },
   "dependencies": {
+    "@aws-sdk/client-s3": "^3.1090.0",
     "@insignia/iios-adapter-sdk": "workspace:*",
     "@insignia/iios-contracts": "workspace:*",
     "@nestjs/common": "^11.1.27",

packages/iios-service/src/media/media.module.ts

@@ -1,16 +1,26 @@
-import { Module } from '@nestjs/common';
+import { Module, Logger } from '@nestjs/common';
 import { PlatformModule } from '../platform/platform.module';
 import { IdentityModule } from '../identity/identity.module';
 import { MediaController } from './media.controller';
 import { MediaService } from './media.service';
 import { LocalDiskStorage } from './local-disk.storage';
-import { STORAGE_PORT } from './storage.port';
+import { S3Storage, s3ConfigFromEnv } from './s3.storage';
+import { STORAGE_PORT, type StoragePort } from './storage.port';
+
+/** S3/MinIO when its env is set (IIOS_S3_BUCKET + keys), else local disk. Env-driven swap. */
+function makeStorage(): StoragePort {
+  const cfg = s3ConfigFromEnv();
+  if (cfg) {
+    new Logger('MediaStorage').log(`using S3 storage (bucket "${cfg.bucket}"${cfg.endpoint ? ` @ ${cfg.endpoint}` : ''})`);
+    return new S3Storage(cfg);
+  }
+  return new LocalDiskStorage();
+}
 
 @Module({
   imports: [PlatformModule, IdentityModule],
   controllers: [MediaController],
-  // Dev binds local disk; prod swaps STORAGE_PORT to an S3/Supabase adapter.
-  providers: [MediaService, { provide: STORAGE_PORT, useClass: LocalDiskStorage }],
+  providers: [MediaService, { provide: STORAGE_PORT, useFactory: makeStorage }],
   // Exported so the capability layer can resolve email attachment bytes at send time.
   exports: [STORAGE_PORT],
 })

packages/iios-service/src/media/s3.storage.spec.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect } from 'vitest';
+import { DeleteObjectCommand, GetObjectCommand, PutObjectCommand } from '@aws-sdk/client-s3';
+import { S3Storage, s3ConfigFromEnv, type S3Config, type S3Like } from './s3.storage';
+
+const CFG: S3Config = { endpoint: 'https://minio.test', region: 'us-east-1', bucket: 'iios', accessKeyId: 'k', secretAccessKey: 's', forcePathStyle: true };
+
+/** A recording stub S3 client; GetObject returns whatever `store[key]` holds (or a NoSuchKey error). */
+function stub(store: Record<string, { body: Buffer; mime: string }> = {}) {
+  const calls: unknown[] = [];
+  const client: S3Like = {
+    async send(command: unknown) {
+      calls.push(command);
+      if (command instanceof PutObjectCommand) { store[command.input.Key!] = { body: command.input.Body as Buffer, mime: command.input.ContentType ?? '' }; return {}; }
+      if (command instanceof DeleteObjectCommand) { delete store[command.input.Key!]; return {}; }
+      if (command instanceof GetObjectCommand) {
+        const hit = store[command.input.Key!];
+        if (!hit) throw Object.assign(new Error('missing'), { name: 'NoSuchKey' });
+        return { Body: { transformToByteArray: async () => new Uint8Array(hit.body) }, ContentType: hit.mime };
+      }
+      return {};
+    },
+  };
+  return { client, calls, store };
+}
+
+describe('s3ConfigFromEnv', () => {
+  it('builds config from env (path-style default true for MinIO)', () => {
+    const cfg = s3ConfigFromEnv({ IIOS_S3_ENDPOINT: 'https://minio.x', IIOS_S3_BUCKET: 'b', IIOS_S3_ACCESS_KEY: 'k', IIOS_S3_SECRET_KEY: 's' } as NodeJS.ProcessEnv);
+    expect(cfg).toMatchObject({ endpoint: 'https://minio.x', bucket: 'b', region: 'us-east-1', forcePathStyle: true });
+  });
+  it('returns null when bucket/keys are missing', () => {
+    expect(s3ConfigFromEnv({ IIOS_S3_ENDPOINT: 'https://minio.x' } as NodeJS.ProcessEnv)).toBeNull();
+  });
+});
+
+describe('S3Storage (StoragePort over S3/MinIO)', () => {
+  it('put stores the object and returns size + sha256', async () => {
+    const s = stub();
+    const store = new S3Storage(CFG, s.client);
+    const res = await store.put('scope/obj1', Buffer.from('hello'), 'text/plain');
+    expect(res.sizeBytes).toBe(5);
+    expect(res.checksumSha256).toMatch(/^[a-f0-9]{64}$/);
+    const put = s.calls[0] as PutObjectCommand;
+    expect(put.input).toMatchObject({ Bucket: 'iios', Key: 'scope/obj1', ContentType: 'text/plain' });
+  });
+
+  it('get round-trips the bytes + mime', async () => {
+    const s = stub();
+    const store = new S3Storage(CFG, s.client);
+    await store.put('scope/obj2', Buffer.from('PDFDATA'), 'application/pdf');
+    const got = await store.get('scope/obj2');
+    expect(got).toEqual({ data: Buffer.from('PDFDATA'), mime: 'application/pdf', sizeBytes: 7 });
+  });
+
+  it('get returns null for a missing key (NoSuchKey → null, not throw)', async () => {
+    const store = new S3Storage(CFG, stub().client);
+    expect(await store.get('nope')).toBeNull();
+  });
+
+  it('remove issues a DeleteObject', async () => {
+    const s = stub({ 'k': { body: Buffer.from('x'), mime: 't' } });
+    await new S3Storage(CFG, s.client).remove('k');
+    expect(s.calls.some((c) => c instanceof DeleteObjectCommand)).toBe(true);
+    expect(s.store['k']).toBeUndefined();
+  });
+});

packages/iios-service/src/media/s3.storage.ts

@@ -0,0 +1,87 @@
+import { createHash } from 'node:crypto';
+import { Injectable } from '@nestjs/common';
+import { DeleteObjectCommand, GetObjectCommand, PutObjectCommand, S3Client } from '@aws-sdk/client-s3';
+import type { StoragePort } from './storage.port';
+
+export interface S3Config {
+  endpoint?: string;      // MinIO/self-hosted URL; omit for AWS
+  region: string;
+  bucket: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  forcePathStyle: boolean; // true for MinIO
+}
+
+/** The one method this adapter uses — lets tests inject a stub client (no live S3/MinIO). */
+export interface S3Like {
+  send(command: unknown): Promise<unknown>;
+}
+
+/** Build an S3Config from env, or null if the required bits are missing (→ fall back to disk). */
+export function s3ConfigFromEnv(env: NodeJS.ProcessEnv = process.env): S3Config | null {
+  const bucket = env.IIOS_S3_BUCKET;
+  const accessKeyId = env.IIOS_S3_ACCESS_KEY;
+  const secretAccessKey = env.IIOS_S3_SECRET_KEY;
+  if (!bucket || !accessKeyId || !secretAccessKey) return null;
+  return {
+    ...(env.IIOS_S3_ENDPOINT ? { endpoint: env.IIOS_S3_ENDPOINT } : {}),
+    region: env.IIOS_S3_REGION ?? 'us-east-1',
+    bucket,
+    accessKeyId,
+    secretAccessKey,
+    // MinIO/self-hosted needs path-style; default true unless explicitly disabled for AWS.
+    forcePathStyle: env.IIOS_S3_FORCE_PATH_STYLE !== 'false',
+  };
+}
+
+/**
+ * S3-compatible object storage (AWS S3, MinIO, R2, Supabase Storage). A drop-in for LocalDiskStorage:
+ * same StoragePort contract. sha256 is computed locally on put (S3 doesn't return it), matching the
+ * disk adapter. A missing object reads back as null (not an error).
+ */
+@Injectable()
+export class S3Storage implements StoragePort {
+  private readonly client: S3Like;
+  private readonly bucket: string;
+
+  constructor(config: S3Config, client?: S3Like) {
+    this.bucket = config.bucket;
+    this.client = client ?? new S3Client({
+      region: config.region,
+      ...(config.endpoint ? { endpoint: config.endpoint } : {}),
+      forcePathStyle: config.forcePathStyle,
+      credentials: { accessKeyId: config.accessKeyId, secretAccessKey: config.secretAccessKey },
+    });
+  }
+
+  async put(objectKey: string, data: Buffer, mime: string): Promise<{ sizeBytes: number; checksumSha256: string }> {
+    const checksumSha256 = createHash('sha256').update(data).digest('hex');
+    await this.client.send(new PutObjectCommand({ Bucket: this.bucket, Key: objectKey, Body: data, ContentType: mime }));
+    return { sizeBytes: data.length, checksumSha256 };
+  }
+
+  async get(objectKey: string): Promise<{ data: Buffer; mime: string; sizeBytes: number } | null> {
+    try {
+      const res = (await this.client.send(new GetObjectCommand({ Bucket: this.bucket, Key: objectKey }))) as {
+        Body?: { transformToByteArray(): Promise<Uint8Array> };
+        ContentType?: string;
+      };
+      if (!res.Body) return null;
+      const bytes = await res.Body.transformToByteArray();
+      const data = Buffer.from(bytes);
+      return { data, mime: res.ContentType ?? 'application/octet-stream', sizeBytes: data.length };
+    } catch (err) {
+      if (isNotFound(err)) return null;
+      throw err;
+    }
+  }
+
+  async remove(objectKey: string): Promise<void> {
+    await this.client.send(new DeleteObjectCommand({ Bucket: this.bucket, Key: objectKey }));
+  }
+}
+
+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;
+}