feat: add --auth-state flag to wp-ajax-test for pw-auth cookie reuse

Adds passwordless authentication to wp-ajax-test by reading Playwright
auth state files from pw-auth. This eliminates the need for plaintext
credentials in temp/auth.json.

- New --auth-state flag reads cookies from pw-auth's cached auth state
- Filters cookies by target domain, skips expired, verifies wordpress_logged_in_*
- --auth-state takes precedence when both --auth and --auth-state are provided
- Deprecation warning on --auth pointing users to --auth-state
- MCP wp_ajax_test tool gains authState parameter (preferred over auth)
- Updated error suggestions to recommend pw-auth workflow
- 2 new MCP tests: auth-state precedence + flag-shaped path rejection
- README quick start updated to show pw-auth workflow first

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: noelsaw1

tools/mcp-server/src/handlers/wp-ajax-test.ts

@@ -78,16 +78,16 @@ function toSuggestions(value: unknown): string[] | null {
   return suggestions.length > 0 ? suggestions : null;
 }
 
-function normalizeAuthPath(authFile?: string): string | undefined {
-  if (!authFile) {
+function normalizeFilePath(filePath: string | undefined, label: string): string | undefined {
+  if (!filePath) {
     return undefined;
   }
 
-  if (authFile.startsWith("-")) {
-    throw new Error("wp_ajax_test auth file path must not start with '-'.");
+  if (filePath.startsWith("-")) {
+    throw new Error(`wp_ajax_test ${label} path must not start with '-'.`);
   }
 
-  return authFile;
+  return filePath;
 }
 
 function assertHttpUrl(url: string): void {
@@ -131,12 +131,17 @@ export function createWpAjaxTestHandlers(deps: WpAjaxTestHandlerDeps) {
       method: "GET" | "POST" = "POST",
       nopriv = false,
       insecure = false,
+      authState?: string,
     ): Promise<WpAjaxTestResult> {
       assertHttpUrl(url);
-      const normalizedAuthFile = normalizeAuthPath(authFile);
+      const normalizedAuthState = normalizeFilePath(authState, "auth-state");
+      const normalizedAuthFile = normalizeFilePath(authFile, "auth");
       const args = ["--url", url, "--action", action, "--data", JSON.stringify(data), "--format", "json", "--method", method];
 
-      if (normalizedAuthFile) {
+      // Prefer --auth-state over --auth
+      if (normalizedAuthState) {
+        args.push("--auth-state", normalizedAuthState);
+      } else if (normalizedAuthFile) {
         args.push("--auth", normalizedAuthFile);
       }
 
@@ -163,7 +168,7 @@ export function createWpAjaxTestHandlers(deps: WpAjaxTestHandlerDeps) {
           method,
           nopriv,
           insecure,
-          authProvided: Boolean(normalizedAuthFile),
+          authProvided: Boolean(normalizedAuthState || normalizedAuthFile),
           success: parsed.success === true,
           statusCode: toNumber(parsed.status_code),
           responseTimeMs: toNumber(parsed.response_time_ms),
@@ -186,7 +191,7 @@ export function createWpAjaxTestHandlers(deps: WpAjaxTestHandlerDeps) {
         method,
         nopriv,
         insecure,
-        authProvided: Boolean(normalizedAuthFile),
+        authProvided: Boolean(normalizedAuthState || normalizedAuthFile),
         success: false,
         statusCode: null,
         responseTimeMs: null,

tools/mcp-server/src/index.ts

@@ -346,7 +346,8 @@ export function createServer() {
         url: z.string().url().refine((value) => /^https?:\/\//i.test(value), "Only http:// and https:// URLs are allowed").describe("Full WordPress site URL, for example http://my-site.local"),
         action: z.string().min(1).describe("AJAX action name"),
         data: z.record(z.string(), z.unknown()).default({}).describe("JSON object payload passed to --data"),
-        auth: z.string().min(1).optional().describe("Optional auth JSON file path for authenticated AJAX requests"),
+        authState: z.string().min(1).optional().describe("Playwright auth state file from pw-auth (preferred — no plaintext passwords)"),
+        auth: z.string().min(1).optional().describe("Legacy auth JSON file with username/password (prefer authState)"),
         method: z.enum(["GET", "POST"]).default("POST"),
         nopriv: z.boolean().default(false).describe("Use the nopriv AJAX endpoint"),
         insecure: z.boolean().default(false).describe("Skip SSL certificate verification for local/self-signed dev environments"),
@@ -370,9 +371,9 @@ export function createServer() {
         exitCode: z.number(),
       },
     },
-    async ({ url, action, data, auth, method, nopriv, insecure }) => {
+    async ({ url, action, data, authState, auth, method, nopriv, insecure }) => {
       try {
-        return successResult(await wpAjaxTestHandlers.runTest(url, action, data ?? {}, auth, method ?? "POST", nopriv ?? false, insecure ?? false));
+        return successResult(await wpAjaxTestHandlers.runTest(url, action, data ?? {}, auth, method ?? "POST", nopriv ?? false, insecure ?? false, authState));
       } catch (error) {
         return errorResult(error);
       }

tools/mcp-server/test/wp-ajax-test.test.ts

@@ -142,6 +142,75 @@ test("wp_ajax_test rejects non-http URLs before execution", async () => {
   }
 });
 
+test("wp_ajax_test prefers --auth-state over --auth when both are provided", async () => {
+  const fixture = await createFixture();
+
+  try {
+    const handlers = createWpAjaxTestHandlers({
+      repoRoot: fixture.repoRoot,
+      execRunner: async (_file, args): Promise<ExecResult> => {
+        // Should pass --auth-state, not --auth
+        assert.ok(args.includes("--auth-state"), "Expected --auth-state in args");
+        assert.ok(!args.includes("--auth"), "Should not include --auth when --auth-state is provided");
+        assert.ok(args.includes("temp/playwright/.auth/admin.json"), "Expected auth state path in args");
+
+        return {
+          stdout: JSON.stringify({
+            success: true,
+            action: "demo_action",
+            url: "http://demo.local/wp-admin/admin-ajax.php",
+            status_code: 200,
+            response_time_ms: 30,
+            response: { ok: true },
+            headers: {},
+          }),
+          stderr: "",
+          exitCode: 0,
+        };
+      },
+    });
+
+    const result = await handlers.runTest(
+      "http://demo.local",
+      "demo_action",
+      {},
+      "temp/auth.json", // legacy auth — should be ignored
+      "POST",
+      false,
+      false,
+      "temp/playwright/.auth/admin.json", // auth-state — should win
+    );
+
+    assert.equal(result.success, true);
+    assert.equal(result.authProvided, true);
+  } finally {
+    await fixture.cleanup();
+  }
+});
+
+test("wp_ajax_test rejects flag-shaped auth-state path", async () => {
+  const fixture = await createFixture();
+  let invoked = false;
+
+  try {
+    const handlers = createWpAjaxTestHandlers({
+      repoRoot: fixture.repoRoot,
+      execRunner: async (): Promise<ExecResult> => {
+        invoked = true;
+        return { stdout: "", stderr: "", exitCode: 0 };
+      },
+    });
+
+    await assert.rejects(
+      () => handlers.runTest("http://demo.local", "demo_action", {}, undefined, "POST", false, false, "--verbose"),
+      /must not start with '-'/,
+    );
+    assert.equal(invoked, false);
+  } finally {
+    await fixture.cleanup();
+  }
+});
+
 test("wp_ajax_test throws when exit 0 stdout is not valid JSON", async () => {
   const fixture = await createFixture();
 

tools/wp-ajax-test/README.md

@@ -27,20 +27,11 @@ wp-ajax-test --version
 
 ## Quick Start
 
-### 1. Create Auth File
+### 1. Authenticate (via pw-auth — no plaintext passwords)
 
 ```bash
-# In your project
-mkdir -p temp
-cat > temp/auth.json <<'EOF'
-{
-  "username": "admin",
-  "password": "your-password"
-}
-EOF
-
-# Add to .gitignore
-echo "temp/auth.json" >> .gitignore
+# One-time login via pw-auth (creates temp/playwright/.auth/admin.json)
+pw-auth login --site-url https://yoursite.local --wp-cli "local-wp yoursite"
 ```
 
 ### 2. Test an Endpoint
@@ -49,26 +40,42 @@ echo "temp/auth.json" >> .gitignore
 # Basic test
 wp-ajax-test --url https://yoursite.local --action my_ajax_action
 
-# With data payload
+# With pw-auth cookies (recommended)
 wp-ajax-test \
   --url https://yoursite.local \
   --action my_ajax_action \
-  --data '{"user_id": 1, "action_type": "update"}'
+  --auth-state temp/playwright/.auth/admin.json
 
-# With authentication
+# With data payload
 wp-ajax-test \
   --url https://yoursite.local \
   --action my_ajax_action \
-  --auth temp/auth.json
+  --auth-state temp/playwright/.auth/admin.json \
+  --data '{"user_id": 1, "action_type": "update"}'
 
 # JSON output (for AI parsing)
 wp-ajax-test \
   --url https://yoursite.local \
   --action my_ajax_action \
-  --auth temp/auth.json \
+  --auth-state temp/playwright/.auth/admin.json \
   --format json
 ```
 
+### Legacy: plaintext auth file (deprecated)
+
+```bash
+# Still works but not recommended — stores passwords in plaintext
+cat > temp/auth.json <<'EOF'
+{
+  "username": "admin",
+  "password": "your-password"
+}
+EOF
+echo "temp/auth.json" >> .gitignore
+
+wp-ajax-test --url https://yoursite.local --action my_ajax_action --auth temp/auth.json
+```
+
 ---
 
 ## Usage

tools/wp-ajax-test/index.js

@@ -8,6 +8,7 @@
  *   wp-ajax-test --url https://site.local --action my_ajax_action
  *   wp-ajax-test --url https://site.local --action my_ajax_action --data '{"key":"value"}'
  *   wp-ajax-test --url https://site.local --action my_ajax_action --auth temp/auth.json
+ *   wp-ajax-test --url https://site.local --action my_ajax_action --auth-state temp/playwright/.auth/admin.json
  */
 
 const { program } = require('commander');
@@ -39,7 +40,8 @@ program
   .requiredOption('-u, --url <url>', 'WordPress site URL')
   .requiredOption('-a, --action <action>', 'AJAX action name')
   .option('-d, --data <json>', 'JSON data payload', '{}')
-  .option('--auth <file>', 'Auth file path (JSON)', null)
+  .option('--auth <file>', 'Auth file path with username/password (JSON) — prefer --auth-state', null)
+  .option('--auth-state <file>', 'Playwright auth state file from pw-auth (no plaintext passwords)', null)
   .option('-f, --format <format>', 'Output format (human|json)', 'human')
   .option('--admin', 'Send the default authenticated/admin-style request flow', true)
   .option('--nopriv', 'Send an unauthenticated request and skip auth/nonce discovery')
@@ -178,31 +180,44 @@ async function main() {
       throw new Error(`Invalid JSON data: ${e.message}`);
     }
 
-    // Load authentication if provided
+    // Auth: prefer --auth-state (pw-auth cookies) over --auth (plaintext credentials)
     let auth = null;
-    if (options.auth && useAuthenticatedFlow) {
+    let authenticatedViaCookies = false;
+
+    if (options.authState && useAuthenticatedFlow) {
+      // Load pre-authenticated cookies from Playwright auth state
+      const cookieCount = loadAuthState(options.authState, options.url);
+      authenticatedViaCookies = true;
+      if (options.verbose) {
+        console.log(`🔐 Loaded ${cookieCount} cookies from auth state: ${options.authState}`);
+      }
+      if (options.auth) {
+        console.error('⚠️  --auth-state takes precedence over --auth. Ignoring --auth.');
+      }
+    } else if (options.auth && useAuthenticatedFlow) {
+      console.error('⚠️  --auth uses plaintext credentials. Consider pw-auth login + --auth-state instead.');
       auth = await loadAuth(options.auth);
       if (options.verbose) {
         console.log(`Loaded auth from: ${options.auth}`);
       }
     }
 
-    if (options.auth && !useAuthenticatedFlow && options.verbose) {
-      console.log('Ignoring --auth because --nopriv sends the request without authentication');
+    if ((options.auth || options.authState) && !useAuthenticatedFlow && options.verbose) {
+      console.log('Ignoring auth options because --nopriv sends the request without authentication');
     }
 
     if (!useAuthenticatedFlow && options.nonceUrl && options.verbose) {
       console.log('Ignoring --nonce-url because --nopriv skips authenticated nonce discovery');
     }
 
-    // Authenticate if needed
+    // Authenticate with username/password if using legacy --auth (not needed for --auth-state)
     if (auth && auth.username && auth.password) {
       await authenticate(options.url, auth);
     }
 
-    // Get nonce if authenticated
+    // Get nonce if authenticated (works with both --auth-state cookies and --auth login)
     let nonce = null;
-    if (auth) {
+    if (auth || authenticatedViaCookies) {
       nonce = await getNonce(options.url, auth, options.nonceUrl, options.nonceField);
       if (options.verbose && nonce) {
         console.log(`Extracted nonce: ${nonce.substring(0, 10)}...`);
@@ -261,7 +276,7 @@ async function main() {
 }
 
 /**
- * Load authentication from file
+ * Load authentication from file (plaintext username/password)
  */
 async function loadAuth(authFile) {
   try {
@@ -276,6 +291,59 @@ async function loadAuth(authFile) {
   }
 }
 
+/**
+ * Load cookies from a Playwright auth state file (from pw-auth).
+ * Filters cookies by the target site domain and populates the global cookies object.
+ * Returns the number of cookies loaded.
+ */
+function loadAuthState(authStateFile, siteUrl) {
+  const authStatePath = path.resolve(authStateFile);
+  if (!fs.existsSync(authStatePath)) {
+    throw new Error(`Auth state file not found: ${authStatePath}`);
+  }
+
+  let state;
+  try {
+    state = JSON.parse(fs.readFileSync(authStatePath, 'utf8'));
+  } catch (e) {
+    throw new Error(`Failed to parse auth state file: ${e.message}`);
+  }
+
+  if (!state || !Array.isArray(state.cookies)) {
+    throw new Error('Auth state file does not contain a cookies array. Expected Playwright storageState format.');
+  }
+
+  const targetHost = new URL(siteUrl).hostname;
+  const now = Date.now() / 1000;
+  let loaded = 0;
+
+  for (const cookie of state.cookies) {
+    if (!cookie.name || typeof cookie.value !== 'string') continue;
+
+    // Match domain: Playwright stores "site.local" (no leading dot)
+    const cookieDomain = (cookie.domain || '').replace(/^\./, '');
+    if (cookieDomain !== targetHost) continue;
+
+    // Skip expired cookies
+    if (cookie.expires && cookie.expires > 0 && cookie.expires < now) continue;
+
+    cookies[cookie.name] = cookie.value;
+    loaded++;
+  }
+
+  if (loaded === 0) {
+    throw new Error(`No valid cookies found for ${targetHost} in auth state file. Run pw-auth login first.`);
+  }
+
+  // Verify we have a wordpress_logged_in cookie
+  const hasLoggedInCookie = Object.keys(cookies).some(k => k.startsWith('wordpress_logged_in_'));
+  if (!hasLoggedInCookie) {
+    throw new Error(`Auth state has cookies for ${targetHost} but no wordpress_logged_in_* cookie. Session may have expired — run pw-auth login --force.`);
+  }
+
+  return loaded;
+}
+
 /**
  * Authenticate with WordPress
  */
@@ -513,14 +581,17 @@ function handleError(error, format) {
   };
 
   // Add specific suggestions based on error
-  if (error.message.includes('Auth file not found')) {
+  if (error.message.includes('Auth file not found') || error.message.includes('Auth state file not found')) {
     errorObj.error.code = 'AUTH_REQUIRED';
-    errorObj.suggestions.push('Create temp/auth.json with username and password');
-    errorObj.suggestions.push('Use --auth flag to specify auth file location');
+    errorObj.suggestions.push('Run: pw-auth login --site-url <url> --wp-cli "local-wp <site>"');
+    errorObj.suggestions.push('Then: --auth-state temp/playwright/.auth/admin.json');
+  } else if (error.message.includes('No valid cookies found') || error.message.includes('no wordpress_logged_in_')) {
+    errorObj.error.code = 'AUTH_EXPIRED';
+    errorObj.suggestions.push('Run: pw-auth login --site-url <url> --force');
   } else if (error.message.includes('Authentication failed')) {
     errorObj.error.code = 'AUTH_FAILED';
     errorObj.suggestions.push('Check username and password in auth file');
-    errorObj.suggestions.push('Verify WordPress site URL is correct');
+    errorObj.suggestions.push('Consider switching to --auth-state with pw-auth (no plaintext passwords)');
   } else if (error.message.includes('ENOTFOUND') || error.message.includes('ECONNREFUSED')) {
     errorObj.error.code = 'CONNECTION_ERROR';
     errorObj.suggestions.push('Check if WordPress site is running');