openchamber/.agents/skills/ui-api-decoupling/references/browser-assets-and-auth.md

# Browser Assets And URL Authentication

## Choose By Request Owner

| Request shape | Correct path |
|---|---|
| UI can fetch a small authenticated asset | `runtimeFetch`, read `blob()`, render an object URL |
| Browser must own a URL (`iframe`, download/open link, large/raw image, rewritten subresource) | `getRuntimeUrlResolver().authenticatedAsset(...)` |
| SSE | `getRuntimeUrlResolver().sse(...)` and owning transport |
| WebSocket | `getRuntimeUrlResolver().websocket(...)` plus `openRuntimeWebSocket` where required |

Do not prebuild a browser URL and then immediately call `runtimeFetch` with it. Ordinary HTTP callers pass route paths to `runtimeFetch`; browser/realtime consumers use resolver URLs.

## Object URLs

- Key caches by runtime identity, entity ID, update/version, and render options.
- Bound caches by count and bytes when values can be large.
- Revoke evicted object URLs with `URL.revokeObjectURL`.
- Render a deterministic fallback while loading or after display-only failure.

## URL Tokens

Browser-owned URLs cannot attach the normal `Authorization` header. Use short-lived scoped `oc_url_token` minted through runtime auth helpers.

- Never manually append `oc_url_token`.
- Never place a long-lived client bearer token in a URL.
- Treat `oc_client_token` query use as legacy stripping/rejection only.
- Add browser-readable GET or realtime paths to the narrow allowlist in `packages/web/server/lib/ui-auth/ui-auth.js`.
- Add allowlist tests; never allow arbitrary `/api/*` URL-token access.

## Showing Somebody Else's Page

OpenChamber does not rewrite third-party HTML to display it. Rewriting a page to
serve it under our origin and a path prefix breaks every absolute URL on it, and
recovering from that means encoding knowledge of each framework's dev-server
internals — which ages badly and fails silently.

- The in-app browser renders a real Chromium `<webview>` (`packages/ui/src/components/browser/`).
- A dev server on a remote OpenChamber host is reached by binding a local port
  and tunnelling raw bytes (`packages/web/server/lib/dev-tunnel/`), so the page
  keeps its own origin at the root of its own host.
- Runtimes without a Chromium host fall back to a plain iframe that can display
  a page but cannot inspect one. State that limit; do not emulate around it.
- Do not use `postMessage('*')`; target a known origin.
- Re-resolve browser URLs after runtime switches; do not retain URLs minted for an old runtime.

## Security Tests

Prefer focused coverage in:

- `packages/ui/src/lib/runtime-url.test.ts`
- `packages/ui/src/lib/runtime-auth.test.ts`
- `packages/web/server/lib/ui-auth/ui-auth.test.js`
- `packages/web/server/lib/dev-tunnel/tunnel.test.js`