openchamber/packages/web/server/lib/markdown-image-grants/DOCUMENTATION.md

# Markdown Image Grants

## Purpose

This module lets the Markdown image gallery display images that an assistant
explicitly referenced from OpenCode's temporary directory when the UI is on a
different machine.

## Contract

- Chat Markdown rendering is independent: assistant image syntax renders as an
  icon and filename, while the gallery only reads finalized Markdown to collect
  image candidates.
- `POST /api/openchamber/sessions/:sessionId/markdown-image-grants` prepares up to 12
  local images in one message-level request. The server fetches the assistant
  message once and verifies every exact image source before reading files.
- Authorization recognizes the same common inline and reference-style image
  destinations collected by the UI, including balanced parentheses, while
  excluding fenced and inline code.
- Relative and workspace-contained absolute paths resolve against the active
  directory. Other absolute paths are accepted only inside
  `os.tmpdir()/opencode` after `realpath` resolution.
- PNG, JPEG, GIF, and WebP files are signature-checked and limited to 10 MiB.
- Prepare requests inspect only file metadata and signatures. Workspace images
  reuse the existing authenticated `/api/fs/raw` asset route directly. Images
  under `os.tmpdir()/opencode` receive the existing path-bound `raw`
  `outsideFileGrant`; this module does not add another asset lifetime, copy, or
  storage layer. Missing files return per-source results so the gallery can
  remove only those items.

The routes are OpenChamber-owned and must be registered before the generic
OpenCode proxy. Web, Electron, hosted mobile, and Capacitor use the shared
server implementation. VS Code does not call this route for workspace images;
those use its local filesystem bridge. If called, the grant route returns an
explicit unsupported response because OpenCode temporary images are not
supported there.

Requests to OpenCode carry the directory in a percent-encoded
`x-opencode-directory` header, matching the SDK wire format; OpenCode rejects
raw non-ASCII header values.