@interopio/gateway-server 0.19.4 → 0.21.0

package/gateway-server.d.ts

@@ -1,18 +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 = {
@@ -21,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,18 +109,65 @@ export namespace GatewayServer {
         },
 
         app?: ServerCustomizer,
+        resources?: {
+            enabled?: boolean,
+            locations: string[]
+        },
         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',
+            mesh?: IOGateway.MeshConfig & {
+                enabled?: boolean
+            }
+            metrics?: IOGateway.MetricsConfig & {
+                enabled?: boolean
+            }
         }
     }
 
     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.4",
+    "version": "0.21.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": {

package/readme.md

@@ -10,9 +10,13 @@ The `@interopio/gateway-server` package is the web server used to run the gatewa
 The server is general purpose http server with support for:
 - HTTP and HTTPS
 - CORS configuration
-- Basic and OAuth2 authentication
+- Basic, mTLS, and OAuth2 authentication
 - Custom API routes (both for HTTP and WebSocket)
 
+```shell
+npm install @interopio/gateway-server
+```
+
 ## Table of Contents
 
 - [Getting Started](#getting-started)
@@ -21,17 +25,22 @@ The server is general purpose http server with support for:
 
 ## Getting Started
 
+### CLI:
+```shell
+npx @interopio/gateway-server run --port 8385 --gateway
+```
+### API:
 ```typescript
-import GatewayServer, {type Server} from '@interopio/gateway-server';
+import GatewayServer, { type Server } from '@interopio/gateway-server';
 
 const server: Server = await GatewayServer({
     port: 8385,
     gateway: {
         route: '/gw',
-        access: 'authenticated',
+        authorize: { access: 'authenticated' },
         ping: {
             interval: 30000,  // 30 seconds
-            type: 'timestamp'
+            data: 'timestamp'
         }
     }
 });
@@ -44,28 +53,201 @@ await server.close();
 
 ## Configure HTTPS
 
+SSL/TLS configuration supports PEM-formatted certificates. Two modes are available:
+
+**1. Explicit certificates** - Provide your own key and certificate files (both must exist):
+```typescript
+const server = await GatewayServer({
+    port: 8443,
+    ssl: {
+        key: "./ssl/gateway-server.key",
+        cert: "./ssl/gateway-server.crt",
+        passphrase: "secret"             // optional, if key is encrypted
+    }
+});
+```
+
+> **Recommended for production:** Generate your own server certificates using a trusted CA or create your own CA infrastructure. See [Generating Server Certificates with OpenSSL](#generating-server-certificates-with-openssl) below.
+
+**2. Auto-generated server certificates** - Provide a CA key via `auth.x509.key` to auto-generate server certificates:
+
+> **⚠️ Development only:** Auto-generated certificates are intended for development and testing. For production environments, use explicit certificates (mode 1) with proper certificate management.
+
+> **Note:** The CA private key is stored under `auth.x509.key` since its primary purpose is generating client certificates for X.509 authentication. It is incidentally used to generate self-signed server certificates when no explicit server cert is provided and ssl is enabled.
+
+```typescript
+// Option A: Specify custom CA paths
+await GatewayServer({
+    port: 8443,
+    host: "example.com",                    // optional: used in generated certificate's CN and SAN
+    ssl: {
+        ca: "./ssl/gateway-ca.crt",        // CA certificate for client verification (optional)
+        key: "./ssl/gateway-server.key",    // optional: save generated server key to file
+        cert: "./ssl/gateway-server.crt",  // optional: save generated server cert to file
+        passphrase: undefined               // optional, if key is encrypted
+    },
+    auth: {
+        type: 'x509',
+        x509: {
+            key: "./ssl/gateway-ca.key",    // CA private key (auto-generates CA if missing)
+            passphrase: undefined,          // optional, if CA key is encrypted
+        }
+    }
+});
+
+// Option B: Use default development CA (simplest for development)
+await GatewayServer({
+    port: 8443,
+    ssl: {},
+    auth: {
+        type: 'x509',
+        x509: {
+            key: "./ssl/gateway-ca.key" // ca cert derives to ./ssl/gateway-ca.crt
+        }
+    }
+});
+
+// Option C: Minimal mode (uses gateway-ca.key and gateway-ca.crt)
+await GatewayServer({
+    port: 8443,
+    ssl: {},
+    auth: {
+        type: 'x509',
+        x509: {
+            key: undefined              // defaults to gateway-ca.key in current directory
+        }
+    }
+});
+```
+
+> **Client Configuration:** For mode 2, distribute the Root CA certificate (`.crt` file) to clients. Clients must import this CA into their trust store. Server certificates are regenerated on each startup (in memory or saved to disk if key/cert paths specified) and are automatically trusted by clients who trust the Root CA.
+>
+> **Auto-generation:** If CA files don't exist (specified in `auth.x509.key`), they are automatically generated and saved to disk. The CA certificate path is derived from the key path by replacing the extension with `.crt` (if not explicitly specified via `ssl.ca`). The CA is valid for 10 years and uses ECDSA secp384r1. Server certificates are regenerated on startup with 7-day validity.
+>
+> **Hostname in certificates:** When auto-generating server certificates (mode 2), the `host` parameter (if specified) is used as the Common Name (CN) and in the Subject Alternative Name (SAN) of the certificate. If `host` is not specified, defaults to `localhost`.
+>
+> **Note:** When both `ssl.key` and `ssl.crt` files exist, mode 1 is used (explicit certificates). Otherwise mode 2 is used (auto-generated from CA key in `auth.x509.key`). **For production deployments, always use mode 1 with properly managed certificates.**
+
+### Generating Server Certificates with OpenSSL
+
+To generate your own server certificates for mode 1 (explicit certificates) using OpenSSL:
+
+> **Production Best Practice:** Use this approach to create properly signed certificates for your production environment. Ensure certificates are renewed before expiration and follow your organization's certificate management policies.
+
+```shell
+# Set the domain name for the server certificate
+DOMAIN=gateway.localhost
+
+# Set paths to your CA certificate and key
+CA_CERT=./ssl/gateway-ca.crt
+CA_KEY=./ssl/gateway-ca.key
+
+# Generate server private key (ECDSA secp256r1)
+openssl ecparam -name prime256v1 -genkey -noout -out ./ssl/gateway-server.key
+
+# Create a certificate signing request (CSR) with extensions
+openssl req -new -key ./ssl/gateway-server.key -out ./ssl/gateway-server.csr \
+  -subj "/CN=${DOMAIN}" \
+  -addext "basicConstraints=CA:FALSE" \
+  -addext "keyUsage=critical,digitalSignature,keyEncipherment" \
+  -addext "extendedKeyUsage=serverAuth" \
+  -addext "subjectAltName=DNS:${DOMAIN},DNS:*.${DOMAIN}"
+
+# Sign the CSR with your Root CA
+openssl x509 -req -in ./ssl/gateway-server.csr \
+  -CA ${CA_CERT} -CAkey ${CA_KEY} \
+  -out ./ssl/gateway-server.crt -days 365 -sha256 \
+  -copy_extensions copyall
+```
+
+> **Important:** The `subjectAltName` with DNS entries is **required** for server certificates. Modern browsers and clients reject certificates without SAN, even if the Common Name (CN) matches the hostname.
+
+### Mutual TLS (Client Certificate Authentication)
+
+Enable client certificate verification for mutual TLS authentication:
+
+```typescript
+const server = await GatewayServer({
+    port: 8443,
+    ssl: {
+        key: "./ssl/gateway-server.key",    // Server private key
+        cert: "./ssl/gateway-server.crt",  // Server certificate
+        ca: "./ssl/gateway-client-ca.crt",  // CA that signed client certificates
+        requestCert: true,          // Ask clients to send certificates
+        rejectUnauthorized: true    // Reject clients without valid certs
+    }
+});
+```
+
+**Configuration options:**
+- `requestCert: false` (default) - Server does not request client certificates
+- `requestCert: true, rejectUnauthorized: false` - Client certs optional (allow anonymous)
+- `requestCert: true, rejectUnauthorized: true` - Client certs required (enforce mutual TLS)
+
+> **Note:** When `requestCert` is `false`, clients will not send certificates even if they have them. The server must explicitly request them during the TLS handshake.
+
+#### Generating Client Certificates with OpenSSL
+
+To generate client certificates for mutual TLS authentication using OpenSSL:
+
+```shell
+# Set paths to your CA certificate and key
+CA_CERT=./ssl/gateway-ca.crt
+CA_KEY=./ssl/gateway-ca.key
+
+# Generate client private key (ECDSA secp256r1)
+openssl ecparam -name prime256v1 -genkey -noout -out ./ssl/gateway-client.key
+
+# Create a certificate signing request (CSR) with extensions
+openssl req -new -key ./ssl/gateway-client.key -out ./ssl/gateway-client.csr \
+  -subj "/CN=dev-user" \
+  -addext "basicConstraints=CA:FALSE" \
+  -addext "keyUsage=critical,digitalSignature,keyEncipherment" \
+  -addext "extendedKeyUsage=clientAuth" \
+  -addext "subjectAltName=email:test@example.com"
+
+# Sign the CSR with your Root CA
+openssl x509 -req -in ./ssl/gateway-client.csr \
+  -CA ${CA_CERT} -CAkey ${CA_KEY} \
+  -out ./ssl/gateway-client.crt -days 365 -sha256 \
+  -copy_extensions copyall
+
+openssl pkcs12 -export -out ./ssl/gateway-client.p12 \
+  -inkey ./ssl/gateway-client.key -in ./ssl/gateway-client.crt \
+  -passout pass:changeit
+```
+
+> **Important:** The `extendedKeyUsage=clientAuth` is critical for client certificates. Without it, the certificate may be rejected during mutual TLS authentication.
+
+### Full Example with Authentication
+
 ```typescript
 import GatewayServer, {type Server} from '@interopio/gateway-server';
 
 const server: Server = await GatewayServer({
     port: 8443,
+    // Enable HTTPS with Development CA
     ssl: {
-        cert: "glue42.crt",
-        ca: "intermediate.crt",
-        key: "glue42.key"
+        ca: './ssl/gateway-ca.crt', // CA cert for client verification
+        rejectUnauthorized: false, // allow anonymous if no client cert
+        requestCert: true, // request client certificates for mutual TLS
     },
     auth: {
-        type: 'oauth2', // or 'basic'
+        type: 'oauth2', // or 'basic' or 'x509'
         oauth2: {
             jwt: {
-                issuer: 'https://auth.example.com',
-                audience: 'https://api.example.com'
+                issuerUri: 'https://auth.example.com',
+                audience: 'https://api.example.com',
+                principalClaimName: 'sub', // claim to use as principal
             }
         },
+        x509: {
+            principalAltName: 'email', // extract principal from certificate email SAN (default: uses subject)
+            key: './ssl/gateway-ca.key'  // CA key for generating certs
+        },
         basic: {
-            username: 'interopio',
-            password: 'passwordo'
-        }
+            realm: 'My Gateway'
+        },
     },
     app: async ({handle}) => {
         handle(

package/types/crypto/argon2.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Argon2 version 1.0 (0x10)
+ */
+export const ARGON2_VERSION_10: number;
+
+/**
+ * Argon2 version 1.3 (0x13) - current version
+ */
+export const ARGON2_VERSION_13: number;
+
+/**
+ * Current Argon2 version used by default
+ */
+export const ARGON2_VERSION: number;
+
+/**
+ * Default salt length in bytes (16)
+ */
+export const DEFAULT_SALT_LENGTH: number;
+
+/**
+ * Default hash length in bytes (32)
+ */
+export const DEFAULT_HASH_LENGTH: number;
+
+/**
+ * Default parallelism parameter (4)
+ */
+export const DEFAULT_PARALLELISM: number;
+
+/**
+ * Default memory cost in KiB (65536 = 64 MB)
+ */
+export const DEFAULT_MEMORY: number;
+
+/**
+ * Default number of iterations (3)
+ */
+export const DEFAULT_PASSES: number;
+
+/**
+ * Argon2 algorithm variants
+ */
+export type Argon2Algorithm = 'argon2d' | 'argon2i' | 'argon2id';
+
+/**
+ * Argon2 hash parameters
+ */
+export type Argon2HashParameters = {
+    memory: number;
+    passes: number;
+    parallelism: number;
+    nonce: Buffer;
+};
+
+/**
+ * Decoded Argon2 hash structure
+ */
+export type Argon2Hash = {
+    algorithm: Argon2Algorithm;
+    version: number;
+    parameters: Argon2HashParameters;
+    hash: Buffer;
+};
+
+/**
+ * Hash a password using Argon2.
+ *
+ * @param password - The plain text password to hash
+ * @param options - Optional parameters. If not provided, defaults will be used.
+ * @returns The encoded Argon2 hash string
+ */
+export function hash(
+    password: string,
+    options?: {
+        saltLength?: number;
+        hashLength?: number;
+        parallelism?: number;
+        memory?: number;
+        passes?: number;
+    }
+): Promise<string>;
+
+/**
+ * Verify a password against an Argon2 hash.
+ *
+ * @param encodedHash - The encoded Argon2 hash to verify against
+ * @param password - The plain text password to verify
+ * @returns true if password matches the hash, false otherwise
+ */
+export function verify(encodedHash: string, password: string): Promise<boolean>;
+
+/**
+ * Create an Argon2 hash from parameters.
+ * Low-level wrapper around node:crypto's argon2Sync.
+ *
+ * @param algorithm - Argon2 algorithm variant ('argon2d' | 'argon2i' | 'argon2id')
+ * @param password - The password to hash
+ * @param hashLength - Length of the output hash in bytes
+ * @param parameters - Argon2 parameters (nonce, memory, passes, parallelism). If not provided, defaults will be used.
+ * @returns The hash buffer
+ */
+export function createHash(
+    algorithm: Argon2Algorithm,
+    password: string,
+    hashLength: number,
+    parameters?: Argon2HashParameters
+): Promise<Buffer>;
+
+/**
+ * Decode an encoded Argon2 hash string into its components.
+ * Format: $argon2id$v=19$m=65536,t=3,p=4$base64salt$base64hash
+ *
+ * @param encodedHash - The encoded Argon2 hash string
+ * @returns Decoded hash components
+ */
+export function decode(encodedHash: string): Argon2Hash;
+
+/**
+ * Encode Argon2 hash components into a standard string format.
+ * Format: $argon2id$v=19$m=65536,t=3,p=4$base64salt$base64hash
+ *
+ * @param hashData - The hash components to encode
+ * @returns Encoded hash string
+ */
+export function encode(hashData: Argon2Hash): string;
+

package/types/crypto/keygen.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Create a random salt (nonce) for cryptographic operations.
+ *
+ * @param length - Length of the salt in bytes
+ * @returns Random salt buffer
+ */
+export function createSalt(length: number): Buffer;

package/types/crypto/mkcert.d.ts

@@ -0,0 +1,47 @@
+import type { RSAKey, KJUR } from 'jsrsasign';
+
+/**
+ * CA private key type - can be a PEM string or a jsrsasign key object
+ */
+type CAPrivateKey = string | RSAKey | KJUR.crypto.DSA | KJUR.crypto.ECDSA;
+
+/**
+ * Default Common Name for the root CA certificate.
+ */
+export const DEFAULT_CA_NAME: string;
+
+/**
+ * Generate a root Certificate Authority (CA) certificate.
+ *
+ * @param options - Options for generating the CA
+ * @param options.name - Common Name for the CA certificate (default: "io.Gateway Dev CA user@host")
+ * @param options.passphrase - Optional passphrase to protect the private key
+ * @returns Object containing the private key and certificate in PEM format
+ */
+export function generateRootCA(options?: { name?: string, passphrase?: string }): {
+    key: string;
+    cert: string;
+};
+
+
+/**
+ * Generate a certificate with custom SAN (Subject Alternative Name) entries.
+ *
+ * @param caKey - CA private key (PEM string or jsrsasign key object)
+ * @param issuer - Issuer DN string from CA certificate
+ * @param sanEntries - Array of SAN entries (e.g., "localhost", "IP:192.168.1.1", "EMAIL:user@example.com")
+ * @param isClient - Generate client certificate (clientAuth) vs server certificate (serverAuth) (default: false)
+ * @param validityDays - Certificate validity in days (default: 7)
+ * @returns Object containing the private key and certificate in PEM format
+ */
+export function generateCert(
+    caKey: CAPrivateKey,
+    issuer: string,
+    sanEntries: string[],
+    isClient?: boolean,
+    validityDays?: number
+): {
+    key: string;
+    cert: string;
+};
+

package/types/tools.d.ts

@@ -0,0 +1,6 @@
+
+export * as argon2 from './crypto/argon2';
+export * as keygen from './crypto/keygen';
+export * as mkcert from './crypto/mkcert';
+
+

package/types/web/server.d.ts

@@ -9,11 +9,12 @@ import type {
     ReadonlyHttpHeaders,
     ResponseCookie
 } from './http';
-import type {WebSocketHandler} from './socket';
-import type {Principal, AuthorizationRule} from '../auth';
-import {AsyncLocalStorage} from 'node:async_hooks';
-import type {AddressInfo} from 'node:net';
-import {IOGateway} from '@interopio/gateway';
+import type { WebSocketHandler } from './socket';
+import type { Principal, AuthorizationRule } from '../auth';
+import type { AsyncLocalStorage } from 'node:async_hooks';
+import type { X509Certificate } from 'node:crypto';
+import type { AddressInfo } from 'node:net';
+import { IOGateway } from '@interopio/gateway';
 
 export type OriginFilters = {
     non_matched?: IOGateway.Filtering.Action
@@ -91,6 +92,10 @@ export interface ServerWebExchangeBuilder<Request extends ServerHttpRequest = Se
     build(): ServerWebExchange<Request, Response>
 }
 
+/**
+ * SSL/TLS connection information
+ */
+export type SslInfo = { peerCertificate?: X509Certificate };
 
 export type ServerHttpRequest = HttpRequest<ReadonlyHttpHeaders> & HttpInputMessage<ReadonlyHttpHeaders> & {
     readonly id: string
@@ -108,6 +113,8 @@ export type ServerHttpRequest = HttpRequest<ReadonlyHttpHeaders> & HttpInputMess
 
     readonly upgrade: boolean
     readonly remoteAddress?: AddressInfo
+    /** SSL/TLS connection information (available for HTTPS requests) */
+    readonly sslInfo?: SslInfo
 }
 
 export interface ServerHttpResponse extends HttpResponse<MutableHttpHeaders>, HttpOutputMessage<MutableHttpHeaders> {