Close all 25 codex audit findings and add KMP contract tests

Remediate all P0-S priority findings from cross-platform architecture audit:
- Add input validation and authorization checks across handlers
- Harden social auth (Apple/Google) token validation
- Add document ownership verification and file type validation
- Add rate limiting config and CORS origin restrictions
- Add subscription tier enforcement in handlers
- Add OpenAPI 3.0.3 spec (81 schemas, 104 operations)
- Add URL-level contract test (KMP API routes match spec paths)
- Add model-level contract test (65 schemas, 464 fields validated)
- Add CI workflow for backend tests

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

internal/handlers/document_handler.go

@@ -241,3 +241,67 @@ func (h *DocumentHandler) DeactivateDocument(c echo.Context) error {
 	}
 	return c.JSON(http.StatusOK, map[string]interface{}{"message": "Document deactivated successfully", "document": response})
 }
+
+// UploadDocumentImage handles POST /api/documents/:id/images/
+func (h *DocumentHandler) UploadDocumentImage(c echo.Context) error {
+	user := c.Get(middleware.AuthUserKey).(*models.User)
+	documentID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		return apperrors.BadRequest("error.invalid_document_id")
+	}
+
+	// Parse multipart form
+	if err := c.Request().ParseMultipartForm(32 << 20); err != nil {
+		return apperrors.BadRequest("error.failed_to_parse_form")
+	}
+
+	// Look for file in common field names
+	var uploadedFile *multipart.FileHeader
+	for _, fieldName := range []string{"image", "file"} {
+		if file, err := c.FormFile(fieldName); err == nil {
+			uploadedFile = file
+			break
+		}
+	}
+
+	if uploadedFile == nil {
+		return apperrors.BadRequest("error.no_file_provided")
+	}
+
+	if h.storageService == nil {
+		return apperrors.Internal(nil)
+	}
+
+	result, err := h.storageService.Upload(uploadedFile, "images")
+	if err != nil {
+		return apperrors.BadRequest("error.failed_to_upload_file")
+	}
+
+	caption := c.FormValue("caption")
+
+	response, err := h.documentService.UploadDocumentImage(uint(documentID), user.ID, result.URL, caption)
+	if err != nil {
+		return err
+	}
+	return c.JSON(http.StatusCreated, response)
+}
+
+// DeleteDocumentImage handles DELETE /api/documents/:id/images/:imageId/
+func (h *DocumentHandler) DeleteDocumentImage(c echo.Context) error {
+	user := c.Get(middleware.AuthUserKey).(*models.User)
+	documentID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		return apperrors.BadRequest("error.invalid_document_id")
+	}
+
+	imageID, err := strconv.ParseUint(c.Param("imageId"), 10, 32)
+	if err != nil {
+		return apperrors.BadRequest("error.invalid_image_id")
+	}
+
+	response, err := h.documentService.DeleteDocumentImage(uint(documentID), uint(imageID), user.ID)
+	if err != nil {
+		return err
+	}
+	return c.JSON(http.StatusOK, response)
+}

internal/handlers/document_handler_test.go

@@ -0,0 +1,213 @@
+package handlers
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"testing"
+
+	"github.com/labstack/echo/v4"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/treytartt/casera-api/internal/models"
+	"github.com/treytartt/casera-api/internal/repositories"
+	"github.com/treytartt/casera-api/internal/services"
+	"github.com/treytartt/casera-api/internal/testutil"
+	"gorm.io/gorm"
+)
+
+func setupDocumentHandler(t *testing.T) (*DocumentHandler, *echo.Echo, *gorm.DB) {
+	db := testutil.SetupTestDB(t)
+	documentRepo := repositories.NewDocumentRepository(db)
+	residenceRepo := repositories.NewResidenceRepository(db)
+	documentService := services.NewDocumentService(documentRepo, residenceRepo)
+	handler := NewDocumentHandler(documentService, nil) // nil storage for JSON-only tests
+	e := testutil.SetupTestRouter()
+	return handler, e, db
+}
+
+func TestDocumentHandler_ListDocuments(t *testing.T) {
+	handler, e, db := setupDocumentHandler(t)
+	user := testutil.CreateTestUser(t, db, "owner", "owner@test.com", "password")
+	residence := testutil.CreateTestResidence(t, db, user.ID, "Test House")
+	testutil.CreateTestDocument(t, db, residence.ID, user.ID, "Test Doc")
+
+	authGroup := e.Group("/api/documents")
+	authGroup.Use(testutil.MockAuthMiddleware(user))
+	authGroup.GET("/", handler.ListDocuments)
+
+	t.Run("successful list", func(t *testing.T) {
+		w := testutil.MakeRequest(e, "GET", "/api/documents/", nil, "test-token")
+		testutil.AssertStatusCode(t, w, http.StatusOK)
+
+		var response []map[string]interface{}
+		err := json.Unmarshal(w.Body.Bytes(), &response)
+		require.NoError(t, err)
+		assert.Len(t, response, 1)
+		assert.Equal(t, "Test Doc", response[0]["title"])
+	})
+}
+
+func TestDocumentHandler_CreateDocument(t *testing.T) {
+	handler, e, db := setupDocumentHandler(t)
+	user := testutil.CreateTestUser(t, db, "owner", "owner@test.com", "password")
+	residence := testutil.CreateTestResidence(t, db, user.ID, "Test House")
+
+	authGroup := e.Group("/api/documents")
+	authGroup.Use(testutil.MockAuthMiddleware(user))
+	authGroup.POST("/", handler.CreateDocument)
+
+	t.Run("successful creation via JSON", func(t *testing.T) {
+		body := map[string]interface{}{
+			"title":        "Warranty Doc",
+			"residence_id": residence.ID,
+		}
+		w := testutil.MakeRequest(e, "POST", "/api/documents/", body, "test-token")
+		testutil.AssertStatusCode(t, w, http.StatusCreated)
+
+		var response map[string]interface{}
+		err := json.Unmarshal(w.Body.Bytes(), &response)
+		require.NoError(t, err)
+		assert.Equal(t, "Warranty Doc", response["title"])
+	})
+
+	t.Run("creation without residence access", func(t *testing.T) {
+		otherUser := testutil.CreateTestUser(t, db, "other", "other@test.com", "password")
+		otherResidence := testutil.CreateTestResidence(t, db, otherUser.ID, "Other House")
+
+		body := map[string]interface{}{
+			"title":        "Unauthorized Doc",
+			"residence_id": otherResidence.ID,
+		}
+		w := testutil.MakeRequest(e, "POST", "/api/documents/", body, "test-token")
+		testutil.AssertStatusCode(t, w, http.StatusForbidden)
+	})
+}
+
+func TestDocumentHandler_GetDocument(t *testing.T) {
+	handler, e, db := setupDocumentHandler(t)
+	user := testutil.CreateTestUser(t, db, "owner", "owner@test.com", "password")
+	residence := testutil.CreateTestResidence(t, db, user.ID, "Test House")
+	doc := testutil.CreateTestDocument(t, db, residence.ID, user.ID, "Test Doc")
+
+	authGroup := e.Group("/api/documents")
+	authGroup.Use(testutil.MockAuthMiddleware(user))
+	authGroup.GET("/:id/", handler.GetDocument)
+
+	t.Run("successful get", func(t *testing.T) {
+		w := testutil.MakeRequest(e, "GET", fmt.Sprintf("/api/documents/%d/", doc.ID), nil, "test-token")
+		testutil.AssertStatusCode(t, w, http.StatusOK)
+
+		var response map[string]interface{}
+		err := json.Unmarshal(w.Body.Bytes(), &response)
+		require.NoError(t, err)
+		assert.Equal(t, "Test Doc", response["title"])
+	})
+
+	t.Run("document not found", func(t *testing.T) {
+		w := testutil.MakeRequest(e, "GET", "/api/documents/99999/", nil, "test-token")
+		testutil.AssertStatusCode(t, w, http.StatusNotFound)
+	})
+}
+
+func TestDocumentHandler_DeleteDocumentImage(t *testing.T) {
+	handler, e, db := setupDocumentHandler(t)
+	user := testutil.CreateTestUser(t, db, "owner", "owner@test.com", "password")
+	residence := testutil.CreateTestResidence(t, db, user.ID, "Test House")
+	doc := testutil.CreateTestDocument(t, db, residence.ID, user.ID, "Test Doc")
+
+	// Create a document image directly
+	img := &models.DocumentImage{
+		DocumentID: doc.ID,
+		ImageURL:   "https://example.com/img.jpg",
+		Caption:    "Test image",
+	}
+	require.NoError(t, db.Create(img).Error)
+
+	authGroup := e.Group("/api/documents")
+	authGroup.Use(testutil.MockAuthMiddleware(user))
+	authGroup.DELETE("/:id/images/:imageId/", handler.DeleteDocumentImage)
+
+	t.Run("successful delete", func(t *testing.T) {
+		w := testutil.MakeRequest(e, "DELETE", fmt.Sprintf("/api/documents/%d/images/%d/", doc.ID, img.ID), nil, "test-token")
+		testutil.AssertStatusCode(t, w, http.StatusOK)
+
+		var response map[string]interface{}
+		err := json.Unmarshal(w.Body.Bytes(), &response)
+		require.NoError(t, err)
+		assert.Equal(t, "Test Doc", response["title"])
+
+		// Verify image is deleted
+		images := response["images"].([]interface{})
+		assert.Len(t, images, 0)
+	})
+
+	t.Run("image not found", func(t *testing.T) {
+		w := testutil.MakeRequest(e, "DELETE", fmt.Sprintf("/api/documents/%d/images/99999/", doc.ID), nil, "test-token")
+		testutil.AssertStatusCode(t, w, http.StatusNotFound)
+	})
+
+	t.Run("document not found", func(t *testing.T) {
+		w := testutil.MakeRequest(e, "DELETE", "/api/documents/99999/images/1/", nil, "test-token")
+		testutil.AssertStatusCode(t, w, http.StatusNotFound)
+	})
+
+	t.Run("access denied", func(t *testing.T) {
+		otherUser := testutil.CreateTestUser(t, db, "other", "other@test.com", "password")
+		otherResidence := testutil.CreateTestResidence(t, db, otherUser.ID, "Other House")
+		otherDoc := testutil.CreateTestDocument(t, db, otherResidence.ID, otherUser.ID, "Other Doc")
+
+		otherImg := &models.DocumentImage{
+			DocumentID: otherDoc.ID,
+			ImageURL:   "https://example.com/other.jpg",
+		}
+		require.NoError(t, db.Create(otherImg).Error)
+
+		w := testutil.MakeRequest(e, "DELETE", fmt.Sprintf("/api/documents/%d/images/%d/", otherDoc.ID, otherImg.ID), nil, "test-token")
+		testutil.AssertStatusCode(t, w, http.StatusForbidden)
+	})
+}
+
+func TestDocumentHandler_UploadDocumentImage_NoStorage(t *testing.T) {
+	handler, e, db := setupDocumentHandler(t)
+	user := testutil.CreateTestUser(t, db, "owner", "owner@test.com", "password")
+	residence := testutil.CreateTestResidence(t, db, user.ID, "Test House")
+	doc := testutil.CreateTestDocument(t, db, residence.ID, user.ID, "Test Doc")
+
+	authGroup := e.Group("/api/documents")
+	authGroup.Use(testutil.MockAuthMiddleware(user))
+	authGroup.POST("/:id/images/", handler.UploadDocumentImage)
+
+	t.Run("document not found", func(t *testing.T) {
+		// Send a plain request (no multipart) - will fail at parse
+		w := testutil.MakeRequest(e, "POST", "/api/documents/99999/images/", nil, "test-token")
+		// Should get 400 because no multipart form
+		assert.True(t, w.Code == http.StatusBadRequest || w.Code == http.StatusNotFound,
+			"expected 400 or 404, got %d", w.Code)
+	})
+
+	_ = doc // used to set up test data
+}
+
+func TestDocumentHandler_DeleteDocument(t *testing.T) {
+	handler, e, db := setupDocumentHandler(t)
+	user := testutil.CreateTestUser(t, db, "owner", "owner@test.com", "password")
+	residence := testutil.CreateTestResidence(t, db, user.ID, "Test House")
+	doc := testutil.CreateTestDocument(t, db, residence.ID, user.ID, "Test Doc")
+
+	authGroup := e.Group("/api/documents")
+	authGroup.Use(testutil.MockAuthMiddleware(user))
+	authGroup.DELETE("/:id/", handler.DeleteDocument)
+
+	t.Run("successful delete", func(t *testing.T) {
+		w := testutil.MakeRequest(e, "DELETE", fmt.Sprintf("/api/documents/%d/", doc.ID), nil, "test-token")
+		testutil.AssertStatusCode(t, w, http.StatusOK)
+	})
+
+	t.Run("document not found after delete", func(t *testing.T) {
+		// Already soft-deleted above
+		w := testutil.MakeRequest(e, "DELETE", fmt.Sprintf("/api/documents/%d/", doc.ID), nil, "test-token")
+		testutil.AssertStatusCode(t, w, http.StatusNotFound)
+	})
+}

internal/handlers/notification_handler.go

@@ -149,6 +149,33 @@ func (h *NotificationHandler) ListDevices(c echo.Context) error {
 	return c.JSON(http.StatusOK, devices)
 }
 
+// UnregisterDevice handles POST /api/notifications/devices/unregister/
+// Accepts {registration_id, platform} and deactivates the matching device
+func (h *NotificationHandler) UnregisterDevice(c echo.Context) error {
+	user := c.Get(middleware.AuthUserKey).(*models.User)
+
+	var req struct {
+		RegistrationID string `json:"registration_id"`
+		Platform       string `json:"platform"`
+	}
+	if err := c.Bind(&req); err != nil {
+		return apperrors.BadRequest("error.invalid_request")
+	}
+	if req.RegistrationID == "" {
+		return apperrors.BadRequest("error.registration_id_required")
+	}
+	if req.Platform == "" {
+		req.Platform = "ios" // Default to iOS
+	}
+
+	err := h.notificationService.UnregisterDevice(req.RegistrationID, req.Platform, user.ID)
+	if err != nil {
+		return err
+	}
+
+	return c.JSON(http.StatusOK, map[string]interface{}{"message": "message.device_unregistered"})
+}
+
 // DeleteDevice handles DELETE /api/notifications/devices/:id/
 func (h *NotificationHandler) DeleteDevice(c echo.Context) error {
 	user := c.Get(middleware.AuthUserKey).(*models.User)

internal/handlers/residence_handler.go

@@ -149,6 +149,28 @@ func (h *ResidenceHandler) DeleteResidence(c echo.Context) error {
 	return c.JSON(http.StatusOK, response)
 }
 
+// GetShareCode handles GET /api/residences/:id/share-code/
+// Returns the active share code for a residence, or null if none exists
+func (h *ResidenceHandler) GetShareCode(c echo.Context) error {
+	user := c.Get(middleware.AuthUserKey).(*models.User)
+
+	residenceID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		return apperrors.BadRequest("error.invalid_residence_id")
+	}
+
+	shareCode, err := h.residenceService.GetShareCode(uint(residenceID), user.ID)
+	if err != nil {
+		return err
+	}
+
+	if shareCode == nil {
+		return c.JSON(http.StatusOK, map[string]interface{}{"share_code": nil})
+	}
+
+	return c.JSON(http.StatusOK, map[string]interface{}{"share_code": shareCode})
+}
+
 // GenerateShareCode handles POST /api/residences/:id/generate-share-code/
 func (h *ResidenceHandler) GenerateShareCode(c echo.Context) error {
 	user := c.Get(middleware.AuthUserKey).(*models.User)

internal/handlers/subscription_handler.go

@@ -113,6 +113,8 @@ func (h *SubscriptionHandler) ProcessPurchase(c echo.Context) error {
 			return apperrors.BadRequest("error.purchase_token_required")
 		}
 		subscription, err = h.subscriptionService.ProcessGooglePurchase(user.ID, req.PurchaseToken, req.ProductID)
+	default:
+		return apperrors.BadRequest("error.invalid_platform")
 	}
 
 	if err != nil {
@@ -158,6 +160,8 @@ func (h *SubscriptionHandler) RestoreSubscription(c echo.Context) error {
 		subscription, err = h.subscriptionService.ProcessApplePurchase(user.ID, req.ReceiptData, req.TransactionID)
 	case "android":
 		subscription, err = h.subscriptionService.ProcessGooglePurchase(user.ID, req.PurchaseToken, req.ProductID)
+	default:
+		return apperrors.BadRequest("error.invalid_platform")
 	}
 
 	if err != nil {

internal/handlers/task_handler.go

@@ -1,7 +1,6 @@
 package handlers
 
 import (
-	"mime/multipart"
 	"net/http"
 	"strconv"
 	"strings"
@@ -75,7 +74,12 @@ func (h *TaskHandler) GetTasksByResidence(c echo.Context) error {
 	}
 
 	daysThreshold := 30
-	if d := c.QueryParam("days_threshold"); d != "" {
+	// Support "days" param first, fall back to "days_threshold" for backward compatibility
+	if d := c.QueryParam("days"); d != "" {
+		if parsed, err := strconv.Atoi(d); err == nil {
+			daysThreshold = parsed
+		}
+	} else if d := c.QueryParam("days_threshold"); d != "" {
 		if parsed, err := strconv.Atoi(d); err == nil {
 			daysThreshold = parsed
 		}
@@ -331,23 +335,17 @@ func (h *TaskHandler) CreateCompletion(c echo.Context) error {
 			}
 		}
 
-		// Handle image upload (look for "images" or "image" or "photo" field)
-		var imageFile interface{}
-		for _, fieldName := range []string{"images", "image", "photo"} {
-			if file, err := c.FormFile(fieldName); err == nil {
-				imageFile = file
-				break
-			}
-		}
-
-		if imageFile != nil {
-			file := imageFile.(*multipart.FileHeader)
-			if h.storageService != nil {
-				result, err := h.storageService.Upload(file, "completions")
-				if err != nil {
-					return apperrors.BadRequest("error.failed_to_upload_image")
+		// Handle multiple image uploads from various field names
+		if h.storageService != nil && c.Request().MultipartForm != nil {
+			for _, fieldName := range []string{"images", "image", "photo", "files"} {
+				files := c.Request().MultipartForm.File[fieldName]
+				for _, file := range files {
+					result, err := h.storageService.Upload(file, "completions")
+					if err != nil {
+						return apperrors.BadRequest("error.failed_to_upload_image")
+					}
+					req.ImageURLs = append(req.ImageURLs, result.URL)
 				}
-				req.ImageURLs = append(req.ImageURLs, result.URL)
 			}
 		}
 	} else {
@@ -364,6 +362,26 @@ func (h *TaskHandler) CreateCompletion(c echo.Context) error {
 	return c.JSON(http.StatusCreated, response)
 }
 
+// UpdateCompletion handles PUT /api/task-completions/:id/
+func (h *TaskHandler) UpdateCompletion(c echo.Context) error {
+	user := c.Get(middleware.AuthUserKey).(*models.User)
+	completionID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		return apperrors.BadRequest("error.invalid_completion_id")
+	}
+
+	var req requests.UpdateTaskCompletionRequest
+	if err := c.Bind(&req); err != nil {
+		return apperrors.BadRequest("error.invalid_request")
+	}
+
+	response, err := h.taskService.UpdateCompletion(uint(completionID), user.ID, &req)
+	if err != nil {
+		return err
+	}
+	return c.JSON(http.StatusOK, response)
+}
+
 // DeleteCompletion handles DELETE /api/task-completions/:id/
 func (h *TaskHandler) DeleteCompletion(c echo.Context) error {
 	user := c.Get(middleware.AuthUserKey).(*models.User)