@diviops/mcp-server 0.2.14 → 0.2.16

package/README.md

@@ -69,6 +69,8 @@ claude mcp add diviops-mcp -- env \
 | `WP_CLI_CMD` | No | Custom WP-CLI command prefix for containerized environments, e.g. `ddev wp`, `npx wp-env run cli wp`, `docker exec -u www-data devkinsta_fpm wp --path=/www/kinsta/public/sitename` |
 | `LOCAL_SITE_ID` | No | Override auto-detection of Local by Flywheel site ID |
 | `DIVIOPS_WP_CLI_ALLOW` | No | Comma-separated list of extended WP-CLI commands to enable (see [WP-CLI Security](#wp-cli-security)) |
+| `DIVIOPS_WP_CLI_SAFE_FS_ROOT` | No | Absolute path to constrain filesystem-touching commands (`wp export`, `acf export/import`). Defaults to `<WP_PATH>/.diviops-tmp/` in host mode. **Required** in `WP_CLI_CMD` wrapper mode (must be the container-namespace path, since the host path can't be inferred) |
+| `DIVIOPS_WP_CLI_UNSAFE_FS` | No | Set to `1` to disable filesystem flag validation entirely. For trusted single-user local-dev setups where the `--dir` / positional-path safety checks get in the way |
 
 ### Local Development Environments
 
@@ -206,7 +208,18 @@ Only list the specific commands you need. Unknown entries are ignored with a war
 
 > **Note on `acf import`**: included in the default allowlist because it's an idempotent dev-time schema operation (re-creates field groups from JSON). Bulk content imports use `wp import` instead, which is opt-in.
 
-> **Known limitation — filesystem access**: Validation is prefix-based, not flag-aware. Commands that read from or write to the filesystem (`acf export`/`acf import`, `export`, opt-in `import`/`eval-file`) can target any path reachable by the WP-CLI user. For shared or multi-tenant environments, consider wrapping the MCP server with a stricter proxy or running it under an account with limited filesystem permissions. Flag-level validation is a candidate future enhancement.
+### Filesystem flag validation
+
+The three DEFAULT-tier filesystem commands (`wp export`, `acf export <path>`, `acf import <path>`) are second-pass validated against a safe root so wrong-path arguments can't write WXR to the web root or read ACF configs from arbitrary locations.
+
+- **Safe root**: `<WP_PATH>/.diviops-tmp/` by default (auto-created on first use in host mode). Override with `DIVIOPS_WP_CLI_SAFE_FS_ROOT=/absolute/path`. All path arguments must canonicalize under this directory; symlinks are resolved via `realpath` so a planted symlink inside the safe root pointing outside it is caught.
+- **`wp export` must pass `--dir=<path-under-safe-root>`** (or `--stdout`). Without `--dir`, wp-cli writes to the current working directory; on prod that's typically the web root.
+- **`--filename_format=` must be a filename template**, not a path — separators (`/`, `\`) are rejected so a crafted template can't escape `--dir`'s scope.
+- **`acf export/import`'s positional path** must resolve under the safe root.
+- **Wrapper mode (`WP_CLI_CMD`)**: the host-derived safe root doesn't correspond to the wrapper's filesystem (e.g., container paths like `/www/app`), so `DIVIOPS_WP_CLI_SAFE_FS_ROOT` is **required** and must be set to the container-namespace path. FS-sensitive commands are rejected with a clear error if it's missing.
+- **Escape hatch**: `DIVIOPS_WP_CLI_UNSAFE_FS=1` disables validation entirely. Appropriate for trusted single-user local-dev setups that don't want the guard.
+
+**EXTENDED-tier filesystem commands** (`import`, `eval-file`) are not flag-validated here — opt-in via `DIVIOPS_WP_CLI_ALLOW` signals the caller has accepted the path-scope risk. That constraint is a candidate future enhancement if the MCP server ships in multi-tenant contexts.
 
 ## Safety Patterns
 

package/dist/compatibility.d.ts

@@ -2,7 +2,7 @@
  * Version compatibility between MCP server and WP plugin.
  */
 /** Minimum WP plugin version this server requires. */
-export declare const MIN_PLUGIN_VERSION = "1.0.0-beta.31";
+export declare const MIN_PLUGIN_VERSION = "1.0.0-beta.34";
 /**
  * Compare two semver-like version strings (supports pre-release tags).
  *

package/dist/compatibility.js

@@ -2,7 +2,7 @@
  * Version compatibility between MCP server and WP plugin.
  */
 /** Minimum WP plugin version this server requires. */
-export const MIN_PLUGIN_VERSION = '1.0.0-beta.31';
+export const MIN_PLUGIN_VERSION = '1.0.0-beta.34';
 /**
  * Compare two semver-like version strings (supports pre-release tags).
  *

package/dist/index.js

@@ -582,7 +582,7 @@ server.registerTool("diviops_create_page", {
 });
 // ── Preset Tools ────────────────────────────────────────────────────
 server.registerTool("diviops_preset_audit", {
-    description: "Audit all Divi presets (module + group). Each entry reports `block_ref_count` (page-content refs via modulePreset / groupPreset block markup), `group_ref_count` (in-registry chain refs from other presets via attrs.groupPresets), and `referenced` (true if either > 0). Group presets that are chain-referenced also expose `referenced_by_presets` (UUIDs of the presets that wire them in — typically module presets, but type-agnostic). Use this before deleting — orphan-cleanup based only on page refs would silently wipe load-bearing chain-wired group presets (font, border, box-shadow, spacing, button).",
+    description: "Audit all Divi presets (module + group). Each entry reports `block_ref_count` (page-content refs via modulePreset / groupPreset block markup), `group_ref_count` (in-registry chain refs from other presets — module presets via top-level `groupPresets.<slot>.presetId`, group presets via `attrs.groupPreset.<slot>.presetId`), and `referenced` (true if either > 0). Group presets that are chain-referenced also expose `referenced_by_presets` (UUIDs of the presets that wire them in — typically module presets, but type-agnostic). Use this before deleting — orphan-cleanup based only on page refs would silently wipe load-bearing chain-wired group presets (font, border, box-shadow, spacing, button).",
 }, async () => {
     const result = await wp.request("/preset-audit");
     return {
@@ -726,7 +726,7 @@ server.registerTool("diviops_preset_create", {
     };
 });
 server.registerTool("diviops_preset_reassign", {
-    description: 'Reassign a preset UUID across page content. Covers both module-level refs (`attrs.modulePreset[...]`) and attribute-level group-preset refs (`attrs.groupPreset.<slot>.presetId`), plus — for group presets — registry chain refs in other presets\' `attrs.groupPresets.<slot>.presetId`. The `scope` param controls which ref types are walked (default "both", auto-selects based on new_uuid\'s bucket). Cross-bucket swaps (module ↔ group) are rejected. For module-scope swaps, optionally strips inline attrs that duplicate the new preset\'s attrs (otherwise inline wins over preset); slot-scoped inline strip for group scope is not yet implemented and is skipped with an advisory. Defaults to dry-run — set mode="apply" to actually rewrite. Use this to consolidate repeated inline styling into a reusable preset after creating one with diviops_preset_create.',
+    description: 'Reassign a preset UUID across page content. Covers both module-level refs (`attrs.modulePreset[...]`) and attribute-level group-preset refs (`attrs.groupPreset.<slot>.presetId`), plus — for group presets — registry chain refs: module-bucket presets via top-level `groupPresets.<slot>.presetId`, group-bucket presets via `attrs.groupPreset.<slot>.presetId`. The `scope` param controls which ref types are walked (default "both", auto-selects based on new_uuid\'s bucket). Cross-bucket swaps (module ↔ group) are rejected. For module-scope swaps, optionally strips inline attrs that duplicate the new preset\'s attrs (otherwise inline wins over preset); slot-scoped inline strip for group scope is not yet implemented and is skipped with an advisory. Defaults to dry-run — set mode="apply" to actually rewrite. Use this to consolidate repeated inline styling into a reusable preset after creating one with diviops_preset_create.',
     inputSchema: {
         old_uuid: z
             .string()
@@ -752,7 +752,7 @@ server.registerTool("diviops_preset_reassign", {
             .enum(["module", "group", "both"])
             .optional()
             .default("both")
-            .describe('"module" walks `attrs.modulePreset[...]` only. "group" walks `attrs.groupPreset.<slot>.presetId` plus registry chain refs (`attrs.groupPresets.<slot>.presetId` in other presets). "both" (default) auto-selects based on new_uuid\'s bucket — module/group identity is disjoint, so there is one valid walk per swap. An explicit "module" or "group" rejects if new_uuid is in the wrong bucket.'),
+            .describe('"module" walks `attrs.modulePreset[...]` only. "group" walks `attrs.groupPreset.<slot>.presetId` plus registry chain refs (top-level `groupPresets.<slot>.presetId` on module presets, `attrs.groupPreset.<slot>.presetId` on group presets). "both" (default) auto-selects based on new_uuid\'s bucket — module/group identity is disjoint, so there is one valid walk per swap. An explicit "module" or "group" rejects if new_uuid is in the wrong bucket.'),
     },
 }, async ({ old_uuid, new_uuid, page_ids, mode, strip_inline, scope }) => {
     const body = {
@@ -1091,11 +1091,11 @@ server.registerTool("diviops_delete_canvas", {
 });
 // ── WP-CLI ──────────────────────────────────────────────────────────
 server.registerTool("diviops_wp_cli", {
-    description: "Run a WP-CLI command on the WordPress site. Requires WP_PATH env var (LOCAL_SITE_ID auto-detected from Local by Flywheel). Commands validated against a safety allowlist. Default tier covers read ops across options/posts/post-types/taxonomies/users/info, non-destructive writes (post/term create+update, post meta read/write, cache/rewrite/transient flush), ACF schema ops (export/import/list/get field-group), and WXR export. Extended tier (requires DIVIOPS_WP_CLI_ALLOW env var) adds destructive or bulk-modifying ops: option update, post/post meta/term delete, search-replace, import, plugin activate/deactivate, eval-file. Use --format=json for structured output. Full allowlist + tier rationale in the MCP server README.",
+    description: "Run a WP-CLI command on the WordPress site. Requires WP_PATH env var (LOCAL_SITE_ID auto-detected from Local by Flywheel), or WP_CLI_CMD for containerized wrappers. Commands validated against a safety allowlist. Default tier covers read ops across options/posts/post-types/taxonomies/users/info/core/db, non-destructive writes (post/term create+update, post meta read/write, cache/rewrite/transient flush), ACF schema ops (export/import/list/get field-group), and WXR export. Extended tier (requires DIVIOPS_WP_CLI_ALLOW env var) adds destructive or bulk-modifying ops: option update, post/post meta/term delete, search-replace, import, plugin activate/deactivate, eval-file. Filesystem-touching commands (`wp export`, `acf export/import`) are additionally constrained: path arguments must resolve under a safe root (defaults to `<WP_PATH>/.diviops-tmp/`, overridable via DIVIOPS_WP_CLI_SAFE_FS_ROOT, disable via DIVIOPS_WP_CLI_UNSAFE_FS=1); `wp export` requires an explicit `--dir=<path>` (or `--stdout`). In WP_CLI_CMD wrapper mode, DIVIOPS_WP_CLI_SAFE_FS_ROOT is required for FS-sensitive commands. Use --format=json for structured output. Full allowlist + tier rationale + filesystem semantics in the MCP server README.",
     inputSchema: {
         command: z
             .string()
-            .describe('WP-CLI command without the "wp" prefix. E.g. "option get blogname", "post list --format=json", "db query \\"SELECT COUNT(*) FROM wp_posts\\""'),
+            .describe('WP-CLI command without the "wp" prefix. E.g. "option get blogname", "post list --format=json", "export --dir=$DIVIOPS_WP_CLI_SAFE_FS_ROOT --filename_format={site}.{date}.xml"'),
     },
 }, async ({ command }) => {
     if (!wpCli) {

package/dist/wp-cli-fs-validator.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Filesystem flag validation for wp-cli commands that read/write outside
+ * the standard WP data surface (options, posts, meta, etc.).
+ *
+ * The main allowlist (wp-cli.ts) uses prefix matching and accepts arbitrary
+ * flags after the prefix. That's fine for commands like `option get` but
+ * leaves path arguments on FS-touching commands unchecked — `wp export
+ * --dir=/var/www/html/public/` would pass the prefix check and dump a WXR
+ * containing user data + password hashes into a web-reachable folder.
+ *
+ * This module adds a second-pass validator specifically for DEFAULT-tier
+ * FS commands. EXTENDED-tier FS commands (`import`, `eval-file`) are
+ * already opt-in via DIVIOPS_WP_CLI_ALLOW; their validation is tracked
+ * separately (see dev-repo #271 scope discussion).
+ *
+ * Guarantees:
+ *   - All path arguments must resolve under SAFE_FS_ROOT after canonicalization
+ *   - `wp export` requires an explicit --dir= so it can't write to the CWD
+ *   - `--filename=` on `wp export` must be a filename, not a path
+ *   - `.diviops-tmp/` (or the configured override) is auto-created on first use
+ *
+ * Escape hatch: `DIVIOPS_WP_CLI_UNSAFE_FS=1` disables all validation for
+ * trusted single-user local-dev setups.
+ */
+export interface FsValidationResult {
+    allowed: boolean;
+    reason?: string;
+}
+export interface FsValidationOptions {
+    /**
+     * Whether wp-cli is invoked via WP_CLI_CMD wrapper (e.g. `docker exec ... wp`).
+     * In wrapper mode, the host-derived safe root (from WP_PATH / process.cwd)
+     * has no correspondence to the wrapper's filesystem namespace, so the
+     * validator requires an explicit DIVIOPS_WP_CLI_SAFE_FS_ROOT before
+     * accepting FS-sensitive commands.
+     */
+    isWrapper?: boolean;
+}
+/**
+ * Resolve the effective safe filesystem root for this wp-cli instance.
+ * Precedence: DIVIOPS_WP_CLI_SAFE_FS_ROOT env var > <wpPath>/.diviops-tmp/.
+ * Returned path is canonical absolute.
+ */
+export declare function resolveSafeFsRoot(wpPath: string): string;
+/** Whether FS validation is disabled via escape-hatch env var. */
+export declare function fsValidationDisabled(): boolean;
+/**
+ * Idempotently create the safe root so first-invocation FS commands don't
+ * fail with "no such directory" when the caller points at a not-yet-existing
+ * safe path. Silently no-ops on failure — if mkdir fails the subsequent
+ * wp-cli call will surface its own error.
+ */
+export declare function ensureSafeFsRoot(safeRoot: string): void;
+/**
+ * Identify which FS-sensitive command a parsed arg vector represents.
+ * Returns the canonical prefix ("export", "acf export", "acf import") or
+ * null if the args don't match a FS-sensitive command.
+ */
+export declare function matchFsSensitiveCommand(args: string[]): string | null;
+/**
+ * Check whether a user-supplied absolute path resolves under safeRoot.
+ *
+ * Requires absolute input — relative paths return false. This matches the
+ * validator's contract that callers must reject relative paths BEFORE this
+ * function runs, because wp-cli resolves relative args against its own CWD
+ * (process.cwd in host mode, config.wpPath in wrapper mode), NOT against
+ * our safe root. Accepting relative paths here would create a validation-
+ * vs-execution semantic gap: the validator would happily resolve the
+ * relative input against safeRoot and pass, but wp-cli would execute it
+ * against a different base and write outside the intended scope.
+ *
+ * Canonicalization uses `fs.realpathSync` with a walk-up fallback (see
+ * `canonicalize`). Realpath follows symlinks, so an attacker-planted
+ * symlink inside SAFE_FS_ROOT pointing outside it is caught.
+ *
+ * The trailing-separator check (`startsWith(rootCanonical + sep)`) prevents
+ * prefix-match tricks like /safe-root-evil passing because /safe-root is
+ * the allowed prefix.
+ */
+export declare function isPathUnderSafeRoot(userPath: string, safeRoot: string): boolean;
+/**
+ * Extract `--dir=`, `--filename_format=`, and `--stdout` from a parsed
+ * arg vector. Supports both `--foo=bar` and `--foo bar` forms.
+ *
+ * wp-cli's `wp export` uses `--filename_format=<template>` for the output
+ * filename template (containing `{site}`, `{date}`, `{n}` placeholders) —
+ * NOT `--filename` (which isn't a real flag). An earlier version of this
+ * validator checked `--filename`, which wp-cli silently ignores, so an
+ * `--filename_format=../../evil` attempt would have passed validation
+ * while wp-cli actually used the malicious template. Fix: check the real
+ * flag name.
+ *
+ * `--stdout` writes WXR to stdout instead of a file — no FS write, so
+ * callers using it don't need `--dir`. Returned as a bool flag so the
+ * validator can waive the `--dir` requirement.
+ */
+export declare function extractExportFlags(args: string[]): {
+    dir: string | null;
+    filenameFormat: string | null;
+    stdout: boolean;
+};
+/**
+ * Extract the first positional (non-flag) argument after a command prefix.
+ * Used for `acf export <path>` / `acf import <path>` where the path is a
+ * positional arg, not a flag value.
+ */
+export declare function extractPositionalAfterPrefix(args: string[], prefixLength: number): string | null;
+/**
+ * Validate a parsed wp-cli arg vector against the FS safe-root rules.
+ * Returns `{ allowed: true }` for any command not in FS_SENSITIVE_COMMANDS
+ * — non-FS commands are out of scope for this validator.
+ *
+ * Caller should invoke only after the main allowlist has accepted the
+ * command; this validator assumes the command itself is already authorized
+ * and only checks path arguments.
+ */
+export declare function validateFilesystemFlags(args: string[], safeRoot: string, opts?: FsValidationOptions): FsValidationResult;

package/dist/wp-cli-fs-validator.js

@@ -0,0 +1,337 @@
+/**
+ * Filesystem flag validation for wp-cli commands that read/write outside
+ * the standard WP data surface (options, posts, meta, etc.).
+ *
+ * The main allowlist (wp-cli.ts) uses prefix matching and accepts arbitrary
+ * flags after the prefix. That's fine for commands like `option get` but
+ * leaves path arguments on FS-touching commands unchecked — `wp export
+ * --dir=/var/www/html/public/` would pass the prefix check and dump a WXR
+ * containing user data + password hashes into a web-reachable folder.
+ *
+ * This module adds a second-pass validator specifically for DEFAULT-tier
+ * FS commands. EXTENDED-tier FS commands (`import`, `eval-file`) are
+ * already opt-in via DIVIOPS_WP_CLI_ALLOW; their validation is tracked
+ * separately (see dev-repo #271 scope discussion).
+ *
+ * Guarantees:
+ *   - All path arguments must resolve under SAFE_FS_ROOT after canonicalization
+ *   - `wp export` requires an explicit --dir= so it can't write to the CWD
+ *   - `--filename=` on `wp export` must be a filename, not a path
+ *   - `.diviops-tmp/` (or the configured override) is auto-created on first use
+ *
+ * Escape hatch: `DIVIOPS_WP_CLI_UNSAFE_FS=1` disables all validation for
+ * trusted single-user local-dev setups.
+ */
+import { isAbsolute, resolve, sep, dirname, basename, join } from 'path';
+import { mkdirSync, realpathSync } from 'fs';
+const SAFE_FS_ROOT_SUBDIR = '.diviops-tmp';
+const UNSAFE_FS_ENV = 'DIVIOPS_WP_CLI_UNSAFE_FS';
+const SAFE_FS_ROOT_OVERRIDE_ENV = 'DIVIOPS_WP_CLI_SAFE_FS_ROOT';
+/**
+ * DEFAULT-tier commands whose arguments can write/read to arbitrary paths.
+ * EXTENDED-tier FS commands (`import`, `eval-file`) are opt-in and not
+ * validated here — opting in implies accepting the path-scope risk.
+ */
+const FS_SENSITIVE_COMMANDS = [
+    'export',
+    'acf export',
+    'acf import',
+];
+/**
+ * Resolve the effective safe filesystem root for this wp-cli instance.
+ * Precedence: DIVIOPS_WP_CLI_SAFE_FS_ROOT env var > <wpPath>/.diviops-tmp/.
+ * Returned path is canonical absolute.
+ */
+export function resolveSafeFsRoot(wpPath) {
+    const override = process.env[SAFE_FS_ROOT_OVERRIDE_ENV]?.trim();
+    if (override)
+        return resolve(override);
+    return resolve(wpPath, SAFE_FS_ROOT_SUBDIR);
+}
+/** Whether FS validation is disabled via escape-hatch env var. */
+export function fsValidationDisabled() {
+    const v = process.env[UNSAFE_FS_ENV]?.trim();
+    return v === '1' || v?.toLowerCase() === 'true';
+}
+/**
+ * Idempotently create the safe root so first-invocation FS commands don't
+ * fail with "no such directory" when the caller points at a not-yet-existing
+ * safe path. Silently no-ops on failure — if mkdir fails the subsequent
+ * wp-cli call will surface its own error.
+ */
+export function ensureSafeFsRoot(safeRoot) {
+    try {
+        mkdirSync(safeRoot, { recursive: true });
+    }
+    catch {
+        // Ignore — downstream wp-cli will report a clearer error if the dir
+        // genuinely isn't usable (permissions, etc.).
+    }
+}
+/**
+ * Identify which FS-sensitive command a parsed arg vector represents.
+ * Returns the canonical prefix ("export", "acf export", "acf import") or
+ * null if the args don't match a FS-sensitive command.
+ */
+export function matchFsSensitiveCommand(args) {
+    if (args.length === 0)
+        return null;
+    const twoWord = args.slice(0, 2).join(' ');
+    if (FS_SENSITIVE_COMMANDS.includes(twoWord))
+        return twoWord;
+    const oneWord = args[0];
+    if (FS_SENSITIVE_COMMANDS.includes(oneWord))
+        return oneWord;
+    return null;
+}
+/**
+ * Resolve a filesystem path to its canonical form including symlink
+ * resolution. Handles non-existent paths (e.g. `wp export --dir=<new>`)
+ * by walking up to the deepest existing ancestor, realpath'ing that, and
+ * preserving the non-existing tail.
+ *
+ * Why the walk-up matters: a naive `realpathSync → catch → path.resolve()`
+ * fallback produces asymmetric canonicalization. If the user path doesn't
+ * exist but the safe root DOES exist and contains a symlink in its ancestry
+ * (e.g. macOS `/tmp` → `/private/tmp`), the fallback keeps the un-resolved
+ * `/tmp/...` form while the root canonicalizes to `/private/tmp/...`, so
+ * the `startsWith` check fails for legitimate non-existing paths inside
+ * the safe root. Walking up ensures the existing portion of both paths
+ * goes through the same symlink resolution.
+ *
+ * Also closes the original security case: realpath on an existing symlink
+ * inside SAFE_FS_ROOT returns the symlink's true target, so
+ * `safe-root/escape-hatch → /var/www/evil` is caught by the `startsWith`
+ * check because the canonical path is `/var/www/evil`, not under safe root.
+ *
+ * Terminates when `dirname` stops changing (root reached); falls back to
+ * `path.resolve` in that edge case.
+ */
+function canonicalize(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        const abs = resolve(p);
+        const parent = dirname(abs);
+        if (parent === abs)
+            return abs;
+        return join(canonicalize(parent), basename(abs));
+    }
+}
+/**
+ * Check whether a user-supplied absolute path resolves under safeRoot.
+ *
+ * Requires absolute input — relative paths return false. This matches the
+ * validator's contract that callers must reject relative paths BEFORE this
+ * function runs, because wp-cli resolves relative args against its own CWD
+ * (process.cwd in host mode, config.wpPath in wrapper mode), NOT against
+ * our safe root. Accepting relative paths here would create a validation-
+ * vs-execution semantic gap: the validator would happily resolve the
+ * relative input against safeRoot and pass, but wp-cli would execute it
+ * against a different base and write outside the intended scope.
+ *
+ * Canonicalization uses `fs.realpathSync` with a walk-up fallback (see
+ * `canonicalize`). Realpath follows symlinks, so an attacker-planted
+ * symlink inside SAFE_FS_ROOT pointing outside it is caught.
+ *
+ * The trailing-separator check (`startsWith(rootCanonical + sep)`) prevents
+ * prefix-match tricks like /safe-root-evil passing because /safe-root is
+ * the allowed prefix.
+ */
+export function isPathUnderSafeRoot(userPath, safeRoot) {
+    if (!userPath)
+        return false;
+    if (!isAbsolute(userPath))
+        return false;
+    const canonical = canonicalize(userPath);
+    const rootCanonical = canonicalize(safeRoot);
+    return canonical === rootCanonical || canonical.startsWith(rootCanonical + sep);
+}
+/**
+ * Reject a user-supplied path argument if it's relative. wp-cli resolves
+ * relative FS-command args against its own CWD (process.cwd in host mode,
+ * config.wpPath in wrapper mode) — neither of which is our safe root.
+ * Accepting relative input at the validator level would silently bypass
+ * the safe-root guarantee on execution.
+ *
+ * Returns a FsValidationResult rejection when relative, or null when absolute.
+ * Callers should short-circuit on a non-null return.
+ */
+function rejectIfRelative(userPath, label, safeRootCanonical) {
+    if (isAbsolute(userPath))
+        return null;
+    return {
+        allowed: false,
+        reason: `${label} "${userPath}" is a relative path. FS-sensitive commands require ` +
+            `absolute paths so the validator's safe-root check matches wp-cli's execution ` +
+            `semantics (wp-cli resolves relative args against the process CWD, not ` +
+            `against the validator's safe root). Use an absolute path under ` +
+            `${safeRootCanonical}, or set ${UNSAFE_FS_ENV}=1 to disable validation ` +
+            `entirely for trusted setups.`,
+    };
+}
+/**
+ * Extract `--dir=`, `--filename_format=`, and `--stdout` from a parsed
+ * arg vector. Supports both `--foo=bar` and `--foo bar` forms.
+ *
+ * wp-cli's `wp export` uses `--filename_format=<template>` for the output
+ * filename template (containing `{site}`, `{date}`, `{n}` placeholders) —
+ * NOT `--filename` (which isn't a real flag). An earlier version of this
+ * validator checked `--filename`, which wp-cli silently ignores, so an
+ * `--filename_format=../../evil` attempt would have passed validation
+ * while wp-cli actually used the malicious template. Fix: check the real
+ * flag name.
+ *
+ * `--stdout` writes WXR to stdout instead of a file — no FS write, so
+ * callers using it don't need `--dir`. Returned as a bool flag so the
+ * validator can waive the `--dir` requirement.
+ */
+export function extractExportFlags(args) {
+    let dir = null;
+    let filenameFormat = null;
+    let stdout = false;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a.startsWith('--dir=')) {
+            dir = a.slice('--dir='.length);
+        }
+        else if (a === '--dir' && i + 1 < args.length) {
+            dir = args[i + 1];
+            i++;
+        }
+        else if (a.startsWith('--filename_format=')) {
+            filenameFormat = a.slice('--filename_format='.length);
+        }
+        else if (a === '--filename_format' && i + 1 < args.length) {
+            filenameFormat = args[i + 1];
+            i++;
+        }
+        else if (a === '--stdout') {
+            stdout = true;
+        }
+    }
+    return { dir, filenameFormat, stdout };
+}
+/**
+ * Extract the first positional (non-flag) argument after a command prefix.
+ * Used for `acf export <path>` / `acf import <path>` where the path is a
+ * positional arg, not a flag value.
+ */
+export function extractPositionalAfterPrefix(args, prefixLength) {
+    for (let i = prefixLength; i < args.length; i++) {
+        const a = args[i];
+        if (a.startsWith('--'))
+            continue;
+        return a;
+    }
+    return null;
+}
+/**
+ * Validate a parsed wp-cli arg vector against the FS safe-root rules.
+ * Returns `{ allowed: true }` for any command not in FS_SENSITIVE_COMMANDS
+ * — non-FS commands are out of scope for this validator.
+ *
+ * Caller should invoke only after the main allowlist has accepted the
+ * command; this validator assumes the command itself is already authorized
+ * and only checks path arguments.
+ */
+export function validateFilesystemFlags(args, safeRoot, opts = {}) {
+    const cmd = matchFsSensitiveCommand(args);
+    if (!cmd)
+        return { allowed: true };
+    // Wrapper-mode gate: when wp-cli runs inside a container/wrapper (WP_CLI_CMD),
+    // the host path we derived for safeRoot has no correspondence to the
+    // wrapper's filesystem namespace. Evaluating user-supplied container paths
+    // against a host path would either (a) reject legitimate wrapper paths or
+    // (b) suggest host-only safe paths the wrapper can't reach. Require the
+    // caller to set DIVIOPS_WP_CLI_SAFE_FS_ROOT explicitly to the correct
+    // container-namespace path before we'll validate FS-sensitive commands.
+    const hasExplicitSafeRoot = !!process.env[SAFE_FS_ROOT_OVERRIDE_ENV]?.trim();
+    if (opts.isWrapper && !hasExplicitSafeRoot) {
+        return {
+            allowed: false,
+            reason: `FS-sensitive command "${cmd}" runs through a WP_CLI_CMD wrapper, but ` +
+                `${SAFE_FS_ROOT_OVERRIDE_ENV} is not set. Host-derived safe roots don't ` +
+                `correspond to the wrapper's filesystem namespace (e.g. container paths ` +
+                `like /www/app). Set ${SAFE_FS_ROOT_OVERRIDE_ENV}=<container-namespace ` +
+                `path> to enable validation, or ${UNSAFE_FS_ENV}=1 to disable validation ` +
+                `entirely for trusted setups.`,
+        };
+    }
+    const safeRootCanonical = resolve(safeRoot);
+    if (cmd === 'export') {
+        const { dir, filenameFormat, stdout } = extractExportFlags(args);
+        // --stdout writes WXR to the response stream instead of the filesystem.
+        // No file is created, so --dir is irrelevant. Still validate
+        // --filename_format shape in case it's set (defensive — wp-cli ignores
+        // it under --stdout, but an attacker-supplied value shouldn't influence
+        // any future path-using code path).
+        if (!stdout) {
+            // Require explicit --dir. Without it, wp-cli writes to the current
+            // working directory, which on prod sites is typically the web root —
+            // our whole reason for existing.
+            if (!dir) {
+                return {
+                    allowed: false,
+                    reason: `wp export requires an explicit --dir=<path> (or --stdout) when filesystem ` +
+                        `validation is enabled. Without --dir, wp-cli writes WXR files to the current ` +
+                        `working directory — on prod sites that's the web root, which would expose ` +
+                        `exported data publicly. Pass --dir=${safeRootCanonical} (or any path under ` +
+                        `it), use --stdout for in-memory transfer, or set ${UNSAFE_FS_ENV}=1 to ` +
+                        `disable validation for trusted setups.`,
+                };
+            }
+            // Reject relative --dir — wp-cli would resolve it against process.cwd,
+            // not our safe root, defeating the validation. See rejectIfRelative.
+            const rel = rejectIfRelative(dir, 'wp export --dir', safeRootCanonical);
+            if (rel)
+                return rel;
+            if (!isPathUnderSafeRoot(dir, safeRootCanonical)) {
+                return {
+                    allowed: false,
+                    reason: `wp export --dir="${dir}" resolves outside the safe filesystem root ` +
+                        `"${safeRootCanonical}". Use a path under the safe root, or set ` +
+                        `${UNSAFE_FS_ENV}=1 to disable validation.`,
+                };
+            }
+        }
+        // --filename_format is a filename template, not a path. wp-cli uses it
+        // to format files produced inside --dir (and contains placeholders like
+        // {site}, {date}, {n}). Reject path separators so a crafted
+        // --filename_format=../../etc/passwd can't escape --dir's scope.
+        if (filenameFormat !== null && (filenameFormat.includes('/') || filenameFormat.includes('\\'))) {
+            return {
+                allowed: false,
+                reason: `wp export --filename_format="${filenameFormat}" contains path separators. ` +
+                    `--filename_format must be a filename template (e.g. "{site}.{date}.{n}.xml"), ` +
+                    `not a path. Use --dir to set the output directory.`,
+            };
+        }
+        return { allowed: true };
+    }
+    if (cmd === 'acf export' || cmd === 'acf import') {
+        const userPath = extractPositionalAfterPrefix(args, 2);
+        if (!userPath) {
+            // Missing positional — let wp-cli surface its own usage error rather
+            // than returning an allowlist rejection that obscures the real issue.
+            return { allowed: true };
+        }
+        // Reject relative positional path — same reason as --dir above. Without
+        // this gate, `acf export relative/file.json` would resolve against
+        // process.cwd at execution time and escape the safe-root scope.
+        const rel = rejectIfRelative(userPath, cmd, safeRootCanonical);
+        if (rel)
+            return rel;
+        if (!isPathUnderSafeRoot(userPath, safeRootCanonical)) {
+            return {
+                allowed: false,
+                reason: `${cmd} "${userPath}" resolves outside the safe filesystem root ` +
+                    `"${safeRootCanonical}". Use a path under the safe root, or set ` +
+                    `${UNSAFE_FS_ENV}=1 to disable validation.`,
+            };
+        }
+        return { allowed: true };
+    }
+    return { allowed: true };
+}

package/dist/wp-cli.js

@@ -9,6 +9,7 @@ import { execFile } from 'child_process';
 import { readdirSync, readFileSync, existsSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
+import { resolveSafeFsRoot, fsValidationDisabled, ensureSafeFsRoot, matchFsSensitiveCommand, validateFilesystemFlags, } from './wp-cli-fs-validator.js';
 /**
  * Default WP-CLI commands — safe for public distribution.
  * Read-only commands + non-destructive writes needed for core MCP functionality.
@@ -321,6 +322,30 @@ export function createWpCli(config) {
             if (!check.allowed) {
                 return { success: false, output: '', error: check.reason };
             }
+            // Second-pass FS validation for commands whose flags/args can read/write
+            // arbitrary paths. Scoped to DEFAULT-tier FS commands only — EXTENDED
+            // (`import`, `eval-file`) are opt-in via DIVIOPS_WP_CLI_ALLOW, so opting
+            // in signals the caller accepts path-scope risk. Skip entirely when the
+            // user explicitly disables via DIVIOPS_WP_CLI_UNSAFE_FS=1.
+            //
+            // Wrapper mode (WP_CLI_CMD set) is gated separately inside
+            // validateFilesystemFlags — host-derived safe roots don't correspond to
+            // the wrapper's filesystem namespace, so the validator requires an
+            // explicit DIVIOPS_WP_CLI_SAFE_FS_ROOT there. We also skip the host-side
+            // mkdir in wrapper mode since the safe root is either container-scoped
+            // (user-managed) or unset (validator rejects).
+            if (!fsValidationDisabled() && matchFsSensitiveCommand(args)) {
+                const safeRoot = resolveSafeFsRoot(config.wpPath);
+                if (!customWpCliCmd) {
+                    ensureSafeFsRoot(safeRoot);
+                }
+                const fsCheck = validateFilesystemFlags(args, safeRoot, {
+                    isWrapper: !!customWpCliCmd,
+                });
+                if (!fsCheck.allowed) {
+                    return { success: false, output: '', error: fsCheck.reason };
+                }
+            }
             const fullArgs = customWpCliCmd
                 ? [...prefixArgs, ...args, '--no-color']
                 : [...args, `--path=${config.wpPath}`, '--no-color'];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diviops/mcp-server",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "description": "MCP server exposing Divi 5 Visual Builder as tools for Claude",
   "type": "module",
   "main": "dist/index.js",