svelte-mud/README.md

# 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)