@oneuptime/common 13.0.4 → 13.0.6

package/build/dist/Server/Utils/SecurityEvent/{GoogleSecOps → Connectors/GoogleSecOps}/GoogleSecOpsClient.js

@@ -1,9 +1,10 @@
 import { createPrivateKey } from "crypto";
 import jwt from "jsonwebtoken";
-import BadDataException from "../../../../Types/Exception/BadDataException";
-import APIException from "../../../../Types/Exception/ApiException";
-import logger from "../../Logger";
-import { redactLogString, redactLogValue } from "../../LogRedaction";
+import BadDataException from "../../../../../Types/Exception/BadDataException";
+import { GOOGLE_SECOPS_SUPPORTED_REGIONS } from "../../../../../Types/SecurityEvent/GoogleSecOpsRegion";
+import APIException from "../../../../../Types/Exception/ApiException";
+import logger from "../../../Logger";
+import { redactLogString, redactLogValue } from "../../../LogRedaction";
 const CHRONICLE_SCOPE = "https://www.googleapis.com/auth/cloud-platform";
 const TOKEN_LIFETIME_IN_SECONDS = 3600;
 const TOKEN_EXPIRY_SLACK_IN_SECONDS = 60;
@@ -26,36 +27,77 @@ const DEFAULT_MAX_ALERTS = 1000;
 const REQUEST_TIMEOUT_IN_SECONDS = 60;
 const REQUEST_TIMEOUT_IN_MS = REQUEST_TIMEOUT_IN_SECONDS * 1000;
 /*
- * The 22 documented {region}-chronicle.googleapis.com prefixes. An
- * allowlist rather than a shape regex because *.googleapis.com is a DNS
- * wildcard: a typo like "us-central1" resolves to a Google frontend and
- * answers with an HTML 404, so a regex that merely looks safe turns a
- * misconfigured region into a parse error instead of "unsupported region".
+ * legacyFetchAlertsView streams, and a stream can end before Google sets
+ * complete=true ("Streaming for this response is done. There will be no
+ * additional updates." is the documented meaning of the flag). Google's
+ * own SDK re-issues the whole GET in that case; this client does the same
+ * a bounded number of times, with a short pause, and then hands the
+ * partial result to the poller, which holds its cursor for it.
+ * https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.legacy/legacyFetchAlertsView
  */
-const SUPPORTED_REGIONS = [
-    "us",
-    "eu",
-    "europe",
-    "africa-south1",
-    "asia-east1",
-    "asia-northeast1",
-    "asia-northeast3",
-    "asia-south1",
-    "asia-southeast1",
-    "asia-southeast2",
-    "australia-southeast1",
-    "europe-central2",
-    "europe-west12",
-    "europe-west2",
-    "europe-west3",
-    "europe-west6",
-    "europe-west9",
-    "me-central1",
-    "me-central2",
-    "me-west1",
-    "northamerica-northeast2",
-    "southamerica-east1",
+const INCOMPLETE_STREAM_MAX_RETRIES = 2;
+const INCOMPLETE_STREAM_RETRY_DELAY_IN_MS = 250;
+/*
+ * legacySearchDetections pages. Google documents pageSize only as
+ * "Maximum number of detections to return" and prints no ceiling; 1000
+ * matches the alerts view's documented ceiling, so one poll never asks for
+ * more than the other endpoint can hand back, and every page is bounded.
+ * https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.legacy/legacySearchDetections
+ */
+const DEFAULT_SEARCH_PAGE_SIZE = 1000;
+const MAX_SEARCH_PAGE_SIZE = 1000;
+/*
+ * ruleId is required by legacySearchDetections; its reference documents the
+ * bare wildcard as "retrieves detections for all revisions of all Rules",
+ * which is exactly one poll's question.
+ *
+ * legacySearchCuratedDetections documents no wildcard at all: its ruleId is
+ * "Required. The specific Curated Rule ID to list detections for". Sending
+ * "-" there is not rejected — Google answers HTTP 200 with no detections,
+ * because no curated rule has that id — so every curated detection was
+ * silently never imported. Curated searches therefore always carry a real
+ * ur_... id, found through countAllCuratedRuleSetDetections.
+ * https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.legacy/legacySearchDetections
+ * https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.legacy/legacySearchCuratedDetections
+ */
+const ALL_RULES_WILDCARD = "-";
+/*
+ * A curated rule id is the last segment of a CuratedRule name (ur_...). The
+ * guard keeps a wildcard, a revision suffix or a path out of the query
+ * string: the curated route has no wildcard, aggregates every revision of
+ * the rule itself, and a separator would reshape the request.
+ */
+const CURATED_RULE_ID_REGEX = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
+/*
+ * Every field a countAllCuratedRuleSetDetections response may carry. A
+ * quiet tenant is a bare `{}`; any other object is not this endpoint's
+ * answer and must not be read as "no curated rule fired".
+ * https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances/countAllCuratedRuleSetDetections
+ */
+const RECOGNIZED_CURATED_COUNT_FIELDS = [
+    "curatedRuleSetCounts",
+    "curatedRuleCounts",
 ];
+/*
+ * Every field a legacySearchDetections / legacySearchCuratedDetections
+ * response may carry. proto3 omits empty fields, so a quiet window is a
+ * bare `{}` and must parse as zero detections; a NON-empty object carrying
+ * none of these is some other endpoint's answer and must never be read as
+ * "nothing new" — the poller would advance its cursor past it.
+ */
+const RECOGNIZED_SEARCH_FIELDS = [
+    "detections",
+    "curatedDetections",
+    "nestedDetectionSamples",
+    "nextPageToken",
+    "respTooLargeDetectionsTruncated",
+];
+/*
+ * The client writes "<step> failed (HTTP <status>): " in front of every
+ * remote rejection; that tail is the documented contract the poller and
+ * the connection tester read the status back out of.
+ */
+const HTTP_STATUS_TAIL_PATTERN = /\(HTTP (\d{3})\)/;
 /*
  * europe-chronicle.googleapis.com is a documented live host while the
  * migration guide names the same multi-region's location code "eu", so the
@@ -121,9 +163,15 @@ export default class GoogleSecOpsClient {
         this.credentials = GoogleSecOpsClient.parseServiceAccountJson(data.serviceAccountJson);
         this.fetchImplementation =
             data.fetchImplementation || fetch;
+        this.requestTimeoutInMs =
+            typeof data.requestTimeoutInMs === "number" &&
+                Number.isFinite(data.requestTimeoutInMs) &&
+                data.requestTimeoutInMs > 0
+                ? Math.floor(data.requestTimeoutInMs)
+                : REQUEST_TIMEOUT_IN_MS;
     }
     static validateRegion(region) {
-        if (SUPPORTED_REGIONS.indexOf(region || "") === -1) {
+        if (GOOGLE_SECOPS_SUPPORTED_REGIONS.indexOf(region || "") === -1) {
             throw new BadDataException("Region must be a Google SecOps regional prefix like 'us' or 'europe'.");
         }
     }
@@ -257,26 +305,44 @@ export default class GoogleSecOpsClient {
                 : "ALERTS_FEATURE_PREFERENCE_DISABLED",
         });
         const url = `${this.getApiBaseUrl()}/legacy:legacyFetchAlertsView?${params.toString()}`;
-        let response = await this.requestAlerts(url, accessToken);
-        let responseText = await response.text();
+        let result = null;
         /*
-         * A key revoked mid-lifetime leaves a cached token Google now refuses,
-         * and every poll until its stated expiry fails against it. One retry
-         * on a fresh token distinguishes "the token went stale" from "the
-         * credential is genuinely rejected", which is what the operator needs
-         * to read off lastError.
+         * The same GET is re-issued, unchanged, when the stream ends without
+         * complete=true — at most INCOMPLETE_STREAM_MAX_RETRIES times, so a
+         * tenant that never completes cannot pin a strictly sequential poll
+         * loop. The last partial result is returned and the poller holds its
+         * cursor for it.
          */
-        if (response.status === 401) {
-            this.clearCachedAccessToken();
-            accessToken = await this.getAccessToken();
-            response = await this.requestAlerts(url, accessToken);
-            responseText = await response.text();
-        }
-        if (!response.ok) {
-            throw new APIException(`Google SecOps alerts fetch failed (HTTP ${response.status}): ${GoogleSecOpsClient.redactErrorBody(responseText)}` +
-                GoogleSecOpsClient.describeHttpFailure(response.status, responseText));
+        for (let attempt = 0; attempt <= INCOMPLETE_STREAM_MAX_RETRIES; attempt++) {
+            if (attempt > 0) {
+                await GoogleSecOpsClient.sleep(INCOMPLETE_STREAM_RETRY_DELAY_IN_MS);
+            }
+            let response = await this.requestAlerts(url, accessToken);
+            let responseText = await response.text();
+            /*
+             * A key revoked mid-lifetime leaves a cached token Google now refuses,
+             * and every poll until its stated expiry fails against it. One retry
+             * on a fresh token distinguishes "the token went stale" from "the
+             * credential is genuinely rejected", which is what the operator needs
+             * to read off lastError.
+             */
+            if (response.status === 401) {
+                this.clearCachedAccessToken();
+                accessToken = await this.getAccessToken();
+                response = await this.requestAlerts(url, accessToken);
+                responseText = await response.text();
+            }
+            if (!response.ok) {
+                throw new APIException(`Google SecOps alerts fetch failed (HTTP ${response.status}): ${GoogleSecOpsClient.redactErrorBody(responseText)}` +
+                    GoogleSecOpsClient.describeHttpFailure(response.status, responseText));
+            }
+            result = GoogleSecOpsClient.parseAlertsBody(responseText, maxReturnedAlerts);
+            if (result.complete) {
+                return result;
+            }
+            logger.warn(`GoogleSecOpsClient: the alerts stream ended without complete=true (attempt ${attempt + 1} of ${INCOMPLETE_STREAM_MAX_RETRIES + 1}).`);
         }
-        return GoogleSecOpsClient.parseAlertsBody(responseText, maxReturnedAlerts);
+        return result;
     }
     /*
      * The legacy top-level shapes, kept as a fallback so a tenant already
@@ -311,12 +377,110 @@ export default class GoogleSecOpsClient {
         }
         return collected;
     }
+    /*
+     * Search detections for every rule, paginated, filtered by the time
+     * Google CREATED them or by detection time. This is the poller's primary
+     * read: legacyFetchAlertsView filters on detection time only, and a
+     * detection created at 10:05 for a window ending 09:00 sits behind a
+     * forward-only cursor forever. Same token handling and one-shot 401 retry
+     * as fetchDetectionAlerts.
+     *
+     * Contract, verified against Google's reference pages:
+     *   GET {base}/legacy:legacySearchDetections
+     *     ?ruleId=-&startTime=<RFC 3339, inclusive>&endTime=<exclusive>
+     *     &listBasis=CREATED_TIME|DETECTION_TIME&pageSize=N
+     *     [&alertState=ALERTING][&pageToken=...]
+     *   → { detections: Collection[], nextPageToken, respTooLargeDetectionsTruncated }
+     * The curated variant is legacy:legacySearchCuratedDetections with the
+     * same parameters, except that ruleId must name ONE curated rule (ur_...),
+     * and `curatedDetections` in place of `detections`.
+     * https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.legacy/legacySearchDetections
+     * https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.legacy/legacySearchCuratedDetections
+     */
+    async searchDetections(data) {
+        const ruleId = GoogleSecOpsClient.resolveSearchRuleId(data.curated === true, data.ruleId);
+        let accessToken = await this.getAccessToken();
+        const pageSize = GoogleSecOpsClient.clampSearchPageSize(data.pageSize);
+        const params = new URLSearchParams({
+            ruleId: ruleId,
+            startTime: data.startTime.toISOString(),
+            endTime: data.endTime.toISOString(),
+            listBasis: data.listBasis,
+            pageSize: String(pageSize),
+        });
+        /*
+         * AlertState is UNSPECIFIED | NOT_ALERTING | ALERTING. Omitting it
+         * returns both states, which is what "Alerts and detections" asks for;
+         * the enum has no "both" value to send explicitly.
+         */
+        if (data.alertingOnly) {
+            params.set("alertState", "ALERTING");
+        }
+        if (data.pageToken) {
+            params.set("pageToken", data.pageToken);
+        }
+        const method = data.curated
+            ? "legacySearchCuratedDetections"
+            : "legacySearchDetections";
+        const url = `${this.getApiBaseUrl()}/legacy:${method}?${params.toString()}`;
+        let response = await this.requestJson(url, accessToken, "detections search");
+        let responseText = await response.text();
+        if (response.status === 401) {
+            this.clearCachedAccessToken();
+            accessToken = await this.getAccessToken();
+            response = await this.requestJson(url, accessToken, "detections search");
+            responseText = await response.text();
+        }
+        if (!response.ok) {
+            throw new APIException(`Google SecOps detections search failed (HTTP ${response.status}): ${GoogleSecOpsClient.redactErrorBody(responseText)}` +
+                GoogleSecOpsClient.describeHttpFailure(response.status, responseText));
+        }
+        return GoogleSecOpsClient.parseSearchDetectionsBody(responseText);
+    }
+    /*
+     * Which curated rules produced detections in an interval, so the curated
+     * search can name each one: legacySearchCuratedDetections has no
+     * wildcard. One POST answers for every curated rule set on the instance,
+     * however many rules the tenant has enabled. Same token handling and
+     * one-shot 401 retry as the searches.
+     *
+     * Contract, verified against Google's reference pages:
+     *   POST {base}:countAllCuratedRuleSetDetections
+     *     { interval: { startTime, endTime } }
+     *   → { curatedRuleSetCounts: [{curatedRuleSet, count}],
+     *       curatedRuleCounts: [{curatedRule, precision, count}] }
+     * https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances/countAllCuratedRuleSetDetections
+     * https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/CuratedRuleCount
+     */
+    async countCuratedRuleDetections(data) {
+        let accessToken = await this.getAccessToken();
+        const url = `${this.getApiBaseUrl()}:countAllCuratedRuleSetDetections`;
+        const body = JSON.stringify({
+            interval: {
+                startTime: data.startTime.toISOString(),
+                endTime: data.endTime.toISOString(),
+            },
+        });
+        let response = await this.postJson(url, accessToken, body, "curated rule detection counts");
+        let responseText = await response.text();
+        if (response.status === 401) {
+            this.clearCachedAccessToken();
+            accessToken = await this.getAccessToken();
+            response = await this.postJson(url, accessToken, body, "curated rule detection counts");
+            responseText = await response.text();
+        }
+        if (!response.ok) {
+            throw new APIException(`Google SecOps curated rule detection counts failed (HTTP ${response.status}): ${GoogleSecOpsClient.redactErrorBody(responseText)}` +
+                GoogleSecOpsClient.describeHttpFailure(response.status, responseText));
+        }
+        return GoogleSecOpsClient.parseCuratedRuleCountsBody(responseText);
+    }
     /*
      * ---------------------------------------------------------------------
-     * Helpers. Everything below is deliberately declared after extractAlerts:
-     * SecurityEventsConnectorGuidanceAccuracy reads this file's method
-     * bodies by slicing between declarations, so a helper placed higher up
-     * would be counted as part of fetchDetectionAlerts.
+     * Helpers. Everything below is deliberately declared after extractAlerts
+     * and searchDetections: SecurityEventsConnectorGuidanceAccuracy reads
+     * this file's method bodies by slicing between declarations, so a helper
+     * placed higher up would be counted as part of fetchDetectionAlerts.
      * ---------------------------------------------------------------------
      */
     clearCachedAccessToken() {
@@ -324,6 +488,9 @@ export default class GoogleSecOpsClient {
         this.cachedAccessTokenExpiresAtInMs = 0;
     }
     async requestAlerts(url, accessToken) {
+        return this.requestJson(url, accessToken, "alerts fetch");
+    }
+    async requestJson(url, accessToken, stepLabel) {
         /*
          * Accept is not a formality here: leaving content negotiation to the
          * server default is what turns a proxy in the path into the
@@ -335,16 +502,174 @@ export default class GoogleSecOpsClient {
                 Authorization: `Bearer ${accessToken}`,
                 Accept: "application/json",
             },
-        }, "alerts fetch");
+        }, stepLabel);
+    }
+    async postJson(url, accessToken, body, stepLabel) {
+        return this.fetchWithTimeout(url, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+                Accept: "application/json",
+                "Content-Type": "application/json",
+            },
+            body: body,
+        }, stepLabel);
+    }
+    /*
+     * The ruleId a search sends. A rule search reads every rule through the
+     * documented wildcard; a curated search must name one curated rule, and
+     * refusing here is what keeps a wildcard from ever reaching the curated
+     * route again, where Google would answer it with an empty success.
+     */
+    static resolveSearchRuleId(curated, ruleId) {
+        if (!curated) {
+            return ruleId || ALL_RULES_WILDCARD;
+        }
+        const trimmed = (ruleId || "").trim();
+        if (!trimmed || !CURATED_RULE_ID_REGEX.test(trimmed)) {
+            throw new BadDataException("A curated rule detections search needs one curated rule id (ur_...); legacySearchCuratedDetections has no wildcard.");
+        }
+        return trimmed;
+    }
+    /*
+     * countAllCuratedRuleSetDetections' body: the curated rules that produced
+     * at least one detection, deduplicated by rule id (a rule can be counted
+     * once per precision) and ordered by id so every poll searches them in
+     * the same order. An unrecognized body throws for the same cursor-safety
+     * reason the other parsers do.
+     */
+    static parseCuratedRuleCountsBody(bodyText) {
+        var _a;
+        const text = (bodyText || "").trim();
+        if (!text) {
+            throw new APIException("Google SecOps curated rule detection counts returned an empty body.");
+        }
+        let root;
+        try {
+            root = JSON.parse(text);
+        }
+        catch (_b) {
+            throw new APIException("Google SecOps curated rule detection counts returned a non-JSON body.");
+        }
+        if (!GoogleSecOpsClient.isJsonObject(root)) {
+            throw new APIException(`Google SecOps curated rule detection counts returned an unrecognized response shape: ${GoogleSecOpsClient.redactErrorBody(text)}`);
+        }
+        if (GoogleSecOpsClient.isJsonObject(root["error"])) {
+            throw new APIException(`Google SecOps curated rule detection counts returned an error in the response: ${GoogleSecOpsClient.summarizeErrorObject(root["error"])}`);
+        }
+        const keys = Object.keys(root);
+        if (keys.length > 0 &&
+            !keys.some((key) => {
+                return RECOGNIZED_CURATED_COUNT_FIELDS.includes(key);
+            })) {
+            throw new APIException(`Google SecOps curated rule detection counts returned an unrecognized response shape: ${GoogleSecOpsClient.redactErrorBody(text)}`);
+        }
+        const counts = new Map();
+        const entries = root["curatedRuleCounts"];
+        if (Array.isArray(entries)) {
+            for (const entry of entries) {
+                if (!GoogleSecOpsClient.isJsonObject(entry)) {
+                    continue;
+                }
+                const name = typeof entry["curatedRule"] === "string" ? entry["curatedRule"] : "";
+                const ruleId = name.split("/").pop() || "";
+                // int32 in the reference, but tolerate the int64-as-string rendering.
+                const count = (_a = GoogleSecOpsClient.readNumber(entry["count"])) !== null && _a !== void 0 ? _a : 0;
+                if (!ruleId || !CURATED_RULE_ID_REGEX.test(ruleId) || count <= 0) {
+                    continue;
+                }
+                counts.set(ruleId, (counts.get(ruleId) || 0) + count);
+            }
+        }
+        return Array.from(counts.entries())
+            .sort((a, b) => {
+            return a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0;
+        })
+            .map((entry) => {
+            return { ruleId: entry[0], count: entry[1] };
+        });
+    }
+    static sleep(delayInMs) {
+        return new Promise((resolve) => {
+            setTimeout(resolve, delayInMs);
+        });
+    }
+    static clampSearchPageSize(pageSize) {
+        if (typeof pageSize !== "number" ||
+            !Number.isFinite(pageSize) ||
+            pageSize < 1) {
+            return DEFAULT_SEARCH_PAGE_SIZE;
+        }
+        return Math.min(MAX_SEARCH_PAGE_SIZE, Math.floor(pageSize));
+    }
+    /*
+     * The status the client wrote into its own "(HTTP <status>)" tail, so a
+     * caller can tell a 403 on the curated endpoint (a tenant without
+     * curated rules) from a 500 without parsing Google's body twice.
+     */
+    static readHttpStatus(error) {
+        const message = error instanceof Error ? error.message : String(error || "");
+        const match = message.match(HTTP_STATUS_TAIL_PATTERN);
+        return match && match[1] ? Number(match[1]) : null;
+    }
+    /*
+     * A unary JSON object, unlike the alerts view's stream. Empty means a
+     * quiet window; a body this parser does not recognize throws, for the
+     * same cursor-safety reason parseAlertsBody does.
+     */
+    static parseSearchDetectionsBody(bodyText) {
+        const text = (bodyText || "").trim();
+        if (!text) {
+            throw new APIException("Google SecOps detections search returned an empty body.");
+        }
+        let root;
+        try {
+            root = JSON.parse(text);
+        }
+        catch (_a) {
+            throw new APIException("Google SecOps detections search returned a non-JSON body.");
+        }
+        if (!GoogleSecOpsClient.isJsonObject(root)) {
+            throw new APIException(`Google SecOps detections search returned an unrecognized response shape: ${GoogleSecOpsClient.redactErrorBody(text)}`);
+        }
+        if (GoogleSecOpsClient.isJsonObject(root["error"])) {
+            throw new APIException(`Google SecOps detections search returned an error in the response: ${GoogleSecOpsClient.summarizeErrorObject(root["error"])}`);
+        }
+        const keys = Object.keys(root);
+        const recognized = keys.some((key) => {
+            return RECOGNIZED_SEARCH_FIELDS.includes(key);
+        });
+        if (keys.length > 0 && !recognized) {
+            throw new APIException(`Google SecOps detections search returned an unrecognized response shape: ${GoogleSecOpsClient.redactErrorBody(text)}`);
+        }
+        const detections = [];
+        // Both keys are read so a curated response on either route parses.
+        for (const key of ["detections", "curatedDetections"]) {
+            const list = root[key];
+            if (Array.isArray(list)) {
+                for (const item of list) {
+                    if (GoogleSecOpsClient.isJsonObject(item)) {
+                        detections.push(item);
+                    }
+                }
+            }
+        }
+        const token = root["nextPageToken"];
+        return {
+            detections: detections,
+            nextPageToken: typeof token === "string" && token ? token : null,
+            truncated: root["respTooLargeDetectionsTruncated"] === true,
+        };
     }
     async fetchWithTimeout(url, init, stepLabel) {
         const controller = new AbortController();
+        const timeoutInSeconds = Math.max(1, Math.round(this.requestTimeoutInMs / 1000));
         let timer;
         const timeout = new Promise((_resolve, reject) => {
             timer = setTimeout(() => {
                 controller.abort();
-                reject(new APIException(`Google SecOps ${stepLabel} timed out after ${REQUEST_TIMEOUT_IN_SECONDS} seconds with no response.`));
-            }, REQUEST_TIMEOUT_IN_MS);
+                reject(new APIException(`Google SecOps ${stepLabel} timed out after ${timeoutInSeconds} seconds with no response.`));
+            }, this.requestTimeoutInMs);
         });
         try {
             return await Promise.race([
@@ -365,7 +690,7 @@ export default class GoogleSecOpsClient {
         }
         catch (error) {
             if (controller.signal.aborted) {
-                throw new APIException(`Google SecOps ${stepLabel} timed out after ${REQUEST_TIMEOUT_IN_SECONDS} seconds with no response.`);
+                throw new APIException(`Google SecOps ${stepLabel} timed out after ${timeoutInSeconds} seconds with no response.`);
             }
             throw error;
         }
@@ -379,12 +704,17 @@ export default class GoogleSecOpsClient {
             parsed = new URL(tokenUri);
         }
         catch (_a) {
-            throw new BadDataException("Service account token_uri must be an absolute https URL.");
+            /*
+             * Every service-account rejection opens with "Service account JSON",
+             * the connection form's field title, so the person reading it knows
+             * which field to fix; the key inside it is named after that.
+             */
+            throw new BadDataException("Service account JSON token_uri must be an absolute https URL.");
         }
         const isGoogleHost = TOKEN_URI_HOSTS.indexOf(parsed.hostname) !== -1 ||
             parsed.hostname.endsWith(TOKEN_URI_HOST_SUFFIX);
         if (parsed.protocol !== "https:" || !isGoogleHost || parsed.username) {
-            throw new BadDataException("Service account token_uri must be an https URL on a Google host such as https://oauth2.googleapis.com/token.");
+            throw new BadDataException("Service account JSON token_uri must be an https URL on a Google host such as https://oauth2.googleapis.com/token.");
         }
     }
     static validatePrivateKey(privateKey) {
@@ -398,9 +728,13 @@ export default class GoogleSecOpsClient {
             createPrivateKey(privateKey);
         }
         catch (_a) {
-            throw new BadDataException("Service account private_key is not a readable PEM private key. Check that newlines are real newlines and the key is not encrypted.");
+            throw new BadDataException("Service account JSON private_key is not a readable PEM private key. Check that newlines are real newlines and the key is not encrypted.");
         }
     }
+    /*
+     * Public so GoogleSecOpsConnector.validateSettings can run every
+     * constructor rule at save time, without building a client.
+     */
     static validateRegionMatchesInstance(region, instanceResourceName) {
         const match = instanceResourceName.match(INSTANCE_LOCATION_REGEX);
         const location = match && match[1] ? match[1] : "";
@@ -503,13 +837,12 @@ export default class GoogleSecOpsClient {
         }
         if (!complete) {
             /*
-             * Warn rather than re-issue the whole GET in a loop the way Google's
-             * SDK does: the poller runs every minute over a 15-minute window
-             * with a minute of overlap, so a partial window is re-covered on the
-             * next tick, and a blocking retry inside a strictly sequential
-             * connection loop would let one slow tenant starve every other one.
+             * Reported rather than swallowed: fetchDetectionAlerts re-issues the
+             * GET a bounded number of times, and the poller holds its cursor when
+             * the last attempt is still partial, so the window is re-covered on
+             * the next tick instead of being lost.
              */
-            logger.warn("GoogleSecOpsClient: the alerts stream ended without complete=true; this window may be partial and will be re-covered by the next poll.");
+            logger.warn("GoogleSecOpsClient: the alerts stream ended without complete=true; this window may be partial and the cursor is held for it.");
         }
         if (alerts.length > maxReturnedAlerts) {
             /*
@@ -779,7 +1112,7 @@ export default class GoogleSecOpsClient {
             const metadata = GoogleSecOpsClient.errorInfoMetadata(error);
             const resource = String((metadata === null || metadata === void 0 ? void 0 : metadata["resource"]) || "");
             const permission = String((metadata === null || metadata === void 0 ? void 0 : metadata["permission"]) || "");
-            return `The service account lacks ${permission || "chronicle.legacies.legacyFetchAlertsView"} on ${resource || "the instance"}. Grant roles/chronicle.viewer (roles/chronicle.admin if Viewer is not enough on this tenant).`;
+            return `The service account lacks ${permission || "the chronicle.legacies read permission for this request"} on ${resource || "the instance"}. Grant roles/chronicle.viewer, which includes legacySearchDetections, legacySearchCuratedDetections, countAllCuratedRuleSetDetections and legacyFetchAlertsView (roles/chronicle.admin if Viewer is not enough on this tenant).`;
         }
         if (reason === "SERVICE_DISABLED") {
             return "The Chronicle API is not enabled on the project the instance is bound to. Enable it in the Google Cloud console.";