@vex-chat/spire 0.8.0 → 1.0.0

package/README.md

@@ -1,50 +1,106 @@
-# 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/build.yml?branch=master&style=flat-square&logo=github&label=CI)](https://github.com/vex-protocol/spire/actions/workflows/build.yml)
+[![Released](https://img.shields.io/github/release-date/vex-protocol/spire?style=flat-square&label=released)](https://github.com/vex-protocol/spire/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/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?style=flat-square&label=Scorecard)](https://securityscorecards.dev/viewer/?uri=github.com/vex-protocol/spire)
+[![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) encrypted chat platform. NodeJS + SQLite + TypeScript, running the wire protocol defined in [@vex-chat/types](https://github.com/vex-protocol/types-js).
 
-## dev setup
+## What's in the box
 
-steps:
+- **REST API** (Express 5) for auth, registration, users, servers, channels, invites, and file upload.
+- **WebSocket server** (native `ws`) for real-time messaging, presence, and push notifications. Frames are msgpack-encoded per the AsyncAPI spec in `@vex-chat/types`.
+- **SQLite persistence** via Kysely + better-sqlite3. Single-file DB, zero external services.
+- **Runtime validation** on every trust boundary: every request body, query string, and WebSocket payload is parsed through a Zod schema before any logic runs.
+- **Interactive docs** — [Scalar](https://scalar.com) at `/docs` for the OpenAPI spec, the [AsyncAPI web component](https://www.asyncapi.com) at `/async-docs` for the WebSocket protocol. Both production-gated for security.
+- **Authentication** via `@vex-chat/crypto` signing keys plus JWT session tokens. Password hashing via native `node:crypto` PBKDF2.
 
+## Install
+
+From public npm:
+
+```sh
+npm install @vex-chat/spire
 ```
-git clone git@github.com:vex-chat/spire
+
+Or clone the repo:
+
+```sh
+git clone git@github.com:vex-protocol/spire
 cd spire
+npm ci
 ```
 
-set up your .env file in the root of the project
+## Running the server
 
-### sample env file for mysql:
+Spire runs directly from source via `node --experimental-strip-types` — no pre-compile step needed in dev or prod. From a clone:
 
+```sh
+npm start
 ```
-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
+Or equivalently:
 
-CANARY=true
+```sh
+node --experimental-strip-types src/run.ts
 ```
 
-### sample env file for sqlite3:
+From an npm install, the source ships in the tarball under `node_modules/@vex-chat/spire/src/`, so you can run it directly:
 
+```sh
+node --experimental-strip-types node_modules/@vex-chat/spire/src/run.ts
 ```
-DB_TYPE=sqlite3
 
-API_PORT=16777
-SOCKET_PORT=16778
+## Configuration
 
-CANARY=true
-```
+Spire reads configuration from environment variables. Use a `.env` file at the repo root (or wherever you run it from) — `dotenv` picks it up automatically.
+
+### Required
 
-### start the project
+| Variable  | Description                                                                                                                                                                                                       |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `SPK`     | Server private key, hex-encoded. Generate one with `npm run gen-spk`. Used for server identity signing and as the default JWT secret if `JWT_SECRET` isn't set.                                                   |
+| `DB_TYPE` | `sqlite`, `sqlite3`, or `sqlite3mem`. Controls database backend. `sqlite3mem` runs an in-memory database useful for tests. (MySQL support was removed in `1.0.0`; operators on older deploys should migrate out.) |
+| `CANARY`  | `true` to enable canary mode (runs extra runtime assertions). `false` for standard production.                                                                                                                    |
 
+### Optional
+
+| Variable     | Default       | Description                                                                                        |
+| ------------ | ------------- | -------------------------------------------------------------------------------------------------- |
+| `API_PORT`   | `16777`       | Port for the REST API and WebSocket server.                                                        |
+| `NODE_ENV`   | `development` | `production` enables hardened Helmet CSP and disables interactive `/docs` / `/async-docs` viewers. |
+| `JWT_SECRET` | `SPK`         | Override the JWT signing secret. Falls back to `SPK` if unset.                                     |
+
+### Sample `.env`
+
+```sh
+SPK=a1b2c3...        # generate with `npm run gen-spk`
+DB_TYPE=sqlite
+CANARY=false
+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,44 @@
-/// <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";
+import { type SpireOptions } from "./Spire.ts";
 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 failed;
     private log;
     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, options?: SpireOptions);
+    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;
 }