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).
This commit is contained in:
Jakub Zych
2026-11-21 09:05:07 +01:00
parent 20260e8bb4
commit fa7a84821e
5 changed files with 74 additions and 14 deletions

View File

@@ -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 `<issuer>/connect?request=<id>`, 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 `<issuer>/connect?request=<id>`, 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`;

View File

@@ -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 `<issuer>/connect?request=<id>`, 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 `<issuer>/connect?request=<id>`, 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`.

View File

@@ -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, ""
}

View File

@@ -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"}) {

View File

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