Kotlin Multiplatform Deterministic Cryptographic Memory Zeroization Guardrail

--- description: Kotlin Multiplatform Deterministic Cryptographic Memory Zeroization Guardrail - Enforces deterministic cryptographic key and biometric token zeroization across Android ART and iOS native runtimes. Mandates pinned, off-heap, or mutable byte buffer allocations purged via volatile compiler-barrier memory wiping immediately after use to eliminate retention in swap space, core dumps, or compacting garbage collection passes. globs: **/crypto/**/*.kt, **/security/**/*.kt, **/auth/**/*.kt, **/commonMain/**/*.kt, **/androidMain/**/*.kt, **/iosMain/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-secure-native-memory-zeroization-standard" --- # Kotlin Multiplatform Deterministic Cryptographic Memory Zeroization Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Leaking Ephemeral Cryptographic Secrets to Unmanaged GC Heaps via Immutable Strings or Unscrubbed ByteArrays ## System Constraints You are a Principal Security and Systems Architect enforcing the Kotlin Multiplatform (KMP) Secure Native Memory Zeroization Standard. Cryptographic keys, biometric session tokens, and raw private credentials must never enter garbage-collected generational heaps via immutable structures like java.lang.String or unpinned Kotlin ByteArrays. You must mandate strict deterministic memory lifecycle management using scoped closures, platform-specific secure wipe primitives (memset_s on Darwin/iOS and JNI direct buffer volatile-wiping on Android), and compiler dead-store elimination defenses. ## Strict Guidelines - Engineers MUST ALWAYS encapsulate raw cryptographic keys, biometric payloads, and plaintexts in a scoped AutoCloseable/Closeable resource (e.g., SecureBytes) and consume them strictly through scoped blocks (`use { ... }`). - Engineers MUST NOT represent cryptographic secrets as `String`, `CharSequence`, or immutable boxed collections, as JVM String interning and Kotlin/Native immutability prevent memory overwriting. - Code SHOULD allocate memory for secret materials using pinned native memory (iOS Kotlin Native `Arena` / `posix.memset_s`) or off-heap DirectByteBuffers on Android to evade GC compaction copies. - Services MUST execute dead-store resistant zeroization (such as `memset_s`, `SecureZeroMemory`, or explicit volatile iteration) before releasing memory buffers back to the OS or allocator. - Components NEVER expose unzeroed ByteArrays across module or FFI boundaries without explicit ownership transfer and caller-cleanup contracts. ## Bad vs Good Implementations ### KMP Secure Cryptographic Secret Lifecycle with Deterministic Zeroization #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Strings are immutable across both JVM and Apple targets, remaining readable in memory dumps indefinitely. Standard ByteArrays allocated on the managed heap cannot guarantee immediate zeroing, are subject to GC compaction duplicating sensitive bytes in memory, and the compiler may optimize away post-use zero-loops as dead-store elimination. ```kotlin // Anti-Pattern: Secret kept in immutable String and unmanaged ByteArray // String cannot be mutated or zeroed; ByteArray survives in GC heap until collection/compaction class KeyManager { fun decryptToken(rawSecretString: String, encryptedPayload: ByteArray): ByteArray { val keyBytes = rawSecretString.encodeToByteArray() // Heap leak 1: String is immutable val cipher = initializePlatformCipher(keyBytes) // Heap leak 2: ByteArray left unscrubbed return cipher.doFinal(encryptedPayload) } } ``` #### Production Standard (Correct) > **Standard**: The secret is encapsulated in a native memory container pinned outside standard generational GC compaction passes. The `useSecret` scope guarantees deterministic purging via `close()`, which delegates to native platform zeroization functions (`memset_s` on iOS and direct JNI volatile-fills on Android), neutralizing compiler dead-store elimination. ```kotlin // Production Guardrail: Expect/Actual scoped zeroization with dead-store prevention expect class NativeSecretBuffer(capacity: Int) : AutoCloseable { val size: Int fun write(source: ByteArray) fun read(destination: ByteArray) override fun close() // Enforces platform memset_s / volatile overwrite } inline fun <R> NativeSecretBuffer.useSecret(block: (NativeSecretBuffer) -> R): R { return try { block(this) } finally { this.close() } } // Usage within business logic class KeyManager { fun decryptToken(secretInput: ByteArray, encryptedPayload: ByteArray): ByteArray { val buffer = NativeSecretBuffer(secretInput.size) return buffer.useSecret { secureKey -> secureKey.write(secretInput) // Execute platform cipher using memory pointer / direct reference executeCryptoOperation(secureKey, encryptedPayload) } // NativeSecretBuffer.close() invokes volatile wipe / memset_s immediately } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kotlin Multiplatform Deterministic Cryptographic Memory Zeroization Guardrail

Kotlin Multiplatform Deterministic Cryptographic Memory Zeroization Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces deterministic cryptographic key and biometric token zeroization across Android ART and iOS native runtimes. Mandates pinned, off-heap, or mutable byte buffer allocations purged via volatile compiler-barrier memory wiping immediately after use to eliminate retention in swap space, core dumps, or compacting garbage collection passes. 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: Leaking Ephemeral Cryptographic Secrets to Unmanaged GC Heaps via Immutable Strings or Unscrubbed ByteArrays 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	Leaking Ephemeral Cryptographic Secrets to Unmanaged GC Heaps via Immutable Strings or Unscrubbed ByteArrays	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 encapsulate raw cryptographic keys, biometric payloads, and plaintexts in a scoped AutoCloseable/Closeable resource (e.g., SecureBytes) and consume them strictly through scoped blocks (`use { ... }`).

Engineers MUST ALWAYS encapsulate raw cryptographic keys, biometric payloads, and plaintexts in a scoped AutoCloseable/Closeable resource (e.g., SecureBytes) and consume them strictly through scoped blocks (`use { ... }`).

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.