@interopio/gateway-server 0.19.4 → 0.20.0

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)
@@ -22,16 +26,16 @@ The server is general purpose http server with support for:
 ## Getting Started
 
 ```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 +48,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> {