feat(oauth2): support RFC 8252 §7.1 authority-less custom-scheme URIs end-to-end

com.example.app:/oauth2redirect (the RFC's own example form, and the default
shape AppAuth-based apps register) passed every write-time validator but was
silently rejected by every runtime gate: URLUtils::canonicalUrl() opens with
FILTER_VALIDATE_URL, which rejects the authority-less shape, so
isUriAllowed()/isPostLogoutUriAllowed() could never match it - a registration
that validates cleanly and never authenticates.

- URLUtils::canonicalUrl(): canonicalize authority-less URIs as scheme +
  rooted lowercased path (query/fragment dropped, same as the authority
  form); opaque URIs (mailto:foo@bar - no authority AND no rooted path)
  keep returning null.
- Client::isPostLogoutUriAllowed(): drop its own FILTER_VALIDATE_URL and
  isset(host) guards - validity is canonicalUrl()'s job now, and the
  host-less crash those guards prevented cannot recur.
- DoctrineOAuth2ClientRepository: anchor the cross-client scheme-uniqueness
  LIKE on ':/' instead of '://' so a scheme claimed via either URI form
  collides with the other - the OS-level interception risk is about the
  scheme, not the shape it was registered in.
- IndirectResponseQueryStringStrategy/IndirectResponseUrlFragmentStrategy:
  Laravel's Redirect::to() relies on the same FILTER_VALIDATE_URL check
  (UrlGenerator::isValidUrl) and rewrote the already-validated redirect
  target as a RELATIVE path (Location: https://<idp>/com.example.app:/logout)
  - caught by live verification only, invisible to the unit layer. Absolute
  URIs Laravel does not recognize are now emitted as a verbatim Location
  header; Symfony still rejects CR/LF in header values.

All four regression tests written and confirmed failing first (TDD). The new
end-session feature test lives in tests/OAuth2EndSessionTest.php because
tests/OAuth2ProtocolTestCase.php's *TestCase.php suffix keeps that whole file
out of PHPUnit's *Test.php discovery - the Application suite never runs it.

Full Application suite: 173 tests / 562 assertions, 0 failures. Live-verified
against the local docker IDP: registered com.example.app:/logout ->
302 Location: com.example.app:/logout?state=xyz (verbatim); unregistered
path -> 400.

Author: smarcet

app/Models/OAuth2/Client.php

@@ -1170,13 +1170,13 @@ public function isPostLogoutUriAllowed($post_logout_uri)
         if(empty($this->post_logout_redirect_uris)) return false;
         if(empty($post_logout_uri)) return false;
 
-        if(!filter_var($post_logout_uri, FILTER_VALIDATE_URL)) return false;
-        if(is_null($this->post_logout_redirect_uris)) return false;
-        if(empty($this->post_logout_redirect_uris)) return false;
-
+        // no FILTER_VALIDATE_URL gate here: it rejects the RFC 8252 SS7.1 authority-less form
+        // (com.example.app:/logout) that native clients may register. Validity is enforced by the
+        // scheme checks below plus canonicalUrl() (which still applies FILTER_VALIDATE_URL to
+        // authority-bearing URIs and requires a rooted path for authority-less ones).
         $parts = @parse_url($post_logout_uri);
 
-        if ($parts == false) {
+        if ($parts == false || !isset($parts['scheme'])) {
             return false;
         }
         // native clients may register custom schemes (myapp://...); every other app type requires https
@@ -1190,10 +1190,9 @@ public function isPostLogoutUriAllowed($post_logout_uri)
         if($this->isNativeDangerousScheme($parts['scheme'], $parts['host'] ?? null))
             return false;
 
-        // host-less URIs (e.g. mailto:, file:///x, myapp:///cb) pass FILTER_VALIDATE_URL but have no
-        // authority to match against; without this guard the concatenation below raises an
-        // "Undefined array key host" warning (converted to ErrorException) on the public end-session endpoint.
-        if(!isset($parts['host'])) return false;
+        // NOTE: no isset($parts['host']) guard here - authority-less URIs go through canonicalUrl(),
+        // which either canonicalizes them (RFC 8252 SS7.1 rooted-path form) or returns null (opaque
+        // forms like mailto:foo@bar), so the host-less crash this gate used to have cannot recur.
 
         // exact match against each registered value, through the same canonicalize+normalize pipeline on
         // both sides (mirrors isUriAllowed()): a registered value's scheme+host[:port] must no longer match

app/Repositories/DoctrineOAuth2ClientRepository.php

@@ -179,13 +179,16 @@ public function hasCustomSchemeRegisteredOnAnotherClientThan(int $id, string $cu
         // fields are comma-separated URI lists; a plain '%scheme://%' substring match false-positives on any
         // longer scheme ending in this one (e.g. 'roipapp' matching inside 'androipapp://...'). Anchor the
         // match to a real list-item boundary: the scheme starts the field, or immediately follows a comma.
-        $starts_with = $scheme . '://%';
-        $after_comma = '%,' . $scheme . '://%';
+        // The boundary is ':/' rather than '://' so BOTH registered forms are seen - the authority form
+        // (scheme://host/...) and the RFC 8252 SS7.1 authority-less form (scheme:/path): the OS-level
+        // interception risk is about the scheme, regardless of which URI form either client registered.
+        $starts_with = $scheme . ':/%';
+        $after_comma = '%,' . $scheme . ':/%';
         // legacy rows: before the create()-validation hardening, POST create persisted lists verbatim,
         // so an item can still sit after ", " (comma + single space - the JSON/forms list artifact).
         // ClientFactory::populate now trims per item, so no NEW rows take this shape; N-space/other
         // whitespace leftovers are for the pre-deploy audit (... LIKE '%, %'), not this query.
-        $after_comma_space = '%, ' . $scheme . '://%';
+        $after_comma_space = '%, ' . $scheme . ':/%';
 
         $qb = $this->getEntityManager()->createQueryBuilder();
         $matches_field = function (string $field) use ($qb) {

app/Strategies/IndirectResponseQueryStringStrategy.php

@@ -12,8 +12,10 @@
  * limitations under the License.
  **/
 use Utils\IHttpResponseStrategy;
+use Illuminate\Http\RedirectResponse;
 use Illuminate\Support\Facades\Redirect;
 use Illuminate\Support\Facades\Response;
+use Illuminate\Support\Facades\URL;
 /**
  * Class IndirectResponseQueryStringStrategy
  * Redirect and http response using a 302 adding params on query string
@@ -36,7 +38,16 @@ public function handle($response)
         }
         $return_to = (strpos($return_to, "?") == false) ? $return_to . "?" . $query_string : $return_to . "&" . $query_string;
 
-        return Redirect::to($return_to)
+        // RFC 8252 SS7.1 authority-less URIs (com.example.app:/cb?code=...) fail Laravel's
+        // UrlGenerator::isValidUrl(), so Redirect::to() would treat the already-validated redirect
+        // target as a RELATIVE path and prefix the site URL, corrupting the redirect. For an absolute
+        // URI (leading scheme) Laravel does not recognize, emit the Location verbatim - Symfony still
+        // rejects CR/LF in the header value, so no header-injection surface is opened.
+        $redirect = (!URL::isValidUrl($return_to) && preg_match('~^[A-Za-z][A-Za-z0-9+.\-]*:~', $return_to) === 1)
+            ? new RedirectResponse($return_to)
+            : Redirect::to($return_to);
+
+        return $redirect
             ->header('Cache-Control', 'no-cache, no-store, max-age=0, must-revalidate')
             ->header('Pragma','no-cache');
     }

app/Strategies/IndirectResponseUrlFragmentStrategy.php

@@ -12,8 +12,10 @@
  * limitations under the License.
  **/
 use Utils\IHttpResponseStrategy;
+use Illuminate\Http\RedirectResponse;
 use Illuminate\Support\Facades\Redirect;
 use Illuminate\Support\Facades\Response;
+use Illuminate\Support\Facades\URL;
 /**
  * Class IndirectResponseUrlFragmentStrategy
  * Redirect and http response using a 302 adding params on url fragment
@@ -37,7 +39,14 @@ public function handle($response)
 
         $return_to = (strpos($return_to, "#") == false) ? $return_to . "#" . $fragment : $return_to . "&" . $fragment;
 
-        return Redirect::to($return_to)
+        // same RFC 8252 SS7.1 authority-less guard as IndirectResponseQueryStringStrategy: an absolute
+        // URI Laravel's UrlGenerator does not recognize must be emitted verbatim, or Redirect::to()
+        // prefixes the site URL and corrupts the already-validated redirect target.
+        $redirect = (!URL::isValidUrl($return_to) && preg_match('~^[A-Za-z][A-Za-z0-9+.\-]*:~', $return_to) === 1)
+            ? new RedirectResponse($return_to)
+            : Redirect::to($return_to);
+
+        return $redirect
             ->header('Cache-Control', 'no-cache, no-store, max-age=0, must-revalidate')
             ->header('Pragma','no-cache');
     }

app/libs/Utils/URLUtils.php

@@ -34,17 +34,24 @@ public static function normalizeUrl(string $url):?string{
      * @return string|null
      */
     public static function canonicalUrl(string $url, bool $usePort = true):?string{
-        if(!filter_var($url, FILTER_VALIDATE_URL)) return null;
         $parts = @parse_url($url);
-        if ($parts == false)
+        if ($parts == false || !isset($parts['scheme']))
         {
             return null;
         }
-        // host-less URIs (e.g. mailto:, file:///x) pass FILTER_VALIDATE_URL but have no authority to
-        // canonicalize; without this guard the concatenation below raises an "Undefined array key host" warning.
         if (!isset($parts['host'])) {
-            return null;
+            // RFC 8252 SS7.1: private-use scheme redirect URIs may omit the authority entirely -
+            // "com.example.app:/oauth2redirect/example-provider" is the RFC's own example form.
+            // FILTER_VALIDATE_URL rejects that shape, so it is canonicalized here from parse_url parts:
+            // scheme + rooted path (query/fragment dropped, path lowercased, same as the authority form).
+            // Opaque URIs (mailto:foo@bar - no authority AND no rooted path) keep returning null: there
+            // is no location to match a redirect against.
+            if (!isset($parts['path']) || !str_starts_with($parts['path'], '/') || isset($parts['user']) || isset($parts['port'])) {
+                return null;
+            }
+            return rtrim($parts['scheme'].':'.strtolower($parts['path']), '/');
         }
+        if(!filter_var($url, FILTER_VALIDATE_URL)) return null;
         $canonical_url = $parts['scheme'].'://'.strtolower($parts['host']);
         if(isset($parts['port']) && $usePort) {
             $canonical_url .= ':'.strtolower($parts['port']);

docs/adr/0001-native-client-custom-uri-schemes.md

@@ -30,10 +30,10 @@ Four consecutive adversarial code-review passes (xhigh-effort, multi-agent) surf
 
 ## Decision
 
-1. **Allow custom app URI schemes in all three URI-bearing Native-client fields** (`redirect_uris`, `allowed_origins`, `post_logout_redirect_uris`), gated by a **deny-list**, not an allow-list — any scheme is treated as a legitimate custom app scheme unless it appears on `IClient::DISALLOWED_NATIVE_URI_SCHEMES`.
+1. **Allow custom app URI schemes in all three URI-bearing Native-client fields** (`redirect_uris`, `allowed_origins`, `post_logout_redirect_uris`), gated by a **deny-list**, not an allow-list — any scheme is treated as a legitimate custom app scheme unless it appears on `IClient::DISALLOWED_NATIVE_URI_SCHEMES`. Both custom-scheme URI shapes are supported end-to-end: the authority form (`myapp://callback`) and the **RFC 8252 §7.1 authority-less form** (`com.example.app:/oauth2redirect` — the RFC's own example, and the default shape AppAuth-based apps register). `URLUtils::canonicalUrl()` canonicalizes the authority-less form as scheme + rooted, lowercased path (query/fragment dropped, same as the authority form); the two forms are distinct URIs and never cross-match. Opaque URIs (`mailto:foo@bar` — no authority *and* no rooted path) remain rejected: there is no location to match a redirect against. The redirect *emitters* (`IndirectResponseQueryStringStrategy`/`IndirectResponseUrlFragmentStrategy`) also special-case this form: Laravel's `Redirect::to()` relies on the same `FILTER_VALIDATE_URL` check internally (`UrlGenerator::isValidUrl()`) and would otherwise treat the already-validated target as a relative path, prefixing the site URL — an absolute URI Laravel does not recognize is emitted as a verbatim `Location` header instead (Symfony still rejects CR/LF in header values, so no header-injection surface opens).
 2. **Single source of truth for the deny-list policy, owned by the OAuth2 domain layer, not a generic HTTP helper.** The deny-list and loopback-host list are `const` arrays on `IClient` (domain policy for Native OAuth2 clients — the same interface already holding `ApplicationType_Native`, `ClientType_Confidential`, etc.). Since PHP interfaces can't hold method bodies, the predicate that interprets them (`isDisallowedNativeUriScheme(string $scheme, ?string $host = null): bool`) is a `public static` method on `Client`, the concrete entity. Both the write-time validator (`ClientService::assertNativeCustomSchemesAllowed()`, and the `redirect_uris` validation branch in `ClientService::update()`) and the runtime allow-gates (`Client::isUriAllowed()`, `Client::isPostLogoutUriAllowed()`, via a shared `Client::isNativeDangerousScheme()` helper) call this one method. The admin UI reads the same two lists at runtime instead of hand-duplicating them in JavaScript: `AdminController` passes `IClient::DISALLOWED_NATIVE_URI_SCHEMES`/`IClient::NATIVE_LOOPBACK_HOSTS` to the edit-client view, which injects them as `window.DISALLOWED_NATIVE_URI_SCHEMES`/`window.NATIVE_LOOPBACK_HOSTS` (the same mechanism already used for `window.APP_TYPES`); `logout_options.js`'s inline validator reads from `window.*` rather than maintaining its own copy. *(This constant/method placement was revised once, after initial review placed the deny-list on the generic `Utils\Http\HttpUtils` class — see Consequences.)*
 3. **`http` is a special case with an RFC 8252 loopback carve-out**: disallowed everywhere except `127.0.0.1` / `::1` / `localhost` (`IClient::NATIVE_LOOPBACK_HOSTS`). At match time (`Client::isUriAllowed()`), a Native client's http-loopback request is additionally compared **port-agnostically**: RFC 8252 §7.3 requires the AS to allow any port specified at request time, because native apps bind an ephemeral loopback port per run. Only the port is ignored — scheme, host, and path still require an exact match, and the loopback hosts are not cross-matched against each other (registering `127.0.0.1` does not allow `localhost`).
-4. **Cross-client scheme uniqueness** (`IClientRepository::hasCustomSchemeRegisteredOnAnotherClientThan`) checks all three URI columns together — a scheme claimed by another client in *any* of the three fields blocks re-registration in any of the three, since the OS-level interception risk is identical regardless of which field either client used. The query anchors matches to real list-item boundaries (start-of-field or immediately after a comma) rather than an unanchored substring `LIKE`, plus a comma-space variant tolerating the legacy `", scheme://"` single-space artifact that the pre-hardening `create()` could persist; `ClientFactory::populate()` now trims each list item before normalizing, so new rows are always canonical regardless of write path.
+4. **Cross-client scheme uniqueness** (`IClientRepository::hasCustomSchemeRegisteredOnAnotherClientThan`) checks all three URI columns together — a scheme claimed by another client in *any* of the three fields blocks re-registration in any of the three, since the OS-level interception risk is identical regardless of which field either client used. The query anchors matches to real list-item boundaries (start-of-field or immediately after a comma) rather than an unanchored substring `LIKE`, plus a comma-space variant tolerating the legacy `", scheme://"` single-space artifact that the pre-hardening `create()` could persist; `ClientFactory::populate()` now trims each list item before normalizing, so new rows are always canonical regardless of write path. The item boundary is `scheme:/` rather than `scheme://`, so a scheme claimed via the authority-less RFC 8252 §7.1 form (`scheme:/path`) collides with one claimed via the authority form (`scheme://host`) and vice versa — the OS-level interception risk is about the scheme, not the URI shape it was registered in.
 5. **Defense-in-depth**: the runtime allow-gates independently re-check the scheme deny-list; write-time validation is not the sole enforcement point.
 6. **Enforced on both write paths** (`create()` and `update()`) for all three fields, including `redirect_uris`. `redirect_uris` initially had no request-level validation in `create()` at all — closed during review (see Consequences) by adding it to the same `assertNativeCustomSchemesAllowed()` field loop already used for the other two fields. This closed gap is itself a deliberate API contract change beyond Native clients: `getCreatePayloadValidationRules()` previously declared none of the three URI fields, so `create()` accepted *any* value for them for every application type; the new `custom_url_set` rule enforces per-item https for non-Native types at create time. Automation that registered Web_App/JS clients with `http://` URIs (e.g. localhost dev tooling) or malformed lists now receives `412` where it previously got `201` — matching what `update()` always enforced for those types.
 7. **The `allowed_origins` admin UI input stays hidden for Native clients.** No runtime path enforces `allowed_origins` for Native today — both the IDP's own `OAuth2BearerAccessTokenRequestValidator` middleware and summit-api's equivalent gate the origin check to `application_type === JS_Client`. The field remains settable via the admin API only (the value ships in token-introspection responses and may be enforced by a resource server in the future), but exposing a UI control for a value nothing currently checks was judged not worth the surface.

tests/ClientApiTest.php

@@ -503,4 +503,38 @@ public function testUpdateNativeClientNotTouchingUriFieldsIgnoresLockContention(
         }
     }
 
+    public function testUpdateNativeClientRejectsSchemeAlreadyRegisteredInAuthorityLessForm(){
+
+        // RFC 8252 SS7.1 authority-less registrations (com.example.app:/oauth2redirect) store the scheme
+        // followed by ":/" instead of "://". The cross-client scheme-uniqueness LIKE must see that shape
+        // too: the OS-level interception risk is about the SCHEME, regardless of which URI form either
+        // client registered it in - so claiming "authlessscheme" via the authority-less form must block
+        // another client from claiming it via the authority form (and vice versa).
+        $client1 = EntityManager::getRepository(Client::class)->findOneBy(['app_name' => 'oauth2_native_app']);
+
+        $response = $this->action("PUT", "Api\\ClientApiController@update",
+            array(
+                'id'               => $client1->id,
+                'application_type' => IClient::ApplicationType_Native,
+                'redirect_uris'    => 'authlessscheme:/callback',
+            ),
+            [],
+            [],
+            []);
+        $this->assertResponseStatus(201);
+
+        $client2 = EntityManager::getRepository(Client::class)->findOneBy(['app_name' => 'oauth2_native_app2']);
+
+        $response = $this->action("PUT", "Api\\ClientApiController@update",
+            array(
+                'id'               => $client2->id,
+                'application_type' => IClient::ApplicationType_Native,
+                'redirect_uris'    => 'authlessscheme://other',
+            ),
+            [],
+            [],
+            []);
+        $this->assertResponseStatus(412);
+    }
+
 }

tests/OAuth2EndSessionTest.php

@@ -0,0 +1,50 @@
+<?php namespace Tests;
+/**
+ * Copyright 2026 OpenStack Foundation
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ **/
+
+use LaravelDoctrine\ORM\Facades\EntityManager;
+use Models\OAuth2\Client;
+
+/**
+ * Class OAuth2EndSessionTest
+ * NOTE: deliberately NOT placed in OAuth2ProtocolTestCase.php - that file's *TestCase.php suffix
+ * keeps it OUT of the Application Test Suite (PHPUnit only auto-discovers *Test.php), so a test
+ * added there would never run in CI.
+ * @package Tests
+ */
+final class OAuth2EndSessionTest extends OpenStackIDBaseTestCase
+{
+    public function testEndSessionRedirectsVerbatimToAuthorityLessPostLogoutUri()
+    {
+        // RFC 8252 SS7.1 authority-less URIs (com.example.app:/logout) fail Laravel's
+        // UrlGenerator::isValidUrl() (FILTER_VALIDATE_URL-based), so Redirect::to() inside
+        // IndirectResponseQueryStringStrategy used to treat the approved post-logout target as a
+        // RELATIVE path and prefix the site URL (Location: http://<idp>/com.example.app:/logout) -
+        // corrupting the redirect at the emitter even once the runtime allow-gates accept the
+        // authority-less form. The Location header must carry the registered URI verbatim, with the
+        // state round-tripped on the query string.
+        $client = EntityManager::getRepository(Client::class)->findOneBy(['app_name' => 'oauth2_native_app']);
+        $client->setPostLogoutRedirectUris('com.example.app:/logout');
+        EntityManager::persist($client);
+        EntityManager::flush();
+
+        $this->call('GET', '/oauth2/end-session', [
+            'client_id'                => $client->getClientId(),
+            'post_logout_redirect_uri' => 'com.example.app:/logout',
+            'state'                    => 'xyz',
+        ]);
+
+        $this->assertResponseStatus(302);
+        $this->assertEquals('com.example.app:/logout?state=xyz', $this->response->headers->get('Location'));
+    }
+}