narrarium-server 0.0.0-stage → 0.1.1

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 CHANGED
@@ -1,3 +1,190 @@
1
- # Temporary Holding Version
1
+ # narrarium-server
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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); `packages/engine` has the same pair (`ENGINE_VERSION`), 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.