mTLS Setup

Overview

Standard TLS only proves the server's identity — the server itself accepts any client that knows the address and client ID. Mutual TLS (mTLS) closes that gap: the client also presents a certificate, so the server verifies who is connecting before accepting the connection. That matters on zero-trust networks and in regulated environments where "reaches the port" isn't an acceptable authorization model — the certificate becomes the credential.

The tls option with caCert, clientCert, and clientKey wires in three artifacts at client construction: the CA certificate (to verify the server, same as one-way TLS) plus the client's own certificate and private key (for the server to verify in return). Verification happens during the handshake, before any messaging traffic flows — a failed handshake surfaces as a ConnectionError.

Gotchas: the certificate and key must be a matched pair signed by a CA the server trusts — a mismatch fails the handshake outright; all three files must be valid, unexpired PEM, and expiry breaks connections with no warning; and the CA that signed the client cert isn't necessarily the CA that verifies the server — mixing them up causes "works with TLS, fails with mTLS" confusion.

Prerequisites

• KubeMQ server running with mTLS enabled
• Node.js SDK installed (npm install kubemq-js)
• TLS certificates (client certificate, client key, and CA certificate)

Code

/**
 * Example: Mutual TLS (mTLS) Setup
 *
 * Demonstrates connecting with mutual TLS where both the client and
 * server authenticate each other using certificates. This provides
 * the strongest transport-level security.
 *
 * Prerequisites:
 *   - KubeMQ server configured for mTLS
 *   - Client certificate, key, and CA certificate files available
 *
 * Run: npx tsx examples/configuration/mtls-setup.ts
 */
import { KubeMQClient, ConnectionError } from 'kubemq-js';

async function main(): Promise<void> {
  try {
    const client = await KubeMQClient.create({
      address: 'kubemq-server:50000',
      clientId: 'js-configuration-mtls-setup-client',
      tls: {
        enabled: true,
        caCert: '/path/to/ca-cert.pem',
        clientCert: '/path/to/client-cert.pem',
        clientKey: '/path/to/client-key.pem',
      },
    });

    console.log('Connected to KubeMQ with mutual TLS');
    console.log('Connection state:', client.state);

    await client.close();
  } catch (err) {
    if (err instanceof ConnectionError) {
      console.error('mTLS connection failed:', err.message);
      console.error('Verify that:');
      console.error('  1. CA cert matches the server certificate issuer');
      console.error('  2. Client cert and key are a matching pair');
      console.error('  3. Certificates have not expired');
    }
  }
}

main().catch(console.error);

How It Works

• The tls object with caCert, clientCert, and clientKey enables mutual TLS authentication.
• The server verifies the client's certificate, and the client verifies the server's certificate, establishing bidirectional trust.
• The error handler demonstrates key troubleshooting checks: CA chain validity, cert/key pairing, and expiration.
• This is the strongest transport-level security option, recommended for production environments.

Related

• Node.js SDK Reference
• TLS Setup