Hardware-Backed Biometric Attestation and Cryptographic Replay-Resistant Bridge Binding

--- description: Hardware-Backed Biometric Attestation and Cryptographic Replay-Resistant Bridge Binding - Requires all Capacitor 7 native biometric verification flows to utilize hardware-backed key attestation (Secure Enclave/StrongBox) with cryptographic challenge-response validation. Forbids relying on boolean bridge evaluation responses ({ success: true }), enforcing backend signature verification and strict session-nonce binding across native-to-web boundaries. globs: src/**/services/auth/**/*.{ts,tsx}, src/**/plugins/**/*.{ts,tsx}, src/**/biometrics/**/*.{ts,tsx}, src/**/security/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor7-biometric-attestation-replay-binding" --- # Hardware-Backed Biometric Attestation and Cryptographic Replay-Resistant Bridge Binding > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Trusting Boolean Native Bridge Returns for Biometric Authorization Without Hardware-Backed Cryptographic Attestation ## System Constraints You are a Principal Mobile Security Architect enforcing Capacitor 7 Biometric Key Attestation and Replay-Resistant Session Binding. Mandate that all biometric authentication across the native-to-web cross-bridge uses hardware-backed cryptographic challenge-response schemes, binding backend sessions to Secure Enclave or StrongBox signatures rather than trusting client-side boolean flags. ## Strict Guidelines - Engineers MUST NEVER trust client-side boolean results (e.g., `result.isSuccess === true` or `{ verified: true }`) across the Capacitor bridge to authorize sensitive state transitions. - Engineers MUST request an ephemeral cryptographic challenge (minimum 256-bit cryptographically secure pseudorandom nonce, max 60-second TTL) from the backend authorization server prior to every native biometric prompt. - Engineers MUST generate private keys in native hardware-backed storage (iOS Secure Enclave / Android StrongBox/Keystore) flagged with strict biometric user authentication requirements (`UserPresence` or `BiometricAny`). - Native biometric plugins MUST return a cryptographic signature of the server challenge along with the hardware key ID, device attestation chain, and an incrementing monotonic counter across the bridge. - Web client services MUST transmit the signature, original challenge, and hardware metadata to the backend for asymmetric signature validation and nonce invalidation before issuing or elevating a session token. - Authentication payloads MUST cryptographically bind the ephemeral challenge to the active WebView origin, native bundle identifier, and target user ID to prevent cross-app relay and confused-deputy attacks. - Components NEVER store unprotected private keys or cached biometric credentials in LocalStorage, IndexedDB, or standard unencrypted bridge preferences. ## Bad vs Good Implementations ### Naive Boolean Bridge Check vs. Cryptographic Hardware Attestation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Trusts a malleable boolean response across the Capacitor native-to-web bridge. A local runtime hook (e.g., Frida or WebView JavaScript injection) can override `result.isSuccess` to true without user interaction or biometric validation, allowing unauthorized privilege escalation. ```typescript import { NativeBiometric } from '@capgo/capacitor-native-biometric'; import { api } from '@/services/api'; export async function authenticateWithBiometrics(userId: string): Promise<boolean> { // VULNERABLE: Relies on boolean returned across Capacitor bridge. // Can be hooked/spoofed via Frida, injected JS, or compromised WebView bridge. const result = await NativeBiometric.verifyIdentity({ reason: 'Authorize transaction', title: 'Biometric Login', }); if (result.isSuccess) { // Insecure: Client informs server that biometric auth succeeded const session = await api.post('/auth/session/elevate', { userId, verified: true }); localStorage.setItem('session_token', session.token); return true; } return false; } ``` #### Production Standard (Correct) > **Standard**: Implements an end-to-end cryptographic challenge-response flow. The server issues a single-use nonce. The native layer signs the nonce inside hardware-backed storage (Secure Enclave/StrongBox) gated by biometrics. The server verifies the signature against the registered public key, preventing bridge tampering, replay attacks, and client spoofing. ```typescript import { SecureHardwareBiometrics } from '@/plugins/secure-hardware-biometrics'; import { apiClient } from '@/services/api-client'; interface BiometricChallengeResponse { challengeId: string; nonce: string; // Base64 encoded 256-bit server nonce expiresAt: number; } interface BiometricVerificationPayload { challengeId: string; keyId: string; signature: string; // Base64 ECDSA P-256 signature from Secure Enclave/StrongBox deviceAttestationCert?: string; counter: number; } export async function authenticateWithHardwareBiometrics(userId: string): Promise<string> { // 1. Fetch single-use ephemeral challenge from the backend const challenge = await apiClient.post<BiometricChallengeResponse>('/auth/biometrics/challenge', { userId, clientTime: Date.now(), }); // 2. Instruct native hardware key (Secure Enclave / Android Keystore) to sign the nonce // Hardware will only release signature upon physical biometric confirmation const signResult = await SecureHardwareBiometrics.signChallenge({ keyAlias: `user-biometric-key-${userId}`, challengeNonce: challenge.nonce, promptTitle: 'Authorize Session', promptSubtitle: 'Confirm biometric identity', }); const payload: BiometricVerificationPayload = { challengeId: challenge.challengeId, keyId: signResult.keyId, signature: signResult.signature, deviceAttestationCert: signResult.attestationCertChain, counter: signResult.operationCounter, }; // 3. Cryptographically verify signature and invalidate nonce on server const response = await apiClient.post<{ sessionToken: string }>('/auth/biometrics/verify', payload); return response.sessionToken; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Hardware-Backed Biometric Attestation and Cryptographic Replay-Resistant Bridge Binding

Hardware-Backed Biometric Attestation and Cryptographic Replay-Resistant Bridge Binding defines an industrial-grade behavioral standard for mobile engineering. Requires all Capacitor 7 native biometric verification flows to utilize hardware-backed key attestation (Secure Enclave/StrongBox) with cryptographic challenge-response validation. Forbids relying on boolean bridge evaluation responses ({ success: true }), enforcing backend signature verification and strict session-nonce binding across native-to-web boundaries. 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: Trusting Boolean Native Bridge Returns for Biometric Authorization Without Hardware-Backed Cryptographic Attestation 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	Trusting Boolean Native Bridge Returns for Biometric Authorization Without Hardware-Backed Cryptographic Attestation	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 NEVER trust client-side boolean results (e.g., `result.isSuccess === true` or `{ verified

Engineers MUST NEVER trust client-side boolean results (e.g., `result.isSuccess === true` or `{ verified: true }`) across the Capacitor bridge to authorize sensitive state transitions.

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.