Capacitor 7 Universal Link Cryptographic Route Intent Attestation

--- description: Capacitor 7 Universal Link Cryptographic Route Intent Attestation - Mandates strict origin-bound verification, hostname enforcement, and cryptographic intent attestation for incoming Universal Links and App Links in Capacitor 7 applications. Precludes authorization code hijacking, parameter injection, and malicious intra-app payload routing caused by trusting unauthenticated custom URI schemes and deep link events. globs: src/**/deepLink*.{ts,tsx}, src/**/app*.{ts,tsx}, src/**/router*.{ts,tsx}, src/main.{ts,tsx}, src/App.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor7-universal-link-route-intent-attestation" --- # Capacitor 7 Universal Link Cryptographic Route Intent Attestation > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Directly Dispatching Navigation or Mutating State from Unverified Deep Link Payloads ## System Constraints You are a Principal Mobile Architect enforcing strict cryptographic route intent attestation and domain validation for Capacitor 7 Universal Links. Reject unvalidated deep link handlers, unauthenticated custom schemes, and direct propagation of URL parameters into application state. ## Strict Guidelines - Engineers MUST ALWAYS enforce strict origin and protocol validation on incoming URLs from App.addListener('appUrlOpen'), asserting that protocol is 'https:' and hostname strictly matches pre-configured trusted domains. - Engineers MUST NOT trust arbitrary custom URI schemes (e.g., 'myapp://') for privileged routes, auth callbacks, or state mutations; enforce Universal Links (iOS) and Android App Links (Digital Asset Links). - Services MUST verify incoming state payloads with cryptographic intent attestation (e.g., verifying a locally generated ephemeral PKCE verifier or non-deterministic state nonce in secure storage) before mutating session or auth state. - Handlers MUST parse incoming deep link URLs using standard URL parsers and strictly validate all query parameters against a runtime schema (e.g., Zod) prior to dispatching. - Components NEVER execute immediate routing or sensitive operational flows directly from unverified global deep-link event listeners without passing through a dedicated, validated intent-attestation barrier. ## Bad vs Good Implementations ### Universal Link Intent Verification Barrier #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The handler blindly accepts any protocol (including hijackable custom URL schemes), executes no hostname check against trusted Universal Link origins, and immediately processes tokens and navigation without cryptographic nonce or schema validation. ```typescript import { App } from '@capacitor/app'; import { router } from './router'; import { authStore } from './auth'; // CRITICAL VULNERABILITY: Blindly trust incoming custom scheme or unverified URL App.addListener('appUrlOpen', (event) => { const url = new URL(event.url); // Accepts arbitrary schemes (e.g., myapp://evil.com/auth) // Direct auth code / token harvesting and open redirection const token = url.searchParams.get('token'); if (token) { authStore.setToken(token); } router.push(url.pathname); }); ``` #### Production Standard (Correct) > **Standard**: Production invariant compliant implementation ensuring memory safety, deterministic execution, and zero runtime hallucination. ```typescript import { App, URLOpenListenerEvent } from '@capacitor/app'; import { z } from 'zod'; import { router } from './router'; import { secureNonceStore } from './security/nonce-store'; import { authService } from './services/auth'; const ALLOWED_ORIGIN = 'https://auth.example.com'; const DeepLinkPayloadSchema = z.object({ code: z.string().min(16).max(256), state: z.string().uuid() }); export async function handleAppUrlOpen(event: URLOpenListenerEvent): Promise<void> { try { const url = new URL(event.url); // 1. Strict Protocol and Origin Verification if (url.origin !== ALLOWED_ORIGIN) { console.error(`Rejected unauthorized deep link origin: ${url.origin}`); return; } if (url.pathname === '/auth/callback') { // 2. Schema Validation of Parameters const rawParams = Object.fromEntries(url.searchParams.entries()); const { code, state } = DeepLinkPayloadSchema.parse(rawParams); // 3. Cryptographic Route Intent Attestation (Anti-CSRF / Anti-Hijacking) const isValidNonce = await secureNonceStore.consumeNonce(state); if (!isValidNonce) { throw new Error('Cryptographic route intent mismatch: Invalid or expired state nonce.'); } await authService.exchangeAuthCode(code); await router.push('/dashboard'); } } catch (error) { console.error('Deep link attestation rejected:', error); await router.push('/security-alert'); } } App.addListener('appUrlOpen', handleAppUrlOpen); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Universal Link Cryptographic Route Intent Attestation

Capacitor 7 Universal Link Cryptographic Route Intent Attestation defines an industrial-grade behavioral standard for mobile engineering. Mandates strict origin-bound verification, hostname enforcement, and cryptographic intent attestation for incoming Universal Links and App Links in Capacitor 7 applications. Precludes authorization code hijacking, parameter injection, and malicious intra-app payload routing caused by trusting unauthenticated custom URI schemes and deep link events. 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 Dispatching Navigation or Mutating State from Unverified Deep Link Payloads 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 Dispatching Navigation or Mutating State from Unverified Deep Link Payloads	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 enforce strict origin and protocol validation on incoming URLs from App.addListener('appUrlOpen'), asserting that protocol is 'https

Engineers MUST ALWAYS enforce strict origin and protocol validation on incoming URLs from App.addListener('appUrlOpen'), asserting that protocol is 'https:' and hostname strictly matches pre-configured trusted domains.

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.