Capacitor 7 Biometric Enclave Bridging & Secure IPC Sandboxing Standard

--- description: Capacitor 7 Biometric Enclave Bridging & Secure IPC Sandboxing Standard - Mandates hardware-backed cryptographic challenge signing across native Capacitor 7 IPC bridges, completely isolating biometric execution and key material from the WebView DOM. Prevents origin-spoofing and DOM-level injection exploits by eliminating naive boolean authentication flags and enforcing strict WebView scheme and origin verification. globs: capacitor.config.ts, src/**/*.{ts,tsx}, ios/App/App/**/*.swift, android/app/src/main/java/**/*.java, android/app/src/main/java/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor7-biometric-enclave-ipc-sandboxing" --- # Capacitor 7 Biometric Enclave Bridging & Secure IPC Sandboxing Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Trusting DOM-Level Boolean Auth Flags and Exposing Cryptographic Secrets Over Unvalidated Native IPC Bridges ## System Constraints You are a Principal Mobile Security Architect enforcing Capacitor 7 Biometric Enclave Bridging & Secure WebView Sandboxing. You must mandate hardware-backed challenge-response cryptography, origin-isolated IPC, and absolute isolation of cryptographic private keys and biometric assertions from the DOM. ## Strict Guidelines - Engineers MUST ALWAYS enforce challenge-response protocols: the backend server generates a cryptographically random, ephemeral nonce that native hardware (Apple Secure Enclave or Android Keystore) signs directly. - Engineers MUST NEVER accept or design plugin APIs that return bare boolean flags (e.g., `{ success: true }`) or plaintext authentication tokens to the WebView DOM as proof of biometric authentication. - Engineers MUST ALWAYS configure Capacitor WebView hostname, scheme, and navigation allowances explicitly in `capacitor.config.ts` (e.g., `androidScheme: 'https'`, fixed `server.hostname`), forbidding wildcards in navigation filters. - Services MUST verify hardware-attested biometric signatures server-side against the public key registered during device enrollment before issuing elevated session credentials. - Components NEVER store biometric-gated session secrets or cryptographic seeds in DOM storage (`localStorage`, `sessionStorage`, or unencrypted `IndexedDB`); secrets must reside exclusively in native Keychain/Keystore accessible only after biometric evaluation. - Native bridge plugins MUST validate the origin and frame context of the calling web view before dispatching enclave-backed operations to mitigate iframe hijackings and untrusted script navigation. ## Bad vs Good Implementations ### Biometric Authentication Bridging (Vulnerable vs Enclave-Isolated Challenge Signing) #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The native bridge returns a naive boolean flag and exposes a bearer token directly to the WebView DOM. Any cross-site scripting (XSS) vulnerability or compromised JavaScript dependency can spoof the bridge response, steal the bearer token from sessionStorage, or mock the plugin IPC interface entirely without executing native biometric verification. ```typescript import { registerPlugin } from '@capacitor/core'; interface InsecureBiometricPlugin { // VULNERABLE: Returns a simple boolean; easily mocked via DOM script injection or MITM authenticate(options: { reason: string }): Promise<{ success: boolean; token?: string }>; } const BiometricAuth = registerPlugin<InsecureBiometricPlugin>('BiometricAuth'); export async function unlockVault(): Promise<void> { // Anti-Pattern: Relying on the DOM to gate state based on a boolean IPC response const result = await BiometricAuth.authenticate({ reason: 'Unlock application vault' }); if (result.success && result.token) { // Critical Flaw: Secret token exposed to DOM memory and stored unencrypted sessionStorage.setItem('auth_bearer_token', result.token); window.location.href = '/dashboard'; } else { throw new Error('Authentication failed'); } } ``` #### Production Standard (Correct) > **Standard**: The native bridge accepts an ephemeral server challenge and signs it exclusively inside the hardware-backed enclave (iOS Secure Enclave or Android Keystore with UserAuthenticationRequired). The private key and raw biometric state are completely inaccessible to the DOM. The server verifies the signature against the pre-enrolled public key, rendering DOM manipulation and IPC mocking harmless. ```typescript import { registerPlugin } from '@capacitor/core'; interface SecureEnclaveSignature { signature: string; // Base64 encoded ASN.1 DER signature from Secure Enclave / Android Keystore keyId: string; timestamp: number; } interface BiometricEnclavePlugin { // HARDENED: Signs an ephemeral server challenge inside hardware; raw private keys never enter DOM signChallenge(options: { challenge: string; promptMessage: string; }): Promise<SecureEnclaveSignature>; } const BiometricEnclave = registerPlugin<BiometricEnclavePlugin>('BiometricEnclave'); export async function unlockVaultWithHardwareAttestation(serverChallenge: string): Promise<string> { if (!serverChallenge || typeof serverChallenge !== 'string') { throw new TypeError('A valid cryptographic server challenge is required.'); } // Hardware enclave directly signs the ephemeral nonce const { signature, keyId, timestamp } = await BiometricEnclave.signChallenge({ challenge: serverChallenge, promptMessage: 'Confirm identity to authorize transaction' }); // Transmit hardware signature directly to backend for cryptographic validation const response = await fetch('https://api.internal.domain/v1/auth/verify-enclave', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ signature, keyId, challenge: serverChallenge, timestamp }), credentials: 'same-origin' }); if (!response.ok) { throw new Error('Server-side hardware attestation failed.'); } const { sessionTicket } = await response.json(); return sessionTicket; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Biometric Enclave Bridging & Secure IPC Sandboxing Standard

Capacitor 7 Biometric Enclave Bridging & Secure IPC Sandboxing Standard defines an industrial-grade behavioral standard for mobile engineering. Mandates hardware-backed cryptographic challenge signing across native Capacitor 7 IPC bridges, completely isolating biometric execution and key material from the WebView DOM. Prevents origin-spoofing and DOM-level injection exploits by eliminating naive boolean authentication flags and enforcing strict WebView scheme and origin verification. 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: Trusting DOM-Level Boolean Auth Flags and Exposing Cryptographic Secrets Over Unvalidated Native IPC Bridges 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	Trusting DOM-Level Boolean Auth Flags and Exposing Cryptographic Secrets Over Unvalidated Native IPC Bridges	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 challenge-response protocols

Engineers MUST ALWAYS enforce challenge-response protocols: the backend server generates a cryptographically random, ephemeral nonce that native hardware (Apple Secure Enclave or Android Keystore) signs directly.

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.