Security & threat model

Audience: operators deploying PearDock in multi-operator or semi-trusted environments. Scope: HyperDHT P2P control plane + local Docker Engine socket.

1. Assets

Asset	Sensitivity
`SERVER_SEED`	Critical: identity and vault key derivation
Docker socket access	Critical: full host container control
Registry passwords (vault)	High: encrypted at rest
Peer invite tokens	Medium: short-lived capabilities
Audit log	Medium: forensic integrity
Container data / env secrets	High: via inspect, logs, exec

2. Trust boundaries

[Client] --Noise/HyperDHT--> [peardock server] --unix socket--> [dockerd]
                                  |
                                  +-- peardock-vault.json (AES-GCM)
                                  +-- peardock-peers.json
                                  +-- peardock-audit.log

Anyone with the server public key can attempt a DHT connection.
Default role is admin unless default role / admin keys / peer policy tighten it.
Swarm / plugins are off unless feature flags enable them.
Holesail tunnels are on by default. Each hs:// URL is a port capability.
Host FS browse is default-deny unless browse roots / open mode are set.

3. Adversaries

Remote peer with public key only: should not get Docker control if allowlist and non-admin default are set.
Stolen invite token: limited by TTL and max uses. Rotate after use.
Compromised client: can use any role the peer holds until revoke.
Local host attacker with filesystem: can steal seed and vault if file perms are wrong.
Malicious container: out of scope for PearDock. Engine isolation applies.

4. Controls (implemented)

Control	Mechanism
Transport E2E	HyperDHT Noise
Capability ACL	viewer / operator / admin + MethodRoles
Peer policy	Invite, register, revoke, optional allowlist
Audit	Append-only log for privileged methods
Rate limit	Per-peer limiter on RPC
Registry secrets	AES-256-GCM vault
Browse FS	Root allowlist / default deny
Tunnel targets	Loopback / allowlisted hosts only

5. Residual risks

Default admin is intentional for single-operator setup. Change it for multi-tenant fleets.
Binary image/export streams are size-capped but still large; DoS via memory if many concurrent transfers.
JSON-over-RPC relies on handler validation (not full hyperschema end-to-end).
Swarm secrets/configs once enabled are highly privileged.

6. Operator hardening checklist

Generate unique SERVER_SEED; back up offline; never commit .env
Set PEARDOCK_DEFAULT_ROLE=viewer or operator
Set PEARDOCK_ADMIN_KEYS=<your client public key hex>
Enable PEARDOCK_PEER_ALLOWLIST=1 after registering operators
Set PEARDOCK_BROWSE_ROOTS only if host path pickers are needed
Enable PEARDOCK_AUDIT=1
Treat hs:// tunnel URLs as secrets; set ENABLE_HOLESAIL=0 if unused
Restrict filesystem permissions on vault, peers, and seed files