diff --git a/.github/workflows/build-ci.yml b/.github/workflows/build-ci.yml index a91978e..22ffe10 100644 --- a/.github/workflows/build-ci.yml +++ b/.github/workflows/build-ci.yml @@ -16,8 +16,25 @@ concurrency: cancel-in-progress: true jobs: + test: + name: Local regression tests (Node ${{ matrix.node }}) + runs-on: ubuntu-latest + strategy: + matrix: + node: ["22.18.0", "24.19.0"] + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: ${{ matrix.node }} + cache: npm + - run: npm ci + - run: npm run typecheck + - run: npm test + build-docker: name: Build Docker + needs: test runs-on: ubuntu-latest steps: - name: Checkout diff --git a/.gitignore b/.gitignore index 95a3107..78a7ed8 100644 --- a/.gitignore +++ b/.gitignore @@ -3,4 +3,5 @@ js .idea *.iml private -dist \ No newline at end of file +dist +/planning/ diff --git a/Dockerfile b/Dockerfile index 32cbacb..a280751 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,16 +1,17 @@ -FROM node:lts-alpine AS build +ARG NODE_IMAGE=node:22.18.0-alpine@sha256:1b2479dd35a99687d6638f5976fd235e26c5b37e8122f786fcd5fe231d63de5b +FROM ${NODE_IMAGE} AS build WORKDIR /app COPY /tsconfig.json ./ COPY /package.json ./ COPY /package-lock.json ./ -RUN npm install +RUN npm ci COPY /build.mjs ./ COPY /src ./src RUN npm run build -FROM node:lts-alpine +FROM ${NODE_IMAGE} EXPOSE 3000 EXPOSE 8080 diff --git a/README.md b/README.md index 963d787..e14f0e4 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,68 @@ Additionally, there are some environment variables that can optionally be specif | `HOST` | The address that the HTTP and websocket servers should bind to. | `127.0.0.1` | | `HTTP_PORT` | The port that the HTTP server should listen on. | `3000` | | `WEBSOCKET_PORT` | The port that the websocket server should listen on. | `8080` | +| `REQUEST_TIMEOUT_MS` | Maximum wait for a complete controller response, in milliseconds. Must be an integer from 1 to 300000; invalid values fall back to the default with a warning. | `60000` | + +## Connection and request behavior + +Controllers are authenticated before registration and protocol handling. A new +connection using an already connected device key is rejected; it does not replace +the existing owner. Authentication has a ten-second deadline; timeout rejects with +close code `1011`, and late results cannot register the connection. Disconnecting +during authentication releases its deadline and wait state. MySQL queries also +have a ten-second driver inactivity limit; a lookup that completes after the +socket's deadline is ignored. The existing 10-second ping interval and missed-pong policy +are preserved. Policy rejections use WebSocket close code `1008`; authentication +backend failures use `1011`. Rejected connections receive an `ERR:` message and a +close frame, with forced termination after five seconds if closing stalls. + +Pending requests belong to their individual controller session. A disconnected +controller fails its pending requests with HTTP `408`, and requests for an absent +controller receive `404`. Requests exceeding `REQUEST_TIMEOUT_MS` receive `408` +with `{"message":"Controller did not respond."}`. Browser departure releases +the pending request without waiting for the controller. A timeout or browser +departure does not cancel an action already sent to the controller. + +The proxy never automatically resends a forwarded request, including GETs: +OpenSprinkler uses GET for some state-changing commands. A timed-out command may +already have executed, so its outcome can be unknown. + +Request IDs remain four hexadecimal characters and are allocated sequentially +within each session, starting at a random value and skipping pending IDs. Full +capacity returns HTTP `429`. The unchanged wire format has no generation field: +a sufficiently delayed response can match a newer request after same-session ID +reuse. Skipping occupied IDs means a counter cycle need not represent 65,536 +forwarded requests. Responses on an old connection cannot answer requests on a +replacement connection. + +Lifecycle logs include connection IDs, token fingerprints, cleanup/rejection +reasons, heartbeat age, and pending counts. HTTP and request-settlement logs retain +recognized endpoint names such as `/jc`, `/cm` and `/s2id_gen`. Unknown endpoints +are logged as `/other`; subsequent path segments are dropped. HTTP logging omits +URLs, query strings, headers, and response headers to avoid leaking tokens and +passwords. Startup diagnostics identify missing or invalid setting names without +printing their values. Malformed +payloads and raw database errors are not logged. Rejection and other repeated +diagnostic events have bounded output and aggregation state. + +Both Docker stages use Node `22.18.0` on Alpine, pinned to the immutable image +index digest in `Dockerfile`. Dependency installation uses `npm ci`. Updating the +base image requires an intentional digest change and runtime validation; it no +longer follows the floating Node LTS tag. + +## Local validation + +```bash +npm ci +npm run typecheck +npm test +``` + +Tests start isolated HTTP/WebSocket servers on loopback with fake device keys and +stubbed authentication. They include a real 31-second response to verify that the +60-second default accommodates a request taking longer than 30 seconds. The suite +does not contact production or physical controllers. Real legacy-client pacing +and device compatibility still require separately authorized staging tests. diff --git a/package.json b/package.json index 1ca733e..a4b3c41 100644 --- a/package.json +++ b/package.json @@ -11,7 +11,8 @@ "scripts": { "build": "node build.mjs", "start": "node dist/index.cjs", - "test": "echo \"Error: no test specified\" && exit 1" + "test": "npm run build && node tests/run.mjs", + "typecheck": "tsc --noEmit" }, "dependencies": { "body-parser": "^1.20.2", diff --git a/src/authenticationPlugins/EnvironmentVariableAuthenticationPlugin.ts b/src/authenticationPlugins/EnvironmentVariableAuthenticationPlugin.ts index 213357d..edd1cfd 100644 --- a/src/authenticationPlugins/EnvironmentVariableAuthenticationPlugin.ts +++ b/src/authenticationPlugins/EnvironmentVariableAuthenticationPlugin.ts @@ -1,5 +1,6 @@ import { Logger } from "pino"; import { AuthenticationPlugin } from "../AuthenticationPlugin"; +import { ConfigurationError } from "../configuration"; /** Validates device keys by checking if they're listed in the environment variable `DEVICE_KEYS`. */ export default class EnvironmentVariableAuthenticationPlugin extends AuthenticationPlugin { @@ -9,7 +10,7 @@ export default class EnvironmentVariableAuthenticationPlugin extends Authenticat public async init(logger: Logger): Promise { this.logger = logger; if (!process.env.DEVICE_KEYS) { - throw `Environment variable 'DEVICE_KEYS' is not defined.`; + throw new ConfigurationError("DEVICE_KEYS", "missing"); } this.deviceKeys = process.env.DEVICE_KEYS.split(","); diff --git a/src/authenticationPlugins/MySQLAuthenticationPlugin.ts b/src/authenticationPlugins/MySQLAuthenticationPlugin.ts index 73fa0a6..1109017 100644 --- a/src/authenticationPlugins/MySQLAuthenticationPlugin.ts +++ b/src/authenticationPlugins/MySQLAuthenticationPlugin.ts @@ -1,6 +1,8 @@ import { Logger } from "pino"; import { AuthenticationPlugin } from "../AuthenticationPlugin"; import * as mysql from "mysql"; +import { backendErrorCode } from "../diagnostics"; +import { ConfigurationError } from "../configuration"; /** * Validates device keys by checking if they exist in a MySQL database. @@ -13,14 +15,19 @@ export default class MySQLAuthenticationPlugin extends AuthenticationPlugin { this.logger = logger; return new Promise((resolve, reject) => { // Make sure that necessary variables have been defined. - for (const key of ["MYSQL_TABLE", "MYSQL_CONNECTION_URL"]) { + for (const key of ["MYSQL_TABLE", "MYSQL_CONNECTION_URL"] as const) { if (!process.env[key]) { - reject(`Environment variable '${key}' is not defined.`); + reject(new ConfigurationError(key, "missing")); return; } } - this.pool = mysql.createPool(process.env.MYSQL_CONNECTION_URL); + try { + this.pool = mysql.createPool(process.env.MYSQL_CONNECTION_URL); + } catch { + reject(new ConfigurationError("MYSQL_CONNECTION_URL", "invalid")); + return; + } resolve(); }); } @@ -28,12 +35,15 @@ export default class MySQLAuthenticationPlugin extends AuthenticationPlugin { public validateKey(deviceKey: string): Promise { return new Promise((resolve, reject) => { this.pool.query( - "SELECT * FROM ?? WHERE device_key = ?", + { sql: "SELECT * FROM ?? WHERE device_key = ?", timeout: 10_000 }, [process.env.MYSQL_TABLE, deviceKey], (err, results, fields) => { if (err) { - this.logger.error(err, "Error querying MySQL database"); - resolve(false); + // mysql errors include the formatted SQL and key. The + // forwarder rate-limits logging of this sanitized failure. + const failure = new Error("Authentication backend unavailable"); + Object.assign(failure, { code: backendErrorCode(err) }); + reject(failure); return; } diff --git a/src/configuration.ts b/src/configuration.ts new file mode 100644 index 0000000..36bef58 --- /dev/null +++ b/src/configuration.ts @@ -0,0 +1,21 @@ +type Setting = "AUTHENTICATION_PLUGIN" | "DEVICE_KEYS" | "MYSQL_TABLE" | "MYSQL_CONNECTION_URL"; + +// These messages are safe to log: they name settings, never their values. +export class ConfigurationError extends Error { + constructor(readonly setting: Setting, readonly reason: "missing" | "unsupported" | "invalid") { + super(`${setting} is ${reason}`); + this.name = "ConfigurationError"; + } +} + +export function startupFailure(error: unknown) { + if (error instanceof ConfigurationError) { + return { event: "startup_failure", setting: error.setting, + reason: error.reason, message: error.message }; + } + const code = (error as { code?: unknown })?.code; + const known = ["EADDRINUSE", "EADDRNOTAVAIL", "EACCES", "EMFILE", "ENFILE"]; + return { event: "startup_failure", reason: "initialization_failed", + errorCode: typeof code === "string" && known.includes(code) ? code : undefined, + message: "Unable to initialize proxy" }; +} diff --git a/src/diagnostics.ts b/src/diagnostics.ts new file mode 100644 index 0000000..fb4669a --- /dev/null +++ b/src/diagnostics.ts @@ -0,0 +1,80 @@ +import { createHash } from "crypto"; +import { Logger } from "pino"; + +export function tokenFingerprint(token: string): string { + return createHash("sha256").update(token).digest("hex").slice(0, 8); +} + +const ENDPOINTS = new Set([ + "", "index.html", "cv", "jc", "dp", "cp", "cr", "mp", "up", "jp", "jpa", + "co", "jo", "sp", "js", "cm", "cs", "jn", "je", "jl", "dl", "su", "cu", + "ja", "pq", "db", "lf", "df", "jsn", "csn", "dsn", "jsl", "dsl", "jsd", + "update", "jsap", "ccap", "jtap", "vo", "vl", "ad", "cc", "jt", + "resetall", "clearlog", "s2id_gen", +]); + +export function forwardedEndpoint(url: string): string | undefined { + const match = /^\/forward\/v1\/[^/?]+(?:\/([^/?#]*))?/.exec(url); + if (!match) return undefined; + const endpoint = match[1] || ""; + // Generic IoT paths can contain secrets too. Log only recognized endpoint + // names, dropping query strings and all subsequent path segments. + return ENDPOINTS.has(endpoint) ? `/${endpoint}` : "/other"; +} + +// Limit both repeated identities and a burst of distinct, untrusted identities. +// Suppression counts are reported with the next permitted event. +export class EventLimiter { + private entries = new Map(); + private windowStart: number; + private emitted = 0; + private suppressed = 0; + + constructor( + private readonly windowMs = 60_000, + private readonly maxEntries = 256, + private readonly maxEvents = 100, + private readonly now = Date.now + ) { + this.windowStart = now(); + } + + log(logger: Logger, level: "info" | "warn" | "debug", event: string, + identity: string, fields: Record = {}): void { + const now = this.now(); + if (now - this.windowStart >= this.windowMs) { + this.windowStart = now; + this.emitted = 0; + } + if (this.emitted >= this.maxEvents) { + this.suppressed++; + return; + } + const key = `${event}:${identity}`; + const entry = this.entries.get(key); + if (entry && now - entry.at < this.windowMs) { + entry.suppressed++; + return; + } + if (!entry && this.entries.size >= this.maxEntries) { + this.entries.delete(this.entries.keys().next().value); + } + this.entries.set(key, { at: now, suppressed: 0 }); + this.emitted++; + logger[level]({ ...fields, event, + suppressed: (entry?.suppressed || 0) + this.suppressed }); + this.suppressed = 0; + } +} + +// Never serialize backend error objects: mysql errors may contain SQL and keys. +export function backendErrorCode(error: unknown): string { + const code = (error as { code?: unknown })?.code; + const known = new Set([ + "ECONNREFUSED", "ETIMEDOUT", "ECONNRESET", "ENOTFOUND", + "PROTOCOL_CONNECTION_LOST", "PROTOCOL_SEQUENCE_TIMEOUT", "ER_ACCESS_DENIED_ERROR", "ER_BAD_DB_ERROR", + "ER_NO_SUCH_TABLE", "ER_PARSE_ERROR", "ER_CON_COUNT_ERROR", + "POOL_ENQUEUELIMIT", + ]); + return typeof code === "string" && known.has(code) ? code : "AUTH_BACKEND_ERROR"; +} diff --git a/src/httpApp.ts b/src/httpApp.ts new file mode 100644 index 0000000..aff7305 --- /dev/null +++ b/src/httpApp.ts @@ -0,0 +1,55 @@ +import bodyParser from "body-parser"; +import cors from "cors"; +import express, { RequestHandler } from "express"; +import { Logger } from "pino"; +import { pinoHttp } from "pino-http"; +import { forwardedEndpoint, tokenFingerprint } from "./diagnostics"; + +export function createHttpApp(forward: RequestHandler, logger: Logger) { + const app = express(); + app.use(pinoHttp({ + logger: logger.child({ name: "http" }), + customSuccessMessage(req, res) { + if ((res as express.Response).locals?.controllerResponseForwarded) { + return "controller response forwarded"; + } + return !req.readableAborted && res.writableEnded ? "request completed" : "request aborted"; + }, + serializers: { + req(req) { + const match = /^\/forward\/v1\/([^/?]+)/.exec(req.url || ""); + return { id: req.id, method: req.method, + route: match ? "/forward/v1/:deviceKey" : "other", + endpoint: forwardedEndpoint(req.url || ""), + tokenHash: match ? tokenFingerprint(match[1]) : undefined }; + }, + // Redirect Location headers can also contain the token and password. + res(res) { + // Pino's standard wrapper reports null until Express sends + // headers. Raw controller replies bypass that Express state. + const raw = res.raw as express.Response; + return { statusCode: raw?.locals?.controllerResponseForwarded + ? raw.statusCode : res.statusCode }; + }, + err() { return { message: "HTTP request failed" }; }, + }, + })); + app.use(cors()); + app.use(bodyParser.text({ type: "*/*", limit: "1mb" })); + app.all("/forward/v1/:deviceKey$", (req, res) => { + res.redirect(301, req.url + "/"); + }); + app.all("/forward/v1/:deviceKey*?", forward); + const errorHandler: express.ErrorRequestHandler = (err, req, res, _next) => { + req.log.warn({ event: "http_request_error" }); + if (res.headersSent) { + res.destroy(); + return; + } + const status = Number.isInteger(err?.status) && err.status >= 400 && err.status < 500 + ? err.status : 500; + res.status(status).json({ message: "Unable to process request." }); + }; + app.use(errorHandler); + return app; +} diff --git a/src/requestIds.ts b/src/requestIds.ts new file mode 100644 index 0000000..6b1e9b4 --- /dev/null +++ b/src/requestIds.ts @@ -0,0 +1,14 @@ +import { randomInt } from "crypto"; + +export class RequestIds { + constructor(private next = randomInt(0x10000)) {} + + allocate(pending: ReadonlyMap): string | undefined { + for (let checked = 0; checked < 0x10000; checked++) { + const id = this.next.toString(16).padStart(4, "0"); + this.next = (this.next + 1) & 0xffff; + if (!pending.has(id)) return id; + } + return undefined; + } +} diff --git a/src/routes/forwarder.ts b/src/routes/forwarder.ts index 3738f82..7888d5f 100644 --- a/src/routes/forwarder.ts +++ b/src/routes/forwarder.ts @@ -1,12 +1,11 @@ -import { Request, Response } from "express"; +import { RequestHandler, Response } from "express"; import WebSocket, { WebSocketServer } from "ws"; -import { IncomingMessage } from "http"; -import { URL } from "url"; -import { AuthenticationPlugin } from "../AuthenticationPlugin"; -import { default as fs } from "fs"; +import { randomUUID } from "crypto"; +import { once } from "events"; import { Logger } from "pino"; -import EnvironmentVariableAuthenticationPlugin from "../authenticationPlugins/EnvironmentVariableAuthenticationPlugin"; -import MySQLAuthenticationPlugin from "../authenticationPlugins/MySQLAuthenticationPlugin"; +import { AuthenticationPlugin } from "../AuthenticationPlugin"; +import { backendErrorCode, EventLimiter, forwardedEndpoint, tokenFingerprint } from "../diagnostics"; +import { RequestIds } from "../requestIds"; /** * Checks if a given buffer contains only correct UTF-8. @@ -73,338 +72,346 @@ function isValidUTF8(buf: Buffer): boolean { return true; } -let server: WebSocketServer; -const connectedControllers: Map = new Map(); -const pendingResponses: Map< - String, - Map -> = new Map(); +export const DEFAULT_REQUEST_TIMEOUT_MS = 60_000; +export const MAX_REQUEST_TIMEOUT_MS = 300_000; +export const AUTHENTICATION_TIMEOUT_MS = 10_000; + +export function requestTimeout(value: unknown, logger: Logger): number { + if (value === undefined) return DEFAULT_REQUEST_TIMEOUT_MS; + const parsed = typeof value === "string" && value.trim() !== "" ? Number(value) + : typeof value === "number" ? value : NaN; + if (Number.isInteger(parsed) && parsed > 0 && parsed <= MAX_REQUEST_TIMEOUT_MS) return parsed; + logger.warn({ event: "invalid_request_timeout", defaultMs: DEFAULT_REQUEST_TIMEOUT_MS }); + return DEFAULT_REQUEST_TIMEOUT_MS; +} + +export interface ForwarderOptions { + host?: string; + port?: number; + requestTimeoutMs?: number; + heartbeatIntervalMs?: number; + rejectionTimeoutMs?: number; + authenticationTimeoutMs?: number; +} + +interface PendingResponse { + res: Response; + startedAt: number; + endpoint: string; + timer: ReturnType; + settled: boolean; + detach: () => void; +} -const AUTHENTICATION_PLUGINS: { [name: string]: AuthenticationPlugin } = { - EnvironmentVariableAuthenticationPlugin: - new EnvironmentVariableAuthenticationPlugin(), - MySQLAuthenticationPlugin: new MySQLAuthenticationPlugin(), -}; +interface Session { + ws: WebSocket; + key: string; + connectionId: string; + logger: Logger; + startedAt: number; + lastPongAt: number; + isAlive: boolean; + closed: boolean; + pending: Map; + ids: RequestIds; + heartbeat?: ReturnType; + onMessage?: (data: WebSocket.RawData, binary: boolean) => void; + onPong?: () => void; +} +// Each instance owns its maps; tests and staged instances cannot share sessions. export async function setupWebsockets( - authPluginRoot: string, + authPlugin: AuthenticationPlugin, logger: Logger, - host: string + options: ForwarderOptions = {} ) { - // Load the specified authentication plugin. - const authPlugin = - AUTHENTICATION_PLUGINS[process.env.AUTHENTICATION_PLUGIN]; - if (authPlugin == undefined) { - logger.error( - `Authentication plugin '${process.env.AUTHENTICATION_PLUGIN}' does not exist.` - ); - process.exit(1); - } - - try { - logger.info("Initializing authentication plugin..."); - await authPlugin.init( - logger.child({ - name: "auth", - plugin: process.env.AUTHENTICATION_PLUGIN, - }) - ); - logger.info("Initialized authentication plugin"); - } catch (err) { - logger.error(err, "Fatal error initializing authentication plugin"); - process.exit(1); - } - - server = new WebSocketServer({ - host, - port: parseInt(process.env.WEBSOCKET_PORT) || 8080, + await authPlugin.init(logger.child({ name: "auth" })); + const timeoutMs = requestTimeout(options.requestTimeoutMs ?? process.env.REQUEST_TIMEOUT_MS, logger); + const heartbeatMs = options.heartbeatIntervalMs ?? 10_000; + const rejectionMs = options.rejectionTimeoutMs ?? 5_000; + const authenticationMs = options.authenticationTimeoutMs ?? AUTHENTICATION_TIMEOUT_MS; + const sessions = new Map(); + const limiter = new EventLimiter(); + let stopping = false; + const server = new WebSocketServer({ + host: options.host ?? "127.0.0.1", + port: options.port ?? 8080, skipUTF8Validation: true, }); - server.on("connection", async (ws: WebSocket, req: IncomingMessage) => { - const wsLogger = logger.child({ - client: req.socket.remoteAddress, - url: req.url, - name: "ws", - }); - wsLogger.trace("A client connected"); - const url = new URL(req.url, "ws://localhost"); - if (url.pathname == "/socket/v1") { - const deviceKey = url.searchParams.get("deviceKey"); - if (!deviceKey || typeof deviceKey !== "string") { - ws.send("ERR: deviceKey was not properly specified."); - ws.terminate(); - return; - } - setupWebsocketConnectionCommon(authPlugin, ws, wsLogger, deviceKey); - setupWebsocketConnectionV1(ws, wsLogger, deviceKey); - } else { - ws.send("ERR: invalid path."); - ws.terminate(); + function settle(session: Session, id: string, entry: PendingResponse, + outcome: { reason: string; body?: Buffer; message?: string }): void { + if (entry.settled) return; + entry.settled = true; + // A delayed callback must never remove a newer entry with the same ID. + if (session.pending.get(id) === entry) session.pending.delete(id); + clearTimeout(entry.timer); + entry.detach(); + const fields = { requestId: id, reason: outcome.reason, + durationMs: Date.now() - entry.startedAt, endpoint: entry.endpoint, + pendingRequests: session.pending.size }; + session.logger.debug({ ...fields, event: "request_settled" }); + if (outcome.reason === "request_timeout") { + limiter.log(session.logger, "warn", "request_timeout", session.connectionId, fields); + } + const res = entry.res; + if (!outcome.body && !outcome.message) return; + const socket = res.socket; + if (!socket || socket.destroyed || !socket.writable || res.destroyed || res.writableEnded) return; + if (res.headersSent) { + res.destroy(); return; } - }); -} - -async function setupWebsocketConnectionCommon( - authPlugin: AuthenticationPlugin, - ws: WebSocket, - wsLogger: Logger, - deviceKey: string -) { - if (connectedControllers.has(deviceKey)) { - ws.send("ERR: A controller with this device key is already connected."); - ws.terminate(); - return; - } - - let isValid = false; - try { - isValid = await authPlugin.validateKey(deviceKey); - } catch (err) { - wsLogger.error(err, "Error validating device key"); - ws.send("ERR: Error validating device key."); - ws.terminate(); - return; - } - if (!isValid) { - ws.send("ERR: Invalid device key."); - ws.terminate(); - return; - } - - connectedControllers.set(deviceKey, ws); - pendingResponses.set(deviceKey, new Map()); - - // Close connections that don't respond to pings within 10 seconds. - ws["isAlive"] = true; - ws.on("pong", () => { - ws["isAlive"] = true; - }); - - function terminate() { - connectedControllers.delete(deviceKey); - if (pendingResponses.has(deviceKey)) { - pendingResponses.get(deviceKey).forEach((v) => { - v.res.status(408).send({ - message: "Controller disconnected.", - }); // Client timeout - }); - pendingResponses.delete(deviceKey); + try { + if (outcome.body) { + // The controller already supplied the complete HTTP response. + // Mark settled BEFORE raw I/O; Express flags do not track it. + const status = /^HTTP\/1\.[01] ([1-5][0-9]{2})(?: |\r)/ + .exec(outcome.body.subarray(0, 64).toString("latin1")); + if (status) res.statusCode = Number(status[1]); + res.locals.controllerResponseForwarded = true; + socket.end(outcome.body); + } else { + res.status(408).json({ message: outcome.message }); + } + } catch { + res.locals.controllerResponseForwarded = false; + socket.destroy(); + limiter.log(session.logger, "warn", "response_write_failed", session.connectionId); } - clearInterval(intervalId); } - const intervalId = setInterval(() => { - // Close the connection if a pong was not received since the last check. - if (!ws["isAlive"]) { - wsLogger.trace( - `A client with device key '${deviceKey}' did not respond to pings.` - ); - ws.terminate(); - terminate(); - return; + function cleanup(session: Session, reason: string, + message = "Controller disconnected.", closeCode?: number): void { + if (session.closed) return; + session.closed = true; + clearInterval(session.heartbeat); + if (session.onMessage) session.ws.off("message", session.onMessage); + if (session.onPong) session.ws.off("pong", session.onPong); + const owned = sessions.get(session.key) === session; + if (owned) sessions.delete(session.key); + const pendingRequests = session.pending.size; + for (const [id, entry] of session.pending) { + settle(session, id, entry, { reason, message }); } + session.logger.info({ event: "session_cleanup", reason, owned, closeCode, + pendingRequests, ageMs: Date.now() - session.startedAt, + lastPongAgeMs: Date.now() - session.lastPongAt }); + } - ws["isAlive"] = false; - ws.ping(); - }, 10 * 1000); - - ws.on("error", (err) => { - if (err.message == "Invalid WebSocket frame: invalid opcode 0") { - // Handle dropped start of fragmented packet gracefully - wsLogger.warn( - `A client with device key '${deviceKey}' dropped the start of a fragmented packet.` - ); - if (pendingResponses.has(deviceKey)) { - pendingResponses.get(deviceKey).forEach((v) => { - v.res.status(408).send({ - message: "Controller dropped packet.", - }); // Client timeout - }); + server.on("connection", (ws, req) => { + const connectionId = randomUUID(); + const connectedAt = Date.now(); + let connectionLogger = logger.child({ name: "ws", connectionId, + client: req.socket.remoteAddress }); + let session: Session | undefined; + let closed = false; + let rejected = false; + let rejectionTimer: ReturnType | undefined; + let authenticationTimer: ReturnType | undefined; + let cancelAuthentication: (() => void) | undefined; + let identity = "unspecified"; + + // Observe transport state before URL parsing or asynchronous auth. + ws.on("close", (code) => { + closed = true; + clearTimeout(rejectionTimer); + clearTimeout(authenticationTimer); + cancelAuthentication?.(); + if (session) { + cleanup(session, "peer_close", undefined, code); + connectionLogger.debug({ event: "connection_closed", closeCode: code, + pendingRequests: session.pending.size }); + } else { + limiter.log(connectionLogger, "debug", rejected ? "rejected_connection_closed" : "auth_closed", + identity, { closeCode: code }); } - } else { - wsLogger.error( - err, - `A client with device key '${deviceKey}' errored:` - ); + }); + ws.on("error", (error) => { + closed = true; + clearTimeout(rejectionTimer); + clearTimeout(authenticationTimer); + cancelAuthentication?.(); + const fragment = error.message === "Invalid WebSocket frame: invalid opcode 0"; + if (session) cleanup(session, fragment ? "fragment_error" : "transport_error", + fragment ? "Controller dropped packet." : "Controller disconnected."); + else if (!rejected) limiter.log(connectionLogger, "warn", "pre_auth_error", identity); ws.terminate(); - terminate(); - } - }); - - ws.on("close", (code, reason) => { - wsLogger.trace( - { code, reason }, - `A client with device key '${deviceKey}' disconnected.` - ); - terminate(); - }); - - wsLogger.info(`A client connected with device key '${deviceKey}'.`); -} + }); -async function setupWebsocketConnectionV1( - ws: WebSocket, - wsLogger: Logger, - deviceKey: string -) { - ws.on("message", (data: WebSocket.Data, isBinary: boolean) => { - // Ignore binary messages. - if (isBinary) { - wsLogger.info( - `Ignoring binary message from client with device key '${deviceKey}'.` - ); - return; + function reject(code: number, reason: string, extra: Record = {}): void { + if (closed || rejected || ws.readyState !== WebSocket.OPEN) return; + rejected = true; + limiter.log(connectionLogger, "info", "connection_rejected", `${identity}:${reason}`, + { reason, closeCode: code, ...extra }); + rejectionTimer = setTimeout(() => { + limiter.log(connectionLogger, "warn", "rejection_forced_close", `${identity}:${reason}`, { reason }); + ws.terminate(); + }, rejectionMs); + rejectionTimer.unref(); + try { + ws.send(`ERR: ${reason}.`); + ws.close(code, reason); + } catch { + clearTimeout(rejectionTimer); + ws.terminate(); + } } - let buffer: Buffer; - - switch (typeof data) { - case "string": - buffer = Buffer.from(data); - break; - case "object": - if (data instanceof Buffer) { - buffer = data; - break; - } else if (data instanceof ArrayBuffer) { - buffer = Buffer.from(data); - break; - } else if (data instanceof Array) { - // Array of buffers - buffer = Buffer.concat(data.map((e) => Uint8Array.from(e))); - } - break; - default: - wsLogger.info( - `Received message with invalid type: ${typeof data} from client with device key '${deviceKey}'.` - ); + let url: URL; + try { url = new URL(req.url || "", "ws://localhost"); } + catch { reject(1008, "invalid path"); return; } + if (url.pathname !== "/socket/v1") { reject(1008, "invalid path"); return; } + const key = url.searchParams.get("deviceKey"); + if (!key) { reject(1008, "missing device key"); return; } + identity = tokenFingerprint(key); + connectionLogger = connectionLogger.child({ tokenHash: identity }); + + async function authenticate(): Promise { + if (closed || stopping || ws.readyState !== WebSocket.OPEN) return; + let valid: boolean; + let timedOut = false; + const authenticationStarted = Date.now(); + const cancelled = new Promise(resolve => { + cancelAuthentication = () => resolve(false); + authenticationTimer = setTimeout(() => { + timedOut = true; + resolve(false); + }, authenticationMs); + authenticationTimer.unref(); + }); + try { + // Promise.race also observes a late backend rejection, so it + // cannot become an unhandled rejection after timeout/close. + valid = await Promise.race([ + Promise.resolve().then(() => authPlugin.validateKey(key)), cancelled, + ]); + } + catch (error) { + reject(1011, "authentication unavailable", { errorCode: backendErrorCode(error) }); return; + } finally { + clearTimeout(authenticationTimer); + cancelAuthentication = undefined; + } + if (closed || stopping || ws.readyState !== WebSocket.OPEN) return; + if (timedOut || Date.now() - authenticationStarted >= authenticationMs) { + reject(1011, "authentication timed out", { errorCode: "AUTH_TIMEOUT" }); + return; + } + if (!valid) { reject(1008, "invalid device key"); return; } + // Final ownership check and claim are synchronous, with no await gap. + const owner = sessions.get(key); + if (owner) { + reject(1008, "device key already connected", { + ownerConnectionId: owner.connectionId, ownerAgeMs: Date.now() - owner.startedAt, + pendingRequests: owner.pending.size, + }); + return; + } + session = { ws, key, connectionId, logger: connectionLogger, + startedAt: connectedAt, lastPongAt: Date.now(), isAlive: true, + closed: false, pending: new Map(), ids: new RequestIds() }; + sessions.set(key, session); + const accepted = session; + accepted.onPong = () => { + if (accepted.closed) return; + accepted.isAlive = true; + accepted.lastPongAt = Date.now(); + }; + ws.on("pong", accepted.onPong); + accepted.heartbeat = setInterval(() => { + if (accepted.closed) return; + if (!accepted.isAlive) { + cleanup(accepted, "heartbeat_expired"); + ws.terminate(); + return; + } + accepted.isAlive = false; + ws.ping(undefined, undefined, (error) => { + if (error) { cleanup(accepted, "ping_failed"); ws.terminate(); } + }); + }, heartbeatMs); + accepted.heartbeat.unref(); + accepted.onMessage = (data, binary) => { + if (accepted.closed || sessions.get(key) !== accepted) return; + const buffer = Buffer.isBuffer(data) ? data + : Array.isArray(data) ? Buffer.concat(data) : Buffer.from(data); + const newline = buffer.indexOf(0x0a); + const header = newline < 0 ? Buffer.alloc(0) : buffer.subarray(0, newline); + const match = !binary && isValidUTF8(header) + ? /^RES: ([0-9a-f]{4})\r$/.exec(header.toString()) : null; + if (!match) { + limiter.log(connectionLogger, "warn", "invalid_response_frame", identity, + { length: buffer.length, reason: binary ? "binary" : "invalid_header" }); + return; + } + const id = match[1]; + const entry = accepted.pending.get(id); + if (!entry) { + limiter.log(connectionLogger, "debug", "unknown_response_id", identity, { requestId: id }); + return; + } + settle(accepted, id, entry, { reason: "controller_response", body: buffer.subarray(newline + 1) }); + }; + ws.on("message", accepted.onMessage); + connectionLogger.info({ event: "session_accepted", authentication: "accepted", pendingRequests: 0 }); } + void authenticate(); + }); - const index = buffer.indexOf(0x0a); - - if (index === -1) { - wsLogger.error( - { message: buffer.toString("hex") }, - `Received message missing the request key from device key '${deviceKey}'.` - ); - return; - } - - const headerBuffer = buffer.subarray(0, index); - - if (!isValidUTF8(headerBuffer)) { - wsLogger.error( - { message: headerBuffer.toString("hex") }, - `Received message with invalid UTF-8 encoding for header from client with device key '${deviceKey}'.` - ); + const forwardRequestV1: RequestHandler = (req, res) => { + const key = req.params.deviceKey; + if (!key || typeof key !== "string") { + res.status(401).json({ message: "No device key was specified or an invalid format was used." }); return; } - - const header = headerBuffer.toString(); - - const match = header.match(/^RES: ([0-9a-f]{4})\r/); - // Ignore messages that aren't formatted like responses to forwarded requests. - if (!match) { - wsLogger.warn( - `Received header with invalid format: ${header} from client with device key '${deviceKey}'.` - ); + const session = sessions.get(key); + if (session && session.ws.readyState !== WebSocket.OPEN) cleanup(session, "transport_unavailable"); + if (!session || session.closed) { + res.status(404).json({ message: "Specified device does not exist or is not connected." }); return; } - const requestKey = match[1]; - const body = buffer.subarray(index + 1, buffer.length); - - // Ignore invalid request IDs. - if (!pendingResponses.has(deviceKey)) { - wsLogger.warn( - `Received response with invalid device key '${deviceKey}'.` - ); + const id = session.ids.allocate(session.pending); + if (id === undefined) { + res.status(429).json({ message: "Controller request capacity reached." }); return; } - - const deviceResponses = pendingResponses.get(deviceKey); - - if (!deviceResponses.has(requestKey)) { - wsLogger.warn( - `Received response with invalid key: ${requestKey} from client with device key '${deviceKey}'.` - ); - return; + const path = /^\/forward\/v1\/[^/?]+(.*)$/.exec(req.url)?.[1] || "/"; + let rawRequest = `${req.method} ${path} HTTP/${req.httpVersion}\r\n`; + for (const [name, value] of Object.entries(req.headers)) rawRequest += `${name}: ${value}\r\n`; + rawRequest += `\r\n${typeof req.body === "string" ? req.body : ""}`; + const entry: PendingResponse = { res, startedAt: Date.now(), settled: false, + endpoint: forwardedEndpoint(req.url), timer: undefined, detach: () => {} }; + const abandoned = () => settle(session, id, entry, { reason: "browser_departed" }); + const finished = () => settle(session, id, entry, { reason: "http_finished" }); + entry.detach = () => { + res.off("close", abandoned); + res.off("error", abandoned); + res.off("finish", finished); + }; + res.once("close", abandoned); + res.once("error", abandoned); + res.once("finish", finished); + entry.timer = setTimeout(() => settle(session, id, entry, + { reason: "request_timeout", message: "Controller did not respond." }), timeoutMs); + entry.timer.unref(); + session.pending.set(id, entry); + if (res.destroyed || !res.socket || res.socket.destroyed) { abandoned(); return; } + try { + session.ws.send(`FWD: ${id}\r\n${rawRequest}`, (error) => { + if (error) settle(session, id, entry, { reason: "send_failed", message: "Controller disconnected." }); + }); + } catch { + settle(session, id, entry, { reason: "send_failed", message: "Controller disconnected." }); } - - const { res, logger } = deviceResponses.get(requestKey); - logger.trace( - `Received response for '${requestKey}' from device with key '${deviceKey}'` - ); - deviceResponses.delete(requestKey); - - res.socket.write(Uint8Array.from(body)); - res.socket.end(); - }); + }; + + await once(server, "listening"); + return { server, forwardRequestV1, async close(): Promise { + stopping = true; + for (const session of sessions.values()) cleanup(session, "server_shutdown"); + for (const client of server.clients) client.terminate(); + await new Promise((resolve, reject) => server.close(error => error ? reject(error) : resolve())); + } }; } - -export const forwardRequestV1 = (req: Request, res: Response) => { - const deviceKey = req.params.deviceKey; - if (!deviceKey || typeof deviceKey !== "string") { - res.status(401).json({ - message: - "No device key was specified or an invalid format was used.", - }); - return; - } - - if (!connectedControllers.has(deviceKey)) { - res.status(404).json({ - message: "Specified device does not exist or is not connected.", - }); - return; - } - - const ws: WebSocket = connectedControllers.get(deviceKey); - - const path = req.url.substring(("/forward/v1/" + deviceKey).length) || "/"; - - let rawRequest: string = `${req.method} ${path} HTTP/${req.httpVersion}\r\n`; - for (const header in req.headers) { - rawRequest += `${header}: ${req.headers[header]}\r\n`; - } - - // req.body be an empty object if no body exists. - rawRequest += `\r\n${Object.keys(req.body).length === 0 ? "" : req.body}`; - - // A random 4 digit hexadecimal number. - const requestId = Math.floor(Math.random() * 0x10000) - .toString(16) - .padStart(4, "0"); - - const responseLogger = req.log.child({ requestId }); - - responseLogger.trace( - `Forwarding request to device with key '${deviceKey}'` - ); - - // Ignore invalid request IDs. - if (!pendingResponses.has(deviceKey)) { - res.status(404).json({ - message: "Specified device does not exist or is not connected.", - }); - return; - } - - const deviceResponses = pendingResponses.get(deviceKey); - - deviceResponses.set(requestId, { - res, - logger: responseLogger, - }); - - req.on("close", () => { - if (pendingResponses.has(deviceKey)) { - const deviceResponses = pendingResponses.get(deviceKey); - deviceResponses.delete(requestId); - } - }); - - ws.send(`FWD: ${requestId}\r\n${rawRequest}`); -}; diff --git a/src/server.ts b/src/server.ts index debb9c0..041f6e2 100644 --- a/src/server.ts +++ b/src/server.ts @@ -1,73 +1,38 @@ -import bodyParser from "body-parser"; -import express from "express"; -import { forwardRequestV1, setupWebsockets } from "./routes/forwarder"; +import { once } from "events"; import { config as dotenv_config } from "dotenv"; -import cors from "cors"; -import { pinoHttp } from "pino-http"; import { pino, LevelWithSilent } from "pino"; - -function getLogLevel(): LevelWithSilent { - switch (process.env.LOG_LEVEL) { - case "trace": - return "trace"; - case "debug": - return "debug"; - case "info": - return "info"; - case "warn": - return "warn"; - case "error": - return "error"; - case "fatal": - return "fatal"; - case "silent": - return "silent"; - default: - return "info"; - } -} - -const logger = pino({ level: getLogLevel() }); +import { setupWebsockets } from "./routes/forwarder"; +import { createHttpApp } from "./httpApp"; +import EnvironmentVariableAuthenticationPlugin from "./authenticationPlugins/EnvironmentVariableAuthenticationPlugin"; +import MySQLAuthenticationPlugin from "./authenticationPlugins/MySQLAuthenticationPlugin"; +import { ConfigurationError, startupFailure } from "./configuration"; dotenv_config(); +const levels = ["trace", "debug", "info", "warn", "error", "fatal", "silent"]; +const level = levels.includes(process.env.LOG_LEVEL) ? process.env.LOG_LEVEL : "info"; +const logger = pino({ level: level as LevelWithSilent }); + +async function main(): Promise { + const auth = process.env.AUTHENTICATION_PLUGIN === "EnvironmentVariableAuthenticationPlugin" + ? new EnvironmentVariableAuthenticationPlugin() + : process.env.AUTHENTICATION_PLUGIN === "MySQLAuthenticationPlugin" + ? new MySQLAuthenticationPlugin() : undefined; + if (!auth) throw new ConfigurationError("AUTHENTICATION_PLUGIN", + process.env.AUTHENTICATION_PLUGIN ? "unsupported" : "missing"); + const host = process.env.HOST || "127.0.0.1"; + const port = parseInt(process.env.HTTP_PORT) || 3000; + const proxy = await setupWebsockets(auth, logger, { + host, port: parseInt(process.env.WEBSOCKET_PORT) || 8080, + }); + const http = createHttpApp(proxy.forwardRequestV1, logger).listen(port, host); + try { await once(http, "listening"); } + catch (error) { await proxy.close(); throw error; } + logger.info({ host, port }, "%s v%s now listening", + process.env.npm_package_description, process.env.npm_package_version); +} -const host = process.env.HOST || "127.0.0.1"; -const port = parseInt(process.env.HTTP_PORT) || 3000; - -const authPluginRoot = `${__dirname}`; - -setupWebsockets(authPluginRoot, logger, host); - -const app = express(); - -app.use( - pinoHttp({ - logger: logger.child({ name: "http" }), - redact: { - paths: [ - "req.headers.authorization", - "req.headers.cookie", - "req.query.pw", - ], - censor: "***CENSORED***", - }, - }) -); - -app.use(cors()); -app.use(bodyParser.text({ type: "*/*", limit: "1mb" })); -// Add a trailing slash -app.all("/forward/v1/:deviceKey$", (req, res, next) => { - res.redirect(301, req.url + "/"); -}); -app.all("/forward/v1/:deviceKey*?", forwardRequestV1); - -app.listen(port, host, () => { - logger.info( - "%s v%s now listening on %s:%d", - process.env.npm_package_description, - process.env.npm_package_version, - host, - port - ); +void main().catch(error => { + const { message, ...fields } = startupFailure(error); + logger.fatal(fields, message); + process.exitCode = 1; }); diff --git a/tests/configuration.test.cjs b/tests/configuration.test.cjs new file mode 100644 index 0000000..34e73a8 --- /dev/null +++ b/tests/configuration.test.cjs @@ -0,0 +1,53 @@ +const { test } = require('node:test'); +const assert = require('node:assert/strict'); +const { spawnSync } = require('node:child_process'); +const { startupFailure, ConfigurationError, forwardedEndpoint } = require(process.env.OTF_TEST_BUNDLE); + +test('startup names invalid/missing settings while hiding all configuration values', () => { + for (const [plugin, keys, table, url, setting, reason] of [ + [undefined, undefined, undefined, undefined, 'AUTHENTICATION_PLUGIN', 'missing'], + ['fake-plugin-secret', undefined, undefined, undefined, 'AUTHENTICATION_PLUGIN', 'unsupported'], + ['EnvironmentVariableAuthenticationPlugin', undefined, undefined, undefined, 'DEVICE_KEYS', 'missing'], + ['MySQLAuthenticationPlugin', undefined, undefined, 'mysql://fake-user:fake-password-secret@localhost/fake-db', 'MYSQL_TABLE', 'missing'], + ['MySQLAuthenticationPlugin', undefined, 'fake-table-secret', undefined, 'MYSQL_CONNECTION_URL', 'missing'], + ['MySQLAuthenticationPlugin', undefined, 'fake-table-secret', 'mysql://bad%ZZ:fake-password-secret@localhost/db', 'MYSQL_CONNECTION_URL', 'invalid'], + ]) { + const env = { ...process.env, LOG_LEVEL: 'info' }; + for (const [key, value] of Object.entries({ AUTHENTICATION_PLUGIN: plugin, DEVICE_KEYS: keys, + MYSQL_TABLE: table, MYSQL_CONNECTION_URL: url })) { + if (value === undefined) delete env[key]; + else env[key] = value; + } + const child = spawnSync(process.execPath, ['dist/index.cjs'], { env, encoding: 'utf8', timeout: 3000 }); + assert.equal(child.status, 1, child.stdout + child.stderr); + const lines = child.stdout.trim().split('\n').map(line => JSON.parse(line)); + const fatal = lines.find(line => line.event === 'startup_failure'); + assert.equal(fatal.setting, setting); + assert.equal(fatal.reason, reason); + assert.match(fatal.msg, new RegExp(setting)); + for (const secret of ['fake-plugin-secret', 'fake-table-secret', 'fake-password-secret', 'bad%ZZ']) { + assert.equal((child.stdout + child.stderr).includes(secret), false); + } + } +}); + +test('unrecognized startup errors cannot leak URLs, SQL or payloads; safe system codes remain', () => { + const failure = startupFailure(Object.assign(new Error('mysql://user:fake-secret@host/db'), { + sql: 'SELECT fake-secret', code: 'EADDRINUSE', + })); + assert.equal(failure.errorCode, 'EADDRINUSE'); + assert.equal(JSON.stringify(failure).includes('fake-secret'), false); + assert.equal(startupFailure({ code: 'fake-secret', message: 'fake-secret' }).errorCode, undefined); + assert.equal(startupFailure(new ConfigurationError('MYSQL_TABLE', 'missing')).setting, 'MYSQL_TABLE'); +}); + +test('endpoint logging distinguishes controller operations while dropping secrets and arbitrary paths', () => { + assert.equal(forwardedEndpoint('/forward/v1/fake-token/jc?pw=fake-secret'), '/jc'); + assert.equal(forwardedEndpoint('/forward/v1/fake-token/cm?sid=1&en=1'), '/cm'); + assert.equal(forwardedEndpoint('/forward/v1/fake-token/s2id_gen'), '/s2id_gen'); + assert.equal(forwardedEndpoint('/forward/v1/fake-token/jc/fake-path-secret'), '/jc'); + assert.equal(forwardedEndpoint('/forward/v1/fake-token/fake-path-secret'), '/other'); + assert.equal(forwardedEndpoint('/forward/v1/fake-token/%6ac?pw=fake-secret'), '/other'); + assert.equal(forwardedEndpoint('/forward/v1/fake-token?pw=fake-secret'), '/'); + assert.equal(forwardedEndpoint('/fake-secret'), undefined); +}); diff --git a/tests/exports.ts b/tests/exports.ts new file mode 100644 index 0000000..027e6e4 --- /dev/null +++ b/tests/exports.ts @@ -0,0 +1,7 @@ +export { setupWebsockets, requestTimeout, DEFAULT_REQUEST_TIMEOUT_MS } from "../src/routes/forwarder"; +export { createHttpApp } from "../src/httpApp"; +export { RequestIds } from "../src/requestIds"; +export { EventLimiter, tokenFingerprint, backendErrorCode } from "../src/diagnostics"; +export { default as MySQLAuthenticationPlugin } from "../src/authenticationPlugins/MySQLAuthenticationPlugin"; +export { ConfigurationError, startupFailure } from "../src/configuration"; +export { forwardedEndpoint } from "../src/diagnostics"; diff --git a/tests/forwarding.test.cjs b/tests/forwarding.test.cjs new file mode 100644 index 0000000..6b20e64 --- /dev/null +++ b/tests/forwarding.test.cjs @@ -0,0 +1,327 @@ +const { test } = require('node:test'); +const assert = require('node:assert/strict'); +const { fixture, receive, reply, id, until, delay } = require('./helpers.cjs'); +const { RequestIds } = require(process.env.OTF_TEST_BUNDLE); + +test('sequential GET and POST preserve path, body and byte-exact responses', async t => { + const f = await fixture(t); + const controller = await f.connect(); + await controller.accepted(); + const body = Buffer.from([0x00, 0xff, 0xc3, 0xa9]); + for (const [method, payload] of [['GET', undefined], ['POST', undefined], ['POST', 'fake-device-password']]) { + const incoming = receive(controller.ws); + const pending = f.request('/s2id_gen?test=1', { method, body: payload }); + const frame = await incoming; + assert.match(frame, new RegExp(`${method} /s2id_gen\\?test=1 HTTP/1\\.1`)); + assert.equal(frame.split('\r\n\r\n')[1], payload || ''); + reply(controller.ws, id(frame), body); + const response = await pending.response; + assert.equal(response.status, 200); + assert.deepEqual(response.body, body); + } + await until(() => f.logs.records().filter(r => r.msg === 'controller response forwarded').length === 3); + assert.equal(f.logs.records().filter(r => r.msg === 'request aborted').length, 0); +}); + +test('concurrent requests use distinct IDs and route out-of-order replies correctly', async t => { + const f = await fixture(t); + const controller = await f.connect(); + await controller.accepted(); + const seen = new Set(); + const frames = []; + controller.ws.on('message', data => { + const frame = data.toString(); + const requestId = id(frame); + assert.equal(seen.has(requestId), false); + seen.add(requestId); + frames.push(frame); + if (frames.length === 40) for (const frame of frames.reverse()) { + reply(controller.ws, id(frame), /GET \/jc\?n=(\d+)/.exec(frame)[1]); + } + }); + const pending = Array.from({ length: 40 }, (_, n) => f.request(`/jc?n=${n}`)); + const results = await Promise.all(pending.map(p => p.response)); + results.forEach((res, n) => assert.equal(res.body.toString(), String(n))); + assert.equal(seen.size, 40); +}); + +test('large valid fragmented responses survive with no second response on duplicates', async t => { + const f = await fixture(t, { requestTimeoutMs: 1000 }); + const controller = await f.connect(); + await controller.accepted(); + const incoming = receive(controller.ws); + const pending = f.request('/jl'); + const requestId = id(await incoming); + const body = 'x'.repeat(256 * 1024); + const response = `RES: ${requestId}\r\nHTTP/1.1 200 OK\r\nContent-Length: ${body.length}\r\n\r\n${body}`; + controller.ws.send(response.slice(0, 3), { fin: false }); + controller.ws.send(response.slice(3, 1000), { fin: false }); + controller.ws.send(response.slice(1000), { fin: true }); + assert.equal((await pending.response).body.toString(), body); + reply(controller.ws, requestId, 'duplicate'); + await delay(10); + assert.equal(f.logs.records().filter(r => r.event === 'request_settled').length, 1); +}); + +test('abandoned browser requests remove entries and listeners; late replies are ignored', async t => { + let response; + let ownedFinish; + const f = await fixture(t, { wrapForward: forward => (req, res) => { + response = res; + const existing = new Set(res.listeners('finish')); + forward(req, res); + ownedFinish = res.listeners('finish').filter(listener => !existing.has(listener)); + } }); + const controller = await f.connect(); + await controller.accepted(); + const incoming = receive(controller.ws); + const pending = f.request(); + const requestId = id(await incoming); + pending.request.destroy(); + await assert.rejects(pending.response); + await until(() => f.logs.records().some(r => r.reason === 'browser_departed')); + assert.ok(ownedFinish.length > 0); + for (const listener of ownedFinish) assert.equal(response.listeners('finish').includes(listener), false); + reply(controller.ws, requestId); + await delay(10); + assert.equal(f.logs.records().filter(r => r.event === 'request_settled').length, 1); + const next = receive(controller.ws); + const healthy = f.request(); + reply(controller.ws, id(await next)); + assert.equal((await healthy.response).status, 200); +}); + +test('timeout gives one 408, does not replay state-changing GET or POST, and skips expired IDs', async t => { + const f = await fixture(t, { requestTimeoutMs: 35 }); + const controller = await f.connect(); + await controller.accepted(); + const seen = []; + controller.ws.on('message', data => seen.push(data.toString())); + for (const method of ['GET', 'POST']) { + const incoming = receive(controller.ws); + const pending = f.request('/cm?sid=1&en=1', { method, body: method === 'POST' ? 'fake-key' : undefined }); + const requestId = id(await incoming); + const result = await pending.response; + assert.equal(result.status, 408); + assert.equal(JSON.parse(result.body).message, 'Controller did not respond.'); + reply(controller.ws, requestId, 'too late'); + } + await delay(45); + assert.equal(seen.length, 2); + assert.notEqual(id(seen[0]), id(seen[1])); + assert.equal(f.logs.records().filter(r => r.event === 'request_settled').length, 2); +}); + +test('a slow legitimate response within its deadline completes', async t => { + const f = await fixture(t, { requestTimeoutMs: 200 }); + const controller = await f.connect(); + await controller.accepted(); + const incoming = receive(controller.ws); + const pending = f.request('/jl'); + const requestId = id(await incoming); + await delay(80); + reply(controller.ws, requestId); + assert.equal((await pending.response).status, 200); + await delay(140); + assert.equal(f.logs.records().filter(r => r.event === 'request_settled').length, 1); +}); + +test('failed sends, thrown sends and delayed send-error callbacks settle only their own request', async t => { + const f = await fixture(t); + const controller = await f.connect(); + await controller.accepted(); + const send = controller.socket.send; + controller.socket.send = (_data, callback) => callback(new Error('send failure')); + assert.equal((await f.request().response).status, 408); + controller.socket.send = () => { throw new Error('send failure'); }; + assert.equal((await f.request().response).status, 408); + let late; + controller.socket.send = function (data, callback) { + late = callback; + return send.call(this, data, () => {}); + }; + const incoming = receive(controller.ws); + const pending = f.request(); + reply(controller.ws, id(await incoming)); + assert.equal((await pending.response).status, 200); + late(new Error('late error')); + assert.equal(f.logs.records().filter(r => r.event === 'request_settled').length, 3); +}); + +test('a response with a missing socket is settled without throwing', async t => { + let response; + const f = await fixture(t, { wrapForward: forward => (req, res) => { response = res; forward(req, res); } }); + const controller = await f.connect(); + await controller.accepted(); + const incoming = receive(controller.ws); + const pending = f.request(); + const requestId = id(await incoming); + response.socket = null; + reply(controller.ws, requestId); + await until(() => f.logs.records().some(r => r.reason === 'controller_response')); + pending.request.destroy(); + await assert.rejects(pending.response); + assert.equal(f.logs.records().filter(r => r.event === 'request_settled').length, 1); +}); + +test('partially sent HTTP responses are destroyed instead of receiving another response', async t => { + let response; + const f = await fixture(t, { wrapForward: forward => (req, res) => { response = res; forward(req, res); } }); + const controller = await f.connect(); + await controller.accepted(); + const incoming = receive(controller.ws); + const pending = f.request(); + const requestId = id(await incoming); + response.write('partial'); + reply(controller.ws, requestId); + await assert.rejects(pending.response); + assert.equal(f.logs.records().filter(r => r.event === 'request_settled').length, 1); +}); + +test('malformed continuation frames fail pending GET and POST exactly once and permit reconnect', async t => { + const f = await fixture(t); + for (const method of ['GET', 'POST']) { + const controller = await f.connect(); + await controller.accepted(); + const incoming = receive(controller.ws); + const pending = f.request('/jc', { method, body: method === 'POST' ? 'fake-key' : undefined }); + await incoming; + controller.ws._socket.write(Buffer.from([0x80, 0x81, 0, 0, 0, 0, 0x58])); + const result = await pending.response; + assert.equal(result.status, 408); + assert.equal(JSON.parse(result.body).message, 'Controller dropped packet.'); + await controller.closed; + } + assert.equal(f.logs.records().filter(r => r.event === 'request_settled').length, 2); + assert.equal(f.logs.records().filter(r => r.event === 'session_cleanup').length, 2); +}); + +test('malformed, binary and invalid UTF-8 headers do not consume pending requests or log payload', async t => { + const f = await fixture(t); + const controller = await f.connect(); + await controller.accepted(); + const incoming = receive(controller.ws); + const pending = f.request(); + const requestId = id(await incoming); + controller.ws.send('fake-payload-secret'); + controller.ws.send('RES: xxxx\r\nfake-payload-secret'); + controller.ws.send(Buffer.from([0xff, 0x0a, 0x61]), { binary: false }); + controller.ws.send(Buffer.from('fake-payload-secret')); + reply(controller.ws, requestId); + assert.equal((await pending.response).status, 200); + assert.equal(f.logs.text().includes('fake-payload-secret'), false); +}); + +test('redirect and HTTP error logging omit URLs, credentials, payloads and response headers', async t => { + const f = await fixture(t); + const redirect = await f.request('?pw=fake-query-secret', { headers: { + authorization: 'fake-auth-secret', cookie: 'fake-cookie-secret', + } }).response; + assert.equal(redirect.status, 301); + assert.match(redirect.headers.location, /pw=fake-query-secret/); + const tooLarge = await f.request('/jc?pw=fake-query-secret', { method: 'POST', + body: 'fake-body-secret'.repeat(100000) }).response; + assert.equal(tooLarge.status, 413); + const malformedPath = await f.request('/jc', { key: 'fake-%FF-secret' }).response; + assert.equal(malformedPath.status, 400); + for (const secret of ['fake-query-secret', 'fake-auth-secret', 'fake-cookie-secret', + 'fake-body-secret', 'fake-%FF-secret', 'local-only-fake-token']) { + assert.equal(f.logs.text().includes(secret), false, secret); + } +}); + +test('HTTP completion and lifecycle logs identify /jc and /cm without query strings', async t => { + const f = await fixture(t); + const controller = await f.connect(); + await controller.accepted(); + for (const endpoint of ['/jc', '/cm', '/fake-path-secret']) { + const incoming = receive(controller.ws); + const pending = f.request(`${endpoint}?pw=fake-query-secret`); + reply(controller.ws, id(await incoming)); + assert.equal((await pending.response).status, 200); + } + await until(() => f.logs.records().filter(r => r.msg === 'controller response forwarded').length === 3); + const httpEndpoints = f.logs.records().filter(r => r.msg === 'controller response forwarded').map(r => r.req.endpoint); + const lifecycleEndpoints = f.logs.records().filter(r => r.event === 'request_settled').map(r => r.endpoint); + assert.deepEqual(httpEndpoints, ['/jc', '/cm', '/other']); + assert.deepEqual(lifecycleEndpoints, httpEndpoints); + assert.equal(f.logs.text().includes('fake-query-secret'), false); + assert.equal(f.logs.text().includes('fake-path-secret'), false); +}); + +test('HTTP diagnostics preserve raw controller status codes without exposing response headers', async t => { + const f = await fixture(t); + const controller = await f.connect(); + await controller.accepted(); + for (const status of [200, 404, 503]) { + const incoming = receive(controller.ws); + const pending = f.request(); + const requestId = id(await incoming); + controller.ws.send(`RES: ${requestId}\r\nHTTP/1.1 ${status} Test\r\nContent-Length: 2\r\nX-Secret: fake-response-secret\r\n\r\nOK`); + const response = await pending.response; + assert.equal(response.status, status); + assert.equal(response.body.toString(), 'OK'); + } + await until(() => f.logs.records().filter(r => r.res).length === 3); + assert.deepEqual(f.logs.records().filter(r => r.res).map(r => r.res.statusCode), [200, 404, 503]); + assert.equal(f.logs.text().includes('fake-response-secret'), false); +}); + +test('full ID capacity returns a non-5xx response without forwarding', async t => { + const f = await fixture(t); + const controller = await f.connect(); + await controller.accepted(); + t.mock.method(RequestIds.prototype, 'allocate', () => undefined); + let forwarded = 0; + controller.ws.on('message', () => forwarded++); + assert.equal((await f.request().response).status, 429); + assert.equal(forwarded, 0); +}); + +test('reply/disconnect and timeout/disconnect races produce one terminal result', async t => { + const f = await fixture(t, { requestTimeoutMs: 40 }); + for (const order of ['reply-first', 'disconnect-first', 'timeout-first']) { + const controller = await f.connect(); + await controller.accepted(); + const incoming = receive(controller.ws); + const pending = f.request(); + const requestId = id(await incoming); + const countBefore = f.logs.records().filter(r => r.event === 'request_settled').length; + if (order === 'reply-first') { + reply(controller.ws, requestId); + controller.ws.close(); + } else if (order === 'disconnect-first') { + controller.ws.close(); + reply(controller.ws, requestId); + } else { + assert.equal((await pending.response).status, 408); + controller.ws.terminate(); + } + const result = await pending.response; + assert.ok([200, 408].includes(result.status)); + await controller.closed; + await delay(50); + assert.equal(f.logs.records().filter(r => r.event === 'request_settled').length, countBefore + 1); + } +}); + +test('the real 60-second default permits a legitimate response after 30 seconds', { timeout: 45000 }, async t => { + const previous = process.env.REQUEST_TIMEOUT_MS; + delete process.env.REQUEST_TIMEOUT_MS; + t.after(() => { + if (previous === undefined) delete process.env.REQUEST_TIMEOUT_MS; + else process.env.REQUEST_TIMEOUT_MS = previous; + }); + const f = await fixture(t, { requestTimeoutMs: undefined }); + const controller = await f.connect(); + await controller.accepted(); + const incoming = receive(controller.ws); + const pending = f.request('/jl'); + const requestId = id(await incoming); + await delay(31000); + reply(controller.ws, requestId, 'slow response'); + assert.equal((await pending.response).body.toString(), 'slow response'); + const terminal = f.logs.records().find(r => r.event === 'request_settled'); + assert.ok(terminal.durationMs >= 30000); + assert.equal(terminal.reason, 'controller_response'); +}); diff --git a/tests/helpers.cjs b/tests/helpers.cjs new file mode 100644 index 0000000..9927744 --- /dev/null +++ b/tests/helpers.cjs @@ -0,0 +1,80 @@ +const assert = require('node:assert/strict'); +const { once } = require('node:events'); +const http = require('node:http'); +const WebSocket = require('ws'); +const pino = require('pino'); +const { setupWebsockets, createHttpApp } = require(process.env.OTF_TEST_BUNDLE); + +const token = 'local-only-fake-token'; +const delay = ms => new Promise(resolve => setTimeout(resolve, ms)); +async function until(check) { + for (let n = 0; n < 300; n++) { + if (check()) return; + await delay(5); + } + assert.fail('Condition did not become true'); +} +function capture() { + let output = ''; + return { logger: pino({ level: 'trace' }, { write: value => { output += value; } }), + text: () => output, + records: () => output.trim() ? output.trim().split('\n').map(line => JSON.parse(line)) : [] }; +} +async function fixture(t, options = {}) { + const logs = capture(); + const auth = options.auth || { init: async () => {}, validateKey: async key => key === token }; + const proxy = await setupWebsockets(auth, logs.logger, { + host: '127.0.0.1', port: 0, requestTimeoutMs: 1000, + heartbeatIntervalMs: 10_000, rejectionTimeoutMs: 60, ...options, + }); + const forward = options.wrapForward ? options.wrapForward(proxy.forwardRequestV1) : proxy.forwardRequestV1; + const server = createHttpApp(forward, logs.logger).listen(0, '127.0.0.1'); + await once(server, 'listening'); + const clients = new Set(); + t.after(async () => { + for (const client of clients) client.terminate(); + server.closeAllConnections(); + const stopped = new Promise(resolve => server.close(resolve)); + await proxy.close(); + await stopped; + }); + async function connect({ key = token, path = '/socket/v1', query, ...wsOptions } = {}) { + const acceptedBefore = logs.records().filter(r => r.event === 'session_accepted').length; + const serverConnection = once(proxy.server, 'connection'); + const ws = new WebSocket(`ws://127.0.0.1:${proxy.server.address().port}${path}${query ?? `?deviceKey=${key}`}`, wsOptions); + clients.add(ws); + ws.on('error', () => {}); + const closed = new Promise(resolve => ws.once('close', (code, reason) => resolve({ code, reason: reason.toString() }))); + await once(ws, 'open'); + const [socket] = await serverConnection; + return { ws, socket, closed, accepted: () => until(() => + logs.records().filter(r => r.event === 'session_accepted').length > acceptedBefore) }; + } + function request(path = '/jc', { method = 'GET', body, headers = {}, key = token } = {}) { + let request; + const response = new Promise((resolve, reject) => { + request = http.request({ host: '127.0.0.1', port: server.address().port, + path: `/forward/v1/${key}${path}`, method, agent: false, + headers: { ...headers, ...(body !== undefined ? { + 'content-length': Buffer.byteLength(body), 'content-type': 'text/plain' } : {}) } }, res => { + const chunks = []; + res.on('data', chunk => chunks.push(chunk)); + res.on('error', reject); + res.on('aborted', () => reject(new Error('Response aborted'))); + res.on('end', () => resolve({ status: res.statusCode, body: Buffer.concat(chunks), headers: res.headers })); + }); + request.on('error', reject); + request.end(body); + }); + response.catch(() => {}); + return { request, response }; + } + return { ...proxy, logs, connect, request, httpServer: server }; +} +async function receive(ws) { return (await once(ws, 'message'))[0].toString(); } +function id(frame) { return /^FWD: ([0-9a-f]{4})\r\n/.exec(frame)[1]; } +function reply(ws, requestId, body = 'OK') { + const bytes = Buffer.isBuffer(body) ? body : Buffer.from(body); + ws.send(Buffer.concat([Buffer.from(`RES: ${requestId}\r\nHTTP/1.1 200 OK\r\nContent-Length: ${bytes.length}\r\n\r\n`), bytes]), { binary: false }); +} +module.exports = { fixture, receive, id, reply, delay, until, capture, token }; diff --git a/tests/lifecycle.test.cjs b/tests/lifecycle.test.cjs new file mode 100644 index 0000000..fce349f --- /dev/null +++ b/tests/lifecycle.test.cjs @@ -0,0 +1,246 @@ +const { test } = require('node:test'); +const assert = require('node:assert/strict'); +const WebSocket = require('ws'); +const { fixture, receive, reply, id, until, delay, token } = require('./helpers.cjs'); + +test('simultaneous delayed authentication accepts only one owner and gates protocol handlers', async t => { + const validations = []; + const f = await fixture(t, { auth: { init: async () => {}, + validateKey: () => new Promise(resolve => validations.push(resolve)) } }); + const first = await f.connect(); + const second = await f.connect(); + assert.equal(first.socket.listenerCount('message'), 0); + assert.equal(second.socket.listenerCount('message'), 0); + validations[1](true); + await second.accepted(); + const incoming = receive(second.ws); + const pending = f.request(); + const requestId = id(await incoming); + // The authenticated-but-not-yet-accepted connection cannot answer for its owner. + reply(first.ws, requestId, 'FORGED'); + await delay(10); + assert.equal(f.logs.records().filter(r => r.event === 'request_settled').length, 0); + validations[0](true); + assert.equal((await first.closed).code, 1008); + reply(second.ws, requestId, 'OWNER'); + assert.equal((await pending.response).body.toString(), 'OWNER'); + assert.equal(f.logs.records().filter(r => r.event === 'session_accepted').length, 1); +}); + +test('disconnect while authenticating cannot later register or install timers', async t => { + let complete; + const f = await fixture(t, { auth: { init: async () => {}, validateKey: () => + new Promise(resolve => { complete = resolve; }) } }); + const controller = await f.connect(); + controller.ws.close(); + await controller.closed; + complete(true); + await delay(10); + assert.equal(controller.socket.listenerCount('message'), 0); + assert.equal(f.logs.records().filter(r => r.event === 'session_accepted').length, 0); + assert.equal((await f.request().response).status, 404); +}); + +test('malformed frames during delayed authentication are observed safely and cannot register', async t => { + let complete; + const f = await fixture(t, { auth: { init: async () => {}, validateKey: () => + new Promise(resolve => { complete = resolve; }) } }); + const controller = await f.connect(); + controller.ws._socket.write(Buffer.from([0x80, 0x81, 0, 0, 0, 0, 0x58])); + await controller.closed; + complete(true); + await delay(10); + assert.equal(f.logs.records().filter(r => r.event === 'session_accepted').length, 0); + assert.equal((await f.request().response).status, 404); +}); + +test('all rejection paths deliver distinct safe close reasons and retain no protocol handler', async t => { + const f = await fixture(t, { auth: { init: async () => {}, validateKey: async key => { + if (key === 'backend') throw Object.assign(new Error(`SQL secret ${token}`), { code: 'ER_PARSE_ERROR', sql: token }); + return key === token; + } } }); + const owner = await f.connect(); + await owner.accepted(); + for (const [options, code, reason] of [ + [{ path: '/wrong' }, 1008, 'invalid path'], + [{ query: '' }, 1008, 'missing device key'], + [{ key: 'invalid' }, 1008, 'invalid device key'], + [{ key: 'backend' }, 1011, 'authentication unavailable'], + [{}, 1008, 'device key already connected'], + ]) { + const client = await f.connect(options); + assert.deepEqual(await client.closed, { code, reason }); + assert.equal(client.socket.listenerCount('message'), 0); + } + assert.equal(owner.ws.readyState, WebSocket.OPEN); + assert.equal(f.logs.text().includes(token), false); + assert.equal(f.logs.text().includes('SQL secret'), false); + assert.equal(f.logs.text().includes('"sql"'), false); +}); + +test('invalid authenticated duplicate cannot displace the owner', async t => { + let valid = true; + const f = await fixture(t, { auth: { init: async () => {}, validateKey: async () => valid } }); + const owner = await f.connect(); + await owner.accepted(); + valid = false; + const duplicate = await f.connect(); + assert.equal((await duplicate.closed).reason, 'invalid device key'); + assert.equal(owner.ws.readyState, WebSocket.OPEN); +}); + +test('old close, error and heartbeat callbacks cannot affect replacement requests', async t => { + const callbacks = []; + const realInterval = global.setInterval; + t.mock.method(global, 'setInterval', (callback, ms) => { + callbacks.push(callback); + return realInterval(callback, ms); + }); + const f = await fixture(t); + const old = await f.connect(); + await old.accepted(); + const lateClose = old.socket.listeners('close')[0]; + const lateError = old.socket.listeners('error')[0]; + const oldIncoming = receive(old.ws); + const oldRequest = f.request(); + await oldIncoming; + old.ws.terminate(); + assert.equal((await oldRequest.response).status, 408); + await until(() => f.logs.records().some(r => r.event === 'session_cleanup')); + const replacement = await f.connect(); + await replacement.accepted(); + const incoming = receive(replacement.ws); + const pending = f.request(); + const requestId = id(await incoming); + lateClose(1006); + lateError(new Error('old transport error')); + callbacks[0](); + lateClose(1006); + reply(replacement.ws, requestId, 'NEW'); + assert.equal((await pending.response).body.toString(), 'NEW'); + assert.equal(f.logs.records().filter(r => r.event === 'session_cleanup').length, 1); +}); + +test('a pending heartbeat pong does not permit a duplicate takeover', async t => { + const f = await fixture(t, { heartbeatIntervalMs: 100 }); + const owner = await f.connect({ autoPong: false }); + await owner.accepted(); + const ping = new Promise(resolve => owner.ws.once('ping', resolve)); + await ping; + const duplicate = await f.connect(); + assert.equal((await duplicate.closed).reason, 'device key already connected'); + owner.ws.pong(); + assert.equal(owner.ws.readyState, WebSocket.OPEN); +}); + +test('heartbeat expiry fails pending requests, then allows reconnect', async t => { + const f = await fixture(t, { heartbeatIntervalMs: 60 }); + const owner = await f.connect({ autoPong: false }); + await owner.accepted(); + const incoming = receive(owner.ws); + const pending = f.request(); + await incoming; + const duplicate = await f.connect(); + assert.equal((await duplicate.closed).code, 1008); + const result = await pending.response; + assert.equal(result.status, 408); + assert.equal(JSON.parse(result.body).message, 'Controller disconnected.'); + await owner.closed; + assert.equal((await f.request().response).status, 404); + const replacement = await f.connect(); + await replacement.accepted(); + const next = receive(replacement.ws); + const request = f.request(); + reply(replacement.ws, id(await next)); + assert.equal((await request.response).status, 200); + const event = f.logs.records().find(r => r.event === 'session_cleanup' && r.reason === 'heartbeat_expired'); + assert.equal(event.pendingRequests, 1); + assert.equal(typeof event.lastPongAgeMs, 'number'); +}); + +test('rejection fallback terminates a stalled close handshake and cancels on normal close', async t => { + let complete; + const f = await fixture(t, { rejectionTimeoutMs: 30, + auth: { init: async () => {}, validateKey: () => new Promise(resolve => { complete = resolve; }) } }); + const normal = await f.connect({ key: 'invalid' }); + complete(false); + assert.equal((await normal.closed).code, 1008); + const slow = await f.connect({ key: 'invalid' }); + // Receive the real close frame but suppress the ws client's automatic reply. + slow.ws._receiver.removeAllListeners('conclude'); + let frameCode; + slow.ws._receiver.on('conclude', code => { frameCode = code; }); + complete(false); + assert.equal((await slow.closed).code, 1006); + assert.equal(frameCode, 1008); + await delay(40); + assert.equal(f.logs.records().filter(r => r.event === 'rejection_forced_close').length, 1); + assert.equal(f.server.clients.size, 0); +}); + +for (const outcome of ['success', 'error']) { + test(`authentication timeout closes with 1011; late ${outcome} cannot affect a replacement`, async t => { + let complete; + let fail; + let calls = 0; + const f = await fixture(t, { authenticationTimeoutMs: 30, auth: { + init: async () => {}, validateKey: () => ++calls === 1 + ? new Promise((resolve, reject) => { complete = resolve; fail = reject; }) + : Promise.resolve(true), + } }); + const old = await f.connect(); + assert.deepEqual(await old.closed, { code: 1011, reason: 'authentication timed out' }); + assert.equal(old.socket.listenerCount('message'), 0); + assert.equal((await f.request().response).status, 404); + const replacement = await f.connect(); + await replacement.accepted(); + if (outcome === 'success') complete(true); + else fail(new Error('late backend secret')); + const incoming = receive(replacement.ws); + const pending = f.request(); + reply(replacement.ws, id(await incoming)); + assert.equal((await pending.response).status, 200); + assert.equal(f.logs.records().filter(r => r.event === 'session_accepted').length, 1); + assert.equal(f.logs.text().includes('late backend secret'), false); + }); +} + +test('an authenticating duplicate timing out preserves its healthy owner and pending requests', async t => { + let calls = 0; + const f = await fixture(t, { authenticationTimeoutMs: 30, auth: { + init: async () => {}, validateKey: () => ++calls === 1 ? Promise.resolve(true) : new Promise(() => {}), + } }); + const owner = await f.connect(); + await owner.accepted(); + const incoming = receive(owner.ws); + const pending = f.request(); + const requestId = id(await incoming); + const duplicate = await f.connect(); + assert.equal((await duplicate.closed).code, 1011); + reply(owner.ws, requestId); + assert.equal((await pending.response).status, 200); + assert.equal(owner.ws.readyState, WebSocket.OPEN); +}); + +test('authentication deadline timers are cancelled on acceptance and peer departure', async t => { + let expired = 0; + const originalTimeout = global.setTimeout; + t.mock.method(global, 'setTimeout', (callback, ms, ...args) => originalTimeout(() => { + if (ms === 30) expired++; + callback(...args); + }, ms)); + let hung = false; + const f = await fixture(t, { authenticationTimeoutMs: 30, auth: { + init: async () => {}, validateKey: () => hung ? new Promise(() => {}) : Promise.resolve(true), + } }); + const owner = await f.connect(); + await owner.accepted(); + hung = true; + const abandoned = await f.connect(); + abandoned.ws.close(); + await abandoned.closed; + await delay(50); + assert.equal(expired, 0); + assert.equal(f.logs.records().filter(r => r.event === 'connection_rejected').length, 0); + assert.equal(owner.ws.readyState, WebSocket.OPEN); +}); diff --git a/tests/run.mjs b/tests/run.mjs new file mode 100644 index 0000000..1d6a193 --- /dev/null +++ b/tests/run.mjs @@ -0,0 +1,22 @@ +import { build } from 'esbuild'; +import { mkdtemp, readdir, rm } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { spawn } from 'node:child_process'; +import { once } from 'node:events'; + +const directory = await mkdtemp(join(tmpdir(), 'otf-proxy-tests-')); +try { + const bundle = join(directory, 'exports.cjs'); + await build({ entryPoints: ['tests/exports.ts'], outfile: bundle, + bundle: true, platform: 'node', format: 'cjs' }); + const files = (await readdir('tests')).filter(name => name.endsWith('.test.cjs')) + .map(name => join('tests', name)); + const child = spawn(process.execPath, ['--test', ...files], { + env: { ...process.env, OTF_TEST_BUNDLE: bundle }, stdio: 'inherit', + }); + const [code] = await once(child, 'exit'); + process.exitCode = code ?? 1; +} finally { + await rm(directory, { recursive: true, force: true }); +} diff --git a/tests/server.test.cjs b/tests/server.test.cjs new file mode 100644 index 0000000..4a96b92 --- /dev/null +++ b/tests/server.test.cjs @@ -0,0 +1,83 @@ +const { test } = require('node:test'); +const assert = require('node:assert/strict'); +const { spawn } = require('node:child_process'); +const { once } = require('node:events'); +const net = require('node:net'); +const WebSocket = require('ws'); + +const token = 'local-only-fake-device-key'; +const delay = ms => new Promise(resolve => setTimeout(resolve, ms)); + +async function freePort() { + const server = net.createServer(); + server.listen(0, '127.0.0.1'); + await once(server, 'listening'); + const port = server.address().port; + await new Promise(resolve => server.close(resolve)); + return port; +} + +async function start(t) { + const httpPort = await freePort(); + const wsPort = await freePort(); + const child = spawn(process.execPath, ['dist/index.cjs'], { + env: { ...process.env, HOST: '127.0.0.1', HTTP_PORT: String(httpPort), + WEBSOCKET_PORT: String(wsPort), DEVICE_KEYS: token, LOG_LEVEL: 'trace', + AUTHENTICATION_PLUGIN: 'EnvironmentVariableAuthenticationPlugin' }, + stdio: ['ignore', 'pipe', 'pipe'], + }); + let logs = ''; + child.stdout.on('data', data => { logs += data; }); + child.stderr.on('data', data => { logs += data; }); + const exit = once(child, 'exit'); + t.after(async () => { + if (child.exitCode === null) child.kill(); + await exit; + }); + for (let i = 0; i < 200 && !logs.includes('now listening'); i++) { + if (child.exitCode !== null) throw new Error(logs); + await delay(10); + } + assert.match(logs, /now listening/); + const url = `ws://127.0.0.1:${wsPort}/socket/v1?deviceKey=${token}`; + const controller = new WebSocket(url); + controller.on('error', () => {}); + t.after(() => controller.terminate()); + await once(controller, 'open'); + return { controller, url, child, logs: () => logs, + base: `http://127.0.0.1:${httpPort}/forward/v1/${token}` }; +} + +test('running proxy forwards GET and body-parsed POST and keeps secrets out of logs', async t => { + const proxy = await start(t); + proxy.controller.on('message', data => { + const frame = data.toString(); + const id = /^FWD: ([0-9a-f]{4})\r\n/.exec(frame)[1]; + proxy.controller.send(`RES: ${id}\r\nHTTP/1.1 200 OK\r\nContent-Length: 2\r\n\r\nOK`); + }); + for (const method of ['GET', 'POST']) { + const response = await fetch(`${proxy.base}/jc?pw=fake-password-secret`, { + method, signal: AbortSignal.timeout(1500), + ...(method === 'POST' ? { body: 'fake-device-password', + headers: { 'content-type': 'text/plain' } } : {}), + }); + assert.equal(response.status, 200); + assert.equal(await response.text(), 'OK'); + } + await delay(20); + assert.equal(proxy.logs().includes(token), false); + assert.equal(proxy.logs().includes('fake-password-secret'), false); + assert.equal(proxy.logs().includes('fake-device-password'), false); +}); + +test('running proxy rejects duplicates with a close frame and preserves its owner', async t => { + const proxy = await start(t); + const duplicate = new WebSocket(proxy.url); + duplicate.on('error', () => {}); + t.after(() => duplicate.terminate()); + const closed = once(duplicate, 'close'); + const [code] = await closed; + assert.equal(code, 1008); + assert.equal(proxy.controller.readyState, WebSocket.OPEN); + assert.equal(proxy.child.exitCode, null); +}); diff --git a/tests/utilities.test.cjs b/tests/utilities.test.cjs new file mode 100644 index 0000000..facc23e --- /dev/null +++ b/tests/utilities.test.cjs @@ -0,0 +1,79 @@ +const { test } = require('node:test'); +const assert = require('node:assert/strict'); +const { capture, token } = require('./helpers.cjs'); +const { RequestIds, requestTimeout, EventLimiter, MySQLAuthenticationPlugin } = require(process.env.OTF_TEST_BUNDLE); + +test('request IDs skip pending values, wrap, and bound exhausted allocation', () => { + const ids = new RequestIds(0xfffe); + const pending = new Map([['fffe', {}], ['0000', {}]]); + assert.equal(ids.allocate(pending), 'ffff'); + assert.equal(ids.allocate(pending), '0001'); + // A single available ID can be reused after scanning occupied values: wrap + // means counter advances, not a guaranteed number of forwarded requests. + const full = new Map(Array.from({ length: 65536 }, (_, n) => [n.toString(16).padStart(4, '0'), {}])); + assert.equal(ids.allocate(full), undefined); + full.delete('0001'); + assert.equal(ids.allocate(full), '0001'); + assert.equal(ids.allocate(full), '0001'); +}); + +test('normal allocation avoids reuse for a complete counter cycle', () => { + const ids = new RequestIds(17); + const seen = new Set(); + const pending = new Map(); + for (let n = 0; n < 65536; n++) { + const value = ids.allocate(pending); + assert.equal(seen.has(value), false); + seen.add(value); + } + assert.equal(ids.allocate(pending), '0011'); +}); + +test('request deadline defaults to 60 seconds and rejects invalid or excessive configuration safely', () => { + const logs = capture(); + assert.equal(requestTimeout(undefined, logs.logger), 60000); + assert.equal(requestTimeout('60000', logs.logger), 60000); + assert.equal(requestTimeout(123, logs.logger), 123); + for (const value of ['', 'not-a-number-secret', 'Infinity', '-1', 0, 0.5, 300001, null]) { + assert.equal(requestTimeout(value, logs.logger), 60000); + } + assert.equal(logs.text().includes('not-a-number-secret'), false); +}); + +test('rejection logging bounds same-key and distinct-key bursts and reports suppression', () => { + let now = 0; + const logs = capture(); + const limiter = new EventLimiter(100, 8, 10, () => now); + for (let n = 0; n < 1000; n++) limiter.log(logs.logger, 'info', 'rejected', 'same'); + assert.equal(logs.records().length, 1); + now = 101; + limiter.log(logs.logger, 'info', 'rejected', 'same'); + assert.equal(logs.records().at(-1).suppressed, 999); + for (let n = 0; n < 1000; n++) limiter.log(logs.logger, 'info', 'rejected', `key-${n}`); + assert.ok(logs.records().length <= 11); + assert.ok(limiter.entries.size <= 8); +}); + +test('MySQL backend errors reject with a sanitized code instead of invalid-key false', async () => { + const logs = capture(); + const plugin = new MySQLAuthenticationPlugin(); + plugin.logger = logs.logger; + plugin.pool = { query: (_sql, args, callback) => { + assert.equal(args[1], token); + callback(Object.assign(new Error(`query contained ${token}`), { + code: 'ER_PARSE_ERROR', sql: `SELECT secret '${token}'`, sqlMessage: token, + })); + } }; + await assert.rejects(plugin.validateKey(token), error => { + assert.equal(error.code, 'ER_PARSE_ERROR'); + assert.equal(error.message, 'Authentication backend unavailable'); + assert.equal('sql' in error, false); + assert.equal(JSON.stringify(error).includes(token), false); + return true; + }); + assert.equal(logs.text().includes(token), false); + plugin.pool = { query: (_sql, _args, callback) => callback(null, []) }; + assert.equal(await plugin.validateKey(token), false); + plugin.pool = { query: (_sql, _args, callback) => callback(null, [{}]) }; + assert.equal(await plugin.validateKey(token), true); +});