Capacitor 7 Native Biometric Bridge Thread Confinement and Lifecycle Token Invalidation

--- description: Capacitor 7 Native Biometric Bridge Thread Confinement and Lifecycle Token Invalidation - Enforces strict thread-confinement for Capacitor 7 biometric authentication routines, ensuring native execution runs exclusively on serial background dispatch queues rather than the UI/main thread. Concurrently mandates atomic invalidation of volatile biometric session tokens upon app state transition to background or suspension, neutralizing session hijacking and lockup race conditions. globs: src/plugins/**/*.{ts,tsx,swift,java}, src/services/**/*.{ts,tsx}, src/features/auth/**/*.{ts,tsx}, ios/App/App/Plugins/**/*.{swift,h,m}, android/app/src/main/java/**/*.java alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-native-biometric-thread-confinement-guardrail" --- # Capacitor 7 Native Biometric Bridge Thread Confinement and Lifecycle Token Invalidation > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Executing Biometric Prompts on the Main UI Thread Coupled with Persistent In-Memory Session Tokens Across App Suspension ## System Constraints You are a Principal Mobile Architect enforcing Capacitor 7 Native Biometric Bridge Thread-Confinement and Lifecycle Guardrails. Your job is to strictly eliminate UI thread deadlocks caused by synchronous biometric prompts and prevent persistent in-memory biometric authentication tokens across app lifecycle suspension boundaries. ## Strict Guidelines - Engineers MUST ALWAYS isolate native biometric challenge invocations (FaceID, TouchID, BiometricPrompt) to dedicated serial execution queues or background coroutines, resolving the bridge promise asynchronously. - Engineers MUST ALWAYS register native app state listeners (AppState.addListener('appStateChange')) that atomically purge, zero-fill, and invalidate active biometric tokens and decrypted credentials when the state transitions to 'hidden' or 'background'. - Engineers MUST NOT execute biometric evaluation directly on the UI/Main Thread (DispatchQueue.main or Android MainLooper), which locks the WebKit render pipeline during hardware sensor evaluation. - Code SHOULD enforce crypto-bound biometric tokens using transient, hardware-backed keys (Secure Enclave / Android Keystore with setUserAuthenticationRequired(true)) that automatically expire on device lock. - Services MUST reject re-authentication attempts if the app underwent background suspension without going through a full re-evaluation cycle. - Components NEVER store decrypted biometric payload results or biometric session authentication tokens in global un-invalidated reactive states or persistent storage (localStorage, IndexedDB). ## Bad vs Good Implementations ### TypeScript Native Biometric Bridge with Atomic Lifecycle Invalidation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The session token persists across app backgrounding and device lock events, allowing unauthorized extraction if memory is inspected or state restored. Additionally, this relies on unconstrained bridge mechanics that risk freezing WebKit if the native plugin interacts synchronously with the UI queue. ```typescript import { Plugins } from '@capacitor/core'; const { NativeBiometric } = Plugins; export class AuthService { private static sessionToken: string | null = null; // ANTI-PATTERN: Blocking call without background state isolation; // session token remains cached in memory across app backgrounding async authenticate(): Promise<string> { const result = await NativeBiometric.verifyIdentity({ reason: 'Access your secure vault', }); AuthService.sessionToken = result.token; return AuthService.sessionToken; } getToken(): string | null { return AuthService.sessionToken; } } ``` #### Production Standard (Correct) > **Standard**: Enforces proactive initialization of Capacitor AppState listeners to purge and zero-out volatile token memory upon suspension. Ensures invocations target serial background routines, keeping the WebKit bridge responsive. ```typescript import { App, AppState } from '@capacitor/app'; import { registerPlugin, PluginListenerHandle } from '@capacitor/core'; interface BiometricPlugin { authenticateSerial(options: { reason: string }): Promise<{ token: string }>; } const NativeBiometric = registerPlugin<BiometricPlugin>('NativeBiometric'); export class SecureBiometricService { private static volatileToken: Uint8Array | null = null; private static appListener: PluginListenerHandle | null = null; static async initialize(): Promise<void> { if (this.appListener) return; this.appListener = await App.addListener('appStateChange', (state: AppState) => { if (!state.isActive) { SecureBiometricService.invalidateSession(); } }); } static async authenticate(reason: string): Promise<Uint8Array> { await this.initialize(); this.invalidateSession(); // Clear prior state before challenge // Native side executes on serial queue; bridge returns unblocking Promise const { token } = await NativeBiometric.authenticateSerial({ reason }); // Store as volatile byte array for explicit zeroization this.volatileToken = new TextEncoder().encode(token); return this.volatileToken; } static invalidateSession(): void { if (this.volatileToken) { this.volatileToken.fill(0); // Atomic zeroization of sensitive credentials this.volatileToken = null; } } static getActiveSession(): Uint8Array { if (!this.volatileToken) { throw new Error('SEC_ERR_NO_ACTIVE_SESSION: Biometric token invalidated.'); } return this.volatileToken; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Native Biometric Bridge Thread Confinement and Lifecycle Token Invalidation

Capacitor 7 Native Biometric Bridge Thread Confinement and Lifecycle Token Invalidation defines an industrial-grade behavioral standard for mobile engineering. Enforces strict thread-confinement for Capacitor 7 biometric authentication routines, ensuring native execution runs exclusively on serial background dispatch queues rather than the UI/main thread. Concurrently mandates atomic invalidation of volatile biometric session tokens upon app state transition to background or suspension, neutralizing session hijacking and lockup race conditions. 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: Executing Biometric Prompts on the Main UI Thread Coupled with Persistent In-Memory Session Tokens Across App Suspension 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	Executing Biometric Prompts on the Main UI Thread Coupled with Persistent In-Memory Session Tokens Across App Suspension	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 isolate native biometric challenge invocations (FaceID, TouchID, BiometricPrompt) to dedicated serial execution queues or background coroutines, resolving the bridge promise asynchronously.

Engineers MUST ALWAYS isolate native biometric challenge invocations (FaceID, TouchID, BiometricPrompt) to dedicated serial execution queues or background coroutines, resolving the bridge promise asynchronously.

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.