Tauri 2.0 Capability-Based IPC Fine-Grained Scoping Standard

--- description: Tauri 2.0 Capability-Based IPC Fine-Grained Scoping Standard - Enforces strict least-privilege isolation in Tauri 2.0 mobile architectures by binding every window and webview context to dedicated, schema-validated capability files. Prohibits global wildcards and unconstrained plugin scopes, ensuring native mobile hardware APIs, secure storage, and filesystem operations are cryptographically and contextually bounded. globs: src-tauri/capabilities/**/*.json, src-tauri/tauri.conf.json, src-tauri/src/**/*.rs, src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/tauri-v2-capability-ipc-scoping-standard" --- # Tauri 2.0 Capability-Based IPC Fine-Grained Scoping Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Permissive Global Default Capabilities and Unscoped Command Invocation in Tauri 2.0 Mobile Runtimes ## System Constraints You are a Principal Mobile Systems Architect and Security Engineer enforcing the Tauri 2.0 Capability-Based IPC Fine-Grained Scoping Standard. You must mandate absolute isolation between native platform capabilities and frontend webview execution contexts. Every IPC command exposed across the Rust-webview boundary on iOS and Android must be constrained to explicit, granular capability files with deterministic path/permission scopes. Never allow wildcard permissions ('*'), never assign default capabilities globally across multiple window contexts, and always guarantee that frontend IPC invocations strictly handle permission-denial exceptions. ## Strict Guidelines - Engineers MUST ALWAYS isolate distinct mobile UI contexts (e.g., main app, biometrics modal, in-app browser) into separate capability JSON files under 'src-tauri/capabilities/'. - Engineers MUST NOT use wildcard characters ('*') in the 'windows' array or permission scope definitions within capability configuration files. - Engineers MUST ALWAYS define explicit directory and file scopes (e.g., '$APPDATA/secure_cache/*', '$APPCACHE/*') for filesystem and media plugins instead of raw unscoped allowances. - Services MUST validate and sanitize all command arguments on the Rust backend using strong serde deserialization schemas, even if already checked on the frontend. - Frontend IPC invokers MUST handle Tauri IPC rejection errors specifically for permission denial ('PermissionDenied' / -32603 code) and provide graceful degradation. - Architectures NEVER rely on 'core:default' without stripping out sensitive native APIs (biometrics, secure storage, contacts) from unprivileged webviews. ## Bad vs Good Implementations ### Tauri 2.0 Capability Configuration: Unscoped Wildcard vs Granular Scoped Definition #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Grants global filesystem and biometric capabilities to any window ('*') without directory-level scoping. A vulnerability in an embedded webview or cross-origin iframe can read arbitrary files and invoke biometric authentication without limitation. ```json { "$schema": "../gen/schemas/desktop-schema.json", "identifier": "mobile-default-capability", "description": "Anti-pattern: Permissive capability granted to all windows", "windows": ["*"], "permissions": [ "core:default", "fs:default", "fs:allow-read-text-file", "biometric:default" ] } ``` #### Production Standard (Correct) > **Standard**: Explicitly binds the capability to a dedicated window ('document-viewer'), excludes dangerous biometric/global permissions, and restricts filesystem read operations strictly to '$APPCACHE/documents/*.pdf'. ```json { "$schema": "../gen/schemas/desktop-schema.json", "identifier": "mobile-document-viewer-capability", "description": "Scoped capability for isolated document viewing window on mobile", "windows": ["document-viewer"], "permissions": [ "core:event:default", "core:window:allow-close", { "identifier": "fs:allow-read-text-file", "allow": [ { "path": "$APPCACHE/documents/*.pdf" } ] } ] } ``` ### TypeScript IPC Client: Safe Typed Invocation with Permission Boundary Handling #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Uses an unvalidated dynamic system path and fails to catch permission denial or capability boundary errors, leading to unexpected crashes or security bypass vectors. ```typescript import { invoke } from '@tauri-apps/api/core'; // Bad: Assumes unrestricted capability and swallows security rejections export async function readMobileDocument(filename: string): Promise<string> { const content = await invoke<string>('plugin:fs|read_text_file', { path: `/data/user/0/com.app/${filename}`, }); return content; } ``` #### Production Standard (Correct) > **Standard**: Strictly sanitizes the filename to prevent directory traversal, uses canonical Tauri path variables matching the capability scope, and explicitly handles capability rejection errors. ```typescript import { invoke } from '@tauri-apps/api/core'; import { z } from 'zod'; const DocumentNameSchema = z.string().regex(/^[a-zA-Z0-9_-]+\.pdf$/, 'Invalid document name format'); export type SafeInvokeResult<T> = | { status: 'success'; data: T } | { status: 'denied'; error: string } | { status: 'failure'; error: string }; export async function readMobileDocument(documentName: string): Promise<SafeInvokeResult<string>> { const validation = DocumentNameSchema.safeParse(documentName); if (!validation.success) { return { status: 'failure', error: validation.error.message }; } try { const content = await invoke<string>('plugin:fs|read_text_file', { path: `$APPCACHE/documents/${validation.data}`, }); return { status: 'success', data: content }; } catch (err: unknown) { const errMessage = typeof err === 'string' ? err : (err as Error)?.message ?? ''; if (errMessage.includes('not allowed') || errMessage.includes('PermissionDenied')) { return { status: 'denied', error: 'Context capability does not grant access to the requested path.' }; } return { status: 'failure', error: errMessage || 'IPC invocation failed.' }; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Tauri 2.0 Capability-Based IPC Fine-Grained Scoping Standard

Tauri 2.0 Capability-Based IPC Fine-Grained Scoping Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces strict least-privilege isolation in Tauri 2.0 mobile architectures by binding every window and webview context to dedicated, schema-validated capability files. Prohibits global wildcards and unconstrained plugin scopes, ensuring native mobile hardware APIs, secure storage, and filesystem operations are cryptographically and contextually bounded. 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: Permissive Global Default Capabilities and Unscoped Command Invocation in Tauri 2.0 Mobile Runtimes 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	Permissive Global Default Capabilities and Unscoped Command Invocation in Tauri 2.0 Mobile Runtimes	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 isolate distinct mobile UI contexts (e.g., main app, biometrics modal, in-app browser) into separate capability JSON files under 'src-tauri/capabilities/'.

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.