Hardware-Backed Enclave Biometric Session Attestation for Capacitor 7 Bridge RPCs

--- description: Hardware-Backed Enclave Biometric Session Attestation for Capacitor 7 Bridge RPCs - Capacitor 7 hybrid WebViews must never trust raw boolean biometric flags returned over the bridge. High-privilege native bridge RPC operations require hardware-level cryptographic session attestation where the iOS Secure Enclave or Android StrongBox/TEE signs an ephemeral server-originated challenge upon biometric unlock, guaranteeing proof of physical presence. 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-enclave-biometric-session-attestation" --- # Hardware-Backed Enclave Biometric Session Attestation for Capacitor 7 Bridge RPCs > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Trusting Boolean Bridge Results ({ authenticated: true }) for Sensitive RPC Operations ## System Constraints You are a Principal Mobile Security Architect enforcing hardware-backed biometric cryptographic attestation in Capacitor 7 applications. Your directive is to strictly prohibit trust in boolean return values over the Capacitor JavaScript-to-Native bridge. Mandate that all sensitive RPC payloads require short-lived, enclave-signed cryptographic assertions bound to hardware key pairs requiring biometric authentication per invocation. ## Strict Guidelines - Engineers MUST ALWAYS require an ephemeral server-originated cryptographic challenge (nonce) before invoking biometric authentication bridge methods. - Engineers MUST NOT permit Capacitor plugins to authorize transactions or privileged state based on simple boolean evaluations (e.g., `if (result.verified) { ... }`). - Native plugins MUST configure hardware-backed keys using `kSecAccessControlBiometryCurrentSet` (iOS Secure Enclave) or `KeyProperties.PURPOSE_SIGN` with `setUserAuthenticationRequired(true)` and `setInvalidatedByBiometricEnrollment(true)` (Android Keystore / TEE). - Bridge responses MUST return the hardware-generated cryptographic signature, the original challenge, and the device key identifier for end-to-end backend validation. - TypeScript bridge consumers MUST enforce a maximum TTL (e.g., 30 to 60 seconds) on client-side attestation assertions before rejecting the session token locally. - Components NEVER store or reconstruct private keys in the JavaScript runtime; private keys MUST be permanently trapped within the hardware enclave. ## Bad vs Good Implementations ### Enclave Signature vs Boolean Biometric Verification in Capacitor Bridge #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The JavaScript runtime relies on a boolean flag (`authResult.isSuccess`). An attacker with device access can trivially bypass this authorization using dynamic instrumentation tools (e.g., Frida, Objection) to rewrite the return value across the Capacitor bridge without touching biometric sensors or hardware. ```typescript // VULNERABLE: Trusting boolean bridge response susceptible to runtime hooking / memory patching import { Plugins } from '@capacitor/core'; const { NativeBiometric } = Plugins; export async function executeTransfer(amount: number, recipientId: string): Promise<void> { // Anti-Pattern: A Frida hook or Xposed script can easily force this to return true const authResult = await NativeBiometric.verifyIdentity({ reason: 'Authenticate to complete fund transfer', }); if (authResult.isSuccess) { await fetch('/api/v1/transfers', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ amount, recipientId }), }); } else { throw new Error('Biometric authentication failed'); } } ``` #### Production Standard (Correct) > **Standard**: Authorization relies on an asymmetric signature computed inside the Secure Enclave or TEE. Even if the WebView environment or native bridge is instrumented, an attacker cannot forge the private key's signature without genuine hardware biometric activation matching the fresh server nonce. ```typescript // SECURE: Hardware-backed attestation requiring Secure Enclave / TEE signature over an ephemeral challenge import { registerPlugin } from '@capacitor/core'; interface EnclaveBiometricPlugin { signChallengeWithBiometric(options: { challenge: string; promptMessage: string; }): Promise<{ signatureBase64: string; keyId: string; timestamp: number }>; } const EnclaveBiometric = registerPlugin<EnclaveBiometricPlugin>('EnclaveBiometric'); export async function executeTransfer(amount: number, recipientId: string): Promise<void> { // 1. Fetch short-lived cryptographic nonce from the authoritative server const challengeResponse = await fetch('/api/v1/attestation/challenge', { method: 'POST' }); const { challenge } = await challengeResponse.json(); // 2. Hardware prompts biometric and signs payload strictly inside Secure Enclave / StrongBox const { signatureBase64, keyId, timestamp } = await EnclaveBiometric.signChallengeWithBiometric({ challenge, promptMessage: 'Authorize transfer via hardware biometric key', }); // 3. Dispatch the payload along with cryptographic hardware assertion to be verified upstream const transferResponse = await fetch('/api/v1/transfers', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Hardware-Signature': signatureBase64, 'X-Key-Identifier': keyId, }, body: JSON.stringify({ amount, recipientId, challenge, signedTimestamp: timestamp, }), }); if (!transferResponse.ok) { throw new Error('Server rejected hardware biometric assertion'); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Hardware-Backed Enclave Biometric Session Attestation for Capacitor 7 Bridge RPCs

Hardware-Backed Enclave Biometric Session Attestation for Capacitor 7 Bridge RPCs defines an industrial-grade behavioral standard for mobile engineering. Capacitor 7 hybrid WebViews must never trust raw boolean biometric flags returned over the bridge. High-privilege native bridge RPC operations require hardware-level cryptographic session attestation where the iOS Secure Enclave or Android StrongBox/TEE signs an ephemeral server-originated challenge upon biometric unlock, guaranteeing proof of physical presence. 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 Bridge Results ({ authenticated: true }) for Sensitive RPC Operations 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 Bridge Results ({ authenticated: true }) for Sensitive RPC Operations	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 require an ephemeral server-originated cryptographic challenge (nonce) before invoking biometric authentication bridge methods.

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.