@superblocksteam/shared 0.9613.2 → 0.9614.1

package/src/utils/attachment-validation.test.ts

@@ -0,0 +1,226 @@
+import { PDFDocument } from 'pdf-lib';
+import { describe, expect, test } from 'vitest';
+
+import {
+  AttachmentValidationError,
+  MAX_ARCHIVE_ATTACHMENT_BYTES,
+  MAX_IMAGE_ATTACHMENT_BYTES,
+  MAX_PDF_ATTACHMENT_BYTES,
+  MAX_TEXT_ATTACHMENT_BYTES,
+  assertAttachmentSize,
+  getAttachmentLimitsHelp,
+  getAttachmentUploadPolicy,
+  getAttachmentUploadLimit,
+  validateAttachmentBytes
+} from './attachment-validation.js';
+
+const encoder = new TextEncoder();
+
+async function pdfWithPages(pageCount: number, useObjectStreams = true): Promise<Uint8Array> {
+  const document = await PDFDocument.create();
+  for (let index = 0; index < pageCount; index += 1) document.addPage();
+  return document.save({ useObjectStreams });
+}
+
+function expectReason(action: () => unknown, reason: AttachmentValidationError['reason']): void {
+  try {
+    action();
+    throw new Error('expected validation to fail');
+  } catch (error) {
+    expect(error).toBeInstanceOf(AttachmentValidationError);
+    if (error instanceof AttachmentValidationError) {
+      expect(error.code).toBe('attachment_invalid');
+      expect(error.reason).toBe(reason);
+    }
+  }
+}
+
+async function expectAsyncReason(action: () => Promise<unknown>, reason: AttachmentValidationError['reason']): Promise<void> {
+  try {
+    await action();
+    throw new Error('expected validation to fail');
+  } catch (error) {
+    expect(error).toBeInstanceOf(AttachmentValidationError);
+    if (error instanceof AttachmentValidationError) expect(error.reason).toBe(reason);
+  }
+}
+
+describe('attachment size policy', () => {
+  test.each([
+    ['spec.pdf', 'application/pdf', MAX_PDF_ATTACHMENT_BYTES],
+    ['photo.jpg', 'image/jpeg', MAX_IMAGE_ATTACHMENT_BYTES],
+    ['notes.md', 'text/markdown', MAX_TEXT_ATTACHMENT_BYTES],
+    ['bundle.zip', 'application/zip', MAX_ARCHIVE_ATTACHMENT_BYTES],
+    ['bundle.tgz', 'application/octet-stream', MAX_ARCHIVE_ATTACHMENT_BYTES],
+    ['orders_prod.dump', 'application/octet-stream', MAX_ARCHIVE_ATTACHMENT_BYTES]
+  ])('allows the exact limit and rejects one byte more for %s', (fileName, mimeType, limit) => {
+    expect(getAttachmentUploadLimit({ fileName, mimeType })).toBe(limit);
+    expect(() => assertAttachmentSize({ fileName, mimeType, sizeBytes: limit })).not.toThrow();
+    expectReason(() => assertAttachmentSize({ fileName, mimeType, sizeBytes: limit + 1 }), 'too_large');
+  });
+
+  test.each([
+    ['spec.pdf', 'application/pdf', 4_500_001, 'This PDF is too large. The limit is 4.5 MB. Split it or attach only the pages you need.'],
+    [
+      'photo.jpg',
+      'IMAGE/JPEG; charset=binary',
+      3_750_001,
+      'This image is too large. The limit is 3.75 MB after conversion. Resize it or choose a smaller image.'
+    ],
+    ['notes.md', '', 5_242_881, 'This text/code file is too large. The limit is 5 MiB. Split it or attach only the content you need.'],
+    [
+      'bundle.zip',
+      'application/zip',
+      52_428_801,
+      'This archive is too large. The limit is 50 MiB. Remove files from it or split it into smaller archives.'
+    ]
+  ])('returns only the applicable size error for %s', (fileName, mimeType, sizeBytes, message) => {
+    expect(() => assertAttachmentSize({ fileName, mimeType, sizeBytes })).toThrow(message);
+    expect(getAttachmentUploadPolicy({ fileName, mimeType }).maxBytes).toBe(sizeBytes - 1);
+  });
+
+  test('uses the same policy for MIME types and extension fallback without trusting a conflicting extension', () => {
+    expect(getAttachmentUploadPolicy({ fileName: 'SPEC.PDF' })).toEqual(getAttachmentUploadPolicy({ mimeType: 'application/pdf' }));
+    expect(getAttachmentUploadPolicy({ fileName: 'spec.pdf', mimeType: 'image/png' }).maxBytes).toBe(3_750_000);
+    expect(getAttachmentLimitsHelp(false)).toBe('PDFs: 4.5 MB each, 100 pages total. Images: 3.75 MB after conversion. Text/code: 5 MiB.');
+    expect(getAttachmentLimitsHelp(true)).toBe(
+      'PDFs: 4.5 MB each, 100 pages total. Images: 3.75 MB after conversion. Text/code: 5 MiB. Supported archives and .dump files: 50 MiB.'
+    );
+  });
+
+  test('rejects unsupported and Office types', () => {
+    expectReason(() => getAttachmentUploadLimit({ fileName: 'logo.svg', mimeType: 'image/svg+xml' }), 'unsupported_type');
+    expectReason(() => getAttachmentUploadLimit({ fileName: 'report.docx', mimeType: 'text/plain' }), 'unsupported_type');
+    expectReason(() => getAttachmentUploadLimit({ fileName: 'notes.txt', mimeType: 'application/octet-stream' }), 'unsupported_type');
+  });
+});
+
+describe('attachment content validation', () => {
+  test.each([
+    ['image/jpeg', new Uint8Array([0xff, 0xd8, 0xff])],
+    ['image/png', new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])],
+    ['image/gif', encoder.encode('GIF89a')],
+    ['image/webp', encoder.encode('RIFF0000WEBP')]
+  ])('accepts valid %s magic', async (mimeType, bytes) => {
+    await expect(validateAttachmentBytes({ mimeType, bytes })).resolves.toEqual({ pdfPages: 0 });
+  });
+
+  test.each([
+    ['bundle.zip', 'application/zip', new Uint8Array([0x50, 0x4b, 0x05, 0x06])],
+    ['bundle.gz', 'application/gzip', new Uint8Array([0x1f, 0x8b])],
+    ['bundle.tgz', 'application/x-tgz', new Uint8Array([0x1f, 0x8b])]
+  ])('accepts valid archive magic for %s', async (fileName, mimeType, bytes) => {
+    await expect(validateAttachmentBytes({ fileName, mimeType, bytes })).resolves.toEqual({ pdfPages: 0 });
+  });
+
+  test('accepts postgres custom-format dump magic for .dump files', async () => {
+    const bytes = encoder.encode('PGDMP\x01\x0e\x00');
+    await expect(validateAttachmentBytes({ fileName: 'orders_prod.dump', mimeType: 'application/octet-stream', bytes })).resolves.toEqual({
+      pdfPages: 0
+    });
+    await expect(validateAttachmentBytes({ fileName: 'orders_prod.dump', mimeType: '', bytes })).resolves.toEqual({ pdfPages: 0 });
+    await expect(validateAttachmentBytes({ fileName: 'orders_prod.dump', mimeType: 'text/plain', bytes })).resolves.toEqual({
+      pdfPages: 0
+    });
+    await expectAsyncReason(
+      () =>
+        validateAttachmentBytes({
+          fileName: 'orders_prod.dump',
+          mimeType: 'application/octet-stream',
+          bytes: encoder.encode('not a dump')
+        }),
+      'invalid_content'
+    );
+  });
+
+  test('accepts dump mime type without a .dump filename', async () => {
+    const bytes = encoder.encode('PGDMP\x01\x0e\x00');
+    await expect(validateAttachmentBytes({ fileName: 'orders', mimeType: 'application/x-postgresql-dump', bytes })).resolves.toEqual({
+      pdfPages: 0
+    });
+  });
+
+  test.each([
+    ['bundle.tgz', new Uint8Array([0x1f, 0x8b])],
+    ['bundle.gzip', new Uint8Array([0x1f, 0x8b])],
+    ['bundle.tar.gz', new Uint8Array([0x1f, 0x8b])],
+    ['bundle.zip', new Uint8Array([0x50, 0x4b, 0x05, 0x06])]
+  ])('accepts archive filename fallback for generic MIME on %s', async (fileName, bytes) => {
+    await expect(validateAttachmentBytes({ fileName, mimeType: 'application/octet-stream', bytes })).resolves.toEqual({ pdfPages: 0 });
+    await expectAsyncReason(
+      () => validateAttachmentBytes({ fileName, mimeType: 'application/octet-stream', bytes: encoder.encode('not an archive') }),
+      'invalid_content'
+    );
+  });
+
+  test('does not use archive filename fallback for an incompatible declared MIME type', async () => {
+    await expectAsyncReason(
+      () => validateAttachmentBytes({ fileName: 'bundle.tgz', mimeType: 'text/plain', bytes: new Uint8Array([0x1f, 0x8b]) }),
+      'invalid_content'
+    );
+  });
+
+  test('accepts UTF-8 text and rejects binary or disguised content', async () => {
+    await expect(
+      validateAttachmentBytes({ fileName: 'notes.md', mimeType: 'text/markdown', bytes: encoder.encode('hello') })
+    ).resolves.toEqual({
+      pdfPages: 0
+    });
+    await expectAsyncReason(
+      () => validateAttachmentBytes({ fileName: 'notes.txt', mimeType: 'text/plain', bytes: new Uint8Array([0xff, 0x00]) }),
+      'invalid_content'
+    );
+    await expectAsyncReason(
+      () => validateAttachmentBytes({ fileName: 'notes.txt', mimeType: 'text/plain', bytes: new Uint8Array([0x50, 0x4b, 0x03, 0x04]) }),
+      'invalid_content'
+    );
+  });
+
+  test('rejects renamed random bytes for images and archives', async () => {
+    await expectAsyncReason(() => validateAttachmentBytes({ mimeType: 'image/png', bytes: encoder.encode('not png') }), 'invalid_content');
+    await expectAsyncReason(
+      () => validateAttachmentBytes({ fileName: 'bundle.zip', mimeType: 'application/zip', bytes: encoder.encode('not zip') }),
+      'invalid_content'
+    );
+  });
+});
+
+describe('PDF validation', () => {
+  test('counts 100 pages in a compressed object stream PDF', async () => {
+    const bytes = await pdfWithPages(100);
+    await expect(validateAttachmentBytes({ fileName: 'spec.pdf', mimeType: 'application/pdf', bytes })).resolves.toEqual({ pdfPages: 100 });
+  });
+
+  test('rejects 101 pages', async () => {
+    const bytes = await pdfWithPages(101, false);
+    await expectAsyncReason(() => validateAttachmentBytes({ mimeType: 'application/pdf', bytes }), 'too_many_pdf_pages');
+  });
+
+  test('rejects malformed, empty, and encrypted PDFs', async () => {
+    await expectAsyncReason(
+      () => validateAttachmentBytes({ mimeType: 'application/pdf', bytes: encoder.encode('%PDF-broken') }),
+      'invalid_content'
+    );
+    await expectAsyncReason(() => validateAttachmentBytes({ mimeType: 'application/pdf', bytes: new Uint8Array() }), 'invalid_content');
+
+    const encrypted = await PDFDocument.create();
+    encrypted.addPage();
+    encrypted.context.trailerInfo.Encrypt = encrypted.context.register(encrypted.context.obj({ Filter: 'Standard', V: 1 }));
+    const encryptedBytes = await encrypted.save();
+    await expectAsyncReason(() => validateAttachmentBytes({ mimeType: 'application/pdf', bytes: encryptedBytes }), 'invalid_content');
+  });
+
+  test('rejects a cyclic page tree without recursive traversal', async () => {
+    const cyclic = await PDFDocument.create();
+    cyclic.addPage();
+    const pages = cyclic.catalog.Pages();
+    const pagesReference = cyclic.context.getObjectRef(pages);
+    if (!pagesReference) throw new Error('expected page tree reference');
+    pages.Kids().push(pagesReference);
+
+    await expectAsyncReason(
+      async () => validateAttachmentBytes({ mimeType: 'application/pdf', bytes: await cyclic.save() }),
+      'invalid_content'
+    );
+  });
+});

package/src/utils/attachment-validation.ts

@@ -0,0 +1,269 @@
+import { PDFDocument, PDFPageLeaf, PDFPageTree } from 'pdf-lib';
+
+import { detectAttachmentArchiveType, isDumpAttachment } from './attachment-delivery.js';
+import { getTextAttachmentType, isOfficeXml } from './attachment-upload.js';
+
+const ATTACHMENT_UPLOAD_POLICIES = {
+  archive: {
+    maxBytes: 50 * 1024 * 1024,
+    sizeLabel: '50 MiB',
+    label: 'archive',
+    advice: 'Remove files from it or split it into smaller archives.',
+    invalidContentMessage: 'This archive could not be read. Re-create it as a ZIP, GZIP, or TGZ archive and try again.'
+  },
+  dump: {
+    maxBytes: 50 * 1024 * 1024,
+    sizeLabel: '50 MiB',
+    label: 'database dump',
+    advice: 'Produce a smaller dump or split the data before attaching it.',
+    invalidContentMessage:
+      'This database dump could not be read. Re-create it with pg_dump custom format (-Fc) so the file starts with PGDMP, then try again.'
+  },
+  image: {
+    maxBytes: 3_750_000,
+    sizeLabel: '3.75 MB after conversion',
+    label: 'image',
+    advice: 'Resize it or choose a smaller image.',
+    invalidContentMessage: 'This image could not be read. Re-export it as a JPEG, PNG, GIF, or WebP image and try again.'
+  },
+  pdf: {
+    maxBytes: 4_500_000,
+    sizeLabel: '4.5 MB',
+    label: 'PDF',
+    advice: 'Split it or attach only the pages you need.',
+    invalidContentMessage: 'This PDF could not be read. Re-export it without encryption or password protection and try again.'
+  },
+  text: {
+    maxBytes: 5 * 1024 * 1024,
+    sizeLabel: '5 MiB',
+    label: 'text/code file',
+    advice: 'Split it or attach only the content you need.',
+    invalidContentMessage: 'This text/code file could not be read. Save it as UTF-8 text and try again.'
+  }
+};
+
+export const MAX_PDF_ATTACHMENT_BYTES = ATTACHMENT_UPLOAD_POLICIES.pdf.maxBytes;
+export const MAX_IMAGE_ATTACHMENT_BYTES = ATTACHMENT_UPLOAD_POLICIES.image.maxBytes;
+export const MAX_TEXT_ATTACHMENT_BYTES = ATTACHMENT_UPLOAD_POLICIES.text.maxBytes;
+export const MAX_ARCHIVE_ATTACHMENT_BYTES = ATTACHMENT_UPLOAD_POLICIES.archive.maxBytes;
+export const MAX_PDF_ATTACHMENT_PAGES = 100;
+
+export function getAttachmentLimitsHelp(archiveAttachmentsEnabled: boolean): string {
+  const { archive, image, pdf, text } = ATTACHMENT_UPLOAD_POLICIES;
+  return `PDFs: ${pdf.sizeLabel} each, ${MAX_PDF_ATTACHMENT_PAGES} pages total. Images: ${image.sizeLabel}. Text/code: ${text.sizeLabel}.${archiveAttachmentsEnabled ? ` Supported archives and .dump files: ${archive.sizeLabel}.` : ''}`;
+}
+
+export type AttachmentValidationReason = 'invalid_content' | 'too_large' | 'too_many_pdf_pages' | 'unsupported_type';
+
+const VALIDATION_MESSAGES: Record<AttachmentValidationReason, string> = {
+  invalid_content: 'This file could not be read. Re-export it and try again.',
+  too_large: 'This upload is too large. Reduce its size and try again.',
+  too_many_pdf_pages: `Clark supports up to ${MAX_PDF_ATTACHMENT_PAGES} PDF pages per request. Remove another PDF or attach fewer pages.`,
+  unsupported_type:
+    'This file type is not supported. Use an image, PDF, text/code file, a supported ZIP, GZIP, or TGZ archive, or a Postgres .dump file.'
+};
+
+export class AttachmentValidationError extends Error {
+  readonly code = 'attachment_invalid';
+
+  constructor(
+    readonly reason: AttachmentValidationReason,
+    input?: AttachmentTypeInput
+  ) {
+    const policy = input && (reason === 'too_large' || reason === 'invalid_content') ? getAttachmentUploadPolicy(input) : undefined;
+    super(policy ? (reason === 'too_large' ? policy.tooLargeMessage : policy.invalidContentMessage) : VALIDATION_MESSAGES[reason]);
+    this.name = 'AttachmentValidationError';
+  }
+}
+
+export type AttachmentTypeInput = {
+  fileName?: string;
+  mimeType?: string | null;
+};
+
+type AttachmentKind = 'archive' | 'dump' | 'gif' | 'jpeg' | 'pdf' | 'png' | 'text' | 'webp';
+const MAX_PDF_PAGE_TREE_NODES = 1_000;
+const POSTGRES_DUMP_MAGIC = [0x50, 0x47, 0x44, 0x4d, 0x50] as const;
+
+function normalizedMimeType(mimeType?: string | null): string {
+  return mimeType?.trim().toLowerCase().split(';', 1)[0] ?? '';
+}
+
+function normalizedFileName(fileName?: string): string {
+  return fileName?.trim().toLowerCase() ?? '';
+}
+
+function getAttachmentKind(input: AttachmentTypeInput): AttachmentKind {
+  if (isOfficeXml(input)) {
+    throw new AttachmentValidationError('unsupported_type');
+  }
+
+  const mimeType = normalizedMimeType(input.mimeType);
+  const fileName = normalizedFileName(input.fileName);
+  if (mimeType) {
+    if (mimeType === 'application/octet-stream' && detectAttachmentArchiveType({ fileName })) return 'archive';
+    if (isDumpAttachment(input)) return 'dump';
+    if (mimeType === 'application/pdf') return 'pdf';
+    if (mimeType === 'image/jpeg' || mimeType === 'image/jpg') return 'jpeg';
+    if (mimeType === 'image/png') return 'png';
+    if (mimeType === 'image/gif') return 'gif';
+    if (mimeType === 'image/webp') return 'webp';
+    if (detectAttachmentArchiveType({ mimeType })) return 'archive';
+    if (mimeType.startsWith('image/')) throw new AttachmentValidationError('unsupported_type');
+    if (getTextAttachmentType({ mimeType })) return 'text';
+    throw new AttachmentValidationError('unsupported_type');
+  }
+
+  if (detectAttachmentArchiveType({ fileName })) return 'archive';
+  if (isDumpAttachment(input)) return 'dump';
+  if (fileName.endsWith('.pdf')) return 'pdf';
+  if (fileName.endsWith('.jpg') || fileName.endsWith('.jpeg')) return 'jpeg';
+  if (fileName.endsWith('.png')) return 'png';
+  if (fileName.endsWith('.gif')) return 'gif';
+  if (fileName.endsWith('.webp')) return 'webp';
+  if (getTextAttachmentType({ fileName })) return 'text';
+  throw new AttachmentValidationError('unsupported_type');
+}
+
+/** Resolve the validated upload policy by MIME, falling back to the extension only when MIME is absent or generic. */
+export function getAttachmentUploadPolicy(input: AttachmentTypeInput) {
+  const kind = getAttachmentKind(input);
+  const policy = ATTACHMENT_UPLOAD_POLICIES[kind === 'archive' || kind === 'dump' || kind === 'pdf' || kind === 'text' ? kind : 'image'];
+  return {
+    ...policy,
+    tooLargeMessage: `This ${policy.label} is too large. The limit is ${policy.sizeLabel}. ${policy.advice}`
+  };
+}
+
+export function getAttachmentUploadLimit(input: AttachmentTypeInput): number {
+  return getAttachmentUploadPolicy(input).maxBytes;
+}
+
+export function assertAttachmentSize(input: AttachmentTypeInput & { sizeBytes: number }): void {
+  if (!Number.isSafeInteger(input.sizeBytes) || input.sizeBytes < 0) {
+    throw new AttachmentValidationError('invalid_content', input);
+  }
+  if (input.sizeBytes > getAttachmentUploadLimit(input)) {
+    throw new AttachmentValidationError('too_large', input);
+  }
+}
+
+export function assertAttachmentPdfPages(pages: number): void {
+  if (pages > MAX_PDF_ATTACHMENT_PAGES) throw new AttachmentValidationError('too_many_pdf_pages');
+}
+
+function startsWith(bytes: Uint8Array, signature: readonly number[]): boolean {
+  return signature.every((value, index) => bytes[index] === value);
+}
+
+function isZip(bytes: Uint8Array): boolean {
+  return (
+    startsWith(bytes, [0x50, 0x4b, 0x03, 0x04]) ||
+    startsWith(bytes, [0x50, 0x4b, 0x05, 0x06]) ||
+    startsWith(bytes, [0x50, 0x4b, 0x07, 0x08])
+  );
+}
+
+function validateImage(kind: AttachmentKind, bytes: Uint8Array): void {
+  const valid =
+    (kind === 'jpeg' && startsWith(bytes, [0xff, 0xd8, 0xff])) ||
+    (kind === 'png' && startsWith(bytes, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) ||
+    (kind === 'gif' &&
+      (new TextDecoder().decode(bytes.subarray(0, 6)) === 'GIF87a' || new TextDecoder().decode(bytes.subarray(0, 6)) === 'GIF89a')) ||
+    (kind === 'webp' &&
+      new TextDecoder().decode(bytes.subarray(0, 4)) === 'RIFF' &&
+      new TextDecoder().decode(bytes.subarray(8, 12)) === 'WEBP');
+  if (!valid) throw new AttachmentValidationError('invalid_content');
+}
+
+function validateArchive(input: AttachmentTypeInput, bytes: Uint8Array): void {
+  const archiveType = detectAttachmentArchiveType(input);
+  const valid = archiveType === 'zip' ? isZip(bytes) : startsWith(bytes, [0x1f, 0x8b]);
+  if (!valid) throw new AttachmentValidationError('invalid_content');
+}
+
+function validateDump(bytes: Uint8Array): void {
+  if (!startsWith(bytes, POSTGRES_DUMP_MAGIC)) {
+    throw new AttachmentValidationError('invalid_content');
+  }
+}
+
+function validateText(bytes: Uint8Array): void {
+  if (
+    bytes.includes(0) ||
+    startsWith(bytes, [0x25, 0x50, 0x44, 0x46, 0x2d]) ||
+    startsWith(bytes, [0xff, 0xd8, 0xff]) ||
+    startsWith(bytes, [0x89, 0x50, 0x4e, 0x47]) ||
+    new TextDecoder().decode(bytes.subarray(0, 3)) === 'GIF' ||
+    (new TextDecoder().decode(bytes.subarray(0, 4)) === 'RIFF' && new TextDecoder().decode(bytes.subarray(8, 12)) === 'WEBP') ||
+    isZip(bytes) ||
+    startsWith(bytes, [0x1f, 0x8b])
+  ) {
+    throw new AttachmentValidationError('invalid_content');
+  }
+  try {
+    new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  } catch {
+    throw new AttachmentValidationError('invalid_content');
+  }
+}
+
+function countPdfPages(document: PDFDocument): number {
+  const pending: (PDFPageLeaf | PDFPageTree)[] = [document.catalog.Pages()];
+  const visited = new Set<PDFPageTree>();
+  let pages = 0;
+
+  while (pending.length > 0) {
+    const node = pending.pop();
+    if (node instanceof PDFPageLeaf) {
+      pages += 1;
+      assertAttachmentPdfPages(pages);
+      continue;
+    }
+    if (!(node instanceof PDFPageTree) || visited.has(node)) throw new AttachmentValidationError('invalid_content');
+    visited.add(node);
+    if (visited.size > MAX_PDF_PAGE_TREE_NODES) throw new AttachmentValidationError('invalid_content');
+    const kids = node.Kids();
+    for (let index = 0; index < kids.size(); index += 1) {
+      const kid = kids.lookup(index);
+      if (!(kid instanceof PDFPageLeaf) && !(kid instanceof PDFPageTree)) {
+        throw new AttachmentValidationError('invalid_content');
+      }
+      pending.push(kid);
+    }
+  }
+
+  if (pages === 0) throw new AttachmentValidationError('invalid_content');
+  return pages;
+}
+
+async function validatePdf(bytes: Uint8Array): Promise<number> {
+  // Match the existing upload sniff: tolerate a BOM or producer prefix.
+  if (!new TextDecoder('latin1').decode(bytes.subarray(0, 1028)).includes('%PDF-')) {
+    throw new AttachmentValidationError('invalid_content');
+  }
+  try {
+    const document = await PDFDocument.load(bytes, { throwOnInvalidObject: true, updateMetadata: false });
+    return countPdfPages(document);
+  } catch (error) {
+    if (error instanceof AttachmentValidationError) throw error;
+    throw new AttachmentValidationError('invalid_content');
+  }
+}
+
+export async function validateAttachmentBytes(input: AttachmentTypeInput & { bytes: Uint8Array }): Promise<{ pdfPages: number }> {
+  assertAttachmentSize({ ...input, sizeBytes: input.bytes.byteLength });
+  const kind = getAttachmentKind(input);
+
+  try {
+    if (kind === 'pdf') return { pdfPages: await validatePdf(input.bytes) };
+    if (kind === 'text') validateText(input.bytes);
+    else if (kind === 'archive') validateArchive(input, input.bytes);
+    else if (kind === 'dump') validateDump(input.bytes);
+    else validateImage(kind, input.bytes);
+    return { pdfPages: 0 };
+  } catch (error) {
+    if (error instanceof AttachmentValidationError) throw new AttachmentValidationError(error.reason, input);
+    throw error;
+  }
+}

package/src/utils/index.ts

@@ -1,6 +1,7 @@
 export * from './apiv2.js';
 export * from './attachment-delivery.js';
 export * from './attachment-upload.js';
+export * from './attachment-validation.js';
 export * from './bytestring.js';
 export * from './configuration.js';
 export * from './env.js';