From 099a23ab726a2c48970b332a79594dc5f697b412 Mon Sep 17 00:00:00 2001
From: Chris Portscheller <cportsche1@gmail.com>
Date: Sun, 20 Sep 2026 19:10:24 -0500
Subject: [PATCH] docs: say that the clearance scope option limits nothing

The plugin carries a clearance_scope option, passes it to the client as
data-scope, and described it as "optional scope passed to the clearance
client (advanced)". Nothing enforces it: a clearance token is bound to
the organization, and no validator reads a token's scope.

Comments only. The option keeps being read and emitted, so a site that
set it behaves exactly as before.

Refs WebDecoy/app#1122.
---
 webdecoy.php | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/webdecoy.php b/webdecoy.php
index f61d5c1..79ee433 100644
--- a/webdecoy.php
+++ b/webdecoy.php
@@ -199,7 +199,12 @@ private function load_options(): void
             // is safe to expose in page markup. Enables silent wd_clearance
             // cookie minting so tripwire/decoy hits bind to a device fingerprint.
             'site_key' => '',
-            // Optional scope passed to the clearance client (advanced).
+            // Passed through to the clearance client as data-scope, and it
+            // limits nothing: a clearance token is bound to the organization,
+            // and no validator reads a token's scope (WebDecoy/app #1122).
+            // Kept so a site that set it years ago keeps working unchanged.
+            // To require more on a sensitive path, set that path's
+            // Verification required level in WebDecoy.
             'clearance_scope' => '',
 
             // Cloud connection metadata, populated by the one-click connect flow
@@ -1015,6 +1020,9 @@ public function add_defer_to_scanner(string $tag, string $handle, string $src):
         // script-tag attributes on older versions). Also load it async.
         if ($handle === 'webdecoy-clearance') {
             $attrs = ' async data-site-key="' . esc_attr((string) $this->options['site_key']) . '"';
+            // data-scope is inert: the client sends it, the mint signs it, and
+            // no validator reads it. Emitted only so a site that set the
+            // option behaves exactly as it did before (WebDecoy/app #1122).
             $scope = (string) ($this->options['clearance_scope'] ?? '');
             if ($scope !== '') {
                 $attrs .= ' data-scope="' . esc_attr($scope) . '"';
@@ -2331,7 +2339,8 @@ public function sanitize_options(array $input): array
             $sanitized['api_key'] = $api_key;
         }
 
-        // Publishable site key + clearance scope (not secret; stored as-is).
+        // Publishable site key, and the inert clearance scope (neither is
+        // secret; stored as-is).
         $sanitized['site_key'] = sanitize_text_field($input['site_key'] ?? '');
         $sanitized['clearance_scope'] = sanitize_text_field($input['clearance_scope'] ?? '');