@oneuptime/common 13.0.4 → 13.0.5

package/Tests/Server/Utils/Telemetry/TraceContextPropagation.test.ts

@@ -0,0 +1,420 @@
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  test,
+} from "@jest/globals";
+import {
+  Span,
+  SpanKind,
+  SpanStatusCode,
+  context,
+  propagation,
+  trace,
+} from "@opentelemetry/api";
+import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";
+import { W3CTraceContextPropagator } from "@opentelemetry/core";
+import {
+  BasicTracerProvider,
+  InMemorySpanExporter,
+  ReadableSpan,
+  SimpleSpanProcessor,
+} from "@opentelemetry/sdk-trace-base";
+import { EventEmitter } from "events";
+import TraceContextPropagation, {
+  resolvePropagationHosts,
+  serverSpanName,
+  shouldTraceIncomingRequest,
+} from "../../../../Server/Utils/Telemetry/TraceContextPropagation";
+import API, { OutgoingRequest } from "../../../../Utils/API";
+import HTTPResponse from "../../../../Types/API/HTTPResponse";
+import HTTPErrorResponse from "../../../../Types/API/HTTPErrorResponse";
+import HTTPMethod from "../../../../Types/API/HTTPMethod";
+import { JSONObject } from "../../../../Types/JSON";
+import Dictionary from "../../../../Types/Dictionary";
+import {
+  ExpressRequest,
+  ExpressResponse,
+} from "../../../../Server/Utils/Express";
+import getJestMockFunction, { MockFunction } from "../../../MockType";
+
+/*
+ * OneUptime's processes only show up connected on a service map when an
+ * incoming request joins its caller's trace and an outgoing request hands
+ * its trace on. These tests drive both halves through a real OpenTelemetry
+ * tracer, W3C propagator and async context manager.
+ *
+ * The outgoing half shares a client with monitor checks, webhooks and
+ * workflow calls to customer endpoints, so the allowlist tests matter as much
+ * as the propagation ones: a customer endpoint must never receive a header it
+ * did not configure.
+ */
+
+const exporter: InMemorySpanExporter = new InMemorySpanExporter();
+const provider: BasicTracerProvider = new BasicTracerProvider({
+  spanProcessors: [new SimpleSpanProcessor(exporter)],
+});
+const contextManager: AsyncLocalStorageContextManager =
+  new AsyncLocalStorageContextManager();
+
+const CALLER_TRACE_ID: string = "4bf92f3577b34da6a3ce929d0e0e4736";
+const CALLER_SPAN_ID: string = "00f067aa0ba902b7";
+
+beforeAll(() => {
+  contextManager.enable();
+  context.setGlobalContextManager(contextManager);
+  propagation.setGlobalPropagator(new W3CTraceContextPropagator());
+  trace.setGlobalTracerProvider(provider);
+});
+
+afterAll(() => {
+  trace.disable();
+  propagation.disable();
+  context.disable();
+});
+
+beforeEach(() => {
+  exporter.reset();
+  TraceContextPropagation.setActiveOverride(true);
+  TraceContextPropagation.resetPropagationHosts({
+    ONEUPTIME_URL: "http://oneuptime-app.oneuptime.svc.cluster.local:3002",
+    HOST: "status.example.com",
+  });
+});
+
+afterEach(() => {
+  TraceContextPropagation.setActiveOverride(null);
+  TraceContextPropagation.resetPropagationHosts();
+  API.setOutgoingRequestTracer(null);
+});
+
+interface FakeResponse extends EventEmitter {
+  statusCode: number;
+}
+
+function fakeRequest(
+  overrides: Partial<ExpressRequest> & JSONObject,
+): ExpressRequest {
+  return {
+    method: "POST",
+    path: "/probe-ingest/response",
+    hostname: "oneuptime-app.oneuptime.svc.cluster.local",
+    protocol: "http",
+    headers: {},
+    ...overrides,
+  } as unknown as ExpressRequest;
+}
+
+function fakeResponse(statusCode: number): FakeResponse {
+  const response: FakeResponse = new EventEmitter() as FakeResponse;
+  response.statusCode = statusCode;
+  return response;
+}
+
+function finishedSpans(): Array<ReadableSpan> {
+  return exporter.getFinishedSpans();
+}
+
+describe("resolvePropagationHosts", () => {
+  test("collects OneUptime's own hosts from URLs and hostnames", () => {
+    expect(
+      Array.from(
+        resolvePropagationHosts({
+          ONEUPTIME_URL: "https://oneuptime.example.com/",
+          PROBE_INGEST_URL: "http://ingest.internal:3400/probe-ingest",
+          TELEMETRY_WRITER_URL:
+            "http://oneuptime-telemetry-writer.oneuptime.svc.cluster.local:3300",
+          HOST: "OneUptime.Example.com",
+          SERVER_APP_HOSTNAME: "app",
+          SERVER_HOME_HOSTNAME: "home",
+          OPENTELEMETRY_TRACE_PROPAGATION_HOSTS: " gateway.internal , ,api:80 ",
+        }),
+      ).sort(),
+    ).toEqual(
+      [
+        "api",
+        "app",
+        "gateway.internal",
+        "home",
+        "ingest.internal",
+        "oneuptime-telemetry-writer.oneuptime.svc.cluster.local",
+        "oneuptime.example.com",
+      ].sort(),
+    );
+  });
+
+  test("never allows loopback, where unset hostname variables default", () => {
+    expect(
+      Array.from(
+        resolvePropagationHosts({
+          SERVER_APP_HOSTNAME: "localhost",
+          ONEUPTIME_URL: "http://127.0.0.1:3002",
+        }),
+      ),
+    ).toEqual([]);
+  });
+});
+
+describe("shouldTraceIncomingRequest", () => {
+  test.each([
+    ["GET", "/api/monitor/get-list", true],
+    ["POST", "/otlp/v1/traces", true],
+    ["OPTIONS", "/api/monitor/get-list", false],
+    ["HEAD", "/", false],
+    ["GET", "/status/live", false],
+    ["GET", "/api/status/ready", false],
+    ["GET", "/metrics", false],
+    ["GET", "/dashboard/assets/app.3f9a.js", false],
+    ["GET", "/fonts/inter.woff2", false],
+    ["GET", "/status-page/overview", true],
+  ])("%s %s → %s", (method: string, path: string, expected: boolean) => {
+    expect(shouldTraceIncomingRequest({ method, path })).toBe(expected);
+  });
+});
+
+describe("serverSpanName", () => {
+  test("uses the matched route template, never the raw path", () => {
+    expect(
+      serverSpanName({
+        method: "get",
+        baseUrl: "/api/monitor",
+        route: { path: "/:id" },
+      }),
+    ).toEqual({ name: "GET /api/monitor/:id", route: "/api/monitor/:id" });
+  });
+
+  test("falls back to the method when nothing matched", () => {
+    expect(serverSpanName({ method: "post" })).toEqual({
+      name: "POST",
+      route: null,
+    });
+  });
+});
+
+describe("incoming requests", () => {
+  test("continue the caller's trace in a SERVER span", async () => {
+    const request: ExpressRequest = fakeRequest({
+      headers: {
+        traceparent: `00-${CALLER_TRACE_ID}-${CALLER_SPAN_ID}-01`,
+      },
+    });
+    const response: FakeResponse = fakeResponse(200);
+    let activeTraceId: string | undefined = undefined;
+
+    TraceContextPropagation.incomingRequestMiddleware(
+      request,
+      response as unknown as ExpressResponse,
+      () => {
+        activeTraceId = trace.getActiveSpan()?.spanContext().traceId;
+        (request as unknown as { route: { path: string } }).route = {
+          path: "/response",
+        };
+        (request as unknown as { baseUrl: string }).baseUrl = "/probe-ingest";
+      },
+    );
+    response.emit("finish");
+    response.emit("close");
+
+    expect(activeTraceId).toBe(CALLER_TRACE_ID);
+    const spans: Array<ReadableSpan> = finishedSpans();
+    expect(spans).toHaveLength(1);
+    const span: ReadableSpan = spans[0]!;
+    expect(span.kind).toBe(SpanKind.SERVER);
+    expect(span.spanContext().traceId).toBe(CALLER_TRACE_ID);
+    expect(span.parentSpanContext?.spanId).toBe(CALLER_SPAN_ID);
+    expect(span.name).toBe("POST /probe-ingest/response");
+    expect(span.attributes).toMatchObject({
+      "http.request.method": "POST",
+      "http.route": "/probe-ingest/response",
+      "http.response.status_code": 200,
+      "server.address": "oneuptime-app.oneuptime.svc.cluster.local",
+    });
+    expect(span.status.code).not.toBe(SpanStatusCode.ERROR);
+  });
+
+  test("start a new trace when the caller sent none", () => {
+    const response: FakeResponse = fakeResponse(204);
+    TraceContextPropagation.incomingRequestMiddleware(
+      fakeRequest({}),
+      response as unknown as ExpressResponse,
+      () => {},
+    );
+    response.emit("finish");
+    const span: ReadableSpan = finishedSpans()[0]!;
+    expect(span.parentSpanContext).toBeUndefined();
+    expect(span.name).toBe("POST");
+  });
+
+  test("mark only 5xx answers as errors", () => {
+    for (const status of [404, 503]) {
+      const response: FakeResponse = fakeResponse(status);
+      TraceContextPropagation.incomingRequestMiddleware(
+        fakeRequest({}),
+        response as unknown as ExpressResponse,
+        () => {},
+      );
+      response.emit("finish");
+    }
+    const [clientError, serverError]: Array<ReadableSpan> = finishedSpans();
+    expect(clientError!.status.code).not.toBe(SpanStatusCode.ERROR);
+    expect(serverError!.status.code).toBe(SpanStatusCode.ERROR);
+  });
+
+  test("spans nested work under the request", () => {
+    const response: FakeResponse = fakeResponse(200);
+    TraceContextPropagation.incomingRequestMiddleware(
+      fakeRequest({}),
+      response as unknown as ExpressResponse,
+      () => {
+        trace
+          .getTracer("test")
+          .startActiveSpan("DatabaseService.findBy", (child: Span) => {
+            child.end();
+          });
+      },
+    );
+    response.emit("finish");
+    const [child, server]: Array<ReadableSpan> = finishedSpans();
+    expect(child!.name).toBe("DatabaseService.findBy");
+    expect(child!.parentSpanContext?.spanId).toBe(server!.spanContext().spanId);
+  });
+
+  test("do nothing when span export is off or the request is ignored", () => {
+    const next: MockFunction = getJestMockFunction();
+    TraceContextPropagation.setActiveOverride(false);
+    TraceContextPropagation.incomingRequestMiddleware(
+      fakeRequest({}),
+      fakeResponse(200) as unknown as ExpressResponse,
+      next as unknown as () => void,
+    );
+    TraceContextPropagation.setActiveOverride(true);
+    TraceContextPropagation.incomingRequestMiddleware(
+      fakeRequest({ method: "GET", path: "/status/live" }),
+      fakeResponse(200) as unknown as ExpressResponse,
+      next as unknown as () => void,
+    );
+    expect(next).toHaveBeenCalledTimes(2);
+    expect(finishedSpans()).toHaveLength(0);
+  });
+});
+
+describe("outgoing requests", () => {
+  function captureTracer(): {
+    run: (
+      url: string,
+      result?: HTTPResponse<JSONObject> | Error,
+    ) => Promise<Dictionary<string>>;
+  } {
+    TraceContextPropagation.installOutgoingRequestTracer();
+    const tracer: {
+      trace: <T>(
+        request: OutgoingRequest,
+        send: () => Promise<T>,
+      ) => Promise<T>;
+    } = (
+      API as unknown as {
+        outgoingRequestTracer: {
+          trace: <T>(
+            request: OutgoingRequest,
+            send: () => Promise<T>,
+          ) => Promise<T>;
+        };
+      }
+    ).outgoingRequestTracer;
+    return {
+      run: async (
+        url: string,
+        result?: HTTPResponse<JSONObject> | Error,
+      ): Promise<Dictionary<string>> => {
+        const headers: Dictionary<string> = {};
+        const send: () => Promise<HTTPResponse<JSONObject>> = async () => {
+          if (result instanceof Error) {
+            throw result;
+          }
+          return result || new HTTPResponse<JSONObject>(200, {}, {});
+        };
+        await tracer
+          .trace({ method: HTTPMethod.POST, url, headers }, send)
+          .catch(() => {});
+        return headers;
+      },
+    };
+  }
+
+  test("inject traceparent and record a CLIENT span for OneUptime hosts", async () => {
+    const { run } = captureTracer();
+    const headers: Dictionary<string> = await run(
+      "http://oneuptime-app.oneuptime.svc.cluster.local:3002/probe-ingest/response?token=secret",
+    );
+
+    const span: ReadableSpan = finishedSpans()[0]!;
+    expect(span.kind).toBe(SpanKind.CLIENT);
+    expect(headers["traceparent"]).toBe(
+      `00-${span.spanContext().traceId}-${span.spanContext().spanId}-01`,
+    );
+    expect(span.attributes).toEqual({
+      "http.request.method": "POST",
+      "server.address": "oneuptime-app.oneuptime.svc.cluster.local",
+      "server.port": 3002,
+      "url.scheme": "http",
+      "http.response.status_code": 200,
+    });
+    // No path, query string or credentials ever reach the span.
+    expect(JSON.stringify(span.attributes)).not.toContain("secret");
+  });
+
+  test("continue the active trace", async () => {
+    const { run } = captureTracer();
+    let parentSpanId: string = "";
+    let headers: Dictionary<string> = {};
+    await trace
+      .getTracer("test")
+      .startActiveSpan("ProbeIngest.send", async (parent: Span) => {
+        parentSpanId = parent.spanContext().spanId;
+        headers = await run("https://status.example.com/api/probe/alive");
+        parent.end();
+      });
+    const client: ReadableSpan | undefined = finishedSpans().find(
+      (span: ReadableSpan) => {
+        return span.kind === SpanKind.CLIENT;
+      },
+    );
+    expect(client?.parentSpanContext?.spanId).toBe(parentSpanId);
+    expect(headers["traceparent"]).toContain(client!.spanContext().traceId);
+  });
+
+  test("leave customer endpoints untouched", async () => {
+    const { run } = captureTracer();
+    const headers: Dictionary<string> = await run(
+      "https://hooks.customer.example/webhook/abc",
+    );
+    expect(headers).toEqual({});
+    expect(finishedSpans()).toHaveLength(0);
+  });
+
+  test("leave every endpoint untouched when span export is off", async () => {
+    const { run } = captureTracer();
+    TraceContextPropagation.setActiveOverride(false);
+    const headers: Dictionary<string> = await run(
+      "https://status.example.com/api/probe/alive",
+    );
+    expect(headers).toEqual({});
+    expect(finishedSpans()).toHaveLength(0);
+  });
+
+  test("mark HTTP error answers and thrown failures as errors", async () => {
+    const { run } = captureTracer();
+    await run(
+      "https://status.example.com/api/x",
+      new HTTPErrorResponse(502, {}, {}),
+    );
+    await run("https://status.example.com/api/y", new Error("ECONNRESET"));
+    const [badGateway, reset]: Array<ReadableSpan> = finishedSpans();
+    expect(badGateway!.attributes["http.response.status_code"]).toBe(502);
+    expect(badGateway!.status.code).toBe(SpanStatusCode.ERROR);
+    expect(reset!.status.code).toBe(SpanStatusCode.ERROR);
+  });
+});

package/Tests/Types/Rum/SessionReplayApiContracts.test.ts

@@ -8,6 +8,7 @@ import {
   SESSION_REPLAY_SORT_BY_VALUES,
   SessionReplayChunksRequestDto,
   SessionReplayExceptionSessionDto,
+  SessionReplayForExceptionRequestDto,
   SessionReplayForExceptionResponseDto,
   SessionReplayHeartbeatResponseDto,
   SessionReplayListFiltersDto,
@@ -38,10 +39,12 @@ import {
   readDtoStringMap,
   readDtoUnixMs,
 } from "../../../Types/Rum/SessionReplayApi";
+import ServiceType from "../../../Types/Telemetry/ServiceType";
 import {
   SESSION_REPLAY_VISITOR_ID_PATTERN,
   SessionReplayChunkManifestEntry,
 } from "../../../Types/Rum/SessionReplay";
+import { JSONObject } from "../../../Types/JSON";
 
 /*
  * The DTOs are the wire between the Dashboard and TelemetryAPI's
@@ -256,6 +259,17 @@ describe("SessionReplayApi DTOs - today's wire shapes satisfy them", () => {
     expect(legacyHeartbeat.secondsWatched).toBe(30);
   });
 
+  it("a scoped /for-exception request carries both entity identifiers", () => {
+    const request: SessionReplayForExceptionRequestDto = {
+      fingerprint: "fp-1",
+      primaryEntityId: "service-1",
+      primaryEntityType: ServiceType.OpenTelemetry,
+    };
+
+    expect(request.primaryEntityId).toBe("service-1");
+    expect(request.primaryEntityType).toBe(ServiceType.OpenTelemetry);
+  });
+
   it("the additive list and manifest fields are all optional and carry the documented types", () => {
     const richItem: SessionReplayListItemDto = {
       ...legacyListItem,
@@ -431,6 +445,65 @@ describe("SessionReplayApi - the additive contracts the surfaces already ship",
     expect(neverIdentified.visitorId).toBe("");
   });
 
+  /*
+   * "Not finalized" is not "still recording". A closed tab's session stays
+   * unfinalized until the finalizer runs, so /list and /manifest now also
+   * say whether every tab of it has ended. Additive on both: an older
+   * server answers without it, and the Dashboard then falls back to
+   * reading "not finalized" as "recording", which is what it always did.
+   */
+  it("/list and /manifest: hasRecordingEnded is additive, and an older payload without it still parses", () => {
+    expect(legacyListItem.hasRecordingEnded).toBeUndefined();
+    expect(legacyHeader.hasRecordingEnded).toBeUndefined();
+
+    /* A payload exactly as an older server sends it, through the wire. */
+    const olderListWire: JSONObject = JSON.parse(
+      JSON.stringify({ ...legacyListItem, isFinalized: false }),
+    ) as JSONObject;
+    const olderHeaderWire: JSONObject = JSON.parse(
+      JSON.stringify({ ...legacyHeader, isFinalized: false }),
+    ) as JSONObject;
+
+    expect("hasRecordingEnded" in olderListWire).toBe(false);
+    expect("hasRecordingEnded" in olderHeaderWire).toBe(false);
+    /* The defensive reader turns "absent" into "not known to have ended". */
+    expect(readDtoBoolean(olderListWire, "hasRecordingEnded")).toBe(false);
+    expect(readDtoBoolean(olderHeaderWire, "hasRecordingEnded")).toBe(false);
+
+    const olderListItem: SessionReplayListItemDto =
+      olderListWire as unknown as SessionReplayListItemDto;
+    expect(olderListItem.isFinalized).toBe(false);
+    expect(olderListItem.hasRecordingEnded).toBeUndefined();
+
+    /* A current server: a closed tab's unfinalized session. */
+    const endedItem: SessionReplayListItemDto = {
+      ...legacyListItem,
+      isFinalized: false,
+      hasRecordingEnded: true,
+    };
+    const liveItem: SessionReplayListItemDto = {
+      ...legacyListItem,
+      isFinalized: false,
+      hasRecordingEnded: false,
+    };
+    const endedHeader: SessionReplayManifestHeaderDto = {
+      ...legacyHeader,
+      isFinalized: false,
+      hasRecordingEnded: true,
+    };
+
+    const endedWire: JSONObject = JSON.parse(
+      JSON.stringify(endedItem),
+    ) as JSONObject;
+    const endedHeaderWire: JSONObject = JSON.parse(
+      JSON.stringify(endedHeader),
+    ) as JSONObject;
+
+    expect(readDtoBoolean(endedWire, "hasRecordingEnded")).toBe(true);
+    expect(readDtoBoolean(endedHeaderWire, "hasRecordingEnded")).toBe(true);
+    expect(liveItem.hasRecordingEnded).toBe(false);
+  });
+
   /*
    * POST /telemetry/rum/session-replay/users: the list rolled up by
    * person. Its own route because a keyset page of sessions cannot be

package/Tests/Types/Rum/SessionReplayTransportContracts.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, test } from "@jest/globals";
+import {
+  SESSION_REPLAY_MOBILE_APP_IDENTIFIER_HEADER,
+  SESSION_REPLAY_MOBILE_RECORDER_CAPABILITIES,
+  SESSION_REPLAY_RECORDER_CAPABILITIES,
+  SESSION_REPLAY_RECORDER_KIND_HEADER,
+  SessionReplayFidelityNotice,
+  parseSessionReplayRecorderKindHeader,
+} from "../../../Types/Rum/SessionReplay";
+
+describe("session replay recorder transport contract", () => {
+  test("pins the public native request header names", () => {
+    expect(SESSION_REPLAY_RECORDER_KIND_HEADER).toBe(
+      "x-oneuptime-replay-recorder-kind",
+    );
+    expect(SESSION_REPLAY_MOBILE_APP_IDENTIFIER_HEADER).toBe(
+      "x-oneuptime-mobile-app-identifier",
+    );
+  });
+
+  test.each([undefined, null])(
+    "treats an absent recorder-kind header (%s) as the legacy DOM recorder",
+    (value: undefined | null) => {
+      expect(parseSessionReplayRecorderKindHeader(value)).toBe("dom");
+    },
+  );
+
+  test.each([
+    ["dom", "dom"],
+    ["rn-view-tree", "rn-view-tree"],
+  ])("accepts exact supported kind %s", (value: string, expected: string) => {
+    expect(parseSessionReplayRecorderKindHeader(value)).toBe(expected);
+  });
+
+  test.each([
+    "",
+    "DOM",
+    "RN-VIEW-TREE",
+    "rn_view_tree",
+    " rn-view-tree",
+    "rn-view-tree ",
+    "browser",
+    "mobile",
+  ])("rejects unknown or non-exact recorder kind %j", (value: string) => {
+    expect(parseSessionReplayRecorderKindHeader(value)).toBeNull();
+  });
+
+  test("rejects a repeated/non-scalar recorder-kind header", () => {
+    expect(
+      parseSessionReplayRecorderKindHeader(["rn-view-tree", "dom"]),
+    ).toBeNull();
+    expect(parseSessionReplayRecorderKindHeader({ value: "dom" })).toBeNull();
+  });
+
+  test("pins the capabilities emitted by the native recorder", () => {
+    expect(SESSION_REPLAY_MOBILE_RECORDER_CAPABILITIES).toEqual([
+      "mobile-view-tree",
+      "mobile-touch-events",
+      "custom-events",
+      "traits",
+      "tags",
+      "visibility",
+      "visitor-id",
+      "route-events",
+      "js-errors",
+    ]);
+    expect(new Set(SESSION_REPLAY_MOBILE_RECORDER_CAPABILITIES).size).toBe(
+      SESSION_REPLAY_MOBILE_RECORDER_CAPABILITIES.length,
+    );
+  });
+
+  test("keeps mobile-only capabilities out of the web recorder baseline", () => {
+    expect(SESSION_REPLAY_RECORDER_CAPABILITIES).not.toContain(
+      "mobile-view-tree",
+    );
+    expect(SESSION_REPLAY_RECORDER_CAPABILITIES).not.toContain(
+      "mobile-touch-events",
+    );
+  });
+
+  test("pins mobile fidelity disclosure codes as additive wire values", () => {
+    expect(SessionReplayFidelityNotice.MobileImagesOpaque).toBe(
+      "mobile-images-opaque",
+    );
+    expect(SessionReplayFidelityNotice.MobileWebViewOpaque).toBe(
+      "mobile-webview-opaque",
+    );
+    expect(SessionReplayFidelityNotice.MobileCanvasOpaque).toBe(
+      "mobile-canvas-opaque",
+    );
+    expect(SessionReplayFidelityNotice.MobileAnimationSampled).toBe(
+      "mobile-animation-sampled",
+    );
+  });
+});

package/Tests/Types/SecurityEvent/Connectors/ConnectorDiagnostics.test.ts

@@ -0,0 +1,82 @@
+import {
+  SecurityConnectorCheck,
+  SecurityConnectorCheckStatus,
+  summarizeCheckStatuses,
+} from "../../../../Types/SecurityEvent/Connectors/ConnectorDiagnostics";
+import { describe, expect, test } from "@jest/globals";
+
+/*
+ * The report verdict is folded from the checks. The rule is what the modal
+ * banner shows, so it is pinned: any failure fails the report, otherwise
+ * any warning makes it a warning, and skips are neutral (a skipped step is
+ * explained by the failure that caused it, never counted twice).
+ */
+
+function check(
+  status: SecurityConnectorCheckStatus,
+  key: string = status,
+): SecurityConnectorCheck {
+  return {
+    key,
+    name: key,
+    status,
+    durationMs: 1,
+    message: `${key} ${status}`,
+  };
+}
+
+describe("summarizeCheckStatuses", () => {
+  test("no checks is a pass (nothing failed, nothing warned)", () => {
+    expect(summarizeCheckStatuses([])).toBe("pass");
+  });
+
+  test("all passing checks pass", () => {
+    expect(summarizeCheckStatuses([check("pass"), check("pass")])).toBe("pass");
+  });
+
+  test("skips alone are neutral and leave the report passing", () => {
+    expect(summarizeCheckStatuses([check("skip")])).toBe("pass");
+    expect(summarizeCheckStatuses([check("pass"), check("skip")])).toBe("pass");
+  });
+
+  test("a single warning turns the report into a warning", () => {
+    expect(
+      summarizeCheckStatuses([check("pass"), check("warn"), check("skip")]),
+    ).toBe("warn");
+  });
+
+  test("a single failure wins over any number of passes and warnings", () => {
+    expect(
+      summarizeCheckStatuses([
+        check("pass"),
+        check("warn"),
+        check("fail"),
+        check("warn"),
+        check("skip"),
+      ]),
+    ).toBe("fail");
+  });
+
+  test("order does not matter", () => {
+    const statuses: Array<SecurityConnectorCheckStatus> = [
+      "warn",
+      "pass",
+      "fail",
+    ];
+
+    expect(
+      summarizeCheckStatuses(
+        statuses.map((status: SecurityConnectorCheckStatus) => {
+          return check(status);
+        }),
+      ),
+    ).toBe("fail");
+    expect(
+      summarizeCheckStatuses(
+        [...statuses].reverse().map((status: SecurityConnectorCheckStatus) => {
+          return check(status);
+        }),
+      ),
+    ).toBe("fail");
+  });
+});