rodauth-token_exchange 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bb462644996fe8687d587e1a0ce2de697ceb99185185b6843cbb34ab7d364afb
+  data.tar.gz: b19c7385614bc78939aa7df47f78c1ac0f797771251f6f05affb43f9c4b2c431
+SHA512:
+  metadata.gz: 27b60c8694c613ed639aaf74bdd12281a0c223cde3bf2d1b6df7c6f624bbbbcb7612a2d8c1546ba6bd186f710ea2a7af146595ea600a172955b6e074f72255c8
+  data.tar.gz: 4f4d90d445658576de85a9b2166c1809e573aee6404cd5829927006aedb1bfd32d281f2156bb34815ce674c15d937277bad47dbe6d7ff9ddb4838a05386e9446

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.0 (2026-10-05)
+
+Initial release.
+
+- Add the RFC 8693 token-exchange grant to the rodauth-oauth token endpoint, accepting and issuing access tokens.
+- Issue independent access tokens; source grants are neither replaced nor revoked.
+- Bound scopes to the intersection of the subject token, actor token and client, and lifetime to an absolute deadline no later than either input's expiration, shared by the database and JWT `exp`.
+- Support delegation: actor tokens, nested `act` history up to 16 entries, `act.iss` for actors with an issuer, and actors named by the subject's `may_act` claim.
+- Support repeated `resource` and `audience` targets, inherited from inputs and never broadened.
+- Render `sub` and local `act.sub` per the receiving client's OIDC subject type (public/pairwise).
+- Provide policy hooks for exchange authorization and targets, and a resolver hook for trusted custom input tokens.
+- Reject inputs whose local subject or actor account is no longer available.
+- Require HTTPS and bound form size, parameter count and encoding for token-exchange requests.
+- Preserve subject, actor and target claims in introspection and JWT output.
+- Enforce resource origins and path boundaries for opaque and JWT access tokens when composed with `oauth_resource_indicators`, without changing the upstream gem or other auth classes.
+- Store exchange context as JSON in a configurable grants column; include an example Sequel migration and nginx reference configuration.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hiroshi Kajisha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,193 @@
+# rodauth-token_exchange
+
+An extension gem for [rodauth-oauth](https://github.com/HoneyryderChuck/rodauth-oauth) that adds the [RFC 8693 OAuth 2.0 Token Exchange](https://www.rfc-editor.org/rfc/rfc8693.html) grant to the token endpoint.
+
+Requires Ruby 3.0 or newer and rodauth-oauth `~> 1.7.0`.
+
+## Installation
+
+Add to your Gemfile and run `bundle install`:
+
+```ruby
+gem "rodauth-token_exchange", "~> 0.1.0"
+```
+
+In your existing Rodauth OAuth server, load the extension and enable it **after** other OAuth features, including `oauth_jwt`, `oauth_token_introspection`, and `oauth_resource_indicators` when used:
+
+```ruby
+require "rodauth/token_exchange"
+
+# Inside your existing Rodauth configuration:
+enable :oauth_token_introspection
+enable :oauth_token_exchange
+```
+
+Keep the existing OAuth database, application registration, client authentication, and signing-key configuration. If an application's `grant_types` is restricted, allow `urn:ietf:params:oauth:grant-type:token-exchange` for that application. The server advertises this grant in its supported grant types.
+
+Enable `oauth_pkce` and `oauth_device_code_grant` before `oauth_token_exchange`
+when composing these features; unsafe ordering raises `Rodauth::ConfigurationError`.
+Features using `oauth_assertion_base`, including `oauth_jwt_bearer_grant`, cannot
+currently be combined with this extension and are rejected at configuration time
+regardless of ordering. Upstream assertion dispatch treats the token-exchange URN
+as an assertion grant. This limitation does not affect JWT access-token output
+through `oauth_jwt`, which is supported and tested.
+
+Add a nullable text column named `token_exchange_context` to the grants table; it stores JSON containing subject, actor, and target context. A Sequel migration is provided in [examples/migrate/001_token_exchange_context.rb](examples/migrate/001_token_exchange_context.rb). The column name is configurable with `oauth_grants_token_exchange_context_column`.
+
+The grants table must allow **multiple grants for the same account and client**. Remove any unique index enforcing one grant per account/client (including variants containing scopes), using your application's actual index name. Keep token and refresh-token uniqueness constraints. Exchanges always insert a new grant and bypass access-token reuse; other grant types retain their existing behavior. The example migration does not guess or remove application-specific indexes.
+
+### Compatibility notes
+
+Enabling the extension changes behavior beyond token-exchange requests in these ways:
+
+- Client authentication changes apply to every endpoint that authenticates a client, including other grants, introspection, and revocation. Basic credentials are form-decoded (see [Exchange an access token](#exchange-an-access-token)), so existing clients whose ID or secret contains `+` or `%` must percent-encode them. Requests combining more than one client-authentication method are rejected.
+- Applications whose `grant_types` column is `NULL` accept every supported grant, as in rodauth-oauth, and can therefore use token exchange immediately. The default policy still limits them to their own tokens, with no actors or targets. Set `grant_types` explicitly to opt applications out.
+- Expiration deadlines are computed in Ruby and stored in the grants table, and expiration checks run in the database. As rodauth-oauth already assumes for introspection and JWT `exp`, Sequel's timezone settings must match the database session timezone.
+- With `oauth_resource_indicators`, this extension replaces rodauth-oauth 1.7's URL prefix checks for the auth class that enables it. This applies to all resource-protected access tokens in that class, including tokens from other grants. Authentication, scope, signature, expiry, and sender-binding checks still run. Other auth classes and the installed upstream gem are unchanged.
+
+## Exchange an access token
+
+Send form-encoded parameters to the existing token endpoint:
+
+Use HTTPS for the token endpoint and every endpoint receiving tokens. The extension
+rejects token-exchange requests, before client authentication, unless the server's
+`rack.url_scheme` is `https`. Other grants and endpoints keep rodauth-oauth's
+transport behavior. A TLS-terminating proxy must use trusted middleware to set that value;
+untrusted `Forwarded` or `X-Forwarded-Proto` headers alone are not accepted. Do not
+expose the backend directly or send credentials over HTTP before a redirect.
+
+```sh
+curl --user "$CLIENT_ID:$CLIENT_SECRET" \
+  --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
+  --data-urlencode "subject_token=$ACCESS_TOKEN" \
+  --data-urlencode 'subject_token_type=urn:ietf:params:oauth:token-type:access_token' \
+  --data-urlencode 'scope=read' \
+  https://auth.example.com/token
+```
+
+The response contains `access_token`, `issued_token_type`, `token_type`, `expires_in`, and `scope`. The issued token type is `urn:ietf:params:oauth:token-type:access_token`, including when `oauth_jwt` produces a JWT-formatted access token. No refresh token is issued. The source token is neither replaced nor revoked by exchange.
+
+`requested_token_type` is optional and accepts only the access-token type above. `actor_token` and `actor_token_type` must be supplied together. Repeated bare `resource` and `audience` parameters are supported. OAuth names are flat: unknown names such as `resource[]` are ignored and never become arrays or overwrite recognized parameters. Empty values are treated as omitted; missing required parameters and duplicate recognized single-value parameters are rejected. Resource values must be absolute URIs without fragments. Exchange and client-authentication parameters belong in the form body, not the query string.
+
+Basic authentication accepts case-insensitive scheme names and form-decodes the
+client ID and secret once, as required by RFC 6749. Percent-encode each component
+before constructing the Basic credential when it contains reserved characters.
+Combining Basic authentication with a body secret or client assertion is rejected.
+
+For token-exchange requests, form bodies and query strings are capped at 4 MiB
+and 4,096 parameters. The body is read with a byte bound before authentication.
+Limits enforced by Rack's configured flat parser also apply, including on
+versions without a pair parser. Stricter Rack limits are preserved. Excess input
+returns `invalid_request`. A body naming the token-exchange grant type in any
+parameter or encoding is parsed as an exchange; other grants keep
+rodauth-oauth's parsing and limits.
+
+Password-authenticated endpoints also require brute-force protection (RFC 6749
+§2.3.1). Configure and test an attempt limit at the deployment's trusted gateway
+or authentication service, shared across workers and covering every endpoint
+alias. The packaged [nginx reference configuration](examples/nginx-token-exchange.conf)
+provides a worker-shared IP limit and verified TLS to the backend. Adapt its
+placeholders, authority, certificates and network boundaries before deployment.
+Enabling the feature alone does not install a limiter or prove deployment compliance.
+
+## Defaults and policy
+
+By default, only a token issued to the authenticated client can be exchanged, resource/audience targets are rejected, and actors are rejected unless the subject identity carries a `may_act` claim (RFC 8693 §4.4) naming that actor. Every `may_act` claim must equal the actor's `sub` or `iss`; any other claim never matches. A `may_act` without `iss` names a principal of the subject's issuer, so the actor's issuer must equal the subject's (both absent for local tokens). An exchange without an actor preserves `may_act`, together with that issuer, for later exchanges, and an exchange that adds an actor consumes it. `may_act` is stored for the authorization server only and is not emitted in JWT or introspection output. Policies can reuse the check through `oauth_token_exchange_may_act?(subject, actor)`. The default resolver accepts active, unexpired local database access tokens, including exchange-issued JWT access tokens whose token hash is stored locally. It rejects sender-bound inputs rather than converting them into bearer tokens. It does not accept arbitrary external JWTs, SAML assertions, refresh tokens, or the `urn:ietf:params:oauth:token-type:jwt` type.
+
+For account-backed inputs, the default resolver also requires the account to be
+available through Rodauth's `oauth_account_ds`. Deleted accounts and accounts
+excluded by that dataset are rejected for both subject and actor tokens. The
+default dataset checks existence; applications can filter closed or disabled
+accounts through that existing hook. Client subjects with no account remain supported.
+
+Scopes are limited to the intersection of the subject token, authenticated application's allowed scopes, and actor token when present. Omitting `scope` selects that intersection; an empty intersection or explicitly requesting anything broader returns `invalid_scope`. Lifetime cannot exceed the configured access-token lifetime or the remaining lifetime of either input token.
+
+Exchange expiration is fixed as an absolute deadline before issuance. Database
+expiration and JWT `exp` share that deadline, so processing delays cannot extend
+the lifetime. Inputs that expire before storage cause `invalid_request`.
+
+Override these Rodauth configuration hooks to implement your application's trust policy:
+
+```ruby
+oauth_token_exchange_authorized? do |subject, actor|
+  # Example: retain same-client, actor-free authorization.
+  actor.nil? && subject[:application_id] ==
+    oauth_application[oauth_applications_id_column]
+end
+
+oauth_token_exchange_targets_allowed? do |resources, audiences, subject, actor|
+  # Example: permit only this API, with no named audience or delegation.
+  actor.nil? && audiences.empty? &&
+    resources == ["https://api.example.com"] &&
+    subject[:application_id] == oauth_application[oauth_applications_id_column]
+end
+```
+
+For delegation or cross-client exchange, the authorization hook must check which authenticated client may act for the subject and actor. Possession of two tokens alone is not sufficient authorization. Avoid unconditional `true` policies.
+
+Targets already attached to subject or actor tokens are inherited when omitted and cannot be broadened on subsequent exchanges, even by an approving target policy. Incompatible target restrictions fail with `invalid_target`. Native `oauth_resource_indicators` resource restrictions are preserved. Named audiences require an application-defined routing and authorization policy.
+
+When composing `oauth_resource_indicators`, protected-resource checks compare the
+request and target's scheme, host, and effective port. A target with no path or
+with `/` permits that origin; another path permits that exact path and descendants
+separated by `/`, not similarly prefixed sibling paths. A query in the target must
+match the request query exactly. Paths containing dot segments (including encoded
+dot segments) or encoded slash/backslash separators are rejected rather than
+depending on router normalization. Non-HTTP audiences need application-defined
+routing; they do not match an HTTP resource URL on their own. Keep the request's
+authority trustworthy through fixed Host configuration or equivalent ingress
+validation. Enable this extension after the other OAuth features on a separate
+resource server too; unsafe ordering is rejected there as well.
+
+Introspection and JWT output preserve `sub`, `act`, and target `aud` claims. Adding an actor creates a new `act.sub` and nests the subject's previous actor history under `act.act`. Exchanging without a new actor preserves existing actor context. Resource servers must enforce the intended audience and current actor authorization as well as token validity; verifying a JWT signature alone is insufficient. Historical nested actors describe prior delegation and do not independently grant current authority.
+
+An actor identity with an `issuer` produces `act.iss` alongside `act.sub`, distinguishing equal subjects from different issuers. An `act` entry without `iss` identifies a subject of this authorization server.
+
+With the `oidc` feature, the issued token's `sub` and local actors' `act.sub` follow the subject type (`public` or `pairwise`) of the client receiving the token, matching rodauth-oauth's JWT access tokens. Pairwise identifiers use that client's sector. The exchange context stores public identifiers and recomputes them for each client, so a pairwise identifier never flows into another client's token. Client subjects and actors with an `iss` are emitted unchanged.
+
+Actor history is limited to 16 nested actors. An exchange exceeding this bound
+returns `invalid_request` without issuing a grant or truncating the history.
+
+JWT exchange tokens include a private `token_exchange_id` claim used to produce a distinct `jti` for each grant. A separate rodauth-oauth resource server using upstream's `jti` verification should load and enable this extension too (after `oauth_jwt`, with `is_authorization_server? false`). Generic JWT consumers can treat `jti` as an opaque identifier. Introspection checks the stored exchange token's expiration and revocation; offline JWT consumers need their own revocation strategy. Revoking an input does not automatically revoke previously issued exchange tokens.
+
+Errors use the existing OAuth JSON response format: `invalid_request` for malformed or invalid credentials and denied exchange policies, `invalid_target` for unacceptable targets, `invalid_scope` for scope escalation, and `unauthorized_client` when the client's allowed grant list excludes exchange. Existing client-authentication errors come from rodauth-oauth.
+
+## Custom input token verification
+
+Override `oauth_token_exchange_resolve_token(token, token_type)` to accept additional trusted inputs. Return `nil` for invalid or unsupported tokens, or a hash containing:
+
+| Key | Meaning |
+| --- | --- |
+| `subject` | Nonempty verified subject string |
+| `account_id` | Mapped local account ID, or `nil` for a client subject |
+| `application_id` | Trusted local issuing application ID used by authorization policy |
+| `scopes` | Array of authorized scope strings |
+| `expires_at` | Expiration as an integer Unix timestamp |
+| `resources` | Optional array of permitted resource URI strings |
+| `audiences` | Optional array of permitted audience strings |
+| `act` | Optional verified actor claim hash |
+| `issuer` | Optional verified issuer string; emitted as `act.iss` when this identity is the actor |
+| `may_act` | Optional verified RFC 8693 `may_act` hash naming who may act for this subject |
+
+Call `super(token, token_type)` for input types handled by the built-in resolver. An external JWT or SAML resolver must verify signature, issuer, expiry, intended audience, and applicable client/key bindings before returning an identity. It must preserve target restrictions and verified actor context. Do not treat decoded claims as verified identity, silently drop sender constraints, or map an untrusted issuer's subject directly onto a local account.
+
+## Development
+
+Run these commands from a source checkout. The installed Gem includes runtime
+code, example configurations and migration, README, changelog, and license;
+development scripts and tests are distributed with the source checkout.
+Development uses Bundler 2.4.22 and requires a C toolchain and Ruby development
+headers to compile the SQLite test dependency for the Ruby version in use.
+
+```sh
+gem install bundler -v 2.4.22
+bundle _2.4.22_ install
+bundle exec rake
+bundle exec ruby -Ilib script/verify_tls.rb
+gem build rodauth-token_exchange.gemspec
+bundle exec ruby script/verify_package.rb rodauth-token_exchange-0.1.0.gem --test
+```
+
+Tests exercise the extension through a Roda token endpoint with an SQLite database. They cover validation, policy, scope/lifetime restriction, delegation, introspection, JWT output, target inheritance, and independent grant storage. Database adapters and framework integrations beyond this test setup are not certified by this project.
+
+Licensed under the [MIT License](LICENSE).

data/examples/migrate/001_token_exchange_context.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "sequel"
+require "sequel/extensions/migration"
+
+# Apply after the application's rodauth-oauth grants migration.
+# Adjust the table/column name to match your Rodauth configuration.
+# Separately remove any application-specific unique index that limits grants
+# to one per account/client (possibly including scopes). Keep token uniqueness.
+Sequel.migration do
+  change do
+    alter_table(:oauth_grants) do
+      add_column :token_exchange_context, String, text: true
+    end
+  end
+end

data/examples/nginx-token-exchange.conf

@@ -0,0 +1,47 @@
+# Reference topology. Render @PLACEHOLDERS@ before use; verify production settings.
+# The backend must be reachable only through trusted ingress or enforce its own
+# equivalent rate limit. This loopback listener is for the executable local probe.
+worker_processes 2;
+pid @DIRECTORY@/nginx.pid;
+error_log @DIRECTORY@/error.log;
+events { worker_connections 128; }
+http {
+    access_log off;
+    client_body_temp_path @DIRECTORY@/body;
+    proxy_temp_path @DIRECTORY@/proxy;
+    fastcgi_temp_path @DIRECTORY@/fastcgi;
+    uwsgi_temp_path @DIRECTORY@/uwsgi;
+    scgi_temp_path @DIRECTORY@/scgi;
+    # Shared by workers. Do not replace the key with supplied headers/credentials.
+    limit_req_zone $binary_remote_addr zone=token_exchange:1m rate=5r/m;
+    server {
+        listen 127.0.0.1:@PORT@ ssl reuseport;
+        ssl_certificate @DIRECTORY@/server.pem;
+        ssl_certificate_key @DIRECTORY@/server.key;
+        ssl_protocols TLSv1.2 TLSv1.3;
+        limit_req zone=token_exchange burst=4 nodelay;
+        limit_req_status 429;
+        # One location covers every route and alias; no unrestricted token path.
+        location / {
+            proxy_pass https://127.0.0.1:@UPSTREAM_PORT@;
+            proxy_ssl_protocols TLSv1.2 TLSv1.3;
+            proxy_ssl_verify on;
+            proxy_ssl_trusted_certificate @DIRECTORY@/upstream-ca.pem;
+            proxy_ssl_verify_depth 2;
+            proxy_ssl_server_name on;
+            proxy_ssl_name @UPSTREAM_NAME@;
+            # Replace localhost with the deployment's fixed public authority.
+            proxy_set_header Host localhost;
+            proxy_set_header X-Forwarded-Proto https;
+            proxy_set_header X-Forwarded-For $remote_addr;
+            proxy_set_header Forwarded "";
+            proxy_set_header X-Forwarded-Host "";
+            proxy_set_header X-Forwarded-Port "";
+            proxy_set_header X-Forwarded-Scheme "";
+            proxy_set_header X-Forwarded-Ssl "";
+            proxy_set_header Front-End-Https "";
+            proxy_connect_timeout 3s;
+            proxy_read_timeout 3s;
+        }
+    }
+}

data/lib/rodauth/features/oauth_token_exchange.rb

@@ -0,0 +1,522 @@
+# frozen_string_literal: true
+
+require "rodauth/oauth"
+require "json"
+require "uri"
+require "rodauth/token_exchange/client_authentication"
+require "rodauth/token_exchange/resource_authorization"
+
+module Rodauth
+  module TokenExchange
+    GRANT_TYPE = "urn:ietf:params:oauth:grant-type:token-exchange"
+    ACCESS_TOKEN_TYPE = "urn:ietf:params:oauth:token-type:access_token"
+    SINGLE_PARAMETERS = %w[grant_type subject_token subject_token_type actor_token actor_token_type requested_token_type scope].freeze
+    TARGET_PARAMETERS = %w[resource audience].freeze
+    CLIENT_PARAMETERS = %w[client_id client_secret client_assertion client_assertion_type].freeze
+    MAX_FORM_BYTES = 4 * 1024 * 1024
+    MAX_FORM_PARAMETERS = 4096
+    MAX_ACTOR_DEPTH = 16
+
+    # Rodauth configuration methods live on the auth class, above feature
+    # modules. Extend the request instance with these constraints so configured
+    # lifetime/reuse values cannot bypass the exchange's security bounds.
+    module TokenSettings
+      def oauth_access_token_expires_in
+        [@oauth_token_exchange_expires_at - Time.now.to_i, 0].max
+      end
+
+      def oauth_reuse_access_token
+        false
+      end
+    end
+  end
+
+  Feature.define(:oauth_token_exchange, :OauthTokenExchange) do
+    depends :oauth_base
+    include TokenExchange::ClientAuthentication
+    include TokenExchange::ResourceAuthorization
+
+    auth_value_method :oauth_grants_token_exchange_context_column, :token_exchange_context
+    auth_methods :oauth_token_exchange_resolve_token, :oauth_token_exchange_authorized?,
+                 :oauth_token_exchange_targets_allowed?
+
+    def oauth_grant_types_supported
+      super | [TokenExchange::GRANT_TYPE]
+    end
+
+    def raw_param(key)
+      return @oauth_token_exchange_params[key] if @oauth_token_exchange_params
+
+      super
+    end
+
+    def resource_indicators
+      return @oauth_token_exchange_params["resource"] if @oauth_token_exchange_params
+
+      super
+    end
+
+    # A resolver returns a validated identity, never unverified decoded claims.
+    def oauth_token_exchange_resolve_token(token, token_type)
+      return unless token_type == TokenExchange::ACCESS_TOKEN_TYPE
+
+      grant = oauth_token_exchange_stored_grant(token)
+      return unless grant
+      binding_columns = [:certificate_thumbprint, :dpop_jkt]
+      binding_columns << oauth_grants_certificate_thumbprint_column if respond_to?(:oauth_grants_certificate_thumbprint_column)
+      binding_columns << oauth_grants_dpop_jkt_column if respond_to?(:oauth_grants_dpop_jkt_column)
+      return if binding_columns.any? { |binding| grant[binding] }
+
+      context = oauth_token_exchange_context(grant)
+      account = grant[oauth_grants_account_id_column]
+      return if account && oauth_account_ds(account).empty?
+
+      application = grant[oauth_grants_oauth_application_id_column]
+      subject = context["sub"] || account&.to_s ||
+                db[oauth_applications_table].where(oauth_applications_id_column => application)
+                                           .get(oauth_applications_client_id_column)
+      {
+        subject: subject, account_id: account, application_id: application,
+        scopes: grant[oauth_grants_scopes_column].to_s.split(oauth_scope_separator),
+        expires_at: grant[oauth_grants_expires_in_column].to_time.to_i,
+        act: context["act"], act_account_ids: context["act_account_ids"], may_act: context["may_act"],
+        resources: context.fetch("resource") {
+          resource_column = respond_to?(:oauth_grants_resource_column) ? oauth_grants_resource_column : :resource
+          grant[resource_column].to_s.split(" ")
+        },
+        audiences: context.fetch("audience", [])
+      }.compact
+    end
+
+    def oauth_token_exchange_authorized?(subject, actor)
+      return false unless subject[:application_id] == oauth_application[oauth_applications_id_column]
+
+      !actor || oauth_token_exchange_may_act?(subject, actor)
+    end
+
+    # RFC 8693 §4.4: every claim in the subject's may_act must identify the actor.
+    # Unsupported may_act claims never match, so they deny rather than widen.
+    def oauth_token_exchange_may_act?(subject, actor)
+      may_act = oauth_token_exchange_may_act(subject)
+      return false unless may_act
+
+      # A sub is unique only within its issuer, so the issuer always takes part.
+      claims = {"sub" => actor[:subject], "iss" => actor[:issuer]}
+      may_act.all? { |claim, value| claims.key?(claim) && claims[claim] == value }
+    end
+
+    # A may_act without iss names a principal of the subject's issuer.
+    def oauth_token_exchange_may_act(subject)
+      may_act = subject[:may_act]
+      return unless may_act.is_a?(Hash) && !may_act.empty?
+
+      may_act = may_act.transform_keys(&:to_s)
+      may_act["iss"] = subject[:issuer] unless may_act.key?("iss")
+      may_act
+    end
+
+    def oauth_token_exchange_targets_allowed?(resources, audiences, _subject, _actor)
+      resources.empty? && audiences.empty?
+    end
+
+    def generate_jti(payload)
+      exchange_id = payload[:token_exchange_id] || payload["token_exchange_id"]
+      exchange_id ? Digest::SHA256.hexdigest("#{super}:#{exchange_id}") : super
+    end
+
+    def oauth_token_subject
+      token = authorization_token
+      if token && token[oauth_grants_type_column] == TokenExchange::GRANT_TYPE
+        return oauth_token_exchange_context(token)["sub"]
+      end
+      super
+    end
+
+    def post_configure
+      super
+      if is_authorization_server? && features.include?(:oauth_assertion_base)
+        raise Rodauth::ConfigurationError, "oauth_token_exchange cannot be combined with oauth_assertion_base (including oauth_jwt_bearer_grant)"
+      end
+      composed = %i[oauth_jwt oauth_token_introspection oauth_resource_indicators oauth_tls_client_auth oauth_dpop
+                    oauth_pkce oauth_device_code_grant]
+      if composed.any? { |feature| features.include?(feature) && features.index(feature) > features.index(:oauth_token_exchange) }
+        raise Rodauth::ConfigurationError, "enable oauth_token_exchange after the other OAuth features"
+      end
+      return unless is_authorization_server?
+
+      grant_keys = [oauth_grants_oauth_application_id_column, oauth_grants_account_id_column,
+                    oauth_grants_scopes_column, oauth_grants_type_column]
+      incompatible_index = db.indexes(oauth_grants_table).values.any? do |index|
+        index[:unique] && !index[:columns].empty? && (index[:columns] - grant_keys).empty?
+      end
+      if __one_oauth_token_per_account || incompatible_index
+        raise Rodauth::ConfigurationError, "token exchange requires multiple grants per account/client; remove the unique grant index"
+      end
+      unless db.schema(oauth_grants_table).any? { |column, _| column == oauth_grants_token_exchange_context_column }
+        raise Rodauth::ConfigurationError, "add the token exchange context column before enabling oauth_token_exchange"
+      end
+    end
+
+    def json_token_introspect_payload(grant)
+      if features.include?(:oauth_jwt) && oauth_jwt_access_tokens && request.path == introspect_path
+        stored = oauth_token_exchange_stored_grant(param("token"))
+        exchange = stored && stored[oauth_grants_type_column] == TokenExchange::GRANT_TYPE
+        # The stored fingerprint authenticates the entire locally minted JWT,
+        # including targeted tokens which upstream's client-audience check rejects.
+        # Consult this record for revocation just as for an opaque access token.
+        if exchange || (grant && grant["token_exchange_id"])
+          grant = exchange ? stored : nil
+        end
+      end
+      payload = super
+      return payload unless grant && payload[:active]
+
+      if grant["sub"]
+        # Decoded JWT claims were already rendered for their issuing client.
+        %w[sub act aud].each { |key| payload[key.to_sym] = grant[key] if grant.key?(key) }
+        return payload
+      end
+
+      application = db[oauth_applications_table]
+                    .where(oauth_applications_id_column => grant[oauth_grants_oauth_application_id_column]).first
+      if grant[oauth_grants_type_column] == TokenExchange::GRANT_TYPE
+        payload[:client_id] = application && application[oauth_applications_client_id_column]
+      end
+      oauth_token_exchange_claims(grant, application).each { |key, value| payload[key.to_sym] = value }
+      payload
+    end
+
+    private
+
+    def require_oauth_application
+      if request.path == token_path && request.post? && request.media_type == "application/x-www-form-urlencoded" &&
+         oauth_token_exchange_candidate?
+        @oauth_token_exchange_params = oauth_token_exchange_parameters(true)
+      end
+      # Only server/trusted middleware may assert transport security. Raw
+      # Forwarded headers are client-controlled and must not bypass this check.
+      # Other grants and endpoints keep rodauth-oauth's transport behavior.
+      if @oauth_token_exchange_params && request.env["rack.url_scheme"] != "https"
+        throw_json_response_error(400, "invalid_request")
+      end
+      super
+    rescue Rack::QueryParser::InvalidParameterError, Rack::QueryParser::ParameterTypeError
+      redirect_response_error("invalid_request")
+    end
+
+    def www_authenticate_header(payload)
+      # Authentication can fail before form parsing; do not read params here.
+      if request.path == token_path && payload["error"] == "invalid_client" &&
+         TokenExchange::ClientAuthentication::BASIC_SCHEME.match?(request.env["HTTP_AUTHORIZATION"].to_s)
+        return 'Basic realm="token"'
+      end
+      super
+    end
+
+    def oauth_token_exchange_stored_grant(token)
+      column = oauth_grants_token_hash_column || oauth_grants_token_column
+      value = oauth_grants_token_hash_column ? generate_token_hash(token) : token
+      # Reapply validity and exact-token predicates after feature-specific lookup
+      # filters; an OR in another feature must never broaden this selection.
+      oauth_grant_by_token_ds(token).where(column => value, oauth_grants_revoked_at_column => nil)
+                                   .where(Sequel[oauth_grants_expires_in_column] > Sequel::CURRENT_TIMESTAMP).first
+    end
+
+    def validate_token_params
+      super
+      return unless param("grant_type") == TokenExchange::GRANT_TYPE
+
+      @oauth_token_exchange_params ||= oauth_token_exchange_parameters
+      params = @oauth_token_exchange_params
+      redirect_response_error("invalid_request") unless request.env["rack.url_scheme"] == "https"
+      %w[subject_token subject_token_type].each do |key|
+        redirect_response_error("invalid_request") unless params[key]
+      end
+      if params.key?("actor_token") != params.key?("actor_token_type")
+        redirect_response_error("invalid_request")
+      end
+      if params["requested_token_type"] && params["requested_token_type"] != TokenExchange::ACCESS_TOKEN_TYPE
+        redirect_response_error("invalid_request")
+      end
+    rescue Rack::QueryParser::InvalidParameterError, Rack::QueryParser::ParameterTypeError
+      # Rack parses params in super, before the exchange-specific wire parser.
+      redirect_response_error("invalid_request")
+    end
+
+    # Exchange-specific form limits must not change other grants. Scan the whole
+    # body, leniently decoding valid escapes, for any occurrence of the grant
+    # type; a match in any name or encoding gets the strict exchange parser.
+    def oauth_token_exchange_candidate?
+      input = request.body
+      input.rewind
+      overlap = TokenExchange::GRANT_TYPE.bytesize * 3
+      tail = String.new(encoding: Encoding::BINARY)
+      while (chunk = input.read(64 * 1024))
+        window = tail + chunk.b
+        decoded = window.gsub(/%(\h\h)/n) { Regexp.last_match(1).hex.chr }
+        return true if decoded.include?(TokenExchange::GRANT_TYPE)
+
+        tail = window.byteslice(-[overlap, window.bytesize].min, overlap)
+      end
+      false
+    ensure
+      input&.rewind
+    end
+
+    def oauth_token_exchange_parameters(only_if_exchange = false)
+      redirect_response_error("invalid_request") unless request.media_type == "application/x-www-form-urlencoded"
+      # Rack's nested parameter parser discards repeated bare keys. Parse the wire
+      # representation to retain RFC 8693 resource/audience multiplicity.
+      input = request.body
+      input.rewind
+      parser = Rack::Utils.default_query_parser
+      limit = TokenExchange::MAX_FORM_BYTES
+      limit = [limit, parser.bytesize_limit].min if parser.respond_to?(:bytesize_limit)
+      raw = input.read(limit + 1)
+      input.rewind
+      redirect_response_error("invalid_request") if raw.bytesize > limit
+      pairs = oauth_token_exchange_form_pairs(raw)
+      return if only_if_exchange && !pairs.include?(["grant_type", TokenExchange::GRANT_TYPE])
+
+      names = TokenExchange::SINGLE_PARAMETERS + TokenExchange::TARGET_PARAMETERS + TokenExchange::CLIENT_PARAMETERS
+      query_names = oauth_token_exchange_form_pairs(request.query_string).map(&:first)
+      redirect_response_error("invalid_request") unless (query_names & names).empty?
+      params = {}
+      seen = {}
+      pairs.each do |name, value|
+        value ||= String.new
+        name.force_encoding(Encoding::UTF_8)
+        value.force_encoding(Encoding::UTF_8)
+        redirect_response_error("invalid_request") unless name.valid_encoding? && value.valid_encoding?
+        # OAuth parameter names are flat: unknown names (including brackets)
+        # are ignored, never interpreted by Rack as arrays or nested objects.
+        next unless names.include?(name)
+
+        target = TokenExchange::TARGET_PARAMETERS.include?(name)
+        redirect_response_error("invalid_request") if !target && seen[name]
+        seen[name] = true
+        next if value.empty?
+
+        if target
+          (params[name] ||= []) << value
+        else
+          params[name] = value
+        end
+      end
+      redirect_response_error("invalid_request") unless params["grant_type"] == TokenExchange::GRANT_TYPE
+      params
+    rescue ArgumentError
+      redirect_response_error("invalid_request")
+    end
+
+    def oauth_token_exchange_form_pairs(raw)
+      if raw.bytesize > TokenExchange::MAX_FORM_BYTES || raw.count("&") >= TokenExchange::MAX_FORM_PARAMETERS ||
+         raw.match?(/%(?![0-9a-fA-F]{2})/)
+        redirect_response_error("invalid_request")
+      end
+      parser = Rack::Utils.default_query_parser
+      if parser.respond_to?(:parse_query_pairs)
+        # Preserve repeated flat keys while retaining Rack's configured limits.
+        parser.parse_query_pairs(raw)
+      else
+        # Older Rack versions have no pair parser. Validate their flat-parser
+        # limits before decoding again to retain repeated keys and raw bytes.
+        parser.parse_query(raw)
+        URI.decode_www_form(raw, Encoding::ASCII_8BIT)
+      end
+    rescue Rack::QueryParser::ParamsTooDeepError, ArgumentError
+      redirect_response_error("invalid_request")
+    end
+
+    def create_token(grant_type)
+      return super unless grant_type == TokenExchange::GRANT_TYPE
+
+      redirect_response_error("unauthorized_client") unless supported_grant_type?(grant_type)
+      params = @oauth_token_exchange_params
+      subject = oauth_token_exchange_identity(params["subject_token"], params["subject_token_type"])
+      actor = oauth_token_exchange_identity(params["actor_token"], params["actor_token_type"]) if params["actor_token"]
+      redirect_response_error("invalid_request") unless oauth_token_exchange_authorized?(subject, actor)
+
+      resources = oauth_token_exchange_targets(params, "resource", :resources, subject, actor)
+      audiences = oauth_token_exchange_targets(params, "audience", :audiences, subject, actor)
+      targets = (resources + audiences).uniq
+      [subject, actor].compact.each do |identity|
+        bound = identity.fetch(:resources, []) + identity.fetch(:audiences, [])
+        if !bound.empty? && !(targets - bound).empty?
+          redirect_response_error("invalid_target")
+        end
+      end
+      resources.each do |resource|
+        begin
+          uri = URI.parse(resource)
+          redirect_response_error("invalid_target") unless uri.absolute? && !uri.fragment
+        rescue URI::InvalidURIError
+          redirect_response_error("invalid_target")
+        end
+      end
+      unless oauth_token_exchange_targets_allowed?(resources, audiences, subject, actor)
+        redirect_response_error("invalid_target")
+      end
+      scope = oauth_token_exchange_scopes(params["scope"], subject, actor)
+      expirations = [Time.now.to_i + oauth_access_token_expires_in, subject[:expires_at]]
+      expirations << actor[:expires_at] if actor
+      @oauth_token_exchange_expires_at = expirations.min
+      redirect_response_error("invalid_request") unless @oauth_token_exchange_expires_at > Time.now.to_i
+      extend(TokenExchange::TokenSettings)
+
+      context = {"sub" => subject[:subject], "resource" => resources, "audience" => audiences}
+      context["aud"] = targets unless targets.empty?
+      context["act"] = subject[:act] if subject[:act]
+      # Local account IDs aligned with the actor chain (outermost first) allow
+      # pairwise clients to receive their own identifiers for local actors.
+      act_account_ids = subject.fetch(:act_account_ids, [])
+      if actor
+        context["act"] = {"sub" => actor[:subject], "iss" => actor[:issuer], "act" => context["act"]}.compact
+        act_account_ids = [actor[:account_id]] + act_account_ids
+      else
+        # A delegation permission is consumed by the exchange that adds an actor.
+        # Store the issuer with it so the namespace survives later exchanges.
+        may_act = oauth_token_exchange_may_act(subject)
+        context["may_act"] = may_act.compact if may_act
+      end
+      context["act_account_ids"] = act_account_ids if act_account_ids.any?
+      history = context["act"]
+      depth = 0
+      while history
+        depth += 1
+        unless history.is_a?(Hash) && depth <= TokenExchange::MAX_ACTOR_DEPTH
+          redirect_response_error("invalid_request")
+        end
+        history = history["act"]
+      end
+
+      grant_params = {
+        oauth_grants_type_column => TokenExchange::GRANT_TYPE,
+        oauth_grants_account_id_column => subject[:account_id],
+        oauth_grants_oauth_application_id_column => oauth_application[oauth_applications_id_column],
+        oauth_grants_scopes_column => scope.join(oauth_scope_separator),
+        oauth_grants_token_exchange_context_column => JSON.generate(context)
+      }
+      if features.include?(:oauth_resource_indicators) && !targets.empty?
+        grant_params[oauth_grants_resource_column] = targets.join(" ")
+      end
+      generate_token(grant_params, false)
+    end
+
+    def oauth_token_exchange_identity(token, type)
+      identity = oauth_token_exchange_resolve_token(token, type)
+      unless identity.is_a?(Hash) && identity[:subject].is_a?(String) && !identity[:subject].empty? &&
+             identity[:scopes].is_a?(Array) && identity[:scopes].all? { |scope| scope.is_a?(String) } &&
+             identity[:expires_at].is_a?(Integer) && identity[:expires_at] > Time.now.to_i &&
+             (identity[:issuer].nil? || (identity[:issuer].is_a?(String) && !identity[:issuer].empty?)) &&
+             (identity[:may_act].nil? || identity[:may_act].is_a?(Hash)) &&
+             (identity[:act_account_ids].nil? || identity[:act_account_ids].is_a?(Array))
+        redirect_response_error("invalid_request")
+      end
+      identity
+    end
+
+    def oauth_token_exchange_targets(params, parameter, key, subject, actor)
+      bound = [subject, actor].compact.map { |identity| identity.fetch(key, []) }.reject(&:empty?).reduce(:&)
+      targets = params[parameter] || bound || []
+      # An empty intersection must not erase an existing target restriction.
+      if bound && (targets.empty? || !(targets - bound).empty?)
+        redirect_response_error("invalid_target")
+      end
+      targets.uniq
+    end
+
+    def oauth_token_exchange_scopes(requested, subject, actor)
+      allowed = subject[:scopes] & oauth_application[oauth_applications_scopes_column].to_s.split(oauth_scope_separator)
+      allowed &= actor[:scopes] if actor
+      redirect_response_error("invalid_scope") if allowed.empty?
+      return allowed unless requested
+
+      # RFC 6749 scope-token: printable ASCII excluding double quote and backslash.
+      unless requested.match?(/\A[\x21\x23-\x5B\x5D-\x7E]+(?: [\x21\x23-\x5B\x5D-\x7E]+)*\z/)
+        redirect_response_error("invalid_scope")
+      end
+      selected = requested.split(" ").uniq
+      redirect_response_error("invalid_scope") unless (selected - allowed).empty?
+      selected
+    end
+
+    def store_token(grant_params, update_params = {})
+      if grant_params[oauth_grants_type_column] == TokenExchange::GRANT_TYPE
+        redirect_response_error("invalid_request") unless @oauth_token_exchange_expires_at > Time.now.to_i
+        update_params = update_params.merge(oauth_grants_expires_in_column => Time.at(@oauth_token_exchange_expires_at))
+      end
+      super(grant_params, update_params)
+    end
+
+    def generate_token(grant_params = {}, should_generate_refresh_token = true)
+      grant = super
+      if grant_params[oauth_grants_type_column] == TokenExchange::GRANT_TYPE &&
+         features.include?(:oauth_jwt) && oauth_jwt_access_tokens
+        # Upstream JWT issuance does not persist the access token. Retain its
+        # fingerprint so later exchanges can check revocation and exact identity.
+        token = grant[oauth_grants_token_column]
+        column = oauth_grants_token_hash_column || oauth_grants_token_column
+        value = oauth_grants_token_hash_column ? generate_token_hash(token) : token
+        db[oauth_grants_table].where(oauth_grants_id_column => grant[oauth_grants_id_column]).update(column => value)
+      end
+      grant
+    end
+
+    def json_access_token_payload(grant)
+      payload = super
+      if grant[oauth_grants_type_column] == TokenExchange::GRANT_TYPE
+        payload["issued_token_type"] = TokenExchange::ACCESS_TOKEN_TYPE
+        payload["scope"] = grant[oauth_grants_scopes_column]
+      end
+      payload
+    end
+
+    def jwt_claims(grant)
+      claims = super
+      context = oauth_token_exchange_context(grant)
+      oauth_token_exchange_claims(grant, oauth_application, context).each { |key, value| claims[key.to_sym] = value }
+      if grant[oauth_grants_type_column] == TokenExchange::GRANT_TYPE
+        claims[:exp] = grant[oauth_grants_expires_in_column].to_time.to_i
+        claims[:token_exchange_id] = grant[oauth_grants_id_column].to_s
+        claims[:resource] = context["aud"] if context["aud"]
+      end
+      claims
+    end
+
+    def oauth_token_exchange_context(grant)
+      value = grant[oauth_grants_token_exchange_context_column]
+      value ? JSON.parse(value) : {}
+    end
+
+    # Context stores subject identifiers as resolved (public for local
+    # accounts). Pairwise clients receive their own sector identifiers for the
+    # subject and local actors, matching upstream JWT access-token subjects.
+    def oauth_token_exchange_claims(grant, application, context = oauth_token_exchange_context(grant))
+      claims = context.slice("sub", "act", "aud")
+      return claims unless oauth_token_exchange_pairwise?(application)
+
+      account = grant[oauth_grants_account_id_column]
+      claims["sub"] = jwt_subject(account, application) if account && claims.key?("sub")
+      if claims["act"]
+        claims["act"] = oauth_token_exchange_pairwise_act(claims["act"], context.fetch("act_account_ids", []), application)
+      end
+      claims
+    end
+
+    def oauth_token_exchange_pairwise?(application)
+      return false unless application && features.include?(:oidc)
+
+      (application[oauth_applications_subject_type_column] || oauth_jwt_subject_type) == "pairwise"
+    end
+
+    def oauth_token_exchange_pairwise_act(act, account_ids, application)
+      return act unless act.is_a?(Hash)
+
+      account, *older = account_ids
+      act = act.merge("sub" => jwt_subject(account, application)) if account && !act.key?("iss")
+      act = act.merge("act" => oauth_token_exchange_pairwise_act(act["act"], older, application)) if act["act"]
+      act
+    end
+  end
+end

data/lib/rodauth/token_exchange/client_authentication.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "base64"
+require "uri"
+
+module Rodauth
+  module TokenExchange
+    module ClientAuthentication
+      BASIC_SCHEME = /\A *Basic(?:\s|\z)/i.freeze
+
+      private
+
+      def require_oauth_application
+        authorization = request.env["HTTP_AUTHORIZATION"]
+        basic = authorization && BASIC_SCHEME.match?(authorization)
+        methods = [basic, !param_or_nil("client_secret").to_s.empty?, !param_or_nil("client_assertion").to_s.empty?]
+        if methods.count { |present| present } > 1
+          redirect_response_error("invalid_request")
+        end
+        return super unless basic
+
+        token = authorization[/\A *Basic +([^\s]+)\z/i, 1]
+        authorization_required unless token
+
+        # Preserve the authentication checks supplied by other OAuth features.
+        begin
+          request.env["HTTP_AUTHORIZATION"] = "Basic #{token}"
+          super
+        ensure
+          request.env["HTTP_AUTHORIZATION"] = authorization
+        end
+      end
+
+      def supports_auth_method?(application, auth_method)
+        return super unless @oauth_token_exchange_params && auth_method == "none"
+        return false unless application
+
+        # PKCE/device grant exceptions must not make an exchange client public.
+        configured = application[oauth_applications_token_endpoint_auth_method_column]
+        methods = configured ? configured.split(/ +/) : oauth_default_token_endpoint_auth_methods
+        methods.include?("none")
+      end
+
+      def require_oauth_application_from_client_secret_basic(token)
+        begin
+          credentials = Base64.strict_decode64(token).split(":", 2)
+          authorization_required unless credentials.length == 2
+          client_id, client_secret = credentials.map { |value| URI.decode_www_form_component(value) }
+          authorization_required unless client_id.valid_encoding? && client_secret.valid_encoding?
+        rescue ArgumentError
+          authorization_required
+        end
+        application = db[oauth_applications_table].where(oauth_applications_client_id_column => client_id).first
+        authorization_required unless supports_auth_method?(application, "client_secret_basic") &&
+                                      secret_matches?(application, client_secret)
+        application
+      end
+    end
+  end
+end

data/lib/rodauth/token_exchange/resource_authorization.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Rodauth
+  module TokenExchange
+    # Compatibility with rodauth-oauth 1.7's resource indicators. Keep the
+    # authentication/scope/sender-binding chain, replacing only its URL checks
+    # for auth classes which explicitly enable this extension.
+    module ResourceAuthorization
+      def require_oauth_authorization(*scopes)
+        return super unless features.include?(:oauth_resource_indicators)
+
+        previous = @oauth_token_exchange_checking_authorization
+        begin
+          @oauth_token_exchange_checking_authorization = true
+          super
+        ensure
+          @oauth_token_exchange_checking_authorization = previous
+        end
+
+        token = authorization_token
+        resources = token[oauth_grants_resource_column] || token["resource"]
+        return unless resources
+
+        resources = resources.split(" ") if resources.is_a?(String)
+        authorization_required unless oauth_token_exchange_resource_matches?(resources)
+      end
+
+      private
+
+      def authorization_token
+        token = super
+        return token unless token && @oauth_token_exchange_checking_authorization
+
+        # Suppress the upstream base_url prefix check only while its full
+        # authorization chain runs. Do not alter its cached grant or JWT claims.
+        # The original resource restriction is checked immediately afterwards,
+        # before require_oauth_authorization returns to the protected route.
+        token.reject { |key, _| key == oauth_grants_resource_column || key == "resource" }
+      end
+
+      def jwt_decode(token, verify_aud: true, **options)
+        return super unless features.include?(:oauth_resource_indicators)
+
+        # The upstream resource wrapper honors verify_aud:false, avoiding both
+        # its starts_with? typo and its unsafe prefix matcher. Other verification
+        # options, including signature, issuer, expiry, headers and jti, survive.
+        claims = super(token, verify_aud: false, **options)
+        return claims unless verify_aud
+        return unless claims && oauth_token_exchange_resource_matches?(claims["aud"])
+
+        claims
+      end
+
+      def oauth_token_exchange_resource_matches?(resources)
+        return false unless resources.is_a?(Array) && !resources.empty?
+
+        requested = URI.parse(request.url)
+        return false unless oauth_token_exchange_http_resource?(requested)
+
+        resources.any? do |resource|
+          next false unless resource.is_a?(String)
+
+          begin
+            target = URI.parse(resource)
+            next false unless oauth_token_exchange_http_resource?(target)
+            next false unless [requested.scheme, requested.host.downcase, requested.port] ==
+                              [target.scheme, target.host.downcase, target.port]
+
+            path = target.path
+            request_path = requested.path
+            path_match = path.empty? || path == "/" || request_path == path ||
+                         request_path.start_with?(path.end_with?("/") ? path : "#{path}/")
+            path_match && (target.query.nil? || target.query == requested.query)
+          rescue URI::InvalidURIError
+            false
+          end
+        end
+      rescue URI::InvalidURIError
+        false
+      end
+
+      def oauth_token_exchange_http_resource?(uri)
+        return false unless %w[http https].include?(uri.scheme) && uri.host && !uri.userinfo && !uri.fragment
+
+        # Avoid path aliases which a downstream router might normalize outside
+        # the allowed subtree. Encoded separators are deliberately fail-closed.
+        return false if uri.path.match?(/%(?:2f|5c)/i)
+
+        uri.path.split("/").none? { |segment| %w[. ..].include?(URI::DEFAULT_PARSER.unescape(segment)) }
+      end
+    end
+  end
+end

data/lib/rodauth/token_exchange/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Rodauth
+  module TokenExchange
+    VERSION = "0.1.0"
+  end
+end

data/lib/rodauth/token_exchange.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require "rodauth/oauth"
+require "rodauth/token_exchange/version"
+require "rodauth/features/oauth_token_exchange"

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: rodauth-token_exchange
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Hiroshi Kajisha
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-10-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rodauth-oauth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.7.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.7.0
+description: Adds the RFC 8693 token-exchange grant to rodauth-oauth's token endpoint,
+  with delegation (act and may_act), bounded scopes and lifetimes, and policy hooks.
+email:
+- 1960696+kajisha@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- examples/migrate/001_token_exchange_context.rb
+- examples/nginx-token-exchange.conf
+- lib/rodauth/features/oauth_token_exchange.rb
+- lib/rodauth/token_exchange.rb
+- lib/rodauth/token_exchange/client_authentication.rb
+- lib/rodauth/token_exchange/resource_authorization.rb
+- lib/rodauth/token_exchange/version.rb
+homepage: https://github.com/kajisha/rodauth-token_exchange
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/kajisha/rodauth-token_exchange
+  bug_tracker_uri: https://github.com/kajisha/rodauth-token_exchange/issues
+  changelog_uri: https://github.com/kajisha/rodauth-token_exchange/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.5
+signing_key: 
+specification_version: 4
+summary: RFC 8693 Token Exchange for rodauth-oauth
+test_files: []