@oneuptime/common 11.7.3 → 12.0.0

package/build/dist/Server/API/TelemetryAPI.js

@@ -1,5 +1,5 @@
 import UserMiddleware from "../Middleware/UserAuthorization";
-import Express from "../Utils/Express";
+import Express, { getClientIp, } from "../Utils/Express";
 import Response from "../Utils/Response";
 import BadDataException from "../../Types/Exception/BadDataException";
 import CommonAPI from "./CommonAPI";
@@ -14,10 +14,24 @@ import PprofEncoder from "../Utils/Profile/PprofEncoder";
 import ProfileService from "../Services/ProfileService";
 import ProfileSampleService from "../Services/ProfileSampleService";
 import SortOrder from "../../Types/BaseDatabase/SortOrder";
-import Permission from "../../Types/Permission";
+import Permission, { PermissionHelper, } from "../../Types/Permission";
+import DatabaseCommonInteractionPropsUtil, { PermissionType, } from "../../Types/BaseDatabase/DatabaseCommonInteractionPropsUtil";
+import NotAuthorizedException from "../../Types/Exception/NotAuthorizedException";
+import PaymentRequiredException from "../../Types/Exception/PaymentRequiredException";
+import PermissionScope from "../../Types/Database/AccessControl/PermissionScope";
+import SubscriptionPlan from "../../Types/Billing/SubscriptionPlan";
+import { IsBillingEnabled, getAllEnvVars } from "../EnvironmentConfig";
+import RumSession from "../../Models/AnalyticsModels/RumSession";
 import ObjectID from "../../Types/ObjectID";
 import OneUptimeDate from "../../Types/Date";
 import ResourceFacetResolver from "../Utils/Telemetry/ResourceFacetResolver";
+import RumApplicationService from "../Services/RumApplicationService";
+import ProjectService from "../Services/ProjectService";
+import SessionReplayTargeting from "../Utils/SessionReplay/SessionReplayTargeting";
+import SessionReplayUsage from "../Utils/SessionReplay/SessionReplayUsage";
+import RumSessionReplayViewService from "../Services/RumSessionReplayViewService";
+import SessionReplayReadService, { DEFAULT_SESSION_REPLAY_LIST_LIMIT, MAX_SESSION_REPLAY_FOR_EXCEPTION_LIMIT, } from "../Utils/SessionReplay/SessionReplayReadService";
+import { DEFAULT_SESSION_REPLAY_MAX_BYTES_PER_PROJECT_PER_DAY, MAX_SESSION_REPLAY_CHUNKS_PER_READ, MAX_SESSION_REPLAY_READ_BYTES, } from "../../Types/Rum/SessionReplay";
 const router = Express.getRouter();
 const createTelemetryReadAccessGuard = (signalReadPermission) => {
     return [
@@ -377,6 +391,37 @@ function parseTraceFilterBody(body) {
         }
         return Object.fromEntries(entries);
     };
+    /*
+     * Exact attribute predicates accept a single value or a list of values
+     * (`IN (...)`) — a multi-select dashboard variable resolves to the latter.
+     * Non-string array entries are dropped, and an array left empty by that
+     * filtering is dropped entirely so it cannot narrow to nothing.
+     */
+    const attributeFilterRecord = () => {
+        const raw = body["attributes"];
+        if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+            return undefined;
+        }
+        const filters = {};
+        for (const [key, value] of Object.entries(raw)) {
+            if (typeof value === "string") {
+                filters[key] = value;
+                continue;
+            }
+            if (Array.isArray(value)) {
+                const values = value.filter((v) => {
+                    return typeof v === "string";
+                });
+                if (values.length > 0) {
+                    filters[key] = values;
+                }
+            }
+        }
+        if (Object.keys(filters).length === 0) {
+            return undefined;
+        }
+        return filters;
+    };
     return {
         serviceIds,
         entityKeys: stringArray("entityKeys"),
@@ -416,7 +461,7 @@ function parseTraceFilterBody(body) {
             ? body["exactDurationNano"]
             : undefined,
         rootOnly: body["rootOnly"] === undefined ? undefined : Boolean(body["rootOnly"]),
-        attributes: stringRecord("attributes"),
+        attributes: attributeFilterRecord(),
         attributeSearches: stringRecord("attributeSearches"),
     };
 }
@@ -1648,5 +1693,897 @@ router.post("/telemetry/profiles/breakdown", ...requireProfileReadAccess, async
         next(err);
     }
 });
+/*
+ * ---------------------------------------------------------------------
+ * Session replay playback
+ * ---------------------------------------------------------------------
+ *
+ * These five routes are the ONLY reader of RumSessionV1 / RumSessionChunkV1:
+ * both analytics models deliberately omit `crudApiPath`, so there is no
+ * generic CRUD surface for them and ModelPermission is NEVER invoked on
+ * this path.
+ *
+ * That has a consequence which is easy to get wrong and expensive to get
+ * wrong: the `payload` column's own read ACL and the narrower ACL on
+ * `identifiedUserLabel` are, on their own, decorative here. Nothing
+ * enforces them unless this file does. Hence a dedicated guard rather
+ * than createTelemetryReadAccessGuard above, whose OR-list already
+ * contains ProjectMember, Viewer and TelemetryViewer - reusing it would
+ * let every read-only member of a project watch recordings of that
+ * project's real end users, which is precisely the outcome the design
+ * rejected.
+ *
+ * Declared before the route registrations below for the same
+ * temporal-dead-zone reason the guards at the top of this file are.
+ */
+/*
+ * Listing sessions. Mirrors RumSession's table-level read ACL exactly:
+ * knowing WHICH sessions errored is triage.
+ */
+const requireSessionReplayListAccess = [
+    UserMiddleware.getUserMiddleware,
+    UserMiddleware.requireUserAuthentication,
+    UserMiddleware.requirePermission({
+        permissions: [
+            Permission.ProjectOwner,
+            Permission.ProjectAdmin,
+            Permission.TelemetryAdmin,
+            Permission.ReadRumSessionReplay,
+        ],
+    }),
+];
+/*
+ * Watching a session. Deliberately a strict subset of the list guard's
+ * audience: reading a recording of a real person's screen is a further
+ * disclosure over knowing that their session went wrong. Mirrors the
+ * `payload` column ACL on RumSessionChunk.
+ */
+const requireSessionReplayPayloadAccess = [
+    UserMiddleware.getUserMiddleware,
+    UserMiddleware.requireUserAuthentication,
+    UserMiddleware.requirePermission({
+        permissions: [
+            Permission.ProjectOwner,
+            Permission.ProjectAdmin,
+            Permission.TelemetryAdmin,
+            Permission.ReadRumSessionReplayPayload,
+        ],
+    }),
+];
+/* The permission list each guard above enforces, reused for label scope. */
+const SESSION_REPLAY_LIST_PERMISSIONS = [
+    Permission.ProjectOwner,
+    Permission.ProjectAdmin,
+    Permission.TelemetryAdmin,
+    Permission.ReadRumSessionReplay,
+];
+const SESSION_REPLAY_PAYLOAD_PERMISSIONS = [
+    Permission.ProjectOwner,
+    Permission.ProjectAdmin,
+    Permission.TelemetryAdmin,
+    Permission.ReadRumSessionReplayPayload,
+];
+/*
+ * The raw end-user identifier carries its own narrower ACL on the model
+ * (no TelemetryAdmin): knowing that *a* user had a bad session is triage,
+ * knowing *which named person* is a further disclosure again.
+ */
+const SESSION_REPLAY_IDENTITY_PERMISSIONS = [
+    Permission.ProjectOwner,
+    Permission.ProjectAdmin,
+    Permission.ReadRumSessionReplayPayload,
+];
+const getSessionReplayLabelScope = (databaseProps, permissions) => {
+    if (databaseProps.isRoot || databaseProps.isMasterAdmin) {
+        return { isUnrestricted: true };
+    }
+    const userPermissions = DatabaseCommonInteractionPropsUtil.getUserPermissions(databaseProps, PermissionType.Allow);
+    const unscopedPermissions = PermissionHelper.getNonAccessControlPermissions(userPermissions);
+    if (PermissionHelper.doesPermissionsIntersect(permissions, unscopedPermissions)) {
+        return { isUnrestricted: true };
+    }
+    const scopedPermissions = PermissionHelper.getAccessControlPermissions(userPermissions);
+    const labelIds = [];
+    for (const permission of permissions) {
+        for (const scopedPermission of scopedPermissions) {
+            if (scopedPermission.permission === permission &&
+                scopedPermission.labelIds.length > 0) {
+                labelIds.push(...scopedPermission.labelIds);
+            }
+        }
+    }
+    if (labelIds.length > 0) {
+        return { isUnrestricted: false, labelIds: labelIds };
+    }
+    /*
+     * Neither an unscoped grant nor a label-scoped one, yet the route guard
+     * let the caller in - so the grant they hold carries a scope this
+     * bespoke path does not implement. PermissionScope.Owned is the real
+     * case: both PermissionHelper filters exclude Owned rows on purpose
+     * because the ORM enforces them through
+     * OwnedScopePermission.addOwnedScopeToQuery, and there is no such step
+     * here. Refusing is the only safe answer; returning "no labels" would
+     * hand an administrator's deliberately narrowed reviewer the whole
+     * project.
+     */
+    const hasOwnedScopedGrant = userPermissions.some((userPermission) => {
+        return (userPermission.scope === PermissionScope.Owned &&
+            permissions.includes(userPermission.permission));
+    });
+    if (hasOwnedScopedGrant) {
+        throw new NotAuthorizedException("Owned-scoped session replay permissions are not supported. Ask an administrator to scope this permission to labels instead.");
+    }
+    /*
+     * No applicable grant at all. This is reachable even behind the route
+     * guard, because the guard matches on permission NAME across every
+     * tenant permission row while getUserPermissions drops block rows. It
+     * means the caller reaches no application, not every application.
+     */
+    return { isUnrestricted: false, labelIds: [] };
+};
+/*
+ * Ceiling on the RUM applications scanned when resolving a label-scoped
+ * caller's reachable set. RUM is keyed by application (service.name), not
+ * by end-user device, so a project has tens of these, not millions.
+ */
+const MAX_RUM_APPLICATIONS_SCANNED = 1000;
+const assertSessionReplayPlan = (databaseProps) => {
+    if (!IsBillingEnabled || !databaseProps.currentPlan) {
+        return;
+    }
+    const requiredPlan = new RumSession().getReadBillingPlan();
+    if (!requiredPlan) {
+        return;
+    }
+    if (!SubscriptionPlan.isFeatureAccessibleOnCurrentPlan(requiredPlan, databaseProps.currentPlan, getAllEnvVars())) {
+        throw new PaymentRequiredException(`Please upgrade your plan to ${requiredPlan} to access session replay.`);
+    }
+};
+const getRumApplicationLabelIds = (application) => {
+    return (application.labels || [])
+        .filter((label) => {
+        return Boolean(label.id);
+    })
+        .map((label) => {
+        return label.id.toString();
+    });
+};
+const isApplicationInSessionReplayScope = (data) => {
+    if (data.scope.isUnrestricted) {
+        return true;
+    }
+    const applicationLabelIds = getRumApplicationLabelIds(data.application);
+    return data.scope.labelIds.some((labelId) => {
+        return applicationLabelIds.includes(labelId.toString());
+    });
+};
+const assertSessionReplayApplicationAccess = async (data) => {
+    const scope = getSessionReplayLabelScope(data.databaseProps, data.permissions);
+    const application = await RumApplicationService.findOneBy({
+        query: {
+            _id: data.rumApplicationId.toString(),
+            projectId: data.projectId,
+        },
+        select: {
+            _id: true,
+            labels: {
+                _id: true,
+            },
+        },
+        props: {
+            isRoot: true,
+        },
+    });
+    /*
+     * An application that does not exist in this project is refused the
+     * same way an out-of-scope one is, so the endpoint cannot be used to
+     * probe which application ids exist elsewhere.
+     */
+    if (!application) {
+        throw new NotAuthorizedException("You do not have access to session replays for this application.");
+    }
+    if (!isApplicationInSessionReplayScope({
+        scope: scope,
+        application: application,
+    })) {
+        throw new NotAuthorizedException("You do not have access to session replays for this application.");
+    }
+    return application;
+};
+const canReadIdentifiedUserLabel = (data) => {
+    let scope;
+    try {
+        scope = getSessionReplayLabelScope(data.databaseProps, SESSION_REPLAY_IDENTITY_PERMISSIONS);
+    }
+    catch (_a) {
+        /*
+         * getSessionReplayLabelScope refuses a scope it cannot enforce. For
+         * an optional column the right answer is to omit the column, not to
+         * fail the whole listing the caller is otherwise entitled to.
+         */
+        return false;
+    }
+    return isApplicationInSessionReplayScope({
+        scope: scope,
+        application: data.application,
+    });
+};
+const resolveAccessibleRumApplicationIds = async (data) => {
+    const scope = getSessionReplayLabelScope(data.databaseProps, data.permissions);
+    if (scope.isUnrestricted) {
+        return { applicationIds: null, isTruncated: false };
+    }
+    if (scope.labelIds.length === 0) {
+        /* Reaches no application at all - not "reaches everything". */
+        return { applicationIds: [], isTruncated: false };
+    }
+    const applications = await RumApplicationService.findBy({
+        query: {
+            projectId: data.projectId,
+        },
+        select: {
+            _id: true,
+            labels: {
+                _id: true,
+            },
+        },
+        /*
+         * A deterministic sort so the page that is scanned is at least
+         * stable between calls, and one row past the ceiling so hitting
+         * it is detectable rather than indistinguishable from a project
+         * that happens to have exactly that many applications.
+         */
+        sort: {
+            createdAt: SortOrder.Ascending,
+        },
+        skip: 0,
+        limit: MAX_RUM_APPLICATIONS_SCANNED + 1,
+        props: {
+            isRoot: true,
+        },
+    });
+    const isTruncated = applications.length > MAX_RUM_APPLICATIONS_SCANNED;
+    const accessibleIds = [];
+    for (const application of applications.slice(0, MAX_RUM_APPLICATIONS_SCANNED)) {
+        if (isApplicationInSessionReplayScope({
+            scope: scope,
+            application: application,
+        }) &&
+            application.id) {
+            accessibleIds.push(application.id);
+        }
+    }
+    return { applicationIds: accessibleIds, isTruncated: isTruncated };
+};
+const resolveAuthorizedSession = async (data) => {
+    const header = await SessionReplayReadService.getSessionHeader({
+        projectId: data.projectId,
+        sessionId: data.sessionId,
+    });
+    if (!header) {
+        throw new BadDataException("Session replay not found.");
+    }
+    await assertSessionReplayApplicationAccess({
+        projectId: data.projectId,
+        rumApplicationId: new ObjectID(header.rumApplicationId),
+        databaseProps: data.databaseProps,
+        permissions: SESSION_REPLAY_PAYLOAD_PERMISSIONS,
+    });
+    return header;
+};
+const readObjectIdFromBody = (body, key) => {
+    const value = body[key];
+    if (typeof value !== "string" || value.length === 0) {
+        throw new BadDataException(`${key} is required`);
+    }
+    if (!ObjectID.isValidUUID(value)) {
+        throw new BadDataException(`${key} is not a valid id`);
+    }
+    return new ObjectID(value);
+};
+const readSessionIdFromBody = (body) => {
+    const sessionId = body["sessionId"];
+    if (typeof sessionId !== "string" || sessionId.length === 0) {
+        throw new BadDataException("sessionId is required");
+    }
+    return sessionId;
+};
+const readStringArrayFromBody = (body, key) => {
+    const value = body[key];
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const strings = value.filter((item) => {
+        return typeof item === "string" && item.length > 0;
+    });
+    return strings.length > 0 ? strings : undefined;
+};
+// --- Session Replay List Endpoint ---
+router.post("/telemetry/rum/session-replay/list", ...requireSessionReplayListAccess, async (req, res, next) => {
+    try {
+        const databaseProps = await CommonAPI.getDatabaseCommonInteractionProps(req);
+        if (!(databaseProps === null || databaseProps === void 0 ? void 0 : databaseProps.tenantId)) {
+            return Response.sendErrorResponse(req, res, new BadDataException("Invalid Project ID"));
+        }
+        assertSessionReplayPlan(databaseProps);
+        const projectId = databaseProps.tenantId;
+        const body = req.body;
+        const rumApplicationId = readObjectIdFromBody(body, "rumApplicationId");
+        /*
+         * The application id is caller-supplied here, which is safe only
+         * because it is the thing being authorized rather than a lookup key
+         * for something already authorized: a caller outside the label
+         * scope is refused, and the query is tenant-pinned regardless.
+         */
+        const application = await assertSessionReplayApplicationAccess({
+            projectId: projectId,
+            rumApplicationId: rumApplicationId,
+            databaseProps: databaseProps,
+            permissions: SESSION_REPLAY_LIST_PERMISSIONS,
+        });
+        const startTime = body["startTime"]
+            ? OneUptimeDate.fromString(body["startTime"])
+            : OneUptimeDate.addRemoveDays(OneUptimeDate.getCurrentDate(), -7);
+        const endTime = body["endTime"]
+            ? OneUptimeDate.fromString(body["endTime"])
+            : OneUptimeDate.getCurrentDate();
+        const rawFilters = body["filters"] || {};
+        const filters = Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, (typeof rawFilters["hasError"] === "boolean" && {
+            hasError: rawFilters["hasError"],
+        })), (typeof rawFilters["hasFrustration"] === "boolean" && {
+            hasFrustration: rawFilters["hasFrustration"],
+        })), (typeof rawFilters["isFinalized"] === "boolean" && {
+            isFinalized: rawFilters["isFinalized"],
+        })), (readStringArrayFromBody(rawFilters, "triggerReasons") && {
+            triggerReasons: readStringArrayFromBody(rawFilters, "triggerReasons"),
+        })), (readStringArrayFromBody(rawFilters, "browserNames") && {
+            browserNames: readStringArrayFromBody(rawFilters, "browserNames"),
+        })), (readStringArrayFromBody(rawFilters, "osNames") && {
+            osNames: readStringArrayFromBody(rawFilters, "osNames"),
+        })), (readStringArrayFromBody(rawFilters, "deviceTypes") && {
+            deviceTypes: readStringArrayFromBody(rawFilters, "deviceTypes"),
+        })), (readStringArrayFromBody(rawFilters, "countryCodes") && {
+            countryCodes: readStringArrayFromBody(rawFilters, "countryCodes"),
+        })), (typeof rawFilters["identifiedUserKey"] === "string" && {
+            identifiedUserKey: rawFilters["identifiedUserKey"],
+        })), (typeof rawFilters["route"] === "string" && {
+            route: rawFilters["route"],
+        })), (typeof rawFilters["minDurationMs"] === "number" && {
+            minDurationMs: rawFilters["minDurationMs"],
+        }));
+        const rawCursor = body["cursor"]
+            ? body["cursor"]
+            : undefined;
+        const cursor = rawCursor &&
+            typeof rawCursor["startTimeUnixMs"] === "number" &&
+            typeof rawCursor["sessionId"] === "string"
+            ? {
+                startTimeUnixMs: rawCursor["startTimeUnixMs"],
+                sessionId: rawCursor["sessionId"],
+            }
+            : undefined;
+        /*
+         * The narrower identity ACL is enforced by simply not naming the
+         * column in the SELECT. There is no ModelPermission on this path to
+         * strip it after the fact. Decided against the application already
+         * loaded by the access check, so a caller whose identity grant is
+         * label-scoped elsewhere does not get named end users here.
+         */
+        const includeIdentifiedUserLabel = canReadIdentifiedUserLabel({
+            databaseProps: databaseProps,
+            application: application,
+        });
+        const result = await SessionReplayReadService.listSessions(Object.assign(Object.assign({ projectId: projectId, rumApplicationId: rumApplicationId, startTime: startTime, endTime: endTime, filters: filters, limit: typeof body["limit"] === "number"
+                ? body["limit"]
+                : DEFAULT_SESSION_REPLAY_LIST_LIMIT }, (cursor !== undefined && { cursor })), { includeIdentifiedUserLabel: includeIdentifiedUserLabel }));
+        return Response.sendJsonObjectResponse(req, res, {
+            sessions: result.sessions,
+            nextCursor: result.nextCursor,
+        });
+    }
+    catch (err) {
+        next(err);
+    }
+});
+// --- Session Replay Manifest Endpoint ---
+router.post("/telemetry/rum/session-replay/manifest", ...requireSessionReplayPayloadAccess, async (req, res, next) => {
+    try {
+        const databaseProps = await CommonAPI.getDatabaseCommonInteractionProps(req);
+        if (!(databaseProps === null || databaseProps === void 0 ? void 0 : databaseProps.tenantId)) {
+            return Response.sendErrorResponse(req, res, new BadDataException("Invalid Project ID"));
+        }
+        assertSessionReplayPlan(databaseProps);
+        const projectId = databaseProps.tenantId;
+        const body = req.body;
+        const sessionId = readSessionIdFromBody(body);
+        const header = await resolveAuthorizedSession({
+            projectId: projectId,
+            sessionId: sessionId,
+            databaseProps: databaseProps,
+        });
+        /*
+         * The authorized application, resolved server-side from the header.
+         * Every chunk-table read below is pinned to it: that table's replace
+         * key is (projectId, sessionId, tabId, chunkIndex) with
+         * rumApplicationId a plain column, so (projectId, sessionId) alone
+         * is not enough to keep two applications' recordings apart.
+         */
+        const authorizedApplicationId = new ObjectID(header.rumApplicationId);
+        /*
+         * The audit row is written BEFORE the manifest is built, not after.
+         * A read that fails halfway through still happened, and an audit
+         * that only records successful reads is an audit an attacker can
+         * evade by aborting the request.
+         */
+        const view = await RumSessionReplayViewService.recordView({
+            projectId: projectId,
+            rumApplicationId: authorizedApplicationId,
+            sessionId: sessionId,
+            viewedByUserId: databaseProps.userId,
+            ipAddress: getClientIp(req),
+            userAgent: typeof req.headers["user-agent"] === "string"
+                ? req.headers["user-agent"]
+                : undefined,
+            accessReason: typeof body["accessReason"] === "string"
+                ? body["accessReason"]
+                : undefined,
+            linkedIncidentId: typeof body["linkedIncidentId"] === "string" &&
+                body["linkedIncidentId"].length > 0
+                ? new ObjectID(body["linkedIncidentId"])
+                : undefined,
+            linkedExceptionFingerprint: typeof body["linkedExceptionFingerprint"] === "string"
+                ? body["linkedExceptionFingerprint"]
+                : undefined,
+        });
+        const manifest = await SessionReplayReadService.getManifest({
+            header: header,
+            projectId: projectId,
+            rumApplicationId: authorizedApplicationId,
+            sessionId: sessionId,
+        });
+        return Response.sendJsonObjectResponse(req, res, {
+            /*
+             * viewId is echoed back so the player's heartbeat can advance the
+             * very row this read created, instead of guessing at one.
+             */
+            viewId: view.id ? view.id.toString() : null,
+            header: manifest.header,
+            tabs: manifest.tabs,
+            isChunkIndexTruncated: manifest.isChunkIndexTruncated,
+        });
+    }
+    catch (err) {
+        next(err);
+    }
+});
+// --- Session Replay Chunk Endpoint ---
+router.post("/telemetry/rum/session-replay/chunks", ...requireSessionReplayPayloadAccess, async (req, res, next) => {
+    try {
+        const databaseProps = await CommonAPI.getDatabaseCommonInteractionProps(req);
+        if (!(databaseProps === null || databaseProps === void 0 ? void 0 : databaseProps.tenantId)) {
+            return Response.sendErrorResponse(req, res, new BadDataException("Invalid Project ID"));
+        }
+        assertSessionReplayPlan(databaseProps);
+        const projectId = databaseProps.tenantId;
+        const body = req.body;
+        const sessionId = readSessionIdFromBody(body);
+        const tabId = body["tabId"];
+        if (typeof tabId !== "string" || tabId.length === 0) {
+            return Response.sendErrorResponse(req, res, new BadDataException("tabId is required"));
+        }
+        const rawChunkIndexes = body["chunkIndexes"];
+        if (!Array.isArray(rawChunkIndexes) || rawChunkIndexes.length === 0) {
+            return Response.sendErrorResponse(req, res, new BadDataException("chunkIndexes is required"));
+        }
+        const chunkIndexes = rawChunkIndexes.filter((index) => {
+            return (typeof index === "number" && Number.isInteger(index) && index >= 0);
+        });
+        if (chunkIndexes.length !== rawChunkIndexes.length) {
+            return Response.sendErrorResponse(req, res, new BadDataException("chunkIndexes must contain only non-negative integers"));
+        }
+        /*
+         * Checked here as well as inside the read service: the route should
+         * refuse an abusive request before it authorizes and queries
+         * anything, and the service must refuse it for any future caller
+         * that does not come through this route.
+         */
+        if (chunkIndexes.length > MAX_SESSION_REPLAY_CHUNKS_PER_READ) {
+            return Response.sendErrorResponse(req, res, new BadDataException(`A maximum of ${MAX_SESSION_REPLAY_CHUNKS_PER_READ} chunks may be requested at a time.`));
+        }
+        const header = await resolveAuthorizedSession({
+            projectId: projectId,
+            sessionId: sessionId,
+            databaseProps: databaseProps,
+        });
+        const chunks = await SessionReplayReadService.getChunks({
+            projectId: projectId,
+            /* Always the application the caller was authorized against. */
+            rumApplicationId: new ObjectID(header.rumApplicationId),
+            sessionId: sessionId,
+            tabId: tabId,
+            chunkIndexes: chunkIndexes,
+        });
+        /*
+         * Concatenated binary frames: [u32 chunkIndex][u32 byteLength][bytes]
+         * repeated, little-endian, application/octet-stream.
+         *
+         * Not JSON: the payload is already a JSON document, so a JSON
+         * envelope would force the server to re-escape and the browser to
+         * double-parse several megabytes per page. The length prefix lets
+         * the player slice the response without scanning it.
+         */
+        const frames = [];
+        /*
+         * The byte cap is re-checked here against the bytes actually being
+         * framed, not only against what the pre-check in the read service
+         * believed. This is the last place the size of the response is
+         * knowable, so it is the one place a cap on the response can be
+         * absolute regardless of how stored size was estimated upstream.
+         */
+        let responseBytes = 0;
+        for (const chunk of chunks) {
+            const payloadBuffer = Buffer.from(chunk.payload, "utf8");
+            responseBytes += payloadBuffer.length + 8;
+            if (responseBytes > MAX_SESSION_REPLAY_READ_BYTES) {
+                return Response.sendErrorResponse(req, res, new BadDataException(`The requested chunks exceed the ${MAX_SESSION_REPLAY_READ_BYTES} byte limit for a single read. Request fewer chunks.`));
+            }
+            const headerBuffer = Buffer.alloc(8);
+            headerBuffer.writeUInt32LE(chunk.chunkIndex, 0);
+            headerBuffer.writeUInt32LE(payloadBuffer.length, 4);
+            frames.push(headerBuffer, payloadBuffer);
+        }
+        const responseBody = Buffer.concat(frames);
+        res.setHeader("Content-Type", "application/octet-stream");
+        res.setHeader("Content-Length", responseBody.length.toString());
+        /*
+         * A recording is personal data. Nothing about it may sit in a
+         * shared cache, and the browser should not keep it on disk either.
+         */
+        res.setHeader("Cache-Control", "no-store");
+        res.send(responseBody);
+    }
+    catch (err) {
+        next(err);
+    }
+});
+// --- Session Replay Heartbeat Endpoint ---
+router.post("/telemetry/rum/session-replay/heartbeat", ...requireSessionReplayPayloadAccess, async (req, res, next) => {
+    try {
+        const databaseProps = await CommonAPI.getDatabaseCommonInteractionProps(req);
+        if (!(databaseProps === null || databaseProps === void 0 ? void 0 : databaseProps.tenantId)) {
+            return Response.sendErrorResponse(req, res, new BadDataException("Invalid Project ID"));
+        }
+        assertSessionReplayPlan(databaseProps);
+        const projectId = databaseProps.tenantId;
+        const body = req.body;
+        const viewId = readObjectIdFromBody(body, "viewId");
+        const secondsWatched = body["secondsWatched"];
+        if (typeof secondsWatched !== "number" ||
+            !Number.isFinite(secondsWatched)) {
+            return Response.sendErrorResponse(req, res, new BadDataException("secondsWatched must be a number"));
+        }
+        /*
+         * Floored to the 15s heartbeat cadence. recordSecondsWatched is
+         * monotonic and returns without writing when the value does not
+         * advance, so flooring here turns a chatty client into at most one
+         * UPDATE per 15 seconds watched without any server-side timer or
+         * cross-pod throttle state.
+         */
+        const throttledSeconds = Math.floor(Math.max(0, secondsWatched) / 15) * 15;
+        /*
+         * secondsWatched is a privacy control, not telemetry: it is shown on
+         * the player as "who watched how much of this recording". Scoping
+         * the write to the tenant alone would let any principal holding the
+         * payload permission inflate somebody else's audit row for a session
+         * they may not even read, which forges the very record the design
+         * relies on.
+         *
+         * The row is therefore looked up as the CALLER'S own view row - a
+         * viewId belonging to anyone else matches nothing and is refused
+         * indistinguishably from one that does not exist - and the
+         * application it points at is authorized exactly as a payload read
+         * would be.
+         */
+        if (!databaseProps.userId) {
+            return Response.sendErrorResponse(req, res, new NotAuthorizedException("You do not have access to this session replay view."));
+        }
+        const view = await RumSessionReplayViewService.findOneBy({
+            query: {
+                _id: viewId.toString(),
+                projectId: projectId,
+                viewedByUserId: databaseProps.userId,
+            },
+            select: {
+                _id: true,
+                rumApplicationId: true,
+            },
+            props: {
+                isRoot: true,
+            },
+        });
+        if (!view || !view.rumApplicationId) {
+            return Response.sendErrorResponse(req, res, new NotAuthorizedException("You do not have access to this session replay view."));
+        }
+        await assertSessionReplayApplicationAccess({
+            projectId: projectId,
+            rumApplicationId: view.rumApplicationId,
+            databaseProps: databaseProps,
+            permissions: SESSION_REPLAY_PAYLOAD_PERMISSIONS,
+        });
+        await RumSessionReplayViewService.recordSecondsWatched({
+            viewId: viewId,
+            projectId: projectId,
+            secondsWatched: throttledSeconds,
+        });
+        return Response.sendJsonObjectResponse(req, res, {
+            secondsWatched: throttledSeconds,
+        });
+    }
+    catch (err) {
+        next(err);
+    }
+});
+// --- Session Replay For Exception Endpoint ---
+router.post("/telemetry/rum/session-replay/for-exception", ...requireSessionReplayListAccess, async (req, res, next) => {
+    try {
+        const databaseProps = await CommonAPI.getDatabaseCommonInteractionProps(req);
+        if (!(databaseProps === null || databaseProps === void 0 ? void 0 : databaseProps.tenantId)) {
+            return Response.sendErrorResponse(req, res, new BadDataException("Invalid Project ID"));
+        }
+        assertSessionReplayPlan(databaseProps);
+        const projectId = databaseProps.tenantId;
+        const body = req.body;
+        const fingerprint = body["fingerprint"];
+        if (typeof fingerprint !== "string" || fingerprint.length === 0) {
+            return Response.sendErrorResponse(req, res, new BadDataException("fingerprint is required"));
+        }
+        /*
+         * An exception is not scoped to a RUM application, so there is no
+         * single application to authorize against. Restrict the query to
+         * the applications the caller's labels reach instead.
+         */
+        const accessibleApplications = await resolveAccessibleRumApplicationIds({
+            projectId: projectId,
+            databaseProps: databaseProps,
+            permissions: SESSION_REPLAY_LIST_PERMISSIONS,
+        });
+        const startTime = body["startTime"]
+            ? OneUptimeDate.fromString(body["startTime"])
+            : undefined;
+        const endTime = body["endTime"]
+            ? OneUptimeDate.fromString(body["endTime"])
+            : undefined;
+        const sessions = await SessionReplayReadService.getSessionsForException(Object.assign(Object.assign(Object.assign({ projectId: projectId, exceptionFingerprint: fingerprint, accessibleRumApplicationIds: accessibleApplications.applicationIds }, (startTime !== undefined && { startTime })), (endTime !== undefined && { endTime })), { limit: typeof body["limit"] === "number"
+                ? body["limit"]
+                : MAX_SESSION_REPLAY_FOR_EXCEPTION_LIMIT }));
+        return Response.sendJsonObjectResponse(req, res, {
+            sessions: sessions,
+            /*
+             * Told, not hidden: the accessible-application scan has a ceiling,
+             * and a caller who hits it is looking at a possibly short answer.
+             */
+            isApplicationScopeTruncated: accessibleApplications.isTruncated,
+        });
+    }
+    catch (err) {
+        next(err);
+    }
+});
+// --- Session Replay Ingest Status Endpoint ---
+/*
+ * Recording health for one application: is replay switched on at every
+ * level, when did the last chunk actually land, and how much of the byte
+ * budgets is spent. This is what lets the Dashboard answer "why are there
+ * no recordings?" and "am I about to hit my budget?" as states rather than
+ * leaving the customer to infer them from silence — the ingest gate's
+ * refusals are deliberately quiet toward end users' browsers, so this
+ * endpoint is the loud side of that trade.
+ *
+ * Reads settings metadata and Redis counters only; never touches recording
+ * payloads, so list-level access is the right bar.
+ *
+ * The application row is loaded with root props even though its columns
+ * carry their own read ACLs. That is deliberate and bounded: every column
+ * returned here (appIdentifier, the replay policy fields, the two health
+ * timestamps) is readable by a plain project Viewer under its declared
+ * ACL — the least-privileged read tier there is — while this route demands
+ * the STRICTER session-replay list permission and pins tenancy and label
+ * scope first. Nothing is disclosed that the caller's project peers cannot
+ * already read through the generic CRUD API. If a column with a narrower
+ * ACL (e.g. anything identity-adjacent) is ever added to this SELECT, it
+ * must get an explicit permission check, not a wider isRoot ride-along.
+ */
+router.post("/telemetry/rum/session-replay/ingest-status", ...requireSessionReplayListAccess, async (req, res, next) => {
+    var _a;
+    try {
+        const databaseProps = await CommonAPI.getDatabaseCommonInteractionProps(req);
+        if (!(databaseProps === null || databaseProps === void 0 ? void 0 : databaseProps.tenantId)) {
+            return Response.sendErrorResponse(req, res, new BadDataException("Invalid Project ID"));
+        }
+        assertSessionReplayPlan(databaseProps);
+        const projectId = databaseProps.tenantId;
+        const body = req.body;
+        const rumApplicationId = readObjectIdFromBody(body, "rumApplicationId");
+        await assertSessionReplayApplicationAccess({
+            projectId: projectId,
+            rumApplicationId: rumApplicationId,
+            databaseProps: databaseProps,
+            permissions: SESSION_REPLAY_LIST_PERMISSIONS,
+        });
+        const application = await RumApplicationService.findOneBy({
+            query: {
+                _id: rumApplicationId.toString(),
+                projectId: projectId,
+            },
+            select: {
+                _id: true,
+                appIdentifier: true,
+                isSessionReplayEnabled: true,
+                sessionReplayAllowedOrigins: true,
+                sessionReplaySamplePercentage: true,
+                sessionReplayCaptureTrigger: true,
+                sessionReplayMonthlyBudgetInGB: true,
+                sessionReplayLastChunkReceivedAt: true,
+                sessionReplayBudgetExceededAt: true,
+            },
+            props: {
+                isRoot: true,
+            },
+        });
+        if (!application) {
+            return Response.sendErrorResponse(req, res, new BadDataException("RUM application not found."));
+        }
+        const project = await ProjectService.findOneBy({
+            query: {
+                _id: projectId.toString(),
+            },
+            select: {
+                isSessionReplayAllowed: true,
+            },
+            props: {
+                isRoot: true,
+            },
+        });
+        const [projectBytesUsedToday, applicationBytesUsedThisMonth] = await Promise.all([
+            SessionReplayUsage.getProjectBytesUsedToday(projectId),
+            SessionReplayUsage.getApplicationBytesUsedThisMonth({
+                projectId: projectId,
+                rumApplicationId: rumApplicationId,
+            }),
+        ]);
+        /*
+         * Same env var, same default, as the value the ingest gate enforces
+         * (App Telemetry Config). The default is a shared constant so the
+         * number shown here cannot drift from the number enforced there.
+         */
+        const dailyCapEnv = parseInt(process.env["SESSION_REPLAY_MAX_BYTES_PER_PROJECT_PER_DAY"] || "", 10);
+        const dailyByteLimit = !isNaN(dailyCapEnv) && dailyCapEnv > 0
+            ? dailyCapEnv
+            : DEFAULT_SESSION_REPLAY_MAX_BYTES_PER_PROJECT_PER_DAY;
+        const applicationView = application;
+        return Response.sendJsonObjectResponse(req, res, {
+            isProjectAllowed: Boolean(project === null || project === void 0 ? void 0 : project["isSessionReplayAllowed"]),
+            isApplicationEnabled: Boolean(applicationView["isSessionReplayEnabled"]),
+            appIdentifier: String(applicationView["appIdentifier"] || ""),
+            allowedOrigins: (applicationView["sessionReplayAllowedOrigins"] ||
+                []),
+            samplePercentage: Number(applicationView["sessionReplaySamplePercentage"] || 0),
+            captureTrigger: String(applicationView["sessionReplayCaptureTrigger"] || ""),
+            lastChunkReceivedAt: applicationView["sessionReplayLastChunkReceivedAt"] ||
+                null,
+            budgetExceededAt: applicationView["sessionReplayBudgetExceededAt"] || null,
+            /* null = counter unreachable; render as unknown, never as zero. */
+            projectBytesUsedToday: projectBytesUsedToday,
+            dailyByteLimit: dailyByteLimit,
+            applicationBytesUsedThisMonth: applicationBytesUsedThisMonth,
+            monthlyBudgetInGB: (_a = applicationView["sessionReplayMonthlyBudgetInGB"]) !== null && _a !== void 0 ? _a : null,
+        });
+    }
+    catch (err) {
+        next(err);
+    }
+});
+/*
+ * "Record the next session for this user."
+ *
+ * One route, three actions, because all three are the same tiny
+ * conversation with one Redis key: set arms a 24h one-shot target for a
+ * named end-user reference, clear disarms it, status reads it. The
+ * response is always the resulting { isPending }.
+ *
+ * The guard requires EDIT on the application, not the session-replay READ
+ * permission: arming this causes a recording of a named person to be
+ * made, which is a capture-policy write - the same class of action as
+ * flipping the enable flag - and a reviewer who may only WATCH recordings
+ * must not be able to order new ones.
+ */
+const requireSessionReplayTargetAccess = [
+    UserMiddleware.getUserMiddleware,
+    UserMiddleware.requireUserAuthentication,
+    UserMiddleware.requirePermission({
+        permissions: [
+            Permission.ProjectOwner,
+            Permission.ProjectAdmin,
+            Permission.TelemetryAdmin,
+            Permission.EditRumApplication,
+        ],
+    }),
+];
+router.post("/telemetry/rum/session-replay/target", ...requireSessionReplayTargetAccess, async (req, res, next) => {
+    try {
+        const databaseProps = await CommonAPI.getDatabaseCommonInteractionProps(req);
+        if (!(databaseProps === null || databaseProps === void 0 ? void 0 : databaseProps.tenantId)) {
+            return Response.sendErrorResponse(req, res, new BadDataException("Invalid Project ID"));
+        }
+        assertSessionReplayPlan(databaseProps);
+        const projectId = databaseProps.tenantId;
+        const body = req.body;
+        const rumApplicationId = readObjectIdFromBody(body, "rumApplicationId");
+        const action = body["action"];
+        if (action !== "set" && action !== "clear" && action !== "status") {
+            return Response.sendErrorResponse(req, res, new BadDataException('action must be one of "set", "clear" or "status".'));
+        }
+        const userRef = body["userRef"];
+        if (!SessionReplayTargeting.isUsableUserRef(userRef)) {
+            return Response.sendErrorResponse(req, res, new BadDataException("userRef must be a non-empty string of at most 512 characters."));
+        }
+        await assertSessionReplayApplicationAccess({
+            projectId: projectId,
+            rumApplicationId: rumApplicationId,
+            databaseProps: databaseProps,
+            permissions: [
+                Permission.ProjectOwner,
+                Permission.ProjectAdmin,
+                Permission.TelemetryAdmin,
+                Permission.EditRumApplication,
+            ],
+        });
+        /*
+         * The Redis key is scoped by the application's ingest identifier -
+         * the name the recorder introduces itself with - not by the row id
+         * the dashboard holds, so resolve one from the other here.
+         */
+        const application = await RumApplicationService.findOneBy({
+            query: {
+                _id: rumApplicationId.toString(),
+                projectId: projectId,
+            },
+            select: {
+                _id: true,
+                appIdentifier: true,
+            },
+            props: {
+                isRoot: true,
+            },
+        });
+        const appIdentifier = String((application === null || application === void 0 ? void 0 : application["appIdentifier"]) || "");
+        if (!application || !appIdentifier) {
+            return Response.sendErrorResponse(req, res, new BadDataException("RUM application not found."));
+        }
+        const target = {
+            projectId: projectId,
+            appIdentifier: appIdentifier,
+            userRef: userRef,
+        };
+        let isPending = false;
+        if (action === "set") {
+            await SessionReplayTargeting.setTarget(target);
+            isPending = true;
+        }
+        else if (action === "clear") {
+            await SessionReplayTargeting.clearTarget(target);
+            isPending = false;
+        }
+        else {
+            isPending = await SessionReplayTargeting.isTargetPending(target);
+        }
+        return Response.sendJsonObjectResponse(req, res, {
+            isPending: isPending,
+        });
+    }
+    catch (err) {
+        next(err);
+    }
+});
 export default router;
 //# sourceMappingURL=TelemetryAPI.js.map