Files

T

Bohdan Triapitsyn 68f1c1efe3 docs(agent): streamline guidance and skills

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.

2026-07-14 00:45:44 +03:00

2.2 KiB

Raw Blame History

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

2.2 KiB Raw Blame History