Initial Commit

openspec/changes/enterprise-api-plugin-file-upload/proposal.md

@@ -0,0 +1,79 @@
+# OpenSpec Change: enterprise-api-plugin-file-upload
+
+- **Change ID**: enterprise-api-plugin-file-upload
+- **Package**: `@suaveplan/api-plugin-file-upload`
+- **Category**: api/data
+- **Target path**: `api/data/api-plugin-file-upload`
+- **Status**: PROPOSED
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/api-plugin-file-upload.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/api-plugin-file-upload` on the genesis branch from scratch at enterprise quality. File upload and management plugin: multipart upload (single + chunked), MIME validation via `@suaveplan/mime`, virus-scan hook, pluggable storage backend (`StorageAdapter` — local disk, S3-compatible via `@suaveplan/storage-s3`), metadata extraction (images via `@suaveplan/exif`, audio via `@suaveplan/audio-metadata`), signed download URL generation, image compression via `@suaveplan/compress-image`, and file lifecycle management (quarantine, approve, delete). Routes under `/files`. Per-table SurrealQL. Events: `file:uploaded`, `file:approved`, `file:deleted`.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/api` (`workspace:^`) | `definePlugin` |
+| `@suaveplan/api-shared` (`workspace:^`) | Helpers |
+| `@suaveplan/api-plugin-auth` (`workspace:^`) | `requireAuth` |
+| `@suaveplan/api-plugin-database` (`workspace:^`) | SurrealDB |
+| `@suaveplan/mime` (`workspace:^`) | MIME type detection |
+| `@suaveplan/exif` (`workspace:^`) | Image EXIF extraction |
+| `@suaveplan/audio-metadata` (`workspace:^`) | Audio metadata extraction |
+| `@suaveplan/compress-image` (`workspace:^`) | Image compression |
+| `@suaveplan/events` (`workspace:^`) | Event bus |
+| `@suaveplan/error` (`workspace:^`) | `FileUploadError` hierarchy |
+| `@suaveplan/rate-limiter` (`workspace:^`) | Upload rate limits |
+| `hono` + `@hono/zod-openapi` + `zod` | Routes |
+| `@opentelemetry/api` | OTel |
+
+---
+
+## Public API surface
+
+```ts
+function createFileUploadPlugin(storageAdapter: FileStorageAdapter, config?: FileUploadPluginConfig): PluginDescriptor
+interface FileStorageAdapter { put(key, stream, meta): Promise<string>; get(key): Promise<ReadableStream>; delete(key): Promise<void>; getSignedUrl(key, ttlSeconds): Promise<string> }
+// Routes: POST /files, GET /files/:id, GET /files/:id/download, DELETE /files/:id, POST /files/chunked/initiate, POST /files/chunked/:uploadId/part, POST /files/chunked/:uploadId/complete
+```
+
+### Error codes
+
+```ts
+type FileUploadErrorCode =
+  | "FILE_NOT_FOUND"
+  | "FILE_TYPE_NOT_ALLOWED"
+  | "FILE_TOO_LARGE"
+  | "FILE_QUARANTINED"
+  | "FILE_UPLOAD_INCOMPLETE"
+  | "FILE_STORAGE_ERROR"
+```
+
+---
+
+## File layout
+
+```text
+api/data/api-plugin-file-upload/
+  package.json  tsconfig.json  vitest.config.ts
+  surql/ (file_record, chunked_upload tables)
+  src/
+    index.ts  events.ts  types/  errors/
+    adapters/storage.port.ts
+    services/upload/  services/metadata/  services/lifecycle/
+    routes/files/  routes/chunked/
+  tests/integration.test.ts
+```
+
+---
+
+## Impact
+
+Prerequisites: `@suaveplan/api`, `@suaveplan/api-plugin-auth`, `@suaveplan/api-plugin-database`, `@suaveplan/mime`, `@suaveplan/exif`, `@suaveplan/audio-metadata`, `@suaveplan/compress-image`.