From fa7a84821e89a713c4a11c8cb05557a9cccb5539 Mon Sep 17 00:00:00 2001 From: Jakub Zych Date: Sat, 21 Nov 2026 09:05:07 +0100 Subject: [PATCH] fix(32.2): WR-01 apply DefaultScopes to offline_access-only authorize requests A request naming only offline_access now gets Options.DefaultScopes (when set) plus offline access instead of a pending request with zero data scopes. The read fallback is only used when the server accepts read; otherwise the request is refused with invalid_scope (RFC 6749 3.3). --- docs/services/oauth-server.md | 2 +- modules/wristband/README.md | 4 +-- modules/wristband/authorize.go | 32 ++++++++++++++++----- modules/wristband/consent_path_test.go | 39 ++++++++++++++++++++++++++ modules/wristband/server.go | 11 +++++--- 5 files changed, 74 insertions(+), 14 deletions(-) diff --git a/docs/services/oauth-server.md b/docs/services/oauth-server.md index d37ccad2..90d1ff01 100644 --- a/docs/services/oauth-server.md +++ b/docs/services/oauth-server.md @@ -106,7 +106,7 @@ The metadata document advertises these paths under the issuer, so mount them at ## Consent -The authorization endpoint sends the browser to `/connect?request=`, or to `wristband.Options.ConsentPath` on the issuer when the application sets one (for a consent page under the admin prefix, for example); an empty path keeps the PHP bytes exactly. A request that names no data scope gets `read`, or `wristband.Options.DefaultScopes` filtered to the accepted scopes when that list leaves anything. That page belongs to the application: it signs the user in, shows what the client asks for and posts the decision to the application's own consent handler, which calls: +The authorization endpoint sends the browser to `/connect?request=`, or to `wristband.Options.ConsentPath` on the issuer when the application sets one (for a consent page under the admin prefix, for example); an empty path keeps the PHP bytes exactly. A request that names no data scope gets `read`, or `wristband.Options.DefaultScopes` filtered to the accepted scopes when that list leaves anything; a server that accepts neither refuses it with `invalid_scope`. With `wristband.Options.DefaultScopes` set, a request that names only `offline_access` gets those scopes too and keeps offline access. That page belongs to the application: it signs the user in, shows what the client asks for and posts the decision to the application's own consent handler, which calls: - `wristband.Server.PendingRequest` to read what to show, as a `wristband.PendingRequestView`, including `wristband.PendingRequestView.OfflineAccess` (the pending row's flag; `offline_access` is not a scope on the view and `wristband.Server.IssueCode` is unchanged); - `wristband.Server.IssueCode` to grant, which returns the redirect URL carrying the code, `iss` and `state`; diff --git a/modules/wristband/README.md b/modules/wristband/README.md index 86e213b8..bc5a47e8 100644 --- a/modules/wristband/README.md +++ b/modules/wristband/README.md @@ -27,7 +27,7 @@ Use cases: - RFC 8414 metadata document (`wristband.Server.Metadata`) advertising the authorize, token and registration endpoints under the issuer, the `authorization_code` and `refresh_token` grants, S256 PKCE and the RFC 9207 `iss` response parameter. - RFC 7591 dynamic client registration (`wristband.Server.Register`): JSON only, a bounded request body, redirect URI validation (HTTPS, or loopback HTTP), public (`none`) and confidential (`client_secret_post`, `client_secret_basic`) clients, a cap on unrevoked clients and a sweep of old clients that never got consent, all in one transaction. -- Authorization endpoint (`wristband.Server.Authorize`): the client and its exact registered redirect URI are validated before any redirect is sent (an unknown client gets a local plain-text 400, never an open redirect); then S256 PKCE, the client's scope ceiling and the RFC 8707 `resource` value are checked, a pending request is stored and the browser is sent to the application's consent page at `/connect?request=`, or at `wristband.Options.ConsentPath` on the issuer when that is set (an empty path keeps the PHP bytes). The accepted scopes are the same resolved list `wristband.Server.Metadata` advertises. A non-empty `wristband.Options.ScopesSupported` is used as given (`read`, `write`, `ai` and `offline_access` from `wristband.DefaultOptions`, which still refuses `backend`; a host that lists an extra scope accepts it). An empty or nil list on the MCP flavour resolves to `read`, `write`, `ai`, `offline_access` and `backend`. The OpenID Connect identity scopes `openid`, `profile` and `email` are dropped from the request before that check (RFC 6749 section 3.3 lets a server grant fewer scopes than requested), so a client that also reads the issuer's OpenID Connect discovery document still connects; a request with nothing else left gets the default `read` (or `wristband.Options.DefaultScopes`, filtered to the accepted list, when that leaves anything), and the three are never advertised. Any other value is `invalid_scope`. OpenID Connect discovery stays `openid`, `profile` and `email` and does not use this list. The OAuth server plugin publishes that list as `pact.MCPAdvertisedScopes`; pier copies `pact.MCPAdvertisedScopes.MCPScopesSupported` when it is non-empty. A route the MCP endpoint runs reads the caller with `pact.MCPCallFrom`. +- Authorization endpoint (`wristband.Server.Authorize`): the client and its exact registered redirect URI are validated before any redirect is sent (an unknown client gets a local plain-text 400, never an open redirect); then S256 PKCE, the client's scope ceiling and the RFC 8707 `resource` value are checked, a pending request is stored and the browser is sent to the application's consent page at `/connect?request=`, or at `wristband.Options.ConsentPath` on the issuer when that is set (an empty path keeps the PHP bytes). The accepted scopes are the same resolved list `wristband.Server.Metadata` advertises. A non-empty `wristband.Options.ScopesSupported` is used as given (`read`, `write`, `ai` and `offline_access` from `wristband.DefaultOptions`, which still refuses `backend`; a host that lists an extra scope accepts it). An empty or nil list on the MCP flavour resolves to `read`, `write`, `ai`, `offline_access` and `backend`. The OpenID Connect identity scopes `openid`, `profile` and `email` are dropped from the request before that check (RFC 6749 section 3.3 lets a server grant fewer scopes than requested), so a client that also reads the issuer's OpenID Connect discovery document still connects; a request with nothing else left gets the default `read` (or `wristband.Options.DefaultScopes`, filtered to the accepted list, when that leaves anything; when neither is accepted it is `invalid_scope`), and the three are never advertised. With `wristband.Options.DefaultScopes` set, a request that names only `offline_access` gets the default scopes as well and keeps offline access. Any other value is `invalid_scope`. OpenID Connect discovery stays `openid`, `profile` and `email` and does not use this list. The OAuth server plugin publishes that list as `pact.MCPAdvertisedScopes`; pier copies `pact.MCPAdvertisedScopes.MCPScopesSupported` when it is non-empty. A route the MCP endpoint runs reads the caller with `pact.MCPCallFrom`. - Consent operations for the application's own consent screen: `wristband.Server.PendingRequest` (what to show, including `wristband.PendingRequestView.OfflineAccess`, the pending row's flag; `offline_access` is not a scope on the view), `wristband.Server.IssueCode` (grant, returning the redirect URL with `code`, `iss` and `state`; the signature is unchanged) and `wristband.Server.DenyPending` (returning an `access_denied` redirect). Missing, foreign, used and expired requests all report the same `wristband.ErrPendingNotFound`. - Token endpoint (`wristband.Server.Token`): code exchange with PKCE verification, then an access token minted by the application plus a rotating refresh token. Reusing a spent refresh token revokes its whole lineage and the linked access tokens. Expired codes and refresh tokens are swept on each call. - Connected-app revocation: `wristband.Server.Revoke` kills an access token and the refresh lineage attached to it. @@ -205,7 +205,7 @@ wristband reads no config keys or environment variables; the application passes | `wristband.Options.AccessTokenTTL` | 1 hour | | `wristband.Options.RefreshTokenTTL` | 30 days | | `wristband.Options.ConsentPath` | none (empty), which hands authorize off to `/connect` on the issuer, byte for byte as the PHP server; a set path (for example `/admin/connect`) replaces `/connect` on the same issuer | -| `wristband.Options.DefaultScopes` | none (empty), which keeps the PHP fallback `read` for a request that names no data scope; a set list is filtered to the accepted scopes and replaces `read` when anything is left | +| `wristband.Options.DefaultScopes` | none (empty), which keeps the PHP fallback `read` for a request that names no data scope (`invalid_scope` when `read` is not accepted); a set list is filtered to the accepted scopes and replaces `read` when anything is left, and then also applies to a request that names only `offline_access` | Always set `wristband.Options.Issuer` and `wristband.Options.Resource` for your deployment. While `wristband.Options.Resource` is empty, an MCP authorization request that sends `resource` is refused with `invalid_target`. diff --git a/modules/wristband/authorize.go b/modules/wristband/authorize.go index 45552d5d..79cbd4f5 100644 --- a/modules/wristband/authorize.go +++ b/modules/wristband/authorize.go @@ -15,6 +15,7 @@ package wristband import ( "fmt" "net/http" + "slices" "strings" ) @@ -108,7 +109,7 @@ func (s *Server) Authorize(w http.ResponseWriter, r *http.Request) { } allowed := s.allowedAuthorizeScopes() - scopes, scopeErr := parseAuthorizeScopes(q.Get("scope"), allowed, s.defaultAuthorizeScopes(allowed)) + scopes, scopeErr := parseAuthorizeScopes(q.Get("scope"), allowed, s.defaultAuthorizeScopes(allowed), len(s.opts.DefaultScopes) > 0) if scopeErr != "" { s.authorizeErrorRedirect(w, redirectURI, "invalid_scope", scopeErr, state) return @@ -206,17 +207,24 @@ func (s *Server) consentPath() string { // defaultAuthorizeScopes is the fallback of an authorize request that names // no data scope: Options.DefaultScopes filtered to allowed, in their given -// order without repeats, or the PHP ["read"] when nothing remains. +// order without repeats (offline_access is not a data scope and is never +// taken from it), or the PHP ["read"] when nothing remains. When read is not +// in allowed either, the answer is empty and the request is refused with +// invalid_scope (RFC 6749 section 3.3) instead of storing a scope the server +// does not advertise. func (s *Server) defaultAuthorizeScopes(allowed map[string]bool) []string { out := make([]string, 0, len(s.opts.DefaultScopes)) for _, sc := range s.opts.DefaultScopes { sc = strings.TrimSpace(sc) - if sc == "" || !allowed[sc] || mcpIgnoredIdentityScopes[sc] || stringSliceContains(out, sc) { + if sc == "" || sc == "offline_access" || !allowed[sc] || mcpIgnoredIdentityScopes[sc] || stringSliceContains(out, sc) { continue } out = append(out, sc) } if len(out) == 0 { + if !allowed["read"] { + return nil + } return []string{"read"} } return out @@ -266,10 +274,14 @@ var mcpIgnoredIdentityScopes = map[string]bool{ // narrowed from refusal to dropping), so the drop happens even when a host // lists one of them in Options.ScopesSupported. An absent, empty or // identity-only scope value falls back to fallback (the PHP ["read"] unless -// Options.DefaultScopes says otherwise, see defaultAuthorizeScopes); any -// other token outside allowed, the server's set (allowedAuthorizeScopes), -// is refused. -func parseAuthorizeScopes(raw string, allowed map[string]bool, fallback []string) ([]string, string) { +// Options.DefaultScopes says otherwise, see defaultAuthorizeScopes); an +// empty fallback refuses it. Any other token outside allowed, the server's +// set (allowedAuthorizeScopes), is refused. When defaultsSet (the host set +// Options.DefaultScopes), a request whose only remaining token is +// offline_access gets fallback plus offline_access, so a client that asks +// only for a refresh token is not stored with zero data scopes; without +// DefaultScopes it keeps the PHP behaviour. +func parseAuthorizeScopes(raw string, allowed map[string]bool, fallback []string, defaultsSet bool) ([]string, string) { parts := strings.Fields(strings.TrimSpace(raw)) kept := make([]string, 0, len(parts)) for _, p := range parts { @@ -278,6 +290,9 @@ func parseAuthorizeScopes(raw string, allowed map[string]bool, fallback []string } } if len(kept) == 0 { + if len(fallback) == 0 { + return nil, "scope is required" + } return append([]string(nil), fallback...), "" } for _, p := range kept { @@ -285,6 +300,9 @@ func parseAuthorizeScopes(raw string, allowed map[string]bool, fallback []string return nil, "scope contains an unsupported value" } } + if defaultsSet && len(fallback) > 0 && !slices.ContainsFunc(kept, func(p string) bool { return p != "offline_access" }) { + return append(append([]string(nil), fallback...), "offline_access"), "" + } return kept, "" } diff --git a/modules/wristband/consent_path_test.go b/modules/wristband/consent_path_test.go index 04675e2b..14c9d7ca 100644 --- a/modules/wristband/consent_path_test.go +++ b/modules/wristband/consent_path_test.go @@ -188,6 +188,45 @@ func TestAuthorizeDefaultScopes(t *testing.T) { } }) + t.Run("an offline_access-only request gets the default scopes and keeps offline access", func(t *testing.T) { + srv := consentPathServer(t, issuer, withCatalog("*", "admin:read", "offline_access")) + for _, scope := range []string{"offline_access", "openid offline_access", "offline_access offline_access"} { + rec := consentPathAuthorize(t, srv, str(scope)) + id := handoffRequest(t, rec.Header().Get("Location"), issuer+"/connect?request=") + view, err := srv.PendingRequest(context.Background(), id, 1) + if err != nil { + t.Fatal(err) + } + if !slices.Equal(view.ScopesRequested, []string{"*", "admin:read"}) { + t.Fatalf("%q stored %v, want the default scopes", scope, view.ScopesRequested) + } + if !view.OfflineAccess { + t.Fatalf("%q lost offline access", scope) + } + } + }) + + t.Run("without default scopes an offline_access-only request keeps the PHP behaviour", func(t *testing.T) { + srv := consentPathServer(t, issuer, nil) + if got := stored(t, srv, str("offline_access")); len(got) != 0 { + t.Fatalf("stored %v, want no data scope (PHP parity)", got) + } + }) + + t.Run("a server that does not accept read refuses a request naming no scope", func(t *testing.T) { + srv := consentPathServer(t, issuer, withCatalog()) + for _, scope := range []*string{nil, str("openid")} { + rec := consentPathAuthorize(t, srv, scope) + loc, err := url.Parse(rec.Header().Get("Location")) + if err != nil { + t.Fatal(err) + } + if !strings.HasPrefix(loc.String(), authorizeTestRedirect) || loc.Query().Get("error") != "invalid_scope" { + t.Fatalf("Location = %q, want an invalid_scope error redirect", loc) + } + } + }) + t.Run("an explicit scope is not replaced", func(t *testing.T) { srv := consentPathServer(t, issuer, withCatalog("*", "acme")) if got := stored(t, srv, str("acme:read")); !slices.Equal(got, []string{"acme:read"}) { diff --git a/modules/wristband/server.go b/modules/wristband/server.go index 994c331e..03a89b54 100644 --- a/modules/wristband/server.go +++ b/modules/wristband/server.go @@ -100,10 +100,13 @@ type Options struct { ConsentPath string // DefaultScopes is what an MCP authorize request gets when it names no - // data scope (an absent, empty or identity-only scope value). Only the - // names the server accepts (ScopesSupported, resolved) are kept; empty - // or unset, or empty after that filter, means the PHP default ["read"]. - // The OIDC flavour ignores it. + // data scope (an absent, empty or identity-only scope value, or, while + // this list is set, one that names only offline_access, which keeps + // offline access). Only the names the server accepts (ScopesSupported, + // resolved) are kept, offline_access never; empty or unset, or empty + // after that filter, means the PHP default ["read"], and a server that + // does not accept read refuses the request with invalid_scope. The OIDC + // flavour ignores it. DefaultScopes []string }