Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/security-14598-hub-login-pkce-contract.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- The Hub's GitHub browser-login contract tests now cover PKCE end to end ([#14598](https://github.com/hivecommons/hive/issues/14598)). The tests check that the authorize redirect carries the S256 challenge of the `hive_oauth_pkce` cookie and that the token exchange sends that exact `code_verifier` in the form body. A missing, expired, malformed or truncated verifier must fail with `400` before the code is redeemed. A verifier GitHub rejects must not create a session or user record. The verifier must never appear in a request URL or the logs. `src/docs/hub-login-token.md` now documents the PKCE step and the fail-closed behavior. Login behavior is unchanged.
38 changes: 27 additions & 11 deletions src/docs/hub-login-token.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,16 +8,32 @@ unchanged.

## Flow

1. `startProviderLogin` redirects to GitHub with `scope=` empty, the exact
`redirect_uri` and a `state` nonce (`src/pkg/hub/oauth.go:604`).
2. The callback exchanges the code at `defaultGHTokenURL`
(`src/pkg/hub/oauth.go:47`) in `exchangeGitHubLogin`
(`src/pkg/hub/oauth.go:934`). `client_id`, `client_secret`, `code` and
`redirect_uri` travel in a form-encoded POST body, never in the URL
(`src/pkg/hub/oauth.go:944`). `redirect_uri` is `oauthRedirectURI()`
(`src/pkg/hub/saas_auth.go:371`), the same value as the authorize request.
3. The token is encrypted with `encryptToken` (`src/pkg/hub/saas_crypto.go:34`)
and stored on the user record (`src/pkg/hub/oauth.go:850`).
1. `startProviderLogin` (`src/pkg/hub/oauth.go:564`) redirects to GitHub with
an empty `scope=`, the exact `redirect_uri`, a `state` nonce and an S256
PKCE `code_challenge` (`src/pkg/hub/oauth.go:627`). The state nonce and the
PKCE `code_verifier` each go in their own short-lived HttpOnly, Secure,
SameSite=Lax cookie (`hive_oauth_state` and `hive_oauth_pkce`).
2. `handleOAuthCallback` reads and clears both cookies on every outcome, so
each login transaction is single-use. A missing or mismatched state, or a
missing, malformed or expired verifier, fails closed with `400`. This
happens before the code is redeemed or any session or user record is
written (`src/pkg/hub/oauth.go:744`, `src/pkg/hub/oauth.go:825`). A verifier
that does not match the challenge is rejected by GitHub at exchange time
and surfaces as `502` with no session.
3. The callback exchanges the code at `defaultGHTokenURL`
(`src/pkg/hub/oauth.go:49`) in `exchangeGitHubLogin`
(`src/pkg/hub/oauth.go:975`). `client_id`, `client_secret`, `code`,
`redirect_uri` and `code_verifier` travel in a form-encoded POST body,
never in the URL (`src/pkg/hub/oauth.go:981`). `redirect_uri` is
`oauthRedirectURI()` (`src/pkg/hub/saas_auth.go:371`), the same value as
the authorize request.
4. The token is encrypted with `encryptToken` (`src/pkg/hub/saas_crypto.go:34`)
and stored on the user record (`src/pkg/hub/oauth.go:887`).

`src/pkg/hub/oauth_browser_contract_test.go` and
`src/pkg/hub/oauth_pkce_test.go` pin this contract. They check the request
method, URL and body, the fail-closed matrix, and that no secret, code, token
or verifier appears in a request URL or the logs.

## Consumers of the stored token

Expand All @@ -35,7 +51,7 @@ there.

GitHub OAuth-app user tokens do not expire by default and no refresh token is
issued. The Hub overwrites the stored token on each successful login
(`src/pkg/hub/oauth.go:850`); there is no refresh job and no revocation on
(`src/pkg/hub/oauth.go:887`); there is no refresh job and no revocation on
logout. A token stops working only if the user revokes the app authorization or
GitHub invalidates it.

Expand Down
119 changes: 106 additions & 13 deletions src/pkg/hub/oauth_browser_contract_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,11 @@ import (
"testing"
)

// These tests pin the browser contract already available on v6. The verifier
// rejection matrix and S256 challenge assertions belong alongside these once
// the PKCE implementation (#14633) lands; do not weaken the state checks then.
// These tests pin the end-to-end browser contract of the Hub's GitHub login
// (#14598): state cookie plus S256 PKCE at authorize, a form-POST exchange that
// carries the exact redirect_uri and the cookie's code_verifier, and fail-closed
// rejection before any exchange or session. oauth_pkce_test.go pins the PKCE
// helpers in isolation; do not weaken either set.
func TestGitHubBrowserLoginContract(t *testing.T) {
const (
clientID = "browser-contract-client"
Expand All @@ -32,6 +34,9 @@ func TestGitHubBrowserLoginContract(t *testing.T) {
{"malformed user", `{"access_token":"` + token + `"}`, `{"login":`, http.StatusBadGateway, 1},
{"empty identity", `{"access_token":"` + token + `"}`, `{"login":""}`, http.StatusBadGateway, 1},
{"invalid identity", `{"access_token":"` + token + `"}`, `{"login":"bad login!"}`, http.StatusBadGateway, 1},
// GitHub rejects a code_verifier that does not hash to the challenge
// (a verifier from another login) with an error body and no token.
{"verifier rejected", `{"error":"bad_verification_code","error_description":"The code passed is incorrect or expired."}`, "", http.StatusBadGateway, 0},
} {
t.Run(tc.name, func(t *testing.T) {
cleanup := helperSetupTempDirs(t)
Expand All @@ -41,12 +46,13 @@ func TestGitHubBrowserLoginContract(t *testing.T) {
var logs bytes.Buffer
s := &HubServer{logger: slog.New(slog.NewTextHandler(&logs, &slog.HandlerOptions{Level: slog.LevelDebug})), hubSecret: testHubSecret}
var tokenCalls, userCalls atomic.Int32
var verifier string
fake := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
// Inspect the URL at both endpoints, not just the token exchange.
if r.URL.RawQuery != "" || r.URL.ForceQuery || r.URL.User != nil {
t.Error("GitHub endpoint request must not carry query or URL credentials")
}
for _, value := range []string{secret, code, token} {
for _, value := range []string{secret, code, token, verifier} {
if strings.Contains(r.URL.String(), value) {
t.Error("secret found in GitHub request URL")
}
Expand All @@ -60,7 +66,7 @@ func TestGitHubBrowserLoginContract(t *testing.T) {
if err := r.ParseForm(); err != nil {
t.Errorf("parse form: %v", err)
}
for key, want := range map[string]string{"client_id": clientID, "client_secret": secret, "code": code, "redirect_uri": oauthRedirectURI()} {
for key, want := range map[string]string{"client_id": clientID, "client_secret": secret, "code": code, "redirect_uri": oauthRedirectURI(), "code_verifier": verifier} {
if values := r.PostForm[key]; len(values) != 1 || values[0] != want {
t.Errorf("missing or incorrect token form field %s", key)
}
Expand All @@ -82,7 +88,9 @@ func TestGitHubBrowserLoginContract(t *testing.T) {
defaultGHTokenURL, defaultGHUserURL = fake.URL+"/token", fake.URL+"/user"
defer func() { defaultGHTokenURL, defaultGHUserURL = oldToken, oldUser }()

state, cookies := beginGitHubBrowserContract(t, s)
var state string
var cookies []*http.Cookie
state, verifier, cookies = beginGitHubBrowserContract(t, s)
callbackURL := "/api/auth/callback?" + url.Values{"code": {code}, "state": {state}}.Encode()
req := httptest.NewRequest(http.MethodGet, callbackURL, nil)
for _, cookie := range cookies {
Expand All @@ -94,6 +102,12 @@ func TestGitHubBrowserLoginContract(t *testing.T) {
t.Fatalf("callback status/calls = %d/%d/%d, want %d/1/%d", rec.Code, tokenCalls.Load(), userCalls.Load(), tc.status, tc.userCalls)
}
assertBrowserContractSession(t, rec, tc.status == http.StatusTemporaryRedirect)
if !pkceCookieCleared(rec) {
t.Error("callback must consume the PKCE verifier cookie on every outcome")
}
if tc.status != http.StatusTemporaryRedirect && loadSaaSUser("octocat") != nil {
t.Error("a failed login must not write a user record")
}
if tc.status == http.StatusTemporaryRedirect {
u := loadSaaSUser("octocat")
if u == nil || u.EncryptedToken == "" || u.EncryptedToken == token {
Expand Down Expand Up @@ -121,7 +135,7 @@ func TestGitHubBrowserLoginContract(t *testing.T) {
}
assertBrowserContractSession(t, replay, false)
}
for _, value := range []string{secret, code, token} {
for _, value := range []string{secret, code, token, verifier} {
if strings.Contains(logs.String(), value) {
t.Error("OAuth logger exposed a secret")
}
Expand All @@ -130,7 +144,7 @@ func TestGitHubBrowserLoginContract(t *testing.T) {
}
}

func beginGitHubBrowserContract(t *testing.T, s *HubServer) (string, []*http.Cookie) {
func beginGitHubBrowserContract(t *testing.T, s *HubServer) (state, verifier string, cookies []*http.Cookie) {
t.Helper()
rec := httptest.NewRecorder()
s.startProviderLogin(rec, httptest.NewRequest(http.MethodGet, "/login", nil), s.resolveProvider("github"), "/dashboard")
Expand All @@ -145,16 +159,34 @@ func beginGitHubBrowserContract(t *testing.T, s *HubServer) (string, []*http.Coo
if authorize.Scheme+"://"+authorize.Host+authorize.Path != defaultGHAuthorizeURL || !q.Has("scope") || q.Get("scope") != "" || q.Get("redirect_uri") != oauthRedirectURI() || q.Get("client_id") != s.resolveProvider("github").ClientID {
t.Fatal("incorrect authorize endpoint, scopes, client or redirect URI")
}
for _, c := range rec.Result().Cookies() {
if c.Name == oauthStateCookieName {
cookies = rec.Result().Cookies()
for _, c := range cookies {
switch c.Name {
case oauthStateCookieName:
if c.Value == "" || !strings.HasPrefix(q.Get("state"), c.Value+oauthStateSeparator) || !c.HttpOnly || !c.Secure || c.SameSite != http.SameSiteLaxMode || c.MaxAge <= 0 {
t.Fatal("authorize state must be bound to a short-lived secure browser cookie")
}
return q.Get("state"), rec.Result().Cookies()
state = q.Get("state")
case oauthPKCECookieName:
if !validPKCEVerifier(c.Value) || !c.HttpOnly || !c.Secure || c.SameSite != http.SameSiteLaxMode || c.MaxAge <= 0 || c.MaxAge > int(oauthStateTTL.Seconds()) {
t.Fatal("PKCE verifier must live in a short-lived secure browser cookie")
}
verifier = c.Value
}
}
t.Fatal("authorize did not set a state cookie")
return "", nil
if state == "" {
t.Fatal("authorize did not set a state cookie")
}
if verifier == "" {
t.Fatal("authorize did not set a PKCE verifier cookie")
}
if q.Get("code_challenge_method") != "S256" || q.Get("code_challenge") != pkceS256Challenge(verifier) {
t.Fatal("authorize must send the S256 challenge of the cookie verifier")
}
if strings.Contains(authorize.RawQuery, verifier) {
t.Fatal("the PKCE verifier must never appear in the authorize URL")
}
return state, verifier, cookies
}

func assertBrowserContractSession(t *testing.T, rec *httptest.ResponseRecorder, want bool) {
Expand Down Expand Up @@ -206,3 +238,64 @@ func TestGitHubBrowserStateFailsBeforeExchange(t *testing.T) {
})
}
}

// TestGitHubBrowserVerifierFailsBeforeExchange starts a real login, so the state
// is valid, then presents the callback without a usable PKCE verifier. An
// expired verifier cookie is dropped by the browser and arrives as "missing".
// Each case must be rejected before the code is redeemed.
func TestGitHubBrowserVerifierFailsBeforeExchange(t *testing.T) {
const code = "verifier-rejected-secret-code"
for _, tc := range []struct {
name string
verifier func(issued string) (string, bool)
}{
{"missing or expired", func(string) (string, bool) { return "", false }},
{"empty", func(string) (string, bool) { return "", true }},
{"malformed", func(string) (string, bool) { return "not a verifier", true }},
{"truncated", func(v string) (string, bool) { return v[:42], true }},
} {
t.Run(tc.name, func(t *testing.T) {
cleanup := helperSetupTempDirs(t)
defer cleanup()
var calls atomic.Int32
fake := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
calls.Add(1)
_ = json.NewEncoder(w).Encode(map[string]string{"access_token": "unexpected-token", "login": "octocat"})
}))
defer fake.Close()
oldToken, oldUser := defaultGHTokenURL, defaultGHUserURL
defaultGHTokenURL, defaultGHUserURL = fake.URL+"/token", fake.URL+"/user"
defer func() { defaultGHTokenURL, defaultGHUserURL = oldToken, oldUser }()

var logs bytes.Buffer
s := &HubServer{logger: slog.New(slog.NewTextHandler(&logs, &slog.HandlerOptions{Level: slog.LevelDebug})), hubSecret: testHubSecret}
state, issued, cookies := beginGitHubBrowserContract(t, s)
req := httptest.NewRequest(http.MethodGet, "/api/auth/callback?"+url.Values{"code": {code}, "state": {state}}.Encode(), nil)
for _, c := range cookies {
if c.Name != oauthPKCECookieName {
req.AddCookie(c)
}
}
if v, present := tc.verifier(issued); present {
req.AddCookie(&http.Cookie{Name: oauthPKCECookieName, Value: v})
}
rec := httptest.NewRecorder()
s.handleOAuthCallback(rec, req)
if rec.Code != http.StatusBadRequest || calls.Load() != 0 {
t.Fatalf("status/calls = %d/%d, want 400/0: invalid verifier must fail before token exchange", rec.Code, calls.Load())
}
assertBrowserContractSession(t, rec, false)
if !pkceCookieCleared(rec) {
t.Error("rejected callback must still clear the PKCE cookie")
}
if loadSaaSUser("octocat") != nil {
t.Error("rejected callback must not write a user record")
}
for _, value := range []string{code, issued} {
if strings.Contains(logs.String(), value) {
t.Error("rejected callback leaked the code or verifier to the logger")
}
}
})
}
}
Loading