⚡ 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
import { Readable } from "node:stream";
import {
CopyObjectCommand,
DeleteObjectCommand,
GetObjectCommand,
HeadBucketCommand,
type HeadObjectCommandOutput,
PutObjectCommand,
S3Client,
type S3ClientConfig,
} from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
import { createId } from "@paralleldrive/cuid2";
import { config } from "dotenv-mono";
import { describeStorageError } from "./describe-storage-error";
import {
headUploadedObject,
isMissingObjectError,
} from "./head-uploaded-object";
config();
const DEFAULT_MAX_IMAGE_UPLOAD_BYTES = 10 * 1024 * 1024;
const DEFAULT_PRESIGN_TTL_SECONDS = 300;
const allowedImageMimeTypes = new Set([
"image/apng",
"image/avif",
"image/gif",
"image/heic",
"image/heif",
"image/jpeg",
"image/jpg",
"image/png",
"image/webp",
]);
export function isImageContentType(contentType: string) {
return allowedImageMimeTypes.has(contentType.toLowerCase());
}
type UploadSurface = "description" | "comment";
type StorageConfig = {
endpoint: string;
region: string;
bucket: string;
accessKeyId: string;
secretAccessKey: string;
publicBaseUrl?: string;
keyPrefix: string;
forcePathStyle: boolean;
maxImageUploadBytes: number;
presignTtlSeconds: number;
};
type TaskImageUploadContext = {
workspaceId: string;
projectId: string;
taskId: string;
surface: UploadSurface;
filename: string;
contentType: string;
};
type TaskImageUploadUrl = {
key: string;
uploadUrl: string;
headers: Record<string, string>;
};
type ProjectBackgroundUploadContext = {
workspaceId: string;
projectId: string;
contentType: string;
size: number;
};
type ProjectBackgroundUploadUrl = {
key: string;
uploadUrl: string;
version: string;
headers: Record<string, string>;
};
type AssetObject = {
body: unknown;
contentType: string | undefined;
contentLength: number | undefined;
etag: string | undefined;
lastModified: Date | undefined;
};
let clientCache:
| {
cacheKey: string;
client: S3Client;
}
| undefined;
function env(name: string) {
return process.env[name]?.trim() || "";
}
export function parseBoolean(value: string | undefined, fallback: boolean) {
if (value === undefined || value.trim() === "") return fallback;
return value.trim().toLowerCase() === "true";
}
export function parsePositiveInt(value: string | undefined, fallback: number) {
const parsed = Number.parseInt(value?.trim() || "", 10);
if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
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) {
throw new Error(
"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",
bucket,
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,
DEFAULT_MAX_IMAGE_UPLOAD_BYTES,
),
presignTtlSeconds: parsePositiveInt(
process.env.S3_PRESIGN_TTL_SECONDS,
DEFAULT_PRESIGN_TTL_SECONDS,
),
};
}
function getMaxImageUploadBytes() {
return parsePositiveInt(
process.env.S3_MAX_IMAGE_UPLOAD_BYTES,
DEFAULT_MAX_IMAGE_UPLOAD_BYTES,
);
}
function getClient(config: StorageConfig) {
const cacheKey = JSON.stringify({
endpoint: config.endpoint,
region: config.region,
accessKeyId: config.accessKeyId,
bucket: config.bucket,
forcePathStyle: config.forcePathStyle,
});
if (clientCache?.cacheKey === cacheKey) {
return clientCache.client;
}
const clientConfig: S3ClientConfig = {
endpoint: config.endpoint,
region: config.region,
forcePathStyle: config.forcePathStyle,
// Avoid auto-injecting checksum params for presigned PUT URLs. Some
// S3-compatible providers (e.g. Garage/R2) reject mismatched hoisted CRCs.
requestChecksumCalculation: "WHEN_REQUIRED",
};
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;
}
export function sanitizePathSegment(value: string) {
return (
value
.toLowerCase()
.replace(/[^a-z0-9._-]+/g, "-")
.replace(/-{2,}/g, "-")
.replace(/^-+|-+$/g, "") || "file"
);
}
export function getFileExtension(filename: string) {
const normalized = filename.trim();
const extension = normalized.includes(".")
? normalized.split(".").pop() || ""
: "";
return sanitizePathSegment(extension).slice(0, 12);
}
export function buildObjectKeyPrefix(
context: Omit<TaskImageUploadContext, "filename" | "contentType">,
) {
const surfaceFolder =
context.surface === "comment" ? "comments" : "descriptions";
return [
"workspace",
sanitizePathSegment(context.workspaceId),
"project",
sanitizePathSegment(context.projectId),
"task",
sanitizePathSegment(context.taskId),
surfaceFolder,
].join("/");
}
export function buildObjectKey(context: TaskImageUploadContext) {
const extension = getFileExtension(context.filename);
const objectKeyPrefix = buildObjectKeyPrefix(context);
const timestamp = Date.now();
const randomId = createId();
const baseName = sanitizePathSegment(
context.filename.replace(/\.[^/.]+$/, "") || "image",
).slice(0, 64);
const fileName = extension
? `${baseName}-${timestamp}-${randomId}.${extension}`
: `${baseName}-${timestamp}-${randomId}`;
return `${objectKeyPrefix}/${fileName}`;
}
export function buildProjectBackgroundObjectKey(
context: Pick<ProjectBackgroundUploadContext, "workspaceId" | "projectId">,
) {
const objectKeyPrefix = buildProjectBackgroundObjectKeyPrefix(context);
const version = createId();
const fileName = `background-${version}`;
return {
rawKey: `${objectKeyPrefix}/${fileName}`,
version,
};
}
export function buildProjectBackgroundObjectKeyPrefix(
context: Pick<ProjectBackgroundUploadContext, "workspaceId" | "projectId">,
) {
return [
"workspace",
sanitizePathSegment(context.workspaceId),
"project",
sanitizePathSegment(context.projectId),
"backgrounds",
].join("/");
}
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,
) {
const maxImageUploadBytes = getMaxImageUploadBytes();
if (!contentType.trim()) {
throw new Error("A valid content type is required.");
}
if (!Number.isSafeInteger(size) || size <= 0) {
throw new Error("Upload size must be a positive safe integer.");
}
if (size > maxImageUploadBytes) {
throw new Error(
`Upload exceeds the maximum upload size of ${Math.floor(maxImageUploadBytes / (1024 * 1024))}MB.`,
);
}
}
export function validateProjectBackgroundUploadInput(
contentType: string,
size: number,
) {
const maxImageUploadBytes = getMaxImageUploadBytes();
if (!contentType.trim()) {
throw new Error("A valid content type is required.");
}
if (!isImageContentType(contentType)) {
throw new Error(
`Unsupported content type "${contentType}". Upload a supported image.`,
);
}
if (size <= 0) {
throw new Error("Upload size must be greater than zero.");
}
if (size > maxImageUploadBytes) {
throw new Error(
`Upload exceeds the maximum upload size of ${Math.floor(maxImageUploadBytes / (1024 * 1024))}MB.`,
);
}
}
export async function createTaskImageUploadUrl(
context: TaskImageUploadContext & { size: number },
): Promise<TaskImageUploadUrl> {
validateTaskAssetUploadInput(context.contentType, context.size);
const config = getStorageConfig();
const client = getClient(config);
const rawKey = buildObjectKey(context);
const key = applyKeyPrefix(config.keyPrefix, rawKey);
const command = new PutObjectCommand({
Bucket: config.bucket,
Key: key,
ContentType: context.contentType,
ContentLength: context.size,
});
const uploadUrl = await getSignedUrl(client, command, {
expiresIn: config.presignTtlSeconds,
signableHeaders: new Set(["content-length", "content-type"]),
});
return {
key,
uploadUrl,
headers: {
// The browser supplies Content-Length from the File body. It is signed,
// but must not be set by JS because it is a forbidden request header.
"Content-Type": context.contentType,
},
};
}
export async function createProjectBackgroundUploadUrl(
context: ProjectBackgroundUploadContext,
): Promise<ProjectBackgroundUploadUrl> {
validateProjectBackgroundUploadInput(context.contentType, context.size);
const config = getStorageConfig();
const client = getClient(config);
const { rawKey, version } = buildProjectBackgroundObjectKey(context);
const key = applyKeyPrefix(config.keyPrefix, rawKey);
const command = new PutObjectCommand({
Bucket: config.bucket,
Key: key,
ContentType: context.contentType,
ContentLength: context.size,
});
const uploadUrl = await getSignedUrl(client, command, {
expiresIn: config.presignTtlSeconds,
signableHeaders: new Set(["content-length", "content-type"]),
});
return {
key,
uploadUrl,
version,
headers: {
"Content-Type": context.contentType,
},
};
}
export class InvalidUploadedAssetError extends Error {}
/** Call only after checking the object's task/workspace key prefix. */
export async function verifyTaskAssetUpload(
key: string,
expected: { size: number; contentType: string },
) {
const config = getStorageConfig();
const client = getClient(config);
const abortSignal = AbortSignal.timeout(10_000);
let object: HeadObjectCommandOutput;
try {
object = await headUploadedObject(client, config.bucket, key, abortSignal);
} catch (error) {
if (isMissingObjectError(error)) {
throw new InvalidUploadedAssetError("Uploaded object was not found.");
}
// Provider errors may include endpoints, signed URLs or other secrets.
console.error(
"Unable to verify uploaded object:",
describeStorageError(error),
);
throw new Error("Unable to verify uploaded object.");
}
const size = object.ContentLength;
if (typeof size === "number" && size > config.maxImageUploadBytes) {
// Also remove oversized objects made with a still-valid older upload URL.
// Invalid client size claims never cause deletion of an in-limit object.
try {
await client.send(
new DeleteObjectCommand({ Bucket: config.bucket, Key: key }),
{ abortSignal },
);
} catch (error) {
console.error(
"Unable to remove oversized uploaded object:",
describeStorageError(error),
);
throw new Error("Unable to remove oversized uploaded object.");
}
throw new InvalidUploadedAssetError(
"Uploaded object exceeds the maximum upload size.",
);
}
if (
!Number.isSafeInteger(size) ||
!size ||
size !== expected.size ||
!object.ContentType ||
object.ContentType.toLowerCase() !== expected.contentType.toLowerCase()
) {
throw new InvalidUploadedAssetError(
"Uploaded object does not match the declared size and content type.",
);
}
return { size, contentType: object.ContentType };
}
export function assertStorageConfigured() {
return getStorageConfig();
}
export function isStorageConfigured() {
try {
getStorageConfig();
return true;
} catch {
return false;
}
}
/** Check that the bucket answers with the configured credentials. */
export async function headStorageBucket(abortSignal: AbortSignal) {
const config = getStorageConfig();
await getClient(config).send(
new HeadBucketCommand({ Bucket: config.bucket }),
{
abortSignal,
},
);
}
export function assertTaskImageKeyMatchesContext(
key: string,
context: Omit<TaskImageUploadContext, "filename" | "contentType">,
) {
const config = getStorageConfig();
const objectPrefix = buildObjectKeyPrefix(context);
const fullPrefix = `${applyKeyPrefix(config.keyPrefix, objectPrefix)}/`;
if (!key.startsWith(fullPrefix)) {
return false;
}
// The prefix alone is not enough: gateways that normalize paths would let
// a traversal suffix walk back out into another workspace's objects.
const suffix = key.slice(fullPrefix.length);
return /^[A-Za-z0-9._-]+$/.test(suffix) && !suffix.startsWith(".");
}
export function assertProjectBackgroundKeyMatchesContext(
key: string,
context: Pick<ProjectBackgroundUploadContext, "workspaceId" | "projectId"> & {
version: string;
},
) {
const config = getStorageConfig();
const objectPrefix = buildProjectBackgroundObjectKeyPrefix(context);
const fullPrefix = `${applyKeyPrefix(config.keyPrefix, objectPrefix)}/`;
if (!key.startsWith(fullPrefix)) {
return false;
}
// The prefix alone is not enough: gateways that normalize paths would let
// a traversal suffix walk back out into another workspace's objects.
if (!/^[A-Za-z0-9_-]+$/.test(context.version)) {
return false;
}
const suffix = key.slice(fullPrefix.length);
return suffix === `background-${context.version}`;
}
export async function getPrivateObject(key: string): Promise<AssetObject> {
const config = getStorageConfig();
const client = getClient(config);
const response = await client.send(
new GetObjectCommand({
Bucket: config.bucket,
Key: key,
}),
);
if (!response.Body) {
throw new Error("Storage object body is missing.");
}
const body =
"transformToWebStream" in response.Body
? response.Body.transformToWebStream()
: Readable.toWeb(response.Body as Readable);
return {
body,
contentType: response.ContentType,
contentLength: response.ContentLength,
etag: response.ETag,
lastModified: response.LastModified,
};
}
export async function copyTaskAssetObject({
sourceKey,
destination,
}: {
sourceKey: string;
destination: TaskImageUploadContext;
}): Promise<string> {
const config = getStorageConfig();
const client = getClient(config);
const key = applyKeyPrefix(config.keyPrefix, buildObjectKey(destination));
await client.send(
new CopyObjectCommand({
Bucket: config.bucket,
CopySource: [config.bucket, ...sourceKey.split("/")]
.map(encodeURIComponent)
.join("/"),
Key: key,
}),
);
return key;
}
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,
}),
);
}