diff --git a/changelog.d/added-19238-hub-github-user-token-proof.md b/changelog.d/added-19238-hub-github-user-token-proof.md new file mode 100644 index 0000000000..e2d0466a5c --- /dev/null +++ b/changelog.d/added-19238-hub-github-user-token-proof.md @@ -0,0 +1 @@ +- **Hub v1 registrations can prove repo ownership with a per-request GitHub token** (#19238). With `HIVE_HUB_PROOF_GITHUB_USER_TOKEN` on, `POST /api/hub/v1/registrations` and `PATCH /api/hub/v1/registrations/{id}` accept `X-Hive-Proof-Method: github-user-token` with a token in `X-Hive-Proof-Token`, so users in orgs that restrict OAuth apps can register repos they administer. The token must belong to the signed-in account, is used only for read-only GitHub calls and is never stored or logged. Discovery lists the method and the scopes it needs, and a failed proof names a reason such as `missing_scope` or `admin_role_not_visible` instead of a bare "not an admin". Off by default. diff --git a/src/docs/api-reference/hub-server.md b/src/docs/api-reference/hub-server.md index 1b6464adbd..d323183f8d 100644 --- a/src/docs/api-reference/hub-server.md +++ b/src/docs/api-reference/hub-server.md @@ -58,8 +58,8 @@ 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:1791` | | `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:1792` | | `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:1793` | -| `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` | 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[], proof_method_details[{name, description, headers, scopes}]}`. Readable without signing in so a client learns the limits before it hits a `4xx`. `proof_methods` is `["hub-session-token"]` (ownership proven with the GitHub token stored at hub sign-in), plus `github-user-token` while `HIVE_HUB_PROOF_GITHUB_USER_TOKEN` is on (a token sent per request in `X-Hive-Proof-Token`, with the scopes listed in `proof_method_details`). `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`, and `X-Hive-Proof-Method: github-user-token` picks the per-request token proof (`400` listing `proof_methods` when the hub does not offer it; `403 {error, proof_method, reason, repo, required_scopes, granted_scopes}` when it fails). `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` | | `PATCH` | `/api/hub/v1/registrations/{id}` | Hub auth | Owner only, by hub session (a registration key is not accepted): change `repos` and/or `dashboard_url` in place with the heartbeat key kept valid ([#18642](https://github.com/hivecommons/hive/issues/18642)). Body: `repos` is a full list (replacement) or `{add[], remove[]}`; `dashboard_url` is an `https` URL or `""` to clear it. `If-Match` is required: `428` when absent, `412` carrying the current `ETag` when stale (checked before any GitHub call and again under the store lock). Only added repos are proven (`403` naming the first refused repo, nothing applied); kept repos keep their proof time and removed repos lose theirs. `org`, the owner, the ID and the keys are not editable: a body naming `org` or any other field is `400`, as is a list that would leave no repo. Over `HIVE_HUB_SELFSERVICE_MAX_REPOS` is `413 {error, limit: "max_repos", max_repos}`. Removing a repo the registration does not list is ignored; an edit that changes nothing answers `200` with the current `ETag` and does not bump the revision. `200 {registration}` with the new `ETag`; the key never appears. `404` for a missing hive, another user's hive and a hub admin who does not own it; `404` while `HIVE_HUB_SELFSERVICE_REGISTRATION` is off | `pkg/hub/selfservice_v1_patch.go` | diff --git a/src/docs/audit-log.md b/src/docs/audit-log.md index be1fc3d346..8f52b17f41 100644 --- a/src/docs/audit-log.md +++ b/src/docs/audit-log.md @@ -208,7 +208,8 @@ a key hash, the master secret or the user's GitHub token. | `selfservice_hive_rotated` | The owner rotated the heartbeat key | `user`, `hive`, `overlap` (how long the previous key keeps authenticating) | | `selfservice_hive_revoked` | The owner or a hub admin revoked the hive; the registry entry is removed in the same request and `registry entry removed` follows | `user`, `hive`, `owner`, `by_admin` | | `selfservice_hive_expired` | The expiry sweep (`pkg/hub/selfservice_expiry.go`, every `HIVE_HUB_SELFSERVICE_SWEEP_INTERVAL`) removed a hive that went longer than `HIVE_HUB_SELFSERVICE_EXPIRY` without an accepted heartbeat; the key is revoked and `registry entry removed` (with `by=selfservice-expiry-sweep`) follows | `id`, `owner`, `last_heartbeat` (RFC 3339, or `never` when no heartbeat was ever accepted), `expiry` | -| `selfservice_hive_refused` | A registration was turned away and nothing was stored | `user`, `hive`, `reason` (`invalid_name`, `invalid_login`, `reserved_prefix`, `duplicate_id`, `invalid_repos`, `invalid_dashboard_url`, `invalid_update` (a `PATCH` body the hub refused), `per_user_cap` with `max_per_user`, `no_github_token`, `no_github_login`, `not_repo_admin` with `repo`, `ownership_check_error` with `repo`) | +| `selfservice_hive_refused` | A registration was turned away and nothing was stored | `user`, `hive`, `reason` (`invalid_name`, `invalid_login`, `reserved_prefix`, `duplicate_id`, `invalid_repos`, `invalid_dashboard_url`, `invalid_update` (a `PATCH` body the hub refused), `per_user_cap` with `max_per_user`, `no_github_token`, `no_github_login`, `not_repo_admin` with `repo`, `ownership_check_error` with `repo`, `proof_token_refused` (a failed `github-user-token` proof) with `proof_method`, `proof_reason` and `repo` when one repo failed) | +| `selfservice_ownership_proven` | A v1 create or `PATCH` proved ownership with the `github-user-token` method; the token itself is never logged | `user`, `hive`, `proof_method`, `repos` (count) | ## Rotation and retention diff --git a/src/docs/env-vars.md b/src/docs/env-vars.md index 019ced95ed..d2191ab860 100644 --- a/src/docs/env-vars.md +++ b/src/docs/env-vars.md @@ -125,6 +125,7 @@ behavior. [Maintenance limitations](#keeping-this-reference-current) still apply | `HIVE_HUB_MAIL_REPLY_HIVE_PER_DAY` | No | `200` | Most replies for one hive in 24 hours. | | `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`; `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_PROOF_GITHUB_USER_TOKEN` | No | off | Offers the `github-user-token` ownership proof on the v1 registration create and `PATCH` routes ([#19238](https://github.com/hivecommons/hive/issues/19238)): the caller sends `X-Hive-Proof-Method: github-user-token` and `X-Hive-Proof-Token`, and the hub checks `permissions.admin` with that token for the request only (never stored or logged). Advertised by `GET /api/hub/v1` in `proof_methods` and `proof_method_details`. Accepts `1/true/yes/on`. 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_HEARTBEAT_PROTOCOL` | No | off | Heartbeat feature negotiation ([#19237](https://github.com/hivecommons/hive/issues/19237)). When on (`1/true/yes/on`), a heartbeat that carries `protocol: {version, features}` is answered with `protocol: {version, accepted, ignored}` (plus `unsupported_version` for a version below `1`). A heartbeat without `protocol` is answered exactly as before. Read per request. See [hub-deployment.md](hub-deployment.md#heartbeat-feature-negotiation). | diff --git a/src/docs/hub-deployment.md b/src/docs/hub-deployment.md index 1f78af3a14..f136b69098 100644 --- a/src/docs/hub-deployment.md +++ b/src/docs/hub-deployment.md @@ -182,6 +182,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`. `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_PROOF_GITHUB_USER_TOKEN` | off | Offers the `github-user-token` ownership proof on `POST /api/hub/v1/registrations` and `PATCH /api/hub/v1/registrations/{id}` ([#19238](https://github.com/hivecommons/hive/issues/19238)). See [Proving ownership with your own token](#proving-ownership-with-your-own-token). Accepts `1/true/yes/on`. Read per request. Only meaningful while `HIVE_HUB_SELFSERVICE_REGISTRATION` is on. | | `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. | @@ -217,6 +218,21 @@ The registry entry becomes a `self-hosted` hive in Active Hives and the fleet vi The route is part of the v1 registration protocol and follows the same switch as the rest of it, `HIVE_HUB_SELFSERVICE_REGISTRATION`; discovery (`GET /api/hub/v1`) lists it under `operations` with `if_match: "required"` and its fields under `patch_fields`, so a hub that does not offer it does not advertise it. The v6 `/api/hub/selfservice/*` routes are unchanged. +#### Proving ownership with your own token + +The hub signs users in with no GitHub scope, so when an org restricts OAuth apps GitHub hides the admin role from the stored token and registration says `not an admin` for repos the user does administer. With `HIVE_HUB_PROOF_GITHUB_USER_TOKEN` on, a v1 create or `PATCH` can prove ownership with a token sent on that request only: + +``` +X-Hive-Proof-Method: github-user-token +X-Hive-Proof-Token: +``` + +- **Scopes:** none for public repos; the classic `repo` scope for private repos. A fine-grained token needs read access (Metadata) to every repo in the request. Discovery lists this under `proof_method_details`. +- **Whose token:** the token must belong to the signed-in GitHub account (`GET /user`); a token made by another account is refused. +- **Never kept:** the token is used for the read-only `GET /user` and `GET /repos/{owner}/{repo}` calls and then dropped. It is not stored, logged or echoed, and the stored sign-in token stays scopeless. +- **Clear refusals:** a failed proof answers `403 {error, proof_method, reason, repo, required_scopes, granted_scopes}`, where `reason` is one of `token_rejected`, `token_user_mismatch`, `sso_not_authorized`, `missing_scope`, `repo_not_visible`, `admin_role_not_visible` (GitHub showed the repo but not the role) or `not_admin`. `granted_scopes` appears only when GitHub reported the token's scopes. +- **Off means off:** while the flag is off, asking for the method is `400` listing the methods the hub offers; it never falls back to the stored token. Without `X-Hive-Proof-Method` the hub proves with the stored token as before (`hub-session-token`). The v6 `/api/hub/selfservice/*` routes ignore both headers. + #### Heartbeat feature negotiation A spoke may send `protocol: {"version": 1, "features": [...]}` in its heartbeat ([#19237](https://github.com/hivecommons/hive/issues/19237)). With `HIVE_HUB_HEARTBEAT_PROTOCOL` on (`1/true/yes/on`, default off, read per request), the hub answers with `protocol: {"version", "accepted", "ignored"}`: the version it speaks for this beat, the requested features it honours, and the requested features it does not. The features a v1 hub accepts are `activity_digest`, `activity_events` and `host_aliases`, all of which it already serves to every spoke; negotiation changes nothing else in the response. diff --git a/src/pkg/hub/selfservice_api.go b/src/pkg/hub/selfservice_api.go index c262fef53a..61e1fea8a6 100644 --- a/src/pkg/hub/selfservice_api.go +++ b/src/pkg/hub/selfservice_api.go @@ -168,38 +168,93 @@ func (s *HubServer) ownershipChecker() *selfServiceOwnershipChecker { // admin specifically; maintain is not accepted (unlike the lite-enrollment // check, which has different stakes). func (c *selfServiceOwnershipChecker) repoAdmin(ctx context.Context, token, owner, repo string) (bool, error) { + res, err := c.repoAdminDetail(ctx, token, owner, repo) + return res.admin, err +} + +// selfServiceRepoAdminResult is what one read-only ownership call learned. +// repoAdmin uses only admin; the github-user-token proof +// (selfservice_v1_proof.go) uses the rest to say why a proof failed. +type selfServiceRepoAdminResult struct { + // status is GitHub's HTTP status for GET /repos/{owner}/{repo}. + status int + admin bool + // permissionsReported is false when GitHub answered 200 without a + // permissions object, which is how an org restricting the token's access + // shows up: the repo is visible, the caller's role is not. + permissionsReported bool + // ssoRequired is set when GitHub answered 403 with an X-GitHub-SSO + // header: the token is not authorized for the org's SAML single sign-on. + ssoRequired bool + // scopes are the classic OAuth scopes GitHub reported for the token; + // scopesKnown is false when GitHub sent no X-OAuth-Scopes header (a + // fine-grained token or a GitHub App token). + scopes []string + scopesKnown bool +} + +// repoAdminDetail is repoAdmin with the detail a clear refusal needs. A 401, +// 403 or 404 is a result, not an error; any other non-2xx is an error. +func (c *selfServiceOwnershipChecker) repoAdminDetail(ctx context.Context, token, owner, repo string) (selfServiceRepoAdminResult, error) { + var res selfServiceRepoAdminResult u, err := url.JoinPath(c.apiBase, "repos", owner, repo) if err != nil { - return false, fmt.Errorf("build GitHub repo URL: %w", err) + return res, fmt.Errorf("build GitHub repo URL: %w", err) } req, err := http.NewRequestWithContext(ctx, http.MethodGet, u, nil) if err != nil { - return false, fmt.Errorf("build GitHub ownership check: %w", err) + return res, fmt.Errorf("build GitHub ownership check: %w", err) } req.Header.Set("Authorization", "Bearer "+token) req.Header.Set("Accept", "application/vnd.github+json") resp, err := c.client.Do(req) if err != nil { - return false, fmt.Errorf("GitHub ownership check failed: %w", err) + return res, fmt.Errorf("GitHub ownership check failed: %w", err) } defer func() { _ = resp.Body.Close() }() + res.status = resp.StatusCode + res.scopes, res.scopesKnown = selfServiceTokenScopes(resp.Header) switch resp.StatusCode { case http.StatusUnauthorized, http.StatusForbidden, http.StatusNotFound: - return false, nil + res.ssoRequired = resp.StatusCode == http.StatusForbidden && strings.TrimSpace(resp.Header.Get("X-GitHub-SSO")) != "" + _, _ = io.Copy(io.Discard, io.LimitReader(resp.Body, selfServiceOwnershipErrorBodyLimit)) + return res, nil } if resp.StatusCode < http.StatusOK || resp.StatusCode >= http.StatusMultipleChoices { _, _ = io.Copy(io.Discard, io.LimitReader(resp.Body, selfServiceOwnershipErrorBodyLimit)) - return false, fmt.Errorf("GitHub ownership check returned HTTP %d", resp.StatusCode) + return res, fmt.Errorf("GitHub ownership check returned HTTP %d", resp.StatusCode) } var payload struct { - Permissions struct { + Permissions *struct { Admin bool `json:"admin"` } `json:"permissions"` } if err := json.NewDecoder(resp.Body).Decode(&payload); err != nil { - return false, fmt.Errorf("decode GitHub ownership check: %w", err) + return res, fmt.Errorf("decode GitHub ownership check: %w", err) + } + if payload.Permissions != nil { + res.permissionsReported = true + res.admin = payload.Permissions.Admin } - return payload.Permissions.Admin, nil + return res, nil +} + +// selfServiceTokenScopes reads GitHub's X-OAuth-Scopes header. known is false +// when the header is absent (fine-grained and App tokens carry no scopes). +func selfServiceTokenScopes(h http.Header) (scopes []string, known bool) { + values, known := h[http.CanonicalHeaderKey("X-OAuth-Scopes")] + if !known { + return nil, false + } + scopes = []string{} + for _, v := range values { + for _, scope := range strings.Split(v, ",") { + if scope = strings.TrimSpace(scope); scope != "" { + scopes = append(scopes, scope) + } + } + } + return scopes, true } // selfServiceRegisterRequest is the body of POST /api/hub/selfservice/hives. @@ -469,6 +524,15 @@ func (s *HubServer) selfServiceRegisterCore(w http.ResponseWriter, r *http.Reque writeJSONError(w, http.StatusUnauthorized, "not authenticated") return SelfServiceHive{}, "", false } + // Only the v1 route reads a proof method; the v6 route always proves with + // the stored sign-in token, as before. + var proof hubV1Proof + if v1 { + var ok bool + if proof, ok = hubV1ReadProof(w, r); !ok { + 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") @@ -525,7 +589,7 @@ func (s *HubServer) selfServiceRegisterCore(w http.ResponseWriter, r *http.Reque return SelfServiceHive{}, "", false } - if !s.selfServiceProveOwnership(w, r, login, id, user, repos) { + if !s.hubV1ProveOwnership(w, r, login, id, user, repos, proof) { return SelfServiceHive{}, "", false } diff --git a/src/pkg/hub/selfservice_v1_api.go b/src/pkg/hub/selfservice_v1_api.go index 35d6bcb788..ba5b326eb9 100644 --- a/src/pkg/hub/selfservice_v1_api.go +++ b/src/pkg/hub/selfservice_v1_api.go @@ -11,9 +11,9 @@ package hub // and status codes. // // Invariants (in addition to selfservice_api.go's): -// - Nothing here writes to GitHub. The only GitHub call is the read-only -// ownership check (GET /repos/{owner}/{repo}) at create, shared with the -// legacy route. +// - Nothing here writes to GitHub. The only GitHub calls are the read-only +// ownership checks (GET /repos/{owner}/{repo}, and GET /user for the +// github-user-token proof) at create and PATCH. // - Every write carries an ETag precondition check inside the store lock, so // two operators acting at once get 412, never a silent overwrite. @@ -35,10 +35,9 @@ const ( 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. + // hubV1ProofHubSessionToken is the default ownership proof: the hub checks + // permissions.admin on each repo with the GitHub token stored at hub + // sign-in. The other methods are in selfservice_v1_proof.go. hubV1ProofHubSessionToken = "hub-session-token" ) @@ -151,7 +150,8 @@ func (s *HubServer) handleHubV1Discovery(w http.ResponseWriter, r *http.Request) "expiry": selfServiceExpiry().String(), "key_rotation_overlap": selfServiceKeyRotationOverlap.String(), }, - "proof_methods": []string{hubV1ProofHubSessionToken}, + "proof_methods": hubV1ProofMethods(), + "proof_method_details": hubV1ProofMethodDetails(), }) } diff --git a/src/pkg/hub/selfservice_v1_patch.go b/src/pkg/hub/selfservice_v1_patch.go index 4ca649ac53..ae7940f359 100644 --- a/src/pkg/hub/selfservice_v1_patch.go +++ b/src/pkg/hub/selfservice_v1_patch.go @@ -15,7 +15,8 @@ package hub // - If-Match is required (428 when absent, 412 when stale). The precondition // is checked before any GitHub call and again inside the store lock. // - Only repos the edit ADDS are proven (the same read-only -// GET /repos/{owner}/{repo} as create, with the owner's stored token). +// GET /repos/{owner}/{repo} as create, with the owner's stored token or, +// when the request picks github-user-token, the token it carries). // Repos that stay keep their proof time; removed repos lose theirs. // - org, the owner, the ID, the keys and every timestamp are not editable: // a body naming any other field is a 400, and the store restores them @@ -266,6 +267,10 @@ func (s *HubServer) handleHubV1Patch(w http.ResponseWriter, r *http.Request) { s.writeHubV1Stale(w, h.ID) return } + proof, ok := hubV1ReadProof(w, r) + if !ok { + return + } data, err := io.ReadAll(io.LimitReader(r.Body, selfServiceRequestBodyLimit())) if err != nil { writeJSONError(w, http.StatusBadRequest, "could not read the request body") @@ -287,7 +292,7 @@ func (s *HubServer) handleHubV1Patch(w http.ResponseWriter, r *http.Request) { writeJSONError(w, http.StatusUnauthorized, "not authenticated") return } - if !s.selfServiceProveOwnership(w, r, login, h.ID, user, plan.added) { + if !s.hubV1ProveOwnership(w, r, login, h.ID, user, plan.added, proof) { return } } diff --git a/src/pkg/hub/selfservice_v1_proof.go b/src/pkg/hub/selfservice_v1_proof.go new file mode 100644 index 0000000000..9123b0574d --- /dev/null +++ b/src/pkg/hub/selfservice_v1_proof.go @@ -0,0 +1,379 @@ +package hub + +// Hub registration protocol v1, rollout step 2: ownership proof methods chosen +// per request (hivecommons/hive#18642, #19056, #19238). +// +// A v1 create or PATCH picks its proof with the X-Hive-Proof-Method header. +// Without it the hub proves ownership as before (hub-session-token: the +// GitHub token stored at hub sign-in). With +// +// X-Hive-Proof-Method: github-user-token +// X-Hive-Proof-Token: +// +// the hub proves ownership with the token sent on THIS request only. That is +// the RFC's fix for orgs that restrict OAuth apps: the sign-in requests no +// scope, so GitHub hides the admin role from the stored token, while a token +// the user makes with the scopes the repos need shows it. +// +// Invariants: +// - Off by default. github-user-token is accepted and advertised only while +// HIVE_HUB_PROOF_GITHUB_USER_TOKEN is on (and the registration API itself +// is on). With it off, asking for the method is a 400 that lists what the +// hub offers, never a silent fallback to the stored token. +// - The per-request token is used for the reads below and then dropped. It +// is never stored, logged, echoed in a response or compared with the +// stored sign-in token, and the stored token stays scopeless. +// - The token must belong to the signed-in GitHub account (GET /user), so a +// token someone else made cannot prove ownership for this login. +// - Read-only: GET /user and GET /repos/{owner}/{repo}. Nothing writes to +// GitHub. +// - Every refusal names the repo, the method and a reason code, and tells +// apart "the token cannot see the admin role" from "you are not an admin". +// - The v6 /api/hub/selfservice routes never read these headers. +// +// The RFC's other methods are not offered here: repo-file is deferred by the +// owner decision on #18642, and github-app-installation needs the hub's App +// installation lookup, which is a separate change. + +import ( + "context" + "encoding/json" + "fmt" + "io" + "net/http" + "net/url" + "os" + "strings" + "unicode" +) + +const ( + // hubV1ProofGitHubUserToken proves ownership with a GitHub token the + // caller sends on the request. + hubV1ProofGitHubUserToken = "github-user-token" + // hubV1ProofGitHubUserTokenEnv turns the github-user-token proof on. + hubV1ProofGitHubUserTokenEnv = "HIVE_HUB_PROOF_GITHUB_USER_TOKEN" + + // hubV1ProofMethodHeader picks the proof method for one request. + hubV1ProofMethodHeader = "X-Hive-Proof-Method" + // hubV1ProofTokenHeader carries the github-user-token token. It is a + // header, not a body field, so it never lands in a stored or echoed body. + hubV1ProofTokenHeader = "X-Hive-Proof-Token" + // hubV1ProofTokenMaxLen bounds the token header. GitHub tokens are far + // shorter; anything longer is not one. + hubV1ProofTokenMaxLen = 255 + + // hubV1ScopeRepo is the classic OAuth scope GitHub needs to show a private + // repo, and the caller's role on it, to a token. + hubV1ScopeRepo = "repo" +) + +// Reason codes in a github-user-token refusal body and its audit line. +const ( + hubV1ProofReasonTokenRejected = "token_rejected" + hubV1ProofReasonTokenUser = "token_user_mismatch" + hubV1ProofReasonSSO = "sso_not_authorized" + hubV1ProofReasonRepoNotVisible = "repo_not_visible" + hubV1ProofReasonMissingScope = "missing_scope" + hubV1ProofReasonRoleNotVisible = "admin_role_not_visible" + hubV1ProofReasonNotAdmin = "not_admin" + selfServiceRefusedProofTokenFail = "proof_token_refused" +) + +// hubV1Proof is the proof method a request picked. The zero value is the +// hub-session-token proof. +type hubV1Proof struct { + method string + token string +} + +func hubV1GitHubUserTokenEnabled() bool { + switch strings.ToLower(strings.TrimSpace(os.Getenv(hubV1ProofGitHubUserTokenEnv))) { + case "1", "true", "yes", "on": + return true + } + return false +} + +// hubV1ProofMethods is the proof methods this hub accepts right now, in the +// order discovery lists them. +func hubV1ProofMethods() []string { + methods := []string{hubV1ProofHubSessionToken} + if hubV1GitHubUserTokenEnabled() { + methods = append(methods, hubV1ProofGitHubUserToken) + } + return methods +} + +// hubV1ProofMethodInfo is one discovery entry describing how to use a method. +type hubV1ProofMethodInfo struct { + Name string `json:"name"` + Description string `json:"description"` + // Headers are the request headers the method reads. + Headers []string `json:"headers,omitempty"` + // Scopes are the classic OAuth scopes a github-user-token needs. + Scopes *hubV1ProofScopes `json:"scopes,omitempty"` +} + +// hubV1ProofScopes says, per kind of repo, which classic OAuth scopes the +// per-request token needs. A fine-grained token needs read access to the +// repos (the Metadata permission) instead. +type hubV1ProofScopes struct { + PublicRepos []string `json:"public_repos"` + PrivateRepos []string `json:"private_repos"` + FineGrained string `json:"fine_grained"` +} + +func hubV1ProofMethodDetails() []hubV1ProofMethodInfo { + details := []hubV1ProofMethodInfo{{ + Name: hubV1ProofHubSessionToken, + Description: "the default: the hub checks your admin role on each repo with the GitHub sign-in it already holds", + }} + if hubV1GitHubUserTokenEnabled() { + details = append(details, hubV1ProofMethodInfo{ + Name: hubV1ProofGitHubUserToken, + Description: "send a GitHub token of your own on this request; the hub reads your admin role with it and does not store it", + Headers: []string{hubV1ProofMethodHeader, hubV1ProofTokenHeader}, + Scopes: &hubV1ProofScopes{ + PublicRepos: []string{}, + PrivateRepos: []string{hubV1ScopeRepo}, + FineGrained: "read access (Metadata) to every repo in the request", + }, + }) + } + return details +} + +// writeHubV1ProofMethodError is the 400 for a proof method the hub does not +// accept, listing the ones it does. +func writeHubV1ProofMethodError(w http.ResponseWriter, msg string) { + writeHubV1JSON(w, http.StatusBadRequest, "", map[string]any{ + "error": msg, + "proof_methods": hubV1ProofMethods(), + }) +} + +// hubV1ReadProof reads the proof method a v1 write asked for. It writes the +// refusal itself and returns ok=false when the request is not usable. It makes +// no GitHub call. +func hubV1ReadProof(w http.ResponseWriter, r *http.Request) (hubV1Proof, bool) { + method := strings.ToLower(strings.TrimSpace(r.Header.Get(hubV1ProofMethodHeader))) + token := r.Header.Get(hubV1ProofTokenHeader) + switch method { + case "", hubV1ProofHubSessionToken: + if token != "" { + writeHubV1ProofMethodError(w, fmt.Sprintf("%s is read only with %s: %s; send that header too, or drop the token", hubV1ProofTokenHeader, hubV1ProofMethodHeader, hubV1ProofGitHubUserToken)) + return hubV1Proof{}, false + } + return hubV1Proof{method: hubV1ProofHubSessionToken}, true + case hubV1ProofGitHubUserToken: + if !hubV1GitHubUserTokenEnabled() { + writeHubV1ProofMethodError(w, fmt.Sprintf("this hub does not offer the %s proof", hubV1ProofGitHubUserToken)) + return hubV1Proof{}, false + } + token = strings.TrimSpace(token) + if token == "" { + writeHubV1ProofMethodError(w, fmt.Sprintf("the %s proof needs a GitHub token in %s", hubV1ProofGitHubUserToken, hubV1ProofTokenHeader)) + return hubV1Proof{}, false + } + if !hubV1PlausibleToken(token) { + // The token is never echoed, not even in a refusal. + writeHubV1ProofMethodError(w, fmt.Sprintf("%s does not hold a GitHub token", hubV1ProofTokenHeader)) + return hubV1Proof{}, false + } + return hubV1Proof{method: hubV1ProofGitHubUserToken, token: token}, true + default: + writeHubV1ProofMethodError(w, fmt.Sprintf("unknown proof method in %s; this hub accepts %s", hubV1ProofMethodHeader, strings.Join(hubV1ProofMethods(), ", "))) + return hubV1Proof{}, false + } +} + +// hubV1PlausibleToken rejects header values that cannot be a GitHub token +// before any of them reaches GitHub. +func hubV1PlausibleToken(token string) bool { + if len(token) > hubV1ProofTokenMaxLen { + return false + } + for _, c := range token { + if c > unicode.MaxASCII || unicode.IsSpace(c) || unicode.IsControl(c) { + return false + } + } + return true +} + +// hubV1ProveOwnership proves login administers every repo in repos with the +// method proof names. It writes the refusal itself and returns false when any +// repo fails. +func (s *HubServer) hubV1ProveOwnership(w http.ResponseWriter, r *http.Request, login, id string, user *SaaSUser, repos []string, proof hubV1Proof) bool { + if proof.method != hubV1ProofGitHubUserToken { + return s.selfServiceProveOwnership(w, r, login, id, user, repos) + } + return s.hubV1ProveWithUserToken(w, r, login, id, user, repos, proof.token) +} + +// hubV1TokenUser is what GET /user said about a per-request token. +type hubV1TokenUser struct { + status int + login string + scopes []string + scopesKnown bool +} + +// tokenUser asks GitHub whose token this is. A 401 or 403 is a result, not an +// error; any other non-2xx is an error, reported by status only. +func (c *selfServiceOwnershipChecker) tokenUser(ctx context.Context, token string) (hubV1TokenUser, error) { + var res hubV1TokenUser + u, err := url.JoinPath(c.apiBase, "user") + if err != nil { + return res, fmt.Errorf("build GitHub user URL: %w", err) + } + req, err := http.NewRequestWithContext(ctx, http.MethodGet, u, nil) + if err != nil { + return res, fmt.Errorf("build GitHub token check: %w", err) + } + req.Header.Set("Authorization", "Bearer "+token) + req.Header.Set("Accept", "application/vnd.github+json") + resp, err := c.client.Do(req) + if err != nil { + return res, fmt.Errorf("GitHub token check failed: %w", err) + } + defer func() { _ = resp.Body.Close() }() + res.status = resp.StatusCode + res.scopes, res.scopesKnown = selfServiceTokenScopes(resp.Header) + if resp.StatusCode == http.StatusUnauthorized || resp.StatusCode == http.StatusForbidden { + _, _ = io.Copy(io.Discard, io.LimitReader(resp.Body, selfServiceOwnershipErrorBodyLimit)) + return res, nil + } + if resp.StatusCode < http.StatusOK || resp.StatusCode >= http.StatusMultipleChoices { + _, _ = io.Copy(io.Discard, io.LimitReader(resp.Body, selfServiceOwnershipErrorBodyLimit)) + return res, fmt.Errorf("GitHub token check returned HTTP %d", resp.StatusCode) + } + var payload struct { + Login string `json:"login"` + } + if err := json.NewDecoder(io.LimitReader(resp.Body, 1<<20)).Decode(&payload); err != nil { + return res, fmt.Errorf("decode GitHub token check: %w", err) + } + res.login = strings.TrimSpace(payload.Login) + return res, nil +} + +// hubV1ProofRefusal is the body of a failed github-user-token proof. +type hubV1ProofRefusal struct { + Error string `json:"error"` + ProofMethod string `json:"proof_method"` + Reason string `json:"reason"` + Repo string `json:"repo,omitempty"` + RequiredScopes []string `json:"required_scopes,omitempty"` + // GrantedScopes is set only when GitHub reported the token's scopes. + GrantedScopes []string `json:"granted_scopes,omitempty"` +} + +func (s *HubServer) writeHubV1ProofRefusal(w http.ResponseWriter, login, id string, status int, body hubV1ProofRefusal) { + body.ProofMethod = hubV1ProofGitHubUserToken + extra := []any{"proof_method", hubV1ProofGitHubUserToken, "proof_reason", body.Reason} + if body.Repo != "" { + extra = append(extra, "repo", body.Repo) + } + s.auditSelfServiceRefused(login, id, selfServiceRefusedProofTokenFail, extra...) + writeHubV1JSON(w, status, "", body) +} + +// hubV1ProveWithUserToken is the github-user-token proof: the token must be +// the signed-in GitHub account's, and must show permissions.admin on every +// repo. +func (s *HubServer) hubV1ProveWithUserToken(w http.ResponseWriter, r *http.Request, login, id string, user *SaaSUser, repos []string, token string) bool { + githubLogin := topRepoProfileLogin(user) + if githubLogin == "" { + s.auditSelfServiceRefused(login, id, selfServiceRefusedNoGitHubLogin) + writeJSONError(w, http.StatusBadRequest, "a GitHub identity is required to register a self-hosted hive") + return false + } + checker := s.ownershipChecker() + who, err := checker.tokenUser(r.Context(), token) + if err != nil { + s.auditSelfServiceRefused(login, id, selfServiceRefusedOwnershipError, "proof_method", hubV1ProofGitHubUserToken) + s.logger.Warn("self-service registration: token check failed", "user", login, "hive", id, "proof_method", hubV1ProofGitHubUserToken, "error", err) + writeJSONError(w, http.StatusBadGateway, "could not check the token in "+hubV1ProofTokenHeader+" with GitHub; try again") + return false + } + if who.status == http.StatusUnauthorized || who.status == http.StatusForbidden || who.login == "" { + s.writeHubV1ProofRefusal(w, login, id, http.StatusForbidden, hubV1ProofRefusal{ + Error: "GitHub rejected the token in " + hubV1ProofTokenHeader + " (expired, revoked or mistyped); make a new token and retry", + Reason: hubV1ProofReasonTokenRejected, + }) + return false + } + if !strings.EqualFold(who.login, githubLogin) { + // Neither login is the secret; naming the signed-in one helps the + // caller see which account the token must come from. + s.writeHubV1ProofRefusal(w, login, id, http.StatusForbidden, hubV1ProofRefusal{ + Error: fmt.Sprintf("the token in %s belongs to a different GitHub account; make it while signed in to GitHub as %s", hubV1ProofTokenHeader, githubLogin), + Reason: hubV1ProofReasonTokenUser, + }) + return false + } + + for _, repo := range repos { + owner, name, _ := strings.Cut(repo, "/") + res, err := checker.repoAdminDetail(r.Context(), token, owner, name) + if err != nil { + s.auditSelfServiceRefused(login, id, selfServiceRefusedOwnershipError, "repo", repo, "proof_method", hubV1ProofGitHubUserToken) + s.logger.Warn("self-service registration: ownership check failed", "user", login, "hive", id, "repo", repo, "proof_method", hubV1ProofGitHubUserToken, "error", err) + writeJSONError(w, http.StatusBadGateway, fmt.Sprintf("could not verify your permission on %s; try again", repo)) + return false + } + if res.admin { + continue + } + status, body := hubV1UserTokenRefusal(repo, res) + s.writeHubV1ProofRefusal(w, login, id, status, body) + return false + } + s.logger.Info("audit: selfservice_ownership_proven", "user", login, "hive", id, "proof_method", hubV1ProofGitHubUserToken, "repos", len(repos)) + return true +} + +// hubV1UserTokenRefusal turns a failed ownership read into a refusal that says +// why it failed. It never includes anything GitHub sent back except the +// token's scope names. +func hubV1UserTokenRefusal(repo string, res selfServiceRepoAdminResult) (int, hubV1ProofRefusal) { + body := hubV1ProofRefusal{Repo: repo} + if res.scopesKnown { + body.GrantedScopes = res.scopes + } + switch { + case res.status == http.StatusUnauthorized: + body.Reason = hubV1ProofReasonTokenRejected + body.Error = "GitHub rejected the token in " + hubV1ProofTokenHeader + " (expired, revoked or mistyped); make a new token and retry" + case res.status == http.StatusForbidden && res.ssoRequired: + body.Reason = hubV1ProofReasonSSO + body.Error = fmt.Sprintf("the token is not authorized for the single sign-on of the org that owns %s; authorize it for that org on GitHub and retry", repo) + case res.status == http.StatusForbidden || res.status == http.StatusNotFound: + if res.scopesKnown && !hubV1HasScope(res.scopes, hubV1ScopeRepo) { + body.Reason = hubV1ProofReasonMissingScope + body.RequiredScopes = []string{hubV1ScopeRepo} + body.Error = fmt.Sprintf("the token cannot see %s; a private repo needs a token with the %s scope", repo, hubV1ScopeRepo) + } else { + body.Reason = hubV1ProofReasonRepoNotVisible + body.Error = fmt.Sprintf("the token cannot see %s; check the repo name and that the token has access to it (a fine-grained token must list the repo)", repo) + } + case !res.permissionsReported: + body.Reason = hubV1ProofReasonRoleNotVisible + body.Error = fmt.Sprintf("the token can see %s but GitHub did not show your role on it (is the org restricting access for this token?)", repo) + default: + body.Reason = hubV1ProofReasonNotAdmin + body.Error = fmt.Sprintf("your GitHub account is not an admin of %s", repo) + } + return http.StatusForbidden, body +} + +func hubV1HasScope(scopes []string, want string) bool { + for _, scope := range scopes { + if strings.EqualFold(scope, want) { + return true + } + } + return false +} diff --git a/src/pkg/hub/selfservice_v1_proof_test.go b/src/pkg/hub/selfservice_v1_proof_test.go new file mode 100644 index 0000000000..33f139722a --- /dev/null +++ b/src/pkg/hub/selfservice_v1_proof_test.go @@ -0,0 +1,358 @@ +package hub + +import ( + "encoding/json" + "net/http" + "net/http/httptest" + "reflect" + "strings" + "sync/atomic" + "testing" +) + +// Tests for the github-user-token ownership proof (#18642, #19056, #19238). +// They reuse the v1 test env but swap its GitHub stub for one that knows +// several per-request tokens as well as the stored sign-in token. + +const ( + proofTestGoodToken = "ghp_proof_good_do_not_leak" + proofTestNoScopeToken = "ghp_proof_noscope_do_not_leak" + proofTestFineToken = "github_pat_proof_fine_do_not_leak" + proofTestBobToken = "ghp_proof_bob_do_not_leak" + proofTestDeadToken = "ghp_proof_revoked_do_not_leak" +) + +// proofStub answers like GitHub for the tokens above. alice/orgrepo is the +// restricted-OAuth-org case: the stored sign-in token sees the repo but not +// its permissions, while the per-request token sees admin. +type proofStub struct { + calls atomic.Int64 + writes atomic.Int64 +} + +func (p *proofStub) serve(w http.ResponseWriter, r *http.Request) { + p.calls.Add(1) + if r.Method != http.MethodGet { + p.writes.Add(1) + w.WriteHeader(http.StatusMethodNotAllowed) + return + } + token := strings.TrimPrefix(r.Header.Get("Authorization"), "Bearer ") + type identity struct { + login string + scopes *string + } + repoScope, noScope := "repo, read:org", "" + tokens := map[string]identity{ + selfServiceTestToken: {login: selfServiceTestUser, scopes: &noScope}, + proofTestGoodToken: {login: selfServiceTestUser, scopes: &repoScope}, + proofTestNoScopeToken: {login: selfServiceTestUser, scopes: &noScope}, + proofTestFineToken: {login: selfServiceTestUser}, + proofTestBobToken: {login: selfServiceTestOther, scopes: &repoScope}, + } + id, ok := tokens[token] + if !ok { + w.WriteHeader(http.StatusUnauthorized) + return + } + if id.scopes != nil { + w.Header().Set("X-OAuth-Scopes", *id.scopes) + } + w.Header().Set("Content-Type", "application/json") + if r.URL.Path == "/user" { + _ = json.NewEncoder(w).Encode(map[string]any{"login": id.login}) + return + } + repo := strings.TrimPrefix(r.URL.Path, "/repos/") + perms := func(admin bool) { + _ = json.NewEncoder(w).Encode(map[string]any{"full_name": repo, "permissions": map[string]bool{"admin": admin}}) + } + switch { + case token == selfServiceTestToken: + switch repo { + case "alice/lab", "alice/tools": + perms(true) + case "alice/orgrepo": + _ = json.NewEncoder(w).Encode(map[string]any{"full_name": repo}) + default: + w.WriteHeader(http.StatusNotFound) + } + case token == proofTestGoodToken || token == proofTestBobToken: + switch repo { + case "alice/lab", "alice/tools", "alice/orgrepo": + perms(true) + case "alice/readonly": + perms(false) + case "alice/restricted": + _ = json.NewEncoder(w).Encode(map[string]any{"full_name": repo}) + case "alice/sso": + w.Header().Set("X-GitHub-SSO", "required; url=https://github.com/orgs/x/sso") + w.WriteHeader(http.StatusForbidden) + case "alice/broken": + w.WriteHeader(http.StatusInternalServerError) + default: + w.WriteHeader(http.StatusNotFound) + } + default: + // The no-scope and fine-grained tokens see no private repo. + w.WriteHeader(http.StatusNotFound) + } +} + +func newProofTestEnv(t *testing.T, enabled bool) (*selfServiceTestEnv, *proofStub) { + t.Helper() + env := newHubV1TestEnv(t) + if enabled { + t.Setenv(hubV1ProofGitHubUserTokenEnv, "true") + } else { + t.Setenv(hubV1ProofGitHubUserTokenEnv, "") + } + stub := &proofStub{} + srv := httptest.NewServer(http.HandlerFunc(stub.serve)) + t.Cleanup(srv.Close) + env.s.selfServiceOwnership = &selfServiceOwnershipChecker{apiBase: srv.URL, client: srv.Client()} + return env, stub +} + +func proofHeaders(token string) map[string]string { + return map[string]string{hubV1ProofMethodHeader: hubV1ProofGitHubUserToken, hubV1ProofTokenHeader: token} +} + +func (env *selfServiceTestEnv) v1Create(t *testing.T, body string, headers map[string]string) *httptest.ResponseRecorder { + t.Helper() + return env.v1(t, selfServiceTestUser, http.MethodPost, hubV1BasePath+"/registrations", body, headers, env.s.handleHubV1Create) +} + +func decodeProofRefusal(t *testing.T, rec *httptest.ResponseRecorder) hubV1ProofRefusal { + t.Helper() + var body hubV1ProofRefusal + if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil { + t.Fatalf("refusal is not JSON: %q", rec.Body.String()) + } + return body +} + +const proofOrgRepoBody = `{"name":"Lab","org":"alice","repos":["alice/lab","alice/orgrepo"]}` + +func TestHubV1DiscoveryAdvertisesUserTokenOnlyWhenEnabled(t *testing.T) { + for _, enabled := range []bool{false, true} { + env, _ := newProofTestEnv(t, enabled) + rec := httptest.NewRecorder() + env.s.handleHubV1Discovery(rec, httptest.NewRequest(http.MethodGet, hubV1BasePath, nil)) + var d struct { + ProofMethods []string `json:"proof_methods"` + Details []hubV1ProofMethodInfo `json:"proof_method_details"` + } + if err := json.Unmarshal(rec.Body.Bytes(), &d); err != nil { + t.Fatal(err) + } + want := []string{hubV1ProofHubSessionToken} + if enabled { + want = append(want, hubV1ProofGitHubUserToken) + } + if !reflect.DeepEqual(d.ProofMethods, want) || len(d.Details) != len(want) { + t.Fatalf("enabled=%v: proof_methods %v, %d details", enabled, d.ProofMethods, len(d.Details)) + } + if !enabled { + continue + } + ut := d.Details[1] + if ut.Name != hubV1ProofGitHubUserToken || ut.Scopes == nil || + !reflect.DeepEqual(ut.Scopes.PrivateRepos, []string{"repo"}) || len(ut.Scopes.PublicRepos) != 0 || + !reflect.DeepEqual(ut.Headers, []string{hubV1ProofMethodHeader, hubV1ProofTokenHeader}) { + t.Fatalf("github-user-token details = %+v", ut) + } + } +} + +func TestHubV1UserTokenProvesWhatTheStoredTokenCannot(t *testing.T) { + env, stub := newProofTestEnv(t, true) + + // The stored sign-in token cannot see the role on alice/orgrepo. + rec := env.v1Create(t, proofOrgRepoBody, nil) + if rec.Code != http.StatusForbidden { + t.Fatalf("stored-token proof: %d %s", rec.Code, rec.Body.String()) + } + + rec = env.v1Create(t, proofOrgRepoBody, proofHeaders(proofTestGoodToken)) + if rec.Code != http.StatusCreated { + t.Fatalf("github-user-token proof: %d %s", rec.Code, rec.Body.String()) + } + view := decodeV1Registration(t, rec) + if view.ID != hubV1TestID || len(view.RepoProofs) != 2 || view.RepoProofs[1].CheckedAt.IsZero() { + t.Fatalf("registration = %+v", view) + } + stored, _ := env.s.selfService.get(hubV1TestID) + raw, _ := json.Marshal(stored) + for where, text := range map[string]string{"response": rec.Body.String(), "logs": env.logs.String(), "store": string(raw)} { + if strings.Contains(text, proofTestGoodToken) { + t.Fatalf("the per-request token leaked into the %s", where) + } + } + if !strings.Contains(env.logs.String(), "proof_method=github-user-token") { + t.Fatal("the proof method is not in the audit log") + } + if stub.writes.Load() != 0 { + t.Fatal("the proof sent a non-GET request to GitHub") + } +} + +func TestHubV1UserTokenOnPatchProvesOnlyAddedRepos(t *testing.T) { + env, stub := newProofTestEnv(t, true) + id, key := env.registerHappy(t) + etag := env.etagOf(t, id) + + if rec := env.v1Patch(t, selfServiceTestUser, id, etag, `{"repos":{"add":["alice/orgrepo"]}}`); rec.Code != http.StatusForbidden { + t.Fatalf("stored-token PATCH: %d %s", rec.Code, rec.Body.String()) + } + before := stub.calls.Load() + headers := proofHeaders(proofTestGoodToken) + headers["If-Match"] = etag + rec := env.v1(t, selfServiceTestUser, http.MethodPatch, hubV1BasePath+"/registrations/"+id, `{"repos":{"add":["alice/orgrepo"]}}`, headers, env.s.handleHubV1Patch) + if rec.Code != http.StatusOK { + t.Fatalf("github-user-token PATCH: %d %s", rec.Code, rec.Body.String()) + } + // One GET /user and one GET /repos for the single added repo. + if got := stub.calls.Load() - before; got != 2 { + t.Fatalf("GitHub calls = %d, want 2", got) + } + if _, ok := env.s.verifyHeartbeatBearerGeneration(key, id); !ok { + t.Fatal("the registration key stopped authenticating") + } + if strings.Contains(env.logs.String(), proofTestGoodToken) { + t.Fatal("the per-request token leaked into the logs") + } +} + +func TestHubV1ProofMethodRequestRefusals(t *testing.T) { + cases := []struct { + name string + enabled bool + headers map[string]string + want string + }{ + {"flag off", false, proofHeaders(proofTestGoodToken), "does not offer"}, + {"unknown method", true, map[string]string{hubV1ProofMethodHeader: "repo-file"}, "unknown proof method"}, + {"token without method", true, map[string]string{hubV1ProofTokenHeader: proofTestGoodToken}, "is read only with"}, + {"method without token", true, map[string]string{hubV1ProofMethodHeader: hubV1ProofGitHubUserToken}, "needs a GitHub token"}, + {"implausible token", true, proofHeaders("ghp_has a space"), "does not hold a GitHub token"}, + {"overlong token", true, proofHeaders(strings.Repeat("a", hubV1ProofTokenMaxLen+1)), "does not hold a GitHub token"}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + env, stub := newProofTestEnv(t, tc.enabled) + rec := env.v1Create(t, selfServiceHappyBody, tc.headers) + var body struct { + Error string `json:"error"` + ProofMethods []string `json:"proof_methods"` + } + _ = json.Unmarshal(rec.Body.Bytes(), &body) + if rec.Code != http.StatusBadRequest || !strings.Contains(body.Error, tc.want) || len(body.ProofMethods) == 0 { + t.Fatalf("%d %s, want 400 containing %q and the offered methods", rec.Code, rec.Body.String(), tc.want) + } + if tok := tc.headers[hubV1ProofTokenHeader]; tok != "" && strings.Contains(rec.Body.String(), tok) { + t.Fatal("the refusal echoed the token") + } + if stub.calls.Load() != 0 { + t.Fatal("a refused proof request reached GitHub") + } + if _, ok := env.s.selfService.get(hubV1TestID); ok { + t.Fatal("a refused proof request stored a registration") + } + }) + } +} + +func TestHubV1UserTokenRefusalsSayWhy(t *testing.T) { + cases := []struct { + name string + token string + repo string + status int + reason string + want string + wantRequired []string + wantGranted []string + grantedAbsent bool + }{ + {"revoked token", proofTestDeadToken, "alice/lab", http.StatusForbidden, hubV1ProofReasonTokenRejected, "GitHub rejected the token", nil, nil, true}, + {"someone else's token", proofTestBobToken, "alice/lab", http.StatusForbidden, hubV1ProofReasonTokenUser, "different GitHub account", nil, nil, true}, + {"not an admin", proofTestGoodToken, "alice/readonly", http.StatusForbidden, hubV1ProofReasonNotAdmin, "not an admin of alice/readonly", nil, []string{"repo", "read:org"}, false}, + {"role hidden by the org", proofTestGoodToken, "alice/restricted", http.StatusForbidden, hubV1ProofReasonRoleNotVisible, "did not show your role", nil, []string{"repo", "read:org"}, false}, + {"sso not authorized", proofTestGoodToken, "alice/sso", http.StatusForbidden, hubV1ProofReasonSSO, "single sign-on", nil, []string{"repo", "read:org"}, false}, + {"missing repo scope", proofTestNoScopeToken, "alice/lab", http.StatusForbidden, hubV1ProofReasonMissingScope, "needs a token with the repo scope", []string{"repo"}, nil, true}, + {"fine-grained token without the repo", proofTestFineToken, "alice/lab", http.StatusForbidden, hubV1ProofReasonRepoNotVisible, "must list the repo", nil, nil, true}, + {"unknown repo with full scopes", proofTestGoodToken, "alice/nowhere", http.StatusForbidden, hubV1ProofReasonRepoNotVisible, "cannot see alice/nowhere", nil, []string{"repo", "read:org"}, false}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + env, _ := newProofTestEnv(t, true) + rec := env.v1Create(t, `{"name":"Lab","repos":["`+tc.repo+`"]}`, proofHeaders(tc.token)) + body := decodeProofRefusal(t, rec) + if rec.Code != tc.status || body.Reason != tc.reason || !strings.Contains(body.Error, tc.want) || body.ProofMethod != hubV1ProofGitHubUserToken { + t.Fatalf("%d %s, want %d reason %q containing %q", rec.Code, rec.Body.String(), tc.status, tc.reason, tc.want) + } + if !reflect.DeepEqual(body.RequiredScopes, tc.wantRequired) { + t.Fatalf("required_scopes = %v, want %v", body.RequiredScopes, tc.wantRequired) + } + if tc.grantedAbsent && body.GrantedScopes != nil { + t.Fatalf("granted_scopes = %v, want absent", body.GrantedScopes) + } + if !tc.grantedAbsent && !reflect.DeepEqual(body.GrantedScopes, tc.wantGranted) { + t.Fatalf("granted_scopes = %v, want %v", body.GrantedScopes, tc.wantGranted) + } + if strings.Contains(rec.Body.String(), tc.token) || strings.Contains(env.logs.String(), tc.token) { + t.Fatal("the token leaked into the refusal or the logs") + } + if !strings.Contains(env.logs.String(), "proof_reason="+tc.reason) { + t.Fatal("the refusal reason is not audited") + } + if _, ok := env.s.selfService.get(hubV1TestID); ok { + t.Fatal("a failed proof stored a registration") + } + }) + } +} + +func TestHubV1UserTokenGitHubErrorIsBadGateway(t *testing.T) { + env, _ := newProofTestEnv(t, true) + rec := env.v1Create(t, `{"name":"Lab","repos":["alice/broken"]}`, proofHeaders(proofTestGoodToken)) + if rec.Code != http.StatusBadGateway || !strings.Contains(rec.Body.String(), "try again") { + t.Fatalf("%d %s", rec.Code, rec.Body.String()) + } +} + +func TestHubV6RouteIgnoresProofHeaders(t *testing.T) { + env, _ := newProofTestEnv(t, true) + req := httptest.NewRequest(http.MethodPost, "/api/hub/selfservice/hives", strings.NewReader(proofOrgRepoBody)) + req.Header.Set("Origin", selfServiceTestOrigin) + for k, v := range proofHeaders(proofTestGoodToken) { + req.Header.Set(k, v) + } + req.AddCookie(&http.Cookie{ + Name: "hive_hub_user", + Value: mintHubUserCookieValueV2(deriveDomainKey(grantableTestSecret, infoSessionEd25519Seed), selfServiceTestUser), + }) + rec := httptest.NewRecorder() + env.s.requireAuth(env.s.handleSelfServiceRegister)(rec, req) + // The legacy route proves with the stored token, which cannot see the + // role on alice/orgrepo, and keeps its pinned not-admin body. + if rec.Code != http.StatusForbidden || decodeError(t, rec)["error"] != "your GitHub account is not an admin of alice/orgrepo" { + t.Fatalf("%d %s", rec.Code, rec.Body.String()) + } +} + +func TestSelfServiceTokenScopes(t *testing.T) { + h := http.Header{} + if scopes, known := selfServiceTokenScopes(h); known || scopes != nil { + t.Fatalf("absent header: %v %v", scopes, known) + } + h.Set("X-OAuth-Scopes", "") + if scopes, known := selfServiceTokenScopes(h); !known || len(scopes) != 0 { + t.Fatalf("empty header: %v %v", scopes, known) + } + h.Set("X-OAuth-Scopes", " repo, read:org ,") + if scopes, known := selfServiceTokenScopes(h); !known || !reflect.DeepEqual(scopes, []string{"repo", "read:org"}) { + t.Fatalf("scopes: %v %v", scopes, known) + } +}