Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
docs: a node can refresh until the key that signed it is retired
Tomas Tormof914204a3014
diff --git a/site/content/docs/concepts/boundaries.md b/site/content/docs/concepts/boundaries.mdindex 677b6ad4..e35e084c 100644--- a/site/content/docs/concepts/boundaries.md+++ b/site/content/docs/concepts/boundaries.md@@ -95,9 +95,12 @@ Both results can be verified offline with the control plane's public key.A credential lasts 24 hours by default and is renewed in the background.Short lifetimes make revocation work without a central check on everyrequest. A stolen credential is useful for at most its remaining lifetime. A-banned node cannot renew. A node that has been offline for longer than the-signing key's grace period has to come back through enrollment instead of-reappearing without notice. The lifetime, the session length, the rotation+banned node cannot renew. Under automatic rotation, the control plane+retires each signing key one grace period after the next rotation. A node+that was offline past the retirement of the key that signed its credential+has to come back through enrollment. So the node cannot reappear without+notice. The one exception is a node that an administrator opted in to+autonomous recovery. The lifetime, the session length, the rotationinterval and the grace period are all control plane flags that the operatorsets.diff --git a/site/content/docs/concepts/identity.md b/site/content/docs/concepts/identity.mdindex a13fb837..d5830af8 100644--- a/site/content/docs/concepts/identity.md+++ b/site/content/docs/concepts/identity.md@@ -232,10 +232,13 @@ already trust. The first key comes from enrollment, and each later key isvouched for by the key it replaces.Nobody can verify a credential signed by a retired key, including the-control plane. A node that was offline for a whole grace period therefore-cannot refresh. This is intentional. The grace period is the deadline after-which a machine that went quiet cannot come back unnoticed. How it comes back-depends on how it enrolled:+control plane. Under automatic rotation, the control plane retires the key+that signed a credential one grace period after the next rotation. With the+defaults, the retirement comes at most 25 hours after the credential was+issued. A node that was offline past that point therefore cannot refresh.+This is intentional. The retirement is the deadline after which a machine+that went quiet cannot come back unnoticed. How it comes back depends on how+it enrolled:- An OIDC node with a refresh token re-enrolls on its own.- A bootstrap node needs an operator to mint a new token and rundiff --git a/site/content/docs/guides/headless-enrollment.md b/site/content/docs/guides/headless-enrollment.mdindex be858390..63fe978a 100644--- a/site/content/docs/guides/headless-enrollment.md+++ b/site/content/docs/guides/headless-enrollment.md@@ -196,19 +196,19 @@ A node or router enrolled with a platform token (`--jwt-path`,`TokenRefreshRequest.jwt` on every `POST /refresh`. As long as the token's`iss|sub` matches the enrolled record, the control plane re-attests the memberin place, updates its stored claims and extends its session-(`--workload-session-ttl`, `48h` by default) without re-enrolling. If the-member was offline longer than the session or key grace period, its renewal-loop automatically re-enrolls with a fresh platform token under the same peer-ID.+(`--workload-session-ttl`, `48h` by default) without re-enrolling. A member+can stay offline past the retirement of the key that signed its credential.+Its renewal loop then re-enrolls with a fresh platform token under the same+peer ID.A node enrolled with a bootstrap token has no login or platform token source-to fall back on. Its credential is refreshed automatically while it runs. But if the node is off-for longer than the control plane's key grace period (`--key-grace-period`,-one hour by default), it comes back with a credential signed by a retired-key, and `/refresh` refuses it. An SDK member in the same position enrolls-again on start when its `enroll` call is given a token, and otherwise-fails with `CredentialRetiredError` naming the state directory. There are-three ways out, in order of preference.+to fall back on. The node refreshes its credential automatically while it+runs. But the control plane retires the key that signed the credential one+`--key-grace-period` (one hour by default) after the next key rotation. If+the node is off past that point, `/refresh` refuses its credential. An SDK+member in the same position enrolls again on start when its `enroll` call is+given a token. Otherwise the SDK member fails with `CredentialRetiredError`+naming the state directory. There are three ways out, in order of preference.**Enroll again.** Mint a new token and run `agentmesh-node join` with it. Thecontrol plane already knows the peer ID, so it mints a new credentialdiff --git a/site/content/docs/guides/kubernetes.md b/site/content/docs/guides/kubernetes.mdindex 374934d1..c98b4d8c 100644--- a/site/content/docs/guides/kubernetes.md+++ b/site/content/docs/guides/kubernetes.md@@ -208,9 +208,12 @@ keep, review these settings:`mesh:system:authenticated` to a role with wide grants: on a publicidentity provider it means everyone. The testnets bind it on purpose. Aprivate mesh should bind groups or service accounts.-- **Signing keys.** `--key-grace-period` defaults to one hour. A node that is- down for longer must enroll again. The testnets use 48 hours. Pick a value- that matches how long your nodes can legitimately be off.+- **Signing keys.** `--key-grace-period` defaults to one hour. The control+ plane retires a key one grace period after the next rotation. A node that+ is down past the retirement of the key that signed its credential must+ enroll again. With the defaults, that retirement comes between about one+ and 25 hours after the node goes down. The testnets use 48 hours. Pick a+ value that matches how long your nodes can legitimately be off.- **Console origin.** When a proxy terminates TLS in front of the console,set `console.externalUrl` so that the OIDC redirect URI and the cookie`Secure` flag do not depend on forwarded headers.