pico-engine 1.6.4 → 1.8.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.
Files changed (98) hide show
  1. package/README.md +13 -8
  2. package/dist/RulesetRegistryLoaderFs.js +14 -2
  3. package/dist/auth/cookies.js +32 -0
  4. package/dist/auth/index.js +6 -1
  5. package/dist/channelIdentityPolicy.js +22 -0
  6. package/dist/cli.js +104 -69
  7. package/dist/engineConfig.js +280 -0
  8. package/dist/identity/IdentityService.js +90 -0
  9. package/dist/identity/crossPico.js +24 -8
  10. package/dist/identity/didoModule.js +80 -18
  11. package/dist/identity/establishSubscription.js +2 -2
  12. package/dist/identity/identityPortable.js +92 -0
  13. package/dist/identity/index.js +10 -1
  14. package/dist/identity/localPeerReconcile.js +65 -0
  15. package/dist/identity/peerDid4.js +175 -0
  16. package/dist/identity/peerDid4Create.js +90 -0
  17. package/dist/identity/portableExportPrepare.js +196 -0
  18. package/dist/identity/portableMove.js +87 -0
  19. package/dist/identity/skyIntro.js +6 -3
  20. package/dist/identity/skyProtocol.js +26 -1
  21. package/dist/identity/skyRotation.js +121 -0
  22. package/dist/identity/store.js +5 -1
  23. package/dist/identity/subscriptionEntSync.js +72 -0
  24. package/dist/identity/veramoDidComm.js +41 -2
  25. package/dist/identity/webvh.js +4 -2
  26. package/dist/identity/webvhRelocation.js +115 -0
  27. package/dist/index.js +82 -22
  28. package/dist/logging.js +8 -12
  29. package/dist/oauth/OAuthService.js +6 -2
  30. package/dist/policyConfigFromJson.js +112 -0
  31. package/dist/runMcp.js +27 -0
  32. package/dist/server.js +56 -24
  33. package/dist/subtreeWrangler.js +180 -0
  34. package/dist/uiChannelPolicies.js +15 -0
  35. package/krl/io.picolabs.oauth.krl +41 -2
  36. package/krl/io.picolabs.pds.krl +131 -10
  37. package/krl/io.picolabs.pico-engine-ui.krl +209 -21
  38. package/krl/io.picolabs.portable_subtree.krl +97 -0
  39. package/krl/io.picolabs.subscription.krl +180 -72
  40. package/krl/io.picolabs.wrangler.krl +296 -57
  41. package/mcp/devResources.js +118 -0
  42. package/mcp/devTools.js +351 -0
  43. package/mcp/engineClient.js +133 -0
  44. package/mcp/meshHttp.js +137 -0
  45. package/mcp/meshTools.js +189 -0
  46. package/mcp/runStdio.js +34 -0
  47. package/mcp/schemaToZod.js +56 -0
  48. package/package.json +20 -8
  49. package/public/docs/_sidebar.md +2 -1
  50. package/public/docs/llms-full.txt +479 -0
  51. package/public/docs/llms.txt +37 -0
  52. package/public/docs/openapi.yaml +78 -0
  53. package/public/docs/pico-engine.md +235 -4
  54. package/public/docs/pico-overview.md +117 -0
  55. package/public/docs/pico.md +3 -1
  56. package/public/docs/rulesets/README.md +25 -0
  57. package/public/docs/rulesets/io.picolabs.oauth.md +71 -0
  58. package/public/docs/rulesets/io.picolabs.pds.md +327 -0
  59. package/public/docs/rulesets/io.picolabs.pico-engine-ui.md +65 -0
  60. package/public/docs/rulesets/io.picolabs.portable_subtree.md +94 -0
  61. package/public/docs/rulesets/io.picolabs.subscription.md +398 -0
  62. package/public/docs/rulesets/io.picolabs.wrangler.md +471 -0
  63. package/public/pico-engine-ui.css +1 -1
  64. package/public/pico-engine-ui.js +28 -26
  65. package/src/RulesetRegistryLoaderFs.ts +18 -3
  66. package/src/auth/cookies.ts +34 -0
  67. package/src/auth/index.ts +7 -0
  68. package/src/channelIdentityPolicy.ts +29 -0
  69. package/src/cli.ts +68 -37
  70. package/src/engineConfig.ts +345 -0
  71. package/src/identity/IdentityService.ts +189 -1
  72. package/src/identity/crossPico.ts +57 -8
  73. package/src/identity/didoModule.ts +140 -23
  74. package/src/identity/establishSubscription.ts +2 -2
  75. package/src/identity/identityPortable.ts +153 -0
  76. package/src/identity/index.ts +14 -0
  77. package/src/identity/localPeerReconcile.ts +97 -0
  78. package/src/identity/peerDid4.ts +197 -0
  79. package/src/identity/peerDid4Create.ts +121 -0
  80. package/src/identity/portableExportPrepare.ts +302 -0
  81. package/src/identity/portableMove.ts +193 -0
  82. package/src/identity/skyIntro.ts +11 -11
  83. package/src/identity/skyProtocol.ts +46 -0
  84. package/src/identity/skyRotation.ts +211 -0
  85. package/src/identity/store.ts +5 -1
  86. package/src/identity/subscriptionEntSync.ts +97 -0
  87. package/src/identity/veramoDidComm.ts +52 -2
  88. package/src/identity/webvh.ts +4 -4
  89. package/src/identity/webvhRelocation.ts +167 -0
  90. package/src/index.ts +119 -25
  91. package/src/logging.ts +8 -14
  92. package/src/oauth/OAuthService.ts +11 -3
  93. package/src/policyConfigFromJson.ts +131 -0
  94. package/src/runMcp.ts +30 -0
  95. package/src/server.ts +79 -26
  96. package/src/subtreeWrangler.ts +278 -0
  97. package/src/uiChannelPolicies.ts +15 -0
  98. package/krl/io.picolabs.did-o.krl +0 -349
@@ -20,28 +20,67 @@ ruleset io.picolabs.oauth {
20
20
  }
21
21
 
22
22
  global {
23
- /** True when this ruleset is installed on the pico (mesh OAuth opt-in marker). */
23
+ /**
24
+ * True when this ruleset is installed on the pico. Its presence is the mesh's
25
+ * opt-in to OAuth.
26
+ * @returns Boolean
27
+ */
24
28
  meshEnabled = function() {
25
29
  true
26
30
  }
27
31
 
28
- /** True when the mesh root has io.picolabs.oauth (mesh lock may still be skipped via mesh-oauth-exempt on a channel). */
32
+ /**
33
+ * True when external /sky/* requests on this channel need a Bearer token: the
34
+ * mesh root has io.picolabs.oauth installed and the channel is not tagged
35
+ * mesh-oauth-exempt or didcomm+ingress.
36
+ * @param eci String "channel to check"
37
+ * @returns Boolean
38
+ */
29
39
  meshRequiresOAuth = function(eci) {
30
40
  oauth:meshRequiresOAuth(eci)
31
41
  }
32
42
 
43
+ /**
44
+ * OAuth webhook status of a channel: whether it is eligible (tagged
45
+ * oauth-webhook), whether OAuth is enabled on it, and whether a client secret
46
+ * exists. Includes a reason when the channel is not eligible or not found.
47
+ * @param eci String "channel to inspect"
48
+ * @returns Map "{ eligible, enabled, hasSecret, reason? }"
49
+ */
33
50
  channelStatus = function(eci) {
34
51
  oauth:channelStatus(eci)
35
52
  }
36
53
 
54
+ /**
55
+ * Create (or replace) the Client Credentials secret for a webhook channel and
56
+ * return it. The secret is returned only here; the engine stores a hash, so
57
+ * save it now. Only works for a channel on this pico or one of its descendants.
58
+ * Changes state despite being a query.
59
+ * @param eci String "webhook channel (tagged oauth-webhook); also the client_id"
60
+ * @returns Map "{ client_id, client_secret }"
61
+ */
37
62
  createChannelSecret = function(eci) {
38
63
  oauth:createChannelSecret(eci)
39
64
  }
40
65
 
66
+ /**
67
+ * Revoke a webhook channel's client secret so it can no longer obtain tokens.
68
+ * Only works for a channel on this pico or one of its descendants. Changes
69
+ * state despite being a query.
70
+ * @param eci String "webhook channel"
71
+ * @returns Map "{ ok: true }"
72
+ */
41
73
  revokeChannelSecret = function(eci) {
42
74
  oauth:revokeChannelSecret(eci)
43
75
  }
44
76
 
77
+ /**
78
+ * Revoke all access tokens issued for a channel, without removing its secret.
79
+ * Only works for a channel on this pico or one of its descendants. Changes
80
+ * state despite being a query.
81
+ * @param eci String "channel whose tokens to revoke"
82
+ * @returns Map "{ ok: true }"
83
+ */
45
84
  revokeTokens = function(eci) {
46
85
  oauth:revokeTokens(eci)
47
86
  }
@@ -4,21 +4,21 @@ ruleset io.picolabs.pds {
4
4
  description <<
5
5
  Pico Data Services (PDS), a common data base structure for all rulesets to use.
6
6
  >>
7
- author "PICOLABS"
7
+ author "Picolabs"
8
8
 
9
9
  use module io.picolabs.wrangler alias wrangler
10
10
 
11
11
  logging on
12
12
 
13
13
  provides items, get_keys,
14
- profile,
15
- settings, get_config_value, get_setting_data_value, config_value, settings_names,
16
- getChannelEci
14
+ profile,
15
+ settings, get_config_value, get_setting_data_value, config_value, settings_names,
16
+ getChannelEci
17
17
 
18
18
  shares items, get_keys,
19
- profile,
20
- settings, get_config_value, get_setting_data_value, config_value, settings_names,
21
- getChannelEci
19
+ profile,
20
+ settings, get_config_value, get_setting_data_value, config_value, settings_names,
21
+ getChannelEci
22
22
 
23
23
  }
24
24
 
@@ -61,7 +61,17 @@ ruleset io.picolabs.pds {
61
61
  // Default avatar: embedded SVG (no external URL dependency)
62
62
  defaultUnknownPhoto = "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA2NCA2NCI+PHJlY3Qgd2lkdGg9IjY0IiBoZWlnaHQ9IjY0IiBmaWxsPSIjZWNlZmYxIi8+PGNpcmNsZSBjeD0iMzIiIGN5PSIyMiIgcj0iMTEiIGZpbGw9IiM3ODkwOWMiLz48ZWxsaXBzZSBjeD0iMzIiIGN5PSI1NCIgcng9IjE4IiByeT0iMTQiIGZpbGw9IiM3ODkwOWMiLz48L3N2Zz4="
63
63
 
64
- items = function (namespace, key){
64
+ /**
65
+ * Read general (namespaced) data. With no namespace, returns all of it; with a
66
+ * namespace, that namespace's map; with both, one value. status is "failed"
67
+ * when no namespace is given (the data is still returned).
68
+ * @param namespace String "namespace to read; omit for everything"
69
+ * @param key String "key within the namespace; omit for the whole namespace"
70
+ * @returns Map "{ status, general }"
71
+ * @example "one namespace" { "namespace": "<app>" }
72
+ * @example "one value" { "namespace": "<app>", "key": "<key>" }
73
+ */
74
+ items = function (namespace = null, key = null){
65
75
  item = function(namespace, keyvalue) {
66
76
  ent:general{[namespace, keyvalue]}
67
77
  };
@@ -77,11 +87,24 @@ ruleset io.picolabs.pds {
77
87
  };
78
88
  }
79
89
 
90
+ /**
91
+ * Keys stored in one namespace of the general data.
92
+ * @param namespace String
93
+ * @returns Array
94
+ */
80
95
  get_keys = function(namespace) {
81
96
  ent:general{namespace}.keys()
82
97
  }
83
98
 
84
- profile = function(key){
99
+ /**
100
+ * This pico's profile: name, description, photo, email, phone, and the
101
+ * _created / _modified timestamps. With a key, just that field.
102
+ * @param key String "profile field to read; omit for the whole profile"
103
+ * @returns Map "{ status, profile }"
104
+ * @example "whole profile" {}
105
+ * @example "name only" { "key": "name" }
106
+ */
107
+ profile = function(key = null){
85
108
  get_profile = function(k) {
86
109
  ent:profile{k};
87
110
  };
@@ -95,6 +118,10 @@ ruleset io.picolabs.pds {
95
118
  };
96
119
  };
97
120
 
121
+ /**
122
+ * Rulesets that have stored settings here, with their display names.
123
+ * @returns Array "[ { setRID, setName } ]"
124
+ */
98
125
  settings_names = function() {
99
126
  ent:settings.keys().map(function(setRID) {
100
127
  setName = ent:settings{[setRID, "name"]};
@@ -105,7 +132,18 @@ ruleset io.picolabs.pds {
105
132
  })
106
133
  };
107
134
 
108
- settings = function(Rid, Key, detail){
135
+ /**
136
+ * Read per-ruleset settings. No arguments: all settings. Rid: that ruleset's
137
+ * settings record ({ name, rid, data, schema }). Rid and Key: one field of the
138
+ * record. Rid, Key, and detail: the value of data key `detail` (Key is ignored).
139
+ * @param Rid String "ruleset id whose settings to read"
140
+ * @param Key String "field of the settings record (name, rid, data, schema)"
141
+ * @param detail String "key within the record's data map"
142
+ * @returns Map "{ status, settings }"
143
+ * @example "one ruleset" { "Rid": "<rid>" }
144
+ * @example "one data value" { "Rid": "<rid>", "Key": "data", "detail": "<key>" }
145
+ */
146
+ settings = function(Rid = null, Key = null, detail = null){
109
147
  get_setting_all = function() {
110
148
  ent:settings
111
149
  };
@@ -142,19 +180,43 @@ ruleset io.picolabs.pds {
142
180
  ent:settings{[setRID, "data", setKey]}
143
181
  };
144
182
 
183
+ /**
184
+ * One configuration value from a ruleset's settings data.
185
+ * @param setRID String "ruleset id"
186
+ * @param setKey String "data key"
187
+ * @returns Any
188
+ */
145
189
  get_setting_data_value = function(setRID, setKey) {
146
190
  setting_data_value(setRID, setKey)
147
191
  }
148
192
 
193
+ /**
194
+ * One configuration value from the calling ruleset's own settings data. Meant
195
+ * to be used as a module function (use module io.picolabs.pds): the ruleset is
196
+ * the caller's, from meta:callingRID().
197
+ * @param setKey String "data key"
198
+ * @returns Any
199
+ */
149
200
  config_value = function(setKey) {
150
201
  setRID = meta:callingRID();
151
202
  ent:settings{[setRID, "data", setKey]}
152
203
  };
153
204
 
205
+ /**
206
+ * Same as config_value: a value from the calling ruleset's own settings data,
207
+ * for use as a module function.
208
+ * @param setKey String "data key"
209
+ * @returns Any
210
+ */
154
211
  get_config_value = function(setKey) {
155
212
  config_value(setKey)
156
213
  }
157
214
 
215
+ /**
216
+ * The ECI of this pico's pds channel, which allows all pds events and queries.
217
+ * Created when this ruleset is installed.
218
+ * @returns String
219
+ */
158
220
  getChannelEci = function() {
159
221
  ent:pds_channel_eci
160
222
  }
@@ -170,6 +232,14 @@ ruleset io.picolabs.pds {
170
232
 
171
233
  //------------------------------- ent: general
172
234
 
235
+ /**
236
+ * Store one value in the general data under namespace and key, replacing any
237
+ * existing value. Raises pds:data_added.
238
+ * @attr namespace String "namespace, e.g. your app's name"
239
+ * @attr key String
240
+ * @attr value Any "value to store"
241
+ * @example "store a value" { "namespace": "<app>", "key": "<key>", "value": "<value>" }
242
+ */
173
243
  rule add_item {
174
244
  select when pds new_data_available
175
245
  pre {
@@ -185,6 +255,15 @@ ruleset io.picolabs.pds {
185
255
  }
186
256
  }
187
257
 
258
+ /**
259
+ * Merge fields into a stored map: each entry of value is written under
260
+ * namespace / key / field, leaving other fields alone. Raises pds:data_updated
261
+ * once per field.
262
+ * @attr namespace String
263
+ * @attr key String
264
+ * @attr value Map "fields to set on the stored map"
265
+ * @example "set fields" { "namespace": "<app>", "key": "<key>", "value": { "<field>": "<value>" } }
266
+ */
188
267
  rule update_item {
189
268
  select when pds updated_data_available
190
269
  foreach(event:attr("value") || {}) setting(avalue, akey)
@@ -200,6 +279,11 @@ ruleset io.picolabs.pds {
200
279
  }
201
280
  }
202
281
 
282
+ /**
283
+ * Delete one key from a namespace of the general data. Raises pds:data_deleted.
284
+ * @attr namespace String
285
+ * @attr key String
286
+ */
203
287
  rule remove_item {
204
288
  select when pds remove_old_data
205
289
  pre{
@@ -214,6 +298,10 @@ ruleset io.picolabs.pds {
214
298
  }
215
299
  }
216
300
 
301
+ /**
302
+ * Delete a whole namespace of the general data. Raises pds:namespace_deleted.
303
+ * @attr namespace String
304
+ */
217
305
  rule remove_namespace {
218
306
  select when pds remove_namespace
219
307
  pre{
@@ -227,6 +315,13 @@ ruleset io.picolabs.pds {
227
315
  }
228
316
  }
229
317
 
318
+ /**
319
+ * Replace an entire namespace of the general data with a map. Raises
320
+ * pds:new_map_added.
321
+ * @attr namespace String
322
+ * @attr mapvalues String "the new namespace contents, as a JSON-encoded map"
323
+ * @example "replace namespace" { "namespace": "<app>", "mapvalues": "{\"<key>\": \"<value>\"}" }
324
+ */
230
325
  rule itemed_mapped {
231
326
  select when pds map_item
232
327
  pre{
@@ -241,6 +336,19 @@ ruleset io.picolabs.pds {
241
336
  }
242
337
  }
243
338
 
339
+ /**
340
+ * Update this pico's profile. Send only the fields to change; fields not sent
341
+ * keep their current values. _created is set on the first update and _modified
342
+ * on every update. Raises pds:profile_updated with _status "success", or
343
+ * "failure" when no fields were sent.
344
+ * @attr name String optional "display name"
345
+ * @attr description String optional
346
+ * @attr photo String optional "image URL or data: URI"
347
+ * @attr email String optional
348
+ * @attr phone String optional
349
+ * @example "rename" { "name": "<name>" }
350
+ * @example "contact info" { "email": "<email>", "phone": "<phone>" }
351
+ */
244
352
  rule update_profile {
245
353
  select when pds updated_profile
246
354
  pre {
@@ -279,6 +387,17 @@ ruleset io.picolabs.pds {
279
387
  }
280
388
  }
281
389
 
390
+ /**
391
+ * Create or update a ruleset's settings record, and optionally set one data
392
+ * value in it. Raises pds:settings_added.
393
+ * @attr keyed_rid String "ruleset id the settings belong to"
394
+ * @attr name String "display name for the settings"
395
+ * @attr schema Array optional "settings schema, stored as given"
396
+ * @attr data_key String optional "data key to set"
397
+ * @attr value Any optional "value for data_key"
398
+ * @example "register settings" { "keyed_rid": "<rid>", "name": "<display name>" }
399
+ * @example "set one value" { "keyed_rid": "<rid>", "name": "<display name>", "data_key": "<key>", "value": "<value>" }
400
+ */
282
401
  rule settings_added {
283
402
  select when pds add_settings
284
403
  pre {
@@ -331,6 +450,8 @@ ruleset io.picolabs.pds {
331
450
  }
332
451
  }
333
452
 
453
+ // Erases all general data, the profile, and all settings with no confirmation.
454
+ // Deliberately not discoverable.
334
455
  rule clearPDS {
335
456
  select when pds clear_all_data
336
457
  noop()