Capacitor 7 Biometric Hardware-Backed Keystore Isolation & Non-Exportability

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Exporting raw cryptographic secrets, private keys, or long-lived authentication payloads into Capacitor WebView memory) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q: Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q: Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Capacitor 7 Biometric Hardware-Backed Keystore Isolation & Non-Exportability

--- description: Capacitor 7 Biometric Hardware-Backed Keystore Isolation & Non-Exportability - Enforces strict isolation between hardware security enclaves (iOS Secure Enclave, Android StrongBox/TEE) and Capacitor 7 WebView runtimes. Cryptographic private keys and raw biometric secrets must remain strictly non-exportable within the native hardware module, allowing only detached digital signatures or short-lived assertion tokens to traverse the bridge into the web execution context. globs: src/**/*.{ts,tsx}, ios/App/**/*.{swift,m}, android/app/src/main/java/**/*.java, android/app/src/main/kotlin/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-biometric-keystore-isolation-standard" --- # Capacitor 7 Biometric Hardware-Backed Keystore Isolation & Non-Exportability > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Exporting raw cryptographic secrets, private keys, or long-lived authentication payloads into Capacitor WebView memory ## System Constraints You are a Principal Mobile Security Architect enforcing Capacitor 7 Biometric Hardware-Backed Keystore Isolation. You mandate that cryptographic private keys NEVER cross the bridge into the WebKit/Chromium JavaScript execution context. All biometric operations must execute via native challenge-response signatures where the private key is configured as non-exportable inside hardware (Secure Enclave or Android KeyStore with StrongBox backing). Enforce zero raw secret leakage, ephemeral challenge consumption, and strict bridge transport boundaries. ## Strict Guidelines - Engineers MUST ALWAYS enforce non-exportable key generation parameters in native implementations (e.g., kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly / SecAccessControlCreateWithFlags with .biometryAny on iOS, and KeyGenParameterSpec with setUserAuthenticationRequired(true) on Android). - Engineers MUST NOT return raw private keys, symmetric master keys, or unencrypted persistent refresh tokens to the Capacitor 7 JavaScript bridge interface. - Engineers MUST implement asynchronous challenge-response assertions: the server issues a cryptographically random, ephemeral challenge (nonce), the native hardware signs it via biometrically guarded private keys, and only the resulting detached signature is returned to the WebView. - Services MUST clear sensitive native signature buffers immediately after serialization over the Capacitor bridge to prevent post-execution memory dump exploits. - Components NEVER store sensitive biometric unlock payloads in standard browser storage APIs such as localStorage, sessionStorage, or unencrypted IndexedDB. ## Bad vs Good Implementations ### Hardware-Bound Assertion vs. In-Memory Key Storage Anti-Pattern #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Raw cryptographic keys and biometric secrets are exported across the bridge into WebKit/Chromium heap memory and persisted in unencrypted browser storage. If an XSS vulnerability exists, attackers can exfiltrate the hardware identity permanently. ```typescript import { registerPlugin } from '@capacitor/core'; interface InsecureBiometricPlugin { getPrivateKey(): Promise<{ privateKeyPem: string }>; getBiometricSecret(): Promise<{ rawSecret: string }>; } const NativeBiometrics = registerPlugin<InsecureBiometricPlugin>('InsecureBiometrics'); export async function authenticateAndSignPayload(payload: string): Promise<string> { // CRITICAL SECURITY VIOLATION: Private key is marshaled over the JS bridge. // This places raw private keys into Chromium/WebKit V8 heap, vulnerable to XSS and heap inspection. const { privateKeyPem } = await NativeBiometrics.getPrivateKey(); const { rawSecret } = await NativeBiometrics.getBiometricSecret(); localStorage.setItem('cached_secret', rawSecret); return `signed:${payload}:${privateKeyPem}`; } ``` #### Production Standard (Correct) > **Standard**: The hardware enclave handles the asymmetric keypair creation and signature verification natively. The private key is non-exportable and never enters the JavaScript engine. Only the detached signature and key reference identifier are transmitted across the Capacitor bridge. ```typescript import { registerPlugin } from '@capacitor/core'; interface SecureEnclavePlugin { signChallengeWithBiometrics(options: { challenge: string; promptMessage: string; }): Promise<{ signature: string; keyId: string }>; } const HardwareVault = registerPlugin<SecureEnclavePlugin>('HardwareVault'); export async function authenticateWithHardwareEnclave(serverNonce: string): Promise<{ signature: string; keyId: string }> { if (!serverNonce || typeof serverNonce !== 'string' || serverNonce.length < 32) { throw new Error('Invalid cryptographic nonce: must be at least 256 bits.'); } // INVARIANT: Private keys never leave the Secure Enclave / StrongBox. // The native plugin accepts a challenge, prompts biometrics via OS APIs, // performs detached signing natively, and only emits the detached signature. const result = await HardwareVault.signChallengeWithBiometrics({ challenge: serverNonce, promptMessage: 'Confirm biometric authentication to verify your session' }); return { signature: result.signature, keyId: result.keyId }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Biometric Hardware-Backed Keystore Isolation & Non-Exportability

Capacitor 7 Biometric Hardware-Backed Keystore Isolation & Non-Exportability defines an industrial-grade behavioral standard for mobile engineering. Enforces strict isolation between hardware security enclaves (iOS Secure Enclave, Android StrongBox/TEE) and Capacitor 7 WebView runtimes. Cryptographic private keys and raw biometric secrets must remain strictly non-exportable within the native hardware module, allowing only detached digital signatures or short-lived assertion tokens to traverse the bridge into the web 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: Exporting raw cryptographic secrets, private keys, or long-lived authentication payloads into Capacitor WebView memory 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 raw cryptographic secrets, private keys, or long-lived authentication payloads into Capacitor WebView memory	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 key generation parameters in native implementations (e.g., kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly / SecAccessControlCreateWithFlags with .biometryAny on iOS, and KeyGenParameterSpec with setUserAuthenticationRequired(true) on Android).

Engineers MUST ALWAYS enforce non-exportable key generation parameters in native implementations (e.g., kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly / SecAccessControlCreateWithFlags with .biometryAny on iOS, and KeyGenParameterSpec with setUserAuthenticationRequired(true) on Android).

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.