Add web multimodal image attachments

2026-07-23 15:20:47 +08:00
parent 3e3ea47296
commit cb4c11b869
116 changed files with 3177 additions and 151 deletions
@@ -0,0 +1,101 @@
+/** Minimal raster header validation used before bytes enter durable storage. */
+
+import { AttachmentError } from '@deepseek-ai/dsh-attachment'
+import type { ImageMediaType } from '@deepseek-ai/dsh-attachment'
+
+/** Decoded metadata from a supported image header. */
+export interface DetectedImage {
+  mediaType: ImageMediaType
+  width: number
+  height: number
+}
+
+function ascii(data: Uint8Array, start: number, value: string): boolean {
+  if (data.length < start + value.length) return false
+  for (let i = 0; i < value.length; i++) if (data[start + i] !== value.charCodeAt(i)) return false
+  return true
+}
+
+function u16be(data: Uint8Array, offset: number): number {
+  return ((data[offset] ?? 0) << 8) | (data[offset + 1] ?? 0)
+}
+
+function u16le(data: Uint8Array, offset: number): number {
+  return (data[offset] ?? 0) | ((data[offset + 1] ?? 0) << 8)
+}
+
+function u24le(data: Uint8Array, offset: number): number {
+  return (data[offset] ?? 0) | ((data[offset + 1] ?? 0) << 8) | ((data[offset + 2] ?? 0) << 16)
+}
+
+function u32be(data: Uint8Array, offset: number): number {
+  return (((data[offset] ?? 0) * 0x1000000) + ((data[offset + 1] ?? 0) << 16)
+    + ((data[offset + 2] ?? 0) << 8) + (data[offset + 3] ?? 0)) >>> 0
+}
+
+function u32le(data: Uint8Array, offset: number): number {
+  return ((data[offset] ?? 0) + ((data[offset + 1] ?? 0) << 8)
+    + ((data[offset + 2] ?? 0) << 16) + ((data[offset + 3] ?? 0) * 0x1000000)) >>> 0
+}
+
+function dimensions(width: number, height: number, mediaType: ImageMediaType): DetectedImage {
+  if (width < 1 || height < 1) throw new AttachmentError('Image dimensions must be positive.', 'INVALID_IMAGE')
+  return { mediaType, width, height }
+}
+
+function jpeg(data: Uint8Array): DetectedImage | null {
+  if (data[0] !== 0xff || data[1] !== 0xd8) return null
+  const sof = new Set([0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf])
+  let offset = 2
+  while (offset + 3 < data.length) {
+    while (data[offset] === 0xff) offset++
+    const marker = data[offset]
+    if (marker === undefined || marker === 0xd9 || marker === 0xda) break
+    if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) {
+      offset++
+      continue
+    }
+    const length = u16be(data, offset + 1)
+    if (length < 2 || offset + 1 + length > data.length) throw new AttachmentError('JPEG data is truncated.', 'INVALID_IMAGE')
+    if (sof.has(marker)) {
+      if (length < 7) throw new AttachmentError('JPEG dimensions are truncated.', 'INVALID_IMAGE')
+      return dimensions(u16be(data, offset + 6), u16be(data, offset + 4), 'image/jpeg')
+    }
+    offset += length + 1
+  }
+  throw new AttachmentError('JPEG dimensions are missing.', 'INVALID_IMAGE')
+}
+
+/**
+ * Detect a supported raster type and intrinsic dimensions from encoded bytes.
+ * @param data - complete encoded image bytes.
+ * @returns verified format and dimensions.
+ */
+export function detectImage(data: Uint8Array): DetectedImage {
+  if (data.length >= 24
+    && data[0] === 0x89 && ascii(data, 1, 'PNG\r\n\u001a\n') && ascii(data, 12, 'IHDR')) {
+    return dimensions(u32be(data, 16), u32be(data, 20), 'image/png')
+  }
+  if (data.length >= 10 && (ascii(data, 0, 'GIF87a') || ascii(data, 0, 'GIF89a'))) {
+    return dimensions(u16le(data, 6), u16le(data, 8), 'image/gif')
+  }
+  const detectedJpeg = jpeg(data)
+  if (detectedJpeg !== null) return detectedJpeg
+  if (data.length >= 30 && ascii(data, 0, 'RIFF') && ascii(data, 8, 'WEBP')) {
+    const declaredLength = u32le(data, 4) + 8
+    if (declaredLength > data.length) throw new AttachmentError('WebP data is truncated.', 'INVALID_IMAGE')
+    if (ascii(data, 12, 'VP8X')) return dimensions(u24le(data, 24) + 1, u24le(data, 27) + 1, 'image/webp')
+    if (ascii(data, 12, 'VP8L') && data[20] === 0x2f) {
+      const b0 = data[21] ?? 0
+      const b1 = data[22] ?? 0
+      const b2 = data[23] ?? 0
+      const b3 = data[24] ?? 0
+      return dimensions(1 + b0 + ((b1 & 0x3f) << 8), 1 + (b1 >> 6) + (b2 << 2) + ((b3 & 0x0f) << 10), 'image/webp')
+    }
+    if (ascii(data, 12, 'VP8 ') && data[23] === 0x9d && data[24] === 0x01 && data[25] === 0x2a) {
+      return dimensions(u16le(data, 26) & 0x3fff, u16le(data, 28) & 0x3fff, 'image/webp')
+    }
+    throw new AttachmentError('WebP dimensions are missing.', 'INVALID_IMAGE')
+  }
+  throw new AttachmentError('Unsupported or malformed image data.', 'INVALID_IMAGE')
+}
@@ -0,0 +1,74 @@
+/** Local durable attachment backend rooted below `DSH_HOME`. @module @deepseek-ai/dsh-attachment-local */
+
+import { join, resolve } from 'node:path'
+import { Context } from 'cordis'
+import z from 'schemastery'
+import { AttachmentStore } from '@deepseek-ai/dsh-attachment'
+import type { ImageAttachmentLimits, ImageAttachmentRef, SaveImageAttachment, StoredImageAttachment } from '@deepseek-ai/dsh-attachment'
+import { resolveDshHome } from '@deepseek-ai/dsh-paths'
+import { readImageFile, saveImageFile } from './store.ts'
+
+export { detectImage } from './image.ts'
+export { readImageFile, saveImageFile } from './store.ts'
+export { AttachmentError } from '@deepseek-ai/dsh-attachment'
+export type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment'
+
+/** Default maximum encoded bytes for one image. */
+export const DEFAULT_MAX_IMAGE_BYTES = 5 * 1024 * 1024
+/** Default maximum images in one prompt. */
+export const DEFAULT_MAX_IMAGES_PER_MESSAGE = 10
+/** Default maximum aggregate image bytes in one prompt. */
+export const DEFAULT_MAX_MESSAGE_IMAGE_BYTES = 20 * 1024 * 1024
+/** Default maximum intrinsic pixels for one image. */
+export const DEFAULT_MAX_IMAGE_PIXELS = 40_000_000
+
+/** Local attachment backend configuration. */
+export interface Config {
+  /** Explicit harness home; omitted follows `DSH_HOME`, then `~/.dsh`. */
+  dshHome?: string
+  /** Maximum encoded bytes accepted for one image. */
+  maxImageBytes?: number
+  /** Maximum image count accepted in one submitted message. */
+  maxImagesPerMessage?: number
+  /** Maximum aggregate encoded image bytes accepted in one submitted message. */
+  maxMessageImageBytes?: number
+  /** Maximum intrinsic width multiplied by height accepted for one image. */
+  maxImagePixels?: number
+}
+
+/** Persistent content-addressed local attachment store. */
+export class LocalAttachmentStore extends AttachmentStore {
+  static Config: z<Config> = z.object({
+    dshHome: z.string(),
+    maxImageBytes: z.number().step(1).min(1).default(DEFAULT_MAX_IMAGE_BYTES),
+    maxImagesPerMessage: z.number().step(1).min(1).default(DEFAULT_MAX_IMAGES_PER_MESSAGE),
+    maxMessageImageBytes: z.number().step(1).min(1).default(DEFAULT_MAX_MESSAGE_IMAGE_BYTES),
+    maxImagePixels: z.number().step(1).min(1).default(DEFAULT_MAX_IMAGE_PIXELS),
+  })
+
+  /** Absolute versioned storage root. */
+  readonly root: string
+  readonly imageLimits: ImageAttachmentLimits
+
+  constructor(ctx: Context, config: Config) {
+    super(ctx)
+    this.root = resolve(join(resolveDshHome(config.dshHome), 'attachments', 'v1'))
+    this.imageLimits = Object.freeze({
+      maxImageBytes: config.maxImageBytes ?? DEFAULT_MAX_IMAGE_BYTES,
+      maxImagesPerMessage: config.maxImagesPerMessage ?? DEFAULT_MAX_IMAGES_PER_MESSAGE,
+      maxMessageImageBytes: config.maxMessageImageBytes ?? DEFAULT_MAX_MESSAGE_IMAGE_BYTES,
+      maxImagePixels: config.maxImagePixels ?? DEFAULT_MAX_IMAGE_PIXELS,
+      mediaTypes: Object.freeze(['image/png', 'image/jpeg', 'image/webp', 'image/gif'] as const),
+    })
+  }
+
+  async saveImage(input: SaveImageAttachment): Promise<ImageAttachmentRef> {
+    return saveImageFile(this.root, input, this.imageLimits)
+  }
+
+  async readImage(ref: ImageAttachmentRef): Promise<StoredImageAttachment> {
+    return readImageFile(this.root, ref, this.imageLimits)
+  }
+}
+
+export default LocalAttachmentStore
@@ -0,0 +1,20 @@
+/** Package-owned invariant companion for `@deepseek-ai/dsh-attachment-local`. @module @deepseek-ai/dsh-attachment-local/invariant */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-attachment-local'
+/** Cordis companion plugin name. */
+export const name = 'attachment-local-invariant'
+/** Services required before package ownership can be reserved. */
+export const inject = ['invariants', 'attachments']
+/** No runtime invariant: immutable writes and verified reads are enforced directly at the backend boundary. */
+const install: InvariantInstaller = () => {}
+/**
+ * Register the package invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the registration disposer.
+ */
+export const apply = (ctx: Context): Promise<() => void> => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
@@ -0,0 +1,121 @@
+/** Content-addressed, owner-private local attachment storage. */
+
+import { createHash, randomUUID } from 'node:crypto'
+import { constants } from 'node:fs'
+import { chmod, link, mkdir, open, readFile, unlink } from 'node:fs/promises'
+import { basename, join } from 'node:path'
+import {
+  AttachmentError,
+  AttachmentId,
+} from '@deepseek-ai/dsh-attachment'
+import type {
+  ImageAttachmentLimits,
+  ImageAttachmentRef,
+  SaveImageAttachment,
+  StoredImageAttachment,
+} from '@deepseek-ai/dsh-attachment'
+import { detectImage } from './image.ts'
+
+const ID_PATTERN = /^sha256:([a-f0-9]{64})$/
+
+function digest(data: Uint8Array): string {
+  return createHash('sha256').update(data).digest('hex')
+}
+
+function displayName(value: string | undefined): string | undefined {
+  if (value === undefined) return undefined
+  const clean = basename(value).replace(/[\u0000-\u001f\u007f]/g, '').trim().slice(0, 255)
+  return clean === '' ? undefined : clean
+}
+
+function objectPath(root: string, sha256: string): string {
+  return join(root, 'objects', sha256.slice(0, 2), sha256)
+}
+
+function ensureReference(ref: ImageAttachmentRef): string {
+  const match = ID_PATTERN.exec(String(ref.attachmentId))
+  if (match?.[1] === undefined) throw new AttachmentError('Attachment reference is invalid.', 'INVALID_ATTACHMENT_REF')
+  return match[1]
+}
+
+function validateMetadata(data: Uint8Array, declaredMediaType: ImageAttachmentRef['mediaType'], limits: ImageAttachmentLimits): Omit<ImageAttachmentRef, 'attachmentId' | 'name'> {
+  if (data.byteLength === 0) throw new AttachmentError('Image is empty.', 'INVALID_IMAGE')
+  if (data.byteLength > limits.maxImageBytes) throw new AttachmentError('Image exceeds the configured byte limit.', 'IMAGE_TOO_LARGE')
+  const detected = detectImage(data)
+  if (detected.mediaType !== declaredMediaType) throw new AttachmentError('Declared image type does not match its bytes.', 'IMAGE_TYPE_MISMATCH')
+  if (detected.width * detected.height > limits.maxImagePixels) throw new AttachmentError('Image exceeds the configured decoded-pixel limit.', 'IMAGE_TOO_MANY_PIXELS')
+  return { ...detected, bytes: data.byteLength }
+}
+
+/**
+ * Save and verify immutable image bytes below a versioned attachment root.
+ * @param root - absolute `DSH_HOME/attachments/v1` root.
+ * @param input - encoded bytes and declared metadata.
+ * @param limits - resolved storage policy.
+ * @returns durable content-addressed reference.
+ */
+export async function saveImageFile(root: string, input: SaveImageAttachment, limits: ImageAttachmentLimits): Promise<ImageAttachmentRef> {
+  const metadata = validateMetadata(input.data, input.mediaType, limits)
+  const sha256 = digest(input.data)
+  const bucket = join(root, 'objects', sha256.slice(0, 2))
+  const staging = join(root, 'tmp')
+  await mkdir(bucket, { recursive: true, mode: 0o700 })
+  await mkdir(staging, { recursive: true, mode: 0o700 })
+  await chmod(bucket, 0o700)
+  await chmod(staging, 0o700)
+  const temporary = join(staging, randomUUID())
+  const target = objectPath(root, sha256)
+  let handle
+  try {
+    handle = await open(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600)
+    await handle.writeFile(input.data)
+    await handle.sync()
+    await handle.close()
+    handle = undefined
+    try {
+      await link(temporary, target)
+    } catch (error) {
+      if (!(error instanceof Error && 'code' in error && error.code === 'EEXIST')) throw error
+      const existing = new Uint8Array(await readFile(target))
+      if (digest(existing) !== sha256) throw new AttachmentError('Stored attachment failed integrity verification.', 'ATTACHMENT_CORRUPT')
+    }
+    await unlink(temporary)
+  } catch (error) {
+    if (handle !== undefined) await handle.close().catch(() => { /* close failure is superseded by the storage failure */ })
+    await unlink(temporary).catch((cleanupError: unknown) => {
+      if (!(cleanupError instanceof Error && 'code' in cleanupError && cleanupError.code === 'ENOENT')) throw cleanupError
+    })
+    if (error instanceof AttachmentError) throw error
+    throw new AttachmentError('Unable to persist image attachment.', 'ATTACHMENT_WRITE_FAILED', { cause: error })
+  }
+  const name = displayName(input.name)
+  return {
+    attachmentId: AttachmentId(`sha256:${sha256}`),
+    ...metadata,
+    ...(name !== undefined ? { name } : {}),
+  }
+}
+
+/**
+ * Read and verify one content-addressed image.
+ * @param root - absolute `DSH_HOME/attachments/v1` root.
+ * @param ref - reference recorded in the session log.
+ * @param limits - resolved storage policy.
+ * @returns verified bytes and reference.
+ */
+export async function readImageFile(root: string, ref: ImageAttachmentRef, limits: ImageAttachmentLimits): Promise<StoredImageAttachment> {
+  const sha256 = ensureReference(ref)
+  let data: Uint8Array
+  try {
+    data = new Uint8Array(await readFile(objectPath(root, sha256)))
+  } catch (error) {
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') throw new AttachmentError('Attachment object is missing.', 'ATTACHMENT_NOT_FOUND')
+    throw new AttachmentError('Unable to read image attachment.', 'ATTACHMENT_READ_FAILED', { cause: error })
+  }
+  if (digest(data) !== sha256) throw new AttachmentError('Stored attachment failed integrity verification.', 'ATTACHMENT_CORRUPT')
+  const metadata = validateMetadata(data, ref.mediaType, limits)
+  if (metadata.bytes !== ref.bytes || metadata.width !== ref.width || metadata.height !== ref.height) {
+    throw new AttachmentError('Stored attachment metadata does not match its reference.', 'ATTACHMENT_CORRUPT')
+  }
+  return { ref, data }
+}