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-19056-hub-v1-patch-registration.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Hub registration protocol v1: a registration can now be edited in place with `PATCH /api/hub/v1/registrations/{id}`, so adding a repo or moving the dashboard URL no longer means deleting the registration (which revoked its key and took the spoke offline) and registering again. The heartbeat key is never touched. The body changes `repos` (a full list, or `{add, remove}`) and/or `dashboard_url`; `If-Match` with the record's `ETag` is required (`428` when missing, `412` when stale), only the repos an edit adds are checked against GitHub with the owner's own stored token (read only), and a repo list over `HIVE_HUB_SELFSERVICE_MAX_REPOS` answers `413` naming the limit. `org`, the owner and the keys are not editable. It is owner-only by hub session, writes nothing to GitHub, is gated by `HIVE_HUB_SELFSERVICE_REGISTRATION` like the rest of v1, and is listed in `GET /api/hub/v1` discovery (`operations` and `patch_fields`); the v6 `/api/hub/selfservice/*` routes are unchanged. Each edit writes a `selfservice_hive_updated` audit line with counts and no key ([#19056](https://github.com/hivecommons/hive/issues/19056)).
1 change: 1 addition & 0 deletions src/docs/api-reference/hub-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,7 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f
| `POST` | `/api/hub/v1/registrations` | Hub auth | Register a self-hosted hive as a resource ([#18642](https://github.com/hivecommons/hive/issues/18642)): the same body, proof and refusals as `POST /api/hub/selfservice/hives` (including `429` over `HIVE_HUB_SELFSERVICE_MAX_PER_USER`), except that a repo list over `HIVE_HUB_SELFSERVICE_MAX_REPOS` answers `413 {error, limit: "max_repos", max_repos}` instead of `400`. `201 {registration, key, hub_url, snippets}` with `Location` and a strong `ETag` header; `registration` is the legacy view plus `etag` and `repo_proofs[{repo, checked_at}]` (when the owner's admin permission on each repo was last proven). The raw key appears once. `404` while `HIVE_HUB_SELFSERVICE_REGISTRATION` is off | `pkg/hub/selfservice_v1_api.go` |
| `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` |
| `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:1791` |
Expand Down
3 changes: 2 additions & 1 deletion src/docs/audit-log.md
Original file line number Diff line number Diff line change
Expand Up @@ -204,10 +204,11 @@ a key hash, the master secret or the user's GitHub token.
| Action | Written when | Keys |
| --- | --- | --- |
| `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_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`, `per_user_cap` with `max_per_user`, `no_github_token`, `no_github_login`, `not_repo_admin` with `repo`, `ownership_check_error` with `repo`) |
| `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`) |

## Rotation and retention

Expand Down
16 changes: 15 additions & 1 deletion src/docs/hub-deployment.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,19 @@ The registry entry becomes a `self-hosted` hive in Active Hives and the fleet vi
- The owner never receives `HIVE_HUB_SECRET`. The hub never consults it in the self-service routes and never returns it.
- Everything the fence withholds still applies: the hub sends the hive no GitHub App config, gateway, cluster ID, authorized users, upgrade or branch-switch instructions, restarts or fleet-breaker actions. Listing is directory metadata only.

#### Editing a registration

`PATCH /api/hub/v1/registrations/{id}` changes `repos` and `dashboard_url` in place, so adding a repo no longer means deleting the registration and registering again (which revoked the key and took the spoke offline). The heartbeat key is not touched: the spoke keeps heartbeating with the key it has.

- **Who:** the owner, signed in to the hub. A registration key cannot edit its own record, and a hub admin who does not own the hive gets `404`.
- **`If-Match` is required.** `GET /api/hub/v1/registrations/{id}` returns the `ETag`; send it back on the `PATCH`. A missing header is `428`, a stale one is `412` with the current `ETag`, so two operators editing at once cannot silently overwrite each other. Heartbeats do not change the `ETag`.
- **`repos`:** a full list replaces the repos, or `{"add": [...], "remove": [...]}` changes them. Only the repos an edit adds are checked against GitHub (the same read-only `permissions.admin` check as registration, with the owner's own stored token); one failing repo refuses the whole edit and nothing is applied. Kept repos keep their proof time, and removed repos lose theirs. At least one repo must remain, and `HIVE_HUB_SELFSERVICE_MAX_REPOS` applies (`413 {limit: "max_repos"}`).
- **`dashboard_url`:** an `https` URL to a public address, or `""` to clear it.
- **Not editable:** `org`, the owner, the ID and the keys. To change the `org`, delete the registration and register it again.
- **No GitHub writes.** The edit changes the hub's own registry only.

The route is part of the v1 registration protocol and follows the same switch as the rest of it, `HIVE_HUB_SELFSERVICE_REGISTRATION`; discovery (`GET /api/hub/v1`) lists it under `operations` with `if_match: "required"` and its fields under `patch_fields`, so a hub that does not offer it does not advertise it. The v6 `/api/hub/selfservice/*` routes are unchanged.

#### Rotation

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.
Expand All @@ -144,7 +157,8 @@ Every decision writes one structured log line, documented in [audit-log.md](audi
| Event | When |
|---|---|
| `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`, `per_user_cap`, `no_github_token`, `no_github_login`, `not_repo_admin`, `ownership_check_error`. |
| `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_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
1 change: 1 addition & 0 deletions src/pkg/hub/selfservice_api.go
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,7 @@ const (
selfServiceRefusedDuplicateID = "duplicate_id"
selfServiceRefusedInvalidRepos = "invalid_repos"
selfServiceRefusedInvalidURL = "invalid_dashboard_url"
selfServiceRefusedInvalidUpdate = "invalid_update"
selfServiceRefusedCap = "per_user_cap"
selfServiceRefusedNoToken = "no_github_token"
selfServiceRefusedNotAdmin = "not_repo_admin"
Expand Down
18 changes: 11 additions & 7 deletions src/pkg/hub/selfservice_v1_api.go
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,10 @@ package hub
// /api/hub/v1 is a versioned resource view of the self-service (byo-)
// registry that selfservice_api.go already serves under /api/hub/selfservice.
// It adds discovery (GET /api/hub/v1) and the registry as resources: create,
// list, get, delete and key rotation, with an ETag on every record and an
// optional If-Match on every write. In-place edits (PATCH) are a later PR of
// the same rollout. The legacy routes keep their bodies and status codes.
// list, get, update (PATCH, selfservice_v1_patch.go), delete and key rotation,
// with an ETag on every record and an If-Match on every write (required on
// PATCH, optional on delete and rotate). The legacy routes keep their bodies
// and status codes.
//
// Invariants (in addition to selfservice_api.go's):
// - Nothing here writes to GitHub. The only GitHub call is the read-only
Expand Down Expand Up @@ -56,13 +57,15 @@ var hubV1Operations = []hubV1Operation{
{Name: "create", Method: http.MethodPost, Path: hubV1BasePath + "/registrations"},
{Name: "list", Method: http.MethodGet, Path: hubV1BasePath + "/registrations"},
{Name: "get", Method: http.MethodGet, Path: hubV1BasePath + "/registrations/{id}"},
{Name: "update", Method: http.MethodPatch, Path: hubV1BasePath + "/registrations/{id}", IfMatch: "required"},
{Name: "rotate_key", Method: http.MethodPost, Path: hubV1BasePath + "/registrations/{id}/keys", IfMatch: "optional"},
{Name: "delete", Method: http.MethodDelete, Path: hubV1BasePath + "/registrations/{id}", IfMatch: "optional"},
}

// hubV1PatchFields are the registration fields an update may change. Empty
// until the update operation exists.
var hubV1PatchFields = []string{}
// hubV1PatchFields are the registration fields an update may change. org is
// not one of them: changing it would mean re-proving every repo, so a client
// deletes and registers again (#18642).
var hubV1PatchFields = []string{"repos", "dashboard_url"}

// registerHubV1Routes wires the v1 routes onto the hub mux. Discovery is
// public (a spoke reads it before it has a session); every other route is
Expand All @@ -73,6 +76,7 @@ func (s *HubServer) registerHubV1Routes() {
s.mux.HandleFunc("POST "+hubV1BasePath+"/registrations", s.requireAuth(s.handleHubV1Create))
s.mux.HandleFunc("GET "+hubV1BasePath+"/registrations", s.requireAuth(s.handleHubV1List))
s.mux.HandleFunc("GET "+hubV1BasePath+"/registrations/{id}", s.requireAuth(s.handleHubV1Get))
s.mux.HandleFunc("PATCH "+hubV1BasePath+"/registrations/{id}", s.requireAuth(s.handleHubV1Patch))
s.mux.HandleFunc("DELETE "+hubV1BasePath+"/registrations/{id}", s.requireAuth(s.handleHubV1Delete))
s.mux.HandleFunc("POST "+hubV1BasePath+"/registrations/{id}/keys", s.requireAuth(s.handleHubV1RotateKey))
}
Expand Down Expand Up @@ -111,7 +115,7 @@ func (s *HubServer) hubV1View(h SelfServiceHive) hubV1RegistrationView {
}
}

// writeHubV1RepoCapError is the v1 over-cap answer for create (and, later, PATCH): 413
// writeHubV1RepoCapError is the v1 over-cap answer for create and PATCH: 413
// naming the limit, so a client can read it without parsing the message.
func writeHubV1RepoCapError(w http.ResponseWriter, err error, maxRepos int) {
writeHubV1JSON(w, http.StatusRequestEntityTooLarge, "", hubV1RepoCapBody(err, maxRepos))
Expand Down
10 changes: 8 additions & 2 deletions src/pkg/hub/selfservice_v1_api_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,7 @@ func TestHubV1Discovery(t *testing.T) {
"create": "POST /api/hub/v1/registrations",
"list": "GET /api/hub/v1/registrations",
"get": "GET /api/hub/v1/registrations/{id}",
"update": "PATCH /api/hub/v1/registrations/{id}",
"rotate_key": "POST /api/hub/v1/registrations/{id}/keys",
"delete": "DELETE /api/hub/v1/registrations/{id}",
}
Expand All @@ -156,8 +157,11 @@ func TestHubV1Discovery(t *testing.T) {
t.Errorf("operation %s = %+v, want %s", name, op, route)
}
}
if len(d.PatchFields) != 0 {
t.Fatalf("patch_fields = %v, want none until update exists", d.PatchFields)
if !reflect.DeepEqual(d.PatchFields, []string{"repos", "dashboard_url"}) {
t.Fatalf("patch_fields = %v, want repos and dashboard_url (org is not editable)", d.PatchFields)
}
if got["update"].IfMatch != "required" {
t.Fatalf("update if_match = %q, want required", got["update"].IfMatch)
}
if got := rec.Header().Get("Content-Type"); got != "application/json" {
t.Fatalf("Content-Type = %q", got)
Expand Down Expand Up @@ -510,6 +514,7 @@ func TestHubV1FlagOffHidesEveryRoute(t *testing.T) {
{"create", http.MethodPost, path, env.s.handleHubV1Create},
{"list", http.MethodGet, path, env.s.handleHubV1List},
{"get", http.MethodGet, path + "/" + id, env.s.handleHubV1Get},
{"update", http.MethodPatch, path + "/" + id, env.s.handleHubV1Patch},
{"rotate", http.MethodPost, path + "/" + id + "/keys", env.s.handleHubV1RotateKey},
{"delete", http.MethodDelete, path + "/" + id, env.s.handleHubV1Delete},
}
Expand Down Expand Up @@ -539,6 +544,7 @@ func TestHubV1RoutesRequireSession(t *testing.T) {
{"create", http.MethodPost, path, env.s.handleHubV1Create},
{"list", http.MethodGet, path, env.s.handleHubV1List},
{"get", http.MethodGet, path + "/" + id, env.s.handleHubV1Get},
{"update", http.MethodPatch, path + "/" + id, env.s.handleHubV1Patch},
{"rotate", http.MethodPost, path + "/" + id + "/keys", env.s.handleHubV1RotateKey},
{"delete", http.MethodDelete, path + "/" + id, env.s.handleHubV1Delete},
}
Expand Down
Loading
Loading