@vex-chat/spire 0.8.0 → 1.0.1

package/README.md

@@ -1,50 +1,105 @@
-# spire
+# @vex-chat/spire
 
-![build](https://github.com/vex-chat/spire/workflows/build/badge.svg)
+[![npm](https://img.shields.io/npm/v/@vex-chat/spire?style=flat-square&color=cb3837&logo=npm)](https://www.npmjs.com/package/@vex-chat/spire)
+[![CI](https://img.shields.io/github/actions/workflow/status/vex-protocol/spire-js/build.yml?branch=master&style=flat-square&logo=github&label=CI)](https://github.com/vex-protocol/spire-js/actions/workflows/build.yml)
+[![Released](https://img.shields.io/github/release-date/vex-protocol/spire-js?style=flat-square&label=released)](https://github.com/vex-protocol/spire-js/releases)
+[![License](https://img.shields.io/npm/l/@vex-chat/spire?style=flat-square&color=blue)](./LICENSE)
+[![Type Coverage](https://img.shields.io/badge/dynamic/json?style=flat-square&label=type-coverage&prefix=%E2%89%A5&suffix=%25&query=$.typeCoverage.atLeast&url=https://raw.githubusercontent.com/vex-protocol/spire-js/master/package.json&color=3178c6&logo=typescript)](https://github.com/plantain-00/type-coverage)
+[![Node](https://img.shields.io/node/v/@vex-chat/spire?style=flat-square&color=339933&logo=nodedotjs)](./package.json)
+[![OpenSSF Scorecard](https://img.shields.io/ossf-scorecard/github.com/vex-protocol/spire-js?style=flat-square&label=Scorecard)](https://securityscorecards.dev/viewer/?uri=github.com/vex-protocol/spire-js)
+[![Socket](https://socket.dev/api/badge/npm/package/@vex-chat/spire)](https://socket.dev/npm/package/@vex-chat/spire)
 
-A vex server implementation in NodeJS.
+Reference server implementation for the [Vex](https://vex.wtf) protocol.
 
-## dev setup
+## What's in the box
 
-steps:
+- **REST API** (Express 5) for full e2e messaging including auth, registration, users, servers, channels, invites, and file upload.
 
-```
-git clone git@github.com:vex-chat/spire
-cd spire
+## Install
+
+Or clone the repo:
+
+```sh
+git clone git@github.com:vex-protocol/spire-js
+cd spire-js
+npm ci
 ```
 
-set up your .env file in the root of the project
+## Running the server (Docker)
 
-### sample env file for mysql:
+From a clone, with Docker and Docker Compose installed:
 
+```sh
+cp .env.example .env
+# set SPK, JWT_SECRET, DB_TYPE, … (see Configuration)
+docker compose up --build
 ```
-SQL_HOST=localhost
-SQL_PORT=3306
-SQL_PASSWORD=hunter2
-SQL_USER=vex
-SQL_DB_NAME=spire
-DB_TYPE=mysql
 
-API_PORT=16777
-SOCKET_PORT=16778
+Compose builds the image from this repo’s `Dockerfile`, starts Spire with a persistent **`spire-data`** volume mounted at `/data` (SQLite + `files/`, `avatars/`, `emoji/`), and fronts it with **nginx** on **port 8080**. Use **http://localhost:8080** for HTTP and WebSocket.
 
-CANARY=true
-```
+## Running without Docker
 
-### sample env file for sqlite3:
+For local development or if you installed from npm, Spire runs with `node --experimental-strip-types` (no separate compile step):
 
+```sh
+npm start
+# or: node --experimental-strip-types src/run.ts
 ```
-DB_TYPE=sqlite3
 
-API_PORT=16777
-SOCKET_PORT=16778
+From an npm install, sources live under `node_modules/@vex-chat/spire/src/`:
 
-CANARY=true
+```sh
+node --experimental-strip-types node_modules/@vex-chat/spire/src/run.ts
 ```
 
-### start the project
+## Configuration
+
+Spire reads configuration from environment variables. **Docker Compose:** put them in a `.env` file next to `docker-compose.yml` (the `env_file` entry injects them into the container). **Bare Node:** `dotenv` loads `.env` from the process working directory when you run `src/run.ts`.
+
+### Required
+
+| Variable     | Description                                                                                                                                                                                                                                                               |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `SPK`        | Server private key, hex-encoded. Generate with `npm run gen-spk` (prints `SPK` and `JWT_SECRET` lines). Used for server identity signing (NaCl).                                                                                                                          |
+| `JWT_SECRET` | Hex or string used as the **HMAC secret for JWTs** — **required** and must be **separate from `SPK`**. `npm run gen-spk` emits a dedicated value; do not reuse `SPK` here.                                                                                                |
+| `DB_TYPE`    | `sqlite`, `sqlite3`, or `sqlite3mem`. All values use **SQLite** via `better-sqlite3` (file or `:memory:`). `sqlite3mem` is for tests. The string `mysql` is still accepted for compatibility but maps to the same SQLite setup as the default (there is no MySQL driver). |
 
+### Optional
+
+| Variable       | Default   | Description                                                                                                                                             |
+| -------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `API_PORT`     | `16777`   | Port for the REST API and WebSocket server (see `Spire` default in code if unset).                                                                      |
+| `NODE_ENV`     | _(unset)_ | Set to `production` to disable interactive `/docs` / `/async-docs`. If unset or any other value, doc viewers are mounted. `helmet()` runs in all modes. |
+| `CORS_ORIGINS` | _(empty)_ | Comma-separated allowed `Origin` values for `cors`. If unset or empty, **no cross-origin browser access** (`origin: false`).                            |
+| `CANARY`       | _(unset)_ |                                                                                                                                                         |
+
+### Sample `.env`
+
+```sh
+# Run `npm run gen-spk` and paste the two lines it prints (SPK + JWT_SECRET).
+SPK=a1b2c3...
+JWT_SECRET=d4e5f6...
+DB_TYPE=sqlite
+# CANARY=true
+API_PORT=16777
+NODE_ENV=production
 ```
-yarn
-yarn start
+
+## Development
+
+```sh
+npm run build         # tsc (sanity check — runtime uses --experimental-strip-types)
+npm run lint          # eslint strictTypeChecked
+npm run lint:fix      # eslint --fix
+npm run format        # prettier --write
+npm run format:check
+npm test              # vitest run
+npx type-coverage     # type-coverage (≥95%)
+npm run license:check # license allowlist gate
 ```
+
+See [AGENTS.md](./AGENTS.md) for the release flow (changesets → publish → deploy-hook) and the rules for writing changesets.
+
+## License
+
+[AGPL-3.0-or-later](./LICENSE)

package/dist/ClientManager.d.ts

@@ -1,46 +1,42 @@
-/// <reference types="node" />
-import { XTypes } from "@vex-chat/types";
+import type { Database } from "./Database.ts";
+import type { BaseMsg, Device, User, UserRecord } from "@vex-chat/types";
+import type WebSocket from "ws";
 import { EventEmitter } from "events";
-import WebSocket from "ws";
-import { Database } from "./Database";
-import { ICensoredUser } from "./server/utils";
-import { ISpireOptions } from "./Spire";
 export declare const POWER_LEVELS: {
-    INVITE: number;
     CREATE: number;
     DELETE: number;
     EMOJI: number;
+    INVITE: number;
 };
 export declare class ClientManager extends EventEmitter {
-    private authed;
     private alive;
-    private conn;
+    private authed;
     private challengeID;
-    private failed;
+    private conn;
     private db;
-    private user;
-    private userDetails;
     private device;
-    private log;
+    private failed;
     private notify;
-    constructor(ws: WebSocket, db: Database, notify: (userID: string, event: string, transmissionID: string) => void, userDetails: ICensoredUser, options?: ISpireOptions);
+    private user;
+    private userDetails;
+    constructor(ws: WebSocket, db: Database, notify: (userID: string, event: string, transmissionID: string) => void, userDetails: User);
+    getDevice(): Device;
+    getUser(): UserRecord;
+    send(msg: BaseMsg, header?: Uint8Array): void;
     toString(): string;
-    getUser(): XTypes.SQL.IUser;
-    send(msg: any, header?: Uint8Array): Promise<void>;
-    getDevice(): XTypes.SQL.IDevice;
     private authorize;
+    private challenge;
     private fail;
-    private setAlive;
-    private pingLoop;
+    private handleReceipt;
+    private initListeners;
+    private parseResourceMsg;
     private ping;
+    private pingLoop;
     private pong;
-    private verifyResponse;
-    private challenge;
-    private sendErr;
-    private sendAuthError;
     private sendAuthedMessage;
+    private sendAuthError;
+    private sendErr;
     private sendSuccess;
-    private parseResourceMsg;
-    private handleReceipt;
-    private initListeners;
+    private setAlive;
+    private verifyResponse;
 }