kandev/docs/plans/plugin-backed-canvases/task-03-isolated-browser-runtime.md

id, title, status, wave, depends_on, plan, requirements, acceptance_criteria, system_design

id	title	status	wave	depends_on	plan	requirements	acceptance_criteria	system_design
03-isolated-browser-runtime	Isolated browser runtime	done	3	02-plugin-web-app-package-foundation	plan.md	REQ-PLUGINS-ISOLATED-WEB-APPS-001 REQ-PLUGINS-ISOLATED-WEB-APPS-003 REQ-PLUGINS-ISOLATED-WEB-APPS-007 REQ-PLUGINS-ISOLATED-WEB-APPS-008 REQ-PLUGINS-ISOLATED-WEB-APPS-009 REQ-PLUGINS-ISOLATED-WEB-APPS-010	AC-PLUGINS-ISOLATED-WEB-APPS-001.2 AC-PLUGINS-ISOLATED-WEB-APPS-001.3 AC-PLUGINS-ISOLATED-WEB-APPS-003.1 AC-PLUGINS-ISOLATED-WEB-APPS-003.2 AC-PLUGINS-ISOLATED-WEB-APPS-003.3 AC-PLUGINS-ISOLATED-WEB-APPS-003.4 AC-PLUGINS-ISOLATED-WEB-APPS-003.5 AC-PLUGINS-ISOLATED-WEB-APPS-007.1 AC-PLUGINS-ISOLATED-WEB-APPS-007.2 AC-PLUGINS-ISOLATED-WEB-APPS-007.3 AC-PLUGINS-ISOLATED-WEB-APPS-007.4 AC-PLUGINS-ISOLATED-WEB-APPS-007.5 AC-PLUGINS-ISOLATED-WEB-APPS-007.6 AC-PLUGINS-ISOLATED-WEB-APPS-007.7 AC-PLUGINS-ISOLATED-WEB-APPS-007.8 AC-PLUGINS-ISOLATED-WEB-APPS-008.2 AC-PLUGINS-ISOLATED-WEB-APPS-009.1 AC-PLUGINS-ISOLATED-WEB-APPS-009.2 AC-PLUGINS-ISOLATED-WEB-APPS-009.3 AC-PLUGINS-ISOLATED-WEB-APPS-010.3	../../specs/plugins/system-design/isolated-web-app-contributions.md

Task 03: Isolated browser runtime

Summary

Serve immutable releases through revocable capabilities. Enforce the opaque sandbox for iframe and direct navigation in web and Tauri hosts.

In scope

• Issue and revalidate user-bound and release-bound capability URLs.
• Serve safe package MIME types without ambient session authorization.
• Build CSP and network policy from normalized grants.
• Add response-level sandbox, referrer, MIME, cache, CORP, and framing headers.
• Add the shared frontend web-application frame.
• Add Tauri frame-src and runtime frame-ancestors support.
• Add direct-navigation, cookie, CORS, Tauri, and policy regression tests.

Out of scope

• Kandev data, state, events, canvas metadata, and navigation.

Acceptance

• Direct and framed runtime documents remain opaque and cannot reach host state.
• Revoked, stale, foreign, expired, or unavailable capabilities fail closed.
• Web and desktop hosts load the runtime while other parents cannot frame it.

Verification

cd apps/backend && go test ./internal/plugins/webapp/... ./internal/plugins/...
cd apps && pnpm --filter @kandev/web test -- components/plugins lib/plugins
cd apps && pnpm --filter @kandev/desktop typecheck

Files likely touched

• apps/backend/internal/plugins/webapp/runtime.go
• apps/backend/internal/plugins/webapp/tokens.go
• apps/backend/internal/plugins/webapp/policy.go
• apps/backend/internal/plugins/handlers.go
• apps/web/components/plugins/web-app-frame.tsx
• apps/web/components/plugins/web-app-frame.test.tsx
• apps/desktop/src-tauri/tauri.conf.json
• desktop runtime smoke fixtures

Dependencies

• Task 02 provides validated releases, instances, grants, and availability.

Risks

• One sandbox token can collapse the opaque-origin boundary.
• A CORP or ancestor value can block one supported host.
• A redirect or referrer can expose a runtime capability.

Parallelism

sequential

Inputs

• Browser host, runtime token, browser security, compatibility, and failure sections.
• Current port-proxy capability and desktop CSP patterns.

Results

• Added digest-only, user and release-bound runtime capabilities with expiry, renewal, revocation, and stale-binding validation.
• Added immutable artifact serving with safe MIME selection, no-store and isolation headers, opaque-origin CORS handling, response CSP sandboxing, and normalized HTTPS network policy.
• Added the responsive WebAppFrame host with the required opaque iframe sandbox and mobile safe-area behavior, plus the desktop loopback frame-src policy and Tauri ancestor support.
• Verification passed for the backend runtime packages, the new frontend component, i18n catalogs, and desktop TypeScript. The broad plugin frontend suite reached 258 passing tests but reported one existing Monaco command registration race as an unhandled error.