mwc-proxy 0.0.1

package/README.md

@@ -0,0 +1,94 @@
+# Minecraft Web Client Proxies
+
+This repository contains the **WebSocket proxy** for making Minecraft servers accessible to web clients.
+
+---
+
+## MWC proxy (this repo)
+
+- **WebSocket-based Minecraft proxy** — browser clients connect via WebSocket; the proxy forwards to Java Minecraft servers (TCP).
+- **Microsoft/Mojang authentication** — makes it possible to connect to official Minecraft servers!
+- **Connection management & rate limiting** — per-IP limits, configurable caps.
+- **SOCKS proxy support** — optional SOCKS5 upstream for outbound connections.
+- **Signal Server integration** — reports to a central server (e.g. signal.mcraft.fun): description, domain, players, CPU, RAM; heartbeat every 10 seconds.
+- **Prometheus metrics** — built-in metrics and optional `express-prom-bundle` middleware.
+- **Callback interface for extensions** — e.g. custom connection routing, connection limits, banned origins.
+
+
+## Using this package as NPM library
+
+Install:
+
+```sh
+pnpm add mwc-proxy
+```
+
+Build the project (if you use the source), then:
+
+```js
+const { createProxyMiddleware } = require('mwc-proxy')
+// or
+import { createProxyMiddleware } from 'mwc-proxy'
+```
+
+Use `createProxyMiddleware(options)` with Express. See `src/api.ts` for `ProxyMiddlewareOptions` (e.g. `urlRoot`, `allowOrigin`, `maxConnectionsPerIp`, `signal`, `to` for host/port allowlist).
+
+CLI entry (standalone server):
+
+```sh
+npx minecraft-web-proxy
+# or
+npx mwp
+```
+
+Environment variables: `PORT`, `URL_ROOT`, `ALLOW_ORIGIN`, `MAX_CONNECTIONS_PER_IP`, `ACCESS_CODE`, `SIGNAL_SERVER_URL`, `SIGNAL_DESCRIPTION`, `SIGNAL_DOMAIN`.
+
+---
+
+## Docker (auto-updated images)
+
+Images are published to GitHub Container Registry and updated on releases.
+
+```sh
+docker pull ghcr.io/zardoy/mwc-proxy:latest
+# or a specific version
+docker pull ghcr.io/zardoy/mwc-proxy:0.1.0
+```
+
+Run:
+
+```sh
+docker run -p 2344:2344 -e PORT=2344 ghcr.io/zardoy/mwc-proxy
+```
+
+The container exposes port **2344** by default. Override with `PORT` or pass `--port` to the app.
+
+---
+
+For more information and the web client itself, visit the [main repo](https://github.com/zardoy/prismarine-web-client/).
+
+---
+
+## Bun WebSocket Proxy (standalone script)
+
+For a minimal setup that only bridges WebSocket ↔ TCP (no auth, no Signal Server), you can use the Bun script so your Minecraft server accepts WebSocket connections.
+
+Connect in the client with something like:
+
+```sh
+wss://ws.your-domain.com
+```
+
+1. **Install [Bun](https://bun.sh/docs/installation)**
+2. **Copy [`ws-proxy.ts`](https://github.com/zardoy/mwc-proxy/blob/main/bun/ws-proxy.ts) to your server** (if present in this repo) and edit:
+   - `YOUR_SERVER_HOST` and `YOUR_SERVER_PORT` — your Minecraft server.
+   - `THIS_PUBLIC_IP` — public address used for redirects.
+3. **Run with PM2** (or systemctl / another process manager):
+   ```sh
+   pm2 start "bun run ws-proxy.ts" --name bun-proxy
+   ```
+
+### Limitations
+
+- Not usable on hosters that block SSH or extra ports (e.g. Aternos).
+- Intended to run on the **same server** as the Minecraft server to avoid extra latency; otherwise consider using MWC proxy servers.

package/dist/api.d.ts

@@ -0,0 +1,109 @@
+import http from 'http';
+export type MwcCallbacks = {
+    log?: (line: string) => void;
+    getConnectData?: () => Record<string, any>;
+    onConnectionChange?: (count: number) => void;
+    getTooManyConnectionsMessage?: (currentCount: number, limit: number) => string;
+    getBannedOriginMessage?: (origin: string) => string;
+    handleConnectionRequest?: (req: any, res: any, handler: (proxies?: string[], timeLimit?: number) => Promise<void>) => Promise<boolean>;
+};
+export type ProxyMiddlewareOptions = {
+    onPing?: (req: any) => void;
+    log?: boolean | ((str: any) => any);
+    urlRoot?: string;
+    server?: http.Server;
+    allowOrigin?: boolean | string;
+    allowOriginApp?: boolean;
+    maxConnectionsPerIp?: number;
+    mwcCallbacks?: MwcCallbacks;
+    https?: {
+        key: string;
+        cert: string;
+    };
+    to?: {
+        host?: string;
+        port?: number;
+        blacklist?: boolean;
+    } | Array<{
+        host?: string;
+        port?: number;
+        blacklist?: boolean;
+    }>;
+    /**
+     * Optional signal server integration. When provided a SignalClient is created internally
+     * and reports connection counts automatically. Pass `getExtraSystemInfo` to include
+     * host-level metrics (cpu/ram) from the calling environment.
+     */
+    signal?: {
+        serverUrl?: string;
+        description?: string;
+        domain?: string;
+        /** When set, signal client runs a self-check (public IP + loop request to self) before reporting */
+        listenPort?: number;
+        getExtraSystemInfo?: () => {
+            cpuLoad?: number;
+            ramLoad?: number;
+        };
+    };
+    /**
+     * @default true
+     */
+    debugUrlEndpoint?: boolean;
+    /**
+     * Allow connections from IPv6 addresses. When false, IPv6 clients get 403.
+     * @default true
+     */
+    allowIPv6?: boolean;
+    /**
+     * Expose Prometheus /metrics scrape endpoint. Metrics are always collected; set to false to hide the endpoint.
+     * @default true
+     */
+    metricsEndpoint?: boolean;
+    /**
+     * Enable p-auth toggle-debug endpoint (GET /toggle-debug) for prismarine-auth debug scope. String for your own endpoint.
+     * @default false
+     */
+    authToggleDebugEndpoint?: boolean | string;
+    /**
+     * Max concurrent auth requests from the same IP.
+     * @default 2
+     */
+    authMaxConcurrentPerIp?: number;
+    /**
+     * Max total concurrent auth requests (all IPs).
+     * @default 5
+     */
+    authMaxConcurrentTotal?: number;
+};
+export declare const currentState: {
+    activeConnections: {
+        [token: string]: {
+            startTime: number;
+            ip: string;
+            host: string;
+        };
+    };
+    pendingConnections: {
+        [requestId: string]: {
+            ip: string;
+            startTime: number;
+        };
+    };
+    everConnected: number;
+};
+export declare function createProxyMiddleware(options?: ProxyMiddlewareOptions, connectionListener?: (ws: any) => void): import("express-serve-static-core").Express;
+export default createProxyMiddleware;
+export declare const parseSocksProxy: (proxy: string) => {
+    ipaddress: string;
+    port: number;
+    type: any;
+    userId?: undefined;
+    password?: undefined;
+} | {
+    ipaddress: string;
+    port: number;
+    userId: string;
+    password: string;
+    type: any;
+};
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}