Hardware-Backed Enclave Biometric Attestation Invariant for Capacitor 7

--- description: Hardware-Backed Enclave Biometric Attestation Invariant for Capacitor 7 - Enforces cryptographic payload signing inside Apple Secure Enclave or Android StrongBox Keymaster during biometric authentication in Capacitor 7 applications. Mitigates rogue WebView bridge interception, memory hooking (Frida/Xposed), and MITM exploits by prohibiting naive boolean biometric resolutions. All biometric authorizations must return an asymmetric cryptographic signature generated natively across a hardware-bound key paired with a server-issued challenge. globs: src/**/*.{ts,tsx}, ios/App/**/*.{swift,m}, android/app/**/*.{kt,java} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-enclave-biometric-attestation" --- # Hardware-Backed Enclave Biometric Attestation Invariant for Capacitor 7 > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Trusting Insecure Boolean Bridge Responses for Biometric Verification Without Hardware Attestation ## System Constraints You are a Principal Mobile Security Architect enforcing zero-trust hardware attestation for Capacitor 7 hybrid applications. You must enforce that no sensitive authorization or authentication decision relies on a boolean result over the Capacitor WebView bridge. You mandate hardware-backed asymmetric cryptographic signing within Apple Secure Enclave (iOS) or Android StrongBox KeyStore, bound to a fresh server challenge and strictly gated by biometric presence flags. ## Strict Guidelines - Engineers MUST ALWAYS enforce that biometric authorization plugins return a DER/ASN.1 cryptographic signature and hardware attestation metadata, never a raw boolean flag. - Engineers MUST NOT persist or execute transaction authorizations without validating a server-derived cryptographic nonce that was signed by a hardware-backed private key. - Services MUST verify the generated biometric signature server-side against the public key registered during hardware onboarding before executing privileged operations. - Native plugins MUST configure private keys with SecAccessControlCreateFlags (iOS: kSecAccessControlBiometryCurrentSet or kSecAccessControlUserPresence) or KeyProperties (Android: PURPOSE_SIGN with setUserAuthenticationRequired(true) and setIsStrongBoxBacked(true)). - Components NEVER store private keys in software keystores, localStorage, IndexedDB, or standard Capacitor SecureStorage plugins. ## Bad vs Good Implementations ### Naive Boolean Biometric Check vs Hardware Enclave Signed Attestation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The client treats a boolean 'success: true' response across the Capacitor JavaScript bridge as proof of authentication. An attacker using Frida or an injected script inside a compromised WebView can easily hook or mock the bridge call and trigger unauthorized financial transfers. ```typescript import { NativeBiometric } from 'capacitor-native-biometric'; export async function authorizeTransaction(amount: number, recipientId: string): Promise<boolean> { // VULNERABLE: Boolean response over WebView bridge is trivial to bypass with Frida // or by monkey-patching window.Capacitor.toNative. const result = await NativeBiometric.verifyIdentity({ reason: 'Confirm high-value transaction', title: 'Biometric Verification' }); if (result.success) { await api.post('/transactions/transfer', { amount, recipientId }); return true; } return false; } ``` #### Production Standard (Correct) > **Standard**: The authorization relies on cryptographic signature generation inside the hardware enclave (Secure Enclave / Android StrongBox). Even if the bridge or memory is tampered with, an attacker cannot forge the elliptic curve signature over the ephemeral server nonce without physical biometric activation. ```typescript import { HardwareEnclaveAuth } from '@company/capacitor-hardware-enclave'; export interface TransactionAttestation { signature: string; nonce: string; keyId: string; payloadHash: string; } export async function authorizeTransaction( amount: number, recipientId: string ): Promise<void> { // 1. Fetch ephemeral server nonce to prevent replay attacks const { nonce } = await api.post<{ nonce: string }>('/auth/biometric/challenge'); // 2. Prepare payload to be committed inside the hardware enclave const payload = JSON.stringify({ amount, recipientId, nonce }); // 3. Hardware enclave performs biometric prompt natively and signs payload inside Secure Enclave/StrongBox const attestation: TransactionAttestation = await HardwareEnclaveAuth.signWithBiometrics({ keyAlias: 'com.app.auth.transaction-key', promptTitle: 'Authorize Transaction', promptSubtitle: `Transfer $${amount} to ${recipientId}`, payloadToSign: payload }); // 4. Server receives signature and raw payload, cryptographically verifying the enclave key and signature await api.post('/transactions/transfer', { payload, attestation }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Hardware-Backed Enclave Biometric Attestation Invariant for Capacitor 7

Hardware-Backed Enclave Biometric Attestation Invariant for Capacitor 7 defines an industrial-grade behavioral standard for mobile engineering. Enforces cryptographic payload signing inside Apple Secure Enclave or Android StrongBox Keymaster during biometric authentication in Capacitor 7 applications. Mitigates rogue WebView bridge interception, memory hooking (Frida/Xposed), and MITM exploits by prohibiting naive boolean biometric resolutions. All biometric authorizations must return an asymmetric cryptographic signature generated natively across a hardware-bound key paired with a server-issued challenge. 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 Insecure Boolean Bridge Responses for Biometric Verification Without Hardware Attestation 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 Insecure Boolean Bridge Responses for Biometric Verification Without Hardware Attestation	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 that biometric authorization plugins return a DER/ASN.1 cryptographic signature and hardware attestation metadata, never a raw boolean flag.

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.