feat: ability to use user-supplied auth

Author: pozil

README.md

@@ -8,17 +8,41 @@ See the [official Pub/Sub API repo](https://github.com/developerforce/pub-sub-ap
 
 Install the client library with `npm install salesforce-pubsub-api-client`.
 
-Create a `.env` file at the root of the project for configuration. You may use either of these authentication flows:
+Create a `.env` file at the root of the project for configuration.
 
--   Username/password authentication
+Pick one of these authentication flows and fill the relevant configuration:
+
+-   User supplied authentication
+-   Username/password authentication (recommended for tests)
 -   OAuth 2.0 client credentials
--   OAuth 2.0 JWT Bearer
+-   OAuth 2.0 JWT Bearer (recommended for production)
 
-> **Warning**<br/>
-> Relying on a username/password authentication flow for production is not recommended. Consider switching to JWT auth or similar for extra security.
+### User supplied authentication
+
+If you already have a Salesforce client in your app, you can reuse its authentication information. You'll only need this minimalistic configuration:
+
+```properties
+SALESFORCE_AUTH_TYPE=user-supplied
+
+PUB_SUB_ENDPOINT=api.pubsub.salesforce.com:7443
+```
+
+When connecting to the Pub/Sub API, use the following method instead of the standard `connect()` method:
+
+```js
+await client.connectWithAuth(
+    accessToken,
+    instanceUrl,
+    organizationId,
+    username
+);
+```
 
 ### Username/password flow
 
+> **Warning**<br/>
+> Relying on a username/password authentication flow for production is not recommended. Consider switching to JWT auth for extra security.
+
 ```properties
 SALESFORCE_AUTH_TYPE=username-password
 SALESFORCE_LOGIN_URL=https://login.salesforce.com
@@ -40,7 +64,9 @@ SALESFORCE_CLIENT_SECRET=YOUR_CONNECTED_APP_CLIENT_SECRET
 PUB_SUB_ENDPOINT=api.pubsub.salesforce.com:7443
 ```
 
-### OAuth 2.0 JWT Bearer Flow
+### OAuth 2.0 JWT bearer flow
+
+This is the most secure authentication option. Recommended for production use.
 
 ```properties
 SALESFORCE_AUTH_TYPE=oauth-jwt-bearer
@@ -56,7 +82,7 @@ PUB_SUB_ENDPOINT=api.pubsub.salesforce.com:7443
 
 Here's an example that will get you started quickly. It listens to a single account change event.
 
-1. Activate account change events in **Salesforce Setup > Change Data Capture**.
+1. Activate Account change events in **Salesforce Setup > Change Data Capture**.
 
 1. Create a `sample.js` file with this content:
 

src/auth.js

@@ -109,7 +109,7 @@ export default class SalesforceAuth {
             );
         }
         const { access_token, instance_url } = await loginResponse.json();
-        // Get user info
+        // Get org and user info
         const userInfoResponse = await fetch(
             `${Configuration.getSfLoginUrl()}/services/oauth2/userinfo`,
             {

src/client.js

@@ -54,10 +54,16 @@ export default class PubSubApiClient {
     }
 
     /**
-     * Connects to the Pub/Sub API
+     * Authenticates with Salesforce then, connects to the Pub/Sub API
      * @returns {Promise<void>} Promise that resolves once the connection is established
      */
     async connect() {
+        if (Configuration.isUserSuppliedAuth()) {
+            throw new Error(
+                'You selected user-supplied authentication mode so you cannot use the "connect()" method. Use "connectWithAuth(...)" instead.'
+            );
+        }
+
         // Connect to Salesforce to obtain an access token
         let conMetadata;
         try {
@@ -70,7 +76,32 @@ export default class PubSubApiClient {
                 cause: error
             });
         }
+        return this.#connectToPubSubApi(conMetadata);
+    }
+
+    /**
+     * Connects to the Pub/Sub API with user-supplied authentication
+     * @param {string} accessToken
+     * @param {string} instanceUrl
+     * @param {string} organizationId
+     * @param {string} username
+     * @returns {Promise<void>} Promise that resolves once the connection is established
+     */
+    async connectWithAuth(accessToken, instanceUrl, organizationId, username) {
+        return this.#connectToPubSubApi({
+            accessToken,
+            instanceUrl,
+            organizationId,
+            username
+        });
+    }
 
+    /**
+     * Connects to the Pub/Sub API
+     * @param {import('./auth.js').ConnectionMetadata} conMetadata
+     * @returns {Promise<void>} Promise that resolves once the connection is established
+     */
+    async #connectToPubSubApi(conMetadata) {
         // Connect to Pub/Sub API
         try {
             // Read certificates

src/configuration.js

@@ -1,7 +1,8 @@
 import * as dotenv from 'dotenv';
 import fs from 'fs';
 
-const AUTH_USERNAME_PASSWORD = 'username-password',
+const AUTH_USER_SUPPLIED = 'user-supplied',
+    AUTH_USERNAME_PASSWORD = 'username-password',
     AUTH_OAUTH_CLIENT_CREDENTIALS = 'oauth-client-credentials',
     AUTH_OAUTH_JWT_BEARER = 'oauth-jwt-bearer';
 
@@ -12,28 +13,31 @@ export default class Configuration {
         // Check mandatory variables
         Configuration.#checkMandatoryVariables([
             'SALESFORCE_AUTH_TYPE',
-            'SALESFORCE_LOGIN_URL',
             'PUB_SUB_ENDPOINT'
         ]);
+        // Check variable for specific auth types
         if (Configuration.isUsernamePasswordAuth()) {
             Configuration.#checkMandatoryVariables([
+                'SALESFORCE_LOGIN_URL',
                 'SALESFORCE_USERNAME',
                 'SALESFORCE_PASSWORD',
                 'SALESFORCE_TOKEN'
             ]);
         } else if (Configuration.isOAuthClientCredentialsAuth()) {
             Configuration.#checkMandatoryVariables([
+                'SALESFORCE_LOGIN_URL',
                 'SALESFORCE_CLIENT_ID',
                 'SALESFORCE_CLIENT_SECRET'
             ]);
         } else if (Configuration.isOAuthJwtBearerAuth()) {
             Configuration.#checkMandatoryVariables([
+                'SALESFORCE_LOGIN_URL',
                 'SALESFORCE_CLIENT_ID',
                 'SALESFORCE_USERNAME',
                 'SALESFORCE_PRIVATE_KEY_FILE'
             ]);
             Configuration.getSfPrivateKey();
-        } else {
+        } else if (!Configuration.isUserSuppliedAuth()) {
             throw new Error(
                 `Invalid value for SALESFORCE_AUTH_TYPE environment variable: ${Configuration.getAuthType()}`
             );
@@ -79,6 +83,10 @@ export default class Configuration {
         return process.env.PUB_SUB_ENDPOINT;
     }
 
+    static isUserSuppliedAuth() {
+        return Configuration.getAuthType() === AUTH_USER_SUPPLIED;
+    }
+
     static isUsernamePasswordAuth() {
         return Configuration.getAuthType() === AUTH_USERNAME_PASSWORD;
     }