@kubesense/kubesense-browser-rum-core 1.0.0

package/src/domain/configuration/jsonPathParser.ts

@@ -0,0 +1,214 @@
+/**
+ * Terminology inspired from https://www.rfc-editor.org/rfc/rfc9535.html
+ *
+ * jsonpath-query      = segment*
+ * segment             = .name-shorthand / bracketed-selection
+ * bracketed-selection = ['name-selector'] / ["name-selector"] / [index-selector]
+ *
+ * Useful references:
+ * - https://goessner.net/articles/JsonPath/
+ * - https://jsonpath.com/
+ * - https://github.com/jsonpath-standard
+ */
+
+interface ParsingContext {
+  quote: string | undefined
+  escapeSequence: string | undefined
+}
+
+/**
+ * Extract selectors from a simple JSON path expression, return [] for an invalid path
+ *
+ * Supports:
+ * - Dot notation: `foo.bar.baz`
+ * - Bracket notation: `['foo']["bar"]`
+ * - Array indices: `items[0]`, `data['users'][1]`
+ *
+ * Examples:
+ * parseJsonPath("['foo'].bar[12]")
+ * => ['foo', 'bar', '12']
+ *
+ * parseJsonPath("['foo")
+ * => []
+ */
+export function parseJsonPath(path: string): string[] {
+  const selectors: string[] = []
+  let previousToken = Token.START
+  let currentToken: Token | undefined
+  const parsingContext: ParsingContext = { quote: undefined, escapeSequence: undefined }
+  let currentSelector = ''
+  for (const char of path) {
+    // find which kind of token is this char
+    currentToken = ALLOWED_NEXT_TOKENS[previousToken].find((token) => TOKEN_PREDICATE[token](char, parsingContext))
+    if (!currentToken) {
+      return []
+    }
+    if (parsingContext.escapeSequence !== undefined && currentToken !== Token.ESCAPE_SEQUENCE_CHAR) {
+      if (!isValidEscapeSequence(parsingContext.escapeSequence)) {
+        return []
+      }
+      currentSelector += resolveEscapeSequence(parsingContext.escapeSequence)
+      parsingContext.escapeSequence = undefined
+    }
+    if (ALLOWED_SELECTOR_TOKENS.includes(currentToken)) {
+      // buffer the char if it belongs to the selector
+      // ex: foo['bar']
+      //      ^    ^
+      currentSelector += char
+    } else if (ALLOWED_SELECTOR_DELIMITER_TOKENS.includes(currentToken) && currentSelector !== '') {
+      // close the current path part if we have reach a path part delimiter
+      // ex: foo.bar['qux']
+      //        ^   ^     ^
+      selectors.push(currentSelector)
+      currentSelector = ''
+    } else if (currentToken === Token.ESCAPE_SEQUENCE_CHAR) {
+      parsingContext.escapeSequence = parsingContext.escapeSequence ? `${parsingContext.escapeSequence}${char}` : char
+    } else if (currentToken === Token.QUOTE_START) {
+      parsingContext.quote = char
+    } else if (currentToken === Token.QUOTE_END) {
+      parsingContext.quote = undefined
+    }
+    previousToken = currentToken
+  }
+  if (!ALLOWED_NEXT_TOKENS[previousToken].includes(Token.END)) {
+    return []
+  }
+  if (currentSelector !== '') {
+    selectors.push(currentSelector)
+  }
+  return selectors
+}
+
+/**
+ * List of all tokens in the path
+ *
+ * @example                        foo.bar['qu\'x'][0]
+ *                                |   |   |        |  |
+ * Token sequence:                |   |   |        |  |
+ * 1. START (before first char) <-+   |   |        |  |
+ * 2. NAME_SHORTHAND_FIRST_CHAR: f    |   |        |  |
+ * 3. NAME_SHORTHAND_CHAR: oo         |   |        |  |
+ * 4. DOT: . <------------------------+   |        |  |
+ * 5. NAME_SHORTHAND_FIRST_CHAR: b        |        |  |
+ * 6. NAME_SHORTHAND_CHAR: ar             |        |  |
+ * 7. BRACKET_START: [ <------------------+        |  |
+ * 8. QUOTE_START: '                               |  |
+ * 9. NAME_SELECTOR_CHAR: qu                       |  |
+ * 10. ESCAPE: \                                   |  |
+ * 11. ESCAPABLE_CHAR: '                           |  |
+ * 12. NAME_SELECTOR_CHAR: x                       |  |
+ * 13. QUOTE_END: '                                |  |
+ * 14. BRACKET_END: ]                              |  |
+ * 15. BRACKET_START: [ <--------------------------+  |
+ * 16. DIGIT: 0                                       |
+ * 17. BRACKET_END: ]                                 |
+ * 18. END (after last char) <------------------------+
+ */
+const enum Token {
+  START,
+  END,
+
+  NAME_SHORTHAND_FIRST_CHAR,
+  NAME_SHORTHAND_CHAR,
+  DOT,
+
+  BRACKET_START,
+  BRACKET_END,
+  DIGIT,
+
+  QUOTE_START,
+  QUOTE_END,
+  NAME_SELECTOR_CHAR,
+  ESCAPE,
+  ESCAPE_SEQUENCE_CHAR,
+}
+
+const NAME_SHORTHAND_FIRST_CHAR_REGEX = /[a-zA-Z_$]/
+const NAME_SHORTHAND_CHAR_REGEX = /[a-zA-Z0-9_$]/
+const DIGIT_REGEX = /[0-9]/
+const UNICODE_CHAR_REGEX = /[a-fA-F0-9]/
+const QUOTE_CHARS = '\'"'
+
+const TOKEN_PREDICATE: { [token in Token]: (char: string, parsingContext: ParsingContext) => boolean } = {
+  // no char should match to START or END
+  [Token.START]: () => false,
+  [Token.END]: () => false,
+
+  [Token.NAME_SHORTHAND_FIRST_CHAR]: (char) => NAME_SHORTHAND_FIRST_CHAR_REGEX.test(char),
+  [Token.NAME_SHORTHAND_CHAR]: (char) => NAME_SHORTHAND_CHAR_REGEX.test(char),
+  [Token.DOT]: (char) => char === '.',
+
+  [Token.BRACKET_START]: (char) => char === '[',
+  [Token.BRACKET_END]: (char) => char === ']',
+  [Token.DIGIT]: (char) => DIGIT_REGEX.test(char),
+
+  [Token.QUOTE_START]: (char) => QUOTE_CHARS.includes(char),
+  [Token.QUOTE_END]: (char, parsingContext) => char === parsingContext.quote,
+  [Token.NAME_SELECTOR_CHAR]: () => true, // any char can be used in name selector
+  [Token.ESCAPE]: (char) => char === '\\',
+  [Token.ESCAPE_SEQUENCE_CHAR]: (char, parsingContext) => {
+    if (parsingContext.escapeSequence === undefined) {
+      // see https://www.rfc-editor.org/rfc/rfc9535.html#name-semantics-3
+      return `${parsingContext.quote}/\\bfnrtu`.includes(char)
+    } else if (parsingContext.escapeSequence.startsWith('u') && parsingContext.escapeSequence.length < 5) {
+      return UNICODE_CHAR_REGEX.test(char)
+    }
+    return false
+  },
+}
+
+const ALLOWED_NEXT_TOKENS: { [token in Token]: Token[] } = {
+  [Token.START]: [Token.NAME_SHORTHAND_FIRST_CHAR, Token.BRACKET_START],
+  [Token.END]: [],
+
+  [Token.NAME_SHORTHAND_FIRST_CHAR]: [Token.NAME_SHORTHAND_CHAR, Token.DOT, Token.BRACKET_START, Token.END],
+  [Token.NAME_SHORTHAND_CHAR]: [Token.NAME_SHORTHAND_CHAR, Token.DOT, Token.BRACKET_START, Token.END],
+  [Token.DOT]: [Token.NAME_SHORTHAND_FIRST_CHAR],
+
+  [Token.BRACKET_START]: [Token.QUOTE_START, Token.DIGIT],
+  [Token.BRACKET_END]: [Token.DOT, Token.BRACKET_START, Token.END],
+  [Token.DIGIT]: [Token.DIGIT, Token.BRACKET_END],
+
+  [Token.QUOTE_START]: [Token.ESCAPE, Token.QUOTE_END, Token.NAME_SELECTOR_CHAR],
+  [Token.QUOTE_END]: [Token.BRACKET_END],
+  [Token.NAME_SELECTOR_CHAR]: [Token.ESCAPE, Token.QUOTE_END, Token.NAME_SELECTOR_CHAR],
+  [Token.ESCAPE]: [Token.ESCAPE_SEQUENCE_CHAR],
+  [Token.ESCAPE_SEQUENCE_CHAR]: [Token.ESCAPE_SEQUENCE_CHAR, Token.ESCAPE, Token.QUOTE_END, Token.NAME_SELECTOR_CHAR],
+}
+
+// foo['bar\n'][12]
+// ^^    ^ ^^   ^
+const ALLOWED_SELECTOR_TOKENS = [
+  Token.NAME_SHORTHAND_FIRST_CHAR,
+  Token.NAME_SHORTHAND_CHAR,
+  Token.DIGIT,
+  Token.NAME_SELECTOR_CHAR,
+]
+
+// foo.bar['qux']
+//    ^   ^     ^
+const ALLOWED_SELECTOR_DELIMITER_TOKENS = [Token.DOT, Token.BRACKET_START, Token.BRACKET_END]
+
+function isValidEscapeSequence(escapeSequence: string): boolean {
+  return '"\'/\\bfnrt'.includes(escapeSequence) || (escapeSequence.startsWith('u') && escapeSequence.length === 5)
+}
+
+const ESCAPED_CHARS: { [key: string]: string } = {
+  '"': '"',
+  "'": "'",
+  '/': '/',
+  '\\': '\\',
+  b: '\b',
+  f: '\f',
+  n: '\n',
+  r: '\r',
+  t: '\t',
+}
+
+function resolveEscapeSequence(escapeSequence: string): string {
+  if (escapeSequence.startsWith('u')) {
+    // build Unicode char from code
+    return String.fromCharCode(parseInt(escapeSequence.slice(1), 16))
+  }
+  return ESCAPED_CHARS[escapeSequence]
+}

package/src/domain/configuration/remoteConfiguration.ts

@@ -0,0 +1,304 @@
+import type { createContextManager, Context } from '@kubesense/kubesense-browser-core'
+import {
+  display,
+  buildEndpointHost,
+  mapValues,
+  getCookie,
+  addTelemetryMetrics,
+  TelemetryMetrics,
+} from '@kubesense/kubesense-browser-core'
+import type { RumInitConfiguration } from './configuration'
+import type { RumSdkConfig, DynamicOption, ContextItem } from './remoteConfiguration.types'
+import { parseJsonPath } from './jsonPathParser'
+
+export type RemoteConfiguration = RumSdkConfig
+export type RumRemoteConfiguration = Exclude<RemoteConfiguration['rum'], undefined>
+const REMOTE_CONFIGURATION_VERSION = 'v1'
+const SUPPORTED_FIELDS: Array<keyof RumInitConfiguration> = [
+  'applicationId',
+  'service',
+  'env',
+  'version',
+  'sessionSampleRate',
+  'sessionReplaySampleRate',
+  'defaultPrivacyLevel',
+  'enablePrivacyForActionName',
+  'traceSampleRate',
+  'trackSessionAcrossSubdomains',
+  'allowedTracingUrls',
+  'allowedTrackingOrigins',
+]
+
+// type needed for switch on union
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+type SerializedRegex = { rcSerializedType: 'regex'; value: string }
+type SerializedOption = { rcSerializedType: 'string'; value: string } | SerializedRegex | DynamicOption
+
+interface SupportedContextManagers {
+  user: ReturnType<typeof createContextManager>
+  context: ReturnType<typeof createContextManager>
+}
+
+export interface RemoteConfigurationMetrics extends Context {
+  fetch: RemoteConfigurationMetricCounters
+  cookie?: RemoteConfigurationMetricCounters
+  dom?: RemoteConfigurationMetricCounters
+  js?: RemoteConfigurationMetricCounters
+}
+
+interface RemoteConfigurationMetricCounters {
+  success?: number
+  missing?: number
+  failure?: number
+  [key: string]: number | undefined
+}
+
+export async function fetchAndApplyRemoteConfiguration(
+  initConfiguration: RumInitConfiguration,
+  supportedContextManagers: SupportedContextManagers
+) {
+  let rumInitConfiguration: RumInitConfiguration | undefined
+  const metrics = initMetrics()
+  const fetchResult = await fetchRemoteConfiguration(initConfiguration)
+  if (!fetchResult.ok) {
+    metrics.increment('fetch', 'failure')
+    display.error(fetchResult.error)
+  } else {
+    metrics.increment('fetch', 'success')
+    rumInitConfiguration = applyRemoteConfiguration(
+      initConfiguration,
+      fetchResult.value,
+      supportedContextManagers,
+      metrics
+    )
+  }
+  // monitor-until: forever
+  addTelemetryMetrics(TelemetryMetrics.REMOTE_CONFIGURATION_METRIC_NAME, { metrics: metrics.get() })
+  return rumInitConfiguration
+}
+
+export function applyRemoteConfiguration(
+  initConfiguration: RumInitConfiguration,
+  rumRemoteConfiguration: RumRemoteConfiguration & { [key: string]: unknown },
+  supportedContextManagers: SupportedContextManagers,
+  metrics: ReturnType<typeof initMetrics>
+): RumInitConfiguration {
+  // intents:
+  // - explicitly set each supported field to limit risk in case an attacker can create configurations
+  // - check the existence in the remote config to avoid clearing a provided init field
+  const appliedConfiguration = { ...initConfiguration } as RumInitConfiguration & { [key: string]: unknown }
+  SUPPORTED_FIELDS.forEach((option: string) => {
+    if (option in rumRemoteConfiguration) {
+      appliedConfiguration[option] = resolveConfigurationProperty(rumRemoteConfiguration[option])
+    }
+  })
+  ;(Object.keys(supportedContextManagers) as Array<keyof SupportedContextManagers>).forEach((context) => {
+    if (rumRemoteConfiguration[context] !== undefined) {
+      resolveContextProperty(supportedContextManagers[context], rumRemoteConfiguration[context])
+    }
+  })
+  return appliedConfiguration
+
+  // share context to access metrics
+
+  function resolveConfigurationProperty(property: unknown): unknown {
+    if (Array.isArray(property)) {
+      return property.map(resolveConfigurationProperty)
+    }
+    if (isObject(property)) {
+      if (isSerializedOption(property)) {
+        const type = property.rcSerializedType
+        switch (type) {
+          case 'string':
+            return property.value
+          case 'regex':
+            return resolveRegex(property.value)
+          case 'dynamic':
+            return resolveDynamicOption(property)
+          default:
+            display.error(`Unsupported remote configuration: "rcSerializedType": "${type as string}"`)
+            return
+        }
+      }
+      return mapValues(property, resolveConfigurationProperty)
+    }
+    return property
+  }
+
+  function resolveContextProperty(
+    contextManager: ReturnType<typeof createContextManager>,
+    contextItems: ContextItem[]
+  ) {
+    contextItems.forEach(({ key, value }) => {
+      contextManager.setContextProperty(key, resolveConfigurationProperty(value))
+    })
+  }
+
+  function resolveDynamicOption(property: DynamicOption) {
+    const strategy = property.strategy
+    let resolvedValue: unknown
+    switch (strategy) {
+      case 'cookie':
+        resolvedValue = resolveCookieValue(property)
+        break
+      case 'dom':
+        resolvedValue = resolveDomValue(property)
+        break
+      case 'js':
+        resolvedValue = resolveJsValue(property)
+        break
+      default:
+        display.error(`Unsupported remote configuration: "strategy": "${strategy as string}"`)
+        return
+    }
+    const extractor = property.extractor
+    if (extractor !== undefined && typeof resolvedValue === 'string') {
+      return extractValue(extractor, resolvedValue)
+    }
+    return resolvedValue
+  }
+
+  function resolveCookieValue({ name }: { name: string }) {
+    const value = getCookie(name)
+    metrics.increment('cookie', value !== undefined ? 'success' : 'missing')
+    return value
+  }
+
+  function resolveDomValue({ selector, attribute }: { selector: string; attribute?: string }) {
+    let element: Element | null
+    try {
+      element = document.querySelector(selector)
+    } catch {
+      display.error(`Invalid selector in the remote configuration: '${selector}'`)
+      metrics.increment('dom', 'failure')
+      return
+    }
+    if (!element) {
+      metrics.increment('dom', 'missing')
+      return
+    }
+    if (isForbidden(element, attribute)) {
+      display.error(`Forbidden element selected by the remote configuration: '${selector}'`)
+      metrics.increment('dom', 'failure')
+      return
+    }
+    const domValue = attribute !== undefined ? element.getAttribute(attribute) : element.textContent
+    if (domValue === null) {
+      metrics.increment('dom', 'missing')
+      return
+    }
+    metrics.increment('dom', 'success')
+    return domValue
+  }
+
+  function isForbidden(element: Element, attribute: string | undefined) {
+    return element.getAttribute('type') === 'password' && attribute === 'value'
+  }
+
+  function resolveJsValue({ path }: { path: string }): unknown {
+    let current = window as unknown as { [key: string]: unknown }
+    const pathParts = parseJsonPath(path)
+    if (pathParts.length === 0) {
+      display.error(`Invalid JSON path in the remote configuration: '${path}'`)
+      metrics.increment('js', 'failure')
+      return
+    }
+    for (const pathPart of pathParts) {
+      if (!(pathPart in current)) {
+        metrics.increment('js', 'missing')
+        return
+      }
+      try {
+        current = current[pathPart] as { [key: string]: unknown }
+      } catch (e) {
+        display.error(`Error accessing: '${path}'`, e)
+        metrics.increment('js', 'failure')
+        return
+      }
+    }
+    metrics.increment('js', 'success')
+    return current
+  }
+}
+
+export function initMetrics() {
+  const metrics: RemoteConfigurationMetrics = { fetch: {} }
+  return {
+    get: () => metrics,
+    increment: (metricName: 'fetch' | DynamicOption['strategy'], type: keyof RemoteConfigurationMetricCounters) => {
+      if (!metrics[metricName]) {
+        metrics[metricName] = {}
+      }
+      if (!metrics[metricName][type]) {
+        metrics[metricName][type] = 0
+      }
+      metrics[metricName][type] = metrics[metricName][type] + 1
+    },
+  }
+}
+
+function isObject(property: unknown): property is { [key: string]: unknown } {
+  return typeof property === 'object' && property !== null
+}
+
+function isSerializedOption(value: object): value is SerializedOption {
+  return 'rcSerializedType' in value
+}
+
+function resolveRegex(pattern: string): RegExp | undefined {
+  try {
+    return new RegExp(pattern)
+  } catch {
+    display.error(`Invalid regex in the remote configuration: '${pattern}'`)
+  }
+}
+
+function extractValue(extractor: SerializedRegex, candidate: string) {
+  const resolvedExtractor = resolveRegex(extractor.value)
+  if (resolvedExtractor === undefined) {
+    return
+  }
+  const regexResult = resolvedExtractor.exec(candidate)
+  if (regexResult === null) {
+    return
+  }
+  const [match, capture] = regexResult
+  return capture ? capture : match
+}
+
+type FetchRemoteConfigurationResult = { ok: true; value: RumRemoteConfiguration } | { ok: false; error: Error }
+
+export async function fetchRemoteConfiguration(
+  configuration: RumInitConfiguration
+): Promise<FetchRemoteConfigurationResult> {
+  let response: Response | undefined
+  try {
+    response = await fetch(buildEndpoint(configuration))
+  } catch {
+    response = undefined
+  }
+  if (!response || !response.ok) {
+    return {
+      ok: false,
+      error: new Error('Error fetching the remote configuration.'),
+    }
+  }
+  const remoteConfiguration: RemoteConfiguration = await response.json()
+  if (remoteConfiguration.rum) {
+    return {
+      ok: true,
+      value: remoteConfiguration.rum,
+    }
+  }
+  return {
+    ok: false,
+    error: new Error('No remote configuration for RUM.'),
+  }
+}
+
+export function buildEndpoint(configuration: RumInitConfiguration) {
+  if (configuration.remoteConfigurationProxy) {
+    return configuration.remoteConfigurationProxy
+  }
+  return `https://sdk-configuration.${buildEndpointHost('rum', configuration)}/${REMOTE_CONFIGURATION_VERSION}/${encodeURIComponent(configuration.remoteConfigurationId!)}.json`
+}

package/src/domain/configuration/remoteConfiguration.types.ts

@@ -0,0 +1,147 @@
+/* eslint-disable */
+/**
+ * DO NOT MODIFY IT BY HAND. Run `yarn json-schemas:sync` instead.
+ */
+
+export type DynamicOption =
+  | {
+      rcSerializedType: 'dynamic'
+      strategy: 'js'
+      path: string
+      extractor?: SerializedRegex
+      [k: string]: unknown
+    }
+  | {
+      rcSerializedType: 'dynamic'
+      strategy: 'cookie'
+      name: string
+      extractor?: SerializedRegex
+      [k: string]: unknown
+    }
+  | {
+      rcSerializedType: 'dynamic'
+      strategy: 'dom'
+      selector: string
+      attribute?: string
+      extractor?: SerializedRegex
+      [k: string]: unknown
+    }
+
+/**
+ * RUM Browser & Mobile SDKs Remote Configuration properties
+ */
+export interface RumSdkConfig {
+  /**
+   * RUM feature Remote Configuration properties
+   */
+  rum?: {
+    /**
+     * UUID of the application
+     */
+    applicationId: string
+    /**
+     * The service name for this application
+     */
+    service?: string
+    /**
+     * The environment for this application
+     */
+    env?: string
+    /**
+     * The version for this application
+     */
+    version?:
+      | {
+          rcSerializedType: 'dynamic'
+          strategy: 'js'
+          path: string
+          extractor?: SerializedRegex
+          [k: string]: unknown
+        }
+      | {
+          rcSerializedType: 'dynamic'
+          strategy: 'cookie'
+          name: string
+          extractor?: SerializedRegex
+          [k: string]: unknown
+        }
+      | {
+          rcSerializedType: 'dynamic'
+          strategy: 'dom'
+          selector: string
+          attribute?: string
+          extractor?: SerializedRegex
+          [k: string]: unknown
+        }
+    /**
+     * The percentage of sessions tracked
+     */
+    sessionSampleRate?: number
+    /**
+     * The percentage of sessions with RUM & Session Replay pricing tracked
+     */
+    sessionReplaySampleRate?: number
+    /**
+     * Session replay default privacy level
+     */
+    defaultPrivacyLevel?: string
+    /**
+     * Privacy control for action name
+     */
+    enablePrivacyForActionName?: boolean
+    /**
+     * URLs where tracing is allowed
+     */
+    allowedTracingUrls?: {
+      match: MatchOption
+      /**
+       * List of propagator types
+       */
+      propagatorTypes?: ('kubesense' | 'b3' | 'b3multi' | 'tracecontext')[] | null
+    }[]
+    /**
+     * Origins where tracking is allowed
+     */
+    allowedTrackingOrigins?: MatchOption[]
+    /**
+     * The percentage of traces sampled
+     */
+    traceSampleRate?: number
+    /**
+     * Whether to track sessions across subdomains
+     */
+    trackSessionAcrossSubdomains?: boolean
+    /**
+     * Function to define user information
+     */
+    user?: ContextItem[]
+    /**
+     * Function to define global context
+     */
+    context?: ContextItem[]
+  }
+}
+export interface SerializedRegex {
+  /**
+   * Remote config serialized type for regex extraction
+   */
+  rcSerializedType: 'regex'
+  /**
+   * Regex pattern for value extraction
+   */
+  value: string
+}
+export interface MatchOption {
+  /**
+   * Remote config serialized type of match
+   */
+  rcSerializedType: 'string' | 'regex'
+  /**
+   * Match value
+   */
+  value: string
+}
+export interface ContextItem {
+  key: string
+  value: DynamicOption
+}