pico-engine 1.5.0 → 1.6.1

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.
Files changed (62) hide show
  1. package/README.md +41 -0
  2. package/dist/RulesetRegistryLoaderFs.js +2 -0
  3. package/dist/auth/AuthService.js +77 -13
  4. package/dist/bundledKrl.js +42 -0
  5. package/dist/identity/IdentityService.js +340 -0
  6. package/dist/identity/crossPico.js +238 -0
  7. package/dist/identity/dbHelpers.js +67 -0
  8. package/dist/identity/didcommIngressRoutes.js +44 -0
  9. package/dist/identity/didoModule.js +252 -0
  10. package/dist/identity/errors.js +11 -0
  11. package/dist/identity/establishSubscription.js +97 -0
  12. package/dist/identity/index.js +15 -0
  13. package/dist/identity/peerDid.js +9 -0
  14. package/dist/identity/skyIntro.js +194 -0
  15. package/dist/identity/skyProtocol.js +105 -0
  16. package/dist/identity/store.js +233 -0
  17. package/dist/identity/types.js +13 -0
  18. package/dist/identity/veramoDidComm.js +260 -0
  19. package/dist/identity/webvh.js +266 -0
  20. package/dist/identity/webvhCrypto.js +128 -0
  21. package/dist/identity/webvhRoutes.js +61 -0
  22. package/dist/index.js +26 -2
  23. package/dist/oauth/OAuthService.js +32 -0
  24. package/dist/provisionRoot.js +56 -18
  25. package/dist/server.js +52 -1
  26. package/dist/uiChannelPolicies.js +48 -0
  27. package/krl/io.picolabs.did-o.krl +5 -1
  28. package/krl/io.picolabs.pico-engine-ui.krl +106 -18
  29. package/krl/io.picolabs.subscription.krl +242 -23
  30. package/krl/io.picolabs.wrangler.krl +221 -12
  31. package/package.json +29 -6
  32. package/public/docs/krl/_sidebar.md +1 -0
  33. package/public/docs/krl/discovery.md +144 -0
  34. package/public/docs/krl/modules/ctx.md +8 -0
  35. package/public/docs/krl/modules/event.md +41 -0
  36. package/public/pico-engine-ui.css +1 -1
  37. package/public/pico-engine-ui.js +21 -18
  38. package/src/RulesetRegistryLoaderFs.ts +2 -0
  39. package/src/auth/AuthService.ts +109 -14
  40. package/src/bundledKrl.ts +42 -0
  41. package/src/identity/IdentityService.ts +571 -0
  42. package/src/identity/crossPico.ts +371 -0
  43. package/src/identity/dbHelpers.ts +51 -0
  44. package/src/identity/didcommIngressRoutes.ts +54 -0
  45. package/src/identity/didoModule.ts +388 -0
  46. package/src/identity/errors.ts +8 -0
  47. package/src/identity/establishSubscription.ts +160 -0
  48. package/src/identity/index.ts +24 -0
  49. package/src/identity/peerDid.ts +22 -0
  50. package/src/identity/skyIntro.ts +321 -0
  51. package/src/identity/skyProtocol.ts +192 -0
  52. package/src/identity/store.ts +343 -0
  53. package/src/identity/types.ts +63 -0
  54. package/src/identity/veramoDidComm.ts +363 -0
  55. package/src/identity/webvh.ts +325 -0
  56. package/src/identity/webvhCrypto.ts +200 -0
  57. package/src/identity/webvhRoutes.ts +64 -0
  58. package/src/index.ts +31 -2
  59. package/src/oauth/OAuthService.ts +36 -0
  60. package/src/provisionRoot.ts +75 -21
  61. package/src/server.ts +58 -1
  62. package/src/uiChannelPolicies.ts +49 -0
@@ -15,19 +15,22 @@ ruleset io.picolabs.wrangler {
15
15
  author "BYU Pico Lab"
16
16
 
17
17
  provides skyQuery, picoQuery,
18
- channels, createChannel, deleteChannel, //channel
18
+ channels, createChannel, updateChannel, deleteChannel, //channel
19
+ discoveryChannel, filterBindingsForCaller, //discovery
19
20
  rulesetConfig, rulesetMeta, installedRIDs, //ruleset
20
- children, parent_eci, name, myself //pico
21
+ children, parent_eci, name, myself, myDid, publicIntro, establishSubscription, callerDid //pico
21
22
 
22
23
  shares skyQuery, picoQuery,
23
24
  channels, //channel
25
+ discoveryChannel, filterBindingsForCaller, //discovery
24
26
  rulesetConfig, rulesetMeta,installedRIDs, //ruleset
25
- children, parent_eci, name, myself, id //pico
27
+ children, parent_eci, name, myself, myDid, publicIntro, establishSubscription, callerDid, id //pico
26
28
  }
27
29
  global {
28
30
  __testing = { "queries": [ {"name": "name"},
29
31
  {"name": "myself"},
30
32
  { "name": "channels", "args":["tags"] },
33
+ { "name": "discoveryChannel"},
31
34
  { "name": "installedRIDs"},
32
35
  {"name":"skyQuery", "args":["eci", "mod", "func", "params","_host","_path","_root_url"]},
33
36
  {"name":"children", "args":[]}
@@ -39,6 +42,8 @@ ruleset io.picolabs.wrangler {
39
42
  "attrs": [ "eci"] },
40
43
  { "domain": "wrangler", "name": "new_channel_request",
41
44
  "attrs": [ "tags", "eventPolicy", "queryPolicy" ] },
45
+ { "domain": "wrangler", "name": "channel_update_request",
46
+ "attrs": [ "eci", "tags", "eventPolicy", "queryPolicy" ] },
42
47
  { "domain": "wrangler", "name": "channel_deletion_request",
43
48
  "attrs": [ "eci" ] },
44
49
  { "domain": "wrangler", "name": "install_ruleset_request",
@@ -143,11 +148,12 @@ ruleset io.picolabs.wrangler {
143
148
  thisPico = ctx:channels.any(function(c){c{"id"}==eci})
144
149
  thisHost = _host.isnull() || _host == meta:host;
145
150
  web_hook = buildWebHook(eci, mod, func, _host, _path, _root_url)
151
+ queryArgs = params.defaultsTo({})
146
152
 
147
153
  response = thisPico => QUERY_SELF_INVALID_HTTP_MAP |
148
- isDid => dido:prepareQuery(eci, {"rid": mod, "name": func, "args": params}) |
149
- thisHost => processQueryResponse(ctx:query(eci, mod, func, {}.put(params))) |
150
- processHTTPResponse(http:get(web_hook, {}.put(params)))
154
+ isDid => dido:picoQuery(eci, {"rid": mod, "name": func, "args": queryArgs}) |
155
+ thisHost => processQueryResponse(ctx:query(eci, mod, func, {}.put(queryArgs))) |
156
+ processHTTPResponse(http:get(web_hook, {}.put(queryArgs)))
151
157
 
152
158
  response
153
159
  }
@@ -199,6 +205,115 @@ ruleset io.picolabs.wrangler {
199
205
  return channel
200
206
  }
201
207
 
208
+ updateChannel = defaction(eci, tags, eventPolicy, queryPolicy) {
209
+ ctx:putChannel(
210
+ eci=eci,
211
+ tags=tags,
212
+ eventPolicy=eventPolicy,
213
+ queryPolicy=queryPolicy
214
+ ) setting(channel)
215
+ return channel
216
+ }
217
+
218
+ // ********************************************************************************************
219
+ // *** Discovery ***
220
+ // ********************************************************************************************
221
+
222
+ discoveryEventPolicy = function() {
223
+ {
224
+ "allow": [{ "domain": "discovery", "name": "capabilities" }],
225
+ "deny": []
226
+ }
227
+ }
228
+
229
+ discoveryQueryPolicy = function() {
230
+ {
231
+ "allow": [],
232
+ "deny": [{ "rid": "*", "name": "*" }]
233
+ }
234
+ }
235
+
236
+ discoveryChannel = function() {
237
+ channels("discovery").head()
238
+ }
239
+
240
+ channelForEci = function(eci) {
241
+ ctx:channels.filter(function(c) {
242
+ c{"id"} == eci
243
+ }).head()
244
+ }
245
+
246
+ policyAllowsEvent = function(eventPolicy, domain, name) {
247
+ eventPolicy{"deny"}.any(function(p) {
248
+ (p{"domain"} == "*" || p{"domain"} == domain) &&
249
+ (p{"name"} == "*" || p{"name"} == name)
250
+ }) => false |
251
+ eventPolicy{"allow"}.any(function(p) {
252
+ (p{"domain"} == "*" || p{"domain"} == domain) &&
253
+ (p{"name"} == "*" || p{"name"} == name)
254
+ })
255
+ }
256
+
257
+ policyAllowsQuery = function(queryPolicy, rid, name) {
258
+ queryPolicy{"deny"}.any(function(p) {
259
+ (p{"rid"} == "*" || p{"rid"} == rid) &&
260
+ (p{"name"} == "*" || p{"name"} == name)
261
+ }) => false |
262
+ queryPolicy{"allow"}.any(function(p) {
263
+ (p{"rid"} == "*" || p{"rid"} == rid) &&
264
+ (p{"name"} == "*" || p{"name"} == name)
265
+ })
266
+ }
267
+
268
+ allowsEventForChannel = function(eci, domain, name) {
269
+ channel = channelForEci(eci)
270
+ channel.isnull() => false |
271
+ policyAllowsEvent(channel{"eventPolicy"}, domain, name)
272
+ }
273
+
274
+ allowsQueryForChannel = function(eci, rid, name) {
275
+ channel = channelForEci(eci)
276
+ channel.isnull() => false |
277
+ policyAllowsQuery(channel{"queryPolicy"}, rid, name)
278
+ }
279
+
280
+ dropTriggerBinding = function(notif, caller_eci) {
281
+ (notif{"trigger"}.isnull() ||
282
+ allowsEventForChannel(caller_eci, notif{"trigger"}{"domain"}, notif{"trigger"}{"name"})) =>
283
+ notif |
284
+ notif.delete("trigger")
285
+ }
286
+
287
+ dropForwardBinding = function(notif, caller_eci) {
288
+ (notif{"forward"}.isnull() ||
289
+ allowsEventForChannel(caller_eci, notif{"forward"}{"domain"}, notif{"forward"}{"name"})) =>
290
+ notif |
291
+ notif.delete("forward")
292
+ }
293
+
294
+ filterNotificationBindings = function(notif, caller_eci) {
295
+ notif.isnull() => null |
296
+ dropForwardBinding(dropTriggerBinding(notif, caller_eci), caller_eci)
297
+ }
298
+
299
+ filterBindingsBody = function(bindings, caller_eci, rid) {
300
+ {
301
+ "version": bindings{"version"},
302
+ "queries": bindings{"queries"}.defaultsTo([]).filter(function(q) {
303
+ allowsQueryForChannel(caller_eci, rid, q{"name"})
304
+ }),
305
+ "events": bindings{"events"}.defaultsTo([]).filter(function(e) {
306
+ allowsEventForChannel(caller_eci, e{"domain"}, e{"name"})
307
+ }),
308
+ "notifications": filterNotificationBindings(bindings{"notifications"}, caller_eci)
309
+ }
310
+ }
311
+
312
+ filterBindingsForCaller = function(bindings, caller_eci, rid) {
313
+ caller_eci.isnull() => bindings |
314
+ filterBindingsBody(bindings.defaultsTo({}), caller_eci, rid)
315
+ }
316
+
202
317
  // ********************************************************************************************
203
318
  // *** Picos ***
204
319
  // ********************************************************************************************
@@ -210,6 +325,30 @@ ruleset io.picolabs.wrangler {
210
325
  "eci":ent:eci
211
326
  }
212
327
  }
328
+
329
+ /** Portable did:webvh for this pico (Layer 2). */
330
+ myDid = function() {
331
+ dido:myDid()
332
+ }
333
+
334
+ /** True when this pico accepts unsolicited intro DIDComm on its did:webvh. */
335
+ publicIntro = function() {
336
+ dido:publicIntro()
337
+ }
338
+
339
+ setPublicIntro = defaction(enabled) {
340
+ dido:setPublicIntro(enabled)
341
+ }
342
+
343
+ /** Layer 2: create did:peer + internal Rx for a subscription bus map. */
344
+ establishSubscription = function(bus) {
345
+ dido:establishSubscription(bus)
346
+ }
347
+
348
+ /** did:webvh of the pico that sent the current event (layer2 cross-pico delivery). */
349
+ callerDid = function() {
350
+ event:attr("callerDid")
351
+ }
213
352
 
214
353
  children = function() {
215
354
  convert = function(eci){
@@ -339,6 +478,22 @@ ruleset io.picolabs.wrangler {
339
478
  }
340
479
  }
341
480
 
481
+ rule updateChannel {
482
+ select when wrangler channel_update_request
483
+ pre {
484
+ eci = event:attrs{"eci"}
485
+ tags = event:attrs{"tags"}
486
+ eventPolicy = event:attrs{"eventPolicy"}
487
+ queryPolicy = event:attrs{"queryPolicy"}
488
+ }
489
+ if eci && tags && eventPolicy && queryPolicy then
490
+ updateChannel(eci, tags, eventPolicy, queryPolicy) setting(channel)
491
+ fired {
492
+ raise wrangler event "channel_updated"
493
+ attributes event:attrs.put({"channel": channel})
494
+ }
495
+ }
496
+
342
497
  // ********************************************************************************************
343
498
  // *** Picos ***
344
499
  // ********************************************************************************************
@@ -347,10 +502,9 @@ ruleset io.picolabs.wrangler {
347
502
  rule createChild {
348
503
  select when wrangler new_child_request
349
504
  name re#.+# // required
350
- backgroundColor re#.*# // optional
505
+ backgroundColor re#.*# // optional (layout rule assigns palette color)
351
506
  pre {
352
507
  name = event:attrs{"name"}
353
- backgroundColor = event:attrs{"backgroundColor"} || "#87CEFA"
354
508
  engine_ui_rid = "io.picolabs.pico-engine-ui"
355
509
  engine_ui_ruleset = function(){
356
510
  the_ruleset = ctx:rulesets
@@ -389,7 +543,6 @@ ruleset io.picolabs.wrangler {
389
543
  name="box",
390
544
  attrs={
391
545
  "name": name,
392
- "backgroundColor": backgroundColor,
393
546
  "parentUiEci": parentUiEci
394
547
  }
395
548
  )
@@ -411,7 +564,6 @@ ruleset io.picolabs.wrangler {
411
564
  parts.splice(parts.length()-1,1,rid+".krl").join("/")
412
565
  }
413
566
  subs_url = sibling_ruleset_url("io.picolabs.subscription")
414
- did_o_url = sibling_ruleset_url("io.picolabs.did-o")
415
567
  pds_url = sibling_ruleset_url("io.picolabs.pds")
416
568
  }
417
569
  fired {
@@ -419,8 +571,6 @@ ruleset io.picolabs.wrangler {
419
571
  attributes {"url": pds_url}
420
572
  raise wrangler event "install_ruleset_request"
421
573
  attributes {"url": subs_url}
422
- raise wrangler event "install_ruleset_request"
423
- attributes {"url": did_o_url}
424
574
  ent:parent_eci := ctx:parent
425
575
  ent:name := event:attr("name")
426
576
  ent:id := ctx:picoId
@@ -482,4 +632,63 @@ ruleset io.picolabs.wrangler {
482
632
  "attrs":{"eci":my_eci}})
483
633
  }
484
634
 
635
+ rule ensure_discovery_channel_on_setup {
636
+ select when engine_ui setup
637
+ pre {
638
+ existing = discoveryChannel()
639
+ }
640
+ if existing.isnull() then
641
+ createChannel(["discovery"], discoveryEventPolicy(), discoveryQueryPolicy())
642
+ }
643
+
644
+ rule ensure_discovery_channel_on_initialized {
645
+ select when wrangler pico_initialized
646
+ pre {
647
+ existing = discoveryChannel()
648
+ }
649
+ if existing.isnull() then
650
+ createChannel(["discovery"], discoveryEventPolicy(), discoveryQueryPolicy())
651
+ }
652
+
653
+ rule ensure_discovery_channel_on_wrangler_installed {
654
+ select when wrangler ruleset_installed where event:attr("rids") >< ctx:rid
655
+ pre {
656
+ existing = discoveryChannel()
657
+ }
658
+ if existing.isnull() then
659
+ createChannel(["discovery"], discoveryEventPolicy(), discoveryQueryPolicy())
660
+ }
661
+
662
+ rule ensure_discovery_channel_on_engine_started {
663
+ select when engine started
664
+ pre {
665
+ existing = discoveryChannel()
666
+ }
667
+ if existing.isnull() then
668
+ createChannel(["discovery"], discoveryEventPolicy(), discoveryQueryPolicy())
669
+ }
670
+
671
+ rule wrangler_set_public_intro {
672
+ select when wrangler set_public_intro
673
+ setPublicIntro(event:attr("enabled"))
674
+ }
675
+
676
+ // ---- DIDComm ingress (folded from io.picolabs.did-o, Layer 2) ----
677
+
678
+ rule didcomm_init_routes_on_setup {
679
+ select when engine_ui setup
680
+ pre {
681
+ ping = dido:addRoute("https://didcomm.org/trust_ping/2.0/ping", "dido", "receive_trust_ping")
682
+ ping_response = dido:addRoute("https://didcomm.org/trust_ping/2.0/ping_response", "dido", "receive_trust_ping_response")
683
+ }
684
+ }
685
+
686
+ rule didcomm_route_message {
687
+ select when dido didcomm_message
688
+ pre {
689
+ response = dido:route(event:attrs.delete("_headers"))
690
+ }
691
+ if response then send_directive("response", {}.put(response))
692
+ }
693
+
485
694
  }//end ruleset
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pico-engine",
3
- "version": "1.5.0",
3
+ "version": "1.6.1",
4
4
  "description": "An implementation of the pico-engine targeting node.js",
5
5
  "repository": {
6
6
  "type": "git",
@@ -33,7 +33,6 @@
33
33
  "node": ">=20.0.0"
34
34
  },
35
35
  "scripts": {
36
- "prepare": "npm run build",
37
36
  "build": "rm -rf dist && tsc",
38
37
  "start": "npm run dev -s",
39
38
  "dev": "scriptsp -r dev:tsc dev:api",
@@ -43,15 +42,38 @@
43
42
  "test:auth": "ava reset-cache && ava --serial ./test/auth.ts --timeout=2m",
44
43
  "test:oauth": "ava reset-cache && ava --serial ./test/oauth.ts --timeout=2m",
45
44
  "test:acg": "ava reset-cache && ava --serial ./test/acg.ts --timeout=2m",
46
- "test:http": "ava reset-cache && ava --serial ./test/httpSurface.ts --timeout=2m"
45
+ "test:http": "ava reset-cache && ava --serial ./test/httpSurface.ts --timeout=2m",
46
+ "test:identity": "ava reset-cache && ava --serial ./test/identityStore.ts ./test/identityStoreEngine.ts --timeout=2m",
47
+ "test:dido": "ava reset-cache && ava --serial ./test/didoModule.ts --timeout=2m",
48
+ "test:webvh": "ava reset-cache && ava --serial ./test/webvh.ts --timeout=2m",
49
+ "test:didcomm": "ava reset-cache && ava --serial ./test/didcommIngress.ts --timeout=2m",
50
+ "test:establish-sub": "ava reset-cache && ava --serial ./test/establishSubscription.ts --timeout=2m",
51
+ "test:sky-intro": "ava reset-cache && ava --serial ./test/skyIntro.ts --timeout=2m",
52
+ "test:layer2-routing": "ava reset-cache && ava --serial ./test/layer2Routing.ts --timeout=2m",
53
+ "test:layer2-cancel": "ava reset-cache && ava --serial ./test/layer2Cancellation.ts --timeout=2m",
54
+ "test:layer2-wrangler": "ava reset-cache && ava --serial ./test/layer2Wrangler.ts --timeout=2m",
55
+ "test:layer2-policy": "ava reset-cache && ava --serial ./test/layer2ChannelPolicy.ts --timeout=2m",
56
+ "test:cross-engine": "ava reset-cache && ava --serial ./test/crossEngineSubscription.ts --timeout=3m",
57
+ "test:epic9": "ava reset-cache && ava --serial ./test/epic9Matrix.ts --timeout=3m"
47
58
  },
48
59
  "dependencies": {
60
+ "@noble/curves": "^1.9.0",
49
61
  "@simplewebauthn/server": "^13.2.2",
62
+ "@veramo/core": "^7.0.0",
63
+ "@veramo/did-comm": "^7.0.0",
64
+ "@veramo/did-manager": "^7.0.0",
65
+ "@veramo/did-provider-peer": "^7.0.0",
66
+ "@veramo/did-resolver": "^7.0.0",
67
+ "@veramo/key-manager": "^7.0.0",
68
+ "@veramo/kms-local": "^7.0.0",
69
+ "@veramo/utils": "^7.0.0",
50
70
  "body-parser": "^1.18.3",
51
71
  "charwise": "^3.0.1",
52
72
  "classic-level": "^1.3.0",
53
73
  "cross-fetch": "^4.0.0",
54
74
  "cuid": "^2.1.8",
75
+ "did-resolver": "^4.1.0",
76
+ "didwebvh-ts": "^2.8.0",
55
77
  "express": "^4.16.4",
56
78
  "helmet": "^7.1.0",
57
79
  "home-dir": "^1.0.0",
@@ -61,8 +83,8 @@
61
83
  "lodash": "^4.17.11",
62
84
  "make-dir": "^4.0.0",
63
85
  "minimist": "^1.2.5",
64
- "pico-engine-core": "^1.5.0",
65
- "pico-framework": "^0.8.0",
86
+ "pico-engine-core": "^1.6.0",
87
+ "pico-framework": "^0.8.1",
66
88
  "rotating-file-stream": "^1.4.1"
67
89
  },
68
90
  "devDependencies": {
@@ -81,6 +103,7 @@
81
103
  "ts"
82
104
  ],
83
105
  "require": [
106
+ "./test/helpers/testEnv.js",
84
107
  "ts-node/register",
85
108
  "./test/helpers/testEnv.ts"
86
109
  ],
@@ -89,5 +112,5 @@
89
112
  "!test/helpers/**/*"
90
113
  ]
91
114
  },
92
- "gitHead": "38f550eb9a0de399e9f1c4554176d4a7cc84d8c8"
115
+ "gitHead": "239f23e636291da954c9eca31ab2454e07193bfa"
93
116
  }
@@ -1,5 +1,6 @@
1
1
  - [KRL Manual](/krl/)
2
2
  - [Rulesets](/krl/rulesets)
3
+ - [Discovery](/krl/discovery)
3
4
  - [Standard Library](/krl/stdlib)
4
5
  - [Modules](/krl/modules)
5
6
  - [ctx](/krl/modules/ctx)
@@ -0,0 +1,144 @@
1
+ # Discovery
2
+
3
+ Every pico has a **`discovery`** channel. Integrators send a single event to learn what the pico can do. Each installed ruleset that participates in discovery responds with a **`discovery capability`** directive.
4
+
5
+ This is event-based (not a query on a specific ruleset) so the engine can aggregate responses from every ruleset that implements discovery.
6
+
7
+ ## Discovery channel
8
+
9
+ Wrangler creates a channel tagged `discovery` on every pico. Its policy allows **only** the discovery event:
10
+
11
+ | Direction | Allowed |
12
+ |-----------|---------|
13
+ | Events in | `discovery capabilities` |
14
+ | Queries | none |
15
+
16
+ Find the channel with `wrangler:discoveryChannel()` or `wrangler:channels(["discovery"])`.
17
+
18
+ ## Integrator flow
19
+
20
+ 1. Obtain the target pico's discovery channel ECI (via subscription metadata, parent query, etc.).
21
+ 2. Send `discovery capabilities` on that channel.
22
+ 3. Optionally include an **`eci`** attribute — the channel the integrator will use for subsequent queries and events on this pico.
23
+ 4. Collect **`discovery capability`** directives from the event response.
24
+
25
+ When `eci` is present, each ruleset filters its bindings so the integrator only sees capabilities that channel's policy **allows**. Denied operations are omitted, not listed and blocked later.
26
+
27
+ Example (HTTP):
28
+
29
+ ```http
30
+ POST /sky/event/{discovery_eci}/discovery/capabilities/wait
31
+ Content-Type: application/json
32
+
33
+ {"eci": "{caller_eci}"}
34
+ ```
35
+
36
+ ## Ruleset author pattern
37
+
38
+ Discovery is opt-in per ruleset. Add:
39
+
40
+ 1. An **`app`** map — short metadata (`name`, `version`, optional `title`, `description`, `iconURL`).
41
+ 2. A **`bindings()`** function — the integrator contract (queries, events, notifications).
42
+ 3. A **discovery rule** that selects on `discovery capabilities` and sends a directive.
43
+
44
+ ```krl
45
+ ruleset io.picolabs.myapp {
46
+ meta {
47
+ use module io.picolabs.wrangler alias wrangler
48
+ }
49
+ global {
50
+ app = {
51
+ "name": "myapp",
52
+ "title": "My App",
53
+ "version": "1.0",
54
+ "description": "One sentence explaining what this app does on the pico."
55
+ };
56
+
57
+ bindings = function() {
58
+ {
59
+ "version": 1,
60
+ "queries": [
61
+ {
62
+ "name": "getStatus",
63
+ "description": "Return the current status map."
64
+ }
65
+ ],
66
+ "events": [
67
+ {
68
+ "domain": "myapp",
69
+ "name": "refresh",
70
+ "attrs": [],
71
+ "description": "Ask the app to refresh its state."
72
+ }
73
+ ]
74
+ }
75
+ }
76
+ }
77
+
78
+ rule discovery {
79
+ select when discovery capabilities
80
+ send_directive("discovery capability", {
81
+ "app": app,
82
+ "rid": meta:rid,
83
+ "bindings": wrangler:filterBindingsForCaller(
84
+ bindings(),
85
+ event:attr("eci"),
86
+ meta:rid
87
+ ),
88
+ "iconURL": "https://example.com/myapp.svg"
89
+ });
90
+ }
91
+ }
92
+ ```
93
+
94
+ ### Bindings shape
95
+
96
+ `bindings()` describes what an integrator may use — not internal rule names.
97
+
98
+ | Key | Purpose |
99
+ |-----|---------|
100
+ | `version` | Bindings schema version (currently `1`) |
101
+ | `queries` | `[{"name": "...", "args": [...], "description": "..."}]` callable via `/sky/query/` |
102
+ | `events` | `[{"domain": "...", "name": "...", "attrs": [...], "description": "..."}]` sendable to this pico |
103
+ | `notifications` | Optional block with `trigger`, `forward`, and `channels` for notification routing |
104
+
105
+ ### App metadata
106
+
107
+ | Field | Purpose |
108
+ |-------|---------|
109
+ | `name` | Short id (e.g. `journal`) |
110
+ | `title` | Human-readable label (e.g. `Journal`) |
111
+ | `version` | App version string |
112
+ | `description` | What the app does on this pico — shown to integrators during discovery |
113
+
114
+ ### Policy filtering
115
+
116
+ Use `wrangler:filterBindingsForCaller(bindings, caller_eci, rid)` in your discovery rule:
117
+
118
+ - **`caller_eci`** — from `event:attr("eci")`; pass through when null (unfiltered).
119
+ - **`rid`** — `meta:rid` for this ruleset (used to check query policy).
120
+
121
+ Filtering uses `wrangler:allowsEventForChannel` and `wrangler:allowsQueryForChannel`, which evaluate the caller channel's policy from `ctx:channels` on this pico.
122
+
123
+ ## Directive: `discovery capability`
124
+
125
+ Each participating ruleset may emit one directive:
126
+
127
+ ```json
128
+ {
129
+ "name": "discovery capability",
130
+ "options": {
131
+ "app": {
132
+ "name": "myapp",
133
+ "title": "My App",
134
+ "version": "1.0",
135
+ "description": "One sentence explaining what this app does."
136
+ },
137
+ "rid": "io.picolabs.myapp",
138
+ "bindings": { "version": 1, "queries": [], "events": [] },
139
+ "iconURL": "https://example.com/myapp.svg"
140
+ }
141
+ }
142
+ ```
143
+
144
+ The engine merges directives from all selecting rules. Integrators should handle zero, one, or many capabilities per pico.
@@ -48,6 +48,14 @@ Raise an event to yourself. This event does not use a channel, only runs on the
48
48
  - `name` - String - The event name.
49
49
  - `attrs` - Map - The event attributes.
50
50
 
51
+ ## ctx:allowsEvent(eci, domain, name)
52
+
53
+ Return `true` when the given channel's event policy would allow an event with this domain and name. Returns `false` for unknown channels or denied events (never throws).
54
+
55
+ ## ctx:allowsQuery(eci, rid, name)
56
+
57
+ Return `true` when the given channel's query policy would allow this query. Returns `false` for unknown channels or denied queries (never throws).
58
+
51
59
  ## ctx:query(eci, rid, name, args = {})
52
60
 
53
61
  Query a local pico.
@@ -25,3 +25,44 @@ Get the event transaction id. `String` or `null`
25
25
  ## event:time
26
26
 
27
27
  Get the event timestamp as number of milliseconds since epoch. `Number` or `null`
28
+
29
+ ## event:send
30
+
31
+ Send an event to another pico. Action.
32
+
33
+ ```krl
34
+ event:send({
35
+ "eci": "<channel id>", // local or remote ECI
36
+ "domain": "wrangler",
37
+ "type": "ping", // alias: "name"
38
+ "attrs": { "key": "value" }
39
+ }, host) // optional host for remote ECI
40
+ ```
41
+
42
+ **DID-based (1.6+) — send by DID** (requires an established DID-based subscription):
43
+
44
+ ```krl
45
+ event:send({
46
+ "did": "did:peer:2....", // or did:webvh:...
47
+ "domain": "wrangler",
48
+ "type": "ping",
49
+ "attrs": {}
50
+ })
51
+ ```
52
+
53
+ **DID-based — send via established subscription map** (from `subscription:established()` etc.):
54
+
55
+ ```krl
56
+ event:send({
57
+ "sub": bus, // established subscription map
58
+ "domain": "wrangler",
59
+ "type": "ping",
60
+ "attrs": {}
61
+ })
62
+ ```
63
+
64
+ When `bus.layer2` is true (DID-based subscription), routing uses `Tx_did` and DIDComm (or verified local dispatch on the same engine). ECI-based subscriptions use `bus.Tx` and optional `bus.Tx_host` as before.
65
+
66
+ ## event:attr
67
+
68
+ Get a single attribute by name. `Function(name)` → value or `null`