pico-engine 1.3.0 → 1.5.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 (43) hide show
  1. package/README.md +147 -0
  2. package/dist/RulesetRegistryLoaderFs.js +4 -7
  3. package/dist/auth/AuthService.js +537 -0
  4. package/dist/auth/index.js +8 -0
  5. package/dist/auth/webauthn.js +97 -0
  6. package/dist/cli.js +11 -0
  7. package/dist/index.js +83 -46
  8. package/dist/logging.js +36 -27
  9. package/dist/oauth/OAuthService.js +356 -0
  10. package/dist/oauth/acg.js +495 -0
  11. package/dist/oauth/channelEligibility.js +26 -0
  12. package/dist/oauth/errors.js +12 -0
  13. package/dist/oauth/index.js +21 -0
  14. package/dist/oauth/krlModule.js +27 -0
  15. package/dist/oauth/meshOAuth.js +43 -0
  16. package/dist/provisionRoot.js +80 -0
  17. package/dist/server.js +565 -17
  18. package/dist/utils/toFileUrl.js +1 -2
  19. package/krl/io.picolabs.did-o.krl +25 -5
  20. package/krl/io.picolabs.oauth.krl +48 -0
  21. package/krl/io.picolabs.pds.krl +344 -0
  22. package/krl/io.picolabs.pico-engine-ui.krl +43 -10
  23. package/krl/io.picolabs.wrangler.krl +21 -20
  24. package/package.json +29 -29
  25. package/public/pico-engine-ui.css +4 -4
  26. package/public/pico-engine-ui.js +50 -16
  27. package/public/pico-labs-logo.png +0 -0
  28. package/src/RulesetRegistryLoaderFs.ts +6 -10
  29. package/src/auth/AuthService.ts +755 -0
  30. package/src/auth/index.ts +17 -0
  31. package/src/auth/webauthn.ts +182 -0
  32. package/src/cli.ts +11 -0
  33. package/src/index.ts +123 -56
  34. package/src/logging.ts +36 -47
  35. package/src/oauth/OAuthService.ts +474 -0
  36. package/src/oauth/acg.ts +666 -0
  37. package/src/oauth/channelEligibility.ts +26 -0
  38. package/src/oauth/errors.ts +10 -0
  39. package/src/oauth/index.ts +14 -0
  40. package/src/oauth/krlModule.ts +31 -0
  41. package/src/oauth/meshOAuth.ts +50 -0
  42. package/src/provisionRoot.ts +97 -0
  43. package/src/server.ts +647 -17
package/README.md CHANGED
@@ -120,11 +120,158 @@ 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
+ - **`/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).
135
+ - **`/auth/*`** — registration, login, session management.
136
+
137
+ ## OAuth
138
+
139
+ OAuth protects external access to the mesh on **`/sky/*`**. The UI and in-engine loops continue to use passkey sessions on **`/c/*`**.
140
+
141
+ Two grant types can coexist in the same mesh:
142
+
143
+ | Grant | Use case | Client ID | Scope |
144
+ |-------|----------|-----------|-------|
145
+ | **Client Credentials** | Inbound webhooks (Stripe, GitHub, …) | Channel **ECI** | Single channel only |
146
+ | **Authorization Code + PKCE** | Apps like Home Assistant | `app_…` | Whole mesh (root + descendants) |
147
+
148
+ ### Mesh lock
149
+
150
+ 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.
151
+
152
+ 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.
153
+
154
+ Ruleset queries (install `io.picolabs.oauth` on the root): `meshEnabled()`, `meshRequiresOAuth(eci)`, `channelStatus(eci)`, `createChannelSecret(eci)`, … — see `krl/io.picolabs.oauth.krl`.
155
+
156
+ ### Webhook credentials (Client Credentials)
157
+
158
+ For channels tagged **`oauth-webhook`** at creation time:
159
+
160
+ 1. Open the channel in the **Channels** tab.
161
+ 2. **Create credentials** — `client_id` is the channel ECI; copy the `client_secret` (shown once).
162
+ 3. Mint a test token in the UI, or call `POST /oauth/token`:
163
+
164
+ ```http
165
+ POST /oauth/token
166
+ Content-Type: application/json
167
+
168
+ {
169
+ "grant_type": "client_credentials",
170
+ "client_id": "<channel-eci>",
171
+ "client_secret": "<secret>"
172
+ }
173
+ ```
174
+
175
+ The returned **`oat_…`** access token works only on **`/sky/*`** URLs for **that ECI**.
176
+
177
+ Family, subscription, and system channels are not eligible.
178
+
179
+ ### OAuth apps (Authorization Code)
180
+
181
+ For integrators that need access across the mesh (e.g. Home Assistant):
182
+
183
+ 1. Install **`io.picolabs.oauth`** on the root pico (mesh lock).
184
+ 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.
185
+ 3. The app sends the user to authorize; after passkey consent, the app exchanges the code for tokens.
186
+
187
+ **Authorize** (browser; user must be signed in):
188
+
189
+ ```http
190
+ GET /oauth/authorize?client_id=app_…&redirect_uri=…&response_type=code&code_challenge=…&code_challenge_method=S256&scope=mesh
191
+ ```
192
+
193
+ Unauthenticated users are redirected to sign in and then returned to authorize (`/?oauth_return=…`).
194
+
195
+ **Token exchange** (must be **POST**, not a browser GET with query params):
196
+
197
+ ```http
198
+ POST /oauth/token
199
+ Content-Type: application/json
200
+
201
+ {
202
+ "grant_type": "authorization_code",
203
+ "code": "oac_…",
204
+ "redirect_uri": "…",
205
+ "client_id": "app_…",
206
+ "code_verifier": "…"
207
+ }
208
+ ```
209
+
210
+ For manual testing with plain PKCE, use `code_challenge_method=plain` and set `code_challenge` and `code_verifier` to the same string.
211
+
212
+ **Refresh:**
213
+
214
+ ```http
215
+ POST /oauth/token
216
+ Content-Type: application/json
217
+
218
+ {
219
+ "grant_type": "refresh_token",
220
+ "refresh_token": "ort_…",
221
+ "client_id": "app_…"
222
+ }
223
+ ```
224
+
225
+ **Use the access token** on any channel ECI in the mesh:
226
+
227
+ ```http
228
+ GET /sky/query/<eci>/io.picolabs.wrangler/name
229
+ Authorization: Bearer oat_…
230
+ ```
231
+
232
+ ### Token prefixes
233
+
234
+ | Prefix | Meaning |
235
+ |--------|---------|
236
+ | `oac_` | Authorization code (single-use, ~10 min) — exchange at `/oauth/token`, not a Bearer token |
237
+ | `oat_` | Access token — use on **`/sky/*`** |
238
+ | `ort_` | Refresh token — use at `/oauth/token` only |
239
+
240
+ ### OAuth HTTP endpoints
241
+
242
+ | Method | Path | Auth | Purpose |
243
+ |--------|------|------|---------|
244
+ | `POST` | `/oauth/token` | Public | Client credentials, authorization code, refresh token |
245
+ | `GET` | `/oauth/token` | Public | Dev-friendly alias (query params); prefer POST |
246
+ | `GET` | `/oauth/authorize` | Passkey session | Authorization code + PKCE; consent page |
247
+ | `POST` | `/oauth/approve` | Passkey session | Consent form handler |
248
+ | `GET/POST/DELETE` | `/oauth/apps` | Passkey session | Register/list/revoke OAuth apps |
249
+ | `GET/POST/DELETE` | `/oauth/channels/:eci/*` | Passkey session | Webhook credential management |
250
+
251
+ ### Building the UI
252
+
253
+ The root `npm run build` compiles the engine only. To pick up UI changes (Settings, Channels OAuth panels, etc.):
254
+
255
+ ```sh
256
+ cd packages/pico-engine-ui && npm run build
257
+ ```
258
+
259
+ That copies the bundle into `packages/pico-engine/public/`. Restart the engine and hard-refresh the browser.
260
+
261
+ For UI development, run the engine and `npm run dev` in `packages/pico-engine-ui` in separate terminals.
262
+
263
+ ### OAuth tests
264
+
265
+ ```sh
266
+ cd packages/pico-engine
267
+ npm run test:oauth # webhook Client Credentials
268
+ npm run test:acg # authorization code + refresh
269
+ npm run test:http # /c/* vs /sky/* surface + mesh lock
270
+ npm run test:auth # passkeys
271
+ ```
272
+
273
+ Tests use isolated temp homes and ephemeral ports; they do not require stopping a running engine.
274
+
128
275
  ## Contributing
129
276
 
130
277
  See the repository [root readme](https://github.com/Picolab/pico-engine#readme)
@@ -11,18 +11,16 @@ 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 = void 0;
14
+ exports.RulesetRegistryLoaderFs = RulesetRegistryLoaderFs;
15
15
  const cross_fetch_1 = require("cross-fetch");
16
16
  const fs = require("fs");
17
- const leveldown_1 = require("leveldown");
18
- const levelup_1 = require("levelup");
17
+ const classic_level_1 = require("classic-level");
19
18
  const makeDir = require("make-dir");
20
19
  const path = require("path");
21
20
  const urlLib = require("url");
22
21
  const krlCompiler = require("krl-compiler");
23
22
  const krlCompilerVersion = require("krl-compiler/package.json").version;
24
23
  const charwise = require("charwise");
25
- const encode = require("encoding-down");
26
24
  const safeJsonCodec = require("level-json-coerce-null");
27
25
  function getUrlFilename(url) {
28
26
  try {
@@ -36,10 +34,10 @@ function getUrlFilename(url) {
36
34
  }
37
35
  function RulesetRegistryLoaderFs(engineHomeDir) {
38
36
  const rulesetDir = path.resolve(engineHomeDir, "rulesets");
39
- const db = (0, levelup_1.default)(encode((0, leveldown_1.default)(path.resolve(engineHomeDir, "rulesets-db")), {
37
+ const db = new classic_level_1.ClassicLevel(path.resolve(engineHomeDir, "rulesets-db"), {
40
38
  keyEncoding: charwise,
41
39
  valueEncoding: safeJsonCodec,
42
- }));
40
+ });
43
41
  async function compileAndLoad(url, krl, hash) {
44
42
  const jsFile = path.resolve(rulesetDir, krlCompilerVersion, hash.substr(0, 2), hash.substr(2, 2), hash + ".js");
45
43
  let compileWarnings = [];
@@ -93,7 +91,6 @@ function RulesetRegistryLoaderFs(engineHomeDir) {
93
91
  },
94
92
  };
95
93
  }
96
- exports.RulesetRegistryLoaderFs = RulesetRegistryLoaderFs;
97
94
  async function fetchKrl(url) {
98
95
  const urlParsed = urlLib.parse(url);
99
96
  if (urlParsed.protocol === "file:") {