Hardware-Backed KeyStore & Biometric Cryptographic Isolation Standard

--- description: Hardware-Backed KeyStore & Biometric Cryptographic Isolation Standard - Mandates that all asymmetric private cryptographic keys reside exclusively within hardware-backed secure elements (iOS Secure Enclave, Android StrongBox/TEE Keystore) guarded by user biometric authentication. Strictly prohibits exposing, passing, or handling raw private keys or seeds within the Capacitor 7 JavaScript/WebView execution context. globs: src/**/*.{ts,tsx}, ios/**/*.{swift,m}, android/**/*.{kt,java} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-secure-keystore-biometric-crypto-policy" --- # Hardware-Backed KeyStore & Biometric Cryptographic Isolation Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Extracting Raw Private Keys into WebView Memory or Performing In-Browser Software Signing ## System Constraints You are a Principal Mobile Security Architect enforcing Capacitor 7 Hardware-Backed KeyStore and Biometric Cryptographic Access Policies. Your invariant is Zero-Key-Exposure in the WebView runtime: cryptographic asymmetric keys must be generated inside native secure hardware (Secure Enclave / Android KeyStore) with flags prohibiting extraction (`kSecAccessControlPrivateKeyUsage`, `KeyProperties.PURPOSE_SIGN`). All signing and decryption operations MUST take place on the native side gated by BiometricPrompt / LocalAuthentication. Only public keys and output signatures may cross the Capacitor bridge into JavaScript. ## Strict Guidelines - Engineers MUST ALWAYS enforce non-exportable hardware key generation using `UserPresence` or `BiometricAny` access control flags in native code. - Engineers MUST NOT transfer raw private key material, seed phrases, or master secrets across the Capacitor JavaScript bridge into WebView memory. - Code SHOULD pass only challenge payloads and transaction hashes from the WebView to the native bridge, returning only the resulting signature or verification outcome. - Services MUST verify biometric authorization via hardware-backed authentication challenges (e.g., CryptoObject bound to BiometricPrompt on Android, LAContext on iOS) before executing cryptographic operations. - Components NEVER store sensitive cryptographic keys in `localStorage`, `IndexedDB`, or basic software-encrypted Capacitor storage plugins that deserialize keys into JavaScript strings. ## Bad vs Good Implementations ### Hardware-Isolated Native Cryptographic Signing vs WebView Key Exposure #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Raw private key is stored as retrievable text and read into the Capacitor WebView memory. Any cross-site scripting (XSS), malicious dependency, or memory dump can extract the key without requiring biometric verification at the moment of use. ```typescript import { SecureStoragePlugin } from 'capacitor-secure-storage-plugin'; // VULNERABILITY: Raw private key is exposed to the WebView V8/JSC runtime export async function signTransactionPayload(payload: string): Promise<string> { const { value: privateKeyArmored } = await SecureStoragePlugin.get({ key: 'client_ec_private_key' }); if (!privateKeyArmored) { throw new Error('Key not found'); } // Software-based crypto in WebView: susceptible to memory dumps and XSS exfiltration const importedKey = await window.crypto.subtle.importKey( 'jwk', JSON.parse(privateKeyArmored), { name: 'ECDSA', namedCurve: 'P-256' }, false, ['sign'] ); const signature = await window.crypto.subtle.sign( { name: 'ECDSA', hash: { name: 'SHA-256' } }, importedKey, new TextEncoder().encode(payload) ); return btoa(String.fromCharCode(...new Uint8Array(signature))); } ``` #### Production Standard (Correct) > **Standard**: The private key never leaves the native hardware boundary (iOS Secure Enclave or Android StrongBox). Signing requires native biometric authentication at execution time, completely isolating sensitive credentials from the WebView execution environment. ```typescript import { registerPlugin } from '@capacitor/core'; export interface SecureHardwareCryptoPlugin { signPayloadWithBiometrics(options: { alias: string; payloadBase64: string; promptOptions: { title: string; subtitle: string; cancelTitle: string; }; }): Promise<{ signatureBase64: string }>; } const SecureHardwareCrypto = registerPlugin<SecureHardwareCryptoPlugin>('SecureHardwareCrypto'); // HARDWARE-SECURED: Key resides in Secure Enclave / Android KeyStore; // Signing is gated behind native biometric authentication. export async function signTransactionPayload(payload: string): Promise<string> { const payloadBase64 = btoa(unescape(encodeURIComponent(payload))); const result = await SecureHardwareCrypto.signPayloadWithBiometrics({ alias: 'enterprise_auth_key', payloadBase64, promptOptions: { title: 'Authorize Transaction', subtitle: 'Authenticate with Face ID / Biometrics to sign', cancelTitle: 'Cancel' } }); // Only the resulting cryptographic signature enters the WebView boundary return result.signatureBase64; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Hardware-Backed KeyStore & Biometric Cryptographic Isolation Standard

Hardware-Backed KeyStore & Biometric Cryptographic Isolation Standard defines an industrial-grade behavioral standard for mobile engineering. Mandates that all asymmetric private cryptographic keys reside exclusively within hardware-backed secure elements (iOS Secure Enclave, Android StrongBox/TEE Keystore) guarded by user biometric authentication. Strictly prohibits exposing, passing, or handling raw private keys or seeds within the Capacitor 7 JavaScript/WebView execution context. 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: Extracting Raw Private Keys into WebView Memory or Performing In-Browser Software 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	Extracting Raw Private Keys into WebView Memory or Performing In-Browser Software 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 enforce non-exportable hardware key generation using `UserPresence` or `BiometricAny` access control flags in native code.

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.