feat(sdk-utils): add Attachment shape and validateAttachments helper

Author: Ripwords

packages/sdk-utils/src/attachments/index.ts

@@ -0,0 +1,2 @@
+export * from "./types"
+export * from "./validate"

packages/sdk-utils/src/attachments/types.ts

@@ -0,0 +1,56 @@
+/**
+ * Transport shape for user-supplied additional attachments. Lives in
+ * sdk-utils because both packages/ui and packages/expo build this same
+ * shape from their respective file pickers and hand it to their intake
+ * clients. The dashboard's AttachmentDTO is a separate, render-side shape.
+ */
+export interface Attachment {
+  /** Local UUID — used as React/Preact key and for picker dedupe. */
+  id: string
+  /** Raw file bytes. In Expo this is wrapped via fetch(uri).blob() before send. */
+  blob: Blob
+  /** Original filename, sanitized client-side. Server is the source of truth. */
+  filename: string
+  /** MIME type. Falls back to "application/octet-stream" if the picker doesn't supply one. */
+  mime: string
+  /** Bytes. */
+  size: number
+  /** Convenience: mime.startsWith("image/"). Set at construction. */
+  isImage: boolean
+  /** Object URL for thumbnail preview. Caller manages revocation. */
+  previewUrl?: string
+}
+
+export interface AttachmentLimits {
+  maxCount: number
+  maxFileBytes: number
+  maxTotalBytes: number
+}
+
+export const DEFAULT_ATTACHMENT_LIMITS: AttachmentLimits = {
+  maxCount: 5,
+  maxFileBytes: 10 * 1024 * 1024,
+  maxTotalBytes: 25 * 1024 * 1024,
+}
+
+/**
+ * Client-side mime denylist. Mirrors (but does not replace) the
+ * server-side denylist. Server is authoritative.
+ */
+export const DENIED_MIME_PREFIXES: readonly string[] = [
+  "application/x-msdownload",
+  "application/x-sh",
+  "text/x-shellscript",
+  "application/x-executable",
+] as const
+
+export const DENIED_FILENAME_EXTENSIONS: readonly string[] = [
+  ".exe",
+  ".bat",
+  ".cmd",
+  ".com",
+  ".scr",
+  ".sh",
+  ".ps1",
+  ".vbs",
+] as const

packages/sdk-utils/src/attachments/validate.test.ts

@@ -0,0 +1,97 @@
+import { expect, test } from "bun:test"
+import { DEFAULT_ATTACHMENT_LIMITS, validateAttachments, type Attachment } from "./index"
+
+function makeFile(name: string, bytes: number, type = "image/png"): File {
+  const blob = new Blob([new Uint8Array(bytes)], { type })
+  return new File([blob], name, { type })
+}
+
+function makeExisting(size: number, mime = "image/png"): Attachment {
+  return {
+    id: "x",
+    blob: new Blob([new Uint8Array(size)], { type: mime }),
+    filename: "existing.png",
+    mime,
+    size,
+    isImage: mime.startsWith("image/"),
+  }
+}
+
+test("accepts a single small image", () => {
+  const result = validateAttachments([makeFile("a.png", 100)], [], DEFAULT_ATTACHMENT_LIMITS)
+  expect(result.accepted).toHaveLength(1)
+  expect(result.rejected).toHaveLength(0)
+  expect(result.accepted[0]?.isImage).toBe(true)
+})
+
+test("rejects a file over per-file cap", () => {
+  const big = makeFile("big.png", DEFAULT_ATTACHMENT_LIMITS.maxFileBytes + 1)
+  const result = validateAttachments([big], [], DEFAULT_ATTACHMENT_LIMITS)
+  expect(result.accepted).toHaveLength(0)
+  expect(result.rejected).toEqual([{ filename: "big.png", reason: "too-large" }])
+})
+
+test("rejects when count would exceed maxCount", () => {
+  const existing = Array.from({ length: 5 }, () => makeExisting(10))
+  const result = validateAttachments([makeFile("new.png", 10)], existing, DEFAULT_ATTACHMENT_LIMITS)
+  expect(result.accepted).toHaveLength(0)
+  expect(result.rejected).toEqual([{ filename: "new.png", reason: "count-exceeded" }])
+})
+
+test("rejects when total bytes would exceed maxTotalBytes", () => {
+  const existing = [makeExisting(20 * 1024 * 1024)]
+  const result = validateAttachments(
+    [makeFile("a.png", 10 * 1024 * 1024)],
+    existing,
+    DEFAULT_ATTACHMENT_LIMITS,
+  )
+  expect(result.accepted).toHaveLength(0)
+  expect(result.rejected).toEqual([{ filename: "a.png", reason: "total-exceeded" }])
+})
+
+test("rejects denylisted mime", () => {
+  const exe = makeFile("evil.exe", 100, "application/x-msdownload")
+  const result = validateAttachments([exe], [], DEFAULT_ATTACHMENT_LIMITS)
+  expect(result.rejected).toEqual([{ filename: "evil.exe", reason: "denied-mime" }])
+})
+
+test("rejects denylisted extension even if mime is benign", () => {
+  const fake = makeFile("script.sh", 100, "text/plain")
+  const result = validateAttachments([fake], [], DEFAULT_ATTACHMENT_LIMITS)
+  expect(result.rejected).toEqual([{ filename: "script.sh", reason: "denied-mime" }])
+})
+
+test("accumulates errors instead of bailing on first", () => {
+  const ok = makeFile("ok.png", 100)
+  const big = makeFile("big.png", DEFAULT_ATTACHMENT_LIMITS.maxFileBytes + 1)
+  const evil = makeFile("evil.exe", 100, "application/x-msdownload")
+  const result = validateAttachments([ok, big, evil], [], DEFAULT_ATTACHMENT_LIMITS)
+  expect(result.accepted).toHaveLength(1)
+  expect(result.accepted[0]?.filename).toBe("ok.png")
+  expect(result.rejected).toEqual([
+    { filename: "big.png", reason: "too-large" },
+    { filename: "evil.exe", reason: "denied-mime" },
+  ])
+})
+
+test("count check considers files added earlier in the same batch", () => {
+  const existing = [makeExisting(10), makeExisting(10), makeExisting(10), makeExisting(10)]
+  const a = makeFile("a.png", 10)
+  const b = makeFile("b.png", 10)
+  const result = validateAttachments([a, b], existing, DEFAULT_ATTACHMENT_LIMITS)
+  expect(result.accepted).toHaveLength(1)
+  expect(result.rejected).toEqual([{ filename: "b.png", reason: "count-exceeded" }])
+})
+
+test("zero-byte file is rejected as unreadable", () => {
+  const empty = makeFile("empty.png", 0)
+  const result = validateAttachments([empty], [], DEFAULT_ATTACHMENT_LIMITS)
+  expect(result.rejected).toEqual([{ filename: "empty.png", reason: "unreadable" }])
+})
+
+test("missing mime defaults to application/octet-stream", () => {
+  const blob = new Blob([new Uint8Array(100)])
+  const file = new File([blob], "data.bin")
+  const result = validateAttachments([file], [], DEFAULT_ATTACHMENT_LIMITS)
+  expect(result.accepted[0]?.mime).toBe("application/octet-stream")
+})

packages/sdk-utils/src/attachments/validate.ts

@@ -0,0 +1,85 @@
+import {
+  DENIED_FILENAME_EXTENSIONS,
+  DENIED_MIME_PREFIXES,
+  type Attachment,
+  type AttachmentLimits,
+} from "./types"
+
+export type ValidationFailureReason =
+  | "too-large"
+  | "denied-mime"
+  | "count-exceeded"
+  | "total-exceeded"
+  | "unreadable"
+
+export interface ValidationFailure {
+  filename: string
+  reason: ValidationFailureReason
+}
+
+export interface ValidationResult {
+  accepted: Attachment[]
+  rejected: ValidationFailure[]
+}
+
+function isDenied(filename: string, mime: string): boolean {
+  if (DENIED_MIME_PREFIXES.some((p) => mime === p || mime.startsWith(`${p}/`))) return true
+  const lower = filename.toLowerCase()
+  return DENIED_FILENAME_EXTENSIONS.some((ext) => lower.endsWith(ext))
+}
+
+function newId(): string {
+  if (typeof crypto !== "undefined" && "randomUUID" in crypto) return crypto.randomUUID()
+  return `${Date.now()}-${Math.random().toString(36).slice(2)}`
+}
+
+export function validateAttachments(
+  candidates: File[],
+  existing: Attachment[],
+  limits: AttachmentLimits,
+): ValidationResult {
+  const accepted: Attachment[] = []
+  const rejected: ValidationFailure[] = []
+
+  let runningCount = existing.length
+  let runningTotal = existing.reduce((n, a) => n + a.size, 0)
+
+  for (const file of candidates) {
+    const filename = file.name
+    const mime = file.type || "application/octet-stream"
+
+    if (file.size === 0) {
+      rejected.push({ filename, reason: "unreadable" })
+      continue
+    }
+    if (isDenied(filename, mime)) {
+      rejected.push({ filename, reason: "denied-mime" })
+      continue
+    }
+    if (file.size > limits.maxFileBytes) {
+      rejected.push({ filename, reason: "too-large" })
+      continue
+    }
+    if (runningCount + 1 > limits.maxCount) {
+      rejected.push({ filename, reason: "count-exceeded" })
+      continue
+    }
+    if (runningTotal + file.size > limits.maxTotalBytes) {
+      rejected.push({ filename, reason: "total-exceeded" })
+      continue
+    }
+
+    accepted.push({
+      id: newId(),
+      blob: file,
+      filename,
+      mime,
+      size: file.size,
+      isImage: mime.startsWith("image/"),
+    })
+    runningCount += 1
+    runningTotal += file.size
+  }
+
+  return { accepted, rejected }
+}

packages/sdk-utils/src/index.ts

@@ -3,3 +3,4 @@ export * from "./redact"
 export * from "./breadcrumbs"
 export * from "./annotation"
 export * from "./theme"
+export * from "./attachments"