Send and receive SMS messages using your Android phone programmatically via a simple HTTP API
docs: add MMS attachment support design spec
Acho Arnold727df631079c
diff --git a/docs/superpowers/specs/2026-04-11-mms-attachments-design.md b/docs/superpowers/specs/2026-04-11-mms-attachments-design.mdnew file mode 100644index 00000000..7b153b60--- /dev/null+++ b/docs/superpowers/specs/2026-04-11-mms-attachments-design.md@@ -0,0 +1,223 @@+# MMS Attachment Support — Design Spec++## Problem++The Android app now forwards MMS attachments (as base64-encoded data) when receiving MMS messages via `HttpSmsApiService.receive()`. The API server needs to:++1. Accept attachment data in the receive endpoint+2. Upload attachments to cloud storage (GCS or in-memory)+3. Store download URLs in the Message entity+4. Serve a download endpoint for retrieving attachments+5. Include attachment URLs in webhook event payloads++## Approach++**Approach A: Storage Interface + Minimal New Code** — Add an `AttachmentStorage` interface with GCS and memory implementations. Upload logic lives in the existing `MessageService.ReceiveMessage()` flow (synchronous). A new `AttachmentHandler` serves downloads. No new database tables — content type is encoded in the URL file extension.++## Design++### 1. Storage Interface++**New file: `pkg/repositories/attachment_storage.go`**++```go+type AttachmentStorage interface {+ Upload(ctx context.Context, path string, data []byte) error+ Download(ctx context.Context, path string) ([]byte, error)+ Delete(ctx context.Context, path string) error+}+```++**GCS Implementation** (`pkg/repositories/gcs_attachment_storage.go`):++- Uses `cloud.google.com/go/storage` SDK+- Configured with bucket name from `GCS_BUCKET_NAME` env var+- Stores objects at: `attachments/{userID}/{messageID}/{index}/{name}.{ext}`+- Extension derived from content type (e.g., `image/jpeg` → `.jpg`); falls back to `.bin` only when no mapping exists++**Memory Implementation** (`pkg/repositories/memory_attachment_storage.go`):++- `sync.Map`-backed in-memory store+- Used when `GCS_BUCKET_NAME` is empty/unset (local dev, testing)++**DI selection** (in `container.go`):++```go+if os.Getenv("GCS_BUCKET_NAME") != "" {+ return NewGCSAttachmentStorage(bucket, tracer, logger)+}+return NewMemoryAttachmentStorage(tracer, logger)+```++### 2. Environment Variables++| Variable | Description | Default |+| ----------------- | ------------------------------------------------------- | ---------------------------------- |+| `GCS_BUCKET_NAME` | GCS bucket for attachments. Empty = use memory storage. | `httpsms-86c51.appspot.com` (prod) |++The API base URL for constructing download links is derived from `EVENTS_QUEUE_ENDPOINT` by stripping the `/v1/events` suffix.++### 3. Request & Validation Changes++**Updated `MessageReceive` request** (`pkg/requests/`):++```go+type MessageReceive struct {+ From string `json:"from"`+ To string `json:"to"`+ Content string `json:"content"`+ Encrypted bool `json:"encrypted"`+ SIM entities.SIM `json:"sim"`+ Timestamp time.Time `json:"timestamp"`+ Attachments []MessageAttachment `json:"attachments"` // NEW+}++type MessageAttachment struct {+ Name string `json:"name"`+ ContentType string `json:"content_type"`+ Content string `json:"content"` // base64-encoded+}+```++**Updated `MessageReceiveParams`** (`pkg/services/`):+The `ToMessageReceiveParams()` method must propagate attachments to the service layer:++```go+type MessageReceiveParams struct {+ // ... existing fields ...+ Attachments []requests.MessageAttachment // NEW — raw attachment data for upload+}+```++**Filename sanitization:**+The `Name` field from the Android client must be sanitized to prevent path traversal attacks. Strip all path separators (`/`, `\`), directory traversal sequences (`..`), and non-printable characters. If the sanitized name is empty, use a fallback like `attachment-{index}`.++**Content type allowlist:**+Only allow known-safe MIME types from the extension mapping table (Section 5). Reject attachments with unrecognized content types with a 400 error.++**Validation rules** (in `pkg/validators/`):++- Attachment count must be ≤ 10+- Each decoded attachment must be ≤ 1.5 MB (1,572,864 bytes)+- Content type must be in the allowlist+- If any limit is exceeded → **reject entire request with 400 Bad Request**+- Validation happens before any upload or storage++### 4. Upload Flow (Synchronous in Receive)++In `MessageService.ReceiveMessage()`:++1. Validate attachment count, sizes, and content types+2. Upload attachments **in parallel** using `errgroup`:+ a. Decode base64 content+ b. Sanitize `name` (strip path separators, `..`, non-printable chars; fallback to `attachment-{index}`)+ c. Map `content_type` → file extension (e.g., `image/jpeg` → `.jpg`, unknown → `.bin`)+ d. Upload to storage at path: `attachments/{userID}/{messageID}/{index}/{sanitizedName}.{ext}`+ e. Build download URL: `{apiBaseURL}/v1/attachments/{userID}/{messageID}/{index}/{sanitizedName}.{ext}`+3. If any upload fails → best-effort delete of already-uploaded files, then return 500+4. Collect download URLs into `message.Attachments` (existing `pq.StringArray` field)+5. Set `Attachments` on `MessagePhoneReceivedPayload` before dispatching event+6. `storeReceivedMessage()` copies `payload.Attachments` → `message.Attachments`+7. Store message in database+8. Fire `message.phone.received` event (includes attachment URLs)++### 5. Content Type → Extension Mapping++A utility function maps MIME types to file extensions:++| Content Type | Extension |+| ----------------- | --------- |+| `image/jpeg` | `.jpg` |+| `image/png` | `.png` |+| `image/gif` | `.gif` |+| `image/webp` | `.webp` |+| `image/bmp` | `.bmp` |+| `video/mp4` | `.mp4` |+| `video/3gpp` | `.3gp` |+| `audio/mpeg` | `.mp3` |+| `audio/ogg` | `.ogg` |+| `audio/amr` | `.amr` |+| `application/pdf` | `.pdf` |+| `text/vcard` | `.vcf` |+| `text/x-vcard` | `.vcf` |+| _(default)_ | `.bin` |++This covers common MMS content types. New mappings can be added as needed.++### 6. Download Handler++**New file: `pkg/handlers/attachment_handler.go`**++**Route:** `GET /v1/attachments/:userID/:messageID/:attachmentIndex/:filename`++- Registered with **both** `AuthenticatedMiddleware` (Firebase bearer) **and** `APIKeyMiddleware` — so both the end-user (via Firebase token) and webhook consumers (via API key) can download attachments+- Authenticates that `:userID` matches the authenticated user's ID (from either auth method)+- Returns 401 if mismatch++**Download flow:**++1. Parse URL params (userID, messageID, attachmentIndex, filename)+2. Verify authenticated user ID matches `:userID`+3. Construct storage path: `attachments/{userID}/{messageID}/{attachmentIndex}/{filename}`+4. Fetch bytes from `AttachmentStorage.Download(ctx, path)`+5. Derive `Content-Type` from filename extension+6. Set security headers: `Content-Disposition: attachment`, `X-Content-Type-Options: nosniff`+7. Respond with binary data + correct `Content-Type` header+8. Return 404 if attachment not found in storage++### 7. Webhook Event Changes++**Updated `MessagePhoneReceivedPayload`** (`pkg/events/message_phone_received_event.go`):++```go+type MessagePhoneReceivedPayload struct {+ MessageID uuid.UUID `json:"message_id"`+ UserID entities.UserID `json:"user_id"`+ Owner string `json:"owner"`+ Encrypted bool `json:"encrypted"`+ Contact string `json:"contact"`+ Timestamp time.Time `json:"timestamp"`+ Content string `json:"content"`+ SIM entities.SIM `json:"sim"`+ Attachments []string `json:"attachments"` // NEW — download URLs+}+```++Webhook subscribers will receive the array of download URLs. They can `GET` each URL with their **API key** (via `x-api-key` header) or **bearer token** to download the attachment.++### 8. Files Changed / Created++**New files:**++- `pkg/repositories/attachment_storage.go` — Interface definition+- `pkg/repositories/gcs_attachment_storage.go` — GCS implementation+- `pkg/repositories/memory_attachment_storage.go` — Memory implementation+- `pkg/handlers/attachment_handler.go` — Download endpoint handler+- `pkg/validators/attachment_handler_validator.go` — Download param validation++**Modified files:**++- `pkg/requests/message_receive.go` (or wherever `MessageReceive` is defined) — Add `Attachments` field+- `pkg/validators/message_handler_validator.go` — Add attachment count/size validation+- `pkg/services/message_service.go` — Add upload logic to `ReceiveMessage()`+- `pkg/events/message_phone_received_event.go` — Add `Attachments` field to payload+- `pkg/di/container.go` — Wire storage, new handler, pass storage to message service+- `api/.env.docker` — Add `GCS_BUCKET_NAME` variable+- `go.mod` / `go.sum` — Add `cloud.google.com/go/storage` dependency++### 9. Validation Constraints++| Constraint | Value | Behavior |+| ------------------------------- | ------------------------ | ---------------------------------------------------- |+| Max attachment count | 10 | 400 Bad Request |+| Max attachment size (decoded) | 1.5 MB (1,572,864 bytes) | 400 Bad Request |+| Content type not in allowlist | — | 400 Bad Request |+| Missing/empty attachments array | — | Message stored without attachments (normal SMS flow) |++### 10. Error Handling++- Storage upload failure → Best-effort delete of already-uploaded attachments, then return 500; message is NOT stored+- Storage download failure → Return 404 or 500 depending on error type+- Invalid base64 content → Return 400 Bad Request+- UserID mismatch on download → Return 401 Unauthorized+- All errors wrapped with `stacktrace.Propagate()` per project convention