# 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`.