Capacitor 7 Hardware-Backed WebAuthn Keystore Interceptor Standard

--- description: Capacitor 7 Hardware-Backed WebAuthn Keystore Interceptor Standard - Mandates that hybrid mobile applications built on Capacitor 7 bind all privileged API session operations to hardware-backed Secure Enclave or Android Keystore/StrongBox cryptographic attestations. Prohibits persistent storage of raw bearer tokens in unprivileged WebView storage, enforcing hardware-isolated WebAuthn/Passkey signatures for state-mutating requests. globs: src/**/*.{ts,tsx}, ios/App/App/**/*.{swift,m}, android/app/src/**/*.{kt,java} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-hardware-webauthn-keystore-interceptor" --- # Capacitor 7 Hardware-Backed WebAuthn Keystore Interceptor Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Persisting Long-Lived Session Tokens in WebView Storage and Emitting Plaintext Authorization Headers ## System Constraints You are a Principal Mobile Security Architect enforcing zero-trust hardware attestation standards in Capacitor 7 hybrid applications. You must enforce that no unencrypted bearer tokens, API keys, or long-lived authentication credentials reside in the WebKit/Blink JavaScript runtime environment (LocalStorage, IndexedDB, Cookies, or naively exposed Capacitor Preferences). Every authenticated request must be signed at the hardware layer via Secure Enclave (iOS) or Android Keystore/StrongBox (Android) using WebAuthn/FIDO2 level-3 biometric assertions with server-provided challenges. ## Strict Guidelines - Engineers MUST ALWAYS isolate private signing keys within hardware-backed security modules (Apple Secure Enclave, Android StrongBox/TEE) using native Capacitor 7 bridge plugins. - Engineers MUST NOT persist raw JWTs, refresh tokens, or authorization bearer secrets in Web Storage (`localStorage`, `sessionStorage`), IndexedDB, or standard Document Cookies. - Services MUST route all authenticated outbound transport through an HTTP interceptor that requests cryptographic assertions from the hardware keystore with an ephemeral server-issued nonce. - The interceptor MUST compute and sign a SHA-256 digest over the canonical request tuple `[METHOD, PATH, TIMESTAMP, NONCE, BODY_HASH]` within the isolated native environment. - Components NEVER hold reference to raw cryptographic private key material; all asymmetric operations must happen strictly across the Capacitor native bridge boundary. - Biometric access MUST enforce user presence and biometric authentication flags (`UserPresence`, `UserVerificationRequired`) configured with biometry-invalidation on new biometric enrollment. ## Bad vs Good Implementations ### Hardware-Backed WebAuthn Keystore Interceptor vs. Insecure WebView Token Injection #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Storing static tokens via Preferences or LocalStorage exposes credentials directly to WebView JavaScript execution contexts. If an attacker achieves Cross-Site Scripting (XSS) or inspects unencrypted device backups, the session token is permanently compromised without hardware attribution. ```typescript import { Preferences } from '@capacitor/preferences'; // CRITICAL ANTI-PATTERN: Raw bearer token persisted in WebView-accessible storage // Vulnerable to DOM XSS, prototype pollution, and bridge interception export async function authenticatedFetch(url: string, options: RequestInit = {}): Promise<Response> { const { value: token } = await Preferences.get({ key: 'auth_token' }); if (!token) { throw new Error('Unauthenticated user session'); } const headers = new Headers(options.headers || {}); headers.set('Authorization', `Bearer ${token}`); return fetch(url, { ...options, headers, }); } ``` #### Production Standard (Correct) > **Standard**: Eliminates static bearer credentials. Instead, requests are signed by a private key bound inside the hardware Secure Enclave/StrongBox. The WebView only passes the hash digest across the Capacitor bridge; private keys are non-exportable and physically inaccessible to malicious JavaScript runtimes. ```typescript import { registerPlugin } from '@capacitor/core'; interface HardwareAssertion { credentialId: string; signature: string; clientDataJSON: string; authenticatorData: string; timestamp: number; } interface NativeKeystorePlugin { signPayload(options: { keyAlias: string; challenge: string; payloadDigest: string; requireBiometric: boolean; }): Promise<HardwareAssertion>; } const NativeBiometricKeystore = registerPlugin<NativeKeystorePlugin>('NativeBiometricKeystore'); async function computeSha256(data: string): Promise<string> { const encoder = new TextEncoder(); const buffer = await crypto.subtle.digest('SHA-256', encoder.encode(data)); return Array.from(new Uint8Array(buffer)).map(b => b.toString(16).padStart(2, '0')).join(''); } export async function secureHardwareFetch( url: string, init: RequestInit, challenge: string ): Promise<Response> { const method = init.method?.toUpperCase() ?? 'GET'; const bodyStr = typeof init.body === 'string' ? init.body : ''; const bodyDigest = await computeSha256(bodyStr); const timestamp = Date.now(); // Canonical signature payload binding the request to the hardware enclave const canonicalPayload = `${method}:${new URL(url).pathname}:${timestamp}:${challenge}:${bodyDigest}`; const payloadDigest = await computeSha256(canonicalPayload); // Hardware-level assertion using Secure Enclave / StrongBox Key const assertion = await NativeBiometricKeystore.signPayload({ keyAlias: 'app_session_attestation_key', challenge, payloadDigest, requireBiometric: true }); const headers = new Headers(init.headers); headers.set('X-Hardware-Key-Id', assertion.credentialId); headers.set('X-Hardware-Signature', assertion.signature); headers.set('X-Hardware-AuthData', assertion.authenticatorData); headers.set('X-Hardware-ClientData', assertion.clientDataJSON); headers.set('X-Signature-Timestamp', timestamp.toString()); headers.set('X-Challenge-Nonce', challenge); return fetch(url, { ...init, headers }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Hardware-Backed WebAuthn Keystore Interceptor Standard

Capacitor 7 Hardware-Backed WebAuthn Keystore Interceptor Standard defines an industrial-grade behavioral standard for mobile engineering. Mandates that hybrid mobile applications built on Capacitor 7 bind all privileged API session operations to hardware-backed Secure Enclave or Android Keystore/StrongBox cryptographic attestations. Prohibits persistent storage of raw bearer tokens in unprivileged WebView storage, enforcing hardware-isolated WebAuthn/Passkey signatures for state-mutating requests. 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 Long-Lived Session Tokens in WebView Storage and Emitting Plaintext Authorization Headers 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 Long-Lived Session Tokens in WebView Storage and Emitting Plaintext Authorization Headers	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 isolate private signing keys within hardware-backed security modules (Apple Secure Enclave, Android StrongBox/TEE) using native Capacitor 7 bridge plugins.

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.