From 9db82d5f59ad24e10bea3bfe37481ba1b0612ebc Mon Sep 17 00:00:00 2001 From: Andrew Anderson Date: Tue, 17 Nov 2026 23:31:15 -0500 Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20hub:=20v1=20registration=20discover?= =?UTF-8?q?y=20and=20configurable=20repo=20cap?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rollout step 1, part A of the hub registration protocol (hivecommons/hive#18642), ported from the tuna-os/hive#189 prototype: - GET /api/hub/v1 discovery: protocol version, operations, limits (max_repos, max_per_user, expiry, key_rotation_overlap) and the proof method the hub actually offers, hub-session-token. Readable without signing in. - HIVE_HUB_SELFSERVICE_MAX_REPOS makes the per-registration repo cap configurable (default 20, clamped to 500). The legacy create keeps its 400 body; the request body limit scales with the cap. Everything is behind HIVE_HUB_SELFSERVICE_REGISTRATION. No GitHub writes; heartbeat_signing.go and the credential fence are untouched. Co-authored-by: James Reilly <5840441+hanthor@users.noreply.github.com> Signed-off-by: James Reilly Signed-off-by: Andrew Anderson --- .../added-18642-hub-v1-discovery-repo-cap.md | 1 + src/docs/api-reference/hub-server.md | 37 +-- src/docs/env-vars.md | 1 + src/docs/hub-deployment.md | 1 + src/pkg/hub/selfservice_api.go | 42 +++- src/pkg/hub/selfservice_api_test.go | 5 + src/pkg/hub/selfservice_v1_api.go | 92 ++++++++ src/pkg/hub/selfservice_v1_api_test.go | 213 ++++++++++++++++++ src/pkg/hub/server.go | 3 + 9 files changed, 368 insertions(+), 27 deletions(-) create mode 100644 changelog.d/added-18642-hub-v1-discovery-repo-cap.md create mode 100644 src/pkg/hub/selfservice_v1_api.go create mode 100644 src/pkg/hub/selfservice_v1_api_test.go diff --git a/changelog.d/added-18642-hub-v1-discovery-repo-cap.md b/changelog.d/added-18642-hub-v1-discovery-repo-cap.md new file mode 100644 index 0000000000..22738f8ab8 --- /dev/null +++ b/changelog.d/added-18642-hub-v1-discovery-repo-cap.md @@ -0,0 +1 @@ +- Added `GET /api/hub/v1`, the discovery document of the hub registration protocol v1 (rollout step 1 of [#18642](https://github.com/hivecommons/hive/issues/18642)): it lists the operations, limits (`max_repos`, `max_per_user`, `expiry`, `key_rotation_overlap`) and the ownership proof method (`hub-session-token`), and answers `404` while `HIVE_HUB_SELFSERVICE_REGISTRATION` is off. The per-registration repo cap is now configurable with `HIVE_HUB_SELFSERVICE_MAX_REPOS` (default `20`, clamped to `500`); the legacy `/api/hub/selfservice/*` responses are unchanged. diff --git a/src/docs/api-reference/hub-server.md b/src/docs/api-reference/hub-server.md index 32d0848409..c8a838b736 100644 --- a/src/docs/api-reference/hub-server.md +++ b/src/docs/api-reference/hub-server.md @@ -35,8 +35,8 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `POST` | `/api/benchmarks/ingest` | Per-hive heartbeat bearer | Spoke push target for anonymized [benchmark records](../benchmarks.md): body `{hive_id, records[]}`; the hub recomputes the hive hash from the authenticated id, rejects records whose `source.hive_id` differs (`401` bad bearer, `403` unregistered hive, `400` malformed), merges accepted records by id into `/data/benchmarks//.json` and returns `202 {accepted, rejected, files}` | `pkg/hub/benchmarks.go` | | `GET` | `/api/hub/benchmarks` | Public | Benchmark publisher status: `last_ingest_at`, `last_publish_at`, `last_publish_files`, `last_error`, `pending_files`, `hive_count`, `record_count` and per-hive-hash `hives{}` counts; the hub commits pending month files hourly to `hivecommons/benchmarks` (`HIVE_BENCHMARKS_REPO`) via its App identity | `pkg/hub/benchmarks.go` | | `GET` | `/api/reach` | Hub admin | PR Reach Report (?pr=NNN or ?recent=K) | `pkg/hub/saas.go:522` | -| `GET` | `/fleet` | Hub handler-specific | My-Hives Fleet Page (static; data via `/api/saas/my-hives`) | `pkg/hub/server.go:1824` | -| `GET` | `/my-hives` | Hub handler-specific | 301 redirect to `/fleet` (query preserved) | `pkg/hub/server.go:1825` | +| `GET` | `/fleet` | Hub handler-specific | My-Hives Fleet Page (static; data via `/api/saas/my-hives`) | `pkg/hub/server.go:1827` | +| `GET` | `/my-hives` | Hub handler-specific | 301 redirect to `/fleet` (query preserved) | `pkg/hub/server.go:1828` | | `GET` | `/activity` | Signed-in user | Fleet activity page ([#16063](https://github.com/hivecommons/hive/issues/16063)): read-only, data-free shell that polls `/api/hub/activity` every 15 s with `If-None-Match`. No session → `307` to `/login`; blocked user → `403`. Own Content-Security-Policy (scripts and styles from `'self'` only, `script-src-attr`/`style-src-attr` `'none'`), `Cache-Control: no-cache` + content `ETag`. See [Hub Fleet activity page](../hub-fleet-activity.md) | `pkg/hub/activity_page.go` | | `GET` | `/activity/public` | Public | Public-safe Fleet activity page ([#15966](https://github.com/hivecommons/hive/issues/15966)): the same data-free shell as `/activity`, served without a session; on this path the page polls `/api/hub/activity/public` with `credentials: 'omit'`. Source of the `twitch.tv/hivecommonsfleet` broadcast. Same CSP and cache headers as `/activity`. See [Hub Fleet activity page](../hub-fleet-activity.md#public-safe-view) | `pkg/hub/activity_public.go` | | `GET` | `/activity/assets/{name}` | Public | The shared tracker assets the Fleet activity page loads, byte-identical: the row asset (`pkg/webassets/trackerrow`, [#16062](https://github.com/hivecommons/hive/issues/16062)) and the `am.*` URL-view and display-playlist helpers (`pkg/webassets/trackerview`, [#16064](https://github.com/hivecommons/hive/issues/16064)); only names in `trackerrow.Files` or `trackerview.Files`, else `404`. `Cache-Control: no-cache` + content `ETag` | `pkg/hub/activity_page.go` | @@ -58,26 +58,27 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `GET` | `/api/hub/selfservice/status` | Hub auth | Self-service registration status: `{enabled, max_per_user, count, expiry}`; always answers so the dashboard can decide whether **Register your own hive** opens the form or the self-hosting guide ([#18060](https://github.com/hivecommons/hive/issues/18060)) | `pkg/hub/server.go:1786` | | `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---` (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/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:1791` | -| `GET` | `/api/contribute/status` | Hub handler-specific | Contribute Status | `pkg/hub/server.go:1792` | -| `GET` | `/api/contribute/ws` | Hub handler-specific | Contribute WSProxy | `pkg/hub/server.go:1793` | -| `POST` | `/api/github/webhook` | Hub handler-specific | GitHub Webhook | `pkg/hub/server.go:1794` | +| `POST` | `/api/contribute/register` | Hub handler-specific | Contribute Proxy | `pkg/hub/server.go:1794` | +| `GET` | `/api/contribute/status` | Hub handler-specific | Contribute Status | `pkg/hub/server.go:1795` | +| `GET` | `/api/contribute/ws` | Hub handler-specific | Contribute WSProxy | `pkg/hub/server.go:1796` | +| `POST` | `/api/github/webhook` | Hub handler-specific | GitHub Webhook | `pkg/hub/server.go:1797` | | `GET` | `/api/mail/hosts` | hive-mx bearer (`HIVE_HUB_MAIL_TOKEN`) | Hosts the mail receiver accepts `hive@` for ([#18395](https://github.com/hivecommons/hive/issues/18395)): `{hosts[]}`, sorted, lower-case: every hosted hive's subdomain host, vanity URL host and reported dashboard URL host. A host claimed by two hives is left out. `401` bad token, `404` while `HIVE_HUB_MAIL_TOKEN` is unset. `Cache-Control: no-store` | `pkg/hub/mail_relay.go` | | `POST` | `/api/mail/inbound` | hive-mx bearer (`HIVE_HUB_MAIL_TOKEN`) | One parsed mail delivery from hive-mx (`pkg/mailin/wire.Delivery`): JSON, or `multipart/form-data` for a large files delivery, routed by the `X-Hive-Mail-Delivery`, `X-Hive-Mail-Kind` and `X-Hive-Mail-Recipient` headers (at most 48 MiB, `HIVE_HUB_MAIL_MAX_BODY_BYTES`, this route only; without the headers, JSON of at most 8 MiB). The body is spooled to disk, never held whole in memory. The hub matches the recipient host to a hosted hive, signs the body byte for byte with that hive's relay key (`X-Hive-Relay-Timestamp`, `X-Hive-Relay-Signature-256` bound to `X-Hive-Relay-Delivery`) and forwards it to the spoke's `/api/meetings/invites`, `/api/inbox/email`, `/api/meetings/calendar-emails/proof` or `/api/inbox/email/report` (a refusal report, [#18699](https://github.com/hivecommons/hive/issues/18699)) by `kind`, behind the webhook relay's private-address guard and without following redirects. A files delivery that is multipart or larger than one piece (`HIVE_HUB_MAIL_CHUNK_BYTES`, 768 KiB) goes to `/api/inbox/email/chunk` in signed pieces instead ([#18564](https://github.com/hivecommons/hive/issues/18564)). Stores nothing once relayed; logs the delivery id only. `202` delivered; `400` invalid delivery; `404` no such hive; `413` too large; `422` the spoke refused it (permanent); `502`/`503` hive not reachable yet or unavailable (hive-mx asks the sender to retry) | `pkg/hub/mail_relay.go` | -| `GET` | `/gh-setup` | Hub handler-specific | GitHub App Setup Router | `pkg/hub/server.go:1797` | -| `GET` | `/learn` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1798` | -| `GET` | `/get-started` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1799` | -| `GET` | `/api/docs` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1802` | -| `GET` | `/api/reading-list` | Hub handler-specific | Reading List | `pkg/hub/server.go:1805` | -| `GET` | `/reading` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1806` | -| `GET` | `/cncf-reference-architecture` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1813` | -| `GET` | `/cncf-reference-architecture/console` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1814` | -| `GET` | `/cncf-reference-architecture/bluefin` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1815` | -| `GET` | `/{$}` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1832` | -| `GET` | `/og-card.png` | Hub handler-specific | OGCard | `pkg/hub/server.go:1837` | -| `GET` | `/` | Public | Static asset fallback (`http.FileServerFS` over the embedded `static/` tree) for any path no other route claims | `pkg/hub/server.go:1839` | +| `GET` | `/gh-setup` | Hub handler-specific | GitHub App Setup Router | `pkg/hub/server.go:1800` | +| `GET` | `/learn` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1801` | +| `GET` | `/get-started` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1802` | +| `GET` | `/api/docs` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1805` | +| `GET` | `/api/reading-list` | Hub handler-specific | Reading List | `pkg/hub/server.go:1808` | +| `GET` | `/reading` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1809` | +| `GET` | `/cncf-reference-architecture` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1816` | +| `GET` | `/cncf-reference-architecture/console` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1817` | +| `GET` | `/cncf-reference-architecture/bluefin` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1818` | +| `GET` | `/{$}` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1835` | +| `GET` | `/og-card.png` | Hub handler-specific | OGCard | `pkg/hub/server.go:1840` | +| `GET` | `/` | Public | Static asset fallback (`http.FileServerFS` over the embedded `static/` tree) for any path no other route claims | `pkg/hub/server.go:1842` | | `GET` | `/api/marketplace/workflows` | Public | Workflow-model marketplace index ([#17620](https://github.com/hivecommons/hive/issues/17620) phase 7): `{generatedAt, entries:[{name, version, hash, tier, description, source, states, columns, publishedAt, publishedBy, sourceSHA?, newerIngestAvailable, adoption:{}, ratings:{}, benchmarks:{}}]}`. Strong `ETag` (sha256 of the body) + `Cache-Control: no-cache`; `If-None-Match` → `304`. Tiers: `built-in`, `curated`, `ingested-unreviewed`, `local-published`. `404` when `HIVE_HUB_MARKETPLACE_DISABLED` is set | `pkg/hub/marketplace.go:36` | | `GET` | `/api/marketplace/workflows/{name}/{version}/bundle` | Public | One immutable signed bundle (`{apiVersion, model, profile, hash, createdAt, createdBy, tier}`), `Cache-Control: immutable`; `404` unknown, `400` malformed key | `pkg/hub/marketplace.go:37` | | `POST` | `/api/marketplace/workflows` | Spoke heartbeat bearer + `X-Hive-ID`, or Hub admin session | Publish a bundle. Body = bundle (≤ 4 MiB); the hub re-verifies the hash and recompiles the model before storing. Publisher may assert tier `local`/`local-published` (normalised to `local-published`) or `ingested-unreviewed`; `curated`/`built-in` require a hub admin session (`403` otherwise). `201 {published, created:true, entry}`; identical republish `200 created:false`; different content under an existing `name@version` `409`; verification failure `422`; unknown hive `403`; no hub secret `503` | `pkg/hub/marketplace.go:38` | diff --git a/src/docs/env-vars.md b/src/docs/env-vars.md index bee5cfa131..531b7698a5 100644 --- a/src/docs/env-vars.md +++ b/src/docs/env-vars.md @@ -98,6 +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_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. | diff --git a/src/docs/hub-deployment.md b/src/docs/hub-deployment.md index ed925c4a83..e6ae911380 100644 --- a/src/docs/hub-deployment.md +++ b/src/docs/hub-deployment.md @@ -102,6 +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_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. | diff --git a/src/pkg/hub/selfservice_api.go b/src/pkg/hub/selfservice_api.go index 2cd965b754..460c6d0bd0 100644 --- a/src/pkg/hub/selfservice_api.go +++ b/src/pkg/hub/selfservice_api.go @@ -50,12 +50,24 @@ const ( selfServiceExpiryEnv = "HIVE_HUB_SELFSERVICE_EXPIRY" selfServiceExpiryDefault = 24 * time.Hour - // selfServiceMaxRequestBody bounds a registration body; the largest legal - // body is selfServiceMaxRepos repo refs plus a URL, far under this. + // selfServiceMaxRequestBody is the floor for a registration body; the + // largest legal body at the default repo cap is far under this. + // selfServiceRequestBodyLimit raises it when the cap is configured higher. selfServiceMaxRequestBody = 64 << 10 - // selfServiceMaxRepos bounds how many repos one registration may prove - // ownership of, and so how many GitHub calls one request can trigger. - selfServiceMaxRepos = 20 + // selfServiceRequestBodyPerRepo is the body budget allowed per repo ref + // above the floor (an owner/name ref is at most ~140 bytes, plus JSON). + selfServiceRequestBodyPerRepo = 256 + // selfServiceMaxReposEnv sets how many repos one registration may list + // (#18642). Each repo is one GitHub ownership call, so the value is also a + // bound on the calls one request can trigger. + selfServiceMaxReposEnv = "HIVE_HUB_SELFSERVICE_MAX_REPOS" + // selfServiceMaxReposDefault is the cap when the env is unset; it is the + // previous fixed cap, so behaviour does not change until an operator + // raises it. + selfServiceMaxReposDefault = 20 + // selfServiceMaxReposCeiling clamps a configured cap so a typo cannot turn + // one request into thousands of GitHub calls. + selfServiceMaxReposCeiling = 500 // selfServiceGitHubAPIBase is the production API the ownership proof // calls; tests point selfServiceOwnershipChecker.apiBase at a stub. selfServiceGitHubAPIBase = "https://api.github.com" @@ -116,6 +128,18 @@ func selfServiceExpiry() time.Duration { return durationEnv(selfServiceExpiryEnv, selfServiceExpiryDefault) } +// selfServiceMaxRepos is how many repos one registration may list. Read per +// request like the other self-service limits; advertised by GET /api/hub/v1. +func selfServiceMaxRepos() int { + return min(positiveIntEnv(selfServiceMaxReposEnv, selfServiceMaxReposDefault), selfServiceMaxReposCeiling) +} + +// selfServiceRequestBodyLimit bounds a registration body so the largest legal +// body at the configured repo cap still fits. +func selfServiceRequestBodyLimit() int64 { + return max(int64(selfServiceMaxRequestBody), int64(selfServiceMaxRepos())*selfServiceRequestBodyPerRepo+selfServiceMaxRequestBody) +} + // selfServiceOwnershipChecker asks GitHub whether a token's user administers // a repo. It is a struct rather than a function so the production instance can // own its SSRF-guarded client while a test substitutes an httptest server. @@ -335,8 +359,8 @@ func selfServiceValidateRepos(repos []string) ([]string, error) { if len(repos) == 0 { return nil, errors.New("at least one owner/name repo is required") } - if len(repos) > selfServiceMaxRepos { - return nil, fmt.Errorf("at most %d repos per registration", selfServiceMaxRepos) + if maxRepos := selfServiceMaxRepos(); len(repos) > maxRepos { + return nil, fmt.Errorf("at most %d repos per registration", maxRepos) } out := make([]string, 0, len(repos)) seen := make(map[string]struct{}, len(repos)) @@ -424,7 +448,7 @@ func (s *HubServer) handleSelfServiceRegister(w http.ResponseWriter, r *http.Req return } var body selfServiceRegisterRequest - if err := json.NewDecoder(io.LimitReader(r.Body, selfServiceMaxRequestBody)).Decode(&body); err != nil { + if err := json.NewDecoder(io.LimitReader(r.Body, selfServiceRequestBodyLimit())).Decode(&body); err != nil { writeJSONError(w, http.StatusBadRequest, "invalid JSON body") return } @@ -512,7 +536,7 @@ func (s *HubServer) handleSelfServiceRegister(w http.ResponseWriter, r *http.Req 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 + // 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{ diff --git a/src/pkg/hub/selfservice_api_test.go b/src/pkg/hub/selfservice_api_test.go index 1884909a41..0cd79a093b 100644 --- a/src/pkg/hub/selfservice_api_test.go +++ b/src/pkg/hub/selfservice_api_test.go @@ -87,6 +87,11 @@ func newSelfServiceTestEnv(t *testing.T) *selfServiceTestEnv { } repo := strings.TrimPrefix(r.URL.Path, "/repos/") admin, known := env.adminRepos[repo] + // alice/bulk-* are admin repos for the repo-cap tests, which need more + // of them than are worth listing. + if strings.HasPrefix(repo, "alice/bulk-") { + admin, known = true, true + } if !known { w.WriteHeader(http.StatusNotFound) return diff --git a/src/pkg/hub/selfservice_v1_api.go b/src/pkg/hub/selfservice_v1_api.go new file mode 100644 index 0000000000..1fb981cee8 --- /dev/null +++ b/src/pkg/hub/selfservice_v1_api.go @@ -0,0 +1,92 @@ +package hub + +// Hub registration protocol v1, rollout step 1 (hivecommons/hive#18642). +// +// /api/hub/v1 is a versioned view of the self-service (byo-) registry that +// selfservice_api.go already serves under /api/hub/selfservice. This file +// holds the discovery document; the resource routes land in later steps of the +// same rollout. The legacy routes keep their bodies and status codes. +// +// Invariants (in addition to selfservice_api.go's): +// - Everything here answers 404 while HIVE_HUB_SELFSERVICE_REGISTRATION is +// off, so a hub that does not offer self-service does not advertise the +// protocol. +// - Nothing here writes to GitHub or to the registry. +// - Discovery lists exactly the operations this hub implements; a client +// never reads an operation that would answer 404. + +import ( + "encoding/json" + "net/http" +) + +const ( + // hubV1BasePath is the root of the versioned registration API. + hubV1BasePath = "/api/hub/v1" + // hubV1Protocol names the protocol discovery describes. + hubV1Protocol = "hive-hub-registration" + // hubV1ProtocolVersion is the protocol version discovery advertises. + hubV1ProtocolVersion = "1" + // hubV1ProofHubSessionToken is the only ownership proof step 1 offers: the + // hub checks permissions.admin on each repo with the GitHub token stored at + // hub sign-in. The RFC's github-user-token (a per-request token with + // explicit scopes) is rollout step 2 and is not advertised until it exists. + // Methods are added later, never renamed. + hubV1ProofHubSessionToken = "hub-session-token" +) + +// hubV1Operation is one entry in the discovery operations list. +type hubV1Operation struct { + Name string `json:"name"` + Method string `json:"method"` + Path string `json:"path"` + // IfMatch is "required", "optional" or empty (not a write). + IfMatch string `json:"if_match,omitempty"` +} + +// hubV1Operations is what this hub implements. Discovery lists exactly this, +// and the route registration below is checked against it by a test. +var hubV1Operations = []hubV1Operation{ + {Name: "discovery", Method: http.MethodGet, Path: hubV1BasePath}, +} + +// hubV1PatchFields are the registration fields an update may change. Empty +// until the update operation exists. +var hubV1PatchFields = []string{} + +// registerHubV1Routes wires the v1 routes onto the hub mux. Discovery is +// public (a spoke reads it before it has a session) and answers 404 while +// HIVE_HUB_SELFSERVICE_REGISTRATION is off. +func (s *HubServer) registerHubV1Routes() { + s.mux.HandleFunc("GET "+hubV1BasePath, s.handleHubV1Discovery) +} + +func writeHubV1JSON(w http.ResponseWriter, code int, etag string, body any) { + w.Header().Set("Content-Type", "application/json") + if etag != "" { + w.Header().Set("ETag", etag) + } + w.WriteHeader(code) + _ = json.NewEncoder(w).Encode(body) +} + +// handleHubV1Discovery is GET /api/hub/v1. +func (s *HubServer) handleHubV1Discovery(w http.ResponseWriter, r *http.Request) { + if !s.requireSelfServiceEnabled(w) { + return + } + writeHubV1JSON(w, http.StatusOK, "", map[string]any{ + "protocol": hubV1Protocol, + "version": hubV1ProtocolVersion, + "base_path": hubV1BasePath, + "operations": hubV1Operations, + "patch_fields": hubV1PatchFields, + "limits": map[string]any{ + "max_repos": selfServiceMaxRepos(), + "max_per_user": selfServiceMaxPerUser(), + "expiry": selfServiceExpiry().String(), + "key_rotation_overlap": selfServiceKeyRotationOverlap.String(), + }, + "proof_methods": []string{hubV1ProofHubSessionToken}, + }) +} diff --git a/src/pkg/hub/selfservice_v1_api_test.go b/src/pkg/hub/selfservice_v1_api_test.go new file mode 100644 index 0000000000..98e82ae7bc --- /dev/null +++ b/src/pkg/hub/selfservice_v1_api_test.go @@ -0,0 +1,213 @@ +package hub + +import ( + "encoding/json" + "fmt" + "log/slog" + "net/http" + "net/http/httptest" + "reflect" + "strings" + "testing" +) + +// Tests for the hub registration protocol v1 discovery and the configurable +// repo cap, rollout step 1 (#18642). They reuse the legacy self-service test +// env (selfservice_api_test.go): stubbed GitHub, temp stores, the flag on. + +func newHubV1TestEnv(t *testing.T) *selfServiceTestEnv { + t.Helper() + t.Setenv(selfServiceMaxReposEnv, "") + return newSelfServiceTestEnv(t) +} + +func TestHubV1Discovery(t *testing.T) { + cases := []struct { + name string + flag string + maxReposEnv string + wantStatus int + wantMaxRepos int + }{ + {name: "default cap", flag: "true", wantStatus: http.StatusOK, wantMaxRepos: selfServiceMaxReposDefault}, + {name: "configured cap", flag: "true", maxReposEnv: "100", wantStatus: http.StatusOK, wantMaxRepos: 100}, + {name: "cap clamped to ceiling", flag: "true", maxReposEnv: "100000", wantStatus: http.StatusOK, wantMaxRepos: selfServiceMaxReposCeiling}, + {name: "invalid cap falls back", flag: "true", maxReposEnv: "-3", wantStatus: http.StatusOK, wantMaxRepos: selfServiceMaxReposDefault}, + {name: "flag off hides the protocol", flag: "", wantStatus: http.StatusNotFound}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + env := newHubV1TestEnv(t) + t.Setenv(selfServiceRegistrationEnv, tc.flag) + t.Setenv(selfServiceMaxReposEnv, tc.maxReposEnv) + // Discovery is public: no session cookie. + req := httptest.NewRequest(http.MethodGet, hubV1BasePath, nil) + rec := httptest.NewRecorder() + env.s.handleHubV1Discovery(rec, req) + if rec.Code != tc.wantStatus { + t.Fatalf("status = %d, want %d (%s)", rec.Code, tc.wantStatus, rec.Body.String()) + } + if tc.wantStatus != http.StatusOK { + return + } + var d struct { + Protocol string `json:"protocol"` + Version string `json:"version"` + BasePath string `json:"base_path"` + Operations []hubV1Operation `json:"operations"` + PatchFields []string `json:"patch_fields"` + Limits struct { + MaxRepos int `json:"max_repos"` + MaxPerUser int `json:"max_per_user"` + Expiry string `json:"expiry"` + KeyRotationOverlap string `json:"key_rotation_overlap"` + } `json:"limits"` + ProofMethods []string `json:"proof_methods"` + } + if err := json.Unmarshal(rec.Body.Bytes(), &d); err != nil { + t.Fatal(err) + } + if d.Protocol != hubV1Protocol || d.Version != "1" || d.BasePath != "/api/hub/v1" { + t.Fatalf("identity = %q %q %q", d.Protocol, d.Version, d.BasePath) + } + if d.Limits.MaxRepos != tc.wantMaxRepos || d.Limits.MaxPerUser != selfServiceMaxPerUserDefault || + d.Limits.Expiry != selfServiceExpiryDefault.String() || d.Limits.KeyRotationOverlap != selfServiceKeyRotationOverlap.String() { + t.Fatalf("limits = %+v", d.Limits) + } + if !reflect.DeepEqual(d.ProofMethods, []string{"hub-session-token"}) { + t.Fatalf("proof_methods = %v", d.ProofMethods) + } + if len(d.Operations) != 1 || d.Operations[0].Name != "discovery" || d.Operations[0].Method != http.MethodGet || d.Operations[0].Path != "/api/hub/v1" { + t.Fatalf("operations = %+v", d.Operations) + } + if len(d.PatchFields) != 0 { + t.Fatalf("patch_fields = %v, want none until update exists", d.PatchFields) + } + if got := rec.Header().Get("Content-Type"); got != "application/json" { + t.Fatalf("Content-Type = %q", got) + } + }) + } +} + +// Discovery must list exactly the operations that are routed, so a client +// never reads an operation that answers 404. +func TestHubV1RoutesAreRegistered(t *testing.T) { + env := newHubV1TestEnv(t) + env.s.mux = http.NewServeMux() + env.s.registerHubV1Routes() + for _, op := range hubV1Operations { + path := strings.ReplaceAll(op.Path, "{id}", "byo-alice--lab") + req := httptest.NewRequest(op.Method, path, nil) + if _, pattern := env.s.mux.Handler(req); pattern != op.Method+" "+op.Path { + t.Errorf("%s %s routed to %q", op.Method, path, pattern) + } + } +} + +// The real hub constructor must wire the v1 routes, not only the helper, and +// the flag gate must hold through the real mux. +func TestHubV1RoutesWiredIntoHubServer(t *testing.T) { + t.Setenv("HUB_DATA_DIR", t.TempDir()) + t.Setenv(selfServiceMaxReposEnv, "") + srv := NewHubServer(0, slog.Default(), "test", "v5") + t.Cleanup(srv.StopSaveLoop) + + t.Setenv(selfServiceRegistrationEnv, "true") + rec := httptest.NewRecorder() + srv.mux.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, hubV1BasePath, nil)) + if rec.Code != http.StatusOK || !strings.Contains(rec.Body.String(), hubV1Protocol) { + t.Fatalf("GET %s through the hub mux: %d %s", hubV1BasePath, rec.Code, rec.Body.String()) + } + + t.Setenv(selfServiceRegistrationEnv, "") + rec = httptest.NewRecorder() + srv.mux.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, hubV1BasePath, nil)) + if rec.Code != http.StatusNotFound { + t.Fatalf("GET %s with the flag off: %d, want 404", hubV1BasePath, rec.Code) + } +} + +func TestSelfServiceMaxReposReader(t *testing.T) { + cases := []struct { + env string + want int + }{ + {"", 20}, + {"1", 1}, + {"20", 20}, + {"21", 21}, + {"500", 500}, + {"501", 500}, + {"100000", 500}, + {"0", 20}, + {"-5", 20}, + {"many", 20}, + } + for _, tc := range cases { + t.Run("env="+tc.env, func(t *testing.T) { + t.Setenv(selfServiceMaxReposEnv, tc.env) + if got := selfServiceMaxRepos(); got != tc.want { + t.Fatalf("selfServiceMaxRepos() = %d, want %d", got, tc.want) + } + }) + } +} + +// A larger cap must not be undone by the body limit: the largest legal body at +// the ceiling has to fit, and the default keeps the old floor. +func TestSelfServiceRequestBodyLimitScalesWithCap(t *testing.T) { + t.Setenv(selfServiceMaxReposEnv, "") + if got := selfServiceRequestBodyLimit(); got < selfServiceMaxRequestBody { + t.Fatalf("default body limit %d below the floor %d", got, selfServiceMaxRequestBody) + } + t.Setenv(selfServiceMaxReposEnv, "500") + // owner/name refs at GitHub's longest (39 + 1 + 100) plus JSON quoting. + const longestRef = 39 + 1 + 100 + 4 + if got := selfServiceRequestBodyLimit(); got < int64(selfServiceMaxReposCeiling)*longestRef { + t.Fatalf("body limit %d cannot hold %d max-length repos", got, selfServiceMaxReposCeiling) + } +} + +// The legacy register route reads the configurable cap and keeps its 400 body. +func TestSelfServiceRegisterRepoCapIsConfigurable(t *testing.T) { + repos := func(n int) string { + out := make([]string, n) + for i := range out { + out[i] = fmt.Sprintf("alice/bulk-%02d", i) + } + b, _ := json.Marshal(out) + return string(b) + } + cases := []struct { + name string + env string + n int + wantStatus int + wantErr string + }{ + {name: "default accepts 20", env: "", n: 20, wantStatus: http.StatusCreated}, + {name: "default refuses 21 with the legacy 400 body", env: "", n: 21, wantStatus: http.StatusBadRequest, wantErr: "at most 20 repos per registration"}, + {name: "raised cap accepts 21", env: "25", n: 21, wantStatus: http.StatusCreated}, + {name: "raised cap refuses past it", env: "25", n: 26, wantStatus: http.StatusBadRequest, wantErr: "at most 25 repos per registration"}, + {name: "ceiling clamps a typo", env: "100000", n: 501, wantStatus: http.StatusBadRequest, wantErr: "at most 500 repos per registration"}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + env := newHubV1TestEnv(t) + t.Setenv(selfServiceMaxReposEnv, tc.env) + rec := env.register(t, selfServiceTestUser, fmt.Sprintf(`{"name":"big","repos":%s}`, repos(tc.n))) + if rec.Code != tc.wantStatus { + t.Fatalf("status = %d, want %d (%s)", rec.Code, tc.wantStatus, rec.Body.String()) + } + if tc.wantErr != "" { + if got := decodeError(t, rec)["error"]; got != tc.wantErr { + t.Fatalf("error = %q, want %q", got, tc.wantErr) + } + if len(env.s.selfService.list()) != 0 { + t.Fatal("refused registration stored a record") + } + } + }) + } +} diff --git a/src/pkg/hub/server.go b/src/pkg/hub/server.go index ec3bc49db2..75569fca54 100644 --- a/src/pkg/hub/server.go +++ b/src/pkg/hub/server.go @@ -1788,6 +1788,9 @@ func NewHubServer(port int, logger *slog.Logger, gitHash, gitBranch string) *Hub s.mux.HandleFunc("POST /api/hub/selfservice/hives", s.requireAuth(s.handleSelfServiceRegister)) s.mux.HandleFunc("POST /api/hub/selfservice/hives/{id}/rotate", s.requireAuth(s.handleSelfServiceRotate)) s.mux.HandleFunc("DELETE /api/hub/selfservice/hives/{id}", s.requireAuth(s.handleSelfServiceDelete)) + // Hub registration protocol v1 (#18642, selfservice_v1_api.go): discovery + // first; the resource routes follow in later steps of the rollout. + s.registerHubV1Routes() s.mux.HandleFunc("POST /api/contribute/register", s.handleContributeProxy) s.mux.HandleFunc("GET /api/contribute/status", s.handleContributeStatus) s.mux.HandleFunc("GET /api/contribute/ws", s.handleContributeWSProxy)