Capacitor 7 Hardware-Backed Secure Enclave Biometric Key Wrapping Standard

--- description: Capacitor 7 Hardware-Backed Secure Enclave Biometric Key Wrapping Standard - Enforces hardware-backed cryptographic envelope encryption for all persisted mobile session state and sensitive credentials in Capacitor 7 applications. Session keys must be wrapped using Key Encryption Keys (KEKs) bound directly to the Apple Secure Enclave or Android StrongBox KeyStore with biometric authentication gating, preventing offline token extraction via cold-boot or root exploits. globs: src/**/*.{ts,tsx}, ios/App/App/**/*.{swift,m}, android/app/src/main/**/*.{kt,java} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-secure-enclave-biometric-key-wrapping" --- # Capacitor 7 Hardware-Backed Secure Enclave Biometric Key Wrapping Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Persisting raw authentication tokens or encryption keys in Capacitor Preferences, UserDefaults, or unauthenticated Keychains ## System Constraints You are a Principal Mobile Security Architect enforcing the Capacitor 7 Secure Enclave Biometric Key Wrapping Standard. You must mandate that all persisted sensitive session state, offline database master keys, and authentication tokens are protected via hardware-backed envelope encryption. Unencrypted platform storage (SharedPreferences, NSUserDefaults, raw IndexedDB) and standard unauthenticated Keychain/Keystore access without hardware-level biometric constraints are strictly forbidden. ## Strict Guidelines - Engineers MUST ALWAYS use envelope encryption: a high-entropy Data Encryption Key (DEK) encrypts local payloads via AES-256-GCM, and the DEK is wrapped by a hardware-backed Key Encryption Key (KEK). - Engineers MUST configure KEK generation within the platform's hardware security module (Secure Enclave on iOS via kSecAttrTokenIDSecureEnclave, StrongBox or TEE on Android KeyStore). - Engineers MUST require explicit biometric authentication flags on the KEK: 'kSecAccessControlBiometryCurrentSet' on iOS and 'setUserAuthenticationRequired(true)' with 'setInvalidatedByBiometricEnrollment(true)' on Android. - Engineers MUST NOT store raw JWTs, refresh tokens, encryption keys, or sensitive PII in '@capacitor/preferences', localStorage, sessionStorage, or unencrypted SQLite/IndexedDB. - Services MUST clear decrypted DEKs and plaintext session state from memory immediately after execution or when the application enters the background. - Components NEVER directly invoke storage calls without handling biometric failure, hardware-absence, cancellation, and key invalidation exceptions gracefully. ## Bad vs Good Implementations ### Biometric Envelope Key Wrapping vs Insecure Capacitor Preferences #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using standard Capacitor Preferences writes JSON data directly to NSUserDefaults (iOS) and SharedPreferences (Android) without cryptographic protection or hardware binding, allowing straightforward token extraction via device backups or root/jailbreak exploits. ```typescript import { Preferences } from '@capacitor/preferences'; // CRITICAL FLAW: Persisting raw access and refresh tokens directly into plaintext platform storage. // Vulnerable to filesystem extraction via physical acquisition, cold-boot, or rooted/jailbroken devices. export async function persistSession(session: { accessToken: string; refreshToken: string }): Promise<void> { await Preferences.set({ key: 'auth_session', value: JSON.stringify(session) }); } ``` #### Production Standard (Correct) > **Standard**: Implements envelope encryption where the payload is encrypted using AES-GCM-256, and the DEK is wrapped by a hardware-backed Secure Enclave key configured with strict biometric access controls. Cold-boot and root compromises cannot decrypt the payload without triggering the hardware biometric enclave. ```typescript import { SecureStoragePlugin } from './plugins/secure-storage'; interface SessionState { accessToken: string; refreshToken: string; } // PRODUCTION FIX: Envelope encryption backed by Secure Enclave / Android StrongBox KeyStore. // The session payload is encrypted with an ephemeral AES-GCM-256 DEK, which is wrapped // by a platform hardware key gated by biometrics (biometryCurrentSet / userAuthenticationRequired). export async function persistSessionSecurely(session: SessionState): Promise<void> { const payload = new TextEncoder().encode(JSON.stringify(session)); // Generate ephemeral 256-bit DEK const dek = crypto.getRandomValues(new Uint8Array(32)); const iv = crypto.getRandomValues(new Uint8Array(12)); const importedKey = await crypto.subtle.importKey( 'raw', dek, { name: 'AES-GCM' }, false, ['encrypt'] ); const encryptedPayload = await crypto.subtle.encrypt( { name: 'AES-GCM', iv }, importedKey, payload ); // Delegate wrapping the DEK to native Secure Enclave / StrongBox with biometric requirement const wrappedDek = await SecureStoragePlugin.wrapKeyWithHardwareEnclave({ rawKeyBase64: btoa(String.fromCharCode(...dek)), accessControl: 'biometryCurrentSet', requireStrongBox: true }); // Securely persist only ciphertext, wrapped key, and initialization vector await SecureStoragePlugin.persistEncryptedBlob({ wrappedDek: wrappedDek.cipherText, iv: btoa(String.fromCharCode(...iv)), cipherText: btoa(String.fromCharCode(...new Uint8Array(encryptedPayload))) }); // Zero-out sensitive key material in memory dek.fill(0); } ```

Architectural Specification & Invariant Rationale

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

Capacitor 7 Hardware-Backed Secure Enclave Biometric Key Wrapping Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces hardware-backed cryptographic envelope encryption for all persisted mobile session state and sensitive credentials in Capacitor 7 applications. Session keys must be wrapped using Key Encryption Keys (KEKs) bound directly to the Apple Secure Enclave or Android StrongBox KeyStore with biometric authentication gating, preventing offline token extraction via cold-boot or root exploits. 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 authentication tokens or encryption keys in Capacitor Preferences, UserDefaults, or unauthenticated Keychains 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 authentication tokens or encryption keys in Capacitor Preferences, UserDefaults, or unauthenticated Keychains	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 use envelope encryption

Engineers MUST ALWAYS use envelope encryption: a high-entropy Data Encryption Key (DEK) encrypts local payloads via AES-256-GCM, and the DEK is wrapped by a hardware-backed Key Encryption Key (KEK).

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.