File Storage — Overview

The File Storage service is the shared binary storage layer for all modules. Modules never write directly to S3 — they call kernel.files() and the service handles upload, virus scanning, image processing, access control, and lifecycle management.

Technical Stack

Staging + AV Scan Pipeline

Every file goes through a two-bucket pipeline before it is accessible. The staging bucket is never exposed publicly.

Client uploads:
  Presigned POST → S3 staging bucket: {tenantId}/staging/{fileId}
                                       Status: pending_scan

S3 Event Notification → File Service → AV scanner
  Clean:    move to main bucket → {tenantId}/{bucket}/{fileId}
            Status: available
  Infected: delete from staging
            Status: rejected
            Notify tenant admin

A file with status pending_scan is not accessible via GET /files/:id. Any attempt returns 404 Not Found until the AV scan completes and the file moves to available.

Staging Overflow Protection

Bucket Layout

All files for all tenants reside in a single S3 bucket, partitioned by {tenantId}/{bucket}/:

One S3 bucket per deployment, not per tenant. This keeps S3 bucket counts manageable (AWS S3: 100-bucket soft limit without quota request) while maintaining strict tenant isolation via prefix and JWT-level access control.

Tenant Isolation

File access is enforced at two levels:

1. S3 key prefix — every file path is prefixed with {tenantId}/. Files from different tenants physically reside under different prefixes.
2. JWT check — the File Service verifies that the tenantId from the JWT matches the tenantId in the file record before serving any request. Cross-tenant file access is structurally impossible.

REST API

File Status Lifecycle

                ┌─────────────┐
                │ pending_scan │  (in staging bucket, not accessible)
                └──────┬──────┘
              AV scan  │
           ┌───────────┴───────────┐
           │ clean                 │ infected
           ▼                       ▼
     ┌───────────┐          ┌─────────────┐
     │ available │          │  rejected   │
     └─────┬─────┘          └─────────────┘
           │  DELETE /files/:id
           ▼
     ┌─────────────┐
     │   deleted   │  (soft delete, in trash, restorable 30 days)
     └─────┬───────┘
           │  30 days elapsed OR DELETE permanent
           ▼
     ┌─────────────┐
     │  destroyed  │  (physically removed from S3, irreversible)
     └─────────────┘

Related Pages

• Uploading Files — multipart upload, presigned URL, staging pipeline
• Downloading Files — direct download, presigned download URL, tenant isolation
• Image Processing — bimg/libvips pipeline, crop, resize, WebP/AVIF
• Thumbnails — 5 presets, auto-generation, on-demand
• Retention & Deletion — soft delete, orphan scan, bucket layout