narrarium-server 0.0.0-stage → 0.1.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 +189 -2
- package/dist/cli.mjs +1305 -0
- package/dist/cli.mjs.map +6 -0
- package/dist/server.mjs +16414 -0
- package/dist/server.mjs.map +6 -0
- package/package.json +53 -4
package/README.md
CHANGED
|
@@ -1,3 +1,190 @@
|
|
|
1
|
-
#
|
|
1
|
+
# narrarium-server
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Personal Narrarium server. It runs the **autopilot** and the **director** of your books on your own computer, even with the browser closed, and keeps them in sync with the [Narrarium web app](https://narrarium.net/app). It bundles [`narrarium-engine`](../engine/README.md), the same engine the web app runs in the browser.
|
|
4
|
+
|
|
5
|
+
## Start
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npx narrarium-server
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Requirements: Node.js 22.14 or newer with npm, on Linux, macOS or Windows. Install `git` to host books stored on GitHub; without it the server hosts local books only.
|
|
12
|
+
|
|
13
|
+
The first start prepares a **verified copy** of the server in its data folder: npm must report a registry signature for it, and every release after the first one must also carry the provenance attestation of this repository's publishing workflow. Then it starts two listeners, both on this computer only:
|
|
14
|
+
|
|
15
|
+
| | Address | Who uses it |
|
|
16
|
+
|---|---|---|
|
|
17
|
+
| API | `http://127.0.0.1:24242` | Narrarium, with a client token |
|
|
18
|
+
| Admin panel | `http://127.0.0.1:24243` | You, with the admin code |
|
|
19
|
+
|
|
20
|
+
Show the admin code with `npx narrarium-server admin-code` and open the admin panel in a browser on the same computer.
|
|
21
|
+
|
|
22
|
+
## Connect Narrarium
|
|
23
|
+
|
|
24
|
+
1. In the admin panel choose **Generate a pairing code** (valid five minutes).
|
|
25
|
+
2. In Narrarium open **Settings → Personal server**, keep the address `http://127.0.0.1:24242` (or type the server's public address), type the nine digits and choose **Pair**.
|
|
26
|
+
3. Back in the admin panel, approve the request. Tick **allow updates** if this device may also update the server.
|
|
27
|
+
|
|
28
|
+
Narrarium checks the server's identity before sending anything: the server signs a fresh random value with its Ed25519 key, and Narrarium remembers the key's fingerprint. A server answering with another key is refused until you pair again. The fingerprint is shown in the admin panel and in Narrarium's settings.
|
|
29
|
+
|
|
30
|
+
Then, with your consent, send your AI router configuration from the same settings page, approve the AI endpoints in the admin panel (**AI endpoints**), and open a book's **Autopilot** page to choose **Move to my server**.
|
|
31
|
+
|
|
32
|
+
You can also create a token without pairing: in the admin panel (**Clients**) or on the server's computer with `npx narrarium-server client-token`, then paste it in Narrarium.
|
|
33
|
+
|
|
34
|
+
### Permissions
|
|
35
|
+
|
|
36
|
+
| Permission | Allows |
|
|
37
|
+
|---|---|
|
|
38
|
+
| `read` | Listing books, reading files, the live stream, the update check |
|
|
39
|
+
| `write` | Registering books, writing files, sending the AI configuration |
|
|
40
|
+
| `run` | Starting, pausing and steering the autopilot, asking the director |
|
|
41
|
+
| `update` | Replacing the server with a newer verified version (granted only when you tick it) |
|
|
42
|
+
|
|
43
|
+
Revoking or rotating a token in the admin panel closes its live connection at once.
|
|
44
|
+
|
|
45
|
+
## Updates
|
|
46
|
+
|
|
47
|
+
When the server runs under the supervisor (`npx narrarium-server start`, the default), a newer release can be installed without touching the server's computer:
|
|
48
|
+
|
|
49
|
+
- from Narrarium, **Settings → Personal server → Version and updates**, with a token that has the `update` permission;
|
|
50
|
+
- from the admin panel, **Updates**.
|
|
51
|
+
|
|
52
|
+
The server accepts an update only when no autopilot is running and from then on refuses new work. The supervisor stops it cleanly, installs the exact version with `npm install --ignore-scripts`, runs `npm audit signatures`, compares the files with any copy of the same version it already has, and restarts the server on the new version. If anything fails, the previous version starts again and the reason is shown in Narrarium and in the admin panel. At most three updates per hour are performed.
|
|
53
|
+
|
|
54
|
+
Locally, `npx narrarium-server update [--to VERSION]` installs a version that the next start will use.
|
|
55
|
+
|
|
56
|
+
Releases without the registry signature and the provenance of `KeyserDSoze/GhostWriterFramework` (directory `packages/server`) are never offered or installed. The only exception is `0.1.0`, published by hand before Trusted Publishing existed, which needs the registry signature and is accepted only as the copy prepared by the first start.
|
|
57
|
+
|
|
58
|
+
## Reach the server from other devices (Cloudflare)
|
|
59
|
+
|
|
60
|
+
Both listeners stay on `127.0.0.1`. To use the server from another computer or from your phone, publish it over HTTPS:
|
|
61
|
+
|
|
62
|
+
- **Existing tunnel**: route a hostname of your tunnel to `http://127.0.0.1:24242`, then in the admin panel (**Approved network**) set it as the public API address.
|
|
63
|
+
- **New tunnel**: in the Cloudflare dashboard create a remotely managed tunnel and route a hostname to `http://127.0.0.1:24242`, install `cloudflared` 2025.4.0 or newer, then paste the connector token in the admin panel (**Cloudflare → Save and start**). The server runs its own connector (`cloudflared tunnel run --token-file`), never touches other connectors and does not restart a connector that stopped.
|
|
64
|
+
|
|
65
|
+
To manage the server remotely as well, route a second hostname (or the same one) to `http://127.0.0.1:24243` and set it as the public admin address. On that address the panel is served and `/api/v1/*` is passed to the API, which still checks the client token. Protect remote administration with Cloudflare Access if you can. Remote administration can be switched off in the same form.
|
|
66
|
+
|
|
67
|
+
Narrarium on `https://narrarium.net` can always call the server; add other web origins under **Approved network**.
|
|
68
|
+
|
|
69
|
+
## Start automatically
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
npx narrarium-server setup --autostart
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
On Linux this installs a systemd user service (`~/.config/systemd/user/narrarium-server.service`; run `sudo loginctl enable-linger $USER` to start it before you log in). On macOS it installs a launch agent (`~/Library/LaunchAgents/net.narrarium.server.plist`, logging to `server.log` in the data folder). On Windows, add `npx narrarium-server start` to Task Scheduler at logon. The service runs the supervisor of the version installed by `setup`; the server it starts is always the active version, so run `setup --autostart` again after updates if you want the supervisor itself to move to the newer version.
|
|
76
|
+
|
|
77
|
+
## Commands
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
npx narrarium-server [start] # run the server under the update supervisor (default)
|
|
81
|
+
npx narrarium-server setup [--autostart]
|
|
82
|
+
npx narrarium-server status # data folder, active version, whether it is running
|
|
83
|
+
npx narrarium-server doctor # Node.js, npm, git, lock tools, cloudflared, data folder
|
|
84
|
+
npx narrarium-server admin-code # show the admin code
|
|
85
|
+
npx narrarium-server rotate-admin-code # replace it with a random one (server running)
|
|
86
|
+
npx narrarium-server set-admin-code [--code-file FILE] # choose it (typed, or from a 0600 file)
|
|
87
|
+
npx narrarium-server client-token [--label NAME] [--scope read,write,run[,update]]
|
|
88
|
+
npx narrarium-server update [--to VERSION]
|
|
89
|
+
npx narrarium-server --version
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
| Option | Commands | Meaning |
|
|
93
|
+
|---|---|---|
|
|
94
|
+
| `--data-root DIR` | all | Data folder (see below). |
|
|
95
|
+
| `--port N` | `start`, `setup` | API port (default `24242`, saved in `config.json`). |
|
|
96
|
+
| `--admin-port N` | `start`, `setup` | Admin panel port (default `24243`, saved). |
|
|
97
|
+
| `--label NAME` | `start`, `setup`, `client-token` | Server name shown in Narrarium, or the new client's name. |
|
|
98
|
+
| `--origin URL` | `start` | Allow another web origin (saved; repeatable). |
|
|
99
|
+
| `--direct` | `start` | Run without the supervisor: everything works except remote updates. |
|
|
100
|
+
| `--verbose` | `start` | Log every request. |
|
|
101
|
+
|
|
102
|
+
The admin code is never accepted on the command line. Rotating it ends every admin session; client tokens keep working. Editing `private/admin-code.txt` by hand and restarting the server also replaces it.
|
|
103
|
+
|
|
104
|
+
## Data folder
|
|
105
|
+
|
|
106
|
+
Default location, unless `--data-root` or `NARRARIUM_SERVER_HOME` says otherwise:
|
|
107
|
+
|
|
108
|
+
| System | Folder |
|
|
109
|
+
|---|---|
|
|
110
|
+
| Linux | `$XDG_DATA_HOME/narrarium-server`, or `~/.local/share/narrarium-server` |
|
|
111
|
+
| macOS | `~/Library/Application Support/Narrarium Server` |
|
|
112
|
+
| Windows | `%APPDATA%\Narrarium\server` |
|
|
113
|
+
|
|
114
|
+
```text
|
|
115
|
+
config.json ports, label, origins, approved network (no secrets)
|
|
116
|
+
books.json hosted books
|
|
117
|
+
books/<id>/repo/ working copy of each book: every autopilot step is a git commit
|
|
118
|
+
private/ 0700
|
|
119
|
+
admin-code.txt admin code (0600)
|
|
120
|
+
authorization.json client tokens as SHA-256 hashes, pending pairing
|
|
121
|
+
master.key vault key (0600; protected by DPAPI on Windows)
|
|
122
|
+
identity.json the server's Ed25519 key, its private half encrypted
|
|
123
|
+
ai.json AI router configuration, encrypted
|
|
124
|
+
book-tokens.json per-book GitHub tokens, encrypted
|
|
125
|
+
cloudflare-tunnel-token, cloudflare-tunnel.json, cloudflared-home/
|
|
126
|
+
npm-runtime/ verified versions and the active one
|
|
127
|
+
update-request.json, update-result.json
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
One server per data folder: a kernel lock on Linux (`flock`), a named mutex on Windows, a lock file on macOS.
|
|
131
|
+
|
|
132
|
+
## Security
|
|
133
|
+
|
|
134
|
+
- Both listeners bind to `127.0.0.1`; requests with an unexpected `Host` header are refused (DNS-rebinding protection). Private Network Access preflights are answered for allowed origins.
|
|
135
|
+
- Browser requests are accepted only from allowed origins. Every API call needs a client token with the right permission.
|
|
136
|
+
- The admin panel needs the admin code, an `HttpOnly`, `SameSite=Strict` cookie and a CSRF token; it is served under a strict Content-Security-Policy.
|
|
137
|
+
- AI keys, GitHub tokens and the identity key are encrypted with AES-256-GCM; client tokens are stored only as hashes and never returned.
|
|
138
|
+
- The server calls only the AI endpoints you approved, GitHub and the npm registry: DNS is resolved once per connection, private addresses are refused (except an approved local model on `127.0.0.1`) and redirects are never followed.
|
|
139
|
+
- npm runs without install scripts and without your npm credentials.
|
|
140
|
+
|
|
141
|
+
## How books travel
|
|
142
|
+
|
|
143
|
+
- **GitHub books**: the server clones the same branch, commits every autopilot step and pushes it; before each step it pulls the author's work. Narrarium pulls the server's commits through its usual repository sync. The book's GitHub token is sent to the server only with the author's explicit consent.
|
|
144
|
+
- **Local books**: files are exchanged with a three-way sync (`syncBookStores` in the engine): changes on one side are copied to the other, and files changed on both sides are reported instead of overwritten.
|
|
145
|
+
|
|
146
|
+
## API
|
|
147
|
+
|
|
148
|
+
All endpoints live under `/api/v1` and return JSON; errors are `{ "code", "message" }`.
|
|
149
|
+
|
|
150
|
+
| Method | Path | Permission | Purpose |
|
|
151
|
+
|---|---|---|---|
|
|
152
|
+
| `GET` | `/info?nonce=HEX64` | none | Identity and version, signed over the nonce. |
|
|
153
|
+
| `POST` | `/pairings`, `/pairings/:id/result` | none | Pair with a code; collect the token once approved. |
|
|
154
|
+
| `GET`/`DELETE` | `/session` | any | The calling client and its permissions / revoke its own token (disconnect). |
|
|
155
|
+
| `GET`/`PUT` | `/ai` | read / write | Redacted AI status (with endpoints awaiting approval) / replace the configuration. |
|
|
156
|
+
| `GET` | `/books` | read | Hosted books with their autopilot summary. |
|
|
157
|
+
| `PUT`/`DELETE` | `/books/:id` | write | Register (local or GitHub) / remove a book. |
|
|
158
|
+
| `GET` | `/books/:id/manifest` | read | Paths and hashes of the book's text files. |
|
|
159
|
+
| `POST` | `/books/:id/files/read`, `/books/:id/files/commit` | read / write | Read files / commit changes with compare-and-swap. |
|
|
160
|
+
| `POST` | `/books/:id/sync` | write | Pull and push the GitHub branch. |
|
|
161
|
+
| `GET` | `/books/:id/autopilot`, `/books/:id/autopilot/events?since=N` | read | Snapshot / recent live events. |
|
|
162
|
+
| `POST` | `/books/:id/autopilot/{start,pause,intervene,answer}` | run | Control the autopilot. |
|
|
163
|
+
| `POST` | `/books/:id/autopilot/{configure,reset}` | write | Change or reset its settings. |
|
|
164
|
+
| `POST` | `/books/:id/director/ask` | run | Ask the director about the book, a chapter or a scene. |
|
|
165
|
+
| `GET` | `/events` | read | Server-sent events: autopilot events and book summaries. |
|
|
166
|
+
| `GET`/`POST` | `/updates` | read / update | Release check / request the verified update. |
|
|
167
|
+
|
|
168
|
+
The typed client is `NarrariumServerClient` in `narrarium-engine` (with `pairWithServer` and `verifyServerIdentity`).
|
|
169
|
+
|
|
170
|
+
## Maintainers: releasing
|
|
171
|
+
|
|
172
|
+
Releases are published by [`.github/workflows/publish-server-npm.yml`](../../.github/workflows/publish-server-npm.yml) through npm Trusted Publishing, with a provenance attestation and without any npm token:
|
|
173
|
+
|
|
174
|
+
1. Bump `version` in `packages/server/package.json` and `SERVER_VERSION` in `src/version.ts` (a test keeps them equal), commit and push.
|
|
175
|
+
2. Push the tag: `git tag narrarium-server-v0.1.1 && git push origin narrarium-server-v0.1.1`.
|
|
176
|
+
|
|
177
|
+
The workflow checks that the tag matches the package, builds and tests the engine and the server, checks the package contents and publishes. The generic `Publish npm packages` workflow never publishes this package.
|
|
178
|
+
|
|
179
|
+
First publication (once): npm can bind a Trusted Publisher only to an existing package, so `0.1.0` is published by hand from a clean, verified checkout:
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
npm ci
|
|
183
|
+
npm run build -w narrarium && npm run build -w narrarium-engine
|
|
184
|
+
npm run test -w narrarium-server
|
|
185
|
+
npm login # with two-factor authentication
|
|
186
|
+
cd packages/server
|
|
187
|
+
npm publish --access public --provenance=false
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
Then, on npmjs.com, open the package **Settings → Trusted publishing** and add GitHub Actions with owner `KeyserDSoze`, repository `GhostWriterFramework`, workflow `publish-server-npm.yml`, environment `npm-publish`. Optionally require two-factor authentication and disallow tokens for publishing.
|