⚡ 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: support AWS IAM roles for S3 storage (#1342)
nitin-bhadauria089a7de9c5b1
diff --git a/apps/api/src/storage/s3.ts b/apps/api/src/storage/s3.tsindex f2b2ef9f8..cbe69d5a4 100644--- a/apps/api/src/storage/s3.ts+++ b/apps/api/src/storage/s3.ts@@ -92,18 +92,54 @@ export function parsePositiveInt(value: string | undefined, fallback: number) {return parsed;}+/**+ * Resolves static S3 credentials from the access key pair.+ *+ * Returns the explicit credentials only when BOTH the access key id and secret+ * are provided. When neither is set, returns `undefined` so the AWS SDK falls+ * back to its default credential provider chain (EC2 instance profile, ECS task+ * role, EKS IRSA, environment variables, or shared config) — enabling+ * IAM-role-based access without static keys.+ *+ * Throws when exactly one of the two is set, since that is almost always a+ * misconfiguration rather than an intentional fallback.+ */+export function resolveS3Credentials(+ accessKeyId: string,+ secretAccessKey: string,+): { accessKeyId: string; secretAccessKey: string } | undefined {+ const hasAccessKeyId = Boolean(accessKeyId);+ const hasSecretAccessKey = Boolean(secretAccessKey);++ if (hasAccessKeyId !== hasSecretAccessKey) {+ throw new Error(+ "Incomplete S3 credentials. Set both S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY, or neither to use the default AWS credential provider chain (IAM role / IRSA / environment).",+ );+ }++ if (hasAccessKeyId && hasSecretAccessKey) {+ return { accessKeyId, secretAccessKey };+ }++ return undefined;+}+function getStorageConfig(): StorageConfig {const endpoint = env("S3_ENDPOINT");const bucket = env("S3_BUCKET");const accessKeyId = env("S3_ACCESS_KEY_ID");const secretAccessKey = env("S3_SECRET_ACCESS_KEY");- if (!endpoint || !bucket || !accessKeyId || !secretAccessKey) {+ if (!endpoint || !bucket) {throw new Error(- "S3 uploads are not configured. Set S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY_ID, and S3_SECRET_ACCESS_KEY.",+ "S3 uploads are not configured. Set S3_ENDPOINT and S3_BUCKET (and either both S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY, or neither to use the default AWS credential provider chain / IAM role).",);}+ // Validate the access key pair early so misconfiguration surfaces here rather+ // than as an opaque signing error later.+ resolveS3Credentials(accessKeyId, secretAccessKey);+return {endpoint,region: env("S3_REGION") || "us-east-1",@@ -151,12 +187,21 @@ function getClient(config: StorageConfig) {// Avoid auto-injecting checksum params for presigned PUT URLs. Some// S3-compatible providers (e.g. Garage/R2) reject mismatched hoisted CRCs.requestChecksumCalculation: "WHEN_REQUIRED",- credentials: {- accessKeyId: config.accessKeyId,- secretAccessKey: config.secretAccessKey,- },};+ const credentials = resolveS3Credentials(+ config.accessKeyId,+ config.secretAccessKey,+ );++ // Only pin explicit credentials when both keys are provided. Otherwise leave+ // `credentials` unset so the AWS SDK resolves them from its default provider+ // chain (EC2 instance profile, ECS task role, EKS IRSA, env, shared config),+ // which is how IAM-role-based access works.+ if (credentials) {+ clientConfig.credentials = credentials;+ }+const client = new S3Client(clientConfig);clientCache = { cacheKey, client };return client;diff --git a/apps/docs/core/installation/environment-variables.mdx b/apps/docs/core/installation/environment-variables.mdxindex c4eea4d4a..ac5a30c14 100644--- a/apps/docs/core/installation/environment-variables.mdx+++ b/apps/docs/core/installation/environment-variables.mdx@@ -67,8 +67,8 @@ Name | Description | Default |--- | --- | --- || `S3_ENDPOINT` | The S3-compatible API endpoint used by the Kaneo API for presigned uploads. Example: `http://minio:9000`. | || `S3_BUCKET` | The bucket Kaneo will use for uploaded files. | |-| `S3_ACCESS_KEY_ID` | Access key used by the Kaneo API to create presigned upload URLs. | |-| `S3_SECRET_ACCESS_KEY` | Secret key used by the Kaneo API to create presigned upload URLs. | |+| `S3_ACCESS_KEY_ID` | Access key used by the Kaneo API to create presigned upload URLs. Optional — leave unset (together with `S3_SECRET_ACCESS_KEY`) to use the default AWS credential provider chain (IAM role / IRSA / instance profile). | |+| `S3_SECRET_ACCESS_KEY` | Secret key used by the Kaneo API to create presigned upload URLs. Must be set together with `S3_ACCESS_KEY_ID`, or left unset for IAM-role-based access. | || `S3_REGION` | The storage region used for request signing. | `us-east-1` || `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` |diff --git a/apps/docs/core/installation/object-storage-and-image-uploads.mdx b/apps/docs/core/installation/object-storage-and-image-uploads.mdxindex 5758bf18f..235a93ef0 100644--- a/apps/docs/core/installation/object-storage-and-image-uploads.mdx+++ b/apps/docs/core/installation/object-storage-and-image-uploads.mdx@@ -136,8 +136,8 @@ Set these in your Kaneo deployment:| --- | --- || `S3_ENDPOINT` | S3-compatible API endpoint used by Kaneo || `S3_BUCKET` | Bucket used for uploaded files |-| `S3_ACCESS_KEY_ID` | Access key used to create presigned upload URLs |-| `S3_SECRET_ACCESS_KEY` | Secret key used to create presigned upload URLs |+| `S3_ACCESS_KEY_ID` | Access key used to create presigned upload URLs. Optional when using an IAM role (see below) |+| `S3_SECRET_ACCESS_KEY` | Secret key used to create presigned upload URLs. Optional when using an IAM role (see below) || `S3_REGION` | Region used for signing || `S3_FORCE_PATH_STYLE` | Usually `true` for MinIO and `fs` |@@ -149,6 +149,40 @@ Optional:| `S3_MAX_IMAGE_UPLOAD_BYTES` | Maximum allowed upload size in bytes for images and other uploaded files || `S3_PRESIGN_TTL_SECONDS` | Presigned upload URL lifetime |+## Using an IAM role (AWS S3) instead of static keys++When Kaneo runs on AWS (EC2, ECS, or EKS), you can let it authenticate with an+IAM role instead of long-lived access keys.++Leave both `S3_ACCESS_KEY_ID` and `S3_SECRET_ACCESS_KEY` unset. Kaneo then falls+back to the AWS SDK's default credential provider chain, which automatically+picks up credentials from:++- an EC2 instance profile+- an ECS task role+- an EKS service account / IRSA (`AWS_WEB_IDENTITY_TOKEN_FILE`)+- standard `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` environment variables+- a shared `~/.aws/credentials` profile++Example for AWS S3 with an attached IAM role:++```env+S3_ENDPOINT=https://s3.us-east-1.amazonaws.com+S3_BUCKET=kaneo-uploads+S3_REGION=us-east-1+S3_FORCE_PATH_STYLE=false+# S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY intentionally omitted+```++The IAM role must allow `s3:PutObject`, `s3:GetObject`, and `s3:DeleteObject`+on the bucket.++<Warning>+ Set both keys or neither. Configuring only one of `S3_ACCESS_KEY_ID` /+ `S3_SECRET_ACCESS_KEY` is treated as a misconfiguration and Kaneo will refuse+ to start the storage client.+</Warning>+## Testing uploadsOnce storage is configured:diff --git a/apps/docs/core/installation/storage-backends.mdx b/apps/docs/core/installation/storage-backends.mdxindex 0e46006cc..774734bd3 100644--- a/apps/docs/core/installation/storage-backends.mdx+++ b/apps/docs/core/installation/storage-backends.mdx@@ -114,6 +114,24 @@ For another AWS region, adjust:- `S3_ENDPOINT`+### Using an IAM role instead of an access key++If Kaneo runs on AWS (EC2, ECS, or EKS), you can omit `S3_ACCESS_KEY_ID` and+`S3_SECRET_ACCESS_KEY` entirely and let Kaneo authenticate with the instance's+IAM role. Leave both unset and the AWS SDK resolves credentials from its default+provider chain (instance profile, ECS task role, or EKS IRSA).++```env+S3_ENDPOINT=https://s3.us-east-1.amazonaws.com+S3_BUCKET=kaneo-uploads+S3_REGION=us-east-1+S3_FORCE_PATH_STYLE=false+# S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY omitted — the IAM role is used+```++Set both keys or neither: configuring only one is rejected. The role must allow+`s3:PutObject`, `s3:GetObject`, and `s3:DeleteObject` on the bucket.+Recommended S3 CORS policy:```jsondiff --git a/tests/api/storage/s3.test.ts b/tests/api/storage/s3.test.tsindex cbc814be0..d317a3627 100644--- a/tests/api/storage/s3.test.ts+++ b/tests/api/storage/s3.test.ts@@ -1,6 +1,7 @@import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";import {applyKeyPrefix,+ assertStorageConfigured,assertTaskImageKeyMatchesContext,buildObjectKey,buildObjectKeyPrefix,@@ -9,6 +10,7 @@ import {isImageContentType,parseBoolean,parsePositiveInt,+ resolveS3Credentials,sanitizePathSegment,validateTaskAssetUploadInput,} from "../../../apps/api/src/storage/s3";@@ -214,6 +216,125 @@ describe("S3 helpers", () => {expect(searchParams.has("x-amz-checksum-crc32")).toBe(false);expect(searchParams.has("x-amz-sdk-checksum-algorithm")).toBe(false);});++ it("resolveS3Credentials returns explicit credentials when both keys are set", () => {+ expect(resolveS3Credentials("AKIA", "secret")).toEqual({+ accessKeyId: "AKIA",+ secretAccessKey: "secret",+ });+ });++ it("resolveS3Credentials returns undefined when both keys are absent (IAM role fallback)", () => {+ expect(resolveS3Credentials("", "")).toBeUndefined();+ });++ it("resolveS3Credentials throws when only one key is set", () => {+ expect(() => resolveS3Credentials("AKIA", "")).toThrow(+ /both S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY/,+ );+ expect(() => resolveS3Credentials("", "secret")).toThrow(+ /both S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY/,+ );+ });++ it("assertStorageConfigured succeeds without static keys (IAM role mode)", () => {+ process.env.S3_ENDPOINT = "https://s3.us-east-1.amazonaws.com";+ process.env.S3_BUCKET = "kaneo";+ delete process.env.S3_ACCESS_KEY_ID;+ delete process.env.S3_SECRET_ACCESS_KEY;++ const config = assertStorageConfigured();+ expect(config.bucket).toBe("kaneo");+ expect(config.accessKeyId).toBe("");+ expect(config.secretAccessKey).toBe("");+ });++ it("assertStorageConfigured throws when only one credential key is set", () => {+ process.env.S3_ENDPOINT = "https://s3.us-east-1.amazonaws.com";+ process.env.S3_BUCKET = "kaneo";+ process.env.S3_ACCESS_KEY_ID = "AKIA";+ delete process.env.S3_SECRET_ACCESS_KEY;++ expect(() => assertStorageConfigured()).toThrow(+ /Incomplete S3 credentials/,+ );+ });++ it("assertStorageConfigured throws when endpoint or bucket is missing", () => {+ delete process.env.S3_ENDPOINT;+ delete process.env.S3_BUCKET;++ expect(() => assertStorageConfigured()).toThrow(+ /S3 uploads are not configured/,+ );+ });+});++describe("S3 credential provider chain (IAM role)", () => {+ const trackedKeys = [+ "S3_ENDPOINT",+ "S3_BUCKET",+ "S3_ACCESS_KEY_ID",+ "S3_SECRET_ACCESS_KEY",+ "S3_REGION",+ "S3_FORCE_PATH_STYLE",+ "S3_KEY_PREFIX",+ "AWS_ACCESS_KEY_ID",+ "AWS_SECRET_ACCESS_KEY",+ "AWS_SESSION_TOKEN",+ ] as const;++ const original: Partial<Record<(typeof trackedKeys)[number], string>> = {};++ beforeEach(() => {+ for (const key of trackedKeys) {+ original[key] = process.env[key];+ delete process.env[key];+ }+ });++ afterEach(() => {+ for (const key of trackedKeys) {+ const value = original[key];+ if (value === undefined) {+ delete process.env[key];+ } else {+ process.env[key] = value;+ }+ }+ });++ it("signs presigned URLs using ambient credentials when S3 keys are unset", async () => {+ // Non-sensitive, obviously-fake credentials generated at runtime so no+ // credential-like literals are committed (avoids secret-scanning hits).+ const ambientAccessKeyId = `test-ambient-key-${Date.now()}`;+ const ambientSecretAccessKey = `test-ambient-secret-${Date.now()}`;++ // Simulates an IAM role / IRSA / instance profile: no S3_ACCESS_KEY_ID is+ // configured, but ambient AWS credentials are resolvable from the+ // environment (the AWS SDK default provider chain reads AWS_* env vars).+ process.env.S3_ENDPOINT = "https://s3.us-east-1.amazonaws.com";+ process.env.S3_BUCKET = "kaneo";+ process.env.S3_REGION = "us-east-1";+ process.env.S3_FORCE_PATH_STYLE = "false";+ process.env.AWS_ACCESS_KEY_ID = ambientAccessKeyId;+ process.env.AWS_SECRET_ACCESS_KEY = ambientSecretAccessKey;++ const upload = await createTaskImageUploadUrl({+ workspaceId: "workspace-1",+ projectId: "project-1",+ taskId: "task-1",+ surface: "description",+ filename: "report.png",+ contentType: "image/png",+ });++ const searchParams = new URL(upload.uploadUrl).searchParams;+ // The signature must be derived from the ambient credentials, proving the+ // SDK default provider chain (used for IAM roles) was applied.+ expect(searchParams.get("X-Amz-Credential")).toContain(ambientAccessKeyId);+ expect(searchParams.has("X-Amz-Signature")).toBe(true);+ });});vi.mock("../../../apps/api/src/database", () => ({ default: {} }));