@interopio/gateway-server 0.20.0 → 0.21.0

package/gateway-server

@@ -3,6 +3,7 @@
 `use strict`;
 
 import { writeFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
 import { configure } from '@interopio/gateway/logging/core';
 
 // import { GatewayServer } from './src/index.ts';
@@ -13,48 +14,61 @@ import { mkcert, argon2 } from './dist/tools/index.js';
 
 function showHelp() {
     console.log(`
-Usage: gateway-server <command> [options]
+Usage: npx @interopio/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                      Start the gateway server
+  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)
+  -p, --port <port>        Specify port or port range to bind the server to (default: 0 i.e. random)
+                           examples: 8385, 8000-8100, 3000,4000-4050
+  -H, --host <host>        Network address to bind to (default: unspecified, listens on all)
+                           examples: localhost, 127.0.0.1, 0.0.0.0, ::1
+  -u, --user <name>        Enables basic authentication and sets the admin username
+  --no-auth                Disable authentication (overrides config, sets auth.type to 'none')
+  -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)
+  --no-ssl, --no-tls       Disable SSL/TLS (overrides config)
+  -g, --gateway            Enable gateway endpoint (default route: /)
+  --no-gateway             Disable gateway endpoint (overrides config)
+  -s, --static <location>  Serve static files from specified location (e.g., ./public)
+  -c, --config <file>      Server configuration file (JSON format)
+  --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" | ...)
+  (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)
+  --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
+  -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 run -p 8443 --ssl --user admin --gateway
+  gateway-server run --port 42443 --tls --ca-key ./ssl/ca.key --host medes --gateway
+  gateway-server run -p 3000 --static ./public --config ./server-config.json
+  gateway-server run --config ./server-config.json --no-gateway --no-ssl --no-auth
   gateway-server passwd
   echo "mySecret123" | gateway-server passwd --stdin
   gateway-server mkcert
@@ -70,37 +84,44 @@ function showVersion() {
     process.exit(0);
 }
 
-
 // Parse command-line arguments
-const args = process.argv.slice(2);
+const { values: globalValues, positionals } = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+        version: { type: 'boolean', short: 'v' },
+        help: { type: 'boolean', short: 'h' },
+    },
+    strict: false,
+    allowPositionals: true,
+});
 
 // Check for global flags first
-if (args.includes('--version') || args.includes('-v')) {
+if (globalValues.version) {
     showVersion();
 }
-if (args.includes('--help') || args.includes('-h')) {
+if (globalValues.help) {
     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);
+// Determine command (required)
+if (positionals.length === 0) {
+    console.error('Error: Command is required');
+    console.log('Use --help to see available commands');
+    process.exit(1);
 }
 
+const command = positionals[0];
+
 // Route to appropriate command handler
 switch (command) {
     case 'run':
-        await runServer(commandArgs);
+        await runServer();
         break;
     case 'passwd':
-        await passwdCommand(commandArgs);
+        await passwdCommand();
         break;
     case 'mkcert':
-        await mkcertCommand(commandArgs);
+        await mkcertCommand();
         break;
     default:
         console.error(`Error: Unknown command "${command}"`);
@@ -109,23 +130,20 @@ switch (command) {
 }
 
 // Command: passwd - Generate password hash
-async function passwdCommand(args) {
-    let password = undefined;
-    let fromStdin = false;
+async function passwdCommand() {
+    const { values } = parseArgs({
+        args: process.argv.slice(3), // Skip 'node', 'gateway-server', and 'passwd'
+        options: {
+            stdin: { type: 'boolean' },
+        },
+        strict: true,
+        allowPositionals: 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);
-        }
-    }
+    let password = undefined;
 
     // Read password from stdin if specified
-    if (fromStdin) {
+    if (values.stdin) {
         password = await readPasswordFromStdin();
     }
 
@@ -220,42 +238,28 @@ async function promptPassword(prompt) {
 }
 
 // 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);
-        }
-    }
+async function mkcertCommand() {
+    const { values, positionals } = parseArgs({
+        args: process.argv.slice(3), // Skip 'node', 'gateway-server', and 'mkcert'
+        options: {
+            client: { type: 'boolean' },
+            user: { type: 'string', short: 'u' },
+            ca: { type: 'string' },
+            'ca-key': { type: 'string' },
+            key: { type: 'string' },
+            cert: { type: 'string' },
+        },
+        strict: true,
+        allowPositionals: true,
+    });
+
+    const isClientCert = values.client || false;
+    const user = values.user || 'dev-user';
+    const caCert = values.ca || './gateway-ca.crt';
+    const caKey = values['ca-key'] || './gateway-ca.key';
+    let keyPath = values.key;
+    let certPath = values.cert;
+    const sanEntries = positionals;
 
     // Default output paths
     // Users typically specify just --cert, and key should go in the same file
@@ -351,83 +355,209 @@ async function mkcertCommand(args) {
 }
 
 // Command: run - Start the server
-async function runServer(args) {
+async function runServer() {
+    const { values } = parseArgs({
+        args: process.argv.slice(3), // Skip 'node', 'gateway-server', and 'run'
+        options: {
+            port: { type: 'string', short: 'p' },
+            host: { type: 'string', short: 'H' },
+            user: { type: 'string', short: 'u' },
+            debug: { type: 'boolean' },
+            ssl: { type: 'boolean', short: 'S' },
+            tls: { type: 'boolean' },
+            cert: { type: 'string' },
+            key: { type: 'string' },
+            ca: { type: 'string' },
+            'ca-key': { type: 'string' },
+            config: { type: 'string', short: 'c' },
+            gateway: { type: 'boolean', short: 'g' },
+            static: { type: 'string', short: 's', multiple: true },
+            auth: { type: 'boolean' }
+        },
+        strict: true,
+        allowNegative: true,
+        allowPositionals: false,
+    });
+
     const options = {
-        port: 0,
-        host: undefined,
-        user: undefined,
-        debug: false,
-        ssl: false,
-        cert: undefined,
-        key: undefined,
-        ca: undefined,
-        caKey: undefined
+        port: values.port,
+        host: values.host,
+        user: values.user,
+        debug: values.debug || false,
+        ssl: values.ssl || values.tls || false,
+        noSsl: values.ssl === false, // --no-ssl explicitly set
+        cert: values.cert,
+        key: values.key,
+        ca: values.ca,
+        caKey: values['ca-key'],
+        config: values.config,
+        gateway: values.gateway,
+        noGateway: values.gateway === false, // --no-gateway explicitly set
+        static: values.static,
     };
 
-    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');
+    configure({
+        level: options.debug ? 'debug' : 'info',
+    });
+
+    // Load server configuration from file if specified
+    let serverConfig = {};
+    if (options.config) {
+        try {
+            const { readFileSync } = await import('node:fs');
+            const configContent = readFileSync(options.config, 'utf8');
+            serverConfig = JSON.parse(configContent);
+        } catch (error) {
+            console.error(`Error: Cannot read server config from ${options.config}`);
+            console.error(error.message);
             process.exit(1);
         }
     }
 
-    configure({
-        level: options.debug ? 'debug' : 'info',
-    });
+    // Apply CLI overrides to server config
+    // CLI arguments take precedence over config file
 
-    const auth = {
-        type: options.user ? 'basic' : options.ssl ? 'x509' : 'none'
-    };
+    // Override port if specified
+    if (values.port !== undefined) {
+        serverConfig.port = options.port;
+    }
+
+    // Override host if specified
+    if (values.host !== undefined) {
+        serverConfig.host = options.host;
+    }
 
-    if (options.user) {
-        auth.user = { name: options.user, roles: ['admin'] };
+    // Override SSL configuration
+    if (options.noSsl) {
+        // --no-ssl: delete SSL config completely
+        delete serverConfig.ssl;
+        options.ssl = false;
+    } else if (options.ssl) {
+        // --ssl specified: merge CLI args with existing config
+        if (!serverConfig.ssl) {
+            serverConfig.ssl = {};
+        }
+        // Only set properties if CLI options are explicitly provided
+        if (options.key !== undefined) {
+            serverConfig.ssl.key = options.key;
+        }
+        if (options.cert !== undefined) {
+            serverConfig.ssl.cert = options.cert;
+        }
+        if (options.ca !== undefined) {
+            serverConfig.ssl.ca = options.ca;
+        }
     }
+    // else: use whatever is in serverConfig (if any)
+
+    // Determine effective SSL state
+    const effectiveSsl = options.ssl || (!options.noSsl && serverConfig.ssl !== undefined);
 
-    if (options.ssl) {
-        auth.x509 = {
-            key: options.caKey || './gateway-ca.key',
-            // principalAltName: 'email',
+    // Configure authentication
+    let auth;
+    if (values.auth === false) {
+        // --no-auth: delete auth config from server config and set to 'none'
+        delete serverConfig.auth;
+        auth = { type: 'none' };
+    }
+    else if (serverConfig.auth) {
+        // Use auth from config file if present
+        auth = serverConfig.auth;
+
+        // Allow --user CLI option to override auth.user.name from config
+        if (options.user) {
+            if (!auth.user) {
+                auth.user = {};
+            }
+            auth.user.name = options.user;
+        }
+    }
+    else {
+        // No auth in config file, determine from CLI args or defaults
+        auth = {
+            type: options.user ? 'basic' : effectiveSsl ? 'x509' : 'none'
         };
+
+        if (options.user) {
+            auth.user = { name: options.user };
+        }
+
+        if (effectiveSsl && auth.type === 'x509') {
+            auth.x509 = {
+                key: options.caKey || './gateway-ca.key',
+                // principalAltName: 'email',
+            };
+
+            // Ensure SSL config exists and has proper mutual TLS settings
+            if (!serverConfig.ssl) {
+                serverConfig.ssl = {};
+            }
+
+            // Enable client certificate verification with proper mutual TLS
+            serverConfig.ssl.requestCert = true;
+
+            // Enforce trust verification to prevent certificate spoofing
+            // rejectUnauthorized must be true to ensure only trusted client certs are accepted
+            serverConfig.ssl.rejectUnauthorized = true;
+
+            // Set CA for client certificate verification (required for mutual TLS)
+            // Use the same CA that signs client certificates
+            if (!serverConfig.ssl.ca) {
+                serverConfig.ssl.ca = options.ca || './gateway-ca.crt';
+            }
+        }
+    }
+
+    // Handle SSL certificate auto-generation when --ssl is specified via CLI
+    // but config file doesn't have server certificates
+    if (options.ssl && effectiveSsl && serverConfig.ssl) {
+        const hasCert = serverConfig.ssl.cert || serverConfig.ssl.key;
+        if (!hasCert) {
+            // SSL enabled but no server cert/key provided
+            // We need a CA key for auto-generating server certificates
+            // Set default CA key path if not already configured
+            if (!auth.x509) {
+                auth.x509 = {};
+            }
+            if (!auth.x509.key) {
+                // Use CLI option, or default to ./gateway-ca.key
+                auth.x509.key = options.caKey || './gateway-ca.key';
+            }
+        }
+    }
+
+    // Override gateway configuration
+    if (options.noGateway) {
+        // --no-gateway: delete gateway config completely
+        delete serverConfig.gateway;
+    } else if (options.gateway) {
+        // --gateway specified: enable gateway endpoint, respect existing config
+        if (!serverConfig.gateway) {
+            serverConfig.gateway = {};
+        }
+        // Set defaults only if not already present in config
+        if (!serverConfig.gateway.route) {
+            serverConfig.gateway.route = '/';
+        }
+        if (!serverConfig.gateway.authorize) {
+            serverConfig.gateway.authorize = { access: auth.type !== 'none' ? 'authenticated' : 'permitted' };
+        }
     }
+    // else: use whatever is in serverConfig (if any)
+
+    // Override static resources if specified
+    if (options.static && options.static.length > 0) {
+        if (!serverConfig.resources) {
+            serverConfig.resources = {};
+        }
+        serverConfig.resources.locations = options.static;
+    }
+
+    // Set auth in server config
+    serverConfig.auth = auth;
 
     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' } },
+        ...(serverConfig),
         app: async (_configurer) => {
             // No custom app logic for now
         },
@@ -438,5 +568,5 @@ async function runServer(args) {
         process.exit(0);
     });
 
-    process.title = `${GatewayServer.VERSION} ${server.address.port}`;
+    // process.title = `${GatewayServer.VERSION} ${server.address.port}`;
 }

package/gateway-server.d.ts

@@ -109,6 +109,10 @@ export namespace GatewayServer {
         },
 
         app?: ServerCustomizer,
+        resources?: {
+            enabled?: boolean,
+            locations: string[]
+        },
         gateway?: IOGateway.GatewayConfig & ServerWebSocketOptions & {
             route?: string,
             /**
@@ -121,6 +125,12 @@ export namespace GatewayServer {
              * @since 0.20.0
              */
             scope?: 'singleton' | 'principal',
+            mesh?: IOGateway.MeshConfig & {
+                enabled?: boolean
+            }
+            metrics?: IOGateway.MetricsConfig & {
+                enabled?: boolean
+            }
         }
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@interopio/gateway-server",
-    "version": "0.20.0",
+    "version": "0.21.0",
     "keywords": [
         "gateway",
         "server",

package/readme.md

@@ -25,6 +25,11 @@ npm install @interopio/gateway-server
 
 ## Getting Started
 
+### CLI:
+```shell
+npx @interopio/gateway-server run --port 8385 --gateway
+```
+### API:
 ```typescript
 import GatewayServer, { type Server } from '@interopio/gateway-server';
 

package/types/web/test.d.ts

@@ -1,4 +1,6 @@
-import {GatewayServer} from '../../gateway-server';
+import type { Middleware, SslInfo } from './server';
+import { GatewayServer } from '../../gateway-server';
+
 
 export interface TestClient {
     readonly fetch: (input: string | URL, init?: RequestInit) => Promise<Response>;
@@ -10,6 +12,8 @@ export interface TestClientBuilder {
 }
 
 export interface MockServerSpec {
+    middleware(...middleware: Middleware): this;
+    sslInfo(sslInfo?: SslInfo): this;
     configureClient(): TestClientBuilder;
     build(): Promise<TestClient>;
 }