Capacitor 7 Hardware-Backed Biometric Key Isolation Standard

--- description: Capacitor 7 Hardware-Backed Biometric Key Isolation Standard - Enforces asymmetric challenge-response authentication anchored in native Secure Enclave and Android KeyStore primitives to eliminate WebView bridge token sniffing. Mandates that cryptographic private keys and long-lived session secrets never enter JavaScript memory or standard persistent storage, restricting bridge communication strictly to ephemeral nonces and hardware-signed cryptographic assertions. globs: src/**/*.{ts,tsx}, ios/App/App/**/*.{swift,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-hardware-key-isolation-standard" --- # Capacitor 7 Hardware-Backed Biometric Key Isolation Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Persisting Raw Bearer Tokens in JavaScript Storage and Relying on Boolean Biometric Checks ## System Constraints You are a Principal Mobile Security Architect enforcing the Capacitor 7 Biometric Hardware-Key Isolation Standard. Your duty is to prevent token interception across the hybrid bridge. Never permit storing long-lived JWTs or authentication secrets in JavaScript storage (localStorage, IndexedDB, Capacitor Preferences). Mandate asymmetric key generation inside Apple Secure Enclave (kSecAttrAccessControl with biometryCurrentSet) and Android KeyStore (KeyGenParameterSpec with setUserAuthenticationRequired). The bridge must only transmit server-generated nonces and receive native hardware-signed assertions. ## Strict Guidelines - Engineers MUST NEVER persist raw authorization tokens (e.g., Bearer JWTs, session cookies) in web storage primitives (`localStorage`, `sessionStorage`, `IndexedDB`) or unencrypted `@capacitor/preferences`. - Engineers MUST NOT decouple biometric verification from cryptographic operations (e.g., calling `NativeBiometric.verifyIdentity()` and subsequently reading a plaintext token upon a boolean `true` response). - Native plugins MUST generate asymmetric key pairs strictly inside hardware-isolated modules (iOS Secure Enclave via `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly` + `biometryCurrentSet`; Android KeyStore with `KeyProperties.PURPOSE_SIGN` and `setUserAuthenticationRequired(true)`). - Bridge communication MUST strictly exchange ephemeral, single-use cryptographically random server challenges and return hardware-signed payloads, ensuring private key material never leaves native memory. - Mobile services MUST invalidate the hardware-bound session if biometric enrollment changes (e.g., new fingerprints or facial profiles added to the OS) using OS-level biometric domain state checks. ## Bad vs Good Implementations ### Biometric Authentication Pattern #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Performs a detached boolean biometric check and retrieves a long-lived plaintext token via Capacitor Preferences. Attackers with WebView XSS or runtime instrumentation (Frida) can intercept the token or spoof the boolean result. ```typescript import { Preferences } from '@capacitor/preferences'; import { NativeBiometric } from 'capacitor-native-biometric'; export async function authenticateAndGetToken(): Promise<string> { // VULNERABLE: Boolean-only check susceptible to bridge interception // and runtime hook bypass (e.g., Frida) const result = await NativeBiometric.verifyIdentity({ reason: 'Authenticate to access your account', }); if (result.success) { // INSECURE: Plaintext token stored in bridge-accessible storage const { value } = await Preferences.get({ key: 'auth_bearer_token' }); if (!value) throw new Error('Token not found'); return value; } throw new Error('Biometric authentication failed'); } ``` #### Production Standard (Correct) > **Standard**: Delegates cryptographic operations directly to the native Secure Enclave or Android KeyStore. The native module prompts for biometrics as part of the signing ceremony, returning only the cryptographic signature over an ephemeral challenge. ```typescript import { registerPlugin } from '@capacitor/core'; interface HardwareKeyPlugin { signChallenge(options: { challenge: string; keyAlias: string }): Promise<{ signature: string }>; getPublicKey(options: { keyAlias: string }): Promise<{ publicKey: string }>; } const HardwareKey = registerPlugin<HardwareKeyPlugin>('HardwareKey'); export async function authenticateSession(challengeNonce: string): Promise<string> { // SECURE: Challenge is signed directly within Secure Enclave / Android KeyStore // No raw private keys or permanent bearer tokens ever cross the hybrid bridge try { const { signature } = await HardwareKey.signChallenge({ challenge: challengeNonce, keyAlias: 'auth_key_v1' }); // Only the hardware-signed assertion is returned across the bridge return signature; } catch (error) { // Fails automatically if biometrics fail or enrollments change throw new Error(`Hardware authentication rejected: ${(error as Error).message}`); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Hardware-Backed Biometric Key Isolation Standard

Capacitor 7 Hardware-Backed Biometric Key Isolation Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces asymmetric challenge-response authentication anchored in native Secure Enclave and Android KeyStore primitives to eliminate WebView bridge token sniffing. Mandates that cryptographic private keys and long-lived session secrets never enter JavaScript memory or standard persistent storage, restricting bridge communication strictly to ephemeral nonces and hardware-signed cryptographic assertions. 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: Persisting Raw Bearer Tokens in JavaScript Storage and Relying on Boolean Biometric Checks 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	Persisting Raw Bearer Tokens in JavaScript Storage and Relying on Boolean Biometric Checks	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 NEVER persist raw authorization tokens (e.g., Bearer JWTs, session cookies) in web storage primitives (`localStorage`, `sessionStorage`, `IndexedDB`) or unencrypted `@capacitor/preferences`.

Engineers MUST NEVER persist raw authorization tokens (e.g., Bearer JWTs, session cookies) in web storage primitives (`localStorage`, `sessionStorage`, `IndexedDB`) or unencrypted `@capacitor/preferences`.

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.