Capacitor 7 Hardware-Backed Keystore Cryptographic Interop Contract

--- description: Capacitor 7 Hardware-Backed Keystore Cryptographic Interop Contract - Enforces asymmetric payload signing exclusively within the native hardware Secure Enclave or Android Keystore via Capacitor 7 native bridges. Eliminates the persistence or exposure of raw cryptographic private keys, refresh tokens, and master credentials within the hybrid WebView JavaScript context. Mandates proof-of-possession signing using ephemeral challenge-response mechanics. globs: src/**/*.{ts,tsx}, ios/App/App/**/*.{swift,m}, android/app/src/main/java/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor7-biometric-secure-enclave-interop" --- # Capacitor 7 Hardware-Backed Keystore Cryptographic Interop Contract > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Exposing Raw Private Keys or Storing Static Bearer Tokens in WebView Storage ## System Constraints You are a Principal Mobile Security Architect enforcing the Capacitor 7 Biometric Hardware-Backed Keystore Interop Contract. You must reject any pattern that deserializes, buffers, or retains raw cryptographic private keys or long-lived authentication bearer tokens inside the JavaScript runtime (LocalStorage, IndexedDB, or in-memory variables). Mandate that all cryptographic assertion is delegated to native plugins leveraging iOS Secure Enclave (kSecAccessControlBiometryAny) or Android KeyStore (KeyGenParameterSpec with setUserAuthenticationRequired). The JavaScript layer may only receive transient challenges from the backend and hand them off to the native bridge to obtain detached signatures. ## Strict Guidelines - Engineers MUST NEVER transfer, export, or reconstruct asymmetric private keys inside the JavaScript runtime context. - Engineers MUST configure native Android Keystore keys with setUserAuthenticationRequired(true) and setUserAuthenticationParameters with biometric flags. - Engineers MUST configure iOS Keychain entries using SecAccessControlCreateWithFlags with kSecAccessControlBiometryCurrentSet or kSecAccessControlBiometryAny. - Code MUST transmit an ephemeral cryptographic challenge and a target payload to the native plugin bridge, receiving only a detached signature (DER or R+S) and public key thumbprint. - Services MUST implement server-driven challenge-response sequences to prevent replay attacks, refusing static token caching in Capacitor Preferences or local web storage. - Components NEVER store JWT refresh tokens or auth tokens in localStorage or IndexedDB; auth states must be verified through hardware-signed assertions. ## Bad vs Good Implementations ### Biometric Authentication via Hardware Signing vs In-Memory Key Extraction #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The code uses biometrics as a cosmetic gate rather than a hardware-enforced decrypt/sign prerequisite. The private key resides in unencrypted software storage accessible to any WebView script or XSS injection, violating TEE/Secure Enclave boundary guarantees. ```typescript import { Preferences } from '@capacitor/preferences'; import { NativeBiometric } from 'capacitor-native-biometric'; export async function signTransactionBad(payload: object): Promise<string> { // Flaw 1: Validating biometrics via boolean check, not hardware key access const verified = await NativeBiometric.verifyIdentity({ reason: 'Authenticate to sign payload' }); if (!verified) throw new Error('Biometric failed'); // Flaw 2: Storing raw private key/session secret in JS-accessible storage const { value: rawPrivateKey } = await Preferences.get({ key: 'user_private_key' }); if (!rawPrivateKey) throw new Error('Key missing'); // Flaw 3: Signing in JS context, exposing keys to XSS & memory inspection return signWithSoftwareKey(JSON.stringify(payload), rawPrivateKey); } declare function signWithSoftwareKey(p: string, k: string): string; ``` #### Production Standard (Correct) > **Standard**: The signature operation delegates directly to a custom Capacitor native bridge. The private key is bound within hardware (Secure Enclave / Android Keystore) and cannot be extracted into memory. The WebView only holds the transient challenge and detached signature. ```typescript import { registerPlugin } from '@capacitor/core'; export interface SecureBiometricSignerPlugin { signChallengeWithHardwareKey(options: { challenge: string; payloadHash: string; promptMessage: string; }): Promise<{ signature: string; keyId: string }>; } const BiometricSigner = registerPlugin<SecureBiometricSignerPlugin>('SecureBiometricSigner'); export async function signTransactionSecure( serverChallenge: string, payload: Record<string, unknown> ): Promise<{ signature: string; keyId: string }> { // Invariant 1: Ensure challenge is non-empty and strictly ephemeral if (!serverChallenge || typeof serverChallenge !== 'string') { throw new Error('Invalid authentication challenge'); } // Invariant 2: Hash payload locally; never serialize raw secret state const encoder = new TextEncoder(); const data = encoder.encode(JSON.stringify(payload)); const hashBuffer = await crypto.subtle.digest('SHA-256', data); const payloadHash = Array.from(new Uint8Array(hashBuffer)) .map((b) => b.toString(16).padStart(2, '0')) .join(''); // Invariant 3: Hardware enclave executes signature natively upon biometric unlock. // Raw private key never touches the V8/JSC runtime. return await BiometricSigner.signChallengeWithHardwareKey({ challenge: serverChallenge, payloadHash, promptMessage: 'Authorize critical operation' }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Hardware-Backed Keystore Cryptographic Interop Contract

Capacitor 7 Hardware-Backed Keystore Cryptographic Interop Contract defines an industrial-grade behavioral standard for mobile engineering. Enforces asymmetric payload signing exclusively within the native hardware Secure Enclave or Android Keystore via Capacitor 7 native bridges. Eliminates the persistence or exposure of raw cryptographic private keys, refresh tokens, and master credentials within the hybrid WebView JavaScript context. Mandates proof-of-possession signing using ephemeral challenge-response mechanics. 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: Exposing Raw Private Keys or Storing Static Bearer Tokens in WebView Storage 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	Exposing Raw Private Keys or Storing Static Bearer Tokens in WebView Storage	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 NEVER transfer, export, or reconstruct asymmetric private keys inside the JavaScript runtime context.

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.