Add support for authenticating a user with an X.509 cert

* Rename `privateKey` -> `certKeyFile` and `certChain` -> `certFile`

.github/workflows/test_EE.yml

@@ -0,0 +1,54 @@
+name: "EE"
+
+on:
+  pull_request:
+  push:
+    branches:
+      - master
+  schedule:
+    - cron: "0 * * * 0" # Every day at 3am UTC.
+
+jobs:
+  tests:
+    name: "${{ matrix.group.name }}"
+    strategy:
+      fail-fast: false
+      matrix:
+        group:
+          - name: plugins
+            path: ./src/__test__/plugins
+    env:
+      # Github only passes secrets to the main repo, so we need to skip some things if they are unavailable
+      SECRETS_AVAILABLE: ${{ secrets.EVENTSTORE_CLOUD_ID != null }}
+      EVENTSTORE_VERSION: "24.2.0-jammy"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Connect to tailscale
+        if: ${{ matrix.group.tailscale && env.SECRETS_AVAILABLE == 'true' }}
+        run: |
+          curl -fsSL https://pkgs.tailscale.com/stable/ubuntu/eoan.gpg | sudo apt-key add -
+          curl -fsSL https://pkgs.tailscale.com/stable/ubuntu/eoan.list | sudo tee /etc/apt/sources.list.d/tailscale.list
+          sudo apt-get update
+          sudo apt-get install tailscale
+          sudo tailscale up --authkey ${{ secrets.TAILSCALE_AUTH }} --hostname "node-client-ci-${{ env.EVENTSTORE_VERSION }}-$(date +'%Y-%m-%d-%H-%M-%S')" --advertise-tags=tag:ci --accept-routes
+      - name: Setup Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: "14.x"
+      - name: Login to Cloudsmith
+        uses: docker/login-action@v3
+        with:
+          registry: docker.eventstore.com
+          username: ${{ secrets.CLOUDSMITH_CICD_USER }}
+          password: ${{ secrets.CLOUDSMITH_CICD_TOKEN }}
+      - name: Install
+        run: yarn
+      - name: Run Tests
+        run: yarn test ${{ matrix.group.path }} --ci --run-in-band --forceExit
+        env:
+          EVENTSTORE_IMAGE: eventstore-ee:${{ env.EVENTSTORE_VERSION }}
+          EVENTSTORE_CLOUD_ID: ${{ secrets.EVENTSTORE_CLOUD_ID }}
+      - name: Disconnect from tailscale
+        if: ${{ always() && matrix.group.tailscale && env.SECRETS_AVAILABLE == 'true' }}
+        run: sudo tailscale down

.gitignore

@@ -108,4 +108,6 @@ dist
 .npmrc
 package-lock.json
 
-src/__test__/utils/instances
+src/__test__/utils/instances
+
+.vscode

package.json

@@ -86,7 +86,7 @@
     "@typescript-eslint/eslint-plugin": "^5.62.0",
     "@typescript-eslint/parser": "^5.62.0",
     "cross-env": "^7.0.3",
-    "docker-compose": "^0.23.19",
+    "docker-compose": "^0.24.7",
     "dotenv": "^10.0.0",
     "eslint": "^7.32.0",
     "eslint-plugin-jsdoc": "^40.3.0",

samples/appending-events.ts

@@ -19,7 +19,7 @@ describe("[sample] appending-events", () => {
     await node.up();
     client = new EventStoreDBClient(
       { endpoint: node.uri },
-      { rootCertificate: node.rootCertificate },
+      { rootCertificate: node.certs.root },
       { username: "admin", password: "changeit" }
     );
   });

samples/persistent-subscriptions.ts

@@ -33,7 +33,7 @@ describe("[sample] persistent-subscriptions", () => {
 
     client = new EventStoreDBClient(
       { endpoint: node.uri },
-      { rootCertificate: node.rootCertificate },
+      { rootCertificate: node.certs.root },
       { username: "admin", password: "changeit" }
     );
 

samples/projection-management.ts

@@ -31,7 +31,7 @@ describe("[sample] projection-management", () => {
 
     client = new EventStoreDBClient(
       { endpoint: node.uri },
-      { rootCertificate: node.rootCertificate },
+      { rootCertificate: node.certs.root },
       { username: "admin", password: "changeit" }
     );
 

samples/reading-events.ts

@@ -26,7 +26,7 @@ describe("[sample] reading-events", () => {
     await node.up();
     client = new EventStoreDBClient(
       { endpoint: node.uri },
-      { rootCertificate: node.rootCertificate },
+      { rootCertificate: node.certs.root },
       { username: "admin", password: "changeit" }
     );
 

samples/server-side-filtering.ts

@@ -16,7 +16,7 @@ describe("[sample] server-side-filtering", () => {
     await node.up();
     client = new EventStoreDBClient(
       { endpoint: node.uri },
-      { rootCertificate: node.rootCertificate },
+      { rootCertificate: node.certs.root },
       { username: "admin", password: "changeit" }
     );
 

samples/subscribing-to-streams.ts

@@ -25,7 +25,7 @@ describe("[sample] server-side-filtering", () => {
     await node.up();
     client = new EventStoreDBClient(
       { endpoint: node.uri },
-      { rootCertificate: node.rootCertificate },
+      { rootCertificate: node.certs.root },
       { username: "admin", password: "changeit" }
     );
 

src/Client/index.ts

@@ -109,10 +109,25 @@ type ConnectionSettings =
   | SingleNodeOptions;
 
 export interface ChannelCredentialOptions {
+  /**
+   * Whether to use an insecure connection.
+   */
   insecure?: boolean;
+  /**
+   * The root certificate data.
+   */
   rootCertificate?: Buffer;
-  privateKey?: Buffer;
-  certChain?: Buffer;
+  /**
+   * The x.509 private key, if available.
+   */
+  certKeyFile?: Buffer;
+  /**
+   * The x.509 key chain, if available.
+   */
+  certFile?: Buffer;
+  /**
+   * Additional options to modify certificate verification.
+   */
   verifyOptions?: Parameters<typeof ChannelCredentials.createSsl>[3];
 }
 
@@ -186,6 +201,35 @@ export class Client {
       }
     }
 
+    if (options.certFile || options.certKeyFile) {
+      if (!options.certFile || !options.certKeyFile) {
+        throw new Error(
+          "Both certPath and certKeyPath must be provided together"
+        );
+      }
+
+      const certPathResolved = isAbsolute(options.certFile)
+        ? options.certFile
+        : resolve(process.cwd(), options.certFile);
+
+      const certKeyPathResolved = isAbsolute(options.certKeyFile)
+        ? options.certKeyFile
+        : resolve(process.cwd(), options.certKeyFile);
+
+      if (!existsSync(certPathResolved)) {
+        throw new Error("Failed to load certificate file. File was not found.");
+      }
+
+      if (!existsSync(certKeyPathResolved)) {
+        throw new Error(
+          "Failed to load certificate key file. File was not found."
+        );
+      }
+
+      channelCredentials.certKeyFile = readFileSync(certKeyPathResolved);
+      channelCredentials.certFile = readFileSync(certPathResolved);
+    }
+
     if (options.dnsDiscover) {
       const [discover] = options.hosts;
 
@@ -317,8 +361,8 @@ export class Client {
       );
       this.#channelCredentials = grpcCredentials.createSsl(
         channelCredentials.rootCertificate,
-        channelCredentials.privateKey,
-        channelCredentials.certChain,
+        channelCredentials.certKeyFile,
+        channelCredentials.certFile,
         channelCredentials.verifyOptions
       );
     }

src/Client/parseConnectionString.ts

@@ -3,6 +3,8 @@ import type { Credentials, EndPoint, NodePreference } from "../types";
 import { debug } from "../utils";
 
 export interface QueryOptions {
+  certFile?: string;
+  certKeyFile?: string;
   maxDiscoverAttempts?: number;
   connectionName?: string;
   defaultDeadline?: number;
@@ -54,6 +56,8 @@ const mapToNodePreference = caseMap<NodePreference>({
 });
 
 const mapToQueryOption = caseMap<keyof QueryOptions>({
+  certFile: "certFile",
+  certKeyFile: "certKeyFile",
   maxDiscoverAttempts: "maxDiscoverAttempts",
   connectionName: "connectionName",
   defaultDeadline: "defaultDeadline",
@@ -291,6 +295,12 @@ const verifyKeyValuePair = (
     case "tlsCAFile": {
       return { key, value: decodeURIComponent(value) };
     }
+    case "certFile": {
+      return { key, value: decodeURIComponent(value) };
+    }
+    case "certKeyFile": {
+      return { key, value: decodeURIComponent(value) };
+    }
     case "maxDiscoverAttempts":
     case "defaultDeadline":
     case "discoveryInterval":

src/__test__/connection/Channel.test.ts

@@ -18,7 +18,7 @@ describe("Channel", () => {
         endpoints: cluster.endpoints,
         nodePreference: "random",
       },
-      { rootCertificate: cluster.rootCertificate },
+      { rootCertificate: cluster.certs.root },
       { username: "admin", password: "changeit" }
     );
 

src/__test__/connection/cluster.test.ts

@@ -17,7 +17,7 @@ describe("cluster", () => {
   test("should successfully connect", async () => {
     const client = new EventStoreDBClient(
       { endpoints: cluster.endpoints },
-      { rootCertificate: cluster.rootCertificate },
+      { rootCertificate: cluster.certs.root },
       { username: "admin", password: "changeit" }
     );
 
@@ -42,7 +42,7 @@ describe("cluster", () => {
         ],
         maxDiscoverAttempts,
       },
-      { rootCertificate: cluster.rootCertificate }
+      { rootCertificate: cluster.certs.root }
     );
 
     await expect(

src/__test__/connection/connectionString/secure-cluster.test.ts

@@ -7,6 +7,6 @@ connectionStringTests({
   createServer: createTestCluster,
   createUri: ({ endpoints }) =>
     endpoints.map(({ address, port }) => `${address}:${port}`).join(","),
-  createQueryString: ({ certPath }) => `tlsCAFile=${certPath}`,
+  createQueryString: ({ certPath }) => `tlsCAFile=${certPath.root}`,
   streamPrefix: "secure-cluster",
 });

src/__test__/connection/connectionString/secure-single-node.test.ts

@@ -6,6 +6,6 @@ connectionStringTests({
   title: "Secure Single Node",
   createServer: createTestNode,
   createUri: ({ uri }) => uri,
-  createQueryString: ({ certPath }) => `tlsCAFile=${certPath}`,
+  createQueryString: ({ certPath }) => `tlsCAFile=${certPath.root}`,
   streamPrefix: "secure-single-node",
 });

src/__test__/connection/deadline/deadline-effects.test.ts

@@ -22,7 +22,7 @@ describe("deadline", () => {
         () =>
           new EventStoreDBClient(
             { endpoints: cluster.endpoints, defaultDeadline: 1 },
-            { rootCertificate: cluster.rootCertificate },
+            { rootCertificate: cluster.certs.root },
             { username: "admin", password: "changeit" }
           ).listProjections(),
       ],
@@ -31,7 +31,7 @@ describe("deadline", () => {
         () =>
           new EventStoreDBClient(
             { endpoints: cluster.endpoints },
-            { rootCertificate: cluster.rootCertificate },
+            { rootCertificate: cluster.certs.root },
             { username: "admin", password: "changeit" }
           ).listProjections({
             deadline: 1,
@@ -42,7 +42,7 @@ describe("deadline", () => {
         () =>
           new EventStoreDBClient(
             { endpoints: cluster.endpoints, defaultDeadline: 200_000 },
-            { rootCertificate: cluster.rootCertificate },
+            { rootCertificate: cluster.certs.root },
             { username: "admin", password: "changeit" }
           ).listProjections({
             deadline: 1,
@@ -53,7 +53,7 @@ describe("deadline", () => {
         () =>
           new EventStoreDBClient(
             { endpoints: cluster.endpoints, defaultDeadline: 200_000 },
-            { rootCertificate: cluster.rootCertificate },
+            { rootCertificate: cluster.certs.root },
             { username: "admin", password: "changeit" }
           ).appendToStream("deadline", jsonTestEvents(), {
             deadline: 1,

src/__test__/connection/defaultCredentials.test.ts

@@ -16,7 +16,7 @@ describe("defaultCredentials", () => {
     test("bad override", async () => {
       const client = new EventStoreDBClient(
         { endpoint: node.uri },
-        { rootCertificate: node.rootCertificate },
+        { rootCertificate: node.certs.root },
         { username: "admin", password: "changeit" }
       );
       await expect(
@@ -35,7 +35,7 @@ describe("defaultCredentials", () => {
     test("good override", async () => {
       const client = new EventStoreDBClient(
         { endpoint: node.uri },
-        { rootCertificate: node.rootCertificate },
+        { rootCertificate: node.certs.root },
         { username: "AzureDiamond", password: "hunter2" }
       );
       await expect(

src/__test__/connection/not-leader.test.ts

@@ -28,7 +28,7 @@ describe("not-leader", () => {
         endpoints: cluster.endpoints,
         nodePreference: FOLLOWER,
       },
-      { rootCertificate: cluster.rootCertificate },
+      { rootCertificate: cluster.certs.root },
       { username: "admin", password: "changeit" }
     );
 
@@ -66,7 +66,7 @@ describe("not-leader", () => {
           {
             endpoint: error.leader,
           },
-          { rootCertificate: cluster.rootCertificate },
+          { rootCertificate: cluster.certs.root },
           { username: "admin", password: "changeit" }
         );
 

src/__test__/connection/parseConnectionStringMockups.ts

@@ -468,6 +468,20 @@ export const valid: Array<
       ],
     },
   ],
+  [
+    "esdb://host?certFile=/home/user/dev/cert.ca&certKeyFile=/home/user/dev/cert.key",
+    {
+      dnsDiscover: false,
+      certFile: "/home/user/dev/cert.ca",
+      certKeyFile: "/home/user/dev/cert.key",
+      hosts: [
+        {
+          address: "host",
+          port: 2113,
+        },
+      ],
+    },
+  ],
 ];
 
 export const invalid: string[] = [

src/__test__/connection/reconnect/NotLeaderError.test.ts

@@ -24,7 +24,7 @@ describe("reconnect", () => {
         // so it's better not to have deadlines here to force the errors we are testing.
         defaultDeadline: Infinity,
       },
-      { rootCertificate: cluster.rootCertificate },
+      { rootCertificate: cluster.certs.root },
       { username: "admin", password: "changeit" }
     );
 

src/__test__/connection/reconnect/UnavailableError.test.ts

@@ -27,7 +27,7 @@ describe("reconnect", () => {
         // so it's better not to have deadlines here to force the errors we are testing.
         defaultDeadline: Infinity,
       },
-      { rootCertificate: cluster.rootCertificate },
+      { rootCertificate: cluster.certs.root },
       { username: "admin", password: "changeit" }
     );
 

src/__test__/connection/reconnect/all-nodes-down.test.ts

@@ -26,7 +26,7 @@ describe("reconnect", () => {
         // so it's better not to have deadlines here to force the errors we are testing.
         defaultDeadline: Infinity,
       },
-      { rootCertificate: cluster.rootCertificate },
+      { rootCertificate: cluster.certs.root },
       { username: "admin", password: "changeit" }
     );
   });