⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.
TypeScript honoissue-managementissue-trackerjira-alternativekanbanlinear-alternativemcpproject-managementreactself-hostedtypescript
feat(api): add S3 key prefix support and auto-delete orphaned assets (#1258)
tiran13384fd6bd38bd2
diff --git a/apps/api/src/activity/controllers/delete-comment.ts b/apps/api/src/activity/controllers/delete-comment.tsindex 4080a0b23..9c73c610d 100644--- a/apps/api/src/activity/controllers/delete-comment.ts+++ b/apps/api/src/activity/controllers/delete-comment.ts@@ -3,11 +3,28 @@ import { HTTPException } from "hono/http-exception";import db from "../../database";import { activityTable, taskTable } from "../../database/schema";import { publishEvent } from "../../events";+import { deleteOrphanedAssets } from "../../storage/cleanup-assets";async function deleteComment(userId: string, id: string) {+ const [existing] = await db+ .select({+ id: activityTable.id,+ content: activityTable.content,+ taskId: activityTable.taskId,+ })+ .from(activityTable)+ .where(and(eq(activityTable.id, id), eq(activityTable.userId, userId)))+ .limit(1);++ if (!existing) {+ throw new HTTPException(404, {+ message: "Comment not found or you are not the author",+ });+ }+const [deletedComment] = await db.delete(activityTable)- .where(and(eq(activityTable.id, id), eq(activityTable.userId, userId)))+ .where(eq(activityTable.id, id)).returning();if (!deletedComment) {@@ -30,6 +47,10 @@ async function deleteComment(userId: string, id: string) {});}+ deleteOrphanedAssets(existing.content, null, {+ taskId: existing.taskId,+ }).catch(() => {});+return deletedComment;}diff --git a/apps/api/src/activity/controllers/update-comment.ts b/apps/api/src/activity/controllers/update-comment.tsindex f462dddc7..b09d96a63 100644--- a/apps/api/src/activity/controllers/update-comment.ts+++ b/apps/api/src/activity/controllers/update-comment.ts@@ -3,12 +3,29 @@ import { HTTPException } from "hono/http-exception";import db from "../../database";import { activityTable, taskTable } from "../../database/schema";import { publishEvent } from "../../events";+import { deleteOrphanedAssets } from "../../storage/cleanup-assets";async function updateComment(userId: string, id: string, content: string) {+ const [existing] = await db+ .select({+ id: activityTable.id,+ content: activityTable.content,+ taskId: activityTable.taskId,+ })+ .from(activityTable)+ .where(and(eq(activityTable.id, id), eq(activityTable.userId, userId)))+ .limit(1);++ if (!existing) {+ throw new HTTPException(404, {+ message: "Comment not found or you are not the author",+ });+ }+const [updated] = await db.update(activityTable).set({ content })- .where(and(eq(activityTable.id, id), eq(activityTable.userId, userId)))+ .where(eq(activityTable.id, id)).returning();if (!updated) {@@ -31,6 +48,10 @@ async function updateComment(userId: string, id: string, content: string) {});}+ deleteOrphanedAssets(existing.content, content, {+ taskId: existing.taskId,+ }).catch(() => {});+return updated;}diff --git a/apps/api/src/comment/controllers/delete-comment.ts b/apps/api/src/comment/controllers/delete-comment.tsindex 339283fa4..7562e3ca2 100644--- a/apps/api/src/comment/controllers/delete-comment.ts+++ b/apps/api/src/comment/controllers/delete-comment.ts@@ -3,10 +3,15 @@ import { HTTPException } from "hono/http-exception";import db from "../../database";import { commentTable, taskTable } from "../../database/schema";import { publishEvent } from "../../events";+import { deleteOrphanedAssets } from "../../storage/cleanup-assets";async function deleteComment(userId: string, id: string) {const [existing] = await db- .select({ userId: commentTable.userId, taskId: commentTable.taskId })+ .select({+ userId: commentTable.userId,+ taskId: commentTable.taskId,+ content: commentTable.content,+ }).from(commentTable).where(eq(commentTable.id, id)).limit(1);@@ -45,6 +50,10 @@ async function deleteComment(userId: string, id: string) {});}+ deleteOrphanedAssets(existing.content, null, {+ taskId: existing.taskId,+ }).catch(() => {});+return deleted;}diff --git a/apps/api/src/comment/controllers/update-comment.ts b/apps/api/src/comment/controllers/update-comment.tsindex 35a2d9703..d2fb4817d 100644--- a/apps/api/src/comment/controllers/update-comment.ts+++ b/apps/api/src/comment/controllers/update-comment.ts@@ -3,10 +3,15 @@ import { HTTPException } from "hono/http-exception";import db from "../../database";import { commentTable, taskTable } from "../../database/schema";import { publishEvent } from "../../events";+import { deleteOrphanedAssets } from "../../storage/cleanup-assets";async function updateComment(userId: string, id: string, content: string) {const [existing] = await db- .select({ userId: commentTable.userId, taskId: commentTable.taskId })+ .select({+ userId: commentTable.userId,+ taskId: commentTable.taskId,+ content: commentTable.content,+ }).from(commentTable).where(eq(commentTable.id, id)).limit(1);@@ -46,6 +51,10 @@ async function updateComment(userId: string, id: string, content: string) {});}+ deleteOrphanedAssets(existing.content, content, {+ taskId: existing.taskId,+ }).catch(() => {});+return updated;}diff --git a/apps/api/src/storage/cleanup-assets.ts b/apps/api/src/storage/cleanup-assets.tsnew file mode 100644index 000000000..227ee0457--- /dev/null+++ b/apps/api/src/storage/cleanup-assets.ts@@ -0,0 +1,175 @@+import { and, eq, inArray, like } from "drizzle-orm";+import db from "../database";+import {+ activityTable,+ assetTable,+ commentTable,+ taskTable,+} from "../database/schema";+import { deleteS3Object } from "./s3";++const ASSET_URL_PATTERN = /\/api\/asset\/([a-z0-9]+)/gi;++export function extractAssetIds(+ content: string | null | undefined,+): Set<string> {+ const ids = new Set<string>();+ if (!content) return ids;++ ASSET_URL_PATTERN.lastIndex = 0;+ for (+ let match = ASSET_URL_PATTERN.exec(content);+ match !== null;+ match = ASSET_URL_PATTERN.exec(content)+ ) {+ if (match[1]) ids.add(match[1]);+ }++ return ids;+}++export function contentReferencesAsset(+ content: string | null | undefined,+ assetId: string,+): boolean {+ return extractAssetIds(content).has(assetId);+}++export interface AssetCleanupScope {+ taskId: string;+}++/**+ * Check whether an asset ID is still referenced in any content belonging to+ * the same task (description, comments, or activity comments).+ */+async function isAssetReferencedElsewhere(+ assetId: string,+ taskId: string,+): Promise<boolean> {+ const pattern = `%/api/asset/${assetId}%`;++ const [taskRef] = await db+ .select({ description: taskTable.description })+ .from(taskTable)+ .where(and(eq(taskTable.id, taskId), like(taskTable.description, pattern)))+ .limit(1);++ if (contentReferencesAsset(taskRef?.description, assetId)) return true;++ const commentRefs = await db+ .select({ content: commentTable.content })+ .from(commentTable)+ .where(+ and(eq(commentTable.taskId, taskId), like(commentTable.content, pattern)),+ );++ if (commentRefs.some((ref) => contentReferencesAsset(ref.content, assetId))) {+ return true;+ }++ const activityRefs = await db+ .select({ content: activityTable.content })+ .from(activityTable)+ .where(+ and(+ eq(activityTable.taskId, taskId),+ like(activityTable.content, pattern),+ ),+ );++ if (+ activityRefs.some((ref) => contentReferencesAsset(ref.content, assetId))+ ) {+ return true;+ }++ return false;+}++export async function deleteOrphanedAssets(+ oldContent: string | null | undefined,+ newContent: string | null | undefined,+ scope: AssetCleanupScope,+): Promise<void> {+ const oldIds = extractAssetIds(oldContent);+ const newIds = extractAssetIds(newContent);++ const removedIds = [...oldIds].filter((id) => !newIds.has(id));+ if (removedIds.length === 0) return;++ const assets = await db+ .select({ id: assetTable.id, objectKey: assetTable.objectKey })+ .from(assetTable)+ .where(+ and(+ inArray(assetTable.id, removedIds),+ eq(assetTable.taskId, scope.taskId),+ ),+ );++ const assetsToDelete: typeof assets = [];+ for (const asset of assets) {+ const stillReferenced = await isAssetReferencedElsewhere(+ asset.id,+ scope.taskId,+ );+ if (!stillReferenced) {+ assetsToDelete.push(asset);+ }+ }++ if (assetsToDelete.length === 0) return;++ const deleteResults = await deleteS3Keys(+ assetsToDelete.map((asset) => asset.objectKey),+ );++ const deletedAssetIds = assetsToDelete+ .filter((_, index) => deleteResults[index]?.status === "fulfilled")+ .map((asset) => asset.id);++ if (deletedAssetIds.length === 0) return;++ await db.delete(assetTable).where(inArray(assetTable.id, deletedAssetIds));+}++export async function getTaskAssetKeys(taskId: string): Promise<string[]> {+ const assets = await db+ .select({ objectKey: assetTable.objectKey })+ .from(assetTable)+ .where(eq(assetTable.taskId, taskId));++ return assets.map((a) => a.objectKey);+}++export async function deleteS3Keys(+ keys: string[],+): Promise<PromiseSettledResult<void>[]> {+ const deleteResults = await Promise.allSettled(+ keys.map((key) => deleteS3Object(key)),+ );++ const failedDeletions = keys+ .map((key, index) => ({ key, result: deleteResults[index] }))+ .filter(+ (+ deletion,+ ): deletion is {+ key: string;+ result: PromiseRejectedResult;+ } => deletion.result?.status === "rejected",+ );++ if (failedDeletions.length > 0) {+ console.error(+ "Failed to delete S3 objects",+ failedDeletions.map(({ key, result }) => ({+ key,+ reason: result.reason,+ })),+ );+ }++ return deleteResults;+}diff --git a/apps/api/src/storage/s3.ts b/apps/api/src/storage/s3.tsindex 6c9ef8723..f2b2ef9f8 100644--- a/apps/api/src/storage/s3.ts+++ b/apps/api/src/storage/s3.ts@@ -1,5 +1,6 @@import { Readable } from "node:stream";import {+ DeleteObjectCommand,GetObjectCommand,PutObjectCommand,S3Client,@@ -40,6 +41,7 @@ type StorageConfig = {accessKeyId: string;secretAccessKey: string;publicBaseUrl?: string;+ keyPrefix: string;forcePathStyle: boolean;maxImageUploadBytes: number;presignTtlSeconds: number;@@ -109,6 +111,7 @@ function getStorageConfig(): StorageConfig {accessKeyId,secretAccessKey,publicBaseUrl: env("S3_PUBLIC_BASE_URL") || undefined,+ keyPrefix: env("S3_KEY_PREFIX"),forcePathStyle: parseBoolean(process.env.S3_FORCE_PATH_STYLE, true),maxImageUploadBytes: parsePositiveInt(process.env.S3_MAX_IMAGE_UPLOAD_BYTES,@@ -212,6 +215,12 @@ export function buildObjectKey(context: TaskImageUploadContext) {return `${objectKeyPrefix}/${fileName}`;}+export function applyKeyPrefix(prefix: string, key: string) {+ if (!prefix) return key;+ const trimmed = prefix.replace(/\/+$/, "");+ return `${trimmed}/${key}`;+}+export function validateTaskAssetUploadInput(contentType: string,size: number,@@ -238,7 +247,8 @@ export async function createTaskImageUploadUrl(): Promise<TaskImageUploadUrl> {const config = getStorageConfig();const client = getClient(config);- const key = buildObjectKey(context);+ const rawKey = buildObjectKey(context);+ const key = applyKeyPrefix(config.keyPrefix, rawKey);const command = new PutObjectCommand({Bucket: config.bucket,@@ -267,8 +277,10 @@ export function assertTaskImageKeyMatchesContext(key: string,context: Omit<TaskImageUploadContext, "filename" | "contentType">,) {- const prefix = `${buildObjectKeyPrefix(context)}/`;- return key.startsWith(prefix);+ const config = getStorageConfig();+ const objectPrefix = buildObjectKeyPrefix(context);+ const fullPrefix = `${applyKeyPrefix(config.keyPrefix, objectPrefix)}/`;+ return key.startsWith(fullPrefix);}export async function getPrivateObject(key: string): Promise<AssetObject> {@@ -298,3 +310,14 @@ export async function getPrivateObject(key: string): Promise<AssetObject> {lastModified: response.LastModified,};}++export async function deleteS3Object(key: string): Promise<void> {+ const config = getStorageConfig();+ const client = getClient(config);+ await client.send(+ new DeleteObjectCommand({+ Bucket: config.bucket,+ Key: key,+ }),+ );+}diff --git a/apps/api/src/task/controllers/delete-task.ts b/apps/api/src/task/controllers/delete-task.tsindex 6e1903d35..df1c96e54 100644--- a/apps/api/src/task/controllers/delete-task.ts+++ b/apps/api/src/task/controllers/delete-task.ts@@ -3,6 +3,7 @@ import { HTTPException } from "hono/http-exception";import db from "../../database";import { taskRelationTable, taskTable } from "../../database/schema";import { publishEvent } from "../../events";+import { deleteS3Keys, getTaskAssetKeys } from "../../storage/cleanup-assets";import getTask from "./get-task";async function deleteTask(taskId: string, currentUserId: string) {@@ -19,6 +20,8 @@ async function deleteTask(taskId: string, currentUserId: string) {).execute();+ const assetKeys = await getTaskAssetKeys(taskId);+const [deletedTask] = await db.delete(taskTable).where(eq(taskTable.id, taskId))@@ -47,6 +50,11 @@ async function deleteTask(taskId: string, currentUserId: string) {});}+ // Fire-and-forget S3 cleanup after successful DB delete+ if (assetKeys.length > 0) {+ deleteS3Keys(assetKeys).catch(() => {});+ }+return task;}diff --git a/apps/api/src/task/controllers/update-task-description.ts b/apps/api/src/task/controllers/update-task-description.tsindex 4c1580c65..1efe82680 100644--- a/apps/api/src/task/controllers/update-task-description.ts+++ b/apps/api/src/task/controllers/update-task-description.ts@@ -3,6 +3,7 @@ import { HTTPException } from "hono/http-exception";import db from "../../database";import { taskTable } from "../../database/schema";import { publishEvent } from "../../events";+import { deleteOrphanedAssets } from "../../storage/cleanup-assets";async function updateTaskDescription({id,@@ -44,6 +45,10 @@ async function updateTaskDescription({type: "description_changed",});+ deleteOrphanedAssets(existingTask.description, description, {+ taskId: id,+ }).catch(() => {});+return updatedTask;}diff --git a/apps/api/src/task/controllers/update-task.ts b/apps/api/src/task/controllers/update-task.tsindex a53aaad61..b65c53fb6 100644--- a/apps/api/src/task/controllers/update-task.ts+++ b/apps/api/src/task/controllers/update-task.ts@@ -3,6 +3,7 @@ import { HTTPException } from "hono/http-exception";import db from "../../database";import { columnTable, taskTable } from "../../database/schema";import { publishEvent } from "../../events";+import { deleteOrphanedAssets } from "../../storage/cleanup-assets";import { assertValidTaskStatus } from "../validate-task-fields";async function updateTask(@@ -86,6 +87,12 @@ async function updateTask(userId: currentUserId,});+ if (existingTask.description !== description) {+ deleteOrphanedAssets(existingTask.description, description, {+ taskId: id,+ }).catch(() => {});+ }+return updatedTask;}diff --git a/apps/docs/core/installation/environment-variables.mdx b/apps/docs/core/installation/environment-variables.mdxindex 239733404..cad771f08 100644--- a/apps/docs/core/installation/environment-variables.mdx+++ b/apps/docs/core/installation/environment-variables.mdx@@ -73,6 +73,7 @@ Name | Description | Default || `S3_PUBLIC_BASE_URL` | Optional public base URL for uploaded assets. Kaneo does not require this for the current private asset flow. | || `S3_FORCE_PATH_STYLE` | Use path-style S3 URLs. This should usually be `true` for MinIO and `fs`. | `true` || `S3_MAX_IMAGE_UPLOAD_BYTES` | Maximum allowed upload size in bytes for images and other uploaded files. | `10485760` |+| `S3_KEY_PREFIX` | Optional prefix prepended to all S3 object keys. Useful for sharing a single bucket across multiple environments (e.g. `staging/`, `prod/kaneo/`). Trailing slashes are trimmed automatically. | || `S3_PRESIGN_TTL_SECONDS` | How long presigned upload URLs remain valid. | `300` |### Access Controldiff --git a/tests/api/storage/s3.test.ts b/tests/api/storage/s3.test.tsindex 6500c7491..cbc814be0 100644--- a/tests/api/storage/s3.test.ts+++ b/tests/api/storage/s3.test.ts@@ -1,5 +1,6 @@import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";import {+ applyKeyPrefix,assertTaskImageKeyMatchesContext,buildObjectKey,buildObjectKeyPrefix,@@ -20,6 +21,7 @@ describe("S3 helpers", () => {const originalSecretAccessKey = process.env.S3_SECRET_ACCESS_KEY;const originalRegion = process.env.S3_REGION;const originalPathStyle = process.env.S3_FORCE_PATH_STYLE;+ const originalKeyPrefix = process.env.S3_KEY_PREFIX;beforeEach(() => {delete process.env.S3_MAX_IMAGE_UPLOAD_BYTES;@@ -69,6 +71,12 @@ describe("S3 helpers", () => {} else {process.env.S3_FORCE_PATH_STYLE = originalPathStyle;}++ if (originalKeyPrefix === undefined) {+ delete process.env.S3_KEY_PREFIX;+ } else {+ process.env.S3_KEY_PREFIX = originalKeyPrefix;+ }});it("recognizes allowed image content types case-insensitively", () => {@@ -117,6 +125,12 @@ describe("S3 helpers", () => {expect(key).toMatch(/^workspace\/workspace-1\/project\/project-2\/task\/task-3\/comments\/sprint-plan-final-1717171717000-[a-z0-9]+\.png$/,);+ process.env.S3_ENDPOINT = "https://storage.example.test";+ process.env.S3_BUCKET = "kaneo";+ process.env.S3_ACCESS_KEY_ID = "test-access-key";+ process.env.S3_SECRET_ACCESS_KEY = "test-secret-key";+ delete process.env.S3_KEY_PREFIX;+expect(assertTaskImageKeyMatchesContext(key, {workspaceId: "Workspace 1",@@ -127,6 +141,42 @@ describe("S3 helpers", () => {).toBe(true);});+ it("applyKeyPrefix prepends prefix and trims trailing slashes", () => {+ expect(applyKeyPrefix("", "workspace/a/file.png")).toBe(+ "workspace/a/file.png",+ );+ expect(applyKeyPrefix("staging", "workspace/a/file.png")).toBe(+ "staging/workspace/a/file.png",+ );+ expect(applyKeyPrefix("prod/kaneo/", "workspace/a/file.png")).toBe(+ "prod/kaneo/workspace/a/file.png",+ );+ expect(applyKeyPrefix("prefix///", "key")).toBe("prefix/key");+ });++ it("assertTaskImageKeyMatchesContext respects S3_KEY_PREFIX", () => {+ process.env.S3_ENDPOINT = "https://storage.example.test";+ process.env.S3_BUCKET = "kaneo";+ process.env.S3_ACCESS_KEY_ID = "test-access-key";+ process.env.S3_SECRET_ACCESS_KEY = "test-secret-key";+ process.env.S3_KEY_PREFIX = "staging";++ const ctx = {+ workspaceId: "ws1",+ projectId: "p1",+ taskId: "t1",+ surface: "description" as const,+ };++ const prefixedKey =+ "staging/workspace/ws1/project/p1/task/t1/descriptions/img-123-abc.png";+ const unprefixedKey =+ "workspace/ws1/project/p1/task/t1/descriptions/img-123-abc.png";++ expect(assertTaskImageKeyMatchesContext(prefixedKey, ctx)).toBe(true);+ expect(assertTaskImageKeyMatchesContext(unprefixedKey, ctx)).toBe(false);+ });+it("validates upload size against the configured maximum", () => {process.env.S3_MAX_IMAGE_UPLOAD_BYTES = "1048576";@@ -149,6 +199,7 @@ describe("S3 helpers", () => {process.env.S3_SECRET_ACCESS_KEY = "test-secret-key";process.env.S3_REGION = "us-east-1";process.env.S3_FORCE_PATH_STYLE = "true";+ delete process.env.S3_KEY_PREFIX;const upload = await createTaskImageUploadUrl({workspaceId: "workspace-1",@@ -164,3 +215,40 @@ describe("S3 helpers", () => {expect(searchParams.has("x-amz-sdk-checksum-algorithm")).toBe(false);});});++vi.mock("../../../apps/api/src/database", () => ({ default: {} }));++const { contentReferencesAsset, extractAssetIds } = await import(+ "../../../apps/api/src/storage/cleanup-assets"+);++describe("extractAssetIds", () => {+ it("extracts asset IDs from content with /api/asset/ URLs", () => {+ const content =+ '<p>Hello <img src="http://localhost:1337/api/asset/abc123" /> world <img src="/api/asset/def456" /></p>';+ const ids = extractAssetIds(content);+ expect(ids).toEqual(new Set(["abc123", "def456"]));+ });++ it("returns empty set for null/undefined/empty content", () => {+ expect(extractAssetIds(null)).toEqual(new Set());+ expect(extractAssetIds(undefined)).toEqual(new Set());+ expect(extractAssetIds("")).toEqual(new Set());+ });++ it("returns empty set when no asset URLs are present", () => {+ expect(extractAssetIds("<p>No images here</p>")).toEqual(new Set());+ });++ it("deduplicates repeated asset IDs", () => {+ const content = "/api/asset/abc123 and again /api/asset/abc123";+ expect(extractAssetIds(content)).toEqual(new Set(["abc123"]));+ });++ it("does not treat asset ID prefixes as references", () => {+ expect(contentReferencesAsset("/api/asset/abc123xyz", "abc123")).toBe(+ false,+ );+ expect(contentReferencesAsset("/api/asset/abc123", "abc123")).toBe(true);+ });+});