standard_id 0.19.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d3af31455bcc5b445cb7398d0d4bc2d4fac8ee7e246bcdc437796419af80284
-  data.tar.gz: 167ef5777acbc1de9bf7ecbb9d9e30f95597094566b6268f48c56d1d462c8d37
+  metadata.gz: faa6cfb238d38d71af682021ba3b6407cf06657c1b12e7ff29474dc97c753277
+  data.tar.gz: 365d86af12a4fef90b669f52114ae449d07facd5389089b438ae67174f75059e
 SHA512:
-  metadata.gz: 68bf2f44b3791c46a08500da1c2c91e0878c4b7b009a810fc761d450aeffdc5c007bf2ecef3e2b1a1193ad09313aac528489925215ec7cb23bdbbdef8df4d3c3
-  data.tar.gz: d5116af139011d0cc8d5955489f751bf3dc8592e5e5474b55ce62178add8d828041e952f272a79a52adf7e20238dac02cadd22a8faa28b49277d789320b5897f
+  metadata.gz: 4ffc829b81cb6315954c5f2b3632889a7afd3c7457c4971297698f04ec9f43682b7eb715f711e2b28ea3c40d33f51519fc7339cd8d0f4996a7adad413677e880
+  data.tar.gz: 6247cc6fd0deeee072d90711ae1443d01d42bb585a58330358d9596fae8e665e14af4c274a478f7bc43b4e47adc2aca05d4f2c6ab7a7dc1c4caa846f751ab917

data/lib/standard_id/errors.rb

@@ -58,6 +58,46 @@ module StandardId
     def oauth_error_code = :invalid_grant
   end
 
+  # Raised at mint time when an account has no profile of the type bound
+  # to the requested audience via `c.oauth.audience_profile_types`.
+  #
+  # Subclass of `InvalidGrantError` so existing OAuth error handling
+  # (which renders OAuthError as RFC 6749 error responses) treats this
+  # as `invalid_grant`. The audience and expected profile types are
+  # surfaced via readers for audit logging only — operators MUST NOT
+  # interpolate them into client-facing error responses, since the
+  # configured profile-type taxonomy is internal-only information.
+  class NoBoundProfileError < InvalidGrantError
+    attr_reader :audience, :expected_profile_types
+
+    def initialize(audience:, expected_profile_types:)
+      @audience = audience
+      @expected_profile_types = Array(expected_profile_types)
+      super("No profile of type [#{@expected_profile_types.join(', ')}] " \
+            "for audience '#{audience}'")
+    end
+  end
+
+  # Raised at mint time when an account has more than one active profile
+  # of the type bound to the requested audience. Selecting one silently
+  # would be non-deterministic and unauditable, so we fail closed and let
+  # the host app resolve the ambiguity (deactivate duplicates, or pass an
+  # explicit `profile_id` once that grant parameter is supported).
+  #
+  # Same audit-only/PII rules as `NoBoundProfileError`: do NOT surface
+  # profile_ids in client-facing responses.
+  class AmbiguousProfileError < InvalidGrantError
+    attr_reader :audience, :expected_profile_types, :profile_ids
+
+    def initialize(audience:, expected_profile_types:, profile_ids:)
+      @audience = audience
+      @expected_profile_types = Array(expected_profile_types)
+      @profile_ids = Array(profile_ids)
+      super("Multiple active profiles of type [#{@expected_profile_types.join(', ')}] " \
+            "for audience '#{audience}' (#{@profile_ids.length} profile(s))")
+    end
+  end
+
   class InvalidScopeError < OAuthError
     def oauth_error_code = :invalid_scope
   end

data/lib/standard_id/oauth/audience_profile_resolver.rb

@@ -59,6 +59,48 @@ module StandardId
           profile_types_for(audience).any?
         end
 
+        # Strict variant of `.call` for mint-time enforcement: returns the
+        # uniquely matching active profile, or raises a typed error so the
+        # token grant flow can fail closed.
+        #
+        # Resolution rules (deterministic, no silent fallbacks):
+        #   - 0 matching active profiles → raises `NoBoundProfileError`
+        #     (NB: an inactive-only match is still 0 active matches and
+        #     fails closed — inactive profiles cannot mint tokens)
+        #   - exactly 1 matching active profile → returns it
+        #   - >1 matching active profile → raises `AmbiguousProfileError`
+        #
+        # The legacy `.call` API preserves its "first active else first match"
+        # behavior, since it is wired into the decode-time concern and host
+        # apps may have grown to depend on its tolerance. Migrating that path
+        # to strict mode is a separate change.
+        #
+        # @raise [StandardId::NoBoundProfileError]
+        # @raise [StandardId::AmbiguousProfileError]
+        def resolve!(account:, audience:)
+          types = profile_types_for(audience)
+          raise ArgumentError, "audience #{audience.inspect} has no profile binding" if types.empty?
+
+          # Custom resolver path: trust the host app's result. It's expected
+          # to enforce its own determinism — if it returns nil we still fail
+          # closed; if it returns a profile we use it as-is.
+          resolver = StandardId.config.oauth.audience_profile_resolver
+          if resolver.respond_to?(:call)
+            filtered = StandardId::Utils::CallableParameterFilter.filter(
+              resolver,
+              { account: account, audience: audience, profile_types: types }
+            )
+            resolved = resolver.call(**filtered)
+            return resolved if resolved
+            raise StandardId::NoBoundProfileError.new(
+              audience: audience,
+              expected_profile_types: types
+            )
+          end
+
+          strict_default_lookup(account, audience, types)
+        end
+
         private
 
         def default_lookup(account, types)
@@ -78,6 +120,44 @@ module StandardId
           active || matches.first
         end
 
+        # Strict default lookup — counterpart to `default_lookup` for mint.
+        #
+        # "Active" semantics:
+        #   - if a profile responds to `active?`, only `active? == true`
+        #     counts toward the match set
+        #   - if it does not, treat it as active (back-compat: not all host
+        #     apps have an activity predicate)
+        def strict_default_lookup(account, audience, types)
+          unless account.respond_to?(:profiles)
+            raise StandardId::NoBoundProfileError.new(
+              audience: audience,
+              expected_profile_types: types
+            )
+          end
+
+          candidates = account.profiles
+          candidates = candidates.to_a unless candidates.is_a?(Array)
+
+          matches = candidates.select { |p| types.include?(profile_type_for(p)) }
+          active_matches = matches.select { |p| !p.respond_to?(:active?) || p.active? }
+
+          case active_matches.length
+          when 0
+            raise StandardId::NoBoundProfileError.new(
+              audience: audience,
+              expected_profile_types: types
+            )
+          when 1
+            active_matches.first
+          else
+            raise StandardId::AmbiguousProfileError.new(
+              audience: audience,
+              expected_profile_types: types,
+              profile_ids: active_matches.map { |p| p.respond_to?(:id) ? p.id : nil }.compact
+            )
+          end
+        end
+
         def profile_type_for(profile)
           if profile.respond_to?(:profileable_type)
             profile.profileable_type.to_s

data/lib/standard_id/oauth/token_grant_flow.rb

@@ -36,9 +36,13 @@ module StandardId
 
       def generate_token_response
         validate_audience!
+        enforce_audience_profile_binding!
         emit_token_issuing
         expires_in = token_expiry
         payload = build_jwt_payload(expires_in)
+        # Pre-generate jti so we can include it in the OAUTH_TOKEN_ISSUED
+        # event payload without re-decoding the encoded JWT.
+        @issued_jti = payload[:jti] ||= SecureRandom.uuid
         access_token = StandardId::JwtService.encode(payload, expires_in: expires_in)
 
         response = {
@@ -212,6 +216,51 @@ module StandardId
         end
       end
 
+      # Fail closed when the requested audience has a profile-type binding
+      # configured (`c.oauth.audience_profile_types`) but the account holds
+      # no matching active profile.
+      #
+      # Before this check existed, mints silently succeeded with `gid` (or
+      # any other profile-derived claim) resolving to `nil`. Downstream
+      # services then received a syntactically-valid bearer that pointed at
+      # nothing — a classic "fail open" foot-gun. Now: the mint raises
+      # `InvalidGrantError` (via `NoBoundProfileError` / `AmbiguousProfileError`),
+      # which the OAuth error handler renders as RFC 6749 `invalid_grant`.
+      #
+      # The resolved profile is stashed in `@resolved_profile` for two
+      # downstream uses:
+      #   1. Inclusion in the OAUTH_TOKEN_ISSUED audit event payload
+      #      (so operators can correlate mints to profiles).
+      #   2. Use by host-app claim resolvers via `claim_resolvers_context`,
+      #      eliminating a redundant DB lookup (and the race window in
+      #      which the profile might be deactivated between lookup and use).
+      #
+      # No-op when audience is unset or no binding is configured for any of
+      # the requested audiences — preserves existing behavior for endpoints
+      # that haven't opted into the audience→profile binding feature.
+      def enforce_audience_profile_binding!
+        requested = Array(audience).reject(&:blank?)
+        return if requested.empty?
+
+        bound = requested.select { |a| StandardId::Oauth::AudienceProfileResolver.configured_for?(a) }
+        return if bound.empty?
+
+        # Multiple bound audiences in one token would imply the holder is
+        # cleared for multiple distinct profile-type contexts simultaneously
+        # — there's no coherent answer for which profile to bind. Reject
+        # rather than silently picking one. Host apps that need cross-
+        # audience tokens should issue separate tokens per audience.
+        if bound.length > 1
+          raise StandardId::InvalidGrantError,
+            "Cannot bind a single token to multiple profile-bound audiences: #{bound.join(', ')}"
+        end
+
+        @resolved_profile = StandardId::Oauth::AudienceProfileResolver.resolve!(
+          account: token_account,
+          audience: bound.first
+        )
+      end
+
       def claims_from_custom_claims
         callable = StandardId.config.oauth.custom_claims
         return {} unless callable.respond_to?(:call)
@@ -253,12 +302,13 @@ module StandardId
       end
 
       def token_account
-        return nil if subject_id.blank?
+        return @token_account if defined?(@token_account)
+        return (@token_account = nil) if subject_id.blank?
 
         account_class = StandardId.account_class
-        return nil unless account_class.respond_to?(:find_by)
+        return (@token_account = nil) unless account_class.respond_to?(:find_by)
 
-        account_class.find_by(id: subject_id)
+        @token_account = account_class.find_by(id: subject_id)
       end
 
       def token_client
@@ -270,7 +320,13 @@ module StandardId
           client: token_client,
           account: token_account,
           request: request,
-          audience: audience
+          audience: audience,
+          # Pre-resolved profile (when the requested audience has a binding).
+          # Host-app claim resolvers that previously looked up the profile by
+          # account+type can now accept this directly via keyword filtering,
+          # avoiding both an extra query and the race in which the profile
+          # is deactivated between resolver lookup and use.
+          profile: @resolved_profile
         }
       end
 
@@ -295,7 +351,16 @@ module StandardId
           grant_type: grant_type,
           client_id: client_id,
           account: token_account,
-          expires_in: expires_in
+          expires_in: expires_in,
+          # Audit enrichment — without these, downstream subscribers
+          # (SIEM, audit log, anomaly detection) cannot meaningfully
+          # correlate a successful mint to the entity it authorizes,
+          # the resource server it targets, the specific token (jti)
+          # for revocation, or the scopes the client requested.
+          profile_id: @resolved_profile&.id,
+          audience: audience,
+          jti: @issued_jti,
+          requested_scopes: current_scopes
         )
       end
     end

data/lib/standard_id/version.rb

@@ -1,3 +1,3 @@
 module StandardId
-  VERSION = "0.19.0"
+  VERSION = "0.20.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_id
 version: !ruby/object:Gem::Version
-  version: 0.19.0
+  version: 0.20.0
 platform: ruby
 authors:
 - Jaryl Sim