Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/added-19235-hub-key-rotation-grace.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- **Hub: registration key rotation with a grace window ([#19235](https://github.com/hivecommons/hive/issues/19235)).** With `HIVE_HUB_SELFSERVICE_KEY_GRACE` on, the old heartbeat key of a self-service registration keeps working for `HIVE_HUB_SELFSERVICE_KEY_GRACE_WINDOW` (default `1h`, clamped to `168h`) after a rotation, and rotating again inside the window keeps the old key and replaces the pending one, so a rotation never cuts off a running spoke. Off by default; existing registrations need no change and nothing writes to GitHub. The `selfservice_hive_rotated` audit line gains `grace`, `replaced_pending` and `old_key_expires_at`, with no key or hash.
4 changes: 2 additions & 2 deletions src/docs/api-reference/hub-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,9 +63,9 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f
| `GET` | `/api/hub/v1/registrations` | Hub auth | The caller's own registrations: `{registrations[]}`, each with its `etag` and `repo_proofs`; never a key or a hash | `pkg/hub/selfservice_v1_api.go` |
| `GET` | `/api/hub/v1/registrations/{id}` | Hub auth | One of the caller's registrations: `{registration}` with a strong `ETag` header; `If-None-Match` with the current ETag answers `304`. Another user's hive, a missing hive and a hub admin who does not own it all get `404`. The ETag comes from a revision counter that heartbeats do not bump, and reveals nothing about the key | `pkg/hub/selfservice_v1_api.go` |
| `PATCH` | `/api/hub/v1/registrations/{id}` | Hub auth | Owner only, by hub session (a registration key is not accepted): change `repos` and/or `dashboard_url` in place with the heartbeat key kept valid ([#18642](https://github.com/hivecommons/hive/issues/18642)). Body: `repos` is a full list (replacement) or `{add[], remove[]}`; `dashboard_url` is an `https` URL or `""` to clear it. `If-Match` is required: `428` when absent, `412` carrying the current `ETag` when stale (checked before any GitHub call and again under the store lock). Only added repos are proven (`403` naming the first refused repo, nothing applied); kept repos keep their proof time and removed repos lose theirs. `org`, the owner, the ID and the keys are not editable: a body naming `org` or any other field is `400`, as is a list that would leave no repo. Over `HIVE_HUB_SELFSERVICE_MAX_REPOS` is `413 {error, limit: "max_repos", max_repos}`. Removing a repo the registration does not list is ignored; an edit that changes nothing answers `200` with the current `ETag` and does not bump the revision. `200 {registration}` with the new `ETag`; the key never appears. `404` for a missing hive, another user's hive and a hub admin who does not own it; `404` while `HIVE_HUB_SELFSERVICE_REGISTRATION` is off | `pkg/hub/selfservice_v1_patch.go` |
| `POST` | `/api/hub/v1/registrations/{id}/keys` | Hub auth | Owner only: rotate the heartbeat key; the previous key keeps authenticating for the 10 minute overlap. `201 {id, key, hub_url, overlap, snippets}` (the legacy rotate answers `200`) with the new `ETag`; the raw key appears once. Optional `If-Match` (`412` when stale). A body asking for a grace window is refused with `400`: caller-chosen grace is a later rollout step | `pkg/hub/selfservice_v1_api.go` |
| `POST` | `/api/hub/v1/registrations/{id}/keys` | Hub auth | Owner only: rotate the heartbeat key; the previous key keeps authenticating for the 10 minute overlap, or for `HIVE_HUB_SELFSERVICE_KEY_GRACE_WINDOW` while `HIVE_HUB_SELFSERVICE_KEY_GRACE` is on, in which case a rotation inside an open window keeps the old key and replaces the pending one ([#19235](https://github.com/hivecommons/hive/issues/19235)). `201 {id, key, hub_url, overlap, snippets}` (the legacy rotate answers `200`) with the new `ETag`; the raw key appears once. Optional `If-Match` (`412` when stale). A body asking for a grace window is refused with `400`: caller-chosen grace is a later rollout step | `pkg/hub/selfservice_v1_api.go` |
| `DELETE` | `/api/hub/v1/registrations/{id}` | Hub auth | Owner or hub admin: revoke the key and remove the registry entry. `200 {removed, id}`. Optional `If-Match` (`412` when stale, carrying the current `ETag`) | `pkg/hub/selfservice_v1_api.go` |
| `POST` | `/api/hub/selfservice/hives/{id}/rotate` | Hub auth | Owner only: mint a new heartbeat key for `{id}`; the previous key keeps authenticating for `overlap` (10 minutes). `200 {id, key, hub_url, overlap, snippets}`, raw key once. Another user's hive, a missing hive and a hub admin who does not own it all get `404` | `pkg/hub/server.go:1794` |
| `POST` | `/api/hub/selfservice/hives/{id}/rotate` | Hub auth | Owner only: mint a new heartbeat key for `{id}`; the previous key keeps authenticating for `overlap` (10 minutes, or the grace window while `HIVE_HUB_SELFSERVICE_KEY_GRACE` is on). `200 {id, key, hub_url, overlap, snippets}`, raw key once. Another user's hive, a missing hive and a hub admin who does not own it all get `404` | `pkg/hub/server.go:1794` |
| `DELETE` | `/api/hub/selfservice/hives/{id}` | Hub auth | Owner or hub admin: revoke the key and remove the registry entry. `200 {removed, id}`; another user's hive is `404` | `pkg/hub/server.go:1795` |
| `POST` | `/api/contribute/register` | Hub handler-specific | Contribute Proxy | `pkg/hub/server.go:1799` |
| `GET` | `/api/contribute/status` | Hub handler-specific | Contribute Status | `pkg/hub/server.go:1800` |
Expand Down
2 changes: 1 addition & 1 deletion src/docs/audit-log.md
Original file line number Diff line number Diff line change
Expand Up @@ -205,7 +205,7 @@ a key hash, the master secret or the user's GitHub token.
| --- | --- | --- |
| `selfservice_hive_registered` | A registration passed every check and the key was minted | `user`, `hive`, `repos` (count), `org` |
| `selfservice_hive_updated` | The owner changed `repos` and/or `dashboard_url` with `PATCH /api/hub/v1/registrations/{id}`; the heartbeat key is untouched. A request that changes nothing writes no line | `user`, `hive`, `repos_added` (count), `repos_removed` (count), `dashboard_changed`, `revision` |
| `selfservice_hive_rotated` | The owner rotated the heartbeat key | `user`, `hive`, `overlap` (how long the previous key keeps authenticating) |
| `selfservice_hive_rotated` | The owner rotated the heartbeat key | `user`, `hive`, `overlap` (how long the previous key keeps authenticating), `grace` (`HIVE_HUB_SELFSERVICE_KEY_GRACE` on), `replaced_pending` (a rotation inside an open grace window replaced the pending key and kept the old one), `old_key_expires_at` (RFC 3339). Never a key or a hash |
| `selfservice_hive_revoked` | The owner or a hub admin revoked the hive; the registry entry is removed in the same request and `registry entry removed` follows | `user`, `hive`, `owner`, `by_admin` |
| `selfservice_hive_expired` | The expiry sweep (`pkg/hub/selfservice_expiry.go`, every `HIVE_HUB_SELFSERVICE_SWEEP_INTERVAL`) removed a hive that went longer than `HIVE_HUB_SELFSERVICE_EXPIRY` without an accepted heartbeat; the key is revoked and `registry entry removed` (with `by=selfservice-expiry-sweep`) follows | `id`, `owner`, `last_heartbeat` (RFC 3339, or `never` when no heartbeat was ever accepted), `expiry` |
| `selfservice_hive_refused` | A registration was turned away and nothing was stored | `user`, `hive`, `reason` (`invalid_name`, `invalid_login`, `reserved_prefix`, `duplicate_id`, `invalid_repos`, `invalid_dashboard_url`, `invalid_update` (a `PATCH` body the hub refused), `per_user_cap` with `max_per_user`, `no_github_token`, `no_github_login`, `not_repo_admin` with `repo`, `ownership_check_error` with `repo`, `proof_token_refused` (a failed `github-user-token` proof) with `proof_method`, `proof_reason` and `repo` when one repo failed) |
Expand Down
2 changes: 2 additions & 0 deletions src/docs/env-vars.md
Original file line number Diff line number Diff line change
Expand Up @@ -126,6 +126,8 @@ behavior. [Maintenance limitations](#keeping-this-reference-current) still apply
| `HIVE_HUB_SELFSERVICE_MAX_PER_USER` | No | `5` | Maximum self-service hives one user may have registered at once; the next registration answers `429` until one is removed. |
| `HIVE_HUB_SELFSERVICE_MAX_REPOS` | No | `20` | Maximum repos one self-service registration may list ([#18642](https://github.com/hivecommons/hive/issues/18642)). Each listed repo costs one read-only GitHub ownership check, so values above `500` are clamped to `500`; a non-numeric or non-positive value falls back to `20`. Advertised by `GET /api/hub/v1` as `limits.max_repos`. Over the cap, `POST /api/hub/selfservice/hives` answers `400`; `POST /api/hub/v1/registrations` answers `413` with `limit: max_repos`. Read per request. Only meaningful while `HIVE_HUB_SELFSERVICE_REGISTRATION` is on. |
| `HIVE_HUB_PROOF_GITHUB_USER_TOKEN` | No | off | Offers the `github-user-token` ownership proof on the v1 registration create and `PATCH` routes ([#19238](https://github.com/hivecommons/hive/issues/19238)): the caller sends `X-Hive-Proof-Method: github-user-token` and `X-Hive-Proof-Token`, and the hub checks `permissions.admin` with that token for the request only (never stored or logged). Advertised by `GET /api/hub/v1` in `proof_methods` and `proof_method_details`. Accepts `1/true/yes/on`. Read per request. Only meaningful while `HIVE_HUB_SELFSERVICE_REGISTRATION` is on. |
| `HIVE_HUB_SELFSERVICE_KEY_GRACE` | No | off | Turns on key rotation with a grace window for self-service registrations ([#19235](https://github.com/hivecommons/hive/issues/19235)). While on, the old key keeps authenticating for `HIVE_HUB_SELFSERVICE_KEY_GRACE_WINDOW` after a rotation, and a rotation while a window is open keeps the old key and replaces the pending one. While off, rotation keeps the fixed 10 minute overlap. Accepts `1/true/yes/on`. Read per request. |
| `HIVE_HUB_SELFSERVICE_KEY_GRACE_WINDOW` | No | `1h` | How long the old key keeps working after a rotation while `HIVE_HUB_SELFSERVICE_KEY_GRACE` is on. Go duration syntax; an invalid or non-positive value falls back to `1h`, and values above `168h` are clamped to `168h`. Advertised by `GET /api/hub/v1` as `limits.key_rotation_overlap`. Read per request. |
| `HIVE_HUB_SELFSERVICE_EXPIRY` | No | `24h` | How long a self-service hive may go without an accepted heartbeat before the expiry sweep revokes its key and removes its registry entry (counted from the last accepted heartbeat, or from registration while there has been none). Reported by `GET /api/hub/selfservice/status` as `expiry`. Go duration syntax. |
| `HIVE_HUB_SELFSERVICE_SWEEP_INTERVAL` | No | `10m` | How often the self-service expiry sweep (`src/pkg/hub/selfservice_expiry.go`) runs. Each removal writes `audit: selfservice_hive_expired` (see [audit-log.md](audit-log.md)). Read at startup; restart after changing. Go duration syntax. |
| `HIVE_HUB_HEARTBEAT_PROTOCOL` | No | off | Heartbeat feature negotiation ([#19237](https://github.com/hivecommons/hive/issues/19237)). When on (`1/true/yes/on`), a heartbeat that carries `protocol: {version, features}` is answered with `protocol: {version, accepted, ignored}` (plus `unsupported_version` for a version below `1`). A heartbeat without `protocol` is answered exactly as before. Read per request. See [hub-deployment.md](hub-deployment.md#heartbeat-feature-negotiation). |
Expand Down
8 changes: 6 additions & 2 deletions src/docs/hub-deployment.md
Original file line number Diff line number Diff line change
Expand Up @@ -183,10 +183,12 @@ The fence above is always on. The registration flow that fills the `byo-` namesp
| `HIVE_HUB_SELFSERVICE_MAX_PER_USER` | `5` | How many `byo-` hives one GitHub login may hold at once. The next registration answers `429` until the user removes one. |
| `HIVE_HUB_SELFSERVICE_MAX_REPOS` | `20` | How many repos one registration may list ([#18642](https://github.com/hivecommons/hive/issues/18642)). Each repo is one read-only GitHub ownership check, so values above `500` are clamped to `500`. `POST /api/hub/selfservice/hives` answers `400` over the cap; `POST /api/hub/v1/registrations` answers `413` with `limit: max_repos`. Advertised to clients by `GET /api/hub/v1` as `limits.max_repos`. Read per request. |
| `HIVE_HUB_PROOF_GITHUB_USER_TOKEN` | off | Offers the `github-user-token` ownership proof on `POST /api/hub/v1/registrations` and `PATCH /api/hub/v1/registrations/{id}` ([#19238](https://github.com/hivecommons/hive/issues/19238)). See [Proving ownership with your own token](#proving-ownership-with-your-own-token). Accepts `1/true/yes/on`. Read per request. Only meaningful while `HIVE_HUB_SELFSERVICE_REGISTRATION` is on. |
| `HIVE_HUB_SELFSERVICE_KEY_GRACE` | off | Key rotation with a grace window ([#19235](https://github.com/hivecommons/hive/issues/19235)); see [Rotation](#rotation). Accepts `1/true/yes/on`. Read per request. |
| `HIVE_HUB_SELFSERVICE_KEY_GRACE_WINDOW` | `1h` | How long the old key keeps working after a rotation while `HIVE_HUB_SELFSERVICE_KEY_GRACE` is on. Clamped to `168h`. Read per request. |
| `HIVE_HUB_SELFSERVICE_EXPIRY` | `24h` | How long a registered hive may go without an accepted heartbeat before the sweep removes it. Counted from the last accepted heartbeat, or from registration while there has been none. |
| `HIVE_HUB_SELFSERVICE_SWEEP_INTERVAL` | `10m` | How often the expiry sweep runs. Read at startup; restart after changing. |

All four are listed with the other hub variables in [env-vars.md](env-vars.md).
All of them are listed with the other hub variables in [env-vars.md](env-vars.md).

#### What a registration does

Expand Down Expand Up @@ -245,6 +247,8 @@ A spoke may send `protocol: {"version": 1, "features": [...]}` in its heartbeat

The owner can rotate from the **Self-hosted hives** list or with `POST /api/hub/selfservice/hives/{id}/rotate`. The hub mints a new key and keeps the previous hash live for a 10 minute overlap so a running spoke can pick up the new value without a gap. After the overlap only the new key is accepted. Only the owner can rotate; a hub admin who does not own the hive gets `404`, the same answer as for a missing hive.

With `HIVE_HUB_SELFSERVICE_KEY_GRACE` on ([#19235](https://github.com/hivecommons/hive/issues/19235)), the overlap is the configurable grace window `HIVE_HUB_SELFSERVICE_KEY_GRACE_WINDOW` (default `1h`) instead of 10 minutes, on both the v6 route and `POST /api/hub/v1/registrations/{id}/keys`. Rotating again while a window is open keeps the old key, the one the spoke is still running, and replaces the pending key: the key from the earlier rotation stops working at once, and the window restarts. So rotating twice by mistake never cuts off the running spoke. The `overlap` in the response and `limits.key_rotation_overlap` in discovery report the window in effect. Existing registrations need no change.

#### Expiry sweep

A background sweep runs every `HIVE_HUB_SELFSERVICE_SWEEP_INTERVAL` and removes any `byo-` hive whose last accepted heartbeat is older than `HIVE_HUB_SELFSERVICE_EXPIRY`, or that never heartbeated within that window after registration. The key is revoked and the registry entry is removed in the same pass. The owner registers again when the hive is back; there is no grace list.
Expand All @@ -262,7 +266,7 @@ Every decision writes one structured log line, documented in [audit-log.md](audi
| `selfservice_hive_registered` | A registration passed every check and a key was minted. |
| `selfservice_hive_refused` | A registration was turned away; `reason` is one of `invalid_name`, `reserved_prefix`, `duplicate_id`, `invalid_repos`, `invalid_dashboard_url`, `invalid_update` (a `PATCH` body that was refused), `per_user_cap`, `no_github_token`, `no_github_login`, `not_repo_admin`, `ownership_check_error`. |
| `selfservice_hive_updated` | The owner edited the repos or dashboard URL with `PATCH`; the line counts repos added and removed and carries no key. |
| `selfservice_hive_rotated` | The owner rotated the key; `overlap` is how long the old key keeps working. |
| `selfservice_hive_rotated` | The owner rotated the key; `overlap` is how long the old key keeps working, `grace` whether the grace window is on, `replaced_pending` whether a pending key inside an open window was replaced, `old_key_expires_at` when the old key stops working. No key or hash. |
| `selfservice_hive_revoked` | The owner or an admin removed the hive; `by_admin` tells which. |
| `selfservice_hive_expired` | The sweep removed a hive; `last_heartbeat` is RFC 3339 or `never`. |

Expand Down
7 changes: 4 additions & 3 deletions src/pkg/hub/selfservice_api.go
Original file line number Diff line number Diff line change
Expand Up @@ -688,7 +688,8 @@ func (s *HubServer) handleSelfServiceRotate(w http.ResponseWriter, r *http.Reque
if !ok {
return
}
rawKey, err := s.selfService.rotate(h.ID)
policy := currentSelfServiceKeyRotationPolicy()
rawKey, rotation, err := s.selfService.rotateWithPolicy(h.ID, "", policy)
if err != nil {
if errors.Is(err, errSelfServiceNotFound) {
writeJSONError(w, http.StatusNotFound, "self-hosted hive not found")
Expand All @@ -698,14 +699,14 @@ func (s *HubServer) handleSelfServiceRotate(w http.ResponseWriter, r *http.Reque
writeJSONError(w, http.StatusInternalServerError, "could not persist the new key")
return
}
s.logger.Info("audit: selfservice_hive_rotated", "user", login, "hive", h.ID, "overlap", selfServiceKeyRotationOverlap.String())
s.auditSelfServiceRotated(login, h.ID, policy, rotation)
hubURL := hubPublicURL()
w.Header().Set("Content-Type", "application/json")
_ = json.NewEncoder(w).Encode(map[string]any{
"id": h.ID,
"key": rawKey,
"hub_url": hubURL,
"overlap": selfServiceKeyRotationOverlap.String(),
"overlap": policy.window.String(),
"snippets": selfServiceSnippets(hubURL, h.ID, rawKey),
})
}
Expand Down
2 changes: 2 additions & 0 deletions src/pkg/hub/selfservice_api_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,8 @@ func newSelfServiceTestEnv(t *testing.T) *selfServiceTestEnv {
t.Helper()
t.Setenv(selfServiceRegistrationEnv, "true")
t.Setenv(selfServiceMaxPerUserEnv, "")
t.Setenv(selfServiceKeyGraceEnv, "")
t.Setenv(selfServiceKeyGraceWindowEnv, "")
t.Setenv(selfServiceTestAdminEnv, selfServiceTestAdmin)
withTempSaaSDirs(t)

Expand Down
Loading
Loading