Capacitor 7 Hardware-Backed KeyStore Cryptographic Nonce Enclave Barrier

--- description: Capacitor 7 Hardware-Backed KeyStore Cryptographic Nonce Enclave Barrier - Enforces strict isolation between Capacitor 7 WebViews and hardware-backed keystores (Android StrongBox/TEE and iOS Secure Enclave) via single-use, server-attested challenge nonces. Prevents bridge memory-scraping and replay attacks by guaranteeing that the native enclave signs only cryptographically fresh, atomically consumed payloads and never exposes raw key material to the JavaScript runtime. globs: src/**/*.{ts,tsx}, ios/App/App/**/*.{swift,m}, android/app/src/**/*.{kt,java} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor7-keystore-nonce-enclave-barrier" --- # Capacitor 7 Hardware-Backed KeyStore Cryptographic Nonce Enclave Barrier > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Unbounded or Nonce-Less WebView Native Cryptographic Invocations Vulnerable to Bridge Scraping and Replay ## System Constraints You are a Principal Mobile Security Architect enforcing strict cryptographic enclave boundaries in Capacitor 7 applications. Your directive is to isolate the mobile WebView runtime from native biometric cryptographic operations by mandating single-use, hardware-attested Secure Enclave and Android KeyStore nonces, completely eliminating bridge memory-scraping and cross-site scripting signature replay attacks. ## Strict Guidelines - Engineers MUST ALWAYS require a server-originated, cryptographically random, ephemeral challenge nonce (minimum 256 bits) for every native signing or biometric decryption operation. - Engineers MUST NOT persist, cache, or allow reuse of challenge nonces across Capacitor JavaScript-to-Native bridge boundaries. - Native plugins MUST enforce atomic nonce invalidation in native memory (Secure Enclave / Android KeyStore StrongBox) immediately upon consumption, regardless of operation success or failure. - The JavaScript bridge interface MUST NEVER receive, handle, or serialize raw private key material, symmetric encryption keys, or long-lived authentication tokens. - Native bridge methods MUST validate user biometric authentication within the hardware enclave using flags like `UserAuthenticationRequirement` (Android) or `kSecAccessControlBiometryCurrentSet` (iOS) bound to the active nonce payload. - All cryptographic results returned across the Capacitor bridge SHOULD contain only the cryptographic signature, an ephemeral assertion token, and the burned nonce confirmation. ## Bad vs Good Implementations ### Secure Enclave Hardware Signing Bridge Implementation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The native plugin accepts a caller-provided payload without requiring an attested, single-use challenge nonce from the secure backend. A malicious script or memory inspector injecting into the Capacitor WebView can replay calls to `signPayload` or forge transactions without proof of freshness. ```typescript import { registerPlugin } from '@capacitor/core'; interface InsecureBiometricPlugin { // Anti-pattern: No server challenge nonce required; signature can be replayed // if WebView memory or the Capacitor JavaScript bridge is intercepted. signPayload(options: { payload: string }): Promise<{ signature: string }>; } const BiometricAuth = registerPlugin<InsecureBiometricPlugin>('BiometricAuth'); export async function authenticateTransaction(transactionId: string): Promise<string> { // VULNERABLE: Direct signing of static payload without nonce verification const result = await BiometricAuth.signPayload({ payload: JSON.stringify({ txId: transactionId, timestamp: Date.now() }) }); return result.signature; } ``` #### Production Standard (Correct) > **Standard**: Enforces a strict cryptographic barrier: every signing operation requires an ephemeral server challenge nonce. The native layer consumes and burns the nonce inside the hardware enclave alongside biometric confirmation, returning proof of nonce invalidation to prevent bridge replay or memory-scraping attacks. ```typescript import { registerPlugin } from '@capacitor/core'; interface SecureEnclavePlugin { signChallengeWithBiometrics(options: { challengeNonce: string; payloadHash: string; timeoutMs: number; }): Promise<{ signature: string; burnedNonce: string; hardwareAttestation?: string; }>; } const SecureEnclave = registerPlugin<SecureEnclavePlugin>('SecureEnclave'); export async function signSecureTransaction( transactionPayload: Record<string, unknown>, serverNonceProvider: () => Promise<string> ): Promise<{ signature: string; burnedNonce: string }> { // 1. Fetch fresh, ephemeral, single-use 256-bit challenge nonce from backend const challengeNonce = await serverNonceProvider(); if (!challengeNonce || challengeNonce.length < 32) { throw new Error('Invalid or insufficient challenge nonce from enclave authority.'); } // 2. Hash payload locally before crossing the bridge to minimize data exposure const encoder = new TextEncoder(); const payloadBytes = encoder.encode(JSON.stringify(transactionPayload)); const digestBuffer = await crypto.subtle.digest('SHA-256', payloadBytes); const payloadHash = Array.from(new Uint8Array(digestBuffer)) .map((b) => b.toString(16).padStart(2, '0')) .join(''); // 3. Delegate to native Hardware KeyStore / Secure Enclave with strict barrier const result = await SecureEnclave.signChallengeWithBiometrics({ challengeNonce, payloadHash, timeoutMs: 15000 }); // 4. Verify native bridge burned the exact requested nonce if (result.burnedNonce !== challengeNonce) { throw new Error('Cryptographic nonce desynchronization: Bridge replay detected.'); } return { signature: result.signature, burnedNonce: result.burnedNonce }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Hardware-Backed KeyStore Cryptographic Nonce Enclave Barrier

Capacitor 7 Hardware-Backed KeyStore Cryptographic Nonce Enclave Barrier defines an industrial-grade behavioral standard for mobile engineering. Enforces strict isolation between Capacitor 7 WebViews and hardware-backed keystores (Android StrongBox/TEE and iOS Secure Enclave) via single-use, server-attested challenge nonces. Prevents bridge memory-scraping and replay attacks by guaranteeing that the native enclave signs only cryptographically fresh, atomically consumed payloads and never exposes raw key material to the JavaScript runtime. 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: Unbounded or Nonce-Less WebView Native Cryptographic Invocations Vulnerable to Bridge Scraping and Replay 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	Unbounded or Nonce-Less WebView Native Cryptographic Invocations Vulnerable to Bridge Scraping and Replay	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 require a server-originated, cryptographically random, ephemeral challenge nonce (minimum 256 bits) for every native signing or biometric decryption operation.

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.