docs(security): RFC — per-agent remote-signer keystore isolation (follow-up to #570)

[bussyjd]

Summary

Design RFC (no controller code yet) for the isolation follow-up that #570 explicitly defers. #570 scopes the controller's Secret access to three names, but a name-scoped ClusterRole still matches remote-signer-keystore in any namespace — so the controller can read every agent's keystore + password. This RFC captures the verified custody flow and a recommended path out.

Full doc: plans/per-agent-keystore-isolation.md

Verified custody flow (code-level)

• Keys are minted in the controller process — openclaw.GenerateKeystoreInMemory() (internal/openclaw/wallet.go:136).
• remote-signer:v0.3.0 only consumes a mounted keystore; no evidence it self-generates.
• Post-mint the controller reads only the address annotation, but GET on the Secret returns the key + password too, so the standing capability is the real exposure.

Two sub-risks

1. Standing cross-agent read — a compromised controller GETs every agent's keystore → drains every agent wallet.
2. In-process custody at mint — the controller holds each private key + password at provisioning time, regardless of RBAC.

Options (full tradeoffs in the doc)

Option	Verdict
0 — Accept + document	Honest fallback, not the goal
A — Per-namespace Role for the controller SA	❌ Rejected — isolation theater (controller manages all agents, binds itself everywhere)
B — Agent self-mints; controller leaves custody path	✅ Recommended
C — Unique per-agent names	Only useful layered onto B

Recommendation

Option B, phased: in-pod keystore generation → namespaced Role for the agent SA + address-via-Agent.status → drop remote-signer-keystore from the controller ClusterRole (+ guard test).

Open questions (gate Phase 1)

1. Can remote-signer:v0.3.0 self-generate a keystore on first boot (empty keystore dir)? If not → init-container mint tool.
2. Is Agent.status.walletAddress the right address channel, with the agent SA granted namespaced patch on agents/status?
3. Anything besides the remote-signer pod consuming the keystore Secret directly?

🤖 Generated with Claude Code

[bussyjd]

Superseded by #573 — the per-agent keystore isolation design now lives as a diagram-rich tracking issue (decoupled from any code branch) so it can be discussed and scheduled independently. The immediate RBAC hardening remains in #570. Branch security/per-agent-keystore-isolation is left intact for reference.