Scope credentials to an origin and add clearAuthentication

Author: GrahamCampbell

CHANGELOG.md

@@ -5,7 +5,7 @@
 
 * Add `disableJavascript` option
 * Allow choosing the box model in `Node::getPosition()`
-* Add `Page::authenticate` method
+* Add `Page::authenticate` and `Page::clearAuthentication` methods
 
 
 ## 1.15.0 (2025-12-27)

README.md

@@ -691,13 +691,17 @@ You can set credentials to answer HTTP authentication challenges, such as basic
 use HeadlessChromium\Exception\AuthenticationFailed;
 
 try {
-    $page->authenticate('username', 'password');
-    $page->navigate('http://example.com/protected')->waitForNavigation();
+    $page->authenticate('username', 'password', 'https://example.com');
+    $page->navigate('https://example.com/protected')->waitForNavigation();
 } catch (AuthenticationFailed $e) {
     // invalid credentials
 }
 ```
 
+The origin argument restricts the credentials to challenges coming from that origin, compared by scheme, host and port, so that they cannot leak to other origins, e.g. through pages embedding cross-origin resources. Omit the origin to answer every challenge, e.g. when authenticating to a proxy. Use `Page::clearAuthentication` to remove the credentials again.
+
+`Page::authenticate` intercepts requests using the DevTools fetch domain, so it should not be combined with custom `Fetch.enable` usage on the same page.
+
 ### Set user agent
 
 You can set up a user-agent per page:

src/Page.php

@@ -30,6 +30,7 @@
 use HeadlessChromium\Exception\TargetDestroyed;
 use HeadlessChromium\Input\Keyboard;
 use HeadlessChromium\Input\Mouse;
+use HeadlessChromium\PageUtils\AuthenticationScope;
 use HeadlessChromium\PageUtils\CookiesGetter;
 use HeadlessChromium\PageUtils\PageEvaluation;
 use HeadlessChromium\PageUtils\PageLayoutMetrics;
@@ -84,6 +85,27 @@ class Page
      */
     protected $authCredentials;
 
+    /**
+     * Scope the authentication credentials are restricted to.
+     *
+     * @var AuthenticationScope|null
+     */
+    protected $authScope;
+
+    /**
+     * Challenges that were already provided the credentials.
+     *
+     * @var array<string, true>
+     */
+    protected $attemptedAuthentications = [];
+
+    /**
+     * Whether the authentication challenge listeners were registered.
+     *
+     * @var bool
+     */
+    protected $authListenersRegistered = false;
+
     /**
      * Page constructor.
      *
@@ -170,48 +192,102 @@ public function getSession(): Session
      * Sets credentials to be used when the page encounters an HTTP authentication challenge,
      * such as basic authentication or a proxy requiring authentication.
      *
-     * Calling this method again replaces the credentials. If the browser rejects the
-     * credentials by challenging the same request again, the request is cancelled and an
+     * When an origin is given, the credentials are only used to answer challenges coming from
+     * that origin, compared by scheme, host and port, and only requests within that origin are
+     * intercepted. Omit the origin to answer every challenge, e.g. when authenticating to a proxy.
+     *
+     * Calling this method again replaces the credentials and the origin. If the browser rejects
+     * the credentials by repeating a challenge, the request is cancelled and an
      * AuthenticationFailed exception is thrown from the method that is reading the browser
      * messages at that time, usually PageNavigation::waitForNavigation.
      *
+     * @throws \InvalidArgumentException
      * @throws CommunicationException
      * @throws NoResponseAvailable
      * @throws OperationTimedOut
      */
-    public function authenticate(string $username, string $password): void
+    public function authenticate(string $username, string $password, ?string $origin = null): void
     {
         $this->assertNotClosed();
 
-        $alreadyEnabled = null !== $this->authCredentials;
+        $scope = null !== $origin ? new AuthenticationScope($origin) : null;
 
         $this->authCredentials = ['username' => $username, 'password' => $password];
+        $this->authScope = $scope;
+        $this->attemptedAuthentications = [];
 
-        if ($alreadyEnabled) {
+        $this->registerAuthenticationListeners();
+
+        $this->getSession()->sendMessageSync(
+            new Message('Fetch.enable', [
+                'handleAuthRequests' => true,
+                'patterns' => [
+                    ['urlPattern' => null !== $scope ? $scope->getUrlPattern() : '*'],
+                ],
+            ])
+        );
+    }
+
+    /**
+     * Removes the credentials set with Page::authenticate and stops intercepting requests.
+     *
+     * @throws CommunicationException
+     * @throws NoResponseAvailable
+     * @throws OperationTimedOut
+     */
+    public function clearAuthentication(): void
+    {
+        $this->assertNotClosed();
+
+        if (null === $this->authCredentials) {
+            return;
+        }
+
+        $this->authCredentials = null;
+        $this->authScope = null;
+        $this->attemptedAuthentications = [];
+
+        $this->getSession()->sendMessageSync(new Message('Fetch.disable'));
+    }
+
+    /**
+     * Registers the fetch domain listeners used to answer authentication challenges.
+     */
+    private function registerAuthenticationListeners(): void
+    {
+        if ($this->authListenersRegistered) {
             return;
         }
 
-        // requests that were already provided the credentials; a second
-        // challenge for the same request means they were rejected
-        $attemptedAuthentications = [];
+        $this->authListenersRegistered = true;
 
-        $this->getSession()->on('method:Fetch.authRequired', function (array $params) use (&$attemptedAuthentications): void {
+        $this->getSession()->on('method:Fetch.authRequired', function (array $params): void {
             $requestId = $params['requestId'];
+            $challenge = $params['authChallenge'] ?? [];
 
-            if (\array_key_exists($requestId, $attemptedAuthentications)) {
-                $this->getSession()->sendMessageSync(
-                    new Message('Fetch.continueWithAuth', [
-                        'requestId' => $requestId,
-                        'authChallengeResponse' => [
-                            'response' => 'CancelAuth',
-                        ],
-                    ])
-                );
+            $attemptKey = \implode("\0", [
+                $requestId,
+                $challenge['source'] ?? '',
+                $challenge['origin'] ?? '',
+                $challenge['scheme'] ?? '',
+                $challenge['realm'] ?? '',
+            ]);
+
+            // a challenge that was already provided the credentials means they were rejected
+            if (\array_key_exists($attemptKey, $this->attemptedAuthentications)) {
+                $this->cancelAuthenticationChallenge($requestId);
 
                 throw new AuthenticationFailed('Authentication failed: invalid credentials.');
             }
 
-            $attemptedAuthentications[$requestId] = true;
+            // cancel out of scope challenges without exposing the credentials
+            if (null === $this->authCredentials || (null !== $this->authScope && !$this->authScope->matchesOrigin($challenge['origin'] ?? ''))) {
+                $this->cancelAuthenticationChallenge($requestId);
+
+                return;
+            }
+
+            $this->attemptedAuthentications[$attemptKey] = true;
 
             $this->getSession()->sendMessageSync(
                 new Message('Fetch.continueWithAuth', [
@@ -232,12 +308,18 @@ public function authenticate(string $username, string $password): void
                 ])
             );
         });
+    }
 
+    /**
+     * Cancels an authentication challenge without exposing the credentials.
+     */
+    private function cancelAuthenticationChallenge(string $requestId): void
+    {
         $this->getSession()->sendMessageSync(
-            new Message('Fetch.enable', [
-                'handleAuthRequests' => true,
-                'patterns' => [
-                    ['urlPattern' => '*'],
+            new Message('Fetch.continueWithAuth', [
+                'requestId' => $requestId,
+                'authChallengeResponse' => [
+                    'response' => 'CancelAuth',
                 ],
             ])
         );

src/PageUtils/AuthenticationScope.php

@@ -0,0 +1,103 @@
+<?php
+
+/*
+ * This file is part of Chrome PHP.
+ *
+ * (c) Soufiane Ghzal <sghzal@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace HeadlessChromium\PageUtils;
+
+/**
+ * Restricts authentication credentials to a single web origin.
+ */
+class AuthenticationScope
+{
+    /**
+     * @var string
+     */
+    protected $scheme;
+
+    /**
+     * @var string
+     */
+    protected $host;
+
+    /**
+     * @var int
+     */
+    protected $port;
+
+    /**
+     * @param string $origin an absolute http or https URI; any path, query or fragment is ignored
+     *
+     * @throws \InvalidArgumentException
+     */
+    public function __construct(string $origin)
+    {
+        $parts = \parse_url($origin);
+
+        if (false === $parts || !isset($parts['scheme'], $parts['host'])) {
+            throw new \InvalidArgumentException('The authentication origin must be an absolute http or https URI.');
+        }
+
+        if (isset($parts['user']) || isset($parts['pass'])) {
+            throw new \InvalidArgumentException('The authentication origin must not contain user info.');
+        }
+
+        $scheme = \strtolower($parts['scheme']);
+
+        if (!\in_array($scheme, ['http', 'https'], true)) {
+            throw new \InvalidArgumentException('The authentication origin must use the http or https scheme.');
+        }
+
+        $host = \strtolower($parts['host']);
+
+        // colons are only valid within bracketed IPv6 literals
+        if ('[' === \substr($host, 0, 1)) {
+            $validHost = 1 === \preg_match('/^\[[0-9a-f:.]+\]$/D', $host);
+        } else {
+            $validHost = 1 === \preg_match('/^[a-z0-9\-._~%]+$/D', $host);
+        }
+
+        if (!$validHost) {
+            throw new \InvalidArgumentException('The authentication origin host contains invalid characters.');
+        }
+
+        $this->scheme = $scheme;
+        $this->host = $host;
+        $this->port = $parts['port'] ?? ('https' === $scheme ? 443 : 80);
+    }
+
+    /**
+     * Check whether the given origin, e.g. of an authentication challenge, is the same web origin.
+     */
+    public function matchesOrigin(string $origin): bool
+    {
+        try {
+            $other = new self($origin);
+        } catch (\InvalidArgumentException $e) {
+            return false;
+        }
+
+        return $other->scheme === $this->scheme && $other->host === $this->host && $other->port === $this->port;
+    }
+
+    /**
+     * Get the fetch request pattern matching only URLs within this origin.
+     */
+    public function getUrlPattern(): string
+    {
+        $pattern = $this->scheme.'://'.$this->host;
+
+        // browsers omit default ports in request URLs
+        if (('http' === $this->scheme && 80 !== $this->port) || ('https' === $this->scheme && 443 !== $this->port)) {
+            $pattern .= ':'.$this->port;
+        }
+
+        return $pattern.'/*';
+    }
+}

tests/AuthenticationTest.php

@@ -67,6 +67,52 @@ public function testAuthenticateUpdatesCredentialsForNewChallenges(): void
         self::assertStringContainsString('Authenticated', $page->getHtml());
     }
 
+    public function testAuthenticateScopedToOriginAllowsMatchingOrigin(): void
+    {
+        $page = self::$browser->createPage();
+
+        $page->authenticate(self::VALID_USER, self::VALID_PASS, 'HTTP://LOCALHOST:8083/ignored/path');
+        $page->navigate(self::sitePath(self::AUTH_URL))->waitForNavigation();
+
+        self::assertStringContainsString('Authenticated', $page->getHtml());
+    }
+
+    public function testAuthenticateScopedToDifferentOriginDoesNotSendCredentials(): void
+    {
+        $page = self::$browser->createPage();
+
+        $page->authenticate(self::VALID_USER, self::VALID_PASS, 'http://127.0.0.1:8083');
+        $page->navigate(self::sitePath(self::AUTH_URL))->waitForNavigation();
+
+        self::assertStringNotContainsString('Authenticated', $page->getHtml());
+    }
+
+    public function testAuthenticateThrowsOnInvalidOrigin(): void
+    {
+        $page = self::$browser->createPage();
+
+        $this->expectException(\InvalidArgumentException::class);
+
+        $page->authenticate(self::VALID_USER, self::VALID_PASS, 'not an origin');
+    }
+
+    public function testClearAuthenticationStopsAnsweringChallenges(): void
+    {
+        $page = self::$browser->createPage();
+
+        $page->authenticate(self::VALID_USER, self::VALID_PASS);
+        $page->navigate(self::sitePath(self::AUTH_URL))->waitForNavigation();
+
+        self::assertStringContainsString('Authenticated', $page->getHtml());
+
+        $page->clearAuthentication();
+
+        // expect different credentials so the previously cached ones no longer authenticate
+        $page->navigate(self::sitePath(self::AUTH_URL.'?user=otheruser&pass=otherpass'))->waitForNavigation();
+
+        self::assertStringNotContainsString('Authenticated', $page->getHtml());
+    }
+
     public function testAuthenticateThrowsOnInvalidCredentials(): void
     {
         $page = self::$browser->createPage();