Capacitor 7 Secure Enclave & Hardware Keystore Vault Interface Invariants

--- description: Capacitor 7 Secure Enclave & Hardware Keystore Vault Interface Invariants - Mandates that all cryptographic private keys, biometric-bound secrets, and high-entropy authentication tokens are strictly sequestered within platform hardware security modules (Apple Secure Enclave and Android StrongBox/KeyStore) rather than standard WebView storage. In Capacitor 7 hybrid environments, access must be mediated via verified native hardware-backed vault bridges enforcing device authentication, key non-exportability, and zeroization of in-memory payloads. globs: src/**/*.{ts,tsx}, ios/App/App/**/*.{swift,h,m}, android/app/src/main/java/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-hardware-vault-security-enclave-guardrail" --- # Capacitor 7 Secure Enclave & Hardware Keystore Vault Interface Invariants > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Persisting Refresh Tokens, Master Cryptographic Keys, or PII in Unencrypted Web Storage or Software-Only Keyrings ## System Constraints You are a Principal Mobile Security Architect enforcing strict hardware-backed vault patterns in Capacitor 7 applications. You must enforce that no sensitive offline cryptographic material, credentials, or session tokens enter DOM storage (localStorage, sessionStorage, unencrypted IndexedDB) or software-emulated key stores. Enforce hardware-backed non-exportable asymmetric operations, biometric access gating, and ephemeral memory handling across all Capacitor bridge interactions. ## Strict Guidelines - Engineers MUST ALWAYS enforce hardware-backed key isolation (Apple Secure Enclave via Keychain Access Groups, Android KeyStore backed by StrongBox or TEE) for any long-lived offline credentials or signing keys. - Engineers MUST NEVER persist authorization tokens, refresh tokens, cryptographic private keys, or session secrets into standard Web Storage APIs ('localStorage', 'sessionStorage'), standard WebSQL/IndexedDB, or raw '@capacitor/preferences'. - Services MUST configure the hardware vault with explicit biometric or device passcode authentication constraints ('DeviceSecurity' / 'Biometric' access control levels) for key decryption operations. - Engineers MUST treat keys as strictly non-extractable; cryptographic operations (e.g., signing, decryption) MUST execute inside the platform hardware enclave rather than passing raw key material into the JavaScript runtime. - Services MUST implement automatic session memory purge (zeroization) upon app backgrounding, app termination, or vault lock events. - Components NEVER store sensitive biometric payloads or raw credentials within JavaScript global states (Pinia, Redux, Zustand) across render lifecycles. ## Bad vs Good Implementations ### Storing Long-Lived Session Tokens & Cryptographic Material #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Writing cryptographic private keys to 'localStorage' exposes them to DOM-based XSS attacks, backup leaks, and unencrypted webview disk caches. Storing tokens using standard '@capacitor/preferences' uses standard SharedPreferences on Android and UserDefaults on iOS, which provide zero hardware protection, lack Secure Enclave/StrongBox backing, and are trivial to extract on compromised devices. ```typescript import { Preferences } from '@capacitor/preferences'; interface SessionPayload { accessToken: string; refreshToken: string; signingKeyPem: string; } export class AuthService { // VULNERABLE: Software-only, plaintext storage vulnerable to WebView extraction and jailbreak/root inspection public async storeSession(session: SessionPayload): Promise<void> { localStorage.setItem('raw_signing_key', session.signingKeyPem); await Preferences.set({ key: 'auth_tokens', value: JSON.stringify({ accessToken: session.accessToken, refreshToken: session.refreshToken }) }); } public async getRefreshToken(): Promise<string | null> { const res = await Preferences.get({ key: 'auth_tokens' }); return res.value ? JSON.parse(res.value).refreshToken : null; } } ``` #### Production Standard (Correct) > **Standard**: Uses an isolated hardware vault interface that forces key generation and credential encryption within the hardware enclave (Secure Enclave on iOS, StrongBox/TEE Keystore on Android). Access requires device-level biometric authentication, the vault automatically locks upon backgrounding, and credentials are never stored unencrypted in WebView databases or preferences. ```typescript import { Vault, DeviceSecurityType, VaultType } from '@ionic-enterprise/identity-vault'; import { Capacitor } from '@capacitor/core'; interface SecureSessionPayload { accessToken: string; refreshToken: string; } export class HardwareVaultService { private vault: Vault; private isInitialized = false; constructor() { // ENFORCED: Backed by iOS Secure Enclave & Android StrongBox Keymaster this.vault = new Vault({ key: 'io.enterprise.app.hardwarevault', type: VaultType.DeviceSecurity, deviceSecurityType: DeviceSecurityType.Biometrics, lockAfterBackgrounded: 2000, shouldClearVaultAfterTooManyFailedAttempts: true, customPasscodeInvalidUnlockAttempts: 3, unlockVaultOnLoad: false }); } public async initialize(): Promise<void> { if (this.isInitialized) return; if (Capacitor.isNativePlatform()) { await this.vault.initialize(); } else { throw new Error('Hardware vault requires native platform execution.'); } this.isInitialized = true; } public async persistSessionTokens(session: SecureSessionPayload): Promise<void> { await this.initialize(); // Tokens are encrypted at rest using a key locked to the Secure Enclave / Android KeyStore await this.vault.setValue('auth_tokens', session); } public async retrieveRefreshToken(): Promise<string | null> { await this.initialize(); const isLocked = await this.vault.isLocked(); if (isLocked) { // Demands Biometric / Enclave pass-through before decrypting await this.vault.unlock(); } const session = await this.vault.getValue<SecureSessionPayload>('auth_tokens'); return session?.refreshToken ?? null; } public async purgeVault(): Promise<void> { await this.initialize(); await this.vault.clear(); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Secure Enclave & Hardware Keystore Vault Interface Invariants

Capacitor 7 Secure Enclave & Hardware Keystore Vault Interface Invariants defines an industrial-grade behavioral standard for mobile engineering. Mandates that all cryptographic private keys, biometric-bound secrets, and high-entropy authentication tokens are strictly sequestered within platform hardware security modules (Apple Secure Enclave and Android StrongBox/KeyStore) rather than standard WebView storage. In Capacitor 7 hybrid environments, access must be mediated via verified native hardware-backed vault bridges enforcing device authentication, key non-exportability, and zeroization of in-memory payloads. 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 Refresh Tokens, Master Cryptographic Keys, or PII in Unencrypted Web Storage or Software-Only Keyrings 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 Refresh Tokens, Master Cryptographic Keys, or PII in Unencrypted Web Storage or Software-Only Keyrings	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 hardware-backed key isolation (Apple Secure Enclave via Keychain Access Groups, Android KeyStore backed by StrongBox or TEE) for any long-lived offline credentials or signing keys.

Engineers MUST ALWAYS enforce hardware-backed key isolation (Apple Secure Enclave via Keychain Access Groups, Android KeyStore backed by StrongBox or TEE) for any long-lived offline credentials or signing keys.

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.