Greptile Summary

This PR fixes a critical bug where plugin webhook POST endpoints were rejected with HTTP 405 when Control UI is root-mounted (the default configuration).

Key changes:

• Moved HTTP method check to after path-based routing logic
• Root-mounted Control UI: non-GET/HEAD requests to non-UI paths now pass through to plugin handlers instead of returning 405
• basePath-mounted Control UI: behavior preserved - still returns 405 for non-GET/HEAD requests under the basePath
• All GET/HEAD behavior unchanged, security checks preserved

Impact:

• Plugin webhooks like BlueBubbles (/bluebubbles-webhook) now work correctly with default Control UI configuration
• Fixes silently broken webhook integrations that were intercepted before reaching plugin handlers

Test coverage:

• Added 3 comprehensive tests covering root-mounted passthrough, basePath 405 behavior, and basePath exclusions
• All 17 existing tests pass, confirming no regression in GET/HEAD behavior or /api//plugins exclusions

Confidence Score: 5/5

• This PR is safe to merge with minimal risk - it fixes a critical bug with well-tested logic changes
• The implementation is sound with proper separation of concerns between root-mounted and basePath-mounted Control UI. The method check relocation is logical and preserves all existing behavior while enabling the pass-through needed for plugin webhooks. Comprehensive test coverage validates the three critical scenarios, and the PR description demonstrates thorough testing and understanding of edge cases.
• No files require special attention

_{Last reviewed commit: dc8fb8b}

🔒 Aisle Security Analysis

We found 2 potential security issue(s) in this PR:

1. 🟡 Control UI basePath check can be bypassed via URL-encoded slashes, allowing plugin route handling under the UI mount

Description

handleControlUiHttpRequest decides whether a request is “under” the configured Control UI basePath using a raw string prefix check on url.pathname (WHATWG URL):

• url.pathname preserves percent-encoded characters like %2F (encoded slash).
• The code only treats requests as under basePath when pathname === basePath or pathname.startsWith(${basePath}/).
• Therefore, requests such as GET /openclaw%2Fsecret are treated as outside the Control UI base path and fall through to later handlers.

However, the plugin HTTP route matcher does canonicalize and repeatedly decodeURIComponent() path variants (including decoding %2F into /) before matching routes:

• findRegisteredPluginHttpRoute() canonicalizes the request path via canonicalizePathVariant().
• canonicalizePathVariant() uses repeated decodeURIComponent() passes.

This mismatch enables route confusion: a request that Control UI treats as outside basePath may be treated by plugin routing as inside that prefix once decoded/canonicalized. That undermines the intended exclusivity of the Control UI mount (and the new “always Control UI traffic under basePath” method guard), and can allow plugins to respond on basePath-equivalent URLs (e.g., bypassing the Control UI 405 behavior for non-GET/HEAD on paths that canonicalize into the basePath).

Vulnerable code:

if (basePath) {
  if (!pathname.startsWith(`${basePath}/`) && pathname !== basePath) {
    return false;
  }
  ​// ... 405 for non-GET/HEAD ...
}

Relevant downstream canonicalization (for context):

• src/gateway/server/plugins-http.ts uses canonicalizePathVariant(pathname) for route matching.
• src/gateway/security-path.ts performs repeated decodeURIComponent() passes when canonicalizing.

Recommendation

Make basePath inclusion checks resilient to encoded path separators so Control UI and plugin routing cannot disagree.

A minimal, fail-closed mitigation (mirroring prefixMatch() in security-path.ts) is to also treat basePath followed by a percent-escape as “under basePath”:

​// Treat /openclaw%2F... as under /openclaw to avoid routing confusion.
const underBasePath =
  pathname === basePath ||
  pathname.startsWith(`${basePath}/`) ||
  pathname.startsWith(`${basePath}%`);

if (!underBasePath) return false;

Alternatively (more robust), reuse the same canonicalization approach used for plugin security checks and evaluate basePath membership across canonicalized candidates, failing closed on malformed/overly-deep decoding.

This ensures paths like /openclaw%2Fsecret cannot bypass Control UI ownership of the configured mount and cannot be reinterpreted differently by downstream routing.

2. 🔵 Open redirect via scheme-relative Control UI basePath in 302 Location header

Description

The Control UI base-path redirect can become an open redirect if gateway.controlUi.basePath is configured as a scheme-relative value such as //evil.example.

• handleControlUiHttpRequest issues a 302 when pathname === basePath and sets Location to ${basePath}/${url.search} ([control-ui.ts:314-319]).
• basePath is derived from configuration and normalized by normalizeControlUiBasePath, which does not reject values starting with // ([control-ui-shared.ts:9-26]).
• Browsers interpret Location: //evil.example/ as a scheme-relative absolute URL, redirecting the user off-site.

Vulnerable code:

res.statusCode = 302;
res.setHeader("Location", `${basePath}/${url.search}`);

Impact:

• If an operator accidentally/maliciously configures basePath as //evil.example, an attacker can send a victim to http(s)://<gateway-host>//evil.example and the gateway will redirect the victim to http(s)://evil.example/.

Recommendation

Reject scheme-relative (and other non-path) base paths during normalization/config validation.

For example:

export function normalizeControlUiBasePath(basePath?: string): string {
  if (!basePath) return "";
  let normalized = basePath.trim();
  if (!normalized) return "";
  if (!normalized.startsWith("/")) normalized = `/${normalized}`;
  if (normalized === "/") return "";
  if (normalized.endsWith("/")) normalized = normalized.slice(0, -1);

  ​// Reject scheme-relative and other ambiguous paths
  if (normalized.startsWith("//")) {
    throw new Error("gateway.controlUi.basePath must not start with '//' (scheme-relative URL)");
  }
  return normalized;
}

This ensures Location is always a relative redirect within the same origin.

Analyzed PR: #31349 at commit 0abd3cd

_{Last updated on: 2026-03-02T16:33:31Z}

Landed via temp rebase onto main.

• Gate: pnpm build; pnpm test src/gateway/control-ui.http.test.ts src/gateway/server.plugin-http-auth.test.ts
• Land commit: 0abd3cd
• Merge commit: c4711a9

Thanks @Sid-Qin!