feat: secure transport foundation

.claude/rules/code-convention.md

@@ -6,7 +6,7 @@ Functions taking `&self`, `&mut self`, or a reference to a struct as their first
 
 ## Enum struct pattern
 
-Enum variants that carry data must use the tuple-variant + named-struct pattern. Never use inline fields on enum variants. See `/.claude/skills/enum-struct-pattern/SKILL.md` for the full pattern including `impl_from_variant!` usage.
+Enum variants that carry data must use the tuple-variant + named-struct pattern. Prefer not using inline fields on enum variants. See `/.claude/skills/enum-struct-pattern/SKILL.md` for the full pattern including `impl_from_variant!` usage. 
 
 ## Result over Option for observability
 

.claude/rules/metadata-state-machine.md

@@ -21,7 +21,11 @@ MetadataStateMachine (one per shard group)
 │
 │   SegmentMeta (nested inside RangeMeta)
 │
-└── topic_name_index: HashMap<String, TopicId>
+├── topic_name_index: HashMap<String, TopicId>
+└── security
+    ├── admissions: Node Certificate Principal → Admission Record
+    ├── ACLs: Resource → ACL Record
+    └── revocations: (Issuer, Serial) → Revocation Record
 ```
 
 ## Commands
@@ -80,3 +84,5 @@ MetadataStateMachine (one per shard group)
 21. **`ReassignSegment` only re-points a sealed segment.** `apply_reassign_segment()` accepts only a `Sealed` segment, swaps `replica_set`, and changes nothing else — state stays `Sealed`; data, offsets, lineage, and timestamps stay frozen (invariant 3). An active, deleting, or unknown segment is rejected (`SegmentNotSealed` / `SegmentNotFound`), logged but not fatal (invariant 11). Re-applying with the same `replica_set` succeeds without raising a metadata event, tolerating duplicate death detection and no-leader re-proposals (cf. invariant 19). The swap runs through `apply`, so the umbrella `assert_invariants` re-checks every other invariant afterward — a reassignment cannot leave the machine inconsistent.
 
 22. **A committed consumer-group generation assigns each active range exactly once.** When a group has members, its assignment keys exactly equal the topic's active ranges and every assignment names a current member. When it has no members, it has no assignments. Membership or range-topology changes advance the generation and recompute the full desired assignment through the Raft log; heartbeat refreshes that do not change membership leave the generation unchanged.
+
+23. **Security map keys match their records.** Admission keys equal the record's Node Certificate Principal, ACL keys equal the record's resource, and revocation keys equal the record's issuer and serial. A map therefore contains at most one current admission per Node Certificate Principal and snapshot restore cannot silently associate a security record with a different lookup key.

.claude/rules/raft-transport.md

@@ -1,38 +1,92 @@
 # Raft Transport (Invariants)
 
-`RaftTransportActor` — async TCP transport for Raft RPCs. Manages persistent bidirectional connections between nodes. Each connection split into a reader task and a writer half held in the per-node `writers` map.
+`RaftTransportActor` — async TCP transport for Raft RPCs. It manages persistent
+bidirectional Raft connections between nodes. Each connection splits into a
+reader task and a writer half held in the per-node `writers` map. 
+The same authenticated cluster listener also serves a one-shot ACL snapshot read used to
+refresh a broker's local authorization cache and a limited admission-record read used to authenticate a connecting process.
 
 Separate from SWIM's UDP transport. Raft uses TCP for reliable, ordered delivery.
 
 ## Architecture (brief)
 
 ```
-RaftTransportActor
-├── listener (raft_port, TCP)
-├── writers: HashMap<NodeId, OwnedWriteHalf>   (one write half per peer)
-└── reader tasks (one per accepted/established connection)
+cluster listener (TCP)
+        │
+        ├── limited admission read ──► security actor → Raft → reply → close
+        │
+        └── request with process proof
+              │
+              ├── both sides verify a TLS-session-bound process proof
+              ├── Raft ──► persistent reader + one writer per peer
+              └── ACL ───► security actor → Raft → reply → close
 ```
 
 ## Wire Protocol
 
-Length-prefixed bincode frames:
-1. **Handshake** (first frame on every connection): `[len: u32][NodeId: bincode]`
-2. **Messages**: `[len: u32][WireRaftMessage: bincode]`, where `WireRaftMessage` carries `shard_group_id` so transport can dispatch to the correct Raft group.
+Length-prefixed Borsh frames:
+
+1. **Initial message:** `InitialClusterMessage` carries one `ClusterRequest` and
+   an optional process-admission proof. Secure Raft and ACL requests include the
+   proof; the limited admission lookup omits it.
+2. **Mutual admission:** the acceptor verifies the connecting node, then replies
+   with its own `AdmissionProof`. Both proofs sign the same TLS exporter value and are
+   checked against the peer's current admission record. The exporter lets both
+   ends derive identical connection-specific bytes without sending those bytes;
+   another TLS connection derives a different value.
+3. **After mutual admission:**
+   - The first Raft message carries its sender. Later frames are raw
+     `WireRaftMessage` values until close. Each carries `shard_group_id`.
+   - An ACL snapshot request carries its requesting node, shard, and resource.
+     Its response is one `AclSnapshotResponse`, then the connection closes.
+4. **Trusted-development initial message:** no cryptographic admission exchange;
+   the Raft or ACL request carries no admission proof.
 
 ## Invariants
 
-1. **Connection identity is established by handshake before any RPCs.** First frame on every connection is the initiator's `NodeId`. The acceptor uses this to key the writer slot and to detect the simultaneous-connect race. Without the handshake, the acceptor cannot route inbound messages to a peer-identified slot.
+1. **Secure connection identity comes from mTLS plus mutual process admission.**
+   TLS supplies each stable Node Certificate Principal. A signature over the TLS
+   exporter value proves possession of the current process key and cannot be
+   replayed on another TLS session. Mutual proof is required because the Raft
+   connection carries traffic in both directions. The Raft sender or ACL requester
+   must equal its admitted `NodeId`. The first Raft sender then keys the writer slot
+   and detects the simultaneous-connect race.
 
 2. **At most one writer per peer.** `writers` is keyed by `NodeId`. Coexisting writers would split messages to the same peer across two TCP connections; per-connection ordering would let later messages overtake earlier ones in unpredictable patterns, causing the leader to chase its own retries.
 
 3. **Lower NodeId wins on simultaneous connect.** When both sides connect concurrently, the acceptor drops the incoming connection if a writer for the peer already exists AND `peer_id > self.node_id`. Without this rule, both sides retain both connections (each thinks it won), violating invariant 2.
 
 4. **Address resolution is always live.** Every connect attempt queries SWIM for the peer's current address; the transport keeps no local address cache. A stale local cache would connect to the wrong host after a peer moves or restarts on a different address.
 
-5. **Frame sizes are bounded.** Handshake frames capped at 1KB; message frames at 4MB. Without bounds, a malicious or buggy peer can exhaust memory by sending a giant length prefix before any payload.
+5. **Handshake work is bounded.** The listener acquires a permit before
+spawning a handshake task, applies a total handshake deadline, and uses a
+bounded queue to return verified Raft streams to the dispatcher. A slow TLS,
+admission lookup, or proof exchange never blocks the transport select loop.
+
+6. **Frame sizes are bounded.** Initial, process-admission, Raft, proof, and response
+frames are capped before allocating their payload.
 
-6. **Transport validates envelope identity but never interprets the RPC.** The
-connection peer must match the envelope `sender`; a mismatch closes that
+7. **Transport validates message identity but never interprets the RPC.** The
+connection peer must match the message `sender`; a mismatch closes that
 connection. The transport routes by `shard_group_id` and passes the authenticated
 peer onward, but the RPC remains opaque. Voter, learner, leader, term, and log
 checks belong to the target Raft state machine.
+
+## Limited Admission Lookup Rule
+
+Admission records are sharded, so the acceptor may need another broker to read
+the record required for its proof check. Requiring process admission for that
+read would recurse. `AdmissionLookup(AdmissionRecordKey)` is therefore accepted
+after mTLS but before process admission. It can read one named admission record
+from one shard, returns one `AdmissionLookupResponse`, and closes. It cannot
+carry Raft, ACL, client, or admission-write traffic.
+
+## ACL Snapshot Rule
+
+An ACL snapshot request is not a Raft RPC and never enters a Raft state machine.
+In secure mode it is served only after the requester completes process
+admission. It asks the local multi-Raft actor for the selected shard's committed
+ACL record through the broker security actor, returns that record on the same
+connection, then closes. It carries no client data request and cannot proxy one.
+A connection admitted for Raft carries only raw Raft frames after its first
+message; an invalid frame closes the connection.