storage

# Butterbase Storage Butterbase stores files in S3 (or LocalStack in dev) and exposes them via presigned URLs. Every file gets a stable `object_id` (UUID) that you persist in your tables; URLs are generated on demand and expire. All storage operations go through one tool: **`manage_storage`** with an `action` parameter. | Action | Purpose | |--------|---------| | `upload_url` | Generate a 15-minute presigned PUT URL and reserve an `object_id` | | `download_url` | Generate a 1-hour presigned GET URL for a stored object | | `list` | List objects (scoped by caller's role) | | `delete` | Permanently remove an object from S3 + database | | `update_config` | Toggle app-level `publicReadEnabled` and other storage settings | --- ## 1. The mental model: `object_id` vs `s3_key` | Field | What it is | When you use it | |-------|-----------|-----------------| | `object_id` | UUID, stable, app-level handle | Persist in your tables (e.g. `users.avatar_id`, `posts.image_id`) | | `s3_key` | Internal bucket path like `app_abc/user_uuid/file.jpg` | Internal only — **never** treat this as a URL | **Critical:** `s3_key` is **not** a URL. You cannot use it as `<img src>` or `<a href>`. Always store the `object_id` and resolve a fresh download URL at render time. --- ## 2. The upload lifecycle A single upload is two HTTP calls and one DB insert in your app: ``` ┌─────────────────────────┐ │ 1. manage_storage( │ → returns { upload_url, object_id, expires_at } │ action: upload_...