fix(gateway): narrow plugin route runtime scopes by vincentkoc · Pull Request #58167 · openclaw/openclaw

vincentkoc · 2026-03-31T06:38:56Z

Summary

Problem: plugin-auth HTTP routes were running with write-capable runtime client scopes.
Why it matters: plugin-owned webhook handlers should not inherit write-capable runtime access unless the route itself requires gateway auth.
What changed: plugin route runtime clients now map auth: "plugin" routes to read scope, keep auth: "gateway" routes on write scope, and add regression coverage that proves write-helper access fails closed on plugin-auth routes.
What did NOT change (scope boundary): route matching, route admission, and gateway-auth enforcement behavior outside runtime scope selection.

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Closes #
Related #
This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

Root cause: plugin HTTP route dispatch minted a synthetic runtime client with write scope for every matched route, regardless of whether the route used plugin auth or gateway auth.
Missing detection / guardrail: there was no regression test that exercised write-helper gating through plugin route runtime scope selection.
Prior context (git blame, prior PR, issue, or refactor if known): the current branch preserves the existing route-scope fix work and adds a tighter regression guardrail on top.
Why this regressed now: runtime scope selection was too coarse and treated all plugin routes as write-capable internal callers.
If unknown, what was ruled out: N/A.

Regression Test Plan (if applicable)

Coverage level that should have caught this:
- Unit test
- Seam / integration test
- End-to-end test
- Existing coverage already sufficient
Target test or file: src/gateway/server/plugins-http.runtime-scopes.test.ts
Scenario the test should lock in: plugin-auth routes fail closed when a write-scoped runtime helper is checked, while gateway-auth routes keep write-capable runtime access.
Why this is the smallest reliable guardrail: it exercises the actual plugin route wrapper plus the shared gateway method scope authorizer without pulling in heavier gateway bootstrap mocks.
Existing test that already covers this (if any): none.
If no new test is added, why not: N/A.

User-visible / Behavior Changes

Plugin-owned HTTP routes that use plugin auth no longer get write-capable runtime helper access by default. Gateway-authenticated plugin routes keep the existing write-capable runtime behavior.

Diagram (if applicable)

Before:
[plugin-auth route] -> [synthetic write-scoped runtime client] -> [write helper allowed]

After:
[plugin-auth route] -> [synthetic read-scoped runtime client] -> [write helper denied]
[gateway-auth route] -> [synthetic write-scoped runtime client] -> [write helper allowed]

Security Impact (required)

New permissions/capabilities? (No)
Secrets/tokens handling changed? (No)
New/changed network calls? (No)
Command/tool execution surface changed? (No)
Data access scope changed? (Yes)
If any Yes, explain risk + mitigation: plugin-auth HTTP routes now run with the narrower read scope, while gateway-auth routes keep write scope. Coverage locks the intended split in place.

Repro + Verification

Environment

OS: macOS
Runtime/container: local worktree
Model/provider: N/A
Integration/channel (if any): gateway plugin HTTP routes
Relevant config (redacted): N/A

Steps

Register a plugin-auth HTTP route whose handler checks write-helper eligibility.
Dispatch that route without gateway auth.
Dispatch an equivalent gateway-auth route with gateway auth satisfied.

Expected

Plugin-auth route fails closed on write-helper access.
Gateway-auth route retains write-helper access.

Actual

Matches expected in the added regression coverage.

Evidence

Failing test/log before + passing after
Trace/log snippets
Screenshot/recording
Perf numbers (if relevant)

Human Verification (required)

Verified scenarios: reviewed the preserved fix, added a focused regression test for plugin-auth vs gateway-auth runtime scope behavior, attempted targeted tests, pnpm check, and pnpm build on the rebased tree.
Edge cases checked: plugin-auth routes still fail closed; gateway-auth routes keep write-helper eligibility.
What you did not verify: full local completion of the targeted Vitest lane, pnpm check, and pnpm build was blocked by host-level process contention during this session.

Review Conversations

I replied to or resolved every bot review conversation I addressed in this PR.
I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

Backward compatible? (Yes)
Config/env changes? (No)
Migration needed? (No)
If yes, exact upgrade steps:

Risks and Mitigations

Risk: plugin-auth routes that were implicitly relying on write-capable runtime helpers will now fail closed.
- Mitigation: gateway-auth routes keep write scope, and the changelog entry plus regression coverage document the intended split.

AI-assisted: yes. Testing: targeted regression coverage added; local verification attempted as noted above.

greptile-apps · 2026-03-31T06:41:51Z

Greptile Summary

This PR narrows the runtime OAuth scope for plugin-owned HTTP routes from operator.write to operator.read when those routes use auth: \"plugin\", keeping operator.write only for routes that require gateway authentication. The one-line change in createPluginRouteRuntimeClient is correct and minimal.

Key changes:

plugins-http.ts: createPluginRouteRuntimeClient now accepts requiresGatewayAuth and selects READ_SCOPE vs WRITE_SCOPE accordingly.
plugins-http.runtime-scopes.test.ts (new): Behavioral regression test that verifies write-helper access throws inside plugin-auth routes and succeeds inside gateway-auth routes.
plugins-http.test.ts: Replaced a heavyweight integration mock (subagent runtime + gateway request mocks) with a lightweight scope-capture helper that directly asserts the assigned scopes — cleaner and more stable.
CHANGELOG.md: Entry added in the correct section.

Confidence Score: 5/5

Safe to merge; the core change is a single-line scope selection with correct logic and two complementary test suites that lock in the intended behavior.

All remaining findings are P2. The logic change is minimal and correct: requiresGatewayAuth is already computed before the runtime client is created and correctly reflects whether any matched route requires gateway auth. The test rewrite removes fragile mocks and asserts directly on observable state. No P0 or P1 issues found.

No files require special attention.

Important Files Changed

Filename	Overview
src/gateway/server/plugins-http.ts	Core change: createPluginRouteRuntimeClient now accepts requiresGatewayAuth and maps plugin-auth routes to READ_SCOPE while gateway-auth routes keep WRITE_SCOPE. Logic is correct and minimal.
src/gateway/server/plugins-http.runtime-scopes.test.ts	New regression test file. Correctly verifies the behavioral contract: plugin-auth routes fail closed when write-helper access is attempted, and gateway-auth routes retain write-helper access.
src/gateway/server/plugins-http.test.ts	Heavy mock infrastructure replaced with a lightweight scope-capture helper. Tests now assert on actual scope values rather than downstream permission failure side-effects.
CHANGELOG.md	Changelog entry added to the correct section, accurately describing the scope narrowing change.

Prompt To Fix All With AI

This is a comment left during a code review.
Path: src/gateway/server/plugins-http.runtime-scopes.test.ts
Line: 48

Comment:
**Partial log stub bypasses type safety**

`{ warn: vi.fn() }` is cast with `as` to the full `SubsystemLogger` type, so any invocation of a non-stubbed method (e.g. `info`, `error`, `debug`) would throw at runtime and produce a confusing test failure rather than a clear type error. `plugins-http.test.ts` avoids this by using `as unknown as PluginHandlerLog`; a consistent pattern here would be safer.

```suggestion
    const log = { warn: vi.fn(), info: vi.fn(), error: vi.fn(), debug: vi.fn() } as Parameters<typeof createGatewayPluginRequestHandler>[0]["log"];
```

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "test(gateway): cover plugin route runtim..." | Re-trigger Greptile}

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 67b6068b40

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-03-31T15:26:30Z

+function createPluginRouteRuntimeClient(
+  requiresGatewayAuth: boolean,
+): GatewayRequestOptions["client"] {
+  const scopes = requiresGatewayAuth ? [WRITE_SCOPE] : [];


Grant read scope for plugin-auth runtime clients

Using an empty scope array for non-gateway plugin routes removes all operator privileges, not just write access. In this codebase, read methods still require operator.read (see authorizeOperatorScopesForMethod), so plugin-auth webhook handlers that call read-only runtime helpers (for example, subagent paths that dispatch sessions.get) will now fail with missing scope: operator.read and return 500s. This change narrows more than intended; plugin-auth routes need a read scope rather than no scope.

Useful? React with 👍 / 👎.

* wip(gateway): preserve plugin route scope progress * test(gateway): cover plugin route runtime scopes * test(gateway): finish plugin route scope rebase * fix(gateway): drop scopes from plugin-auth routes

openclaw-barnacle Bot added gateway Gateway runtime size: M maintainer Maintainer-authored PR labels Mar 31, 2026

vincentkoc self-assigned this Mar 31, 2026

greptile-apps Bot reviewed Mar 31, 2026

View reviewed changes

Comment thread src/gateway/server/plugins-http.runtime-scopes.test.ts Outdated

vincentkoc added 3 commits March 31, 2026 17:37

wip(gateway): preserve plugin route scope progress

d6d988e

test(gateway): cover plugin route runtime scopes

c95c907

test(gateway): finish plugin route scope rebase

863ef68

vincentkoc force-pushed the triage-mhgq-plugin-route-scope branch from 363cd87 to 863ef68 Compare March 31, 2026 08:45

vincentkoc added 3 commits March 31, 2026 21:43

Merge branch 'main' into triage-mhgq-plugin-route-scope

b5cdabd

Merge branch 'main' into triage-mhgq-plugin-route-scope

8c48df0

fix(gateway): drop scopes from plugin-auth routes

67b6068

vincentkoc merged commit 2a1db0c into main Mar 31, 2026
9 checks passed

vincentkoc deleted the triage-mhgq-plugin-route-scope branch March 31, 2026 15:21

chatgpt-codex-connector Bot reviewed Mar 31, 2026

View reviewed changes

github-actions Bot mentioned this pull request Mar 31, 2026

📡 Upstream Digest — 2026-03-31 16:50 UTC curtismercier/openclaw-mods#423

Open

greptile-apps Bot mentioned this pull request Apr 8, 2026

fix(security): apply security patches for multiple GHSA vulnerabilities #63017

Closed

clawsweeper Bot mentioned this pull request May 14, 2026

fix(security): preserve dmPolicy settings during wizard runs #63827

Closed

mushuiyu886 mentioned this pull request Jul 8, 2026

fix(gateway): finish plugin HTTP responses after post-header failures #102125

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix(gateway): narrow plugin route runtime scopes#58167

fix(gateway): narrow plugin route runtime scopes#58167
vincentkoc merged 6 commits into
mainfrom
triage-mhgq-plugin-route-scope

vincentkoc commented Mar 31, 2026

Uh oh!

greptile-apps Bot commented Mar 31, 2026

Important Files Changed

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Mar 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Uh oh!

Conversation

vincentkoc commented Mar 31, 2026

Summary

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Root Cause / Regression History (if applicable)

Regression Test Plan (if applicable)

User-visible / Behavior Changes

Diagram (if applicable)

Security Impact (required)

Repro + Verification

Environment

Steps

Expected

Actual

Evidence

Human Verification (required)

Review Conversations

Compatibility / Migration

Risks and Mitigations

Uh oh!

greptile-apps Bot commented Mar 31, 2026

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant