Storage
FRAME supports s3 and local as production storage providers through
NEST_STORAGE_PROVIDER.
Upload lifecycle
Section titled “Upload lifecycle”The client requests an upload grant from /api/upload/presigned-url. Nest validates
the authenticated user, upload intent, MIME type, and file size before returning the
provider-specific upload and public URLs.
S3 grants use a presigned bucket URL. Local grants use a short-lived HMAC token bound to the storage key, MIME type, byte size, and expiration. The local endpoint streams the request into a temporary file, validates its size and content signature, and publishes the completed file atomically. Incomplete temporary files left by an interrupted process are removed during startup.
Public local assets use immutable keys and are served at /uploads with long-lived
browser caching. Uploaded files are public; authorization applies when generating an
upload grant, not when reading the resulting asset.
Local filesystem deployment
Section titled “Local filesystem deployment”Local runtime data has one canonical location:
| Environment | Directory |
|---|---|
| Host development | apps/nest/storage |
| Production container | /app/storage |
The production Compose stacks mount the nest_uploads volume at /app/storage.
Configure the public ingress so /api and /uploads reach Nest without stripping the
path. Include nest_uploads in backup and restore procedures.
Local storage supports one Docker host. Multiple Nest replicas require the same read-write filesystem; use S3 when replicas span hosts or shared storage is unavailable.
Security properties
Section titled “Security properties”- Storage keys are generated by registered upload intents and use canonical extensions derived from validated MIME types.
- Signed local grants expire after 15 minutes and cannot be changed without invalidating their signature.
- Streaming limits prevent requests from exceeding the granted size.
- Files become public only after validation and atomic publication into the uploads tree.
- Storage paths reject absolute paths, traversal segments, dotfiles, and invalid names.
- Local storage readiness checks require the canonical directory to be readable and writable.