Skip to content

Send and receive SMS messages using your Android phone programmatically via a simple HTTP API

docs: add MMS attachments implementation plan

Acho Arnold14af0a1dc065
diff --git a/docs/superpowers/plans/2026-04-11-mms-attachments.md b/docs/superpowers/plans/2026-04-11-mms-attachments.md
new file mode 100644
index 00000000..a759e1c4
--- /dev/null
+++ b/docs/superpowers/plans/2026-04-11-mms-attachments.md
@@ -0,0 +1,1139 @@
+# MMS Attachment Support Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add MMS attachment upload/download support to the httpSMS API so received MMS attachments are stored in cloud storage and downloadable via a public URL.
+
+**Architecture:** Android sends base64-encoded attachments in the receive request. The API decodes and uploads them to GCS (or in-memory storage) via a storage interface, stores download URLs in the existing `Message.Attachments` field, and exposes an unauthenticated download endpoint. The webhook event payload includes attachment URLs.
+
+**Tech Stack:** Go, Fiber v2, GORM, `cloud.google.com/go/storage`, `errgroup`, `stacktrace`
+
+---
+
+## File Structure
+
+**New files:**
+
+| File | Responsibility |
+| --------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `api/pkg/repositories/attachment_storage.go` | `AttachmentStorage` interface + content-type-to-extension mapping + sanitization |
+| `api/pkg/repositories/gcs_attachment_storage.go` | GCS implementation of `AttachmentStorage` |
+| `api/pkg/repositories/memory_attachment_storage.go` | In-memory implementation of `AttachmentStorage` |
+| `api/pkg/repositories/attachment_storage_test.go` | Unit tests for content-type mapping and filename sanitization |
+| `api/pkg/handlers/attachment_handler.go` | Download endpoint handler (`GET /v1/attachments/...`) |
+
+**Modified files:**
+
+| File | Change |
+| ------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `api/pkg/requests/message_receive_request.go` | Add `Attachments` field + `MessageAttachment` struct |
+| `api/pkg/services/message_service.go` | Add `Attachments` to params, upload logic in `ReceiveMessage()`, set on message |
+| `api/pkg/validators/message_handler_validator.go` | Add attachment count/size/content-type validation |
+| `api/pkg/events/message_phone_received_event.go` | Add `Attachments []string` to payload |
+| `api/pkg/di/container.go` | Wire `AttachmentStorage`, `AttachmentHandler`, `RegisterAttachmentRoutes()` |
+| `api/.env.docker` | Add `GCS_BUCKET_NAME` |
+| `api/go.mod` / `api/go.sum` | Add `cloud.google.com/go/storage` and `golang.org/x/sync` (errgroup) |
+
+---
+
+### Task 1: Add GCS SDK and errgroup dependencies
+
+**Files:**
+
+- Modify: `api/go.mod`
+
+- [ ] **Step 1: Add dependencies**
+
+```bash
+cd api && go get cloud.google.com/go/storage && go get golang.org/x/sync
+```
+
+- [ ] **Step 2: Verify build still works**
+
+Run: `cd api && go build ./...`
+Expected: Build succeeds
+
+- [ ] **Step 3: Commit**
+
+```bash
+cd api && git add go.mod go.sum && git commit -m "chore: add cloud.google.com/go/storage and golang.org/x/sync deps"
+```
+
+---
+
+### Task 2: Storage interface, content-type mapping, and filename sanitization
+
+**Files:**
+
+- Create: `api/pkg/repositories/attachment_storage.go`
+- Create: `api/pkg/repositories/attachment_storage_test.go`
+
+- [ ] **Step 1: Write the test file**
+
+Create `api/pkg/repositories/attachment_storage_test.go`:
+
+```go
+package repositories
+
+import "testing"
+
+func TestExtensionFromContentType(t *testing.T) {
+ tests := []struct {
+ contentType string
+ expected string
+ }{
+ {"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"},
+ {"application/octet-stream", ".bin"},
+ {"unknown/type", ".bin"},
+ {"", ".bin"},
+ }
+ for _, tt := range tests {
+ t.Run(tt.contentType, func(t *testing.T) {
+ got := ExtensionFromContentType(tt.contentType)
+ if got != tt.expected {
+ t.Errorf("ExtensionFromContentType(%q) = %q, want %q", tt.contentType, got, tt.expected)
+ }
+ })
+ }
+}
+
+func TestSanitizeFilename(t *testing.T) {
+ tests := []struct {
+ name string
+ index int
+ expected string
+ }{
+ {"photo.jpg", 0, "photo"},
+ {"../../etc/passwd", 0, "etcpasswd"},
+ {"hello/world\\test", 0, "helloworldtest"},
+ {"normal_file", 0, "normal_file"},
+ {"", 0, "attachment-0"},
+ {" ", 0, "attachment-0"},
+ {"...", 1, "attachment-1"},
+ }
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ got := SanitizeFilename(tt.name, tt.index)
+ if got != tt.expected {
+ t.Errorf("SanitizeFilename(%q, %d) = %q, want %q", tt.name, tt.index, got, tt.expected)
+ }
+ })
+ }
+}
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cd api && go test ./pkg/repositories/ -run "TestExtensionFromContentType|TestSanitizeFilename" -v`
+Expected: FAIL — functions not defined
+
+- [ ] **Step 3: Write the storage interface and utility functions**
+
+Create `api/pkg/repositories/attachment_storage.go`:
+
+```go
+package repositories
+
+import (
+ "context"
+ "fmt"
+ "path/filepath"
+ "strings"
+)
+
+// AttachmentStorage is the interface for storing and retrieving message attachments
+type AttachmentStorage interface {
+ // Upload stores attachment data at the given path
+ Upload(ctx context.Context, path string, data []byte) error
+ // Download retrieves attachment data from the given path
+ Download(ctx context.Context, path string) ([]byte, error)
+ // Delete removes an attachment at the given path
+ Delete(ctx context.Context, path string) error
+}
+
+// contentTypeExtensions maps MIME types to file extensions
+var contentTypeExtensions = map[string]string{
+ "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",
+}
+
+// AllowedContentTypes returns the set of allowed MIME types for attachments
+func AllowedContentTypes() map[string]bool {
+ allowed := make(map[string]bool, len(contentTypeExtensions))
+ for ct := range contentTypeExtensions {
+ allowed[ct] = true
+ }
+ return allowed
+}
+
+// ExtensionFromContentType returns the file extension for a MIME content type.
+// Returns ".bin" if the content type is not recognized.
+func ExtensionFromContentType(contentType string) string {
+ if ext, ok := contentTypeExtensions[contentType]; ok {
+ return ext
+ }
+ return ".bin"
+}
+
+// ContentTypeFromExtension returns the MIME content type for a file extension.
+// Returns "application/octet-stream" if the extension is not recognized.
+func ContentTypeFromExtension(ext string) string {
+ for ct, e := range contentTypeExtensions {
+ if e == ext {
+ return ct
+ }
+ }
+ return "application/octet-stream"
+}
+
+// SanitizeFilename removes path separators and traversal sequences from a filename.
+// Returns "attachment-{index}" if the sanitized name is empty.
+func SanitizeFilename(name string, index int) string {
+ name = strings.TrimSuffix(name, filepath.Ext(name))
+ name = strings.ReplaceAll(name, "/", "")
+ name = strings.ReplaceAll(name, "\\", "")
+ name = strings.ReplaceAll(name, "..", "")
+ name = strings.TrimSpace(name)
+
+ if name == "" {
+ return fmt.Sprintf("attachment-%d", index)
+ }
+ return name
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cd api && go test ./pkg/repositories/ -run "TestExtensionFromContentType|TestSanitizeFilename" -v`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+cd api && git add -A && git commit -m "feat: add AttachmentStorage interface and content-type utilities"
+```
+
+---
+
+### Task 3: Memory storage implementation
+
+**Files:**
+
+- Create: `api/pkg/repositories/memory_attachment_storage.go`
+
+- [ ] **Step 1: Write the implementation**
+
+Create `api/pkg/repositories/memory_attachment_storage.go`:
+
+```go
+package repositories
+
+import (
+ "context"
+ "fmt"
+ "sync"
+
+ "github.com/NdoleStudio/httpsms/pkg/telemetry"
+ "github.com/palantir/stacktrace"
+)
+
+// MemoryAttachmentStorage stores attachments in memory
+type MemoryAttachmentStorage struct {
+ logger telemetry.Logger
+ tracer telemetry.Tracer
+ data sync.Map
+}
+
+// NewMemoryAttachmentStorage creates a new MemoryAttachmentStorage
+func NewMemoryAttachmentStorage(
+ logger telemetry.Logger,
+ tracer telemetry.Tracer,
+) *MemoryAttachmentStorage {
+ return &MemoryAttachmentStorage{
+ logger: logger.WithService(fmt.Sprintf("%T", &MemoryAttachmentStorage{})),
+ tracer: tracer,
+ }
+}
+
+// Upload stores attachment data at the given path
+func (s *MemoryAttachmentStorage) Upload(ctx context.Context, path string, data []byte) error {
+ _, span := s.tracer.Start(ctx)
+ defer span.End()
+
+ s.data.Store(path, data)
+ s.logger.Info(fmt.Sprintf("stored attachment at path [%s] with size [%d]", path, len(data)))
+ return nil
+}
+
+// Download retrieves attachment data from the given path
+func (s *MemoryAttachmentStorage) Download(ctx context.Context, path string) ([]byte, error) {
+ _, span := s.tracer.Start(ctx)
+ defer span.End()
+
+ value, ok := s.data.Load(path)
+ if !ok {
+ return nil, stacktrace.NewError(fmt.Sprintf("attachment not found at path [%s]", path))
+ }
+ return value.([]byte), nil
+}
+
+// Delete removes an attachment at the given path
+func (s *MemoryAttachmentStorage) Delete(ctx context.Context, path string) error {
+ _, span := s.tracer.Start(ctx)
+ defer span.End()
+
+ s.data.Delete(path)
+ s.logger.Info(fmt.Sprintf("deleted attachment at path [%s]", path))
+ return nil
+}
+```
+
+- [ ] **Step 2: Verify build**
+
+Run: `cd api && go build ./...`
+Expected: Build succeeds
+
+- [ ] **Step 3: Commit**
+
+```bash
+cd api && git add -A && git commit -m "feat: add MemoryAttachmentStorage implementation"
+```
+
+---
+
+### Task 4: GCS storage implementation
+
+**Files:**
+
+- Create: `api/pkg/repositories/gcs_attachment_storage.go`
+
+- [ ] **Step 1: Write the implementation**
+
+Create `api/pkg/repositories/gcs_attachment_storage.go`:
+
+```go
+package repositories
+
+import (
+ "context"
+ "fmt"
+ "io"
+
+ "cloud.google.com/go/storage"
+ "github.com/NdoleStudio/httpsms/pkg/telemetry"
+ "github.com/palantir/stacktrace"
+)
+
+// GCSAttachmentStorage stores attachments in Google Cloud Storage
+type GCSAttachmentStorage struct {
+ logger telemetry.Logger
+ tracer telemetry.Tracer
+ client *storage.Client
+ bucket string
+}
+
+// NewGCSAttachmentStorage creates a new GCSAttachmentStorage
+func NewGCSAttachmentStorage(
+ logger telemetry.Logger,
+ tracer telemetry.Tracer,
+ client *storage.Client,
+ bucket string,
+) *GCSAttachmentStorage {
+ return &GCSAttachmentStorage{
+ logger: logger.WithService(fmt.Sprintf("%T", &GCSAttachmentStorage{})),
+ tracer: tracer,
+ client: client,
+ bucket: bucket,
+ }
+}
+
+// Upload stores attachment data at the given path in GCS
+func (s *GCSAttachmentStorage) Upload(ctx context.Context, path string, data []byte) error {
+ ctx, span := s.tracer.Start(ctx)
+ defer span.End()
+
+ writer := s.client.Bucket(s.bucket).Object(path).NewWriter(ctx)
+ if _, err := writer.Write(data); err != nil {
+ return s.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, fmt.Sprintf("cannot write attachment to GCS path [%s]", path)))
+ }
+
+ if err := writer.Close(); err != nil {
+ return s.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, fmt.Sprintf("cannot close GCS writer for path [%s]", path)))
+ }
+
+ s.logger.Info(fmt.Sprintf("uploaded attachment to GCS path [%s/%s] with size [%d]", s.bucket, path, len(data)))
+ return nil
+}
+
+// Download retrieves attachment data from the given path in GCS
+func (s *GCSAttachmentStorage) Download(ctx context.Context, path string) ([]byte, error) {
+ ctx, span := s.tracer.Start(ctx)
+ defer span.End()
+
+ reader, err := s.client.Bucket(s.bucket).Object(path).NewReader(ctx)
+ if err != nil {
+ return nil, s.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, fmt.Sprintf("cannot open GCS reader for path [%s]", path)))
+ }
+ defer reader.Close()
+
+ data, err := io.ReadAll(reader)
+ if err != nil {
+ return nil, s.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, fmt.Sprintf("cannot read attachment from GCS path [%s]", path)))
+ }
+
+ return data, nil
+}
+
+// Delete removes an attachment at the given path in GCS
+func (s *GCSAttachmentStorage) Delete(ctx context.Context, path string) error {
+ ctx, span := s.tracer.Start(ctx)
+ defer span.End()
+
+ if err := s.client.Bucket(s.bucket).Object(path).Delete(ctx); err != nil {
+ return s.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, fmt.Sprintf("cannot delete GCS object at path [%s]", path)))
+ }
+
+ s.logger.Info(fmt.Sprintf("deleted attachment from GCS path [%s/%s]", s.bucket, path))
+ return nil
+}
+```
+
+- [ ] **Step 2: Verify build**
+
+Run: `cd api && go build ./...`
+Expected: Build succeeds
+
+- [ ] **Step 3: Commit**
+
+```bash
+cd api && git add -A && git commit -m "feat: add GCSAttachmentStorage implementation"
+```
+
+---
+
+### Task 5: Update request and event structs
+
+**Files:**
+
+- Modify: `api/pkg/requests/message_receive_request.go` (full file)
+- Modify: `api/pkg/services/message_service.go:290-300` (MessageReceiveParams)
+- Modify: `api/pkg/events/message_phone_received_event.go:14-23` (payload struct)
+
+**Important:** The `requests` package already imports `services` (for `ToMessageReceiveParams`), so we **cannot** import `requests` from `services`. Define a `ServiceAttachment` struct in the services package to avoid a circular import.
+
+- [ ] **Step 1: Add ServiceAttachment to services package**
+
+In `api/pkg/services/message_service.go`, add after the imports (before `MessageService` struct at line 22):
+
+```go
+// ServiceAttachment represents attachment data passed to the service layer
+type ServiceAttachment struct {
+ Name string
+ ContentType string
+ Content string // base64-encoded
+}
+```
+
+Update `MessageReceiveParams` (lines 290-300) to add `Attachments`:
+
+```go
+type MessageReceiveParams struct {
+ Contact string
+ UserID entities.UserID
+ Owner phonenumbers.PhoneNumber
+ Content string
+ SIM entities.SIM
+ Timestamp time.Time
+ Encrypted bool
+ Source string
+ Attachments []ServiceAttachment
+}
+```
+
+- [ ] **Step 2: Add MessageAttachment struct and update MessageReceive request**
+
+In `api/pkg/requests/message_receive_request.go`, add the `MessageAttachment` struct before the `MessageReceive` struct, and add the `Attachments` field:
+
+```go
+// MessageAttachment represents a single MMS attachment in a receive request
+type MessageAttachment struct {
+ // Name is the original filename of the attachment
+ Name string `json:"name" example:"photo.jpg"`
+ // ContentType is the MIME type of the attachment
+ ContentType string `json:"content_type" example:"image/jpeg"`
+ // Content is the base64-encoded attachment data
+ Content string `json:"content" example:"base64data..."`
+}
+
+// MessageReceive is the payload for receiving an SMS/MMS message
+type MessageReceive struct {
+ request
+ From string `json:"from" example:"+18005550199"`
+ To string `json:"to" example:"+18005550100"`
+ Content string `json:"content" example:"This is a sample text message received on a phone"`
+ // Encrypted is used to determine if the content is end-to-end encrypted
+ Encrypted bool `json:"encrypted" example:"false"`
+ // SIM card that received the message
+ SIM entities.SIM `json:"sim" example:"SIM1"`
+ // Timestamp is the time when the event was emitted
+ Timestamp time.Time `json:"timestamp" example:"2022-06-05T14:26:09.527976+03:00"`
+ // Attachments is the list of MMS attachments received with the message
+ Attachments []MessageAttachment `json:"attachments"`
+}
+```
+
+Update `ToMessageReceiveParams` to convert attachments:
+
+```go
+func (input *MessageReceive) ToMessageReceiveParams(userID entities.UserID, source string) *services.MessageReceiveParams {
+ phone, _ := phonenumbers.Parse(input.To, phonenumbers.UNKNOWN_REGION)
+
+ attachments := make([]services.ServiceAttachment, len(input.Attachments))
+ for i, a := range input.Attachments {
+ attachments[i] = services.ServiceAttachment{
+ Name: a.Name,
+ ContentType: a.ContentType,
+ Content: a.Content,
+ }
+ }
+
+ return &services.MessageReceiveParams{
+ Source: source,
+ Contact: input.From,
+ UserID: userID,
+ Timestamp: input.Timestamp,
+ Encrypted: input.Encrypted,
+ Owner: *phone,
+ Content: input.Content,
+ SIM: input.SIM,
+ Attachments: attachments,
+ }
+}
+```
+
+- [ ] **Step 3: Update MessagePhoneReceivedPayload**
+
+In `api/pkg/events/message_phone_received_event.go`, add `Attachments` field to the payload struct (after the `SIM` field):
+
+```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"`
+}
+```
+
+- [ ] **Step 4: Verify build compiles (will fail until service constructor is updated)**
+
+Run: `cd api && go vet ./pkg/requests/... ./pkg/events/...`
+Expected: No errors in these packages
+
+- [ ] **Step 5: Commit**
+
+```bash
+cd api && git add -A && git commit -m "feat: add attachment fields to request, params, and event structs"
+```
+
+---
+
+### Task 6: Add attachment validation
+
+**Files:**
+
+- Modify: `api/pkg/validators/message_handler_validator.go:49-77`
+
+- [ ] **Step 1: Update ValidateMessageReceive to validate attachments**
+
+In `api/pkg/validators/message_handler_validator.go`, replace the `ValidateMessageReceive` method (lines 49-77) with:
+
+```go
+const (
+ maxAttachmentCount = 10
+ maxAttachmentSize = (3 * 1024 * 1024) / 2 // 1.5 MB
+)
+
+// ValidateMessageReceive validates the requests.MessageReceive request
+func (validator MessageHandlerValidator) ValidateMessageReceive(_ context.Context, request requests.MessageReceive) url.Values {
+ v := govalidator.New(govalidator.Options{
+ Data: &request,
+ Rules: govalidator.MapData{
+ "to": []string{
+ "required",
+ phoneNumberRule,
+ },
+ "from": []string{
+ "required",
+ },
+ "content": []string{
+ "required",
+ "min:1",
+ "max:2048",
+ },
+ "sim": []string{
+ "required",
+ "in:" + strings.Join([]string{
+ string(entities.SIM1),
+ string(entities.SIM2),
+ }, ","),
+ },
+ },
+ })
+
+ errors := v.ValidateStruct()
+
+ if len(request.Attachments) > 0 {
+ attachmentErrors := validator.validateAttachments(request.Attachments)
+ for key, values := range attachmentErrors {
+ for _, value := range values {
+ errors.Add(key, value)
+ }
+ }
+ }
+
+ return errors
+}
+
+func (validator MessageHandlerValidator) validateAttachments(attachments []requests.MessageAttachment) url.Values {
+ errors := url.Values{}
+ allowedTypes := repositories.AllowedContentTypes()
+
+ if len(attachments) > maxAttachmentCount {
+ errors.Add("attachments", fmt.Sprintf("attachment count [%d] exceeds maximum of [%d]", len(attachments), maxAttachmentCount))
+ return errors
+ }
+
+ for i, attachment := range attachments {
+ if !allowedTypes[attachment.ContentType] {
+ errors.Add("attachments", fmt.Sprintf("attachment [%d] has unsupported content type [%s]", i, attachment.ContentType))
+ continue
+ }
+
+ decoded, err := base64.StdEncoding.DecodeString(attachment.Content)
+ if err != nil {
+ errors.Add("attachments", fmt.Sprintf("attachment [%d] has invalid base64 content", i))
+ continue
+ }
+
+ if len(decoded) > maxAttachmentSize {
+ errors.Add("attachments", fmt.Sprintf("attachment [%d] size [%d] exceeds maximum of [%d] bytes", i, len(decoded), maxAttachmentSize))
+ }
+ }
+
+ return errors
+}
+```
+
+Add these imports to the file: `"encoding/base64"`, `"github.com/NdoleStudio/httpsms/pkg/repositories"`.
+
+- [ ] **Step 2: Verify build**
+
+Run: `cd api && go vet ./pkg/validators/...`
+Expected: No errors
+
+- [ ] **Step 3: Commit**
+
+```bash
+cd api && git add -A && git commit -m "feat: add attachment count, size, and content-type validation"
+```
+
+---
+
+### Task 7: Upload logic in MessageService.ReceiveMessage()
+
+**Files:**
+
+- Modify: `api/pkg/services/message_service.go:22-47` (struct + constructor)
+- Modify: `api/pkg/services/message_service.go:302-337` (ReceiveMessage)
+- Modify: `api/pkg/services/message_service.go:550-581` (storeReceivedMessage)
+
+- [ ] **Step 1: Add AttachmentStorage and apiBaseURL to MessageService**
+
+Update the `MessageService` struct (lines 22-30):
+
+```go
+type MessageService struct {
+ service
+ logger telemetry.Logger
+ tracer telemetry.Tracer
+ eventDispatcher *EventDispatcher
+ phoneService *PhoneService
+ repository repositories.MessageRepository
+ attachmentStorage repositories.AttachmentStorage
+ apiBaseURL string
+}
+```
+
+Update `NewMessageService` (lines 33-47) to accept the new parameters:
+
+```go
+func NewMessageService(
+ logger telemetry.Logger,
+ tracer telemetry.Tracer,
+ repository repositories.MessageRepository,
+ eventDispatcher *EventDispatcher,
+ phoneService *PhoneService,
+ attachmentStorage repositories.AttachmentStorage,
+ apiBaseURL string,
+) (s *MessageService) {
+ return &MessageService{
+ logger: logger.WithService(fmt.Sprintf("%T", s)),
+ tracer: tracer,
+ repository: repository,
+ phoneService: phoneService,
+ eventDispatcher: eventDispatcher,
+ attachmentStorage: attachmentStorage,
+ apiBaseURL: apiBaseURL,
+ }
+}
+```
+
+- [ ] **Step 2: Add the uploadAttachments helper method**
+
+Add this after `storeReceivedMessage`. Add imports: `"encoding/base64"`, `"golang.org/x/sync/errgroup"`:
+
+```go
+func (service *MessageService) uploadAttachments(ctx context.Context, userID entities.UserID, messageID uuid.UUID, attachments []ServiceAttachment) ([]string, error) {
+ ctx, span := service.tracer.Start(ctx)
+ defer span.End()
+
+ ctxLogger := service.tracer.CtxLogger(service.logger, span)
+
+ g, gCtx := errgroup.WithContext(ctx)
+ urls := make([]string, len(attachments))
+ paths := make([]string, len(attachments))
+
+ for i, attachment := range attachments {
+ i, attachment := i, attachment
+ g.Go(func() error {
+ decoded, err := base64.StdEncoding.DecodeString(attachment.Content)
+ if err != nil {
+ return stacktrace.Propagate(err, fmt.Sprintf("cannot decode base64 content for attachment [%d]", i))
+ }
+
+ sanitizedName := repositories.SanitizeFilename(attachment.Name, i)
+ ext := repositories.ExtensionFromContentType(attachment.ContentType)
+ filename := sanitizedName + ext
+
+ path := fmt.Sprintf("attachments/%s/%s/%d/%s", userID, messageID, i, filename)
+ paths[i] = path
+
+ if err = service.attachmentStorage.Upload(gCtx, path, decoded); err != nil {
+ return stacktrace.Propagate(err, fmt.Sprintf("cannot upload attachment [%d] to path [%s]", i, path))
+ }
+
+ urls[i] = fmt.Sprintf("%s/v1/attachments/%s/%s/%d/%s", service.apiBaseURL, userID, messageID, i, filename)
+ ctxLogger.Info(fmt.Sprintf("uploaded attachment [%d] to [%s]", i, path))
+ return nil
+ })
+ }
+
+ if err := g.Wait(); err != nil {
+ for _, path := range paths {
+ if path != "" {
+ _ = service.attachmentStorage.Delete(ctx, path)
+ }
+ }
+ return nil, stacktrace.Propagate(err, "cannot upload attachments")
+ }
+
+ return urls, nil
+}
+```
+
+- [ ] **Step 3: Update ReceiveMessage to upload attachments before event dispatch**
+
+Replace the `ReceiveMessage` method (lines 302-337):
+
+```go
+func (service *MessageService) ReceiveMessage(ctx context.Context, params *MessageReceiveParams) (*entities.Message, error) {
+ ctx, span := service.tracer.Start(ctx)
+ defer span.End()
+
+ ctxLogger := service.tracer.CtxLogger(service.logger, span)
+
+ messageID := uuid.New()
+ var attachmentURLs []string
+
+ if len(params.Attachments) > 0 {
+ ctxLogger.Info(fmt.Sprintf("uploading [%d] attachments for message [%s]", len(params.Attachments), messageID))
+ var err error
+ attachmentURLs, err = service.uploadAttachments(ctx, params.UserID, messageID, params.Attachments)
+ if err != nil {
+ msg := fmt.Sprintf("cannot upload attachments for message [%s]", messageID)
+ return nil, service.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, msg))
+ }
+ }
+
+ eventPayload := events.MessagePhoneReceivedPayload{
+ MessageID: messageID,
+ UserID: params.UserID,
+ Encrypted: params.Encrypted,
+ Owner: phonenumbers.Format(&params.Owner, phonenumbers.E164),
+ Contact: params.Contact,
+ Timestamp: params.Timestamp,
+ Content: params.Content,
+ SIM: params.SIM,
+ Attachments: attachmentURLs,
+ }
+
+ ctxLogger.Info(fmt.Sprintf("creating cloud event for received with ID [%s]", eventPayload.MessageID))
+
+ event, err := service.createMessagePhoneReceivedEvent(params.Source, eventPayload)
+ if err != nil {
+ msg := fmt.Sprintf("cannot create %T from payload with message id [%s]", event, eventPayload.MessageID)
+ return nil, service.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, msg))
+ }
+
+ ctxLogger.Info(fmt.Sprintf("created event [%s] with id [%s] and message id [%s]", event.Type(), event.ID(), eventPayload.MessageID))
+
+ if err = service.eventDispatcher.Dispatch(ctx, event); err != nil {
+ msg := fmt.Sprintf("cannot dispatch event type [%s] and id [%s]", event.Type(), event.ID())
+ return nil, service.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, msg))
+ }
+ ctxLogger.Info(fmt.Sprintf("event [%s] dispatched successfully", event.ID()))
+
+ return service.storeReceivedMessage(ctx, eventPayload)
+}
+```
+
+- [ ] **Step 4: Update storeReceivedMessage to set Attachments on message**
+
+In the `storeReceivedMessage` method (lines 550-581), add `Attachments` to the message construction:
+
+```go
+ message := &entities.Message{
+ ID: params.MessageID,
+ Owner: params.Owner,
+ UserID: params.UserID,
+ Contact: params.Contact,
+ Content: params.Content,
+ Attachments: params.Attachments,
+ SIM: params.SIM,
+ Encrypted: params.Encrypted,
+ Type: entities.MessageTypeMobileOriginated,
+ Status: entities.MessageStatusReceived,
+ RequestReceivedAt: params.Timestamp,
+ CreatedAt: time.Now().UTC(),
+ UpdatedAt: time.Now().UTC(),
+ OrderTimestamp: params.Timestamp,
+ ReceivedAt: &params.Timestamp,
+ }
+```
+
+- [ ] **Step 5: Verify the services package compiles**
+
+Run: `cd api && go vet ./pkg/services/...`
+Expected: No errors (the full build may still fail until DI container is updated)
+
+- [ ] **Step 6: Commit**
+
+```bash
+cd api && git add -A && git commit -m "feat: add attachment upload logic to MessageService.ReceiveMessage()"
+```
+
+---
+
+### Task 8: Attachment download handler
+
+**Files:**
+
+- Create: `api/pkg/handlers/attachment_handler.go`
+
+- [ ] **Step 1: Write the handler**
+
+Create `api/pkg/handlers/attachment_handler.go`:
+
+```go
+package handlers
+
+import (
+ "fmt"
+ "path/filepath"
+
+ "github.com/NdoleStudio/httpsms/pkg/repositories"
+ "github.com/NdoleStudio/httpsms/pkg/telemetry"
+ "github.com/gofiber/fiber/v2"
+ "github.com/palantir/stacktrace"
+)
+
+// AttachmentHandler handles attachment download requests
+type AttachmentHandler struct {
+ handler
+ logger telemetry.Logger
+ tracer telemetry.Tracer
+ storage repositories.AttachmentStorage
+}
+
+// NewAttachmentHandler creates a new AttachmentHandler
+func NewAttachmentHandler(
+ logger telemetry.Logger,
+ tracer telemetry.Tracer,
+ storage repositories.AttachmentStorage,
+) (h *AttachmentHandler) {
+ return &AttachmentHandler{
+ logger: logger.WithService(fmt.Sprintf("%T", h)),
+ tracer: tracer,
+ storage: storage,
+ }
+}
+
+// RegisterRoutes registers the routes for the AttachmentHandler (no auth middleware — public endpoint)
+func (h *AttachmentHandler) RegisterRoutes(router fiber.Router) {
+ router.Get("/v1/attachments/:userID/:messageID/:attachmentIndex/:filename", h.GetAttachment)
+}
+
+// GetAttachment downloads an attachment
+// @Summary Download a message attachment
+// @Description Download an MMS attachment by its path components
+// @Tags Attachments
+// @Produce octet-stream
+// @Param userID path string true "User ID"
+// @Param messageID path string true "Message ID"
+// @Param attachmentIndex path string true "Attachment index"
+// @Param filename path string true "Filename with extension"
+// @Success 200 {file} binary
+// @Failure 404 {object} responses.NotFoundResponse
+// @Failure 500 {object} responses.InternalServerError
+// @Router /attachments/{userID}/{messageID}/{attachmentIndex}/{filename} [get]
+func (h *AttachmentHandler) GetAttachment(c *fiber.Ctx) error {
+ ctx, span := h.tracer.StartFromFiberCtx(c)
+ defer span.End()
+
+ ctxLogger := h.tracer.CtxLogger(h.logger, span)
+
+ userID := c.Params("userID")
+ messageID := c.Params("messageID")
+ attachmentIndex := c.Params("attachmentIndex")
+ filename := c.Params("filename")
+
+ path := fmt.Sprintf("attachments/%s/%s/%s/%s", userID, messageID, attachmentIndex, filename)
+
+ ctxLogger.Info(fmt.Sprintf("downloading attachment from path [%s]", path))
+
+ data, err := h.storage.Download(ctx, path)
+ if err != nil {
+ msg := fmt.Sprintf("cannot download attachment from path [%s]", path)
+ ctxLogger.Warn(stacktrace.Propagate(err, msg))
+ return h.responseNotFound(c, "attachment not found")
+ }
+
+ ext := filepath.Ext(filename)
+ contentType := repositories.ContentTypeFromExtension(ext)
+
+ c.Set("Content-Type", contentType)
+ c.Set("Content-Disposition", "attachment")
+ c.Set("X-Content-Type-Options", "nosniff")
+
+ return c.Send(data)
+}
+```
+
+- [ ] **Step 2: Verify build**
+
+Run: `cd api && go vet ./pkg/handlers/...`
+Expected: No errors
+
+- [ ] **Step 3: Commit**
+
+```bash
+cd api && git add -A && git commit -m "feat: add AttachmentHandler for downloading attachments"
+```
+
+---
+
+### Task 9: Wire everything in the DI container and env config
+
+**Files:**
+
+- Modify: `api/pkg/di/container.go:104-163` (NewContainer)
+- Modify: `api/pkg/di/container.go:1424-1434` (MessageService creation)
+- Modify: `api/.env.docker`
+
+- [ ] **Step 1: Add GCS_BUCKET_NAME to .env.docker**
+
+In `api/.env.docker`, add after the `REDIS_URL=redis://@redis:6379` line (line 49):
+
+```env
+
+# Google Cloud Storage bucket for MMS attachments. Leave empty to use in-memory storage.
+GCS_BUCKET_NAME=
+```
+
+- [ ] **Step 2: Add `attachmentStorage` field to Container struct**
+
+In `api/pkg/di/container.go`, add `attachmentStorage` to the `Container` struct (around line 82-90):
+
+```go
+type Container struct {
+ projectID string
+ db *gorm.DB
+ dedicatedDB *gorm.DB
+ version string
+ app *fiber.App
+ eventDispatcher *services.EventDispatcher
+ logger telemetry.Logger
+ attachmentStorage repositories.AttachmentStorage
+}
+```
+
+- [ ] **Step 3: Add AttachmentStorage, APIBaseURL, and AttachmentHandler getters to container.go**
+
+Add these methods to `api/pkg/di/container.go`. Also add required imports: `"cloud.google.com/go/storage"` and `"context"`:
+
+```go
+// AttachmentStorage creates a cached AttachmentStorage based on configuration
+func (container *Container) AttachmentStorage() repositories.AttachmentStorage {
+ if container.attachmentStorage != nil {
+ return container.attachmentStorage
+ }
+
+ bucket := os.Getenv("GCS_BUCKET_NAME")
+ if bucket != "" {
+ container.logger.Debug("creating GCSAttachmentStorage")
+ client, err := storage.NewClient(context.Background())
+ if err != nil {
+ container.logger.Fatal(stacktrace.Propagate(err, "cannot create GCS client"))
+ }
+ container.attachmentStorage = repositories.NewGCSAttachmentStorage(
+ container.Logger(),
+ container.Tracer(),
+ client,
+ bucket,
+ )
+ } else {
+ container.logger.Debug("creating MemoryAttachmentStorage (GCS_BUCKET_NAME not set)")
+ container.attachmentStorage = repositories.NewMemoryAttachmentStorage(
+ container.Logger(),
+ container.Tracer(),
+ )
+ }
+
+ return container.attachmentStorage
+}
+
+// APIBaseURL returns the API base URL derived from EVENTS_QUEUE_ENDPOINT
+func (container *Container) APIBaseURL() string {
+ endpoint := os.Getenv("EVENTS_QUEUE_ENDPOINT")
+ return strings.TrimSuffix(endpoint, "/v1/events")
+}
+
+// AttachmentHandler creates a new AttachmentHandler
+func (container *Container) AttachmentHandler() (handler *handlers.AttachmentHandler) {
+ container.logger.Debug(fmt.Sprintf("creating %T", handler))
+ return handlers.NewAttachmentHandler(
+ container.Logger(),
+ container.Tracer(),
+ container.AttachmentStorage(),
+ )
+}
+
+// RegisterAttachmentRoutes registers routes for the /attachments prefix
+func (container *Container) RegisterAttachmentRoutes() {
+ container.logger.Debug(fmt.Sprintf("registering %T routes", &handlers.AttachmentHandler{}))
+ container.AttachmentHandler().RegisterRoutes(container.App())
+}
+```
+
+- [ ] **Step 3: Update MessageService creation to pass new parameters**
+
+Update the `MessageService()` getter (around line 1424-1434):
+
+```go
+func (container *Container) MessageService() (service *services.MessageService) {
+ container.logger.Debug(fmt.Sprintf("creating %T", service))
+ return services.NewMessageService(
+ container.Logger(),
+ container.Tracer(),
+ container.MessageRepository(),
+ container.EventDispatcher(),
+ container.PhoneService(),
+ container.AttachmentStorage(),
+ container.APIBaseURL(),
+ )
+}
+```
+
+- [ ] **Step 4: Register attachment routes in NewContainer**
+
+In the `NewContainer` function (lines 104-163), add `container.RegisterAttachmentRoutes()` after `container.RegisterMessageRoutes()` (after line 120):
+
+```go
+ container.RegisterMessageRoutes()
+ container.RegisterAttachmentRoutes()
+ container.RegisterBulkMessageRoutes()
+```
+
+- [ ] **Step 5: Verify full build**
+
+Run: `cd api && go build ./...`
+Expected: Build succeeds — all components are now wired
+
+- [ ] **Step 6: Run all tests**
+
+Run: `cd api && go test ./...`
+Expected: All tests pass
+
+- [ ] **Step 7: Commit**
+
+```bash
+cd api && git add -A && git commit -m "feat: wire attachment storage and handler in DI container
+
+- Add AttachmentStorage selection (GCS vs memory) based on GCS_BUCKET_NAME env var
+- Wire AttachmentHandler for public download endpoint
+- Pass storage and API base URL to MessageService
+- Add GCS_BUCKET_NAME to .env.docker"
+```
+
+---
+
+### Task 10: Final verification
+
+- [ ] **Step 1: Run full build**
+
+Run: `cd api && go build -o ./tmp/main.exe .`
+Expected: Build succeeds
+
+- [ ] **Step 2: Run all tests**
+
+Run: `cd api && go test ./... -v`
+Expected: All tests pass including `TestExtensionFromContentType` and `TestSanitizeFilename`
+
+- [ ] **Step 3: Verify go vet**
+
+Run: `cd api && go vet ./...`
+Expected: No issues
+
+- [ ] **Step 4: Final commit if any remaining changes**
+
+```bash
+cd api && git add -A && git diff --cached --stat
+```
diff --git a/docs/superpowers/specs/2026-04-11-mms-attachments-design.md b/docs/superpowers/specs/2026-04-11-mms-attachments-design.md
index 7b153b60..7beea85f 100644
--- a/docs/superpowers/specs/2026-04-11-mms-attachments-design.md
+++ b/docs/superpowers/specs/2026-04-11-mms-attachments-design.md
@@ -150,20 +150,18 @@ This covers common MMS content types. New mappings can be added as needed.
**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
+- Registered **without authentication middleware** — publicly accessible, consistent with outgoing attachment URLs
+- The `{userID}/{messageID}/{attachmentIndex}` path components provide sufficient obscurity (UUIDs are unguessable)
**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
+2. Construct storage path: `attachments/{userID}/{messageID}/{attachmentIndex}/{filename}`
+3. Fetch bytes from `AttachmentStorage.Download(ctx, path)`
+4. Derive `Content-Type` from filename extension
+5. Set security headers: `Content-Disposition: attachment`, `X-Content-Type-Options: nosniff`
+6. Respond with binary data + correct `Content-Type` header
+7. Return 404 if attachment not found in storage
### 7. Webhook Event Changes
@@ -183,7 +181,7 @@ type MessagePhoneReceivedPayload struct {
}
```
-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.
+Webhook subscribers will receive the array of download URLs. They can `GET` each URL directly — no authentication required.
### 8. Files Changed / Created
@@ -219,5 +217,4 @@ Webhook subscribers will receive the array of download URLs. They can `GET` each
- 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