feat: Add basic secure mode support for browser SDK.

Author: kinyoklion

packages/sdk/browser/BrowserIdentifyOptions.ts

@@ -0,0 +1,9 @@
+import { LDIdentifyOptions } from '@launchdarkly/js-client-sdk-common';
+
+export interface BrowserIdentifyOptions extends Omit<LDIdentifyOptions, 'waitForNetworkresults'> {
+  /**
+   * The signed context key if you are using [Secure Mode]
+   * (https://docs.launchdarkly.com/sdk/features/secure-mode#configuring-secure-mode-in-the-javascript-client-side-sdk).
+   */
+  hash?: string;
+}

packages/sdk/browser/__tests__/BrowserDataManager.test.ts

@@ -11,13 +11,13 @@ import {
   internal,
   LDEmitter,
   LDHeaders,
-  LDIdentifyOptions,
   LDLogger,
   Platform,
   Response,
   ServiceEndpoints,
 } from '@launchdarkly/js-client-sdk-common';
 
+import { BrowserIdentifyOptions } from '../BrowserIdentifyOptions';
 import BrowserDataManager from '../src/BrowserDataManager';
 import validateOptions, { ValidatedOptions } from '../src/options';
 import BrowserEncoding from '../src/platform/BrowserEncoding';
@@ -196,7 +196,7 @@ describe('given a BrowserDataManager with mocked dependencies', () => {
     );
 
     const context = Context.fromLDContext({ kind: 'user', key: 'test-user' });
-    const identifyOptions: LDIdentifyOptions = { waitForNetworkResults: false };
+    const identifyOptions: BrowserIdentifyOptions = {};
     const identifyResolve = jest.fn();
     const identifyReject = jest.fn();
 
@@ -205,9 +205,91 @@ describe('given a BrowserDataManager with mocked dependencies', () => {
     expect(platform.requests.createEventSource).toHaveBeenCalled();
   });
 
+  it('includes the secure mode hash for streaming requests', async () => {
+    dataManager = new BrowserDataManager(
+      platform,
+      flagManager,
+      'test-credential',
+      config,
+      validateOptions({ streaming: true }, logger),
+      () => ({
+        pathGet(encoding: Encoding, _plainContextString: string): string {
+          return `/msdk/evalx/contexts/${base64UrlEncode(_plainContextString, encoding)}`;
+        },
+        pathReport(_encoding: Encoding, _plainContextString: string): string {
+          return `/msdk/evalx/context`;
+        },
+      }),
+      () => ({
+        pathGet(encoding: Encoding, _plainContextString: string): string {
+          return `/meval/${base64UrlEncode(_plainContextString, encoding)}`;
+        },
+        pathReport(_encoding: Encoding, _plainContextString: string): string {
+          return `/meval`;
+        },
+      }),
+      baseHeaders,
+      emitter,
+      diagnosticsManager,
+    );
+
+    const context = Context.fromLDContext({ kind: 'user', key: 'test-user' });
+    const identifyOptions: BrowserIdentifyOptions = { hash: 'potato' };
+    const identifyResolve = jest.fn();
+    const identifyReject = jest.fn();
+
+    await dataManager.identify(identifyResolve, identifyReject, context, identifyOptions);
+
+    expect(platform.requests.createEventSource).toHaveBeenCalledWith(
+      '/meval/eyJraW5kIjoidXNlciIsImtleSI6InRlc3QtdXNlciJ9?h=potato&withReasons=true',
+      expect.anything(),
+    );
+  });
+
+  it('includes secure mode hash for initial poll request', async () => {
+    dataManager = new BrowserDataManager(
+      platform,
+      flagManager,
+      'test-credential',
+      config,
+      validateOptions({ streaming: false }, logger),
+      () => ({
+        pathGet(encoding: Encoding, _plainContextString: string): string {
+          return `/msdk/evalx/contexts/${base64UrlEncode(_plainContextString, encoding)}`;
+        },
+        pathReport(_encoding: Encoding, _plainContextString: string): string {
+          return `/msdk/evalx/context`;
+        },
+      }),
+      () => ({
+        pathGet(encoding: Encoding, _plainContextString: string): string {
+          return `/meval/${base64UrlEncode(_plainContextString, encoding)}`;
+        },
+        pathReport(_encoding: Encoding, _plainContextString: string): string {
+          return `/meval`;
+        },
+      }),
+      baseHeaders,
+      emitter,
+      diagnosticsManager,
+    );
+
+    const context = Context.fromLDContext({ kind: 'user', key: 'test-user' });
+    const identifyOptions: BrowserIdentifyOptions = { hash: 'potato' };
+    const identifyResolve = jest.fn();
+    const identifyReject = jest.fn();
+
+    await dataManager.identify(identifyResolve, identifyReject, context, identifyOptions);
+
+    expect(platform.requests.fetch).toHaveBeenCalledWith(
+      '/msdk/evalx/contexts/eyJraW5kIjoidXNlciIsImtleSI6InRlc3QtdXNlciJ9?withReasons=true&h=potato',
+      expect.anything(),
+    );
+  });
+
   it('should load cached flags and continue to poll to complete identify', async () => {
     const context = Context.fromLDContext({ kind: 'user', key: 'test-user' });
-    const identifyOptions: LDIdentifyOptions = { waitForNetworkResults: false };
+    const identifyOptions: BrowserIdentifyOptions = {};
     const identifyResolve = jest.fn();
     const identifyReject = jest.fn();
 
@@ -230,7 +312,7 @@ describe('given a BrowserDataManager with mocked dependencies', () => {
 
   it('should identify from polling when there are no cached flags', async () => {
     const context = Context.fromLDContext({ kind: 'user', key: 'test-user' });
-    const identifyOptions: LDIdentifyOptions = { waitForNetworkResults: false };
+    const identifyOptions: BrowserIdentifyOptions = {};
     const identifyResolve = jest.fn();
     const identifyReject = jest.fn();
 
@@ -253,7 +335,7 @@ describe('given a BrowserDataManager with mocked dependencies', () => {
 
   it('creates a stream when streaming is enabled after construction', async () => {
     const context = Context.fromLDContext({ kind: 'user', key: 'test-user' });
-    const identifyOptions: LDIdentifyOptions = { waitForNetworkResults: false };
+    const identifyOptions: BrowserIdentifyOptions = {};
     const identifyResolve = jest.fn();
     const identifyReject = jest.fn();
 
@@ -268,7 +350,7 @@ describe('given a BrowserDataManager with mocked dependencies', () => {
 
   it('does not re-create the stream if it already running', async () => {
     const context = Context.fromLDContext({ kind: 'user', key: 'test-user' });
-    const identifyOptions: LDIdentifyOptions = { waitForNetworkResults: false };
+    const identifyOptions: BrowserIdentifyOptions = {};
     const identifyResolve = jest.fn();
     const identifyReject = jest.fn();
 
@@ -296,7 +378,7 @@ describe('given a BrowserDataManager with mocked dependencies', () => {
 
   it('starts a stream on demand when not forced on/off', async () => {
     const context = Context.fromLDContext({ kind: 'user', key: 'test-user' });
-    const identifyOptions: LDIdentifyOptions = { waitForNetworkResults: false };
+    const identifyOptions: BrowserIdentifyOptions = {};
     const identifyResolve = jest.fn();
     const identifyReject = jest.fn();
 
@@ -315,7 +397,7 @@ describe('given a BrowserDataManager with mocked dependencies', () => {
 
   it('does not start a stream when forced off', async () => {
     const context = Context.fromLDContext({ kind: 'user', key: 'test-user' });
-    const identifyOptions: LDIdentifyOptions = { waitForNetworkResults: false };
+    const identifyOptions: BrowserIdentifyOptions = {};
     const identifyResolve = jest.fn();
     const identifyReject = jest.fn();
 
@@ -335,7 +417,7 @@ describe('given a BrowserDataManager with mocked dependencies', () => {
 
   it('starts streaming on identify if the automatic state is true', async () => {
     const context = Context.fromLDContext({ kind: 'user', key: 'test-user' });
-    const identifyOptions: LDIdentifyOptions = { waitForNetworkResults: false };
+    const identifyOptions: BrowserIdentifyOptions = {};
     const identifyResolve = jest.fn();
     const identifyReject = jest.fn();
 

packages/sdk/browser/src/BrowserClient.ts

@@ -13,22 +13,29 @@ import {
   LDHeaders,
   Platform,
 } from '@launchdarkly/js-client-sdk-common';
-import { LDIdentifyOptions } from '@launchdarkly/js-client-sdk-common/dist/api/LDIdentifyOptions';
 import { EventName } from '@launchdarkly/js-client-sdk-common/dist/LDEmitter';
 
+import { BrowserIdentifyOptions as LDIdentifyOptions } from '../BrowserIdentifyOptions';
 import BrowserDataManager from './BrowserDataManager';
 import GoalManager from './goals/GoalManager';
 import { Goal, isClick } from './goals/Goals';
 import validateOptions, { BrowserOptions, filterToBaseOptions } from './options';
 import BrowserPlatform from './platform/BrowserPlatform';
 
 /**
- * We are not supporting dynamically setting the connection mode on the LDClient.
- * The SDK does not support offline mode. Instead bootstrap data can be used.
+ *
+ * The LaunchDarkly SDK client object.
+ *
+ * Applications should configure the client at page load time and reuse the same instance.
+ *
+ * For more information, see the [SDK Reference Guide](https://docs.launchdarkly.com/sdk/client-side/javascript).
+ *
+ * @ignore Implementation Note: We are not supporting dynamically setting the connection mode on the LDClient.
+ * @ignore Implementation Note: The SDK does not support offline mode. Instead bootstrap data can be used.
  */
 export type LDClient = Omit<
   CommonClient,
-  'setConnectionMode' | 'getConnectionMode' | 'getOffline'
+  'setConnectionMode' | 'getConnectionMode' | 'getOffline' | 'identify'
 > & {
   /**
    * Specifies whether or not to open a streaming connection to LaunchDarkly for live flag updates.
@@ -40,9 +47,38 @@ export type LDClient = Omit<
    * This can also be set as the `streaming` property of {@link LDOptions}.
    */
   setStreaming(streaming?: boolean): void;
+
+  /**
+   * Identifies a context to LaunchDarkly.
+   *
+   * Unlike the server-side SDKs, the client-side JavaScript SDKs maintain a current context state,
+   * which is set when you call `identify()`.
+   *
+   * Changing the current context also causes all feature flag values to be reloaded. Until that has
+   * finished, calls to {@link variation} will still return flag values for the previous context. You can
+   * await the Promise to determine when the new flag values are available.
+   *
+   * @param context
+   *    The LDContext object.
+   * @param identifyOptions
+   *    Optional configuration. Please see {@link LDIdentifyOptions}.
+   * @returns
+   *    A Promise which resolves when the flag values for the specified
+   * context are available. It rejects when:
+   *
+   * 1. The context is unspecified or has no key.
+   *
+   * 2. The identify timeout is exceeded. In client SDKs this defaults to 5s.
+   * You can customize this timeout with {@link LDIdentifyOptions | identifyOptions}.
+   *
+   * 3. A network error is encountered during initialization.
+   *
+   * @ignore Implementation Note: Browser implementation has different options.
+   */
+  identify(context: LDContext, identifyOptions?: LDIdentifyOptions): Promise<void>;
 };
 
-export class BrowserClient extends LDClientImpl {
+export class BrowserClient extends LDClientImpl implements LDClient {
   private readonly goalManager?: GoalManager;
 
   constructor(

packages/sdk/browser/src/BrowserDataManager.ts

@@ -13,6 +13,7 @@ import {
   Requestor,
 } from '@launchdarkly/js-client-sdk-common';
 
+import { BrowserIdentifyOptions } from '../BrowserIdentifyOptions';
 import { ValidatedOptions } from './options';
 
 const logTag = '[BrowserDataManager]';
@@ -22,6 +23,7 @@ export default class BrowserDataManager extends BaseDataManager {
   // Otherwise we automatically manage streaming state.
   private forcedStreaming?: boolean = undefined;
   private automaticStreamingState: boolean = false;
+  private secureModeHash?: string;
 
   // +-----------+-----------+---------------+
   // |  forced   | automatic |     state     |
@@ -68,9 +70,18 @@ export default class BrowserDataManager extends BaseDataManager {
     identifyResolve: () => void,
     identifyReject: (err: Error) => void,
     context: Context,
-    _identifyOptions?: LDIdentifyOptions,
+    identifyOptions?: LDIdentifyOptions,
   ): Promise<void> {
     this.context = context;
+    const browserIdentifyOptions = identifyOptions as BrowserIdentifyOptions;
+    if (browserIdentifyOptions.hash) {
+      this.setConnectionParams({
+        queryParameters: [{ key: 'h', value: browserIdentifyOptions.hash }],
+      });
+    } else {
+      this.setConnectionParams();
+    }
+    this.secureModeHash = browserIdentifyOptions.hash;
     if (await this.flagManager.loadCached(context)) {
       this.debugLog('Identify - Flags loaded from cache. Continuing to initialize via a poll.');
     }
@@ -162,6 +173,9 @@ export default class BrowserDataManager extends BaseDataManager {
     if (this.config.withReasons) {
       parameters.push({ key: 'withReasons', value: 'true' });
     }
+    if (this.secureModeHash) {
+      parameters.push({ key: 'h', value: this.secureModeHash });
+    }
 
     const headers: { [key: string]: string } = { ...this.baseHeaders };
     let body;

packages/shared/sdk-client/__tests__/polling/PollingProcessor.test.ts

@@ -75,6 +75,7 @@ function makeConfig(
   pollInterval: number,
   withReasons: boolean,
   useReport: boolean,
+  queryParameters?: { key: string; value: string }[],
 ): PollingDataSourceConfig {
   return {
     credential: 'the-sdk-key',
@@ -91,6 +92,7 @@ function makeConfig(
     withReasons,
     useReport,
     pollInterval,
+    queryParameters,
   };
 }
 
@@ -109,6 +111,49 @@ it('makes no requests until it is started', () => {
   expect(requests.fetch).toHaveBeenCalledTimes(0);
 });
 
+it('includes custom query parameters when specified', () => {
+  const requests = makeRequests();
+
+  const polling = new PollingProcessor(
+    'mockContextString',
+    makeConfig(1, true, false, [
+      { key: 'custom', value: 'value' },
+      { key: 'custom2', value: 'value2' },
+    ]),
+    requests,
+    makeEncoding(),
+    (_flags) => {},
+    (_error) => {},
+  );
+  polling.start();
+
+  expect(requests.fetch).toHaveBeenCalledWith(
+    'mockPollingEndpoint/poll/path/get?custom=value&custom2=value2&withReasons=true&filter=testPayloadFilterKey',
+    expect.anything(),
+  );
+  polling.stop();
+});
+
+it('works without any custom query parameters', () => {
+  const requests = makeRequests();
+
+  const polling = new PollingProcessor(
+    'mockContextString',
+    makeConfig(1, true, false),
+    requests,
+    makeEncoding(),
+    (_flags) => {},
+    (_error) => {},
+  );
+  polling.start();
+
+  expect(requests.fetch).toHaveBeenCalledWith(
+    'mockPollingEndpoint/poll/path/get?withReasons=true&filter=testPayloadFilterKey',
+    expect.anything(),
+  );
+  polling.stop();
+});
+
 it('polls immediately when started', () => {
   const requests = makeRequests();