standard_id 0.49.1 → 0.51.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b5e02f9651266077753a98125e3772a99bd2cf935da68d17f98df4bfd59505e
-  data.tar.gz: e703964c3b6c2c0ffd10a5475f370c9dea0f6f4873fd6827606ee9869a12726d
+  metadata.gz: 70dbbe49421726d198ba1ee5502ec80abcce347b4ed006073ed81c99de743321
+  data.tar.gz: dcb5337f9cfc348a256f8317dbb5a946f3b8d5e10f64829287cceb1108d38ac4
 SHA512:
-  metadata.gz: 4091588b0c3b2cc3f06c25682e840cb2a1293a94d67abaf25eb81cce6331fe7a8325aea577fd69ceb5405c09dd0aa39fc0e70ed17df493a92da566fd8da10343
-  data.tar.gz: a10b76363a599b3c5fc29681665f8a20d564476cb6682a32c8555f4e2464945f41e0ccfcc7897db8c65df57483f8be3b927294282121d47bbc3226564e3dc0b2
+  metadata.gz: c469c67c58017cd97529b1e1eb47c5368c1c0e878f1123806796267f31c7791e4233bdb57597958fb460fb838ff8ae2f9ddf50864671d981f04796d5372ddfa5
+  data.tar.gz: bb7d5b2686415c1aa2d0198da73cb2df31372fc7ff36454ac879959bc0628552aafba5da7cd2aedf43bbd47801a673c6e172762abba4c8d3eabdbc6abb557534

data/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.51.0] - 2026-10-20
+
+### Added
+
+- **Dynamic-client lifecycle events**: `oauth.client.registered`, `oauth.client.updated` and `oauth.client.deregistered` (`StandardId::Events::OAUTH_CLIENT_*`, in `OAUTH_EVENTS` and `SECURITY_EVENTS`), published by `Oauth::ClientRegistration` once the change has committed, with the client, its registered metadata, the owner by `owner_type` / `owner_id` (never the record, so no lazy load under strict loading) and, on registration and update, the RFC 7591 document as sent. A raising subscriber is logged and never fails the registration, whose one-time secrets are already committed. Consumers can move their registration audit off the owner row's `after_create_commit` and gain update/deregistration rows.
+- **`protected_resources` entries can say what `aud` their tokens carry and which origin they live on.** `audience: :resource` binds the resource's tokens to its absolute URL (`resource`, RFC 8707 style) instead of the key, or a String names that `aud`; `origin: ->(request:) { ... }` builds `resource`, the metadata URL and the challenge's `resource_metadata` on a public origin other than `request.base_url` (a rewriting proxy). The key stays the resource's name for `protected_resource`, `audience_scopes` and the realm. `StandardId::ResourceServer` checks the per-request audience, so a host whose audience is a URL (jumpdrive-web) can serve its RFC 9728 document from the gem. `verify_audience` accepts a zero-argument callable for an audience known only per request.
+- **`TokenMinter.mint(profile:)`**: mint for a specific profile of the account instead of the strict audience → profile lookup, which refuses an account holding several active profiles of the bound type. The profile must belong to the account, be active, and be of the bound type when the audience has a binding (`InvalidGrantError` otherwise); claim resolvers receive it as `profile:` and `OAUTH_TOKEN_ISSUED` reports its id. For hosts that choose the profile themselves (sidekick-web's Slack and trigger mints).
+- **`TokenMinter.mint(audit_errors: :report)`**: an `OAUTH_TOKEN_ISSUED` subscriber that raises no longer costs the caller a token that is already signed; the error is logged and returned as the new `Result#audit_error`. The default stays `:raise`, like every grant. `OAUTH_TOKEN_ISSUING`, whose subscribers are the account-status and locking guards, always raises. `AudienceProfileResolver.profile_type_for` is now public.
+- **`StandardId::RequestRefused`** (`status:`, `body:`, `headers:`): raised from a host hook, the API engine renders the host's own JSON response verbatim after the usual refusal cleanup — for refusals a client must tell apart from an OAuth error (a region block, a pending deletion) in the host's error envelope.
+- **`c.social.before_account`**: runs on the API social callback once the provider has vouched for the user and before the account is found or created, with `provider:`, `social_info:`, `provider_tokens:`, `params:` and `request:`. Raising refuses with no account row and no account events.
+- **`c.social.completion_before_mint`** (default false): the API social callback publishes `SOCIAL_AUTH_COMPLETED` after `before_mint` and before the mint, then reloads the account, for a host whose completion subscriber creates what the mint depends on (an invitation's profile). With these three and `before_mint`, sidekick-web can delete its subclass of `Api::Oauth::Callback::ProvidersController` (rarebit-sre#478).
+- `TokenMinter` details: `Result#audit_error` is optional when building a `Result` by hand (host stubs keep working); `audit_errors: nil` raises `ArgumentError` like any unknown mode; a reported audit error is logged at `error` with its first backtrace line; an explicit `profile:` documents that `oauth.audience_profile_resolver` is not consulted; the bound-audience rule lives in one place (`TokenGrantFlow#profile_bound_audience`).
+- `before_account` and `before_mint` both receive `audience:` and `scopes:`.
+- **An `audience_profile_types` binding keyed by the resource name still applies under `audience: :resource`.** The binding is looked up under the matched `aud` first and, in a `StandardId::ResourceServer`, falls back to the resource's name, so switching a resource to URL audiences no longer silently drops a binding configured as `"mcp" => [...]`.
+- **Dynamic-client lifecycle events wait for the outermost transaction** (`ActiveRecord.after_all_transactions_commit`): a host that wraps `ClientRegistration` in its own transaction and rolls it back no longer gets an event for a client that never existed.
+- `StandardId::ResourceServer` resolves a resource's `origin:` callable once per request.
+
+## [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

@@ -478,6 +478,25 @@ refuses the sign-in on an account that already existed, what the hook wrote
 stays: make it idempotent. It covers the API callback only; the WebEngine's
 social callback does not run it.
 
+Two more knobs on the same callback. `config.social.before_account` runs before
+the account is found or created (same keywords minus `account:`), for a refusal
+that must leave no account row and fire no account events — and no event of its
+own, so audit it in the hook. `config.social.completion_before_mint = true`
+publishes `SOCIAL_AUTH_COMPLETED` after `before_mint` and before the mint (then
+reloads the account), for a completion subscriber that creates what the mint
+depends on; if the mint then refuses on an account that already existed, the
+subscriber's writes stay, so make it idempotent. Either hook can refuse in the
+host's own error envelope:
+
+```ruby
+config.social.before_account = ->(social_info:, request:) {
+  if RegionBlock.blocked?(request)
+    raise StandardId::RequestRefused.new(status: :forbidden,
+      body: { error: { code: "REGION_BLOCKED", message: "Sign-in is not available here" } })
+  end
+}
+```
+
 
 The `social.google_*` and `social.apple_*` fields are declared by the **provider
 plugin gems**, not by `standard_id` itself — add `standard_id-google` and/or
@@ -909,6 +928,9 @@ Every StandardId event automatically carries tracing metadata (`event_id`, `time
 |  | `oauth.token.issued` | `access_token_id`, `grant_type`, `client_id`, `account`, `expires_in` | After tokens are generated |
 |  | `oauth.token.refreshed` | `old_token_id`, `new_token_id`, `client_id`, `account` | After a refresh token is redeemed |
 |  | `oauth.code.consumed` | `authorization_code`, `client_id`, `account` | After an authorization code is exchanged |
+|  | `oauth.client.registered` | `client_application`, `client_id`, `client_name`, `client_type`, `redirect_uris`, `scope`, `owner_type`, `owner_id`, `client_metadata` | After a dynamic registration (RFC 7591) commits. Never fails the registration: a raising subscriber is logged |
+|  | `oauth.client.updated` | same as `registered` | After an RFC 7592 update commits |
+|  | `oauth.client.deregistered` | same, without `client_metadata` | After an RFC 7592 deregistration commits |
 | Passwordless | `passwordless.code.requested` | `identifier`, `channel` (email/sms), `realm` | After the challenge row is committed, before `code.generated` / delivery. Subscribers should not raise: the previous code is already invalidated by then |
 |  | `passwordless.code.generated` | `code_challenge`, `identifier`, `channel`, `expires_at` | After an OTP is created |
 |  | `passwordless.code.sent` | `identifier`, `channel`, `realm`, `delivery_status` | After an OTP is handed to delivery (not for `Otp.issue(delivery: :manual)`). `delivery_status`: `"sent"` (built-in mailer enqueued it), `"failed"` (built-in mailer was responsible but did not enqueue), `"delegated"` (a host `PASSWORDLESS_CODE_GENERATED` subscriber delivers — the engine can't confirm it) |
@@ -1367,9 +1389,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 +1400,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/concerns/standard_id/audience_verification.rb

@@ -75,9 +75,13 @@ module StandardId
       # Declare the allowed audiences for this controller.
       # The token's `aud` claim must include at least one of these values.
       #
-      # @param audiences [Array<String>] allowed JWT `aud` claim values
+      # An audience known only per request (a resource identified by its own
+      # absolute URL behind a host-dependent origin) may be given as a
+      # zero-argument callable, evaluated on the controller instance.
+      #
+      # @param audiences [Array<String, Proc>] allowed JWT `aud` claim values
       def verify_audience(*audiences)
-        self._required_audiences = audiences.flatten.map(&:to_s)
+        self._required_audiences = audiences.flatten.map { |a| a.respond_to?(:call) ? a : a.to_s }
       end
     end
 
@@ -97,12 +101,13 @@ module StandardId
       # layer handle 401 — don't mask it with a 403.
       return unless current_session
 
+      required = required_audiences
       token_audiences = Array(current_session.aud)
-      matched = (token_audiences & _required_audiences).first
+      matched = (token_audiences & required).first
 
       if matched.nil?
         raise StandardId::InvalidAudienceError.new(
-          required: _required_audiences,
+          required: required,
           actual: token_audiences
         )
       end
@@ -110,15 +115,22 @@ module StandardId
       enforce_audience_profile_binding!(matched, token_audiences)
     end
 
+    # `_required_audiences` with any callable entries evaluated for this request.
+    def required_audiences
+      _required_audiences.flat_map { |a| a.respond_to?(:call) ? Array(instance_exec(&a)) : [a] }
+        .map(&:to_s).reject(&:blank?).uniq
+    end
+
     # Enforce `audience_profile_types[matched]` against the current account.
     # No-op when the audience has no binding configured (back-compat).
     def enforce_audience_profile_binding!(matched_audience, token_audiences)
-      expected_types = StandardId::Oauth::AudienceProfileResolver.profile_types_for(matched_audience)
+      binding_audience = profile_binding_audience(matched_audience)
+      expected_types = StandardId::Oauth::AudienceProfileResolver.profile_types_for(binding_audience)
       return if expected_types.empty?
 
       profile = StandardId::Oauth::AudienceProfileResolver.call(
         account: current_account,
-        audience: matched_audience
+        audience: binding_audience
       )
       actual_type = profile_type_name(profile)
 
@@ -133,13 +145,28 @@ module StandardId
         audience: matched_audience,
         expected_profile_types: expected_types,
         actual_profile_type: actual_type,
-        required: _required_audiences,
+        required: required_audiences,
         actual: token_audiences
       )
       emit_audience_mismatch(error)
       raise error
     end
 
+    # The key `audience_profile_types` is looked up under: the matched `aud`,
+    # or — for a StandardId::ResourceServer whose tokens carry the resource's
+    # URL (`protected_resources` entry with `audience: :resource`) — the
+    # resource's name when only that is configured. Without the fallback a
+    # binding configured under the name would silently stop applying once the
+    # resource switched to URL audiences.
+    def profile_binding_audience(matched_audience)
+      return matched_audience if StandardId::Oauth::AudienceProfileResolver.profile_types_for(matched_audience).any?
+
+      resource_name = respond_to?(:_protected_resource_audience) ? _protected_resource_audience.presence : nil
+      return matched_audience if resource_name.nil?
+
+      StandardId::Oauth::AudienceProfileResolver.profile_types_for(resource_name).any? ? resource_name : matched_audience
+    end
+
     def profile_type_name(profile)
       return nil if profile.nil?
       return profile.profileable_type.to_s if profile.respond_to?(:profileable_type)

data/app/controllers/concerns/standard_id/resource_server.rb

@@ -70,7 +70,9 @@ module StandardId
       def protected_resource(audience, scopes: nil)
         self._protected_resource_audience = audience.to_s
         self._protected_resource_scopes = Array(scopes).flat_map { |s| s.to_s.split }.reject(&:blank?).uniq
-        verify_audience audience.to_s
+        # Per request: with `audience: :resource` the `aud` is the resource's
+        # absolute URL, which depends on the origin.
+        verify_audience -> { protected_resource_token_audience }
       end
     end
 
@@ -91,8 +93,23 @@ module StandardId
       require_scopes!(*_protected_resource_scopes)
     end
 
+    # The `aud` a token for this resource must carry (the audience itself,
+    # unless its `protected_resources` entry says otherwise).
+    def protected_resource_token_audience
+      StandardId::Oauth::ProtectedResourceDocument.token_audience(
+        audience: protected_resource_audience, origin: protected_resource_origin
+      )
+    end
+
+    # Memoized: the host's `origin:` callable answers once per request, so
+    # the audience check, the challenge and the metadata URL agree.
+    def protected_resource_origin
+      @protected_resource_origin ||=
+        StandardId::Oauth::ProtectedResourceDocument.origin_for(protected_resource_audience, request: request)
+    end
+
     def protected_resource_metadata_url
-      StandardId::Oauth::ProtectedResourceDocument.metadata_url(audience: protected_resource_audience, origin: request.base_url)
+      StandardId::Oauth::ProtectedResourceDocument.metadata_url(audience: protected_resource_audience, origin: protected_resource_origin)
     end
 
     # The description never carries operator- or user-authored text: it goes
@@ -133,7 +150,7 @@ module StandardId
       response.set_header(
         "WWW-Authenticate",
         StandardId::Oauth::ProtectedResourceDocument.challenge(
-          audience: protected_resource_audience, origin: request.base_url,
+          audience: protected_resource_audience, origin: protected_resource_origin,
           error: error, error_description: error_description, scope: scope
         )
       )

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/app/controllers/standard_id/api/base_controller.rb

@@ -31,6 +31,9 @@ module StandardId
       # WebEngine's existing handling covers it — so it is mapped here.
       rescue_from StandardId::LoginMethodDenied, with: :handle_login_method_denied
 
+      # A host hook refused the request with its own response.
+      rescue_from StandardId::RequestRefused, with: :handle_request_refused
+
       protected
 
       def validate_content_type!
@@ -90,6 +93,11 @@ module StandardId
         }, status: error.http_status
       end
 
+      def handle_request_refused(error)
+        error.headers.each { |name, value| response.set_header(name.to_s, value.to_s) }
+        render json: error.body, status: error.status
+      end
+
       def handle_oauth_error(error)
         # A lib-level rate limit (StandardId::RateLimiter) knows its window;
         # say so, as the controller-level limits do.

data/app/controllers/standard_id/api/oauth/callback/providers_controller.rb

@@ -22,6 +22,7 @@ module StandardId
           provider_response = fetch_provider_user_info
           social_info = provider_response[:user_info]
           provider_tokens = provider_response[:tokens]
+          run_before_social_account(social_info:, provider_tokens:)
           account = find_or_create_account_from_social(social_info)
           newly_created = account.previously_new_record?
 
@@ -33,8 +34,16 @@ module StandardId
           # new account, and no usable token or session from this request.
           token_response = nil
           flow = nil
+          completion_before_mint = StandardId.config.social.completion_before_mint
           begin
             run_before_social_mint(account:, social_info:, provider_tokens:)
+            if completion_before_mint
+              complete_social_sign_in(account:, social_info:, provider_tokens:)
+              # The subscriber may have created records hanging off +account+
+              # (a profile); the mint, and AccountCleanup on a refusal, must
+              # see the database rather than those in-memory objects.
+              account.reload
+            end
             flow = StandardId::Oauth::SocialFlow.new(
               params,
               request,
@@ -43,13 +52,7 @@ module StandardId
               scopes: params[:scope]
             )
             token_response = flow.execute
-            run_social_callback(
-              provider: provider.provider_name,
-              social_info:,
-              provider_tokens:,
-              account:,
-              original_request_params: forwarded_request_params
-            )
+            complete_social_sign_in(account:, social_info:, provider_tokens:) unless completion_before_mint
             commit_social_link!
           rescue StandardError
             removed = social_account_removed_concurrently?(account, newly_created:)
@@ -72,25 +75,54 @@ module StandardId
           true
         end
 
+        def complete_social_sign_in(account:, social_info:, provider_tokens:)
+          run_social_callback(
+            provider: provider.provider_name,
+            social_info:,
+            provider_tokens:,
+            account:,
+            original_request_params: forwarded_request_params
+          )
+        end
+
+        # config.social.before_account: before find-or-create, so a refusal
+        # here has nothing to clean up. The hook audits its own refusals: no
+        # event is published for them (none would have an account to name).
+        def run_before_social_account(social_info:, provider_tokens:)
+          call_social_hook(StandardId.config.social.before_account,
+            provider: provider.provider_name,
+            social_info: social_info,
+            provider_tokens: provider_tokens,
+            **requested_audience_and_scopes,
+            params: forwarded_request_params,
+            request: request)
+        end
+
         # config.social.before_mint, inside the same begin/rescue as the mint
-        # so a refusal here is cleaned up exactly like one from the grant.
+        # so a refusal here is cleaned up exactly like one from the grant —
+        # except in the concurrent-removal race, where the retryable
+        # InvalidGrantError replaces even a StandardId::RequestRefused.
         def run_before_social_mint(account:, social_info:, provider_tokens:)
-          hook = StandardId.config.social.before_mint
-          return unless hook.respond_to?(:call)
-
-          # audience: and scopes: are passed explicitly: forwarded_request_params
-          # strips both (RESERVED_CALLBACK_PARAMS), and the audience is the
-          # thing the headline use case keys on.
-          context = {
+          call_social_hook(StandardId.config.social.before_mint,
             account: account,
             provider: provider.provider_name,
             social_info: social_info,
             provider_tokens: provider_tokens,
-            audience: params[:audience].presence,
-            scopes: params[:scope].presence,
+            **requested_audience_and_scopes,
             params: forwarded_request_params,
-            request: request
-          }
+            request: request)
+        end
+
+        # audience: and scopes: are passed explicitly: forwarded_request_params
+        # strips both (RESERVED_CALLBACK_PARAMS), and the audience is the
+        # thing the headline use cases key on.
+        def requested_audience_and_scopes
+          { audience: params[:audience].presence, scopes: params[:scope].presence }
+        end
+
+        def call_social_hook(hook, **context)
+          return unless hook.respond_to?(:call)
+
           hook.call(**StandardId::Utils::CallableParameterFilter.filter(hook, context))
         end
 

data/app/controllers/standard_id/api/well_known/oauth_protected_resource_controller.rb

@@ -28,7 +28,9 @@ module StandardId
 
           response.headers["Cache-Control"] = "public, max-age=3600"
           render json: StandardId::Oauth::ProtectedResourceDocument.build(
-            audience: audience, origin: request.base_url, request: request
+            audience: audience,
+            origin: StandardId::Oauth::ProtectedResourceDocument.origin_for(audience, request: request),
+            request: request
           )
         end
 

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
@@ -443,6 +461,10 @@ StandardId::ConfigSchema.define do
     # emitted as given (callables receive `{ origin:, audience:, issuer:,
     # request: }`; nil removes a member). `root: true` picks the resource the
     # bare /.well-known/oauth-protected-resource serves when several exist.
+    # `origin: ->(request:) { ... }` builds `resource` and the metadata URL on
+    # a public origin other than `request.base_url` (a rewriting proxy);
+    # `audience: :resource` says tokens for the resource carry its absolute URL
+    # as `aud` rather than the key (or a String names that `aud`).
     #
     #   c.oauth.protected_resources = { "mcp" => { path: "/mcp", scopes_supported: %w[mcp mcp:read] } }
     #
@@ -712,10 +734,30 @@ StandardId::ConfigSchema.define do
     # if those refuse the sign-in on an account that already existed, whatever
     # the hook wrote stays (make it idempotent); and it covers the API
     # callback only — the WebEngine's social callback does not run it.
-    # SOCIAL_AUTH_COMPLETED still fires after the mint as before. Replaces the
+    # SOCIAL_AUTH_COMPLETED fires after the mint unless completion_before_mint
+    # is set; raise StandardId::RequestRefused to answer in the host's own
+    # error envelope. Replaces the
     # host subclass of the callback controller that reordered these steps by
     # copying its body.
     field :before_mint, type: :any, default: nil
+    # Runs on the API social callback once the provider has vouched for the
+    # user and BEFORE the account is found or created — for a refusal that
+    # must leave no account row and fire no account events (a region block).
+    # A callable taking any subset of `provider:`, `social_info:`,
+    # `provider_tokens:`, `audience:`, `scopes:`, `params:` (forwarded, as for
+    # before_mint) and `request:`. Raising refuses the sign-in with nothing
+    # written; raise StandardId::RequestRefused to answer with the host's own
+    # response. No event is published for the refusal: audit it in the hook.
+    # API callback only, like before_mint.
+    field :before_account, type: :any, default: nil
+    # When true, the API social callback publishes SOCIAL_AUTH_COMPLETED after
+    # before_mint and BEFORE the mint (then reloads the account), instead of
+    # after it — for a host whose completion subscriber writes what the mint
+    # depends on (accepting an invitation that creates the profile the
+    # audience is bound to). A refusal at the mint then comes after the
+    # subscriber's writes, which stay on an account that already existed, so
+    # the subscriber must be idempotent. The web callback is unchanged.
+    field :completion_before_mint, type: :boolean, default: false
     field :allowed_redirect_url_prefixes, type: :array, default: []
     field :available_scopes, type: :array, default: -> { [] }
     # How a social login whose (provider, sub) is not linked yet may link to

data/lib/standard_id/errors.rb

@@ -191,6 +191,27 @@ module StandardId
   # Lifecycle hook errors
   class AuthenticationDenied < StandardError; end
 
+  # Raised by a host hook (`config.social.before_account`,
+  # `config.social.before_mint`) to refuse a request with the host's own
+  # response: the API engine renders `body` as JSON with `status` (and any
+  # `headers`) verbatim, after the refusing flow has cleaned up as for any
+  # other refusal. For a refusal the host's clients must be able to tell apart
+  # from an OAuth error — a region block, a pending deletion — in the host's
+  # error envelope.
+  #
+  #   raise StandardId::RequestRefused.new(status: :forbidden,
+  #     body: { error: { code: "REGION_BLOCKED", message: "..." } })
+  class RequestRefused < StandardError
+    attr_reader :status, :body, :headers
+
+    def initialize(status:, body:, headers: {}, message: nil)
+      @status = status
+      @body = body
+      @headers = headers.to_h
+      super(message || "Request refused (#{status})")
+    end
+  end
+
   # Raised when `config.login_method_policy` refuses an authentication method
   # for an account (e.g. "staff must sign in with the org IdP"). See
   # StandardId::LoginMethodPolicy.

data/lib/standard_id/events/definitions.rb

@@ -46,6 +46,9 @@ module StandardId
       OAUTH_REFRESH_TOKEN_REUSE_DETECTED = "oauth.refresh_token.reuse_detected"
       OAUTH_REFRESH_TOKEN_REUSE_GRACED = "oauth.refresh_token.reuse_graced"
       OAUTH_AUDIENCE_MISMATCH = "oauth.audience.mismatch"
+      OAUTH_CLIENT_REGISTERED = "oauth.client.registered"
+      OAUTH_CLIENT_UPDATED = "oauth.client.updated"
+      OAUTH_CLIENT_DEREGISTERED = "oauth.client.deregistered"
 
       PASSWORDLESS_CODE_REQUESTED = "passwordless.code.requested"
       PASSWORDLESS_CODE_GENERATED = "passwordless.code.generated"
@@ -122,7 +125,10 @@ module StandardId
         OAUTH_TOKEN_REVOKED,
         OAUTH_REFRESH_TOKEN_REUSE_DETECTED,
         OAUTH_REFRESH_TOKEN_REUSE_GRACED,
-        OAUTH_AUDIENCE_MISMATCH
+        OAUTH_AUDIENCE_MISMATCH,
+        OAUTH_CLIENT_REGISTERED,
+        OAUTH_CLIENT_UPDATED,
+        OAUTH_CLIENT_DEREGISTERED
       ].freeze
 
       PASSWORDLESS_EVENTS = [
@@ -184,6 +190,9 @@ module StandardId
         OAUTH_TOKEN_REVOKED,
         OAUTH_REFRESH_TOKEN_REUSE_DETECTED,
         OAUTH_AUDIENCE_MISMATCH,
+        OAUTH_CLIENT_REGISTERED,
+        OAUTH_CLIENT_UPDATED,
+        OAUTH_CLIENT_DEREGISTERED,
         # Passwordless
         PASSWORDLESS_CODE_FAILED,
         PASSWORDLESS_ACCOUNT_CREATED,

data/lib/standard_id/events/subscribers/logging_subscriber.rb

@@ -40,6 +40,9 @@ module StandardId
           "oauth.token.issued" => :info,
           "oauth.token.refreshed" => :debug,
           "oauth.code.consumed" => :debug,
+          "oauth.client.registered" => :info,
+          "oauth.client.updated" => :info,
+          "oauth.client.deregistered" => :info,
           "passwordless.code.requested" => :debug,
           "passwordless.code.generated" => :debug,
           "passwordless.code.sent" => :info,

data/lib/standard_id/oauth/audience_profile_resolver.rb

@@ -83,6 +83,18 @@ module StandardId
           ) { resolve_bound_profile!(account, audience) }
         end
 
+        # The type name a profile is matched on: `profileable_type`, else
+        # `type`, else its class name.
+        def profile_type_for(profile)
+          if profile.respond_to?(:profileable_type)
+            profile.profileable_type.to_s
+          elsif profile.respond_to?(:type)
+            profile.type.to_s
+          else
+            profile.class.name.to_s
+          end
+        end
+
         private
 
         def resolve_bound_profile!(account, audience)
@@ -163,16 +175,6 @@ module StandardId
             )
           end
         end
-
-        def profile_type_for(profile)
-          if profile.respond_to?(:profileable_type)
-            profile.profileable_type.to_s
-          elsif profile.respond_to?(:type)
-            profile.type.to_s
-          else
-            profile.class.name.to_s
-          end
-        end
       end
     end
   end

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/oauth/client_registration.rb

@@ -87,9 +87,40 @@ module StandardId
             client.refresh_tokens.where(revoked_at: nil).update_all(revoked_at: now)
           end
         end
+        publish_lifecycle_event(StandardId::Events::OAUTH_CLIENT_DEREGISTERED, client)
         client
       end
 
+      # OAUTH_CLIENT_REGISTERED / _UPDATED / _DEREGISTERED, after the change has
+      # committed — the outermost transaction, so a host that wraps the call in
+      # its own transaction gets no event for a change it then rolls back
+      # (and gets it immediately when no transaction is open). The owner is identified by type and id rather than published
+      # as a record: on update and deregister it is not loaded, and a host
+      # running strict_loading_by_default would refuse the lazy read. Never
+      # raises: the change is already committed, and a registration whose
+      # one-time secret and registration access token never reach the client
+      # because an audit subscriber failed is worse than a missing audit row.
+      def self.publish_lifecycle_event(event, client, client_metadata: nil)
+        payload = {
+          client_application: client,
+          client_id: client.client_id,
+          client_name: client.name,
+          client_type: client.client_type,
+          redirect_uris: client.redirect_uris_array,
+          scope: client.scopes,
+          owner_type: client.owner_type,
+          owner_id: client.owner_id
+        }
+        payload[:client_metadata] = client_metadata unless client_metadata.nil?
+        ActiveRecord.after_all_transactions_commit do
+          StandardId::Events.publish(event, payload)
+        rescue StandardError => e
+          StandardId.logger&.warn("[StandardId] failed to publish #{event}: #{e.class}: #{e.message}")
+        end
+      rescue StandardError => e
+        StandardId.logger&.warn("[StandardId] failed to publish #{event}: #{e.class}: #{e.message}")
+      end
+
       # Everything, the owner resolver included, runs inside one transaction:
       # a host whose resolver creates a per-registration owner row must not be
       # left with that row when the client itself is refused.
@@ -117,6 +148,7 @@ module StandardId
           end
         end
 
+        self.class.publish_lifecycle_event(StandardId::Events::OAUTH_CLIENT_REGISTERED, client, client_metadata: metadata)
         Result.new(client: client, client_secret: secret_plaintext, token_endpoint_auth_method: auth_method,
           registration_access_token: registration_access_token)
       rescue ActiveRecord::RecordInvalid => e
@@ -144,6 +176,7 @@ module StandardId
         attrs[:scopes] = scope unless pinned.key?("scopes") || metadata[:scope].blank?
 
         client.update!(attrs)
+        self.class.publish_lifecycle_event(StandardId::Events::OAUTH_CLIENT_UPDATED, client, client_metadata: metadata)
         Result.new(client: client, token_endpoint_auth_method: client.token_endpoint_auth_method)
       rescue ActiveRecord::RecordInvalid => e
         raise_for(e.record)

data/lib/standard_id/oauth/direct_mint_flow.rb

@@ -13,9 +13,16 @@ module StandardId
     # grant_type strings to flows explicitly, and this one is never in that
     # map. The caller supplies the account; the flow authenticates nothing.
     class DirectMintFlow < TokenGrantFlow
+      AUDIT_ERROR_MODES = %i[raise report].freeze
+
       def initialize(account:, audience:, grant_type:, scopes: nil, client_id: nil, claims: {}, expires_in: nil,
-        refresh_token: false, request: nil, auth_method: nil, auth_provider: nil)
+        refresh_token: false, request: nil, auth_method: nil, auth_provider: nil, profile: nil, audit_errors: :raise)
         super({ audience: audience }, request || NullRequest.new)
+        @profile = profile
+        @audit_errors = audit_errors.to_s.to_sym
+        unless AUDIT_ERROR_MODES.include?(@audit_errors)
+          raise ArgumentError, "audit_errors must be one of #{AUDIT_ERROR_MODES.join(', ')} (got #{audit_errors.inspect})"
+        end
         @account = account
         @audience = audience
         @grant_type = grant_type.to_s
@@ -34,6 +41,10 @@ module StandardId
         @issued_jti
       end
 
+      # The error an OAUTH_TOKEN_ISSUED subscriber raised under
+      # `audit_errors: :report`, else nil.
+      attr_reader :audit_error
+
       def authenticate!
         raise StandardId::InvalidGrantError, "Account is required" if @account.nil?
         raise StandardId::InvalidGrantError, "Account must be persisted" unless @account.respond_to?(:persisted?) && @account.persisted?
@@ -51,6 +62,65 @@ module StandardId
 
       private
 
+      # An explicit profile replaces the strict lookup: the host already knows
+      # which of the account's profiles the token is for (several of one type
+      # is legitimate there, and AmbiguousProfileError would refuse it). It
+      # must still be the account's, active, and of the bound type when the
+      # audience has a binding — the guarantees the lookup gives. Resolvers
+      # receive it as `profile:` either way. config.oauth.audience_profile_resolver
+      # is NOT consulted: the host chose the profile, so any extra gate that
+      # resolver applies is the caller's to apply before minting.
+      def enforce_audience_profile_binding!
+        return super if @profile.nil?
+
+        validate_explicit_profile!
+        @resolved_profile = @profile
+      end
+
+      def validate_explicit_profile!
+        unless profile_belongs_to_account?(@profile)
+          raise StandardId::InvalidGrantError, "profile does not belong to the account"
+        end
+        if @profile.respond_to?(:active?) && !@profile.active?
+          raise StandardId::InvalidGrantError, "profile is not active"
+        end
+
+        bound = profile_bound_audience
+        return if bound.nil?
+
+        types = StandardId::Oauth::AudienceProfileResolver.profile_types_for(bound)
+        return if types.include?(StandardId::Oauth::AudienceProfileResolver.profile_type_for(@profile))
+
+        raise StandardId::InvalidGrantError,
+          "profile is not of a type bound to audience #{bound.inspect} (expected #{types.join(', ')})"
+      end
+
+      def profile_belongs_to_account?(profile)
+        return profile.account_id.to_s == @account.id.to_s if profile.respond_to?(:account_id)
+        return @account.profiles.include?(profile) if @account.respond_to?(:profiles)
+
+        false
+      end
+
+      # Under `audit_errors: :report` a raising OAUTH_TOKEN_ISSUED subscriber
+      # no longer costs the caller a token that is already signed (and, with a
+      # refresh token, committed): the error is logged and handed back on the
+      # result. OAUTH_TOKEN_ISSUING is never softened — its subscribers are the
+      # account-status and locking guards.
+      def emit_token_issued(expires_in)
+        return super if @audit_errors == :raise
+
+        begin
+          super
+        rescue StandardError => e
+          @audit_error = e
+          StandardId.config.logger&.error(
+            "[StandardId] OAUTH_TOKEN_ISSUED subscriber raised for #{grant_type} (token still issued): " \
+            "#{e.class}: #{e.message} at #{e.backtrace&.first}"
+          )
+        end
+      end
+
       # No new authentication happened here: the host vouches for the account.
       def login_method_policy_context
         nil

data/lib/standard_id/oauth/protected_resource_document.rb

@@ -20,6 +20,19 @@ module StandardId
     # origin. Any member may be a callable taking one Hash
     # `{ origin:, audience:, issuer:, request: }`; a nil value removes the member.
     #
+    # Two members configure the resource rather than the document:
+    #
+    #   origin:   ->(request:) { ENV.fetch("PUBLIC_URL") { request.base_url } }
+    #             the origin `resource` and the metadata URL are built on, for a
+    #             host behind a proxy that rewrites `request.base_url`
+    #             (default: the request's origin)
+    #   audience: :resource
+    #             tokens for this resource carry its absolute URL (`resource`)
+    #             as `aud`, RFC 8707 style, instead of the key; or a String
+    #             naming that `aud`. The key stays the resource's name: what
+    #             `protected_resource` and `audience_scopes` refer to, and the
+    #             challenge realm.
+    #
     # The document for a resource is served at
     # `<origin>/.well-known/oauth-protected-resource<path>` (RFC 9728 §3.1,
     # the path-inserted form that is the exact URL the challenge names) by
@@ -43,7 +56,7 @@ module StandardId
       WELL_KNOWN_PATH = "/.well-known/oauth-protected-resource".freeze
       # `resource` is computed, never configured: RFC 9728 §3.3 requires it to
       # match the URL the client used, which is the request origin plus `path`.
-      RESERVED_KEYS = %w[path root resource].freeze
+      RESERVED_KEYS = %w[path root resource origin audience].freeze
 
       module_function
 
@@ -81,6 +94,35 @@ module StandardId
         nil
       end
 
+      # The origin `audience`'s documents and challenges are built on: the
+      # entry's `origin` callable when it returns one, else the request's.
+      def origin_for(audience, request:)
+        configured_origin = configured.dig(audience.to_s, "origin")
+        resolved = if configured_origin.respond_to?(:call)
+          args = StandardId::Utils::CallableParameterFilter.filter(configured_origin, { request: request })
+          configured_origin.call(**args)
+        else
+          configured_origin
+        end
+        (resolved.presence || request&.base_url).to_s.chomp("/")
+      end
+
+      # The `aud` tokens for `audience` carry: the key itself (also for an
+      # audience with no entry, as before entries could say otherwise), the
+      # resource's absolute URL (`audience: :resource`), or the String the
+      # entry names.
+      # @raise [StandardId::ConfigurationError] for an `audience` member of any
+      #   other shape
+      def token_audience(audience:, origin:)
+        value = configured.dig(audience.to_s, "audience")
+        return audience.to_s if value.nil?
+        return resource_url(audience: audience, origin: origin) if value.to_s == "resource"
+        return value if value.is_a?(String) && value.present?
+
+        raise StandardId::ConfigurationError,
+          "oauth.protected_resources[#{audience.inspect}][:audience] must be :resource or a String (got #{value.inspect})"
+      end
+
       # Absolute URL of the resource (RFC 9728 `resource`).
       def resource_url(audience:, origin:)
         path = path_for!(audience)

data/lib/standard_id/oauth/token_grant_flow.rb

@@ -362,26 +362,30 @@ module StandardId
       # 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 = profile_bound_audience
+        return if bound.nil?
 
-        bound = requested.select { |a| StandardId::Oauth::AudienceProfileResolver.configured_for?(a) }
-        return if bound.empty?
+        @resolved_profile = StandardId::Oauth::AudienceProfileResolver.resolve!(
+          account: token_account,
+          audience: bound
+        )
+      end
 
-        # 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.
+      # The one requested audience with a profile-type binding, or nil.
+      #
+      # 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.
+      def profile_bound_audience
+        bound = Array(audience).reject(&:blank?).select { |a| StandardId::Oauth::AudienceProfileResolver.configured_for?(a) }
         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
-        )
+        bound.first
       end
 
       def claims_from_custom_claims

data/lib/standard_id/token_minter.rb

@@ -29,7 +29,13 @@ module StandardId
   # Raises the same errors the token endpoint would (InvalidGrantError,
   # InvalidRequestError, NoBoundProfileError, AccountDeactivatedError, …).
   module TokenMinter
-    Result = Data.define(:access_token, :refresh_token, :token_type, :expires_in, :scope, :jti)
+    Result = Data.define(:access_token, :refresh_token, :token_type, :expires_in, :scope, :jti, :audit_error) do
+      # audit_error arrived in 0.51; optional so a host spec that builds a
+      # Result to stub +mint+ keeps working.
+      def initialize(audit_error: nil, **members)
+        super
+      end
+    end
 
     module_function
 
@@ -52,13 +58,26 @@ module StandardId
     #   account, recorded on the refresh token for login_method_policy; nil is
     #   judged as :unspecified on refresh, which a restrictive policy refuses
     # @param auth_provider [String, nil]
+    # @param profile [ActiveRecord::Base, nil] the account's profile the token
+    #   is for, instead of the strict audience → profile lookup (which refuses
+    #   an account holding several active profiles of the bound type). Must
+    #   belong to the account, be active, and be of the bound type when the
+    #   audience has a binding; claim resolvers receive it as `profile:`.
+    #   oauth.audience_profile_resolver is not consulted for it — apply any
+    #   gate that resolver enforces before calling.
+    # @param audit_errors [Symbol] :raise (default) re-raises an
+    #   OAUTH_TOKEN_ISSUED subscriber's error, as every grant does; :report
+    #   logs it and returns it as +Result#audit_error+ with the token, for a
+    #   caller whose contract is that an audit failure never costs it the
+    #   credential. Report it to your error tracker: the gem only logs it.
+    #   OAUTH_TOKEN_ISSUING (the status / locking guards) always raises.
     # @return [Result]
     def mint(account:, audience:, grant_type:, scopes: nil, client_id: nil, claims: {}, expires_in: nil,
-      refresh_token: false, request: nil, auth_method: nil, auth_provider: nil)
+      refresh_token: false, request: nil, auth_method: nil, auth_provider: nil, profile: nil, audit_errors: :raise)
       flow = StandardId::Oauth::DirectMintFlow.new(
         account: account, audience: audience, grant_type: grant_type, scopes: scopes, client_id: client_id,
         claims: claims, expires_in: expires_in, refresh_token: refresh_token, request: request,
-        auth_method: auth_method, auth_provider: auth_provider
+        auth_method: auth_method, auth_provider: auth_provider, profile: profile, audit_errors: audit_errors
       )
       response = flow.execute
       Result.new(
@@ -67,7 +86,8 @@ module StandardId
         token_type: response[:token_type],
         expires_in: response[:expires_in],
         scope: response[:scope],
-        jti: flow.issued_jti
+        jti: flow.issued_jti,
+        audit_error: flow.audit_error
       )
     end
   end

data/lib/standard_id/version.rb

@@ -1,3 +1,3 @@
 module StandardId
-  VERSION = "0.49.1"
+  VERSION = "0.51.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.51.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