Repository navigation
Description
Summary
Turn hub self-service registration (#18060) into a versioned registration protocol. It gives discovery, edit, rotation with a grace window, more than one ownership proof, and limits the hub advertises. Operators and spokes then manage a self-hosted hive's hub record through an API, not through dashboard-only handlers.
This is a held RFC, a design proposal for discussion, targeted at Hive v7. It carries hold so no hive agent picks it up until the open questions are settled. It covers the hub's own registry only. It adds no GitHub write path, and it doesn't change the heartbeat credential fence (#18081) or the Hive App's write boundary.
Related: #18060 (the self-service RFC), #18142 (registry store with hashed per-hive keys), #18148 (report-only mirror heartbeat), #18170 (byo-<login>--<name> ID hardening).
What we hit
We registered two self-hosted hives (byo-hanthor--school and byo-hanthor--reef) on hive.hivecommons.dev the day self-service was turned on. Each step below happened during that registration:
- No edit. The routes are register, list, rotate and delete (
src/pkg/hub/server.go,/api/hub/selfservice/...). The first registrations went in with one repo each. Adding the other repos meant deleting each registration and registering it again. That revoked the key, so both spokes went dark until we re-keyed and restarted them. - The ownership proof needs a credential the hub never asks for. The GitHub sign-in requests no scope (
src/pkg/hub/oauth.go: "An EMPTY scope is deliberate"). Registration then checkspermissions.adminon every repo with that stored token (selfServiceOwnershipChecker.repoAdmin). If the org restricts OAuth apps, GitHub doesn't report the admin role, so the user getsyour GitHub account is not an admin of tuna-os/<repo>for repos they do administer. There's also nothing to grant on the org side, because the app never requested access. - A fixed cap of 20 repos (
selfServiceMaxRepos). Each of our hives covers 21 repos, so each registration leaves one out, and a spoke can't learn the limit before it hits it. - No hive-to-hub path. Every operation needs a person's hub session. A spoke can't keep its own record current, for example when its repo list changes.
- No discovery. A client can't ask which operations, limits and proof methods a hub supports, so mismatches show up as 4xx errors at run time.
Proposal
1. Versioned resource API
Base path /api/hub/v1, JSON bodies.
| Method | Path | Purpose |
|---|---|---|
GET |
/api/hub/v1 |
Discovery: protocol version, operations, limits (max_repos, max_per_user, expiry), proof methods, accepted heartbeat fields |
POST |
/registrations |
Create from {name, org, dashboard_url, repos[]}. The key is shown once, as today |
GET |
/registrations, /registrations/{id} |
List or read your own registrations |
PATCH |
/registrations/{id} |
Change repos (add and remove lists, or a full replacement), dashboard_url or org. The key stays valid. Only added repos need a new proof |
POST |
/registrations/{id}/keys |
Rotate. An optional grace (for example 1h) keeps the old key accepted for that window, so a rotation causes no outage |
DELETE |
/registrations/{id} |
Remove |
Writes take If-Match with an ETag, so two operators editing at once can't silently overwrite each other.
2. Pluggable ownership proof
The method is chosen per request from the ones discovery lists:
github-user-token: the caller presents a GitHub token for this request only. It needsread:org, orrepofor private repos, and the hub checkspermissions.admin. The token isn't stored, so the stored sign-in token stays scopeless.github-app-installation: the repos are covered by an installation of the hub's GitHub App, made by an org admin. This works when the org restricts OAuth apps.repo-file: the hub issues a challenge, and the caller commits it to the repo's default branch at a fixed path (for example.hive/hub-challenge). The hub only reads it.
A failed proof says why. "Your token can't see the admin role on tuna-os/x (is the org restricting OAuth apps?)" is a different error from "you aren't an admin of tuna-os/x".
3. Hive-to-hub record sync
A registration key, sent the way heartbeats send it today, may call PATCH /registrations/{id} with op: sync-repos, on its own registration only.
- Repos that already have a proof apply immediately.
- New repos go to a
pending_prooflist. They count only after the owner approves them or a proof method clears them. - The key can't change
org, the owner,dashboard_url, or any other registration.
This changes the hub's registry and nothing else. Nothing in this RFC writes to GitHub.
4. Limits through discovery
max_repos (proposed default 100), max_per_user and expiry are advertised and enforced with 413 or 409 responses that name the limit. The fixed cap of 20 goes away.
5. Feature negotiation in the heartbeat
Spokes send protocol: {version, features: [...]}. The hub answers with the features and fields it accepted and the ones it ignored, so a field the report-only mirror path drops is reported instead of disappearing silently.
Compatibility
The v6 /api/hub/selfservice/* routes stay as aliases for one minor release. IDs (byo-<login>--<name>), keys and the 24h no-heartbeat expiry don't change. Existing registrations become v1 resources without any change to their data.
Rollout
- Discovery, plus
PATCHforreposanddashboard_urlwith the key kept. This alone removes the re-key outage. - The
github-user-tokenproof with explicit, per-request scopes and better errors. Thengithub-app-installationandrepo-file. - Key rotation with a grace window.
sync-reposfrom the spoke, and feature negotiation in the heartbeat.
Each step is additive and off until a hub enables it.
Open questions
- Are
pending_proofrepos shown on the hub as unverified, or hidden until proven? - Does the hub re-check ownership on a schedule, and drop a repo whose admin has left?
- Should an org be able to own registrations (several maintainers, one record) instead of one login?
- Is
repo-fileworth the extra path, given the App installation proof?
🤖 Generated with Claude Code
Activity
hanthor commentedon Nov 17, 2026
Update 1: rollout step 1 prototyped in the tuna-os fork (tuna-os#189, v2-tests green). All of it is behind
HIVE_HUB_SELFSERVICE_REGISTRATION, and the legacy/api/hub/selfservice/*responses are pinned unchanged by a test.What step 1 looks like in code
GET /api/hub/v1: discovery, readable without signing in. It lists the operations, the fields PATCH can change, the limits (max_repos,max_per_user,expiry) and the proof methods.POST/GET/DELETE /api/hub/v1/registrations[/{id}], plus rotation asPOST .../keys.PATCH .../registrations/{id}forrepos({add, remove}or a full list) anddashboard_url. The key is untouched. Only added repos get the ownership read.If-Matchis required on PATCH (428 when missing, 412 when stale). The ETag comes from a revision counter that heartbeats don't bump, so a live spoke never invalidates an operator's ETag, and the ETag reveals nothing about the key.HIVE_HUB_SELFSERVICE_MAX_REPOS: default 20, so nothing changes unless set. Values are clamped to 500.Answers the prototype forced (proposed; corrections welcome)
hub-session-token.github-user-token(a token sent per request with explicit scopes) appears only once step 2 ships, so no client sends a token the hub ignores.OwnershipCheckedAtis one timestamp per record, but proofs are now per repo. The record should keep a proof time for each repo, which a scheduled re-check (open question 2) needs anyway.limit: max_reposon both create and PATCH. Legacy create keeps its 400.orgis not editable in v1. Changing it would mean re-proving every repo. Clients delete and re-create instead, until there's a case for it. The RFC table is amended accordingly.The prototype didn't touch the heartbeat credential fence (#18081), which is byte-identical, and makes no GitHub writes: the ownership check is a read-only
GET /repos/{o}/{r}.✨ hub: apply the hivecommons#18642 owner decisions to the v1 registra…
✨ hub: registration protocol v1 discovery and in-place PATCH
✨ hub: apply the hivecommons#18642 owner decisions to the v1 registra…
✨ hub: registration protocol v1 discovery and in-place PATCH (prototy…
clubanderson commentedon Nov 18, 2026
Owner decisions on the open questions (v1 registration protocol), based on the prototype in tuna-os#189 and a read of v5. The hold is lifted and the port to hivecommons/hive v5 is starting; hive agents please do not duplicate it.
Open questions
repo-fileproof: deferred, and dropped unless restricted-OAuth orgs cannot be solved otherwise.Answers the prototype forced: all accepted
hub-session-tokenin step 1 (new methods are added later, never renamed).repo_proofs), with the legacyOwnershipCheckedAtkept.limit: max_repos; the legacy routes keep their pinned 400.orgis not editable in v1 (delete and re-register); the RFC table is amended.Port plan (v5, behind
HIVE_HUB_SELFSERVICE_REGISTRATION, authorship of the original commits preserved)HIVE_HUB_SELFSERVICE_MAX_REPOS, default 20, clamped to 500) plusGET /api/hub/v1discovery.If-Match, the key untouched, only added repos proved.sync-reposand heartbeat feature negotiation are later, security-reviewed PRs.hivecommons-hive commentedon Nov 18, 2026
Hive status — updated in place; edits do not notify. Full history is in the Activity Monitor.
PR #18892 covers this issue: #18892
The PR body says this is partial/non-closing work (
Refs/Part ofor leave-open wording), so Hive will not add a closing keyword. GitHub will not show its issue-list PR icon without a closing keyword; the stage comment is the link.✨ hub: v1 registration discovery and configurable repo cap (#18892)
✨ hub: v1 registration resources, per-repo proofs and revision
hivecommons-hive commentedon Nov 18, 2026
Fixed by #18892 (merged 095dde4). Closing. Reply /reopen if the problem persists.
github-actions commentedon Nov 18, 2026
@hanthor this issue was closed by @hivecommons-hive[bot] as completed.
If this was closed by a merged PR, the fix only takes effect once it ships in a tagged release and your deployment updates to it — check your running version against the fix before concluding the fix failed.
If you are still seeing the problem, comment
/reopenand it will be reopened for you — you do not need write access. Please add what you are still observing (running version, logs, steps) so it is not closed the same way again.✨ hub: v1 registration resources, per-repo proofs and revision (2/3) (#…