standard_id 0.40.0 → 0.41.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89d297a5e9c69566991b97cca501fd5a714b2d2e1200d2e740b3e45684981aab
-  data.tar.gz: d93fc7206735373f14ac2cd51c4612aaf7b1d19244022d884f0c84757d8f78c6
+  metadata.gz: 8cbe67c8d05fe6c7daeeb4d4a44562507e1d5104c32eeba94b701e98e6afe3ea
+  data.tar.gz: 8f9cb74cf37bb063c66547c7f563005f870a5a86509fe8f89b0bb57893f0ed82
 SHA512:
-  metadata.gz: 1ce536a136af167e65ec9d01e370a187d71f77a2f60f0c5af47ee5c23a9b58cb87444b95191a019fa06689902765f51eaff20656aeedcdef288e34f577c99c91
-  data.tar.gz: f825db9970c937a76592c421fb71a9607f3ea0667dfafa105ff2d6ce78bbd754f5ca01f873cf3321962876c3ab0f8c7f7314ec95604cf5900d56291cede6ec57
+  metadata.gz: e8110399efd07b7b0455f2b8a5ee2c93acfb7dd9bb3847c1a7b43a78aec874b1709aebc05d7be37877007b81f19946322496745793da0418757ecd3de0349121
+  data.tar.gz: '08736fdbf31a259270c02c232f3a8e163c1dc80ca7f5fd3a4dba2168adb812aa91307bf662b7766bc0078b532bf549be64998342cf90f4e5c54048d31f2becd8'

data/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.41.0] - 2026-09-15
+
+### Added
+
+- **Per-audience scope vocabulary hook.** An app can now declare, per audience, the set of scopes a client targeting that audience may request and be granted — the mechanism sidekick-web needs to express its per-audience MCP scope vocabularies (`mcp`, `mcp:read`, `mcp:eval:run`, …) through the gem instead of hard-coding a single flat `scopes_supported` list shared by every audience. This is the scope-side counterpart to the existing `audience_profile_types` binding: that binds an audience to a required profile, this binds an audience to a grantable scope vocabulary, and the two are configured and read the same way on purpose.
+
+  `c.oauth.audience_scopes` is a static `audience => Array<String>` map; `c.oauth.audience_scope_resolver` is an optional callable `->(audience:, client:, configured_scopes:) { … }` for apps that compute the vocabulary dynamically (per-client entitlements), filtered by arity like every other gem callable and returning `nil` to fall back to the static map. `StandardId::Oauth::AudienceScopeResolver` reads them and exposes `scopes_for`, `configured_for?`, `permits?`, `filter` (narrow a grant to the vocabulary), `disallowed`, and `assert!` (fail-closed, raising `InvalidScopeError` / RFC 6749 `invalid_scope`, naming only the client's offending scopes so the endpoint is not a vocabulary-enumeration oracle).
+
+  An **unconfigured** audience fails **open** everywhere — `filter`/`assert!` pass requested scopes through unchanged — exactly like `audience_profile_types` skips its check when unmapped, so an app that does not model per-audience vocabularies sees no behaviour change. The resolver ships ahead of any mint-/registration-time wiring so the hook API can be settled in review first, mirroring how `AudienceProfileResolver#resolve!` shipped before its strict path was wired.
+
+### Removed
+
+- **The per-client `refresh_token_lifetime` column is dropped** (`standard_id_client_applications`), resolving the #765 asymmetry. It was never honoured: `TokenLifetimeResolver.refresh_token_lifetime` resolves the refresh-token lifetime **globally** from `oauth.refresh_token_lifetime` and has no per-client branch, so the column advertised a knob that did nothing. Refresh-token lifetime is a global policy by design — a client's re-authorization cadence is governed by **revocation**, not by a per-client lifetime (see the 0.39.x linked-session reasoning: "Revocation is the property the estate wants; lifetime remains `refresh_token_lifetime`'s job, which already exists and is already configured per host"). Access- and authorization-code lifetimes remain per-client.
+
+  **Migration:** consumers pick up `20260915000000_remove_refresh_token_lifetime_from_standard_id_client_applications` (idempotent, reversible). The global `oauth.refresh_token_lifetime` config is unchanged and continues to govern refresh-token lifetime for every client.
+
 ## [0.40.0] - 2026-09-05
 
 ### Fixed

data/README.md

@@ -235,6 +235,38 @@ end
 
 Resolvers receive keyword arguments with the context containing `client`, `account`, and `request`, so you can reference only what you need. This lets you, for example, pull organization info off the client application or decorate claims with account attributes.
 
+### Per-Audience Scope Vocabulary
+
+Declare, per audience, the set of scopes a client targeting that audience may request and be granted. This lets each audience expose its own MCP scope vocabulary rather than sharing one flat `scopes_supported` list. It is the scope-side counterpart to the `audience_profile_types` binding: that binds an audience to a required profile, this binds it to a grantable scope vocabulary.
+
+```ruby
+StandardId.configure do |config|
+  config.oauth.audience_scopes = {
+    "harness"       => %w[mcp mcp:read mcp:eval:run mcp:prompt:write],
+    "companion_kit" => %w[mcp mcp:read],
+    "admin_kit"     => %w[mcp mcp:read mcp:admin]
+  }
+
+  # Optional: compute a vocabulary dynamically (e.g. per-client entitlements).
+  # Return an Array<String>, or nil to fall back to the static map above.
+  config.oauth.audience_scope_resolver = ->(audience:, client:, configured_scopes:) {
+    Entitlements.mcp_scopes_for(client, audience) || configured_scopes
+  }
+end
+```
+
+`StandardId::Oauth::AudienceScopeResolver` reads this config:
+
+```ruby
+R = StandardId::Oauth::AudienceScopeResolver
+R.scopes_for(audience: "companion_kit")                          # => ["mcp", "mcp:read"]
+R.permits?(scope: "mcp:admin", audience: "companion_kit")        # => false
+R.filter(requested: %w[mcp mcp:admin], audience: "companion_kit") # => ["mcp"]  (narrows, never raises)
+R.assert!(requested: %w[mcp mcp:admin], audience: "companion_kit") # => raises InvalidScopeError
+```
+
+An **unconfigured** audience fails **open** — `filter` and `assert!` pass the requested scopes through unchanged — so an app that does not model per-audience vocabularies sees no behaviour change; narrowing only bites once an audience has an explicit vocabulary.
+
 ### Social Login Setup
 
 The `social.google_*` and `social.apple_*` fields are declared by the **provider

data/app/models/standard_id/client_application.rb

@@ -19,8 +19,13 @@ module StandardId
     validates :scopes, presence: true
     validates :code_challenge_methods, presence: true, if: :require_pkce?
 
-    # Lifecycle validations
-    validates :access_token_lifetime, :refresh_token_lifetime, :authorization_code_lifetime,
+    # Lifecycle validations.
+    #
+    # Refresh-token lifetime is deliberately NOT per-client: it is resolved
+    # globally by TokenLifetimeResolver from `oauth.refresh_token_lifetime`, so
+    # there is no `refresh_token_lifetime` column to validate here (removed in
+    # migration 20260915000000, the #765 asymmetry fix).
+    validates :access_token_lifetime, :authorization_code_lifetime,
               presence: true, numericality: { greater_than: 0 }
 
     # Security: public clients cannot opt out of PKCE. Public clients run in

data/db/migrate/20260915000000_remove_refresh_token_lifetime_from_standard_id_client_applications.rb

@@ -0,0 +1,23 @@
+class RemoveRefreshTokenLifetimeFromStandardIdClientApplications < ActiveRecord::Migration[7.1]
+  # Drops the per-client `refresh_token_lifetime` column. It was never honoured:
+  # `TokenLifetimeResolver.refresh_token_lifetime` resolves the refresh-token
+  # lifetime GLOBALLY from `oauth.refresh_token_lifetime` and has no per-client
+  # branch, so the column advertised a knob that did nothing (the #765
+  # asymmetry). Refresh-token lifetime is a global policy by design — a client's
+  # session cadence is governed by revocation, not by a per-client lifetime
+  # (see CHANGELOG, "Revocation is the property the estate wants") — so the
+  # column is removed rather than wired up.
+  #
+  # Access- and authorization-code lifetimes remain per-client.
+  def up
+    return unless column_exists?(:standard_id_client_applications, :refresh_token_lifetime)
+
+    remove_column :standard_id_client_applications, :refresh_token_lifetime
+  end
+
+  def down
+    return if column_exists?(:standard_id_client_applications, :refresh_token_lifetime)
+
+    add_column :standard_id_client_applications, :refresh_token_lifetime, :integer, default: 2592000
+  end
+end

data/lib/standard_id/config/schema.rb

@@ -341,6 +341,39 @@ StandardId::ConfigSchema.define do
     # and prefers an `active?`-responding record if multiple match.
     field :audience_profile_resolver, type: :any, default: nil
 
+    # Audience → scope-vocabulary binding (the per-audience MCP scope hook).
+    #
+    # Maps each configured audience string to the Array<String> of scopes a
+    # client targeting that audience may request and be granted. This is the
+    # scope-side counterpart to `audience_profile_types`: that binds an audience
+    # to a required profile, this binds an audience to a grantable scope
+    # vocabulary. `StandardId::Oauth::AudienceScopeResolver` reads it.
+    #
+    # Values may be a single space-delimited String or an Array<String>.
+    #
+    # Example:
+    #   c.oauth.audience_scopes = {
+    #     "harness"       => %w[mcp mcp:read mcp:eval:run mcp:prompt:write],
+    #     "companion_kit" => %w[mcp mcp:read],
+    #     "admin_kit"     => %w[mcp mcp:read mcp:admin]
+    #   }
+    #
+    # When empty (default) or the matched audience is absent from the map, the
+    # vocabulary is empty and the resolver's enforcement helpers fail OPEN
+    # (requested scopes pass through unchanged) — back-compat with apps that do
+    # not model per-audience scope vocabularies.
+    field :audience_scopes, type: :hash, default: -> { {} }
+
+    # Optional resolver for computing an audience's scope vocabulary
+    # dynamically (e.g. per-client entitlements). Called with keyword arguments
+    # `(audience:, client:, configured_scopes:)` — any subset is accepted,
+    # arguments are filtered by arity — where `configured_scopes` is the
+    # `Array<String>` from `audience_scopes` for that audience. Must return an
+    # Array<String> (or nil to fall back to the static `audience_scopes` map).
+    #
+    # When nil (default), only the static `audience_scopes` map is consulted.
+    field :audience_scope_resolver, type: :any, default: nil
+
     # JWT signing configuration (for asymmetric algorithms)
     # If nil, uses HS256 with Rails.application.secret_key_base
     field :signing_key, type: :any, default: nil

data/lib/standard_id/oauth/audience_scope_resolver.rb

@@ -0,0 +1,179 @@
+module StandardId
+  module Oauth
+    # Resolves the scope VOCABULARY a given audience is allowed to express —
+    # the set of scope strings a client targeting that audience may request and
+    # be granted. This is the hook an app uses to declare its per-audience MCP
+    # scope vocabulary through the gem, rather than hard-coding a single flat
+    # `scopes_supported` list that every audience shares.
+    #
+    # It is the scope-side counterpart to `AudienceProfileResolver`
+    # (`c.oauth.audience_profile_types` + `c.oauth.audience_profile_resolver`):
+    # that one binds an audience to the PROFILE an account must hold; this one
+    # binds an audience to the SCOPES a client may carry. The two are read the
+    # same way and configured the same way, on purpose.
+    #
+    # Configuration (both optional, both default to "unconfigured"):
+    #
+    #   # Static map: audience string => Array<String> of grantable scopes.
+    #   c.oauth.audience_scopes = {
+    #     "harness"       => %w[mcp mcp:read mcp:eval:run mcp:prompt:write],
+    #     "companion_kit" => %w[mcp mcp:read],
+    #     "admin_kit"     => %w[mcp mcp:read mcp:admin]
+    #   }
+    #
+    #   # Optional callable, for apps that compute the vocabulary dynamically
+    #   # (e.g. per-client entitlements). Receives keyword args
+    #   # `(audience:, client:, configured_scopes:)` — any subset is accepted,
+    #   # arguments are filtered by arity — and must return an Array<String>
+    #   # (or nil to fall back to the static map for that audience).
+    #   c.oauth.audience_scope_resolver = ->(audience:, client:, **) {
+    #     Entitlements.mcp_scopes_for(client, audience)
+    #   }
+    #
+    # When an audience is UNCONFIGURED (absent from the map and the resolver
+    # returns nil / is unset), the vocabulary is empty and the enforcement
+    # helpers below fail OPEN — they pass the requested scopes through
+    # unchanged. This mirrors `audience_profile_types`: an app that does not
+    # model per-audience scope vocabularies sees no behaviour change. Narrowing
+    # only bites once an audience has an explicit vocabulary.
+    #
+    # @example
+    #   StandardId::Oauth::AudienceScopeResolver.filter(
+    #     requested: %w[mcp mcp:admin openid],
+    #     audience: "companion_kit"
+    #   ) # => ["mcp"]   (mcp:admin + openid are not in companion_kit's vocabulary)
+    module AudienceScopeResolver
+      class << self
+        # The scope vocabulary for `audience` as an Array<String>.
+        #
+        # Resolution order:
+        #   1. the configured callable `audience_scope_resolver`, when set and
+        #      it returns a non-nil value — filtered by arity like every other
+        #      gem callable, and handed the static-map value as
+        #      `configured_scopes:` so it can extend rather than replace it;
+        #   2. otherwise the static `audience_scopes` map entry;
+        #   3. otherwise `[]` (unconfigured).
+        #
+        # Always returns a de-duplicated Array<String> with blanks removed.
+        #
+        # @param audience [String, Symbol, nil]
+        # @param client [Object, nil] the ClientApplication in play, when known;
+        #   passed through to the resolver callable for per-client vocabularies.
+        # @return [Array<String>]
+        def scopes_for(audience:, client: nil)
+          return [] if audience.blank?
+
+          configured = static_scopes_for(audience)
+
+          resolver = StandardId.config.oauth.audience_scope_resolver
+          if resolver.respond_to?(:call)
+            filtered = StandardId::Utils::CallableParameterFilter.filter(
+              resolver,
+              { audience: audience.to_s, client: client, configured_scopes: configured }
+            )
+            resolved = resolver.call(**filtered)
+            return normalize(resolved) unless resolved.nil?
+          end
+
+          configured
+        end
+
+        # True when `audience` has a non-empty scope vocabulary. Callers use
+        # this to distinguish "audience is unconfigured, pass everything" from
+        # "audience is configured with an empty vocabulary, allow nothing".
+        def configured_for?(audience, client: nil)
+          scopes_for(audience: audience, client: client).any?
+        end
+
+        # True when `scope` is within `audience`'s vocabulary. An unconfigured
+        # audience permits every scope (fail-open) — see the module note.
+        #
+        # @param scope [String, Symbol]
+        def permits?(scope:, audience:, client: nil)
+          return false if scope.blank?
+
+          vocabulary = scopes_for(audience: audience, client: client)
+          return true if vocabulary.empty? # unconfigured -> fail open
+
+          vocabulary.include?(scope.to_s)
+        end
+
+        # The subset of `requested` that `audience`'s vocabulary permits, in the
+        # requested order, de-duplicated. An unconfigured audience returns the
+        # requested scopes unchanged (fail-open). Use this to NARROW a grant
+        # down to what the audience allows without raising.
+        #
+        # @param requested [Array<String>, String] space-delimited String or Array
+        # @return [Array<String>]
+        def filter(requested:, audience:, client: nil)
+          req = normalize(requested)
+          vocabulary = scopes_for(audience: audience, client: client)
+          return req if vocabulary.empty? # unconfigured -> pass through
+
+          allowed = vocabulary.to_set
+          req.select { |s| allowed.include?(s) }
+        end
+
+        # The scopes in `requested` that `audience`'s vocabulary does NOT permit.
+        # Empty for an unconfigured audience (nothing is out of vocabulary when
+        # there is no vocabulary).
+        #
+        # @return [Array<String>]
+        def disallowed(requested:, audience:, client: nil)
+          req = normalize(requested)
+          vocabulary = scopes_for(audience: audience, client: client)
+          return [] if vocabulary.empty?
+
+          allowed = vocabulary.to_set
+          req.reject { |s| allowed.include?(s) }
+        end
+
+        # Strict, fail-closed variant for mint / registration enforcement.
+        #
+        # Returns the requested scopes (normalized) when every one is within the
+        # audience's vocabulary, and raises `StandardId::InvalidScopeError` —
+        # which renders as RFC 6749 `invalid_scope` — the moment one is not. An
+        # unconfigured audience is a no-op pass-through (fail-open), so wiring
+        # this into a mint path does not change behaviour for audiences that
+        # have not opted in.
+        #
+        # The error message names the offending scopes (which are the CLIENT's
+        # own request, not internal taxonomy) but never the full vocabulary, so
+        # the endpoint does not become a scope-enumeration oracle.
+        #
+        # @raise [StandardId::InvalidScopeError]
+        # @return [Array<String>]
+        def assert!(requested:, audience:, client: nil)
+          bad = disallowed(requested: requested, audience: audience, client: client)
+          return normalize(requested) if bad.empty?
+
+          raise StandardId::InvalidScopeError,
+            "Scope(s) not permitted for audience '#{audience}': #{bad.join(', ')}"
+        end
+
+        private
+
+        def static_scopes_for(audience)
+          mapping = StandardId.config.oauth.audience_scopes || {}
+          return [] if mapping.empty?
+
+          normalize(mapping[audience.to_s] || mapping[audience.to_sym])
+        end
+
+        # Coerce a String (space-delimited) or Array into a clean, de-duplicated
+        # Array<String>. Matches the space-delimited scope convention used by
+        # ClientApplication#scopes_array and RFC 6749.
+        def normalize(value)
+          list =
+            case value
+            when nil then []
+            when Array then value
+            else value.to_s.split(/\s+/)
+            end
+
+          list.map { |s| s.to_s.strip }.reject(&:blank?).uniq
+        end
+      end
+    end
+  end
+end

data/lib/standard_id/testing/factories/oauth.rb

@@ -12,7 +12,6 @@ FactoryBot.define do
     require_pkce { true }
     code_challenge_methods { "S256" }
     access_token_lifetime { 3600 }
-    refresh_token_lifetime { 2_592_000 }
     authorization_code_lifetime { 600 }
     active { true }
 

data/lib/standard_id/version.rb

@@ -1,3 +1,3 @@
 module StandardId
-  VERSION = "0.40.0"
+  VERSION = "0.41.0"
 end

data/lib/standard_id.rb

@@ -29,6 +29,7 @@ require "standard_id/api/token_manager"
 require "standard_id/api/authentication_guard"
 require "standard_id/utils/callable_parameter_filter"
 require "standard_id/oauth/audience_profile_resolver"
+require "standard_id/oauth/audience_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.40.0
+  version: 0.41.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -230,6 +230,7 @@ files:
 - db/migrate/20260414200000_add_target_created_at_index_to_code_challenges.rb
 - db/migrate/20260416180511_add_partial_indexes_for_active_session_and_challenge_lookups.rb
 - db/migrate/20260611000000_create_standard_id_client_grants.rb
+- db/migrate/20260915000000_remove_refresh_token_lifetime_from_standard_id_client_applications.rb
 - lib/generators/standard_id/install/install_generator.rb
 - lib/generators/standard_id/install/templates/standard_id.rb
 - lib/standard_id.rb
@@ -261,6 +262,7 @@ files:
 - lib/standard_id/http_client.rb
 - lib/standard_id/jwt_service.rb
 - lib/standard_id/oauth/audience_profile_resolver.rb
+- lib/standard_id/oauth/audience_scope_resolver.rb
 - lib/standard_id/oauth/authorization_code_authorization_flow.rb
 - lib/standard_id/oauth/authorization_code_flow.rb
 - lib/standard_id/oauth/authorization_flow.rb