Capacitor 7 Biometric Hardware-Backed KeyStore & Secure Enclave Token Guardrail

--- description: Capacitor 7 Biometric Hardware-Backed KeyStore & Secure Enclave Token Guardrail - Enforces hardware-backed cryptographic key generation and authentication-gated storage for offline session tokens in Capacitor 7 applications. Mandates the use of Android StrongBox Keymaster and iOS Secure Enclave with user authentication binding (`setUserAuthenticationRequired` and `kSecAccessControlBiometryAny`) to prevent extraction from memory dumps or compromised root environments. globs: src/**/*.{ts,tsx}, android/app/src/main/java/**/*.java, android/app/src/main/java/**/*.kt, ios/App/App/**/*.swift alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-biometric-keystore-hardware-token-standard" --- # Capacitor 7 Biometric Hardware-Backed KeyStore & Secure Enclave Token Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Storing sensitive session credentials in software-only KeyStore, standard SharedPreferences, iOS Keychain without Secure Enclave access controls, or unencrypted web storage like Preferences/LocalStorage. ## System Constraints You are a Principal Mobile Security Architect enforcing the Capacitor 7 Biometric Hardware-Backed KeyStore Token Standard. You must mandate that all offline sensitive session tokens, cryptographic seed phrases, and high-privilege refresh tokens use asymmetric or hardware-backed AES/GCM keys protected by Android StrongBox KeyStore and iOS Secure Enclave. Plaintext tokens must never hit unmanaged web runtimes or persistent unencrypted memory. ## Strict Guidelines - Engineers MUST ALWAYS require biometric authentication flags (`kSecAccessControlBiometryCurrentSet` or `setUserAuthenticationRequired(true)`) when provisioning hardware-backed credentials. - Engineers MUST NOT fall back to software-emulated keystores or standard Web Storage API (`localStorage`, `sessionStorage`, `@capacitor/preferences`) for auth tokens under any circumstances. - Native plugins MUST request Android StrongBox backing (`setIsStrongBoxBacked(true)`) when available on Android API 28+, falling back to standard TEE (Trusted Execution Environment) hardware Keymaster only if StrongBox is physically unavailable. - Services MUST zero out sensitive raw binary buffers and ephemeral strings immediately after biometric-gated cryptographic signing or decryption completes. - Hybrid bridges MUST NEVER pass master refresh tokens across the JavaScript bridge as cleartext strings that persist in WebView memory; instead, sign authentication payloads natively via hardware keys. ## Bad vs Good Implementations ### Insecure Storage via Capacitor Preferences vs Hardware-Backed Biometric Secure Storage Bridge #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Storing session tokens via @capacitor/preferences writes raw base64 or plaintext strings to SharedPreferences on Android and NSUserDefaults on iOS, leaving tokens trivial to extract via simple filesystem access or runtime memory inspection. ```typescript import { Preferences } from '@capacitor/preferences'; export async function persistSessionToken(rawToken: string): Promise<void> { // CRITICAL VULNERABILITY: Cleartext stored in SharedPreferences / NSUserDefaults // Memory and disk inspectable on rooted/jailbroken devices await Preferences.set({ key: 'auth_session_token', value: rawToken, }); } export async function getSessionToken(): Promise<string | null> { const result = await Preferences.get({ key: 'auth_session_token' }); return result.value; } ``` #### Production Standard (Correct) > **Standard**: Leverages a hardware-backed native bridge enforcing Secure Enclave and StrongBox Keymaster. Raw tokens are protected by native hardware boundaries requiring physical biometric gating (Touch ID, Face ID, BiometricPrompt) to perform cryptographic operations. ```typescript import { registerPlugin } from '@capacitor/core'; export interface SecureBiometricKeyStorePlugin { storeSessionSecret(options: { alias: string; secret: string; requireStrongBox?: boolean }): Promise<{ success: boolean }>; executeGatedSignature(options: { alias: string; payload: string; promptMessage: string }): Promise<{ signature: string }>; } const SecureKeyStore = registerPlugin<SecureBiometricKeyStorePlugin>('SecureBiometricKeyStore'); export async function saveHardwareEncryptedToken(alias: string, secret: string): Promise<void> { // Invariant: Native implementation routes to KeyGenParameterSpec with StrongBox/TEE // and iOS kSecAttrAccessControl with Secure Enclave biometry requirement await SecureKeyStore.storeSessionSecret({ alias, secret, requireStrongBox: true, }); } export async function signWithBiometricKey(alias: string, challenge: string): Promise<string> { const response = await SecureKeyStore.executeGatedSignature({ alias, payload: challenge, promptMessage: 'Authenticate to authorize device session', }); return response.signature; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Biometric Hardware-Backed KeyStore & Secure Enclave Token Guardrail

Capacitor 7 Biometric Hardware-Backed KeyStore & Secure Enclave Token Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces hardware-backed cryptographic key generation and authentication-gated storage for offline session tokens in Capacitor 7 applications. Mandates the use of Android StrongBox Keymaster and iOS Secure Enclave with user authentication binding (`setUserAuthenticationRequired` and `kSecAccessControlBiometryAny`) to prevent extraction from memory dumps or compromised root environments. 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: Storing sensitive session credentials in software-only KeyStore, standard SharedPreferences, iOS Keychain without Secure Enclave access controls, or unencrypted web storage like Preferences/LocalStorage. 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	Storing sensitive session credentials in software-only KeyStore, standard SharedPreferences, iOS Keychain without Secure Enclave access controls, or unencrypted web storage like Preferences/LocalStorage.	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 require biometric authentication flags (`kSecAccessControlBiometryCurrentSet` or `setUserAuthenticationRequired(true)`) when provisioning hardware-backed credentials.

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.