Capacitor 7 Deep-Link Intent Sandboxing & IPC Bridge Isolation Standard

--- description: Capacitor 7 Deep-Link Intent Sandboxing & IPC Bridge Isolation Standard - Enforces strict origin validation, cryptographic payload schema verification, and isolated execution contexts for external deep-link intents prior to dispatching them across Capacitor 7's JavaScript-to-Native bridge. Prevents prototype pollution, arbitrary JavaScript execution, and internal plugin method invocation originating from untrusted native intent injections. Guarantees that parsed intent parameters are strictly decoupled from internal IPC router arguments. globs: src/router/**/*.{ts,tsx}, src/services/**/*.{ts,tsx}, src/plugins/**/*.{ts,tsx}, src/core/**/*.{ts,tsx}, src/App.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-deep-link-intent-sandboxing-standard" --- # Capacitor 7 Deep-Link Intent Sandboxing & IPC Bridge Isolation Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Directly feeding raw deep-link URLs and unvalidated query parameters into internal Capacitor plugin calls and IPC dispatchers. ## System Constraints You are a Principal Security Architect enforcing the Capacitor 7 Deep-Link Intent Sandboxing Standard. Your mandate is to prevent arbitrary native-bridge execution and internal schema poisoning. You must guarantee that all deep-link handlers execute within a sealed parsing pipeline, sanitizing all intent parameters against strict Zod/Valibot schemas before routing or invoking any native plugins via Capacitor's IPC bridge. ## Strict Guidelines - Engineers MUST ALWAYS wrap the Capacitor App 'appUrlOpen' listener in a defensive sandbox that rejects non-allowlisted URI schemes, hosts, and paths. - Engineers MUST validate deep-link payloads against strict runtime schemas (e.g., Zod) with 'strip' or 'strict' enforcement to prevent prototype injection. - Engineers MUST NOT forward raw URL query parameters, fragment identifiers, or intent data directly into Capacitor plugin invocations or state stores. - Services MUST translate sanitized intent data into strictly typed, internal-only domain command objects before passing them to internal routers or native plugins. - Components NEVER execute raw JavaScript or evaluate dynamic Capacitor plugin names from inbound deep-link paths (e.g., dynamic plugin invocation patterns). ## Bad vs Good Implementations ### Deep-Link Handling: Raw Intent Forwarding vs. Sandboxed Safe Dispatch #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Raw external intent data is extracted without scheme or host verification. The code directly feeds unvalidated query parameters into a native bridge plugin (NativeSettings) and forwards raw paths directly into navigation, exposing the app to arbitrary internal command execution, open redirects, and IPC bridge abuse. ```typescript import { App, URLOpenListenerEvent } from '@capacitor/app'; import { NativeSettings, SettingPath } from 'capacitor-native-settings'; // CRITICAL FLAW: Blindly trusting deep-link payloads and routing them directly to bridge plugins export function initializeDeepLinks(): void { App.addListener('appUrlOpen', (event: URLOpenListenerEvent) => { const url = new URL(event.url); const pluginAction = url.searchParams.get('action'); const targetPath = url.searchParams.get('target'); // Vulnerability 1: Arbitrary internal route injection if (url.pathname.startsWith('/bridge-invoke')) { // Vulnerability 2: Invoking arbitrary native capabilities directly from intent parameters NativeSettings.open({ option: targetPath as SettingPath, }); } // Vulnerability 3: Directly pushing raw unsanitized URL to application router window.location.href = url.pathname + url.search; }); } ``` #### Production Standard (Correct) > **Standard**: The good implementation uses defensive sandboxing: strictly enforcing allowed URL protocols/hosts, validating parameter structure against an immutable Zod schema with `.strict()`, rejecting unhandled mutations, and preventing any direct access to native Capacitor plugins from the deep-link entry point. ```typescript import { App, URLOpenListenerEvent } from '@capacitor/app'; import { z } from 'zod'; const ALLOWED_SCHEME = 'myapp:'; const ALLOWED_HOSTS = new Set(['app.example.com', 'link']); const SafeActionSchema = z.enum(['view_profile', 'open_document']); const DeepLinkPayloadSchema = z.object({ action: SafeActionSchema, targetId: z.string().uuid(), }).strict(); type SafeDeepLinkPayload = z.infer<typeof DeepLinkPayloadSchema>; export function initializeDeepLinks(dispatcher: (payload: SafeDeepLinkPayload) => void): void { App.addListener('appUrlOpen', (event: URLOpenListenerEvent) => { try { const parsedUrl = new URL(event.url); // Sandboxing Step 1: Enforce protocol and origin allowlists if (parsedUrl.protocol !== ALLOWED_SCHEME && !ALLOWED_HOSTS.has(parsedUrl.host)) { console.error('Sandboxed intent rejected: unauthorized origin', parsedUrl.origin); return; } // Sandboxing Step 2: Strictly decouple & sanitize raw params using Zod const rawPayload = { action: parsedUrl.searchParams.get('action'), targetId: parsedUrl.searchParams.get('targetId'), }; const parseResult = DeepLinkPayloadSchema.safeParse(rawPayload); if (!parseResult.success) { console.error('Sandboxed intent rejected: payload validation failed', parseResult.error.issues); return; } // Sandboxing Step 3: Dispatch only validated domain commands to safe handlers dispatcher(parseResult.data); } catch (error) { console.error('Sandboxed intent execution failed safely:', error); } }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Deep-Link Intent Sandboxing & IPC Bridge Isolation Standard

Capacitor 7 Deep-Link Intent Sandboxing & IPC Bridge Isolation Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces strict origin validation, cryptographic payload schema verification, and isolated execution contexts for external deep-link intents prior to dispatching them across Capacitor 7's JavaScript-to-Native bridge. Prevents prototype pollution, arbitrary JavaScript execution, and internal plugin method invocation originating from untrusted native intent injections. Guarantees that parsed intent parameters are strictly decoupled from internal IPC router arguments. 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: Directly feeding raw deep-link URLs and unvalidated query parameters into internal Capacitor plugin calls and IPC dispatchers. 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	Directly feeding raw deep-link URLs and unvalidated query parameters into internal Capacitor plugin calls and IPC dispatchers.	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 wrap the Capacitor App 'appUrlOpen' listener in a defensive sandbox that rejects non-allowlisted URI schemes, hosts, and paths.

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.