Capacitor 7 Biometric Hardware Key Attestation & Token Invariant

--- description: Capacitor 7 Biometric Hardware Key Attestation & Token Invariant - Enforces that client-side authentication tokens and cryptographic challenges in Capacitor 7 hybrid applications are anchored to hardware-backed keystores (Apple Secure Enclave, Android StrongBox/TEE) via non-exportable biometric-bound keys. This prevents Cross-Site Scripting (DOM injection) vulnerabilities within the WebView from exfiltrating access tokens or forging authenticated transactions. globs: src/**/*.{ts,tsx}, ios/App/App/**/*.{swift,m}, android/app/src/main/java/**/*.{java,kt} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-biometric-hardware-key-attestation-invariant" --- # Capacitor 7 Biometric Hardware Key Attestation & Token Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Persisting raw bearer tokens in WebView-accessible storage (localStorage, IndexedDB, or standard unauthenticated native preferences) susceptible to DOM exfiltration. ## System Constraints You are a Principal Mobile Security Architect enforcing the Capacitor 7 Biometric Hardware Key Attestation Invariant. You must reject any code storing unencrypted session tokens in localStorage, IndexedDB, or standard Capacitor Preferences. You must mandate asymmetric key pairs generated inside hardware-backed keystores (Secure Enclave or Android StrongBox/TEE) requiring UserPresence or Biometric authentication for every private key signature operation. Session validation must use ephemeral cryptographic challenge-response signatures rather than passing static bearer credentials through the DOM. ## Strict Guidelines - Engineers MUST ALWAYS generate cryptographic key pairs natively within the hardware-backed keystore (Secure Enclave or StrongBox/TEE) with non-exportable private keys requiring biometric access control flags. - Engineers MUST NOT store long-lived bearer tokens (JWTs, OAuth refresh tokens) in the WebView DOM storage (window.localStorage, sessionStorage, IndexedDB) or unencrypted native storage. - Code SHOULD enforce native challenge-response signing where the backend issues a high-entropy, short-lived cryptographic nonce that is signed inside the hardware security module upon biometric prompt. - Services MUST verify hardware key attestation records (Apple DeviceCheck/App Attest or Android KeyStore Key Attestation) during client enrollment to verify keys originated in genuine hardware security chips. - Components NEVER expose private keys to the JavaScript runtime; only public keys and cryptographic signatures generated via the native bridge may cross the Capacitor boundary. ## Bad vs Good Implementations ### Hardware-Bound Biometric Signature vs DOM Storage #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Reading static session tokens across the bridge and passing them via HTTP headers allows any DOM-based injection (XSS or malicious third-party script) to steal the token and impersonate the user indefinitely. ```typescript import { Preferences } from '@capacitor/preferences'; import axios from 'axios'; export async function authenticateTransaction(amount: number, recipient: string) { // CRITICAL VULNERABILITY: Bearer token is exposed to DOM injection/XSS const { value: bearerToken } = await Preferences.get({ key: 'auth_token' }); return axios.post('/api/transact', { amount, recipient }, { headers: { Authorization: `Bearer ${bearerToken}` } }); } ``` #### Production Standard (Correct) > **Standard**: Private keys never enter the WebView runtime. The hardware-backed Secure Enclave or StrongBox creates an asymmetric signature over an ephemeral challenge only when authenticated biometrically, mitigating token exfiltration. ```typescript import { registerPlugin } from '@capacitor/core'; import axios from 'axios'; interface HardwareCryptoPlugin { signPayload(options: { payload: string; prompt: string }): Promise<{ signature: string; keyId: string }>; } const HardwareCrypto = registerPlugin<HardwareCryptoPlugin>('HardwareCrypto'); export async function authenticateTransaction(amount: number, recipient: string) { // 1. Fetch ephemeral server nonce (prevents replay attacks) const { data: challenge } = await axios.get<{ nonce: string }>('/api/auth/challenge'); const payload = JSON.stringify({ amount, recipient, nonce: challenge.nonce, timestamp: Date.now() }); // 2. Hardware Enclave prompts biometrics and signs with non-exportable private key const { signature, keyId } = await HardwareCrypto.signPayload({ payload, prompt: 'Authorize transaction via Touch ID / Face ID / Biometrics' }); // 3. Submit transaction with hardware-attested signature; no bearer token in DOM return axios.post('/api/transact', { payload, signature, keyId }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Biometric Hardware Key Attestation & Token Invariant

Capacitor 7 Biometric Hardware Key Attestation & Token Invariant defines an industrial-grade behavioral standard for mobile engineering. Enforces that client-side authentication tokens and cryptographic challenges in Capacitor 7 hybrid applications are anchored to hardware-backed keystores (Apple Secure Enclave, Android StrongBox/TEE) via non-exportable biometric-bound keys. This prevents Cross-Site Scripting (DOM injection) vulnerabilities within the WebView from exfiltrating access tokens or forging authenticated transactions. 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 raw bearer tokens in WebView-accessible storage (localStorage, IndexedDB, or standard unauthenticated native preferences) susceptible to DOM exfiltration. 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 raw bearer tokens in WebView-accessible storage (localStorage, IndexedDB, or standard unauthenticated native preferences) susceptible to DOM exfiltration.	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 generate cryptographic key pairs natively within the hardware-backed keystore (Secure Enclave or StrongBox/TEE) with non-exportable private keys requiring biometric access control flags.

Engineers MUST ALWAYS generate cryptographic key pairs natively within the hardware-backed keystore (Secure Enclave or StrongBox/TEE) with non-exportable private keys requiring biometric access control flags.

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.