Capacitor 7 Verified App Links Cryptographic Attestation Invariant

--- description: Capacitor 7 Verified App Links Cryptographic Attestation Invariant - Enforces strict origin verification and cryptographic domain attestation for deep links ingested via Capacitor 7 before delegating control to the embedded WebView router. Prevents cross-app intent spoofing, parameter tampering, and state injection attacks caused by untrusted custom URL schemes or unverified Android App Links and iOS Universal Links. globs: src/**/*.{ts,tsx,js,jsx}, android/app/src/main/AndroidManifest.xml, ios/App/App/AppDelegate.swift alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-verified-app-links-cryptographic-attestation" --- # Capacitor 7 Verified App Links Cryptographic Attestation Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Blind Ingestion of Deep-Link Payloads and State Hydration via Unverified Custom Schemes ## System Constraints You are a Principal Mobile Security Architect enforcing the Capacitor 7 Verified App Links Cryptographic Attestation Invariant. You must reject any deep link handling implementation that blindly parses incoming URLs from custom URI schemes or unverified origins without validating SHA-256 asset fingerprints or Apple App Site Association (AASA) entitlements prior to routing or state hydration. ## Strict Guidelines - Engineers MUST ALWAYS restrict deep-link intake exclusively to verified Universal Links and Android App Links (`https://`) backed by cryptographic Digital Asset Links (assetlinks.json SHA-256) and AASA domains. - Engineers MUST NOT extract sensitive tokens, session credentials, or administrative state directly from URL query parameters ingested via App.addListener('appUrlOpen', ...). - Code SHOULD validate the full URL origin against an immutable compile-time allowlist of verified domains before invoking any internal router transitions. - Services MUST sanitize, validate, and parse deep-link parameters using strict type validators (such as Zod) before executing business logic. - Components NEVER invoke side-effects or state store mutations (e.g., auth, payment, user impersonation) directly from unverified deep-link payloads without backend challenge-response validation. ## Bad vs Good Implementations ### Capacitor 7 Deep Link Intake and Cryptographic Origin Validation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The code blindly accepts events from custom schemes (e.g. `myapp://`) without validating that the link originated from a cryptographically verified Digital Asset Link or Universal Link. It also extracts an authentication token directly from URL query parameters, enabling session hijack via intent interception. ```typescript import { App } from '@capacitor/app'; import { useRouter } from 'vue-router'; import { useAuthStore } from '@/stores/auth'; export function setupDeepLinks() { const router = useRouter(); const authStore = useAuthStore(); // VULNERABLE: Ingests any custom scheme or spoofed intent without domain attestation App.addListener('appUrlOpen', (event) => { const url = new URL(event.url); // Blindly trusting query parameters to mutate authentication state const authToken = url.searchParams.get('token'); if (authToken) { authStore.setSessionToken(authToken); } // Open redirect vulnerability inside the embedded webview const targetPath = url.pathname + url.search; router.push(targetPath); }); } ``` #### Production Standard (Correct) > **Standard**: Enforces origin verification against an immutable allowlist matching the app's cryptographic attestation (Android App Links SHA-256 fingerprint / iOS Universal Links). Uses a strict Zod schema for parameter parsing and rejects token-in-URL anti-patterns. ```typescript import { App, URLOpenListenerEvent } from '@capacitor/app'; import { z } from 'zod'; const VERIFIED_ORIGINS = Object.freeze([ 'https://auth.production.example.com', 'https://app.production.example.com' ] as const); const SafeDeepLinkParamsSchema = z.object({ action: z.enum(['reset-password', 'view-transaction']), ticketId: z.string().uuid() }); export function setupSecureDeepLinks( navigateCallback: (path: string, params: z.infer<typeof SafeDeepLinkParamsSchema>) => void ) { App.addListener('appUrlOpen', (event: URLOpenListenerEvent) => { try { const parsedUrl = new URL(event.url); // Invariant: Enforce HTTPS scheme and verified domain attestation const isVerifiedOrigin = VERIFIED_ORIGINS.some( (origin) => parsedUrl.origin.toLowerCase() === origin.toLowerCase() ); if (!isVerifiedOrigin) { console.error(`Rejected unverified deep-link origin: ${parsedUrl.origin}`); return; } // Enforce strict payload validation; never accept raw tokens via URL params const rawParams = Object.fromEntries(parsedUrl.searchParams.entries()); const validated = SafeDeepLinkParamsSchema.safeParse(rawParams); if (!validated.success) { console.error('Invalid deep-link payload schema', validated.error); return; } // Route safely using vetted path and validated parameters navigateCallback(parsedUrl.pathname, validated.data); } catch (err) { console.error('Failed to parse incoming deep-link payload', err); } }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Verified App Links Cryptographic Attestation Invariant

Capacitor 7 Verified App Links Cryptographic Attestation Invariant defines an industrial-grade behavioral standard for mobile engineering. Enforces strict origin verification and cryptographic domain attestation for deep links ingested via Capacitor 7 before delegating control to the embedded WebView router. Prevents cross-app intent spoofing, parameter tampering, and state injection attacks caused by untrusted custom URL schemes or unverified Android App Links and iOS Universal 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 Ingestion of Deep-Link Payloads and State Hydration via Unverified Custom Schemes 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 Ingestion of Deep-Link Payloads and State Hydration via Unverified Custom Schemes	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 restrict deep-link intake exclusively to verified Universal Links and Android App Links (`https

Engineers MUST ALWAYS restrict deep-link intake exclusively to verified Universal Links and Android App Links (`https://`) backed by cryptographic Digital Asset Links (assetlinks.json SHA-256) and AASA 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.