Skip to content

armgit / kaneo

Public Imported from GitHub
0

⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.

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.ts
index 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.mdx
index 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.mdx
index 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 uploads
Once storage is configured:
diff --git a/apps/docs/core/installation/storage-backends.mdx b/apps/docs/core/installation/storage-backends.mdx
index 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:
```json
diff --git a/tests/api/storage/s3.test.ts b/tests/api/storage/s3.test.ts
index 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: {} }));