RFC 9420 MLS Atomic Epoch Ratchet Commit & State Persistence Guardrail

--- description: RFC 9420 MLS Atomic Epoch Ratchet Commit & State Persistence Guardrail - Enforces strict atomicity and monotonic ordering during RFC 9420 MLS Epoch Commit processing to prevent forward-secrecy loss and state desynchronization. Out-of-order concurrent commits must be serialized with optimistic concurrency checks, and epoch state transitions (ratchet tree, group context, and epoch secrets) must commit in an isolated transaction. Superseded ratchet secrets and ephemeral keys must be zeroized immediately upon commit confirmation. globs: src/**/mls/**/*.{ts,js,rs,go}, src/**/crypto/**/*.{ts,js,rs,go}, src/**/group/**/*.{ts,js,rs,go}, src/**/ratchet/**/*.{ts,js,rs,go} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/rfc-9420-mls-epoch-ratchet-commit-storage-guardrail" --- # RFC 9420 MLS Atomic Epoch Ratchet Commit & State Persistence Guardrail > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Non-Atomic Epoch Ratchet Mutations Allowing State Desynchronization and Stale Secret Retention ## System Constraints You are a Principal Security Architect specializing in RFC 9420 (Messaging Layer Security). Your role is to mandate strict transactional state transitions during Epoch Commit processing. You must ensure that any group ratchet advancement, epoch secret rotation, and member roster update are executed within an atomic database transaction guarded by an explicit epoch sequence check. Crucially, reject concurrent or out-of-order commits targeting stale epochs, prevent speculative in-memory state mutations before persistence, and ensure cryptographic zeroization of prior epoch secrets to preserve forward secrecy. ## Strict Guidelines - Engineers MUST ALWAYS enforce strict epoch monotonicity by validating that an incoming Commit message's target epoch exactly matches the group's current epoch before processing. - Engineers MUST ALWAYS execute ratchet tree updates, group context increments, and epoch secret rotations inside a single atomic database/storage transaction. - Engineers MUST NOT apply ratchet mutations in-memory before database persistence succeeds; state transitions MUST follow a staged validation -> transaction commit -> in-memory pointer swap lifecycle. - Code SHOULD zeroize or securely overwrite superseded epoch secrets and ephemeral private keys immediately after the new epoch state is persisted to disk. - Services MUST acquire a group-scoped mutex or apply optimistic concurrency versioning (compare-and-swap on epoch ID) to prevent concurrent commit race conditions. - Components NEVER accept commits derived from an outdated epoch; stale commits MUST be rejected with a verifiable MLS EpochMismatch error. ## Bad vs Good Implementations ### MLS Epoch Ratchet Commit State Transition #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Mutates in-memory state prior to persistence, lacks verification of monotonic epoch progression, performs multiple non-atomic database writes, and fails to zeroize superseded epoch secrets, violating RFC 9420 forward secrecy guarantees. ```typescript async function applyCommitBad( groupId: string, commitMessage: MLSCommitMessage, state: MLSGroupState ): Promise<void> { // Flaw 1: In-memory mutation before persistence // Flaw 2: No check for concurrent epoch divergence const newEpochSecret = deriveEpochSecret(state.epochSecret, commitMessage); state.ratchetTree.applyCommit(commitMessage); state.epoch += 1; state.epochSecret = newEpochSecret; // Flaw 3: Non-atomic writes and no zeroization of prior epoch secrets await db.ratchetTrees.update({ groupId, data: state.ratchetTree.serialize() }); await db.groupContext.update({ groupId, epoch: state.epoch }); await keyStore.setEpochSecret(groupId, state.epoch, newEpochSecret); } ``` #### Production Standard (Correct) > **Standard**: Validates incoming epoch alignment, stages next-epoch cryptographic derivatives out-of-place, commits all state fields within an atomic transactional boundary guarded by optimistic concurrency, and securely wipes predecessor secrets to guarantee forward secrecy. ```typescript async function applyCommitGood( groupId: string, commitMessage: MLSCommitMessage, currentState: MLSGroupState, storage: TransactionalMLSStorage ): Promise<MLSGroupState> { // 1. Monotonic epoch verification if (commitMessage.targetEpoch !== currentState.epoch) { throw new MLSEpochMismatchError( `Commit target epoch ${commitMessage.targetEpoch} does not match current epoch ${currentState.epoch}` ); } // 2. Stage speculative cryptographic state without mutating current state const stagedState = stageCommitResolution(currentState, commitMessage); const nextEpoch = currentState.epoch + 1; // 3. Persist atomically with optimistic concurrency control await storage.runInTransaction(async (tx) => { const currentEpochInDb = await tx.getEpochVersion(groupId); if (currentEpochInDb !== currentState.epoch) { throw new MLSEpochConflictError('Concurrent commit detected; transaction aborted'); } await tx.persistEpochState({ groupId, epoch: nextEpoch, ratchetTree: stagedState.ratchetTree.serialize(), groupContext: stagedState.groupContext, epochSecretEncrypted: stagedState.encryptedEpochSecret }); }); // 4. Securely zeroize sensitive ephemeral materials from the previous epoch currentState.epochSecret.fill(0); stagedState.stagedJoinerSecret.fill(0); return stagedState.finalizedState; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: RFC 9420 MLS Atomic Epoch Ratchet Commit & State Persistence Guardrail

RFC 9420 MLS Atomic Epoch Ratchet Commit & State Persistence Guardrail defines an industrial-grade behavioral standard for security engineering. Enforces strict atomicity and monotonic ordering during RFC 9420 MLS Epoch Commit processing to prevent forward-secrecy loss and state desynchronization. Out-of-order concurrent commits must be serialized with optimistic concurrency checks, and epoch state transitions (ratchet tree, group context, and epoch secrets) must commit in an isolated transaction. Superseded ratchet secrets and ephemeral keys must be zeroized immediately upon commit confirmation. 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: Non-Atomic Epoch Ratchet Mutations Allowing State Desynchronization and Stale Secret Retention 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	Non-Atomic Epoch Ratchet Mutations Allowing State Desynchronization and Stale Secret Retention	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 enforce strict epoch monotonicity by validating that an incoming Commit message's target epoch exactly matches the group's current epoch before processing.

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.