@grwnd/openclaw-governance 1.4.2 → 1.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +122 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
# @grwnd/openclaw-governance
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@grwnd/openclaw-governance)
|
|
4
|
+
[](../../LICENSE)
|
|
5
|
+
|
|
6
|
+
OpenClaw identity bridge plugin for [@grwnd/pi-governance](https://github.com/Grwnd-AI/pi-governance).
|
|
7
|
+
|
|
8
|
+
Parses OpenClaw session keys (WhatsApp, Discord, Slack, Telegram) and maps channel users to governance roles — so pi-governance enforces the right RBAC policy per user without any manual env var setup.
|
|
9
|
+
|
|
10
|
+
## How it works
|
|
11
|
+
|
|
12
|
+
```
|
|
13
|
+
OpenClaw session_start
|
|
14
|
+
→ @grwnd/openclaw-governance plugin
|
|
15
|
+
→ parse sessionKey "agent:<id>:whatsapp:dm:+15550123"
|
|
16
|
+
→ lookup "whatsapp:+15550123" in openclaw-users.yaml
|
|
17
|
+
→ write process.env.GRWND_USER, GRWND_ROLE, GRWND_ORG_UNIT
|
|
18
|
+
→ @grwnd/pi-governance Pi extension
|
|
19
|
+
→ EnvIdentityProvider reads the env vars
|
|
20
|
+
→ governance enforced with correct role
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Quick start
|
|
24
|
+
|
|
25
|
+
### 1. Install both packages
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
# Install the governance Pi extension
|
|
29
|
+
pi install npm:@grwnd/pi-governance
|
|
30
|
+
|
|
31
|
+
# Install the OpenClaw identity bridge plugin
|
|
32
|
+
openclaw plugins install @grwnd/openclaw-governance
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
### 2. Create a users mapping file
|
|
36
|
+
|
|
37
|
+
Create `openclaw-users.yaml` alongside your OpenClaw config:
|
|
38
|
+
|
|
39
|
+
```yaml
|
|
40
|
+
users:
|
|
41
|
+
# WhatsApp — key by phone number
|
|
42
|
+
whatsapp:+15550123:
|
|
43
|
+
role: report_author
|
|
44
|
+
org_unit: field-ops
|
|
45
|
+
|
|
46
|
+
# Discord — key by user ID
|
|
47
|
+
discord:428374928374:
|
|
48
|
+
role: analyst
|
|
49
|
+
|
|
50
|
+
# Slack — key by member ID
|
|
51
|
+
slack:U04ABCD1234:
|
|
52
|
+
role: project_lead
|
|
53
|
+
org_unit: engineering
|
|
54
|
+
|
|
55
|
+
# Fallback for unknown users (remove to deny access)
|
|
56
|
+
default:
|
|
57
|
+
role: analyst
|
|
58
|
+
org_unit: default
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Keys are `<channel>:<peerId>` — the channel name and the platform-specific user identifier.
|
|
62
|
+
|
|
63
|
+
### 3. Configure the plugin
|
|
64
|
+
|
|
65
|
+
In your OpenClaw config, point to the users file:
|
|
66
|
+
|
|
67
|
+
```json
|
|
68
|
+
{
|
|
69
|
+
"plugins": {
|
|
70
|
+
"grwnd-openclaw-governance": {
|
|
71
|
+
"users_file": "./openclaw-users.yaml"
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
If `users_file` is omitted, it defaults to `./openclaw-users.yaml` in the current working directory.
|
|
78
|
+
|
|
79
|
+
### 4. Set up governance rules
|
|
80
|
+
|
|
81
|
+
Create your pi-governance config and rules as normal — see the [pi-governance docs](https://grwnd-ai.github.io/pi-governance/guide/quickstart). The roles you assign in `openclaw-users.yaml` must match roles defined in `governance-rules.yaml`.
|
|
82
|
+
|
|
83
|
+
### 5. Verify
|
|
84
|
+
|
|
85
|
+
When a WhatsApp user sends a message to your OpenClaw agent, you'll see in the audit log:
|
|
86
|
+
|
|
87
|
+
```json
|
|
88
|
+
{
|
|
89
|
+
"event": "session_start",
|
|
90
|
+
"userId": "whatsapp:+15550123",
|
|
91
|
+
"role": "report_author",
|
|
92
|
+
"orgUnit": "field-ops"
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## Session key formats
|
|
97
|
+
|
|
98
|
+
| Format | Example |
|
|
99
|
+
| ------ | ---------------------------------------------------- |
|
|
100
|
+
| DM | `agent:<agentId>:<channel>:dm:<peerId>` |
|
|
101
|
+
| Group | `agent:<agentId>:<channel>:group:<groupId>:<peerId>` |
|
|
102
|
+
|
|
103
|
+
The plugin ignores keys it cannot parse (e.g. `agent:<id>:main` for direct operator access), leaving the env vars unset so pi-governance falls through to its next identity provider.
|
|
104
|
+
|
|
105
|
+
## API
|
|
106
|
+
|
|
107
|
+
The plugin exports its internals for programmatic use:
|
|
108
|
+
|
|
109
|
+
```typescript
|
|
110
|
+
import { parseSessionKey, loadUsers, lookupUser } from '@grwnd/openclaw-governance';
|
|
111
|
+
|
|
112
|
+
const parsed = parseSessionKey('agent:abc:whatsapp:dm:+15550123');
|
|
113
|
+
// { agentId: 'abc', channel: 'whatsapp', chatType: 'dm', peerId: '+15550123' }
|
|
114
|
+
|
|
115
|
+
const config = loadUsers('./openclaw-users.yaml');
|
|
116
|
+
const user = lookupUser(config, 'whatsapp', '+15550123');
|
|
117
|
+
// { role: 'report_author', org_unit: 'field-ops' }
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
## License
|
|
121
|
+
|
|
122
|
+
[Apache-2.0](../../LICENSE)
|