pico-engine 1.4.0 → 1.6.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 (82) hide show
  1. package/README.md +188 -0
  2. package/dist/RulesetRegistryLoaderFs.js +2 -0
  3. package/dist/auth/AuthService.js +601 -0
  4. package/dist/auth/index.js +8 -0
  5. package/dist/auth/webauthn.js +97 -0
  6. package/dist/bundledKrl.js +42 -0
  7. package/dist/cli.js +11 -0
  8. package/dist/identity/IdentityService.js +340 -0
  9. package/dist/identity/crossPico.js +238 -0
  10. package/dist/identity/dbHelpers.js +67 -0
  11. package/dist/identity/didcommIngressRoutes.js +44 -0
  12. package/dist/identity/didoModule.js +252 -0
  13. package/dist/identity/errors.js +11 -0
  14. package/dist/identity/establishSubscription.js +97 -0
  15. package/dist/identity/index.js +15 -0
  16. package/dist/identity/peerDid.js +9 -0
  17. package/dist/identity/skyIntro.js +194 -0
  18. package/dist/identity/skyProtocol.js +105 -0
  19. package/dist/identity/store.js +233 -0
  20. package/dist/identity/types.js +13 -0
  21. package/dist/identity/veramoDidComm.js +260 -0
  22. package/dist/identity/webvh.js +266 -0
  23. package/dist/identity/webvhCrypto.js +128 -0
  24. package/dist/identity/webvhRoutes.js +61 -0
  25. package/dist/index.js +100 -44
  26. package/dist/oauth/OAuthService.js +388 -0
  27. package/dist/oauth/acg.js +495 -0
  28. package/dist/oauth/channelEligibility.js +26 -0
  29. package/dist/oauth/errors.js +12 -0
  30. package/dist/oauth/index.js +21 -0
  31. package/dist/oauth/krlModule.js +27 -0
  32. package/dist/oauth/meshOAuth.js +43 -0
  33. package/dist/provisionRoot.js +118 -0
  34. package/dist/server.js +609 -15
  35. package/dist/uiChannelPolicies.js +48 -0
  36. package/krl/io.picolabs.did-o.krl +5 -1
  37. package/krl/io.picolabs.oauth.krl +48 -0
  38. package/krl/io.picolabs.pico-engine-ui.krl +106 -18
  39. package/krl/io.picolabs.subscription.krl +242 -23
  40. package/krl/io.picolabs.wrangler.krl +225 -16
  41. package/package.json +38 -9
  42. package/public/docs/krl/_sidebar.md +1 -0
  43. package/public/docs/krl/discovery.md +144 -0
  44. package/public/docs/krl/modules/ctx.md +8 -0
  45. package/public/docs/krl/modules/event.md +41 -0
  46. package/public/pico-engine-ui.css +1 -1
  47. package/public/pico-engine-ui.js +24 -20
  48. package/public/pico-labs-logo.png +0 -0
  49. package/src/RulesetRegistryLoaderFs.ts +2 -0
  50. package/src/auth/AuthService.ts +850 -0
  51. package/src/auth/index.ts +17 -0
  52. package/src/auth/webauthn.ts +182 -0
  53. package/src/bundledKrl.ts +42 -0
  54. package/src/cli.ts +11 -0
  55. package/src/identity/IdentityService.ts +571 -0
  56. package/src/identity/crossPico.ts +371 -0
  57. package/src/identity/dbHelpers.ts +51 -0
  58. package/src/identity/didcommIngressRoutes.ts +54 -0
  59. package/src/identity/didoModule.ts +388 -0
  60. package/src/identity/errors.ts +8 -0
  61. package/src/identity/establishSubscription.ts +160 -0
  62. package/src/identity/index.ts +24 -0
  63. package/src/identity/peerDid.ts +22 -0
  64. package/src/identity/skyIntro.ts +321 -0
  65. package/src/identity/skyProtocol.ts +192 -0
  66. package/src/identity/store.ts +343 -0
  67. package/src/identity/types.ts +63 -0
  68. package/src/identity/veramoDidComm.ts +363 -0
  69. package/src/identity/webvh.ts +325 -0
  70. package/src/identity/webvhCrypto.ts +200 -0
  71. package/src/identity/webvhRoutes.ts +64 -0
  72. package/src/index.ts +145 -53
  73. package/src/oauth/OAuthService.ts +510 -0
  74. package/src/oauth/acg.ts +666 -0
  75. package/src/oauth/channelEligibility.ts +26 -0
  76. package/src/oauth/errors.ts +10 -0
  77. package/src/oauth/index.ts +14 -0
  78. package/src/oauth/krlModule.ts +31 -0
  79. package/src/oauth/meshOAuth.ts +50 -0
  80. package/src/provisionRoot.ts +151 -0
  81. package/src/server.ts +700 -24
  82. package/src/uiChannelPolicies.ts +49 -0
package/README.md CHANGED
@@ -120,11 +120,199 @@ The server is configured via some environment variables.
120
120
  - `PORT` - The port the http server should listen on. By default it's `3000`
121
121
  - `PICO_ENGINE_HOME` - Where the database and other files should be stored. By default it's `~/.pico-engine/`
122
122
  - `PICO_ENGINE_BASE_URL` - The public url prefix to reach this engine. By default it's `"http://localhost:3000"`
123
+ - `PICO_ENGINE_ALLOW_SELF_SIGNUP` - Set to `"true"` or `"1"` to allow open registration after bootstrap (default: off; bootstrap and invite still work)
124
+ - `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.
123
125
 
124
126
  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.
125
127
 
126
128
  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.
127
129
 
130
+ ## Authentication
131
+
132
+ 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).
133
+
134
+ When self-signup is disabled, **Settings → Invite someone** can include an optional **bootstrap ruleset URL** (`file://` or `https://`). The engine validates the URL when the invite is created; when the invitee registers, that ruleset is installed on their new root after the base OS rulesets (e.g. a Manifold bootstrap KRL). The invite **label** pre-fills the invitee's mesh name (editable before registering). WebAuthn `user.name` is set to the mesh name so password managers (e.g. 1Password) show it alongside the site hostname.
135
+
136
+ - **`/c/*`** — internal/UI API; requires a passkey session cookie (localhost bypass is on by default for in-engine KRL HTTP loops; set `PICO_ENGINE_ALLOW_LOCALHOST_C=0` to disable).
137
+ - **`/auth/*`** — registration, login, session management.
138
+
139
+ ## OAuth
140
+
141
+ OAuth protects external access to the mesh on **`/sky/*`**. The UI and in-engine loops continue to use passkey sessions on **`/c/*`**.
142
+
143
+ Two grant types can coexist in the same mesh:
144
+
145
+ | Grant | Use case | Client ID | Scope |
146
+ |-------|----------|-----------|-------|
147
+ | **Client Credentials** | Inbound webhooks (Stripe, GitHub, …) | Channel **ECI** | Single channel only |
148
+ | **Authorization Code + PKCE** | Apps like Home Assistant | `app_…` | Whole mesh (root + descendants) |
149
+
150
+ ### Mesh lock
151
+
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.
153
+
154
+ 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
+
156
+ Ruleset queries (install `io.picolabs.oauth` on the root): `meshEnabled()`, `meshRequiresOAuth(eci)`, `channelStatus(eci)`, `createChannelSecret(eci)`, … — see `krl/io.picolabs.oauth.krl`.
157
+
158
+ ### Webhook credentials (Client Credentials)
159
+
160
+ For channels tagged **`oauth-webhook`** at creation time:
161
+
162
+ 1. Open the channel in the **Channels** tab.
163
+ 2. **Create credentials** — `client_id` is the channel ECI; copy the `client_secret` (shown once).
164
+ 3. Mint a test token in the UI, or call `POST /oauth/token`:
165
+
166
+ ```http
167
+ POST /oauth/token
168
+ Content-Type: application/json
169
+
170
+ {
171
+ "grant_type": "client_credentials",
172
+ "client_id": "<channel-eci>",
173
+ "client_secret": "<secret>"
174
+ }
175
+ ```
176
+
177
+ The returned **`oat_…`** access token works only on **`/sky/*`** URLs for **that ECI**.
178
+
179
+ Family, subscription, and system channels are not eligible.
180
+
181
+ ### OAuth apps (Authorization Code)
182
+
183
+ For integrators that need access across the mesh (e.g. Home Assistant):
184
+
185
+ 1. Install **`io.picolabs.oauth`** on the root pico (mesh lock).
186
+ 2. **Settings → OAuth apps** — register an app (name, redirect URIs, public vs confidential client). The **client ID** (`app_…`) is not secret; a confidential client’s **secret** is shown once.
187
+ 3. The app sends the user to authorize; after passkey consent, the app exchanges the code for tokens.
188
+
189
+ **Authorize** (browser; user must be signed in):
190
+
191
+ ```http
192
+ GET /oauth/authorize?client_id=app_…&redirect_uri=…&response_type=code&code_challenge=…&code_challenge_method=S256&scope=mesh
193
+ ```
194
+
195
+ Unauthenticated users are redirected to sign in and then returned to authorize (`/?oauth_return=…`).
196
+
197
+ **Token exchange** (must be **POST**, not a browser GET with query params):
198
+
199
+ ```http
200
+ POST /oauth/token
201
+ Content-Type: application/json
202
+
203
+ {
204
+ "grant_type": "authorization_code",
205
+ "code": "oac_…",
206
+ "redirect_uri": "…",
207
+ "client_id": "app_…",
208
+ "code_verifier": "…"
209
+ }
210
+ ```
211
+
212
+ For manual testing with plain PKCE, use `code_challenge_method=plain` and set `code_challenge` and `code_verifier` to the same string.
213
+
214
+ **Refresh:**
215
+
216
+ ```http
217
+ POST /oauth/token
218
+ Content-Type: application/json
219
+
220
+ {
221
+ "grant_type": "refresh_token",
222
+ "refresh_token": "ort_…",
223
+ "client_id": "app_…"
224
+ }
225
+ ```
226
+
227
+ **Use the access token** on any channel ECI in the mesh:
228
+
229
+ ```http
230
+ GET /sky/query/<eci>/io.picolabs.wrangler/name
231
+ Authorization: Bearer oat_…
232
+ ```
233
+
234
+ ### Token prefixes
235
+
236
+ | Prefix | Meaning |
237
+ |--------|---------|
238
+ | `oac_` | Authorization code (single-use, ~10 min) — exchange at `/oauth/token`, not a Bearer token |
239
+ | `oat_` | Access token — use on **`/sky/*`** |
240
+ | `ort_` | Refresh token — use at `/oauth/token` only |
241
+
242
+ ### OAuth HTTP endpoints
243
+
244
+ | Method | Path | Auth | Purpose |
245
+ |--------|------|------|---------|
246
+ | `POST` | `/oauth/token` | Public | Client credentials, authorization code, refresh token |
247
+ | `GET` | `/oauth/token` | Public | Dev-friendly alias (query params); prefer POST |
248
+ | `GET` | `/oauth/authorize` | Passkey session | Authorization code + PKCE; consent page |
249
+ | `POST` | `/oauth/approve` | Passkey session | Consent form handler |
250
+ | `GET/POST/DELETE` | `/oauth/apps` | Passkey session | Register/list/revoke OAuth apps |
251
+ | `GET/POST/DELETE` | `/oauth/channels/:eci/*` | Passkey session | Webhook credential management |
252
+
253
+ ### Building the UI
254
+
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.
262
+
263
+ For UI development, run the engine and `npm run dev` in `packages/pico-engine-ui` in separate terminals.
264
+
265
+ ### OAuth tests
266
+
267
+ ```sh
268
+ cd packages/pico-engine
269
+ npm run test:oauth # webhook Client Credentials
270
+ npm run test:acg # authorization code + refresh
271
+ npm run test:http # /c/* vs /sky/* surface + mesh lock
272
+ npm run test:auth # passkeys
273
+ ```
274
+
275
+ Tests use isolated temp homes and ephemeral ports; they do not require stopping a running engine.
276
+
277
+ ## Layer 2 identity and subscriptions (1.6)
278
+
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.
280
+
281
+ - **Same engine:** intra-mesh queries/events stay local when roots share a mesh.
282
+ - **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.
285
+
286
+ **Deprecated:** `io.picolabs.did-o` and `dido:prepareQuery` — use **`wrangler:picoQuery`** and **`event:send({ did: … })`**.
287
+
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)
289
+
290
+ **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
+
292
+ ### Layer 2 tests
293
+
294
+ ```sh
295
+ cd packages/pico-engine
296
+ npm run test:epic9 # release regression matrix
297
+ npm run test:cross-engine # two engines, intro + query + event
298
+ npm run test:layer2-wrangler
299
+ npm run test:layer2-policy
300
+ ```
301
+
302
+ ### Cross-engine demo (two processes on one machine)
303
+
304
+ Use separate data directories and ports so each engine is an independent mesh. `PICO_ENGINE_BASE_URL` defaults to `http://localhost:$PORT`, which works for passkeys and for peer DID fetch (same as `npm run test:cross-engine`).
305
+
306
+ ```sh
307
+ # terminal 1
308
+ PICO_ENGINE_HOME=/tmp/pico-engine-a PORT=3001 npm start
309
+
310
+ # terminal 2 (from repo root)
311
+ PICO_ENGINE_HOME=/tmp/pico-engine-b PORT=3002 npm start
312
+ ```
313
+
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`).
315
+
128
316
  ## Contributing
129
317
 
130
318
  See the repository [root readme](https://github.com/Picolab/pico-engine#readme)
@@ -18,6 +18,7 @@ const classic_level_1 = require("classic-level");
18
18
  const makeDir = require("make-dir");
19
19
  const path = require("path");
20
20
  const urlLib = require("url");
21
+ const bundledKrl_1 = require("./bundledKrl");
21
22
  const krlCompiler = require("krl-compiler");
22
23
  const krlCompilerVersion = require("krl-compiler/package.json").version;
23
24
  const charwise = require("charwise");
@@ -92,6 +93,7 @@ function RulesetRegistryLoaderFs(engineHomeDir) {
92
93
  };
93
94
  }
94
95
  async function fetchKrl(url) {
96
+ url = (0, bundledKrl_1.resolveBundledKrlUrl)(url);
95
97
  const urlParsed = urlLib.parse(url);
96
98
  if (urlParsed.protocol === "file:") {
97
99
  return new Promise((resolve, reject) => {