Capacitor 7 Hardware-Backed Keystore Attestation & Challenge-Response Protocol

--- description: Capacitor 7 Hardware-Backed Keystore Attestation & Challenge-Response Protocol - Enforces cryptographic hardware-backed attestation (Android KeyStore StrongBox/TEE and iOS Secure Enclave) for biometric authentication flows in Capacitor 7. Prohibits trusting local client-side boolean verification results to prevent runtime hooking attacks (e.g., via Frida, Objection, or substrate) and mandates an ephemeral, server-issued nonce challenge-response protocol. globs: src/**/*.{ts,tsx}, android/app/src/main/java/**/*.java, android/app/src/main/kotlin/**/*.kt, ios/App/App/**/*.swift alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-hardware-keystore-attestation-protocol" --- # Capacitor 7 Hardware-Backed Keystore Attestation & Challenge-Response Protocol > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Trusting Client-Side Boolean Biometric Evaluation Flags Over Server-Verified Hardware Key Signatures ## System Constraints You are a Principal Mobile Security Architect enforcing zero-trust hardware-backed attestation in Capacitor 7. You must reject any biometric implementation that relies on client-side boolean outcomes (e.g., result.isSuccess === true). You mandate that all biometric operations unlock a private key protected by the Secure Enclave or Android StrongBox/TEE that signs a single-use cryptographically random server challenge nonce, with signature and key attestation validated strictly on the backend. ## Strict Guidelines - Engineers MUST ALWAYS fetch a cryptographically secure, time-bounded, single-use nonce from the authorization server immediately prior to requesting biometric authentication. - Engineers MUST ALWAYS require biometric prompts to unlock a hardware-backed asymmetric key pair (P-256 ECC) generated inside the Secure Enclave (kSecAccessControlBiometryAny/CurrentSet) or Android KeyStore (KeyProperties.PURPOSE_SIGN with setUserAuthenticationRequired(true)). - Services MUST NEVER grant authenticated access, elevate privileges, or issue authorization tokens based on a local boolean flag returned by Capacitor biometric plugins. - Engineers MUST pass the server nonce into the native hardware keystore signing pipeline and transmit the raw ECDSA signature, the public key/attestation certificate chain, and client metadata to the backend for cryptographic validation. - Native plugins MUST enforce KeyGenParameterSpec.Builder.setIsStrongBoxBacked(true) on Android when supported, falling back gracefully to TEE, and fail permanently if the key pair is software-backed. ## Bad vs Good Implementations ### Insecure Client-Side Boolean Evaluation vs. Hardware-Backed Nonce Signature Attestation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The client-side boolean flag (`result.isSuccess`) is intercepted and bypassed trivially via runtime instrumentation tools (e.g., `Memory.patch` or method hooking on `BiometricPrompt.AuthenticationCallback`). The backend issues a privileged session without proof of cryptographic execution within a hardware security module. ```typescript import { NativeBiometric } from 'capacitor-native-biometric'; import { apiClient } from '../api/client'; export async function authenticateUser(userId: string): Promise<boolean> { // VULNERABLE: Frida/Objection hooks can intercept NativeBiometric.verifyIdentity // and force return true without biometric hardware activation. const result = await NativeBiometric.verifyIdentity({ reason: 'Authenticate to access secure vault', title: 'Biometric Login', }); if (result.isSuccess) { // DANGEROUS: Server blindly trusts the client's assertion of successful biometrics const response = await apiClient.post('/auth/biometric-session', { userId }); return response.data.authenticated; } return false; } ``` #### Production Standard (Correct) > **Standard**: The authentication flow delegates cryptographic authorization to the Secure Enclave / Android TEE. The hardware-backed private key cannot be extracted or forced to sign without actual user biometric confirmation at the microkernel/TEE level. The backend verifies the signature of the single-use nonce against the public key established during hardware enrollment. ```typescript import { HardwareKeyAttestationPlugin } from '../plugins/hardware-keystore'; import { apiClient } from '../api/client'; interface BiometricAuthResponse { sessionToken: string; } export async function authenticateUserHardwareBacked(userId: string): Promise<BiometricAuthResponse> { // 1. Fetch ephemeral server nonce to prevent replay attacks (TTL: 60s) const { challengeNonce } = await apiClient.post<{ challengeNonce: string }>('/auth/biometric-challenge', { userId, }); // 2. Hardware Enclave unlocks key requiring biometric prompt and signs the challenge // Hardware will reject signing if biometric verification fails or is hooked in user space const { signature, keyAlias, rawPublicKeyDer } = await HardwareKeyAttestationPlugin.signWithBiometricKey({ challenge: challengeNonce, keyAlias: `user_auth_${userId}`, promptTitle: 'Authorize Access', promptSubtitle: 'Verify identity using Secure Enclave / StrongBox', }); // 3. Server validates signature against stored hardware public key & attestation chain const response = await apiClient.post<BiometricAuthResponse>('/auth/verify-hardware-challenge', { userId, challengeNonce, signature, keyAlias, rawPublicKeyDer, }); return response.data; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Hardware-Backed Keystore Attestation & Challenge-Response Protocol

Capacitor 7 Hardware-Backed Keystore Attestation & Challenge-Response Protocol defines an industrial-grade behavioral standard for mobile engineering. Enforces cryptographic hardware-backed attestation (Android KeyStore StrongBox/TEE and iOS Secure Enclave) for biometric authentication flows in Capacitor 7. Prohibits trusting local client-side boolean verification results to prevent runtime hooking attacks (e.g., via Frida, Objection, or substrate) and mandates an ephemeral, server-issued nonce challenge-response protocol. 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 Client-Side Boolean Biometric Evaluation Flags Over Server-Verified Hardware Key Signatures 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 Client-Side Boolean Biometric Evaluation Flags Over Server-Verified Hardware Key Signatures	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 fetch a cryptographically secure, time-bounded, single-use nonce from the authorization server immediately prior to requesting biometric authentication.

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.