Capacitor 7 Hardware-Backed Secure Enclave & Keystore Cryptographic Pinning

--- description: Capacitor 7 Hardware-Backed Secure Enclave & Keystore Cryptographic Pinning - Enforces storage and cryptographic operations for sensitive credentials inside hardware-backed chips (Apple Secure Enclave, Android StrongBox Keymaster) via native Capacitor 7 bridge interfaces. Prohibits direct transit of raw private keys or plain bearer tokens into the JavaScript WebView heap to eliminate credential scraping from Cross-Site Scripting (XSS) or malicious bridge inspection. globs: src/**/*.{ts,tsx,js,jsx}, ios/App/App/**/*.{swift,m,h}, 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-secure-enclave-pinning" --- # Capacitor 7 Hardware-Backed Secure Enclave & Keystore Cryptographic Pinning > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Persisting Raw Bearer Tokens in WebView-Accessible Storage or Bridge RAM ## System Constraints You are a Principal Mobile Security Architect enforcing strict hardware-backed cryptographic pinning in Capacitor 7 hybrid applications. You must reject any code pattern that stores access tokens, private keys, or refresh tokens in localStorage, IndexedDB, raw Capacitor Preferences, or unencrypted bridge payloads. Mandate that all authentication signatures and token exchanges occur inside hardware-isolated modules (iOS Secure Enclave / Android StrongBox/TEE) using asymmetric challenge-response or hardware-encrypted reference tokens. ## Strict Guidelines - Engineers MUST ALWAYS isolate persistent cryptographic credentials inside Apple Secure Enclave (kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly / SecAccessControlCreateWithFlags) or Android Hardware-backed Keystore (MasterKey.Builder with StrongBox/TEE enforcement). - Engineers MUST NOT transfer plain asymmetric private keys, symmetric master keys, or raw long-lived refresh tokens across the Capacitor JavaScript bridge. - Code MUST handle authentication via hardware-rooted challenge-response (asymmetric signing inside the Secure Enclave/KeyStore) or via opaque hardware-encrypted handles where decryption strictly occurs at the native HTTP networking layer. - Services MUST verify hardware backing at runtime via native plugins (e.g., KeyInfo.isInsideSecureHardware() on Android, kSecAttrTokenIDSecureEnclave on iOS) and fail closed if running in downgraded or emulated software keystores without explicit development override flags. - Components NEVER store authentication tokens or cryptographic materials in browser-accessible primitives including localStorage, sessionStorage, IndexedDB, or standard unencrypted Capacitor Preferences. ## Bad vs Good Implementations ### Insecure Token Storage in WebView vs Hardware-Pinned Secure Enclave Delegation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Stores plaintext bearer tokens across the bridge into Capacitor Preferences. A single DOM injection or compromised library in the hybrid runtime can scrape the token directly out of the WebView or memory heap. ```typescript import { Preferences } from '@capacitor/preferences'; import axios from 'axios'; export class AuthService { // ANTI-PATTERN: Raw JWT stored in Preferences (WebView-accessible SQLite/SharedPreferences) // If WebView is compromised via XSS or prototype pollution, the bearer token is exfiltrated instantly. async storeSession(token: string): Promise<void> { await Preferences.set({ key: 'auth_bearer_token', value: token }); } async makeAuthenticatedRequest(url: string): Promise<any> { const { value: token } = await Preferences.get({ key: 'auth_bearer_token' }); if (!token) throw new Error('Unauthenticated'); return axios.get(url, { headers: { Authorization: `Bearer ${token}` } }); } } ``` #### Production Standard (Correct) > **Standard**: Delegates cryptographic operations to the Secure Enclave via a native Capacitor plugin interface. The private key never leaves the hardware security module, and requests are either signed inside the enclave or delegated to the native network stack, insulating credentials from WebView exploits. ```typescript import { registerPlugin } from '@capacitor/core'; export interface SecureEnclavePlugin { generateHardwareKeyPair(options: { alias: string; requireBiometric: boolean }): Promise<{ publicKey: string }>; signPayload(options: { alias: string; payload: string }): Promise<{ signature: string }>; executeSecureRequest(options: { url: string; method: 'GET' | 'POST'; keyAlias: string; headers?: Record<string, string>; }): Promise<{ status: number; data: string }>; } const SecureEnclave = registerPlugin<SecureEnclavePlugin>('SecureEnclave'); export class SecureAuthService { private readonly keyAlias = 'app_hardware_identity_v1'; // INVARIANT: Private keys never touch JavaScript. Hardware creates asymmetric keypair inside HSM. async initializeDeviceAttestation(): Promise<string> { const result = await SecureEnclave.generateHardwareKeyPair({ alias: this.keyAlias, requireBiometric: false }); return result.publicKey; } // INVARIANT: The WebView asks the native enclave to sign a challenge or dispatch through native client. // Private keys remain permanently sealed within Secure Enclave / Android StrongBox. async makeHardwareAttestedRequest(url: string, challenge: string): Promise<any> { const { signature } = await SecureEnclave.signPayload({ alias: this.keyAlias, payload: challenge }); return SecureEnclave.executeSecureRequest({ url, method: 'POST', keyAlias: this.keyAlias, headers: { 'X-Client-Signature': signature, 'X-Device-Challenge': challenge } }); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Hardware-Backed Secure Enclave & Keystore Cryptographic Pinning

Capacitor 7 Hardware-Backed Secure Enclave & Keystore Cryptographic Pinning defines an industrial-grade behavioral standard for mobile engineering. Enforces storage and cryptographic operations for sensitive credentials inside hardware-backed chips (Apple Secure Enclave, Android StrongBox Keymaster) via native Capacitor 7 bridge interfaces. Prohibits direct transit of raw private keys or plain bearer tokens into the JavaScript WebView heap to eliminate credential scraping from Cross-Site Scripting (XSS) or malicious bridge inspection. 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: Persisting Raw Bearer Tokens in WebView-Accessible Storage or Bridge RAM 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	Persisting Raw Bearer Tokens in WebView-Accessible Storage or Bridge RAM	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 isolate persistent cryptographic credentials inside Apple Secure Enclave (kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly / SecAccessControlCreateWithFlags) or Android Hardware-backed Keystore (MasterKey.Builder with StrongBox/TEE enforcement).

Engineers MUST ALWAYS isolate persistent cryptographic credentials inside Apple Secure Enclave (kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly / SecAccessControlCreateWithFlags) or Android Hardware-backed Keystore (MasterKey.Builder with StrongBox/TEE enforcement).

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.