47 lines
2.2 KiB
Markdown
47 lines
2.2 KiB
Markdown
|
# 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.
|
||
|
|
|
||
|
|
## Preview Iframes And Rewritten Resources
|
||
|
|
|
||
|
|
- Use preview proxy helpers so preview and URL tokens propagate to rewritten resources and redirects.
|
||
|
|
- Strip legacy client-token query parameters before forwarding upstream.
|
||
|
|
- Do not use `postMessage('*')`; target the known preview origin.
|
||
|
|
- Preserve CSP where possible. If injecting a bridge, prefer a per-response nonce and remove only directives that block framing or the bridge.
|
||
|
|
- 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/preview/proxy-runtime.test.js`
|