74 lines
3.4 KiB
Markdown
74 lines
3.4 KiB
Markdown
# SvelteMUD
|
|
|
|
SvelteMUD is an accessible, installable MUD client built with Svelte 5 and SvelteKit. It supports multiple simultaneous Telnet connections through a constrained WebSocket proxy, ANSI color, GMCP, triggers, profiles, and screen-reader-oriented navigation.
|
|
|
|
## Security model
|
|
|
|
- Browsers connect only to the same-origin `/mud-ws` endpoint. The proxy accepts a small JSON control protocol and carries Telnet data in binary WebSocket frames.
|
|
- The proxy rejects private, loopback, link-local, multicast, and otherwise special-use targets after DNS resolution. It pins the selected public address for the connection and verifies TLS certificates.
|
|
- Anonymous proxy use is rate-, connection-, bandwidth-, and buffer-limited. Resume tokens are random, single-tab credentials stored in `sessionStorage`, rotate after use, and expire after five minutes.
|
|
- Passwords are held in memory only. Existing passwords from older profile data are removed during migration, and backups never contain passwords.
|
|
- Server output is rendered as text, not HTML. Triggers cannot execute JavaScript. Trigger regular expressions are length- and complexity-limited.
|
|
- Server-requested remote media is disabled by default and must be enabled explicitly in Settings.
|
|
|
|
The proxy is intended for public MUD servers. It is not a general TCP tunnel and deliberately blocks access to private infrastructure and common mail ports.
|
|
|
|
## Features
|
|
|
|
- Multiple persistent connection tabs, including background output
|
|
- Incremental Telnet parsing and GMCP negotiation
|
|
- ANSI and 256-color output
|
|
- Plain-text and constrained regular-expression triggers
|
|
- Trigger highlighting, sounds, and command sending
|
|
- Per-profile command/output history
|
|
- High contrast, text-to-speech, font scaling, and keyboard navigation
|
|
- PWA installation and generated application icons
|
|
|
|
## Development
|
|
|
|
Requires Node.js 22 or newer.
|
|
|
|
```bash
|
|
npm ci
|
|
npm run dev:full
|
|
```
|
|
|
|
`npm run dev:full` starts Vite and the WebSocket proxy. By default, development browser origins on localhost are accepted. Useful checks are:
|
|
|
|
```bash
|
|
npm test
|
|
npm run check
|
|
npm run build
|
|
npm audit --omit=dev
|
|
```
|
|
|
|
## Production configuration
|
|
|
|
The supplied Docker Compose file runs the SvelteKit app and proxy as separate processes/containers. Caddy routes normal requests to the app and `/mud-ws` to the proxy.
|
|
|
|
Proxy environment variables:
|
|
|
|
- `ALLOWED_ORIGINS`: comma-separated exact browser origins; required in production
|
|
- `TRUST_PROXY=1`: trust the first `X-Forwarded-For` address when deployed behind the configured reverse proxy
|
|
- `WS_PORT`: proxy listen port, default `3001`
|
|
|
|
Set `ALLOWED_ORIGINS` to the deployed HTTPS origin and keep the proxy reachable only through a trusted reverse proxy. See [DOCKER-README.md](DOCKER-README.md).
|
|
|
|
## Data migration
|
|
|
|
Older local data is migrated on load. Stored profile passwords and trigger JavaScript actions are discarded. Backup import accepts only known settings, profile, and trigger keys, enforces a size limit, and sanitizes legacy data before applying it.
|
|
|
|
## Project layout
|
|
|
|
- `src/lib/connection/` — WebSocket control protocol and incremental Telnet parser
|
|
- `src/lib/gmcp/` — GMCP packages and routing
|
|
- `src/lib/triggers/` — trigger validation and execution
|
|
- `src/lib/profiles/` — profile storage and in-memory credentials
|
|
- `src/lib/stores/` — per-profile application state
|
|
- `src/websocket-server.js` — constrained WebSocket-to-Telnet proxy
|
|
- `static/icons/` — generated PWA icons
|
|
|
|
## License
|
|
|
|
[MIT](LICENSE)
|