Capacitor 7 Hardware-Attested Keystore Cryptographic RPC Handshake

--- description: Capacitor 7 Hardware-Attested Keystore Cryptographic RPC Handshake - Mandates that all privileged bridge executions in Capacitor 7 undergo a two-phase challenge-response handshake backed by hardware keystores (Android StrongBox Keymaster and iOS Secure Enclave). Prevents arbitrary bridge dispatch from compromised WebView contexts by requiring single-use hardware-signed nonces and cryptographic payload envelopes before executing sensitive native operations. globs: src/**/*.{ts,tsx}, ios/App/App/**/*.swift, android/app/src/main/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-secure-keystore-crypto-rpc-handshake" --- # Capacitor 7 Hardware-Attested Keystore Cryptographic RPC Handshake > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Direct WebView Bridge Invocation Without Hardware-Attested Cryptographic Nonce Envelopes ## System Constraints You are a Principal Mobile Security Architect enforcing zero-trust hardware attestation in Capacitor 7 hybrid applications. You strictly prohibit unprotected, direct JavaScript-to-Native bridge invocations for privileged operations (e.g., identity verification, cryptographic operations, secure storage mutation, biometric verification, or financial transactions). You mandate a strict two-phase cryptographic RPC protocol: first, obtaining an ephemeral, hardware-attested cryptographic nonce generated within Android StrongBox or iOS Secure Enclave; second, dispatching a canonical, cryptographically sealed envelope verifying WebView origin, payload integrity, and single-use nonce consumption within a bounded time window. ## Strict Guidelines - Engineers MUST ALWAYS implement a two-step cryptographic handshake (Acquire Nonce -> Transmit Sealed Payload) for any privileged Capacitor plugin call. - Engineers MUST NOT expose native methods that perform state-mutating or privileged operations without validating a hardware-signed, single-use attestation nonce. - Native plugins MUST bind key generation to hardware isolation (iOS: 'kSecAttrTokenIDSecureEnclave'; Android: 'setIsStrongBoxBacked(true)' with KeyProperties.PURPOSE_SIGN). - Services MUST enforce strict time-to-live (TTL) on native nonces (maximum 30 seconds) and immediately invalidate nonces upon first evaluation to prevent replay attacks. - Components NEVER execute raw plugin methods directly from UI components; all calls must route through an authenticated RPC gateway enforcing envelope generation. ## Bad vs Good Implementations ### Privileged Bridge Dispatch Without Hardware Attestation (Vulnerable) #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly invokes the native bridge with cleartext parameters and no attestation. Any arbitrary script injection inside the WebView context (DOM-based XSS, compromised CDN script) can exfiltrate sensitive keys directly. ```typescript import { registerPlugin } from '@capacitor/core'; interface SecureVaultPlugin { exportSigningKey(options: { alias: string }): Promise<{ privateKeyArmored: string }>; } const SecureVault = registerPlugin<SecureVaultPlugin>('SecureVault'); // CRITICAL VULNERABILITY: XSS or injected script inside the WebView can invoke // privileged bridge endpoints without cryptographic proof of origin or hardware attestation. export async function extractKey(alias: string): Promise<string> { const response = await SecureVault.exportSigningKey({ alias }); return response.privateKeyArmored; } ``` #### Production Standard (Correct) > **Standard**: Implements an attested zero-trust RPC handshake. The native layer issues a cryptographic challenge generated via StrongBox/Secure Enclave. The WebView seals the payload with the challenge nonce, preventing unauthorized script execution, parameter tampering, and replay attacks. ```typescript import { registerPlugin } from '@capacitor/core'; interface AttestationChallenge { nonceId: string; nonceValue: string; hardwareAttestationJwt: string; issuedAt: number; } interface EnclavePayloadEnvelope<T> { nonceId: string; canonicalPayloadSha256: string; clientTimestamp: number; payload: T; } interface HardwareVaultPlugin { requestHardwareChallenge(): Promise<AttestationChallenge>; executePrivilegedDispatch<T, R>(options: EnclavePayloadEnvelope<T>): Promise<R>; } const HardwareVault = registerPlugin<HardwareVaultPlugin>('HardwareVault'); export async function executeHardwareGatedOperation<T, R>(payload: T): Promise<R> { // Phase 1: Request hardware-backed nonce generated within StrongBox / Secure Enclave const challenge = await HardwareVault.requestHardwareChallenge(); // Phase 2: Compute deterministic payload digest bound to the ephemeral nonce const serializedPayload = JSON.stringify(payload); const encoder = new TextEncoder(); const payloadBuffer = encoder.encode(`${challenge.nonceValue}:${serializedPayload}`); const digestBuffer = await crypto.subtle.digest('SHA-256', payloadBuffer); const canonicalPayloadSha256 = Array.from(new Uint8Array(digestBuffer)) .map((b) => b.toString(16).padStart(2, '0')) .join(''); // Phase 3: Execute sealed privileged RPC with hardware nonce verification return await HardwareVault.executePrivilegedDispatch<T, R>({ nonceId: challenge.nonceId, canonicalPayloadSha256, clientTimestamp: Date.now(), payload, }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Hardware-Attested Keystore Cryptographic RPC Handshake

Capacitor 7 Hardware-Attested Keystore Cryptographic RPC Handshake defines an industrial-grade behavioral standard for mobile engineering. Mandates that all privileged bridge executions in Capacitor 7 undergo a two-phase challenge-response handshake backed by hardware keystores (Android StrongBox Keymaster and iOS Secure Enclave). Prevents arbitrary bridge dispatch from compromised WebView contexts by requiring single-use hardware-signed nonces and cryptographic payload envelopes before executing sensitive native operations. 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: Direct WebView Bridge Invocation Without Hardware-Attested Cryptographic Nonce Envelopes 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	Direct WebView Bridge Invocation Without Hardware-Attested Cryptographic Nonce Envelopes	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 implement a two-step cryptographic handshake (Acquire Nonce -> Transmit Sealed Payload) for any privileged Capacitor plugin call.

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.