pico-engine 1.9.4 → 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.
Files changed (186) hide show
  1. package/README.md +13 -5
  2. package/demos/bootstrap/README.md +12 -0
  3. package/demos/bootstrap/com.example.visitors.bootstrap.krl +101 -0
  4. package/demos/bootstrap/com.example.visitors.format.krl +25 -0
  5. package/demos/bootstrap/com.example.visitors.krl +228 -0
  6. package/demos/bootstrap/try-it.md +5 -0
  7. package/demos/child_tasks/README.md +12 -0
  8. package/demos/child_tasks/com.example.task_runner.bootstrap.krl +88 -0
  9. package/demos/child_tasks/com.example.task_runner.krl +139 -0
  10. package/demos/child_tasks/com.example.task_worker.krl +45 -0
  11. package/demos/child_tasks/try-it.md +5 -0
  12. package/demos/collection/README.md +13 -0
  13. package/demos/collection/com.example.collection.bootstrap.krl +148 -0
  14. package/demos/collection/com.example.collection.krl +95 -0
  15. package/demos/collection/com.example.collection.report.krl +93 -0
  16. package/demos/collection/com.example.collection.room.krl +101 -0
  17. package/demos/collection/try-it.md +6 -0
  18. package/demos/echo/README.md +11 -0
  19. package/demos/echo/com.example.echo.bootstrap.krl +84 -0
  20. package/demos/echo/com.example.echo.krl +73 -0
  21. package/demos/echo/try-it.md +5 -0
  22. package/demos/guard_rules/README.md +12 -0
  23. package/demos/guard_rules/com.example.archive.bootstrap.krl +98 -0
  24. package/demos/guard_rules/com.example.archive.krl +213 -0
  25. package/demos/guard_rules/com.example.archive_store.krl +36 -0
  26. package/demos/guard_rules/try-it.md +5 -0
  27. package/demos/json_query/README.md +11 -0
  28. package/demos/json_query/com.example.json_query.bootstrap.krl +84 -0
  29. package/demos/json_query/com.example.json_query.krl +162 -0
  30. package/demos/json_query/try-it.md +5 -0
  31. package/demos/kblog/README.md +14 -0
  32. package/demos/kblog/com.example.kblog.bootstrap.krl +135 -0
  33. package/demos/kblog/com.example.kblog.config.krl +50 -0
  34. package/demos/kblog/com.example.kblog.data.krl +75 -0
  35. package/demos/kblog/com.example.kblog.krl +184 -0
  36. package/demos/kblog/com.example.kblog.posting.krl +109 -0
  37. package/demos/kblog/try-it.md +6 -0
  38. package/demos/layered_rulesets/README.md +13 -0
  39. package/demos/layered_rulesets/com.example.invitations.bootstrap.krl +87 -0
  40. package/demos/layered_rulesets/com.example.invitations.krl +164 -0
  41. package/demos/layered_rulesets/com.example.invitations.short_links.krl +45 -0
  42. package/demos/layered_rulesets/com.example.invitations.welcome.krl +39 -0
  43. package/demos/layered_rulesets/try-it.md +5 -0
  44. package/demos/moving_picos/README.md +15 -0
  45. package/demos/moving_picos/io.picolabs.club_gear_demo.krl +650 -0
  46. package/demos/moving_picos/io.picolabs.ride_coordinator_demo.krl +331 -0
  47. package/demos/score_tracker/README.md +11 -0
  48. package/demos/score_tracker/com.example.score_tracker.bootstrap.krl +107 -0
  49. package/demos/score_tracker/com.example.score_tracker.krl +162 -0
  50. package/demos/score_tracker/try-it.md +5 -0
  51. package/demos/secrets/README.md +12 -0
  52. package/demos/secrets/com.example.hook_service.krl +120 -0
  53. package/demos/secrets/com.example.notifier.bootstrap.krl +130 -0
  54. package/demos/secrets/com.example.notifier.krl +138 -0
  55. package/demos/secrets/try-it.md +5 -0
  56. package/demos/try-it-order.json +1 -0
  57. package/demos/two_picos/README.md +12 -0
  58. package/demos/two_picos/com.example.two_picos.answerer.krl +125 -0
  59. package/demos/two_picos/com.example.two_picos.asker.krl +124 -0
  60. package/demos/two_picos/com.example.two_picos.bootstrap.krl +134 -0
  61. package/demos/two_picos/try-it.md +5 -0
  62. package/demos/xmlui/README.md +17 -0
  63. package/demos/xmlui/com.example.contacts.krl +132 -0
  64. package/demos/xmlui/com.example.fav_color.krl +39 -0
  65. package/demos/xmlui/com.example.guestbook.krl +61 -0
  66. package/demos/xmlui/com.example.hello.krl +19 -0
  67. package/demos/xmlui/com.example.temperature_sensors_view.krl +105 -0
  68. package/demos/xmlui/com.example.thermostat.bootstrap.krl +95 -0
  69. package/demos/xmlui/com.example.thermostat.krl +124 -0
  70. package/demos/xmlui/temperature_sensors.krl +56 -0
  71. package/demos/xmlui/try-it.md +5 -0
  72. package/dist/bundledKrl.js +97 -12
  73. package/dist/cli.js +7 -1
  74. package/dist/engineConfig.js +20 -1
  75. package/dist/identity/portableMove.js +5 -1
  76. package/dist/index.js +45 -12
  77. package/dist/internalAccess.js +110 -0
  78. package/dist/oauth/OAuthService.js +172 -10
  79. package/dist/oauth/acg.js +194 -24
  80. package/dist/oauth/cimd.js +381 -0
  81. package/dist/oauth/discovery.js +175 -0
  82. package/dist/runMcp.js +1 -1
  83. package/dist/server.js +210 -47
  84. package/dist/subtreeWrangler.js +8 -5
  85. package/dist/uiChannelPolicies.js +2 -0
  86. package/krl/io.picolabs.pds.krl +109 -21
  87. package/krl/io.picolabs.pico-engine-ui.krl +13 -7
  88. package/krl/io.picolabs.wrangler.krl +21 -9
  89. package/krl/io.picolabs.xmlui.krl +3 -2
  90. package/mcp/devResources.js +52 -0
  91. package/mcp/devTools.js +40 -9
  92. package/mcp/docs/CLAUDE.md +6 -4
  93. package/mcp/docs/cookbook/README.md +23 -0
  94. package/mcp/docs/cookbook/bootstrap/README.md +23 -0
  95. package/mcp/docs/cookbook/bootstrap/instructions.md +75 -0
  96. package/mcp/docs/cookbook/child_tasks/README.md +20 -0
  97. package/mcp/docs/cookbook/child_tasks/instructions.md +60 -0
  98. package/mcp/docs/cookbook/collection/README.md +21 -0
  99. package/mcp/docs/cookbook/collection/instructions.md +93 -0
  100. package/mcp/docs/cookbook/echo/README.md +19 -0
  101. package/mcp/docs/cookbook/echo/instructions.md +59 -0
  102. package/mcp/docs/cookbook/guard_rules/README.md +22 -0
  103. package/mcp/docs/cookbook/guard_rules/instructions.md +73 -0
  104. package/mcp/docs/cookbook/json_query/README.md +26 -0
  105. package/mcp/docs/cookbook/json_query/instructions.md +64 -0
  106. package/mcp/docs/cookbook/kblog/README.md +60 -0
  107. package/mcp/docs/cookbook/kblog/instructions.md +102 -0
  108. package/mcp/docs/cookbook/layered_rulesets/README.md +24 -0
  109. package/mcp/docs/cookbook/layered_rulesets/instructions.md +87 -0
  110. package/mcp/docs/cookbook/moving_picos/README.md +44 -0
  111. package/mcp/docs/cookbook/moving_picos/instructions.md +150 -0
  112. package/mcp/docs/cookbook/score_tracker/README.md +19 -0
  113. package/mcp/docs/cookbook/score_tracker/instructions.md +73 -0
  114. package/mcp/docs/cookbook/secrets/README.md +25 -0
  115. package/mcp/docs/cookbook/secrets/instructions.md +98 -0
  116. package/mcp/docs/cookbook/two_picos/README.md +20 -0
  117. package/mcp/docs/cookbook/two_picos/instructions.md +88 -0
  118. package/mcp/docs/cookbook/xmlui/README.md +23 -0
  119. package/mcp/docs/cookbook/xmlui/instructions.md +84 -0
  120. package/mcp/docs/developing/README.md +28 -0
  121. package/mcp/docs/developing/accepting-relationship-requests.md +65 -0
  122. package/mcp/docs/developing/arrays-and-maps.md +77 -0
  123. package/mcp/docs/developing/converting-time-formats.md +28 -0
  124. package/mcp/docs/developing/cookies-and-redirects.md +81 -0
  125. package/mcp/docs/developing/decoding-form-data.md +67 -0
  126. package/mcp/docs/developing/engine-log-files.md +34 -0
  127. package/mcp/docs/developing/event-loop.md +77 -0
  128. package/mcp/docs/developing/events-from-email.md +80 -0
  129. package/mcp/docs/developing/initializing-entity-variables.md +83 -0
  130. package/mcp/docs/developing/mcp-ai-tools.md +98 -0
  131. package/mcp/docs/developing/misconceptions.md +467 -0
  132. package/mcp/docs/developing/names-and-scope.md +44 -0
  133. package/mcp/docs/developing/postman.md +159 -0
  134. package/mcp/docs/developing/querying-another-pico.md +47 -0
  135. package/mcp/docs/developing/singleton-picos.md +36 -0
  136. package/mcp/docs/developing/tabular-data.md +67 -0
  137. package/mcp/docs/developing/tips.md +251 -0
  138. package/mcp/docs/developing/webhook-signatures.md +56 -0
  139. package/mcp/docs/developing/workflow.md +106 -0
  140. package/mcp/docs/exp/README.md +46 -0
  141. package/mcp/docs/exp/event.md +110 -0
  142. package/mcp/docs/exp/query.md +94 -0
  143. package/mcp/docs/lessons/README.md +59 -0
  144. package/mcp/docs/lessons/events-and-queries.md +247 -0
  145. package/mcp/docs/lessons/gossip.md +28 -0
  146. package/mcp/docs/lessons/modules-and-apis.md +270 -0
  147. package/mcp/docs/lessons/pico-based-systems.md +470 -0
  148. package/mcp/docs/lessons/pico-state.md +267 -0
  149. package/mcp/docs/lessons/pico-views.md +290 -0
  150. package/mcp/docs/lessons/quickstart.md +157 -0
  151. package/mcp/docs/lessons/relationships.md +530 -0
  152. package/mcp/docs/lessons/scatter-gather.md +362 -0
  153. package/mcp/docs/pico-engine.md +10 -5
  154. package/mcp/docs/pico-overview.md +3 -3
  155. package/mcp/docs/wrangler/README.md +47 -0
  156. package/mcp/docs/wrangler/channels.md +235 -0
  157. package/mcp/docs/wrangler/oauth.md +56 -0
  158. package/mcp/docs/wrangler/pds.md +423 -0
  159. package/mcp/docs/wrangler/portable-subtree.md +44 -0
  160. package/mcp/docs/wrangler/relationships.md +297 -0
  161. package/mcp/docs/wrangler/wrangler.md +253 -0
  162. package/mcp/docs/wrangler/xmlui.md +60 -0
  163. package/mcp/engineClient.js +57 -5
  164. package/mcp/mcpScopes.js +118 -0
  165. package/mcp/meshHttp.js +151 -45
  166. package/mcp/runStdio.js +2 -0
  167. package/mcp/subtreeTools.js +184 -0
  168. package/mcp/tryItTools.js +202 -0
  169. package/package.json +18 -9
  170. package/public/.DS_Store +0 -0
  171. package/public/pico-engine-ui.css +1 -1
  172. package/public/pico-engine-ui.js +26 -25
  173. package/src/bundledKrl.ts +118 -12
  174. package/src/cli.ts +8 -2
  175. package/src/engineConfig.ts +33 -2
  176. package/src/identity/portableMove.ts +6 -1
  177. package/src/index.ts +469 -422
  178. package/src/internalAccess.ts +127 -0
  179. package/src/oauth/OAuthService.ts +243 -11
  180. package/src/oauth/acg.ts +289 -25
  181. package/src/oauth/cimd.ts +508 -0
  182. package/src/oauth/discovery.ts +233 -0
  183. package/src/runMcp.ts +3 -1
  184. package/src/server.ts +266 -51
  185. package/src/subtreeWrangler.ts +17 -5
  186. package/src/uiChannelPolicies.ts +2 -0
package/src/index.ts CHANGED
@@ -1,422 +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 { server } from "./server";
35
- import {
36
- installEngineRuntimeSettings,
37
- resolveEngineSettings,
38
- } from "./engineConfig";
39
- const charwise = require("charwise");
40
- const safeJsonCodec = require("level-json-coerce-null");
41
-
42
- const version = require("../package.json").version;
43
-
44
- /**
45
- * Configuration options that may be set by the user
46
- */
47
- export interface PicoEngineConfiguration {
48
- /**
49
- * The absolute path to the folder where the engine should store the database and logs.
50
- *
51
- * Default: "~/.pico-engine/"
52
- */
53
- home?: string;
54
-
55
- /**
56
- * The port number the http server should listen on.
57
- *
58
- * If you want an available port assigned to you, set it to 0
59
- *
60
- * Default: 3000
61
- */
62
- port?: number;
63
-
64
- /**
65
- * The base url others should use when addressing your engine.
66
- *
67
- * Default: "http://localhost:3000"
68
- */
69
- base_url?: string;
70
-
71
- /**
72
- * Provide any custom krl modules
73
- */
74
- modules?: { [domain: string]: krl.Module };
75
-
76
- /**
77
- * Trust event.time input. Used for testing
78
- */
79
- useEventInputTime?: boolean;
80
-
81
- log?: KrlLogger;
82
-
83
- /**
84
- * WebAuthn relying-party id (a registrable domain). Defaults to the hostname
85
- * of `base_url` (e.g. "localhost").
86
- */
87
- rpID?: string;
88
-
89
- /**
90
- * Human-friendly relying-party name shown by the OS passkey UI.
91
- */
92
- rpName?: string;
93
-
94
- /**
95
- * Expected WebAuthn origin (scheme://host[:port]). Defaults to the origin of
96
- * `base_url`.
97
- */
98
- origin?: string;
99
-
100
- /**
101
- * When true, anyone may register additional accounts/roots after bootstrap.
102
- * When false (default), only bootstrap (zero accounts), legacy claim, or a valid
103
- * invite may create a new account.
104
- */
105
- allowSelfSignup?: boolean;
106
-
107
- /**
108
- * Override the WebAuthn ceremony/verification implementation. Intended for
109
- * testing with a deterministic authenticator.
110
- */
111
- webauthn?: WebAuthnAdapter;
112
-
113
- /**
114
- * When true, boot auto-creates a single root (historical behavior). Defaults
115
- * to false — fresh engines start with zero roots until passkey registration.
116
- * Tests may set this to true.
117
- */
118
- autoCreateRootPico?: boolean;
119
-
120
- /** Default max channel policy for root picos (1.8 policy ceiling). */
121
- defaultRootPolicyCeiling?: PolicyCeiling;
122
-
123
- /** Engine-wide event denies on every channel ECI (1.8). */
124
- globalEventDeny?: EventPolicyRule[];
125
-
126
- /** Engine-wide query denies on every channel ECI (1.8). */
127
- globalQueryDeny?: QueryPolicyRule[];
128
- }
129
-
130
- export interface PicoEngine {
131
- version: string;
132
-
133
- home: string;
134
- port: number;
135
- base_url: string;
136
-
137
- pf: PicoFramework;
138
- core: PicoEngineCore;
139
- /** UI channel for the session root; null when no roots exist yet at boot. */
140
- uiECI: string | null;
141
- rsRegistry: RulesetRegistry;
142
- auth: AuthService;
143
- oauth: OAuthService;
144
- identity: IdentityStore;
145
- identityService: IdentityService;
146
-
147
- /** Stop HTTP and close LevelDB stores (for container SIGTERM). */
148
- shutdown(): Promise<void>;
149
- }
150
-
151
- /** Integration harnesses (e.g. manifold-api Docker tests): boot with one root, no passkey. */
152
- function autoCreateRootFromEnv(): boolean | undefined {
153
- const v = process.env.PICO_ENGINE_AUTO_CREATE_ROOT;
154
- if (typeof v !== "string" || v.trim().length === 0) {
155
- return undefined;
156
- }
157
- const s = v.trim().toLowerCase();
158
- if (s === "1" || s === "true" || s === "yes") {
159
- return true;
160
- }
161
- if (s === "0" || s === "false" || s === "no") {
162
- return false;
163
- }
164
- return undefined;
165
- }
166
-
167
- export async function startEngine(
168
- configuration: PicoEngineConfiguration = {}
169
- ): Promise<PicoEngine> {
170
- const settings = resolveEngineSettings({
171
- home: configuration.home,
172
- port: configuration.port,
173
- base_url: configuration.base_url,
174
- rpID: configuration.rpID,
175
- rpName: configuration.rpName,
176
- origin: configuration.origin,
177
- allowSelfSignup: configuration.allowSelfSignup,
178
- defaultRootPolicyCeiling: configuration.defaultRootPolicyCeiling,
179
- globalEventDeny: configuration.globalEventDeny,
180
- globalQueryDeny: configuration.globalQueryDeny,
181
- });
182
- installEngineRuntimeSettings(settings);
183
-
184
- const home = settings.home;
185
- let port = configuration.port ?? settings.port;
186
- const baseUrlFromCaller = configuration.base_url;
187
- /** Filled after listen when using port 0 or when config baseUrl port does not match. */
188
- let base_url: string | undefined = baseUrlFromCaller;
189
- if (base_url == null && port > 0) {
190
- base_url = settings.baseUrl;
191
- }
192
- await makeDir(home);
193
-
194
- const logFilePath = resolveEngineLogFilePath(home);
195
- const log = configuration.log
196
- ? configuration.log
197
- : makeKrlLogger(makeEngineLogWriter(logFilePath, home));
198
-
199
- const db = await openClassicLevelWithRecovery<PicoDbKey, any>(
200
- path.resolve(home, "db"),
201
- {
202
- keyEncoding: charwise,
203
- valueEncoding: safeJsonCodec,
204
- },
205
- log
206
- );
207
- const rulesetLoaderHandle = await createRulesetRegistryLoaderFs(home, log);
208
-
209
- const core = new PicoEngineCore({
210
- db,
211
- rsRegLoader: rulesetLoaderHandle.loader,
212
- log,
213
- modules: configuration.modules,
214
- useEventInputTime: configuration.useEventInputTime,
215
- autoCreateRootPico:
216
- configuration.autoCreateRootPico ??
217
- autoCreateRootFromEnv() ??
218
- false,
219
- defaultRootPolicyCeiling:
220
- configuration.defaultRootPolicyCeiling ??
221
- settings.defaultRootPolicyCeiling,
222
- globalEventDeny: configuration.globalEventDeny ?? settings.globalEventDeny,
223
- globalQueryDeny: configuration.globalQueryDeny ?? settings.globalQueryDeny,
224
- getPicoLogs(picoId) {
225
- return Promise.resolve(picoLogEntries(picoId));
226
- },
227
- });
228
- const pf = core.picoFramework;
229
- core.resolveBundledRulesetUrl = resolveBundledKrlUrl;
230
- core.subtreeImportServices = wranglerSubtreeImportServices(core.rsRegistry);
231
- const identity = new IdentityStore({ db: pf.db });
232
- let identityService!: IdentityService;
233
- const onPicoCreated = async (
234
- picoId: string,
235
- ctx: { isRoot: boolean; parentPicoId: string }
236
- ) => {
237
- if (core.base_url) {
238
- await identityService.ensureWebvhDid(picoId, { isRoot: ctx.isRoot });
239
- }
240
- };
241
- identityService = new IdentityService({
242
- store: identity,
243
- getBaseUrl: () => core.base_url || base_url || "",
244
- pf,
245
- rsRegistry: core.rsRegistry,
246
- resolveBundledRulesetUrl: resolveBundledKrlUrl,
247
- reloadImportedSchedules: (picoIds) => core.reloadImportedSchedules(picoIds),
248
- firePicoImported: async (result) => {
249
- const importedRoot = pf.getPico(result.newRootPicoId);
250
- if (!importedRoot) {
251
- return;
252
- }
253
- await importedRoot.event({
254
- eci: result.newRootEci,
255
- domain: "wrangler",
256
- name: "pico_imported",
257
- data: {
258
- attrs: {
259
- oldRootPicoId: result.oldRootPicoId,
260
- newRootPicoId: result.newRootPicoId,
261
- eciMap: result.eciMap,
262
- picoIdMap: result.picoIdMap,
263
- portableIdentity: true,
264
- },
265
- },
266
- time: Date.now(),
267
- });
268
- },
269
- });
270
- core.onPicoCreated = onPicoCreated;
271
- core.subtreePortableHooks = createSubtreePortableHooks(identity, pf);
272
- core.modules["dido"] = initDidoModule(identityService);
273
-
274
- try {
275
- await core.start();
276
- } catch (err) {
277
- log.error("Engine startup failed", { error: err });
278
- await rulesetLoaderHandle.close().catch(() => undefined);
279
- await db.close().catch(() => undefined);
280
- throw err;
281
- }
282
- const rsRegistry = core.rsRegistry;
283
-
284
- // Fresh engines boot with zero roots. Adopt + (re)provision only when roots
285
- // already exist (test harness with autoCreateRootPico, or a migrated DB).
286
- let uiECI: string | null = null;
287
- const existingRoots = pf.rootPicos();
288
- if (existingRoots.length > 0) {
289
- const provisioned = await provisionRoot(pf, core, { root: existingRoots[0] });
290
- uiECI = provisioned.uiECI;
291
- }
292
-
293
- const auth = new AuthService({
294
- db: pf.db,
295
- webauthn: configuration.webauthn || makeWebAuthnAdapter(),
296
- getBaseUrl: () => core.base_url,
297
- rpID: configuration.rpID,
298
- rpName: configuration.rpName,
299
- origin: configuration.origin,
300
- allowSelfSignup:
301
- configuration.allowSelfSignup ?? settings.allowSelfSignup,
302
- flushBootstrapUrl: async (url) => {
303
- const flushed = await rsRegistry.flush(url);
304
- return { rid: flushed.rid };
305
- },
306
- provisionRoot: async (opts) => {
307
- const { root, uiECI } = await provisionRoot(pf, core, opts);
308
- if (core.base_url) {
309
- await identityService.ensureWebvhDid(root.id, { isRoot: true });
310
- }
311
- return { rootPicoId: root.id, uiECI };
312
- },
313
- getUiECI: (rootPicoId: string) => uiECIForRoot(pf, rootPicoId),
314
- getPrimaryRootPicoId: () => {
315
- try {
316
- return pf.rootPico.id;
317
- } catch {
318
- return null;
319
- }
320
- },
321
- onAccountClaimed: async (rootPicoId, displayName) => {
322
- const uiChannel = uiECIForRoot(pf, rootPicoId);
323
- if (!uiChannel || !displayName.trim()) {
324
- return;
325
- }
326
- await pf.eventWait({
327
- eci: uiChannel,
328
- domain: "engine_ui",
329
- name: "box",
330
- data: { attrs: { name: displayName.trim() } },
331
- time: 0,
332
- });
333
- },
334
- });
335
-
336
- const oauth = new OAuthService({
337
- db: pf.db,
338
- pf,
339
- });
340
- core.modules["oauth"] = initOAuthModule(oauth);
341
-
342
- const app = server(core, uiECI, auth, oauth, identityService);
343
-
344
- if ((!port || !_.isInteger(port) || port < 1) && port !== 0) {
345
- port = process.env.NODE_ENV === "test" ? 0 : 3000;
346
- }
347
- let httpServer: Server | undefined;
348
- await new Promise<void>((resolve) => {
349
- httpServer = app.listen(port, () => {
350
- if (httpServer) {
351
- const addr = httpServer.address();
352
- if (addr && typeof addr !== "string" && _.isInteger(addr.port)) {
353
- // Get the actual port i.e. if they set port to 0 nodejs will assign you an available port
354
- port = addr.port;
355
- }
356
- }
357
- resolve(undefined);
358
- });
359
- });
360
- if (typeof base_url !== "string") {
361
- base_url = `http://localhost:${port}`;
362
- } else if (
363
- baseUrlFromCaller == null &&
364
- (configuration.port === 0 || port !== settings.port)
365
- ) {
366
- base_url = `http://localhost:${port}`;
367
- }
368
- core.base_url = base_url;
369
-
370
- await identityService.ensureWebvhForAllLoadedPicos();
371
-
372
- log.info(`Listening at ${base_url}`);
373
-
374
- if (uiECI) {
375
- pf.event({
376
- eci: uiECI,
377
- domain: "engine",
378
- name: "started",
379
- data: { attrs: {} },
380
- time: 0, // TODO remove this typescript requirement
381
- }).catch((error) => {
382
- log.error("Error signaling engine:started event", { error });
383
- });
384
- }
385
-
386
- let shuttingDown = false;
387
- async function shutdown() {
388
- if (shuttingDown) {
389
- return;
390
- }
391
- shuttingDown = true;
392
- log.info("Shutting down pico-engine");
393
- await new Promise<void>((resolve, reject) => {
394
- if (!httpServer) {
395
- resolve(undefined);
396
- return;
397
- }
398
- httpServer.close((err) => (err ? reject(err) : resolve(undefined)));
399
- });
400
- await rulesetLoaderHandle.close();
401
- await db.close();
402
- log.info("Shutdown complete");
403
- }
404
-
405
- return {
406
- version,
407
-
408
- home,
409
- port,
410
- base_url,
411
-
412
- pf,
413
- core,
414
- uiECI,
415
- rsRegistry,
416
- auth,
417
- oauth,
418
- identity,
419
- identityService,
420
- shutdown,
421
- };
422
- }
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
+ }