Toju/agents-docs/features/link-preview-media-proxy.md

Link Preview & Media Proxy

Status: Active Last updated: 2026-07-05

Overview

The signaling server fetches untrusted URLs on behalf of clients for link embed previews and image proxying, with SSRF guards. Chat and DM composers render embeds using these endpoints.

Responsibilities

• Server: outbound fetch with host validation, caching, size limits.
• Client chat domain: request metadata when messages contain URLs; render cards in message list.
• It does NOT store embeds long-term on the server beyond in-memory cache.

API

GET /api/link-metadata

• Auth: Public
• Query: url (http/https)
• Response: { title?, description?, imageUrl?, siteName? }
• Guards: resolveAndValidateHost + safeFetch; 8 s timeout; HTML capped at 512 KB; in-memory cache sized by variables.json link-preview config

GET /api/image-proxy

• Auth: Public
• Query: url (http/https)
• Response: Raw image bytes (Content-Type from origin)
• Limits: image/* only; max 8 MB; 8 s timeout; SSRF validation
• Cache: Cache-Control: public, max-age=3600

Client usage

Message markdown / link-embed pipeline calls link-metadata for unfurling; proxied images load through /api/image-proxy when direct fetch would fail (CORS, mixed content).

Related

• server-directory.md — requests use active server's API base
• Domain README: toju-app/src/app/domains/chat/README.md

Changelog

Date	Change
2026-07-05	Initial link preview / image proxy contract