From ee3e53af459eab88289954a4d42ea70dfec2c8a1 Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Mon, 8 Jul 2024 05:43:06 +0200
Subject: [PATCH] Mark parameters containing user credentials as sensitive

PHP 8.2 introduced the `SensitiveParameter` attribute.

The effect of the attribute is that the value of the parameter is no longer directly shown in stack traces; instead, starting with PHP 8.2, the parameter will be presented as a `SensitiveParameterValue` object.

As the attribute only applies to parameters, it (unfortunately) has no effect on serialization of the object. See: https://3v4l.org/StoQO
Might be an idea to start a discussion about an `SensitiveProperty` attribute on the PHP Internals mailing list, but that's outside the scope of this PR.

For now, this PR marks the `$args` parameter for the `Auth\Basic` class constructor and the `Proxy\Http` constructor as sensitive as both of these are supposed to contain user credentials (user name, password) for accessing a protected URL.

Includes updating the example code for custom authentication to also use the attribute.

**Open question**: the `$options` array passed to a large range of Requests methods can [also contain credentials](https://github.com/WordPress/Requests/blob/ebb9f65855c860bc33005b3d8bccf6444e598fba/src/Requests.php#L395-L399). Should this parameter also be marked as sensitive in all appropriate places ?

Refs:
* https://www.php.net/manual/en/class.sensitiveparameter.php
* https://wiki.php.net/rfc/redact_parameters_in_back_traces
---
 docs/authentication-custom.md | 5 ++++-
 src/Auth/Basic.php            | 6 +++++-
 src/Proxy/Http.php            | 5 ++++-
 3 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/docs/authentication-custom.md b/docs/authentication-custom.md
index 8d7d6a519..4df56f5ba 100644
--- a/docs/authentication-custom.md
+++ b/docs/authentication-custom.md
@@ -16,7 +16,10 @@ services that do this; perhaps this is a market waiting to be tapped?)
 class MySoftware_Auth_Hotdog implements WpOrg\Requests\Auth {
     protected $password;
 
-    public function __construct($password) {
+    public function __construct(
+        #[\SensitiveParameter]
+        $password
+    ) {
         $this->password = $password;
     }
 
diff --git a/src/Auth/Basic.php b/src/Auth/Basic.php
index 829216f82..7c5787a97 100644
--- a/src/Auth/Basic.php
+++ b/src/Auth/Basic.php
@@ -9,6 +9,7 @@
 
 namespace WpOrg\Requests\Auth;
 
+use SensitiveParameter;
 use WpOrg\Requests\Auth;
 use WpOrg\Requests\Exception\ArgumentCount;
 use WpOrg\Requests\Exception\InvalidArgument;
@@ -48,7 +49,10 @@ class Basic implements Auth {
 	 * @throws \WpOrg\Requests\Exception\InvalidArgument When the passed argument is not an array or null.
 	 * @throws \WpOrg\Requests\Exception\ArgumentCount   On incorrect number of array elements (`authbasicbadargs`).
 	 */
-	public function __construct($args = null) {
+	public function __construct(
+		#[SensitiveParameter]
+		$args = null
+	) {
 		if (is_array($args)) {
 			if (count($args) !== 2) {
 				throw ArgumentCount::create('an array with exactly two elements', count($args), 'authbasicbadargs');
diff --git a/src/Proxy/Http.php b/src/Proxy/Http.php
index 2461e47ce..12c901e67 100644
--- a/src/Proxy/Http.php
+++ b/src/Proxy/Http.php
@@ -65,7 +65,10 @@ final class Http implements Proxy {
 	 * @throws \WpOrg\Requests\Exception\InvalidArgument When the passed argument is not an array, a string or null.
 	 * @throws \WpOrg\Requests\Exception\ArgumentCount On incorrect number of arguments (`proxyhttpbadargs`)
 	 */
-	public function __construct($args = null) {
+	public function __construct(
+		#[SensitiveParameter]
+		$args = null
+	) {
 		if (is_string($args)) {
 			$this->proxy = $args;
 		} elseif (is_array($args)) {