@oneuptime/common 14.0.1 → 14.0.3

package/Utils/Rum/SessionReplayWireEncoding.ts

@@ -0,0 +1,137 @@
+/*
+ * Byte-level encoding of a session-replay chunk POST, chosen so that a web
+ * application firewall between the customer's page and OneUptime lets it
+ * through.
+ *
+ * Customers route the recorder through their own edge (Azure Front Door,
+ * Application Gateway, Cloudflare, a ModSecurity or Coraza proxy), and those
+ * edges run the OWASP Core Rule Set or a ruleset baselined on it. Two of its
+ * rules decide whether a chunk arrives at all:
+ *
+ *  - 920420 refuses any Content-Type outside a short allowlist. That is why
+ *    SESSION_REPLAY_CONTENT_TYPE is application/octet-stream - see its note.
+ *    An octet-stream body also selects no body processor, so the firewall
+ *    never turns the envelope's URLs or trait values into ARGS for the
+ *    injection rules, the way it does for an OTLP/JSON request.
+ *
+ *  - 921110 ("HTTP Request Smuggling Attack") still reads the RAW body of a
+ *    request no processor parsed. After t:urlDecodeUni, t:htmlEntityDecode
+ *    and t:lowercase it looks for
+ *
+ *      <method>\s+(?:/|\w)[^\s]*(?:\s+http/\d|[\r\n])
+ *
+ *    where <method> is get, post, put, head, copy, move, lock, track, trace,
+ *    patch, delete, options, connect and a few more, matched INSIDE words:
+ *    "target", "budget", "widget", "input", "ahead", "remove", "block".
+ *
+ *    A frame is `<envelope JSON>\n<payload>`, and that newline is the [\r\n]
+ *    the rule wants. An envelope whose url was /search/gadget+case reads,
+ *    decoded, `...gadget case","routes":[...]...}\n`: the word, whitespace,
+ *    a run with no whitespace in it, then the frame's own newline - and the
+ *    whole chunk is blocked. So is an identified user called "Bridget
+ *    Jones", a path with a %20 in it, or a %0A anywhere in the body.
+ *
+ * The rule ends either on a line break or on `http/<digit>`. This file
+ * leaves it neither:
+ *
+ *  1. No transform can DECODE a line break out of the body. Every `%` and
+ *     `&` inside a JSON string goes out as its \uXXXX escape, so there is
+ *     nothing for t:urlDecodeUni (%0a, %u000d, ...) or t:htmlEntityDecode
+ *     (&#10;, &#x0d;, ...) to decode, and JSON text never contains a literal
+ *     CR or LF. Applied to the envelope AND to every event of the payload -
+ *     the uncompressed terminal flush is plain JSON too.
+ *
+ *  2. The only line breaks left are the frame separators, and every one of
+ *     them has a SPACE in front of it. A match ending there needs a run of
+ *     non-whitespace characters right before the newline; the space makes
+ *     that run empty. Without it, whatever precedes the newline - the
+ *     envelope, and through it the tail of the previous frame's payload,
+ *     which is text with spaces in it - is exactly such a run.
+ *
+ *  3. The slash of every `http/` goes out as JSON's own `\/` escape, so a
+ *     page that shows an HTTP request line - API documentation printing
+ *     "GET /v1/users HTTP/1.1", recorded verbatim under the default masking
+ *     mode - cannot match through the rule's other ending. With `%` and `&`
+ *     escaped nothing can decode a slash back in front of the digit.
+ *
+ * (1) and (2) are each insufficient alone, and the tests hold all three.
+ * Whitespace itself is left alone on purpose: with nothing left to end on
+ * it cannot complete a match, and escaping it would grow trait values and
+ * DOM text by a sixth or more against the envelope cap and the keepalive
+ * quota.
+ *
+ * A gzip payload is opaque bytes and can contain anything; measured against
+ * CRS 3.3.2, random and real compressed payloads match nothing.
+ *
+ * None of this changes what the server reads. JSON.parse decodes \uXXXX to
+ * the same characters and ignores the space before the newline, and the
+ * envelope parser has always sliced up to the first 0x0A and parsed that -
+ * so every server version accepts these frames, and this server still
+ * accepts frames from recorders that predate them.
+ *
+ * This file must stay dependency-free: it is bundled into the browser
+ * recorder as well as imported by the server. The mobile recorder cannot
+ * import it at all (it is published into customer apps without Common), so
+ * it carries a copy that its ContractParity test holds to this one.
+ */
+
+/*
+ * What ends every envelope line: a space, then the 0x0A separator the
+ * parser splits on. The space is load-bearing - see (2) above.
+ */
+export const SESSION_REPLAY_ENVELOPE_TERMINATOR: string = " \n";
+
+/*
+ * `%`, `&`, and the slash of `http/` in any case. No lookbehind: the
+ * recorder still loads on browsers that cannot parse one.
+ */
+const ESCAPED_SEQUENCES: RegExp = /[%&]|(http)\//gi;
+
+export default class SessionReplayWireEncoding {
+  /*
+   * The complete header line of one frame: the envelope as escaped JSON,
+   * then SESSION_REPLAY_ENVELOPE_TERMINATOR. The payload bytes follow it
+   * directly.
+   *
+   * Byte budgets on the envelope (the recorder's 7 KB, the parser's 8 KB)
+   * are measured on THIS string: each `%` and `&` is six bytes here.
+   *
+   * `unknown` rather than the envelope type: the browser and the mobile
+   * recorder each have their own, and the E2E helpers build theirs loose.
+   * Anything JSON.stringify turns into an object is a valid argument.
+   */
+  public static encodeEnvelopeLine(envelope: unknown): string {
+    return (
+      SessionReplayWireEncoding.escapeJson(JSON.stringify(envelope)) +
+      SESSION_REPLAY_ENVELOPE_TERMINATOR
+    );
+  }
+
+  /*
+   * Rewrite every `%` and `&` in a JSON text as "\u0025" / "\u0026", and
+   * every `http/` as `http\/`. The result parses to exactly the same value.
+   *
+   * A plain global replace is exact for JSON.stringify output: `%`, `&` and
+   * `http/` can only appear inside a string literal, where "\u0025" and "%"
+   * - or "\/" and "/" - are the same string, and a backslash there is always
+   * the first half of an escape pair that none of these characters belongs
+   * to. It is also idempotent, since none of the escapes contains what it
+   * replaces.
+   *
+   * The recorder applies it where it serialises each event rather than on
+   * the way out, so every byte budget downstream - the flush threshold, the
+   * keepalive split, the request cap - measures what is actually sent.
+   */
+  public static escapeJson(json: string): string {
+    return json.replace(
+      ESCAPED_SEQUENCES,
+      (match: string, http: string | undefined): string => {
+        if (http !== undefined) {
+          return `${http}\\/`;
+        }
+
+        return match === "%" ? "\\u0025" : "\\u0026";
+      },
+    );
+  }
+}

package/Utils/Rum/SessionTraceState.ts

@@ -0,0 +1,212 @@
+/*
+ * The replay session id, carried on W3C trace context.
+ *
+ * The browser recorder adds one `tracestate` list member to the requests a
+ * page makes to its own origin:
+ *
+ *   tracestate: oneuptime=sid:<32 hex session id>[;p:<16 hex parent id>]
+ *
+ * tracestate is the one channel a stock OpenTelemetry backend carries
+ * without being told to. Every SDK's W3C propagator extracts it onto the
+ * remote parent, every child span inherits it, every OTLP exporter sends
+ * it as the span's `traceState`, and every outgoing call re-injects it. So
+ * span ingest can stamp Span.sessionId for every service a browser request
+ * touched, with no code in the customer's backend. (OTLP log records carry
+ * no trace state; logs are joined to a session by trace id instead.)
+ *
+ * `p` is present only when the recorder MINTED the traceparent. Its parent
+ * id then names a browser span that is never exported, so the backend's
+ * entry span would otherwise arrive pointing at a parent that does not
+ * exist: never a root span, flagged as missing its parent. Ingest treats a
+ * span whose parent is exactly `p` as the root it really is.
+ *
+ * Both halves live here so the recorder that writes the member and the
+ * ingest that reads it cannot drift. Standalone functions rather than
+ * class statics, because the recorder bundle tree-shakes unused exports
+ * but not unused statics - the recorder imports only the builder.
+ *
+ * Dependency-free: bundled into the browser recorder as well as imported
+ * by the server.
+ */
+
+/* The list-member key. A valid W3C tracestate simple key. */
+export const SESSION_TRACE_STATE_KEY: string = "oneuptime";
+
+/*
+ * Hostile-input bounds for the parser. W3C caps a well-formed header at 32
+ * members, and the OpenTelemetry JS SDK at 512 characters, but other SDKs
+ * only cap member count and member length, so a legitimate value carrying
+ * other vendors' members can be longer than 512. Past these a value is not
+ * one the recorder wrote, so no session is read out of it - but our
+ * members are still stripped from it.
+ */
+const MAX_TRACE_STATE_LENGTH: number = 8192;
+const MAX_TRACE_STATE_MEMBERS: number = 64;
+
+const SESSION_ID_PATTERN: RegExp = /^[0-9a-f]{32}$/;
+const PARENT_SPAN_ID_PATTERN: RegExp = /^[0-9a-f]{16}$/;
+const ALL_ZERO_PATTERN: RegExp = /^0+$/;
+
+export interface SessionTraceState {
+  /* 32 lowercase hex characters. */
+  sessionId: string;
+
+  /*
+   * 16 lowercase hex characters: the parent id of a traceparent the
+   * recorder minted, which no exported span carries. null when the
+   * traceparent came from the page or its own instrumentation.
+   */
+  syntheticParentSpanId: string | null;
+}
+
+export interface ParsedSessionTraceState {
+  /* The session member, or null when there is none or it is malformed. */
+  sessionTraceState: SessionTraceState | null;
+
+  /*
+   * The trace state with every `oneuptime` member removed, so the session
+   * id is stored in exactly one column - the one erasure deletes by -
+   * rather than also in the raw trace state. Other vendors' members are
+   * kept verbatim (trimmed of optional whitespace), in order.
+   */
+  remainingTraceState: string;
+}
+
+/*
+ * The tracestate list member for a session. Callers pass recorder-minted
+ * values (a 32-hex session id, a 16-hex parent id); nothing here needs
+ * escaping, because hex and the ':' / ';' separators are all legal in a
+ * tracestate value.
+ */
+export function buildSessionTraceStateMember(
+  sessionId: string,
+  syntheticParentSpanId?: string | null,
+): string {
+  return (
+    SESSION_TRACE_STATE_KEY +
+    "=sid:" +
+    sessionId +
+    (syntheticParentSpanId ? ";p:" + syntheticParentSpanId : "")
+  );
+}
+
+/*
+ * Read the session member out of a span's trace state.
+ *
+ * Accepts anything, because the value comes from an OTLP body a customer
+ * (or anyone holding an ingestion key) controls: a non-string, an
+ * oversized string or a malformed member yields no session and never
+ * throws. The first `oneuptime` member wins, as in the W3C rule that a
+ * vendor's own member is the left-most one; fields inside it are
+ * `name:value` pairs separated by ';', in any order, and unknown fields are
+ * ignored so the format can grow.
+ */
+export function parseSessionTraceState(
+  traceState: unknown,
+): ParsedSessionTraceState {
+  if (typeof traceState !== "string") {
+    return { sessionTraceState: null, remainingTraceState: "" };
+  }
+
+  /*
+   * Fast path, and the path almost every span takes: no member of ours,
+   * nothing to parse and nothing to strip.
+   */
+  if (traceState.indexOf(SESSION_TRACE_STATE_KEY) === -1) {
+    return { sessionTraceState: null, remainingTraceState: traceState };
+  }
+
+  const members: Array<string> = traceState.split(",");
+
+  /*
+   * Past the bounds nothing is READ as a session - a value this far out of
+   * spec is not one the recorder wrote - but our members are still
+   * stripped, so an id cannot survive in the raw trace state just because
+   * the value around it was oversized.
+   */
+  const isWithinBounds: boolean =
+    traceState.length <= MAX_TRACE_STATE_LENGTH &&
+    members.length <= MAX_TRACE_STATE_MEMBERS;
+
+  let sessionTraceState: SessionTraceState | null = null;
+  let sawSessionMember: boolean = false;
+  const remaining: Array<string> = [];
+
+  for (const rawMember of members) {
+    const member: string = rawMember.trim();
+
+    if (member === "") {
+      continue;
+    }
+
+    const equalsIndex: number = member.indexOf("=");
+    const key: string =
+      equalsIndex === -1 ? member : member.slice(0, equalsIndex).trim();
+
+    if (key !== SESSION_TRACE_STATE_KEY) {
+      remaining.push(member);
+      continue;
+    }
+
+    /*
+     * Every member under our key is stripped, parsed or not: a malformed
+     * one can still hold an id, and the point of stripping is that no id
+     * survives outside the sessionId column.
+     */
+    if (isWithinBounds && !sawSessionMember && equalsIndex !== -1) {
+      sessionTraceState = readSessionMemberValue(member.slice(equalsIndex + 1));
+    }
+
+    sawSessionMember = true;
+  }
+
+  return {
+    sessionTraceState: sessionTraceState,
+    remainingTraceState: remaining.join(","),
+  };
+}
+
+function readSessionMemberValue(value: string): SessionTraceState | null {
+  let sessionId: string | null = null;
+  let syntheticParentSpanId: string | null = null;
+
+  for (const rawField of value.split(";")) {
+    const field: string = rawField.trim();
+    const colonIndex: number = field.indexOf(":");
+
+    if (colonIndex === -1) {
+      continue;
+    }
+
+    const name: string = field.slice(0, colonIndex);
+    const fieldValue: string = field.slice(colonIndex + 1).toLowerCase();
+
+    if (name === "sid" && sessionId === null) {
+      if (!SESSION_ID_PATTERN.test(fieldValue)) {
+        return null;
+      }
+
+      sessionId = fieldValue;
+    } else if (name === "p" && syntheticParentSpanId === null) {
+      /*
+       * A malformed parent id costs only the root-span repair, never the
+       * session: the session id is what the member is for.
+       */
+      if (
+        PARENT_SPAN_ID_PATTERN.test(fieldValue) &&
+        !ALL_ZERO_PATTERN.test(fieldValue)
+      ) {
+        syntheticParentSpanId = fieldValue;
+      }
+    }
+  }
+
+  if (sessionId === null || ALL_ZERO_PATTERN.test(sessionId)) {
+    return null;
+  }
+
+  return {
+    sessionId: sessionId,
+    syntheticParentSpanId: syntheticParentSpanId,
+  };
+}