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.

16.7 KB
Raw Blame
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,
    }),
  );
}