DRIVERS-2960: Clarify Reauthentication and Speculative Authentication…

… combination behavior

source/auth/auth.md

@@ -1787,7 +1787,8 @@ def speculative_auth(connection):
 
 If any operation fails with `ReauthenticationRequired` (error code 391) and MONGODB-OIDC is in use, the driver MUST
 reauthenticate the connection. Drivers MUST NOT resend a `hello` message during reauthentication, instead using SASL
-messages directly. See the main [reauthentication](#reauthentication-1) section for more information.
+messages directly. Drivers MUST NOT try to use Speculative Authentication during reauthentication.
+See the main [reauthentication](#reauthentication-1) section for more information.
 
 To reauthenticate a connection, invalidate the access token stored on the connection (i.e. the *Connection Cache*) from
 the *Client Cache*, fetch a new access token, and re-run the SASL conversation.
@@ -2040,6 +2041,7 @@ to EC2 instance metadata in ECS, for security reasons, Amazon states it's best p
 [IAM Roles for Tasks](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html))
 
 ## Changelog
+- 2024-08-19: Clarify Reauthentication and Speculative Authentication combination behavior.
 
 - 2024-05-29: Disallow comma character when `TOKEN_RESOURCE` is given in a connection string.
 

source/auth/tests/mongodb-oidc.md

@@ -129,7 +129,7 @@ source the `secrets-export.sh` file and use the associated env variables in your
 
 ### (4) Reauthentication
 
-\*\*4.1 Reauthentication Succeeds
+#### 4.1 Reauthentication Succeeds
 
 - Create an OIDC configured client.
 - Set a fail point for `find` commands of the form:
@@ -153,7 +153,7 @@ source the `secrets-export.sh` file and use the associated env variables in your
 - Assert that the callback was called 2 times (once during the connection handshake, and again during reauthentication).
 - Close the client.
 
-\*\*4.2 Read Commands Fail If Reauthentication Fails
+#### 4.2 Read Commands Fail If Reauthentication Fails
 
 - Create a `MongoClient` whose OIDC callback returns one good token and then bad tokens after the first call.
 - Perform a `find` operation that succeeds.
@@ -203,6 +203,35 @@ source the `secrets-export.sh` file and use the associated env variables in your
 - Assert that the callback was called 2 times.
 - Close the client.
 
+#### 4.4 Speculative Authentication should be ignored on Reauthentication
+
+- Create an OIDC configured client.
+- Poison the *Client Cache* with a valid access token to enforce Speculative Authentication.
+- Perform an `insert` operation that succeeds.
+- Assert that the callback was not called.
+- Assert there were no `SaslStart` commands executed.
+- Set a fail point for `insert` commands of the form:
+
+```javascript
+{
+ configureFailPoint: "failCommand",
+ mode: {
+ times: 1
+ },
+ data: {
+ failCommands: [
+ "insert"
+ ],
+ errorCode: 391 // ReauthenticationRequired
+ }
+}
+```
+
+- Perform an `insert` operation that succeeds.
+- Assert that the callback was called once.
+- Assert there were `SaslStart` commands executed.
+- Close the client.
+
 ## (5) Azure Tests
 
 Drivers MUST only run the Azure tests when testing on an Azure VM. See instructions in