Bohdan Triapitsyn
68f1c1efe3
Keep always-on instructions concise and route specialized work through focused skills. Split large skills into progressive references and add dedicated change, desktop, sync, and performance guidance.
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`
|