@eserstack/noskills-web 0.0.0-bootstrap.0 โ 5.0.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/LICENSE +13 -0
- package/README.md +248 -0
- package/dist/auth.d.ts +50 -0
- package/dist/auth.js +107 -0
- package/dist/mod.d.ts +13 -0
- package/dist/mod.js +11 -0
- package/dist/request-context.d.ts +35 -0
- package/dist/request-context.js +19 -0
- package/dist/routes/api.d.ts +45 -0
- package/dist/routes/api.js +167 -0
- package/dist/routes/pages.d.ts +20 -0
- package/dist/routes/pages.js +80 -0
- package/dist/routes/sse.d.ts +15 -0
- package/dist/routes/sse.js +61 -0
- package/dist/routes/static.d.ts +10 -0
- package/dist/routes/static.js +52 -0
- package/dist/server.d.ts +53 -0
- package/dist/server.js +228 -0
- package/dist/static/client.js +257 -0
- package/dist/static/icons/icon.svg +12 -0
- package/dist/static/manifest.json +17 -0
- package/dist/static/mux-remote.js +192 -0
- package/dist/static/mux-render.js +224 -0
- package/dist/static/style.css +391 -0
- package/dist/static/sw-register.js +31 -0
- package/dist/static/sw.js +109 -0
- package/dist/templates/components.d.ts +17 -0
- package/dist/templates/components.js +89 -0
- package/dist/templates/dashboard.d.ts +8 -0
- package/dist/templates/dashboard.js +28 -0
- package/dist/templates/escape.d.ts +8 -0
- package/dist/templates/escape.js +14 -0
- package/dist/templates/layout.d.ts +12 -0
- package/dist/templates/layout.js +83 -0
- package/dist/templates/spec-detail.d.ts +7 -0
- package/dist/templates/spec-detail.js +83 -0
- package/dist/terminal/mux-host.d.ts +65 -0
- package/dist/terminal/mux-host.js +166 -0
- package/dist/terminal/ws-bridge.d.ts +9 -0
- package/dist/terminal/ws-bridge.js +26 -0
- package/package.json +35 -1
package/LICENSE
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
Copyright 2023-present Eser Ozvataf and other contributors.
|
|
2
|
+
|
|
3
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
4
|
+
you may not use this file except in compliance with the License.
|
|
5
|
+
You may obtain a copy of the License at
|
|
6
|
+
|
|
7
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
8
|
+
|
|
9
|
+
Unless required by applicable law or agreed to in writing, software
|
|
10
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
11
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
12
|
+
See the License for the specific language governing permissions and
|
|
13
|
+
limitations under the License.
|
package/README.md
ADDED
|
@@ -0,0 +1,248 @@
|
|
|
1
|
+
# ๐ฅ๏ธ [@eserstack/noskills-web](./)
|
|
2
|
+
|
|
3
|
+
> **Note:** JSR is frozen at 4.5.x. From 5.0.0, `@eserstack/noskills-web` is
|
|
4
|
+
> published on npm under the same name (`pnpm add @eserstack/noskills-web`); the
|
|
5
|
+
> JSR versions stay available but get no updates.
|
|
6
|
+
|
|
7
|
+
> **eserstack Product** ยท [eser/stack on GitHub](https://github.com/eser/stack)
|
|
8
|
+
> ยท **Install:** `pnpm add @eserstack/noskills-web`
|
|
9
|
+
|
|
10
|
+
`@eserstack/noskills-web` is the browser dashboard that `noskills web` starts.
|
|
11
|
+
One local server on 127.0.0.1 shows the specs of a noskills project, a spec page
|
|
12
|
+
with its tasks, open questions and phase actions, and coding-agent tabs rendered
|
|
13
|
+
with xterm.js. The pages are HTML rendered from TypeScript templates, with plain
|
|
14
|
+
browser scripts and no build step. The server listens, accepts the `/mux`
|
|
15
|
+
WebSocket and handles Ctrl+C through `runtime.http` and `runtime.process` from
|
|
16
|
+
`@eserstack/standards/cross-runtime`, so it calls no runtime-specific API
|
|
17
|
+
itself.
|
|
18
|
+
|
|
19
|
+
## Quick Start
|
|
20
|
+
|
|
21
|
+
In a project where you have run `noskills init`, start the dashboard from the
|
|
22
|
+
noskills command line:
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
noskills web # serves http://localhost:3000
|
|
26
|
+
noskills web --port=4000 --open # another port, and open the browser
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
To start the same server from your own code, pass the project root:
|
|
30
|
+
|
|
31
|
+
```typescript
|
|
32
|
+
import * as noskillsWeb from "@eserstack/noskills-web";
|
|
33
|
+
|
|
34
|
+
await noskillsWeb.startServer({ root: ".", port: 3000 });
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
`startServer` prints the dashboard URL and resolves once the server stops, which
|
|
38
|
+
happens when its `signal` aborts. Ctrl+C closes every tab, kills the agent
|
|
39
|
+
processes, removes their session files and exits the process.
|
|
40
|
+
|
|
41
|
+
## Server
|
|
42
|
+
|
|
43
|
+
### `startServer(options)`
|
|
44
|
+
|
|
45
|
+
| Option | Type | Default | Description |
|
|
46
|
+
| ---------- | ------------------- | ------------------------- | --------------------------------------------------------------------------- |
|
|
47
|
+
| `root` | `string` | | Project root that holds the `.eser/` directory |
|
|
48
|
+
| `port` | `number` | `3000` | Port to listen on; the server binds to 127.0.0.1 only. `0` picks a free one |
|
|
49
|
+
| `open` | `boolean` | `false` | Opens the dashboard in the default browser after the server listens |
|
|
50
|
+
| `signal` | `AbortSignal` | | Stops the server when aborted, for tests and embedding |
|
|
51
|
+
| `onListen` | `(address) => void` | | Called once the server listens, with `{ hostname, port }` |
|
|
52
|
+
| `logger` | `RequestLogger` | the `noskills-web` logger | Receives the error records, see [Logging](#logging) |
|
|
53
|
+
|
|
54
|
+
Stop a server you started from code with an `AbortController`. With `port: 0`,
|
|
55
|
+
`onListen` tells you the port the system picked:
|
|
56
|
+
|
|
57
|
+
```typescript
|
|
58
|
+
import * as noskillsWeb from "@eserstack/noskills-web";
|
|
59
|
+
|
|
60
|
+
const controller = new AbortController();
|
|
61
|
+
const server = noskillsWeb.startServer({
|
|
62
|
+
root: ".",
|
|
63
|
+
port: 0,
|
|
64
|
+
signal: controller.signal,
|
|
65
|
+
onListen: ({ port }) => {
|
|
66
|
+
console.log(`listening on ${port}`);
|
|
67
|
+
},
|
|
68
|
+
});
|
|
69
|
+
|
|
70
|
+
// When you are done with it:
|
|
71
|
+
controller.abort();
|
|
72
|
+
await server;
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
### Routes
|
|
76
|
+
|
|
77
|
+
| Method | Path | Purpose |
|
|
78
|
+
| ------------- | --------------------------------------------------- | ------------------------------------------------------------- |
|
|
79
|
+
| `GET` | `/` | Dashboard: spec list, pending mentions, agent tabs |
|
|
80
|
+
| `GET` | `/spec/:name` | Spec page with tasks, questions and the phase actions |
|
|
81
|
+
| `GET` | `/events` | Server-Sent Events stream of dashboard events |
|
|
82
|
+
| `GET` | `/api/state` | Dashboard state as JSON |
|
|
83
|
+
| `GET` | `/api/tabs` | Open tabs as JSON |
|
|
84
|
+
| `GET` | `/api/spec/:name/ledger`, `/api/spec/:name/summary` | Decision ledger records, or only the maturity summary |
|
|
85
|
+
| `POST` | `/api/spec/:name/:action` | `approve`, `note`, `question`, `signoff`, `reply`, `complete` |
|
|
86
|
+
| `POST` | `/api/tab` | Open an agent tab, bound to a spec with `{ "spec": "name" }` |
|
|
87
|
+
| `DELETE` | `/api/tab/:id` | Close a tab |
|
|
88
|
+
| `GET` upgrade | `/mux?token=...` | WebSocket that carries the whole multiplexer |
|
|
89
|
+
| `GET` | `/static/*`, `/sw.js`, `/manifest.json` | Browser scripts, styles and the PWA files |
|
|
90
|
+
|
|
91
|
+
`note`, `question` and `reply` read `text` from the JSON body, and `reply` also
|
|
92
|
+
reads `mentionId`. An action the dashboard refuses, such as approving a spec in
|
|
93
|
+
the wrong phase or an unknown action name, answers status 400 with
|
|
94
|
+
`{ "ok": false, "error": "..." }`. The error message names the problem.
|
|
95
|
+
|
|
96
|
+
An approved spec has no web action that starts execution. Start it from the
|
|
97
|
+
coding agent with `noskills spec your_spec_name next`, for example in an agent
|
|
98
|
+
tab bound to the spec.
|
|
99
|
+
|
|
100
|
+
A fault answers with a fixed message and the request id:
|
|
101
|
+
`{ "ok": false, "error": "Action could not be completed", "requestId": "..." }`
|
|
102
|
+
for a failed action (status 400), and `"Request could not be completed"` with
|
|
103
|
+
status 500 when a route throws. The cause stays out of the response and goes to
|
|
104
|
+
the log under the same request id.
|
|
105
|
+
|
|
106
|
+
### Logging
|
|
107
|
+
|
|
108
|
+
The server logs each fault through `@eserstack/logging`, under the
|
|
109
|
+
`noskills-web` category, as one error record. The record carries `requestId`,
|
|
110
|
+
`method`, `path` (never the query string, which holds the `/mux` token) and the
|
|
111
|
+
caught `error` with its stack and causes. A failed action also adds `spec` and
|
|
112
|
+
`action`. Names and emails from the request body are not logged.
|
|
113
|
+
|
|
114
|
+
`noskills web` configures nothing, and `@eserstack/logging` then writes its
|
|
115
|
+
records to stderr, so the detail appears in the terminal that runs the server.
|
|
116
|
+
To send the records elsewhere, pass a `logger`: any object with `with(fields)`
|
|
117
|
+
and `error(message)`, such as a `Logger` from `@eserstack/logging`:
|
|
118
|
+
|
|
119
|
+
```typescript
|
|
120
|
+
import * as logging from "@eserstack/logging";
|
|
121
|
+
import * as noskillsWeb from "@eserstack/noskills-web";
|
|
122
|
+
|
|
123
|
+
await noskillsWeb.startServer({
|
|
124
|
+
root: ".",
|
|
125
|
+
logger: logging.logger.getLogger(["your_app", "dashboard"]),
|
|
126
|
+
});
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
### Access Control
|
|
130
|
+
|
|
131
|
+
Binding to 127.0.0.1 keeps other machines out, but any page open in your browser
|
|
132
|
+
can still send requests to localhost and open WebSockets to it. The server
|
|
133
|
+
therefore checks two things before it changes state:
|
|
134
|
+
|
|
135
|
+
- The `Origin` header, when present, must be `http://localhost:<port>`,
|
|
136
|
+
`http://127.0.0.1:<port>` or `http://[::1]:<port>`. This applies to every
|
|
137
|
+
`POST`, `PUT`, `PATCH`, `DELETE` and to `/mux`.
|
|
138
|
+
- A per-process token must match: in the `x-noskills-token` header on mutating
|
|
139
|
+
requests, and in the `token` query parameter on `/mux`. Mutating requests
|
|
140
|
+
other than `DELETE` must also send `content-type: application/json`, which an
|
|
141
|
+
HTML form cannot post across origins.
|
|
142
|
+
|
|
143
|
+
The dashboard page carries the token in a `<meta name="noskills-token">` tag,
|
|
144
|
+
and `static/client.js` sends it with every mutating call. Every HTML page sends
|
|
145
|
+
a Content-Security-Policy that allows scripts only from the server itself and
|
|
146
|
+
from `cdn.jsdelivr.net/npm/`, and the xterm.js files from jsDelivr load with
|
|
147
|
+
Subresource Integrity digests.
|
|
148
|
+
|
|
149
|
+
### Environment Variables
|
|
150
|
+
|
|
151
|
+
| Name | Required | Default | Purpose |
|
|
152
|
+
| --------------------------- | -------- | ------------------------- | --------------------------------------------------------------------------------------------- |
|
|
153
|
+
| `NOSKILLS_WEB_TOKEN` | No | A fresh token per process | Fixes the access token, so a trusted tool can call the API without reading the dashboard HTML |
|
|
154
|
+
| `NOSKILLS_WEB_DEBUG_ERRORS` | No | Off | `1` or `true` adds the underlying error text to fault responses as `detail` |
|
|
155
|
+
|
|
156
|
+
For example, `NOSKILLS_WEB_TOKEN=your_access_token noskills web` lets a script
|
|
157
|
+
send `x-noskills-token: your_access_token`. Leave `NOSKILLS_WEB_DEBUG_ERRORS`
|
|
158
|
+
unset outside debugging: the detail can contain file paths of your machine.
|
|
159
|
+
|
|
160
|
+
## Agent Tabs
|
|
161
|
+
|
|
162
|
+
### `MuxHost`
|
|
163
|
+
|
|
164
|
+
`MuxHost` owns the multiplexer behind the dashboard: one `@eserstack/mux` server
|
|
165
|
+
for every tab, pane and PTY, plus the noskills session bound to each tab.
|
|
166
|
+
`startServer` creates one for you. Use it directly to drive tabs from your own
|
|
167
|
+
code:
|
|
168
|
+
|
|
169
|
+
```typescript
|
|
170
|
+
import * as noskillsWeb from "@eserstack/noskills-web";
|
|
171
|
+
|
|
172
|
+
const host = new noskillsWeb.MuxHost(".");
|
|
173
|
+
|
|
174
|
+
// Starts the coding agent (Claude Code by default) in a new tab bound to a spec.
|
|
175
|
+
const tab = await host.createTab("your_spec_name");
|
|
176
|
+
host.notifySpec("your_spec_name", "\n[noskills: review requested]\n");
|
|
177
|
+
|
|
178
|
+
console.log(host.listTabs()); // [{ id, specName, sessionId }]
|
|
179
|
+
host.closeTab(tab.id);
|
|
180
|
+
await host.killAll();
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
| Member | Description |
|
|
184
|
+
| ---------------------------- | --------------------------------------------------------------------- |
|
|
185
|
+
| `createTab(specName?)` | Starts the agent in a new tab and records a noskills session for it |
|
|
186
|
+
| `closeTab(tabId)` | Closes one tab without moving the active tab |
|
|
187
|
+
| `findTabBySpec(specName)` | The tab bound to a spec, or `undefined` |
|
|
188
|
+
| `notifySpec(specName, text)` | Types `text` into the PTY of the spec's focused pane; `false` if none |
|
|
189
|
+
| `listTabs()` | Open tabs as `WebTab` values: `id`, `specName`, `sessionId` |
|
|
190
|
+
| `killAll()` | Closes every pane and PTY and deletes the tabs' session files |
|
|
191
|
+
| `attachSocket(socket)` | Connects a browser WebSocket to the multiplexer (see below) |
|
|
192
|
+
|
|
193
|
+
The `/mux` route calls `attachSocket` after it checks the Origin and the token;
|
|
194
|
+
authenticate a socket the same way before you attach it. Every frame from the
|
|
195
|
+
socket passes the `@eserstack/mux` remote sanitizer, so a frame cannot choose
|
|
196
|
+
the command, arguments or directory of a new pane. One socket is connected at a
|
|
197
|
+
time: attaching a new one closes the old one, and the panes keep running while
|
|
198
|
+
no socket is connected.
|
|
199
|
+
|
|
200
|
+
## Browser Scripts
|
|
201
|
+
|
|
202
|
+
The files in `static/` load as plain `<script>` tags:
|
|
203
|
+
|
|
204
|
+
- `mux-render.js` draws a mux scene with one xterm.js terminal per pane and
|
|
205
|
+
exposes `globalThis.MuxRender`. It does not know the transport.
|
|
206
|
+
- `client.js` connects `MuxRender` to `/mux` over a WebSocket, follows
|
|
207
|
+
`/events`, and sends the tab and spec actions.
|
|
208
|
+
- `mux-remote.js` exposes `globalThis.startRemoteMux(...)`, which renders the
|
|
209
|
+
same scene from a `noskills-server` daemon over WebTransport. Its header marks
|
|
210
|
+
it as not yet tested against a live daemon.
|
|
211
|
+
- `sw.js` and `sw-register.js` register the service worker that shows push
|
|
212
|
+
notifications. On a page served over HTTPS, which is the `noskills-server`
|
|
213
|
+
daemon, `sw-register.js` also hands the worker the daemon's certificate
|
|
214
|
+
fingerprint from `/api/cert-fingerprint`. The plain-HTTP dashboard has no
|
|
215
|
+
certificate, so it skips that request.
|
|
216
|
+
|
|
217
|
+
## Upgrading from 4.x
|
|
218
|
+
|
|
219
|
+
These changes since 4.5.2 need a change in code, commands or files that use this
|
|
220
|
+
package. The [changelog](https://github.com/eser/stack/blob/main/CHANGELOG.md)
|
|
221
|
+
lists the changes in every package.
|
|
222
|
+
|
|
223
|
+
- `MuxHost` no longer has a public `server` field. Connect a browser WebSocket,
|
|
224
|
+
after authenticating it, with `host.attachSocket(socket)`. Code that drove the
|
|
225
|
+
mux server directly (`dispatch`, `getState`, `dispose`) creates its own with
|
|
226
|
+
`mux.createServer` from `@eserstack/mux`.
|
|
227
|
+
- A route that throws answers 500 JSON
|
|
228
|
+
`{ ok: false, error: "Request could not be completed", requestId }` instead of
|
|
229
|
+
the runtime's default 500, and an `Action could not be completed` fault
|
|
230
|
+
carries `requestId`. Use `requestId` to find the server log record.
|
|
231
|
+
- Server errors are written as `@eserstack/logging` records (JSON lines on
|
|
232
|
+
stderr, category `noskills-web`) instead of `[noskills-web] reason: <error>`
|
|
233
|
+
console lines. Read the JSON records, or pass your own `logger` to
|
|
234
|
+
`startServer`.
|
|
235
|
+
- Ctrl+C runs the graceful shutdown on Node too, and the SIGINT listener
|
|
236
|
+
is removed once the server stops. An embedder that relied on Node's default
|
|
237
|
+
Ctrl+C exit while the server runs gets the shutdown instead.
|
|
238
|
+
|
|
239
|
+
## ๐ Links
|
|
240
|
+
|
|
241
|
+
- [eser/stack on GitHub](https://github.com/eser/stack)
|
|
242
|
+
- [`@eserstack/noskills`](../noskills/README.md): the `noskills` command and the
|
|
243
|
+
dashboard state this package renders
|
|
244
|
+
- [`@eserstack/mux`](../mux/): the terminal multiplexer behind the agent tabs
|
|
245
|
+
- [`@eserstack/logging`](../logging/README.md): the logger behind the server's
|
|
246
|
+
error records
|
|
247
|
+
- [`noskills-server`](../../../cmd/noskills-server/README.md): the daemon that
|
|
248
|
+
`mux-remote.js` attaches to
|
package/dist/auth.d.ts
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
/** Query-string parameter carrying the token on the WebSocket upgrade. */
|
|
2
|
+
export declare const TOKEN_QUERY_PARAM = "token";
|
|
3
|
+
/** Header carrying the token on mutating REST calls. */
|
|
4
|
+
export declare const TOKEN_HEADER = "x-noskills-token";
|
|
5
|
+
/**
|
|
6
|
+
* Mint a per-process token.
|
|
7
|
+
*
|
|
8
|
+
* 32 bytes from the CSPRNG, hex-encoded. Regenerated on every start, so a
|
|
9
|
+
* token leaked from one session is useless against the next.
|
|
10
|
+
*/
|
|
11
|
+
export declare const createToken: () => string;
|
|
12
|
+
/**
|
|
13
|
+
* Build the set of origins the server answers to.
|
|
14
|
+
*
|
|
15
|
+
* Only loopback on the port we are actually listening on. `localhost` and the
|
|
16
|
+
* two loopback literals are distinct origins to a browser, so all three are
|
|
17
|
+
* listed; anything else -- including a LAN address for the same server -- is
|
|
18
|
+
* rejected.
|
|
19
|
+
*/
|
|
20
|
+
export declare const allowedOrigins: (port: number) => ReadonlySet<string>;
|
|
21
|
+
/**
|
|
22
|
+
* Check a request's Origin.
|
|
23
|
+
*
|
|
24
|
+
* A missing Origin is allowed: non-browser clients (curl, the CLI's own
|
|
25
|
+
* fetches) omit it, and they are not the threat this guard addresses -- the
|
|
26
|
+
* token is. Every browser-issued cross-origin request *does* carry one, which
|
|
27
|
+
* is what makes the check effective where it matters.
|
|
28
|
+
*/
|
|
29
|
+
export declare const isOriginAllowed: (request: Request, port: number) => boolean;
|
|
30
|
+
/** Check the token supplied as a query parameter (WebSocket upgrade). */
|
|
31
|
+
export declare const hasValidQueryToken: (request: Request, expected: string) => boolean;
|
|
32
|
+
/** Check the token supplied as a header (mutating REST). */
|
|
33
|
+
export declare const hasValidHeaderToken: (request: Request, expected: string) => boolean;
|
|
34
|
+
/**
|
|
35
|
+
* Reject a request whose body is a CSRF-simple content type.
|
|
36
|
+
*
|
|
37
|
+
* `application/x-www-form-urlencoded`, `multipart/form-data` and `text/plain`
|
|
38
|
+
* are the three types an HTML form can post cross-origin without a preflight.
|
|
39
|
+
* Requiring JSON forces a preflight, which the Origin check then fails.
|
|
40
|
+
*/
|
|
41
|
+
export declare const hasJsonContentType: (request: Request) => boolean;
|
|
42
|
+
/** 403 with a short reason; the body is deliberately uninformative. */
|
|
43
|
+
export declare const forbidden: (reason: string) => Response;
|
|
44
|
+
/**
|
|
45
|
+
* Read a token supplied by the environment, if any.
|
|
46
|
+
*
|
|
47
|
+
* Lets a trusted external tool drive the server without scraping the dashboard
|
|
48
|
+
* HTML. Absent, a fresh token is minted per process.
|
|
49
|
+
*/
|
|
50
|
+
export declare const tokenFromEnv: () => string | null;
|
package/dist/auth.js
ADDED
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
// Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
|
|
2
|
+
/**
|
|
3
|
+
* Origin and token guards for the noskills web server.
|
|
4
|
+
*
|
|
5
|
+
* Binding to 127.0.0.1 is not an authorization boundary. WebSockets are exempt
|
|
6
|
+
* from the same-origin policy: any page the developer visits while `noskills
|
|
7
|
+
* web` is running can open `ws://localhost:<port>/mux` and drive the
|
|
8
|
+
* multiplexer. Form posts are likewise cross-origin-reachable. Both therefore
|
|
9
|
+
* need an explicit check.
|
|
10
|
+
*
|
|
11
|
+
* Two independent guards, because each covers the other's gap:
|
|
12
|
+
*
|
|
13
|
+
* - **Origin allowlist** stops a browser page on another origin. It cannot
|
|
14
|
+
* stop a non-browser client, which sets any Origin it likes.
|
|
15
|
+
* - **Per-process token** stops any client that has not read the dashboard
|
|
16
|
+
* HTML. It is minted per run and never persisted.
|
|
17
|
+
*
|
|
18
|
+
* @module
|
|
19
|
+
*/
|
|
20
|
+
import { runtime } from "@eserstack/standards/cross-runtime";
|
|
21
|
+
/** Query-string parameter carrying the token on the WebSocket upgrade. */
|
|
22
|
+
export const TOKEN_QUERY_PARAM = "token";
|
|
23
|
+
/** Header carrying the token on mutating REST calls. */
|
|
24
|
+
export const TOKEN_HEADER = "x-noskills-token";
|
|
25
|
+
/**
|
|
26
|
+
* Mint a per-process token.
|
|
27
|
+
*
|
|
28
|
+
* 32 bytes from the CSPRNG, hex-encoded. Regenerated on every start, so a
|
|
29
|
+
* token leaked from one session is useless against the next.
|
|
30
|
+
*/
|
|
31
|
+
export const createToken = () => {
|
|
32
|
+
const bytes = new Uint8Array(32);
|
|
33
|
+
crypto.getRandomValues(bytes);
|
|
34
|
+
return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
|
|
35
|
+
};
|
|
36
|
+
/** Constant-time string comparison, to keep the token off a timing side channel. */
|
|
37
|
+
const timingSafeEqual = (a, b) => {
|
|
38
|
+
if (a.length !== b.length) {
|
|
39
|
+
return false;
|
|
40
|
+
}
|
|
41
|
+
let diff = 0;
|
|
42
|
+
for (let i = 0; i < a.length; i++) {
|
|
43
|
+
diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
|
|
44
|
+
}
|
|
45
|
+
return diff === 0;
|
|
46
|
+
};
|
|
47
|
+
/**
|
|
48
|
+
* Build the set of origins the server answers to.
|
|
49
|
+
*
|
|
50
|
+
* Only loopback on the port we are actually listening on. `localhost` and the
|
|
51
|
+
* two loopback literals are distinct origins to a browser, so all three are
|
|
52
|
+
* listed; anything else -- including a LAN address for the same server -- is
|
|
53
|
+
* rejected.
|
|
54
|
+
*/
|
|
55
|
+
export const allowedOrigins = (port) => new Set([
|
|
56
|
+
`http://localhost:${port}`,
|
|
57
|
+
`http://127.0.0.1:${port}`,
|
|
58
|
+
`http://[::1]:${port}`,
|
|
59
|
+
]);
|
|
60
|
+
/**
|
|
61
|
+
* Check a request's Origin.
|
|
62
|
+
*
|
|
63
|
+
* A missing Origin is allowed: non-browser clients (curl, the CLI's own
|
|
64
|
+
* fetches) omit it, and they are not the threat this guard addresses -- the
|
|
65
|
+
* token is. Every browser-issued cross-origin request *does* carry one, which
|
|
66
|
+
* is what makes the check effective where it matters.
|
|
67
|
+
*/
|
|
68
|
+
export const isOriginAllowed = (request, port) => {
|
|
69
|
+
const origin = request.headers.get("origin");
|
|
70
|
+
if (origin === null || origin === "") {
|
|
71
|
+
return true;
|
|
72
|
+
}
|
|
73
|
+
return allowedOrigins(port).has(origin);
|
|
74
|
+
};
|
|
75
|
+
/** Check the token supplied as a query parameter (WebSocket upgrade). */
|
|
76
|
+
export const hasValidQueryToken = (request, expected) => {
|
|
77
|
+
const supplied = new URL(request.url).searchParams.get(TOKEN_QUERY_PARAM);
|
|
78
|
+
return supplied !== null && timingSafeEqual(supplied, expected);
|
|
79
|
+
};
|
|
80
|
+
/** Check the token supplied as a header (mutating REST). */
|
|
81
|
+
export const hasValidHeaderToken = (request, expected) => {
|
|
82
|
+
const supplied = request.headers.get(TOKEN_HEADER);
|
|
83
|
+
return supplied !== null && timingSafeEqual(supplied, expected);
|
|
84
|
+
};
|
|
85
|
+
/**
|
|
86
|
+
* Reject a request whose body is a CSRF-simple content type.
|
|
87
|
+
*
|
|
88
|
+
* `application/x-www-form-urlencoded`, `multipart/form-data` and `text/plain`
|
|
89
|
+
* are the three types an HTML form can post cross-origin without a preflight.
|
|
90
|
+
* Requiring JSON forces a preflight, which the Origin check then fails.
|
|
91
|
+
*/
|
|
92
|
+
export const hasJsonContentType = (request) => {
|
|
93
|
+
const contentType = request.headers.get("content-type") ?? "";
|
|
94
|
+
return contentType.split(";")[0]?.trim().toLowerCase() === "application/json";
|
|
95
|
+
};
|
|
96
|
+
/** 403 with a short reason; the body is deliberately uninformative. */
|
|
97
|
+
export const forbidden = (reason) => new Response(`Forbidden: ${reason}`, { status: 403 });
|
|
98
|
+
/**
|
|
99
|
+
* Read a token supplied by the environment, if any.
|
|
100
|
+
*
|
|
101
|
+
* Lets a trusted external tool drive the server without scraping the dashboard
|
|
102
|
+
* HTML. Absent, a fresh token is minted per process.
|
|
103
|
+
*/
|
|
104
|
+
export const tokenFromEnv = () => {
|
|
105
|
+
const value = runtime.env.get("NOSKILLS_WEB_TOKEN");
|
|
106
|
+
return value === undefined || value === "" ? null : value;
|
|
107
|
+
};
|
package/dist/mod.d.ts
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* noskills web โ browser interface for noskills dashboard.
|
|
3
|
+
*
|
|
4
|
+
* Provides the same experience as the TUI manager:
|
|
5
|
+
* tabs, spec reading, inline CTAs, terminal interaction.
|
|
6
|
+
*
|
|
7
|
+
* @module
|
|
8
|
+
*/
|
|
9
|
+
export { startServer } from "./server.ts";
|
|
10
|
+
export type { ListenAddress, ServerOptions } from "./server.ts";
|
|
11
|
+
export type { RequestLogger } from "./request-context.ts";
|
|
12
|
+
export { MuxHost } from "./terminal/mux-host.ts";
|
|
13
|
+
export type { WebTab } from "./terminal/mux-host.ts";
|
package/dist/mod.js
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
// Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
|
|
2
|
+
/**
|
|
3
|
+
* noskills web โ browser interface for noskills dashboard.
|
|
4
|
+
*
|
|
5
|
+
* Provides the same experience as the TUI manager:
|
|
6
|
+
* tabs, spec reading, inline CTAs, terminal interaction.
|
|
7
|
+
*
|
|
8
|
+
* @module
|
|
9
|
+
*/
|
|
10
|
+
export { startServer } from "./server.js";
|
|
11
|
+
export { MuxHost } from "./terminal/mux-host.js";
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The ids and the logger of one HTTP request.
|
|
3
|
+
*
|
|
4
|
+
* The server creates a context for every request it answers. Its request id
|
|
5
|
+
* goes into each log record of that request and into the failure response, so a
|
|
6
|
+
* user who reports a failed action can be matched to the record that has the
|
|
7
|
+
* detail.
|
|
8
|
+
*
|
|
9
|
+
* @module
|
|
10
|
+
*/
|
|
11
|
+
/**
|
|
12
|
+
* The logger calls the request handlers make. A `Logger` from
|
|
13
|
+
* `@eserstack/logging` satisfies it; tests pass a fake that keeps the records.
|
|
14
|
+
*/
|
|
15
|
+
export type RequestLogger = {
|
|
16
|
+
/** A logger that adds `properties` to every record it writes. */
|
|
17
|
+
with(properties: Record<string, unknown>): RequestLogger;
|
|
18
|
+
/** Writes an error record. */
|
|
19
|
+
error(message: string): Promise<unknown>;
|
|
20
|
+
};
|
|
21
|
+
/** The ids and the logger of one request. */
|
|
22
|
+
export type RequestContext = {
|
|
23
|
+
/** A random id that the log records and the failure response share. */
|
|
24
|
+
readonly requestId: string;
|
|
25
|
+
/** Writes records with `requestId`, `method` and `path` attached. */
|
|
26
|
+
readonly log: RequestLogger;
|
|
27
|
+
};
|
|
28
|
+
/**
|
|
29
|
+
* Create the context of `request`: a fresh request id, and a logger that
|
|
30
|
+
* attaches it with the method and the path.
|
|
31
|
+
*
|
|
32
|
+
* Only the path is logged. The query string stays out of the log because the
|
|
33
|
+
* `/mux` upgrade carries the access token in it.
|
|
34
|
+
*/
|
|
35
|
+
export declare const createRequestContext: (request: Request, logger: RequestLogger) => RequestContext;
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
// Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
|
|
2
|
+
/**
|
|
3
|
+
* Create the context of `request`: a fresh request id, and a logger that
|
|
4
|
+
* attaches it with the method and the path.
|
|
5
|
+
*
|
|
6
|
+
* Only the path is logged. The query string stays out of the log because the
|
|
7
|
+
* `/mux` upgrade carries the access token in it.
|
|
8
|
+
*/
|
|
9
|
+
export const createRequestContext = (request, logger) => {
|
|
10
|
+
const requestId = crypto.randomUUID();
|
|
11
|
+
return {
|
|
12
|
+
requestId,
|
|
13
|
+
log: logger.with({
|
|
14
|
+
requestId,
|
|
15
|
+
method: request.method,
|
|
16
|
+
path: new URL(request.url).pathname,
|
|
17
|
+
}),
|
|
18
|
+
};
|
|
19
|
+
};
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import type * as requestContext from "../request-context.ts";
|
|
2
|
+
import type { MuxHost } from "../terminal/mux-host.ts";
|
|
3
|
+
/**
|
|
4
|
+
* Log a caught fault under the request id and answer
|
|
5
|
+
* `{ ok: false, error, requestId }`.
|
|
6
|
+
*
|
|
7
|
+
* `reason` is written at the call site; it is never derived from `cause`, and
|
|
8
|
+
* `cause` never reaches the wire. Everything below this layer reports faults
|
|
9
|
+
* as a bare `Error` carrying whatever the runtime threw, such as
|
|
10
|
+
* `NotFound: ... open '/Users/<name>/<repo>/.eser/specs/<spec>/state.json'`, so
|
|
11
|
+
* forwarding its message or stack would map out the host's directory layout
|
|
12
|
+
* and the internal module structure for the caller. The token guard narrows
|
|
13
|
+
* who can ask, but it is a single per-process secret embedded in the dashboard
|
|
14
|
+
* HTML, not a reason to answer with a stack trace. The detail goes to the log
|
|
15
|
+
* instead, and the request id in the response leads to it.
|
|
16
|
+
*
|
|
17
|
+
* @param context - The request the fault happened in
|
|
18
|
+
* @param reason - What failed, in words the user can act on
|
|
19
|
+
* @param status - The HTTP status of the response
|
|
20
|
+
* @param cause - The caught error; logged, never sent
|
|
21
|
+
* @returns The JSON failure response
|
|
22
|
+
*/
|
|
23
|
+
export declare const faultResponse: (context: requestContext.RequestContext, reason: string, status: number, cause: unknown) => Promise<Response>;
|
|
24
|
+
/** GET /api/state โ Full dashboard state. */
|
|
25
|
+
export declare const handleGetState: (root: string) => Promise<Response>;
|
|
26
|
+
/**
|
|
27
|
+
* GET /api/spec/:name/ledger | summary โ read-only decision-ledger data.
|
|
28
|
+
* `ledger` returns the full records + summary; `summary` returns only the
|
|
29
|
+
* maturity summary. Missing files yield empty records / null summary, never 404.
|
|
30
|
+
*/
|
|
31
|
+
export declare const handleSpecRead: (root: string, specName: string, kind: "ledger" | "summary") => Promise<Response>;
|
|
32
|
+
/**
|
|
33
|
+
* POST /api/spec/:name/:action: run one dashboard action on a spec.
|
|
34
|
+
*
|
|
35
|
+
* The actions are the ones `@eserstack/noskills/dashboard` implements. The spec
|
|
36
|
+
* page offers only these; a button for any other action would answer 400 on
|
|
37
|
+
* every click (server.test.ts checks the buttons of every phase).
|
|
38
|
+
*/
|
|
39
|
+
export declare const handleAction: (root: string, specName: string, action: string, body: Readonly<Record<string, unknown>>, host: MuxHost, context: requestContext.RequestContext) => Promise<Response>;
|
|
40
|
+
/** POST /api/tab โ Create a new tab. */
|
|
41
|
+
export declare const handleCreateTab: (host: MuxHost, body: Readonly<Record<string, unknown>>) => Promise<Response>;
|
|
42
|
+
/** DELETE /api/tab/:id โ Close a tab. */
|
|
43
|
+
export declare const handleCloseTab: (host: MuxHost, tabId: string) => Response;
|
|
44
|
+
/** GET /api/tabs โ List tabs. */
|
|
45
|
+
export declare const handleListTabs: (host: MuxHost) => Response;
|