Capacitor 7 Secure Hardware-Backed WebAuthn Biometric Bridge Invariant

--- description: Capacitor 7 Secure Hardware-Backed WebAuthn Biometric Bridge Invariant - Enforces that FIDO2/WebAuthn cryptographic key generation and assertion signing never cross into the Capacitor JavaScript WebView runtime. All biometric cryptographic operations must bind directly to native platform authenticators (iOS Secure Enclave via AuthenticationServices and Android StrongBox/TEE via Credential Manager), treating the JavaScript runtime strictly as a blind challenge-response relay. 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-hardware-webauthn-biometric-bridge-invariant" --- # Capacitor 7 Secure Hardware-Backed WebAuthn Biometric Bridge Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Simulating WebAuthn Credentials or Emulating Key Material in JavaScript Memory ## System Constraints You are a Principal Mobile Security Architect enforcing strict hardware-backed cryptographic boundaries in Capacitor 7 applications. You must prevent any pattern that exposes raw private keys, simulates WebAuthn with software-based WebCrypto in the WebView, or handles biometrics without hardware-isolated platform authenticators. Ensure that iOS ASAuthorizationController and Android Credential Manager APIs handle all cryptographic primitives directly inside the Secure Enclave or StrongBox Keystore. ## Strict Guidelines - Engineers MUST ALWAYS delegate WebAuthn operations to native platform authenticators (Apple AuthenticationServices on iOS; Credential Manager API on Android 14+ / Google Play Services) via a verified native Capacitor 7 plugin bridge. - Engineers MUST NOT generate, import, or manipulate asymmetric private keys or raw seed entropy inside the JavaScript WebView runtime. - Code SHOULD enforce `userVerification: 'required'` across all native bridge registrations and assertions to ensure platform biometric hardware gates every cryptographic signature. - Services MUST transport backend Relying Party (RP) challenges directly into the native bridge as opaque base64url nonces without in-flight JS mutation or storage in insecure persistence layers. - Components NEVER store attestation statements, raw client data JSON, or authenticator data in local storage, IndexedDB, or memory caches longer than the immediate invocation lifecycle. ## Bad vs Good Implementations ### Native Hardware Bridge vs. In-Memory WebCrypto Polyfill #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: This anti-pattern attempts to simulate WebAuthn credentials inside the WebView using extractable WebCrypto keys. Key material exists in the JavaScript V8/JavaScriptCore heap, bypassing iOS Secure Enclave and Android StrongBox hardware protection. ```typescript import { Preferences } from '@capacitor/preferences'; // VULNERABILITY: Emulating WebAuthn in WebView memory using WebCrypto // Exposes private key material to XSS and memory scraping inside the JavaScript engine. export async function registerBiometricCredential(challenge: string): Promise<{ id: string; key: string }> { const keyPair = await window.crypto.subtle.generateKey( { name: 'ECDSA', namedCurve: 'P-256', }, true, // Extractable private key allows memory exfiltration ['sign', 'verify'] ); const exportedPriv = await window.crypto.subtle.exportKey('pkcs8', keyPair.privateKey); const keyString = btoa(String.fromCharCode(...new Uint8Array(exportedPriv))); // Storing synthetic credentials in unprotected Capacitor storage await Preferences.set({ key: 'auth_key', value: keyString }); return { id: crypto.randomUUID(), key: keyString, }; } ``` #### Production Standard (Correct) > **Standard**: The native bridge hands the RP challenge directly to the underlying platform authenticators. The private key is created and locked within hardware-backed security modules (Secure Enclave/StrongBox) and cannot be inspected or leaked by JavaScript runtime memory. ```typescript import { registerPlugin } from '@capacitor/core'; interface NativePasskeyPlugin { register( options: NativePasskeyRegisterOptions ): Promise<NativePasskeyRegistrationResult>; } interface NativePasskeyRegisterOptions { rpId: string; challengeBase64Url: string; userIdBase64Url: string; userName: string; userVerification: 'required' | 'preferred'; } interface NativePasskeyRegistrationResult { credentialId: string; clientDataJSON: string; attestationObject: string; } const NativePasskey = registerPlugin<NativePasskeyPlugin>('NativePasskey'); // PRODUCTION INVARIANT: JavaScript runtime operates exclusively as a blind transit pipe. // Hardware generation remains fully confined within ASAuthorizationController / CredentialManager. export async function registerHardwareWebAuthn( rpId: string, challenge: string, userId: string, userName: string ): Promise<NativePasskeyRegistrationResult> { return await NativePasskey.register({ rpId, challengeBase64Url: challenge, userIdBase64Url: userId, userName, userVerification: 'required', }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Secure Hardware-Backed WebAuthn Biometric Bridge Invariant

Capacitor 7 Secure Hardware-Backed WebAuthn Biometric Bridge Invariant defines an industrial-grade behavioral standard for mobile engineering. Enforces that FIDO2/WebAuthn cryptographic key generation and assertion signing never cross into the Capacitor JavaScript WebView runtime. All biometric cryptographic operations must bind directly to native platform authenticators (iOS Secure Enclave via AuthenticationServices and Android StrongBox/TEE via Credential Manager), treating the JavaScript runtime strictly as a blind challenge-response relay. 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: Simulating WebAuthn Credentials or Emulating Key Material in JavaScript Memory 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	Simulating WebAuthn Credentials or Emulating Key Material in JavaScript Memory	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 delegate WebAuthn operations to native platform authenticators (Apple AuthenticationServices on iOS

Engineers MUST ALWAYS delegate WebAuthn operations to native platform authenticators (Apple AuthenticationServices on iOS; Credential Manager API on Android 14+ / Google Play Services) via a verified native Capacitor 7 plugin bridge.

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.