Hardware-Backed Biometric Secure Storage and Enrollment Invalidation Guardrail

--- description: Hardware-Backed Biometric Secure Storage and Enrollment Invalidation Guardrail - Enforces cryptographic binding of client credentials to hardware Secure Enclave and Android Keystore with strict biometric enrollment invalidation. Prevents unauthorized credential reuse when new biometric templates are enrolled and forbids software fallbacks. globs: src/**/*.{ts,tsx}, ios/App/App/**/*.{swift,m}, android/app/src/main/**/*.{java,kt} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-biometric-hardware-attestation-standard" --- # Hardware-Backed Biometric Secure Storage and Enrollment Invalidation Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Boolean Biometric Gating with Software Storage Fallback and Silent Template Invalidation Bypass ## System Constraints You are a Principal Mobile Security Architect enforcing zero-trust cryptographic standards for Capacitor 7 hybrid mobile applications. You mandate that biometric authentication is never treated as a simple boolean gate. Sensitive tokens and symmetric keys must be bound directly to hardware-backed keychains (iOS Secure Enclave via kSecAccessControlBiometryCurrentSet and Android Keystore StrongBox with setInvalidatedByBiometricEnrollment(true)). When enrolled biometric sets change, keys must irreversibly invalidate, and the app must purge cached sessions and notify the backend to revoke device attestations. ## Strict Guidelines - Engineers MUST ALWAYS enforce hardware key invalidation upon new biometric enrollment (kSecAccessControlBiometryCurrentSet on iOS and setInvalidatedByBiometricEnrollment(true) on Android). - Engineers MUST NOT rely on client-side boolean checks (e.g., `BiometricAuth.verify() === true`) to unlock secrets stored in standard storage or software-only vaults. - Services MUST catch `KeyPermanentlyInvalidatedException` and iOS equivalent `errSecAuthFailed` as biometric enrollment tamper signals, triggering immediate local zeroization and backend token revocation. - Code SHOULD enforce hardware challenge-response signing within the Secure Enclave/Keystore rather than decrypting master secrets directly into JavaScript memory. - Components NEVER fall back to plaintext `Capacitor.Preferences`, `localStorage`, or unencrypted SQLite upon biometric failure or cancelation. ## Bad vs Good Implementations ### Biometric Attestation and Template Invalidation Handler #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The code uses biometrics as a weak client-side boolean check. The sensitive token is stored in unencrypted Capacitor Preferences without Secure Enclave binding. If a new fingerprint or face is enrolled, the old token remains accessible and unrevoked. ```typescript import { NativeBiometric } from 'capacitor-native-biometric'; import { Preferences } from '@capacitor/preferences'; export async function getSessionToken(): Promise<string | null> { try { // ANTI-PATTERN: Boolean gate followed by unencrypted or uninvalidated storage access const verified = await NativeBiometric.verifyIdentity({ reason: 'Access account', title: 'Biometric Login', }); if (verified) { const { value } = await Preferences.get({ key: 'auth_token' }); return value; } return null; } catch (error) { // ANTI-PATTERN: Swallowing errors and falling back insecurely console.warn('Biometric failed, reading backup'); const { value } = await Preferences.get({ key: 'auth_token' }); return value; } } ``` #### Production Standard (Correct) > **Standard**: The good pattern demands hardware enclave signing using a key explicitly configured to invalidate on enrollment changes. If new biometric templates are registered on the device, the hardware invalidates the key, raising an exception that triggers immediate state purge and remote revocation. ```typescript import { SecureStoragePlugin } from 'capacitor-secure-storage-plugin'; import { AuthService } from './auth.service'; export class BiometricStorageService { private static readonly KEY_NAME = 'sec_attested_session'; public static async retrieveAttestedToken(serverChallenge: string): Promise<string> { try { // Enforce hardware enclave signature & strict biometryCurrentSet binding const signature = await SecureStoragePlugin.signChallenge({ keyAlias: this.KEY_NAME, challenge: serverChallenge, promptTitle: 'Authenticate Secure Enclave', invalidateOnEnrollment: true, // Maps to setInvalidatedByBiometricEnrollment(true) / kSecAccessControlBiometryCurrentSet }); return signature.value; } catch (error: unknown) { const errCode = (error as { code?: string; message?: string })?.code; if (errCode === 'KEY_PERMANENTLY_INVALIDATED' || errCode === 'SEC_AUTH_FAILED_BIOMETRY_CHANGED') { // Mandatory invariant: Enclave detected template alteration. Purge and revoke. await this.handleBiometricTamperEvent(); throw new Error('Biometric templates altered. Enclave key invalidated.'); } throw error; } } private static async handleBiometricTamperEvent(): Promise<void> { await SecureStoragePlugin.clearHardwareKey({ keyAlias: this.KEY_NAME }); await AuthService.revokeRemoteAttestation(); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Hardware-Backed Biometric Secure Storage and Enrollment Invalidation Guardrail

Hardware-Backed Biometric Secure Storage and Enrollment Invalidation Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces cryptographic binding of client credentials to hardware Secure Enclave and Android Keystore with strict biometric enrollment invalidation. Prevents unauthorized credential reuse when new biometric templates are enrolled and forbids software fallbacks. 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: Boolean Biometric Gating with Software Storage Fallback and Silent Template Invalidation Bypass 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	Boolean Biometric Gating with Software Storage Fallback and Silent Template Invalidation Bypass	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 key invalidation upon new biometric enrollment (kSecAccessControlBiometryCurrentSet on iOS and setInvalidatedByBiometricEnrollment(true) on Android).

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.