Capacitor 7 Hardware-Backed WebAuthn PRF Invariant

--- description: Capacitor 7 Hardware-Backed WebAuthn PRF Invariant - Enforces client-side deterministic key derivation via WebAuthn Pseudo-Random Function (PRF) extensions in Capacitor 7 hybrid applications. Mandates that local encryption keys are transiently derived on-demand from secure hardware authenticators without ever persisting raw master secrets or encryption keys in WebView storage, secure storage plugins, or client-side disk caches. globs: src/services/auth/**/*.{ts,tsx}, src/services/crypto/**/*.{ts,tsx}, src/services/storage/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-webauthn-prf-storage-invariants" --- # Capacitor 7 Hardware-Backed WebAuthn PRF Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Persisting Raw Symmetric Encryption Keys in Local Storage or Keystore Plugins ## System Constraints You are a Principal Security Architect enforcing the Capacitor 7 Hardware-Backed WebAuthn PRF Invariant. You must reject any code storing static cryptographic master keys in SQLite, IndexedDB, localStorage, or standard Keychain/Keystore plugins. Ensure all local database and storage encryption keys are derived dynamically using the WebAuthn PRF extension via standard navigator.credentials.get calls backed by native platform authenticators (Passkeys/FIDO2). Verify key isolation, secure zeroization in memory, and transient derivation cycles. ## Strict Guidelines - Engineers MUST ALWAYS invoke `navigator.credentials.get()` with `extensions: { prf: { eval: { first: saltBuffer } } }` to derive storage encryption keys dynamically. - Engineers MUST NOT persist derived WebAuthn PRF symmetric keys (`CryptoKey` or raw buffers) to persistent storage, SQLite, IndexedDB, or Keychain/Keystore plugins. - Code MUST pass the derived PRF output through HKDF-SHA-256 with an app-specific context salt before utilizing it as an AES-GCM-256 key for local database encryption. - Services MUST clear sensitive buffers in memory (`Uint8Array.fill(0)`) immediately after wrapping or unwrap operations complete. - Components NEVER accept raw passwords or static tokens to unlock client databases; credential unlock MUST be gated by hardware biometrics via the platform authenticator. ## Bad vs Good Implementations ### Local Storage Encryption Key Derivation via PRF vs. Stored Static Secret #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Stores the symmetric master encryption key persistently on the device. If the device is compromised or plugin storage is backed up unencrypted, all client data can be decrypted without hardware authorization. ```typescript import { Preferences } from '@capacitor/preferences'; import { SecureStoragePlugin } from 'capacitor-secure-storage-plugin'; // ANTI-PATTERN: Master database key stored permanently in Keychain or insecure Preferences export async function getDatabaseKey(): Promise<CryptoKey> { const existingKey = await SecureStoragePlugin.get({ key: 'db_master_key' }).catch(() => null); if (existingKey && existingKey.value) { const rawKey = Uint8Array.from(atob(existingKey.value), (c) => c.charCodeAt(0)); return crypto.subtle.importKey('raw', rawKey, { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']); } const rawKey = crypto.getRandomValues(new Uint8Array(32)); const base64Key = btoa(String.fromCharCode(...rawKey)); await SecureStoragePlugin.set({ key: 'db_master_key', value: base64Key }); return crypto.subtle.importKey('raw', rawKey, { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']); } ``` #### Production Standard (Correct) > **Standard**: The encryption key is deterministically derived within the secure enclave / hardware authenticator via the WebAuthn PRF extension on demand. The secret material never exists in persistent storage and is wiped from memory after use. ```typescript export interface PrfDerivationOptions { credentialId: Uint8Array; salt: Uint8Array; info: Uint8Array; } // PRODUCTION INVARIANT: Hardware-backed on-demand key derivation via WebAuthn PRF extension export async function deriveKeyViaWebAuthnPrf( options: PrfDerivationOptions ): Promise<CryptoKey> { const assertion = await navigator.credentials.get({ publicKey: { challenge: crypto.getRandomValues(new Uint8Array(32)), allowCredentials: [{ id: options.credentialId, type: 'public-key', transports: ['internal'] }], userVerification: 'required', extensions: { prf: { eval: { first: options.salt } } } as any } }) as PublicKeyCredential; const results = assertion?.getClientExtensionResults() as any; const prfOutput: ArrayBuffer | undefined = results?.prf?.results?.first; if (!prfOutput) { throw new Error('WebAuthn PRF extension unsupported or failed to evaluate on hardware authenticator.'); } try { const ikm = await crypto.subtle.importKey('raw', prfOutput, 'HKDF', false, ['deriveKey']); return await crypto.subtle.deriveKey( { name: 'HKDF', hash: 'SHA-256', salt: options.salt, info: options.info }, ikm, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt'] ); } finally { new Uint8Array(prfOutput).fill(0); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Hardware-Backed WebAuthn PRF Invariant

Capacitor 7 Hardware-Backed WebAuthn PRF Invariant defines an industrial-grade behavioral standard for mobile engineering. Enforces client-side deterministic key derivation via WebAuthn Pseudo-Random Function (PRF) extensions in Capacitor 7 hybrid applications. Mandates that local encryption keys are transiently derived on-demand from secure hardware authenticators without ever persisting raw master secrets or encryption keys in WebView storage, secure storage plugins, or client-side disk caches. 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 Raw Symmetric Encryption Keys in Local Storage or Keystore Plugins 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 Raw Symmetric Encryption Keys in Local Storage or Keystore Plugins	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 invoke `navigator.credentials.get()` with `extensions

Engineers MUST ALWAYS invoke `navigator.credentials.get()` with `extensions: { prf: { eval: { first: saltBuffer } } }` to derive storage encryption keys dynamically.

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.