Capacitor 7 Hardware Key-Store Bridge Boundary and Cryptographic Isolation

--- description: Capacitor 7 Hardware Key-Store Bridge Boundary and Cryptographic Isolation - Enforces strict isolation between Capacitor 7 Webview contexts and native hardware security modules (Secure Enclave on iOS, AndroidKeyStore on Android). Mandates that raw cryptographic keys and sensitive authentication refresh tokens never cross the JavaScript bridge, requiring hardware-backed asymmetric signing operations and cryptographic attestation directly in native space to prevent unauthorized Webview script injection exploitation. globs: src/**/*.{ts,tsx,js,jsx}, 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/capacitor-7-hardware-keystore-bridge-boundary" --- # Capacitor 7 Hardware Key-Store Bridge Boundary and Cryptographic Isolation > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Exposing Raw Cryptographic Material or Unsigned Auth Payloads across the Hybrid JavaScript Bridge ## System Constraints You are a Principal Mobile Security Architect enforcing strict Capacitor 7 native-bridge cryptographic boundaries. Mandate that private keys and primary refresh tokens are strictly bound to native hardware (Secure Enclave / StrongBox KeyStore) with biometrics or native gatekeeping. Never serialize private keys into Webview memory (localStorage, IndexedDB, or Bridge message responses). Require challenge-response signing signatures over bridge commands to prevent DOM-based XSS session hijacking. ## Strict Guidelines - Engineers MUST ALWAYS generate asymmetric key pairs inside the native Secure Enclave or AndroidKeyStore using `.userPresence` or `.biometricAny` flags, exposing only the public key to the Capacitor Webview layer. - Engineers MUST NOT return raw private keys, unencrypted symmetric keys, or long-lived authentication refresh tokens across the Capacitor JavaScript bridge. - Bridge communication MUST use challenge-response architecture where the Webview passes ephemeral server challenges to native code to be signed by the hardware key, returning only the cryptographic signature. - Native plugins MUST enforce rate limiting, origin verification, and runtime tamper detection (integrity checks) before executing hardware cryptographic operations invoked via bridge calls. - Webview components NEVER persist tokens in `localStorage`, `sessionStorage`, or raw `IndexedDB`; any transient bearer token returned from native signing must be retained exclusively in scoped JavaScript closures. ## Bad vs Good Implementations ### Hardware Bridge Challenge Signing vs Bridge Key Extraction #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Raw cryptographic keys and permanent refresh tokens cross the native-to-JS bridge, allowing any XSS vulnerability or injected script in the Webview to permanently compromise user identity by accessing memory or Web Storage. ```typescript // BAD: Extracting or storing raw credentials/keys across the Capacitor bridge import { registerPlugin } from '@capacitor/core'; interface InsecureCryptoPlugin { getPrivateKey(): Promise<{ privateKey: string }>; getStoredRefreshToken(): Promise<{ token: string }>; } const InsecureCrypto = registerPlugin<InsecureCryptoPlugin>('InsecureCrypto'); export async function authenticateSession(challenge: string): Promise<string> { // Anti-pattern: Leaking private key or raw token across the bridge into DOM space const { privateKey } = await InsecureCrypto.getPrivateKey(); const { token } = await InsecureCrypto.getStoredRefreshToken(); // Compromised Webview context allows XSS to exfiltrate raw private keys localStorage.setItem('cached_token', token); return signChallengeLocally(challenge, privateKey); } function signChallengeLocally(challenge: string, key: string): string { return btoa(`${challenge}:${key}`); } ``` #### Production Standard (Correct) > **Standard**: The private key never leaves the native hardware boundary. The Webview merely passes an ephemeral server nonce across the bridge, receiving a hardware-generated signature only after hardware authentication succeeds. ```typescript // GOOD: Hardware-isolated cryptographic challenge signing via native bridge import { registerPlugin } from '@capacitor/core'; interface SecureEnclavePlugin { signChallenge(options: { challenge: string; requireBiometric: boolean }): Promise<{ signature: string; keyId: string }>; getPublicKey(): Promise<{ publicKeyPem: string }>; } const SecureEnclave = registerPlugin<SecureEnclavePlugin>('SecureEnclave'); export async function authenticateSession(serverNonce: string): Promise<{ signature: string; keyId: string }> { if (!serverNonce || typeof serverNonce !== 'string') { throw new Error('Invalid authentication challenge'); } // Hardware key operates exclusively inside native Secure Enclave / KeyStore. // Webview never observes or caches raw private keys or persistent credentials. const result = await SecureEnclave.signChallenge({ challenge: serverNonce, requireBiometric: true, }); return { signature: result.signature, keyId: result.keyId }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Hardware Key-Store Bridge Boundary and Cryptographic Isolation

Capacitor 7 Hardware Key-Store Bridge Boundary and Cryptographic Isolation defines an industrial-grade behavioral standard for mobile engineering. Enforces strict isolation between Capacitor 7 Webview contexts and native hardware security modules (Secure Enclave on iOS, AndroidKeyStore on Android). Mandates that raw cryptographic keys and sensitive authentication refresh tokens never cross the JavaScript bridge, requiring hardware-backed asymmetric signing operations and cryptographic attestation directly in native space to prevent unauthorized Webview script injection exploitation. 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 Cryptographic Material or Unsigned Auth Payloads across the Hybrid JavaScript Bridge 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 Cryptographic Material or Unsigned Auth Payloads across the Hybrid JavaScript Bridge	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 generate asymmetric key pairs inside the native Secure Enclave or AndroidKeyStore using `.userPresence` or `.biometricAny` flags, exposing only the public key to the Capacitor Webview layer.

Engineers MUST ALWAYS generate asymmetric key pairs inside the native Secure Enclave or AndroidKeyStore using `.userPresence` or `.biometricAny` flags, exposing only the public key to the Capacitor Webview layer.

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.