docs: document invalid_scope handling and scope allowlist alignment

Clarifies that requested SDK scopes must be enabled on the provider OAuth client and adds callback-handling guidance for invalid_scope failures.

README.md

@@ -129,6 +129,7 @@ This wrapper now delegates to `BlackWall\Auth\AuthClient`.
 
 - Always validate OAuth `state` in callback handlers.
 - Handle provider callback errors (`error`, `error_description`) explicitly; treat `access_denied` as an expected user/authorisation outcome rather than a transport failure.
+- Treat `invalid_scope` as a client-configuration mismatch: requested scopes must be a subset of scopes allowed on the provider client.
 - Expect `access_denied` even after the consent page is displayed if provider-side project membership or tenant scope changes before consent submission.
 - Expect provider token introspection to return `active=false` when user/project/client state is no longer active.
 - Expect revoked JWT access tokens to be rejected by provider `userinfo` even before token expiry.
@@ -144,6 +145,7 @@ This wrapper now delegates to `BlackWall\Auth\AuthClient`.
 - Apply bounded CSV import sizes and row counts for admin bulk-user operations.
 - Never place client secrets, refresh tokens, or access tokens in URL query strings.
 - For OIDC providers, include a per-request `nonce` in authorisation requests.
+- Ensure requested `scope` values in SDK config/examples (for example `offline_access`) are enabled on the provider-side client before rollout.
 - For direct Cryptbin API usage, send `key_b64url` on unwrap calls; provider rejects key-mismatch unwrap attempts with `403 Forbidden`.
 - For newly created Cryptbin items, continue using the creating WebAuthn credential for unwrap/update/delete flows.
 - Always use HTTPS in production.

docs/INTEGRATION_GUIDE.md

@@ -67,7 +67,8 @@ if (isset($_GET['error'])) {
     $description = isset($_GET['error_description']) ? (string) $_GET['error_description'] : 'Unknown provider error';
     // access_denied is a normal authorisation outcome (for example, membership
     // revoked, privilege changed, or user denied consent between request and submit).
-    http_response_code($error === 'access_denied' ? 403 : 400);
+    // invalid_scope usually means the app requested scopes not enabled on the provider client.
+    http_response_code(in_array($error, ['access_denied', 'invalid_scope'], true) ? 403 : 400);
     exit('Authorization failed: ' . $description);
 }
 
@@ -142,6 +143,7 @@ Provider login/authorization steps can also fail with `access_denied` when accou
 WebAuthn-based login verification can return credential-style failures for disabled accounts even when authenticator assertions are otherwise valid.
 Existing authenticated sessions may also be invalidated when account status changes to disabled.
 OAuth authorization consent submission can return `access_denied` if the account becomes inactive between session establishment and consent completion.
+OAuth authorization can also return `invalid_scope` if requested scopes are not explicitly allowed on the provider client configuration.
 Provider user/project assignment views may exclude disabled projects even if historical assignments exist.
 
 ## Operational guidance