Capacitor 7 Biometric Hardware Keystore Invalidation & Secure Enclave Attestation

--- description: Capacitor 7 Biometric Hardware Keystore Invalidation & Secure Enclave Attestation - Enforces cryptographic hardware-backed key revocation and state-bound attestation across Android KeyStore and iOS Secure Enclave within Capacitor 7 architectures. Guarantees that any device biometric enrollment modification (e.g., newly added fingerprints or facial enrollments) permanently invalidates cached biometric keys and purges authentication tokens. Prevents cross-identity session hijacking and unauthorized hardware-level key reuse across OS credential changes. globs: src/**/*.{ts,tsx}, android/app/src/main/java/**/*.java, ios/App/App/**/*.swift alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-biometric-keystore-hardware-attestation-guardrail" --- # Capacitor 7 Biometric Hardware Keystore Invalidation & Secure Enclave Attestation > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Persisting Unbound Refresh Tokens or Bypassing invalidateOnEnrollment Hardware Keystore Flags ## System Constraints You are a Principal Mobile Security Architect enforcing zero-trust hardware-backed credential storage in Capacitor 7 applications. You must ensure that all biometric authentication flows bind cryptographic key lifecycles directly to the hardware Secure Enclave (iOS) and Android KeyStore (Android) with biometric enrollment invalidation enabled. Never permit pure software-based fallback tokens, unauthenticated biometric boolean checks, or retention of decrypted tokens in web-runtime state across lifecycle pauses. ## Strict Guidelines - Engineers MUST ALWAYS enforce hardware-backed key creation using `setInvalidatedByBiometricEnrollment(true)` on Android and `kSecAccessControlBiometryCurrentSet` on iOS. - Engineers MUST NOT rely on mere boolean return flags from biometric plugins (`isAvailable`, `verifyBiometrics`) to authorize API sessions; cryptographic signing or decryption via the Secure Enclave/KeyStore MUST occur to release session credentials. - Code SHOULD catch OS-level key invalidation errors (`KeyPermanentlyInvalidatedException` / `errSecKeyInvalidated`) and immediately execute an unrecoverable local logout and remote token revocation. - Services MUST clear unencrypted tokens and key material from in-memory JavaScript/TypeScript state immediately after completing network requests or during app backgrounding lifecycle events. - Components NEVER store sensitive refresh tokens in unencrypted web storage engines such as `localStorage`, `sessionStorage`, or unencrypted IndexedDB. ## Bad vs Good Implementations ### Biometric Credential Retrieval with Cryptographic Invalidation Handling #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The implementation performs a decoupled, client-side boolean prompt. It retrieves the secret from unencrypted localStorage without binding token decryption to hardware-attested key state. If an attacker gains device access and registers an additional fingerprint or face, the app happily accepts the new biometric and surrenders the token. ```typescript import { NativeBiometric } from 'capacitor-native-biometric'; export async function getSessionToken(): Promise<string | null> { // Anti-pattern: Relies solely on a UI prompt boolean without hardware-level key binding const verification = await NativeBiometric.verifyIdentity({ reason: 'Please authenticate to proceed', title: 'Biometric Login', }); if (verification) { // Vulnerable: Stored token is completely accessible even if new biometrics were enrolled return localStorage.getItem('auth_refresh_token'); } return null; } ``` #### Production Standard (Correct) > **Standard**: The good pattern configures explicit hardware flags (`invalidateOnEnrollment: true`) targeting Android KeyStore's `setInvalidatedByBiometricEnrollment` and iOS's `kSecAccessControlBiometryCurrentSet`. When any new biometric enrollment alters device state, the hardware cryptographic key permanently self-destructs, throwing an invalidation exception that forces a local teardown and server-side session termination. ```typescript import { SecureStoragePlugin } from 'capacitor-secure-storage-plugin'; import { App } from '@capacitor/app'; interface HardwareCryptoError extends Error { code?: string; } export async function getAttestedSessionSecret(keyAlias: string): Promise<string> { try { // Enforces cryptographic key retrieval bound to kSecAccessControlBiometryCurrentSet // and Android KeyGenParameterSpec.setInvalidatedByBiometricEnrollment(true) const { value } = await SecureStoragePlugin.get({ key: keyAlias, options: { biometricAuth: true, biometricPrompt: 'Authenticate to access cryptographic key', invalidateOnEnrollment: true, // Hardware Enclave / StrongBox requirement }, }); return value; } catch (error: unknown) { const err = error as HardwareCryptoError; // Hardware KeyPermanentlyInvalidatedException or errSecKeyInvalidated if (err.code === 'KEY_INVALIDATED' || err.message?.includes('invalidated')) { await purgeCompromisedSession(); throw new Error('HARDWARE_SECURITY_BREACH_DETECTED: Biometric enrollment state mutated. Session invalidated.'); } throw error; } } async function purgeCompromisedSession(): Promise<void> { await SecureStoragePlugin.clear().catch(() => {}); // Force clear webview memory references sessionStorage.clear(); window.location.replace('/login?reason=biometric_invalidation'); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Biometric Hardware Keystore Invalidation & Secure Enclave Attestation

Capacitor 7 Biometric Hardware Keystore Invalidation & Secure Enclave Attestation defines an industrial-grade behavioral standard for mobile engineering. Enforces cryptographic hardware-backed key revocation and state-bound attestation across Android KeyStore and iOS Secure Enclave within Capacitor 7 architectures. Guarantees that any device biometric enrollment modification (e.g., newly added fingerprints or facial enrollments) permanently invalidates cached biometric keys and purges authentication tokens. Prevents cross-identity session hijacking and unauthorized hardware-level key reuse across OS credential changes. 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 Unbound Refresh Tokens or Bypassing invalidateOnEnrollment Hardware Keystore Flags 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 Unbound Refresh Tokens or Bypassing invalidateOnEnrollment Hardware Keystore Flags	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 creation using `setInvalidatedByBiometricEnrollment(true)` on Android and `kSecAccessControlBiometryCurrentSet` on iOS.

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.