Tauri 2.0 Dynamic Capability Scope and Remote Webview Isolation Invariant

--- description: Tauri 2.0 Dynamic Capability Scope and Remote Webview Isolation Invariant - Enforces strict origin-to-command capability mapping and deterministic window labeling in Tauri 2.0 architectures to prevent privilege escalation via IPC bridge exposure. Guarantees that dynamically spawned webviews and remote contexts cannot inherit ambient native permissions or execute unauthorized backend commands. globs: src/**/*.{ts,tsx}, src-tauri/capabilities/**/*.json, src-tauri/tauri.conf.json alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/tauri-v2-dynamic-capability-scope-invariant" --- # Tauri 2.0 Dynamic Capability Scope and Remote Webview Isolation Invariant > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Spawning Dynamic Webview Contexts with Ambient Capability Inheritance and Unscoped Remote IPC Execution ## System Constraints You are a Principal Security Architect enforcing the Tauri 2.0 Dynamic Capability Scope Invariant. In Tauri 2.0, the legacy allowlist is replaced by the Capability and Access Control List (ACL) system. You must enforce that every frontend invocation of native commands and dynamic webview instantiation strictly adheres to defined window labels, explicit origin constraints, and least-privilege capability boundaries. Reject any code that attempts to spawn webview windows inheriting default or wildcard capability scopes when loading external or dynamic URLs. ## Strict Guidelines - Engineers MUST ALWAYS declare isolated, non-wildcard window labels when creating dynamic `WebviewWindow` or `Webview` instances (e.g., `isolated-guest-*`) mapped to an explicit least-privilege capability file. - Engineers MUST NOT map high-privilege permissions (e.g., `core:default`, `fs:*`, `shell:*`, `process:*`) to capabilities containing remote URL patterns (`remote: { urls: [...] }`) or wildcard window lists (`windows: ["*"]`). - Dynamic contexts loading remote or untrusted URLs MUST configure strict isolation by setting `windowOptions.proxyUrl` or running inside an isolated sandbox without native bridge execution privileges. - Frontend IPC invokers MUST NOT dynamically construct command strings from external inputs or unvalidated window states without compile-time discriminant typing. - Dynamic window factory services MUST explicitly validate target URLs against an immutable allowlist of origins before instantiating webview windows. - Components NEVER execute raw `@tauri-apps/api/core::invoke` within context frames or webviews whose origin is not strictly equal to the canonical application scheme (e.g., `tauri://localhost` or configured custom protocol). ## Bad vs Good Implementations ### Dynamic Webview Instantiation with Ambient IPC vs. Isolated Capability Scope #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Creating dynamic webviews using unbounded window labels and external URLs causes them to inherit capabilities using wildcard targeting ('*'). A compromised or untrusted external page loaded in this webview can issue `window.__TAURI_INTERNALS__.invoke` calls against the native host runtime. ```typescript import { WebviewWindow } from '@tauri-apps/api/webviewWindow'; // CRITICAL FLAW: Dynamically opens external/remote target with a random label, // implicitly inheriting ambient/default capability sets with raw IPC bridge access. export async function openExternalDocumentation(targetUrl: string): Promise<void> { const dynamicId = `doc-viewer-${Date.now()}`; const webview = new WebviewWindow(dynamicId, { url: targetUrl, title: 'External Documentation', }); // Untrusted external context now potentially inherits ambient command permissions // if capabilities/default.json uses wildcard window targeting: ["*"] await webview.once('tauri://error', (e) => { console.error('Webview error', e); }); } ``` #### Production Standard (Correct) > **Standard**: Validates the remote origin before instantiation and uses a deterministic label prefix explicitly defined in an isolated Tauri 2.0 capability scope that grants zero core permissions (no fs, shell, or arbitrary custom commands). ```typescript import { WebviewWindow } from '@tauri-apps/api/webviewWindow'; // Production Invariant: Validated origin and deterministic restricted window label prefix // mapped strictly to `guest-viewer.json` capability with zero ambient native plugins. const ALLOWED_DOCS_ORIGIN = 'https://docs.internal.company.com'; const ISOLATED_WINDOW_PREFIX = 'isolated-guest-window'; export async function openExternalDocumentation(targetUrl: string): Promise<WebviewWindow> { const parsed = new URL(targetUrl); if (parsed.origin !== ALLOWED_DOCS_ORIGIN) { throw new Error(`Untrusted origin rejected: ${parsed.origin}`); } // Deterministic label strictly targeted in src-tauri/capabilities/guest-viewer.json const windowLabel = `${ISOLATED_WINDOW_PREFIX}-${crypto.randomUUID()}`; const webview = new WebviewWindow(windowLabel, { url: parsed.toString(), title: 'Isolated Viewer', incognito: true, // Ensure native bridge injection is disabled for non-local origins javascriptDisabled: false }); return webview; } ``` ### Tauri 2.0 Capability Manifest Isolation (guest-viewer.json) #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring 'windows': ['*'] grants every dynamic webview, popup, and iframe instantiated in the app access to the core runtime commands, completely disabling Tauri 2.0 security isolation for dynamic contexts. ```typescript // src-tauri/capabilities/default.json (Anti-pattern: Ambient wildcard binding) /* { "identifier": "main-capability", "description": "Broad access for all windows", "windows": ["*"], "permissions": [ "core:default", "fs:allow-read-text-file", "shell:allow-open" ] } */ export const antiPatternTauriScope = null; ``` #### Production Standard (Correct) > **Standard**: Explicitly binds the capability to the deterministic prefix 'isolated-guest-window-*', specifies an immutable remote URL pattern, and provisions an empty permissions array, enforcing total native execution isolation. ```typescript // src-tauri/capabilities/guest-viewer.json (Production standard: Zero ambient privilege) /* { "$schema": "../gen/schemas/desktop-schema.json", "identifier": "guest-viewer-capability", "description": "Strictly isolated sandbox for guest documentation webviews", "windows": ["isolated-guest-window-*"], "permissions": [], "remote": { "urls": ["https://docs.internal.company.com/*"] } } */ export const productionTauriScope = true; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Tauri 2.0 Dynamic Capability Scope and Remote Webview Isolation Invariant

Tauri 2.0 Dynamic Capability Scope and Remote Webview Isolation Invariant defines an industrial-grade behavioral standard for frontend engineering. Enforces strict origin-to-command capability mapping and deterministic window labeling in Tauri 2.0 architectures to prevent privilege escalation via IPC bridge exposure. Guarantees that dynamically spawned webviews and remote contexts cannot inherit ambient native permissions or execute unauthorized backend commands. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Spawning Dynamic Webview Contexts with Ambient Capability Inheritance and Unscoped Remote IPC Execution Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Spawning Dynamic Webview Contexts with Ambient Capability Inheritance and Unscoped Remote IPC Execution	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS declare isolated, non-wildcard window labels when creating dynamic `WebviewWindow` or `Webview` instances (e.g., `isolated-guest-*`) mapped to an explicit least-privilege capability file.

Engineers MUST ALWAYS declare isolated, non-wildcard window labels when creating dynamic `WebviewWindow` or `Webview` instances (e.g., `isolated-guest-*`) mapped to an explicit least-privilege capability file.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.