@camunda/ccma-shared-types 2.0.0 → 3.0.0

package/dist/_tests/permissions/session-permissions.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/approvals/policy.d.ts

@@ -50,6 +50,14 @@ export interface ApprovalActorView {
  * are one mailbox and must not pass as two people.
  */
 export declare function isSameActorEmail(one?: string, other?: string): boolean;
+/**
+ * Reports whether this actor carries an address that names a person.
+ *
+ * A machine-to-machine token carries none: accounts-backend builds the
+ * permissions of such a token from its `permissions` claim alone, and there is
+ * no person behind it. See `creatorEmailRequired` of the use case.
+ */
+export declare function hasActorEmail(actor: ApprovalActorView): boolean;
 /**
  * Why an action is not allowed.
  *
@@ -57,7 +65,7 @@ export declare function isSameActorEmail(one?: string, other?: string): boolean;
  * frontend can branch on it. The message is for a person, and it is shown as
  * written.
  */
-export type ApprovalDenialCode = 'forbidden' | 'not-pending' | 'self-approval' | 'already-acknowledged' | 'expired' | 'not-creator' | 'not-executable' | 'no-reason';
+export type ApprovalDenialCode = 'forbidden' | 'not-pending' | 'self-approval' | 'already-acknowledged' | 'expired' | 'not-creator' | 'not-executable' | 'no-reason' | 'too-few-acks' | 'no-creator-email';
 export type ApprovalDecision = {
     allowed: true;
 } | {
@@ -76,7 +84,75 @@ export declare function isExpired(job: ApprovalJobDto, now: Date): boolean;
 export declare function effectiveStatus(job: ApprovalJobDto, now: Date): ApprovalJobDto['status'];
 /** Reports how many more acknowledgements the request needs. */
 export declare function remainingAcks(job: ApprovalJobDto): number;
-export declare function canCreate(actor: ApprovalActorView, useCase: ApprovalUseCaseDto): ApprovalDecision;
+/**
+ * Reports whether the actor holds EVERY permission of the set.
+ *
+ * Every, and not one of them. A payload that raises the guard adds a
+ * permission, so "one of them" would let the base permission alone carry a
+ * request that the extra permission exists to stop.
+ *
+ * An EMPTY set is held by nobody. That is the opposite of what `Array.every`
+ * answers, and it is deliberate: this function guards a privileged action, so
+ * the empty case must fail closed. A row with no permissions is not a row that
+ * everybody may run — it is a row that lost its guard, through a migration
+ * that did not backfill it or a write that went around the service. Every use
+ * case builds a set of at least one, so no real request meets this branch.
+ */
+export declare function hasEveryPermission(actor: ApprovalActorView, permissions: string[]): boolean;
+/**
+ * What a person must hold to act on a request.
+ *
+ * A request carries its own set, because a payload can raise the guard. A use
+ * case that never does has a set of one, and it is the base permission.
+ */
+export declare function requiredPermissionsOf(job: ApprovalJobDto): string[];
+/**
+ * Who can READ a request.
+ *
+ * Two people: one who can act on it, and the one who opened it. A Camundi who
+ * holds neither has no reason to read which customer somebody proposed to
+ * expire, so the list and the detail both hide it.
+ *
+ * The rule reads the BASE permission of the use case and not the effective set
+ * of the request. A payload that raises the guard raises who can APPROVE, and
+ * not who can look: a generation update with the yolo flag is visible to
+ * everybody who can approve a plain one, and only the yolo permission runs it.
+ * The list filters by use case in SQL, which is what makes one page of rows
+ * the same page that a person is allowed to read.
+ */
+export declare function canView(job: ApprovalJobDto, actor: ApprovalActorView, useCase: ApprovalUseCaseDto): ApprovalDecision;
+/**
+ * Who can OPEN a request, and with what.
+ *
+ * `createPermission` is what keeps the pool that asks as small as the pool that
+ * approves. A use case that leaves it absent says the opposite on purpose: the
+ * approvals are the guard, and anybody signed in can propose the action.
+ *
+ * The two checks after it are about the request and not about the person. A
+ * count below the floor of the use case, and a missing reason, are both a 400
+ * and not a 403, so the words say which one the caller must repair.
+ */
+export declare function canCreate(actor: ApprovalActorView, useCase: ApprovalUseCaseDto, request?: {
+    reason?: string;
+    requiredAcks?: number;
+    /**
+     * The effective permissions of the payload, from `permissionsFor`.
+     *
+     * Absent means "the base permission alone", which is what most use cases
+     * build. Only the permissions ABOVE the base one gate opening a request:
+     * see the note in the body.
+     */
+    requiredPermissions?: string[];
+}): ApprovalDecision;
+/**
+ * The approvals that a new request asks for.
+ *
+ * The caller names a number or names none. A number below the floor is refused
+ * by `canCreate`, and this function holds the answer inside the range anyway:
+ * the two run in the same call, and a floor that only one of them knows is a
+ * floor that a later caller can step over.
+ */
+export declare function resolveRequiredAcks(useCase: ApprovalUseCaseDto, requested?: number): number;
 /**
  * The four-eyes rule.
  *
@@ -88,7 +164,7 @@ export declare function canCreate(actor: ApprovalActorView, useCase: ApprovalUse
  * token, and the email. See `ApprovalActorView.email` for why one of them is
  * not enough.
  */
-export declare function canAcknowledge(job: ApprovalJobDto, actor: ApprovalActorView, useCase: ApprovalUseCaseDto, now: Date): ApprovalDecision;
+export declare function canAcknowledge(job: ApprovalJobDto, actor: ApprovalActorView, now: Date): ApprovalDecision;
 /**
  * A rejection needs the same permission as an acknowledgement, and a reason.
  *
@@ -96,7 +172,7 @@ export declare function canAcknowledge(job: ApprovalJobDto, actor: ApprovalActor
  * and stopping it would only push the person to the withdraw button, where the
  * reason is lost.
  */
-export declare function canReject(job: ApprovalJobDto, actor: ApprovalActorView, useCase: ApprovalUseCaseDto, now: Date, reason: string): ApprovalDecision;
+export declare function canReject(job: ApprovalJobDto, actor: ApprovalActorView, now: Date, reason: string): ApprovalDecision;
 /** Only the person who opened a request can take it back. */
 export declare function canWithdraw(job: ApprovalJobDto, actor: ApprovalActorView, now: Date): ApprovalDecision;
 /**
@@ -105,5 +181,18 @@ export declare function canWithdraw(job: ApprovalJobDto, actor: ApprovalActorVie
  * This is the button of the explicit mode. `failed` is executable again,
  * because a failure is often a problem of the system that is now repaired, and
  * asking for the approvals a second time helps nobody.
+ *
+ * ANY holder of the permission may press it, and not only the person who
+ * opened the request. The decision was made when the request reached
+ * `approved`: `canAcknowledge` refuses the creator, so the approvals on the
+ * row came from other people, and the button only carries out what they
+ * already agreed to. Holding the button to the creator would let one Camundi
+ * on holiday freeze an approved action, and a use case that must not run
+ * without its author has `executionMode: 'auto'` instead.
+ *
+ * Who PRESSED it and who ASKED for it are two different facts, and both are
+ * kept: the audit trail of control-backend records the actor of the run, and
+ * an action that names a person to another service names the creator. See
+ * `onBehalfOf` of `extend-trial`.
  */
-export declare function canExecute(job: ApprovalJobDto, actor: ApprovalActorView, useCase: ApprovalUseCaseDto): ApprovalDecision;
+export declare function canExecute(job: ApprovalJobDto, actor: ApprovalActorView): ApprovalDecision;

package/dist/approvals/policy.js

@@ -1,11 +1,14 @@
 import { UNKNOWN_ACTOR_EMAIL } from "../constants/misc.const.js";
 function isSameActorEmail(one, other) {
-  const normalize = (value) => {
-    const trimmed = value?.trim().toLowerCase() ?? "";
-    return trimmed === UNKNOWN_ACTOR_EMAIL ? "" : trimmed;
-  };
-  const left = normalize(one);
-  return left.length > 0 && left === normalize(other);
+  const left = comparableActorEmail(one);
+  return left.length > 0 && left === comparableActorEmail(other);
+}
+function comparableActorEmail(value) {
+  const trimmed = value?.trim().toLowerCase() ?? "";
+  return trimmed === UNKNOWN_ACTOR_EMAIL ? "" : trimmed;
+}
+function hasActorEmail(actor) {
+  return comparableActorEmail(actor.email).length > 0;
 }
 const ALLOWED = { allowed: true };
 function deny(code, message) {
@@ -20,14 +23,56 @@ function effectiveStatus(job, now) {
 function remainingAcks(job) {
   return Math.max(0, job.requiredAcks - job.acks.length);
 }
-function canCreate(actor, useCase) {
+function hasEveryPermission(actor, permissions) {
+  if (permissions.length === 0) {
+    return false;
+  }
+  return permissions.every((permission) => actor.has(permission));
+}
+function requiredPermissionsOf(job) {
+  return job.requiredPermissions;
+}
+function canView(job, actor, useCase) {
+  if (actor.has(useCase.requiredPermission) || job.createdBy.userId === actor.userId || isSameActorEmail(job.createdBy.email, actor.email)) {
+    return ALLOWED;
+  }
+  return deny("forbidden", "You cannot see this request.");
+}
+function canCreate(actor, useCase, request = {}) {
   if (useCase.createPermission && !actor.has(useCase.createPermission)) {
     return deny("forbidden", "You cannot open this request.");
   }
+  const raised = (request.requiredPermissions ?? []).filter(
+    (permission) => permission !== useCase.requiredPermission
+  );
+  if (raised.length > 0 && !hasEveryPermission(actor, raised)) {
+    return deny("forbidden", "You cannot open this request.");
+  }
+  if (useCase.creatorEmailRequired && !hasActorEmail(actor)) {
+    return deny(
+      "no-creator-email",
+      "This action needs the email address of the person who asks for it, and your session carries none. Sign in as a person to open this request."
+    );
+  }
+  if (useCase.reasonRequired && (request.reason ?? "").trim().length === 0) {
+    return deny("no-reason", "Give a reason to open this request.");
+  }
+  if (request.requiredAcks !== void 0 && request.requiredAcks < useCase.minAcks) {
+    return deny(
+      "too-few-acks",
+      `This action needs at least ${useCase.minAcks} approvals.`
+    );
+  }
   return ALLOWED;
 }
-function canAcknowledge(job, actor, useCase, now) {
-  if (!actor.has(useCase.requiredPermission)) {
+function resolveRequiredAcks(useCase, requested) {
+  if (requested === void 0) {
+    return Math.max(useCase.defaultAcks, useCase.minAcks);
+  }
+  return Math.max(Math.trunc(requested), useCase.minAcks);
+}
+function canAcknowledge(job, actor, now) {
+  if (!hasEveryPermission(actor, job.requiredPermissions)) {
     return deny("forbidden", "You cannot approve this request.");
   }
   if (isExpired(job, now)) {
@@ -55,8 +100,8 @@ function canAcknowledge(job, actor, useCase, now) {
   }
   return ALLOWED;
 }
-function canReject(job, actor, useCase, now, reason) {
-  if (!actor.has(useCase.requiredPermission)) {
+function canReject(job, actor, now, reason) {
+  if (!hasEveryPermission(actor, job.requiredPermissions)) {
     return deny("forbidden", "You cannot reject this request.");
   }
   if (reason.trim().length === 0) {
@@ -97,8 +142,8 @@ function canWithdraw(job, actor, now) {
   }
   return ALLOWED;
 }
-function canExecute(job, actor, useCase) {
-  if (!actor.has(useCase.requiredPermission)) {
+function canExecute(job, actor) {
+  if (!hasEveryPermission(actor, job.requiredPermissions)) {
     return deny("forbidden", "You cannot run this request.");
   }
   if (job.status !== "approved" && job.status !== "failed") {
@@ -114,10 +159,15 @@ export {
   canCreate,
   canExecute,
   canReject,
+  canView,
   canWithdraw,
   effectiveStatus,
+  hasActorEmail,
+  hasEveryPermission,
   isExpired,
   isSameActorEmail,
-  remainingAcks
+  remainingAcks,
+  requiredPermissionsOf,
+  resolveRequiredAcks
 };
 //# sourceMappingURL=policy.js.map

package/dist/approvals/policy.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/approvals/policy.ts"],
-  "sourcesContent": ["/*\n * Copyright Camunda Services GmbH and/or licensed to Camunda Services GmbH\n * under one or more contributor license agreements. Licensed under a commercial license.\n * You may not use this file except in compliance with the commercial license.\n */\n\nimport { UNKNOWN_ACTOR_EMAIL } from '../constants/misc.const.js'\nimport type {\n  ApprovalJobDto,\n  ApprovalUseCaseDto,\n} from '../dtos/ApprovalJob.dto.js'\n\n/**\n * The rules of the approval mechanism, as pure functions.\n *\n * Three consumers run this file: control-backend decides whether to reject a\n * request, control-frontend decides whether to disable a button, and cloudbot\n * decides whether to answer. One copy means the button and the endpoint can\n * never disagree.\n *\n * Two choices in the signatures carry the design:\n *\n * - The actor is an interface with a `has` method. The backend holds an array\n *   of Auth0 claims, and `useSession()` in the frontend gives a flat record of\n *   booleans. Neither side has to convert to the shape of the other.\n * - `now` is a parameter. The expiry is lazy, so a stored `pending` request can\n *   be expired already. A parameter makes a difference between the two clocks\n *   an input that a test can set, and not a silent disagreement.\n *\n * No function here does I/O or returns a promise. The browser call site is what\n * enforces that, and it also stops a later use case from turning a list of 50\n * rows into 200 network calls.\n */\n\n/** Who is asking. See the note above on why this is an interface. */\nexport interface ApprovalActorView {\n  userId: string\n  /**\n   * The email of the actor. It is the SECOND identity of the four-eyes rule.\n   *\n   * `userId` alone is not enough. One person can hold more than one identity in\n   * Auth0 \u2014 a connection through SSO and a connection through a database, or an\n   * account that was made again \u2014 and each one carries a different `sub`. The\n   * same human then opens a request with one identity and approves it with the\n   * other, which is the rule defeated.\n   *\n   * It is optional because a token can carry no email. See\n   * `isSameActorEmail` for what that means for the comparison.\n   */\n  email?: string\n  has(permission: string): boolean\n}\n\n/**\n * Reports whether two email addresses name one person.\n *\n * Two values that are absent, empty, or `UNKNOWN_ACTOR_EMAIL` are NOT one\n * person. A token with no email would otherwise make every actor equal to\n * every other actor, and the rule would refuse everybody.\n *\n * The comparison removes the spaces and the case. Auth0 gives the address as\n * the identity provider wrote it, so `A.B@camunda.com` and `a.b@camunda.com`\n * are one mailbox and must not pass as two people.\n */\nexport function isSameActorEmail(one?: string, other?: string): boolean {\n  const normalize = (value?: string): string => {\n    const trimmed = value?.trim().toLowerCase() ?? ''\n    return trimmed === UNKNOWN_ACTOR_EMAIL ? '' : trimmed\n  }\n  const left = normalize(one)\n  return left.length > 0 && left === normalize(other)\n}\n\n/**\n * Why an action is not allowed.\n *\n * The code is for a program: control-backend maps it to a status, and the\n * frontend can branch on it. The message is for a person, and it is shown as\n * written.\n */\nexport type ApprovalDenialCode =\n  | 'forbidden'\n  | 'not-pending'\n  | 'self-approval'\n  | 'already-acknowledged'\n  | 'expired'\n  | 'not-creator'\n  | 'not-executable'\n  | 'no-reason'\n\nexport type ApprovalDecision =\n  | { allowed: true }\n  | { allowed: false; code: ApprovalDenialCode; message: string }\n\nconst ALLOWED: ApprovalDecision = { allowed: true }\n\nfunction deny(code: ApprovalDenialCode, message: string): ApprovalDecision {\n  return { allowed: false, code, message }\n}\n\n/**\n * Reports whether the time to answer a request has passed.\n *\n * Only a `pending` request expires. A request that already reached an end state\n * keeps that state, because \"expired\" would lose the answer that was given.\n */\nexport function isExpired(job: ApprovalJobDto, now: Date): boolean {\n  return (\n    job.status === 'pending' &&\n    new Date(job.expiresAt).getTime() <= now.getTime()\n  )\n}\n\n/** Reports the status to show, which is `expired` once the time has passed. */\nexport function effectiveStatus(\n  job: ApprovalJobDto,\n  now: Date,\n): ApprovalJobDto['status'] {\n  return isExpired(job, now) ? 'expired' : job.status\n}\n\n/** Reports how many more acknowledgements the request needs. */\nexport function remainingAcks(job: ApprovalJobDto): number {\n  return Math.max(0, job.requiredAcks - job.acks.length)\n}\n\nexport function canCreate(\n  actor: ApprovalActorView,\n  useCase: ApprovalUseCaseDto,\n): ApprovalDecision {\n  if (useCase.createPermission && !actor.has(useCase.createPermission)) {\n    return deny('forbidden', 'You cannot open this request.')\n  }\n  return ALLOWED\n}\n\n/**\n * The four-eyes rule.\n *\n * The bans are in the order a person meets them, and each one has its own\n * message: \"you already approved this\" and \"you cannot approve your own\n * request\" are different mistakes, and one message for both helps nobody.\n *\n * Each of the two bans on a person reads BOTH identities: the `sub` of the\n * token, and the email. See `ApprovalActorView.email` for why one of them is\n * not enough.\n */\nexport function canAcknowledge(\n  job: ApprovalJobDto,\n  actor: ApprovalActorView,\n  useCase: ApprovalUseCaseDto,\n  now: Date,\n): ApprovalDecision {\n  if (!actor.has(useCase.requiredPermission)) {\n    return deny('forbidden', 'You cannot approve this request.')\n  }\n  if (isExpired(job, now)) {\n    return deny(\n      'expired',\n      'This request expired and can no longer be approved.',\n    )\n  }\n  if (job.status !== 'pending') {\n    return deny(\n      'not-pending',\n      `This request is ${job.status} and can no longer be approved.`,\n    )\n  }\n  if (\n    job.createdBy.userId === actor.userId ||\n    isSameActorEmail(job.createdBy.email, actor.email)\n  ) {\n    return deny(\n      'self-approval',\n      'You opened this request, so you cannot approve it.',\n    )\n  }\n  if (\n    job.acks.some(\n      (ack) =>\n        ack.userId === actor.userId || isSameActorEmail(ack.email, actor.email),\n    )\n  ) {\n    return deny('already-acknowledged', 'You already approved this request.')\n  }\n  return ALLOWED\n}\n\n/**\n * A rejection needs the same permission as an acknowledgement, and a reason.\n *\n * The creator MAY reject their own request. That is a withdrawal with a reason,\n * and stopping it would only push the person to the withdraw button, where the\n * reason is lost.\n */\nexport function canReject(\n  job: ApprovalJobDto,\n  actor: ApprovalActorView,\n  useCase: ApprovalUseCaseDto,\n  now: Date,\n  reason: string,\n): ApprovalDecision {\n  if (!actor.has(useCase.requiredPermission)) {\n    return deny('forbidden', 'You cannot reject this request.')\n  }\n  if (reason.trim().length === 0) {\n    return deny('no-reason', 'Give a reason to reject this request.')\n  }\n  if (isExpired(job, now)) {\n    return deny(\n      'expired',\n      'This request expired and can no longer be rejected.',\n    )\n  }\n  if (job.status !== 'pending') {\n    return deny(\n      'not-pending',\n      `This request is ${job.status} and can no longer be rejected.`,\n    )\n  }\n  return ALLOWED\n}\n\n/** Only the person who opened a request can take it back. */\nexport function canWithdraw(\n  job: ApprovalJobDto,\n  actor: ApprovalActorView,\n  now: Date,\n): ApprovalDecision {\n  if (job.createdBy.userId !== actor.userId) {\n    return deny(\n      'not-creator',\n      'Only the person who opened a request can withdraw it.',\n    )\n  }\n  if (isExpired(job, now)) {\n    return deny(\n      'expired',\n      'This request expired and can no longer be withdrawn.',\n    )\n  }\n  if (job.status !== 'pending') {\n    return deny(\n      'not-pending',\n      `This request is ${job.status} and can no longer be withdrawn.`,\n    )\n  }\n  return ALLOWED\n}\n\n/**\n * Runs a request that has its approvals.\n *\n * This is the button of the explicit mode. `failed` is executable again,\n * because a failure is often a problem of the system that is now repaired, and\n * asking for the approvals a second time helps nobody.\n */\nexport function canExecute(\n  job: ApprovalJobDto,\n  actor: ApprovalActorView,\n  useCase: ApprovalUseCaseDto,\n): ApprovalDecision {\n  if (!actor.has(useCase.requiredPermission)) {\n    return deny('forbidden', 'You cannot run this request.')\n  }\n  if (job.status !== 'approved' && job.status !== 'failed') {\n    return deny(\n      'not-executable',\n      `This request is ${job.status} and cannot be run.`,\n    )\n  }\n  return ALLOWED\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["/*\n * Copyright Camunda Services GmbH and/or licensed to Camunda Services GmbH\n * under one or more contributor license agreements. Licensed under a commercial license.\n * You may not use this file except in compliance with the commercial license.\n */\n\nimport { UNKNOWN_ACTOR_EMAIL } from '../constants/misc.const.js'\nimport type {\n  ApprovalJobDto,\n  ApprovalUseCaseDto,\n} from '../dtos/ApprovalJob.dto.js'\n\n/**\n * The rules of the approval mechanism, as pure functions.\n *\n * Three consumers run this file: control-backend decides whether to reject a\n * request, control-frontend decides whether to disable a button, and cloudbot\n * decides whether to answer. One copy means the button and the endpoint can\n * never disagree.\n *\n * Two choices in the signatures carry the design:\n *\n * - The actor is an interface with a `has` method. The backend holds an array\n *   of Auth0 claims, and `useSession()` in the frontend gives a flat record of\n *   booleans. Neither side has to convert to the shape of the other.\n * - `now` is a parameter. The expiry is lazy, so a stored `pending` request can\n *   be expired already. A parameter makes a difference between the two clocks\n *   an input that a test can set, and not a silent disagreement.\n *\n * No function here does I/O or returns a promise. The browser call site is what\n * enforces that, and it also stops a later use case from turning a list of 50\n * rows into 200 network calls.\n */\n\n/** Who is asking. See the note above on why this is an interface. */\nexport interface ApprovalActorView {\n  userId: string\n  /**\n   * The email of the actor. It is the SECOND identity of the four-eyes rule.\n   *\n   * `userId` alone is not enough. One person can hold more than one identity in\n   * Auth0 \u2014 a connection through SSO and a connection through a database, or an\n   * account that was made again \u2014 and each one carries a different `sub`. The\n   * same human then opens a request with one identity and approves it with the\n   * other, which is the rule defeated.\n   *\n   * It is optional because a token can carry no email. See\n   * `isSameActorEmail` for what that means for the comparison.\n   */\n  email?: string\n  has(permission: string): boolean\n}\n\n/**\n * Reports whether two email addresses name one person.\n *\n * Two values that are absent, empty, or `UNKNOWN_ACTOR_EMAIL` are NOT one\n * person. A token with no email would otherwise make every actor equal to\n * every other actor, and the rule would refuse everybody.\n *\n * The comparison removes the spaces and the case. Auth0 gives the address as\n * the identity provider wrote it, so `A.B@camunda.com` and `a.b@camunda.com`\n * are one mailbox and must not pass as two people.\n */\nexport function isSameActorEmail(one?: string, other?: string): boolean {\n  const left = comparableActorEmail(one)\n  return left.length > 0 && left === comparableActorEmail(other)\n}\n\n/**\n * The address in the one form that a comparison may use.\n *\n * An absent address, an empty one and `UNKNOWN_ACTOR_EMAIL` all become an\n * empty string, because none of the three names a person. The spaces and the\n * case go as well: Auth0 gives the address as the identity provider wrote it.\n */\nfunction comparableActorEmail(value?: string): string {\n  const trimmed = value?.trim().toLowerCase() ?? ''\n  return trimmed === UNKNOWN_ACTOR_EMAIL ? '' : trimmed\n}\n\n/**\n * Reports whether this actor carries an address that names a person.\n *\n * A machine-to-machine token carries none: accounts-backend builds the\n * permissions of such a token from its `permissions` claim alone, and there is\n * no person behind it. See `creatorEmailRequired` of the use case.\n */\nexport function hasActorEmail(actor: ApprovalActorView): boolean {\n  return comparableActorEmail(actor.email).length > 0\n}\n\n/**\n * Why an action is not allowed.\n *\n * The code is for a program: control-backend maps it to a status, and the\n * frontend can branch on it. The message is for a person, and it is shown as\n * written.\n */\nexport type ApprovalDenialCode =\n  | 'forbidden'\n  | 'not-pending'\n  | 'self-approval'\n  | 'already-acknowledged'\n  | 'expired'\n  | 'not-creator'\n  | 'not-executable'\n  | 'no-reason'\n  | 'too-few-acks'\n  | 'no-creator-email'\n\nexport type ApprovalDecision =\n  | { allowed: true }\n  | { allowed: false; code: ApprovalDenialCode; message: string }\n\nconst ALLOWED: ApprovalDecision = { allowed: true }\n\nfunction deny(code: ApprovalDenialCode, message: string): ApprovalDecision {\n  return { allowed: false, code, message }\n}\n\n/**\n * Reports whether the time to answer a request has passed.\n *\n * Only a `pending` request expires. A request that already reached an end state\n * keeps that state, because \"expired\" would lose the answer that was given.\n */\nexport function isExpired(job: ApprovalJobDto, now: Date): boolean {\n  return (\n    job.status === 'pending' &&\n    new Date(job.expiresAt).getTime() <= now.getTime()\n  )\n}\n\n/** Reports the status to show, which is `expired` once the time has passed. */\nexport function effectiveStatus(\n  job: ApprovalJobDto,\n  now: Date,\n): ApprovalJobDto['status'] {\n  return isExpired(job, now) ? 'expired' : job.status\n}\n\n/** Reports how many more acknowledgements the request needs. */\nexport function remainingAcks(job: ApprovalJobDto): number {\n  return Math.max(0, job.requiredAcks - job.acks.length)\n}\n\n/**\n * Reports whether the actor holds EVERY permission of the set.\n *\n * Every, and not one of them. A payload that raises the guard adds a\n * permission, so \"one of them\" would let the base permission alone carry a\n * request that the extra permission exists to stop.\n *\n * An EMPTY set is held by nobody. That is the opposite of what `Array.every`\n * answers, and it is deliberate: this function guards a privileged action, so\n * the empty case must fail closed. A row with no permissions is not a row that\n * everybody may run \u2014 it is a row that lost its guard, through a migration\n * that did not backfill it or a write that went around the service. Every use\n * case builds a set of at least one, so no real request meets this branch.\n */\nexport function hasEveryPermission(\n  actor: ApprovalActorView,\n  permissions: string[],\n): boolean {\n  if (permissions.length === 0) {\n    return false\n  }\n  return permissions.every((permission) => actor.has(permission))\n}\n\n/**\n * What a person must hold to act on a request.\n *\n * A request carries its own set, because a payload can raise the guard. A use\n * case that never does has a set of one, and it is the base permission.\n */\nexport function requiredPermissionsOf(job: ApprovalJobDto): string[] {\n  return job.requiredPermissions\n}\n\n/**\n * Who can READ a request.\n *\n * Two people: one who can act on it, and the one who opened it. A Camundi who\n * holds neither has no reason to read which customer somebody proposed to\n * expire, so the list and the detail both hide it.\n *\n * The rule reads the BASE permission of the use case and not the effective set\n * of the request. A payload that raises the guard raises who can APPROVE, and\n * not who can look: a generation update with the yolo flag is visible to\n * everybody who can approve a plain one, and only the yolo permission runs it.\n * The list filters by use case in SQL, which is what makes one page of rows\n * the same page that a person is allowed to read.\n */\nexport function canView(\n  job: ApprovalJobDto,\n  actor: ApprovalActorView,\n  useCase: ApprovalUseCaseDto,\n): ApprovalDecision {\n  if (\n    actor.has(useCase.requiredPermission) ||\n    job.createdBy.userId === actor.userId ||\n    isSameActorEmail(job.createdBy.email, actor.email)\n  ) {\n    return ALLOWED\n  }\n  return deny('forbidden', 'You cannot see this request.')\n}\n\n/**\n * Who can OPEN a request, and with what.\n *\n * `createPermission` is what keeps the pool that asks as small as the pool that\n * approves. A use case that leaves it absent says the opposite on purpose: the\n * approvals are the guard, and anybody signed in can propose the action.\n *\n * The two checks after it are about the request and not about the person. A\n * count below the floor of the use case, and a missing reason, are both a 400\n * and not a 403, so the words say which one the caller must repair.\n */\nexport function canCreate(\n  actor: ApprovalActorView,\n  useCase: ApprovalUseCaseDto,\n  request: {\n    reason?: string\n    requiredAcks?: number\n    /**\n     * The effective permissions of the payload, from `permissionsFor`.\n     *\n     * Absent means \"the base permission alone\", which is what most use cases\n     * build. Only the permissions ABOVE the base one gate opening a request:\n     * see the note in the body.\n     */\n    requiredPermissions?: string[]\n  } = {},\n): ApprovalDecision {\n  if (useCase.createPermission && !actor.has(useCase.createPermission)) {\n    return deny('forbidden', 'You cannot open this request.')\n  }\n  // What the PAYLOAD raised, on top of the base permission of the use case.\n  // A bulk generation update with the yolo flag needs the yolo permission, and\n  // without this check a person who holds the base permission alone could open\n  // one. They could not approve it and could not run it, so it is not an\n  // escalation \u2014 it is a request that its own author is not allowed to make,\n  // waiting in the queue of the people who are.\n  //\n  // The BASE permission is deliberately not checked here. `createPermission`\n  // above is the only gate on the person, and a use case that leaves it absent\n  // means that anybody signed in can propose the action. Checking the base\n  // permission too would take that choice away from every use case.\n  const raised = (request.requiredPermissions ?? []).filter(\n    (permission) => permission !== useCase.requiredPermission,\n  )\n  if (raised.length > 0 && !hasEveryPermission(actor, raised)) {\n    return deny('forbidden', 'You cannot open this request.')\n  }\n  // The action of this use case carries the address of the person who asked,\n  // so a caller with no address must be refused HERE. The alternative is a\n  // request that looks ordinary, collects its approvals over days, and then\n  // fails because the other service cannot find a user called \"unknown\".\n  if (useCase.creatorEmailRequired && !hasActorEmail(actor)) {\n    return deny(\n      'no-creator-email',\n      'This action needs the email address of the person who asks for it, ' +\n        'and your session carries none. Sign in as a person to open this ' +\n        'request.',\n    )\n  }\n  if (useCase.reasonRequired && (request.reason ?? '').trim().length === 0) {\n    return deny('no-reason', 'Give a reason to open this request.')\n  }\n  if (\n    request.requiredAcks !== undefined &&\n    request.requiredAcks < useCase.minAcks\n  ) {\n    return deny(\n      'too-few-acks',\n      `This action needs at least ${useCase.minAcks} approvals.`,\n    )\n  }\n  return ALLOWED\n}\n\n/**\n * The approvals that a new request asks for.\n *\n * The caller names a number or names none. A number below the floor is refused\n * by `canCreate`, and this function holds the answer inside the range anyway:\n * the two run in the same call, and a floor that only one of them knows is a\n * floor that a later caller can step over.\n */\nexport function resolveRequiredAcks(\n  useCase: ApprovalUseCaseDto,\n  requested?: number,\n): number {\n  if (requested === undefined) {\n    return Math.max(useCase.defaultAcks, useCase.minAcks)\n  }\n  return Math.max(Math.trunc(requested), useCase.minAcks)\n}\n\n/**\n * The four-eyes rule.\n *\n * The bans are in the order a person meets them, and each one has its own\n * message: \"you already approved this\" and \"you cannot approve your own\n * request\" are different mistakes, and one message for both helps nobody.\n *\n * Each of the two bans on a person reads BOTH identities: the `sub` of the\n * token, and the email. See `ApprovalActorView.email` for why one of them is\n * not enough.\n */\nexport function canAcknowledge(\n  job: ApprovalJobDto,\n  actor: ApprovalActorView,\n  now: Date,\n): ApprovalDecision {\n  if (!hasEveryPermission(actor, job.requiredPermissions)) {\n    return deny('forbidden', 'You cannot approve this request.')\n  }\n  if (isExpired(job, now)) {\n    return deny(\n      'expired',\n      'This request expired and can no longer be approved.',\n    )\n  }\n  if (job.status !== 'pending') {\n    return deny(\n      'not-pending',\n      `This request is ${job.status} and can no longer be approved.`,\n    )\n  }\n  if (\n    job.createdBy.userId === actor.userId ||\n    isSameActorEmail(job.createdBy.email, actor.email)\n  ) {\n    return deny(\n      'self-approval',\n      'You opened this request, so you cannot approve it.',\n    )\n  }\n  if (\n    job.acks.some(\n      (ack) =>\n        ack.userId === actor.userId || isSameActorEmail(ack.email, actor.email),\n    )\n  ) {\n    return deny('already-acknowledged', 'You already approved this request.')\n  }\n  return ALLOWED\n}\n\n/**\n * A rejection needs the same permission as an acknowledgement, and a reason.\n *\n * The creator MAY reject their own request. That is a withdrawal with a reason,\n * and stopping it would only push the person to the withdraw button, where the\n * reason is lost.\n */\nexport function canReject(\n  job: ApprovalJobDto,\n  actor: ApprovalActorView,\n  now: Date,\n  reason: string,\n): ApprovalDecision {\n  if (!hasEveryPermission(actor, job.requiredPermissions)) {\n    return deny('forbidden', 'You cannot reject this request.')\n  }\n  if (reason.trim().length === 0) {\n    return deny('no-reason', 'Give a reason to reject this request.')\n  }\n  if (isExpired(job, now)) {\n    return deny(\n      'expired',\n      'This request expired and can no longer be rejected.',\n    )\n  }\n  if (job.status !== 'pending') {\n    return deny(\n      'not-pending',\n      `This request is ${job.status} and can no longer be rejected.`,\n    )\n  }\n  return ALLOWED\n}\n\n/** Only the person who opened a request can take it back. */\nexport function canWithdraw(\n  job: ApprovalJobDto,\n  actor: ApprovalActorView,\n  now: Date,\n): ApprovalDecision {\n  if (job.createdBy.userId !== actor.userId) {\n    return deny(\n      'not-creator',\n      'Only the person who opened a request can withdraw it.',\n    )\n  }\n  if (isExpired(job, now)) {\n    return deny(\n      'expired',\n      'This request expired and can no longer be withdrawn.',\n    )\n  }\n  if (job.status !== 'pending') {\n    return deny(\n      'not-pending',\n      `This request is ${job.status} and can no longer be withdrawn.`,\n    )\n  }\n  return ALLOWED\n}\n\n/**\n * Runs a request that has its approvals.\n *\n * This is the button of the explicit mode. `failed` is executable again,\n * because a failure is often a problem of the system that is now repaired, and\n * asking for the approvals a second time helps nobody.\n *\n * ANY holder of the permission may press it, and not only the person who\n * opened the request. The decision was made when the request reached\n * `approved`: `canAcknowledge` refuses the creator, so the approvals on the\n * row came from other people, and the button only carries out what they\n * already agreed to. Holding the button to the creator would let one Camundi\n * on holiday freeze an approved action, and a use case that must not run\n * without its author has `executionMode: 'auto'` instead.\n *\n * Who PRESSED it and who ASKED for it are two different facts, and both are\n * kept: the audit trail of control-backend records the actor of the run, and\n * an action that names a person to another service names the creator. See\n * `onBehalfOf` of `extend-trial`.\n */\nexport function canExecute(\n  job: ApprovalJobDto,\n  actor: ApprovalActorView,\n): ApprovalDecision {\n  if (!hasEveryPermission(actor, job.requiredPermissions)) {\n    return deny('forbidden', 'You cannot run this request.')\n  }\n  if (job.status !== 'approved' && job.status !== 'failed') {\n    return deny(\n      'not-executable',\n      `This request is ${job.status} and cannot be run.`,\n    )\n  }\n  return ALLOWED\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/approvals/use-cases.const.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The names and the value ranges of the registered use cases.
+ *
+ * control-backend owns the registry, and a frontend reads it at run time
+ * (`GET /api/approvals/use-cases`). Two things cannot wait for that answer:
+ *
+ * - **The identifier**, because a caller must NAME a use case to find it in the
+ *   registry, and to open a request of it.
+ * - **The range of a payload field**, because a form holds the value before any
+ *   call goes out.
+ *
+ * Both live here, so the schema of the service and the form of the browser can
+ * never hold different numbers.
+ */
+/** The identifier of each use case, on the wire and in the table. */
+export declare const APPROVAL_USE_CASE_TYPES: {
+    readonly sendToExpiredTrial: "send-to-expired-trial";
+    readonly extendTrial: "extend-trial";
+};
+export type ApprovalUseCaseType = (typeof APPROVAL_USE_CASE_TYPES)[keyof typeof APPROVAL_USE_CASE_TYPES];
+/**
+ * The shortest extension that accounts-backend accepts.
+ *
+ * `POST /:orgId/extendtrial` refuses a date that is less than 14 days away
+ * when the body carries `onBehalfOf`, and it measures those 14 days when the
+ * CALL arrives. The floor here is 15 and not 14, for two reasons:
+ *
+ * - The two clocks are not the same instant. Accounts builds its own "14 days
+ *   from now" a few milliseconds after control-backend builds the date, so a
+ *   date of exactly 14 days is already in the past for the comparison.
+ * - Accounts counts with `setDate`, which is calendar arithmetic. A change of
+ *   the daylight saving time moves its limit by an hour.
+ */
+export declare const EXTEND_TRIAL_MIN_DAYS = 15;
+/**
+ * The longest extension that accounts-backend accepts.
+ *
+ * The same route refuses a date more than 62 days away. 61 keeps the same
+ * margin as the floor above.
+ */
+export declare const EXTEND_TRIAL_MAX_DAYS = 61;

package/dist/approvals/use-cases.const.js

@@ -0,0 +1,12 @@
+const APPROVAL_USE_CASE_TYPES = {
+  sendToExpiredTrial: "send-to-expired-trial",
+  extendTrial: "extend-trial"
+};
+const EXTEND_TRIAL_MIN_DAYS = 15;
+const EXTEND_TRIAL_MAX_DAYS = 61;
+export {
+  APPROVAL_USE_CASE_TYPES,
+  EXTEND_TRIAL_MAX_DAYS,
+  EXTEND_TRIAL_MIN_DAYS
+};
+//# sourceMappingURL=use-cases.const.js.map

package/dist/approvals/use-cases.const.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/approvals/use-cases.const.ts"],
+  "sourcesContent": ["/*\n * Copyright Camunda Services GmbH and/or licensed to Camunda Services GmbH\n * under one or more contributor license agreements. Licensed under a commercial license.\n * You may not use this file except in compliance with the commercial license.\n */\n\n/**\n * The names and the value ranges of the registered use cases.\n *\n * control-backend owns the registry, and a frontend reads it at run time\n * (`GET /api/approvals/use-cases`). Two things cannot wait for that answer:\n *\n * - **The identifier**, because a caller must NAME a use case to find it in the\n *   registry, and to open a request of it.\n * - **The range of a payload field**, because a form holds the value before any\n *   call goes out.\n *\n * Both live here, so the schema of the service and the form of the browser can\n * never hold different numbers.\n */\n\n/** The identifier of each use case, on the wire and in the table. */\nexport const APPROVAL_USE_CASE_TYPES = {\n  sendToExpiredTrial: 'send-to-expired-trial',\n  extendTrial: 'extend-trial',\n} as const\n\nexport type ApprovalUseCaseType =\n  (typeof APPROVAL_USE_CASE_TYPES)[keyof typeof APPROVAL_USE_CASE_TYPES]\n\n/**\n * The shortest extension that accounts-backend accepts.\n *\n * `POST /:orgId/extendtrial` refuses a date that is less than 14 days away\n * when the body carries `onBehalfOf`, and it measures those 14 days when the\n * CALL arrives. The floor here is 15 and not 14, for two reasons:\n *\n * - The two clocks are not the same instant. Accounts builds its own \"14 days\n *   from now\" a few milliseconds after control-backend builds the date, so a\n *   date of exactly 14 days is already in the past for the comparison.\n * - Accounts counts with `setDate`, which is calendar arithmetic. A change of\n *   the daylight saving time moves its limit by an hour.\n */\nexport const EXTEND_TRIAL_MIN_DAYS = 15\n\n/**\n * The longest extension that accounts-backend accepts.\n *\n * The same route refuses a date more than 62 days away. 61 keeps the same\n * margin as the floor above.\n */\nexport const EXTEND_TRIAL_MAX_DAYS = 61\n"],
+  "mappings": "AAsBO,MAAM,0BAA0B;AAAA,EACrC,oBAAoB;AAAA,EACpB,aAAa;AACf;AAkBO,MAAM,wBAAwB;AAQ9B,MAAM,wBAAwB;",
+  "names": []
+}

package/dist/dtos/AlertSubscription.dto.d.ts

@@ -13,6 +13,12 @@ export interface AlertSubscriptionDto {
     updated: Date;
     lastTimeTriggered?: Date;
     numberOfTimesTriggered: number;
+    /**
+     * The address of an `Email` subscription. alert-distributor adds it from the
+     * user id, which its list endpoint then replaces with the name of the user.
+     * Thus this field is the only reliable way to identify the person.
+     */
+    recepientEmail?: string;
 }
 export interface AlertSubscriptionEntryDto {
     errorMessage?: string;

package/dist/dtos/AlertSubscription.dto.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/dtos/AlertSubscription.dto.ts"],
-  "sourcesContent": ["/*\n * Copyright Camunda Services GmbH and/or licensed to Camunda Services GmbH\n * under one or more contributor license agreements. Licensed under a commercial license.\n * You may not use this file except in compliance with the commercial license.\n */\n\nimport type {\n  AlertSubscriptionReportType,\n  AlertSubscriptionType,\n} from '../enums/AlertSubscription.enum.js'\n\nexport interface AlertSubscriptionDto {\n  uuid: string\n  userIdOrWebhook: string\n  type: AlertSubscriptionType\n  report: AlertSubscriptionReportType\n  webhookAuth?: AlertSubscriptionWebhookAuth\n  createdBy: string\n  createdByName: string\n  created: Date\n  updatedBy: string\n  updatedByName: string\n  updated: Date\n  lastTimeTriggered?: Date\n  numberOfTimesTriggered: number\n}\n\nexport interface AlertSubscriptionEntryDto {\n  errorMessage?: string\n  errorType?: string\n  flowNodeId?: string\n  jobKey?: string\n  creationTime?: string\n  processInstanceId?: string\n  processName?: string\n  processVersion?: number\n  bpmnProcessId?: string\n}\n\nexport const HMAC_SUPPORTED_ALGORITHM = 'sha256'\nexport const HMAC_HEADER_POSITION = 'X-Camunda-Signature-256'\n\n/**\n * Webhook targets a customer may not point an alert at, to limit SSRF.\n *\n * Despite the name, each entry is a URL prefix, scheme included: callers match\n * with `url.href.startsWith(entry)`. So add entries as `https://<host>`, with\n * no trailing slash and no path.\n */\nexport const FORBIDDEN_HOSTNAMES_FOR_WEBHOOK_ALERTS = [\n  'https://camunda.com',\n  'https://console.cloud.camunda.io',\n  'https://accounts.cloud.camunda.io',\n  'https://console.camunda.io',\n  'https://accounts.camunda.io',\n  'https://console.ultrawombat.com',\n  'https://console.cloud.ultrawombat.com',\n  'https://accounts.cloud.ultrawombat.com',\n  'https://accounts.ultrawombat.com',\n  'https://console.cloud.dev.ultrawombat.com',\n  'https://console.dev.ultrawombat.com',\n  'https://accounts.cloud.dev.ultrawombat.com',\n  'https://accounts.dev.ultrawombat.com',\n  // Hub and consolelegacy, all stages.\n  // Note: This list contains URL prefixes (`https://<host>`), not bare hostnames.\n  // Callers compare with `url.href.startsWith(...)`.\n  'https://hub.dev.ultrawombat.com',\n  'https://hub.ultrawombat.com',\n  'https://hub.camunda.io',\n  'https://consolelegacy.dev.ultrawombat.com',\n  'https://consolelegacy.ultrawombat.com',\n  'https://consolelegacy.camunda.io',\n]\n\nexport type ALERT_SUBSCRIPTION_TYPES = 'ProcessAlert'\nexport type ALERT_SUBSCRIPTION_REPORT_TYPES = 'Email' | 'Webhook'\n\nexport interface AlertSubscriptionWebhookAuth {\n  hmac?: {\n    secret: string\n  }\n}\n\nexport type CheckFailedReason =\n  | 'urlEmpty'\n  | 'urlNoHead'\n  | 'generatedHmacNotAccepted'\n  | 'urlBad'\n  | 'urlPrivate'\n"],
-  "mappings": "AAuCO,MAAM,2BAA2B;AACjC,MAAM,uBAAuB;AAS7B,MAAM,yCAAyC;AAAA,EACpD;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA;AAAA;AAAA;AAAA,EAIA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;",
+  "sourcesContent": ["/*\n * Copyright Camunda Services GmbH and/or licensed to Camunda Services GmbH\n * under one or more contributor license agreements. Licensed under a commercial license.\n * You may not use this file except in compliance with the commercial license.\n */\n\nimport type {\n  AlertSubscriptionReportType,\n  AlertSubscriptionType,\n} from '../enums/AlertSubscription.enum.js'\n\nexport interface AlertSubscriptionDto {\n  uuid: string\n  userIdOrWebhook: string\n  type: AlertSubscriptionType\n  report: AlertSubscriptionReportType\n  webhookAuth?: AlertSubscriptionWebhookAuth\n  createdBy: string\n  createdByName: string\n  created: Date\n  updatedBy: string\n  updatedByName: string\n  updated: Date\n  lastTimeTriggered?: Date\n  numberOfTimesTriggered: number\n  /**\n   * The address of an `Email` subscription. alert-distributor adds it from the\n   * user id, which its list endpoint then replaces with the name of the user.\n   * Thus this field is the only reliable way to identify the person.\n   */\n  recepientEmail?: string\n}\n\nexport interface AlertSubscriptionEntryDto {\n  errorMessage?: string\n  errorType?: string\n  flowNodeId?: string\n  jobKey?: string\n  creationTime?: string\n  processInstanceId?: string\n  processName?: string\n  processVersion?: number\n  bpmnProcessId?: string\n}\n\nexport const HMAC_SUPPORTED_ALGORITHM = 'sha256'\nexport const HMAC_HEADER_POSITION = 'X-Camunda-Signature-256'\n\n/**\n * Webhook targets a customer may not point an alert at, to limit SSRF.\n *\n * Despite the name, each entry is a URL prefix, scheme included: callers match\n * with `url.href.startsWith(entry)`. So add entries as `https://<host>`, with\n * no trailing slash and no path.\n */\nexport const FORBIDDEN_HOSTNAMES_FOR_WEBHOOK_ALERTS = [\n  'https://camunda.com',\n  'https://console.cloud.camunda.io',\n  'https://accounts.cloud.camunda.io',\n  'https://console.camunda.io',\n  'https://accounts.camunda.io',\n  'https://console.ultrawombat.com',\n  'https://console.cloud.ultrawombat.com',\n  'https://accounts.cloud.ultrawombat.com',\n  'https://accounts.ultrawombat.com',\n  'https://console.cloud.dev.ultrawombat.com',\n  'https://console.dev.ultrawombat.com',\n  'https://accounts.cloud.dev.ultrawombat.com',\n  'https://accounts.dev.ultrawombat.com',\n  // Hub and consolelegacy, all stages.\n  // Note: This list contains URL prefixes (`https://<host>`), not bare hostnames.\n  // Callers compare with `url.href.startsWith(...)`.\n  'https://hub.dev.ultrawombat.com',\n  'https://hub.ultrawombat.com',\n  'https://hub.camunda.io',\n  'https://consolelegacy.dev.ultrawombat.com',\n  'https://consolelegacy.ultrawombat.com',\n  'https://consolelegacy.camunda.io',\n]\n\nexport type ALERT_SUBSCRIPTION_TYPES = 'ProcessAlert'\nexport type ALERT_SUBSCRIPTION_REPORT_TYPES = 'Email' | 'Webhook'\n\nexport interface AlertSubscriptionWebhookAuth {\n  hmac?: {\n    secret: string\n  }\n}\n\nexport type CheckFailedReason =\n  | 'urlEmpty'\n  | 'urlNoHead'\n  | 'generatedHmacNotAccepted'\n  | 'urlBad'\n  | 'urlPrivate'\n"],
+  "mappings": "AA6CO,MAAM,2BAA2B;AACjC,MAAM,uBAAuB;AAS7B,MAAM,yCAAyC;AAAA,EACpD;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA;AAAA;AAAA;AAAA,EAIA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;",
   "names": []
 }