Skip to content

📝 RFC: v7 - Hub registration protocol for self-hosted hives #18642

Closed

Description

@hanthor

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:

  1. 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.
  2. 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 checks permissions.admin on every repo with that stored token (selfServiceOwnershipChecker.repoAdmin). If the org restricts OAuth apps, GitHub doesn't report the admin role, so the user gets your 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.
  3. 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.
  4. 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.
  5. 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 needs read:org, or repo for private repos, and the hub checks permissions.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_proof list. 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

  1. Discovery, plus PATCH for repos and dashboard_url with the key kept. This alone removes the re-key outage.
  2. The github-user-token proof with explicit, per-request scopes and better errors. Then github-app-installation and repo-file.
  3. Key rotation with a grace window.
  4. sync-repos from the spoke, and feature negotiation in the heartbeat.

Each step is additive and off until a hub enables it.

Open questions

  1. Are pending_proof repos shown on the hub as unverified, or hidden until proven?
  2. Does the hub re-check ownership on a schedule, and drop a repo whose admin has left?
  3. Should an org be able to own registrations (several maintainers, one record) instead of one login?
  4. Is repo-file worth the extra path, given the App installation proof?

🤖 Generated with Claude Code

Activity

  1. added
    proposalRFC / design proposal for discussion
    kind/designCreated by Hive for agent-filed issue provenance
    on Nov 17, 2026
  2. added
    help wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.
    on Nov 17, 2026
  3. hanthor commented on Nov 17, 2026

    @hanthor
    ContributorAuthor

    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 as POST .../keys.
    • PATCH .../registrations/{id} for repos ({add, remove} or a full list) and dashboard_url. The key is untouched. Only added repos get the ownership read.
    • If-Match is 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)

    1. Proof-method naming. Step 1 still proves ownership with the stored sign-in token. Discovery should advertise that honestly as 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.
    2. Proof time per repo. OwnershipCheckedAt is 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.
    3. Over-limit status. v1 returns 413 with limit: max_repos on both create and PATCH. Legacy create keeps its 400.
    4. org is 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.
    5. Rotate returns 201, because it creates a new key. Legacy rotate keeps its 200.

    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}.

  4. added 3 commits that reference this issue on Nov 17, 2026
  5. added
    stage/018-open-for-discussionOpen for discussion: proposal / design issue with no live claim; claimable, no agent work queued
    and removed on Nov 18, 2026
  6. self-assigned this
    on Nov 18, 2026
  7. clubanderson commented on Nov 18, 2026

    @clubanderson
    Member

    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

    1. Repos awaiting proof: hidden until proven (decide again when sync-repos lands, step 4).
    2. Re-check of repo admin rights: only on PATCH or an explicit re-verify, no scheduled drop. Per-repo proof times are kept so a periodic check can be added later (mark stale, never auto-drop).
    3. Org ownership: a single owner login per registration for step 1. Org-owned registrations need their own RFC.
    4. repo-file proof: deferred, and dropped unless restricted-OAuth orgs cannot be solved otherwise.

    Answers the prototype forced: all accepted

    1. The proof method is named hub-session-token in step 1 (new methods are added later, never renamed).
    2. One proof time per repo (repo_proofs), with the legacy OwnershipCheckedAt kept.
    3. v1 over-limit returns 413 with limit: max_repos; the legacy routes keep their pinned 400.
    4. org is not editable in v1 (delete and re-register); the RFC table is amended.
    5. Rotate returns 201 on v1.

    Port plan (v5, behind HIVE_HUB_SELFSERVICE_REGISTRATION, authorship of the original commits preserved)

    • PR A: configurable repo cap (HIVE_HUB_SELFSERVICE_MAX_REPOS, default 20, clamped to 500) plus GET /api/hub/v1 discovery.
    • PR B: per-repo proofs and revision, v1 create, list, delete and rotate.
    • PR C: PATCH with strong If-Match, the key untouched, only added repos proved.
    • Heartbeat signing and the fence are not changed in step 1. Spoke sync-repos and heartbeat feature negotiation are later, security-reviewed PRs.
    • After the v5 merges, the v6 top-up carries it.
  8. added
    stage/020-claimedClaimed by the scanner or a relay contributor
    and removed
    stage/018-open-for-discussionOpen for discussion: proposal / design issue with no live claim; claimable, no agent work queued
    on Nov 18, 2026
  9. hivecommons-hive commented on Nov 18, 2026

    @hivecommons-hive
    Contributor

    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 of or 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.

  10. hivecommons-hive commented on Nov 18, 2026

    @hivecommons-hive
    Contributor

    Fixed by #18892 (merged 095dde4). Closing. Reply /reopen if the problem persists.

  11. github-actions commented on Nov 18, 2026

    @github-actions
    Contributor

    @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 /reopen and 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

help wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.kind/designCreated by Hive for agent-filed issue provenanceproposalRFC / design proposal for discussion

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions