Capacitor 7 Dual-Ed25519 Native Keystore Delta Verification Invariant

--- description: Capacitor 7 Dual-Ed25519 Native Keystore Delta Verification Invariant - Enforces mandatory native-layer dual asymmetric Ed25519 cryptographic signature verification against immutable hardware-backed trust anchors (iOS Secure Enclave / Keychain and Android KeyStore) prior to uncompressing, applying, or staging dynamic Capacitor 7 web asset delta hot-patches. Prevents Remote Code Execution (RCE) and rogue bundle substitution resulting from compromised CI/CD credentials, malicious CDNs, or runtime JavaScript inspection bypasses. globs: ios/App/App/**/*.swift, android/app/src/main/**/*.kt, src/services/updater/**/*.ts, src/plugins/updater/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor7-delta-update-dual-ed25519-keystore-invariant" --- # Capacitor 7 Dual-Ed25519 Native Keystore Delta Verification Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Applying Dynamic Hot-Patches via Single-Key JavaScript Verification or Unverified File System Extraction ## System Constraints You are a Principal Mobile Security Architect enforcing cryptographic invariants for dynamic bundle hot-patching in Capacitor 7. You MUST prohibit any dynamic runtime asset hydration that does not pass dual Ed25519 cryptographic signature verification inside native execution contexts (Swift/Kotlin) anchored to immutable hardware certificates. Never permit signature verification in the web runtime or reliance on single-key trust models. ## Strict Guidelines - Engineers MUST ALWAYS execute bundle delta extraction and cryptographic verification entirely within native code (Swift/Kotlin) before exposing new asset paths to Capacitor's WebView. - Engineers MUST require dual Ed25519 asymmetric signatures (e.g., an automated CI build key AND an air-gapped security quorum key) embedded in the patch manifest. - Services MUST validate the public keys against hardware-backed keystore certificates provisioned at build time (iOS Secure Enclave/Keychain and Android KeyStore with StrongBox/TEE backing) rather than remotely fetched or mutable keys. - Engineers MUST NOT verify delta update manifests or calculate SHA-256/Ed25519 signatures inside the JavaScript/TypeScript Web runtime, as client-side memory and prototype modification can invalidate assertions. - Code MUST verify the cryptographic integrity of the cumulative patched output digest (SHA-256) matching the signed manifest before toggling the Capacitor local server directory pointer. - Components NEVER stage unverified delta archives directly into the active Capacitor deployment directory; staging must occur in an isolated quarantine filesystem location. ## Bad vs Good Implementations ### Vulnerable Client-Side Single-Signature Update Application #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Verifying signatures in JavaScript using dynamically passed public keys is vulnerable to prototype pollution, script injection, memory tampering, and CDN key-substitution attacks. ```typescript import { Filesystem, Directory } from '@capacitor/filesystem'; import { Http } from '@capacitor-community/http'; import * as nacl from 'tweetnacl'; export async function applyBundleUpdate(manifestUrl: string, patchUrl: string, remotePublicKey: string) { const manifestResp = await Http.get({ url: manifestUrl }); const { patchHash, signature } = manifestResp.data; // CRITICAL FLAW: Trust anchor is passed dynamically and verification is executed in JS runtime. // An attacker can mock nacl.sign.detached.verify via prototype pollution or MITM the remote public key. const isValid = nacl.sign.detached.verify( new TextEncoder().encode(patchHash), Buffer.from(signature, 'hex'), Buffer.from(remotePublicKey, 'hex') ); if (isValid) { const patchData = await Http.downloadFile({ url: patchUrl, filePath: 'patch.delta' }); // Directly applied without hardware-anchored native verification window.location.reload(); } } ``` #### Production Standard (Correct) > **Standard**: Delegates delta patching and dual-signature validation entirely to native code, enforcing hardware-backed keystore certificates for Ed25519 validation in an isolated quarantine sandbox before hot-patch activation. ```typescript import { registerPlugin } from '@capacitor/core'; interface NativeSecureUpdaterPlugin { applyDeltaBundle(options: { deltaUri: string; manifestUri: string; expectedTargetHash: string; }): Promise<{ status: 'SUCCESS' | 'VERIFICATION_FAILED'; appliedVersion: string }>; } const NativeSecureUpdater = registerPlugin<NativeSecureUpdaterPlugin>('NativeSecureUpdater'); export async function applySecureUpdate(deltaUri: string, manifestUri: string, targetDigest: string) { // Invariant: Verification and dual-signature verification against Hardware Keystore (TEE/StrongBox/SE) // occurs strictly in native code (Swift/Kotlin). The TS bridge only instructs native execution. try { const result = await NativeSecureUpdater.applyDeltaBundle({ deltaUri, manifestUri, expectedTargetHash: targetDigest }); if (result.status !== 'SUCCESS') { throw new Error('Native dual-signature cryptographic verification failed. Quarantine maintained.'); } window.location.reload(); } catch (err) { console.error('Cryptographic invariant breach or delta failure:', err); throw err; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Dual-Ed25519 Native Keystore Delta Verification Invariant

Capacitor 7 Dual-Ed25519 Native Keystore Delta Verification Invariant defines an industrial-grade behavioral standard for mobile engineering. Enforces mandatory native-layer dual asymmetric Ed25519 cryptographic signature verification against immutable hardware-backed trust anchors (iOS Secure Enclave / Keychain and Android KeyStore) prior to uncompressing, applying, or staging dynamic Capacitor 7 web asset delta hot-patches. Prevents Remote Code Execution (RCE) and rogue bundle substitution resulting from compromised CI/CD credentials, malicious CDNs, or runtime JavaScript inspection bypasses. 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: Applying Dynamic Hot-Patches via Single-Key JavaScript Verification or Unverified File System Extraction 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	Applying Dynamic Hot-Patches via Single-Key JavaScript Verification or Unverified File System Extraction	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 execute bundle delta extraction and cryptographic verification entirely within native code (Swift/Kotlin) before exposing new asset paths to Capacitor's WebView.

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.