Skip to content

✨ hub: remaining ownership proof methods with per-request scopes - #19241

Merged
kubestellar-prow[bot] merged 2 commits into
v5from
scanner/fix-19238
Nov 19, 2026
Merged

kubestellar-prow[bot] merged 2 commits into
v5from
scanner/fix-19238

Conversation

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Summary

The hub signs users in with no GitHub scope, so in an org that restricts OAuth apps GitHub hides the admin role from the stored token, and registration says "not an admin" for repos the user does administer. There is nothing the user or the org can grant to fix it. This adds the RFC's per-request token proof so those users can register, without making the stored sign-in token any broader.

  • Which RFC methods were missing (📝 RFC: v7 - Hub registration protocol for self-hosted hives #18642): github-user-token, github-app-installation and repo-file. Only hub-session-token (the stored-token permissions.admin check) existed.
  • Implemented here: github-user-token, the simplest read-only one. repo-file stays out per the owner decision on 📝 RFC: v7 - Hub registration protocol for self-hosted hives #18642 (deferred). github-app-installation needs an App installation lookup and is left as a follow-up rather than folded into this PR.
  • Flag-gated: HIVE_HUB_PROOF_GITHUB_USER_TOKEN (off by default, on top of HIVE_HUB_SELFSERVICE_REGISTRATION). While off, asking for the method is a 400 listing what the hub offers, never a silent fallback.
  • Explicit per-request scopes: the caller picks the method per request with X-Hive-Proof-Method and sends the token in X-Hive-Proof-Token. Discovery lists the scopes the token needs (none for public repos, repo for private, read access for fine-grained tokens), and a refusal reports required_scopes and the granted_scopes GitHub reported.
  • Clear errors: a failed proof names a reason (token_rejected, token_user_mismatch, sso_not_authorized, missing_scope, repo_not_visible, admin_role_not_visible, not_admin), so "the token cannot see your role" is no longer reported as "you are not an admin".
  • Safety: the token must belong to the signed-in GitHub account, is used only for read-only GET /user and GET /repos/{o}/{r}, and is never stored, logged or echoed. Nothing writes to GitHub. The v6 /api/hub/selfservice/* routes ignore the headers, and their pinned bodies are unchanged. RFC note: the hub does not ask for read:org, since the only call it makes on a repo is GET /repos/{o}/{r}.

Related issues

Closes #19238 (part of #19056, RFC #18642)

Testing

  • Not run locally: CI runs validation for agent-authored PRs (AGENTS.md forbids local builds/tests in agent panes). Only gofmt -l was run on the changed files.
  • New src/pkg/hub/selfservice_v1_proof_test.go covers discovery with the flag on and off, a token proving what the stored token cannot (create and PATCH), every request refusal and every proof refusal reason, 502 on a GitHub error, the v6 route ignoring the headers, and that the token never shows up in responses, logs or the store.

Contributor checklist

  • Changelog: changelog.d/added-19238-hub-github-user-token-proof.md
  • PR targets v5.
  • Title uses the repo emoji convention.
  • Commits include DCO sign-off.
  • Docs updated (hub-deployment.md, env-vars.md, api-reference/hub-server.md, audit-log.md).
  • No secrets, credentials, or local runtime state are committed.

🤖 Generated with Claude Code

-- hive: agent=scanner backend=claude model=claude-sonnet-5-5 claude=2.1.328 requested_by=@clubanderson

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>
@kubestellar-prow kubestellar-prow Bot added dco-signoff: yes Indicates the PR's author has signed the DCO. size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. labels Nov 19, 2026
@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: v5

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

PR Title Relation Files
#19253 ✨ customers: hub import disclosure, docs and consent views same files src/docs/env-vars.md
src/docs/hub-deployment.md
#19206 ✨ ask: hive panel and rollout verification for optional Ask AI help same files src/docs/api-reference/hub-server.md
src/docs/env-vars.md
src/docs/hub-deployment.md
#19204 ✨ ask: hive backend and hub relay for optional Ask AI help same files src/docs/api-reference/hub-server.md
src/docs/env-vars.md
src/docs/hub-deployment.md
#19202 ✨ ask: hub panel for optional Ask AI help same files src/docs/api-reference/hub-server.md
src/docs/env-vars.md
src/docs/hub-deployment.md
#19252 ✨ feature: let spokes sync their own registration repos same files src/docs/api-reference/hub-server.md
src/pkg/hub/selfservice_v1_api.go
src/pkg/hub/selfservice_v1_patch.go
#19240 ✨ hub: registration key rotation with a grace window CONFLICT src/docs/api-reference/hub-server.md
src/docs/audit-log.md
src/docs/env-vars.md (conflict)
src/docs/hub-deployment.md (conflict)
src/pkg/hub/selfservice_api.go
src/pkg/hub/selfservice_v1_api.go

@github-actions github-actions Bot added the conflicts-with-open-pr Open PR has a merge conflict with another open PR label Nov 19, 2026
@hivecommons-hive hivecommons-hive Bot added author/hive This repository's own hive (the App or one of its agent lanes) authored this PR dco All commits are DCO signed-off stage/050-review-pending Review swarm requested; awaiting a verdict for the current head labels Nov 19, 2026

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Decision needed: @clubanderson should the hub accept a caller-supplied GitHub token (X-Hive-Proof-Token) as ownership proof behind HIVE_HUB_PROOF_GITHUB_USER_TOKEN?

Read selfservice_v1_proof.go in full. I found no defect; this goes to a person because it makes the hub handle a user's GitHub token on a new path.

Verified in the code: the token is read only from a header, length and charset checked (hubV1PlausibleToken), never echoed or logged (the log lines at hubV1ProveWithUserToken carry user, hive, repo, status only), and tokenUser requires the token's GET /user login to equal the signed-in login (strings.EqualFold), so another person's token cannot prove ownership. The method is off by default and a disabled request is a 400, not a silent fallback to the stored token.

Open question for the maintainer: whether request headers are ever dumped by the hub's access logging or the reverse proxy in front of it; I could not verify that from this diff, and X-Hive-Proof-Token would then land in logs.

-- hive: agent=reviewer-2 backend=claude model=claude-sonnet-5-5 claude=2.1.328

@hivecommons-hive hivecommons-hive Bot added role/trusted Author is trusted for unattended merge (trusted-author role or registry/claim tier in require_tiers) stage/085-needs-decision A human decision is owed: sentinel alert, hold/needs-decision label, human-only rule or parked issue and removed stage/050-review-pending Review swarm requested; awaiting a verdict for the current head labels Nov 19, 2026
@hivecommons-hive

hivecommons-hive Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor Author

Needs a decision, not a merge:

  • the reviewer swarm returned requires_human @ddf2b4d
  • the review found: the reviewer marked this change high-risk
  • reviewer question: @clubanderson should decide whether the hub accepts a per-request GitHub token (X-Hive-Proof-Token, flag HIVE_HUB_PROOF_GITHUB_USER_TOKEN) as an ownership proof, given it is a new credential-handling path and only one of the three RFC 📝 RFC: v7 - Hub registration protocol for self-hosted hives #18642 methods.
  • the automerge lane will not merge this unattended

Head: verdict requires_human @ddf2b4d, 72/73 checks green, 1 pending, DCO yes, soak 0s of 10m0s.

What to do: approve this head (ddf2b4d) to merge as-is, or leave a changes requested review (or reply /hive decision <what to change>) and the hive will push the fix.

How to release it:

  • After reading the verdict, a trusted merger can submit a GitHub Approve review for the current head and the lane clears the hold on its next pass; /hive approve replies on a PR are acknowledged but not consumed.

Clear the cause and the hive re-evaluates on its next pass; the stage moves to stage/090-ready-for-human-merge, stage/095-pre-merge-soak or the merge queue on its own. Approval does not bypass CI, hold labels or other merge gates.

Updated 2026-11-19 09:31 UTC.

@github-actions github-actions Bot removed the conflicts-with-open-pr Open PR has a merge conflict with another open PR label Nov 19, 2026
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>
@github-actions github-actions Bot added the conflicts-with-open-pr Open PR has a merge conflict with another open PR label Nov 19, 2026
@hivecommons-hive hivecommons-hive Bot added stage/050-review-pending Review swarm requested; awaiting a verdict for the current head and removed stage/085-needs-decision A human decision is owed: sentinel alert, hold/needs-decision label, human-only rule or parked issue labels Nov 19, 2026

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Decision needed: @clubanderson should decide whether the hub may accept a user-minted GitHub token in the X-Hive-Proof-Token request header (even flag-gated, off by default) for registration ownership proof.

Read selfservice_v1_proof.go and the changed repoAdminDetail/tokenUser paths. I found no defect in the code I read, and the invariants it states hold: the token is length and charset checked (hubV1PlausibleToken), bound to the signed-in login through GET /user (strings.EqualFold(who.login, githubLogin)), only used for read-only GETs, and absent from refusal bodies. The flag defaults to off and a disabled request is a 400, not a fallback.

This PR introduces a new path where the hub receives a user's GitHub credential on each request. That is a credential-handling policy choice, so I am routing it rather than approving.

Open questions I could not verify from the diff alone (not claimed as defects):

  • Whether any reverse proxy, ingress or access-log middleware in front of the hub records request headers; if one does, X-Hive-Proof-Token would be persisted despite the in-handler no-log guarantee.
  • The conflicts-with-open-pr label is set; the overlapping PR was not checked here.

-- hive: agent=reviewer backend=claude model=claude-sonnet-5-5 claude=2.1.328

@hivecommons-hive

Copy link
Copy Markdown
Contributor Author

Hive status — updated in place; edits do not notify. Full history is in the Activity Monitor.

Review findings from reviewer-2 (folded here because this head already carries its hive review):

The code reads correctly to me; the open point is a policy call, not a defect.

Read src/pkg/hub/selfservice_v1_proof.go and the repoAdminDetail refactor in selfservice_api.go. The token is taken per request, must match the signed-in login via GET /user (hubV1ProveWithUserToken), then must show permissions.admin on every repo. The pointer-typed Permissions correctly separates "role not shown" from "not admin". The flag is off by default, the v6 routes never read the headers, and the token is not logged or echoed in the paths I read.

Open question for a human: this adds a credential-bearing request header to the registration API. Is that acceptable for the hub, and should the rollout wait for github-app-installation so a user token is not the only fix for restricted orgs? Operators should also know X-Hive-Proof-Token will appear in any proxy or access log that records request headers; that is not covered by the docs diff I read, so I did not verify it either way.

@hivecommons-hive hivecommons-hive Bot added stage/085-needs-decision A human decision is owed: sentinel alert, hold/needs-decision label, human-only rule or parked issue and removed stage/050-review-pending Review swarm requested; awaiting a verdict for the current head labels Nov 19, 2026
@clubanderson

Copy link
Copy Markdown
Member

Maintainer-side review of the decision question (accept a caller-supplied GitHub token in X-Hive-Proof-Token as ownership proof, behind HIVE_HUB_PROOF_GITHUB_USER_TOKEN).

Verdict: acceptable as is. The method is off by default and only read when the flag is on.

Checked against the code:

  • Token comes only from a header, is length and charset checked (hubV1PlausibleToken), and is never put in a response, audit line or log line. The log lines in hubV1ProveWithUserToken carry user, hive, repo, proof_method and status only.
  • The token must belong to the signed-in account: tokenUser calls GET /user and the login must match (strings.EqualFold against topRepoProfileLogin). Another person's token cannot prove ownership.
  • Only GET /user and GET /repos/{o}/{r} are called. Nothing writes to GitHub. The v6 routes never call hubV1ReadProof.
  • Flag off plus the method requested is a 400, not a fallback. A token sent without the method header is also a 400.
  • The open logging question: I found no request header dumping in src/pkg/hub (no DumpRequest, no loops over r.Header), and src/deploy/nginx.conf has no custom log_format, so the default access log does not record this header. The v1 routes set no CORS Allow-Headers, so a cross-origin page cannot send X-Hive-Proof-Token with a user's cookie.

Optional follow-up, not blocking: in hub-deployment.md, recommend a fine-grained token with only Metadata read on the listed repos and a short expiry, ahead of the classic repo scope (which is full read and write).

Note: the overlap check reports a conflict with #19240 (key rotation); whichever merges second needs a rebase.

@clubanderson clubanderson added lgtm Indicates that a PR is ready to be merged. approved Indicates a PR has been approved by an approver from all required OWNERS files. labels Nov 19, 2026
@kubestellar-prow

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is APPROVED

Approval requirements bypassed by manually added approval.

This pull-request has been approved by:

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@clubanderson clubanderson left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved at head ddf2b4d. Off by default behind HIVE_HUB_PROOF_GITHUB_USER_TOKEN; the token is bound to the signed-in user, used only for read-only GitHub calls, and never returned or logged; no hub code or nginx log format records the header.

@kubestellar-prow
kubestellar-prow Bot merged commit 6e5f681 into v5 Nov 19, 2026
110 checks passed
@hivecommons-hive hivecommons-hive Bot added stage/050-review-pending Review swarm requested; awaiting a verdict for the current head and removed stage/085-needs-decision A human decision is owed: sentinel alert, hold/needs-decision label, human-only rule or parked issue labels Nov 19, 2026
@kubestellar-prow
kubestellar-prow Bot deleted the scanner/fix-19238 branch November 19, 2026 16:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

approved Indicates a PR has been approved by an approver from all required OWNERS files. author/hive This repository's own hive (the App or one of its agent lanes) authored this PR conflicts-with-open-pr Open PR has a merge conflict with another open PR copilot dco All commits are DCO signed-off dco-signoff: yes Indicates the PR's author has signed the DCO. lgtm Indicates that a PR is ready to be merged. role/trusted Author is trusted for unattended merge (trusted-author role or registry/claim tier in require_tiers) size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. stage/050-review-pending Review swarm requested; awaiting a verdict for the current head

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[scanner] hub: remaining ownership proof methods with per-request scopes

1 participant