feat: add S3 cleanup on image change/remove

- Fix S3KeySchema to match actual key format (folder/uuid-filename.ext)
- Add removeByUrl command for URL-based S3 deletion
- Delete old S3 files when images are changed or removed
- Add extractS3KeyFromUrl helper function
- Update tests for new key format

Author: aster-void

docs/knowledges/image-upload.md

@@ -42,8 +42,38 @@ const MAX_BASE64_SIZE = Math.ceil(10 * 1024 * 1024 * 1.37);
 - Base64 adds ~37% overhead
 - 10MB file → ~13.7MB base64
 
+## S3 Key Format
+
+Keys follow the format: `{folder}/{uuid}-{filename}.{ext}`
+
+Example: `articles/a1b2c3d4-e5f6-7890-abcd-ef1234567890-cover.webp`
+
+Allowed folders: `images`, `uploads`, `covers`, `avatars`, `articles`, `members`, `projects`
+
+## S3 Cleanup
+
+When images are changed or removed, the old S3 file is automatically deleted:
+
+- **Change**: Old image deleted after new upload succeeds
+- **Remove**: Image deleted immediately when "Remove" button clicked
+- **External URLs**: Non-S3 URLs (different host) are ignored safely
+
+The `removeByUrl` command in `storage.remote.ts` handles URL-to-key conversion server-side.
+
+## User Input Methods
+
+The `ImageUpload` component supports:
+
+1. **Click**: Click to open file picker
+2. **Drag & Drop**: Drag image files onto the component
+3. **Paste (Ctrl+V)**: Paste from clipboard anywhere on the page
+
+Paste is handled globally via `svelte:window onpaste` and skips INPUT/TEXTAREA elements to avoid conflicts.
+
 ## Design Decisions
 
 - **Never reject user uploads**: Compress instead of refusing
 - **Quality over size**: Try high quality first, only reduce if needed
 - **GIF exception**: GIFs skip compression (animation would be lost)
+- **Clean up S3**: Delete old files on change/remove to avoid orphans
+- **Fire-and-forget cleanup**: S3 deletion errors don't block the UI

src/lib/components/image-upload.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
 	import { AlertCircle, Loader2, RotateCw, Upload, X } from "lucide-svelte";
-	import { upload } from "$lib/data/private/storage.remote";
+	import { removeByUrl, upload } from "$lib/data/private/storage.remote";
 	import {
 		type AllowedFolder,
 		isAcceptedImageType,
@@ -55,6 +55,9 @@
 		// Compress image before upload
 		const processedFile = await compressImage(file);
 
+		// Store old URL to delete after successful upload
+		const oldUrl = value;
+
 		// Immediate preview
 		previewUrl = URL.createObjectURL(processedFile);
 		isUploading = true;
@@ -72,6 +75,11 @@
 			});
 			value = result.url;
 			lastFailedFile = null; // Clear on success
+
+			// Delete old S3 image after successful upload
+			if (oldUrl) {
+				removeByUrl(oldUrl).catch(console.error);
+			}
 		} catch {
 			error = "Upload failed. Please try again.";
 			previewUrl = null;
@@ -128,6 +136,10 @@
 	}
 
 	function clearImage() {
+		// Delete S3 image if it exists
+		if (value) {
+			removeByUrl(value).catch(console.error);
+		}
 		value = "";
 		previewUrl = null;
 		error = null;

src/lib/data/private/storage.remote.ts

@@ -1,10 +1,11 @@
 import * as v from "valibot";
 import { command } from "$app/server";
+import { env } from "$lib/env/env.server";
 import { requireUtCodeMember } from "$lib/server/database/auth.server";
 import { compressImage } from "$lib/server/database/image.server";
 import { deleteFile, uploadBuffer } from "$lib/server/database/storage.server";
 import { ACCEPTED_IMAGE_TYPES, ALLOWED_FOLDERS } from "$lib/shared/logic/image";
-import { S3KeySchema } from "$lib/shared/logic/storage";
+import { extractS3KeyFromUrl, S3KeySchema } from "$lib/shared/logic/storage";
 
 /** Allowed folder paths for uploads */
 const FolderSchema = v.optional(v.picklist([...ALLOWED_FOLDERS]));
@@ -39,3 +40,21 @@ export const remove = command(S3KeySchema, async (key) => {
   await requireUtCodeMember();
   await deleteFile(key);
 });
+
+/**
+ * Delete an image by its URL
+ * Only works for S3-hosted images (checks against S3_PUBLIC_URL)
+ * Returns true if deleted, false if URL was not an S3 image
+ */
+export const removeByUrl = command(v.string(), async (url) => {
+  await requireUtCodeMember();
+
+  const key = extractS3KeyFromUrl(url, env.S3_PUBLIC_URL);
+  if (!key) {
+    // Not an S3 URL or invalid key - nothing to delete
+    return false;
+  }
+
+  await deleteFile(key);
+  return true;
+});

src/lib/shared/logic/storage.test.ts

@@ -1,34 +1,39 @@
 import { describe, expect, test } from "bun:test";
 import * as v from "valibot";
-import { getExtensionFromKey, S3_KEY_PATTERN, S3KeySchema, validateS3Key } from "./storage";
+import {
+  extractS3KeyFromUrl,
+  getExtensionFromKey,
+  S3_KEY_PATTERN,
+  S3KeySchema,
+  validateS3Key,
+} from "./storage";
 
 describe("storage", () => {
   describe("validateS3Key", () => {
-    test("accepts valid UUID key", () => {
-      expect(validateS3Key("a1b2c3d4-e5f6/a1b2c3d4-e5f6.jpg")).toBe(true);
+    test("accepts valid key with folder/uuid-filename format", () => {
+      expect(validateS3Key("articles/a1b2c3d4-e5f6-7890-abcd-ef1234567890-cover.jpg")).toBe(true);
     });
 
     test("accepts valid key with full UUID format", () => {
-      expect(
-        validateS3Key(
-          "550e8400-e29b-41d4-a716-446655440000/550e8400-e29b-41d4-a716-446655440000.png",
-        ),
-      ).toBe(true);
+      expect(validateS3Key("projects/550e8400-e29b-41d4-a716-446655440000-thumbnail.png")).toBe(
+        true,
+      );
     });
 
-    test("accepts various file extensions", () => {
-      expect(validateS3Key("abc123/def456.jpg")).toBe(true);
-      expect(validateS3Key("abc123/def456.png")).toBe(true);
-      expect(validateS3Key("abc123/def456.webp")).toBe(true);
-      expect(validateS3Key("abc123/def456.gif")).toBe(true);
+    test("accepts various allowed folders", () => {
+      expect(validateS3Key("images/abc-123-file.jpg")).toBe(true);
+      expect(validateS3Key("uploads/abc-123-file.png")).toBe(true);
+      expect(validateS3Key("covers/abc-123-file.webp")).toBe(true);
+      expect(validateS3Key("avatars/abc-123-file.gif")).toBe(true);
+      expect(validateS3Key("members/abc-123-file.jpg")).toBe(true);
     });
 
     test("rejects path traversal attempt", () => {
       expect(validateS3Key("../../../etc/passwd")).toBe(false);
     });
 
     test("rejects key without extension", () => {
-      expect(validateS3Key("a1b2c3d4-e5f6/a1b2c3d4-e5f6")).toBe(false);
+      expect(validateS3Key("articles/a1b2c3d4-cover")).toBe(false);
     });
 
     test("rejects key without slash", () => {
@@ -43,8 +48,12 @@ describe("storage", () => {
       expect(validateS3Key("test/../admin/secret.jpg")).toBe(false);
     });
 
-    test("rejects uppercase letters", () => {
-      expect(validateS3Key("ABC123/DEF456.jpg")).toBe(false);
+    test("rejects uppercase folder", () => {
+      expect(validateS3Key("ARTICLES/abc-123.jpg")).toBe(false);
+    });
+
+    test("rejects invalid folder", () => {
+      expect(validateS3Key("invalid/abc-123-file.jpg")).toBe(false);
     });
 
     test("rejects empty string", () => {
@@ -54,19 +63,19 @@ describe("storage", () => {
 
   describe("getExtensionFromKey", () => {
     test("extracts jpg extension", () => {
-      expect(getExtensionFromKey("abc123/def456.jpg")).toBe("jpg");
+      expect(getExtensionFromKey("articles/abc-123-file.jpg")).toBe("jpg");
     });
 
     test("extracts png extension", () => {
-      expect(getExtensionFromKey("abc123/def456.png")).toBe("png");
+      expect(getExtensionFromKey("projects/abc-123-file.png")).toBe("png");
     });
 
     test("extracts webp extension", () => {
-      expect(getExtensionFromKey("abc123/def456.webp")).toBe("webp");
+      expect(getExtensionFromKey("images/abc-123-file.webp")).toBe("webp");
     });
 
     test("returns null for key without extension", () => {
-      expect(getExtensionFromKey("abc123/def456")).toBe(null);
+      expect(getExtensionFromKey("articles/abc-123-file")).toBe(null);
     });
 
     test("returns null for empty string", () => {
@@ -76,7 +85,7 @@ describe("storage", () => {
 
   describe("S3KeySchema (Valibot)", () => {
     test("passes valid key", () => {
-      const result = v.safeParse(S3KeySchema, "a1b2c3d4-e5f6/a1b2c3d4-e5f6.jpg");
+      const result = v.safeParse(S3KeySchema, "articles/a1b2c3d4-cover.jpg");
       expect(result.success).toBe(true);
     });
 
@@ -89,15 +98,58 @@ describe("storage", () => {
     });
 
     test("fails path without extension", () => {
-      const result = v.safeParse(S3KeySchema, "abc123/def456");
+      const result = v.safeParse(S3KeySchema, "articles/abc-123-file");
       expect(result.success).toBe(false);
     });
+
+    test("fails with invalid folder", () => {
+      const result = v.safeParse(S3KeySchema, "invalid/abc-123-file.jpg");
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.issues[0].message).toBe("Invalid folder");
+      }
+    });
   });
 
   describe("S3_KEY_PATTERN", () => {
     test("is exported and usable", () => {
       expect(S3_KEY_PATTERN).toBeInstanceOf(RegExp);
-      expect(S3_KEY_PATTERN.test("abc123/def456.jpg")).toBe(true);
+      expect(S3_KEY_PATTERN.test("articles/abc-123-file.jpg")).toBe(true);
+    });
+  });
+
+  describe("extractS3KeyFromUrl", () => {
+    const baseUrl = "http://localhost:9000/dev";
+
+    test("extracts key from valid S3 URL", () => {
+      expect(extractS3KeyFromUrl(`${baseUrl}/articles/a1b2c3d4-cover.webp`, baseUrl)).toBe(
+        "articles/a1b2c3d4-cover.webp",
+      );
+    });
+
+    test("returns null for external URL", () => {
+      expect(extractS3KeyFromUrl("https://example.com/image.jpg", baseUrl)).toBe(null);
+    });
+
+    test("returns null for URL with different base", () => {
+      expect(extractS3KeyFromUrl("http://other.host/articles/a1b2c3d4-cover.webp", baseUrl)).toBe(
+        null,
+      );
+    });
+
+    test("returns null for invalid key format", () => {
+      expect(extractS3KeyFromUrl(`${baseUrl}/invalid/key`, baseUrl)).toBe(null);
+    });
+
+    test("returns null for empty URL", () => {
+      expect(extractS3KeyFromUrl("", baseUrl)).toBe(null);
+    });
+
+    test("works with production-like URLs", () => {
+      const prodUrl = "https://s3.example.com/bucket";
+      expect(extractS3KeyFromUrl(`${prodUrl}/members/a1b2c3d4-avatar.png`, prodUrl)).toBe(
+        "members/a1b2c3d4-avatar.png",
+      );
     });
   });
 });

src/lib/shared/logic/storage.ts

@@ -1,24 +1,33 @@
 import * as v from "valibot";
+import { ALLOWED_FOLDERS } from "./image";
 
 /**
- * Regex pattern for valid S3 keys: {uuid}/{uuid}.{ext} format
+ * Regex pattern for valid S3 keys: {folder}/{uuid}-{filename}.{ext} format
+ * Example: articles/a1b2c3d4-e5f6-7890-abcd-ef1234567890-cover.webp
  * This prevents path traversal attacks and ensures consistent key structure
  */
-export const S3_KEY_PATTERN = /^[a-f0-9-]+\/[a-f0-9-]+\.[a-zA-Z0-9]+$/;
+export const S3_KEY_PATTERN = /^[a-z]+\/[a-f0-9-]+-[^/]+\.[a-zA-Z0-9]+$/;
 
 /**
  * Valibot schema for S3 key validation
- * Ensures keys follow the {uuid}/{uuid}.{ext} format
+ * Ensures keys follow the {folder}/{uuid}-{filename}.{ext} format
  */
-export const S3KeySchema = v.pipe(v.string(), v.regex(S3_KEY_PATTERN, "Invalid S3 key format"));
+export const S3KeySchema = v.pipe(
+  v.string(),
+  v.regex(S3_KEY_PATTERN, "Invalid S3 key format"),
+  v.check((key) => {
+    const folder = key.split("/")[0];
+    return ALLOWED_FOLDERS.some((f) => f === folder);
+  }, "Invalid folder"),
+);
 
 /**
  * Validates an S3 key string
  * @param key - The S3 key to validate
  * @returns true if valid, false otherwise
  */
 export function validateS3Key(key: string): boolean {
-  return S3_KEY_PATTERN.test(key);
+  return S3_KEY_PATTERN.test(key) && ALLOWED_FOLDERS.some((f) => f === key.split("/")[0]);
 }
 
 /**
@@ -30,3 +39,15 @@ export function getExtensionFromKey(key: string): string | null {
   const match = key.match(/\.([a-zA-Z0-9]+)$/);
   return match?.[1] ?? null;
 }
+
+/**
+ * Extracts S3 key from a full S3 URL
+ * @param url - The full S3 URL (e.g., http://localhost:9000/dev/articles/uuid-file.webp)
+ * @param baseUrl - The S3 public URL base (e.g., http://localhost:9000/dev)
+ * @returns The S3 key or null if invalid
+ */
+export function extractS3KeyFromUrl(url: string, baseUrl: string): string | null {
+  if (!url.startsWith(baseUrl)) return null;
+  const key = url.slice(baseUrl.length + 1); // +1 for the trailing slash
+  return validateS3Key(key) ? key : null;
+}