Skip to content

Commit fb6fba1

Browse files
vincentkocvincentkoc
authored
Merge branch 'main' into docs/plugin-sdk-generated-reference-recovery
2 parents 647eb8a + 0f2c380 commit fb6fba1

File tree

75 files changed

+2228
-174
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

75 files changed

+2228
-174
lines changed

‎.agents/skills/security-triage/SKILL.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
---
2+
name: security-triage
3+
description: Triage GitHub security advisories for OpenClaw with high-confidence close/keep decisions, exact tag and commit verification, trust-model checks, optional hardening notes, and a final reply ready to post and copy to clipboard.
4+
---
5+
6+
# Security Triage
7+
8+
Use when reviewing OpenClaw security advisories, drafts, or GHSA reports.
9+
10+
Goal: high-confidence maintainers' triage without over-closing real issues or shipping unnecessary regressions.
11+
12+
## Close Bar
13+
14+
Close only if one of these is true:
15+
16+
- duplicate of an existing advisory or fixed issue
17+
- invalid against shipped behavior
18+
- out of scope under `SECURITY.md`
19+
- fixed before any affected release/tag
20+
21+
Do not close only because `main` is fixed. If latest shipped tag or npm release is affected, keep it open until released or published with the right status.
22+
23+
## Required Reads
24+
25+
Before answering:
26+
27+
1. Read `SECURITY.md`.
28+
2. Read the GHSA body with `gh api /repos/openclaw/openclaw/security-advisories/<GHSA>`.
29+
3. Inspect the exact implicated code paths.
30+
4. Verify shipped state:
31+
- `git tag --sort=-creatordate | head`
32+
- `npm view openclaw version --userconfig "$(mktemp)"`
33+
- `git tag --contains <fix-commit>`
34+
- if needed: `git show <tag>:path/to/file`
35+
5. Search for canonical overlap:
36+
- existing published GHSAs
37+
- older fixed bugs
38+
- same trust-model class already covered in `SECURITY.md`
39+
40+
## Review Method
41+
42+
For each advisory, decide:
43+
44+
- `close`
45+
- `keep open`
46+
- `keep open but narrow`
47+
48+
Check in this order:
49+
50+
1. Trust model
51+
- Is the prerequisite already inside trusted host/local/plugin/operator state?
52+
- Does `SECURITY.md` explicitly call this class out as out of scope or hardening-only?
53+
2. Shipped behavior
54+
- Is the bug present in the latest shipped tag or npm release?
55+
- Was it fixed before release?
56+
3. Exploit path
57+
- Does the report show a real boundary bypass, not just prompt injection, local same-user control, or helper-level semantics?
58+
4. Functional tradeoff
59+
- If a hardening change would reduce intended user functionality, call that out before proposing it.
60+
- Prefer fixes that preserve user workflows over deny-by-default regressions unless the boundary demands it.
61+
62+
## Response Format
63+
64+
When preparing a maintainer-ready close reply:
65+
66+
1. Print the GHSA URL first.
67+
2. Then draft a detailed response the maintainer can post.
68+
3. Include:
69+
- exact reason for close
70+
- exact code refs
71+
- exact shipped tag / release facts
72+
- exact fix commit or canonical duplicate GHSA when applicable
73+
- optional hardening note only if worthwhile and functionality-preserving
74+
75+
Keep tone firm, specific, non-defensive.
76+
77+
## Clipboard Step
78+
79+
After drafting the final post body, copy it:
80+
81+
```bash
82+
pbcopy <<'EOF'
83+
<final response>
84+
EOF
85+
```
86+
87+
Tell the user that the clipboard now contains the proposed response.
88+
89+
## Useful Commands
90+
91+
```bash
92+
gh api /repos/openclaw/openclaw/security-advisories/<GHSA>
93+
gh api /repos/openclaw/openclaw/security-advisories --paginate
94+
git tag --sort=-creatordate | head -n 20
95+
npm view openclaw version --userconfig "$(mktemp)"
96+
git tag --contains <commit>
97+
git show <tag>:<path>
98+
gh search issues --repo openclaw/openclaw --match title,body,comments -- "<terms>"
99+
gh search prs --repo openclaw/openclaw --match title,body,comments -- "<terms>"
100+
```
101+
102+
## Decision Notes
103+
104+
- “fixed on main, unreleased” is usually not a close.
105+
- “needs attacker-controlled trusted local state first” is usually out of scope.
106+
- “same-host same-user process can already read/write local state” is usually out of scope.
107+
- “helper function behaves differently than documented config semantics” is usually invalid.
108+
- If only the severity is wrong but the bug is real, keep it open and narrow the impact in the reply.

‎docs/.i18n/glossary.zh-CN.json‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -238,5 +238,65 @@
238238
{
239239
"source": "env var",
240240
"target": "环境变量"
241+
},
242+
{
243+
"source": "Plugin SDK",
244+
"target": "插件 SDK"
245+
},
246+
{
247+
"source": "Plugin SDK Overview",
248+
"target": "插件 SDK 概览"
249+
},
250+
{
251+
"source": "SDK Overview",
252+
"target": "SDK 概览"
253+
},
254+
{
255+
"source": "Plugin Entry Points",
256+
"target": "插件入口点"
257+
},
258+
{
259+
"source": "Entry Points",
260+
"target": "入口点"
261+
},
262+
{
263+
"source": "Plugin Runtime",
264+
"target": "插件运行时"
265+
},
266+
{
267+
"source": "Runtime",
268+
"target": "运行时"
269+
},
270+
{
271+
"source": "Plugin Setup",
272+
"target": "插件设置"
273+
},
274+
{
275+
"source": "Setup",
276+
"target": "设置"
277+
},
278+
{
279+
"source": "Channel Plugin SDK",
280+
"target": "渠道插件 SDK"
281+
},
282+
{
283+
"source": "Channel Plugins",
284+
"target": "渠道插件"
285+
},
286+
{
287+
"source": "Provider Plugin SDK",
288+
"target": "提供商插件 SDK"
289+
},
290+
{
291+
"source": "Provider Plugins",
292+
"target": "提供商插件"
293+
},
294+
{
295+
"source": "Plugin SDK Testing",
296+
"target": "插件 SDK 测试"
297+
},
298+
{
299+
"source": "Testing",
300+
"target": "测试"
241301
}
242302
]

‎docs/docs.json‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1045,6 +1045,18 @@
10451045
"plugins/architecture"
10461046
]
10471047
},
1048+
{
1049+
"group": "Plugin SDK",
1050+
"pages": [
1051+
"plugins/sdk-overview",
1052+
"plugins/sdk-entrypoints",
1053+
"plugins/sdk-runtime",
1054+
"plugins/sdk-setup",
1055+
"plugins/sdk-channel-plugins",
1056+
"plugins/sdk-provider-plugins",
1057+
"plugins/sdk-testing"
1058+
]
1059+
},
10481060
{
10491061
"group": "Skills",
10501062
"pages": [

‎docs/gateway/tools-invoke-http-api.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ title: "Tools Invoke API"
88

99
# Tools Invoke (HTTP)
1010

11-
OpenClaw’s Gateway exposes a simple HTTP endpoint for invoking a single tool directly. It is always enabled, but gated by Gateway auth and tool policy.
11+
OpenClaw’s Gateway exposes a simple HTTP endpoint for invoking a single tool directly. It is always enabled and uses Gateway auth plus tool policy, but callers that pass Gateway bearer auth are treated as trusted operators for that gateway.
1212

1313
- `POST /tools/invoke`
1414
- Same port as the Gateway (WS + HTTP multiplex): `http://<gateway-host>:<port>/tools/invoke`
@@ -26,6 +26,7 @@ Notes:
2626
- When `gateway.auth.mode="token"`, use `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`).
2727
- When `gateway.auth.mode="password"`, use `gateway.auth.password` (or `OPENCLAW_GATEWAY_PASSWORD`).
2828
- If `gateway.auth.rateLimit` is configured and too many auth failures occur, the endpoint returns `429` with `Retry-After`.
29+
- Treat this credential as a full-access operator secret for that gateway. It is not a scoped API token for a narrower `/tools/invoke` role.
2930

3031
## Request body
3132

@@ -59,8 +60,15 @@ Tool availability is filtered through the same policy chain used by Gateway agen
5960

6061
If a tool is not allowed by policy, the endpoint returns **404**.
6162

63+
Important boundary notes:
64+
65+
- `POST /tools/invoke` is in the same trusted-operator bucket as other Gateway HTTP APIs such as `/v1/chat/completions`, `/v1/responses`, and `/api/channels/*`.
66+
- Exec approvals are operator guardrails, not a separate authorization boundary for this HTTP endpoint. If a tool is reachable here via Gateway auth + tool policy, `/tools/invoke` does not add an extra per-call approval prompt.
67+
- Do not share Gateway bearer credentials with untrusted callers. If you need separation across trust boundaries, run separate gateways (and ideally separate OS users/hosts).
68+
6269
Gateway HTTP also applies a hard deny list by default (even if session policy allows the tool):
6370

71+
- `cron`
6472
- `sessions_spawn`
6573
- `sessions_send`
6674
- `gateway`

‎docs/plugins/building-plugins.md‎

Lines changed: 18 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -181,7 +181,7 @@ my-plugin/
181181
// Correct: focused subpaths
182182
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
183183
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
184-
import { buildOauthProviderAuthResult } from "openclaw/plugin-sdk/provider-oauth";
184+
import { buildOauthProviderAuthResult } from "openclaw/plugin-sdk/provider-auth";
185185

186186
// Wrong: monolithic root (lint will reject this)
187187
import { ... } from "openclaw/plugin-sdk";
@@ -195,22 +195,23 @@ my-plugin/
195195
| --- | --- |
196196
| `plugin-sdk/plugin-entry` | Canonical `definePluginEntry` helper + provider/plugin entry types |
197197
| `plugin-sdk/core` | Channel entry helpers, channel builders, and shared base types |
198-
| `plugin-sdk/channel-setup` | Setup wizard adapters |
198+
| `plugin-sdk/runtime-store` | Safe module-level runtime storage |
199+
| `plugin-sdk/setup` | Shared setup-wizard helpers |
200+
| `plugin-sdk/channel-setup` | Channel setup adapters |
199201
| `plugin-sdk/channel-pairing` | DM pairing primitives |
200-
| `plugin-sdk/channel-reply-pipeline` | Reply prefix + typing wiring |
201-
| `plugin-sdk/channel-config-schema` | Config schema builders |
202-
| `plugin-sdk/channel-policy` | Group/DM policy helpers |
202+
| `plugin-sdk/channel-actions` | Shared `message` tool schema helpers |
203+
| `plugin-sdk/channel-contract` | Pure channel types |
203204
| `plugin-sdk/secret-input` | Secret input parsing/helpers |
204205
| `plugin-sdk/webhook-ingress` | Webhook request/target helpers |
205-
| `plugin-sdk/runtime-store` | Persistent plugin storage |
206-
| `plugin-sdk/allow-from` | Allowlist resolution |
207206
| `plugin-sdk/reply-payload` | Message reply types |
208-
| `plugin-sdk/provider-oauth` | OAuth login + PKCE helpers |
207+
| `plugin-sdk/provider-auth` | Provider auth and OAuth helpers |
209208
| `plugin-sdk/provider-onboard` | Provider onboarding config patches |
209+
| `plugin-sdk/provider-models` | Model catalog helpers |
210210
| `plugin-sdk/testing` | Test utilities |
211211
</Accordion>
212212

213-
Use the narrowest subpath that matches the job.
213+
Use the narrowest subpath that matches the job. For the curated map and
214+
examples, see [Plugin SDK Overview](/plugins/sdk-overview).
214215

215216
</Step>
216217

@@ -266,7 +267,7 @@ my-plugin/
266267
For unit tests, import test helpers from the testing surface:
267268

268269
```typescript
269-
import { createTestRuntime } from "openclaw/plugin-sdk/testing";
270+
import { createWindowsCmdShimFixture } from "openclaw/plugin-sdk/testing";
270271
```
271272

272273
</Step>
@@ -370,6 +371,13 @@ patterns is strongly recommended.
370371
## Related
371372

372373
- [Plugin SDK Migration](/plugins/sdk-migration) — migrating from deprecated compat surfaces
374+
- [Plugin SDK Overview](/plugins/sdk-overview) — public SDK map and subpath guidance
375+
- [Plugin Entry Points](/plugins/sdk-entrypoints) — `definePluginEntry` and `defineChannelPluginEntry`
376+
- [Plugin Runtime](/plugins/sdk-runtime) — injected runtime and runtime-store
377+
- [Plugin Setup](/plugins/sdk-setup) — setup, channel setup, and secret input helpers
378+
- [Channel Plugin SDK](/plugins/sdk-channel-plugins) — channel contracts and actions
379+
- [Provider Plugin SDK](/plugins/sdk-provider-plugins) — provider auth, onboarding, and catalogs
380+
- [Plugin SDK Testing](/plugins/sdk-testing) — public test helpers
373381
- [Plugin Architecture](/plugins/architecture) — internals and capability model
374382
- [Plugin Manifest](/plugins/manifest) — full manifest schema
375383
- [Plugin Agent Tools](/plugins/building-plugins#registering-agent-tools) — adding agent tools in a plugin

0 commit comments

Comments
 (0)