Capacitor 7 Biometric Hardware-Backed Secure Enclave Bridge Standard

--- description: Capacitor 7 Biometric Hardware-Backed Secure Enclave Bridge Standard - Enforces cryptographic isolation between the hybrid Capacitor WebView and native secure hardware (iOS Secure Enclave and Android KeyStore StrongBox). Mandates that raw private keys, biometrically unlocked symmetric secrets, and plain credentials never cross the bridge into the dynamic JavaScript DOM runtime, mitigating XSS, malicious deep-link invocations, and unauthorized WebView inspections. globs: src/**/*.{ts,tsx,js,jsx}, ios/App/App/**/*.{swift,h,m}, android/app/src/main/java/**/*.{java,kt} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-biometric-secure-enclave-bridge-standard" --- # Capacitor 7 Biometric Hardware-Backed Secure Enclave Bridge Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Exporting Raw Private Keys or Cleartext Secrets Across the Capacitor Bridge into WebView Contexts ## System Constraints You are a Principal Mobile Security Architect enforcing the Capacitor 7 Biometric Hardware-Backed Secure Enclave Bridge Standard. You must mandate that raw cryptographic material, non-ephemeral authentication tokens, and private keys never cross the JavaScript-to-Native bridge. All cryptographic operations requiring biometrics (kSecAccessControlBiometryAny/BiometricPrompt) must execute strictly on-chip inside platform hardware enclaves. Deep-link handlers and dynamic WebView contexts must only receive one-time, opaque, ephemeral operation handles or cryptographic signatures verified on a remote backend. ## Strict Guidelines - Engineers MUST ALWAYS enforce platform hardware-level attestation and key generation (kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly or Android KeyProperties.PURPOSE_SIGN with setUserAuthenticationRequired(true)). - Engineers MUST NOT return raw private keys, plain master secrets, or unencrypted biometric payload strings across the Capacitor bridge to the WebView. - Code SHOULD verify deep-link payload integrity and user presence before permitting the native layer to invoke biometric hardware signing operations. - Services MUST execute all asymmetric signing and key derivation inside native code (Swift/Kotlin plugins), transmitting only ephemeral digital signatures or opaque session IDs to JavaScript. - Components NEVER store biometrically unlocked cryptographic material in Capacitor Preferences, LocalStorage, IndexedDB, or memory-mapped JavaScript objects. ## Bad vs Good Implementations ### Biometric Authentication & Hardware-Bound Transaction Signing #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Exporting the raw cryptographic key or secret into the WebView DOM exposes it directly to Cross-Site Scripting (XSS), devtools inspection, memory dumps, and compromised dynamic dependencies. ```typescript import { registerPlugin } from '@capacitor/core'; interface InsecureBiometricPlugin { // VULNERABILITY: Raw secret retrieved from Keychain across the bridge into DOM getBiometricSecret(options: { prompt: string }): Promise<{ privateKeyPem: string }>; } const InsecureVault = registerPlugin<InsecureBiometricPlugin>('InsecureVault'); export async function signPayload(payload: string): Promise<string> { const { privateKeyPem } = await InsecureVault.getBiometricSecret({ prompt: 'Authorize Transaction' }); // Any injected DOM script or XSS payload can intercept 'privateKeyPem' return localJsSign(payload, privateKeyPem); } ``` #### Production Standard (Correct) > **Standard**: Keeps private cryptographic keys locked within the Secure Enclave or Android StrongBox. The WebView passes an immutable challenge to the native layer, which prompts for biometrics and returns only the resulting signature, ensuring zero private material leakage. ```typescript import { registerPlugin } from '@capacitor/core'; interface SecureBridgePlugin { // INVARIANT: Native side signs inside Enclave/KeyStore; raw keys never cross the bridge signWithHardwareKey(options: { challenge: string; promptMessage: string; allowedOrigin: string; }): Promise<{ signature: string; keyId: string }>; } const SecureBridge = registerPlugin<SecureBridgePlugin>('SecureEnclaveBridge'); export async function signPayload(challengeHex: string): Promise<{ signature: string; keyId: string }> { if (!/^[a-fA-F0-9]{64}$/.test(challengeHex)) { throw new Error('Invalid challenge format: must be 256-bit hex'); } // Hardware-backed signing occurs entirely in native Swift/Kotlin return await SecureBridge.signWithHardwareKey({ challenge: challengeHex, promptMessage: 'Confirm Authentication with Biometrics', allowedOrigin: window.location.origin }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Biometric Hardware-Backed Secure Enclave Bridge Standard

Capacitor 7 Biometric Hardware-Backed Secure Enclave Bridge Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces cryptographic isolation between the hybrid Capacitor WebView and native secure hardware (iOS Secure Enclave and Android KeyStore StrongBox). Mandates that raw private keys, biometrically unlocked symmetric secrets, and plain credentials never cross the bridge into the dynamic JavaScript DOM runtime, mitigating XSS, malicious deep-link invocations, and unauthorized WebView inspections. 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: Exporting Raw Private Keys or Cleartext Secrets Across the Capacitor Bridge into WebView Contexts 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	Exporting Raw Private Keys or Cleartext Secrets Across the Capacitor Bridge into WebView Contexts	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 platform hardware-level attestation and key generation (kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly or Android KeyProperties.PURPOSE_SIGN with setUserAuthenticationRequired(true)).

Engineers MUST ALWAYS enforce platform hardware-level attestation and key generation (kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly or Android KeyProperties.PURPOSE_SIGN with setUserAuthenticationRequired(true)).

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.