Hardware-Attested Biometric Bridge Gate for Capacitor 7 Native-Web IPC

--- description: Hardware-Attested Biometric Bridge Gate for Capacitor 7 Native-Web IPC - Mandates per-call cryptographic hardware attestation tokens across Capacitor 7 native-to-web bridge invocations. Replaces vulnerable boolean bridge payloads with hardware-signed nonces generated inside Apple Secure Enclave or Android StrongBox KeyStore to completely neutralize runtime memory injection and Frida bridge hooking. 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-biometric-hardware-attestation-gate" --- # Hardware-Attested Biometric Bridge Gate for Capacitor 7 Native-Web IPC > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Returning Unsigned Boolean State Across Capacitor Native Bridge Vulnerable to Runtime Hooking and Memory Modification ## System Constraints You are a Principal Mobile Security Architect enforcing zero-trust hardware-attested bridge architectures in Capacitor 7 hybrid applications. You must enforce per-call cryptographic attestation on all sensitive bridge calls, prohibiting naked boolean results and unauthenticated web-to-native message passing. ## Strict Guidelines - Engineers MUST NEVER rely on bare boolean flags (e.g., `{ success: true }`) returned across the Capacitor bridge for security-critical actions. - Native bridge plugins MUST require an ephemeral, server-issued cryptographic challenge (nonce minimum 256 bits) for every protected bridge invocation. - All biometric authorizations MUST trigger cryptographic signing operations directly within hardware-backed security modules (Apple Secure Enclave or Android StrongBox/TEE). - Native bridge implementations MUST bind the biometric prompt directly to private key release using `UserAuthenticationRequired` (Android) or `kSecAccessControlBiometryCurrentSet` (iOS). - Bridge responses for authenticated operations MUST return a structured hardware attestation payload containing `signature`, `nonce`, `keyId`, `clientDataHash`, and `timestamp`. - Engineers MUST NOT cache hardware-attested biometric tokens in JavaScript runtime memory or LocalStorage/IndexedDB across distinct session contexts. - Web clients MUST forward the hardware-signed attestation payload directly to the backend authorization service for cryptographic verification before granting state changes. ## Bad vs Good Implementations ### Insecure Bridge Invocation vs Hardware-Attested Nonce Gate #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The native bridge returns a primitive boolean. Any runtime instrumentation tool (Frida, Objection) or compromised web view JavaScript context can mutate `result.verified` to `true`, completely bypassing physical biometric verification. ```typescript import { registerPlugin } from '@capacitor/core'; interface LegacyBiometricPlugin { authenticateUser(options: { reason: string }): Promise<{ verified: boolean }>; } const BiometricAuth = registerPlugin<LegacyBiometricPlugin>('BiometricAuth'); export async function executeHighValueTransfer(recipientId: string, amount: number): Promise<void> { // CRITICAL VULNERABILITY: Bridge result can be intercepted and forced via Frida: // Interceptor.replace(BiometricAuth.authenticateUser, new NativeCallback(() => ({ verified: true }))); const result = await BiometricAuth.authenticateUser({ reason: 'Confirm high-value transaction' }); if (result.verified) { await fetch('/api/transfer', { method: 'POST', body: JSON.stringify({ recipientId, amount }) }); } } ``` #### Production Standard (Correct) > **Standard**: Physical biometric authorization is tied directly to an asymmetric key stored in the hardware enclave. A tampering attacker can modify the JS context or hook bridge calls, but cannot forge the hardware-signed cryptographic payload without the enclave's authentic biometric release. ```typescript import { registerPlugin } from '@capacitor/core'; export interface AttestationPayload { signature: string; nonce: string; keyId: string; clientDataJSON: string; timestamp: number; } interface HardwareAttestedBridgePlugin { signChallengeWithHardwareBiometrics(options: { challenge: string; payloadDigest: string; promptMessage: string; }): Promise<AttestationPayload>; } const BiometricGate = registerPlugin<HardwareAttestedBridgePlugin>('BiometricHardwareGate'); export async function executeHighValueTransfer( recipientId: string, amount: number ): Promise<void> { // 1. Fetch ephemeral cryptographically secure server nonce const challengeResponse = await fetch('/api/auth/challenge', { method: 'POST' }); const { challenge } = (await challengeResponse.json()) as { challenge: string }; // 2. Compute canonical digest of transaction intent const canonicalPayload = JSON.stringify({ recipientId, amount, challenge }); const encoder = new TextEncoder(); const digestBuffer = await crypto.subtle.digest('SHA-256', encoder.encode(canonicalPayload)); const payloadDigest = Array.from(new Uint8Array(digestBuffer)) .map((b) => b.toString(16).padStart(2, '0')) .join(''); // 3. Hardware-backed signature generated exclusively inside Secure Enclave / StrongBox KeyStore const attestation = await BiometricGate.signChallengeWithHardwareBiometrics({ challenge, payloadDigest, promptMessage: `Authorize transfer of $${amount.toFixed(2)}` }); // 4. Submit cryptographically sealed assertion to backend; backend verifies key signature const verifyResponse = await fetch('/api/transfer/execute', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ recipientId, amount, attestation }) }); if (!verifyResponse.ok) { throw new Error('Cryptographic attestation validation failed on remote gateway'); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Hardware-Attested Biometric Bridge Gate for Capacitor 7 Native-Web IPC

Hardware-Attested Biometric Bridge Gate for Capacitor 7 Native-Web IPC defines an industrial-grade behavioral standard for mobile engineering. Mandates per-call cryptographic hardware attestation tokens across Capacitor 7 native-to-web bridge invocations. Replaces vulnerable boolean bridge payloads with hardware-signed nonces generated inside Apple Secure Enclave or Android StrongBox KeyStore to completely neutralize runtime memory injection and Frida bridge hooking. 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: Returning Unsigned Boolean State Across Capacitor Native Bridge Vulnerable to Runtime Hooking and Memory Modification 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	Returning Unsigned Boolean State Across Capacitor Native Bridge Vulnerable to Runtime Hooking and Memory Modification	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 rely on bare boolean flags (e.g., `{ success

Engineers MUST NEVER rely on bare boolean flags (e.g., `{ success: true }`) returned across the Capacitor bridge for security-critical actions.

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.