standard_id 0.48.1 → 0.49.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cdf22579e98c4ceb592cb20766d510d937d0e5d2f7f70c41074f984ddc3b0393
-  data.tar.gz: 35fbb21a24d40a307bd55279a86fa0d91549641e30f30d4101d667d9c5d7c793
+  metadata.gz: 960b6bdf3cc6fd613e1f3cdb6a172f9b30fb42f2c215174787f7858f0c532075
+  data.tar.gz: 654fde0c77971e868578805a3d033909adbe49da8006ca1f1174110975e2b255
 SHA512:
-  metadata.gz: cd202ffabe7287cb374442e6aeee83d0f2853a17d9cb7654ba816f28f48c4d6970b859b7d4d83581f09ef4a2793689b5fc620b545246bfb515691fda9a4cd1dd
-  data.tar.gz: 0e17bfff08af26fc343dedaf0d9500bbef69fe118031c305bdc29f33ede7231c8641c14b2b6156395702c4957c58b605dc6a24b54b4f975fa19618c8f4cade01
+  metadata.gz: f5a099d1243e7ac19872b907c402937941a3718efec2caffa7fc75af717893bc6b685671d528929e99c658bc08187cb58d776fc36c744978190f1c850bf5c457
+  data.tar.gz: db01eff1f65d191da0166de6f09def5231d88a9675d6240efd0d2c0eddd02b91553b2aad9f1d062d026fccfcf9d17ee1ffca4e04c2b6e1cfe4b627229d8a56be

data/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.49.0] - 2026-10-20
+
+### Added
+
+- **Dynamic client registration pins what the client may not choose, and RFC 7592 manages it.** `c.oauth.dynamic_registration_attributes` (Hash or callable `(metadata:, request:)`) pins `scopes`, `metadata` (e.g. `"audience" => "mcp"`, which `/authorize` now reads), `access_token_lifetime`, `authorization_code_lifetime`, `require_consent` and `description` on every registered client; with no `scopes` pinned, a pinned audience's `audience_scopes` vocabulary is the client's scope. `c.oauth.dynamic_registration_auth_methods` allowlists `token_endpoint_auth_method`. `dynamic_registration_owner` may now take `(metadata:, request:)`. Migration **`20261020120000`** adds `registration_access_token_digest` to client applications; once run, registration returns a one-time `registration_access_token` + `registration_client_uri`, and `GET`/`PUT`/`DELETE /oauth/register/:client_id` (RFC 7592) read, update (client-shaped members only) and deregister (deactivate + revoke refresh tokens) the client, authenticated by that token and throttled separately (`c.rate_limits.dynamic_registration_management_per_ip`, 60/hour). **`StandardId::PurgeStaleDynamicClientsJob`** (also in `CleanupAllJob`, `standard_id:cleanup:dynamic_clients`, and scheduled daily by the install generator) deletes deregistered clients and never-authorized ones after a grace window. Replaces the per-app `RegisterDynamicClient` operation (and sidekick's RFC 7592 update/delete/purge) every consumer carried.
+- **RFC 9728 protected-resource metadata and `StandardId::ResourceServer`.** `c.oauth.protected_resources = { "mcp" => { path: "/mcp" } }` declares the resources a host serves, keyed by audience; `standard_id_protected_resource_routes` serves their documents at `/.well-known/oauth-protected-resource(/<path>)` (also under the engine mount), built by `StandardId::Oauth::ProtectedResourceDocument` with `scopes_supported` from `audience_scopes`, `authorization_servers` from the issuer, and any other member from the entry. `include StandardId::ResourceServer` + `protected_resource "mcp", scopes: %w[mcp]` is the bearer check a resource server needs: token verification, audience verification, optional scope requirement, and RFC 6750 `401 invalid_token` / `403 insufficient_scope` responses whose `WWW-Authenticate` challenge carries the `resource_metadata` pointer the MCP authorization spec requires. Replaces the protected-resource controller and the hand-rolled 401 every consumer carried. A request with no credential gets the RFC 6750 §3.1 form (realm + `resource_metadata`, no error code); `metadata_url` raises `ConfigurationError` for an unconfigured audience instead of naming a bare URL; `resource` is computed, never configured.
+
+- **`/authorize` resolves the audience server-side** (`StandardId::Oauth::AudienceResolver`): `c.oauth.audience_resolver` (callable) when set, else the `audience` param, else the RFC 8707 **`resource`** param mapped through the new **`c.oauth.resource_audiences`** hash, else the client's registered default `metadata["audience"]`. The result is bound to the authorization code as before. `resource` is now a permitted parameter on both authorize flows and accepted at the token endpoint. A dynamically registered client whose registration stamps `metadata["audience"]` therefore gets its `aud` with no audience-injecting shim in front of the endpoint — the shim every consumer carried (sidekick-web #1126 → nutripod-web #949 → luminality-web #821 → fundbright-web #809).
+- **`c.oauth.audience_scopes` is enforced at `/authorize`**: a scope outside the resolved audience's vocabulary is refused with `invalid_scope` before anything is issued (unconfigured audiences and empty scopes pass through, as before). This is the one behaviour change for a consumer that already configures `audience_scopes`: a client requesting a scope outside its audience's vocabulary now gets `invalid_scope` where it used to get a code. The check is only as strong as `allowed_audiences` at the token endpoint, since a client-supplied `audience` still outranks the registered default.
+- **`StandardId::InvalidTargetError`** (`invalid_target`, RFC 8707 §2): raised at `/authorize` when `c.oauth.resource_audiences` is configured and the `resource` parameter is not in it. With no mapping configured the parameter is ignored, so a host relying on the client's registered default still gets it when MCP clients send `resource` on every request.
+- `c.oauth.audience_resolver` and `c.oauth.audience_scope_resolver` are now checked at boot by `Config::CallableValidator` (an unsupported keyword fails at boot, not at request time). The audience resolver must return a String, Symbol or nil; anything else raises `StandardId::ConfigurationError`.
+
+### Added
+
+- **`StandardId::TokenMinter.mint(account:, audience:, grant_type:, scopes:, client_id:, claims:, expires_in:, refresh_token:, request:)`**: mint a token for an account the host already authenticated, through the same pipeline as `/oauth/token` (`Oauth::DirectMintFlow`, not reachable from the endpoint): audience validation, audience → profile binding, `scope_claims` / `claim_resolvers` / `custom_claims`, the AccountStatus / AccountLocking guards, `OAUTH_TOKEN_ISSUING` / `OAUTH_TOKEN_ISSUED`, optional refresh token (bound to `client_id`'s application) and session persistence when a request is passed. Replaces the hand-rolled `JwtService.encode` mint sites that re-derive the initializer's claim resolvers (sidekick-web has nine).
+- **`c.social.before_mint`** (callable): runs on the API social callback after the account is found or created and before the token is minted, with any subset of `account:`, `provider:`, `social_info:`, `provider_tokens:`, `params:`, `request:`. Raising refuses the sign-in through the callback's existing cleanup. Replaces the host subclass of `Api::Oauth::Callback::ProvidersController` that reordered those steps by copying the method body (sidekick-web, re-synced on 6 of the last 10 bumps).
+
 ## [0.48.1] - 2026-10-20
 
 ### Added

data/README.md

@@ -278,6 +278,39 @@ It honours the current scope, returns `nil` (never raises) for a blank,
 unknown, mismatched, or malformed-digest token, and has an instance-level
 counterpart, `session.authenticate_token(token)`.
 
+### Minting Tokens Outside the Token Endpoint
+
+`StandardId::TokenMinter` mints a token for an account the host has already
+authenticated by its own means — an operator console, a service-to-service
+credential, a self-service "mint me a token" tool — through the same pipeline
+`/oauth/token` uses, so it carries the same claims, obeys the same audience →
+profile binding and account-status guards, and publishes the same
+`OAUTH_TOKEN_ISSUING` / `OAUTH_TOKEN_ISSUED` events:
+
+```ruby
+result = StandardId::TokenMinter.mint(
+  account: account,
+  audience: "harness",
+  scopes: "profile permissions",
+  grant_type: "harness.mint",          # free-form; lands in the JWT and the audit event
+  claims: { permissions: profile.harness_scopes },  # host extras; reserved keys are dropped
+  expires_in: 60.minutes,
+  refresh_token: false                  # true also persists and returns a refresh token
+)
+result.access_token
+result.jti                              # what OAUTH_TOKEN_ISSUED carried
+```
+
+`scope_claims` / `claim_resolvers` and `custom_claims` run exactly as for the
+endpoint (the resolvers see `client:` as the `ClientApplication` named by
+`client_id:`, or nil, and `request:` as nil for a sessionless mint). Pass
+`request:` to let `session.session_type_resolver` materialise a session;
+without it the mint is sessionless, like `client_credentials`. A refreshable
+token needs `client_id:` (the refresh grant matches on it) and, under a
+`login_method_policy`, `auth_method:` / `auth_provider:` so the refresh is not
+judged as `:unspecified`. `expires_in:` must be positive. The grant is not
+reachable from `/oauth/token`.
+
 ### Custom Token Claims
 
 You can add additional JWT claims for any token issued through the OAuth token endpoint by mapping scopes to claim names and providing callbacks to resolve each claim. Scopes listed in `oauth.scope_claims` are evaluated against the requested token scopes; when a scope matches, every claim listed for that scope is resolved via the callable defined in `oauth.claim_resolvers`.
@@ -331,8 +364,121 @@ R.assert!(requested: %w[mcp mcp:admin], audience: "companion_kit") # => raises I
 
 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.
 
+### Serving a Protected Resource (RFC 9728)
+
+A resource server — an MCP endpoint, a service API — needs three things: the bearer
+check, a 401/403 that tells the client where the authorization server is, and the
+RFC 9728 metadata document that 401 points at. The gem provides all three.
+
+```ruby
+# config/initializers/standard_id.rb
+StandardId.configure do |config|
+  config.oauth.audience_scopes = { "mcp" => %w[mcp mcp:read] }
+  config.oauth.protected_resources = {
+    "mcp" => { path: "/mcp" }   # scopes_supported defaults to audience_scopes["mcp"]
+  }
+end
+
+# config/routes.rb
+standard_id_protected_resource_routes   # /.well-known/oauth-protected-resource(/mcp)
+
+# app/controllers/mcp/base_controller.rb
+class Mcp::BaseController < ActionController::API
+  include StandardId::ResourceServer
+  protected_resource "mcp", scopes: %w[mcp]
+end
+```
+
+`protected_resource` verifies the access token, requires its `aud` to carry the
+audience (with the audience → profile-type binding when configured) and one of
+`scopes:` when given. A missing, expired, revoked or invalid token, or a deactivated
+or locked account, is `401 invalid_token`; a token for another audience or without a
+required scope is `403 insufficient_scope`. Every refusal carries
+`WWW-Authenticate: Bearer realm="mcp", error=…, resource_metadata="<origin>/.well-known/oauth-protected-resource/mcp"`,
+which is how an MCP client discovers the authorization server and starts the
+authorization-code + PKCE flow. The document itself is built by
+`StandardId::Oauth::ProtectedResourceDocument` from the entry: `path` (required, or
+an absolute URL on another origin), `scopes_supported`, `authorization_servers`
+(default `[issuer]`), `bearer_methods_supported` (default `["header"]`) and any other
+RFC 9728 member; callables receive `{ origin:, audience:, issuer:, request: }` and
+`nil` removes a member. Rate limiting and resolving the token's claims to a profile
+stay in the host controller.
+
+Two things to know. The document's `resource` and the challenge URL are built from
+the request origin, as RFC 9728 §3.3 requires, so pin `Host` (`config.hosts`, or at
+the proxy): the document is served with `Cache-Control: public`. And a token minted
+for an audience outside `config.oauth.allowed_audiences` is refused at decode time
+as `401 invalid_token`, before the concern sees it; the `403 insufficient_scope` is
+for a token minted for another *allowed* audience.
+
+### Dynamic Client Registration (RFC 7591 / RFC 7592)
+
+`POST /oauth/register` is off by default (`config.oauth.dynamic_registration_enabled`).
+When on, a self-registering client (an MCP connector, say) chooses only what a client
+should: its name, redirect URIs, grant and response types, and its
+`token_endpoint_auth_method` from `config.oauth.dynamic_registration_auth_methods`
+(`%w[none]` to accept public PKCE clients only). Everything else is yours to pin:
+
+```ruby
+StandardId.configure do |config|
+  config.oauth.dynamic_registration_enabled = true
+  config.oauth.dynamic_registration_owner = ->(metadata:) { Oauth::DynamicRegistration.create!(client_metadata: metadata) }
+  config.oauth.dynamic_registration_attributes = {
+    scopes: %w[mcp mcp:read],                       # whatever scope was requested
+    metadata: { "audience" => "mcp", "dcr" => true }, # what AudienceResolver reads at /authorize
+    access_token_lifetime: 3600
+  }
+end
+```
+
+`dynamic_registration_attributes` may also be a callable taking `metadata:` and/or
+`request:`. Pinnable keys: `scopes`, `metadata`, `access_token_lifetime`,
+`authorization_code_lifetime`, `require_consent`, `description`. With no `scopes`
+pinned, a pinned `metadata["audience"]` that has an `audience_scopes` vocabulary
+gives the client that vocabulary. Every registered client is PKCE/S256 and
+consent-gated unless you pin `require_consent: false`; do that knowingly, because a
+consent-free client never records a `ClientGrant`, so the stale-client purge below
+cannot tell an abandoned registration from one in daily use and reaps such clients
+only once they deregister themselves. The per-IP registration limit is then the only
+defence against bot-created rows.
+
+Once migration `20261020120000` has run, the registration response also carries
+`registration_client_uri` and a one-time `registration_access_token` (stored as a
+digest), and the RFC 7592 client-configuration endpoint is live:
+`GET`/`PUT`/`DELETE /oauth/register/:client_id`, authenticated by that token as a
+bearer credential. `PUT` changes the client-shaped members under the registration
+rules (never the pinned attributes or the client type); `DELETE` deactivates the
+client and revokes its refresh tokens. An unknown client, a wrong token and a
+deregistered client are the same `401`. `StandardId::PurgeStaleDynamicClientsJob`
+(in `CleanupAllJob`, `standard_id:cleanup:dynamic_clients`, scheduled daily by the
+install generator) deletes deregistered clients and clients nobody ever authorized
+after a 7-day grace window.
+
 ### Social Login Setup
 
+Need the account ready before the token is minted — a profile the requested
+audience is bound to, a region check, a first-touch record? Set
+`config.social.before_mint`; it runs on the API callback after the account is
+found or created and before `SocialFlow` mints, and a raise refuses the
+sign-in through the callback's normal cleanup (nothing minted, staged link
+dropped, a just-created account removed):
+
+```ruby
+config.social.before_mint = ->(account:, audience:, params:) {
+  DeviceUserProfiles::Ensure.call(account:, region: params["region"]) if audience == "companion_kit"
+}
+```
+
+The hook receives any subset of `account:`, `provider:`, `social_info:`,
+`provider_tokens:`, `audience:`, `scopes:`, `params:` (the forwarded request
+params; the reserved OAuth ones such as `audience` and `scope` are stripped,
+which is why those two arrive as their own keywords) and `request:`. It runs
+before the login-method policy and the audience → profile binding, so if either
+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.
+
+
 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
 `standard_id-apple` to your Gemfile first. Writing a field whose gem is absent
@@ -1219,6 +1365,32 @@ redirect_to "/api/authorize?" + {
 }.to_query
 ```
 
+**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
+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
+`metadata: { "audience" => "mcp" }` gets `aud=mcp` with no audience-injecting shim
+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"] }`.
+
+```ruby
+StandardId.configure do |config|
+  config.oauth.resource_audiences = { "https://app.example.com/mcp" => "mcp" }   # RFC 8707
+  # or decide yourself:
+  config.oauth.audience_resolver = ->(client:, resource:) { client.metadata["audience"] || (resource && "mcp") }
+end
+```
+
 ### Social Login
 
 ```ruby

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

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module StandardId
+  # The bearer check a resource server (an MCP endpoint, a service API) needs,
+  # in one line:
+  #
+  #   class Mcp::BaseController < ActionController::API
+  #     include StandardId::ResourceServer
+  #     protected_resource "mcp", scopes: %w[mcp]
+  #   end
+  #
+  # It verifies the access token (ApiAuthentication), requires the token's
+  # `aud` to carry the resource's audience (AudienceVerification, including the
+  # audience → profile-type binding when configured), requires one of `scopes:`
+  # when given, and answers every refusal the way RFC 6750 and the MCP
+  # authorization spec expect:
+  #
+  #   * 401 `invalid_token` for a missing, expired, revoked or otherwise invalid
+  #     token, and for a deactivated or locked account, with a
+  #     `WWW-Authenticate` challenge that names the RFC 9728 metadata document
+  #     for this resource (`resource_metadata=`) so a client can discover the
+  #     authorization server and start the authorization-code + PKCE flow;
+  #   * 403 `insufficient_scope` for a token minted for another audience, or
+  #     without a required scope, with the same pointer and (for scope) the
+  #     `scope` parameter listing what the resource needed.
+  #
+  # The audience must be configured in `config.oauth.protected_resources`
+  # (see StandardId::Oauth::ProtectedResourceDocument) so the challenge can
+  # name a document that exists. Anything else — rate limiting, resolving the
+  # token's `gid` to a profile — stays the host's, as before.
+  module ResourceServer
+    extend ActiveSupport::Concern
+
+    included do
+      include StandardId::ApiAuthentication unless include?(StandardId::ApiAuthentication)
+
+      # Order matters: AudienceVerification's verify_audience! returns early
+      # unless current_session is set, so the token must be verified first.
+      before_action :verify_access_token!
+
+      include StandardId::AudienceVerification
+
+      before_action :verify_protected_resource_scopes!
+
+      class_attribute :_protected_resource_audience, instance_writer: false, default: nil
+      class_attribute :_protected_resource_scopes, instance_writer: false, default: []
+
+      rescue_from StandardId::NotAuthenticatedError,
+        StandardId::InvalidSessionError,
+        StandardId::InvalidTokenError,
+        StandardId::AccountDeactivatedError,
+        StandardId::AccountLockedError,
+        with: :render_protected_resource_unauthorized
+
+      # Registered after AudienceVerification's own handler so this one wins:
+      # same 403 insufficient_scope, same generic description, plus the
+      # resource_metadata pointer.
+      rescue_from StandardId::InvalidAudienceError,
+        StandardId::InvalidAudienceProfileError,
+        with: :render_protected_resource_wrong_audience
+
+      rescue_from StandardId::InvalidScopeError, with: :render_protected_resource_insufficient_scope
+    end
+
+    class_methods do
+      # @param audience [String] the audience configured in
+      #   `config.oauth.protected_resources` that tokens for this resource carry
+      # @param scopes [Array<String>, String, nil] when given, the token must
+      #   carry at least one of these
+      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
+      end
+    end
+
+    private
+
+    def protected_resource_audience
+      _protected_resource_audience.presence ||
+        raise(StandardId::ConfigurationError, "#{self.class.name} includes StandardId::ResourceServer but never called protected_resource")
+    end
+
+    def verify_protected_resource_scopes!
+      return if _protected_resource_scopes.empty?
+
+      require_scopes!(*_protected_resource_scopes)
+    end
+
+    def protected_resource_metadata_url
+      StandardId::Oauth::ProtectedResourceDocument.metadata_url(audience: protected_resource_audience, origin: request.base_url)
+    end
+
+    # The description never carries operator- or user-authored text: it goes
+    # into a quoted header and to an unauthenticated caller.
+    #
+    # RFC 6750 §3.1: when the request carried no credential at all, the
+    # challenge names the realm and the metadata document but no error code —
+    # that is the form an MCP client sees first, before it has any token.
+    def render_protected_resource_unauthorized(error = nil)
+      if request.authorization.blank?
+        set_protected_resource_challenge!(error: nil)
+        render json: { error: "invalid_token", error_description: "An access token is required" }, status: :unauthorized
+        return
+      end
+
+      description = case error
+      when StandardId::AccountDeactivatedError then "The account is deactivated"
+      when StandardId::AccountLockedError then "The account is locked"
+      else "The access token is invalid or has expired"
+      end
+      set_protected_resource_challenge!(error: "invalid_token", error_description: description)
+      render json: { error: "invalid_token", error_description: description }, status: :unauthorized
+    end
+
+    def render_protected_resource_wrong_audience(_error)
+      description = StandardId::AudienceVerification::GENERIC_INSUFFICIENT_SCOPE_MESSAGE
+      set_protected_resource_challenge!(error: "insufficient_scope", error_description: description)
+      render json: { error: "insufficient_scope", error_description: description }, status: :forbidden
+    end
+
+    def render_protected_resource_insufficient_scope(error)
+      description = error.message.presence || "The access token is missing a required scope"
+      set_protected_resource_challenge!(error: "insufficient_scope", error_description: description, scope: _protected_resource_scopes)
+      render json: { error: "insufficient_scope", error_description: description }, status: :forbidden
+    end
+
+    def set_protected_resource_challenge!(error:, error_description: nil, scope: nil)
+      response.set_header(
+        "WWW-Authenticate",
+        StandardId::Oauth::ProtectedResourceDocument.challenge(
+          audience: protected_resource_audience, origin: request.base_url,
+          error: error, error_description: error_description, scope: scope
+        )
+      )
+    end
+  end
+end

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

@@ -106,6 +106,7 @@ module StandardId
           redirect_uri: params[:redirect_uri],
           scope: params[:scope],
           audience: params[:audience],
+          resource: params[:resource],
           state: params[:state],
           code_challenge: params[:code_challenge],
           code_challenge_method: params[:code_challenge_method],

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

@@ -34,6 +34,7 @@ module StandardId
           token_response = nil
           flow = nil
           begin
+            run_before_social_mint(account:, social_info:, provider_tokens:)
             flow = StandardId::Oauth::SocialFlow.new(
               params,
               request,
@@ -71,6 +72,28 @@ module StandardId
           true
         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.
+        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 = {
+            account: account,
+            provider: provider.provider_name,
+            social_info: social_info,
+            provider_tokens: provider_tokens,
+            audience: params[:audience].presence,
+            scopes: params[:scope].presence,
+            params: forwarded_request_params,
+            request: request
+          }
+          hook.call(**StandardId::Utils::CallableParameterFilter.filter(hook, context))
+        end
+
         # The response was never sent, but the grant may already have
         # persisted a refresh token and a session — also when the grant itself
         # raised after writing them (e.g. an OAUTH_TOKEN_ISSUED subscriber), so

data/app/controllers/standard_id/api/oauth/registrations_controller.rb

@@ -1,34 +1,68 @@
 module StandardId
   module Api
     module Oauth
-      # RFC 7591 Dynamic Client Registration endpoint (POST /oauth/register).
+      # RFC 7591 Dynamic Client Registration (POST /oauth/register) and RFC
+      # 7592 client-configuration management (GET/PUT/DELETE
+      # /oauth/register/:client_id).
       #
-      # The endpoint is fully absent (404) unless
-      # `StandardId.config.oauth.dynamic_registration_enabled` is true — an open,
-      # unauthenticated registration endpoint is state-mutating attack surface,
-      # so it is opt-in. When enabled, the controller stays thin: it parses the
-      # JSON client metadata and delegates the RFC 7591 -> ClientApplication
-      # mapping (and the engine's security defaults) to
-      # StandardId::Oauth::ClientRegistration.
+      # Everything is absent (404) unless
+      # `StandardId.config.oauth.dynamic_registration_enabled` is true — an
+      # open, unauthenticated registration endpoint is state-mutating attack
+      # surface, so it is opt-in. The controller stays thin: it parses the JSON
+      # client metadata and delegates the RFC 7591 -> ClientApplication mapping
+      # (and the engine's security defaults and the host's pinned attributes)
+      # to StandardId::Oauth::ClientRegistration.
+      #
+      # The management actions are authenticated by the per-client registration
+      # access token issued at registration (returned once, stored as a digest),
+      # presented as a bearer credential; a client manages only itself. They
+      # exist once migration 20261020120000 has run.
       class RegistrationsController < BaseController
         public_controller
 
         # Throttle the open, unauthenticated registration endpoint by IP so an
-        # enabled deployment can't be flooded with ClientApplication rows.
+        # enabled deployment can't be flooded with ClientApplication rows, and
+        # the management endpoint separately so token guessing is slow without
+        # management traffic competing with registrations for one budget.
         rate_limit to: StandardId.config.rate_limits.dynamic_registration_per_ip,
                    within: 1.hour,
                    name: "dynamic-registration-ip",
                    only: :create,
                    store: StandardId::RateLimitHandling::RATE_LIMIT_STORE
+        rate_limit to: StandardId.config.rate_limits.dynamic_registration_management_per_ip,
+                   within: 1.hour,
+                   name: "dynamic-registration-management-ip",
+                   only: %i[show update destroy],
+                   store: StandardId::RateLimitHandling::RATE_LIMIT_STORE
 
+        # GET and DELETE carry no body, so no Content-Type to validate.
+        skip_before_action :validate_content_type!, only: %i[show destroy]
         before_action :require_dynamic_registration_enabled!
+        before_action :authenticate_registration_access!, only: %i[show update destroy]
 
         # POST /oauth/register
         def create
-          result = StandardId::Oauth::ClientRegistration.call(client_metadata)
+          result = StandardId::Oauth::ClientRegistration.call(client_metadata, request: request)
           render json: registration_response(result), status: :created
         end
 
+        # GET /oauth/register/:client_id — RFC 7592 §2.1
+        def show
+          render json: client_information_response(@client)
+        end
+
+        # PUT /oauth/register/:client_id — RFC 7592 §2.2
+        def update
+          result = StandardId::Oauth::ClientRegistration.update(@client, client_metadata, request: request)
+          render json: client_information_response(result.client)
+        end
+
+        # DELETE /oauth/register/:client_id — RFC 7592 §2.3
+        def destroy
+          StandardId::Oauth::ClientRegistration.deregister(@client)
+          head :no_content
+        end
+
         private
 
         # Return 404 (not 403) when the feature is off so the endpoint is
@@ -37,11 +71,34 @@ module StandardId
           head(:not_found) unless StandardId.config.oauth.dynamic_registration_enabled
         end
 
+        # RFC 7592 §2: an unknown client, a client that was not dynamically
+        # registered, a deregistered one, and a wrong or missing token are all
+        # the same 401, so the endpoint does not reveal which client_ids exist.
+        def authenticate_registration_access!
+          return head(:not_found) unless StandardId::ClientApplication.registration_management_column?
+
+          token = StandardId::BearerTokenExtraction.extract(request.headers["Authorization"])
+          client = StandardId::ClientApplication.live.dynamically_registered.find_by(client_id: params[:client_id])
+
+          if client&.authenticate_registration_access_token(token)
+            @client = client
+            return
+          end
+
+          challenge = token.present? ? %(Bearer error="invalid_token") : "Bearer"
+          response.set_header("WWW-Authenticate", challenge)
+          render json: {
+            error: "invalid_token",
+            error_description: "The registration access token does not authorize this client"
+          }, status: :unauthorized
+        end
+
         # Permit the full RFC 7591 client metadata document. We hand the raw
         # values to the service, which whitelists/maps them; the controller does
         # not need typed param coercion here.
         def client_metadata
           params.permit(
+            :client_id,
             :client_name,
             :scope,
             :token_endpoint_auth_method,
@@ -55,15 +112,36 @@ module StandardId
             %i[redirect_uris grant_types response_types].each do |key|
               permitted[key] = params[key] if permitted[key].blank? && params[key].present?
             end
+            # The route's :client_id shadows a body client_id in `params`; RFC
+            # 7592 §2.2 wants the DOCUMENT's id checked against the path.
+            permitted[:client_id] = request.request_parameters["client_id"]
           end
         end
 
         # RFC 7591 §3.2.1 success response. Echoes the registered metadata and,
         # for confidential clients, the one-time client_secret with
-        # client_secret_expires_at: 0 (never expires).
+        # client_secret_expires_at: 0 (never expires); plus, when management is
+        # available, the RFC 7592 registration_client_uri and the one-time
+        # registration_access_token.
         def registration_response(result)
-          client = result.client
+          body = client_information_response(result.client)
+          # Echo the registered value (RFC 7591 §3.2.1), not a value derived
+          # from client_type — both client_secret_basic and client_secret_post
+          # are accepted and both work at the token endpoint.
+          body[:token_endpoint_auth_method] = result.token_endpoint_auth_method
 
+          if result.client_secret
+            body[:client_secret] = result.client_secret
+            body[:client_secret_expires_at] = 0
+          end
+          body[:registration_access_token] = result.registration_access_token if result.registration_access_token
+          body
+        end
+
+        # The stable client information document shared by create/show/update
+        # (RFC 7591 §3.2.1, RFC 7592 §3). Never carries a secret or the
+        # registration access token; those are returned once, at registration.
+        def client_information_response(client)
           body = {
             client_id: client.client_id,
             client_id_issued_at: client.created_at.to_i,
@@ -72,19 +150,18 @@ module StandardId
             grant_types: client.grant_types_array,
             response_types: client.response_types_array,
             scope: client.scopes,
-            # Echo the registered value (RFC 7591 §3.2.1), not a value derived
-            # from client_type — both client_secret_basic and client_secret_post
-            # are accepted and both work at the token endpoint.
-            token_endpoint_auth_method: result.token_endpoint_auth_method
+            token_endpoint_auth_method: client.token_endpoint_auth_method
           }
-
-          if result.client_secret
-            body[:client_secret] = result.client_secret
-            body[:client_secret_expires_at] = 0
-          end
-
+          body[:registration_client_uri] = registration_client_uri(client) if client.dynamically_registered?
           body
         end
+
+        # Built from the request the way DiscoveryResolver builds endpoint URLs
+        # for a document served inside the mount: script_name IS the mount path.
+        def registration_client_uri(client)
+          mount = StandardId::Oauth::DiscoveryResolver.normalize_path(request.script_name)
+          "#{request.base_url}#{mount}/oauth/register/#{client.client_id}"
+        end
       end
     end
   end

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

@@ -0,0 +1,46 @@
+module StandardId
+  module Api
+    module WellKnown
+      # RFC 9728 OAuth 2.0 Protected Resource Metadata.
+      #
+      # `GET /.well-known/oauth-protected-resource/<resource path>` serves the
+      # document for the resource configured at that path in
+      # `config.oauth.protected_resources`; the bare form serves the default
+      # (the only configured resource, or the one marked `root: true`). 404
+      # when nothing matches, so a host with no protected resources exposes no
+      # document. Public and cacheable, like the other discovery documents.
+      #
+      # Drawn at the origin root by `standard_id_protected_resource_routes`
+      # (the challenge in StandardId::ResourceServer names that URL) and also
+      # under the engine's own mount.
+      class OauthProtectedResourceController < ActionController::API
+        include StandardId::ControllerPolicy
+        public_controller
+
+        def show
+          audience = resolve_audience
+
+          unless audience
+            render json: { error: "not_found", error_description: "No protected resource is configured at this path" },
+              status: :not_found
+            return
+          end
+
+          response.headers["Cache-Control"] = "public, max-age=3600"
+          render json: StandardId::Oauth::ProtectedResourceDocument.build(
+            audience: audience, origin: request.base_url, request: request
+          )
+        end
+
+        private
+
+        def resolve_audience
+          path = params[:resource_path].presence
+          return StandardId::Oauth::ProtectedResourceDocument.default_audience if path.nil?
+
+          StandardId::Oauth::ProtectedResourceDocument.audience_for_path("/#{path}")
+        end
+      end
+    end
+  end
+end