pico-engine 1.6.2 → 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 (107) hide show
  1. package/README.md +117 -14
  2. package/dist/RulesetRegistryLoaderFs.js +24 -8
  3. package/dist/auth/cookies.js +32 -0
  4. package/dist/auth/index.js +6 -1
  5. package/dist/bundledKrl.js +129 -11
  6. package/dist/channelIdentityPolicy.js +22 -0
  7. package/dist/cli.js +105 -46
  8. package/dist/engineConfig.js +280 -0
  9. package/dist/identity/IdentityService.js +90 -0
  10. package/dist/identity/crossPico.js +106 -30
  11. package/dist/identity/didoModule.js +80 -18
  12. package/dist/identity/establishSubscription.js +2 -2
  13. package/dist/identity/identityPortable.js +92 -0
  14. package/dist/identity/index.js +10 -1
  15. package/dist/identity/localPeerReconcile.js +65 -0
  16. package/dist/identity/peerDid4.js +175 -0
  17. package/dist/identity/peerDid4Create.js +90 -0
  18. package/dist/identity/portableExportPrepare.js +196 -0
  19. package/dist/identity/portableMove.js +87 -0
  20. package/dist/identity/skyIntro.js +10 -4
  21. package/dist/identity/skyProtocol.js +26 -1
  22. package/dist/identity/skyRotation.js +121 -0
  23. package/dist/identity/store.js +5 -1
  24. package/dist/identity/subscriptionEntSync.js +72 -0
  25. package/dist/identity/veramoDidComm.js +41 -2
  26. package/dist/identity/webvh.js +4 -2
  27. package/dist/identity/webvhRelocation.js +115 -0
  28. package/dist/index.js +127 -34
  29. package/dist/levelDb.js +102 -0
  30. package/dist/logging.js +47 -8
  31. package/dist/oauth/OAuthService.js +12 -5
  32. package/dist/oauth/channelEligibility.js +7 -1
  33. package/dist/oauth/index.js +3 -1
  34. package/dist/policyConfigFromJson.js +112 -0
  35. package/dist/runMcp.js +27 -0
  36. package/dist/server.js +95 -24
  37. package/dist/subtreeWrangler.js +180 -0
  38. package/dist/uiChannelPolicies.js +16 -0
  39. package/krl/io.picolabs.oauth.krl +51 -5
  40. package/krl/io.picolabs.pds.krl +131 -10
  41. package/krl/io.picolabs.pico-engine-ui.krl +219 -22
  42. package/krl/io.picolabs.portable_subtree.krl +97 -0
  43. package/krl/io.picolabs.subscription.krl +226 -72
  44. package/krl/io.picolabs.wrangler.krl +300 -58
  45. package/mcp/devResources.js +118 -0
  46. package/mcp/devTools.js +351 -0
  47. package/mcp/engineClient.js +133 -0
  48. package/mcp/meshHttp.js +137 -0
  49. package/mcp/meshTools.js +189 -0
  50. package/mcp/runStdio.js +34 -0
  51. package/mcp/schemaToZod.js +56 -0
  52. package/package.json +22 -8
  53. package/public/docs/_sidebar.md +2 -1
  54. package/public/docs/llms-full.txt +479 -0
  55. package/public/docs/llms.txt +37 -0
  56. package/public/docs/openapi.yaml +78 -0
  57. package/public/docs/pico-engine.md +235 -4
  58. package/public/docs/pico-overview.md +117 -0
  59. package/public/docs/pico.md +3 -1
  60. package/public/docs/rulesets/README.md +25 -0
  61. package/public/docs/rulesets/io.picolabs.oauth.md +71 -0
  62. package/public/docs/rulesets/io.picolabs.pds.md +327 -0
  63. package/public/docs/rulesets/io.picolabs.pico-engine-ui.md +65 -0
  64. package/public/docs/rulesets/io.picolabs.portable_subtree.md +94 -0
  65. package/public/docs/rulesets/io.picolabs.subscription.md +398 -0
  66. package/public/docs/rulesets/io.picolabs.wrangler.md +471 -0
  67. package/public/pico-engine-ui.css +1 -1
  68. package/public/pico-engine-ui.js +28 -26
  69. package/src/RulesetRegistryLoaderFs.ts +43 -11
  70. package/src/auth/cookies.ts +34 -0
  71. package/src/auth/index.ts +7 -0
  72. package/src/bundledKrl.ts +150 -12
  73. package/src/channelIdentityPolicy.ts +29 -0
  74. package/src/cli.ts +98 -40
  75. package/src/engineConfig.ts +345 -0
  76. package/src/identity/IdentityService.ts +189 -1
  77. package/src/identity/crossPico.ts +161 -41
  78. package/src/identity/didoModule.ts +140 -23
  79. package/src/identity/establishSubscription.ts +2 -2
  80. package/src/identity/identityPortable.ts +153 -0
  81. package/src/identity/index.ts +14 -0
  82. package/src/identity/localPeerReconcile.ts +97 -0
  83. package/src/identity/peerDid4.ts +197 -0
  84. package/src/identity/peerDid4Create.ts +121 -0
  85. package/src/identity/portableExportPrepare.ts +302 -0
  86. package/src/identity/portableMove.ts +193 -0
  87. package/src/identity/skyIntro.ts +16 -12
  88. package/src/identity/skyProtocol.ts +46 -0
  89. package/src/identity/skyRotation.ts +211 -0
  90. package/src/identity/store.ts +5 -1
  91. package/src/identity/subscriptionEntSync.ts +97 -0
  92. package/src/identity/veramoDidComm.ts +52 -2
  93. package/src/identity/webvh.ts +4 -4
  94. package/src/identity/webvhRelocation.ts +167 -0
  95. package/src/index.ts +179 -39
  96. package/src/levelDb.ts +122 -0
  97. package/src/logging.ts +63 -11
  98. package/src/oauth/OAuthService.ts +20 -6
  99. package/src/oauth/channelEligibility.ts +9 -0
  100. package/src/oauth/index.ts +7 -1
  101. package/src/policyConfigFromJson.ts +131 -0
  102. package/src/runMcp.ts +30 -0
  103. package/src/server.ts +133 -27
  104. package/src/subtreeWrangler.ts +278 -0
  105. package/src/uiChannelPolicies.ts +16 -0
  106. package/krl/io.picolabs.did-o.krl +0 -349
  107. package/krl/test/didtestdid.krl +0 -78
package/README.md CHANGED
@@ -4,6 +4,17 @@
4
4
 
5
5
  An implementation of the [pico-engine](http://www.windley.com/archives/2016/03/rebuilding_krl.shtml) hosted on node.js
6
6
 
7
+ ## Quick start
8
+
9
+ ```sh
10
+ npm install -g pico-engine
11
+ pico-engine
12
+ ```
13
+
14
+ Open `http://localhost:3000` — a root pico and UI channel are created on first run. Operator settings (port, data dir, policy ceiling) live in **`~/.config/pico-engine/config.json`**; copy [`config.example.json`](config.example.json). See [`public/docs/pico-engine.md`](public/docs/pico-engine.md).
15
+
16
+ **Agents (local dev):** [`CLAUDE.md`](../../CLAUDE.md) at repo root + `pico-engine mcp --stdio` (stdio MCP to the same engine). Machine-readable docs: [`public/docs/llms.txt`](public/docs/llms.txt).
17
+
7
18
  ## Getting Started
8
19
 
9
20
  ### Installing
@@ -122,11 +133,95 @@ The server is configured via some environment variables.
122
133
  - `PICO_ENGINE_BASE_URL` - The public url prefix to reach this engine. By default it's `"http://localhost:3000"`
123
134
  - `PICO_ENGINE_ALLOW_SELF_SIGNUP` - Set to `"true"` or `"1"` to allow open registration after bootstrap (default: off; bootstrap and invite still work)
124
135
  - `PICO_ENGINE_ALLOW_LOCALHOST_C` - Set to `"0"` to require passkey session on `/c/*` even from localhost (default: allow localhost without session for in-engine HTTP loops). Full registry: repo `MEMORY.md` § Engine environment variables.
136
+ - `PICO_ENGINE_LOG_FILE` - Log file path. Set to `stdout`, `-`, or `0` for **stdout only** (recommended on Fargate + EFS; use CloudWatch for retention). Default: `$PICO_ENGINE_HOME/pico-engine.log`.
125
137
 
126
138
  The `PORT` is the only value used in setting up the engine’s [nodejs http server](https://nodejs.org/api/net.html#net_server_listen_port_host_backlog_callback). We only specify the `port` so it listens listens to all traffic on that port, it will not filter by host.
127
139
 
128
140
  For example, say you want to have your engine running with SSL on a custom domain i.e. `https://example.com` Starting the engine like this `PICO_ENGINE_BASE_URL=https://example.com pico-engine` is not enough. You will need to use a reverse proxy server like nginx to handle the SSL termination, and then forward the traffic to your private port that is running the engine.
129
141
 
142
+ ### Containers
143
+
144
+ The engine stores mesh state in **LevelDB** under `PICO_ENGINE_HOME`:
145
+
146
+ | Path | Purpose |
147
+ |------|---------|
148
+ | `db/` | Main mesh state (picos, channels, auth, identity, …) |
149
+ | `rulesets-db/` | Cached flushed ruleset metadata (rebuildable from URLs) |
150
+ | `rulesets/` | Compiled ruleset JS |
151
+ | `pico-engine.log` | Rotating log file |
152
+
153
+ On startup the engine opens both LevelDB directories. If a previous process exited uncleanly (e.g. container SIGKILL), startup removes a stale `LOCK` file and may run LevelDB repair before failing.
154
+
155
+ The CLI handles **SIGTERM** and **SIGINT** by closing the HTTP server and both databases cleanly.
156
+
157
+ **Docker Compose (local or any host):**
158
+
159
+ ```yaml
160
+ services:
161
+ pico-engine:
162
+ image: picolabs/pico-engine:1.8.0
163
+ ports:
164
+ - "3001:3000"
165
+ environment:
166
+ PICO_ENGINE_HOME: /var/pico-image
167
+ PICO_ENGINE_BASE_URL: http://localhost:3001
168
+ volumes:
169
+ - pico-engine-data:/var/pico-image
170
+
171
+ volumes:
172
+ pico-engine-data:
173
+ ```
174
+
175
+ Use a **named volume** or bind mount for `PICO_ENGINE_HOME`. Do not run two containers against the same volume.
176
+
177
+ #### Running on AWS ECS / Fargate
178
+
179
+ Fargate has no persistent disk of its own. For a mesh that **survives redeploys and image updates**, mount **Amazon EFS** at `/var/pico-image` and set `PICO_ENGINE_HOME=/var/pico-image`.
180
+
181
+ EFS + LevelDB is a common deployment pattern. LevelDB expects a **single writer**; it is not safe for two tasks to share one database directory. With one Fargate task and graceful shutdown, EFS persistence works well in practice.
182
+
183
+ **Do not use Fargate managed EBS** for durable mesh storage on a service: those volumes are deleted when the task stops, so each deploy would start with an empty mesh unless you build a snapshot workflow.
184
+
185
+ **Task definition (essentials):**
186
+
187
+ | Setting | Value |
188
+ |---------|--------|
189
+ | Container port | `3000` |
190
+ | `PICO_ENGINE_HOME` | `/var/pico-image` |
191
+ | `PICO_ENGINE_BASE_URL` | Public **HTTPS** origin users hit (e.g. `https://picos.example.com`) — required for passkeys and did:webvh |
192
+ | `PICO_ENGINE_LOG_FILE` | `stdout` — log to CloudWatch only; avoid writing `pico-engine.log` on EFS (NFS stale-handle errors can crash the process) |
193
+ | EFS mount | `containerPath`: `/var/pico-image` |
194
+ | Container `stopTimeout` | `120` (seconds) |
195
+
196
+ `PICO_ENGINE_BASE_URL` must match the URL in the browser (scheme, host, no trailing slash). Put TLS at Cloudflare, an ALB, or another reverse proxy in front of the task.
197
+
198
+ **Service deployment:**
199
+
200
+ | Setting | Recommended | Why |
201
+ |---------|-------------|-----|
202
+ | `desiredCount` | `1` | One writer per EFS mount |
203
+ | `minimumHealthyPercent` | `0` | Stop old task before starting new one |
204
+ | `maximumPercent` | `100` | Avoid two tasks on the same volume during deploy |
205
+ | `healthCheckGracePeriodSeconds` | `60`–`120` | Allow startup before health checks fail |
206
+
207
+ **TLS / public URL:** Terminate HTTPS in front of the container (ALB, Cloudflare Tunnel, nginx, etc.). The engine listens on HTTP port 3000 inside the task.
208
+
209
+ **If the engine fails to start** with LevelDB errors after an unclean shutdown:
210
+
211
+ 1. Stop the service (ensure no task is using the volume).
212
+ 2. Remove only the database directories on the EFS mount: `db/` and `rulesets-db/`.
213
+ 3. Start the service again and register a new passkey (fresh mesh).
214
+
215
+ That wipes mesh state but preserves the volume mount and deployment layout. Export/backup of mesh state is a separate operational concern (see repo design docs on pico move/export).
216
+
217
+ **Checklist for operators:**
218
+
219
+ - [ ] EFS mounted at `/var/pico-image`
220
+ - [ ] `PICO_ENGINE_BASE_URL` set to the public HTTPS URL
221
+ - [ ] Single task per EFS volume
222
+ - [ ] `stopTimeout` ≥ 60s; deploy stops old task before starting new one
223
+ - [ ] Image includes graceful shutdown (1.6.x+)
224
+
130
225
  ## Authentication
131
226
 
132
227
  The developer UI uses **passkeys** (WebAuthn). On first visit you register a passkey, which creates your account and root pico. Sign in again with the same passkey; add more passkeys or invite others from **Settings** (gear icon).
@@ -149,12 +244,26 @@ Two grant types can coexist in the same mesh:
149
244
 
150
245
  ### Mesh lock
151
246
 
152
- Install the optional ruleset **`io.picolabs.oauth`** on the **root pico** to require a Bearer token on all **`/sky/*`** requests for that mesh. Without it, open channels work as before (channel policy only); channels tagged **`oauth-webhook`** always require Bearer.
247
+ Install the optional ruleset **`io.picolabs.oauth`** on the **root pico** to require a Bearer token on most **`/sky/*`** requests for that mesh. Without it, open channels work as before (channel policy only); channels tagged **`oauth-webhook`** always require Bearer.
153
248
 
154
249
  From the Rulesets tab, install `io.picolabs.oauth` (KRL source: `packages/pico-engine/krl/io.picolabs.oauth.krl`). Removing the ruleset unlocks the mesh again.
155
250
 
156
251
  Ruleset queries (install `io.picolabs.oauth` on the root): `meshEnabled()`, `meshRequiresOAuth(eci)`, `channelStatus(eci)`, `createChannelSecret(eci)`, … — see `krl/io.picolabs.oauth.krl`.
157
252
 
253
+ **Bearer evaluation order** (engine `skyRequiresBearer`):
254
+
255
+ | Condition | `/sky/*` Bearer required? |
256
+ |-----------|---------------------------|
257
+ | Channel tags `didcomm` + `ingress` | No (DIDComm ingress) |
258
+ | Channel tag `oauth-webhook` | **Yes** (Client Credentials) |
259
+ | Channel tag **`mesh-oauth-exempt`** | **No** (opt out of mesh lock) |
260
+ | Root has `io.picolabs.oauth` | **Yes** (mesh lock) |
261
+ | Otherwise | No |
262
+
263
+ Use **`mesh-oauth-exempt`** on inbound webhook channels that cannot send `Authorization` (e.g. LoRa/Helium POST to `/sky/event/...`) while mesh OAuth stays enabled for integrators (Home Assistant ACG). Tight **event policy** on those channels still applies. If a channel has both `oauth-webhook` and `mesh-oauth-exempt`, **`oauth-webhook` wins** (Bearer required).
264
+
265
+ When mesh OAuth is enabled, the **Channels → New Channel** form offers a one-click **`mesh-oauth-exempt`** tag. Existing channels: add the tag under **Edit channel** → Tags.
266
+
158
267
  ### Webhook credentials (Client Credentials)
159
268
 
160
269
  For channels tagged **`oauth-webhook`** at creation time:
@@ -252,13 +361,7 @@ Authorization: Bearer oat_…
252
361
 
253
362
  ### Building the UI
254
363
 
255
- The root `npm run build` compiles the engine only. To pick up UI changes (Settings, Channels OAuth panels, etc.):
256
-
257
- ```sh
258
- cd packages/pico-engine-ui && npm run build
259
- ```
260
-
261
- That copies the bundle into `packages/pico-engine/public/`. Restart the engine and hard-refresh the browser.
364
+ Repo root `npm run build` includes the UI bundle (via `lerna run build`), copied into `packages/pico-engine/public/`. Restart the engine and hard-refresh the browser after a build.
262
365
 
263
366
  For UI development, run the engine and `npm run dev` in `packages/pico-engine-ui` in separate terminals.
264
367
 
@@ -274,18 +377,18 @@ npm run test:auth # passkeys
274
377
 
275
378
  Tests use isolated temp homes and ephemeral ports; they do not require stopping a running engine.
276
379
 
277
- ## Layer 2 identity and subscriptions (1.6)
380
+ ## Layer 2 identity and relationships (1.6)
278
381
 
279
- Every pico has a portable **did:webvh** identity. **Layer 2 subscriptions** use **`layer2: true`** and a **`target_did`** (did:webvh) instead of the legacy **`wellKnown_Tx`** ECI handshake. After intro, remote traffic uses **did:peer** DIDs and SKY over **DIDComm** when picos are on different meshes or engines.
382
+ Every pico has a portable **did:webvh** identity. **DID-based relationships** (Layer 2) use **`layer2: true`** and a **`target_did`** (did:webvh) instead of the legacy **`wellKnown_Tx`** ECI handshake. After intro, remote traffic uses **did:peer** DIDs and SKY over **DIDComm** when picos are on different meshes or engines. Prefer **`wrangler:relationship`** and **`use module io.picolabs.subscription alias relationship`** in new rulesets; legacy *subscription* event names remain supported.
280
383
 
281
384
  - **Same engine:** intra-mesh queries/events stay local when roots share a mesh.
282
385
  - **Cross-engine:** set a peer-reachable **`PICO_ENGINE_BASE_URL`** on each engine (for local demos, two processes on `localhost:3001` and `:3002` — see below).
283
- - **Developer UI:** **Subscriptions** tab (Layer 2 create, inbound approval, established subs with `Tx_did` / `Rx_did`).
284
- - **Legacy ECI subscriptions** are unchanged.
386
+ - **Developer UI:** **Relationships** tab (DID-based create, inbound approval, established relationships with `Tx_did` / `Rx_did`). A pico cannot target itself (`target_did` / `wellKnown_Tx` checks).
387
+ - **Legacy ECI relationships** are unchanged.
285
388
 
286
389
  **Deprecated:** `io.picolabs.did-o` and `dido:prepareQuery` — use **`wrangler:picoQuery`** and **`event:send({ did: … })`**.
287
390
 
288
- Full guide: [docs/guides/layer2-subscriptions.md](../../docs/guides/layer2-subscriptions.md) · Release notes: [docs/release/1.6.md](../../docs/release/1.6.md)
391
+ Full guide: [docs/guides/layer2-subscriptions.md](../../docs/guides/layer2-subscriptions.md) · Release notes: [docs/release/1.6.md](../../docs/release/1.6.md) · [CHANGELOG.md](../../CHANGELOG.md) (1.6.4 mesh-oauth-exempt + KRL directory UI; 1.6.3 fixes)
289
392
 
290
393
  **Dependency:** pico-engine 1.6 requires **pico-framework `^0.8.1`** (npm). When developing engine + framework together, use `npm run link-framework` from the repo root.
291
394
 
@@ -311,7 +414,7 @@ PICO_ENGINE_HOME=/tmp/pico-engine-a PORT=3001 npm start
311
414
  PICO_ENGINE_HOME=/tmp/pico-engine-b PORT=3002 npm start
312
415
  ```
313
416
 
314
- Open http://localhost:3001 and http://localhost:3002 — register on both, then Layer 2 subscribe A→B. See [docs/guides/layer2-subscriptions.md](../../docs/guides/layer2-subscriptions.md). Test/demo homes live under **`/tmp`** (not `~/.pico-engine`).
417
+ Open http://localhost:3001 and http://localhost:3002 — register on both, then form a Layer 2 relationship A→B. See [docs/guides/layer2-subscriptions.md](../../docs/guides/layer2-subscriptions.md). Test/demo homes live under **`/tmp`** (not `~/.pico-engine`).
315
418
 
316
419
  ## Contributing
317
420
 
@@ -11,16 +11,17 @@ var __rest = (this && this.__rest) || function (s, e) {
11
11
  return t;
12
12
  };
13
13
  Object.defineProperty(exports, "__esModule", { value: true });
14
- exports.RulesetRegistryLoaderFs = RulesetRegistryLoaderFs;
14
+ exports.createRulesetRegistryLoaderFs = createRulesetRegistryLoaderFs;
15
15
  const cross_fetch_1 = require("cross-fetch");
16
16
  const fs = require("fs");
17
- const classic_level_1 = require("classic-level");
18
17
  const makeDir = require("make-dir");
19
18
  const path = require("path");
20
19
  const urlLib = require("url");
21
20
  const bundledKrl_1 = require("./bundledKrl");
21
+ const levelDb_1 = require("./levelDb");
22
22
  const krlCompiler = require("krl-compiler");
23
23
  const krlCompilerVersion = require("krl-compiler/package.json").version;
24
+ const rulesetCompileGeneration = require("krl-compiler/src/rulesetCompileGeneration");
24
25
  const charwise = require("charwise");
25
26
  const safeJsonCodec = require("level-json-coerce-null");
26
27
  function getUrlFilename(url) {
@@ -33,14 +34,17 @@ function getUrlFilename(url) {
33
34
  catch (err) { }
34
35
  return null;
35
36
  }
36
- function RulesetRegistryLoaderFs(engineHomeDir) {
37
+ function compileGenerationDir() {
38
+ return rulesetCompileGeneration().replace(/[^a-zA-Z0-9._-]+/g, "_");
39
+ }
40
+ async function createRulesetRegistryLoaderFs(engineHomeDir, log) {
37
41
  const rulesetDir = path.resolve(engineHomeDir, "rulesets");
38
- const db = new classic_level_1.ClassicLevel(path.resolve(engineHomeDir, "rulesets-db"), {
42
+ const db = await (0, levelDb_1.openClassicLevelWithRecovery)(path.resolve(engineHomeDir, "rulesets-db"), {
39
43
  keyEncoding: charwise,
40
44
  valueEncoding: safeJsonCodec,
41
- });
45
+ }, log);
42
46
  async function compileAndLoad(url, krl, hash) {
43
- const jsFile = path.resolve(rulesetDir, krlCompilerVersion, hash.substr(0, 2), hash.substr(2, 2), hash + ".js");
47
+ const jsFile = path.resolve(rulesetDir, compileGenerationDir(), hash.substr(0, 2), hash.substr(2, 2), hash + ".js");
44
48
  let compileWarnings = [];
45
49
  if (await fsExist(jsFile)) {
46
50
  // already compiled
@@ -62,13 +66,21 @@ function RulesetRegistryLoaderFs(engineHomeDir) {
62
66
  });
63
67
  }
64
68
  const ruleset = require(jsFile);
69
+ const compileGeneration = rulesetCompileGeneration();
65
70
  return {
66
71
  ruleset,
67
- compiler: { version: krlCompilerVersion, warnings: compileWarnings },
72
+ compiler: {
73
+ version: krlCompilerVersion,
74
+ warnings: compileWarnings,
75
+ compileGeneration,
76
+ },
68
77
  };
69
78
  }
70
- return {
79
+ const loader = {
71
80
  fetchKrl,
81
+ getCompileGeneration() {
82
+ return rulesetCompileGeneration();
83
+ },
72
84
  async save(_a) {
73
85
  var { ruleset } = _a, rest = __rest(_a, ["ruleset"]);
74
86
  let toWrite = rest;
@@ -91,6 +103,10 @@ function RulesetRegistryLoaderFs(engineHomeDir) {
91
103
  compiler });
92
104
  },
93
105
  };
106
+ return {
107
+ loader,
108
+ close: () => db.close(),
109
+ };
94
110
  }
95
111
  async function fetchKrl(url) {
96
112
  url = (0, bundledKrl_1.resolveBundledKrlUrl)(url);
@@ -0,0 +1,32 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.DEFAULT_CEREMONY_COOKIE = exports.DEFAULT_SESSION_COOKIE = void 0;
4
+ exports.authCookieNames = authCookieNames;
5
+ exports.sessionCookieHeader = sessionCookieHeader;
6
+ exports.DEFAULT_SESSION_COOKIE = "pico-session";
7
+ exports.DEFAULT_CEREMONY_COOKIE = "pico-ceremony";
8
+ /** Session/ceremony cookie names scoped by port on local dev hosts. */
9
+ function authCookieNames(origin) {
10
+ try {
11
+ const url = new URL(origin);
12
+ const local = url.hostname === "localhost" ||
13
+ url.hostname === "127.0.0.1" ||
14
+ url.hostname.endsWith(".localhost");
15
+ if (local && url.port) {
16
+ return {
17
+ session: `${exports.DEFAULT_SESSION_COOKIE}-${url.port}`,
18
+ ceremony: `${exports.DEFAULT_CEREMONY_COOKIE}-${url.port}`,
19
+ };
20
+ }
21
+ }
22
+ catch (_e) {
23
+ // fall through
24
+ }
25
+ return {
26
+ session: exports.DEFAULT_SESSION_COOKIE,
27
+ ceremony: exports.DEFAULT_CEREMONY_COOKIE,
28
+ };
29
+ }
30
+ function sessionCookieHeader(origin, token) {
31
+ return `${authCookieNames(origin).session}=${token}`;
32
+ }
@@ -1,8 +1,13 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.makeWebAuthnAdapter = exports.AuthError = exports.AuthService = void 0;
3
+ exports.DEFAULT_CEREMONY_COOKIE = exports.DEFAULT_SESSION_COOKIE = exports.sessionCookieHeader = exports.authCookieNames = exports.makeWebAuthnAdapter = exports.AuthError = exports.AuthService = void 0;
4
4
  var AuthService_1 = require("./AuthService");
5
5
  Object.defineProperty(exports, "AuthService", { enumerable: true, get: function () { return AuthService_1.AuthService; } });
6
6
  Object.defineProperty(exports, "AuthError", { enumerable: true, get: function () { return AuthService_1.AuthError; } });
7
7
  var webauthn_1 = require("./webauthn");
8
8
  Object.defineProperty(exports, "makeWebAuthnAdapter", { enumerable: true, get: function () { return webauthn_1.makeWebAuthnAdapter; } });
9
+ var cookies_1 = require("./cookies");
10
+ Object.defineProperty(exports, "authCookieNames", { enumerable: true, get: function () { return cookies_1.authCookieNames; } });
11
+ Object.defineProperty(exports, "sessionCookieHeader", { enumerable: true, get: function () { return cookies_1.sessionCookieHeader; } });
12
+ Object.defineProperty(exports, "DEFAULT_SESSION_COOKIE", { enumerable: true, get: function () { return cookies_1.DEFAULT_SESSION_COOKIE; } });
13
+ Object.defineProperty(exports, "DEFAULT_CEREMONY_COOKIE", { enumerable: true, get: function () { return cookies_1.DEFAULT_CEREMONY_COOKIE; } });
@@ -1,7 +1,13 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.BUNDLED_KRL_FILES = void 0;
3
+ exports.ROOT_ONLY_RULESET_RIDS = exports.BUNDLED_KRL_FILES = void 0;
4
4
  exports.bundledKrlDir = bundledKrlDir;
5
+ exports.listEngineKrlRelativePaths = listEngineKrlRelativePaths;
6
+ exports.engineKrlHttpPath = engineKrlHttpPath;
7
+ exports.engineKrlFileUrl = engineKrlFileUrl;
8
+ exports.listEngineKrlSources = listEngineKrlSources;
9
+ exports.engineKrlRelativeFromUrl = engineKrlRelativeFromUrl;
10
+ exports.resolveEngineKrlFile = resolveEngineKrlFile;
5
11
  exports.resolveBundledKrlUrl = resolveBundledKrlUrl;
6
12
  const fs = require("fs");
7
13
  const path = require("path");
@@ -17,25 +23,137 @@ exports.BUNDLED_KRL_FILES = [
17
23
  "io.picolabs.subscription.krl",
18
24
  "io.picolabs.pds.krl",
19
25
  ];
26
+ /** Rulesets that only function when installed on the mesh root pico. */
27
+ exports.ROOT_ONLY_RULESET_RIDS = new Set(["io.picolabs.oauth"]);
20
28
  function bundledKrlDir() {
21
29
  return path.resolve(__dirname, "..", "krl");
22
30
  }
23
- function resolveBundledKrlUrl(url) {
24
- let filename = null;
25
- try {
26
- const parsed = new URL(url);
27
- if (parsed.protocol === "file:") {
28
- filename = path.basename(parsed.pathname);
31
+ function walkKrlFiles(dir, baseDir, out) {
32
+ for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
33
+ const fullPath = path.join(dir, entry.name);
34
+ if (entry.isDirectory()) {
35
+ walkKrlFiles(fullPath, baseDir, out);
36
+ continue;
37
+ }
38
+ if (entry.isFile() && entry.name.endsWith(".krl")) {
39
+ out.push(path.relative(baseDir, fullPath).split(path.sep).join("/"));
40
+ }
41
+ }
42
+ }
43
+ /** All `.krl` files under the engine's shipped `krl/` directory. */
44
+ function listEngineKrlRelativePaths() {
45
+ const root = bundledKrlDir();
46
+ if (!fs.existsSync(root)) {
47
+ return [];
48
+ }
49
+ const paths = [];
50
+ walkKrlFiles(root, root, paths);
51
+ return paths.sort();
52
+ }
53
+ function ridFromRelativePath(relativePath) {
54
+ const basename = path.basename(relativePath, ".krl");
55
+ return basename;
56
+ }
57
+ function readKrlMeta(filePath) {
58
+ const text = fs.readFileSync(filePath, { encoding: "utf8", flag: "r" }).slice(0, 4000);
59
+ const ridMatch = text.match(/^ruleset\s+(\S+)/m);
60
+ const nameMatch = text.match(/\bname\s+"([^"]+)"/);
61
+ let description;
62
+ const descQuoted = text.match(/\bdescription\s+"([^"]+)"/);
63
+ if (descQuoted) {
64
+ description = descQuoted[1];
65
+ }
66
+ else {
67
+ const descHere = text.match(/\bdescription\s+<<\s*([\s\S]*?)\s*>>/);
68
+ if (descHere) {
69
+ description = descHere[1].replace(/\s+/g, " ").trim();
29
70
  }
30
71
  }
72
+ return {
73
+ rid: ridMatch ? ridMatch[1] : ridFromRelativePath(path.basename(filePath)),
74
+ name: nameMatch ? nameMatch[1] : undefined,
75
+ description,
76
+ };
77
+ }
78
+ function engineKrlHttpPath(relativePath) {
79
+ return `/krl/${relativePath.split(path.sep).join("/")}`;
80
+ }
81
+ function engineKrlFileUrl(relativePath, baseUrl) {
82
+ if (baseUrl) {
83
+ return `${baseUrl.replace(/\/$/, "")}${engineKrlHttpPath(relativePath)}`;
84
+ }
85
+ return (0, toFileUrl_1.toFileUrl)(path.join(bundledKrlDir(), relativePath));
86
+ }
87
+ function listEngineKrlSources(baseUrl) {
88
+ const root = bundledKrlDir();
89
+ return listEngineKrlRelativePaths().map((relativePath) => {
90
+ const filePath = path.join(root, relativePath);
91
+ const meta = readKrlMeta(filePath);
92
+ const filename = path.basename(relativePath);
93
+ return {
94
+ rid: meta.rid,
95
+ filename,
96
+ relativePath,
97
+ url: engineKrlFileUrl(relativePath, baseUrl),
98
+ name: meta.name,
99
+ description: meta.description,
100
+ rootOnly: exports.ROOT_ONLY_RULESET_RIDS.has(meta.rid),
101
+ };
102
+ });
103
+ }
104
+ /** Map a URL to a relative path under `krl/`, if it refers to an engine-shipped ruleset. */
105
+ function engineKrlRelativeFromUrl(url) {
106
+ let parsed;
107
+ try {
108
+ parsed = new URL(url);
109
+ }
31
110
  catch (_a) {
32
- return url;
111
+ return null;
112
+ }
113
+ if (parsed.protocol === "file:") {
114
+ const filePath = decodeURI(parsed.pathname).replace(/^\/([a-z]:\/)/i, "$1");
115
+ const normalized = path.normalize(filePath);
116
+ const root = bundledKrlDir();
117
+ if (normalized.startsWith(root + path.sep) || normalized === root) {
118
+ return path.relative(root, normalized).split(path.sep).join("/");
119
+ }
120
+ const basename = path.basename(normalized);
121
+ const candidate = path.join(root, basename);
122
+ if (basename.endsWith(".krl") && fs.existsSync(candidate)) {
123
+ return basename;
124
+ }
125
+ return null;
33
126
  }
34
- if (!filename || !exports.BUNDLED_KRL_FILES.includes(filename)) {
127
+ if (parsed.protocol === "http:" || parsed.protocol === "https:") {
128
+ const match = parsed.pathname.match(/^\/krl\/(.+\.krl)$/);
129
+ if (match) {
130
+ const relativePath = match[1].split("/").join(path.sep);
131
+ const candidate = path.join(bundledKrlDir(), relativePath);
132
+ if (fs.existsSync(candidate)) {
133
+ return match[1];
134
+ }
135
+ }
136
+ }
137
+ return null;
138
+ }
139
+ function resolveEngineKrlFile(relativePath) {
140
+ const normalized = relativePath.split("/").join(path.sep);
141
+ const candidate = path.resolve(bundledKrlDir(), normalized);
142
+ const root = bundledKrlDir();
143
+ if (candidate.startsWith(root + path.sep) &&
144
+ fs.existsSync(candidate) &&
145
+ candidate.endsWith(".krl")) {
146
+ return candidate;
147
+ }
148
+ return null;
149
+ }
150
+ function resolveBundledKrlUrl(url) {
151
+ const relativePath = engineKrlRelativeFromUrl(url);
152
+ if (!relativePath) {
35
153
  return url;
36
154
  }
37
- const localPath = path.join(bundledKrlDir(), filename);
38
- if (fs.existsSync(localPath)) {
155
+ const localPath = resolveEngineKrlFile(relativePath);
156
+ if (localPath) {
39
157
  return (0, toFileUrl_1.toFileUrl)(localPath);
40
158
  }
41
159
  return url;
@@ -0,0 +1,22 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.wildcardSkyRequireBearerEnabled = wildcardSkyRequireBearerEnabled;
4
+ exports.channelHasUnrestrictedAllow = channelHasUnrestrictedAllow;
5
+ exports.isDidcommIngressChannel = isDidcommIngressChannel;
6
+ const pico_framework_1 = require("pico-framework");
7
+ const engineConfig_1 = require("./engineConfig");
8
+ /** See {@link EngineSettings.wildcardSkyRequireBearer} (config file or env). */
9
+ function wildcardSkyRequireBearerEnabled() {
10
+ return (0, engineConfig_1.getEngineRuntimeSettings)().wildcardSkyRequireBearer;
11
+ }
12
+ /**
13
+ * True when the channel grants unrestricted events or queries (*.* allow rules).
14
+ * Such channels require an authenticated HTTP caller (OAuth bearer or /c/* session).
15
+ */
16
+ function channelHasUnrestrictedAllow(channel) {
17
+ return ((0, pico_framework_1.hasUnrestrictedEventAllow)(channel.eventPolicy) ||
18
+ (0, pico_framework_1.hasUnrestrictedQueryAllow)(channel.queryPolicy));
19
+ }
20
+ function isDidcommIngressChannel(channel) {
21
+ return (channel.tags.includes("didcomm") && channel.tags.includes("ingress"));
22
+ }
package/dist/cli.js CHANGED
@@ -1,59 +1,118 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  const index_1 = require("./index");
4
+ const engineConfig_1 = require("./engineConfig");
4
5
  const version = require("../package.json").version;
5
- const args = require("minimist")(process.argv.slice(2), {
6
- boolean: ["help", "version"],
7
- alias: {
8
- help: "h",
9
- },
10
- });
11
- if (args.version) {
12
- console.log(version);
6
+ let argv;
7
+ try {
8
+ argv = (0, engineConfig_1.applyConfigCliArgs)(process.argv.slice(2));
9
+ }
10
+ catch (err) {
11
+ console.error(err instanceof Error ? err.message : err);
12
+ process.exit(1);
13
+ }
14
+ if (argv[0] === "mcp") {
15
+ Promise.resolve().then(() => require("./runMcp")).then(({ runMcpCli }) => runMcpCli(argv))
16
+ .catch((err) => {
17
+ console.error(err);
18
+ process.exit(1);
19
+ });
20
+ }
21
+ else if (argv[0] === "config" && argv[1] === "path") {
22
+ const { resolveEngineConfigFilePath, defaultEngineConfigFilePath } = require("./engineConfig");
23
+ const target = resolveEngineConfigFilePath();
24
+ console.log(target);
25
+ if (target === defaultEngineConfigFilePath()) {
26
+ console.error("(default; copy packages/pico-engine/config.example.json here to customize)");
27
+ }
13
28
  process.exit(0);
14
29
  }
15
- if (args.help) {
16
- console.log(`
30
+ else {
31
+ startPicoEngineCli();
32
+ }
33
+ function startPicoEngineCli() {
34
+ const args = require("minimist")(argv, {
35
+ boolean: ["help", "version"],
36
+ alias: {
37
+ help: "h",
38
+ },
39
+ });
40
+ if (args.version) {
41
+ console.log(version);
42
+ process.exit(0);
43
+ }
44
+ if (args.help) {
45
+ console.log(`
17
46
  USAGE
18
47
 
19
- pico-engine [--version] [--help|-h]
48
+ pico-engine [--config|-c <path>] [--version] [--help|-h]
49
+ pico-engine [--config|-c <path>] config path
50
+ pico-engine [--config|-c <path>] mcp --stdio
51
+
52
+ Multiple engines on one machine: use a separate config file per process (unique
53
+ home, port, baseUrl). Examples: packages/pico-engine/config.instances.example/
54
+ and docker/config/ for compose.
55
+
56
+ Configuration (preferred):
57
+
58
+ ~/.config/pico-engine/config.json
59
+ (or --config / PICO_ENGINE_CONFIG to another file path)
20
60
 
21
- Environment Variables:
61
+ See packages/pico-engine/config.example.json (and config.policy-ceiling.example.json for 1.8 policy fields).
62
+ Precedence: defaults → environment variables → config file → tests/API overrides.
63
+ (Config file wins over PORT and PICO_ENGINE_HOME when both are set; env fills gaps the file omits.)
22
64
 
23
- PORT - The port the http server should listen on. By default it's 3000
24
- PICO_ENGINE_HOME - Where the database and other files should be stored. By default it's ~/.pico-engine/
25
- PICO_ENGINE_BASE_URL - The public url prefix to reach this engine. By default it's http://localhost:$PORT
26
- PICO_ENGINE_ALLOW_SELF_SIGNUP - Set to "true" or "1" to allow anyone to register a new account
27
- after the engine is bootstrapped. Default is false (login only; bootstrap and invite still work).
28
- PICO_ENGINE_ALLOW_LOCALHOST_C - Set to "0" to require passkey session on /c/* even from localhost.
29
- Default (unset) allows localhost without session for in-engine ctx:event HTTP loops. See MEMORY.md.
65
+ Environment (optional; Docker/CI when not set in config file):
66
+
67
+ PORT - HTTP listen port
68
+ PICO_ENGINE_CONFIG - Path to config JSON (default ~/.config/pico-engine/config.json)
69
+ PICO_ENGINE_HOME - Data directory (DB, ruleset cache); overridden by config "home" when present
70
+ PICO_ENGINE_BASE_URL - Public URL (WebAuthn, did:webvh)
71
+ PICO_ENGINE_RP_ID / PICO_ENGINE_ORIGIN - WebAuthn (or use webauthn block in config file)
72
+ PICO_ENGINE_ALLOW_SELF_SIGNUP - "true"/"1" or "false"/"0"
73
+ PICO_ENGINE_ALLOW_LOCALHOST_C - "0" disables localhost /c/* bypass (see config allowLocalhostChannelBypass)
74
+ PICO_ENGINE_WILDCARD_SKY_REQUIRE_BEARER - "1" enables wildcard /sky/* bearer requirement
75
+ PICO_ENGINE_LOG_FILE - Log path, or stdout/- / 0 for console only
30
76
  `);
31
- process.exit(0);
32
- }
33
- const env = {};
34
- if (process.env.PORT) {
35
- const port = parseInt(process.env.PORT, 10);
36
- if (port > 0) {
37
- env.port = port;
77
+ process.exit(0);
38
78
  }
79
+ const settings = (0, engineConfig_1.resolveEngineSettings)({});
80
+ const env = {
81
+ home: settings.home,
82
+ port: settings.port,
83
+ base_url: settings.baseUrl,
84
+ rpID: settings.rpID,
85
+ rpName: settings.rpName,
86
+ origin: settings.origin,
87
+ allowSelfSignup: settings.allowSelfSignup,
88
+ };
89
+ function installGracefulShutdown(engine) {
90
+ let shuttingDown = false;
91
+ const onSignal = (signal) => {
92
+ if (shuttingDown) {
93
+ return;
94
+ }
95
+ shuttingDown = true;
96
+ console.log(`Received ${signal}; shutting down`);
97
+ engine
98
+ .shutdown()
99
+ .then(() => process.exit(0))
100
+ .catch((err) => {
101
+ console.error("Shutdown failed.");
102
+ console.error(err);
103
+ process.exit(1);
104
+ });
105
+ };
106
+ process.on("SIGTERM", onSignal);
107
+ process.on("SIGINT", onSignal);
108
+ }
109
+ (0, index_1.startEngine)(env)
110
+ .then((engine) => {
111
+ installGracefulShutdown(engine);
112
+ })
113
+ .catch((err) => {
114
+ console.error("Failed to start engine.");
115
+ console.error(err);
116
+ process.exit(1);
117
+ });
39
118
  }
40
- if (typeof process.env.PICO_ENGINE_HOME === "string" &&
41
- process.env.PICO_ENGINE_HOME.length > 0) {
42
- env.home = process.env.PICO_ENGINE_HOME;
43
- }
44
- if (typeof process.env.PICO_ENGINE_BASE_URL === "string" &&
45
- process.env.PICO_ENGINE_BASE_URL.length > 0) {
46
- env.base_url = process.env.PICO_ENGINE_BASE_URL;
47
- }
48
- const allowSelfSignupEnv = process.env.PICO_ENGINE_ALLOW_SELF_SIGNUP;
49
- if (allowSelfSignupEnv === "true" || allowSelfSignupEnv === "1") {
50
- env.allowSelfSignup = true;
51
- }
52
- else if (allowSelfSignupEnv === "false" || allowSelfSignupEnv === "0") {
53
- env.allowSelfSignup = false;
54
- }
55
- (0, index_1.startEngine)(env).catch((err) => {
56
- console.error("Failed to start engine.");
57
- console.error(err);
58
- process.exit(1);
59
- });