Skip to content

Commit 5b0c278

Browse files
cdeckerclaude
andcommitted
docs: Describe signer state integrity in the security model
Add the trust split for the signer state stored by the node, and how state signatures and the planned state anchor protect it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ji71TQF9Mzmw65zDR1juzH
1 parent 3e531d0 commit 5b0c278

1 file changed

Lines changed: 33 additions & 0 deletions

File tree

‎docs/src/reference/security.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,39 @@ operations. An attacker that gains access to the node is unable to
9090
provide either these signatures and will therefore fail to convince
9191
the signer of its injected commands.
9292

93+
## Signer State Integrity
94+
95+
The signer does not store its own state. The node stores the
96+
[signer state](signer-state.md) (channel states, allowed on-chain
97+
destinations, known invoices) and attaches it to every request. An
98+
attacker with access to the node infrastructure can therefore read,
99+
withhold, replay or modify the state a signer receives, and the signer
100+
must not trust it blindly.
101+
102+
| Party | Trusted with | Not trusted with |
103+
|-------|--------------|------------------|
104+
| Node infrastructure | Storing and returning the state | The content, age or completeness of the state |
105+
| Signer | Writing and signing state entries | |
106+
| Application embedding the signer | Keeping the state anchor, choosing enforcement options | |
107+
108+
- **Authenticity:** every state entry is signed with a key derived
109+
from the node secret. In `hard` state signature mode the signer
110+
refuses entries with missing or invalid signatures, so the node
111+
cannot inject or alter state.
112+
- **Freshness and completeness** (planned): a small _state anchor_
113+
kept on the device records the latest version of every key the
114+
signer has seen. On start, the signer refuses state that is older
115+
than its anchor, is missing keys, or brings back deleted keys.
116+
- **Enforcement options belong to the application.** The state
117+
signature mode and anchor enforcement are set where the signer is
118+
embedded; the node cannot change them, and there is no way for the
119+
node to reset an anchor.
120+
121+
A signer without an anchor, for example right after pairing or
122+
recovery, trusts the first state it receives. See
123+
[Signer State](signer-state.md) for the details and the configuration
124+
options.
125+
93126
## Client &rlarr; Signer Authorization
94127

95128
The [`rune`][rune]-based signer authentication verifies a client's

0 commit comments

Comments
 (0)