Capacitor 7 Biometric Secure Enclave Key Derivation & Non-Exportability Invariant

Enforces that cryptographic client credentials in Capacitor 7 hybrid applications are generated directly within hardware-isolated subsystems (Apple Secure Enclave and Android Hardware-backed Keystore) protected by biometric access-control flags (`kSecAccessControlBiometryAny` / `UserAuthenticationValidityDurationSeconds`). Strictly forbids JavaScript-layer key derivation, runtime exportability, or in-memory persistence of raw keys across WKWebView or Android WebView process terminations and reloads.

--- description: Capacitor 7 Biometric Secure Enclave Key Derivation & Non-Exportability Invariant - Enforces that cryptographic client credentials in Capacitor 7 hybrid applications are generated directly within hardware-isolated subsystems (Apple Secure Enclave and Android Hardware-backed Keystore) protected by biometric access-control flags (`kSecAccessControlBiometryAny` / `UserAuthenticationValidityDurationSeconds`). Strictly forbids JavaScript-layer key derivation, runtime exportability, or in-memory persistence of raw keys across WKWebView or Android WebView process terminations and reloads. 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/capacitor7-biometric-secure-enclave-key-derivation" --- # Capacitor 7 Biometric Secure Enclave Key Derivation & Non-Exportability Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Exporting or Deriving Cryptographic Private Keys in WebCore/V8 JavaScript Memory Instead of Hardware-Isolated Enclave Signing ## System Constraints You are a Principal Mobile Security Architect enforcing strict hardware-backed cryptographic boundaries in Capacitor 7. You must ensure that no private cryptographic keys, seed phrases, or unencrypted session secrets ever transit through or reside within the JavaScript execution environment. Private keys must be created inside iOS Secure Enclave (kSecAttrTokenIDSecureEnclave with SecKeyCreateRandomKey) or Android Keystore (MasterKey/KeyGenParameterSpec with PURPOSE_SIGN) requiring explicit biometric authentication for every operation or within an ephemeral, attested hardware window. The web runtime must only transmit challenge nonces and receive signed payloads, preventing key compromise across WKWebView engine restarts, XSS, or memory dumps. ## Strict Guidelines - Engineers MUST ALWAYS delegate cryptographic key generation and payload signing to native plugins utilizing Apple Secure Enclave (`kSecAttrTokenIDSecureEnclave`) and Android Keystore (`AndroidKeyStore`). - Engineers MUST NOT generate, export, serialize, or hold asymmetric private keys or raw entropy seeds within the Capacitor JavaScript/TypeScript runtime or WebStorage (localStorage, IndexedDB). - Native plugins MUST enforce biometric authorization (`SecAccessControlCreateWithFlags` using `.biometryCurrentSet` or `.userPresence`, and `setUserAuthenticationRequired(true)`) directly at the OS keystore boundary. - Cryptographic workflows MUST use asymmetric challenge-response architectures where the JavaScript layer only forwards a server-generated nonce to native code and receives back a signature or signed JWT. - The TypeScript layer MUST explicitly handle native biometric cancellation, invalidation (e.g., biometric enrollment changes via `KeyPermanentlyInvalidatedException`), and lifecycle failures gracefully without caching fallbacks in web memory. ## Bad vs Good Implementations ### Hardware Enclave Cryptographic Signing vs. JavaScript Memory Key Handling #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Private keys are generated in pure JavaScript software memory and stored in Capacitor Preferences (unencrypted plist/SharedPreferences). If the WKWebView process recycles, or if an XSS vulnerability occurs, the raw private key can be exfiltrated. The key is completely decoupled from device hardware biometrics and does not leverage the Secure Enclave. ```typescript import { Preferences } from '@capacitor/preferences'; import * as elliptic from 'elliptic'; // ANTI-PATTERN: Generating and holding private keys in WebCore/V8 JavaScript heap export class ClientAuthManager { private ec = new elliptic.ec('p256'); async initializeAndSign(challenge: string): Promise<string> { let privKeyHex = (await Preferences.get({ key: 'client_priv_key' })).value; if (!privKeyHex) { // CRITICAL FLAW: Key generated in software JS engine, entirely exportable const key = this.ec.genKeyPair(); privKeyHex = key.getPrivate('hex'); // CRITICAL FLAW: Persisted insecurely in web preferences across process restarts await Preferences.set({ key: 'client_priv_key', value: privKeyHex }); } const keyPair = this.ec.keyFromPrivate(privKeyHex, 'hex'); const signature = keyPair.sign(challenge); return signature.toDER('hex'); } } ``` #### Production Standard (Correct) > **Standard**: Private keys are strictly generated and bound within the Secure Enclave/Android Keystore. The JavaScript runtime only receives the public key and passes challenges into the native layer. Keys are non-exportable, surviving WKWebView crashes and process recycles without ever exposing raw key bytes to user-space memory or WebStorage. ```typescript import { registerPlugin } from '@capacitor/core'; export interface SecureBiometricAuthPlugin { generateHardwareKey(options: { alias: string; requireBiometric: boolean }): Promise<{ publicKeyHex: string }>; signHardwareChallenge(options: { alias: string; challengeBase64: string }): Promise<{ signatureBase64: string }>; } const SecureBiometricAuth = registerPlugin<SecureBiometricAuthPlugin>('SecureBiometricAuth'); export class ClientAuthManager { private readonly keyAlias = 'app_client_device_attested_auth'; async getOrCreateHardwareKey(): Promise<string> { // Invariant: Native implementation must set kSecAttrTokenIDSecureEnclave or KeyGenParameterSpec.Builder const result = await SecureBiometricAuth.generateHardwareKey({ alias: this.keyAlias, requireBiometric: true, }); return result.publicKeyHex; } async authenticateChallenge(challengeBase64: string): Promise<string> { // Invariant: Private key never enters JavaScript. Challenge is passed into the Secure Enclave. // Hardware prompts biometric authentication. Fails immediately if biometric set changed. try { const response = await SecureBiometricAuth.signHardwareChallenge({ alias: this.keyAlias, challengeBase64, }); return response.signatureBase64; } catch (error: unknown) { // Handles native hardware rejection, biometric lockouts, or key invalidation throw new Error(`Secure Enclave signing failed: ${(error as Error).message}`); } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Biometric Secure Enclave Key Derivation & Non-Exportability Invariant

Capacitor 7 Biometric Secure Enclave Key Derivation & Non-Exportability Invariant defines an industrial-grade behavioral standard for mobile engineering. Enforces that cryptographic client credentials in Capacitor 7 hybrid applications are generated directly within hardware-isolated subsystems (Apple Secure Enclave and Android Hardware-backed Keystore) protected by biometric access-control flags (`kSecAccessControlBiometryAny` / `UserAuthenticationValidityDurationSeconds`). Strictly forbids JavaScript-layer key derivation, runtime exportability, or in-memory persistence of raw keys across WKWebView or Android WebView process terminations and reloads. 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: Exporting or Deriving Cryptographic Private Keys in WebCore/V8 JavaScript Memory Instead of Hardware-Isolated Enclave Signing 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	Exporting or Deriving Cryptographic Private Keys in WebCore/V8 JavaScript Memory Instead of Hardware-Isolated Enclave Signing	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 delegate cryptographic key generation and payload signing to native plugins utilizing Apple Secure Enclave (`kSecAttrTokenIDSecureEnclave`) and Android Keystore (`AndroidKeyStore`).

Engineers MUST ALWAYS delegate cryptographic key generation and payload signing to native plugins utilizing Apple Secure Enclave (`kSecAttrTokenIDSecureEnclave`) and Android Keystore (`AndroidKeyStore`).

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.