Update usage.md and known-issues.md regarding AADSTS70000 errors

contrib/init.d/onedrive.init

@@ -1,7 +1,7 @@
 #!/bin/sh
 #
 # chkconfig: 2345 20 80
-# description: Starts and stops OneDrive Free Client
+# description: Starts and stops OneDrive Client for Linux
 #
 
 # Source function library.
@@ -19,7 +19,7 @@ fi
 # Check that networking is up.
 [ ${NETWORKING} = "no" ] && exit 1
 
-APP_NAME="OneDrive Free Client"
+APP_NAME="OneDrive Client for Linux"
 STOP_TIMEOUT=${STOP_TIMEOUT-5}
 RETVAL=0
 

docs/advanced-usage.md

@@ -1,4 +1,4 @@
-# Advanced Configuration of the OneDrive Free Client
+# Advanced Configuration of the OneDrive Client for Linux
 This document covers the following scenarios:
 *   [Configuring the client to use multiple OneDrive accounts / configurations](#configuring-the-client-to-use-multiple-onedrive-accounts--configurations)
 *   [Configuring the client to use multiple OneDrive accounts / configurations using Docker](#configuring-the-client-to-use-multiple-onedrive-accounts--configurations-using-docker)

docs/known-issues.md

@@ -60,4 +60,49 @@ Recommended steps to address this issue include:
 * Reporting the issue to the OpenSSL and/or Curl teams for improved handling of such connection failures.
 * Creating a HTTPS Debug Log during the issue and submitting a support request to Microsoft with the log for their analysis.
 
-For more in-depth SSL troubleshooting, please read: https://maulwuff.de/research/ssl-debugging.html
+For more in-depth SSL troubleshooting, please read: https://maulwuff.de/research/ssl-debugging.html
+
+
+## AADSTS70000 returned during initial authorisation or re-authentication
+
+**Summary:**
+During initial authentication or when running `onedrive --reauth`, the client fails with:
+```
+AADSTS70000: The provided value for the 'code' parameter is not valid
+```
+This issue is **not a client bug** and is caused by the authorisation code being invalid at the time it is redeemed.
+
+**Detailed Description:**
+
+When authenticating, the user is redirected to a Microsoft login page in their web browser. After successful consent, the browser is redirected to a URL of the form:
+```
+https://login.microsoftonline.com/common/oauth2/nativeclient?code=<value>
+```
+The user must copy this URL and paste it back into the CLI when prompted.
+
+Microsoft authorisation codes are single-use and short-lived. If the code is altered, reused, expired, or otherwise invalidated before the client redeems it, Microsoft Entra ID returns AADSTS70000.
+
+**Technical Explanation:**
+
+The most common cause is **browser-side interference** with the redirect URL before the user copies it. Privacy and security tooling (such as ad-blockers, URL sanitisation, or “remove tracking parameters” features) can modify or invalidate the `code` query parameter.
+
+Other contributing factors include:
+* Copying the wrong URL (for example, not copying directly from the browser address bar immediately after consent)
+* Refreshing the page or attempting to reuse the same redirect URI
+* Waiting too long before pasting the redirect URI back into the CLI
+
+Once an authorisation code is invalid, it **cannot** be reused or recovered.
+
+**Recommended Resolution Steps:**
+
+1. Re-run authentication using:
+```
+onedrive --reauth
+```
+2. Use a private/incognito browser session or a clean browser profile
+3. Temporarily disable browser extensions or privacy features that modify URLs for the Microsoft login pages (for example: uBlock Origin, ClearURLs, Brave Shields)
+4. Complete the browser consent flow and immediately copy the redirect URI from the address bar and paste it into the CLI
+
+**Additional Notes:**
+
+For security reasons, users should **never post full redirect URIs** (they contain sensitive authorisation codes). Any such URLs must be redacted when shared in logs, issues, or support requests.

docs/usage.md

@@ -407,6 +407,26 @@ user@hostname:~$
 > [!IMPORTANT]
 > Without additional input or configuration, the OneDrive Client for Linux will automatically adhere to default application settings during synchronisation processes with Microsoft OneDrive.
 
+> [!IMPORTANT]
+> **Handling a AADSTS70000 response**
+>
+> If you paste the redirect URI back into the CLI and receive:
+> `AADSTS70000: The provided value for the 'code' parameter is not valid.`
+> this is **not a client bug**.
+>
+> Microsoft authorisation codes are single-use and short-lived, so the code you pasted is no longer redeemable.
+>
+> **Common causes:**
+> * Browser extensions / privacy tools modifying the redirect URL (for example, ad-blockers or 'remove tracking parameters' features within browsers)
+> * Copying the wrong URL (ensure you copy from the browser address bar immediately after consent)
+> * Refreshing the page or reusing the same redirect URI (codes can only be redeemed once)
+> * Waiting too long before pasting the URL back
+>
+> **Remediation steps for AADSTS70000:**
+> 1. Re-run: `onedrive --reauth`
+> 2. Use a private/incognito browser session or a clean browser profile
+> 3. Temporarily disable URL-filtering/privacy extensions for the Microsoft login pages (uBlock Origin / ClearURLs / Brave Shields / similar), then retry
+
 
 #### Single Sign-On (SSO) via Intune using the Microsoft Identity Device Broker 
 To use this method of authentication, you must add the following configuration to your 'config' file:
@@ -470,7 +490,7 @@ You will have ~15 minutes before the code expires.
 > If using a Personal Microsoft OneDrive account (e.g., @outlook.com or @hotmail.com), please complete authentication using the interactive authentication method detailed above.
 >
 > **Further Reading:**  
-> 📚 [Microsoft Documentation — OAuth 2.0 device authorization grant](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-device-code)
+> 📚 [Microsoft Documentation — OAuth 2.0 device authorisation grant](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-device-code)
 
 ### Display Your Applicable Runtime Configuration
 To verify the configuration that the application will use, use the following command: