pico-engine 1.9.5 → 1.10.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 +11 -5
- package/demos/bootstrap/com.example.visitors.bootstrap.krl +9 -5
- package/demos/child_tasks/com.example.task_runner.bootstrap.krl +10 -7
- package/demos/echo/com.example.echo.bootstrap.krl +10 -7
- package/demos/guard_rules/com.example.archive.bootstrap.krl +10 -7
- package/demos/json_query/README.md +11 -0
- package/demos/json_query/com.example.json_query.bootstrap.krl +84 -0
- package/demos/json_query/com.example.json_query.krl +162 -0
- package/demos/json_query/try-it.md +5 -0
- package/demos/kblog/com.example.kblog.bootstrap.krl +10 -7
- package/demos/layered_rulesets/com.example.invitations.bootstrap.krl +10 -7
- package/demos/score_tracker/com.example.score_tracker.bootstrap.krl +10 -7
- package/demos/secrets/com.example.notifier.bootstrap.krl +10 -7
- package/demos/try-it-order.json +1 -1
- package/demos/two_picos/com.example.two_picos.bootstrap.krl +5 -2
- package/demos/xmlui/com.example.thermostat.bootstrap.krl +10 -7
- package/dist/cli.js +5 -1
- package/dist/engineConfig.js +1 -1
- package/dist/identity/portableMove.js +5 -1
- package/dist/index.js +44 -12
- package/dist/internalAccess.js +110 -0
- package/dist/oauth/OAuthService.js +172 -10
- package/dist/oauth/acg.js +194 -24
- package/dist/oauth/cimd.js +381 -0
- package/dist/oauth/discovery.js +175 -0
- package/dist/runMcp.js +1 -1
- package/dist/server.js +197 -48
- package/dist/subtreeWrangler.js +8 -5
- package/dist/uiChannelPolicies.js +2 -0
- package/krl/io.picolabs.pds.krl +109 -21
- package/krl/io.picolabs.pico-engine-ui.krl +13 -7
- package/krl/io.picolabs.wrangler.krl +21 -9
- package/mcp/devResources.js +52 -0
- package/mcp/devTools.js +40 -9
- package/mcp/docs/CLAUDE.md +3 -2
- package/mcp/docs/cookbook/README.md +23 -0
- package/mcp/docs/cookbook/bootstrap/README.md +23 -0
- package/mcp/docs/cookbook/bootstrap/instructions.md +75 -0
- package/mcp/docs/cookbook/child_tasks/README.md +20 -0
- package/mcp/docs/cookbook/child_tasks/instructions.md +60 -0
- package/mcp/docs/cookbook/collection/README.md +21 -0
- package/mcp/docs/cookbook/collection/instructions.md +93 -0
- package/mcp/docs/cookbook/echo/README.md +19 -0
- package/mcp/docs/cookbook/echo/instructions.md +59 -0
- package/mcp/docs/cookbook/guard_rules/README.md +22 -0
- package/mcp/docs/cookbook/guard_rules/instructions.md +73 -0
- package/mcp/docs/cookbook/json_query/README.md +26 -0
- package/mcp/docs/cookbook/json_query/instructions.md +64 -0
- package/mcp/docs/cookbook/kblog/README.md +60 -0
- package/mcp/docs/cookbook/kblog/instructions.md +102 -0
- package/mcp/docs/cookbook/layered_rulesets/README.md +24 -0
- package/mcp/docs/cookbook/layered_rulesets/instructions.md +87 -0
- package/mcp/docs/cookbook/moving_picos/README.md +44 -0
- package/mcp/docs/cookbook/moving_picos/instructions.md +150 -0
- package/mcp/docs/cookbook/score_tracker/README.md +19 -0
- package/mcp/docs/cookbook/score_tracker/instructions.md +73 -0
- package/mcp/docs/cookbook/secrets/README.md +25 -0
- package/mcp/docs/cookbook/secrets/instructions.md +98 -0
- package/mcp/docs/cookbook/two_picos/README.md +20 -0
- package/mcp/docs/cookbook/two_picos/instructions.md +88 -0
- package/mcp/docs/cookbook/xmlui/README.md +23 -0
- package/mcp/docs/cookbook/xmlui/instructions.md +84 -0
- package/mcp/docs/developing/README.md +28 -0
- package/mcp/docs/developing/accepting-relationship-requests.md +65 -0
- package/mcp/docs/developing/arrays-and-maps.md +77 -0
- package/mcp/docs/developing/converting-time-formats.md +28 -0
- package/mcp/docs/developing/cookies-and-redirects.md +81 -0
- package/mcp/docs/developing/decoding-form-data.md +67 -0
- package/mcp/docs/developing/engine-log-files.md +34 -0
- package/mcp/docs/developing/event-loop.md +77 -0
- package/mcp/docs/developing/events-from-email.md +80 -0
- package/mcp/docs/developing/initializing-entity-variables.md +83 -0
- package/mcp/docs/developing/mcp-ai-tools.md +98 -0
- package/mcp/docs/developing/misconceptions.md +467 -0
- package/mcp/docs/developing/names-and-scope.md +44 -0
- package/mcp/docs/developing/postman.md +159 -0
- package/mcp/docs/developing/querying-another-pico.md +47 -0
- package/mcp/docs/developing/singleton-picos.md +36 -0
- package/mcp/docs/developing/tabular-data.md +67 -0
- package/mcp/docs/developing/tips.md +251 -0
- package/mcp/docs/developing/webhook-signatures.md +56 -0
- package/mcp/docs/developing/workflow.md +106 -0
- package/mcp/docs/exp/README.md +46 -0
- package/mcp/docs/exp/event.md +110 -0
- package/mcp/docs/exp/query.md +94 -0
- package/mcp/docs/lessons/README.md +59 -0
- package/mcp/docs/lessons/events-and-queries.md +247 -0
- package/mcp/docs/lessons/gossip.md +28 -0
- package/mcp/docs/lessons/modules-and-apis.md +270 -0
- package/mcp/docs/lessons/pico-based-systems.md +470 -0
- package/mcp/docs/lessons/pico-state.md +267 -0
- package/mcp/docs/lessons/pico-views.md +290 -0
- package/mcp/docs/lessons/quickstart.md +157 -0
- package/mcp/docs/lessons/relationships.md +530 -0
- package/mcp/docs/lessons/scatter-gather.md +362 -0
- package/mcp/docs/pico-engine.md +7 -5
- package/mcp/docs/pico-overview.md +3 -3
- package/mcp/docs/wrangler/README.md +47 -0
- package/mcp/docs/wrangler/channels.md +235 -0
- package/mcp/docs/wrangler/oauth.md +56 -0
- package/mcp/docs/wrangler/pds.md +423 -0
- package/mcp/docs/wrangler/portable-subtree.md +44 -0
- package/mcp/docs/wrangler/relationships.md +297 -0
- package/mcp/docs/wrangler/wrangler.md +253 -0
- package/mcp/docs/wrangler/xmlui.md +60 -0
- package/mcp/engineClient.js +57 -5
- package/mcp/mcpScopes.js +118 -0
- package/mcp/meshHttp.js +151 -45
- package/mcp/runStdio.js +2 -0
- package/mcp/subtreeTools.js +184 -0
- package/mcp/tryItTools.js +202 -0
- package/package.json +14 -8
- package/public/pico-engine-ui.js +26 -26
- package/src/cli.ts +6 -2
- package/src/engineConfig.ts +5 -2
- package/src/identity/portableMove.ts +6 -1
- package/src/index.ts +469 -430
- package/src/internalAccess.ts +127 -0
- package/src/oauth/OAuthService.ts +243 -11
- package/src/oauth/acg.ts +289 -25
- package/src/oauth/cimd.ts +508 -0
- package/src/oauth/discovery.ts +233 -0
- package/src/runMcp.ts +3 -1
- package/src/server.ts +252 -52
- package/src/subtreeWrangler.ts +17 -5
- package/src/uiChannelPolicies.ts +2 -0
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
# Managing channels
|
|
2
|
+
|
|
3
|
+
## What are pico channels?
|
|
4
|
+
|
|
5
|
+
A pico receives events and answers queries on its channels. A channel is one stream of communication with a pico, and a pico can have any number of them. Each channel has a policy that says which events and queries it accepts.
|
|
6
|
+
|
|
7
|
+
A channel is identified by its ECI (event channel identifier), a unique string such as `ckiz680qq000a7u2r8myeezof`. To use a channel you need only the ECI and the address of the pico's engine. Then you send events and queries to it [over HTTP](/exp/), or from KRL with `event:send` and `wrangler:picoQuery`. [Relationships](/wrangler/relationships) between picos are built on channels too.
|
|
8
|
+
|
|
9
|
+
## Why channels
|
|
10
|
+
|
|
11
|
+
Imagine a pico for a lamp. It lets some parties check whether the lamp is on, and others turn it on and off.
|
|
12
|
+
|
|
13
|
+
For each party that may control the lamp, the lamp pico makes a channel that accepts `lamp:on` and `lamp:off` events, and gives that party the ECI. For parties that may only check, it makes channels that allow only an `isLampOn` query.
|
|
14
|
+
|
|
15
|
+
Because each party has its own channel, the lamp pico can restrict or delete one party's channel, say one that flashes the light too fast, without affecting anyone else.
|
|
16
|
+
|
|
17
|
+
## Kinds of channels
|
|
18
|
+
|
|
19
|
+
Every channel has an ECI, one or more tags, and a policy. Tags are how you find a channel without knowing its ECI. The policy says what the channel may be used for. A pico's **Channels** tab in the developer UI lists them all.
|
|
20
|
+
|
|
21
|
+
### Family channels
|
|
22
|
+
|
|
23
|
+
Family channels have the tag `system`. They can only be used inside the engine, by the right pico, and they allow any event or query from it:
|
|
24
|
+
|
|
25
|
+
- **Self** (`system, self`): every pico has one, and its ECI is the pico's id. It identifies the pico.
|
|
26
|
+
- **Child** (`system, child`): every pico except the root has one. Its parent uses it to send this pico events and queries.
|
|
27
|
+
- **Parent** (`system, parent`): a pico has one for each child. The child uses it to reach its parent.
|
|
28
|
+
|
|
29
|
+
### Other channels Wrangler makes
|
|
30
|
+
|
|
31
|
+
Every pico also has these:
|
|
32
|
+
|
|
33
|
+
- **Developer UI** (`engine, ui`): what the developer UI uses for this pico. It allows the UI's own events and queries.
|
|
34
|
+
- **Discovery** (`discovery`): lets anyone ask what the pico can do.
|
|
35
|
+
- **DIDComm ingress** (`didcomm, ingress`): where DID-based relationship traffic from other engines arrives.
|
|
36
|
+
- **Well-known** (`wellknown_rx, tx_rx`): accepts requests for classic (ECI-based) relationships.
|
|
37
|
+
- **PDS** (`pds`): `pds` events and `io.picolabs.pds` queries; see [Pico data store](/wrangler/pds).
|
|
38
|
+
|
|
39
|
+
### External channels
|
|
40
|
+
|
|
41
|
+
Every other channel can be used by other picos on the same engine, picos on other engines, or any system on the internet. Each external channel defines an API for the pico: the rulesets installed decide what the pico can do, and the channel's policy decides how much of that this channel can reach.
|
|
42
|
+
|
|
43
|
+
## Creating a channel
|
|
44
|
+
|
|
45
|
+
### In the developer UI
|
|
46
|
+
|
|
47
|
+
The **Channels** tab has a form for a new channel: tags, an event policy, and a query policy. The engine assigns the ECI. Check the box beside a channel to see its policies.
|
|
48
|
+
|
|
49
|
+
For the lamp, one channel might allow `lamp:*` events, for trusted parties. Another might allow only the `isLampOn` query and could be shared more widely. If a party misbehaves, delete its channel and make a new one; give the new ECI only to the parties who should still have it.
|
|
50
|
+
|
|
51
|
+
### From KRL, synchronously
|
|
52
|
+
|
|
53
|
+
`wrangler:createChannel(tags, eventPolicy, queryPolicy)` creates a channel and returns it. The ruleset needs `use module io.picolabs.wrangler alias wrangler`.
|
|
54
|
+
|
|
55
|
+
```krl
|
|
56
|
+
rule create_limited_use_channel {
|
|
57
|
+
select when lamp read_only_channel_needed
|
|
58
|
+
pre {
|
|
59
|
+
tags = ["lamp", "read-only"]
|
|
60
|
+
eventPolicy = {"allow": [], "deny": [{"domain": "*", "name": "*"}]}
|
|
61
|
+
queryPolicy = {"allow": [{"rid": meta:rid, "name": "isLampOn"}], "deny": []}
|
|
62
|
+
}
|
|
63
|
+
every {
|
|
64
|
+
wrangler:createChannel(tags, eventPolicy, queryPolicy) setting(channel)
|
|
65
|
+
send_directive("new channel", {"eci": channel{"id"}})
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
The directive gives the new ECI to whoever sent the event: a trusted page, say, that builds a link for checking the lamp.
|
|
71
|
+
|
|
72
|
+
Pass `rawBody: true` on `wrangler:new_channel_request`, or as the last argument of `wrangler:createChannel`, when the channel receives a webhook whose signature covers the exact request body. `event:raw_body()` is then that body. On every other channel it is `null`. The Channels tab has the same checkbox. See [Webhook signatures](/developing/webhook-signatures).
|
|
73
|
+
|
|
74
|
+
A ruleset often creates its channel when it's installed, from a rule that selects its own `wrangler:ruleset_installed`. See the [Bootstrap and channels](/cookbook/bootstrap/) demo, which also updates the channel instead of making a duplicate when the rule runs again.
|
|
75
|
+
|
|
76
|
+
### From KRL, asynchronously
|
|
77
|
+
|
|
78
|
+
Raise `wrangler:new_channel_request`. Any attributes you add are passed through to `wrangler:channel_created`, which carries the new `channel`:
|
|
79
|
+
|
|
80
|
+
```krl
|
|
81
|
+
raise wrangler event "new_channel_request" attributes {
|
|
82
|
+
"tags": ["lamp", "read-only"],
|
|
83
|
+
"eventPolicy": {"allow": [], "deny": [{"domain": "*", "name": "*"}]},
|
|
84
|
+
"queryPolicy": {"allow": [{"rid": meta:rid, "name": "isLampOn"}], "deny": []},
|
|
85
|
+
"co_id": meta:rid
|
|
86
|
+
}
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
```krl
|
|
90
|
+
rule on_new_channel {
|
|
91
|
+
select when wrangler channel_created where event:attr("co_id") == meta:rid
|
|
92
|
+
pre {
|
|
93
|
+
channel = event:attr("channel").klog("New channel")
|
|
94
|
+
}
|
|
95
|
+
always {
|
|
96
|
+
ent:read_only_eci := channel{"id"}
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
The channel looks like this:
|
|
102
|
+
|
|
103
|
+
```json
|
|
104
|
+
{
|
|
105
|
+
"id": "ckj081v5a0093fi2r9es49i77",
|
|
106
|
+
"tags": ["lamp", "read-only"],
|
|
107
|
+
"eventPolicy": {"allow": [], "deny": [{"domain": "*", "name": "*"}]},
|
|
108
|
+
"queryPolicy": {"allow": [{"rid": "lamp_ruleset", "name": "isLampOn"}], "deny": []},
|
|
109
|
+
"familyChannelPicoID": null
|
|
110
|
+
}
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
## Updating a channel
|
|
114
|
+
|
|
115
|
+
Sometimes a channel should change rather than be replaced: tighter or looser policies as trust changes, different tags, or the `oauth-webhook` tag for OAuth client credentials. Updating keeps the ECI, so anything that already uses the channel (links, relationships, stored credentials) keeps working.
|
|
116
|
+
|
|
117
|
+
Family channels (tagged `system`) can't be updated; the engine manages them. Channels you created can.
|
|
118
|
+
|
|
119
|
+
### In the developer UI
|
|
120
|
+
|
|
121
|
+
On the **Channels** tab, check the box beside a channel. Editable channels have an **Edit channel** form: tags (comma-separated, with a shortcut for `oauth-webhook`), and the event and query policies. With the `oauth-webhook` tag, a **Webhook OAuth** panel appears below the form, for creating credentials and minting tokens.
|
|
122
|
+
|
|
123
|
+
### From KRL, synchronously
|
|
124
|
+
|
|
125
|
+
`wrangler:updateChannel(eci, tags, eventPolicy, queryPolicy)` replaces the channel's tags and policies and returns the updated channel. All four arguments are required: it replaces, it doesn't merge, so pass the whole policies even to change one thing. This adds the `oauth-webhook` tag and keeps the rest:
|
|
126
|
+
|
|
127
|
+
```krl
|
|
128
|
+
rule protect_webhook_channel {
|
|
129
|
+
select when myapp webhook_protection_needed
|
|
130
|
+
pre {
|
|
131
|
+
eci = event:attr("eci")
|
|
132
|
+
chann = wrangler:channels().filter(function(c) { c{"id"} == eci }).head()
|
|
133
|
+
}
|
|
134
|
+
if chann then every {
|
|
135
|
+
wrangler:updateChannel(eci, chann{"tags"}.append("oauth-webhook"), chann{"eventPolicy"}, chann{"queryPolicy"}) setting(updated)
|
|
136
|
+
send_directive("channel updated", {"eci": updated{"id"}, "tags": updated{"tags"}})
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Adding `oauth-webhook` makes the channel require an access token. Until you create credentials for it, in the developer UI or with [`io.picolabs.oauth`](/wrangler/oauth), outside requests on it are refused.
|
|
142
|
+
|
|
143
|
+
### From KRL, asynchronously
|
|
144
|
+
|
|
145
|
+
Raise `wrangler:channel_update_request` with `eci`, `tags`, `eventPolicy`, and `queryPolicy`. Wrangler raises `wrangler:channel_updated`, with your attributes passed through and the updated `channel`.
|
|
146
|
+
|
|
147
|
+
### Update, or delete and recreate?
|
|
148
|
+
|
|
149
|
+
To revoke a party's access, deleting the channel and making a new one is simplest. To change what a channel allows, while the people using it keep using it, update it.
|
|
150
|
+
|
|
151
|
+
## Deleting a channel
|
|
152
|
+
|
|
153
|
+
`wrangler:deleteChannel(eci)` deletes a channel. Or raise `wrangler:channel_deletion_request` with its `eci`:
|
|
154
|
+
|
|
155
|
+
```krl
|
|
156
|
+
raise wrangler event "channel_deletion_request" attributes {"eci": old_eci, "co_id": meta:rid}
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Wrangler raises `wrangler:channel_deleted` with the same attributes. To delete channels by their tags, find them first with `wrangler:channels(tags)`.
|
|
160
|
+
|
|
161
|
+
## Channel attributes
|
|
162
|
+
|
|
163
|
+
| Attribute | Meaning |
|
|
164
|
+
|-----------|---------|
|
|
165
|
+
| `id` | The ECI: a globally unique identifier. Anyone who knows it and can reach the engine can send the channel events and queries, so treat it as a capability |
|
|
166
|
+
| `tags` | One or more tags, for finding the channel. `wrangler:channels(tags)` finds the channels with exactly those tags |
|
|
167
|
+
| `eventPolicy` | Which events the channel accepts |
|
|
168
|
+
| `queryPolicy` | Which queries the channel accepts |
|
|
169
|
+
|
|
170
|
+
## Policies
|
|
171
|
+
|
|
172
|
+
A policy has an `allow` list and a `deny` list. An event policy's rules name a `domain` and a `name`; a query policy's rules name a `rid` and a `name`. Every rule needs both fields, and `"*"` matches anything. An event or query is accepted if it matches a rule in `allow` and none in `deny`. `deny` wins.
|
|
173
|
+
|
|
174
|
+
Allow only `foo:bar`:
|
|
175
|
+
|
|
176
|
+
```json
|
|
177
|
+
"eventPolicy": {
|
|
178
|
+
"allow": [{"domain": "foo", "name": "bar"}],
|
|
179
|
+
"deny": []
|
|
180
|
+
}
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
Allow every `foo` event except `foo:bar`, and also `aaa:bbb`:
|
|
184
|
+
|
|
185
|
+
```json
|
|
186
|
+
"eventPolicy": {
|
|
187
|
+
"allow": [
|
|
188
|
+
{"domain": "foo", "name": "*"},
|
|
189
|
+
{"domain": "aaa", "name": "bbb"}
|
|
190
|
+
],
|
|
191
|
+
"deny": [
|
|
192
|
+
{"domain": "foo", "name": "bar"}
|
|
193
|
+
]
|
|
194
|
+
}
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
| Event | Result |
|
|
198
|
+
|-------|--------|
|
|
199
|
+
| `foo:foo`, `foo:wat` | Allowed |
|
|
200
|
+
| `foo:bar` | Denied: it matches `deny` |
|
|
201
|
+
| `aaa:bbb` | Allowed |
|
|
202
|
+
| `aaa:ccc`, `zzz:wat` | Denied: nothing in `allow` matches |
|
|
203
|
+
|
|
204
|
+
Allow everything except `system` events and `danger:nuke`:
|
|
205
|
+
|
|
206
|
+
```json
|
|
207
|
+
"eventPolicy": {
|
|
208
|
+
"allow": [{"domain": "*", "name": "*"}],
|
|
209
|
+
"deny": [
|
|
210
|
+
{"domain": "system", "name": "*"},
|
|
211
|
+
{"domain": "danger", "name": "nuke"}
|
|
212
|
+
]
|
|
213
|
+
}
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
Query policies work the same way, with `rid` instead of `domain`. A channel that allows everything:
|
|
217
|
+
|
|
218
|
+
```json
|
|
219
|
+
{
|
|
220
|
+
"eventPolicy": {"allow": [{"domain": "*", "name": "*"}], "deny": []},
|
|
221
|
+
"queryPolicy": {"allow": [{"rid": "*", "name": "*"}], "deny": []}
|
|
222
|
+
}
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
Give each channel the least it needs. A pico's schema can build a policy that allows exactly its documented API; see the [Bootstrap and channels](/cookbook/bootstrap/) demo and `wrangler:channelSchema(eci)`.
|
|
226
|
+
|
|
227
|
+
## Using channels
|
|
228
|
+
|
|
229
|
+
- **Over HTTP**: events at `/sky/event/<eci>/...` and queries at `/sky/query/<eci>/...`. See the [Event Exchange Protocol](/exp/).
|
|
230
|
+
- **`event:send`**, from KRL, to a channel on this engine or another.
|
|
231
|
+
- **`wrangler:picoQuery`**, from KRL, to call a function on another pico. See [The wrangler ruleset](/wrangler/wrangler).
|
|
232
|
+
- **The developer UI's Testing tab**, which sends events and queries on a channel you pick.
|
|
233
|
+
- **`raise`** in a postlude, which is handled on the same pico, as if it came in on the channel of the event being handled (`meta:eci`).
|
|
234
|
+
|
|
235
|
+
For every channel event and function, see the [wrangler API reference](/rulesets/io.picolabs.wrangler).
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# OAuth: io.picolabs.oauth
|
|
2
|
+
|
|
3
|
+
*Optional. Not installed by default. Install it on the root pico only. API reference: [io.picolabs.oauth](/rulesets/io.picolabs.oauth).*
|
|
4
|
+
|
|
5
|
+
`io.picolabs.oauth` turns on OAuth for a mesh: once it is installed on the mesh's root pico, most requests to `/sky/*` need an access token (a bearer token). It also holds the mesh's OAuth configuration.
|
|
6
|
+
|
|
7
|
+
Without it, a channel's policy is the only gate on `/sky/*`: anyone with the ECI can use what the policy allows. The developer UI and the engine's own calls use passkey sessions on `/c/*`, and OAuth doesn't change that.
|
|
8
|
+
|
|
9
|
+
## Install it
|
|
10
|
+
|
|
11
|
+
On the root pico's **Rulesets** tab, install `https://<your engine>/krl/io.picolabs.oauth.krl`. To turn OAuth off for the mesh again, uninstall it.
|
|
12
|
+
|
|
13
|
+
## What needs a token
|
|
14
|
+
|
|
15
|
+
| Channel | Needs a bearer token on `/sky/*`? |
|
|
16
|
+
|---------|-----------------------------------|
|
|
17
|
+
| Tagged `didcomm` and `ingress` | No: DIDComm traffic between engines |
|
|
18
|
+
| Tagged `oauth-webhook` | Yes, always, even without this ruleset |
|
|
19
|
+
| Tagged `mesh-oauth-exempt` | No: opts out of the mesh lock |
|
|
20
|
+
| Any other, with this ruleset on the root | Yes |
|
|
21
|
+
| Any other, without it | No |
|
|
22
|
+
|
|
23
|
+
Use `mesh-oauth-exempt` for webhook channels whose senders can't add an `Authorization` header. Their event policy still applies. If a channel has both `oauth-webhook` and `mesh-oauth-exempt`, `oauth-webhook` wins.
|
|
24
|
+
|
|
25
|
+
## Two kinds of credentials
|
|
26
|
+
|
|
27
|
+
| Grant | For | Client id | Reaches |
|
|
28
|
+
|-------|-----|-----------|---------|
|
|
29
|
+
| Client credentials | Incoming webhooks (from services such as GitHub or Stripe) | The channel's ECI | That one channel |
|
|
30
|
+
| Authorization code with PKCE | Apps such as Home Assistant | `app_…` | The whole mesh |
|
|
31
|
+
|
|
32
|
+
**Webhook credentials.** Tag a channel `oauth-webhook`. On the **Channels** tab, create credentials for it: the client id is the ECI, and the secret is shown once. Exchange them for a token at `POST /oauth/token` with `grant_type` `client_credentials`. The token (`oat_…`) works only on `/sky/*` for that ECI. Family, relationship, and system channels can't have credentials.
|
|
33
|
+
|
|
34
|
+
**Apps.** With this ruleset installed, register an app under **Settings** → **OAuth apps**, with its redirect URIs. The app sends the user to `/oauth/authorize`, the user approves with their passkey, and the app exchanges the code for tokens at `/oauth/token`. A public app's access token lasts one hour. Refreshing returns a new refresh token and invalidates the old one. Presenting that old refresh token again revokes the new one too.
|
|
35
|
+
|
|
36
|
+
## From KRL
|
|
37
|
+
|
|
38
|
+
The ruleset shares functions for the mesh's state, for rulesets on the root pico:
|
|
39
|
+
|
|
40
|
+
| Function | Returns |
|
|
41
|
+
|----------|---------|
|
|
42
|
+
| `meshEnabled()` | Whether OAuth is on for this mesh |
|
|
43
|
+
| `meshRequiresOAuth(eci)` | Whether a request on that channel needs a token |
|
|
44
|
+
| `channelStatus(eci)` | A channel's OAuth status |
|
|
45
|
+
| `createChannelSecret(eci)`, `revokeChannelSecret(eci)`, `revokeTokens(eci)` | Manage a webhook channel's credentials |
|
|
46
|
+
|
|
47
|
+
Creating a new channel secret revokes the tokens already made from the old one.
|
|
48
|
+
|
|
49
|
+
## Effects elsewhere
|
|
50
|
+
|
|
51
|
+
- [Pico views](/pico-views) on an OAuth mesh need an access token in the browser; see their OAuth section.
|
|
52
|
+
- The Try It! demos aren't meant for OAuth meshes: their pages send no token.
|
|
53
|
+
- The channel MCP server (`/mcp/:eci`) and the whole-mesh server (`/mcp/mesh/:eci`) need a bearer token. Connecting Claude or another remote client is [AI tools over MCP](/developing/mcp-ai-tools). A request without a token gets `401` and `WWW-Authenticate: Bearer resource_metadata="…", scope="mesh:read mesh:act"`. The metadata URL is `/.well-known/oauth-protected-resource/mcp/{eci}` (and `…/mcp/mesh/{eci}` for the whole-mesh endpoint). The authorization server document is `/.well-known/oauth-authorization-server`. PKCE is S256 only. A token is bound to the `resource` it was issued for: `{engine}/sky` on Sky routes, `{engine}/mcp/{eci}` on that channel's MCP URL, or `{engine}/mcp/mesh/{eci}` on that mesh URL (authorization-code tokens only). A token with no `resource` (a webhook or an older app token) still works on `/sky/*` and is rejected at MCP. `mesh:read` covers schemas and queries; `mesh:act` covers events. A call that needs a scope the token does not have gets `403` and `error="insufficient_scope"`. `mesh:admin` is reserved and unlocks nothing in this release. A client-credentials token for a channel MCP URL receives `mesh:read` and `mesh:act` when the client does not name a scope.
|
|
54
|
+
- A `client_id` that is an https URL is fetched as a Client ID Metadata Document. The approval screen shows that client's name, host, and page, and the mesh being approved. Pre-registered apps are unchanged.
|
|
55
|
+
|
|
56
|
+
The package README's OAuth section has the HTTP details for every grant.
|