redweb 0.8.0 → 0.10.0

package/src/http/HttpServer.js

@@ -1,26 +1,26 @@
-const http = require('http');
-const { BaseHttpServer } = require('./BaseHttpServer');
-const { listenServer, closeServer } = require('../serverLifecycle');
+const http = require('http');
+const { BaseHttpServer } = require('./BaseHttpServer');
+const { listenServer, closeServer } = require('../serverLifecycle');
 
 /**
  * HTTP Server
  * @param {RedWebOptions} options - Configuration options for RedWeb.
  * @return {Object} Express application instance.
  */
-function HttpServer(options) {
-    BaseHttpServer.call(this, options);
-    this.server = http.createServer(this.app);
-    this.shutdown = () => closeServer(this.server);
-    if (this.listen !== false) {
-        listenServer(this.server, {
-            port: this.port,
-            bind: this.bind,
-            callback: this.listenCallback,
-            logger: this.logger,
-            name: 'HttpServer',
-        });
-    }
-    return this;
-}
+function HttpServer(options) {
+    BaseHttpServer.call(this, options);
+    this.server = http.createServer(this.app);
+    this.shutdown = () => closeServer(this.server);
+    if (this.listen !== false) {
+        listenServer(this.server, {
+            port: this.port,
+            bind: this.bind,
+            callback: this.listenCallback,
+            logger: this.logger,
+            name: 'HttpServer',
+        });
+    }
+    return this;
+}
 
 module.exports = HttpServer;

package/src/http/HttpsServer.js

@@ -1,30 +1,30 @@
 const https = require('https');
 const { BaseHttpServer } = require('./BaseHttpServer');
-const loadSslConfig = require('../sslConfig');
-const { listenServer, closeServer } = require('../serverLifecycle');
+const loadSslConfig = require('../sslConfig');
+const { listenServer, closeServer } = require('../serverLifecycle');
 
 /**
  * HTTPS Server
  * @param {RedWebOptions} options - Configuration options for RedWeb.
  * @return {Object} Express application instance.
  */
-function HttpsServer(options) {
-    BaseHttpServer.call(this, options);
-    const sslOptions = loadSslConfig(this.ssl);
-    this.server = https.createServer(sslOptions, this.app);
-    this.shutdown = () => closeServer(this.server);
-    if (this.listen === false) {
-        return this;
-    }
-
-    listenServer(this.server, {
-        port: this.port,
-        bind: this.bind,
-        callback: this.listenCallback,
-        logger: this.logger,
-        name: 'HttpsServer',
-    });
-    return this;
-}
+function HttpsServer(options) {
+    BaseHttpServer.call(this, options);
+    const sslOptions = loadSslConfig(this.ssl);
+    this.server = https.createServer(sslOptions, this.app);
+    this.shutdown = () => closeServer(this.server);
+    if (this.listen === false) {
+        return this;
+    }
+
+    listenServer(this.server, {
+        port: this.port,
+        bind: this.bind,
+        callback: this.listenCallback,
+        logger: this.logger,
+        name: 'HttpsServer',
+    });
+    return this;
+}
 
 module.exports = HttpsServer;

package/src/serverLifecycle.js

@@ -1,46 +1,46 @@
-function listenServer(server, { port, bind, callback, logger = console, name = 'Server' }) {
-    const onListening = callback || (() => logger?.log?.(`RedWeb ${name} listening on ${bind}:${port}`));
-    server.listen(port, bind, onListening);
-}
-
-function validateListenerOptions(options) {
-    if (!Number.isInteger(options.port) || options.port < 0 || options.port > 65535) {
-        throw new TypeError('`port` must be an integer between 0 and 65535.');
-    }
-    if (typeof options.bind !== 'string' || !options.bind) {
-        throw new TypeError('`bind` must be a non-empty string.');
-    }
-    if (typeof options.listen !== 'boolean') {
-        throw new TypeError('`listen` must be a boolean.');
-    }
-    if (options.listenCallback !== undefined && typeof options.listenCallback !== 'function') {
-        throw new TypeError('`listenCallback` must be a function.');
-    }
-}
-
-async function settleTasks(tasks) {
-    const results = await Promise.allSettled(tasks.map(task => Promise.resolve().then(task)));
-    return results.filter(result => result.status === 'rejected').map(result => result.reason);
-}
-
-function throwCleanupErrors(errors, message) {
-    if (!errors.length) return;
-    const aggregate = new Error(message);
-    aggregate.errors = errors;
-    throw aggregate;
-}
-
-function closeServer(server) {
-    return new Promise((resolve, reject) => {
-        if (!server?.listening) return resolve();
-        server.close((error) => error ? reject(error) : resolve());
-    });
-}
-
-module.exports = {
-    listenServer,
-    closeServer,
-    settleTasks,
-    throwCleanupErrors,
-    validateListenerOptions,
-};
+function listenServer(server, { port, bind, callback, logger = console, name = 'Server' }) {
+    const onListening = callback || (() => logger?.log?.(`RedWeb ${name} listening on ${bind}:${port}`));
+    server.listen(port, bind, onListening);
+}
+
+function validateListenerOptions(options) {
+    if (!Number.isInteger(options.port) || options.port < 0 || options.port > 65535) {
+        throw new TypeError('`port` must be an integer between 0 and 65535.');
+    }
+    if (typeof options.bind !== 'string' || !options.bind) {
+        throw new TypeError('`bind` must be a non-empty string.');
+    }
+    if (typeof options.listen !== 'boolean') {
+        throw new TypeError('`listen` must be a boolean.');
+    }
+    if (options.listenCallback !== undefined && typeof options.listenCallback !== 'function') {
+        throw new TypeError('`listenCallback` must be a function.');
+    }
+}
+
+async function settleTasks(tasks) {
+    const results = await Promise.allSettled(tasks.map(task => Promise.resolve().then(task)));
+    return results.filter(result => result.status === 'rejected').map(result => result.reason);
+}
+
+function throwCleanupErrors(errors, message) {
+    if (!errors.length) return;
+    const aggregate = new Error(message);
+    aggregate.errors = errors;
+    throw aggregate;
+}
+
+function closeServer(server) {
+    return new Promise((resolve, reject) => {
+        if (!server?.listening) return resolve();
+        server.close((error) => error ? reject(error) : resolve());
+    });
+}
+
+module.exports = {
+    listenServer,
+    closeServer,
+    settleTasks,
+    throwCleanupErrors,
+    validateListenerOptions,
+};

package/src/ws/AdmissionPolicy.js

@@ -0,0 +1,145 @@
+const ADMISSION_CONTEXT = Symbol('redweb.admissionContext');
+const PLACEMENT_REDIRECT = Symbol('redweb.placementRedirect');
+const ADMISSION_SETTLEMENT = Symbol('redweb.admissionSettlement');
+
+class AdmissionPolicy {
+    constructor(options) {
+        const config = typeof options === 'function' ? { authenticate: options } : options;
+        if (!config || typeof config !== 'object' || Array.isArray(config)) {
+            throw new TypeError('`admission` must be a function or an object.');
+        }
+        const {
+            authenticate,
+            origins,
+            place,
+            timeoutMs = 5000,
+            allowedPlacementOrigins,
+            allowInsecurePlacement = false,
+        } = config;
+        if (authenticate !== undefined && typeof authenticate !== 'function') {
+            throw new TypeError('`admission.authenticate` must be a function.');
+        }
+        if (!(Array.isArray(origins) || typeof origins === 'function' || origins === undefined)) {
+            throw new TypeError('`admission.origins` must be an array or a function.');
+        }
+        if (place !== undefined && typeof place !== 'function') {
+            throw new TypeError('`admission.place` must be a function.');
+        }
+        if (Array.isArray(origins) && origins.some(origin => typeof origin !== 'string' || !origin)) {
+            throw new TypeError('Every `admission.origins` entry must be a non-empty string.');
+        }
+        if (!Number.isInteger(timeoutMs) || timeoutMs < 1) {
+            throw new TypeError('`admission.timeoutMs` must be a positive integer.');
+        }
+        if (typeof allowInsecurePlacement !== 'boolean') {
+            throw new TypeError('`admission.allowInsecurePlacement` must be a boolean.');
+        }
+        if (allowedPlacementOrigins !== undefined && !Array.isArray(allowedPlacementOrigins)) {
+            throw new TypeError('`admission.allowedPlacementOrigins` must be an array.');
+        }
+        this.allowedPlacementOrigins = allowedPlacementOrigins?.map(origin => this.validatePlacementOrigin(origin));
+        if (this.allowedPlacementOrigins && new Set(this.allowedPlacementOrigins).size !== this.allowedPlacementOrigins.length) {
+            throw new TypeError('`admission.allowedPlacementOrigins` entries must be unique.');
+        }
+        if (!authenticate && !origins && !place) {
+            throw new TypeError('`admission` requires `authenticate`, `origins`, or `place`.');
+        }
+        this.authenticate = authenticate;
+        this.origins = origins;
+        this.place = place;
+        this.timeoutMs = timeoutMs;
+        this.allowInsecurePlacement = allowInsecurePlacement;
+    }
+
+    async authorize(request, rawSocket, route, externalSignal) {
+        const controller = new AbortController();
+        const onClose = () => controller.abort();
+        const onExternalAbort = () => controller.abort();
+        rawSocket.once('close', onClose);
+        if (externalSignal?.aborted) controller.abort();
+        else externalSignal?.addEventListener('abort', onExternalAbort, { once: true });
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        timer.unref();
+        try {
+            const evaluation = Promise.resolve().then(() => this.evaluate(request, route, controller.signal));
+            request[ADMISSION_SETTLEMENT] = evaluation.then(() => undefined, () => undefined);
+            const cancelled = new Promise((_, reject) => {
+                controller.signal.addEventListener('abort', () => reject(new Error('Admission cancelled.')), { once: true });
+            });
+            const result = await Promise.race([
+                evaluation,
+                cancelled,
+            ]);
+            if (result === false || rawSocket.destroyed || controller.signal.aborted) return false;
+            if (result.redirect) {
+                request[PLACEMENT_REDIRECT] = result.redirect;
+                return false;
+            }
+            request[ADMISSION_CONTEXT] = { principal: result.principal };
+            return true;
+        } catch {
+            return false;
+        } finally {
+            clearTimeout(timer);
+            rawSocket.off?.('close', onClose);
+            externalSignal?.removeEventListener?.('abort', onExternalAbort);
+        }
+    }
+
+    validatePlacementOrigin(origin) {
+        if (typeof origin !== 'string' || !origin) {
+            throw new TypeError('Placement origins must be non-empty strings.');
+        }
+        let parsed;
+        try {
+            parsed = new URL(origin);
+        } catch {
+            throw new TypeError('Placement origins must be valid ws or wss origins.');
+        }
+        if (!['ws:', 'wss:'].includes(parsed.protocol) || parsed.username || parsed.password || parsed.pathname !== '/' || parsed.search || parsed.hash) {
+            throw new TypeError('Placement origins must be ws or wss origins without credentials, paths, queries, or fragments.');
+        }
+        return parsed.origin;
+    }
+
+    isSafeRedirect(value) {
+        if (!value || value.length > 2048 || /[\r\n]/.test(value)) return false;
+        try {
+            const parsed = new URL(value);
+            if (!['ws:', 'wss:'].includes(parsed.protocol) || parsed.username || parsed.password || parsed.hash) return false;
+            if (parsed.protocol === 'ws:' && !this.allowInsecurePlacement) return false;
+            return !this.allowedPlacementOrigins || this.allowedPlacementOrigins.includes(parsed.origin);
+        } catch {
+            return false;
+        }
+    }
+
+    async evaluate(request, route, signal) {
+        if (!await this.acceptsOrigin(request)) return false;
+        const context = {
+            signal,
+            networkIdentity: route.resolveRemoteAddress(request),
+            route,
+        };
+        const principal = this.authenticate ? await this.authenticate(request, context) : undefined;
+        if (principal === false) return false;
+        if (!this.place) return { principal };
+        const placement = await this.place(principal, request, context);
+        if (placement === false) return false;
+        if (typeof placement === 'string') {
+            return this.isSafeRedirect(placement) ? { redirect: placement } : false;
+        }
+        return { principal };
+    }
+
+    async acceptsOrigin(request) {
+        if (!this.origins) return true;
+        const origin = request?.headers?.origin;
+        if (typeof this.origins === 'function') {
+            return Boolean(await this.origins(origin, request));
+        }
+        return typeof origin === 'string' && this.origins.includes(origin);
+    }
+}
+
+module.exports = { AdmissionPolicy, ADMISSION_CONTEXT, PLACEMENT_REDIRECT, ADMISSION_SETTLEMENT };

package/src/ws/BaseHandler.js

@@ -18,47 +18,47 @@ class BaseHandler {
      * @param {WebSocket & {sendJson: (message: Object) => void, broadcast: (message: Object) => void}} socket - The WebSocket connection that sent the message.
      * @param {any} message - The incoming message in parsed JSON.
      */
-    async handleMessage(socket, message) {
-        const validationResult = await this.validateMessage(message, socket);
-        if (validationResult === false) {
-            throw new Error('Invalid message');
-        }
-        return this.onMessage(socket, message);
-    }
-
-    validateMessage() {
-        return true;
-    }
-
-    /**
-     * Handles an incoming binary message.
-     * @param {WebSocket & {sendJson: (message: Object) => void}} socket - The WebSocket connection that sent the message.
-     * @param {Buffer} buffer - The incoming binary message.
-     */
-    async handleBinaryMessage(socket, buffer) {
-        return this.onBinaryMessage(socket, buffer);
-    }
-
-    /**
-     * Method to be overriden to process messages.
-     * @param {WebSocket} socket - The WebSocket connection that sent the message.
-     * @param {any} message - The incoming message in parsed JSON.
+    async handleMessage(socket, message) {
+        const validationResult = await this.validateMessage(message, socket);
+        if (validationResult === false) {
+            throw new Error('Invalid message');
+        }
+        return this.onMessage(socket, message);
+    }
+
+    validateMessage() {
+        return true;
+    }
+
+    /**
+     * Handles an incoming binary message.
+     * @param {WebSocket & {sendJson: (message: Object) => void}} socket - The WebSocket connection that sent the message.
+     * @param {Buffer} buffer - The incoming binary message.
      */
-    onMessage(socket, message) {
-        throw new Error('onMessage must be implemented by the handler.');
-    }
-
-    /**
-     * Method to be overriden to process binary messages.
-     * @param {WebSocket & {sendJson: (message: Object) => void}} socket - The WebSocket connection that sent the message.
-     * @param {Buffer} buffer - The incoming binary message.
-     */
-    onBinaryMessage(socket, buffer) {
-        socket.sendJson({ error: 'Binary messages are not supported by this handler' });
-    }
-
-    onInitialContact(socket) {
-
+    async handleBinaryMessage(socket, buffer) {
+        return this.onBinaryMessage(socket, buffer);
+    }
+
+    /**
+     * Method to be overriden to process messages.
+     * @param {WebSocket} socket - The WebSocket connection that sent the message.
+     * @param {any} message - The incoming message in parsed JSON.
+     */
+    onMessage(socket, message) {
+        throw new Error('onMessage must be implemented by the handler.');
+    }
+
+    /**
+     * Method to be overriden to process binary messages.
+     * @param {WebSocket & {sendJson: (message: Object) => void}} socket - The WebSocket connection that sent the message.
+     * @param {Buffer} buffer - The incoming binary message.
+     */
+    onBinaryMessage(socket, buffer) {
+        socket.sendJson({ error: 'Binary messages are not supported by this handler' });
+    }
+
+    onInitialContact(socket) {
+
     }
 }