standard_id 0.49.1 → 0.50.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b5e02f9651266077753a98125e3772a99bd2cf935da68d17f98df4bfd59505e
-  data.tar.gz: e703964c3b6c2c0ffd10a5475f370c9dea0f6f4873fd6827606ee9869a12726d
+  metadata.gz: f6f93f66f3e1a4d95ac6effab590e560e39f2993dd072010676a3121efec6098
+  data.tar.gz: 6934ab15f5b9c394db6d15eb37ca91d41965421589553135c2a05fea1ebbf551
 SHA512:
-  metadata.gz: 4091588b0c3b2cc3f06c25682e840cb2a1293a94d67abaf25eb81cce6331fe7a8325aea577fd69ceb5405c09dd0aa39fc0e70ed17df493a92da566fd8da10343
-  data.tar.gz: a10b76363a599b3c5fc29681665f8a20d564476cb6682a32c8555f4e2464945f41e0ccfcc7897db8c65df57483f8be3b927294282121d47bbc3226564e3dc0b2
+  metadata.gz: 73eab42991c65471c2f77d7be554b4ec1d002eacb73e62d8d77bc79003b5121f4b64bd9750ce8991113ff451556313f54165cfd75b642501251dcb947c0f3900
+  data.tar.gz: 6a0b2b9e4628842eb1ab6d56acf348c829abc083a00e29671c3efadca5dc57e56aa63d958577c884a7ca224f6e768aebedc66755d5c1128912fe4ef1d9eed576

data/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.50.0] - 2026-10-20
+
+### Changed
+
+- **`AudienceResolver`: the client's registered `metadata["audience"]` now outranks the `audience` parameter.** The registered default is set by the server (`dynamic_registration_attributes`) or an operator; letting the request's `audience` beat it meant an openly registered client could ask `/authorize` for another allowed audience, which every consumer's shim had prevented by stripping the parameter. New order: `audience_resolver` hook → registered default → `audience` param → RFC 8707 `resource`. Hosts that set `audience_resolver` to return the registered default are unaffected; a client with no registered default behaves as before.
+
+### Added
+
+- **`c.oauth.authorize_scope_resolver`**: normalise the requested scope at `/authorize` once the client and audience are known and before `audience_scopes` is enforced — collapse a hierarchy, narrow to what the audience consumes, append a default. Callable `(scope:, audience:, client:, request:)` returning a String, Array or nil (unchanged); the answer is what the code is issued with and what consent shows. Validated at boot.
+
 ## [0.49.1] - 2026-10-20
 
 ### Fixed

data/README.md

@@ -1367,9 +1367,9 @@ redirect_to "/api/authorize?" + {
 
 **Which audience is the token for?** `/authorize` resolves it server-side
 (`StandardId::Oauth::AudienceResolver`), in this order: `config.oauth.audience_resolver`
-when set; the `audience` parameter; the RFC 8707 `resource` parameter mapped through
-`config.oauth.resource_audiences`; the client's registered default
-`metadata["audience"]`. The result is bound to the authorization code and reaches
+when set; the client's registered default `metadata["audience"]` (server-set, so it
+outranks the request); the `audience` parameter; the RFC 8707 `resource` parameter
+mapped through `config.oauth.resource_audiences`. The result is bound to the authorization code and reaches
 the token as `aud`, and `config.oauth.audience_scopes` is enforced for it at
 `/authorize` (a scope outside the audience's vocabulary is `invalid_scope`). So a
 dynamically registered MCP client whose registration stamps
@@ -1378,10 +1378,28 @@ in front of the endpoint. The `resource` parameter is ignored until
 `resource_audiences` is set; once it is, an unmapped resource is `invalid_target`
 (RFC 8707 §2).
 
-A client-supplied `audience` still outranks the registered default, so
-`audience_scopes` enforcement is only as strong as `config.oauth.allowed_audiences`
-at the token endpoint. A host that wants the registered default to be the only
-answer sets `audience_resolver` to `->(client:) { client.metadata["audience"] }`.
+For a client with no registered default, a client-supplied `audience` is taken as
+is, so `audience_scopes` enforcement for such clients is only as strong as
+`config.oauth.allowed_audiences` at the token endpoint.
+
+**Which scope?** `config.oauth.authorize_scope_resolver` normalises the requested
+scope once the client and audience are known and before `audience_scopes` is
+enforced — collapse a hierarchy, narrow to what the audience consumes, append a
+default — and its answer is what the code is issued with and the consent screen
+shows:
+
+```ruby
+config.oauth.authorize_scope_resolver = ->(scope:, audience:) {
+  tokens = scope.to_s.split
+  next nil unless audience == "mcp" && tokens.include?("mcp")   # nil leaves the request as is
+
+  tokens - ["mcp:read"]   # "mcp" already implies read; an Array or a String is fine
+}
+```
+
+It runs again when a consent resumes, so make it idempotent (its own output must
+come back unchanged); it also decides what the consent screen shows and what the
+grant records.
 
 ```ruby
 StandardId.configure do |config|

data/app/controllers/standard_id/api/authorization_controller.rb

@@ -74,7 +74,7 @@ module StandardId
         !StandardId::ClientGrant.granted?(
           account: current_account,
           client_id: client.client_id,
-          requested_scope: params[:scope]
+          requested_scope: consent_scope
         )
       end
 
@@ -82,6 +82,21 @@ module StandardId
         @consent_client ||= StandardId::ClientApplication.active.find_by(client_id: params[:client_id])
       end
 
+      # The scope consent is checked against, shown and recorded: the request's,
+      # normalised by `oauth.authorize_scope_resolver` exactly as the flow will
+      # normalise it when the code is issued, so the screen and the grant never
+      # disagree with the token. Needs the client and the resolved audience, so
+      # it is computed here rather than inside the flow.
+      def consent_scope
+        return @consent_scope if defined?(@consent_scope)
+
+        client = consent_client
+        audience = StandardId::Oauth::AudienceResolver.resolve(client: client, params: params, request: request)
+        @consent_scope = StandardId::Oauth::AuthorizeScopeResolver.resolve(
+          scope: params[:scope], audience: audience, client: client, request: request
+        )
+      end
+
       def redirect_to_consent
         payload = StandardId::Oauth::ConsentPayload.encode(authorize_params_for_resume)
         base = StandardId.config.login_url.present? ? consent_base_from_login_url : "/consent"
@@ -98,13 +113,14 @@ module StandardId
 
       # The exact params required to resume authorization-code issuance after
       # approval. Carried through a signed payload so they cannot be tampered
-      # with; redirect_uri + PKCE are revalidated when the flow re-runs.
+      # with; redirect_uri + PKCE are revalidated when the flow re-runs. The
+      # scope is the normalised one the user is shown (see #consent_scope).
       def authorize_params_for_resume
         {
           response_type: response_type,
           client_id: params[:client_id],
           redirect_uri: params[:redirect_uri],
-          scope: params[:scope],
+          scope: consent_scope,
           audience: params[:audience],
           resource: params[:resource],
           state: params[:state],

data/lib/standard_id/config/callable_validator.rb

@@ -61,6 +61,11 @@ module StandardId
           kind: :keyword,
           keywords: %i[metadata request]
         },
+        "oauth.authorize_scope_resolver" => {
+          signature: "(scope:, audience:, client:, request:)",
+          kind: :keyword,
+          keywords: %i[scope audience client request]
+        },
         "oauth.audience_scope_resolver" => {
           signature: "(audience:, client:, configured_scopes:)",
           kind: :keyword,

data/lib/standard_id/config/schema.rb

@@ -421,13 +421,31 @@ StandardId::ConfigSchema.define do
     # instead of trusting a client-supplied `audience` alone. Resolution order
     # (StandardId::Oauth::AudienceResolver): this callable when set (any
     # subset of client:, audience:, resource:, request:; a non-nil answer is
-    # final), else the `audience` param, else the RFC 8707 `resource` param
-    # mapped through `resource_audiences`, else the client's registered
-    # default `metadata["audience"]`. The resolved audience is bound to the
-    # authorization code and reaches the token as `aud`; `audience_scopes`
+    # final), else the client's registered default `metadata["audience"]`
+    # (server-set, so it outranks the request), else the `audience` param,
+    # else the RFC 8707 `resource` param mapped through `resource_audiences`.
+    # The resolved audience is bound to the authorization code and reaches the
+    # token as `aud`; `audience_scopes`
     # (above) is then enforced at /authorize for it.
     field :audience_resolver, type: :any, default: nil
 
+    # Normalise the scope an /authorize request asks for, once the client and
+    # audience are known and before `audience_scopes` is enforced — the place
+    # for what hosts used to do in a shim: collapse a hierarchy ("mcp mcp:read"
+    # → "mcp"), narrow a request to what the chosen audience consumes, append
+    # a default. A callable taking any subset of `scope:` (the raw param),
+    # `audience:` (resolved), `client:` and `request:`; returns the scope as a
+    # String or Array, or nil to leave the request unchanged. The result is
+    # what the code is issued with, what the consent screen shows and what the
+    # grant is checked against and recorded as. It runs again on the consent
+    # resume, so it must be idempotent (its own output must come back unchanged).
+    #
+    #   c.oauth.authorize_scope_resolver = ->(scope:, audience:) {
+    #     tokens = scope.to_s.split
+    #     audience == "mcp" && tokens.include?("mcp") ? tokens - ["mcp:read"] : nil
+    #   }
+    field :authorize_scope_resolver, type: :any, default: nil
+
     # RFC 8707: resource indicator → audience, e.g.
     # { "https://app.example.com/mcp" => "mcp" }. Matched with the trailing
     # slash removed. Empty (the default) means the `resource` parameter is

data/lib/standard_id/oauth/audience_resolver.rb

@@ -9,9 +9,14 @@ module StandardId
     #      subset of `client:`, `audience:` (the raw param), `resource:` (the
     #      RFC 8707 param) and `request:`. A non-nil answer is final; nil
     #      falls through to the defaults below.
-    #   2. The `audience` parameter, when present (what hosts' shims inject
-    #      today, so nothing changes for them).
-    #   3. The `resource` parameter (RFC 8707), mapped through
+    #   2. The client's registered default, `metadata["audience"]` — set by the
+    #      server at registration (`dynamic_registration_attributes`) or by an
+    #      operator, so it is the one input here the client did not choose, and
+    #      it outranks what the request says (0.50.0; before that the
+    #      `audience` parameter came first, which let an openly registered
+    #      client ask for another allowed audience).
+    #   3. The `audience` parameter, when present.
+    #   4. The `resource` parameter (RFC 8707), mapped through
     #      `config.oauth.resource_audiences` ({ "https://app.example/mcp" =>
     #      "mcp" }); compared with the trailing slash removed. With no mapping
     #      configured the parameter is ignored (MCP clients send it on every
@@ -19,9 +24,6 @@ module StandardId
     #      get that default). With a mapping, an unmapped resource is refused
     #      with `invalid_target` (RFC 8707 §2), never silently issued without
     #      an audience.
-    #   4. The client's registered default, `metadata["audience"]` — the
-    #      convention every dynamic-registration operation in the estate
-    #      stamps, and the reason each app carried an authorize shim.
     #
     # Nil when none of these apply: audience stays optional at /authorize.
     module AudienceResolver
@@ -38,10 +40,12 @@ module StandardId
           return coerce_hook_answer(answer) unless answer.nil?
         end
 
+        registered = client_default(client)
+        return registered if registered
         return requested.to_s if requested
         return from_resource(resource) if resource && resource_mapping.any?
 
-        client_default(client)
+        nil
       end
 
       # @raise [StandardId::InvalidTargetError] when a mapping is configured

data/lib/standard_id/oauth/authorization_flow.rb

@@ -92,8 +92,19 @@ module StandardId
         params[:state]
       end
 
+      # The requested scope, normalised by `oauth.authorize_scope_resolver`
+      # when set (a host that collapses a scope hierarchy, or narrows a
+      # request to what the chosen audience consumes, does it here instead of
+      # in a shim in front of this endpoint). Resolved once, after the client
+      # and audience are known; nil from the hook leaves the request as is.
       def scope
-        params[:scope]
+        return @scope if defined?(@scope)
+
+        @scope = resolve_scope(params[:scope])
+      end
+
+      def resolve_scope(requested)
+        StandardId::Oauth::AuthorizeScopeResolver.resolve(scope: requested, audience: audience, client: @client, request: request)
       end
 
       # Resolved once, after the client is known (see AudienceResolver): the

data/lib/standard_id/oauth/authorize_scope_resolver.rb

@@ -0,0 +1,36 @@
+module StandardId
+  module Oauth
+    # Applies `config.oauth.authorize_scope_resolver` to an /authorize request's
+    # scope once the client and audience are known. Shared by the authorize
+    # flows (what the code is issued with) and the consent gate (what the user
+    # is shown, what the grant is checked against and recorded as), so the two
+    # cannot disagree.
+    #
+    # The consent resume re-runs the flow with the already-normalised scope, so
+    # a resolver must be idempotent: applying it to its own output must change
+    # nothing. Collapsing, filtering and appending a default all are; an
+    # append that does not check for presence is not (the Array/String output
+    # is de-duplicated, which covers the common case).
+    module AuthorizeScopeResolver
+      module_function
+
+      # @return [String, nil] the normalised scope (nil/blank in → nil/blank out
+      #   unless the resolver answers)
+      def resolve(scope:, audience:, client:, request: nil)
+        custom = StandardId.config.oauth.authorize_scope_resolver
+        return scope unless custom.respond_to?(:call)
+
+        context = { scope: scope, audience: audience, client: client, request: request }
+        answer = custom.call(**StandardId::Utils::CallableParameterFilter.filter(custom, context))
+        case answer
+        when nil then scope
+        when Array then answer.map(&:to_s).reject(&:blank?).uniq.join(" ")
+        when String, Symbol then answer.to_s.split.uniq.join(" ")
+        else
+          raise StandardId::ConfigurationError,
+            "StandardId config: `oauth.authorize_scope_resolver` must return a String, Array, Symbol or nil, got #{answer.class}"
+        end
+      end
+    end
+  end
+end

data/lib/standard_id/version.rb

@@ -1,3 +1,3 @@
 module StandardId
-  VERSION = "0.49.1"
+  VERSION = "0.50.0"
 end

data/lib/standard_id.rb

@@ -39,6 +39,7 @@ require "standard_id/account_cleanup"
 require "standard_id/oauth/audience_profile_resolver"
 require "standard_id/oauth/audience_scope_resolver"
 require "standard_id/oauth/audience_resolver"
+require "standard_id/oauth/authorize_scope_resolver"
 require "standard_id/oauth/base_request_flow"
 require "standard_id/oauth/token_lifetime_resolver"
 require "standard_id/oauth/oauth_session_persistence"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_id
 version: !ruby/object:Gem::Version
-  version: 0.49.1
+  version: 0.50.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -287,6 +287,7 @@ files:
 - lib/standard_id/oauth/authorization_code_authorization_flow.rb
 - lib/standard_id/oauth/authorization_code_flow.rb
 - lib/standard_id/oauth/authorization_flow.rb
+- lib/standard_id/oauth/authorize_scope_resolver.rb
 - lib/standard_id/oauth/base_request_flow.rb
 - lib/standard_id/oauth/client_credentials_flow.rb
 - lib/standard_id/oauth/client_registration.rb