C-3: a node takes its licence token from the vault (issue 1409)

The agent module asks the seat's current which licence it holds and its key,
then the vault's get for that licence's access secret sealed to its own key:
at its start, on a binding.changed with a newer generation than it applied,
and on the vault's secret-changed for the licence it holds. The applied
binding keeps the licence's key, so the vault's event is matched by the
carried key, never one formed here.

Builds: design 39 bus-and-switch §19, §18, B7, B9, B11

Claude-Session: https://claude.ai/code/session_01NcbgfHb9d4T9nq5Q6WqdiJ
This commit is contained in:
2026-11-11 23:51:00 +01:00
parent 6eccfc286a
commit 31ce47d1cc
7 changed files with 157 additions and 76 deletions
+77 -30
View File
@@ -10,8 +10,10 @@ package main
// fingerprints and expiries — never a token. Written at start and on every change of the credentials
// file, so the licence manager learns a login, or a node already logged in, from the state alone.
// - The grant itself leaves only when the manager asks `claude_code_grant`, sealed to the key it gives.
// - What this node should hold is the manager's `bindings` state; a newer generation for this node is
// fetched with the seat's `current` verb, sealed to this module's key, and written access-token-only.
// - What this node should hold is the manager's binding, heard as `binding.changed` and asked at start; the
// seat's `current` says which licence, and its `access` secret is asked from the vault, sealed to this
// module's key, at start, on a newer generation and on the vault's `secret-changed` for it, and written
// access-token-only (design 39 bus-and-switch §19).
// - An MCP server registered through this module is a key in its `servers` state — `all.<server>` for
// every node, `<node>.<server>` for one — which every node watches.
@@ -30,12 +32,23 @@ import (
"time"
)
// Seat is the licence manager's role, and Manager the module whose `bindings` state this one reads.
// Seat is the licence manager's role, and Manager the module whose events this one consumes.
const (
Seat = "anthropic-licence-manager"
Manager = "claude-licence-manager"
)
// VaultGet is the vault's verb a licence's access secret is asked by, and SecretChanged the vault's event that it
// changed (design 39 bus-and-switch §19, B9).
const (
VaultGet = "seat:mesh-vault.get"
SecretChanged = "mesh-vault.secret-changed"
)
// AccessSecret is the name of a licence's access secret in the vault, by the licence's key as the manager says it
// (§15, B7: the key is carried, never formed here).
func AccessSecret(key string) string { return "licence." + key + ".access" }
// SeatVerb is a seat's verb as the runtime addresses it: a role, not a module.
func SeatVerb(verb string) string { return "seat:" + Seat + "." + verb }
@@ -309,13 +322,14 @@ type BindingState struct {
By string `json:"by,omitempty"`
}
// Current is what the seat answers to `current`: the licence this node is bound to and its token, sealed.
// Current is what the seat answers to `current`: the licence this node is bound to, its key and its account, never
// its token (§18, B7).
type Current struct {
Licence string `json:"licence"`
Kind string `json:"kind"`
Generation int64 `json:"generation"`
Sealed *SealedBox `json:"sealed"`
Identity *Identity `json:"identity"`
Licence string `json:"licence"`
Key string `json:"key"`
Kind string `json:"kind"`
Generation int64 `json:"generation"`
Identity *Identity `json:"identity"`
}
// Holdings is what this node holds, as the `holdings` state carries it (ADR 0206): enough for the manager
@@ -404,40 +418,50 @@ func GrantFor(p Paths, managerPublicKey string) (GrantAnswer, error) {
return GrantAnswer{Sealed: &box, Identity: ReadIdentity(p.account()), Fingerprint: Fingerprint(rt)}, nil
}
// Pull asks the seat for this node's current token and applies it.
// Pull asks the seat which licence this node holds, then the vault for that licence's access secret, sealed to this
// module's key, and applies it (§19).
func Pull(p Paths, ask Ask, write WriteManaged) (map[string]any, error) {
keys, err := Keypair(p)
if err != nil {
return nil, err
}
raw, err := ask(SeatVerb("current"), map[string]any{"consumer": p.Node, "public_key": keys.PublicKey})
raw, err := ask(SeatVerb("current"), map[string]any{"consumer": p.Node})
if err != nil {
return nil, err
}
var c Current
if err := json.Unmarshal(raw, &c); err != nil || c.Sealed == nil {
if err := json.Unmarshal(raw, &c); err != nil || c.Licence == "" || c.Key == "" {
return map[string]any{"applied": false, "reason": "the seat holds no licence for this node"}, nil
}
return Apply(p, c, write)
raw, err = ask(VaultGet, map[string]any{"name": AccessSecret(c.Key), "public_key": keys.PublicKey})
if err != nil {
return nil, err
}
var got struct {
Sealed *SealedBox `json:"sealed"`
}
if err := json.Unmarshal(raw, &got); err != nil || got.Sealed == nil {
return nil, fmt.Errorf("the vault answered no sealed %s", AccessSecret(c.Key))
}
return Apply(p, c, *got.Sealed, write)
}
// OnBinding takes a change to this node's key in the manager's `bindings` state (ADR 0206): the token is
// fetched when the binding differs from the one applied. A released binding keeps the last token, which
// lives hours, and says so.
//
// **Differs, not "is newer"** (novox/hq issue 243). The state keeps only the latest value per node, so
// nothing older can arrive. A manager whose store was rebuilt counts generations from one again, and
// a node that waited for a number above its own ignored every binding it was sent, its login and the
// licence's rotations included, until the count caught up. Only the binding already applied is skipped.
// OnBinding takes this node's binding as the manager said it: the token is fetched when its generation is newer than
// the one applied (§19). A home that holds no token of the applied kind has nothing applied, so it is fetched too. A
// released binding keeps the last token, which lives hours, and says so.
func OnBinding(p Paths, b *BindingState, ask Ask, write WriteManaged) (string, error) {
if b == nil {
return "this node's binding was released; it keeps its last token until it expires", nil
}
var applied Binding
if readJSON(p.binding(), &applied) && applied.Generation == b.Generation && applied.Licence == b.Licence &&
holdsApplied(p, applied.Kind) {
if readJSON(p.binding(), &applied) && b.Generation <= applied.Generation && holdsApplied(p, applied.Kind) {
return "", nil
}
return fetched(p, b, ask, write)
}
// fetched pulls this node's token for binding b and says the line naming it.
func fetched(p Paths, b *BindingState, ask Ask, write WriteManaged) (string, error) {
out, err := Pull(p, ask, write)
if err != nil {
return "", err
@@ -497,21 +521,44 @@ func FirstBinding(p Paths, ask Ask, write WriteManaged) (string, error) {
return "", fmt.Errorf("the seat's bindings answered what is not a list of bindings: %w", err)
}
for _, b := range listed {
if b.Consumer == p.Node {
return OnBinding(p, b.state(), ask, write)
if b.Consumer == p.Node && b.state() != nil {
// At its start the module asks the vault whatever it applied before (§19).
return fetched(p, b.state(), ask, write)
}
}
return OnBinding(p, nil, ask, write)
}
// Apply applies what the seat handed over. A switch replaces the grant whole and cleans up after the old
// licence; whatever it is, the file is written without a refresh token, so the agent here never refreshes.
func Apply(p Paths, c Current, write WriteManaged) (map[string]any, error) {
// secretChanged is the vault's `secret-changed` as it says it: the secret's name and generation, never its value.
type secretChanged struct {
Name string `json:"name"`
Generation int64 `json:"generation"`
}
// OnSecretChanged takes one `secret-changed`: acted on only when it names the access secret of the licence this node
// holds, which is then asked again (§19).
func OnSecretChanged(p Paths, body []byte, ask Ask, write WriteManaged) (string, error) {
var e secretChanged
if err := json.Unmarshal(body, &e); err != nil {
return "", fmt.Errorf("%s is not a secret's change: %w", SecretChanged, err)
}
var applied Binding
if !readJSON(p.binding(), &applied) || applied.Key == "" || e.Name != AccessSecret(applied.Key) {
return "", nil
}
return fetched(p, &BindingState{Licence: applied.Licence, Kind: applied.Kind, Generation: applied.Generation,
Why: "the vault's " + e.Name + " changed"}, ask, write)
}
// Apply applies the access secret the vault handed over for the licence the seat named. A switch replaces the grant
// whole and cleans up after the old licence; whatever it is, the file is written without a refresh token, so the
// agent here never refreshes.
func Apply(p Paths, c Current, sealed SealedBox, write WriteManaged) (map[string]any, error) {
keys, err := Keypair(p)
if err != nil {
return nil, err
}
plain, err := Open(*c.Sealed, keys.PrivateKey)
plain, err := Open(sealed, keys.PrivateKey)
if err != nil {
return nil, err
}
@@ -571,7 +618,7 @@ func Apply(p Paths, c Current, write WriteManaged) (map[string]any, error) {
if gen == 0 {
gen = previous.Generation
}
raw, _ := json.Marshal(Binding{Licence: c.Licence, Kind: c.Kind, Generation: gen})
raw, _ := json.Marshal(Binding{Licence: c.Licence, Key: c.Key, Kind: c.Kind, Generation: gen})
if err := fsys.WriteFile(p.binding(), append(raw, '\n'), 0o600); err != nil {
return nil, err
}