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.
- package/README.md +147 -0
- package/dist/RulesetRegistryLoaderFs.js +4 -7
- package/dist/auth/AuthService.js +537 -0
- package/dist/auth/index.js +8 -0
- package/dist/auth/webauthn.js +97 -0
- package/dist/cli.js +11 -0
- package/dist/index.js +83 -46
- package/dist/logging.js +36 -27
- package/dist/oauth/OAuthService.js +356 -0
- package/dist/oauth/acg.js +495 -0
- package/dist/oauth/channelEligibility.js +26 -0
- package/dist/oauth/errors.js +12 -0
- package/dist/oauth/index.js +21 -0
- package/dist/oauth/krlModule.js +27 -0
- package/dist/oauth/meshOAuth.js +43 -0
- package/dist/provisionRoot.js +80 -0
- package/dist/server.js +565 -17
- package/dist/utils/toFileUrl.js +1 -2
- package/krl/io.picolabs.did-o.krl +25 -5
- package/krl/io.picolabs.oauth.krl +48 -0
- package/krl/io.picolabs.pds.krl +344 -0
- package/krl/io.picolabs.pico-engine-ui.krl +43 -10
- package/krl/io.picolabs.wrangler.krl +21 -20
- package/package.json +29 -29
- package/public/pico-engine-ui.css +4 -4
- package/public/pico-engine-ui.js +50 -16
- package/public/pico-labs-logo.png +0 -0
- package/src/RulesetRegistryLoaderFs.ts +6 -10
- package/src/auth/AuthService.ts +755 -0
- package/src/auth/index.ts +17 -0
- package/src/auth/webauthn.ts +182 -0
- package/src/cli.ts +11 -0
- package/src/index.ts +123 -56
- package/src/logging.ts +36 -47
- package/src/oauth/OAuthService.ts +474 -0
- package/src/oauth/acg.ts +666 -0
- package/src/oauth/channelEligibility.ts +26 -0
- package/src/oauth/errors.ts +10 -0
- package/src/oauth/index.ts +14 -0
- package/src/oauth/krlModule.ts +31 -0
- package/src/oauth/meshOAuth.ts +50 -0
- package/src/provisionRoot.ts +97 -0
- 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 =
|
|
14
|
+
exports.RulesetRegistryLoaderFs = RulesetRegistryLoaderFs;
|
|
15
15
|
const cross_fetch_1 = require("cross-fetch");
|
|
16
16
|
const fs = require("fs");
|
|
17
|
-
const
|
|
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 =
|
|
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:") {
|