@fg-lab/amadeus-qq 0.0.0-stage → 1.2.1

package/src/onebot.js

@@ -0,0 +1,378 @@
+import { normalizeId, normalizeMessageId, sceneIdentity } from './storage.js'
+
+const SEGMENT_LIMIT = 100
+const EVENT_SIZE_LIMIT = 256 * 1024
+const MEDIA_SEGMENT_TYPES = new Set(['image', 'record', 'video', 'file'])
+const MAX_MEDIA_ID_LENGTH = 256
+const DIAGNOSTIC_INTERVAL_MS = 60_000
+
+function plainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+/**
+ * A media `file` field is an opaque platform handle, not a locator. Keep only
+ * short, single-token handles; every URL scheme, local path, UNC path, CQ code
+ * and control character is dropped so an inbound event can never carry a
+ * network or filesystem target into durable state or the model prompt.
+ */
+function safeMediaId(value) {
+  if (typeof value !== 'string' || value.length < 1 || value.length > MAX_MEDIA_ID_LENGTH) return null
+  if (value.trim() !== value) return null
+  if (/[\u0000-\u001f\u007f]/.test(value)) return null
+  if (/\[CQ:/i.test(value)) return null
+  if (/^[a-z][a-z0-9+.-]*:/i.test(value)) return null
+  if (/^[A-Za-z]:/.test(value)) return null
+  if (value.includes('/') || value.includes('\\')) return null
+  if (value === '.' || value === '..' || value.includes('..')) return null
+  if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(value)) return null
+  return value
+}
+
+function safeId(value, normalize) {
+  try { return normalize(value) } catch { return null }
+}
+
+/**
+ * String-format OneBot messages may contain arbitrary CQ payloads. Their
+ * parameters can hold locators or inline data, so remove each complete code
+ * while leaving ordinary words on either side intact.
+ */
+function stripCqCodes(text) {
+  let removed = false
+  const stripped = text.replace(/\[CQ:[a-z_]+(?:,[^\]]*)?\]/gi, () => {
+    removed = true
+    return ' '
+  })
+  // Keep the words on both sides separate without carrying a CQ parameter.
+  return removed ? stripped.replace(/[ \t]{2,}/g, ' ').trim() : text
+}
+
+/**
+ * Every inbound segment is reduced to a per-type whitelist: text keeps only
+ * its text, at/reply keep only the IDs used for trigger and quote semantics,
+ * face keeps only a bounded face ID, media keep only a non-locating handle,
+ * and unknown segments keep their type with an empty data object. No URL,
+ * local path, base64/CQ locator or arbitrary platform field is retained.
+ */
+export function sanitizeInboundSegments(source) {
+  if (!Array.isArray(source)) throw new TypeError('invalid OneBot message segments')
+  if (source.length > SEGMENT_LIMIT) throw new Error('OneBot message has too many segments')
+  return source.map(segment => {
+    if (!plainObject(segment) || typeof segment.type !== 'string' || !/^[a-z_]{1,32}$/i.test(segment.type) || !plainObject(segment.data)) {
+      throw new TypeError('invalid OneBot segment')
+    }
+    const type = segment.type.toLowerCase()
+    if (type === 'text') {
+      const text = typeof segment.data.text === 'string' ? stripCqCodes(segment.data.text) : ''
+      return { type, data: { text } }
+    }
+    if (type === 'at') {
+      const qq = safeId(segment.data.qq, value => normalizeId(value, 'at.qq'))
+      return { type, data: qq === null ? {} : { qq } }
+    }
+    if (type === 'reply') {
+      // Preserve the existing distinction: a missing ID means "no reply",
+      // while a malformed non-empty ID still rejects the event.
+      if (segment.data.id == null) return { type, data: {} }
+      return { type, data: { id: normalizeMessageId(segment.data.id, 'reply.id') } }
+    }
+    if (type === 'face') {
+      const id = safeId(segment.data.id, normalizeFaceId)
+      return { type, data: id === null ? {} : { id } }
+    }
+    if (MEDIA_SEGMENT_TYPES.has(type)) {
+      const file = safeMediaId(segment.data.file)
+      return { type, data: file === null ? {} : { file } }
+    }
+    return { type, data: {} }
+  })
+}
+
+export function normalizeOneBotMessage(raw) {
+  if (!plainObject(raw) || raw.post_type !== 'message') return null
+  if (raw.message_type !== 'group' && raw.message_type !== 'private') return null
+  if (JSON.stringify(raw).length > EVENT_SIZE_LIMIT) throw new Error('OneBot event exceeds size limit')
+  const scene = sceneIdentity({
+    botId: raw.self_id,
+    kind: raw.message_type,
+    peerId: raw.message_type === 'group' ? raw.group_id : raw.user_id,
+  })
+  const senderId = normalizeId(raw.user_id, 'senderId')
+  const messageId = normalizeMessageId(raw.message_id)
+  const source = Array.isArray(raw.message)
+    ? raw.message
+    : [{ type: 'text', data: { text: String(raw.message ?? '') } }]
+  const segments = sanitizeInboundSegments(source)
+  const atIds = segments.filter(item => item.type === 'at').map(item => {
+    try { return normalizeId(item.data.qq, 'at.qq') } catch { return null }
+  }).filter(Boolean)
+  const replyId = segments.find(item => item.type === 'reply')?.data?.id
+  return {
+    scene,
+    message: {
+      messageId,
+      senderId,
+      time: Number.isFinite(raw.time) ? raw.time : null,
+      segments,
+      replyToMessageId: replyId == null ? null : normalizeMessageId(replyId, 'reply.id'),
+      atIds,
+      sender: plainObject(raw.sender)
+        ? { nickname: typeof raw.sender.nickname === 'string' ? raw.sender.nickname.slice(0, 100) : null,
+            card: typeof raw.sender.card === 'string' ? raw.sender.card.slice(0, 100) : null }
+        : null,
+    },
+  }
+}
+
+const MAX_FACE_ID = 1_000_000
+
+/**
+ * Normalize a standard QQ face ID. Only a canonical non-negative decimal ID
+ * within a small bound is accepted; any other data fields are intentionally
+ * dropped by the caller.
+ */
+function normalizeFaceId(value) {
+  if (typeof value === 'number') {
+    if (!Number.isSafeInteger(value) || value < 0 || value > MAX_FACE_ID) throw new TypeError('invalid face segment')
+    return String(value)
+  }
+  if (typeof value !== 'string' || !/^(0|[1-9]\d{0,6})$/.test(value)) throw new TypeError('invalid face segment')
+  const id = Number(value)
+  if (!Number.isSafeInteger(id) || id > MAX_FACE_ID) throw new TypeError('invalid face segment')
+  return String(id)
+}
+
+export function validateOutgoingSegments(raw) {
+  if (!Array.isArray(raw) || raw.length < 1 || raw.length > 20) throw new TypeError('message must contain 1–20 segments')
+  return raw.map(segment => {
+    if (!plainObject(segment) || !plainObject(segment.data)) throw new TypeError('invalid outgoing segment')
+    if (segment.type === 'text') {
+      if (typeof segment.data.text !== 'string' || !segment.data.text.trim() || segment.data.text.length > 4000) throw new TypeError('invalid text segment')
+      return { type: 'text', data: { text: segment.data.text } }
+    }
+    if (segment.type === 'at') return { type: 'at', data: { qq: normalizeId(segment.data.qq, 'at.qq') } }
+    if (segment.type === 'reply') return { type: 'reply', data: { id: normalizeMessageId(segment.data.id, 'reply.id') } }
+    if (segment.type === 'face') return { type: 'face', data: { id: normalizeFaceId(segment.data.id) } }
+    throw new TypeError(`unsupported outgoing segment: ${String(segment.type)}`)
+  })
+}
+
+function responseTooLarge() {
+  const error = new Error('ONEBOT_RESPONSE_TOO_LARGE')
+  error.code = 'ONEBOT_RESPONSE_TOO_LARGE'
+  return error
+}
+
+async function readBoundedJson(response, maxBytes) {
+  const declared = response.headers?.get?.('content-length')
+  if (declared !== null && declared !== undefined) {
+    const length = Number(declared)
+    if (Number.isFinite(length) && length > maxBytes) {
+      try { await response.body?.cancel?.() } catch { /* best effort */ }
+      throw responseTooLarge()
+    }
+  }
+  if (!response.body || typeof response.body.getReader !== 'function') {
+    throw new Error('ONEBOT_RESPONSE_UNSUPPORTED')
+  }
+  const reader = response.body.getReader()
+  const chunks = []
+  let total = 0
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      const chunk = Buffer.from(value)
+      total += chunk.length
+      if (total > maxBytes) {
+        try { await reader.cancel() } catch { /* best effort */ }
+        throw responseTooLarge()
+      }
+      chunks.push(chunk)
+    }
+  } finally {
+    try { reader.releaseLock() } catch { /* already closed */ }
+  }
+  return JSON.parse(Buffer.concat(chunks).toString('utf8'))
+}
+
+export class OneBotAdapter {
+  constructor(config = {}, dependencies = {}) {
+    this.config = config
+    this.fetch = dependencies.fetch ?? globalThis.fetch
+    this.makeWebSocket = dependencies.makeWebSocket
+    this.socket = null
+    this.stopped = config.enabled !== true
+    this.pendingActions = new Set()
+    this.reconnectTimer = null
+    this.retryMs = 1000
+    this.onEvent = null
+    this.onDiagnostic = typeof dependencies.onDiagnostic === 'function' ? dependencies.onDiagnostic : null
+    this.diagnosticAt = new Map()
+    this.status = 'disabled'
+  }
+
+  /**
+   * Emit one fixed-code diagnostic per bounded interval. Callers pass only a
+   * constant code: exception messages, event bodies, URLs, credentials and
+   * paths never leave the adapter. A diagnostic sink failure cannot affect the
+   * connection or create an unhandled rejection.
+   */
+  #diagnose(code) {
+    if (!this.onDiagnostic) return
+    const now = Date.now()
+    if (now - (this.diagnosticAt.get(code) ?? 0) < DIAGNOSTIC_INTERVAL_MS) return
+    this.diagnosticAt.set(code, now)
+    try {
+      Promise.resolve(this.onDiagnostic(Object.freeze({ code }))).catch(() => {})
+    } catch {
+      // The diagnostic sink is best-effort and must never break transport.
+    }
+  }
+
+  get token() {
+    if (this.config.token) {
+      if (typeof this.config.token !== 'string' || this.config.token.length > 256 || /[\r\n]/.test(this.config.token)) throw new TypeError('invalid token')
+      return this.config.token
+    }
+    const name = this.config.tokenEnv
+    if (!name) return ''
+    if (typeof name !== 'string' || !/^[A-Z][A-Z0-9_]*$/.test(name)) throw new TypeError('invalid tokenEnv')
+    return process.env[name] ?? ''
+  }
+
+  async start(onEvent) {
+    if (this.config.enabled !== true) { this.status = 'disabled'; return }
+    if (typeof onEvent !== 'function') throw new TypeError('onEvent callback required')
+    if (!/^wss?:\/\//.test(this.config.wsUrl ?? '') || !/^https?:\/\//.test(this.config.httpUrl ?? '')) {
+      throw new TypeError('OneBot WS and HTTP URLs are required')
+    }
+    this.onEvent = onEvent
+    this.stopped = false
+    await this.#connect()
+  }
+
+  async #connect() {
+    if (this.stopped) return
+    this.status = 'connecting'
+    try {
+      const factory = this.makeWebSocket ?? ((await import('ws')).default)
+      if (this.stopped) return
+      const headers = this.token ? { Authorization: `Bearer ${this.token}` } : {}
+      const ws = new factory(this.config.wsUrl, { headers })
+      this.socket = ws
+      ws.on('open', () => {
+        if (this.stopped) { ws.close?.(); return }
+        this.status = 'connected'; this.retryMs = 1000
+      })
+      ws.on('message', data => {
+        if (this.stopped) return
+        let event
+        try {
+          if (data.length > EVENT_SIZE_LIMIT) return
+          event = JSON.parse(String(data))
+        } catch {
+          // A malformed platform event is harmless and cannot stop the socket.
+          return
+        }
+        Promise.resolve()
+          .then(() => { if (!this.stopped) return this.onEvent(event) })
+          .catch(() => this.#diagnose('QQ_INBOUND_HANDLER_FAILED'))
+      })
+      ws.on('error', () => {
+        if (this.stopped) return
+        this.status = 'disconnected'
+        this.#diagnose('QQ_ONEBOT_SOCKET_ERROR')
+      })
+      ws.on('close', () => {
+        if (this.socket === ws) this.socket = null
+        this.status = this.stopped ? 'disabled' : 'disconnected'
+        if (!this.stopped) this.#scheduleReconnect()
+      })
+    } catch {
+      if (this.stopped) return
+      this.status = 'disconnected'
+      this.#diagnose('QQ_ONEBOT_CONNECT_FAILED')
+      this.#scheduleReconnect()
+    }
+  }
+
+  #scheduleReconnect() {
+    if (this.stopped || this.reconnectTimer) return
+    const delay = this.retryMs
+    this.retryMs = Math.min(this.retryMs * 2, 30_000)
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null
+      void this.#connect()
+    }, delay)
+    this.reconnectTimer.unref?.()
+  }
+
+  async action(name, params, timeoutMs = 10_000, maxResponseBytes = undefined) {
+    if (this.config.enabled !== true || this.stopped) {
+      const error = new Error('QQ_HANDOFF_PAUSED: OneBot transport is disabled')
+      error.code = 'QQ_HANDOFF_PAUSED'
+      throw error
+    }
+    if (!/^[a-z][a-z0-9_]{1,80}$/.test(name)) throw new TypeError('invalid OneBot action')
+    if (maxResponseBytes !== undefined &&
+      (!Number.isSafeInteger(maxResponseBytes) || maxResponseBytes < 1)) {
+      throw new TypeError('maxResponseBytes must be a positive safe integer')
+    }
+    const url = new URL(name, `${this.config.httpUrl.replace(/\/+$/, '')}/`)
+    const controller = new AbortController()
+    this.pendingActions.add(controller)
+    try {
+      const response = await this.fetch(url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...(this.token ? { Authorization: `Bearer ${this.token}` } : {}) },
+        body: JSON.stringify(params),
+        signal: AbortSignal.any([AbortSignal.timeout(timeoutMs), controller.signal]),
+      })
+      const result = maxResponseBytes === undefined
+        ? await response.json()
+        : await readBoundedJson(response, maxResponseBytes)
+      if (this.stopped) {
+        const error = new Error('QQ_HANDOFF_INTERRUPTED: OneBot action outcome is unknown')
+        error.code = 'QQ_HANDOFF_INTERRUPTED'
+        throw error
+      }
+      if (!response.ok || !plainObject(result) || result.status !== 'ok' || result.retcode !== 0) {
+        const error = new Error(`OneBot action ${name} rejected`)
+        error.code = 'ONEBOT_REJECTED'
+        throw error
+      }
+      return result.data
+    } catch (cause) {
+      if (this.stopped && cause?.code !== 'QQ_HANDOFF_INTERRUPTED') {
+        const error = new Error('QQ_HANDOFF_INTERRUPTED: OneBot action outcome is unknown')
+        error.code = 'QQ_HANDOFF_INTERRUPTED'
+        throw error
+      }
+      throw cause
+    } finally {
+      this.pendingActions.delete(controller)
+    }
+  }
+
+  async send(scene, segments) {
+    const identity = sceneIdentity(scene)
+    const action = identity.kind === 'group' ? 'send_group_msg' : 'send_private_msg'
+    const params = identity.kind === 'group'
+      ? { group_id: identity.peerId, message: segments }
+      : { user_id: identity.peerId, message: segments }
+    const result = await this.action(action, params)
+    return { messageId: normalizeMessageId(result?.message_id, 'send receipt message_id') }
+  }
+
+  stop() {
+    this.stopped = true
+    this.status = 'disabled'
+    for (const controller of this.pendingActions) controller.abort()
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer)
+    this.reconnectTimer = null
+    this.socket?.close?.()
+    this.socket = null
+  }
+}

package/src/outbound-media.js

@@ -0,0 +1,309 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { createHash } from 'node:crypto'
+
+const MIB = 1024 * 1024
+export const OUTBOUND_MEDIA_LIMITS = Object.freeze({
+  image: 5 * MIB,
+  gif: 5 * MIB,
+  video: 20 * MIB,
+  file: 20 * MIB,
+  audio: 4 * MIB,
+})
+export const TTS_UNAVAILABLE_CODE = 'QQ_TTS_UNAVAILABLE'
+
+const BLOCKED_FILE_EXTENSIONS = new Set([
+  '.bat', '.cmd', '.com', '.dll', '.exe', '.hta', '.js', '.jse', '.lnk',
+  '.msi', '.msp', '.ps1', '.scr', '.vbe', '.vbs', '.wsf', '.wsh',
+])
+
+function mediaError(code) {
+  const error = new Error(code)
+  error.code = code
+  return error
+}
+
+function assertSend(core, sessionId) {
+  let scene
+  try {
+    scene = core.authorizedScene(sessionId)
+  } catch {
+    throw mediaError('QQ_PERMISSION_DENIED: qq.send')
+  }
+  let allowed = false
+  try {
+    allowed = core.authorizeSessionCapability(sessionId, 'qq.send') === true
+  } catch {
+    allowed = false
+  }
+  if (!allowed) throw mediaError('QQ_PERMISSION_DENIED: qq.send')
+  return scene
+}
+
+function resolveSendRoot(sendRoot) {
+  if (typeof sendRoot !== 'string' || !path.isAbsolute(sendRoot)) throw mediaError('QQ_MEDIA_ROOT_INVALID')
+  let root
+  try {
+    root = fs.realpathSync(sendRoot)
+    if (!fs.statSync(root).isDirectory()) throw new Error('not a directory')
+  } catch {
+    throw mediaError('QQ_MEDIA_ROOT_INVALID')
+  }
+  return root
+}
+
+function resolveRootSource(relative, root, sendRoot) {
+  if (typeof relative !== 'string' || relative.length === 0 || relative.includes('\u0000')) {
+    throw mediaError('QQ_MEDIA_PATH_INVALID')
+  }
+  if (path.isAbsolute(relative)) throw mediaError('QQ_MEDIA_PATH_INVALID')
+  const candidate = path.resolve(sendRoot, relative)
+  const lexical = path.relative(sendRoot, candidate)
+  if (lexical === '' || lexical === '..' || lexical.startsWith(`..${path.sep}`) || path.isAbsolute(lexical)) {
+    throw mediaError('QQ_MEDIA_PATH_OUTSIDE_ROOT')
+  }
+
+  let entry
+  try {
+    entry = fs.lstatSync(candidate)
+  } catch {
+    throw mediaError('QQ_MEDIA_PATH_INVALID')
+  }
+  if (entry.isSymbolicLink() || !entry.isFile()) throw mediaError('QQ_MEDIA_PATH_INVALID')
+
+  let real
+  try {
+    real = fs.realpathSync(candidate)
+  } catch {
+    throw mediaError('QQ_MEDIA_PATH_INVALID')
+  }
+  const relativeReal = path.relative(root, real)
+  if (relativeReal === '' || relativeReal === '..' ||
+    relativeReal.startsWith(`..${path.sep}`) || path.isAbsolute(relativeReal)) {
+    throw mediaError('QQ_MEDIA_PATH_OUTSIDE_ROOT')
+  }
+
+  let cursor = sendRoot
+  for (const part of lexical.split(path.sep)) {
+    cursor = path.join(cursor, part)
+    try {
+      if (fs.lstatSync(cursor).isSymbolicLink()) throw mediaError('QQ_MEDIA_PATH_INVALID')
+    } catch (error) {
+      if (error.code === 'QQ_MEDIA_PATH_INVALID') throw error
+      throw mediaError('QQ_MEDIA_PATH_INVALID')
+    }
+  }
+  return real
+}
+
+function resolveHostAttachment(source, kind, attachments) {
+  const ref = source.attachment
+  if (!ref || typeof ref !== 'object' || Array.isArray(ref) ||
+    typeof ref.attachmentId !== 'string' || !/^sha256:[a-f0-9]{64}$/.test(ref.attachmentId) ||
+    typeof ref.name !== 'string' || typeof ref.bytes !== 'number' ||
+    !Number.isSafeInteger(ref.bytes) || ref.bytes < 1) {
+    throw mediaError('QQ_MEDIA_ATTACHMENT_INVALID')
+  }
+  if (!attachments || typeof attachments !== 'object') throw mediaError('QQ_MEDIA_ATTACHMENTS_UNAVAILABLE')
+  const resolver = kind === 'image' || kind === 'gif' ? attachments.imageHostPath : attachments.fileHostPath
+  if (typeof resolver !== 'function') throw mediaError('QQ_MEDIA_ATTACHMENTS_UNAVAILABLE')
+  let hostPath
+  try {
+    hostPath = resolver.call(attachments, ref)
+  } catch {
+    throw mediaError('QQ_MEDIA_ATTACHMENT_INVALID')
+  }
+  if (typeof hostPath !== 'string' || !path.isAbsolute(hostPath)) throw mediaError('QQ_MEDIA_ATTACHMENT_INVALID')
+  return hostPath
+}
+
+function statRegularFile(file) {
+  let entry
+  try {
+    entry = fs.lstatSync(file)
+  } catch {
+    throw mediaError('QQ_MEDIA_PATH_INVALID')
+  }
+  if (entry.isSymbolicLink() || !entry.isFile()) throw mediaError('QQ_MEDIA_PATH_INVALID')
+  return entry
+}
+
+function sniffKind(kind, data, name) {
+  if (kind === 'image') {
+    if (data.length >= 8 && data.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) return 'image/png'
+    if (data.length >= 3 && data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff) return 'image/jpeg'
+    if (data.length >= 12 && data.toString('ascii', 0, 4) === 'RIFF' && data.toString('ascii', 8, 12) === 'WEBP') return 'image/webp'
+    throw mediaError('QQ_MEDIA_FORMAT_INVALID')
+  }
+  if (kind === 'gif') {
+    if (data.length >= 6 && (data.toString('ascii', 0, 6) === 'GIF87a' || data.toString('ascii', 0, 6) === 'GIF89a')) return 'image/gif'
+    throw mediaError('QQ_MEDIA_FORMAT_INVALID')
+  }
+  if (kind === 'video') {
+    if (data.length >= 12 && data.toString('ascii', 4, 8) === 'ftyp') return 'video/mp4'
+    if (data.length >= 4 && data[0] === 0x1a && data[1] === 0x45 && data[2] === 0xdf && data[3] === 0xa3) return 'video/webm'
+    throw mediaError('QQ_MEDIA_FORMAT_INVALID')
+  }
+  if (kind === 'audio') {
+    if (data.length >= 12 && data.toString('ascii', 0, 4) === 'RIFF' && data.toString('ascii', 8, 12) === 'WAVE') return 'audio/wav'
+    if (data.length >= 3 && data.toString('ascii', 0, 3) === 'ID3') return 'audio/mpeg'
+    if (data.length >= 2 && data[0] === 0xff && (data[1] & 0xe0) === 0xe0) return 'audio/mpeg'
+    if (data.length >= 4 && data.toString('ascii', 0, 4) === 'OggS') return 'audio/ogg'
+    if (data.length >= 4 && data.toString('ascii', 0, 4) === 'fLaC') return 'audio/flac'
+    if (data.length >= 6 && data.toString('ascii', 0, 6) === '#!AMR\n') return 'audio/amr'
+    throw mediaError('QQ_MEDIA_FORMAT_INVALID')
+  }
+  if (kind === 'file') {
+    const extension = path.extname(name).toLowerCase()
+    if (!extension || BLOCKED_FILE_EXTENSIONS.has(extension)) throw mediaError('QQ_MEDIA_FORMAT_INVALID')
+    return 'application/octet-stream'
+  }
+  throw mediaError('QQ_MEDIA_UNSUPPORTED_KIND')
+}
+
+async function readAndHash(file, maxBytes) {
+  let handle
+  try {
+    handle = await fs.promises.open(file, 'r')
+    const stats = await handle.stat()
+    if (!stats.isFile()) throw mediaError('QQ_MEDIA_PATH_INVALID')
+    if (stats.size <= 0) throw mediaError('QQ_MEDIA_EMPTY')
+    if (stats.size > maxBytes) throw mediaError('QQ_MEDIA_TOO_LARGE')
+    const data = Buffer.alloc(stats.size)
+    let offset = 0
+    while (offset < data.length) {
+      const { bytesRead } = await handle.read(data, offset, data.length - offset, offset)
+      if (bytesRead <= 0) throw mediaError('QQ_MEDIA_READ_FAILED')
+      offset += bytesRead
+    }
+    return { data, sha256: createHash('sha256').update(data).digest('hex') }
+  } catch (error) {
+    if (typeof error?.code === 'string' && error.code.startsWith('QQ_MEDIA_')) throw error
+    throw mediaError('QQ_MEDIA_READ_FAILED')
+  } finally {
+    if (handle) await handle.close().catch(() => {})
+  }
+}
+
+function safeName(value, kind) {
+  const base = path.basename(String(value ?? '')).replace(/[\u0000-\u001f\u007f]/g, '').trim()
+  if (base.length === 0) return kind === 'video' ? 'qq-video' : 'qq-file'
+  return base.slice(0, 128)
+}
+
+/**
+ * Validate one controlled PNG/JPEG/GIF below sendRoot and copy the exact bytes
+ * into a private temporary snapshot for one platform call. The caller owns
+ * cleanup and must never expose the snapshot path to model output.
+ */
+export async function snapshotControlledImage({ sendRoot, relativePath, tempRoot } = {}) {
+  const root = resolveSendRoot(sendRoot)
+  const source = resolveRootSource(relativePath, root, sendRoot)
+  const { data, sha256 } = await readAndHash(source, 5 * MIB)
+  let mediaType
+  try {
+    mediaType = sniffKind('image', data, path.basename(source))
+  } catch {
+    mediaType = sniffKind('gif', data, path.basename(source))
+  }
+  if (tempRoot !== undefined && (typeof tempRoot !== 'string' || !path.isAbsolute(tempRoot))) {
+    throw mediaError('QQ_MEDIA_TEMP_INVALID')
+  }
+  let tempDir
+  try {
+    if (tempRoot !== undefined && !fs.statSync(tempRoot).isDirectory()) throw new Error('not a directory')
+    tempDir = await fs.promises.mkdtemp(path.join(tempRoot ?? os.tmpdir(), 'amadeus-qq-avatar-'))
+    await fs.promises.chmod(tempDir, 0o700)
+    const extension = mediaType === 'image/png' ? '.png' : mediaType === 'image/jpeg' ? '.jpg' : '.gif'
+    const snapshot = path.join(tempDir, `avatar${extension}`)
+    await fs.promises.writeFile(snapshot, data, { flag: 'wx', mode: 0o600 })
+    const written = await fs.promises.readFile(snapshot)
+    if (written.length !== data.length || createHash('sha256').update(written).digest('hex') !== sha256) {
+      throw mediaError('QQ_MEDIA_SNAPSHOT_INVALID')
+    }
+    let cleaned = false
+    return {
+      path: snapshot,
+      mediaType,
+      bytes: data.length,
+      sha256,
+      async cleanup() {
+        if (cleaned) return
+        cleaned = true
+        await fs.promises.rm(tempDir, { recursive: true, force: true }).catch(() => {})
+      },
+    }
+  } catch (error) {
+    if (tempDir) await fs.promises.rm(tempDir, { recursive: true, force: true }).catch(() => {})
+    if (typeof error?.code === 'string' && error.code.startsWith('QQ_MEDIA_')) throw error
+    throw mediaError('QQ_MEDIA_SNAPSHOT_FAILED')
+  }
+}
+
+/**
+ * Build one controlled outbound media plan. `source` must be either a relative
+ * path below the configured sendRoot, or an already-validated Host attachment
+ * reference owned by the caller. Never pass model-supplied paths, URLs or
+ * base64 into this helper. Message plans are ready for core.send(); upload
+ * plans require the core's delivery ledger with the returned fingerprint.
+ */
+export async function prepareOutboundMedia({
+  core,
+  sessionId,
+  kind,
+  source,
+  sendRoot,
+  attachments,
+}) {
+  if (kind === 'voice' || kind === 'record') throw mediaError(TTS_UNAVAILABLE_CODE)
+  if (!Object.hasOwn(OUTBOUND_MEDIA_LIMITS, kind)) throw mediaError('QQ_MEDIA_UNSUPPORTED_KIND')
+  if (!source || typeof source !== 'object' || Array.isArray(source)) throw mediaError('QQ_MEDIA_SOURCE_INVALID')
+
+  const scene = assertSend(core, sessionId)
+  const maxBytes = OUTBOUND_MEDIA_LIMITS[kind]
+  let root
+  let file
+  if (source.type === 'send-root') {
+    if (Object.keys(source).sort().join(',') !== 'path,type') throw mediaError('QQ_MEDIA_SOURCE_INVALID')
+    root = resolveSendRoot(sendRoot)
+    file = resolveRootSource(source.path, root, sendRoot)
+  } else if (source.type === 'host-attachment') {
+    if (Object.keys(source).sort().join(',') !== 'attachment,type') throw mediaError('QQ_MEDIA_SOURCE_INVALID')
+    file = resolveHostAttachment(source, kind, attachments)
+    statRegularFile(file)
+  } else {
+    throw mediaError('QQ_MEDIA_SOURCE_INVALID')
+  }
+
+  const { data, sha256 } = await readAndHash(file, maxBytes)
+  const name = safeName(path.basename(file), kind)
+  const mediaType = sniffKind(kind, data, name)
+
+  // Re-check the bound Scene immediately before returning an executable plan.
+  assertSend(core, sessionId)
+
+  if (kind === 'file') {
+    const group = scene.kind === 'group'
+    return {
+      mode: 'upload',
+      action: group ? 'upload_group_file' : 'upload_private_file',
+      params: group
+        ? { group_id: scene.peerId, file, name, upload_file: true }
+        : { user_id: scene.peerId, file, name, upload_file: true },
+      mediaType,
+      bytes: data.length,
+      fingerprint: sha256,
+    }
+  }
+  return {
+    mode: 'message',
+    segments: [{
+      type: kind === 'video' ? 'video' : kind === 'audio' ? 'record' : 'image',
+      data: { file },
+    }],
+    mediaType,
+    bytes: data.length,
+    fingerprint: sha256,
+  }
+}