Capacitor 7 Hardware-Bound Biometric Session Invalidation Invariant

--- description: Capacitor 7 Hardware-Bound Biometric Session Invalidation Invariant - Eliminates token hijacking and persistent session leakage in hybrid runtimes by tying WebView session persistence directly to Secure Enclave and Android StrongBox cryptographic key lifecycles. Mandates that authentication tokens stored across the bridge are encrypted with hardware-backed keys configured to invalidate immediately upon biometric enrollment changes or OS-level credential revocation. globs: src/services/auth/**/*.{ts,tsx}, src/plugins/**/*.{ts,tsx}, 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/capacitor7-hardware-biometric-session-invalidation" --- # Capacitor 7 Hardware-Bound Biometric Session Invalidation Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Persisting Raw Bearer Tokens in WebView LocalStorage or Unbound Keychains Vulnerable to Extraction and Biometric Re-enrollment Hijacking ## System Constraints You are a Principal Mobile Security Architect enforcing zero-trust hardware-bound authentication invariants in Capacitor 7 hybrid applications. You must ensure that WebView runtimes never hold raw long-lived tokens in insecure local storage, IndexedDB, or standard unauthenticated native preferences. Every session-bearing credential must be encrypted using hardware-backed asymmetric keys generated inside iOS Secure Enclave (kSecAccessControlBiometryCurrentSet) or Android StrongBox Keymaster/KeyMint (setInvalidatedByBiometricEnrollment(true)). Any cryptographic operation failure indicating key invalidation due to newly registered biometrics or lock-screen changes must atomically purge in-memory credentials and trigger an immediate bridge-level hard logout. ## Strict Guidelines - Engineers MUST ALWAYS store session tokens encrypted at rest via hardware-backed keychains leveraging Apple Secure Enclave or Android StrongBox/TEE. - Engineers MUST configure iOS Keychain items with `kSecAccessControlBiometryCurrentSet` to ensure cryptographic keys automatically invalidate when new biometric enrollments occur. - Engineers MUST configure Android KeyGenParameterSpec with `setInvalidatedByBiometricEnrollment(true)` and `setUserAuthenticationRequired(true)`. - Engineers MUST NOT store unencrypted refresh tokens or JWTs inside WebView `localStorage`, `sessionStorage`, or `IndexedDB`. - Code MUST trap OS-level key invalidation exceptions (`KeyPermanentlyInvalidatedException` on Android and `errSecItemNotFound` or `errSecAuthFailed` under `CurrentSet` on iOS) and unconditionally purge WebView session memory. - Services MUST request ephemeral cryptographic signing challenges or decryption handles via the Capacitor 7 Native Bridge strictly per API transaction cycle, never caching decrypted refresh tokens across app resume cycles. ## Bad vs Good Implementations ### Hardware-Bound Biometric Token Storage and Bridge-Level Invalidation Handling #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Storing tokens using generic Preferences or localStorage bypasses Secure Enclave and StrongBox guarantees. If an attacker gains device access and registers a new biometric imprint, the existing session remains completely valid and accessible. ```typescript import { Preferences } from '@capacitor/preferences'; interface Session { accessToken: string; refreshToken: string; } export class InsecureAuthService { // VULNERABLE: Tokens are stored unencrypted in WebView-accessible native preferences. // An attacker with WebView XSS, native backup access, or a newly enrolled fingerprint // retains complete session access without hardware attestation or invalidation. async persistSession(session: Session): Promise<void> { await Preferences.set({ key: 'auth_session', value: JSON.stringify(session), }); } async getSession(): Promise<Session | null> { const raw = await Preferences.get({ key: 'auth_session' }); return raw.value ? JSON.parse(raw.value) : null; } } ``` #### Production Standard (Correct) > **Standard**: Tokens are hardware-encrypted with keys bound to the current biometric configuration. Modifying enrolled biometrics forces the OS to permanently invalidate the keys, which this service detects, purging in-memory and persisted state. ```typescript import { registerPlugin } from '@capacitor/core'; export interface HardwareKeyStorePlugin { encryptToken(options: { alias: string; payload: string }): Promise<{ encryptedBlob: string }>; decryptToken(options: { alias: string; encryptedBlob: string }): Promise<{ decryptedPayload: string }>; purgeHardwareKeys(options: { alias: string }): Promise<void>; } const HardwareKeyStore = registerPlugin<HardwareKeyStorePlugin>('HardwareKeyStore'); export class SecureHardwareAuthService { private static readonly KEY_ALIAS = 'prod_session_hw_key'; private static readonly STORAGE_CIPHERTEXT_KEY = 'hw_bound_auth_blob'; async persistHardwareBoundSession(refreshToken: string): Promise<void> { // Hardware KeyStore creates/uses key with biometryCurrentSet & setInvalidatedByBiometricEnrollment(true) const { encryptedBlob } = await HardwareKeyStore.encryptToken({ alias: SecureHardwareAuthService.KEY_ALIAS, payload: refreshToken, }); sessionStorage.setItem(SecureHardwareAuthService.STORAGE_CIPHERTEXT_KEY, encryptedBlob); } async resolveHardwareBoundSession(): Promise<string> { const encryptedBlob = sessionStorage.getItem(SecureHardwareAuthService.STORAGE_CIPHERTEXT_KEY); if (!encryptedBlob) { throw new Error('AUTH_SESSION_NOT_FOUND'); } try { const { decryptedPayload } = await HardwareKeyStore.decryptToken({ alias: SecureHardwareAuthService.KEY_ALIAS, encryptedBlob, }); return decryptedPayload; } catch (error: unknown) { const message = error instanceof Error ? error.message : String(error); // Invariant: Traps KeyPermanentlyInvalidatedException or errSecItemNotFound / errSecAuthFailed if ( message.includes('KeyPermanentlyInvalidatedException') || message.includes('errSecAuthFailed') || message.includes('BIOMETRIC_ENROLLMENT_MODIFIED') ) { await this.handleHardwareInvalidation(); } throw error; } } private async handleHardwareInvalidation(): Promise<void> { sessionStorage.clear(); await HardwareKeyStore.purgeHardwareKeys({ alias: SecureHardwareAuthService.KEY_ALIAS }); window.dispatchEvent(new CustomEvent('app:session-invalidated', { detail: { reason: 'BIOMETRIC_RE_ENROLLMENT' } })); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Hardware-Bound Biometric Session Invalidation Invariant

Capacitor 7 Hardware-Bound Biometric Session Invalidation Invariant defines an industrial-grade behavioral standard for mobile engineering. Eliminates token hijacking and persistent session leakage in hybrid runtimes by tying WebView session persistence directly to Secure Enclave and Android StrongBox cryptographic key lifecycles. Mandates that authentication tokens stored across the bridge are encrypted with hardware-backed keys configured to invalidate immediately upon biometric enrollment changes or OS-level credential revocation. 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 LocalStorage or Unbound Keychains Vulnerable to Extraction and Biometric Re-enrollment Hijacking 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 LocalStorage or Unbound Keychains Vulnerable to Extraction and Biometric Re-enrollment Hijacking	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 session tokens encrypted at rest via hardware-backed keychains leveraging Apple Secure Enclave or Android StrongBox/TEE.

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.