@interopio/gateway-server 0.19.3 → 0.20.0

package/gateway-server

@@ -0,0 +1,442 @@
+#!/usr/bin/env node
+
+`use strict`;
+
+import { writeFileSync } from 'node:fs';
+import { configure } from '@interopio/gateway/logging/core';
+
+// import { GatewayServer } from './src/index.ts';
+// import { mkcert, argon2 } from './src/tools/index.ts';
+
+import { GatewayServer } from './dist/index.js';
+import { mkcert, argon2 } from './dist/tools/index.js';
+
+function showHelp() {
+    console.log(`
+Usage: gateway-server <command> [options]
+
+Commands:
+  run                    Run the gateway server (default if no command specified)
+  passwd                 Generate password hash (default using Argon2)
+  mkcert                 Generate client and/or server certificate signed by Dev CA
+
+run options:
+  -p, --port <port>      Specify port or port range to bind the server to (default: 0 i.e. random available port)
+                         examples: 8385, 8000-8100, 3000,4000-4050
+  -H, --host <host>      Network address to bind to (default: unspecified, listens on all interfaces)
+                         examples: localhost, 127.0.0.1, 0.0.0.0, ::1
+  -u, --user <name>      Enables basic authentication and sets the admin username
+  -S, --ssl, --tls       Enable HTTPS. Auto-generates Dev CA and/or server certificates if not present. Enables x509 client cert auth if --user not specified.
+  --cert <file>          File with SSL/TLS certificate (default: ./gateway-server.crt)
+  --key <file>           File with SSL/TLS private key (default: ./gateway-server.key)
+  --ca <file>            File with CA certificates (default: ./gateway-ca.crt)
+  --ca-key <file>        File with CA private key (default: ./gateway-ca.key)
+  --debug                Enable debug logging (default: info level)
+
+passwd options:
+  (no args)              Prompt for password interactively (masked input)
+  --stdin                Read password from stdin (for piping, e.g., echo "pass" | ...)
+
+mkcert options:
+  --client               Generate client certificate (default: server certificate)
+  -u, --user <name>      Common Name for the certificate (default: dev-user for client certs) (--client only)
+  --ca <file>            File with CA certificate (default: ./gateway-ca.crt)
+  --ca-key <file>        File with CA private key (default: ./gateway-ca.key)
+  --key <file>           Output file for private key (default: ./gateway-server.key for server, ./gateway-client.key for client)
+  --cert <file>          Output file for certificate (default: ./gateway-server.crt for server, ./gateway-client.crt for client)
+  [name...]              DNS names, IP addresses, or email addresses for subjectAltName
+                         (DNS by default, prefix with 'IP:' or 'EMAIL:' for other types)
+
+Global Options:
+  -v, --version          Show version information and exit
+  --help                 Show this help message and exit
+
+Examples:
+  gateway-server run -p 3000
+  gateway-server run -u admin --port 8385,8388 --debug
+  gateway-server run -p 8443 --ssl --user admin
+  gateway-server passwd
+  echo "mySecret123" | gateway-server passwd --stdin
+  gateway-server mkcert
+  gateway-server mkcert localhost 127.0.0.1 IP:192.168.1.100
+  gateway-server mkcert --client EMAIL:john.doe@example.com
+  gateway-server mkcert example.com *.example.com --key ./gateway-server.key --cert ./gateway-server.crt
+`);
+    process.exit(0);
+}
+
+function showVersion() {
+    console.log(GatewayServer.VERSION);
+    process.exit(0);
+}
+
+
+// Parse command-line arguments
+const args = process.argv.slice(2);
+
+// Check for global flags first
+if (args.includes('--version') || args.includes('-v')) {
+    showVersion();
+}
+if (args.includes('--help') || args.includes('-h')) {
+    showHelp();
+}
+
+// Determine command (default to 'run' for backward compatibility)
+let command = 'run';
+let commandArgs = args;
+
+if (args.length > 0 && !args[0].startsWith('-')) {
+    command = args[0];
+    commandArgs = args.slice(1);
+}
+
+// Route to appropriate command handler
+switch (command) {
+    case 'run':
+        await runServer(commandArgs);
+        break;
+    case 'passwd':
+        await passwdCommand(commandArgs);
+        break;
+    case 'mkcert':
+        await mkcertCommand(commandArgs);
+        break;
+    default:
+        console.error(`Error: Unknown command "${command}"`);
+        console.log('Use --help to see available commands');
+        process.exit(1);
+}
+
+// Command: passwd - Generate password hash
+async function passwdCommand(args) {
+    let password = undefined;
+    let fromStdin = false;
+
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--stdin') {
+            fromStdin = true;
+        } else {
+            console.error(`Error: Unknown option "${args[i]}"`);
+            console.log('Use: gateway-server passwd');
+            console.log('  or: gateway-server passwd --stdin');
+            process.exit(1);
+        }
+    }
+
+    // Read password from stdin if specified
+    if (fromStdin) {
+        password = await readPasswordFromStdin();
+    }
+
+    // If no password provided, prompt interactively
+    if (!password) {
+        password = await promptPassword('Enter password: ');
+    }
+
+    if (!password) {
+        console.error('Error: password is required');
+        process.exit(1);
+    }
+
+    const hashValue = await argon2.hash(password);
+    const hash = `{argon2id}${hashValue}`;
+    console.log(hash);
+    process.exit(0);
+}
+
+// Read password from piped stdin (non-interactive)
+async function readPasswordFromStdin() {
+    // Check if stdin is a TTY (interactive terminal)
+    if (process.stdin.isTTY) {
+        // Interactive mode - use readline with hidden input
+        return promptPassword('Password: ');
+    }
+
+    // Piped mode - read until EOF or newline
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    const content = Buffer.concat(chunks).toString('utf8');
+    // Strip trailing newline
+    return content.replace(/\r?\n$/, '');
+}
+
+// Prompt for password with masked input
+async function promptPassword(prompt) {
+    return new Promise((resolve) => {
+        process.stdout.write(prompt);
+
+        // Only set raw mode if stdin is a TTY
+        if (!process.stdin.isTTY) {
+            console.error('Error: Interactive password prompt requires a terminal');
+            process.exit(1);
+        }
+
+        process.stdin.setRawMode(true);
+        process.stdin.resume();
+        process.stdin.setEncoding('utf8');
+
+        let password = '';
+
+        const cleanup = () => {
+            process.stdin.setRawMode(false);
+            process.stdin.pause();
+            process.stdin.removeListener('data', onData);
+            process.stdout.write('\n');
+        };
+
+        const onData = (char) => {
+            // Ctrl+C
+            if (char === '\u0003') {
+                cleanup();
+                process.exit(1);
+            }
+
+            // Enter
+            if (char === '\r' || char === '\n') {
+                cleanup();
+                resolve(password);
+                return;
+            }
+
+            // Backspace
+            if (char === '\u007f' || char === '\b') {
+                if (password.length > 0) {
+                    password = password.slice(0, -1);
+                    process.stdout.write('\b \b');
+                }
+                return;
+            }
+
+            // Regular character
+            password += char;
+            process.stdout.write('*');
+        };
+
+        process.stdin.on('data', onData);
+    });
+}
+
+// Command: mkcert - Generate client or server certificate
+async function mkcertCommand(args) {
+    let isClientCert = false;
+    let user = 'dev-user';
+    let caCert = './gateway-ca.crt';
+    let caKey = './gateway-ca.key';
+    let keyPath = undefined;
+    let certPath = undefined;
+    const sanEntries = [];
+
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--client') {
+            isClientCert = true;
+        } else if ((args[i] === '--user' || args[i] === '-u') && i + 1 < args.length) {
+            user = args[i + 1];
+            i++;
+        } else if (args[i] === '--ca' && i + 1 < args.length) {
+            caCert = args[i + 1];
+            i++;
+        } else if (args[i] === '--ca-key' && i + 1 < args.length) {
+            caKey = args[i + 1];
+            i++;
+        } else if (args[i] === '--key' && i + 1 < args.length) {
+            keyPath = args[i + 1];
+            i++;
+        } else if (args[i] === '--cert' && i + 1 < args.length) {
+            certPath = args[i + 1];
+            i++;
+        } else if (!args[i].startsWith('-')) {
+            // Positional argument - add to SAN entries
+            sanEntries.push(args[i]);
+        } else {
+            console.error(`Error: Unknown option "${args[i]}"`);
+            console.log('Use: gateway-server mkcert [--client] [--user <name>] [--ca <file>] [--ca-key <file>] [--key <file>] [--cert <file>] [name...]');
+            process.exit(1);
+        }
+    }
+
+    // Default output paths
+    // Users typically specify just --cert, and key should go in the same file
+    if (!keyPath && !certPath) {
+        // Neither specified: use defaults based on certificate type
+        if (isClientCert) {
+            // Client certificate: combined file by default
+            keyPath = './gateway-client.key';
+            certPath = './gateway-client.crt';
+        } else {
+            // Server certificate: separate files by default
+            keyPath = './gateway-server.key';
+            certPath = './gateway-server.crt';
+        }
+    } else if (keyPath && !certPath) {
+        // Only --key specified: cert goes in the same file (combined)
+        certPath = keyPath;
+    } else if (!keyPath && certPath) {
+        // Only --cert specified: key goes in the same file (combined)
+        keyPath = certPath;
+    }
+    // else: both specified, use as-is
+
+    if (sanEntries.length === 0) {
+        if (isClientCert) {
+            sanEntries.push(user);
+        }
+        else {
+            // Default SAN entry for server certs
+            sanEntries.push('localhost');
+        }
+    }
+
+    const { readFileSync } = await import('node:fs');
+    const { KEYUTIL, X509 } = await import('jsrsasign');
+
+    // Load CA key
+    let caKeyObj;
+    try {
+        const caKeyPem = readFileSync(caKey, 'utf8');
+        caKeyObj = KEYUTIL.getKey(caKeyPem);
+    } catch (error) {
+        console.error(`Error: Cannot read CA key from ${caKey}`);
+        console.error(error.message);
+        process.exit(1);
+    }
+
+    // Extract issuer from CA certificate
+    let issuer;
+    try {
+        const caCertPem = readFileSync(caCert, 'utf8');
+        const caCertObj = new X509();
+        caCertObj.readCertPEM(caCertPem);
+        issuer = caCertObj.getSubjectString();
+    } catch (error) {
+        console.error(`Error: Cannot read CA certificate from ${caCert}`);
+        console.error(error.message);
+        process.exit(1);
+    }
+
+    // Generate certificate using SAN entries
+    const cert = mkcert.generateCert(caKeyObj, issuer, sanEntries, isClientCert);
+
+    // Write files
+    try {
+        if (keyPath === certPath) {
+            // Concatenate cert and key into single file (cert first, then key)
+            const combined = cert.cert + cert.key;
+            writeFileSync(keyPath, combined, { mode: 0o600 });
+            console.log(`${isClientCert ? 'Client' : 'Server'} certificate generated successfully:`);
+            console.log(`  Combined (cert+key): ${keyPath}`);
+            if (sanEntries.length > 0) {
+                console.log(`  SAN: ${sanEntries.join(', ')}`);
+            }
+        } else {
+            // Write separate files
+            writeFileSync(keyPath, cert.key, { mode: 0o600 });
+            writeFileSync(certPath, cert.cert, { mode: 0o644 });
+            console.log(`${isClientCert ? 'Client' : 'Server'} certificate generated successfully:`);
+            console.log(`  Private key: ${keyPath}`);
+            console.log(`  Certificate: ${certPath}`);
+            if (sanEntries.length > 0) {
+                console.log(`  SAN: ${sanEntries.join(', ')}`);
+            }
+        }
+
+        process.exit(0);
+    } catch (error) {
+        console.error(`Error: Cannot write certificate files`);
+        console.error(error.message);
+        process.exit(1);
+    }
+}
+
+// Command: run - Start the server
+async function runServer(args) {
+    const options = {
+        port: 0,
+        host: undefined,
+        user: undefined,
+        debug: false,
+        ssl: false,
+        cert: undefined,
+        key: undefined,
+        ca: undefined,
+        caKey: undefined
+    };
+
+    for (let i = 0; i < args.length; i++) {
+        if ((args[i] === '--port' || args[i] === '-p') && i + 1 < args.length) {
+            options.port = args[i + 1];
+            i++;
+        } else if ((args[i] === '--host' || args[i] === '-H') && i + 1 < args.length) {
+            options.host = args[i + 1];
+            i++;
+        } else if ((args[i] === '--user' || args[i] === '-u') && i + 1 < args.length) {
+            options.user = args[i + 1];
+            i++;
+        } else if (args[i] === '--ssl' || args[i] === '-S' || args[i] === '--tls') {
+            options.ssl = true;
+        } else if (args[i] === '--cert' && i + 1 < args.length) {
+            options.cert = args[i + 1];
+            i++;
+        } else if (args[i] === '--key' && i + 1 < args.length) {
+            options.key = args[i + 1];
+            i++;
+        } else if (args[i] === '--ca' && i + 1 < args.length) {
+            options.ca = args[i + 1];
+            i++;
+        } else if (args[i] === '--ca-key' && i + 1 < args.length) {
+            options.caKey = args[i + 1];
+            i++;
+        } else if (args[i] === '--debug') {
+            options.debug = true;
+        } else {
+            console.error(`Error: Unknown option "${args[i]}"`);
+            console.log('Use --help to see available options');
+            process.exit(1);
+        }
+    }
+
+    configure({
+        level: options.debug ? 'debug' : 'info',
+    });
+
+    const auth = {
+        type: options.user ? 'basic' : options.ssl ? 'x509' : 'none'
+    };
+
+    if (options.user) {
+        auth.user = { name: options.user, roles: ['admin'] };
+    }
+
+    if (options.ssl) {
+        auth.x509 = {
+            key: options.caKey || './gateway-ca.key',
+            // principalAltName: 'email',
+        };
+    }
+
+    const server = await GatewayServer.Factory({
+        port: options.port,
+        host: options.host,
+        ssl: options.ssl ? {
+            key: options.key,
+            cert: options.cert,
+            ca: options.ca,
+            requestCert: auth.type === 'x509',
+            rejectUnauthorized: false
+        } : undefined,
+        auth,
+        gateway: { route: '/gw', authorize: { access: auth.type !== 'none' ? 'authenticated' : 'permitted' } },
+        app: async (_configurer) => {
+            // No custom app logic for now
+        },
+    });
+
+    process.on('SIGINT', async () => {
+        await server.close();
+        process.exit(0);
+    });
+
+    process.title = `${GatewayServer.VERSION} ${server.address.port}`;
+}

package/gateway-server.d.ts

@@ -1,17 +1,75 @@
 import { IOGateway } from '@interopio/gateway';
+import type { AddressInfo } from 'node:net';
 import type { ServerCorsConfig, ServerConfigurer, ServerWebSocketOptions } from './types/web/server';
+
 export default GatewayServer.Factory;
 
 export namespace GatewayServer {
     export const Factory: (options: ServerConfig) => Promise<Server>
-    export type SslConfig = Readonly<{ key?: string, cert?: string, ca?: string }>
+    /**
+     * SSL/TLS configuration.
+     * All key and certificate files must be in PEM format.
+     */
+    export type SslConfig = Readonly<{
+        /** Path to server private key file (PEM format) */
+        key?: string,
+        /** Path to server certificate file (PEM format) */
+        cert?: string,
+        /** Path to CA certificate for client certificate verification (PEM format) */
+        ca?: string,
+        /**
+         *  Passphrase for encrypted private key
+         * @since 0.20.0
+         */
+        passphrase?: string,
+        /**
+         * Request client certificate during TLS handshake.
+         * When false (default), clients will not send certificates.
+         * When true, clients are asked to send a certificate.
+         * @since 0.20.0
+         */
+        requestCert?: boolean,
+        /**
+         * Reject clients with invalid or missing certificates.
+         * Only effective when requestCert is true.
+         * When false, clients without valid certs are still allowed.
+         * When true, enforces mutual TLS authentication.
+         * @since 0.20.0
+         */
+        rejectUnauthorized?: boolean
+    }>
 
     export import LoggerConfig = IOGateway.Logging.LogConfig;
+
     export type AuthConfig = Readonly<{
-        type: 'none' | 'basic' | 'oauth2',
-        basic?: { user?: {name: string, password?: string}, realm?: string }
-        oauth2?: { jwt: { issuerUri: string, issuer?: string, audience?: string | string[] } }
+        type: 'none'
+            | 'basic'
+            | 'x509' // since 0.20.0
+            | 'oauth2'
+        ,
+        /** X.509 client certificate authentication configuration
+         * @since 0.20.0
+         */
+        x509?: {
+            /** Path to CA private key file (PEM format), for generating client certificates and server certificates */
+            key?: string,
+            /** Passphrase for encrypted CA private key */
+            passphrase?: string,
+            /** Extract principal from Subject Alternative Name. Use 'email' to extract from email SAN. If undefined, uses subject (default). */
+            principalAltName?: 'email'
+        },
+        /** Basic authentication configuration */
+        basic?: {
+            realm?: string
+        },
+        /** OAuth2 authentication configuration */
+        oauth2?: {
+            jwt: { issuerUri: string, issuer?: string, audience?: string | string[] }
+        },
+        // in-memory user for basic auth
+        user?: { name: string, password?: string, readonly roles?: string[] }
     }>;
+
     export type ServerCustomizer = (configurer: ServerConfigurer, config: ServerConfig) => Promise<void>;
 
     export type ServerConfig = {
@@ -20,7 +78,7 @@ export namespace GatewayServer {
          * Accepts a single value or a range.
          * If a range is specified, will bind to the first available port in the range.
          *
-         * Default: 0 - a random port.
+         * @defaultValue 0 (random port)
          */
         port?: number | string
         /**
@@ -52,13 +110,54 @@ export namespace GatewayServer {
 
         app?: ServerCustomizer,
         gateway?: IOGateway.GatewayConfig & ServerWebSocketOptions & {
-            route?: string
+            route?: string,
+            /**
+             * Gateway scope - determines how gateway instances are managed:
+             * - 'principal': Each authenticated principal gets their own gateway instance.
+             *                A default (shared) gateway instance handles all unauthenticated connections.
+             * - 'singleton': All connections share the same gateway instance
+             *
+             * @defaultValue 'principal'
+             * @since 0.20.0
+             */
+            scope?: 'singleton' | 'principal',
         }
     }
 
     export interface Server {
-        readonly gateway: IOGateway.Gateway
+        readonly gateway: ScopedGateway
+        /**
+         * Returns the bound address info.
+         * Useful when the server is bound to a random port.
+         */
+        readonly address: AddressInfo | null
 
         close(): Promise<void>
     }
+
+    /**
+     * A scoped gateway that extends the base Gateway interface with methods
+     * to access and manage multiple gateway instances based on scope.
+     * @since 0.20.0
+     */
+    export interface ScopedGateway extends IOGateway.Gateway {
+
+        /**
+         * Get gateway info.
+         * @param gatewayId - The gateway ID. If omitted, returns aggregated info for all gateways.
+         */
+        info(gatewayId?: string): Record<string, unknown>
+
+        /**
+         * Stop a gateway instance.
+         * @param gatewayId - The gateway ID to stop. If omitted, stops all gateways.
+         */
+        stop(gatewayId?: string): Promise<IOGateway.Gateway>;
+
+        /**
+         * Get all managed gateway instances.
+         * @returns A map of gateway IDs to their corresponding Gateway instances
+         */
+        getGateways(): Map<string, IOGateway.Gateway>;
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@interopio/gateway-server",
-    "version": "0.19.3",
+    "version": "0.20.0",
     "keywords": [
         "gateway",
         "server",
@@ -48,6 +48,10 @@
             "types": "./types/web/test.d.ts",
             "import": "./dist/web/test.js"
         },
+        "./tools": {
+            "types": "./types/tools.d.ts",
+            "import": "./dist/tools/index.js"
+        },
         "./metrics/publisher/rest": {
             "import": "./dist/metrics/publisher/rest.js",
             "node": "./dist/metrics/publisher/rest.cjs",
@@ -68,20 +72,23 @@
             }
         }
     },
+    "bin": {
+        "gateway-server": "./gateway-server"
+    },
     "main": "dist/index.js",
     "types": "gateway-server.d.ts",
     "type": "module",
     "engines": {
-        "node": ">=20.10 || >= 22.12 || >= 24"
+        "node": ">=20.18 || >=22.12 || >=24"
     },
     "dependencies": {
-        "@interopio/gateway": "^0.22.3",
-        "ws": "^8.18.3",
+        "@interopio/gateway": "^0.23.0",
         "tough-cookie": "^6.0.0",
-        "http-cookie-agent": "^7.0.3"
+        "http-cookie-agent": "^7.0.3",
+        "ws": "^8.19.0"
     },
     "peerDependencies": {
-        "undici": "^7.16.0"
+        "undici": "^7.18.2"
     },
     "peerDependenciesMeta": {
         "undici": {