Capacitor 7 Hardware-Backed Secure Enclave Session Vault Invariant

Enforces that high-privilege authentication credentials and cryptographic tokens within Capacitor 7 hybrid applications are strictly isolated to platform-native hardware security modules (Apple Secure Enclave and Android StrongBox/TEE). Prohibits persisting session secrets within Chromium or WebKit storage partitions such as localStorage, sessionStorage, or IndexedDB, which are prone to extraction via WebView XSS or unencrypted filesystem inspectability. Mandates transient in-memory handling and hardware-backed biometric authentication gateways for token retrieval.

--- description: Capacitor 7 Hardware-Backed Secure Enclave Session Vault Invariant - Enforces that high-privilege authentication credentials and cryptographic tokens within Capacitor 7 hybrid applications are strictly isolated to platform-native hardware security modules (Apple Secure Enclave and Android StrongBox/TEE). Prohibits persisting session secrets within Chromium or WebKit storage partitions such as localStorage, sessionStorage, or IndexedDB, which are prone to extraction via WebView XSS or unencrypted filesystem inspectability. Mandates transient in-memory handling and hardware-backed biometric authentication gateways for token retrieval. globs: src/auth/**/*.{ts,tsx}, src/services/**/*.{ts,tsx}, src/plugins/**/*.{ts,tsx}, src/core/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-secure-enclave-session-vault-standard" --- # Capacitor 7 Hardware-Backed Secure Enclave Session Vault Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Persisting Session Tokens and Refresh Credentials in WebView Local Storage or Unencrypted Preferences ## System Constraints You are a Principal Mobile Systems Architect and Security Engineer enforcing strict session isolation in Capacitor 7 applications. You must reject any code pattern that persists authentication tokens, JWTs, refresh tokens, or cryptographic key material inside web runtime storage (localStorage, sessionStorage, IndexedDB, or standard unencrypted cookies). Enforce native bridge integration with platform keystores (iOS Keychain backed by Secure Enclave with kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly / Android Keystore backed by StrongBox Keymaster or TEE). Mandate ephemeral in-memory token states that flush on backgrounding and require biometrics or system passcode unlock for token decrypt operations. ## Strict Guidelines - Engineers MUST ALWAYS store long-lived credentials (refresh tokens, private keys) exclusively in platform hardware-backed vaults (e.g., @ionic-enterprise/identity-vault or custom Secure Enclave/Keymaster native bridges). - Engineers MUST NOT write authentication tokens, user credentials, or cryptographic keys to window.localStorage, window.sessionStorage, IndexedDB, or unencrypted SQLite/Preferences partitions. - Services MUST keep access tokens in ephemeral in-memory state only, requesting them dynamically across the native bridge with hardware authentication checks when expired. - Code SHOULD register Capacitor App lifecycle listeners (e.g., App.addListener('appStateChange')) to clear in-memory session caches and lock native vaults when the application transitions to the background. - Components NEVER directly read session credentials from the DOM or expose raw tokens to unmonitored global window variables. ## Bad vs Good Implementations ### Hardware Vault vs. Insecure Web Storage for Hybrid Authentication #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Storing access tokens in localStorage exposes them to arbitrary DOM access and cross-site scripting (XSS) within the WebView. Using Capacitor Preferences without native hardware encryption writes refresh tokens directly to plaintext XML/plist files in the application sandbox, allowing extraction via backup analysis or rooted/jailbroken devices. ```typescript import { Preferences } from '@capacitor/preferences'; interface Session { accessToken: string; refreshToken: string; } export class AuthService { // VULNERABLE: Stores high-privilege tokens in unencrypted web storage or plain SharedPreferences async persistSession(session: Session): Promise<void> { localStorage.setItem('access_token', session.accessToken); await Preferences.set({ key: 'refresh_token', value: session.refreshToken, }); } async getAccessToken(): Promise<string | null> { return localStorage.getItem('access_token'); } } ``` #### Production Standard (Correct) > **Standard**: Delegates persistence entirely to hardware security modules (Apple Secure Enclave / Android StrongBox TEE) via native biometric gating. The ephemeral access token is never written to disk, and the background state listener purges in-memory secrets when the app is minimized, preventing memory dump extractions. ```typescript import { App } from '@capacitor/app'; import { Vault, DeviceSecurityType, VaultType, BrowserVault, } from '@ionic-enterprise/identity-vault'; import { Capacitor } from '@capacitor/core'; interface SessionSecrets { refreshToken: string; } export class SecureSessionVault { private static instance: SecureSessionVault; private vault: Vault | BrowserVault; private ephemeralAccessToken: string | null = null; private constructor() { const config = { key: 'io.enterprise.securevault.auth', type: VaultType.DeviceSecurity, deviceSecurityType: DeviceSecurityType.Biometrics, lockAfterBackgrounded: 2000, shouldClearVaultAfterTooManyFailedAttempts: true, customPasscodeInvalidUnlockAttempts: 3, unlockVaultOnLoad: false, }; this.vault = Capacitor.isNativePlatform() ? new Vault(config) : new BrowserVault(); // For fallback development environments only this.initLifecycleProtection(); } public static getInstance(): SecureSessionVault { if (!SecureSessionVault.instance) { SecureSessionVault.instance = new SecureSessionVault(); } return SecureSessionVault.instance; } private initLifecycleProtection(): void { if (Capacitor.isNativePlatform()) { App.addListener('appStateChange', ({ isActive }) => { if (!isActive) { this.purgeVolatileMemory(); } }); } } public async storeRefreshToken(refreshToken: string): Promise<void> { await this.vault.setValue('refreshToken', refreshToken); } public async retrieveRefreshToken(): Promise<string | null> { if (await this.vault.isLocked()) { await this.vault.unlock(); } return this.vault.getValue('refreshToken'); } public setEphemeralAccessToken(token: string): void { this.ephemeralAccessToken = token; } public getEphemeralAccessToken(): string | null { return this.ephemeralAccessToken; } public purgeVolatileMemory(): void { this.ephemeralAccessToken = null; } public async clearSession(): Promise<void> { this.purgeVolatileMemory(); await this.vault.clear(); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Hardware-Backed Secure Enclave Session Vault Invariant

Capacitor 7 Hardware-Backed Secure Enclave Session Vault Invariant defines an industrial-grade behavioral standard for mobile engineering. Enforces that high-privilege authentication credentials and cryptographic tokens within Capacitor 7 hybrid applications are strictly isolated to platform-native hardware security modules (Apple Secure Enclave and Android StrongBox/TEE). Prohibits persisting session secrets within Chromium or WebKit storage partitions such as localStorage, sessionStorage, or IndexedDB, which are prone to extraction via WebView XSS or unencrypted filesystem inspectability. Mandates transient in-memory handling and hardware-backed biometric authentication gateways for token retrieval. 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 Session Tokens and Refresh Credentials in WebView Local Storage or Unencrypted Preferences 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 Session Tokens and Refresh Credentials in WebView Local Storage or Unencrypted Preferences	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 store long-lived credentials (refresh tokens, private keys) exclusively in platform hardware-backed vaults (e.g., @ionic-enterprise/identity-vault or custom Secure Enclave/Keymaster native bridges).

Engineers MUST ALWAYS store long-lived credentials (refresh tokens, private keys) exclusively in platform hardware-backed vaults (e.g., @ionic-enterprise/identity-vault or custom Secure Enclave/Keymaster native bridges).

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.