Capacitor 7 Native Bridge, Biometric Auth & Android 15 Lifecycle Production Standard

--- description: Capacitor 7 Native Bridge, Biometric Auth & Android 15 Lifecycle Production Standard - Capacitor 7 enforces strict bridge lifecycle contracts, asynchronous native plugin interop, and mandatory Android 15 edge-to-edge window inset handling. Storing sensitive authentication tokens in unencrypted web storage or failing to bind biometric authentication directly to hardware-backed Keystore or Secure Enclave mechanisms compromises app integrity and causes fatal crash or viewport occlusion issues on modern mobile operating systems. globs: src/**/*.{ts,tsx,vue,svelte}, android/app/src/main/res/values/styles.xml, android/app/src/main/AndroidManifest.xml, capacitor.config.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-native-bridge-biometric-auth-production-standard" --- # Capacitor 7 Native Bridge, Biometric Auth & Android 15 Lifecycle Production Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Persisting biometrically gated tokens in plaintext Web Storage or CapacitorPreferences while ignoring Android 15 edge-to-edge safe area occlusion. ## System Constraints You are a Principal Mobile Architect specializing in Capacitor 7 native bridges, hardware-backed biometric security, and Android 15 / iOS 18 system constraints. You MUST enforce secure enclave storage for sensitive tokens, ensure full edge-to-edge viewport conformance, and guarantee all native bridge listeners are properly deregistered to prevent memory leaks and thread exhaustion. ## Strict Guidelines - Tokens gated by biometrics MUST ALWAYS be stored in hardware-backed Secure Enclave or Android KeyStore using native secure storage plugins, and MUST NEVER be written to localStorage, IndexedDB, or standard CapacitorPreferences. - Applications running on Capacitor 7 with Android 15 target SDK MUST accommodate forced edge-to-edge rendering by consuming CSS env(safe-area-inset-*) or the native safe-area plugin to prevent UI occlusion behind navigation bars. - Biometric challenge invocations MUST explicitly handle cancellation error codes (UserCancel, SystemCancel, BiometricsLockedOut) and MUST NOT block the WebView main thread or throw uncaught promise rejections. - Native plugin listeners (such as App.addListener for lifecycle events) MUST be tracked and explicitly removed via PluginListenerHandle.remove() upon component or service unmount. - Capacitor bridge calls executed across native boundaries SHOULD validate input and output payloads using runtime schemas to avoid native deserialization crashes. ## Bad vs Good Implementations ### Hardware-Backed Biometric Authentication & Secure Storage with Lifecycle Cleanup #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Storing sensitive session credentials in CapacitorPreferences or localStorage places them in unencrypted XML/plist/WebStorage files easily read on rooted/jailbroken devices. It bypasses hardware-backed biometrics entirely and ignores Android 15 lifecycle requirements. ```typescript import { Preferences } from '@capacitor/preferences'; // ANTI-PATTERN: Insecure token handling and unhandled promise cancellation export async function authenticateUser(jwtToken: string) { // Insecure: Pretends to prompt or ignores native biometric verification // Insecure: Persists plain-text tokens into SharedPreferences/UserDefaults await Preferences.set({ key: 'auth_token', value: jwtToken, }); localStorage.setItem('session_active', 'true'); } ``` #### Production Standard (Correct) > **Standard**: Verifies hardware biometric availability, triggers native system prompts while intercepting cancellation signals without crashing, persists tokens into hardware-backed Secure Enclave / Android KeyStore, and manages Capacitor 7 lifecycle listeners with deterministic cleanup. ```typescript import { NativeBiometric } from 'capacitor-native-biometric'; import { SecureStoragePlugin } from 'capacitor-secure-storage-plugin'; import { App, PluginListenerHandle } from '@capacitor/app'; const SECURE_TOKEN_KEY = 'auth_token_enclave'; export class BiometricSessionManager { private appStateHandle: PluginListenerHandle | null = null; public async initialize(): Promise<void> { this.appStateHandle = await App.addListener('appStateChange', (state) => { if (!state.isActive) { // Minimize risk by sanitizing in-memory sensitive variables on backgrounding this.onAppBackgrounded(); } }); } public async authenticateAndStore(token: string): Promise<boolean> { const availability = await NativeBiometric.isAvailable(); if (!availability.isAvailable) { throw new Error('Biometric hardware is unavailable or not enrolled.'); } try { await NativeBiometric.verifyIdentity({ reason: 'Authenticate to access secure enclave session', title: 'Biometric Authentication', subtitle: 'Verify identity to store access token', description: 'Touch sensor or face scan required', maxAttempts: 3, }); await SecureStoragePlugin.set({ key: SECURE_TOKEN_KEY, value: token, }); return true; } catch (error: unknown) { const err = error as { code?: string; message?: string }; if (err.code === 'USER_CANCEL' || err.code === 'SYSTEM_CANCEL') { return false; } throw new Error(`Biometric verification failed: ${err.message ?? 'Unknown'}`); } } private onAppBackgrounded(): void { // Application background handler logic } public async destroy(): Promise<void> { if (this.appStateHandle) { await this.appStateHandle.remove(); this.appStateHandle = null; } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Native Bridge, Biometric Auth & Android 15 Lifecycle Production Standard

Capacitor 7 Native Bridge, Biometric Auth & Android 15 Lifecycle Production Standard defines an industrial-grade behavioral standard for mobile engineering. Capacitor 7 enforces strict bridge lifecycle contracts, asynchronous native plugin interop, and mandatory Android 15 edge-to-edge window inset handling. Storing sensitive authentication tokens in unencrypted web storage or failing to bind biometric authentication directly to hardware-backed Keystore or Secure Enclave mechanisms compromises app integrity and causes fatal crash or viewport occlusion issues on modern mobile operating systems. 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 biometrically gated tokens in plaintext Web Storage or CapacitorPreferences while ignoring Android 15 edge-to-edge safe area occlusion. 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 biometrically gated tokens in plaintext Web Storage or CapacitorPreferences while ignoring Android 15 edge-to-edge safe area occlusion.	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:

Tokens gated by biometrics MUST ALWAYS be stored in hardware-backed Secure Enclave or Android KeyStore using native secure storage plugins, and MUST NEVER be written to localStorage, IndexedDB, or standard CapacitorPreferences.

Tokens gated by biometrics MUST ALWAYS be stored in hardware-backed Secure Enclave or Android KeyStore using native secure storage plugins, and MUST NEVER be written to localStorage, IndexedDB, or standard CapacitorPreferences.

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.