feat: add mTLS client certificate support

Author: phillipleblanc

package-lock.json

@@ -423,6 +423,9 @@ export class SpiceClient {
   private _httpUrl: string;
   private _userAgent: string;
   private _flightTlsEnabled: boolean = true;
+  private _tlsClientCertFile?: string;
+  private _tlsClientKeyFile?: string;
+  private _tlsRootCertFile?: string;
   private _maxRetries: number;
   private _customHeaders?: { [key: string]: string };
   private _platform: PlatformAdapter;
@@ -466,6 +469,9 @@ export class SpiceClient {
         flightOnly,
         httpOnly,
         logging,
+        tlsClientCertFile,
+        tlsClientKeyFile,
+        tlsRootCertFile,
       } = params;
 
       // Initialize logger (default: enabled)
@@ -507,6 +513,9 @@ export class SpiceClient {
         ? `${userAgent} ${platform.getUserAgent()}`
         : platform.getUserAgent();
       this._customHeaders = customHeaders;
+      this._tlsClientCertFile = tlsClientCertFile;
+      this._tlsClientKeyFile = tlsClientKeyFile;
+      this._tlsRootCertFile = tlsRootCertFile;
     }
 
     // Determine if this is Spice Cloud endpoint (compute once)
@@ -526,6 +535,9 @@ export class SpiceClient {
         this._userAgent,
         this._flightTlsEnabled,
         this._logger,
+        this._tlsClientCertFile,
+        this._tlsClientKeyFile,
+        this._tlsRootCertFile,
       );
     }
 

src/client-common.ts

@@ -168,6 +168,7 @@ class SpiceClient {
   private _useGrpc: boolean = grpcAvailable;
   private _initPromise: Promise<void>;
   private _customHeaders?: { [key: string]: string };
+  private _httpsAgent: https.Agent;
 
   public constructor(params: string | SpiceClientConfig = {}) {
     // support legacy constructor with api_key as first agument
@@ -176,6 +177,7 @@ class SpiceClient {
       this._httpUrl = 'https://data.spiceai.io';
       this._flightUrl = 'flight.spiceai.io:443';
       this._userAgent = getUserAgent();
+      this._httpsAgent = new https.Agent({ keepAlive: true });
     } else {
       const {
         apiKey,
@@ -184,6 +186,9 @@ class SpiceClient {
         flightTlsEnabled,
         userAgent,
         customHeaders,
+        tlsClientCertFile,
+        tlsClientKeyFile,
+        tlsRootCertFile,
       } = params;
 
       this._apiKey = apiKey;
@@ -204,6 +209,30 @@ class SpiceClient {
         ? `${userAgent} ${getUserAgent()}`
         : getUserAgent();
       this._customHeaders = customHeaders;
+
+      // Validate that client cert and key are either both set or both unset
+      if (
+        (tlsClientCertFile && !tlsClientKeyFile) ||
+        (!tlsClientCertFile && tlsClientKeyFile)
+      ) {
+        const missing = tlsClientCertFile
+          ? 'tlsClientKeyFile'
+          : 'tlsClientCertFile';
+        throw new Error(
+          `Both tlsClientCertFile and tlsClientKeyFile must be provided together for mTLS. ${missing} is missing.`,
+        );
+      }
+
+      // Build per-instance HTTPS agent with optional mTLS certs
+      const agentOpts: https.AgentOptions = { keepAlive: true };
+      if (tlsRootCertFile) {
+        agentOpts.ca = fs.readFileSync(tlsRootCertFile);
+      }
+      if (tlsClientCertFile && tlsClientKeyFile) {
+        agentOpts.cert = fs.readFileSync(tlsClientCertFile);
+        agentOpts.key = fs.readFileSync(tlsClientKeyFile);
+      }
+      this._httpsAgent = new https.Agent(agentOpts);
     }
 
     // Initialize gRPC during construction
@@ -822,7 +851,7 @@ class SpiceClient {
     };
 
     if (this._httpUrl.startsWith('https://')) {
-      fetchOptions.agent = httpsAgent;
+      fetchOptions.agent = this._httpsAgent;
     }
 
     return fetch(url, fetchOptions);

src/client.ts

@@ -140,19 +140,29 @@ export class GrpcFlightClient {
   private initPromise: Promise<void>;
   private useGrpc: boolean = grpcAvailable;
   private logger: Logger;
+  private tlsClientCertFile?: string;
+  private tlsClientKeyFile?: string;
+
+  private tlsRootCertFile?: string;
 
   constructor(
     apiKey: string | undefined,
     flightUrl: string,
     userAgent: string,
     flightTlsEnabled: boolean,
     logger?: Logger,
+    tlsClientCertFile?: string,
+    tlsClientKeyFile?: string,
+    tlsRootCertFile?: string,
   ) {
     this.apiKey = apiKey;
     this.flightUrl = flightUrl;
     this.userAgent = userAgent;
     this.flightTlsEnabled = flightTlsEnabled;
     this.logger = logger || new Logger(true);
+    this.tlsClientCertFile = tlsClientCertFile;
+    this.tlsClientKeyFile = tlsClientKeyFile;
+    this.tlsRootCertFile = tlsRootCertFile;
     this.initPromise = this.initialize();
   }
 
@@ -219,7 +229,10 @@ export class GrpcFlightClient {
       );
     }
 
-    const creds = grpc.credentials.createSsl();
+    const rootCerts = this.tlsRootCertFile ? fs.readFileSync(this.tlsRootCertFile) : null;
+    const clientCert = this.tlsClientCertFile ? fs.readFileSync(this.tlsClientCertFile) : null;
+    const clientKey = this.tlsClientKeyFile ? fs.readFileSync(this.tlsClientKeyFile) : null;
+    const creds = grpc.credentials.createSsl(rootCerts, clientKey, clientCert);
     const metaCallback = (_params: any, callback: any) => {
       callback(null, meta);
     };

src/grpc/client.node.ts

@@ -23,6 +23,21 @@ export interface SpiceClientConfig {
    * @default true
    */
   logging?: boolean;
+  /**
+   * Path to a PEM-encoded CA certificate file for server verification.
+   * When set, this CA is used instead of the system certificate store.
+   */
+  tlsRootCertFile?: string;
+  /**
+   * Path to a PEM-encoded client certificate file for mTLS.
+   * Must be used together with `tlsClientKeyFile`.
+   */
+  tlsClientCertFile?: string;
+  /**
+   * Path to a PEM-encoded client private key file for mTLS.
+   * Must be used together with `tlsClientCertFile`.
+   */
+  tlsClientKeyFile?: string;
 }
 
 export interface SchemaField {