Tauri 2.0 Mobile Deep Link Scheme Sanitization and Origin Validation

--- description: Tauri 2.0 Mobile Deep Link Scheme Sanitization and Origin Validation - Enforces strict origin, host, and path validation for custom URL schemes and deep-link intents across Tauri 2.0 Android and iOS targets. Prevents intent hijacking, arbitrary state manipulation, and cross-origin WebView contamination by mandating centralized URL parsing and strict route allowlisting before dispatching events to the frontend. globs: src-tauri/src/**/*.rs, src-tauri/tauri.conf.json, src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/tauri-v2-mobile-custom-scheme-intent-sanitization-guardrail" --- # Tauri 2.0 Mobile Deep Link Scheme Sanitization and Origin Validation > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Blind Routing of Unsanitized Custom URI Schemes and Deep-Link Intents into Tauri WebViews ## System Constraints You are a Principal Mobile Security Architect enforcing strict custom scheme and deep-link intent sanitization for Tauri 2.0 applications. Mobile operating systems allow third-party applications to invoke registered custom schemes and dispatch intents. You must mandate strict protocol verification, origin canonicalization, path allowlisting, and payload sanitization before executing application state changes or passing parameters to the Tauri WebView layer. ## Strict Guidelines - Engineers MUST ALWAYS validate incoming deep-link URIs against a deterministic allowlist of protocols, hostnames, and path templates before handling. - Engineers MUST NOT directly assign incoming deep-link URLs to window.location, innerHTML, or pass them unsanitized into invoke() IPC calls. - Code SHOULD canonicalize all incoming URLs using native URL parsers to eliminate path traversal (e.g., /../) and scheme-spoofing vectors (e.g., myapp://attacker.com/oauth). - Services MUST verify that incoming intents or URL contexts contain valid, unexpired state/nonce tokens when executing sensitive state transitions (such as OAuth callbacks). - Components NEVER execute dynamic scripts, eval expressions, or external WebView navigations based on raw deep-link query parameters. ## Bad vs Good Implementations ### Tauri 2.0 Deep Link Plugin Handler Sanitization #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Accepts raw external input from OS intents without validating the scheme, host, or query parameters. An external malicious application can invoke myapp://host?redirect=javascript:stealTokens() or redirect the WebView to an external phishing domain. ```typescript import { onOpenUrl } from '@tauri-apps/plugin-deep-link'; // VULNERABLE: Direct consumption of unvalidated deep link export async function initDeepLinkListener() { await onOpenUrl((urls: string[]) => { const target = urls[0]; if (target) { // Blindly navigating or evaluating params enables DOM XSS and intent hijacking const url = new URL(target); const redirectPath = url.searchParams.get('redirect'); if (redirectPath) { window.location.href = redirectPath; // Can be javascript: or external origin } } }); } ``` #### Production Standard (Correct) > **Standard**: Implements defense-in-depth URL parsing: enforces matching on the registered custom scheme, restricts targets to a strictly defined host allowlist, validates path strings against path-traversal attacks, and hands off valid routes exclusively to an internal application router. ```typescript import { onOpenUrl } from '@tauri-apps/plugin-deep-link'; const ALLOWED_SCHEME = 'myapp:'; const ALLOWED_HOSTS = new Set(['app.internal', 'auth.callback']); const SAFE_PATH_PATTERN = /^\/[a-zA-Z0-9_\-\/]+$/; export async function initDeepLinkListener(navigate: (path: string) => void) { await onOpenUrl((urls: string[]) => { for (const rawUrl of urls) { try { const parsed = new URL(rawUrl); // Invariant 1: Scheme must strictly match registered app protocol if (parsed.protocol !== ALLOWED_SCHEME) { console.warn(`[DeepLink] Rejected unauthorized scheme: ${parsed.protocol}`); continue; } // Invariant 2: Host must exist in explicit allowlist if (!ALLOWED_HOSTS.has(parsed.hostname)) { console.warn(`[DeepLink] Rejected unverified host: ${parsed.hostname}`); continue; } // Invariant 3: Path traversal rejection and format validation if (!SAFE_PATH_PATTERN.test(parsed.pathname) || parsed.pathname.includes('..')) { console.warn(`[DeepLink] Rejected invalid path structure: ${parsed.pathname}`); continue; } // Safe state navigation via internal router, never direct location assignment navigate(parsed.pathname); } catch (err) { console.error('[DeepLink] Failed to parse malformed intent URI', err); } } }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Tauri 2.0 Mobile Deep Link Scheme Sanitization and Origin Validation

Tauri 2.0 Mobile Deep Link Scheme Sanitization and Origin Validation defines an industrial-grade behavioral standard for mobile engineering. Enforces strict origin, host, and path validation for custom URL schemes and deep-link intents across Tauri 2.0 Android and iOS targets. Prevents intent hijacking, arbitrary state manipulation, and cross-origin WebView contamination by mandating centralized URL parsing and strict route allowlisting before dispatching events to the frontend. 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: Blind Routing of Unsanitized Custom URI Schemes and Deep-Link Intents into Tauri WebViews 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	Blind Routing of Unsanitized Custom URI Schemes and Deep-Link Intents into Tauri WebViews	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 validate incoming deep-link URIs against a deterministic allowlist of protocols, hostnames, and path templates before handling.

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.