Capacitor 7 Hardware-Backed StrongBox and Secure Enclave Bridge Protocol

--- description: Capacitor 7 Hardware-Backed StrongBox and Secure Enclave Bridge Protocol - Enforces hardware-backed cryptographic key isolation using Android StrongBox/TEE Keystore and iOS Secure Enclave for Capacitor 7 hybrid mobile applications. Prevents plaintext key exposure across the JavaScript-to-native bridge and guarantees hardware-bound biometric authentication lifecycles with explicit enrollment invalidation. globs: src/**/*.{ts,tsx}, ios/App/App/**/*.swift, android/app/src/main/java/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-hardware-keystore-enclave-bridge" --- # Capacitor 7 Hardware-Backed StrongBox and Secure Enclave Bridge Protocol > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Software-Emulated Keystore Fallback and Plaintext Key Transit Over Web-Native Bridge ## System Constraints You are a Principal Mobile Security Architect enforcing hardware-backed cryptographic guarantees in Capacitor 7 applications. Your mandate is to prevent reliance on software-backed keystores, unauthenticated SharedPreferences/UserDefaults storage, and insecure FFI transit of sensitive material. Ensure all asymmetric/symmetric keys are bound to Android StrongBox/TEE or Apple Secure Enclave with biometryCurrentSet / setInvalidatedByBiometricEnrollment, ensuring zero-knowledge cryptographic operations where raw keys never cross the WebKit/WebView JavaScript boundary. ## Strict Guidelines - Engineers MUST ALWAYS verify native security evaluation via hardware-backed indicators (Android StrongBox or TEE KeyStore, iOS kSecAttrTokenIDSecureEnclave) prior to persisting high-entropy secrets. - Engineers MUST NOT transmit raw cryptographic private or symmetric master keys across the Capacitor bridge into the JavaScript V8/JavaScriptCore runtime context. - Native plugins MUST enforce biometric authorization at the hardware level using kSecAccessControlBiometryCurrentSet (iOS) or setUserAuthenticationRequired(true) with setInvalidatedByBiometricEnrollment(true) (Android). - Bridge services MUST explicitly catch and classify cryptographic hardware invalidation events (e.g., KeyPermanentlyInvalidatedException or errSecAuthFailed) when new biometrics are enrolled, triggering a deterministic re-keying flow. - Cryptographic operations (signing, decryption, cipher block generation) MUST occur strictly inside native hardware isolation boundaries, returning only ciphertexts, signatures, or ephemeral session tokens to the Web layer. - Components NEVER store sensitive tokens or hardware-bound cryptographic aliases in Capacitor Preferences, localStorage, or unencrypted IndexedDB. ## Bad vs Good Implementations ### Hardware-Enclave Vault Bridge with Invalidation Detection #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Stores sensitive keys using @capacitor/preferences which persists in plaintext XML/plist files. The raw key is exposed in the WebView JavaScript heap, bypasses hardware isolation (TEE/StrongBox/Secure Enclave), and lacks biometric gating or invalidation on biometric enrollment changes. ```typescript import { Preferences } from '@capacitor/preferences'; // VULNERABLE: Soft storage fallback, plaintext keys in JS runtime, // no biometric binding or hardware security verification. export class VaultBridgeService { async storeSessionKey(keyAlias: string, rawKey: string): Promise<void> { // Plaintext key stored in unencrypted SharedPreferences/UserDefaults await Preferences.set({ key: `vault_${keyAlias}`, value: rawKey, }); } async getSessionKey(keyAlias: string): Promise<string | null> { const { value } = await Preferences.get({ key: `vault_${keyAlias}` }); return value; } } ``` #### Production Standard (Correct) > **Standard**: Delegates cryptographic operations directly to native hardware isolation boundaries through a dedicated bridge interface. Validates StrongBox/TEE/Secure Enclave availability, binds key lifecycle to biometric enrollment changes, avoids exposing raw symmetric master keys in JavaScript memory, and handles hardware key invalidation explicitly. ```typescript import { registerPlugin } from '@capacitor/core'; export interface SecureStorageHardwareBridgePlugin { encryptPayload(options: { alias: string; plaintext: string; requireBiometric: boolean; invalidateOnBiometricChange?: boolean; }): Promise<{ ciphertext: string; hardwareSecurityLevel: 'STRONGBOX' | 'TEE' | 'SECURE_ENCLAVE' }>; decryptPayload(options: { alias: string; ciphertext: string; biometricPromptTitle: string; }): Promise<{ plaintext: string }>; isHardwareLevelSupported(): Promise<{ hasSecureEnclaveOrStrongBox: boolean; enrolledBiometrics: boolean; }>; } export const SecureStorageBridge = registerPlugin<SecureStorageHardwareBridgePlugin>('SecureStorageHardwareBridge'); export class EnclaveBoundVaultService { public async secureStoreSecret( keyAlias: string, sensitiveData: string ): Promise<{ ciphertext: string }> { const hardware = await SecureStorageBridge.isHardwareLevelSupported(); if (!hardware.hasSecureEnclaveOrStrongBox) { throw new Error('HARDWARE_SECURITY_VIOLATION: Device lacks isolated enclave/StrongBox execution environment.'); } if (!hardware.enrolledBiometrics) { throw new Error('BIOMETRIC_NOT_ENROLLED: Hardware enclave requires registered biometric credentials.'); } return await SecureStorageBridge.encryptPayload({ alias: keyAlias, plaintext: sensitiveData, requireBiometric: true, invalidateOnBiometricChange: true, }); } public async retrieveSecret(keyAlias: string, ciphertext: string): Promise<string> { try { const result = await SecureStorageBridge.decryptPayload({ alias: keyAlias, ciphertext, biometricPromptTitle: 'Authenticate to access cryptographic enclave', }); return result.plaintext; } catch (error: unknown) { const message = error instanceof Error ? error.message : String(error); if (message.includes('KEY_INVALIDATED') || message.includes('errSecAuthFailed')) { throw new Error('CRYPTOGRAPHIC_ENCLAVE_REVOKED: Keys invalidated due to biometric state change.'); } throw error; } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Hardware-Backed StrongBox and Secure Enclave Bridge Protocol

Capacitor 7 Hardware-Backed StrongBox and Secure Enclave Bridge Protocol defines an industrial-grade behavioral standard for mobile engineering. Enforces hardware-backed cryptographic key isolation using Android StrongBox/TEE Keystore and iOS Secure Enclave for Capacitor 7 hybrid mobile applications. Prevents plaintext key exposure across the JavaScript-to-native bridge and guarantees hardware-bound biometric authentication lifecycles with explicit enrollment invalidation. 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: Software-Emulated Keystore Fallback and Plaintext Key Transit Over Web-Native Bridge 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	Software-Emulated Keystore Fallback and Plaintext Key Transit Over Web-Native Bridge	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 verify native security evaluation via hardware-backed indicators (Android StrongBox or TEE KeyStore, iOS kSecAttrTokenIDSecureEnclave) prior to persisting high-entropy secrets.

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.