fix(plugins): secure setup-mode provider discovery against untrusted workspace plugins [AI-assisted]

[mmaps]

Summary

• Problem: Default setup-mode provider discovery called resolveDiscoveredProviderPluginIds / resolveDiscoverableProviderOwnerPluginIds with includeUntrustedWorkspacePlugins unset (undefined), which evaluated undefined === false as false — leaving shouldFilterUntrustedWorkspacePlugins = false and allowing untrusted workspace plugin code to be imported and executed before any explicit user trust.
• Why it matters: A malicious or accidental workspace-local plugin placed in .openclaw/extensions/ could run arbitrary code at setup-discovery time, before the user has ever enabled or approved that plugin.
• What changed: Two conditions in providers.ts changed from === false to !== true, making the default (undefined) secure — untrusted workspace plugins are filtered unless the caller explicitly passes includeUntrustedWorkspacePlugins: true.
• What did NOT change: Runtime (non-setup) provider loading, bundled plugin behavior, behavior when includeUntrustedWorkspacePlugins is explicitly false or true, and the provider-install-catalog / provider-auth-choices paths (which use a different, intentional semantic for that flag).

Change Type (select all)

• Bug fix
• Security hardening

Scope (select all touched areas)

• Auth / tokens

Linked Issue/PR

• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

• Behavior or issue addressed: Untrusted workspace provider plugin code (top-level module + register()) executed during default setup discovery with no explicit trust granted.
• Real environment tested: Linux, Node 22, source checkout.
• Exact steps or command run after this patch: pnpm test src/plugins/providers.setup-trust.test.ts and pnpm test src/plugins/providers.test.ts
• Evidence after fix: Both new test files pass. The integration test in providers.setup-trust.test.ts uses filesystem markers written by the plugin's top-level code and register() to prove no plugin code runs for the untrusted case, and that it does run for the explicitly-trusted (allowlisted) case.
• Observed result after fix: resolvePluginProviders({ mode: "setup" }) without explicit trust returns [] and produces zero filesystem side effects from the workspace plugin.
• What was not tested: Live macOS gateway, E2E provider auth flow.
• Before evidence: PoC log showed register() called with registrationMode: "discovery" and top-level marker written during default setup-mode call with no explicit trust.

Root Cause

• Root cause: === false strict-equality check treated undefined (parameter omitted) identically to true — both left shouldFilterUntrustedWorkspacePlugins = false, disabling the workspace-plugin filter by default.
• Missing detection / guardrail: No test covered the omitted-parameter (default) case for setup-mode discovery; only the explicit false path was tested.
• Contributing context: The flag was introduced with the safe explicit-false call sites in auth helpers, masking that the default left the gate open in the setup discovery path.

Regression Test Plan

• Coverage level that should have caught this:
  • Seam / integration test
• Target test or file: src/plugins/providers.setup-trust.test.ts (new), src/plugins/providers.test.ts (updated)
• Scenario the test should lock in: Default-params setup-mode call must not import or execute workspace plugin code; file-system markers confirm no side effects.
• Why this is the smallest reliable guardrail: The integration test drives the real runtime path with a real filesystem plugin fixture, so a regression in the flag logic will fail the marker assertions regardless of mock layering.
• Existing test that already covered this: None — prior tests only covered the explicit false path.

User-visible / Behavior Changes

Workspace-origin provider plugins are no longer loaded during setup-mode discovery unless they appear in config.plugins.allow. Users relying on implicit setup-mode loading of workspace plugins must add those plugin IDs to their allow list.

Diagram

Before:
[setup discovery, no includeUntrustedWorkspacePlugins param]
  -> shouldFilterUntrustedWorkspacePlugins = (undefined === false) = false
  -> workspace plugin imported + register() called

After:
[setup discovery, no includeUntrustedWorkspacePlugins param]
  -> shouldFilterUntrustedWorkspacePlugins = (undefined !== true) = true
  -> workspace plugin skipped unless in config.plugins.allow

Security Impact

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? Yes — workspace plugin code is no longer executed at setup-discovery time without explicit trust.
• Data access scope changed? No
• Explanation: The surface reduction is the fix: untrusted workspace plugin register() and module-level code can no longer run during setup-mode provider discovery.

Repro + Verification

Environment

• OS: Linux (Node 22)
• Runtime/container: source checkout, pnpm
• Relevant config: config.plugins.enabled: true, no allow list

Steps

1. Place a workspace plugin in .openclaw/extensions/<id>/ with a register() that writes a filesystem marker.
2. Call resolvePluginProviders({ mode: "setup", config: { plugins: { enabled: true } } }) without setting includeUntrustedWorkspacePlugins.
3. Check for marker files.

Expected

• No providers returned, no marker files written.

Actual (after fix)

• No providers returned, no marker files written.

Evidence

• Failing test/log before + passing after — providers.setup-trust.test.ts integration markers + updated providers.test.ts assertions.

Human Verification (required)

• Verified scenarios: Default-omitted param filters workspace plugin; explicit true includes it; explicit false still filters; bundled plugins unaffected.
• Edge cases checked: Plugin in allow list is still discoverable in setup mode (second integration test).
• What you did not verify: Downstream callers that pass includeUntrustedWorkspacePlugins explicitly (all confirmed to pass false, which remains filtering behavior).

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? No — workspace plugins no longer auto-discovered in setup mode without allowlisting.
• Config/env changes? No
• Migration needed? Yes — users with workspace provider plugins must add plugin IDs to config.plugins.allow.
• Exact upgrade steps: Add the plugin ID string to the plugins.allow array in your OpenClaw config.

Risks and Mitigations

• Risk: Workspace provider plugins that were previously auto-discovered in setup mode will no longer appear until explicitly trusted.
  • Mitigation: The new behavior is intentional and correct; affected users must opt in via config.plugins.allow. Error messaging in setup flows should guide users to add the plugin to their allow list.

[clawsweeper]

Codex review: needs maintainer review before merge.

Workflow note: Future ClawSweeper reviews update this same comment in place.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Summary
The PR makes setup-mode provider discovery filter workspace-origin provider plugins by default unless includeUntrustedWorkspacePlugins: true is passed, and adds marker-file regression coverage.

Reproducibility: yes. Current main forwards an omitted setup trust flag into helpers that only filter on explicit false, then selected setup plugin IDs reach module loading; the posted terminal proof shows the after-fix setup path.

PR rating
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Summary: Strong terminal proof and a narrow patch make this a solid PR, with readiness gated by compatibility approval and proof-check housekeeping.

Rank-up moves:

• Get maintainer sign-off on the setup workspace-provider allowlist migration before merge.
• Copy the posted proof into the PR body or apply an explicit proof override so the current proof check is no longer red.

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Real behavior proof
Sufficient (terminal): Terminal output in a PR comment shows the after-fix default setup path skips the workspace plugin with zero marker side effects and an allowlisted control executes it; the latest body-only proof check still needs maintainer handling.

Risk before merge

• Merging intentionally changes upgrade behavior: workspace provider plugins that were implicitly visible during setup discovery will stop appearing until their plugin ID is trusted through plugins.allow or an explicit include path.
• Because the changed path controls provider setup discovery, affected users may see different provider auth/setup choices until they allowlist the workspace plugin.
• The current head has a failing body-only Real behavior proof check despite sufficient terminal proof in a PR comment, so landing may require copying the proof into the PR body or an explicit maintainer override.
• This PR only covers setup-mode discovery; the startup-discovery companion at fix(security): block untrusted workspace providers in startup discovery #74302 remains separate work.

Maintainer options:

1. Accept the setup allowlist migration (recommended)
   Merge once maintainers agree setup discovery should fail closed for workspace provider plugins, with landing notes that affected users must add the plugin ID to plugins.allow.
2. Preserve implicit setup discovery first
   If existing implicit workspace setup discovery must keep working on upgrade, require a compatibility path or explicit strict mode before changing the default.
3. Coordinate with startup hardening
   Pause if maintainers want one combined policy decision for setup and startup workspace-provider discovery rather than landing this setup-only fix first.

Next step before merge
The remaining action is maintainer acceptance of the compatibility/auth-provider migration plus proof-check housekeeping, not an automated code repair.

Security
Cleared: The diff reduces a setup-time workspace plugin execution surface and does not add dependencies, workflow changes, secret handling, downloads, or broader execution paths.

Review details

Best possible solution:

Land the fail-closed setup-discovery fix after maintainer acceptance of the plugins.allow migration, while keeping startup-discovery hardening tracked separately.

Do we have a high-confidence way to reproduce the issue?

Yes. Current main forwards an omitted setup trust flag into helpers that only filter on explicit false, then selected setup plugin IDs reach module loading; the posted terminal proof shows the after-fix setup path.

Is this the best way to solve the issue?

Yes. The !== true gate is the narrow code-level fix for the omitted-parameter trust bug; the remaining question is maintainer acceptance of the setup-provider allowlist migration.

Label changes:

• add proof: sufficient: Contributor real behavior proof is sufficient. Terminal output in a PR comment shows the after-fix default setup path skips the workspace plugin with zero marker side effects and an allowlisted control executes it; the latest body-only proof check still needs maintainer handling.

Label justifications:

• P1: The PR narrows a pre-trust workspace plugin code-execution surface in provider setup discovery, with security impact but setup-limited blast radius.
• merge-risk: 🚨 compatibility: Existing workspace provider plugins that relied on implicit setup discovery will stop appearing until explicitly allowlisted.
• merge-risk: 🚨 auth-provider: The changed discovery path controls which provider setup/auth options are offered during setup.
• rating: 🐚 platinum hermit: Current PR rating is 🐚 platinum hermit because proof is 🦞 diamond lobster, patch quality is 🐚 platinum hermit, and Strong terminal proof and a narrow patch make this a solid PR, with readiness gated by compatibility approval and proof-check housekeeping.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): Terminal output in a PR comment shows the after-fix default setup path skips the workspace plugin with zero marker side effects and an allowlisted control executes it; the latest body-only proof check still needs maintainer handling.
• proof: sufficient: Contributor real behavior proof is sufficient. Terminal output in a PR comment shows the after-fix default setup path skips the workspace plugin with zero marker side effects and an allowlisted control executes it; the latest body-only proof check still needs maintainer handling.

What I checked:

• Current main default trust gap: Current main computes setup-discovery workspace filtering with includeUntrustedWorkspacePlugins === false, so an omitted setup flag leaves workspace provider plugins unfiltered. (src/plugins/providers.ts:266, 777a113973e9)
• Setup path forwards omitted flag: resolveSetupProviderPluginLoadState forwards params.includeUntrustedWorkspacePlugins unchanged into both setup discovery helper calls. (src/plugins/providers.runtime.ts:172, 777a113973e9)
• Selected setup plugins execute code: When selected plugin IDs reach the loader, module evaluation begins through loadPluginModule, which is the setup-time execution surface this PR narrows. (src/plugins/loader.ts:2099, 777a113973e9)
• PR applies narrow gate change: The PR head changes both setup discovery helper comparisons to includeUntrustedWorkspacePlugins !== true, preserving explicit opt-in while making the omitted default fail closed. (src/plugins/providers.ts:266, 28e0b880fcdc)
• Regression fixture covers module and register side effects: The added test writes a workspace provider plugin whose top-level module and register write markers, then asserts default setup discovery leaves both marker files empty while the allowlisted control loads. (src/plugins/providers.setup-trust.test.ts:90, 28e0b880fcdc)
• Real behavior proof comment: A PR comment posts terminal output for commit 926cf98 showing default setup discovery returns no providers and zero marker side effects, while an allowlisted control discovers the provider and writes both markers. (926cf98da6e0)

Likely related people:

• steipete: Authored the setup-mode provider loading simplification and bundled discovery allowlist default changes in the same provider discovery files. (role: recent provider discovery contributor; confidence: high; commits: d655a8bc7654, b2096d19ecde; files: src/plugins/providers.ts, src/plugins/providers.runtime.ts, src/plugins/providers.test.ts)
• dougbtv: Authored earlier provider discovery allowlist gating work that changed the same helper and test surface. (role: adjacent allowlist behavior contributor; confidence: medium; commits: f738663c7967; files: src/plugins/providers.ts, src/plugins/providers.test.ts, src/plugins/activation-context.ts)
• sjf: Introduced the current provider discovery/runtime files and the omitted setup trust flag forwarding now being patched. (role: recent area contributor; confidence: medium; commits: 4f80cc1943b9; files: src/plugins/providers.ts, src/plugins/providers.runtime.ts, src/plugins/providers.test.ts)

Codex review notes: model gpt-5.5, reasoning high; reviewed against 777a113973e9.

[mmaps]

Not applicable to this automation stage; changelog/release-note and external real behavior proof requirements are handled outside auto-pr stages.

Quoted comment from @clawsweeper:

Codex review: needs real behavior proof before merge.

Summary
The PR makes setup-mode provider discovery filter workspace provider plugins unless includeUntrustedWorkspacePlugins: true is passed, and adds regression coverage for the omitted-parameter default.

Reproducibility: yes. Source inspection shows current main forwards an omitted setup trust flag into helpers that only filter on explicit false, then imports/registers selected setup plugins; I did not run a fixture because this review checkout must remain read-only.

Real behavior proof
Needs real behavior proof before merge: The PR body only cites tests and marker assertions; the contributor should add redacted terminal/live output, logs, or a recording showing the after-fix behavior, then update the PR body so ClawSweeper re-reviews automatically or ask a maintainer for @clawsweeper re-review.

Next step before merge
This security-hardening PR appears code-correct, but it needs contributor-provided real behavior proof and maintainer compatibility review rather than an automated repair PR.

Security
Cleared: The diff narrows a setup-time plugin code-execution surface and does not add dependencies, workflow changes, secret handling expansion, or new execution paths.

Review details

Best possible solution:

Land a narrow fail-closed setup-discovery fix that preserves explicit trusted opt-in and documents or handles the workspace-provider compatibility expectation if maintainers accept that policy.

Do we have a high-confidence way to reproduce the issue?

Yes. Source inspection shows current main forwards an omitted setup trust flag into helpers that only filter on explicit false, then imports/registers selected setup plugins; I did not run a fixture because this review checkout must remain read-only.

Is this the best way to solve the issue?

Yes, the proposed !== true gate is the narrowest code-level fix for the default trust bug. Merge should still wait for real behavior proof and maintainer acceptance of the compatibility impact.

What I checked:

• Current main source shows the default trust gap: On current main, both setup discovery helpers compute shouldFilterUntrustedWorkspacePlugins with params.includeUntrustedWorkspacePlugins === false, so an omitted value leaves workspace plugins unfiltered. (src/plugins/providers.ts:257, 263d7cbf27ad)
• Setup-mode call path forwards the omitted flag: resolveSetupProviderPluginLoadState forwards params.includeUntrustedWorkspacePlugins unchanged into both discovery helper calls, so default setup calls hit the omitted-value path. (src/plugins/providers.runtime.ts:162, 263d7cbf27ad)
• Selected setup plugins are imported and registered: After setup discovery returns plugin IDs, loadOpenClawPlugins loads the plugin module and runs register, which is the code-execution surface this PR is trying to avoid for untrusted workspace plugins. (src/plugins/loader.ts:2062, 263d7cbf27ad)
• PR diff targets the implicated comparisons: The PR changes the two providers.ts comparisons from === false to !== true and adds a filesystem-marker integration test for default setup discovery plus an allowlisted workspace plugin case. (src/plugins/providers.ts:257, 66785f81cd39)
• Proof gate is not yet satisfied: The PR body cites pnpm test src/plugins/providers.setup-trust.test.ts and pnpm test src/plugins/providers.test.ts, and the live PR has triage: mock-only-proof; there is no copied terminal output, recording, or redacted runtime log showing the after-fix behavior outside the test assertion. (66785f81cd39)
• Related search found adjacent but not superseding work: Search found fix(security): block untrusted workspace providers in startup discovery #74302 on untrusted workspace providers in startup discovery; it is open and targets a different startup-discovery call path, so it does not make this setup-mode PR obsolete.

Likely related people:

• steipete: Authored recent commits that changed provider setup discovery, bundled discovery defaults, and provider setup loading in the same files this PR touches. (role: recent provider discovery contributor; confidence: high; commits: b2096d19ecde, d655a8bc7654; files: src/plugins/providers.ts, src/plugins/providers.test.ts, src/plugins/providers.runtime.ts)
• dougbtv: Authored the earlier bundled provider allowlist gating work that introduced related discovery-policy behavior in src/plugins/providers.ts and tests. (role: adjacent allowlist behavior contributor; confidence: medium; commits: f738663c7967; files: src/plugins/providers.ts, src/plugins/providers.test.ts, src/plugins/bundled-compat.ts)

Remaining risk / open question:

• The PR still lacks after-fix real behavior proof beyond tests, so the external contributor proof gate is not satisfied.
• The change is intentionally not backward compatible for workspace provider setup auto-discovery and should receive maintainer acceptance before merge.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 263d7cbf27ad.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/25744175834
• Updated: 2026-05-12T15:30:24.776Z

[eleqtrizit]

Real behavior proof for PR head 926cf98da6e026d48922213277c63cdc8e263849.

This is a one-off runtime proof against the production resolvePluginProviders setup path. It creates a workspace-local provider plugin under a temp workspace .openclaw/extensions/ directory whose module top level and register(api) both write marker files. The default setup discovery call omits includeUntrustedWorkspacePlugins; the allowlisted control uses the same fixture with plugins.allow.

Command:

GITHUB_SHA=926cf98da6e026d48922213277c63cdc8e263849 node --import tsx /tmp/openclaw-pr-81069-real-proof.ts

Output:

OpenClaw PR 81069 real behavior proof
head=926cf98da6e026d48922213277c63cdc8e263849
workspace_fixture=<tmp-proof-root>/workspace

default setup discovery, no includeUntrustedWorkspacePlugins:
{
  "providers": [],
  "topLevelMarkerCount": 0,
  "registerMarkerCount": 0,
  "topLevelMarkers": [],
  "registerMarkers": []
}

allowlisted setup discovery control:
{
  "providers": [
    {
      "id": "setup-autoload",
      "label": "Setup Trust Provider",
      "auth": [],
      "pluginId": "setup-autoload-provider"
    }
  ],
  "topLevelMarkerCount": 1,
  "registerMarkerCount": 1,
  "topLevelMarkers": [
    "{\"event\":\"top-level\",\"registrationMode\":\"module-import\"}"
  ],
  "registerMarkers": [
    "{\"event\":\"register\",\"registrationMode\":\"discovery\"}"
  ]
}

Observed result: with default setup discovery and no explicit trust, OpenClaw returns no provider and neither the top-level marker nor the register marker exists. With the same plugin explicitly allowlisted, the provider is discovered and both markers are written, confirming the proof fixture would show execution if setup discovery loaded the workspace plugin.

I also ran the focused regression proof with:

node scripts/run-vitest.mjs run src/plugins/providers.setup-trust.test.ts --reporter=verbose

That command exited 0 in this Codex worktree; the wrapper emitted no stdout for this run.

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/26245335877
• Updated: 2026-05-21T18:38:04.367Z

[clawsweeper]

ClawSweeper PR egg

✨ Hatched: 🥚 common Mossy Clawlet

Hatch command

Comment @clawsweeper hatch when this PR is hatchable.

Hatchability rules:

• Merged PRs are hatchable.
• Open PRs are hatchable when they are status: 👀 ready for maintainer look, status: 🚀 automerge armed, or labeled clawsweeper:automerge.
• Closed unmerged PRs are hatchable only when one of those hatchable labels is still present in the durable record.

Rarity: 🥚 common.
Trait: hums during re-review.
Image traits: location diff observatory; accessory rollback rope; palette cobalt, lime, and pearl; mood proud; pose nestled inside a glowing shell; shell polished stone shell; lighting gentle morning glow; background smooth stones and checkmarks.
Share on X: post this hatch
Copy: My PR egg hatched a 🥚 common Mossy Clawlet in ClawSweeper.

What is this egg doing here?

• Eggs appear after the PR passes real-behavior proof. It is here for vibes, not verdicts: it does not change labels, ratings, merge decisions, or automation.
• The shell reacts to review momentum: open follow-up work warms it up, re-review makes it wobble, and a clean final review lets it hatch.
• Hatchability usually comes from sufficient real-behavior proof, no blocking P0/P1/P2 findings, no security attention needed, and clean correctness. A merged PR is already final, so merge makes the egg hatchable independently.
• The hatch is seeded from this repository and PR number, so the same PR keeps the same creature; the reviewed head SHA can only change safe visual details.
• Rarity is just collectible sparkle: 🥚 common, 🌱 uncommon, 💎 rare, ✨ glimmer, and 🌈 legendary.

[eleqtrizit]

There is a small compatibility risk but it only involves setup. Let's rebase so we can update the changelog.