docs(security): clarify peer identity boundaries

Author: AlisinaDevelo

CHANGELOG.md

@@ -8,6 +8,7 @@ All notable changes to StreamHive are documented here. This project follows [Sem
 
 - **`p2p`**: `PeerSnapshots` exposes connected peer metadata for operational tooling.
 - **Docs**: protocol reference for SHV1 frames, replication messages, limits, and repair behavior.
+- **Docs**: TLS/mTLS peer identity guidance and remaining application-level auth gaps.
 
 ### Changed
 

SECURITY.md

@@ -8,6 +8,23 @@ If you believe you have found a security vulnerability, please open a **private*
 
 This project is experimental research code. It is not hardened for hostile networks; treat deployments accordingly.
 
+## Transport Security And Identity
+
+StreamHive can wrap peer connections in TLS:
+
+- `-tls-cert` and `-tls-key` enable TLS on the listener.
+- `-tls-ca` and `-tls-server-name` enable outbound certificate verification.
+- `-tls-insecure-skip-verify` is for local development only.
+
+Library users can configure `p2p.TCPTransport.TLSServerConfig` and
+`p2p.TCPTransport.TLSClientConfig` directly. Use `tls.Config.ClientAuth`,
+`ClientCAs`, and client certificates when you need mTLS.
+
+TLS protects the TCP channel and, when configured with CA verification, authenticates the
+certificate presented by the peer. StreamHive does not yet have application-level peer
+identity, authorization, ACLs, or signed replication messages. Do not expose the P2P
+port to untrusted networks without a deployment-level trust boundary.
+
 ## Dependency scanning
 
 CI runs `govulncheck ./...` on each push and pull request to `main`.

docs/ARCHITECTURE.md

@@ -112,7 +112,7 @@ stateDiagram-v2
 
 - **Dial** respects context cancellation and optional `DialTimeout`.
 - **Max peers** rejects new inbound connections when the cap is reached (`PeersRejected` metric).
-- **TLS** failures surface from `HandshakeContext` on outbound dials. **mTLS** is supported by configuring `tls.Config` yourself (`ClientAuth`, `ClientCAs` on `TLSServerConfig`; client certs on `TLSClientConfig`). There is no application-level identity beyond TLS yet.
+- **TLS** failures surface from `HandshakeContext` on outbound dials. **mTLS** is supported by configuring `tls.Config` yourself (`ClientAuth`, `ClientCAs` on `TLSServerConfig`; client certs on `TLSClientConfig`). TLS can authenticate certificates, but StreamHive still has no application-level peer identity, authorization, ACLs, or signed replication messages.
 - **Replication decode/apply** rejects unknown message types, empty keys, oversized keys, and oversized payloads before writing to storage.
 
 ## Replication v0.3 scope

docs/DEPLOYMENT.md

@@ -14,7 +14,7 @@ docker run --rm -p 7070:7070 -p 8080:8080 streamhive:local \
 - **7070** — P2P TCP listener (example).
 - **8080** — HTTP `/livez`, `/readyz`, `/peers` (JSON peer metadata), `/metrics` (JSON counters), `/metrics/prometheus` (Prometheus text).
 
-Use TLS flags (`-tls-cert`, `-tls-key`, `-tls-ca`, …) when exposing services beyond a lab network.
+Use TLS flags (`-tls-cert`, `-tls-key`, `-tls-ca`, `-tls-server-name`) when exposing services beyond a lab network. Reserve `-tls-insecure-skip-verify` for local development. For mTLS or custom trust policy, configure `p2p.TCPTransport.TLSServerConfig` and `TLSClientConfig` in library code. StreamHive does not yet provide application-level peer identity or authorization; keep the P2P port behind a trusted network boundary.
 
 ## Docker Compose demo