Capacitor 7 Custom Scheme Hardware-Backed Asset Decryption Interceptor Standard

--- description: Capacitor 7 Custom Scheme Hardware-Backed Asset Decryption Interceptor Standard - Enforces that all proprietary hybrid assets served inside Capacitor 7 native webviews are encrypted at rest using AES-GCM-256 and decrypted strictly in memory on-the-fly via custom scheme URL interceptors. Mandates that cryptographic keys reside inside hardware-backed storage (Android KeyStore StrongBox or iOS Secure Enclave / Keychain) and forbids writing decrypted payloads back to persistent disk or web storage caches. globs: capacitor.config.ts, android/app/src/main/java/**/*.java, android/app/src/main/java/**/*.kt, ios/App/App/**/*.swift, src/security/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-custom-scheme-asset-encryption-standard" --- # Capacitor 7 Custom Scheme Hardware-Backed Asset Decryption Interceptor Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Plaintext Asset Distribution and Local Storage Decryption Caching in Capacitor WebViews ## System Constraints You are a Principal Mobile Security Engineer enforcing the Capacitor 7 Custom Scheme Asset Encryption Interceptor Standard. Mandate that all production assets served to the WebView use custom schemes intercepted by native handlers (WKURLSchemeHandler on iOS and WebViewAssetLoader on Android) with hardware-backed key derivation. Prevent plaintext bundling of proprietary JavaScript bundles, prevent disk-based decryption artifacts, and enforce streaming or zero-persistence memory decryption with strict Content-Security-Policy headers. ## Strict Guidelines - Engineers MUST ALWAYS register custom scheme interceptors ('app://' or 'ionic://') via WKURLSchemeHandler on iOS and WebViewAssetLoader.PathHandler on Android to stream decrypted assets dynamically. - Engineers MUST derive and retrieve AES-GCM-256 asset keys exclusively from hardware-backed keystores (Android StrongBox KeyStore and iOS Keychain backed by Secure Enclave). - Engineers MUST NOT write decrypted intermediate buffers, scripts, or markup to the application sandbox cache directory, localStorage, IndexedDB, or temporary file system paths. - Engineers MUST configure capacitor.config.ts with a custom scheme and disable arbitrary file scheme access (allowFileAccess: false, allowContentAccess: false). - Code MUST verify cryptographic authentication tags (GCM tag validation) before streaming bytes to the WebView and terminate the session if integrity checks fail. - Services MUST inject restrictive Content-Security-Policy (CSP) headers directly from the native interceptor response to prevent unauthorized inline script evaluation. ## Bad vs Good Implementations ### Configuring Capacitor Custom Scheme and Preventing File Scheme Leaks #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Default HTTP or file schemes expose bundled hybrid code directly on the file system, leaving proprietary logic unencrypted in the APK/IPA and vulnerable to extraction on rooted or jailbroken devices. ```typescript import { CapacitorConfig } from '@capacitor/cli'; const config: CapacitorConfig = { appId: 'com.enterprise.app', appName: 'SecureClient', webDir: 'dist', server: { // INSECURE: Default standard schemes allow plaintext inspection // and allowFileAccess exposes raw bundle paths on Android androidScheme: 'http', allowNavigation: ['*'] } }; export default config; ``` #### Production Standard (Correct) > **Standard**: Configuring explicit schemes and strict hostnames enables native interceptors (WKURLSchemeHandler / WebViewAssetLoader) to capture asset requests and stream hardware-decrypted bytes directly without touching persistent local disks. ```typescript import { CapacitorConfig } from '@capacitor/cli'; const config: CapacitorConfig = { appId: 'com.enterprise.app', appName: 'SecureClient', webDir: 'dist', server: { // SECURE: Enforces custom secure scheme intercepted by native security layer scheme: 'secureapp', androidScheme: 'https', hostname: 'secureapp.local', cleartext: false }, android: { allowMixedContent: false, captureInput: true } }; export default config; ``` ### Native iOS WKURLSchemeHandler On-The-Fly AES-GCM Decryption #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Decrypting assets to disk exposes plaintext source code to disk scraping and uses hardcoded cryptographic keys instead of hardware-backed storage. ```swift // INSECURE: Decrypting entire asset bundle to disk before loading into WKWebView func decryptAndLoad(url: URL) -> URL { let encryptedData = try! Data(contentsOf: url) let decryptedData = SimpleCrypto.decrypt(data: encryptedData, hardcodedKey: "1234567890123456") let tempPath = FileManager.default.temporaryDirectory.appendingPathComponent(url.lastPathComponent) try! decryptedData.write(to: tempPath) // Disclosed on physical extraction return tempPath } ``` #### Production Standard (Correct) > **Standard**: Implements WKURLSchemeHandler with on-the-fly AES-GCM decryption using Secure Enclave hardware keys. Cleartext bytes are streamed directly into memory without any temporary disk writes. ```swift import Foundation import WebKit import CryptoKit final class EncryptedAssetSchemeHandler: NSObject, WKURLSchemeHandler { private let keyTag = "com.enterprise.app.assetkey" func webView(_ webView: WKWebView, start urlSchemeTask: WKURLSchemeTask) { guard let url = urlSchemeTask.request.url else { return } DispatchQueue.global(qos: .userInitiated).async { do { let rawAssetPath = Bundle.main.path(forResource: url.path, ofType: nil, inDirectory: "public_encrypted")! let cipherBytes = try Data(contentsOf: URL(fileURLWithPath: rawAssetPath)) // Retrieve symmetric key derived from Secure Enclave seed let key = try SecureEnclaveKeyManager.retrieveHardwareAssetKey(tag: self.keyTag) let sealedBox = try AES.GCM.SealedBox(combined: cipherBytes) let clearData = try AES.GCM.open(sealedBox, using: key) let mimeType = MimeTypeResolver.resolve(for: url.pathExtension) let response = HTTPURLResponse( url: url, statusCode: 200, httpVersion: "HTTP/1.1", headerFields: [ "Content-Type": mimeType, "Content-Security-Policy": "default-src 'self' secureapp:; script-src 'self' secureapp:;", "Cache-Control": "no-store, no-cache, must-revalidate" ] )! urlSchemeTask.didReceive(response) urlSchemeTask.didReceive(clearData) urlSchemeTask.didFinish() } catch { urlSchemeTask.didFailWithError(error) } } } func webView(_ webView: WKWebView, stop urlSchemeTask: WKURLSchemeTask) {} } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Custom Scheme Hardware-Backed Asset Decryption Interceptor Standard

Capacitor 7 Custom Scheme Hardware-Backed Asset Decryption Interceptor Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces that all proprietary hybrid assets served inside Capacitor 7 native webviews are encrypted at rest using AES-GCM-256 and decrypted strictly in memory on-the-fly via custom scheme URL interceptors. Mandates that cryptographic keys reside inside hardware-backed storage (Android KeyStore StrongBox or iOS Secure Enclave / Keychain) and forbids writing decrypted payloads back to persistent disk or web storage 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: Plaintext Asset Distribution and Local Storage Decryption Caching in Capacitor WebViews 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	Plaintext Asset Distribution and Local Storage Decryption Caching in Capacitor WebViews	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 register custom scheme interceptors ('app

Engineers MUST ALWAYS register custom scheme interceptors ('app://' or 'ionic://') via WKURLSchemeHandler on iOS and WebViewAssetLoader.PathHandler on Android to stream decrypted assets 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.