Support HEIC image decoding in the /api/media/image proxy

package.json

@@ -42,6 +42,7 @@
     "arweave": "^1.15.7",
     "chat": "^4.20.2",
     "exifr": "^7.1.3",
+    "heic-convert": "^2.1.0",
     "image-meta": "^0.2.2",
     "link-preview-js": "^4.0.0",
     "multiformats": "^13.4.2",

src/lib/media/__tests__/imageProxyHandler.heic.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import imageProxyHandler from '@/lib/media/imageProxyHandler';
+
+vi.mock('@/lib/arweave/fetchUri');
+
+import fetchUri from '@/lib/arweave/fetchUri';
+
+const readHeicFixture = (name: string): Buffer =>
+  readFileSync(join(__dirname, '../../telegram/chat/__tests__/fixtures', name));
+
+const HEIC_DECODE_TIMEOUT_MS = 30_000;
+
+describe('imageProxyHandler HEIC integration', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it(
+    'converts HEIC to webp blur output via sharp',
+    async () => {
+    const heicBuffer = readHeicFixture('apple-styled-photo.heic');
+
+    vi.mocked(fetchUri).mockResolvedValue({
+      ok: true,
+      arrayBuffer: () => Promise.resolve(heicBuffer.buffer),
+    } as Response);
+
+    const result = await imageProxyHandler({
+      url: 'ar://test-heic',
+      width: 16,
+      height: undefined,
+      quality: 10,
+      format: 'webp',
+    });
+
+    expect(result.status).toBe(200);
+    expect(result.headers.get('Content-Type')).toBe('image/webp');
+
+    const body = Buffer.from(await result.arrayBuffer());
+    expect(body.length).toBeGreaterThan(0);
+    expect(body.toString('ascii', 0, 4)).toBe('RIFF');
+    },
+    HEIC_DECODE_TIMEOUT_MS
+  );
+});

src/lib/media/__tests__/isHeicBuffer.test.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import isHeicBuffer from '../isHeicBuffer';
+
+const readHeicFixture = (name: string): Buffer =>
+  readFileSync(join(__dirname, '../../telegram/chat/__tests__/fixtures', name));
+
+describe('isHeicBuffer', () => {
+  it('returns true for Apple multi-brand HEIC', () => {
+    expect(isHeicBuffer(readHeicFixture('apple-styled-photo.heic'))).toBe(true);
+  });
+
+  it('returns true for the shelf HEIC fixture', () => {
+    expect(
+      isHeicBuffer(readHeicFixture('shelf-christmas-decoration.heic'))
+    ).toBe(true);
+  });
+
+  it('returns false for non-HEIC bytes', () => {
+    expect(isHeicBuffer(Buffer.from('not-an-image'))).toBe(false);
+  });
+});

src/lib/media/__tests__/prepareImageBufferForSharp.test.ts

@@ -0,0 +1,34 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import prepareImageBufferForSharp from '../prepareImageBufferForSharp';
+
+const readHeicFixture = (name: string): Buffer =>
+  readFileSync(join(__dirname, '../../telegram/chat/__tests__/fixtures', name));
+
+const HEIC_DECODE_TIMEOUT_MS = 30_000;
+
+describe('prepareImageBufferForSharp', () => {
+  it(
+    'decodes HEIC fixtures to JPEG for sharp',
+    async () => {
+      for (const fixture of [
+        'apple-styled-photo.heic',
+        'shelf-christmas-decoration.heic',
+      ]) {
+        const output = await prepareImageBufferForSharp(
+          readHeicFixture(fixture)
+        );
+        expect(output[0]).toBe(0xff);
+        expect(output[1]).toBe(0xd8);
+      }
+    },
+    HEIC_DECODE_TIMEOUT_MS
+  );
+
+  it('passes through non-HEIC buffers unchanged', async () => {
+    const input = Buffer.from([0x89, 0x50, 0x4e, 0x47]);
+    const output = await prepareImageBufferForSharp(input);
+    expect(output).toBe(input);
+  });
+});

src/lib/media/decodeHeicToJpegBuffer.ts

@@ -0,0 +1,13 @@
+import convert from 'heic-convert';
+
+const decodeHeicToJpegBuffer = async (buffer: Buffer): Promise<Buffer> => {
+  const output = await convert({
+    buffer,
+    format: 'JPEG',
+    quality: 1,
+  });
+
+  return Buffer.from(output);
+};
+
+export default decodeHeicToJpegBuffer;

src/lib/media/imageProxyHandler.ts

@@ -1,6 +1,7 @@
 import { NextResponse } from 'next/server';
 import sharp from 'sharp';
 import fetchUri from '@/lib/arweave/fetchUri';
+import prepareImageBufferForSharp from '@/lib/media/prepareImageBufferForSharp';
 
 const CONTENT_TYPES: Record<string, string> = {
   webp: 'image/webp',
@@ -33,8 +34,9 @@ const imageProxyHandler = async ({
 
   const arrayBuffer = await response.arrayBuffer();
   const buffer = Buffer.from(arrayBuffer);
+  const sharpInput = await prepareImageBufferForSharp(buffer);
 
-  let pipeline = sharp(buffer).autoOrient();
+  let pipeline = sharp(sharpInput).autoOrient();
 
   // Resize if dimensions provided
   if (width || height) {

src/lib/media/isHeicBuffer.ts

@@ -0,0 +1,13 @@
+import readFtypBrands from './readFtypBrands';
+
+const HEIC_BRANDS = new Set(['heic', 'heix', 'heim', 'heis', 'mif1']);
+const HEIF_BRANDS = new Set(['heif', 'hevc', 'hevx', 'hevm', 'hevs', 'msf1']);
+
+const isHeicBuffer = (buffer: Buffer): boolean => {
+  const brands = readFtypBrands(buffer);
+  return brands.some(
+    (brand) => HEIC_BRANDS.has(brand) || HEIF_BRANDS.has(brand)
+  );
+};
+
+export default isHeicBuffer;

src/lib/media/prepareImageBufferForSharp.ts

@@ -0,0 +1,9 @@
+import decodeHeicToJpegBuffer from './decodeHeicToJpegBuffer';
+import isHeicBuffer from './isHeicBuffer';
+
+const prepareImageBufferForSharp = async (buffer: Buffer): Promise<Buffer> => {
+  if (!isHeicBuffer(buffer)) return buffer;
+  return decodeHeicToJpegBuffer(buffer);
+};
+
+export default prepareImageBufferForSharp;

src/lib/media/readFtypBrands.ts

@@ -0,0 +1,16 @@
+const readFtypBrands = (buffer: Buffer): string[] => {
+  if (buffer.length < 16 || buffer.toString('ascii', 4, 8) !== 'ftyp') {
+    return [];
+  }
+
+  const ftypLength = buffer.readUInt32BE(0);
+  if (ftypLength < 16 || ftypLength > buffer.length) return [];
+
+  const brands: string[] = [];
+  for (let offset = 16; offset + 4 <= ftypLength; offset += 4) {
+    brands.push(buffer.toString('ascii', offset, offset + 4));
+  }
+  return brands;
+};
+
+export default readFtypBrands;

src/lib/og/__tests__/getBase64Image.heic.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import getBase64Image from '@/lib/og/getBase64Image';
+
+vi.mock('@/lib/arweave/fetchUri');
+
+import fetchUri from '@/lib/arweave/fetchUri';
+
+const readHeicFixture = (name: string): Buffer =>
+  readFileSync(join(__dirname, '../../telegram/chat/__tests__/fixtures', name));
+
+const HEIC_DECODE_TIMEOUT_MS = 30_000;
+
+describe('getBase64Image HEIC integration', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it(
+    'converts HEIC to a JPEG data URL',
+    async () => {
+    const heicBuffer = readHeicFixture('apple-styled-photo.heic');
+
+    vi.mocked(fetchUri).mockResolvedValue({
+      ok: true,
+      arrayBuffer: () => Promise.resolve(heicBuffer.buffer),
+    } as Response);
+
+    const result = await getBase64Image('ar://test-heic');
+
+    expect(result).toMatch(/^data:image\/jpeg;base64,/);
+    expect(
+      Buffer.from(result!.split(',')[1]!, 'base64').length
+    ).toBeGreaterThan(0);
+    },
+    HEIC_DECODE_TIMEOUT_MS
+  );
+});

src/lib/og/getBase64Image.ts

@@ -1,5 +1,6 @@
 import sharp from 'sharp';
 import fetchUri from '../arweave/fetchUri';
+import prepareImageBufferForSharp from '@/lib/media/prepareImageBufferForSharp';
 
 const MAX_SIZE = 200;
 
@@ -13,8 +14,10 @@ const getBase64Image = async (
     if (!response.ok) return null;
 
     const data = await response.arrayBuffer();
+    const buffer = Buffer.from(data);
+    const sharpInput = await prepareImageBufferForSharp(buffer);
 
-    const resized = await sharp(Buffer.from(data))
+    const resized = await sharp(sharpInput)
       .resize(MAX_SIZE, MAX_SIZE, { fit: 'cover' })
       .jpeg({ quality: 70 })
       .toBuffer();

src/types/heic-convert.d.ts

@@ -0,0 +1,10 @@
+declare module 'heic-convert' {
+  type HeicConvertInput = {
+    buffer: Buffer;
+    format: 'JPEG' | 'PNG';
+    quality?: number;
+  };
+
+  const convert: (input: HeicConvertInput) => Promise<Uint8Array>;
+  export default convert;
+}