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-18642-hub-v1-registrations.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Added the hub registration protocol v1 registration resources (rollout step 1 of [#18642](https://github.com/hivecommons/hive/issues/18642)): `POST/GET /api/hub/v1/registrations`, `GET/DELETE /api/hub/v1/registrations/{id}` and `POST .../{id}/keys` over the existing self-service registry, with a strong `ETag` on every record (from a revision counter that heartbeats do not bump), optional `If-Match` on delete and rotate, per-repo ownership proof times (`repo_proofs`), a `413` with `limit: max_repos` for a repo list over the cap and `201` on rotate. The legacy `/api/hub/selfservice/*` responses are unchanged and everything stays behind `HIVE_HUB_SELFSERVICE_REGISTRATION`.
5 changes: 5 additions & 0 deletions src/docs/api-reference/hub-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,11 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f
| `GET` | `/api/hub/selfservice/hives` | Hub auth | The caller's own self-service (`byo-`) hives: `{hives[]}` of `{id, owner, org, repos, dashboard_url, created_at, ownership_checked_at, last_accepted_heartbeat_at, online}`; never a key or a hash. `404` while `HIVE_HUB_SELFSERVICE_REGISTRATION` is off | `pkg/hub/server.go:1787` |
| `POST` | `/api/hub/selfservice/hives` | Hub auth | Register a self-hosted hive: body `{name, org, repos[], dashboard_url}`; the ID is `byo-<github login>--<name>` (the double hyphen keeps IDs unambiguous, since logins contain hyphens but never `--`). Proves `permissions.admin` on every `owner/name` repo with the caller's own stored GitHub token (`403` naming the refused repo, nothing stored); `400` invalid or reserved name, a login that contains `--` or starts or ends with `-`, bare-org or `.`/`..` repo, or non-`https`/private `dashboard_url`; `409` ID already registered; `429` over `HIVE_HUB_SELFSERVICE_MAX_PER_USER` (enforced again under the store lock, so concurrent registrations cannot exceed it). `201 {hive, key, hub_url, snippets{docker_compose, podman, kubernetes}}`: the raw key appears here once and only its hash is stored. `404` while the flag is off | `pkg/hub/server.go:1788` |
| `GET` | `/api/hub/v1` | Public | Hub registration protocol v1 discovery ([#18642](https://github.com/hivecommons/hive/issues/18642)): `{protocol, version, base_path, operations[], patch_fields[], limits{max_repos, max_per_user, expiry, key_rotation_overlap}, proof_methods[]}`. Readable without signing in so a client learns the limits before it hits a `4xx`. `proof_methods` is `["hub-session-token"]`: ownership is proven with the GitHub token stored at hub sign-in. `max_repos` is `HIVE_HUB_SELFSERVICE_MAX_REPOS`. `404` while `HIVE_HUB_SELFSERVICE_REGISTRATION` is off | `pkg/hub/selfservice_v1_api.go` |
| `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` |
| `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:1789` |
| `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:1790` |
| `POST` | `/api/contribute/register` | Hub handler-specific | Contribute Proxy | `pkg/hub/server.go:1794` |
Expand Down
2 changes: 1 addition & 1 deletion src/docs/env-vars.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,7 @@ behavior. [Maintenance limitations](#keeping-this-reference-current) still apply
| `HIVE_HUB_MAIL_CHUNK_BYTES` | No | `786432` | Piece size when the hub relays a large mail-in delivery to the spoke (768 KiB, under the 1 MiB ingress default); clamped to 64 KiB to 8 MiB. |
| `HIVE_HUB_MAIL_SPOOL_DIR` | No | system temp directory | Where the hub keeps a delivery on disk while it relays it. |
| `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`. Read per request. Only meaningful while `HIVE_HUB_SELFSERVICE_REGISTRATION` is on. |
| `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_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_AGENT_RESTART_PROBLEM_THRESHOLD` | No | `5` | Hosted hub threshold for surfacing agent restart storms on `/fleet`. When an agent reports at least this many restarts in the last 24 hours (or since the hub-side reset marker), the hive gets a restart problem chip and drift signal. |
Expand Down
2 changes: 1 addition & 1 deletion src/docs/hub-deployment.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ The fence above is always on. The registration flow that fills the `byo-` namesp
|---|---|---|
| `HIVE_HUB_SELFSERVICE_REGISTRATION` | off | Turns on `/api/hub/selfservice/*` and the **Register your own hive** form on the dashboard. Accepts `1/true/yes/on`. Read per request, so no restart is needed. While off, every route except `GET /api/hub/selfservice/status` answers `404`, and the dashboard button sends users to the self-hosting guide instead of the form. |
| `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`. The registration route answers `400` over the cap. Advertised to clients by `GET /api/hub/v1` as `limits.max_repos`. Read per request. |
| `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_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. |

Expand Down
129 changes: 79 additions & 50 deletions src/pkg/hub/selfservice_api.go
Original file line number Diff line number Diff line change
Expand Up @@ -441,76 +441,140 @@ func (s *HubServer) handleSelfServiceRegister(w http.ResponseWriter, r *http.Req
if !s.requireSelfServiceEnabled(w) {
return
}
stored, rawKey, ok := s.selfServiceRegisterCore(w, r, false)
if !ok {
return
}
hubURL := hubPublicURL()
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusCreated)
_ = json.NewEncoder(w).Encode(map[string]any{
"hive": selfServiceView(stored, false),
"key": rawKey,
"hub_url": hubURL,
"snippets": selfServiceSnippets(hubURL, stored.ID, rawKey),
})
}

// selfServiceRegisterCore validates a registration body, runs the ownership
// proof and stores the record. It writes every refusal itself and returns
// ok=false; on success it writes nothing, so the v6 route and the v1 resource
// route (selfservice_v1_api.go) can each shape their own 201 body. v1 selects
// the v1 over-cap answer (413 naming the limit); the v6 route keeps its 400.
func (s *HubServer) selfServiceRegisterCore(w http.ResponseWriter, r *http.Request, v1 bool) (SelfServiceHive, string, bool) {
login := s.getAuthUser(r)
user := loadSaaSUser(login)
if user == nil {
writeJSONError(w, http.StatusUnauthorized, "not authenticated")
return
return SelfServiceHive{}, "", false
}
var body selfServiceRegisterRequest
if err := json.NewDecoder(io.LimitReader(r.Body, selfServiceRequestBodyLimit())).Decode(&body); err != nil {
writeJSONError(w, http.StatusBadRequest, "invalid JSON body")
return
return SelfServiceHive{}, "", false
}

githubLogin := topRepoProfileLogin(user)
if githubLogin == "" {
s.auditSelfServiceRefused(login, "", selfServiceRefusedNoGitHubLogin)
writeJSONError(w, http.StatusBadRequest, "a GitHub identity is required to register a self-hosted hive")
return
return SelfServiceHive{}, "", false
}
id, reason, err := selfServiceBuildID(githubLogin, body.Name)
if err != nil {
s.auditSelfServiceRefused(login, "", reason)
writeJSONError(w, http.StatusBadRequest, err.Error())
return
return SelfServiceHive{}, "", false
}
if s.selfServiceRegistryHas(id) {
s.auditSelfServiceRefused(login, id, selfServiceRefusedDuplicateID)
writeJSONError(w, http.StatusConflict, "a hive with this ID is already registered")
return
return SelfServiceHive{}, "", false
}
if _, exists := s.selfService.get(id); exists {
s.auditSelfServiceRefused(login, id, selfServiceRefusedDuplicateID)
writeJSONError(w, http.StatusConflict, "a hive with this ID is already registered")
return
return SelfServiceHive{}, "", false
}
org := strings.TrimSpace(body.Org)
if org != "" && !isValidName(org) {
s.auditSelfServiceRefused(login, id, selfServiceRefusedInvalidName)
writeJSONError(w, http.StatusBadRequest, "org may contain only letters, digits, '.', '_' and '-'")
return
return SelfServiceHive{}, "", false
}
repos, err := selfServiceValidateRepos(body.Repos)
if err != nil {
s.auditSelfServiceRefused(login, id, selfServiceRefusedInvalidRepos)
if maxRepos := selfServiceMaxRepos(); v1 && len(body.Repos) > maxRepos {
writeHubV1RepoCapError(w, err, maxRepos)
return SelfServiceHive{}, "", false
}
writeJSONError(w, http.StatusBadRequest, err.Error())
return
return SelfServiceHive{}, "", false
}
dashboardURL, err := selfServiceValidateDashboardURL(r.Context(), body.DashboardURL)
if err != nil {
s.auditSelfServiceRefused(login, id, selfServiceRefusedInvalidURL)
writeJSONError(w, http.StatusBadRequest, err.Error())
return
return SelfServiceHive{}, "", false
}
if maxPerUser := selfServiceMaxPerUser(); s.selfServiceCount(login) >= maxPerUser {
s.auditSelfServiceRefused(login, id, selfServiceRefusedCap, "max_per_user", maxPerUser)
writeJSONError(w, http.StatusTooManyRequests, fmt.Sprintf("you already have %d self-hosted hives registered; remove one first", maxPerUser))
return
return SelfServiceHive{}, "", false
}

if !s.selfServiceProveOwnership(w, r, login, id, user, repos) {
return SelfServiceHive{}, "", false
}

now := time.Now().UTC()
// The cap is enforced again inside the store, under the lock that inserts
// the record: the count above ran before up to selfServiceMaxRepos() GitHub
// calls, so concurrent POSTs from one user could all have passed it.
maxPerUser := selfServiceMaxPerUser()
rawKey, err := s.selfService.registerCapped(SelfServiceHive{
ID: id, Owner: login, Org: org, Repos: repos, DashboardURL: dashboardURL, OwnershipCheckedAt: now,
RepoProofs: selfServiceProofTimes(nil, repos, time.Time{}, now, repos),
}, maxPerUser)
if err != nil {
if errors.Is(err, errSelfServiceExists) {
s.auditSelfServiceRefused(login, id, selfServiceRefusedDuplicateID)
writeJSONError(w, http.StatusConflict, "a hive with this ID is already registered")
return SelfServiceHive{}, "", false
}
if errors.Is(err, errSelfServiceCapReached) {
s.auditSelfServiceRefused(login, id, selfServiceRefusedCap, "max_per_user", maxPerUser)
writeJSONError(w, http.StatusTooManyRequests, fmt.Sprintf("you already have %d self-hosted hives registered; remove one first", maxPerUser))
return SelfServiceHive{}, "", false
}
s.logger.Error("self-service registration: store write failed", "user", login, "hive", id, "error", err)
writeJSONError(w, http.StatusInternalServerError, "could not persist the registration")
return SelfServiceHive{}, "", false
}
s.logger.Info("audit: selfservice_hive_registered", "user", login, "hive", id, "repos", len(repos), "org", org)

stored, _ := s.selfService.get(id)
return stored, rawKey, true
}

// selfServiceProveOwnership checks that user administers every repo in repos,
// with the user's OWN stored GitHub token. It is a read (GET /repos/{o}/{r})
// and nothing else. It writes the refusal and returns false when any repo
// fails; true means every repo passed.
func (s *HubServer) selfServiceProveOwnership(w http.ResponseWriter, r *http.Request, login, id string, user *SaaSUser, repos []string) bool {
// Ownership proof with the user's OWN token, never the hub's App token: the
// question is what this person administers, not what the hub can see.
if strings.TrimSpace(user.EncryptedToken) == "" {
s.auditSelfServiceRefused(login, id, selfServiceRefusedNoToken)
writeJSONError(w, http.StatusForbidden, "no GitHub token is stored for your account; sign out and back in with GitHub, then retry")
return
return false
}
token, err := decryptToken(user.EncryptedToken)
if err != nil {
s.logger.Warn("self-service registration: stored token could not be decrypted", "user", login, "error", err)
writeJSONError(w, http.StatusInternalServerError, "stored GitHub token could not be read")
return
return false
}
checker := s.ownershipChecker()
for _, repo := range repos {
Expand All @@ -520,7 +584,7 @@ func (s *HubServer) handleSelfServiceRegister(w http.ResponseWriter, r *http.Req
s.auditSelfServiceRefused(login, id, selfServiceRefusedOwnershipError, "repo", repo)
s.logger.Warn("self-service registration: ownership check failed", "user", login, "hive", id, "repo", repo, "error", err)
writeJSONError(w, http.StatusBadGateway, fmt.Sprintf("could not verify your permission on %s; try again", repo))
return
return false
}
if !admin {
s.auditSelfServiceRefused(login, id, selfServiceRefusedNotAdmin, "repo", repo)
Expand All @@ -530,45 +594,10 @@ func (s *HubServer) handleSelfServiceRegister(w http.ResponseWriter, r *http.Req
"error": fmt.Sprintf("your GitHub account is not an admin of %s", repo),
"repo": repo,
})
return
return false
}
}

now := time.Now().UTC()
// The cap is enforced again inside the store, under the lock that inserts
// the record: the count above ran before up to selfServiceMaxRepos() GitHub
// calls, so concurrent POSTs from one user could all have passed it.
maxPerUser := selfServiceMaxPerUser()
rawKey, err := s.selfService.registerCapped(SelfServiceHive{
ID: id, Owner: login, Org: org, Repos: repos, DashboardURL: dashboardURL, OwnershipCheckedAt: now,
}, maxPerUser)
if err != nil {
if errors.Is(err, errSelfServiceExists) {
s.auditSelfServiceRefused(login, id, selfServiceRefusedDuplicateID)
writeJSONError(w, http.StatusConflict, "a hive with this ID is already registered")
return
}
if errors.Is(err, errSelfServiceCapReached) {
s.auditSelfServiceRefused(login, id, selfServiceRefusedCap, "max_per_user", maxPerUser)
writeJSONError(w, http.StatusTooManyRequests, fmt.Sprintf("you already have %d self-hosted hives registered; remove one first", maxPerUser))
return
}
s.logger.Error("self-service registration: store write failed", "user", login, "hive", id, "error", err)
writeJSONError(w, http.StatusInternalServerError, "could not persist the registration")
return
}
s.logger.Info("audit: selfservice_hive_registered", "user", login, "hive", id, "repos", len(repos), "org", org)

stored, _ := s.selfService.get(id)
hubURL := hubPublicURL()
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusCreated)
_ = json.NewEncoder(w).Encode(map[string]any{
"hive": selfServiceView(stored, false),
"key": rawKey,
"hub_url": hubURL,
"snippets": selfServiceSnippets(hubURL, id, rawKey),
})
return true
}

// selfServiceOwnedHive loads the hive named in the path and checks login owns
Expand Down
Loading
Loading