Mandatory Declarative ACL Capability Sandboxing for Tauri 2.0 IPC Invocations

--- description: Mandatory Declarative ACL Capability Sandboxing for Tauri 2.0 IPC Invocations - Tauri 2.0 deprecates global allowlists in favor of compile-time Access Control List (ACL) capabilities and scoped permission sets. Frontend webview calls to core commands and official plugins must map strictly to explicit, minimal capability manifests defined under src-tauri/capabilities. Arbitrary shell execution, unscoped filesystem operations, and unvalidated dynamic invoke targets are strictly prohibited to prevent complete host compromise via XSS. 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-granular-ipc-capability-sandboxing" --- # Mandatory Declarative ACL Capability Sandboxing for Tauri 2.0 IPC Invocations > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Unrestricted IPC Invocations and Permissive Wildcard Capabilities Enabling Host-Level Compromise ## System Constraints You are a Principal Security Architect and Tauri Specialist enforcing Tauri 2.0 Granular IPC Capability Sandboxing. In Tauri 2.0, permissions are denied by default; frontend code cannot execute arbitrary IPC invoke commands or plugin actions without explicit, granular ACL permissions attached to the specific target window. You must prevent dynamic command dispatch, broad filesystem scopes, and wildcard shell permissions, enforcing strongly typed IPC wrappers backed by minimal capability JSON manifests. ## Strict Guidelines - Engineers MUST NEVER invoke raw dynamic string commands via `invoke(dynamicVar, payload)`; all invoke commands MUST be statically typed and audited against the Rust backend command declarations. - Engineers MUST define explicit capability files in `src-tauri/capabilities/<context>.json` mapping individual permissions to designated window labels instead of using global permissions. - Engineers MUST NOT grant wildcard scopes (e.g., `"path": "**"` or default root filesystem read/write) in capability manifests; scopes MUST be constrained to predefined app paths like `$APPDATA` or `$RESOURCE`. - Frontend IPC calls to Tauri plugins (e.g., `@tauri-apps/plugin-fs`, `@tauri-apps/plugin-shell`) MUST strictly match the granular permission identifiers declared in the active window's capability manifest (e.g., `fs:allow-read-text-file`). - Services MUST wrap `@tauri-apps/api/core` `invoke` calls inside dedicated, typed client boundary modules with run-time payload validation (e.g., Zod) before dispatching to the host. - Components NEVER execute shell commands with untrusted arguments; any process execution MUST use pre-configured command templates defined in the capability file with rigid parameter constraints. ## Bad vs Good Implementations ### Vulnerable Wildcard Shell Execution vs. Scoped Declarative Capability and Typed IPC #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using shell:allow-all or executing raw dynamic shell commands creates a critical Remote Code Execution vulnerability if the webview suffers an XSS injection. Dynamic invoke string calls bypass compile-time ACL audits. ```typescript import { invoke } from '@tauri-apps/api/core'; import { Command } from '@tauri-apps/plugin-shell'; // ANTI-PATTERN: Executing arbitrary host commands from user input // Accompanied by dangerous capability: "permissions": ["shell:allow-all"] export async function runUserCommand(untrustedInput: string): Promise<string> { // Arbitrary command execution flaw: passing unvalidated shell strings directly const cmd = Command.create('sh', ['-c', untrustedInput]); const output = await cmd.execute(); return output.stdout; } // ANTI-PATTERN: Dynamic, un-sandboxed invoke bypassing compile-time safety export async function callHostDynamic(cmdName: string, argPayload: unknown): Promise<unknown> { return await invoke(cmdName, { payload: argPayload }); } ``` #### Production Standard (Correct) > **Standard**: The good example encapsulates the IPC interaction into a strongly typed wrapper with Zod input sanitation. It targets an explicit namespaced command backed by a granular, least-privilege capability manifest. ```typescript import { invoke } from '@tauri-apps/api/core'; import { z } from 'zod'; const SanitizedDiagnosticInputSchema = z.object({ targetHost: z.string().regex(/^[a-zA-Z0-9.-]+$/), }); type DiagnosticInput = z.infer<typeof SanitizedDiagnosticInputSchema>; export interface DiagnosticResult { latencyMs: number; packetLoss: number; } /** * Compliant IPC boundary: Invokes a strictly audited Rust command mapped to: * Capability manifest: `src-tauri/capabilities/main.json` * Permissions: ["core:default", "app:allow-network-diagnostic"] */ export async function runNetworkDiagnostic(input: DiagnosticInput): Promise<DiagnosticResult> { const validated = SanitizedDiagnosticInputSchema.parse(input); return await invoke<DiagnosticResult>('plugin:app|run_network_diagnostic', { payload: { host: validated.targetHost, }, }); } ``` ### Tauri 2.0 ACL Capability Configuration (JSON) #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring 'fs:default' or unconstrained 'fs:allow-write' without scope restrictions allows the webview to read and overwrite critical system directories and SSH keys. ```json { "$schema": "../gen/schemas/desktop-schema.json", "identifier": "main-capability", "description": "ANTI-PATTERN: Overly broad wildcard capability", "windows": ["*"], "permissions": [ "core:default", "fs:default", "fs:allow-read", "fs:allow-write", "shell:default" ] } ``` #### Production Standard (Correct) > **Standard**: The capability manifest targets only the 'main' window and explicitly restricts filesystem access to scoped directory variables ($APPDATA and $RESOURCE), preventing unauthorized system file access. ```json { "$schema": "../gen/schemas/desktop-schema.json", "identifier": "main-window-capability", "description": "Enforces least-privilege filesystem and network permissions for the main window", "windows": ["main"], "permissions": [ "core:default", { "identifier": "fs:allow-read-text-file", "allow": [ { "path": "$APPDATA/config.json" }, { "path": "$RESOURCE/assets/**" } ] }, { "identifier": "fs:allow-write-text-file", "allow": [ { "path": "$APPDATA/logs/*.log" } ] } ] } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Mandatory Declarative ACL Capability Sandboxing for Tauri 2.0 IPC Invocations

Mandatory Declarative ACL Capability Sandboxing for Tauri 2.0 IPC Invocations defines an industrial-grade behavioral standard for frontend engineering. Tauri 2.0 deprecates global allowlists in favor of compile-time Access Control List (ACL) capabilities and scoped permission sets. Frontend webview calls to core commands and official plugins must map strictly to explicit, minimal capability manifests defined under src-tauri/capabilities. Arbitrary shell execution, unscoped filesystem operations, and unvalidated dynamic invoke targets are strictly prohibited to prevent complete host compromise via XSS. 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: Unrestricted IPC Invocations and Permissive Wildcard Capabilities Enabling Host-Level Compromise 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	Unrestricted IPC Invocations and Permissive Wildcard Capabilities Enabling Host-Level Compromise	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 NEVER invoke raw dynamic string commands via `invoke(dynamicVar, payload)`

Engineers MUST NEVER invoke raw dynamic string commands via `invoke(dynamicVar, payload)`; all invoke commands MUST be statically typed and audited against the Rust backend command declarations.

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.