Skip to content

Commit a0fb7fb

Browse files
steipetesteipete
committed
refactor: centralize channel ingress access
1 parent 1725eeb commit a0fb7fb

250 files changed

Lines changed: 11345 additions & 8096 deletions

File tree

Some content is hidden

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

‎docs/.generated/plugin-sdk-api-baseline.sha256‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
1-
f303fc2fea17115736f9b7565ab2b6cfa07cfb46e5b3c804c55a945922f749db plugin-sdk-api-baseline.json
2-
90a4a9538691ee1af4d1fcf10b3b0c1d161e835c03e87b09dc0ff0020d1ded7a plugin-sdk-api-baseline.jsonl
1+
d0bbcee28603940444071492f65e293e708d2b437bdc6f0fb492fc41a0920760 plugin-sdk-api-baseline.json
2+
f6a73cf469f279671ab00ff5a0e95eb0ff89d8a8b9652cf1ff9cd983aa69093d plugin-sdk-api-baseline.jsonl

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

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,22 @@
5959
"source": "Channel message API",
6060
"target": "频道消息 API"
6161
},
62+
{
63+
"source": "Channel ingress API",
64+
"target": "频道入口 API"
65+
},
66+
{
67+
"source": "Channel access cleanup",
68+
"target": "频道访问清理"
69+
},
70+
{
71+
"source": "Ingress core shrink plan",
72+
"target": "入口核心精简计划"
73+
},
74+
{
75+
"source": "Ingress core shrink",
76+
"target": "入口核心精简"
77+
},
6278
{
6379
"source": "Talk mode",
6480
"target": "Talk 模式"

‎docs/channels/access-groups.md‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -125,7 +125,26 @@ Access groups are available in shared message-channel authorization paths, inclu
125125
- channel-specific per-room sender allowlists that use the same sender matching rules
126126
- command authorization paths that reuse message-channel sender allowlists
127127

128-
Channel support depends on whether that channel is wired through the shared OpenClaw sender-authorization helpers. Current bundled support includes Discord, Google Chat, Nostr, WhatsApp, Zalo, and Zalo Personal. Static `message.senders` groups are designed to be channel-agnostic, so new message channels should support them by using the shared plugin SDK helpers instead of custom allowlist expansion.
128+
Channel support depends on whether that channel is wired through the shared OpenClaw sender-authorization helpers. Current bundled support includes BlueBubbles, Discord, Feishu, Google Chat, iMessage, LINE, Mattermost, Microsoft Teams, Nextcloud Talk, Nostr, QQBot, Signal, WhatsApp, Zalo, and Zalo Personal. Static `message.senders` groups are designed to be channel-agnostic, so new message channels should support them by using the shared plugin SDK helpers instead of custom allowlist expansion.
129+
130+
## Plugin diagnostics
131+
132+
Plugin authors can inspect structured access-group state without expanding it back into a flat allowlist:
133+
134+
```typescript
135+
import { resolveAccessGroupAllowFromState } from "openclaw/plugin-sdk/security-runtime";
136+
137+
const state = await resolveAccessGroupAllowFromState({
138+
accessGroups: cfg.accessGroups,
139+
allowFrom: channelConfig.allowFrom,
140+
channel: "my-channel",
141+
accountId: "default",
142+
senderId,
143+
isSenderAllowed,
144+
});
145+
```
146+
147+
The result reports referenced, matched, missing, unsupported, and failed groups. Use this when you need diagnostics or conformance tests. Use `expandAllowFromWithAccessGroups(...)` only for compatibility paths that still expect a flat `allowFrom` array.
129148

130149
## Discord channel audiences
131150

‎docs/channels/discord.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -451,8 +451,8 @@ Example:
451451

452452
</Tab>
453453

454-
<Tab title="DM access groups">
455-
Discord DMs can use dynamic `accessGroup:<name>` entries in `channels.discord.allowFrom`.
454+
<Tab title="Access groups">
455+
Discord DMs and text command authorization can use dynamic `accessGroup:<name>` entries in `channels.discord.allowFrom`.
456456

457457
Access group names are shared across message channels. Use `type: "message.senders"` for a static group whose members are expressed in each channel's normal `allowFrom` syntax, or `type: "discord.channelAudience"` when a Discord channel's current `ViewChannel` audience should define membership dynamically. Shared access-group behavior is documented here: [Access groups](/channels/access-groups).
458458

‎docs/channels/imessage.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -217,7 +217,7 @@ If SIP-disabled isn't acceptable for your threat model:
217217

218218
Allowlist field: `channels.imessage.allowFrom`.
219219

220-
Allowlist entries can be handles or chat targets (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`).
220+
Allowlist entries can be handles, static sender access groups (`accessGroup:<name>`), or chat targets (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`).
221221

222222
</Tab>
223223

@@ -230,6 +230,8 @@ If SIP-disabled isn't acceptable for your threat model:
230230

231231
Group sender allowlist: `channels.imessage.groupAllowFrom`.
232232

233+
`groupAllowFrom` entries can also reference static sender access groups (`accessGroup:<name>`).
234+
233235
Runtime fallback: if `groupAllowFrom` is unset, iMessage group sender checks fall back to `allowFrom` when available.
234236
Runtime note: if `channels.imessage` is completely missing, runtime falls back to `groupPolicy="allowlist"` and logs a warning (even if `channels.defaults.groupPolicy` is set).
235237

‎docs/channels/line.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -139,6 +139,7 @@ Allowlists and policies:
139139
- `channels.line.groupPolicy`: `allowlist | open | disabled`
140140
- `channels.line.groupAllowFrom`: allowlisted LINE user IDs for groups
141141
- Per-group overrides: `channels.line.groups.<groupId>.allowFrom`
142+
- Static sender access groups can be referenced from `allowFrom`, `groupAllowFrom`, and per-group `allowFrom` with `accessGroup:<name>`.
142143
- Runtime note: if `channels.line` is completely missing, runtime falls back to `groupPolicy="allowlist"` for group checks (even if `channels.defaults.groupPolicy` is set).
143144

144145
LINE IDs are case-sensitive. Valid IDs look like:

‎docs/channels/mattermost.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -189,11 +189,13 @@ Notes:
189189
- `openclaw pairing list mattermost`
190190
- `openclaw pairing approve mattermost <CODE>`
191191
- Public DMs: `channels.mattermost.dmPolicy="open"` plus `channels.mattermost.allowFrom=["*"]`.
192+
- `channels.mattermost.allowFrom` accepts `accessGroup:<name>` entries. See [Access groups](/channels/access-groups).
192193

193194
## Channels (groups)
194195

195196
- Default: `channels.mattermost.groupPolicy = "allowlist"` (mention-gated).
196197
- Allowlist senders with `channels.mattermost.groupAllowFrom` (user IDs recommended).
198+
- `channels.mattermost.groupAllowFrom` accepts `accessGroup:<name>` entries. See [Access groups](/channels/access-groups).
197199
- Per-channel mention overrides live under `channels.mattermost.groups.<channelId>.requireMention` or `channels.mattermost.groups["*"].requireMention` for a default.
198200
- `@username` matching is mutable and only enabled when `channels.mattermost.dangerouslyAllowNameMatching: true`.
199201
- Open channels: `channels.mattermost.groupPolicy="open"` (mention-gated).

‎docs/channels/msteams.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -146,14 +146,14 @@ Disable with:
146146
**DM access**
147147

148148
- Default: `channels.msteams.dmPolicy = "pairing"`. Unknown senders are ignored until approved.
149-
- `channels.msteams.allowFrom` should use stable AAD object IDs.
149+
- `channels.msteams.allowFrom` should use stable AAD object IDs or static sender access groups such as `accessGroup:core-team`.
150150
- Do not rely on UPN/display-name matching for allowlists - they can change. OpenClaw disables direct name matching by default; opt in explicitly with `channels.msteams.dangerouslyAllowNameMatching: true`.
151151
- The wizard can resolve names to IDs via Microsoft Graph when credentials allow.
152152

153153
**Group access**
154154

155155
- Default: `channels.msteams.groupPolicy = "allowlist"` (blocked unless you add `groupAllowFrom`). Use `channels.defaults.groupPolicy` to override the default when unset.
156-
- `channels.msteams.groupAllowFrom` controls which senders can trigger in group chats/channels (falls back to `channels.msteams.allowFrom`).
156+
- `channels.msteams.groupAllowFrom` controls which senders or static sender access groups can trigger in group chats/channels (falls back to `channels.msteams.allowFrom`).
157157
- Set `groupPolicy: "open"` to allow any member (still mention-gated by default).
158158
- To allow **no channels**, set `channels.msteams.groupPolicy: "disabled"`.
159159

@@ -164,7 +164,7 @@ Example:
164164
channels: {
165165
msteams: {
166166
groupPolicy: "allowlist",
167-
groupAllowFrom: ["[email protected]"],
167+
groupAllowFrom: ["00000000-0000-0000-0000-000000000000", "accessGroup:core-team"],
168168
},
169169
},
170170
}

‎docs/channels/nextcloud-talk.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -157,6 +157,7 @@ Provider options:
157157
- `channels.nextcloud-talk.groupPolicy`: `allowlist | open | disabled`.
158158
- `channels.nextcloud-talk.groupAllowFrom`: group allowlist (user IDs).
159159
- `channels.nextcloud-talk.rooms`: per-room settings and allowlist.
160+
- Static sender access groups can be referenced from `allowFrom` and `groupAllowFrom` with `accessGroup:<name>`.
160161
- `channels.nextcloud-talk.historyLimit`: group history limit (0 disables).
161162
- `channels.nextcloud-talk.dmHistoryLimit`: DM history limit (0 disables).
162163
- `channels.nextcloud-talk.dms`: per-DM overrides (historyLimit).

‎docs/channels/qa-channel.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,14 @@ Account keys:
4444
- `botUserId` - Matrix-style bot user id used in target grammar.
4545
- `botDisplayName` - display name for outbound messages.
4646
- `pollTimeoutMs` - long-poll wait window. Integer between 100 and 30000.
47-
- `allowFrom` - sender allowlist (user ids or `"*"`).
47+
- `allowFrom` - sender allowlist (user ids or `"*"`). Direct messages and
48+
allowlisted group policy both use these synthetic sender ids.
49+
- `groupPolicy` - shared-room policy: `"open"` (default), `"allowlist"`, or
50+
`"disabled"`.
51+
- `groupAllowFrom` - optional shared-room sender allowlist. When omitted under
52+
`"allowlist"`, QA Channel falls back to `allowFrom`.
53+
- `groups.<room>.requireMention` - require a bot mention before replying in a
54+
specific group/channel room. `groups."*"` sets the default.
4855
- `defaultTo` - fallback target when none is supplied.
4956
- `actions.messages` / `actions.reactions` / `actions.search` / `actions.threads` - per-action tool gating.
5057

0 commit comments

Comments
 (0)