@oneuptime/common 12.0.32 → 12.0.34

package/Types/Rum/SessionReplayHealth.ts

@@ -0,0 +1,238 @@
+/*
+ * Recording health for one RUM application: the answer to "why are there
+ * no recordings?" as data rather than as silence.
+ *
+ * Two shapes live here. SessionReplayIngestStatusResponseDto is the JSON
+ * that POST /telemetry/rum/session-replay/ingest-status answers today
+ * plus its additive fields, every new one optional. RecordingHealthStatus
+ * is the normalised object the Dashboard builds from it (see
+ * parseRecordingHealthStatus in Common/Utils/Rum/SessionReplayHealth.ts)
+ * and the only input diagnoseRecordingHealth takes. Keeping the two apart
+ * is what lets the diagnosis be exhaustively tested against a stable
+ * shape while the wire grows a field at a time.
+ *
+ * One rule runs through both: a counter that could not be read is null,
+ * never 0. "0 refusals" and "the refusal counter is unreachable" are
+ * different facts and the UI says "unknown" for the second.
+ */
+
+/*
+ * WHY the ingest gate refused a chunk. This is the gate's EXISTING closed
+ * vocabulary (SessionReplayIngestService.gateChunkRequest), copied rather
+ * than invented: the refusal counters are keyed on the reason string the
+ * gate already puts on the chunk response, so a customer's support ticket,
+ * the recorder's debug log and this list all quote the same word.
+ */
+export type SessionReplayRefusalReason =
+  /* SESSION_REPLAY_INGEST_ENABLED=false on this deployment. */
+  | "ingest-disabled"
+  /* No recorder artifact is published, so nothing should be posting. */
+  | "instance-not-offering-replay"
+  /* The policy lookup threw; failed closed. */
+  | "policy-unavailable"
+  /* Project or application switched off, or an unknown identifier. */
+  | "not-enabled"
+  /* The Origin header is not in the application's allowed origins. */
+  | "origin-not-allowed"
+  /* The session already holds MAX_SESSION_REPLAY_CHUNKS_PER_SESSION. */
+  | "session-chunk-cap"
+  /* The server's sampling draw disagrees with the recorder's. */
+  | "not-sampled"
+  | "rate-limited"
+  /* The rate counter (Redis) was unreachable; failed closed. */
+  | "rate-counter-unavailable"
+  /* The project's daily byte budget is spent. */
+  | "budget-exhausted"
+  /* The budget counter (Redis) was unreachable; failed closed. */
+  | "budget-counter-unavailable"
+  /* The application's own monthly budget is spent. */
+  | "app-monthly-budget-exhausted"
+  /*
+   * Every frame in the request asserted consent Unknown while the
+   * application requires explicit consent. The recorder is told to keep
+   * recording (directive continue): the page simply has not called
+   * grantConsent() yet, and this is the count that tells the customer so.
+   */
+  | "consent-required";
+
+export const SESSION_REPLAY_REFUSAL_REASONS: ReadonlyArray<SessionReplayRefusalReason> =
+  [
+    "ingest-disabled",
+    "instance-not-offering-replay",
+    "policy-unavailable",
+    "not-enabled",
+    "origin-not-allowed",
+    "session-chunk-cap",
+    "not-sampled",
+    "rate-limited",
+    "rate-counter-unavailable",
+    "budget-exhausted",
+    "budget-counter-unavailable",
+    "app-monthly-budget-exhausted",
+    "consent-required",
+  ];
+
+export function isSessionReplayRefusalReason(
+  value: unknown,
+): value is SessionReplayRefusalReason {
+  return (
+    typeof value === "string" &&
+    (SESSION_REPLAY_REFUSAL_REASONS as ReadonlyArray<string>).includes(value)
+  );
+}
+
+export interface SessionReplayRefusalCount {
+  reason: SessionReplayRefusalReason;
+  count: number;
+}
+
+/*
+ * The wire response of /ingest-status. The first block is what the route
+ * has always answered; everything after it is additive and optional.
+ */
+export interface SessionReplayIngestStatusResponseDto {
+  isProjectAllowed: boolean;
+  isApplicationEnabled: boolean;
+  appIdentifier: string;
+  allowedOrigins: Array<string>;
+  samplePercentage: number;
+  captureTrigger: string;
+  /* ISO-8601 or null. */
+  lastChunkReceivedAt: string | null;
+  budgetExceededAt: string | null;
+  /* null = counter unreachable. */
+  projectBytesUsedToday: number | null;
+  dailyByteLimit: number;
+  applicationBytesUsedThisMonth: number | null;
+  monthlyBudgetInGB: number | null;
+
+  /* ---- Additive. ---- */
+  consentMode?: string;
+  maskingMode?: string;
+  retentionInDays?: number;
+  /* The recorder artifact version the /config route hands out; null when none is built. */
+  publishedRecorderVersion?: string | null;
+  /* RumApplication.lastSeenAt: the /config route stamps it on every fetch. */
+  lastConfigFetchAt?: string | null;
+  lastSessionStartedAt?: string | null;
+  sessionsLast24h?: number | null;
+  playableSessionsLast24h?: number | null;
+  /* null when the counter store is unreachable; [] when nothing was refused. */
+  refusalsLast24h?: Array<{ reason: string; count: number }> | null;
+  /*
+   * Chunks the server ACCEPTED (202) and then dropped in the ingest worker,
+   * by reason. Kept apart from refusals because the recorder was told these
+   * landed; an open vocabulary (scrub-incomplete, over-cap, erased, ...)
+   * because the worker's drop reasons are operational, not a contract.
+   */
+  dropsLast24h?: Array<{ reason: string; count: number }> | null;
+  /*
+   * What the recorder that most recently uploaded announced it can
+   * capture (SESSION_REPLAY_RECORDER_CAPABILITIES on the chunk envelope,
+   * the same vocabulary the manifest header carries). The setup guide and
+   * the health card show it so "no clicks in the rail" can be answered
+   * with "this recorder does not send click events" rather than left as a
+   * mystery. null = not reported (an older server, or no chunk yet);
+   * [] = a recorder uploaded and announced nothing, which is a different
+   * fact and reads as "unknown capabilities" on purpose.
+   */
+  recorderCapabilities?: Array<string> | null;
+}
+
+/* The policy half of the status, as the recorder would see it. */
+export interface RecordingHealthPolicy {
+  isProjectEnabled: boolean;
+  isApplicationEnabled: boolean;
+  /* SessionReplayCaptureTrigger value; "" when the server did not say. */
+  captureTrigger: string;
+  samplePercentage: number;
+  /* SessionReplayConsentMode value; "" when the server did not say. */
+  consentMode: string;
+  /* SessionReplayMaskingMode value; "" when the server did not say. */
+  maskingMode: string;
+  /* null when the server did not say. */
+  retentionInDays: number | null;
+}
+
+/*
+ * Normalised health status. Timestamps stay ISO strings (null when the
+ * event never happened); the diagnosis converts them against `now` so it
+ * remains a pure function of its inputs.
+ */
+export interface RecordingHealthStatus {
+  appIdentifier: string;
+  allowedOrigins: Array<string>;
+  policy: RecordingHealthPolicy;
+  /* null when no recorder artifact is published or the server did not say. */
+  publishedRecorderVersion: string | null;
+  lastConfigFetchAt: string | null;
+  lastChunkReceivedAt: string | null;
+  lastSessionStartedAt: string | null;
+  budgetExceededAt: string | null;
+  sessionsLast24h: number | null;
+  playableSessionsLast24h: number | null;
+  refusalsLast24h: Array<SessionReplayRefusalCount> | null;
+  /*
+   * Open vocabulary; see SessionReplayIngestStatusResponseDto.dropsLast24h.
+   * Optional as well as nullable: it was added after the surfaces that
+   * build this object, and absent means the same as null (unknown).
+   */
+  dropsLast24h?: Array<{ reason: string; count: number }> | null;
+  /*
+   * See SessionReplayIngestStatusResponseDto.recorderCapabilities. Carried
+   * through parseRecordingHealthStatus so the surfaces that already hold a
+   * RecordingHealthStatus do not have to keep a second parse of the same
+   * body alive. Optional as well as nullable for the same reason
+   * dropsLast24h is: it postdates the objects that build this shape.
+   */
+  recorderCapabilities?: Array<string> | null;
+  projectBytesUsedToday: number | null;
+  dailyByteLimit: number;
+  applicationBytesUsedThisMonth: number | null;
+  monthlyBudgetInGB: number | null;
+}
+
+/*
+ * In strict priority order. The diagnosis returns the FIRST state whose
+ * condition holds, so a project that is switched off is reported as
+ * switched off even when its refusal counters are also climbing.
+ */
+export type RecordingHealthState =
+  | "disabled-project"
+  | "disabled-app"
+  | "budget-paused"
+  | "refusing"
+  | "never-loaded"
+  | "loaded-never-uploaded"
+  | "stale"
+  | "healthy-quiet"
+  | "healthy"
+  | "unknown";
+
+export type RecordingHealthSeverity = "ok" | "info" | "warning" | "error";
+
+/* Where the one offered action takes the viewer. */
+export type RecordingHealthActionTarget =
+  | "app-settings"
+  | "project-settings"
+  | "setup-guide"
+  | "docs-consent"
+  | "docs-csp"
+  | "budget"
+  | "allowed-origins";
+
+export interface RecordingHealthAction {
+  label: string;
+  target: RecordingHealthActionTarget;
+}
+
+export interface RecordingHealthDiagnosis {
+  state: RecordingHealthState;
+  severity: RecordingHealthSeverity;
+  /* One line: names the cause. */
+  title: string;
+  /* One or two sentences: quantifies it. */
+  detail: string;
+  /* At most one. Absent when nothing in the product fixes the state. */
+  action?: RecordingHealthAction;
+}

package/Types/Telemetry/ErrorClass.ts

@@ -0,0 +1,274 @@
+/*
+ * The fault domain of a thrown value: whose problem is it?
+ *
+ * This is the canonical vocabulary for the whole platform. It was originally
+ * introduced as `ExceptionAIClassification` — an after-the-fact LLM verdict on
+ * an already-ingested exception group — but the same five values are what the
+ * emitting code needs in order to decide, at the moment an error is thrown,
+ * whether it is worth waking anyone up. That file now re-exports this one so
+ * there is exactly ONE answer to "what kind of failure is this" in the
+ * codebase, with several possible sources (declared > human > AI > default).
+ *
+ * - CodeFault: a defect in the monitored code — the only class the automatic
+ *   fix lane opens pull requests for. This is the BASE DEFAULT on purpose:
+ *   forgetting to classify an exception must leave it noisy, never silent.
+ * - UserError: expected consequence of invalid end-user input (bad
+ *   parameters, malformed values). The right change, if any, is earlier
+ *   validation and clearer error UX — routed to a human, never auto-fixed.
+ * - ExpectedDenial: an intentional check doing its job (auth failure,
+ *   plan/paywall denial, scanner/fuzzer probe tripping validation).
+ *   Never auto-fixed; optionally auto-archived.
+ * - Infrastructure: environmental conditions (timeouts, connection resets,
+ *   resource exhaustion) where a code "fix" is usually tuning — routed to a
+ *   human. NOTE: this stays an Issue. It is a real failure, just not one to
+ *   auto-fix.
+ * - Unknown: triage could not decide — treated conservatively (no automatic
+ *   fix, and still shown).
+ */
+enum ErrorClass {
+  CodeFault = "code-fault",
+  UserError = "user-error",
+  ExpectedDenial = "expected-denial",
+  Infrastructure = "infrastructure",
+  Unknown = "unknown",
+}
+
+/*
+ * The classes that do NOT warrant an Issue. Everything else — including
+ * Infrastructure and Unknown — stays loud.
+ *
+ * Exported as the single list so the emit path, the ingest path, the Issues
+ * list default scope and the AI detectors can never drift apart on which
+ * classes are suppressed.
+ */
+export const NON_ACTIONABLE_ERROR_CLASSES: ReadonlyArray<ErrorClass> = [
+  ErrorClass.UserError,
+  ErrorClass.ExpectedDenial,
+];
+
+export function isNonActionableErrorClass(value: unknown): boolean {
+  return NON_ACTIONABLE_ERROR_CLASSES.includes(value as ErrorClass);
+}
+
+/**
+ * Every value the enum can take, for validating strings that arrive from
+ * outside (an OTLP attribute, a database column written by an older release).
+ */
+export function toErrorClass(value: unknown): ErrorClass | null {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  const match: ErrorClass | undefined = Object.values(ErrorClass).find(
+    (candidate: ErrorClass) => {
+      return candidate === value;
+    },
+  );
+
+  return match ?? null;
+}
+
+/*
+ * `Symbol.for` rather than `Symbol()`: Common/ ships its own node_modules and
+ * is consumed by App/, Probe/, Runner/ and others, so this module can be
+ * instantiated more than once in a single process. A unique symbol would not
+ * match across those instances and a tag written by one copy would be
+ * invisible to another. The global symbol registry is keyed by string, so all
+ * copies agree.
+ */
+const ERROR_CLASS_SYMBOL: symbol = Symbol.for("oneuptime.error.class");
+const ERROR_CLASS_AUTHORITATIVE_SYMBOL: symbol = Symbol.for(
+  "oneuptime.error.class.authoritative",
+);
+const ERROR_REPORTED_SYMBOL: symbol = Symbol.for("oneuptime.error.reported");
+
+/**
+ * A fault domain plus how much to trust it.
+ *
+ * `authoritative: false` is a CLASS-LEVEL default — "BadDataException usually
+ * means the caller sent something wrong". It is a generalisation, so it is
+ * subject to the unit-of-work promotion: outside an HTTP request there is no
+ * caller, and the generalisation does not hold.
+ *
+ * `authoritative: true` is a SITE-LEVEL declaration — a developer looked at
+ * one specific throw or one specific log line and said what it is. That is a
+ * deliberate, reviewable judgment about a single place in the code, so it is
+ * never second-guessed. This is what lets a probe report "the endpoint we were
+ * asked to check is down" as a non-defect even though a probe check has no
+ * HTTP request around it.
+ */
+export interface DeclaredErrorClass {
+  errorClass: ErrorClass;
+  authoritative: boolean;
+}
+
+type Taggable = { [key: symbol]: unknown };
+
+function canTag(value: unknown): value is Taggable {
+  return (
+    value !== null && (typeof value === "object" || typeof value === "function")
+  );
+}
+
+/**
+ * Attach a fault domain to a thrown value.
+ *
+ * `enumerable: false` keeps it invisible to `JSON.stringify`,
+ * `Logger.redactBody` and `Telemetry.getExceptionAttributes`, so tagging can
+ * never change what a log line or a span attribute bag looks like.
+ *
+ * Never throws: this runs from the `Exception` constructor and from catch
+ * blocks, where a frozen object or a hostile Proxy must not take down the
+ * error path. Returns the value so it can be tagged inline.
+ */
+export function tagErrorClass<T>(
+  value: T,
+  errorClass: ErrorClass,
+  authoritative: boolean = false,
+): T {
+  if (!canTag(value)) {
+    return value;
+  }
+
+  try {
+    Object.defineProperty(value, ERROR_CLASS_SYMBOL, {
+      value: errorClass,
+      enumerable: false,
+      writable: true,
+      configurable: true,
+    });
+
+    if (authoritative) {
+      Object.defineProperty(value, ERROR_CLASS_AUTHORITATIVE_SYMBOL, {
+        value: true,
+        enumerable: false,
+        writable: true,
+        configurable: true,
+      });
+    }
+  } catch {
+    // Frozen / sealed / exotic object — the resolver falls back to CodeFault.
+  }
+
+  return value;
+}
+
+/**
+ * Declare the fault domain for ONE specific throw or log line, overriding the
+ * class-level default and exempting it from the unit-of-work promotion.
+ */
+export function tagErrorClassAuthoritative<T>(
+  value: T,
+  errorClass: ErrorClass,
+): T {
+  return tagErrorClass(value, errorClass, true);
+}
+
+/**
+ * Read the fault domain a thrown value declared for itself, or null when it
+ * declared none.
+ *
+ * A null return is meaningful and must stay distinct from
+ * `ErrorClass.Unknown`: "nobody predicted this" is the strongest possible
+ * signal that it is a bug, whereas Unknown means "we looked and could not
+ * tell". Callers turn null into CodeFault.
+ *
+ * Also duck-types off a plain `errorClass` property so an error crossing a
+ * process or module boundary (where the symbol is lost) can still declare
+ * itself.
+ */
+export function declaredErrorClass(value: unknown): DeclaredErrorClass | null {
+  if (!canTag(value)) {
+    return null;
+  }
+
+  try {
+    const authoritative: boolean =
+      value[ERROR_CLASS_AUTHORITATIVE_SYMBOL] === true;
+
+    const tagged: ErrorClass | null = toErrorClass(value[ERROR_CLASS_SYMBOL]);
+
+    if (tagged !== null) {
+      return { errorClass: tagged, authoritative: authoritative };
+    }
+
+    /*
+     * Duck-type off a plain property too, so an error that crossed a process
+     * or module boundary (where the symbol is lost) can still declare itself.
+     * A property survives serialization, so treat it as a deliberate
+     * declaration.
+     */
+    const ducked: ErrorClass | null = toErrorClass(
+      (value as { errorClass?: unknown }).errorClass,
+    );
+
+    if (ducked !== null) {
+      return { errorClass: ducked, authoritative: true };
+    }
+
+    return null;
+  } catch {
+    // Throwing getter on an exotic thrown value.
+    return null;
+  }
+}
+
+/**
+ * Mark a thrown value as already reported, returning whether it had ALREADY
+ * been marked.
+ *
+ * This is what stops one thrown error from filing N exception events as it
+ * propagates through N `@CaptureSpan` frames. The fingerprint hashes no spanId
+ * and no span name, so without this every frame's event lands in the same
+ * group and `occuranceCount` jumps by the depth of the call stack — measured
+ * at 3 for a create with a missing field and 6 for a permission-denied
+ * get-list.
+ *
+ * Untaggable values (a thrown string, a frozen object) always report `false`,
+ * i.e. they are reported every time. Over-reporting is the safe direction.
+ */
+export function markErrorReported(value: unknown): boolean {
+  if (!canTag(value)) {
+    return false;
+  }
+
+  try {
+    const alreadyReported: boolean = value[ERROR_REPORTED_SYMBOL] === true;
+
+    if (!alreadyReported) {
+      Object.defineProperty(value, ERROR_REPORTED_SYMBOL, {
+        value: true,
+        enumerable: false,
+        writable: true,
+        configurable: true,
+      });
+    }
+
+    return alreadyReported;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Test seam: forget that a value was reported. Only used by tests that reuse
+ * one error object across cases.
+ */
+export function clearErrorReported(value: unknown): void {
+  if (!canTag(value)) {
+    return;
+  }
+
+  try {
+    Object.defineProperty(value, ERROR_REPORTED_SYMBOL, {
+      value: false,
+      enumerable: false,
+      writable: true,
+      configurable: true,
+    });
+  } catch {
+    // Nothing to clear.
+  }
+}
+
+export default ErrorClass;

package/Types/Telemetry/TelemetryIngestSurface.ts

@@ -0,0 +1,95 @@
+/*
+ * Every distinct endpoint family that accepts a TelemetryIngestionKey.
+ *
+ * This enum exists so the "may this key write here?" decision is made in ONE
+ * place against a closed vocabulary, rather than each route inventing its own
+ * ad-hoc check. Each ingest route names the surface it is, the shared guard
+ * answers yes or no, and adding a new route becomes a conscious decision about
+ * whether a public browser key may reach it (the Record below will not compile
+ * until the new member is given a readable name).
+ *
+ * The string values are the wire/log form and are deliberately stable: they
+ * appear in refusal messages and in ingest logs, so renaming one changes what
+ * an operator greps for.
+ */
+enum TelemetryIngestSurface {
+  OtelTraces = "otel-traces",
+  OtelLogs = "otel-logs",
+  OtelMetrics = "otel-metrics",
+  OtelProfiles = "otel-profiles",
+  SessionReplay = "session-replay",
+  SourceMap = "source-map",
+  Syslog = "syslog",
+  Fluent = "fluent",
+  Pyroscope = "pyroscope",
+  KubernetesCost = "kubernetes-cost",
+  ChangeEvents = "change-events",
+  SecurityEvents = "security-events",
+  Grpc = "grpc",
+  Mqtt = "mqtt",
+}
+
+/*
+ * The only surfaces a Browser key may write to. This is an ALLOWLIST, not a
+ * denylist, on purpose: a surface added later is refused to browser keys until
+ * someone deliberately adds it here, so the failure mode of forgetting is
+ * "browser keys cannot reach a new endpoint" rather than "a key scraped off a
+ * public page can reach it".
+ *
+ * The four members are exactly what a real browser agent emits: OTLP traces,
+ * logs and metrics from the web SDKs, plus session replay chunks. Everything
+ * else is a server-side or infrastructure pipe that no page has any business
+ * calling - profiles, syslog, Fluent, Pyroscope, Kubernetes cost, gRPC, MQTT -
+ * or is a build-time artifact upload (source maps) that belongs in CI with a
+ * server key, not in the browser bundle, which would otherwise be able to
+ * overwrite the maps used to de-obfuscate everyone else's stack traces.
+ */
+export const BROWSER_ALLOWED_INGEST_SURFACES: ReadonlySet<TelemetryIngestSurface> =
+  new Set<TelemetryIngestSurface>([
+    TelemetryIngestSurface.OtelTraces,
+    TelemetryIngestSurface.OtelLogs,
+    TelemetryIngestSurface.OtelMetrics,
+    TelemetryIngestSurface.SessionReplay,
+  ]);
+
+/*
+ * Typed as a total Record rather than a partial lookup so that adding a member
+ * to the enum without naming it is a compile error, not a surface that
+ * silently reports itself by its raw slug in a customer-facing error.
+ */
+const INGEST_SURFACE_READABLE_NAMES: Record<TelemetryIngestSurface, string> = {
+  [TelemetryIngestSurface.OtelTraces]: "OTLP trace ingest",
+  [TelemetryIngestSurface.OtelLogs]: "OTLP log ingest",
+  [TelemetryIngestSurface.OtelMetrics]: "OTLP metric ingest",
+  [TelemetryIngestSurface.OtelProfiles]: "OTLP profile ingest",
+  [TelemetryIngestSurface.SessionReplay]: "session replay ingest",
+  [TelemetryIngestSurface.SourceMap]: "source map upload",
+  [TelemetryIngestSurface.Syslog]: "syslog ingest",
+  [TelemetryIngestSurface.Fluent]: "Fluentd / Fluent Bit ingest",
+  [TelemetryIngestSurface.Pyroscope]: "Pyroscope profile ingest",
+  [TelemetryIngestSurface.KubernetesCost]: "Kubernetes cost ingest",
+  [TelemetryIngestSurface.ChangeEvents]: "change event ingest",
+  [TelemetryIngestSurface.SecurityEvents]: "security event ingest",
+  [TelemetryIngestSurface.Grpc]: "gRPC ingest",
+  [TelemetryIngestSurface.Mqtt]: "MQTT ingest",
+};
+
+type GetIngestSurfaceReadableNameFunction = (
+  surface: TelemetryIngestSurface,
+) => string;
+
+export const getIngestSurfaceReadableName: GetIngestSurfaceReadableNameFunction =
+  (surface: TelemetryIngestSurface): string => {
+    /*
+     * The fallback guards the one case the type system cannot: a surface
+     * string that came off the wire, or out of an older row, and was cast
+     * into the enum. Echoing the raw slug beats rendering "undefined" in a
+     * refusal message.
+     */
+    const readableName: string | undefined =
+      INGEST_SURFACE_READABLE_NAMES[surface];
+
+    return readableName || String(surface);
+  };
+
+export default TelemetryIngestSurface;

package/Types/Telemetry/TelemetryIngestionKeyPolicy.ts

@@ -0,0 +1,75 @@
+import ObjectID from "../ObjectID";
+import TelemetryIngestionKeyType from "./TelemetryIngestionKeyType";
+
+/*
+ * The resolved, ingest-time view of one TelemetryIngestionKey: everything the
+ * guard needs to decide whether to accept a request, and nothing else.
+ *
+ * It is a plain type rather than the model itself so the hot path can cache it
+ * (and so nothing downstream is tempted to reach for the model's other
+ * columns, or to write through it). Note what is deliberately ABSENT: the
+ * secret. Once a request has been authenticated the secret has done its job,
+ * and a value that must never be logged is safest in a shape that never
+ * carries it.
+ *
+ * Every field is non-optional - null is spelled out - because these are
+ * decisions, and "the caller forgot to set it" must not be indistinguishable
+ * from "there is deliberately no limit here".
+ */
+export default interface TelemetryIngestionKeyPolicy {
+  ingestionKeyId: ObjectID;
+  projectId: ObjectID;
+
+  keyType: TelemetryIngestionKeyType;
+
+  /*
+   * Origins this key may be used from. REQUIRED and strictly enforced on a
+   * Browser key (empty means the key cannot be used at all, since a public
+   * key with no origin binding is just a key anyone may write with); IGNORED
+   * on a Server key, which has no Origin header to check in the first place.
+   *
+   * Note this is the opposite polarity from
+   * RumApplication.sessionReplayAllowedOrigins, where empty means "any
+   * origin". That column is an optional hardening control on an existing
+   * feature and could not be tightened without breaking live installations;
+   * this one is on a key type that did not exist before, so it can start
+   * closed.
+   */
+  allowedOrigins: Array<string>;
+
+  /*
+   * When set, every OTLP resource ingested with this key has its service.name
+   * REPLACED with this value. Null means the payload's own service.name is
+   * kept (the historical behaviour, and the only sane one for a server key
+   * that legitimately reports for many services).
+   */
+  pinnedServiceName: string | null;
+
+  /* Kill switch. False refuses everything, immediately, without deleting. */
+  isEnabled: boolean;
+
+  /* Null means never expires - the historical behaviour of every key. */
+  expiresAt: Date | null;
+
+  /*
+   * Null means "no explicit limit configured", which resolves differently per
+   * key type: a Browser key falls back to
+   * DEFAULT_BROWSER_KEY_REQUESTS_PER_MINUTE, a Server key is unlimited.
+   */
+  requestsPerMinuteLimit: number | null;
+}
+
+/*
+ * Shipped ceiling for a Browser key that has not set its own limit.
+ *
+ * Sized to be irrelevant to honest traffic and material to an abuser: 6000
+ * requests/minute is 100/second sustained, which a real page cannot approach
+ * (browser SDKs batch and flush on an interval, so one visitor generates
+ * single-digit requests per minute), while a scraped key driven from a script
+ * hits it in seconds. The limit is per KEY, not per visitor, so it must clear
+ * the whole legitimate fleet behind one key - hence a headroom this generous
+ * rather than a tight per-client number.
+ *
+ * A customer who genuinely needs more sets requestsPerMinuteLimit explicitly.
+ */
+export const DEFAULT_BROWSER_KEY_REQUESTS_PER_MINUTE: number = 6000;