Hardware Enclave Keystore Bridging for Cryptographic Operations

--- description: Hardware Enclave Keystore Bridging for Cryptographic Operations - Enforces strict delegation of authentication tokens and cryptographic operations to native platform hardware (iOS Secure Enclave and Android Hardware-backed Keystore / StrongBox) via Capacitor 7 bridges. Prevents persistent plaintext token storage or in-memory token reconstruction in the JavaScript runtime context where it remains vulnerable to heap inspection and XSS. globs: src/services/auth/**/*.{ts,tsx}, src/plugins/**/*.{ts,tsx}, android/app/src/main/java/**/*.java, ios/App/App/**/*.swift alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-secure-enclave-keystore-bridging" --- # Hardware Enclave Keystore Bridging for Cryptographic Operations > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Persisting Refresh Tokens in Web Storage or Extracting Raw Secrets into the WebView Runtime Memory ## System Constraints You are a Principal Mobile Security Architect enforcing strict hardware-backed cryptographic signing boundaries in Capacitor 7 applications. You must ensure that high-entropy secrets and long-lived authentication credentials never traverse into the JavaScript heap or unencrypted storage layers. ## Strict Guidelines - Engineers MUST NEVER store refresh tokens, session master keys, or private signing keys in localStorage, sessionStorage, IndexedDB, or standard unencrypted Preferences. - Engineers MUST delegate cryptographic signature generation (such as DPoP or client assertion JWTs) directly across the native bridge into the iOS Secure Enclave (kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly) or Android KeyStore/StrongBox. - Native plugins MUST enforce non-exportable key flags (e.g., KeyProperties.PURPOSE_SIGN for Android KeyStore, kSecAttrIsExtractable: false for iOS Keychain/Secure Enclave) during asymmetric key generation. - Bridge methods MUST only return proof signatures, cryptographic assertions, or ephemeral access tokens; raw private keys and encrypted token buffers MUST NOT be exposed across the bridge into the web context. - Services MUST implement challenge-response assertions where the server issues an ephemeral nonce and the native bridge signs it within the secure hardware boundary, eliminating persistent refresh tokens from client memory. ## Bad vs Good Implementations ### Anti-Pattern: Storing and Reading Raw Refresh Tokens in JavaScript Memory #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Stores long-lived credentials in Capacitor Preferences (unencrypted SQLite/SharedPreferences). The raw token is exposed in the JavaScript runtime heap, leaving it vulnerable to process memory scraping, WebView inspection, and XSS extraction. ```typescript import { Preferences } from '@capacitor/preferences'; import axios from 'axios'; export class AuthService { // VULNERABLE: Refresh token is exposed to the WebView JS heap and unencrypted preferences async refreshSession(): Promise<string> { const { value: rawRefreshToken } = await Preferences.get({ key: 'auth_refresh_token' }); if (!rawRefreshToken) throw new Error('Unauthenticated'); const response = await axios.post('https://api.domain.com/v1/auth/token', { grant_type: 'refresh_token', refresh_token: rawRefreshToken, }); await Preferences.set({ key: 'auth_refresh_token', value: response.data.refresh_token }); return response.data.access_token; } } ``` #### Production Standard (Correct) > **Standard**: Delegates cryptographic operations to the device hardware enclave. The private key material is physically non-exportable from the Secure Enclave / StrongBox, and only signed ephemeral challenges pass across the Capacitor bridge. ```typescript import { registerPlugin } from '@capacitor/core'; export interface SecureEnclavePlugin { signChallenge(options: { challenge: string; keyAlias: string }): Promise<{ signature: string; keyId: string }>; } const SecureEnclave = registerPlugin<SecureEnclavePlugin>('SecureEnclave'); export class AuthService { // SECURE: Raw keys never enter JavaScript memory; hardware enclave signs proof-of-possession async refreshSession(challenge: string): Promise<string> { const { signature, keyId } = await SecureEnclave.signChallenge({ challenge, keyAlias: 'auth_session_signing_key', }); const response = await fetch('https://api.domain.com/v1/auth/token', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ grant_type: 'hardware_assertion', key_id: keyId, assertion: signature, }), }); if (!response.ok) throw new Error('Hardware verification failed'); const payload = await response.json(); return payload.access_token; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Hardware Enclave Keystore Bridging for Cryptographic Operations

Hardware Enclave Keystore Bridging for Cryptographic Operations defines an industrial-grade behavioral standard for mobile engineering. Enforces strict delegation of authentication tokens and cryptographic operations to native platform hardware (iOS Secure Enclave and Android Hardware-backed Keystore / StrongBox) via Capacitor 7 bridges. Prevents persistent plaintext token storage or in-memory token reconstruction in the JavaScript runtime context where it remains vulnerable to heap inspection and XSS. 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 Refresh Tokens in Web Storage or Extracting Raw Secrets into the WebView Runtime Memory 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 Refresh Tokens in Web Storage or Extracting Raw Secrets into the WebView Runtime Memory	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 store refresh tokens, session master keys, or private signing keys in localStorage, sessionStorage, IndexedDB, or standard unencrypted Preferences.

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.