@respira/wordpress-mcp-server 8.3.19 → 8.3.21

package/dist/wordpress-client.js

@@ -286,12 +286,62 @@ const PUT_FALLBACK_CONNECTION_CODES = new Set(['ECONNABORTED', 'ETIMEDOUT', 'ECO
 export function isRetryableAsPost(error) {
     if (PUT_FALLBACK_STATUSES.has(error?.response?.status))
         return true;
-    if (error?.name === 'http_403_non_wordpress')
+    if (PUT_FALLBACK_STATUSES.has(codedNonWordPressStatus(error)))
         return true;
     if (error?.response)
         return false;
     return PUT_FALLBACK_CONNECTION_CODES.has(String(error?.code || '').toUpperCase());
 }
+/**
+ * The HTTP status behind a `http_<status>_non_wordpress` coded error, or NaN.
+ *
+ * `handleError` rebuilds every non-2xx into a fresh `Error` via `codedError`,
+ * which does not carry `.response`. So check (1) in `isRetryableAsPost` —
+ * `error.response.status` — can only ever fire on an error that has NOT been
+ * through the interceptor. Through the real client it never fires, and the
+ * hardcoded `error.name === 'http_403_non_wordpress'` check that patched
+ * around that covered exactly one of the three statuses in
+ * PUT_FALLBACK_STATUSES.
+ *
+ * That is why ticket 139f7353's host was not rescued by the fallback even
+ * where the fallback was already wired in: its edge answers PUT with 405 and
+ * an HTML body, which arrives as `http_405_non_wordpress` with no `.response`
+ * and no matching name, so the retry was skipped and the tool surfaced the
+ * 405. Reading the status back out of the code keeps PUT_FALLBACK_STATUSES
+ * the single source of truth instead of growing a second hardcoded list.
+ *
+ * Deliberately only matches the `_non_wordpress` codes. A 403/404/405 raised
+ * BY WordPress arrives with its own WP_Error code stamped on `.name`, and
+ * those are real decisions ("you may not edit this", "no such route"), not
+ * verb-level routing facts, so they must still not be retried.
+ */
+function codedNonWordPressStatus(error) {
+    const match = /^http_(\d{3})_non_wordpress$/.exec(String(error?.name || ''));
+    return match ? Number(match[1]) : NaN;
+}
+/**
+ * Error codes that mean the failure came from the RESPIRA account service, not
+ * from the customer's WordPress install.
+ *
+ * The plugin cannot validate a dashboard site token or an OAuth access token
+ * locally: it POSTs to respira.press/api/mcp/site-token/introspect. When that
+ * call fails, the plugin still has to answer the agent with something, and the
+ * something is a 5xx carrying one of these codes.
+ *
+ * `respira_invalid_site_token` is on the list for a reason that looks wrong at
+ * first. On plugin builds shipped before this fix, ANY introspection failure —
+ * including a Respira-side Supabase outage — came back with that code and the
+ * upstream HTTP status adopted verbatim. Those builds are in the field. A 500
+ * carrying `respira_invalid_site_token` is therefore a Respira outage, not a
+ * bad token: a genuinely invalid token comes back 401/403, which classifies as
+ * `auth`, not `server`.
+ */
+const RESPIRA_ACCOUNT_SERVICE_CODES = new Set([
+    'respira_site_token_validation_failed',
+    'respira_invalid_site_token',
+    'introspection_unavailable',
+    'introspection_failed',
+]);
 /**
  * Classify a failed v2 status probe.
  *
@@ -308,45 +358,125 @@ export function classifyV2Failure(error) {
         return { kind: 'auth', status, code, detail };
     if (status === 404)
         return { kind: 'missing', status };
+    // `code` was being dropped here while the auth branch kept it, so a 5xx that
+    // said in plain text "this came from the Respira account service" arrived at
+    // describeV2Failure as an anonymous server error and got site-side advice.
     if (Number.isFinite(status) && status > 0)
-        return { kind: 'server', status, detail };
+        return { kind: 'server', status, code, detail };
     return { kind: 'network', detail: typeof error?.message === 'string' ? error.message : undefined };
 }
+/**
+ * Default: how long a FAILED v2 negotiation stays cached before the next
+ * v2-gated call re-probes instead of reusing the cached failure.
+ *
+ * A SUCCESSFUL negotiation ('v2') is cached for the life of the
+ * WordPressClient — respira/v2 does not appear and disappear on a healthy
+ * site, and re-probing it on every call would be pure overhead. A FAILURE is
+ * different: it can mean "this site really is v1-only" (worth caching, so a
+ * genuinely v1-only site isn't re-probed on every single tool call) or "the
+ * host had a transient 500 / hiccup" (must NOT stay cached, or every retry
+ * for the rest of the session repeats a stale verdict). The client cannot
+ * tell those two cases apart from here, so both get this same short TTL
+ * rather than the permanent latch that stranded tickets 7dce1a8a and
+ * f3310791 for 15+ minutes: every retry returned the identical cached
+ * message with zero new HTTP requests and nothing in the site's server logs.
+ *
+ * Overridable via RESPIRA_V2_NEGOTIATION_TTL_MS (ms). Not a documented
+ * customer-facing setting — it exists so tests don't need to sleep for a
+ * full production TTL.
+ */
+export const DEFAULT_V2_NEGOTIATION_FAILURE_TTL_MS = 60_000;
+export function v2NegotiationFailureTtlMs(env = process.env) {
+    const raw = env.RESPIRA_V2_NEGOTIATION_TTL_MS;
+    if (raw === undefined || raw === '')
+        return DEFAULT_V2_NEGOTIATION_FAILURE_TTL_MS;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_V2_NEGOTIATION_FAILURE_TTL_MS;
+}
 /**
  * Turn a negotiation failure into something the reader can act on.
  *
  * Each branch names what is actually known, and only the `missing` branch
  * keeps the old list of environmental causes, because that list is only ever
  * true for a real 404.
+ *
+ * @param observedAt When set, this failure is being reported from cache
+ * rather than from a probe made during this call — pass the timestamp
+ * (`Date.now()` epoch ms) the failure was first observed so the reader isn't
+ * told about a request that didn't happen. `null`/`undefined` means the probe
+ * ran during this call and the result is fresh.
  */
-export function describeV2Failure(failure, siteUrl) {
+export function describeV2Failure(failure, siteUrl, observedAt) {
     const probe = `${siteUrl}/wp-json/respira/v2/status`;
+    let message;
     if (failure?.kind === 'auth') {
-        return (`respira/v2 rejected this API key (HTTP ${failure.status}${failure.code ? `, ${failure.code}` : ''}).\n\n` +
-            (failure.detail ? `The site said: ${failure.detail}\n\n` : '') +
-            'The v2 routes exist and are reachable — this is an authentication result, not a missing namespace. ' +
-            'Most often the key was deactivated (a lapsed licence disables API keys, and renewing does not ' +
-            'currently re-enable them) or it was minted for a different site.\n\n' +
-            'To fix: reconnect the site from respira.press/dashboard/sites to mint a fresh key, then restart your MCP client.');
-    }
-    if (failure?.kind === 'server') {
-        return (`respira/v2 returned HTTP ${failure.status} on this site.\n\n` +
-            (failure.detail ? `The site said: ${failure.detail}\n\n` : '') +
-            `The namespace is registered but the request failed server-side. Check wp-content/debug.log, then open ${probe}.`);
-    }
-    if (failure?.kind === 'network') {
-        return ('Could not reach respira/v2 on this site.\n\n' +
-            (failure.detail ? `${failure.detail}\n\n` : '') +
-            `This is a connectivity failure, not a plugin problem. Confirm the site is up, then open ${probe}.`);
-    }
-    // kind === 'missing', or we never got to probe at all.
-    return ('respira/v2 is not available on this site.\n\n' +
-        'Common causes:\n' +
-        '• A security plugin (Wordfence, Sucuri, iThemes Security) is blocking the /wp-json/respira/v2/ path — whitelist that path in the plugin settings.\n' +
-        '• WordPress permalinks are set to "Plain" — go to Settings → Permalinks and choose any option except Plain.\n' +
-        '• A WAF or CDN (e.g. Cloudflare) is blocking requests with the X-Respira-API-Key header — add a WAF exception for /wp-json/respira/.\n' +
-        '• The Respira plugin is outdated — update to the latest version from your WordPress admin.\n\n' +
-        `To diagnose: open ${probe} in a browser. If you see a 404 or blocked page, one of the above applies.`);
+        message =
+            `respira/v2 rejected this API key (HTTP ${failure.status}${failure.code ? `, ${failure.code}` : ''}).\n\n` +
+                (failure.detail ? `The site said: ${failure.detail}\n\n` : '') +
+                'The v2 routes exist and are reachable — this is an authentication result, not a missing namespace. ' +
+                'Most often the key was deactivated (a lapsed licence disables API keys, and renewing does not ' +
+                'currently re-enable them) or it was minted for a different site.\n\n' +
+                'To fix: reconnect the site from respira.press/dashboard/sites to mint a fresh key, then restart your MCP client.';
+    }
+    else if (failure?.kind === 'server' && failure.code && RESPIRA_ACCOUNT_SERVICE_CODES.has(failure.code)) {
+        // The customer who triggered this fix read "The site said: Could not query
+        // the database for the schema cache. Retrying." plus "Check
+        // wp-content/debug.log" and spent hours hunting a fault in his own install.
+        // That sentence was PostgREST PGRST002 from the Respira Supabase. Say whose
+        // fault it is, and never send the reader to their own logs for it.
+        message =
+            `respira/v2 returned HTTP ${failure.status} on this site (${failure.code}).\n\n` +
+                'This is a Respira account-service problem, not a problem with this WordPress site. ' +
+                'The plugin cannot validate a dashboard or OAuth token on its own, so it asks respira.press; ' +
+                'respira.press did not answer, and the plugin refused the call rather than guess.\n\n' +
+                (failure.detail ? `respira.press reported: ${failure.detail}\n\n` : '') +
+                'There is nothing to fix on this site, and nothing about this will appear in its logs. ' +
+                'Retry in a minute. If it persists, contact https://respira.press/support with the time and the code above.';
+    }
+    else if (failure?.kind === 'server') {
+        message =
+            `respira/v2 returned HTTP ${failure.status} on this site${failure.code ? ` (${failure.code})` : ''}.\n\n` +
+                (failure.detail ? `The site said: ${failure.detail}\n\n` : '') +
+                `The namespace is registered but the request failed server-side. Check wp-content/debug.log, then open ${probe}.`;
+    }
+    else if (failure?.kind === 'network') {
+        message =
+            'Could not reach respira/v2 on this site.\n\n' +
+                (failure.detail ? `${failure.detail}\n\n` : '') +
+                `This is a connectivity failure, not a plugin problem. Confirm the site is up, then open ${probe}.`;
+    }
+    else {
+        // kind === 'missing', or we never got to probe at all.
+        message =
+            'respira/v2 is not available on this site.\n\n' +
+                'Common causes:\n' +
+                '• A security plugin (Wordfence, Sucuri, iThemes Security) is blocking the /wp-json/respira/v2/ path — whitelist that path in the plugin settings.\n' +
+                '• WordPress permalinks are set to "Plain" — go to Settings → Permalinks and choose any option except Plain.\n' +
+                '• A WAF or CDN (e.g. Cloudflare) is blocking requests with the X-Respira-API-Key header — add a WAF exception for /wp-json/respira/.\n' +
+                '• The Respira plugin is outdated — update to the latest version from your WordPress admin.\n\n' +
+                `To diagnose: open ${probe} in a browser. If you see a 404 or blocked page, one of the above applies.`;
+    }
+    // Ticket 7dce1a8a / f3310791: a transient 500 latched this client to 'v1'
+    // for the rest of the session, and every retry repeated this exact message
+    // as if it had just re-checked — the plugin's server logs showed nothing
+    // because nothing was ever actually resent. A cached failure now says so.
+    if (observedAt) {
+        const ageMs = Math.max(0, Date.now() - observedAt);
+        message +=
+            `\n\n(This is a cached result, not a fresh check: v2 was first seen failing at ` +
+                `${new Date(observedAt).toISOString()} (${formatFailureAge(ageMs)} ago). ` +
+                'A later call will automatically re-probe once the cache expires.)';
+    }
+    return message;
+}
+/** Render a cached-failure age for `describeV2Failure`'s honesty note. */
+function formatFailureAge(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    const seconds = ms / 1000;
+    if (seconds < 60)
+        return `${seconds.toFixed(1)}s`;
+    return `${(seconds / 60).toFixed(1)}m`;
 }
 /**
  * Guarantee a delete call answers with SOMETHING an agent can act on.
@@ -443,6 +573,14 @@ export class WordPressClient {
      * of blaming the namespace for what was actually an auth rejection.
      */
     negotiationFailure = null;
+    /**
+     * `Date.now()` when `negotiationFailure` was set. Drives the TTL that
+     * expires a cached FAILURE (see `v2NegotiationFailureTtlMs`) and lets
+     * `describeV2Failure` say when a cached result was first observed instead
+     * of reading as a fresh check. Always `null` when `negotiatedApiVersion`
+     * is `'v2'` or the client hasn't negotiated yet.
+     */
+    negotiationFailureAt = null;
     // Version compatibility check — populated lazily on first API call.
     compatibilityChecked = false;
     compatibilityPromise = null;
@@ -1022,10 +1160,45 @@ export class WordPressClient {
     }
     /**
      * Determine whether site supports respira/v2 and cache the result.
+     *
+     * Wraps `negotiateApiVersion()`, which callers that need to know whether
+     * THIS call made a fresh HTTP request (vs. reused a cached failure) use
+     * directly — see `ensureV2()`.
      */
     async getApiVersion() {
-        if (this.negotiatedApiVersion) {
-            return this.negotiatedApiVersion;
+        return (await this.negotiateApiVersion()).version;
+    }
+    /**
+     * Core negotiation. A successful 'v2' result is cached for the life of the
+     * client. A failure (falls back to 'v1') is cached only for
+     * `v2NegotiationFailureTtlMs()` — once that ages out, the cached failure is
+     * discarded and the next call below re-probes for real, rather than
+     * repeating a verdict from a possibly long-gone transient error. See the
+     * comment on `v2NegotiationFailureTtlMs` for why (tickets 7dce1a8a,
+     * f3310791).
+     *
+     * `freshlyProbed` tells the caller whether THIS invocation actually sent
+     * the HTTP request (true — the result, if a failure, is brand new) or
+     * reused an existing cached failure (false — `negotiationFailureAt` names
+     * when it was first observed). `ensureV2()` uses this so a cached failure
+     * is reported honestly instead of reading like a request that just ran.
+     */
+    async negotiateApiVersion() {
+        if (this.negotiatedApiVersion === 'v2') {
+            return { version: 'v2', freshlyProbed: false };
+        }
+        if (this.negotiatedApiVersion === 'v1') {
+            const ttl = v2NegotiationFailureTtlMs();
+            const age = this.negotiationFailureAt !== null ? Date.now() - this.negotiationFailureAt : Infinity;
+            if (age < ttl) {
+                return { version: 'v1', freshlyProbed: false };
+            }
+            // The cached FAILURE aged out. Clear the latch so the block below runs
+            // a genuinely fresh probe instead of returning stale data — this is
+            // the fix for the permanent-latch bug: only a SUCCESS stays cached
+            // indefinitely; a failure never does.
+            this.negotiatedApiVersion = null;
+            this.negotiationPromise = null;
         }
         if (!this.negotiationPromise) {
             this.negotiationPromise = (async () => {
@@ -1046,6 +1219,7 @@ export class WordPressClient {
                     if (response.status >= 200 && response.status < 300) {
                         this.negotiatedApiVersion = 'v2';
                         this.negotiationFailure = null;
+                        this.negotiationFailureAt = null;
                         return 'v2';
                     }
                     this.negotiationFailure = classifyV2Failure({ response });
@@ -1056,10 +1230,12 @@ export class WordPressClient {
                     this.negotiationFailure = classifyV2Failure(error);
                 }
                 this.negotiatedApiVersion = 'v1';
+                this.negotiationFailureAt = Date.now();
                 return 'v1';
             })();
         }
-        return this.negotiationPromise;
+        const version = await this.negotiationPromise;
+        return { version, freshlyProbed: true };
     }
     /**
      * Expose negotiated API version for diagnostics.
@@ -1071,9 +1247,9 @@ export class WordPressClient {
      * Ensure connected site supports respira/v2.
      */
     async ensureV2() {
-        const version = await this.getApiVersion();
+        const { version, freshlyProbed } = await this.negotiateApiVersion();
         if (version !== 'v2') {
-            throw new Error(describeV2Failure(this.negotiationFailure, this.siteConfig.url));
+            throw new Error(describeV2Failure(this.negotiationFailure, this.siteConfig.url, freshlyProbed ? null : this.negotiationFailureAt));
         }
     }
     // ---------------------------------------------------------------------------
@@ -1222,12 +1398,33 @@ export class WordPressClient {
      * `forceWriteMethod: 'post'` on the site config skips the PUT entirely, for
      * hosts already known to drop it (support can set it without a plugin
      * change). Ticket e2d884cb.
+     *
+     * Ticket 139f7353: "every PUT write goes through here" was aspirational, not
+     * true. The fallback was wired into the shared callers (callRestV1 /
+     * callRestV2) and the three post-like methods, and the ~25 dedicated methods
+     * that call `client.put()` directly were left on a bare PUT. On a host whose
+     * edge blocks PUT (Kinsta + Cloudflare, reported against
+     * `respira_update_menu_item`) `respira_create_menu_item` worked, because it
+     * is a POST, and `respira_update_menu_item` returned 405, so a menu could be
+     * built and never reordered. Every one of those call sites now routes
+     * through here.
+     *
+     * This is safe for the whole set because the plugin registers all of them
+     * with `WP_REST_Server::EDITABLE`, which is literally `'POST, PUT, PATCH'`:
+     * the fallback POST reaches the identical handler. It is deliberately NOT
+     * extended to DELETE. Those routes are registered `DELETABLE`, so a fallback
+     * POST would return `rest_no_route` — a 404 that reads like "the plugin is
+     * too old" and would be a worse diagnosis than the honest 405. Making delete
+     * survive a blocked verb needs a plugin-side route change, not a connector
+     * change; see the ticket for the enumerated list.
      */
-    async putWithPostFallback(client, url, data) {
+    async putWithPostFallback(client, url, data, config = {}) {
         const callId = randomUUID();
-        const firstAttempt = { headers: { 'Idempotency-Key': callId } };
+        const extraHeaders = (config.headers || {});
+        const firstAttempt = { ...config, headers: { ...extraHeaders, 'Idempotency-Key': callId } };
         const fallbackAttempt = {
-            headers: { 'Idempotency-Key': callId, [ORIGINAL_METHOD_HEADER]: 'PUT' },
+            ...config,
+            headers: { ...extraHeaders, 'Idempotency-Key': callId, [ORIGINAL_METHOD_HEADER]: 'PUT' },
         };
         if (this.siteConfig.forceWriteMethod === 'post') {
             // No PUT was sent, so there is no earlier attempt to alias onto: a plain
@@ -1375,9 +1572,27 @@ export class WordPressClient {
             const res = await axios.get(probeUrl, {
                 timeout: 10000,
                 validateStatus: () => true,
-                headers: { Accept: 'application/json' },
+                // Ticket 44fcf6b5. This probe used to send `{ Accept }` and nothing
+                // else. Every other request this client makes carries
+                // `this.defaultHeaders`, which is where the site's configured
+                // `httpAuth` Basic credential lives — so on a site behind server-level
+                // HTTP Basic Auth this was the one request that went out without it.
+                // It came back 401 from the web server, `registered` evaluated false,
+                // and the connector then told the operator, in as many words, that the
+                // Respira REST namespace is not registered and the plugin is
+                // deactivated, deleted or failing to load. The plugin was fine; the
+                // connector had simply forgotten to log in for one request and then
+                // reported the resulting silence as a fact about their site.
+                headers: { ...this.defaultHeaders, Accept: 'application/json' },
             });
             const body = res.data;
+            // A 401/403 is the web server or WordPress declining to answer the
+            // question, not an answer to it. Returning `false` there is a claim the
+            // probe cannot support: the namespace could be perfectly well
+            // registered behind that challenge. `null` means "could not tell", and
+            // every caller already handles it by staying quiet.
+            if (res.status === 401 || res.status === 403)
+                return null;
             // A registered namespace answers with its own index. Anything else,
             // including another rest_no_route, means it is not there.
             const registered = res.status === 200
@@ -1404,18 +1619,56 @@ export class WordPressClient {
             // Handle specific error codes
             if (status === 401) {
                 if (isNonWordPressResponse) {
-                    // Likely nginx/Apache HTTP Basic Auth or a CDN/WAF challenge page
-                    const wwwAuth = error.response.headers?.['www-authenticate'] || '';
+                    // Likely nginx/Apache HTTP Basic Auth or a CDN/WAF challenge page.
+                    //
+                    // Ticket 44fcf6b5. Two things were wrong with the old wording, and
+                    // both of them are the same mistake: describing a guess as a fact.
+                    //
+                    // 1. When the challenge said `WWW-Authenticate: Basic`, this told
+                    //    the operator to add "httpAuth" to their site config — WITHOUT
+                    //    checking whether httpAuth was already there. On the reported
+                    //    site it was, and it had been sent on this very request. So the
+                    //    connector's advice was to do the thing that had already been
+                    //    done, and the one fact that would have moved the investigation
+                    //    forward (credentials were supplied and the server rejected
+                    //    them, or the challenge covers this verb specifically) was the
+                    //    one fact withheld.
+                    // 2. When the challenge did NOT say Basic, this asserted that "a
+                    //    firewall, CDN, or maintenance mode may be blocking API
+                    //    access". Nothing in a 401 is evidence of maintenance mode. A
+                    //    401 is an authentication challenge; maintenance mode is a 503.
+                    //    Naming maintenance sent people to look for an outage that was
+                    //    not happening.
+                    //
+                    // What this says now is only what the response actually contained:
+                    // the verb, the realm if the server named one, and whether this
+                    // connector sent a credential.
+                    const wwwAuth = String(error.response.headers?.['www-authenticate'] || '');
                     const isBasicAuth = /basic/i.test(wwwAuth);
-                    const hint = isBasicAuth
-                        ? 'The site requires HTTP Basic Authentication (username/password) — this is separate from your Respira API key. ' +
-                            'This is common on staging sites. To fix this, add "httpAuth" to your site config:\n\n' +
-                            '  "httpAuth": { "username": "your-user", "password": "your-pass" }\n\n' +
-                            'Or disable HTTP Basic Auth for the /wp-json/respira/* path in your server config.'
-                        : 'The site returned an HTML error page instead of a WordPress REST API response. ' +
-                            'A firewall, CDN, or maintenance mode may be blocking API access. ' +
-                            'Verify that ' + this.siteConfig.url + '/wp-json/respira/v1/context/site-info is accessible in your browser.';
-                    return this.codedError(`Site not reachable: ${this.siteConfig.url} returned a ${status} response from the web server (not WordPress).\n\n${hint}`, 'http_401_non_wordpress');
+                    const realmMatch = /realm="?([^",]+)"?/i.exec(wwwAuth);
+                    const realm = realmMatch ? realmMatch[1].trim() : null;
+                    const method = String(error.config?.method || '').toUpperCase() || 'the request';
+                    const credentialSent = !!(this.siteConfig.httpAuth?.username && this.siteConfig.httpAuth?.password);
+                    const what = isBasicAuth
+                        ? `The web server asked for HTTP Basic Authentication${realm ? ` (realm "${realm}")` : ''} on this ${method}. ` +
+                            'That is the server password, separate from your Respira API key.'
+                        : `The web server refused this ${method} with a 401 and an HTML page. ` +
+                            (wwwAuth
+                                ? `It sent an authentication challenge: ${wwwAuth}.`
+                                : 'It sent no WWW-Authenticate header, so it did not say which credential it wants.');
+                    const hint = credentialSent
+                        ? 'httpAuth IS configured for this site and those credentials were sent on this request, so this is not a missing-credential problem. ' +
+                            'Either the username/password no longer match what the server expects, or the protected area covers this HTTP method and not the ones that are working. ' +
+                            `Run respira_diagnose_connection: it reports the status of GET, OPTIONS and PUT separately, which is what separates "wrong password" from "${method} specifically is challenged". ` +
+                            'Re-check the credentials against the server config, and check whether the auth block is scoped by method (Apache <Limit>/<LimitExcept>, an nginx `limit_except` inside the protected location).'
+                        : isBasicAuth
+                            ? 'No httpAuth is configured for this site, so no credential was sent. Add one to your site config:\n\n' +
+                                '  "httpAuth": { "username": "your-user", "password": "your-pass" }\n\n' +
+                                'Or exempt the /wp-json/respira/* path from HTTP Basic Auth in your server config.'
+                            : 'No httpAuth is configured for this site, so no credential was sent. If the site prompts for a username and password in a browser, add one to your site config:\n\n' +
+                                '  "httpAuth": { "username": "your-user", "password": "your-pass" }\n\n' +
+                                `Otherwise a CDN or WAF is challenging the request. Open ${this.siteConfig.url}/wp-json/respira/v1/context/site-info in a browser to see which.`;
+                    return this.codedError(`Authentication required: ${this.siteConfig.url} returned a ${status} from the web server (not WordPress).\n\n${what}\n\n${hint}`, 'http_401_non_wordpress');
                 }
                 const reason = data?.message || data?.code || 'Invalid API key';
                 const authError = this.codedError(`Authentication failed: ${reason}`, typeof data?.code === 'string' && data.code ? data.code : 'http_401', data);
@@ -2993,7 +3246,7 @@ export class WordPressClient {
             const timeout = updates.content && updates.content.length > 50000
                 ? 60000 // 60 seconds for large content
                 : 30000; // 30 seconds default
-            const response = await this.client.put(`/builder/${builder}/modules/${pageId}`, {
+            const response = await this.putWithPostFallback(this.client, `/builder/${builder}/modules/${pageId}`, {
                 module_identifier: moduleIdentifier,
                 updates,
                 editTarget,
@@ -3306,6 +3559,12 @@ export class WordPressClient {
                         server: respHeaders['server'] ?? null,
                         'x-respira-auth-arrived': respHeaders['x-respira-auth-arrived'] ?? null,
                         link: respHeaders['link'] ?? null,
+                        // Ticket 44fcf6b5: the one header that separates "the edge blocks
+                        // this verb" from "the server is asking for a password". It was
+                        // being read on every response and recorded on none, so a Basic
+                        // Auth challenge on OPTIONS/PUT graded out as a method block and
+                        // sent the operator into WAF rules that had nothing to do with it.
+                        'www-authenticate': respHeaders['www-authenticate'] ?? null,
                     },
                 });
             }
@@ -3437,11 +3696,31 @@ export class WordPressClient {
         // An HTML 4xx/5xx is something in front of WordPress answering instead.
         const putReachedWordPress = !!putProbe && typeof putProbe.status === 'number' && putProbe.looks_like_html === false;
         const putBlockedAtEdge = !!putProbe && typeof putProbe.status === 'number' && putProbe.status >= 400 && !putReachedWordPress;
+        // Ticket 44fcf6b5. A 401/407 is not a method block, it is the server
+        // asking for a credential, and the two need opposite fixes. Grading an
+        // authentication challenge as "the edge is blocking non-GET methods"
+        // pointed a customer at Cloudflare and Wordfence rules on a site whose
+        // only gate was an .htaccess password, and the recommendation text never
+        // mentioned Basic Auth at all. `www-authenticate` on the response is the
+        // discriminator; the status alone is not, because some edges challenge
+        // with 403 and some WAFs reject with 401.
+        const authChallenged = (p) => !!p &&
+            typeof p.status === 'number' &&
+            (p.status === 401 || p.status === 407 || !!p.headers?.['www-authenticate']);
+        const putAuthChallenged = authChallenged(putProbe);
+        const optionsAuthChallenged = authChallenged(optionsProbe);
+        const httpAuthConfigured = !!(this.siteConfig.httpAuth?.username && this.siteConfig.httpAuth?.password);
         const writeMethodVerdict = (() => {
             // If plain GET is not healthy, nothing can be concluded about writes
             // specifically — the whole connection is the problem.
             if (!getOk)
                 return 'unknown';
+            // Checked BEFORE `blocked`: a 401 satisfies putBlockedAtEdge too, and
+            // the old ordering meant every auth challenge was reported as a method
+            // block. The verb never reached WordPress, so this diagnostic cannot
+            // say whether the verb itself is allowed — only that it was challenged.
+            if (putAuthChallenged || optionsAuthChallenged)
+                return 'auth_challenge';
             if (optionsBlocked || putBlockedAtEdge)
                 return 'blocked';
             if (putDropped || optionsDropped)
@@ -3452,13 +3731,36 @@ export class WordPressClient {
         })();
         // Kept as a tri-state boolean rather than a string so an existing truthiness
         // check still means "proven blocked" and never accidentally fires on the
-        // unknown case. null = could not tell.
+        // unknown case. null = could not tell — which is the honest answer for an
+        // auth challenge as well as for a dropped probe.
         const writeMethodBlocked = writeMethodVerdict === 'blocked' ? true : writeMethodVerdict === 'not_blocked' ? false : null;
         const forceWriteMethodHint = ' Unblock this connection immediately without touching the host: add ' +
             `"forceWriteMethod": "post" to the site object in ${CONFIG_FILE}. The Respira plugin ` +
             'registers the same handler on PUT and POST for every updatable resource, so POST does ' +
             'identical work and the connector stops sending PUT at all. Fixing the host is still the ' +
             'better end state, this just stops the bleeding.';
+        if (writeMethodVerdict === 'auth_challenge') {
+            const challengedProbe = putAuthChallenged ? putProbe : optionsProbe;
+            const verb = putAuthChallenged ? 'PUT' : 'OPTIONS';
+            const challenge = String(challengedProbe?.headers?.['www-authenticate'] || '');
+            const scheme = /basic/i.test(challenge)
+                ? 'HTTP Basic Auth'
+                : challenge
+                    ? `an authentication challenge (${challenge})`
+                    : 'an authentication challenge with no WWW-Authenticate header';
+            recommendations.push(`${verb} /wp-json/respira/v1/ping returned ${challengedProbe?.status} with ${scheme} while GET returned 2xx. ` +
+                'This is an authentication challenge, not a blocked HTTP verb: the request never reached WordPress, so nothing here ' +
+                'proves the verb is allowed OR disallowed, and no WAF or CDN method rule is implicated. ' +
+                (httpAuthConfigured
+                    ? 'httpAuth IS configured for this site and was sent on this probe, so the credential is either wrong now or does not cover this method. ' +
+                        'Check the username and password against the server, and check whether the protected block is scoped by method ' +
+                        '(Apache <Limit>/<LimitExcept> inside the auth block, or an nginx `limit_except` inside the protected location) — ' +
+                        'a method-scoped auth block is exactly what makes GET work and everything else fail.'
+                    : 'No httpAuth is configured for this site, so no credential was sent. Add ' +
+                        `"httpAuth": { "username": "...", "password": "..." } to the site object in ${CONFIG_FILE}, ` +
+                        'or exempt /wp-json/respira/* from the password in the server config.') +
+                ' Do not set "forceWriteMethod": "post" for this: POST is challenged the same way, so it would change nothing.');
+        }
         if (writeMethodVerdict === 'unknown' && (putDropped || optionsDropped)) {
             const droppedLabel = putDropped ? 'PUT' : 'OPTIONS';
             const droppedCode = String((putDropped ? putProbe : optionsProbe)?.code || 'no response');
@@ -3532,14 +3834,23 @@ export class WordPressClient {
             // `write_method_verdict` for the named state; never treat null as false.
             write_method_blocked: writeMethodBlocked,
             write_method_verdict: writeMethodVerdict,
+            // Ticket 44fcf6b5: whether a credential was configured and sent is part
+            // of the evidence, not background knowledge the reader is assumed to
+            // have. Without it, "401 on PUT" and "401 on PUT with the password
+            // supplied" read identically, and they mean different things.
+            http_auth_configured: httpAuthConfigured,
             write_method_probe: {
                 options_status: optionsProbe?.status ?? null,
                 options_dropped: optionsDropped,
+                options_auth_challenged: optionsAuthChallenged,
                 put_status: putProbe?.status ?? null,
                 put_dropped: putDropped,
+                put_auth_challenged: putAuthChallenged,
                 put_reached_wordpress: putReachedWordPress,
                 put_error: putProbe?.error ?? null,
                 put_error_code: putProbe?.code ?? null,
+                put_www_authenticate: putProbe?.headers?.['www-authenticate'] ?? null,
+                options_www_authenticate: optionsProbe?.headers?.['www-authenticate'] ?? null,
             },
             target_post_id: opts.post_id ?? null,
             recommendations,
@@ -3728,7 +4039,7 @@ export class WordPressClient {
         return response.data;
     }
     async updateUser(id, data) {
-        const response = await this.client.put(`/users/${id}`, data);
+        const response = await this.putWithPostFallback(this.client, `/users/${id}`, data);
         return response.data;
     }
     async deleteUser(id, reassign, approval_token) {
@@ -3751,7 +4062,7 @@ export class WordPressClient {
         return response.data;
     }
     async updateComment(id, data) {
-        const response = await this.client.put(`/comments/${id}`, data);
+        const response = await this.putWithPostFallback(this.client, `/comments/${id}`, data);
         return response.data;
     }
     async deleteComment(id, approvalToken) {
@@ -3782,7 +4093,7 @@ export class WordPressClient {
         return response.data;
     }
     async updateTerm(taxonomy, id, data) {
-        const response = await this.client.put(`/taxonomies/${taxonomy}/terms/${id}`, data);
+        const response = await this.putWithPostFallback(this.client, `/taxonomies/${taxonomy}/terms/${id}`, data);
         return response.data;
     }
     async deleteTerm(taxonomy, id, approvalToken) {
@@ -3945,11 +4256,11 @@ export class WordPressClient {
         return response.data;
     }
     async updateMedia(id, data) {
-        const response = await this.client.put(`/media/${id}`, data);
+        const response = await this.putWithPostFallback(this.client, `/media/${id}`, data);
         return response.data.media || response.data;
     }
     async updateMediaBatch(items) {
-        const response = await this.client.put('/media/batch', { items });
+        const response = await this.putWithPostFallback(this.client, '/media/batch', { items });
         return response.data;
     }
     /**
@@ -3995,7 +4306,7 @@ export class WordPressClient {
         return response.data;
     }
     async updateMenu(id, data) {
-        const response = await this.client.put(`/menus/${id}`, data);
+        const response = await this.putWithPostFallback(this.client, `/menus/${id}`, data);
         return response.data;
     }
     async deleteMenu(id, approval_token) {
@@ -4010,7 +4321,7 @@ export class WordPressClient {
         return response.data;
     }
     async assignMenuToLocation(location, menuId) {
-        const response = await this.client.put(`/menus/locations/${location}`, { menu_id: menuId });
+        const response = await this.putWithPostFallback(this.client, `/menus/locations/${location}`, { menu_id: menuId });
         return response.data;
     }
     // Menu Items
@@ -4027,7 +4338,7 @@ export class WordPressClient {
         return response.data;
     }
     async updateMenuItem(itemId, data) {
-        const response = await this.client.put(`/menus/items/${itemId}`, data);
+        const response = await this.putWithPostFallback(this.client, `/menus/items/${itemId}`, data);
         return response.data;
     }
     async deleteMenuItem(itemId) {
@@ -4048,7 +4359,7 @@ export class WordPressClient {
         return response.data;
     }
     async woocommerceUpdateProduct(id, data) {
-        const response = await this.client.put(`/woocommerce/products/${id}`, data);
+        const response = await this.putWithPostFallback(this.client, `/woocommerce/products/${id}`, data);
         return response.data;
     }
     async woocommerceDuplicateProduct(id) {
@@ -4068,7 +4379,7 @@ export class WordPressClient {
         return response.data;
     }
     async woocommerceUpdateCategory(id, data) {
-        const response = await this.client.put(`/woocommerce/categories/${id}`, data);
+        const response = await this.putWithPostFallback(this.client, `/woocommerce/categories/${id}`, data);
         return response.data;
     }
     async woocommerceDeleteCategory(id) {
@@ -4088,7 +4399,7 @@ export class WordPressClient {
         return response.data;
     }
     async woocommerceUpdateTag(id, data) {
-        const response = await this.client.put(`/woocommerce/tags/${id}`, data);
+        const response = await this.putWithPostFallback(this.client, `/woocommerce/tags/${id}`, data);
         return response.data;
     }
     async woocommerceDeleteTag(id) {
@@ -4104,7 +4415,7 @@ export class WordPressClient {
         return response.data;
     }
     async woocommerceUpdateOrderStatus(id, status) {
-        const response = await this.client.put(`/woocommerce/orders/${id}/status`, { status });
+        const response = await this.putWithPostFallback(this.client, `/woocommerce/orders/${id}/status`, { status });
         return response.data;
     }
     async woocommerceGetStockStatus() {
@@ -4112,7 +4423,7 @@ export class WordPressClient {
         return response.data;
     }
     async woocommerceUpdateStock(id, data) {
-        const response = await this.client.put(`/woocommerce/products/${id}/stock`, data);
+        const response = await this.putWithPostFallback(this.client, `/woocommerce/products/${id}/stock`, data);
         return response.data;
     }
     async woocommerceSalesReport(params) {
@@ -4133,7 +4444,7 @@ export class WordPressClient {
         return response.data;
     }
     async woocommerceUpdateBrand(id, data) {
-        const response = await this.client.put(`/woocommerce/brands/${id}`, data);
+        const response = await this.putWithPostFallback(this.client, `/woocommerce/brands/${id}`, data);
         return response.data;
     }
     async woocommerceDeleteBrand(id) {
@@ -4231,7 +4542,7 @@ export class WordPressClient {
         return response.data;
     }
     async woocommerceSetVariationGallery(id, data) {
-        const response = await this.client.put(`/woocommerce/variations/${id}/gallery`, data);
+        const response = await this.putWithPostFallback(this.client, `/woocommerce/variations/${id}/gallery`, data);
         return response.data;
     }
     // WooCommerce Add-on v3.0 — coupons and customers
@@ -4244,7 +4555,7 @@ export class WordPressClient {
         return response.data;
     }
     async woocommerceUpdateCoupon(id, data) {
-        const response = await this.client.put(`/woocommerce/coupons/${id}`, data);
+        const response = await this.putWithPostFallback(this.client, `/woocommerce/coupons/${id}`, data);
         return response.data;
     }
     async woocommerceCreateCustomer(data) {
@@ -4252,7 +4563,7 @@ export class WordPressClient {
         return response.data;
     }
     async woocommerceUpdateCustomer(id, data) {
-        const response = await this.client.put(`/woocommerce/customers/${id}`, data);
+        const response = await this.putWithPostFallback(this.client, `/woocommerce/customers/${id}`, data);
         return response.data;
     }
     // WooCommerce Add-on v3.0 — order notes and refunds
@@ -4278,11 +4589,11 @@ export class WordPressClient {
         return response.data;
     }
     async woocommerceUpdateSubscriptionStatus(id, data) {
-        const response = await this.client.put(`/woocommerce/subscriptions/${id}/status`, data || {});
+        const response = await this.putWithPostFallback(this.client, `/woocommerce/subscriptions/${id}/status`, data || {});
         return response.data;
     }
     async woocommerceUpdateSubscriptionDates(id, data) {
-        const response = await this.client.put(`/woocommerce/subscriptions/${id}/dates`, data || {});
+        const response = await this.putWithPostFallback(this.client, `/woocommerce/subscriptions/${id}/dates`, data || {});
         return response.data;
     }
     async woocommerceAddSubscriptionNote(id, data) {
@@ -4298,11 +4609,11 @@ export class WordPressClient {
         return response.data;
     }
     async woocommerceUpdateBookingStatus(id, data) {
-        const response = await this.client.put(`/woocommerce/bookings/${id}/status`, data || {});
+        const response = await this.putWithPostFallback(this.client, `/woocommerce/bookings/${id}/status`, data || {});
         return response.data;
     }
     async woocommerceRescheduleBooking(id, data) {
-        const response = await this.client.put(`/woocommerce/bookings/${id}/reschedule`, data || {});
+        const response = await this.putWithPostFallback(this.client, `/woocommerce/bookings/${id}/reschedule`, data || {});
         return response.data;
     }
     async woocommerceListMembershipPlans(params) {
@@ -4318,11 +4629,11 @@ export class WordPressClient {
         return response.data;
     }
     async woocommerceUpdateMembershipStatus(id, data) {
-        const response = await this.client.put(`/woocommerce/memberships/${id}/status`, data || {});
+        const response = await this.putWithPostFallback(this.client, `/woocommerce/memberships/${id}/status`, data || {});
         return response.data;
     }
     async woocommerceSetMembershipEndDate(id, data) {
-        const response = await this.client.put(`/woocommerce/memberships/${id}/end-date`, data || {});
+        const response = await this.putWithPostFallback(this.client, `/woocommerce/memberships/${id}/end-date`, data || {});
         return response.data;
     }
     // WooCommerce Add-on v3.1 — assisted checkout
@@ -4535,7 +4846,7 @@ export class WordPressClient {
         const { method, path, body } = resolver(args);
         const req = method === 'GET' ? this.client.get(path)
             : method === 'POST' ? this.client.post(path, body || {})
-                : method === 'PUT' ? this.client.put(path, body || {})
+                : method === 'PUT' ? this.putWithPostFallback(this.client, path, body || {})
                     : this.client.request({ method: 'DELETE', url: path, data: body || {} });
         const response = await req;
         return response.data;