Capacitor 7 Cryptographic Intent & Universal Link Verification Guardrail

--- description: Capacitor 7 Cryptographic Intent & Universal Link Verification Guardrail - Enforces deterministic origin verification and cryptographic domain association for all inbound deep links and intents in Capacitor 7 hybrid applications. Eliminates custom URL scheme hijacking and unauthorized native bridge invocation by restricting state mutation to cryptographically proven Universal Links (iOS) and Android App Links. globs: src/**/*.{ts,tsx,js,jsx}, ios/App/App/**/*.{swift,m}, android/app/src/main/**/*.{java,kt,xml}, capacitor.config.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-native-intent-link-verification-guardrail" --- # Capacitor 7 Cryptographic Intent & Universal Link Verification Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Blind Trust in Insecure Custom Scheme Intents Driving Privileged Native Bridge Actions ## System Constraints You are a Principal Mobile Security Architect enforcing strict cryptographic domain association and inbound intent validation in Capacitor 7 applications. Your objective is to prevent deep-link hijacking, malicious intent redirection, and unverified IPC/bridge payload consumption. You must ensure that no custom URI schemes (e.g., myapp://) perform sensitive state mutations, that all deep links adhere strictly to validated HTTPS Universal Links/App Links backed by AASA/assetlinks.json, and that inbound payloads undergo runtime schema validation before dispatch to native plugins or web application state. ## Strict Guidelines - Engineers MUST NEVER execute privileged native bridge actions or mutate authentication/session state based on custom URL schemes (e.g., myapp://). Custom schemes are unverified and hijackable by any malicious application installed on the host OS. - Engineers MUST ALWAYS enforce Universal Links (iOS) via apple-app-site-association (AASA) and Android App Links via Digital Asset Links (assetlinks.json) with autoVerify=true for any inbound navigation or state alteration. - Code MUST validate deep-link hostnames and paths against a strict compile-time whitelist inside the App.addListener('appUrlOpen') handler before deserializing parameters. - Services MUST sanitize, decode, and parse inbound URL query parameters through strict runtime schemas (e.g., Zod) and reject any payload containing dangerous scheme redirects (javascript:, data:, file:) or raw JSON tokens. - Native Android Manifest files MUST explicitly set android:exported="true" ONLY on intent filters that include android:autoVerify="true" with deterministic https schemes and verified domain hosts. - Components NEVER render or navigate directly using deep link URLs without explicit path resolution and sanitization. ## Bad vs Good Implementations ### Insecure Custom Scheme Listener vs. Cryptographically Verified Universal Link Router #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Listens for insecure custom URL schemes, directly stores unverified auth tokens from query parameters into secure storage, and performs unvalidated client-side redirects that expose the app to open redirection and token injection attacks. ```typescript import { App, URLOpenListenerEvent } from '@capacitor/app'; import { Preferences } from '@capacitor/preferences'; // VULNERABLE: Blindly trusts custom schemes (myapp://) and unverified query parameters. // An attacker can register myapp:// in a malicious app, intercept traffic, // or trigger auth mutations by sending an intent with a forged token. App.addListener('appUrlOpen', async (event: URLOpenListenerEvent) => { const url = new URL(event.url); if (url.protocol === 'myapp:') { const authToken = url.searchParams.get('token'); const redirect = url.searchParams.get('redirectUrl'); if (authToken) { await Preferences.set({ key: 'auth_token', value: authToken }); } if (redirect) { window.location.href = redirect; } } }); ``` #### Production Standard (Correct) > **Standard**: Rejects non-HTTPS schemes, enforces strict origin matching against verified domains configured for AASA/App Links, and validates parameters using a rigid runtime schema before propagating the event. ```typescript import { App, URLOpenListenerEvent } from '@capacitor/app'; import { z } from 'zod'; const ALLOWED_HOSTS = new Set(['app.example.com', 'secure.example.com']); const DeepLinkPayloadSchema = z.object({ path: z.enum(['/auth/callback', '/workspace/invite']), code: z.string().regex(/^[a-zA-Z0-9_-]{32,128}$/), state: z.string().uuid() }); App.addListener('appUrlOpen', async (event: URLOpenListenerEvent): Promise<void> => { try { const parsedUrl = new URL(event.url); // Invariant: Enforce HTTPS scheme and strict host matching if (parsedUrl.protocol !== 'https:' || !ALLOWED_HOSTS.has(parsedUrl.hostname)) { console.warn(`[Security] Rejected unauthorized deep-link origin: ${parsedUrl.origin}`); return; } // Runtime schema validation on path and query parameters const validatedParams = DeepLinkPayloadSchema.parse({ path: parsedUrl.pathname, code: parsedUrl.searchParams.get('code') ?? '', state: parsedUrl.searchParams.get('state') ?? '' }); // Hand off validated payload to internal state machine await window.dispatchEvent( new CustomEvent('app:verified-intent', { detail: validatedParams }) ); } catch (error) { console.error('[Security] Malformed or unverified deep-link payload received', error); } }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Cryptographic Intent & Universal Link Verification Guardrail

Capacitor 7 Cryptographic Intent & Universal Link Verification Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces deterministic origin verification and cryptographic domain association for all inbound deep links and intents in Capacitor 7 hybrid applications. Eliminates custom URL scheme hijacking and unauthorized native bridge invocation by restricting state mutation to cryptographically proven Universal Links (iOS) and Android App Links. 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 Trust in Insecure Custom Scheme Intents Driving Privileged Native Bridge Actions 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 Trust in Insecure Custom Scheme Intents Driving Privileged Native Bridge Actions	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 execute privileged native bridge actions or mutate authentication/session state based on custom URL schemes (e.g., myapp

Engineers MUST NEVER execute privileged native bridge actions or mutate authentication/session state based on custom URL schemes (e.g., myapp://). Custom schemes are unverified and hijackable by any malicious application installed on the host OS.

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.