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
package/src/index.ts
CHANGED
|
@@ -1,430 +1,469 @@
|
|
|
1
|
-
import { krl, KrlLogger, makeKrlLogger } from "krl-stdlib";
|
|
2
|
-
import * as _ from "lodash";
|
|
3
|
-
import * as makeDir from "make-dir";
|
|
4
|
-
import * as path from "path";
|
|
5
|
-
import type { Server } from "http";
|
|
6
|
-
import { PicoEngineCore, RulesetRegistry } from "pico-engine-core";
|
|
7
|
-
import {
|
|
8
|
-
EventPolicyRule,
|
|
9
|
-
PicoDbKey,
|
|
10
|
-
PicoFramework,
|
|
11
|
-
PolicyCeiling,
|
|
12
|
-
QueryPolicyRule,
|
|
13
|
-
} from "pico-framework";
|
|
14
|
-
import { AuthService, WebAuthnAdapter, makeWebAuthnAdapter } from "./auth";
|
|
15
|
-
import {
|
|
16
|
-
IdentityStore,
|
|
17
|
-
IdentityService,
|
|
18
|
-
initDidoModule,
|
|
19
|
-
createSubtreePortableHooks,
|
|
20
|
-
} from "./identity";
|
|
21
|
-
import { registerWebvhRoutes } from "./identity/webvhRoutes";
|
|
22
|
-
import { OAuthService, initOAuthModule } from "./oauth";
|
|
23
|
-
import {
|
|
24
|
-
picoLogEntries,
|
|
25
|
-
makeEngineLogWriter,
|
|
26
|
-
resolveEngineLogFilePath,
|
|
27
|
-
resolvePicoLogsReadPath,
|
|
28
|
-
} from "./logging";
|
|
29
|
-
import { openClassicLevelWithRecovery } from "./levelDb";
|
|
30
|
-
import { provisionRoot, uiECIForRoot } from "./provisionRoot";
|
|
31
|
-
import { createRulesetRegistryLoaderFs } from "./RulesetRegistryLoaderFs";
|
|
32
|
-
import { resolveBundledKrlUrl } from "./bundledKrl";
|
|
33
|
-
import { wranglerSubtreeImportServices } from "./subtreeWrangler";
|
|
34
|
-
import {
|
|
35
|
-
import {
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
const
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
*
|
|
52
|
-
*
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
*
|
|
59
|
-
*
|
|
60
|
-
*
|
|
61
|
-
*
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
*
|
|
68
|
-
*
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
*
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
*
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
* When
|
|
104
|
-
*
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
*
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
*
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
/**
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
)
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
const
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
log
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
)
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
const
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
}
|
|
1
|
+
import { krl, KrlLogger, makeKrlLogger } from "krl-stdlib";
|
|
2
|
+
import * as _ from "lodash";
|
|
3
|
+
import * as makeDir from "make-dir";
|
|
4
|
+
import * as path from "path";
|
|
5
|
+
import type { Server } from "http";
|
|
6
|
+
import { PicoEngineCore, RulesetRegistry, warmPdsSecretLog } from "pico-engine-core";
|
|
7
|
+
import {
|
|
8
|
+
EventPolicyRule,
|
|
9
|
+
PicoDbKey,
|
|
10
|
+
PicoFramework,
|
|
11
|
+
PolicyCeiling,
|
|
12
|
+
QueryPolicyRule,
|
|
13
|
+
} from "pico-framework";
|
|
14
|
+
import { AuthService, WebAuthnAdapter, makeWebAuthnAdapter } from "./auth";
|
|
15
|
+
import {
|
|
16
|
+
IdentityStore,
|
|
17
|
+
IdentityService,
|
|
18
|
+
initDidoModule,
|
|
19
|
+
createSubtreePortableHooks,
|
|
20
|
+
} from "./identity";
|
|
21
|
+
import { registerWebvhRoutes } from "./identity/webvhRoutes";
|
|
22
|
+
import { OAuthService, initOAuthModule } from "./oauth";
|
|
23
|
+
import {
|
|
24
|
+
picoLogEntries,
|
|
25
|
+
makeEngineLogWriter,
|
|
26
|
+
resolveEngineLogFilePath,
|
|
27
|
+
resolvePicoLogsReadPath,
|
|
28
|
+
} from "./logging";
|
|
29
|
+
import { openClassicLevelWithRecovery } from "./levelDb";
|
|
30
|
+
import { provisionRoot, uiECIForRoot } from "./provisionRoot";
|
|
31
|
+
import { createRulesetRegistryLoaderFs } from "./RulesetRegistryLoaderFs";
|
|
32
|
+
import { resolveBundledKrlUrl } from "./bundledKrl";
|
|
33
|
+
import { wranglerSubtreeImportServices } from "./subtreeWrangler";
|
|
34
|
+
import { writeInternalToken } from "./internalAccess";
|
|
35
|
+
import { server } from "./server";
|
|
36
|
+
import {
|
|
37
|
+
installEngineRuntimeSettings,
|
|
38
|
+
resolveEngineSettings,
|
|
39
|
+
ShowTryItMenu,
|
|
40
|
+
} from "./engineConfig";
|
|
41
|
+
const charwise = require("charwise");
|
|
42
|
+
const safeJsonCodec = require("level-json-coerce-null");
|
|
43
|
+
|
|
44
|
+
const version = require("../package.json").version;
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* Configuration options that may be set by the user
|
|
48
|
+
*/
|
|
49
|
+
export interface PicoEngineConfiguration {
|
|
50
|
+
/**
|
|
51
|
+
* The absolute path to the folder where the engine should store the database and logs.
|
|
52
|
+
*
|
|
53
|
+
* Default: "~/.pico-engine/"
|
|
54
|
+
*/
|
|
55
|
+
home?: string;
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* The port number the http server should listen on.
|
|
59
|
+
*
|
|
60
|
+
* If you want an available port assigned to you, set it to 0
|
|
61
|
+
*
|
|
62
|
+
* Default: 3000
|
|
63
|
+
*/
|
|
64
|
+
port?: number;
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* The base url others should use when addressing your engine.
|
|
68
|
+
*
|
|
69
|
+
* Default: "http://localhost:3000"
|
|
70
|
+
*/
|
|
71
|
+
base_url?: string;
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* Provide any custom krl modules
|
|
75
|
+
*/
|
|
76
|
+
modules?: { [domain: string]: krl.Module };
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* Trust event.time input. Used for testing
|
|
80
|
+
*/
|
|
81
|
+
useEventInputTime?: boolean;
|
|
82
|
+
|
|
83
|
+
log?: KrlLogger;
|
|
84
|
+
|
|
85
|
+
/**
|
|
86
|
+
* WebAuthn relying-party id (a registrable domain). Defaults to the hostname
|
|
87
|
+
* of `base_url` (e.g. "localhost").
|
|
88
|
+
*/
|
|
89
|
+
rpID?: string;
|
|
90
|
+
|
|
91
|
+
/**
|
|
92
|
+
* Human-friendly relying-party name shown by the OS passkey UI.
|
|
93
|
+
*/
|
|
94
|
+
rpName?: string;
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* Expected WebAuthn origin (scheme://host[:port]). Defaults to the origin of
|
|
98
|
+
* `base_url`.
|
|
99
|
+
*/
|
|
100
|
+
origin?: string;
|
|
101
|
+
|
|
102
|
+
/**
|
|
103
|
+
* When true, anyone may register additional accounts/roots after bootstrap.
|
|
104
|
+
* When false (default), only bootstrap (zero accounts), legacy claim, or a valid
|
|
105
|
+
* invite may create a new account.
|
|
106
|
+
*/
|
|
107
|
+
allowSelfSignup?: boolean;
|
|
108
|
+
|
|
109
|
+
/**
|
|
110
|
+
* When true, a direct loopback connection may call `/c/*`, `/api/dev/local`,
|
|
111
|
+
* and `/api/try-it` without a passkey or the internal token. Default false.
|
|
112
|
+
* Proxied requests and a spoofed Host header never qualify.
|
|
113
|
+
*/
|
|
114
|
+
allowLocalhostChannelBypass?: boolean;
|
|
115
|
+
|
|
116
|
+
/**
|
|
117
|
+
* Where the developer UI shows the Try It! tab: "off", "root_only" (default),
|
|
118
|
+
* or "all". Config file key: show_tryit_menu.
|
|
119
|
+
*/
|
|
120
|
+
showTryItMenu?: ShowTryItMenu;
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* Override the WebAuthn ceremony/verification implementation. Intended for
|
|
124
|
+
* testing with a deterministic authenticator.
|
|
125
|
+
*/
|
|
126
|
+
webauthn?: WebAuthnAdapter;
|
|
127
|
+
|
|
128
|
+
/**
|
|
129
|
+
* When true, boot auto-creates a single root (historical behavior). Defaults
|
|
130
|
+
* to false — fresh engines start with zero roots until passkey registration.
|
|
131
|
+
* Tests may set this to true.
|
|
132
|
+
*/
|
|
133
|
+
autoCreateRootPico?: boolean;
|
|
134
|
+
|
|
135
|
+
/** Default max channel policy for root picos (1.8 policy ceiling). */
|
|
136
|
+
defaultRootPolicyCeiling?: PolicyCeiling;
|
|
137
|
+
|
|
138
|
+
/** Engine-wide event denies on every channel ECI (1.8). */
|
|
139
|
+
globalEventDeny?: EventPolicyRule[];
|
|
140
|
+
|
|
141
|
+
/** Engine-wide query denies on every channel ECI (1.8). */
|
|
142
|
+
globalQueryDeny?: QueryPolicyRule[];
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
export interface PicoEngine {
|
|
146
|
+
version: string;
|
|
147
|
+
|
|
148
|
+
home: string;
|
|
149
|
+
port: number;
|
|
150
|
+
base_url: string;
|
|
151
|
+
|
|
152
|
+
pf: PicoFramework;
|
|
153
|
+
core: PicoEngineCore;
|
|
154
|
+
/** UI channel for the session root; null when no roots exist yet at boot. */
|
|
155
|
+
uiECI: string | null;
|
|
156
|
+
rsRegistry: RulesetRegistry;
|
|
157
|
+
auth: AuthService;
|
|
158
|
+
oauth: OAuthService;
|
|
159
|
+
identity: IdentityStore;
|
|
160
|
+
identityService: IdentityService;
|
|
161
|
+
|
|
162
|
+
/** Stop HTTP and close LevelDB stores (for container SIGTERM). */
|
|
163
|
+
shutdown(): Promise<void>;
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
/** Integration harnesses (e.g. manifold-api Docker tests): boot with one root, no passkey. */
|
|
167
|
+
function autoCreateRootFromEnv(): boolean | undefined {
|
|
168
|
+
const v = process.env.PICO_ENGINE_AUTO_CREATE_ROOT;
|
|
169
|
+
if (typeof v !== "string" || v.trim().length === 0) {
|
|
170
|
+
return undefined;
|
|
171
|
+
}
|
|
172
|
+
const s = v.trim().toLowerCase();
|
|
173
|
+
if (s === "1" || s === "true" || s === "yes") {
|
|
174
|
+
return true;
|
|
175
|
+
}
|
|
176
|
+
if (s === "0" || s === "false" || s === "no") {
|
|
177
|
+
return false;
|
|
178
|
+
}
|
|
179
|
+
return undefined;
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
export async function startEngine(
|
|
183
|
+
configuration: PicoEngineConfiguration = {}
|
|
184
|
+
): Promise<PicoEngine> {
|
|
185
|
+
const settings = resolveEngineSettings({
|
|
186
|
+
home: configuration.home,
|
|
187
|
+
port: configuration.port,
|
|
188
|
+
base_url: configuration.base_url,
|
|
189
|
+
rpID: configuration.rpID,
|
|
190
|
+
rpName: configuration.rpName,
|
|
191
|
+
origin: configuration.origin,
|
|
192
|
+
allowSelfSignup: configuration.allowSelfSignup,
|
|
193
|
+
allowLocalhostChannelBypass: configuration.allowLocalhostChannelBypass,
|
|
194
|
+
showTryItMenu: configuration.showTryItMenu,
|
|
195
|
+
defaultRootPolicyCeiling: configuration.defaultRootPolicyCeiling,
|
|
196
|
+
globalEventDeny: configuration.globalEventDeny,
|
|
197
|
+
globalQueryDeny: configuration.globalQueryDeny,
|
|
198
|
+
});
|
|
199
|
+
installEngineRuntimeSettings(settings);
|
|
200
|
+
|
|
201
|
+
const home = settings.home;
|
|
202
|
+
let port = configuration.port ?? settings.port;
|
|
203
|
+
const baseUrlFromCaller = configuration.base_url;
|
|
204
|
+
/** Filled after listen when using port 0 or when config baseUrl port does not match. */
|
|
205
|
+
let base_url: string | undefined = baseUrlFromCaller;
|
|
206
|
+
if (base_url == null && port > 0) {
|
|
207
|
+
base_url = settings.baseUrl;
|
|
208
|
+
}
|
|
209
|
+
await makeDir(home);
|
|
210
|
+
|
|
211
|
+
const logFilePath = resolveEngineLogFilePath(home);
|
|
212
|
+
const log = configuration.log
|
|
213
|
+
? configuration.log
|
|
214
|
+
: makeKrlLogger(makeEngineLogWriter(logFilePath, home));
|
|
215
|
+
|
|
216
|
+
const db = await openClassicLevelWithRecovery<PicoDbKey, any>(
|
|
217
|
+
path.resolve(home, "db"),
|
|
218
|
+
{
|
|
219
|
+
keyEncoding: charwise,
|
|
220
|
+
valueEncoding: safeJsonCodec,
|
|
221
|
+
},
|
|
222
|
+
log
|
|
223
|
+
);
|
|
224
|
+
const rulesetLoaderHandle = await createRulesetRegistryLoaderFs(home, log);
|
|
225
|
+
|
|
226
|
+
const core = new PicoEngineCore({
|
|
227
|
+
db,
|
|
228
|
+
rsRegLoader: rulesetLoaderHandle.loader,
|
|
229
|
+
log,
|
|
230
|
+
modules: configuration.modules,
|
|
231
|
+
useEventInputTime: configuration.useEventInputTime,
|
|
232
|
+
autoCreateRootPico:
|
|
233
|
+
configuration.autoCreateRootPico ??
|
|
234
|
+
autoCreateRootFromEnv() ??
|
|
235
|
+
false,
|
|
236
|
+
defaultRootPolicyCeiling:
|
|
237
|
+
configuration.defaultRootPolicyCeiling ??
|
|
238
|
+
settings.defaultRootPolicyCeiling,
|
|
239
|
+
globalEventDeny: configuration.globalEventDeny ?? settings.globalEventDeny,
|
|
240
|
+
globalQueryDeny: configuration.globalQueryDeny ?? settings.globalQueryDeny,
|
|
241
|
+
getPicoLogs(picoId) {
|
|
242
|
+
return Promise.resolve(picoLogEntries(picoId));
|
|
243
|
+
},
|
|
244
|
+
});
|
|
245
|
+
const pf = core.picoFramework;
|
|
246
|
+
core.resolveBundledRulesetUrl = resolveBundledKrlUrl;
|
|
247
|
+
core.subtreeImportServices = wranglerSubtreeImportServices(core.rsRegistry, (picoId, ctx) =>
|
|
248
|
+
onPicoCreated(picoId, ctx)
|
|
249
|
+
);
|
|
250
|
+
const identity = new IdentityStore({ db: pf.db });
|
|
251
|
+
let identityService!: IdentityService;
|
|
252
|
+
const onPicoCreated = async (
|
|
253
|
+
picoId: string,
|
|
254
|
+
ctx: { isRoot: boolean; parentPicoId: string }
|
|
255
|
+
) => {
|
|
256
|
+
if (core.base_url) {
|
|
257
|
+
await identityService.ensureWebvhDid(picoId, { isRoot: ctx.isRoot });
|
|
258
|
+
}
|
|
259
|
+
};
|
|
260
|
+
identityService = new IdentityService({
|
|
261
|
+
store: identity,
|
|
262
|
+
getBaseUrl: () => core.base_url || base_url || "",
|
|
263
|
+
pf,
|
|
264
|
+
rsRegistry: core.rsRegistry,
|
|
265
|
+
resolveBundledRulesetUrl: resolveBundledKrlUrl,
|
|
266
|
+
reloadImportedSchedules: (picoIds) => core.reloadImportedSchedules(picoIds),
|
|
267
|
+
firePicoImported: async (result) => {
|
|
268
|
+
const importedRoot = pf.getPico(result.newRootPicoId);
|
|
269
|
+
if (!importedRoot) {
|
|
270
|
+
return;
|
|
271
|
+
}
|
|
272
|
+
await importedRoot.event({
|
|
273
|
+
eci: result.newRootEci,
|
|
274
|
+
domain: "wrangler",
|
|
275
|
+
name: "pico_imported",
|
|
276
|
+
data: {
|
|
277
|
+
attrs: {
|
|
278
|
+
oldRootPicoId: result.oldRootPicoId,
|
|
279
|
+
newRootPicoId: result.newRootPicoId,
|
|
280
|
+
eciMap: result.eciMap,
|
|
281
|
+
picoIdMap: result.picoIdMap,
|
|
282
|
+
portableIdentity: true,
|
|
283
|
+
},
|
|
284
|
+
},
|
|
285
|
+
time: Date.now(),
|
|
286
|
+
});
|
|
287
|
+
},
|
|
288
|
+
});
|
|
289
|
+
core.onPicoCreated = onPicoCreated;
|
|
290
|
+
core.subtreePortableHooks = createSubtreePortableHooks(identity, pf);
|
|
291
|
+
core.modules["dido"] = initDidoModule(identityService);
|
|
292
|
+
|
|
293
|
+
try {
|
|
294
|
+
await core.start();
|
|
295
|
+
} catch (err) {
|
|
296
|
+
log.error("Engine startup failed", { error: err });
|
|
297
|
+
await rulesetLoaderHandle.close().catch(() => undefined);
|
|
298
|
+
await db.close().catch(() => undefined);
|
|
299
|
+
throw err;
|
|
300
|
+
}
|
|
301
|
+
const rsRegistry = core.rsRegistry;
|
|
302
|
+
|
|
303
|
+
// Fresh engines boot with zero roots. Adopt + (re)provision only when roots
|
|
304
|
+
// already exist (test harness with autoCreateRootPico, or a migrated DB).
|
|
305
|
+
let uiECI: string | null = null;
|
|
306
|
+
const existingRoots = pf.rootPicos();
|
|
307
|
+
if (existingRoots.length > 0) {
|
|
308
|
+
const provisioned = await provisionRoot(pf, core, { root: existingRoots[0] });
|
|
309
|
+
uiECI = provisioned.uiECI;
|
|
310
|
+
}
|
|
311
|
+
|
|
312
|
+
const auth = new AuthService({
|
|
313
|
+
db: pf.db,
|
|
314
|
+
webauthn: configuration.webauthn || makeWebAuthnAdapter(),
|
|
315
|
+
getBaseUrl: () => core.base_url,
|
|
316
|
+
rpID: configuration.rpID,
|
|
317
|
+
rpName: configuration.rpName,
|
|
318
|
+
origin: configuration.origin,
|
|
319
|
+
allowSelfSignup:
|
|
320
|
+
configuration.allowSelfSignup ?? settings.allowSelfSignup,
|
|
321
|
+
flushBootstrapUrl: async (url) => {
|
|
322
|
+
const flushed = await rsRegistry.flush(url);
|
|
323
|
+
return { rid: flushed.rid };
|
|
324
|
+
},
|
|
325
|
+
provisionRoot: async (opts) => {
|
|
326
|
+
const { root, uiECI } = await provisionRoot(pf, core, opts);
|
|
327
|
+
if (core.base_url) {
|
|
328
|
+
await identityService.ensureWebvhDid(root.id, { isRoot: true });
|
|
329
|
+
}
|
|
330
|
+
return { rootPicoId: root.id, uiECI };
|
|
331
|
+
},
|
|
332
|
+
getUiECI: (rootPicoId: string) => uiECIForRoot(pf, rootPicoId),
|
|
333
|
+
getPrimaryRootPicoId: () => {
|
|
334
|
+
try {
|
|
335
|
+
return pf.rootPico.id;
|
|
336
|
+
} catch {
|
|
337
|
+
return null;
|
|
338
|
+
}
|
|
339
|
+
},
|
|
340
|
+
onAccountClaimed: async (rootPicoId, displayName) => {
|
|
341
|
+
const uiChannel = uiECIForRoot(pf, rootPicoId);
|
|
342
|
+
if (!uiChannel || !displayName.trim()) {
|
|
343
|
+
return;
|
|
344
|
+
}
|
|
345
|
+
await pf.eventWait({
|
|
346
|
+
eci: uiChannel,
|
|
347
|
+
domain: "engine_ui",
|
|
348
|
+
name: "box",
|
|
349
|
+
data: { attrs: { name: displayName.trim() } },
|
|
350
|
+
time: 0,
|
|
351
|
+
});
|
|
352
|
+
},
|
|
353
|
+
});
|
|
354
|
+
|
|
355
|
+
const oauth = new OAuthService({
|
|
356
|
+
db: pf.db,
|
|
357
|
+
pf,
|
|
358
|
+
getBaseUrl: () => core.base_url,
|
|
359
|
+
});
|
|
360
|
+
core.modules["oauth"] = initOAuthModule(oauth);
|
|
361
|
+
|
|
362
|
+
await warmPdsSecretLog(core);
|
|
363
|
+
const internalToken = writeInternalToken(home);
|
|
364
|
+
const app = server(core, uiECI, auth, oauth, identityService, internalToken);
|
|
365
|
+
|
|
366
|
+
if ((!port || !_.isInteger(port) || port < 1) && port !== 0) {
|
|
367
|
+
port = process.env.NODE_ENV === "test" ? 0 : 3000;
|
|
368
|
+
}
|
|
369
|
+
let httpServer: Server | undefined;
|
|
370
|
+
let listening = false;
|
|
371
|
+
try {
|
|
372
|
+
await new Promise<void>((resolve, reject) => {
|
|
373
|
+
httpServer = app.listen(port, () => {
|
|
374
|
+
listening = true;
|
|
375
|
+
if (httpServer) {
|
|
376
|
+
const addr = httpServer.address();
|
|
377
|
+
if (addr && typeof addr !== "string" && _.isInteger(addr.port)) {
|
|
378
|
+
// Get the actual port i.e. if they set port to 0 nodejs will assign you an available port
|
|
379
|
+
port = addr.port;
|
|
380
|
+
}
|
|
381
|
+
}
|
|
382
|
+
resolve(undefined);
|
|
383
|
+
});
|
|
384
|
+
// listen failures are an 'error' event. With no listener, Node throws.
|
|
385
|
+
httpServer.on("error", (err: NodeJS.ErrnoException) => {
|
|
386
|
+
if (!listening) {
|
|
387
|
+
reject(err);
|
|
388
|
+
return;
|
|
389
|
+
}
|
|
390
|
+
log.error("HTTP server error", { error: err });
|
|
391
|
+
});
|
|
392
|
+
});
|
|
393
|
+
} catch (err) {
|
|
394
|
+
const coded = err as NodeJS.ErrnoException;
|
|
395
|
+
if (coded.code === "EADDRINUSE") {
|
|
396
|
+
log.error(`Port ${port} is already in use`);
|
|
397
|
+
} else {
|
|
398
|
+
log.error("HTTP server failed to listen", { error: err, port });
|
|
399
|
+
}
|
|
400
|
+
if (httpServer) {
|
|
401
|
+
await new Promise<void>((resolve) => httpServer!.close(() => resolve()));
|
|
402
|
+
}
|
|
403
|
+
await rulesetLoaderHandle.close().catch(() => undefined);
|
|
404
|
+
await db.close().catch(() => undefined);
|
|
405
|
+
throw err;
|
|
406
|
+
}
|
|
407
|
+
if (typeof base_url !== "string") {
|
|
408
|
+
base_url = `http://localhost:${port}`;
|
|
409
|
+
} else if (
|
|
410
|
+
baseUrlFromCaller == null &&
|
|
411
|
+
(configuration.port === 0 || port !== settings.port)
|
|
412
|
+
) {
|
|
413
|
+
base_url = `http://localhost:${port}`;
|
|
414
|
+
}
|
|
415
|
+
core.base_url = base_url;
|
|
416
|
+
|
|
417
|
+
await identityService.ensureWebvhForAllLoadedPicos();
|
|
418
|
+
|
|
419
|
+
log.info(`Listening at ${base_url}`);
|
|
420
|
+
|
|
421
|
+
if (uiECI) {
|
|
422
|
+
pf.event({
|
|
423
|
+
eci: uiECI,
|
|
424
|
+
domain: "engine",
|
|
425
|
+
name: "started",
|
|
426
|
+
data: { attrs: {} },
|
|
427
|
+
time: 0, // TODO remove this typescript requirement
|
|
428
|
+
}).catch((error) => {
|
|
429
|
+
log.error("Error signaling engine:started event", { error });
|
|
430
|
+
});
|
|
431
|
+
}
|
|
432
|
+
|
|
433
|
+
let shuttingDown = false;
|
|
434
|
+
async function shutdown() {
|
|
435
|
+
if (shuttingDown) {
|
|
436
|
+
return;
|
|
437
|
+
}
|
|
438
|
+
shuttingDown = true;
|
|
439
|
+
log.info("Shutting down pico-engine");
|
|
440
|
+
await new Promise<void>((resolve, reject) => {
|
|
441
|
+
if (!httpServer) {
|
|
442
|
+
resolve(undefined);
|
|
443
|
+
return;
|
|
444
|
+
}
|
|
445
|
+
httpServer.close((err) => (err ? reject(err) : resolve(undefined)));
|
|
446
|
+
});
|
|
447
|
+
await rulesetLoaderHandle.close();
|
|
448
|
+
await db.close();
|
|
449
|
+
log.info("Shutdown complete");
|
|
450
|
+
}
|
|
451
|
+
|
|
452
|
+
return {
|
|
453
|
+
version,
|
|
454
|
+
|
|
455
|
+
home,
|
|
456
|
+
port,
|
|
457
|
+
base_url,
|
|
458
|
+
|
|
459
|
+
pf,
|
|
460
|
+
core,
|
|
461
|
+
uiECI,
|
|
462
|
+
rsRegistry,
|
|
463
|
+
auth,
|
|
464
|
+
oauth,
|
|
465
|
+
identity,
|
|
466
|
+
identityService,
|
|
467
|
+
shutdown,
|
|
468
|
+
};
|
|
469
|
+
}
|