From f9323110cea17ccd8265590074ffd7b9a5576976 Mon Sep 17 00:00:00 2001
From: Andy Dixon <andy@andydixon.com>
Date: Thu, 26 Feb 2026 12:02:21 +0000
Subject: [PATCH] docs: prohibit URL query transport of secrets and tokens

Update SDK security guidance to explicitly forbid placing client secrets or bearer tokens in URL query strings, matching provider-side hardening against secret leakage.
---
 README.md                 | 1 +
 docs/INTEGRATION_GUIDE.md | 1 +
 2 files changed, 2 insertions(+)

diff --git a/README.md b/README.md
index bdc3d09..e9da455 100644
--- a/README.md
+++ b/README.md
@@ -132,6 +132,7 @@ This wrapper now delegates to `BlackWall\Auth\AuthClient`.
 - Expect `access_denied` even after the consent page is displayed if provider-side project membership or tenant scope changes before consent submission.
 - Register only HTTPS redirect URIs in provider client settings (HTTP should be used only for localhost loopback during development).
 - Use OAuth/portal authentication endpoints for end users; provider admin login endpoints enforce separate admin scope checks.
+- Never place client secrets, refresh tokens, or access tokens in URL query strings.
 - For OIDC providers, include a per-request `nonce` in authorisation requests.
 - Always use HTTPS in production.
 - Store refresh tokens securely.
diff --git a/docs/INTEGRATION_GUIDE.md b/docs/INTEGRATION_GUIDE.md
index 4da2bf0..3358f41 100644
--- a/docs/INTEGRATION_GUIDE.md
+++ b/docs/INTEGRATION_GUIDE.md
@@ -147,6 +147,7 @@ try {
 - Configure OAuth client redirect URIs as HTTPS in production; reserve HTTP for localhost loopback testing only.
 - Assume provider rate limits are enforced per source identity (for example IP) and shared across related auth endpoints.
 - Rotate client secrets for confidential clients.
+- Do not transport secrets or tokens in URL query parameters; keep them in server-side session or secure storage only.
 - Add a unique `nonce` to each OIDC authorisation request.
 - Validate `state` on every callback request.
 - Use secure session cookies (`Secure`, `HttpOnly`, `SameSite=Lax` or stricter).