Chapter 20 — Message Security and Convergence Preconditions

Chapter objective: After this chapter, a developer can separate cluster admission, authenticity, confidentiality, replay prevention, abuse control, and audit, and explain the compatibility window during key rotation.

Learning objectives

1. Define ordered security gates for a remote envelope.
2. Distinguish HMAC authentication, payload encryption, and nonce replay prevention.
3. Explain key version, minimum acceptable version, and rotation window.
4. Map every rejection to a structured error, metric, and audit event.

Prerequisites

• Wire envelopes from Chapter 11 and observation surfaces from Chapter 19 are understood.
• TLS/network isolation does not automatically replace message identity and replay protection.
• Security misconfiguration fails closed.

Case progress

The fulfillment cluster begins receiving cross-node deltas. It needs to reject nodes with a wrong token, detect payload tampering, expire old signing keys, stop replay of a valid message, and limit senders that consume validation resources through repeated failures.

Five gates answer five questions

Encryption does not authenticate a sender, and authentication does not stop replay of a valid packet. One "security enabled" flag hides configuration and diagnosis details.

Key rotation is a window

The security integration test validates rolling migration: old and new signatures coexist temporarily. Receivers choose the verification key by version. After every sender moves, raising min-acceptable-key-version rejects old envelopes.

phase A: active=1, accept >=1
phase B: publish key 2, send active=2, receive accept >=1
phase C: after all nodes switch, accept >=2

Keeping only the new key immediately disconnects nodes not yet rolled. Never raising the minimum leaves exposure from an old key indefinitely.

Nonce window and memory bound

SlidingWindowNonceTracker accepts an increasing nonce or an unseen nonce inside the window, and rejects duplicates, stale values, and zero. maxTrackedSenders plus LRU eviction prevents unknown senders from consuming unbounded memory. Too small a limit repeatedly forgets senders; too large a limit expands memory exposure.

Audit is not a debug log

SecurityAuditLog records token mismatch, signature failure, replay, challenge timeout, sender ban, and fencing rejection. An event contains stable reason, sender, and time without secrets, plaintext keys, or a full sensitive payload.

Counterexample and fault injection

• Tamper with a signed payload and expect authentication failure plus audit.
• Submit one nonce twice and expect replay rejection.
• Require encryption then send plaintext and expect explicit rejection.
• Send enough bad messages to ban a sender and observe recovery after expiry.
• Raise minimum key version to 2 and reject a version 1 envelope.

Experiment

cd submodule/dsm
mvn -q -pl dsm-security,dsm-integration-test -am \
  -Dtest='HmacMessageAuthenticatorTest,SlidingWindowNonceTrackerTest,'\
'SharedKeyClusterTokenValidatorTest,SenderRateLimiterTest,'\
'BuiltInMessageEncryptorTest,SecurityIntegrationTest' \
  -Dsurefire.failIfNoSpecifiedTests=false test

Use security-gates.json to check input, rejection reason, metric, and audit outcome for each gate; secret values are excluded.

Experiment acceptance card

Review

• Admission, authentication, encryption, replay prevention, rate limiting, and audit are separate responsibilities.
• Rotation needs a dual-version compatibility window followed by a higher minimum version.
• A nonce tracker combines replay protection with a sender-capacity bound.
• Security fails closed without putting secrets into observation data.

Next

Chapter 21 defines startup, registry freeze, readiness, and shutdown so deployment automation does not treat STARTING as RUNNING.

Evidence links

• HmacMessageAuthenticator
• SlidingWindowNonceTracker
• SecurityAuditLog
• SecurityIntegrationTest