Skip to content

Add plugin manifest contract for SecretRef provider integrations#82326

Merged
sallyom merged 15 commits into
openclaw:mainfrom
sallyom:secret-provider-integrations
May 29, 2026
Merged

Add plugin manifest contract for SecretRef provider integrations#82326
sallyom merged 15 commits into
openclaw:mainfrom
sallyom:secret-provider-integrations

Conversation

@sallyom

@sallyom sallyom commented May 15, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

  • add a manifest-level SecretRef provider integration contract for plugins
  • store plugin-owned provider refs in secrets.providers.<alias>.pluginIntegration instead of copying plugin resolver command/args into config
  • resolve the current exec command from the active plugin manifest at startup/reload and SecretRef resolution time
  • expose SDK types and cover manifest normalization/materialization with focused tests

Why

External providers like Vault, OneCLI, 1Password, Bitwarden, and similar stores were already possible through manual exec SecretRef configuration. This makes them discoverable, portable, and installable as plugins without hardcoding provider-specific logic in OpenClaw core.

Real Behavior Proof

Behavior addressed: External SecretRef providers could already be wired manually with exec, but plugin-owned Vault-style integrations were not discoverable or portable through plugin manifest metadata. This patch lets config refer to the owning plugin integration and lets OpenClaw materialize the resolver from the installed plugin manifest.

Real environment tested: OpenShift namespace openclaw-bob, running pod openclaw-cbbc765d8-sth7w, container gateway; git-installed Vault plugin from git:github.com/sallyom/claw-vault; Vault available at http://vault.vault.svc:8200; OpenClaw image from this PR branch. Earlier proof also covered a local Podman OpenClaw + HashiCorp Vault dev setup using an external git-installed Vault plugin and OpenRouter.

Exact steps or command run after this patch:

openclaw vault -h
openclaw vault status --json

The running deployment also confirmed configured models are accessible using Vault-resolved SecretRefs.

Evidence after fix:

Usage: openclaw vault [options] [command]

Manage Vault SecretRefs

Commands:
  setup       Create a Vault SecretRef setup plan
  status      Show Vault SecretRef provider status

{
  "providerAlias": "vault",
  "provider": {
    "configured": true,
    "source": "exec",
    "pluginIntegration": {
      "pluginId": "vault",
      "integrationId": "vault"
    }
  },
  "resolverScript": "/home/node/.openclaw/git/git-c317c86c2672b3ca/repo/dist/vault-secret-ref-resolver.js",
  "vaultAddr": "http://vault.vault.svc:8200",
  "kvMount": "secret",
  "kvVersion": "2",
  "hasVaultToken": true
}

Prior live proof also ran openclaw secrets audit --allow-exec --json and a live OpenRouter agent turn using a Vault-resolved model API key; terminal-command repro is captured at https://gist.github.com/sallyom/50f4678b053eaa93c4311a5509e52aeb.

Observed result after fix: The plugin-owned openclaw vault CLI command is registered, openclaw vault status --json reports the new pluginIntegration contract with canonical plugin id vault, the resolver script is loaded from the installed plugin root, Vault runtime env is visible without printing the token, and configured models are accessible through Vault-resolved SecretRefs.

What was not tested: Production Vault auth methods beyond the current deployment setup, and non-Vault providers such as 1Password, Bitwarden, or OneCLI.

Before evidence: Before this contract, the same Vault resolver could only be wired by hand through explicit secrets.providers.vault.command / args config; there was no plugin manifest preset for OpenClaw to discover or materialize.

Verification

  • node scripts/run-vitest.mjs src/secrets/provider-integrations.test.ts src/secrets/resolve.test.ts src/secrets/plan.test.ts src/commands/daemon-install-helpers.test.ts
  • node scripts/run-tsgo.mjs -p tsconfig.core.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/core.tsbuildinfo
  • git diff --check
  • .agents/skills/autoreview/scripts/autoreview --mode branch --base origin/main

@sallyom sallyom requested a review from a team as a code owner May 15, 2026 21:09
@github-actions github-actions Bot added the dependencies-changed PR changes dependency-related files label May 15, 2026
@github-actions

github-actions Bot commented May 15, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Dependency Changes Detected

This PR changes dependency-related files. Maintainers should confirm these changes are intentional.

Changed files:

  • package.json

Maintainer follow-up:

  • Review whether the dependency changes are intentional.
  • Inspect resolved package deltas when lockfile, shrinkwrap, or workspace dependency policy changes are present.
  • Treat package-lock.json and npm-shrinkwrap.json diffs as security-review surfaces.
  • Run pnpm deps:changes:report -- --base-ref origin/main --markdown /tmp/dependency-changes.md --json /tmp/dependency-changes.json locally for detailed release-style evidence.

@openclaw-barnacle openclaw-barnacle Bot added size: M maintainer Maintainer-authored PR labels May 15, 2026
@sallyom

sallyom commented May 15, 2026 •
edited by clawsweeper Bot
Loading

Copy link
Copy Markdown
Contributor Author

Vault/OpenClaw live smoke

I tested this branch with an external claw-vault plugin against a real OpenRouter model key stored in Vault.

The smoke test uses a normal OpenClaw SecretRef:

{
  "source": "exec",
  "provider": "vault",
  "id": "providers/openrouter/apiKey"
}

Verification result:

{
  "ok": true,
  "warningCount": 0
}

Then a live agent turn completed through openrouter/openai/gpt-4.1-nano with the model API key resolved from Vault by the claw-vault exec resolver. The expected response included:

vault-secretref-ok

Note: Vault was run in dev mode for this smoke, so the secret lives in Vault memory and disappears when the dev Vault container is removed.

Re-review progress:

@clawsweeper

clawsweeper Bot commented May 15, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge. Reviewed May 29, 2026, 5:30 PM ET / 21:30 UTC.

Summary
The branch adds manifest-declared SecretRef exec provider presets, a persisted pluginIntegration provider config variant, runtime materialization/validation, a plugin SDK subpath, docs, focused tests, and an E2E proof script.

PR surface: Source +996, Tests +1742, Docs +80, Config +4, Generated 0, Other +1522. Total +4344 across 37 files.

Reproducibility: not applicable. this is a feature/API PR rather than a bug report. The after-fix behavior is supported by the PR body/comment live proof and the added E2E script surface.

Review metrics: 3 noteworthy metrics.

  • Public contract surfaces: 3 added: manifest field, config provider variant, SDK subpath. These surfaces become compatibility commitments for plugin authors and persisted user config after release.
  • Config/provider default impact: 1 additive provider variant, 0 existing provider variants removed. Existing manual env/file/exec provider shapes remain present, while the new variant adds operator-visible fail-closed behavior for adopters.
  • Real proof breadth: 2 real environments plus 1 live model turn reported. The PR body/comment proof covers local Vault/OpenRouter and OpenShift Vault plugin usage, but not all named provider families.

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🦞 diamond lobster
Patch quality: 🦐 gold shrimp
Result: needs maintainer review before merge.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • [P1] Get explicit maintainer/security approval for the manifest/config/SDK contract and fail-closed behavior.
  • Keep the PR body verification current for the latest head SHA and note any remaining provider-family gaps maintainers accept.

Risk before merge

  • [P1] This creates a public manifest field, persisted config variant, and SDK subpath; once released, external plugins and user configs may depend on the exact contract.
  • [P1] Configured pluginIntegration providers intentionally fail closed when the owning plugin is disabled, removed, untrusted, or stops declaring the integration, which can make existing SecretRef-backed startup/reload paths stop for operators who adopt the new config.
  • [P1] Trusted plugin manifests can now materialize exec resolvers that receive SecretRef resolution requests and selected environment variables, so the origin, activation, path, symlink, hardlink, and passEnv model needs explicit security acceptance.
  • [P1] The posted proof is strong for Vault-style integrations, but it does not cover every named provider family or production Vault auth method before the contract becomes public.

Maintainer options:

  1. Require explicit contract approval (recommended)
    Have the responsible maintainers/security reviewers explicitly approve the manifest field, config variant, SDK subpath, fail-closed behavior, and trust model before merge.
  2. Narrow the public surface first
    If the contract is not ready to freeze, remove or mark experimental the SDK/config/docs surface and keep only the internal proof path until the API direction is settled.
  3. Pause if core ownership is not accepted
    If maintainers do not want core to own plugin-declared SecretRef providers, close or pause this PR and continue with manual exec providers or a narrower plugin API design issue.

Next step before merge

  • [P2] Manual review is required because the protected maintainer label and new public SecretRef plugin API/security boundary require human product/security approval rather than an automated repair.

Security
Needs attention: No current lockfile or dependency-source concern was found in the active diff, but the new manifest-declared exec resolver trust boundary needs maintainer/security approval.

Review details

Best possible solution:

Land only after maintainers explicitly approve the public manifest/config/SDK contract, fail-closed upgrade behavior, and trusted-plugin exec resolver model; otherwise narrow or defer the contract before release.

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

Not applicable: this is a feature/API PR rather than a bug report. The after-fix behavior is supported by the PR body/comment live proof and the added E2E script surface.

Is this the best way to solve the issue?

Unclear until maintainer/security review: the manifest-first approach fits plugin ownership and avoids provider-specific core hardcoding, but it freezes a public config/SDK contract and fail-closed exec behavior that owners must accept.

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

  • add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🦐 gold shrimp.
  • remove rating: 🐚 platinum hermit: Current PR rating is rating: 🦐 gold shrimp, so this older rating label is no longer current.

Label justifications:

  • P2: This is a normal-priority but security-sensitive feature/API change with limited blast radius until adopted by plugin SecretRef users.
  • merge-risk: 🚨 compatibility: The PR adds public manifest, persisted config, and SDK surfaces that become compatibility commitments after release.
  • merge-risk: 🚨 auth-provider: SecretRef provider resolution and model credential access now depend on active plugin manifest metadata for plugin-managed exec providers.
  • merge-risk: 🚨 security-boundary: Trusted plugin manifests can materialize exec resolvers that handle SecretRef requests and selected environment variables.
  • rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🦐 gold shrimp.
  • status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (live_output): The PR body and comments provide after-fix terminal/live-output proof from OpenShift and local Vault setups, including CLI status JSON, secrets audit, and a live OpenRouter agent turn with a Vault-resolved key.
  • proof: sufficient: Contributor real behavior proof is sufficient. The PR body and comments provide after-fix terminal/live-output proof from OpenShift and local Vault setups, including CLI status JSON, secrets audit, and a live OpenRouter agent turn with a Vault-resolved key.
Evidence reviewed

PR surface:

Source +996, Tests +1742, Docs +80, Config +4, Generated 0, Other +1522. Total +4344 across 37 files.

View PR surface stats
Area Files Added Removed Net
Source 20 1050 54 +996
Tests 9 1775 33 +1742
Docs 3 80 0 +80
Config 1 4 0 +4
Generated 2 6 6 0
Other 2 1522 0 +1522
Total 37 4437 93 +4344

Security concerns:

  • [medium] Approve the manifest-declared exec resolver trust boundary — src/secrets/provider-integrations.ts:199
    The diff lets trusted plugin manifests materialize exec SecretRef resolvers that receive requested secret IDs and selected environment variables; the path/origin checks are meaningful, but this is a new security boundary that should be explicitly accepted before release.
    Confidence: 0.86

What I checked:

  • Repository policy applies: Root policy treats plugin APIs, provider routing, persisted config/default surfaces, setup/startup checks, fail-closed behavior, and security boundaries as compatibility-sensitive merge risks; that directly applies to this PR. (AGENTS.md:26, a841778b7b94)
  • Scoped plugin policy applies: The plugins guide says manifest parsing, config validation, setup/onboarding hints, and activation planning belong to metadata/control-plane seams, with runtime execution kept in runtime resolution. (src/plugins/AGENTS.md:24, a841778b7b94)
  • New manifest contract: The PR adds PluginManifestSecretProviderIntegration with exec resolver metadata and normalizes secretProviderIntegrations from plugin manifests. (src/plugins/manifest.ts:164, ce9f9267b4dc)
  • New persisted config variant: The PR splits manual exec providers from plugin-managed exec providers and adds PluginIntegrationSecretProviderConfig under secrets.providers config. (src/config/types.secrets.ts:289, ce9f9267b4dc)
  • New SDK/package surface: The package exports a new public ./plugin-sdk/secret-provider-integration subpath, making this a plugin SDK contract after release. (package.json:548, ce9f9267b4dc)
  • Fail-closed behavior is documented: The docs state plugin-managed exec providers resolve command details from the installed manifest and fail closed if the plugin is disabled, removed, untrusted, or no longer declares the integration. Public docs: docs/gateway/secrets.md. (docs/gateway/secrets.md:229, ce9f9267b4dc)

Likely related people:

  • Peter Steinberger: Current-main blame and log for the existing SecretRef, manifest, and plugin SDK/package surfaces point to recent work by Peter across the central files this PR extends. (role: recent area contributor; confidence: medium; commits: 1e2fda9e6886, 2b15850b471a; files: src/config/types.secrets.ts, src/secrets/resolve.ts, src/plugins/manifest.ts)
  • joshavant: The PR history shows Josh authored the latest hardening, service-env, validation, and E2E proof commits on the branch after maintainer review activity. (role: branch hardening contributor; confidence: high; commits: a54e049abd22, 3d64dbea9d56, 1004333770ac; files: src/secrets/provider-integrations.ts, src/commands/daemon-install-helpers.ts, scripts/e2e/secret-provider-integrations.mjs)
  • sallyom: Sally authored the initial branch commits and supplied live Vault/OpenRouter proof plus linked external Vault/OneCLI/1Password plugin work, which is directly tied to the requested provider-integration behavior. (role: external integration proposer; confidence: medium; commits: 553954448ebf, 0f0fe7bb142d, 5b9c85b135df; files: src/secrets/provider-integrations.ts, docs/gateway/secrets.md, docs/plugins/manifest.md)
  • altaywtf: The PR timeline shows assignment, review, and branch force-push activity from altaywtf during the maintainer review cycle for this feature. (role: reviewer and adjacent PR contributor; confidence: low; commits: e3c7fe74eb53, f3b376314726; files: src/secrets/provider-integrations.ts, src/plugins/manifest.ts)
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.

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.

@sallyom sallyom force-pushed the secret-provider-integrations branch from 66d2b46 to db32d0b Compare May 15, 2026 21:33
@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation scripts Repository scripts labels May 15, 2026
@clawsweeper clawsweeper Bot added the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 15, 2026
@sallyom sallyom force-pushed the secret-provider-integrations branch 2 times, most recently from 9a0f5ec to cca6433 Compare May 15, 2026 21:56
@socket-security

socket-security Bot commented May 15, 2026 •
edited
Loading

Copy link
Copy Markdown

Warning

Review the following alerts detected in dependencies.

According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.

Action Severity Alert  (click "▶" to expand/collapse)
Warn Medium
Deprecated by its maintainer: npm has-own

Reason: This project is not maintained. Use Object.hasOwn() instead.

From: extensions/feishu/npm-shrinkwrap.json → npm/@larksuiteoapi/node-sdk@1.66.0 → npm/has-own@1.0.1

ℹ Read more on: This package | This alert | What is a deprecated package?

Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev.

Suggestion: Research the state of the package and determine if there are non-deprecated versions that can be used, or if it should be replaced with a new, supported solution.

Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/has-own@1.0.1. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report

@sallyom

sallyom commented May 15, 2026

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

@clawsweeper

clawsweeper Bot commented May 15, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

🦞🧹
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:

@clawsweeper clawsweeper Bot mentioned this pull request May 16, 2026
Open
@sallyom sallyom force-pushed the secret-provider-integrations branch 2 times, most recently from 1cc05be to 5d3f4dc Compare May 16, 2026 18:34
@sallyom

sallyom commented May 16, 2026

Copy link
Copy Markdown
Contributor Author

@joshavant ptal. I have a few external secret provider plugins to go along with this. I've been testing with
https://github.com/sallyom/claw-vault,claw-onecli,claw-1password

Related to #71593. My PR adds the manifest/provider integration layer that lets plugins declare installable SecretRef providers.

@sallyom sallyom force-pushed the secret-provider-integrations branch from 5d3f4dc to 1990e8e Compare May 17, 2026 02:58
@clawsweeper clawsweeper Bot added P2 Normal backlog priority with limited blast radius. impact:security Security boundary, credential, authz, sandbox, or sensitive-data risk. impact:auth-provider Auth, provider routing, model choice, or SecretRef resolution may break. labels May 17, 2026
@sallyom sallyom force-pushed the secret-provider-integrations branch from 1990e8e to 7388581 Compare May 17, 2026 14:41
@altaywtf altaywtf self-assigned this May 17, 2026
@altaywtf altaywtf force-pushed the secret-provider-integrations branch 2 times, most recently from e3c7fe7 to f3b3763 Compare May 17, 2026 22:44
@sallyom sallyom force-pushed the secret-provider-integrations branch from 582e43c to 675c4d7 Compare May 24, 2026 17:42
@clawsweeper clawsweeper Bot added rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. and removed rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. labels May 24, 2026
@sallyom sallyom force-pushed the secret-provider-integrations branch from 675c4d7 to b7f57f4 Compare May 24, 2026 18:11
@clawsweeper clawsweeper Bot added status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. and removed status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. labels May 24, 2026
@sallyom sallyom force-pushed the secret-provider-integrations branch from b7f57f4 to c7597c0 Compare May 25, 2026 04:02
@clawsweeper clawsweeper Bot removed the rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. label May 25, 2026
@socket-security

socket-security Bot commented May 25, 2026 •
edited
Loading

Copy link
Copy Markdown

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff Package Supply Chain
Security		 Vulnerability Quality Maintenance License
Addednpm/​nostr-tools@​2.23.59610010093100

View full report

@joshavant

joshavant commented May 29, 2026

Copy link
Copy Markdown
Contributor

@clawsweeper re-review

@clawsweeper

clawsweeper Bot commented May 29, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

🦞🧹
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:

sallyom and others added 15 commits May 29, 2026 18:14
@github-actions github-actions Bot mentioned this pull request May 29, 2026
Open
@clawsweeper clawsweeper Bot mentioned this pull request Jun 8, 2026
Draft
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@altaywtf altaywtf altaywtf approved these changes

Assignees

@joshavant joshavant

Labels

cli CLI command changes commands Command implementations docs Improvements or additions to documentation gateway Gateway runtime maintainer Maintainer-authored PR merge-risk: 🚨 auth-provider 🚨 May break OAuth, tokens, provider routing, model choice, or credentials. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. merge-risk: 🚨 security-boundary 🚨 May affect sandboxing, authorization, credentials, or sensitive data. P2 Normal backlog priority with limited blast radius. proof: sufficient ClawSweeper judged the real behavior proof convincing. rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. scripts Repository scripts size: XL status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@sallyom @Colstuwjx @joshavant @altaywtf