@camunda/ccma-shared-types 3.0.0 → 5.0.0

package/dist/_tests/approvals/cluster-bulk-operation.spec.d.ts

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

package/dist/_tests/types/PreprodClusterTtl.type.spec.d.ts

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

package/dist/annotations/policy.d.ts

@@ -0,0 +1,98 @@
+import type { AnnotationDto } from '../dtos/Annotation.dto.js';
+/**
+ * The rules of the annotations, as pure functions.
+ *
+ * Two consumers run this file: control-backend decides whether to refuse a
+ * write, and control-frontend decides whether to show the button. One copy
+ * means the button and the route can never disagree.
+ *
+ * No function here does I/O or returns a promise, which is what keeps it safe
+ * for a browser bundle and for a list of 200 rows.
+ */
+/** Who is asking. The frontend has this from `useSession`. */
+export interface AnnotationActorView {
+    userId: string;
+    /**
+     * The address of the actor. It is the SECOND identity of the author rule,
+     * for the same reason as in the approvals: one person can hold two Auth0
+     * identities with two different `sub` values, and the author of a note must
+     * still be able to edit it after signing in through the other one.
+     */
+    email?: string;
+}
+/**
+ * Why a write was refused.
+ *
+ * The backend maps each code to a status, and the frontend shows the same
+ * words. See `ANNOTATION_DENIAL_MESSAGES`.
+ */
+export type AnnotationDenialCode = 'not-author' | 'empty-body' | 'body-too-long' | 'empty-tag' | 'tag-too-long';
+/**
+ * What a person reads for each denial.
+ *
+ * The MESSAGE is here, and not in the error catalogue of the backend, because
+ * the frontend shows it beside a disabled button before any request is sent.
+ * Two spellings of one rule is the drift that this file exists to stop.
+ */
+export declare const ANNOTATION_DENIAL_MESSAGES: Record<AnnotationDenialCode, string>;
+/** A rule that refused, with the code and the words for it. */
+export interface AnnotationDenial {
+    ok: false;
+    code: AnnotationDenialCode;
+    message: string;
+}
+/** A rule that let the write through. */
+export interface AnnotationAllowance {
+    ok: true;
+}
+export type AnnotationDecision = AnnotationAllowance | AnnotationDenial;
+/**
+ * Reports whether the actor wrote this annotation.
+ *
+ * The id is read first, and the address second. See `AnnotationActorView.email`
+ * for why one identity is not enough.
+ */
+export declare function isAuthor(annotation: AnnotationDto, actor: AnnotationActorView): boolean;
+/**
+ * Whether the actor can change the text of a note.
+ *
+ * Only the author. A note carries an opinion with a name on it, so a second
+ * person who edits it would put words in that person's mouth. Somebody who
+ * disagrees writes a note of their own, and both stay visible.
+ */
+export declare function canEditNote(annotation: AnnotationDto, actor: AnnotationActorView): AnnotationDecision;
+/**
+ * Whether the actor can remove an annotation.
+ *
+ * A NOTE follows `canEditNote`: the author, and nobody else.
+ *
+ * A TAG is different, and anybody can remove one. A tag is a grouping and not
+ * a statement, a wrong tag makes a search answer wrongly for everybody, and
+ * the person who can see the mistake is rarely the person who made it. The
+ * removal keeps the row, so who added it and who took it off both stay
+ * readable.
+ */
+export declare function canRemove(annotation: AnnotationDto, actor: AnnotationActorView): AnnotationDecision;
+/**
+ * Whether this text can be a note.
+ *
+ * The frontend runs it on every keystroke to hold the button, and the route
+ * runs it on the body that arrives. The Zod schema of the route holds the same
+ * two numbers, so a caller that skips the frontend still meets them.
+ */
+export declare function checkNoteBody(body: string): AnnotationDecision;
+/**
+ * Whether this text can be a tag name.
+ *
+ * The dictionary stores TWO values for one tag, so both are measured. The
+ * identity is `normalizeTagName(name)`, which the unique index holds, and the
+ * displayed name is `name.trim()`, which is what a reader sees on every badge.
+ * They are not the same length: normalizing turns a run of inner spaces into
+ * one hyphen, so `a<many spaces>b` is shorter after it than before. Measuring
+ * only the normalized value therefore let a display name through that is
+ * longer than the ceiling this function exists to hold.
+ *
+ * Emptiness is asked of the normalized value alone: a name of nothing but
+ * whitespace has no identity, whatever it looks like.
+ */
+export declare function checkTagName(name: string): AnnotationDecision;

package/dist/annotations/policy.js

@@ -0,0 +1,61 @@
+import { isSameActorEmail } from "../approvals/policy.js";
+import {
+  ANNOTATION_BODY_MAX,
+  ANNOTATION_TAG_NAME_MAX,
+  normalizeTagName
+} from "../dtos/Annotation.dto.js";
+const ANNOTATION_DENIAL_MESSAGES = {
+  "not-author": "Only the person who wrote a note can change or remove it.",
+  "empty-body": "A note needs some text.",
+  "body-too-long": `A note holds at most ${ANNOTATION_BODY_MAX} characters.`,
+  "empty-tag": "A tag needs a name.",
+  "tag-too-long": `A tag name holds at most ${ANNOTATION_TAG_NAME_MAX} characters.`
+};
+const ALLOW = { ok: true };
+function deny(code) {
+  return { ok: false, code, message: ANNOTATION_DENIAL_MESSAGES[code] };
+}
+function isAuthor(annotation, actor) {
+  if (annotation.createdBy.userId === actor.userId) {
+    return true;
+  }
+  return isSameActorEmail(annotation.createdBy.email, actor.email);
+}
+function canEditNote(annotation, actor) {
+  return isAuthor(annotation, actor) ? ALLOW : deny("not-author");
+}
+function canRemove(annotation, actor) {
+  if (annotation.kind === "tag") {
+    return ALLOW;
+  }
+  return canEditNote(annotation, actor);
+}
+function checkNoteBody(body) {
+  const trimmed = body.trim();
+  if (trimmed.length === 0) {
+    return deny("empty-body");
+  }
+  if (trimmed.length > ANNOTATION_BODY_MAX) {
+    return deny("body-too-long");
+  }
+  return ALLOW;
+}
+function checkTagName(name) {
+  const normalized = normalizeTagName(name);
+  if (normalized.length === 0) {
+    return deny("empty-tag");
+  }
+  if (normalized.length > ANNOTATION_TAG_NAME_MAX || name.trim().length > ANNOTATION_TAG_NAME_MAX) {
+    return deny("tag-too-long");
+  }
+  return ALLOW;
+}
+export {
+  ANNOTATION_DENIAL_MESSAGES,
+  canEditNote,
+  canRemove,
+  checkNoteBody,
+  checkTagName,
+  isAuthor
+};
+//# sourceMappingURL=policy.js.map

package/dist/annotations/policy.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/annotations/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 { isSameActorEmail } from '../approvals/policy.js'\nimport type { AnnotationDto } from '../dtos/Annotation.dto.js'\nimport {\n  ANNOTATION_BODY_MAX,\n  ANNOTATION_TAG_NAME_MAX,\n  normalizeTagName,\n} from '../dtos/Annotation.dto.js'\n\n/**\n * The rules of the annotations, as pure functions.\n *\n * Two consumers run this file: control-backend decides whether to refuse a\n * write, and control-frontend decides whether to show the button. One copy\n * means the button and the route can never disagree.\n *\n * No function here does I/O or returns a promise, which is what keeps it safe\n * for a browser bundle and for a list of 200 rows.\n */\n\n/** Who is asking. The frontend has this from `useSession`. */\nexport interface AnnotationActorView {\n  userId: string\n  /**\n   * The address of the actor. It is the SECOND identity of the author rule,\n   * for the same reason as in the approvals: one person can hold two Auth0\n   * identities with two different `sub` values, and the author of a note must\n   * still be able to edit it after signing in through the other one.\n   */\n  email?: string\n}\n\n/**\n * Why a write was refused.\n *\n * The backend maps each code to a status, and the frontend shows the same\n * words. See `ANNOTATION_DENIAL_MESSAGES`.\n */\nexport type AnnotationDenialCode =\n  | 'not-author'\n  | 'empty-body'\n  | 'body-too-long'\n  | 'empty-tag'\n  | 'tag-too-long'\n\n/**\n * What a person reads for each denial.\n *\n * The MESSAGE is here, and not in the error catalogue of the backend, because\n * the frontend shows it beside a disabled button before any request is sent.\n * Two spellings of one rule is the drift that this file exists to stop.\n */\nexport const ANNOTATION_DENIAL_MESSAGES: Record<AnnotationDenialCode, string> =\n  {\n    'not-author': 'Only the person who wrote a note can change or remove it.',\n    'empty-body': 'A note needs some text.',\n    'body-too-long': `A note holds at most ${ANNOTATION_BODY_MAX} characters.`,\n    'empty-tag': 'A tag needs a name.',\n    'tag-too-long': `A tag name holds at most ${ANNOTATION_TAG_NAME_MAX} characters.`,\n  }\n\n/** A rule that refused, with the code and the words for it. */\nexport interface AnnotationDenial {\n  ok: false\n  code: AnnotationDenialCode\n  message: string\n}\n\n/** A rule that let the write through. */\nexport interface AnnotationAllowance {\n  ok: true\n}\n\nexport type AnnotationDecision = AnnotationAllowance | AnnotationDenial\n\nconst ALLOW: AnnotationAllowance = { ok: true }\n\nfunction deny(code: AnnotationDenialCode): AnnotationDenial {\n  return { ok: false, code, message: ANNOTATION_DENIAL_MESSAGES[code] }\n}\n\n/**\n * Reports whether the actor wrote this annotation.\n *\n * The id is read first, and the address second. See `AnnotationActorView.email`\n * for why one identity is not enough.\n */\nexport function isAuthor(\n  annotation: AnnotationDto,\n  actor: AnnotationActorView,\n): boolean {\n  if (annotation.createdBy.userId === actor.userId) {\n    return true\n  }\n  return isSameActorEmail(annotation.createdBy.email, actor.email)\n}\n\n/**\n * Whether the actor can change the text of a note.\n *\n * Only the author. A note carries an opinion with a name on it, so a second\n * person who edits it would put words in that person's mouth. Somebody who\n * disagrees writes a note of their own, and both stay visible.\n */\nexport function canEditNote(\n  annotation: AnnotationDto,\n  actor: AnnotationActorView,\n): AnnotationDecision {\n  return isAuthor(annotation, actor) ? ALLOW : deny('not-author')\n}\n\n/**\n * Whether the actor can remove an annotation.\n *\n * A NOTE follows `canEditNote`: the author, and nobody else.\n *\n * A TAG is different, and anybody can remove one. A tag is a grouping and not\n * a statement, a wrong tag makes a search answer wrongly for everybody, and\n * the person who can see the mistake is rarely the person who made it. The\n * removal keeps the row, so who added it and who took it off both stay\n * readable.\n */\nexport function canRemove(\n  annotation: AnnotationDto,\n  actor: AnnotationActorView,\n): AnnotationDecision {\n  if (annotation.kind === 'tag') {\n    return ALLOW\n  }\n  return canEditNote(annotation, actor)\n}\n\n/**\n * Whether this text can be a note.\n *\n * The frontend runs it on every keystroke to hold the button, and the route\n * runs it on the body that arrives. The Zod schema of the route holds the same\n * two numbers, so a caller that skips the frontend still meets them.\n */\nexport function checkNoteBody(body: string): AnnotationDecision {\n  const trimmed = body.trim()\n  if (trimmed.length === 0) {\n    return deny('empty-body')\n  }\n  if (trimmed.length > ANNOTATION_BODY_MAX) {\n    return deny('body-too-long')\n  }\n  return ALLOW\n}\n\n/**\n * Whether this text can be a tag name.\n *\n * The dictionary stores TWO values for one tag, so both are measured. The\n * identity is `normalizeTagName(name)`, which the unique index holds, and the\n * displayed name is `name.trim()`, which is what a reader sees on every badge.\n * They are not the same length: normalizing turns a run of inner spaces into\n * one hyphen, so `a<many spaces>b` is shorter after it than before. Measuring\n * only the normalized value therefore let a display name through that is\n * longer than the ceiling this function exists to hold.\n *\n * Emptiness is asked of the normalized value alone: a name of nothing but\n * whitespace has no identity, whatever it looks like.\n */\nexport function checkTagName(name: string): AnnotationDecision {\n  const normalized = normalizeTagName(name)\n  if (normalized.length === 0) {\n    return deny('empty-tag')\n  }\n  if (\n    normalized.length > ANNOTATION_TAG_NAME_MAX ||\n    name.trim().length > ANNOTATION_TAG_NAME_MAX\n  ) {\n    return deny('tag-too-long')\n  }\n  return ALLOW\n}\n"],
+  "mappings": "AAMA,SAAS,wBAAwB;AAEjC;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AA6CA,MAAM,6BACX;AAAA,EACE,cAAc;AAAA,EACd,cAAc;AAAA,EACd,iBAAiB,wBAAwB,mBAAmB;AAAA,EAC5D,aAAa;AAAA,EACb,gBAAgB,4BAA4B,uBAAuB;AACrE;AAgBF,MAAM,QAA6B,EAAE,IAAI,KAAK;AAE9C,SAAS,KAAK,MAA8C;AAC1D,SAAO,EAAE,IAAI,OAAO,MAAM,SAAS,2BAA2B,IAAI,EAAE;AACtE;AAQO,SAAS,SACd,YACA,OACS;AACT,MAAI,WAAW,UAAU,WAAW,MAAM,QAAQ;AAChD,WAAO;AAAA,EACT;AACA,SAAO,iBAAiB,WAAW,UAAU,OAAO,MAAM,KAAK;AACjE;AASO,SAAS,YACd,YACA,OACoB;AACpB,SAAO,SAAS,YAAY,KAAK,IAAI,QAAQ,KAAK,YAAY;AAChE;AAaO,SAAS,UACd,YACA,OACoB;AACpB,MAAI,WAAW,SAAS,OAAO;AAC7B,WAAO;AAAA,EACT;AACA,SAAO,YAAY,YAAY,KAAK;AACtC;AASO,SAAS,cAAc,MAAkC;AAC9D,QAAM,UAAU,KAAK,KAAK;AAC1B,MAAI,QAAQ,WAAW,GAAG;AACxB,WAAO,KAAK,YAAY;AAAA,EAC1B;AACA,MAAI,QAAQ,SAAS,qBAAqB;AACxC,WAAO,KAAK,eAAe;AAAA,EAC7B;AACA,SAAO;AACT;AAgBO,SAAS,aAAa,MAAkC;AAC7D,QAAM,aAAa,iBAAiB,IAAI;AACxC,MAAI,WAAW,WAAW,GAAG;AAC3B,WAAO,KAAK,WAAW;AAAA,EACzB;AACA,MACE,WAAW,SAAS,2BACpB,KAAK,KAAK,EAAE,SAAS,yBACrB;AACA,WAAO,KAAK,cAAc;AAAA,EAC5B;AACA,SAAO;AACT;",
+  "names": []
+}

package/dist/approvals/cluster-bulk-operation.d.ts

@@ -0,0 +1,196 @@
+/**
+ * The cluster bulk operation on the approval mechanism of control-backend.
+ *
+ * control-backend and control-frontend both read this file. The backend
+ * builds its six use cases from `CLUSTER_BULK_OPERATION_RULES`, and the form
+ * of the frontend reads the same table to run `canCreate` before the request
+ * goes out. A permission that only one side knew would be a button that the
+ * server then refuses.
+ *
+ * console-backend reads the step types at the end. control-backend calls one
+ * step for each cluster, and console-backend does the work of that step with
+ * the same code that its own bulk operation runs.
+ */
+import { ClusterBulkOperationStatus, ClusterBulkOperationType } from '../enums/ClusterBulkOperation.enum.js';
+import type { ClusterBulkOperationParameter } from '../types/ClusterBulkOperation.type.js';
+/**
+ * The most clusters that one request holds.
+ *
+ * The payload is a json column, and the create route reads it in one body of
+ * at most 1 MiB. 3000 clusters with the longest names stay far below that.
+ * A larger set is two requests, which is also two decisions for the people
+ * who approve.
+ */
+export declare const CLUSTER_BULK_OPERATION_MAX_CLUSTERS = 3000;
+/** The longest name of an operation. The name is what the queue shows. */
+export declare const CLUSTER_BULK_OPERATION_NAME_MAX_LENGTH = 200;
+/**
+ * The longest cluster name that the payload keeps.
+ *
+ * The name is a copy for a reader. The id alone decides what the step
+ * changes.
+ */
+export declare const CLUSTER_BULK_OPERATION_CLUSTER_NAME_MAX_LENGTH = 100;
+/**
+ * The wait between two sleeping clusters of one datacenter.
+ *
+ * The same number as the bulk operation of console-backend. A wake-up loads
+ * the datacenter, and many wake-ups together overload it. Datacenters do not
+ * wait for each other.
+ */
+export declare const CLUSTER_BULK_SLEEPING_CLUSTER_DELAY_MS = 60000;
+/** What one operation type needs, and which use case carries it. */
+export interface ClusterBulkOperationRule {
+    useCase: string;
+    label: string;
+    /** The permission that opens, approves and runs a request of this type. */
+    permission: string;
+}
+/**
+ * The floor of approvals of a cluster bulk operation on prod, for every type.
+ * Dev, int and local use `CLUSTER_BULK_OPERATION_TEST_STAGE_MIN_ACKS`.
+ *
+ * A bulk operation changes many clusters with one decision, so it needs two
+ * people other than the requester. Every other use case needs one. This
+ * floor replaces `MINIMUM_EYEPAIRS` for the approval flow only. The old flow
+ * of console-backend still reads `MINIMUM_EYEPAIRS`.
+ */
+export declare const CLUSTER_BULK_OPERATION_MIN_ACKS = 2;
+/**
+ * The floor of approvals of a cluster bulk operation on dev, int and local.
+ *
+ * A test stage often has one other Camundi who can approve. One approval
+ * there still tests the whole flow.
+ */
+export declare const CLUSTER_BULK_OPERATION_TEST_STAGE_MIN_ACKS = 1;
+/**
+ * The rules of each operation type.
+ *
+ * The permissions are the ones that the bulk operation of console-backend
+ * checks today (`getBulkOpRequiredPermission`), so a Camundi who can run one
+ * flow can run the other. `CLUSTERS_READALLCLUSTERINFO` is part of every
+ * type there, and `clusterBulkRequiredPermissions` adds it here.
+ */
+export declare const CLUSTER_BULK_OPERATION_RULES: Record<ClusterBulkOperationType, ClusterBulkOperationRule>;
+/** The operation types in the order that a form offers them. */
+export declare const CLUSTER_BULK_OPERATION_TYPES: ClusterBulkOperationType[];
+/** The operation type of a use case, or `undefined` for any other use case. */
+export declare function clusterBulkOperationTypeOf(useCase: string): ClusterBulkOperationType | undefined;
+/** One cluster of a request. */
+export interface ClusterBulkTargetDto {
+    id: string;
+    /** A copy for a reader. The step reads the id alone. */
+    name?: string;
+    orgId?: string;
+}
+export interface ClusterBulkGenerationUpdateSettings {
+    targetGenerationId: string;
+    /** A copy for a reader. */
+    targetGenerationName?: string;
+    /** See `ClusterBulkOperationGenerationUpdateParameter.yoloAllClusters`. */
+    yoloAllClusters?: boolean;
+    /** See `ClusterBulkOperationGenerationUpdateParameter.yoloForceUpdate`. */
+    yoloForceUpdate?: boolean;
+}
+export interface ClusterBulkPlanUpdateSettings {
+    targetPlanId: string;
+    targetPlanName?: string;
+    /** Keeps the active modification of a cluster through the change. */
+    keepModification?: boolean;
+}
+/**
+ * No `keepModification`: the parameter of a plan type update in the old flow
+ * has none, and its dialog never sends it.
+ */
+export interface ClusterBulkPlanTypeUpdateSettings {
+    targetPlanTypeId: string;
+    targetPlanTypeName?: string;
+}
+export interface ClusterBulkSleepWakeupSettings {
+    action: 'sleep' | 'wakeup';
+}
+/** The settings of each type. Deletion and spec update have none. */
+export interface ClusterBulkSettingsByType {
+    [ClusterBulkOperationType.GENERATION_UPDATE]: ClusterBulkGenerationUpdateSettings;
+    [ClusterBulkOperationType.PLAN_UPDATE]: ClusterBulkPlanUpdateSettings;
+    [ClusterBulkOperationType.PLAN_TYPE_UPDATE]: ClusterBulkPlanTypeUpdateSettings;
+    [ClusterBulkOperationType.SLEEP_WAKEUP]: ClusterBulkSleepWakeupSettings;
+    [ClusterBulkOperationType.DELETION]: Record<string, never>;
+    [ClusterBulkOperationType.SPEC_UPDATE]: Record<string, never>;
+}
+/** The payload of a request, for one operation type. */
+export interface ClusterBulkOperationPayloadDto<T extends ClusterBulkOperationType = ClusterBulkOperationType> {
+    name: string;
+    clusters: ClusterBulkTargetDto[];
+    settings: ClusterBulkSettingsByType[T];
+}
+/** True when the settings of a generation update go past a safety check. */
+export declare function isClusterBulkYolo(type: ClusterBulkOperationType, settings: unknown): boolean;
+/**
+ * Every permission that a request of this type and these settings needs.
+ *
+ * control-backend stores the answer on the request as
+ * `requiredPermissions`, and the form passes the same answer to `canCreate`.
+ * A yolo flag adds `CLUSTERS_CAN_UPDATE_GENERATION_YOLO`, which is the rule
+ * of `needsGenerationYolo` in console-backend.
+ */
+export declare function clusterBulkRequiredPermissions(type: ClusterBulkOperationType, settings: unknown): string[];
+/**
+ * Turns the settings of a request into the parameter of console-backend.
+ *
+ * The step route of console-backend reads the parameter shape of its own
+ * bulk operation, so one function in console-backend serves both flows.
+ * `nop` of the sleep action is not reachable from here on purpose: a request
+ * that changes nothing is not a request that people approve.
+ */
+export declare function clusterBulkParameterOf(type: ClusterBulkOperationType, settings: unknown): ClusterBulkOperationParameter;
+/** The outcome of one cluster, once its step finished. */
+export type ClusterBulkFinalStatus = ClusterBulkOperationStatus.DONE | ClusterBulkOperationStatus.ERRORED | ClusterBulkOperationStatus.SKIPPED;
+/**
+ * What a request records for one cluster, in `executionResult`.
+ *
+ * `executionResult` of a bulk request is an object with ONE key for each
+ * cluster that finished, keyed by the id of the cluster. A cluster with no
+ * key has not run yet. That is what lets an interrupted run skip the
+ * clusters that are finished, and what a reader shows as "not reached".
+ */
+export interface ClusterBulkClusterResultDto {
+    result: ClusterBulkFinalStatus;
+    /** Why a cluster errored or was skipped, or a note on a done cluster. */
+    error?: string;
+    /** An ISO timestamp: when the step answered. */
+    at: string;
+}
+/** Reads the result of one cluster out of `executionResult`. */
+export declare function clusterBulkResultOf(executionResult: Record<string, unknown> | undefined, clusterId: string): ClusterBulkClusterResultDto | undefined;
+/**
+ * The body of the step route of console-backend.
+ *
+ * `api/admin/approvals/clusters/:clusterId/bulk-step`. One call does the work
+ * of one operation type on one cluster.
+ */
+export interface ClusterBulkStepRequestDto {
+    type: ClusterBulkOperationType;
+    parameter: ClusterBulkOperationParameter;
+    /**
+     * When true, a sleeping cluster is NOT changed. The answer is `deferred`,
+     * with the datacenter of the cluster.
+     *
+     * This is how control-backend keeps the stagger of the old run: the first
+     * pass changes the awake clusters and learns which ones sleep, and a second
+     * pass changes the sleeping ones: one lane for each datacenter, the lanes
+     * side by side, and the clusters of one lane
+     * `CLUSTER_BULK_SLEEPING_CLUSTER_DELAY_MS` apart.
+     */
+    deferIfSleeping: boolean;
+}
+/** The answer of the step route. */
+export type ClusterBulkStepResultDto = {
+    outcome: 'finished';
+    result: ClusterBulkFinalStatus;
+    error?: string;
+} | {
+    outcome: 'deferred';
+    /** The k8s context of the cluster, or `unknown`. */
+    datacenter: string;
+};

package/dist/approvals/cluster-bulk-operation.js

@@ -0,0 +1,127 @@
+import {
+  ClusterBulkOperationStatus,
+  ClusterBulkOperationType
+} from "../enums/ClusterBulkOperation.enum.js";
+import { ConsolePermissions } from "../permissions/console.permissions.js";
+import { APPROVAL_USE_CASE_TYPES } from "./use-cases.const.js";
+const CLUSTER_BULK_OPERATION_MAX_CLUSTERS = 3e3;
+const CLUSTER_BULK_OPERATION_NAME_MAX_LENGTH = 200;
+const CLUSTER_BULK_OPERATION_CLUSTER_NAME_MAX_LENGTH = 100;
+const CLUSTER_BULK_SLEEPING_CLUSTER_DELAY_MS = 6e4;
+const CLUSTER_BULK_OPERATION_MIN_ACKS = 2;
+const CLUSTER_BULK_OPERATION_TEST_STAGE_MIN_ACKS = 1;
+const CLUSTER_BULK_OPERATION_RULES = {
+  [ClusterBulkOperationType.GENERATION_UPDATE]: {
+    useCase: APPROVAL_USE_CASE_TYPES.clusterBulkGenerationUpdate,
+    label: "Generation update",
+    permission: ConsolePermissions.CLUSTERS_CAN_UPDATE_GENERATION
+  },
+  [ClusterBulkOperationType.PLAN_UPDATE]: {
+    useCase: APPROVAL_USE_CASE_TYPES.clusterBulkPlanUpdate,
+    label: "Plan update",
+    permission: ConsolePermissions.CLUSTERS_CAN_UPDATE_CLUSTERPLANTYPE
+  },
+  [ClusterBulkOperationType.PLAN_TYPE_UPDATE]: {
+    useCase: APPROVAL_USE_CASE_TYPES.clusterBulkPlanTypeUpdate,
+    label: "Plan type update",
+    permission: ConsolePermissions.CLUSTERS_CAN_UPDATE_CLUSTERPLANTYPE
+  },
+  [ClusterBulkOperationType.SLEEP_WAKEUP]: {
+    useCase: APPROVAL_USE_CASE_TYPES.clusterBulkSleepWakeup,
+    label: "Sleep / wake up",
+    permission: ConsolePermissions.CLUSTERS_CAN_SEND_TO_SLEEP
+  },
+  [ClusterBulkOperationType.DELETION]: {
+    useCase: APPROVAL_USE_CASE_TYPES.clusterBulkDeletion,
+    label: "Deletion",
+    permission: ConsolePermissions.CLUSTERS_DELETE_CLUSTER
+  },
+  [ClusterBulkOperationType.SPEC_UPDATE]: {
+    useCase: APPROVAL_USE_CASE_TYPES.clusterBulkSpecUpdate,
+    label: "Spec update",
+    permission: ConsolePermissions.CLUSTERS_CAN_UPDATE_CLUSTERPLANTYPE
+  }
+};
+const CLUSTER_BULK_OPERATION_TYPES = [
+  ClusterBulkOperationType.GENERATION_UPDATE,
+  ClusterBulkOperationType.PLAN_UPDATE,
+  ClusterBulkOperationType.PLAN_TYPE_UPDATE,
+  ClusterBulkOperationType.SLEEP_WAKEUP,
+  ClusterBulkOperationType.SPEC_UPDATE,
+  ClusterBulkOperationType.DELETION
+];
+function clusterBulkOperationTypeOf(useCase) {
+  return CLUSTER_BULK_OPERATION_TYPES.find(
+    (type) => CLUSTER_BULK_OPERATION_RULES[type].useCase === useCase
+  );
+}
+function isClusterBulkYolo(type, settings) {
+  if (type !== ClusterBulkOperationType.GENERATION_UPDATE || typeof settings !== "object" || settings === null) {
+    return false;
+  }
+  const typed = settings;
+  return typed.yoloAllClusters === true || typed.yoloForceUpdate === true;
+}
+function clusterBulkRequiredPermissions(type, settings) {
+  const permissions = [
+    CLUSTER_BULK_OPERATION_RULES[type].permission,
+    ConsolePermissions.CLUSTERS_READALLCLUSTERINFO
+  ];
+  if (isClusterBulkYolo(type, settings)) {
+    permissions.push(ConsolePermissions.CLUSTERS_CAN_UPDATE_GENERATION_YOLO);
+  }
+  return permissions;
+}
+function clusterBulkParameterOf(type, settings) {
+  const values = settings ?? {};
+  switch (type) {
+    case ClusterBulkOperationType.GENERATION_UPDATE:
+      return {
+        toGenerationUuid: String(values.targetGenerationId),
+        yoloAllClusters: values.yoloAllClusters === true,
+        yoloForceUpdate: values.yoloForceUpdate === true
+      };
+    case ClusterBulkOperationType.PLAN_UPDATE:
+      return {
+        toPlanUuid: String(values.targetPlanId),
+        yolo: false,
+        keepModification: values.keepModification === true
+      };
+    case ClusterBulkOperationType.PLAN_TYPE_UPDATE:
+      return {
+        toPlanTypeUuid: String(values.targetPlanTypeId),
+        yolo: false
+      };
+    case ClusterBulkOperationType.SLEEP_WAKEUP:
+      return { toSleep: values.action === "wakeup" ? "wakeup" : "sleep" };
+    default:
+      return void 0;
+  }
+}
+function clusterBulkResultOf(executionResult, clusterId) {
+  const entry = executionResult?.[clusterId];
+  if (typeof entry !== "object" || entry === null) {
+    return void 0;
+  }
+  const result = entry.result;
+  if (result !== ClusterBulkOperationStatus.DONE && result !== ClusterBulkOperationStatus.ERRORED && result !== ClusterBulkOperationStatus.SKIPPED) {
+    return void 0;
+  }
+  return entry;
+}
+export {
+  CLUSTER_BULK_OPERATION_CLUSTER_NAME_MAX_LENGTH,
+  CLUSTER_BULK_OPERATION_MAX_CLUSTERS,
+  CLUSTER_BULK_OPERATION_MIN_ACKS,
+  CLUSTER_BULK_OPERATION_NAME_MAX_LENGTH,
+  CLUSTER_BULK_OPERATION_RULES,
+  CLUSTER_BULK_OPERATION_TEST_STAGE_MIN_ACKS,
+  CLUSTER_BULK_OPERATION_TYPES,
+  CLUSTER_BULK_SLEEPING_CLUSTER_DELAY_MS,
+  clusterBulkOperationTypeOf,
+  clusterBulkParameterOf,
+  clusterBulkRequiredPermissions,
+  clusterBulkResultOf,
+  isClusterBulkYolo
+};
+//# sourceMappingURL=cluster-bulk-operation.js.map

package/dist/approvals/cluster-bulk-operation.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/approvals/cluster-bulk-operation.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 cluster bulk operation on the approval mechanism of control-backend.\n *\n * control-backend and control-frontend both read this file. The backend\n * builds its six use cases from `CLUSTER_BULK_OPERATION_RULES`, and the form\n * of the frontend reads the same table to run `canCreate` before the request\n * goes out. A permission that only one side knew would be a button that the\n * server then refuses.\n *\n * console-backend reads the step types at the end. control-backend calls one\n * step for each cluster, and console-backend does the work of that step with\n * the same code that its own bulk operation runs.\n */\n\nimport {\n  ClusterBulkOperationStatus,\n  ClusterBulkOperationType,\n} from '../enums/ClusterBulkOperation.enum.js'\nimport { ConsolePermissions } from '../permissions/console.permissions.js'\nimport type { ClusterBulkOperationParameter } from '../types/ClusterBulkOperation.type.js'\nimport { APPROVAL_USE_CASE_TYPES } from './use-cases.const.js'\n\n/**\n * The most clusters that one request holds.\n *\n * The payload is a json column, and the create route reads it in one body of\n * at most 1 MiB. 3000 clusters with the longest names stay far below that.\n * A larger set is two requests, which is also two decisions for the people\n * who approve.\n */\nexport const CLUSTER_BULK_OPERATION_MAX_CLUSTERS = 3000\n\n/** The longest name of an operation. The name is what the queue shows. */\nexport const CLUSTER_BULK_OPERATION_NAME_MAX_LENGTH = 200\n\n/**\n * The longest cluster name that the payload keeps.\n *\n * The name is a copy for a reader. The id alone decides what the step\n * changes.\n */\nexport const CLUSTER_BULK_OPERATION_CLUSTER_NAME_MAX_LENGTH = 100\n\n/**\n * The wait between two sleeping clusters of one datacenter.\n *\n * The same number as the bulk operation of console-backend. A wake-up loads\n * the datacenter, and many wake-ups together overload it. Datacenters do not\n * wait for each other.\n */\nexport const CLUSTER_BULK_SLEEPING_CLUSTER_DELAY_MS = 60_000\n\n/** What one operation type needs, and which use case carries it. */\nexport interface ClusterBulkOperationRule {\n  useCase: string\n  label: string\n  /** The permission that opens, approves and runs a request of this type. */\n  permission: string\n}\n\n/**\n * The floor of approvals of a cluster bulk operation on prod, for every type.\n * Dev, int and local use `CLUSTER_BULK_OPERATION_TEST_STAGE_MIN_ACKS`.\n *\n * A bulk operation changes many clusters with one decision, so it needs two\n * people other than the requester. Every other use case needs one. This\n * floor replaces `MINIMUM_EYEPAIRS` for the approval flow only. The old flow\n * of console-backend still reads `MINIMUM_EYEPAIRS`.\n */\nexport const CLUSTER_BULK_OPERATION_MIN_ACKS = 2\n\n/**\n * The floor of approvals of a cluster bulk operation on dev, int and local.\n *\n * A test stage often has one other Camundi who can approve. One approval\n * there still tests the whole flow.\n */\nexport const CLUSTER_BULK_OPERATION_TEST_STAGE_MIN_ACKS = 1\n\n/**\n * The rules of each operation type.\n *\n * The permissions are the ones that the bulk operation of console-backend\n * checks today (`getBulkOpRequiredPermission`), so a Camundi who can run one\n * flow can run the other. `CLUSTERS_READALLCLUSTERINFO` is part of every\n * type there, and `clusterBulkRequiredPermissions` adds it here.\n */\nexport const CLUSTER_BULK_OPERATION_RULES: Record<\n  ClusterBulkOperationType,\n  ClusterBulkOperationRule\n> = {\n  [ClusterBulkOperationType.GENERATION_UPDATE]: {\n    useCase: APPROVAL_USE_CASE_TYPES.clusterBulkGenerationUpdate,\n    label: 'Generation update',\n    permission: ConsolePermissions.CLUSTERS_CAN_UPDATE_GENERATION,\n  },\n  [ClusterBulkOperationType.PLAN_UPDATE]: {\n    useCase: APPROVAL_USE_CASE_TYPES.clusterBulkPlanUpdate,\n    label: 'Plan update',\n    permission: ConsolePermissions.CLUSTERS_CAN_UPDATE_CLUSTERPLANTYPE,\n  },\n  [ClusterBulkOperationType.PLAN_TYPE_UPDATE]: {\n    useCase: APPROVAL_USE_CASE_TYPES.clusterBulkPlanTypeUpdate,\n    label: 'Plan type update',\n    permission: ConsolePermissions.CLUSTERS_CAN_UPDATE_CLUSTERPLANTYPE,\n  },\n  [ClusterBulkOperationType.SLEEP_WAKEUP]: {\n    useCase: APPROVAL_USE_CASE_TYPES.clusterBulkSleepWakeup,\n    label: 'Sleep / wake up',\n    permission: ConsolePermissions.CLUSTERS_CAN_SEND_TO_SLEEP,\n  },\n  [ClusterBulkOperationType.DELETION]: {\n    useCase: APPROVAL_USE_CASE_TYPES.clusterBulkDeletion,\n    label: 'Deletion',\n    permission: ConsolePermissions.CLUSTERS_DELETE_CLUSTER,\n  },\n  [ClusterBulkOperationType.SPEC_UPDATE]: {\n    useCase: APPROVAL_USE_CASE_TYPES.clusterBulkSpecUpdate,\n    label: 'Spec update',\n    permission: ConsolePermissions.CLUSTERS_CAN_UPDATE_CLUSTERPLANTYPE,\n  },\n}\n\n/** The operation types in the order that a form offers them. */\nexport const CLUSTER_BULK_OPERATION_TYPES: ClusterBulkOperationType[] = [\n  ClusterBulkOperationType.GENERATION_UPDATE,\n  ClusterBulkOperationType.PLAN_UPDATE,\n  ClusterBulkOperationType.PLAN_TYPE_UPDATE,\n  ClusterBulkOperationType.SLEEP_WAKEUP,\n  ClusterBulkOperationType.SPEC_UPDATE,\n  ClusterBulkOperationType.DELETION,\n]\n\n/** The operation type of a use case, or `undefined` for any other use case. */\nexport function clusterBulkOperationTypeOf(\n  useCase: string,\n): ClusterBulkOperationType | undefined {\n  return CLUSTER_BULK_OPERATION_TYPES.find(\n    (type) => CLUSTER_BULK_OPERATION_RULES[type].useCase === useCase,\n  )\n}\n\n/** One cluster of a request. */\nexport interface ClusterBulkTargetDto {\n  id: string\n  /** A copy for a reader. The step reads the id alone. */\n  name?: string\n  orgId?: string\n}\n\nexport interface ClusterBulkGenerationUpdateSettings {\n  targetGenerationId: string\n  /** A copy for a reader. */\n  targetGenerationName?: string\n  /** See `ClusterBulkOperationGenerationUpdateParameter.yoloAllClusters`. */\n  yoloAllClusters?: boolean\n  /** See `ClusterBulkOperationGenerationUpdateParameter.yoloForceUpdate`. */\n  yoloForceUpdate?: boolean\n}\n\nexport interface ClusterBulkPlanUpdateSettings {\n  targetPlanId: string\n  targetPlanName?: string\n  /** Keeps the active modification of a cluster through the change. */\n  keepModification?: boolean\n}\n\n/**\n * No `keepModification`: the parameter of a plan type update in the old flow\n * has none, and its dialog never sends it.\n */\nexport interface ClusterBulkPlanTypeUpdateSettings {\n  targetPlanTypeId: string\n  targetPlanTypeName?: string\n}\n\nexport interface ClusterBulkSleepWakeupSettings {\n  action: 'sleep' | 'wakeup'\n}\n\n/** The settings of each type. Deletion and spec update have none. */\nexport interface ClusterBulkSettingsByType {\n  [ClusterBulkOperationType.GENERATION_UPDATE]: ClusterBulkGenerationUpdateSettings\n  [ClusterBulkOperationType.PLAN_UPDATE]: ClusterBulkPlanUpdateSettings\n  [ClusterBulkOperationType.PLAN_TYPE_UPDATE]: ClusterBulkPlanTypeUpdateSettings\n  [ClusterBulkOperationType.SLEEP_WAKEUP]: ClusterBulkSleepWakeupSettings\n  [ClusterBulkOperationType.DELETION]: Record<string, never>\n  [ClusterBulkOperationType.SPEC_UPDATE]: Record<string, never>\n}\n\n/** The payload of a request, for one operation type. */\nexport interface ClusterBulkOperationPayloadDto<\n  T extends ClusterBulkOperationType = ClusterBulkOperationType,\n> {\n  name: string\n  clusters: ClusterBulkTargetDto[]\n  settings: ClusterBulkSettingsByType[T]\n}\n\n/** True when the settings of a generation update go past a safety check. */\nexport function isClusterBulkYolo(\n  type: ClusterBulkOperationType,\n  settings: unknown,\n): boolean {\n  if (\n    type !== ClusterBulkOperationType.GENERATION_UPDATE ||\n    typeof settings !== 'object' ||\n    settings === null\n  ) {\n    return false\n  }\n  const typed = settings as ClusterBulkGenerationUpdateSettings\n  return typed.yoloAllClusters === true || typed.yoloForceUpdate === true\n}\n\n/**\n * Every permission that a request of this type and these settings needs.\n *\n * control-backend stores the answer on the request as\n * `requiredPermissions`, and the form passes the same answer to `canCreate`.\n * A yolo flag adds `CLUSTERS_CAN_UPDATE_GENERATION_YOLO`, which is the rule\n * of `needsGenerationYolo` in console-backend.\n */\nexport function clusterBulkRequiredPermissions(\n  type: ClusterBulkOperationType,\n  settings: unknown,\n): string[] {\n  const permissions = [\n    CLUSTER_BULK_OPERATION_RULES[type].permission,\n    ConsolePermissions.CLUSTERS_READALLCLUSTERINFO,\n  ]\n  if (isClusterBulkYolo(type, settings)) {\n    permissions.push(ConsolePermissions.CLUSTERS_CAN_UPDATE_GENERATION_YOLO)\n  }\n  return permissions\n}\n\n/**\n * Turns the settings of a request into the parameter of console-backend.\n *\n * The step route of console-backend reads the parameter shape of its own\n * bulk operation, so one function in console-backend serves both flows.\n * `nop` of the sleep action is not reachable from here on purpose: a request\n * that changes nothing is not a request that people approve.\n */\nexport function clusterBulkParameterOf(\n  type: ClusterBulkOperationType,\n  settings: unknown,\n): ClusterBulkOperationParameter {\n  const values = (settings ?? {}) as Record<string, unknown>\n  switch (type) {\n    case ClusterBulkOperationType.GENERATION_UPDATE:\n      return {\n        toGenerationUuid: String(values.targetGenerationId),\n        yoloAllClusters: values.yoloAllClusters === true,\n        yoloForceUpdate: values.yoloForceUpdate === true,\n      }\n    case ClusterBulkOperationType.PLAN_UPDATE:\n      return {\n        toPlanUuid: String(values.targetPlanId),\n        yolo: false,\n        keepModification: values.keepModification === true,\n      }\n    case ClusterBulkOperationType.PLAN_TYPE_UPDATE:\n      return {\n        toPlanTypeUuid: String(values.targetPlanTypeId),\n        yolo: false,\n      }\n    case ClusterBulkOperationType.SLEEP_WAKEUP:\n      return { toSleep: values.action === 'wakeup' ? 'wakeup' : 'sleep' }\n    default:\n      return undefined\n  }\n}\n\n/** The outcome of one cluster, once its step finished. */\nexport type ClusterBulkFinalStatus =\n  | ClusterBulkOperationStatus.DONE\n  | ClusterBulkOperationStatus.ERRORED\n  | ClusterBulkOperationStatus.SKIPPED\n\n/**\n * What a request records for one cluster, in `executionResult`.\n *\n * `executionResult` of a bulk request is an object with ONE key for each\n * cluster that finished, keyed by the id of the cluster. A cluster with no\n * key has not run yet. That is what lets an interrupted run skip the\n * clusters that are finished, and what a reader shows as \"not reached\".\n */\nexport interface ClusterBulkClusterResultDto {\n  result: ClusterBulkFinalStatus\n  /** Why a cluster errored or was skipped, or a note on a done cluster. */\n  error?: string\n  /** An ISO timestamp: when the step answered. */\n  at: string\n}\n\n/** Reads the result of one cluster out of `executionResult`. */\nexport function clusterBulkResultOf(\n  executionResult: Record<string, unknown> | undefined,\n  clusterId: string,\n): ClusterBulkClusterResultDto | undefined {\n  const entry = executionResult?.[clusterId]\n  if (typeof entry !== 'object' || entry === null) {\n    return undefined\n  }\n  const result = (entry as { result?: unknown }).result\n  if (\n    result !== ClusterBulkOperationStatus.DONE &&\n    result !== ClusterBulkOperationStatus.ERRORED &&\n    result !== ClusterBulkOperationStatus.SKIPPED\n  ) {\n    return undefined\n  }\n  return entry as ClusterBulkClusterResultDto\n}\n\n/**\n * The body of the step route of console-backend.\n *\n * `api/admin/approvals/clusters/:clusterId/bulk-step`. One call does the work\n * of one operation type on one cluster.\n */\nexport interface ClusterBulkStepRequestDto {\n  type: ClusterBulkOperationType\n  parameter: ClusterBulkOperationParameter\n  /**\n   * When true, a sleeping cluster is NOT changed. The answer is `deferred`,\n   * with the datacenter of the cluster.\n   *\n   * This is how control-backend keeps the stagger of the old run: the first\n   * pass changes the awake clusters and learns which ones sleep, and a second\n   * pass changes the sleeping ones: one lane for each datacenter, the lanes\n   * side by side, and the clusters of one lane\n   * `CLUSTER_BULK_SLEEPING_CLUSTER_DELAY_MS` apart.\n   */\n  deferIfSleeping: boolean\n}\n\n/** The answer of the step route. */\nexport type ClusterBulkStepResultDto =\n  | {\n      outcome: 'finished'\n      result: ClusterBulkFinalStatus\n      error?: string\n    }\n  | {\n      outcome: 'deferred'\n      /** The k8s context of the cluster, or `unknown`. */\n      datacenter: string\n    }\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/approvals/policy.d.ts

@@ -38,6 +38,16 @@ export interface ApprovalActorView {
     email?: string;
     has(permission: string): boolean;
 }
+/**
+ * Builds the `has` of an actor from the permissions that the actor holds.
+ *
+ * `ConsolePermissions.APPROVALS_ALL_USE_CASES` stands in for every permission
+ * that a use case asks for. Both actor builders call this function, the one of
+ * control-backend and the one of the browser, so the button and the route
+ * agree on it. A rule that reads `actor.has` needs no change for it, and nor
+ * does a use case that a later change adds.
+ */
+export declare function approvalPermissionCheck(held: ReadonlySet<string>): (permission: string) => boolean;
 /**
  * Reports whether two email addresses name one person.
  *
@@ -50,6 +60,19 @@ export interface ApprovalActorView {
  * are one mailbox and must not pass as two people.
  */
 export declare function isSameActorEmail(one?: string, other?: string): boolean;
+/**
+ * Reports whether one identity of a request names the actor.
+ *
+ * The `sub` of the token OR the email, because one person can hold more than
+ * one Auth0 identity. Every rule that asks "is this the same human?" reads both
+ * through this function, so a rule cannot forget the second half: `canWithdraw`
+ * did, and it refused a creator whose browser and whose service resolved the
+ * id from two different tokens.
+ */
+export declare function isSameActor(identity: {
+    userId: string;
+    email?: string;
+}, actor: ApprovalActorView): boolean;
 /**
  * Reports whether this actor carries an address that names a person.
  *
@@ -65,7 +88,7 @@ export declare function hasActorEmail(actor: ApprovalActorView): 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' | 'too-few-acks' | 'no-creator-email';
+export type ApprovalDenialCode = 'forbidden' | 'not-pending' | 'self-approval' | 'self-rejection' | 'already-acknowledged' | 'expired' | 'not-creator' | 'not-executable' | 'no-reason' | 'too-few-acks' | 'no-creator-email';
 export type ApprovalDecision = {
     allowed: true;
 } | {
@@ -168,12 +191,29 @@ export declare function canAcknowledge(job: ApprovalJobDto, actor: ApprovalActor
 /**
  * A rejection needs the same permission as an acknowledgement, and a reason.
  *
- * The creator MAY reject their own request. That is a withdrawal with a reason,
- * and stopping it would only push the person to the withdraw button, where the
- * reason is lost.
+ * Two people answer a request, and each one has ONE verb. Somebody else
+ * approves or rejects it; the person who opened it withdraws it. The creator is
+ * refused here for the same reason `canAcknowledge` refuses them: one person
+ * must not be both sides of a four-eyes decision. The message names the button
+ * that they do have, and the trail loses nothing, because a withdrawal writes
+ * its reason into the same field.
+ *
+ * The ORDER of the checks is the order that a person meets them, and the state
+ * of the request comes before the reason. A closed request must answer
+ * "already closed" whatever the caller typed: with the reason first, a page
+ * that had no reason yet read `no-reason` from a rejected request, and the
+ * Reject button of control-frontend stayed enabled on a request that nothing
+ * could reject any more.
  */
 export declare function canReject(job: ApprovalJobDto, actor: ApprovalActorView, now: Date, reason: string): ApprovalDecision;
-/** Only the person who opened a request can take it back. */
+/**
+ * Only the person who opened a request can take it back.
+ *
+ * BOTH identities, as every other rule of this file reads them. One person can
+ * hold two Auth0 identities with two different `sub` values, and a rule that
+ * read the id alone refused the creator their own withdrawal as soon as the
+ * browser and the service resolved that id from two different tokens.
+ */
 export declare function canWithdraw(job: ApprovalJobDto, actor: ApprovalActorView, now: Date): ApprovalDecision;
 /**
  * Runs a request that has its approvals.