Capacitor 7 Hardware-Backed Biometric Enrollment Invalidation Standard

--- description: Capacitor 7 Hardware-Backed Biometric Enrollment Invalidation Standard - Mandates that native cryptographic credentials and long-lived tokens stored in Capacitor 7 hybrid mobile applications strictly bind to hardware-backed biometric sets (kSecAccessControlBiometryCurrentSet on iOS and setInvalidatedByBiometricEnrollment(true) on Android). Forces immediate, atomic local credential destruction and backend session invalidation whenever a device's biometric enrollment configuration changes. globs: src/**/*.{ts,tsx}, ios/App/**/*.{swift,m}, android/app/**/*.{kt,java} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-biometric-enrollment-invalidation" --- # Capacitor 7 Hardware-Backed Biometric Enrollment Invalidation Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Persisting Refresh Tokens Under Permissive Biometric Policies That Retain Access After New Biometric Enrollments ## System Constraints You are a Principal Mobile Security Architect enforcing zero-trust hardware-backed credential storage in Capacitor 7 applications. You must enforce strict biometric enrollment invalidation across Android Keystore and iOS Keychain to prevent unauthorized token access if an attacker or rogue user registers an additional biometric credential on an unlocked device. ## Strict Guidelines - Engineers MUST ALWAYS enforce hardware-backed biometric access control flags tied exclusively to the active biometric set: 'kSecAccessControlBiometryCurrentSet' on iOS and 'setInvalidatedByBiometricEnrollment(true)' on Android Keystore. - Engineers MUST NOT rely on soft UI-only biometric checks (e.g., verifying biometrics with LocalAuthentication or BiometricPrompt and then reading plain tokens from insecure storage like Preferences or default Keychain/SharedPreferences). - Services MUST implement deterministic exception handling for 'KeyPermanentlyInvalidatedException' (Android) and 'errSecAuthFailed' / 'errSecItemNotFound' under biometric-current-set flags (iOS) by instantly wiping the secure vault and invalidating server-side sessions. - Code SHOULD enforce fail-closed cryptographic decryptions such that any tampering, fallback failure, or biometric state mutation triggers atomic memory and storage purges. - Components NEVER store encryption keys or unencrypted refresh tokens in WebStorage (localStorage, sessionStorage) or unencrypted SQLite databases within the Capacitor WebView context. ## Bad vs Good Implementations ### Hardware Biometric Token Access & Enrollment Invalidation Guardrail #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The biometric verification is purely a software gate decoupled from hardware cryptographic keys. If a second fingerprint or face is registered on the device, Preferences.get() continues to return the sensitive token without invalidation, violating mobile zero-trust security postures. ```typescript import { Preferences } from '@capacitor/preferences'; import { NativeBiometric } from 'capacitor-native-biometric'; export async function getSecureRefreshToken(): Promise<string | null> { // Anti-pattern: Decoupled UI verification without hardware cryptographic binding const isAvailable = await NativeBiometric.isAvailable(); if (isAvailable.isAvailable) { const verified = await NativeBiometric.verifyIdentity({ reason: 'Authenticate to access session', }); if (verified) { // Token is stored in plain SharedPreferences/UserDefaults or non-invalidated key const { value } = await Preferences.get({ key: 'auth_refresh_token' }); return value; } } return null; } ``` #### Production Standard (Correct) > **Standard**: Cryptographic material is securely coupled to the device's exact biometric set via hardware-backed KeyStore/Keychain primitives. Any biometric addition or deletion invalidates the underlying key, triggering an atomic local wipe and session eviction. ```typescript import { NativeBiometricVault } from '@/services/nativeBiometricVault'; import { authStateService } from '@/services/authStateService'; export enum BiometricSecurityError { ENROLLMENT_CHANGED = 'BIOMETRIC_ENROLLMENT_CHANGED', AUTH_FAILED = 'BIOMETRIC_AUTH_FAILED', } export async function getHardwareProtectedRefreshToken(): Promise<string> { try { // NativeBiometricVault uses kSecAccessControlBiometryCurrentSet (iOS) // and setInvalidatedByBiometricEnrollment(true) via KeyGenParameterSpec (Android) return await NativeBiometricVault.retrieveToken({ keyAlias: 'auth_session_refresh_token', promptMessage: 'Authenticate with enrolled biometrics', requireCurrentBiometricSet: true, }); } catch (error: unknown) { const err = error as { code?: string; message?: string }; // Android: KeyPermanentlyInvalidatedException | iOS: errSecAuthFailed with mutated biometric set if (err.code === BiometricSecurityError.ENROLLMENT_CHANGED || err.message?.includes('permanently invalidated')) { // Atomic purge across hardware storage and active session state await NativeBiometricVault.purgeCredentials('auth_session_refresh_token'); await authStateService.triggerSecurityEviction({ reason: 'Biometric enrollment set altered. Re-authentication required.', }); throw new Error('Device biometric profile altered. Stored tokens securely destroyed.'); } throw error; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Hardware-Backed Biometric Enrollment Invalidation Standard

Capacitor 7 Hardware-Backed Biometric Enrollment Invalidation Standard defines an industrial-grade behavioral standard for mobile engineering. Mandates that native cryptographic credentials and long-lived tokens stored in Capacitor 7 hybrid mobile applications strictly bind to hardware-backed biometric sets (kSecAccessControlBiometryCurrentSet on iOS and setInvalidatedByBiometricEnrollment(true) on Android). Forces immediate, atomic local credential destruction and backend session invalidation whenever a device's biometric enrollment configuration 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 Refresh Tokens Under Permissive Biometric Policies That Retain Access After New Biometric Enrollments 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 Under Permissive Biometric Policies That Retain Access After New Biometric Enrollments	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 biometric access control flags tied exclusively to the active biometric set

Engineers MUST ALWAYS enforce hardware-backed biometric access control flags tied exclusively to the active biometric set: 'kSecAccessControlBiometryCurrentSet' on iOS and 'setInvalidatedByBiometricEnrollment(true)' on Android Keystore.

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.