# 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](server-directory.md) — requests use active server's API base
- Domain README: [`toju-app/src/app/domains/chat/README.md`](../../toju-app/src/app/domains/chat/README.md)

## Changelog

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