@oneuptime/common 12.0.8 → 12.0.9

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

@@ -0,0 +1,599 @@
+import UserMiddleware from "../Middleware/UserAuthorization";
+import OnCallReadinessService from "../Services/OnCallReadinessService";
+import OnCallDutyPolicyService from "../Services/OnCallDutyPolicyService";
+import OnCallSetupReminderService from "../Services/OnCallSetupReminderService";
+import TeamMemberService from "../Services/TeamMemberService";
+import Express from "../Utils/Express";
+import Response from "../Utils/Response";
+import CommonAPI from "./CommonAPI";
+import DatabaseCommonInteractionPropsUtil, { PermissionType, } from "../../Types/BaseDatabase/DatabaseCommonInteractionPropsUtil";
+import BadDataException from "../../Types/Exception/BadDataException";
+import NotAuthorizedException from "../../Types/Exception/NotAuthorizedException";
+import ObjectID from "../../Types/ObjectID";
+import Permission from "../../Types/Permission";
+/*
+ * "Can this responder actually be paged?" answered over HTTP, for one policy,
+ * one project, or one user. Everything the routes below return is computed by
+ * OnCallReadinessService; this file is transport and authorisation only, and
+ * deliberately holds no readiness logic of its own so the API and any in-process
+ * caller (TeamComplianceService, the on-call banner) can never disagree.
+ *
+ * Why a plain ExpressRouter rather than `extends BaseAPI`:
+ *
+ * The obvious model for this file, TeamComplianceAPI, does
+ * `class TeamComplianceAPI extends BaseAPI<Team, TeamServiceType>` and calls
+ * `super(Team, TeamService)` purely to inherit `this.router`. That side effect
+ * is not free: the BaseAPI constructor registers the ENTIRE Team CRUD route set
+ * (list, get, count, create, update, delete) onto that router. Team is already
+ * registered independently at App/FeatureSet/BaseAPI/Index.ts:2884, and Express
+ * dispatches to whichever matching handler was `app.use`d first, so the second
+ * copy is dead code that exists only to be shadowed - and it would quietly stop
+ * being dead the day the mount order changed. Readiness is not a CRUD model at
+ * all, so there is nothing to inherit here even in principle. AIReadinessAPI
+ * (Common/Server/API/AIReadinessAPI.ts) is the pattern this follows instead: a
+ * bare router, exported as the router itself, mounted with
+ * `app.use(prefix, OnCallReadinessAPI)`.
+ *
+ * Authorisation, on every route:
+ *
+ * These endpoints deliberately disclose ONE USER'S CONFIGURATION TO ANOTHER -
+ * which channels they have, which severities they are covered for. That is the
+ * whole point (an owner has to be able to see who cannot be reached), but it
+ * means the usual "the model's TableAccessControl will catch it" reasoning does
+ * not apply: OnCallReadinessService reads with `isRoot: true`, so these handlers
+ * are the only gate underneath. UserMiddleware.getUserMiddleware is NOT that
+ * gate - it admits anonymous callers as UserType.Public and calls next(), and
+ * the tenant id it attaches comes straight off the caller-supplied `tenantid`
+ * header before any authorisation runs. So each route asserts, itself:
+ *
+ *   1. the caller is a logged-in member of the project it named
+ *      (CommonAPI.assertAuthenticatedProjectMember), and
+ *   2. the resource in the path - the policy, or the user - actually belongs to
+ *      that same project, because otherwise a member of project A reads project
+ *      B's data simply by sending their own `tenantid` header alongside a
+ *      borrowed id.
+ *
+ * OnCallReadinessService guards its own reads too - getReadinessForPolicy
+ * rejects a policy from another project, getReadinessForUser rejects a user who
+ * is not a member of one - and the checks here deliberately duplicate that.
+ * They are not redundant belt-and-braces for its own sake: the service's guards
+ * are data-scoping guards that answer with BadDataException (a 400), whereas a
+ * member of project A reaching for project B's policy id is an authorisation
+ * failure and should be answered as one. More to the point, an endpoint's
+ * authorisation should be legible in the endpoint. If the service later relaxes
+ * its guard for a legitimate internal caller - a preview for a user not yet
+ * added to the project, say - these routes must not quietly become a
+ * cross-project probe as a side effect. The cost is one primary-key lookup on a
+ * request that is about to do considerably more work than that.
+ *
+ * Identifiers are masked by the service, before they ever reach this file, and
+ * the serialisers below copy `maskedIdentifier` and nothing else. There is no
+ * "unmask for self" branch anywhere: the contract carries no raw field to
+ * populate, so a future change would have to widen the contract in the open
+ * rather than slip a raw phone number through a boolean flag.
+ *
+ * The two summary routes are PAGED - see READINESS_PAGE_SIZE_DEFAULT below for
+ * why, and for the rule that keeps a paged answer from lying about the whole.
+ *
+ * THE ONE ROUTE THAT IS NOT A READ:
+ *
+ * /on-call-readiness/send-setup-reminder is a POST that sends branded email to
+ * real people, and it therefore carries a HIGHER bar than its read siblings -
+ * see SETUP_REMINDER_PERMISSIONS below. Membership was the original bar and it
+ * was the wrong one: `assertAuthenticatedProjectMember` proves only that the
+ * caller has SOME access entry for the project, which every read-only Viewer
+ * has, so anyone who could look at the readiness table could also make the
+ * product mail their colleagues in the project's name. Disclosure and action are
+ * different questions, and this route is the only one here that answers the
+ * second.
+ */
+const router = Express.getRouter();
+/*
+ * Paging, and the one rule that makes it safe.
+ *
+ * A summary carries one UserReadiness per responder, and each of those carries a
+ * coverage cell per (rule type, severity) pair: four rule types against, say,
+ * eight incident and eight alert severities is 32 cells with a name and two ids
+ * apiece. That is a few kilobytes per responder, so a project with a few
+ * thousand responders serialises to tens of megabytes of JSON - built in memory,
+ * on every page load, by a service that also caches it. Nobody reads a table of
+ * five thousand rows in one screen, so the wire format should not pretend
+ * otherwise.
+ *
+ * THE RULE: the response is bounded, but the FACTS ARE NOT. readyCount,
+ * partiallyReadyCount and notReachableCount always describe the entire scope,
+ * never the page, and `totalCount` states how many responders the scope holds so
+ * a client can always see that it is holding part of a list. This is the
+ * difference between a paged answer and a truncated one, and it is the whole
+ * reason the counts are computed by the service rather than derived by the
+ * client from `users.length`: a UI that counted the rows it received would put a
+ * reassuring "3 not reachable" under a page that happened to contain three, in a
+ * project with forty.
+ *
+ * Ordering is what makes the FIRST page the useful one: the service sorts
+ * most-broken-first (NotReachable, then PartiallyReady, then Ready), so page one
+ * of a paged response holds the responders somebody needs to act on, and the
+ * rows that fall off the end are the healthy ones.
+ *
+ * A `limit` above the maximum is REFUSED rather than clamped. Silently returning
+ * 500 rows to a caller who asked for 5,000 is precisely the failure this feature
+ * exists to prevent - a client cannot tell a short page from a complete list -
+ * so the caller is told the ceiling and asked to page.
+ */
+const READINESS_PAGE_SIZE_DEFAULT = 100;
+const READINESS_PAGE_SIZE_MAX = 500;
+/*
+ * Digits and nothing else. No sign, no decimal point, no trailing units: a page
+ * parameter is a count of rows.
+ */
+const WHOLE_NUMBER = /^\d+$/;
+/*
+ * Query parameters are strings from an untrusted caller. parseInt("12abc") is
+ * 12 and parseInt("abc") is NaN, and both would otherwise become a page size, so
+ * the value is required to be nothing but digits before it is believed.
+ */
+function readPositiveIntegerParam(req, name, fallback) {
+    const raw = req.query[name];
+    if (raw === undefined || raw === null || raw === "") {
+        return fallback;
+    }
+    if (!WHOLE_NUMBER.test(raw)) {
+        throw new BadDataException(`${name} must be a whole number. Received: "${raw}".`);
+    }
+    return parseInt(raw, 10);
+}
+/*
+ * An explicit refresh must actually re-read.
+ *
+ * The service answers from a 60s in-process cache, which is right for the
+ * ordinary case - several surfaces ask the same question on one screen. It is
+ * wrong for the one interaction where the user has just CHANGED the answer: a
+ * responder verifies a device while an admin watches, the admin presses
+ * Recheck, and a cached summary redraws them as still unreachable. The admin
+ * concludes the fix did not work.
+ *
+ * `?refresh=true` drops this replica's cache before recomputing. It is a
+ * deliberate, user-initiated cost, and it is bounded by the same authorisation
+ * as the read itself, so it cannot be used to force recomputation on a project
+ * the caller cannot already read. Each replica clears only its own copy; the
+ * TTL remains the only cross-process guarantee.
+ */
+function isRefreshRequested(req) {
+    const raw = req.query["refresh"];
+    if (raw === undefined || raw === null) {
+        return false;
+    }
+    const normalized = String(raw).trim().toLowerCase();
+    return normalized === "true" || normalized === "1";
+}
+function readPageRequest(req) {
+    const limit = readPositiveIntegerParam(req, "limit", READINESS_PAGE_SIZE_DEFAULT);
+    const skip = readPositiveIntegerParam(req, "skip", 0);
+    if (limit < 1 || limit > READINESS_PAGE_SIZE_MAX) {
+        throw new BadDataException(`limit must be between 1 and ${READINESS_PAGE_SIZE_MAX}. Ask for the next page with skip instead.`);
+    }
+    return {
+        limit: limit,
+        skip: skip,
+    };
+}
+/*
+ * Project membership for the user NAMED IN THE PATH (not the caller). Without
+ * this, /on-call-readiness/user/:userId is a cross-project probe: the readiness
+ * queries are all projectId-scoped and would come back empty for a stranger,
+ * but the summary still carries that stranger's name and login email, read from
+ * the User table where no project scoping exists. TeamMember is the membership
+ * table for a project - even the creating owner gets a row
+ * (ProjectService.ts:1853) - so its absence is a definitive "not in this
+ * project".
+ *
+ * Invitation state is deliberately not part of the query, matching the check
+ * OnCallReadinessService.getReadinessForUser makes for the same reason. A user
+ * with a pending invitation can already be selected onto an escalation rule, and
+ * "is this person reachable?" is exactly the question worth asking about them;
+ * requiring hasAcceptedInvitation would refuse the readiness read for the
+ * responders most likely to be misconfigured.
+ *
+ * The rejection reuses assertResourceBelongsToProject's wording verbatim so a
+ * caller cannot tell "this user exists but is in another project" apart from
+ * "this user does not exist", and therefore cannot enumerate users through it.
+ */
+async function assertUserBelongsToProject(userId, projectId) {
+    const memberships = await TeamMemberService.findBy({
+        query: {
+            userId: userId,
+            projectId: projectId,
+        },
+        select: {
+            _id: true,
+        },
+        limit: 1,
+        skip: 0,
+        props: {
+            isRoot: true,
+        },
+    });
+    if (memberships.length === 0) {
+        throw new NotAuthorizedException("You are not authorized to access this project's data.");
+    }
+}
+/*
+ * Who may make the product send mail in this project's name.
+ *
+ * The action is "manage on-call", so the granular permission that means exactly
+ * that - EditProjectOnCallDutyPolicy, the one that lets somebody change who gets
+ * paged - is the permission this asks for. The two project roles and the on-call
+ * role are listed ALONGSIDE it rather than being expanded into it because
+ * OneUptime's teams hold ROLES, not granular permissions: a project created
+ * before this feature existed has an owner whose team carries ProjectOwner and
+ * nothing more granular, and a gate that named only the granular permission
+ * would lock every existing project's owner out of their own button.
+ *
+ * Deliberately NOT here:
+ *
+ *   - ProjectMember and Viewer, which is the whole point of the change. Both can
+ *     read the readiness table, and reading who is unreachable is a different
+ *     act from mailing them about it under the project's branding.
+ *   - OnCallMember and OnCallViewer. The on-call tiers below Admin are for
+ *     people who are ON call, not people who administer it.
+ *
+ * The read routes keep the membership bar: they disclose configuration to
+ * somebody who is already inside the project, which is what the feature is for.
+ */
+const SETUP_REMINDER_PERMISSIONS = [
+    Permission.ProjectOwner,
+    Permission.ProjectAdmin,
+    Permission.OnCallAdmin,
+    Permission.EditProjectOnCallDutyPolicy,
+];
+/*
+ * The permission check, read the way the rest of the API reads permissions.
+ *
+ * getUserPermissions(Allow) rather than `userTenantAccessPermission[...]`
+ * directly, and that is not a stylistic preference. That dictionary's entries
+ * hold GRANTS AND DENIALS in one array, discriminated only by
+ * `isBlockPermission`; mapping it raw would count a team's explicit BLOCK of
+ * ProjectAdmin as a grant of ProjectAdmin, so the admin action that restricts a
+ * team would be the thing that handed it this endpoint. The helper filters by
+ * type and scopes to props.tenantId, which is the same project
+ * assertAuthenticatedProjectMember just authorised the caller for.
+ *
+ * The refusal reuses the router's single refusal sentence verbatim, so an
+ * under-privileged member cannot tell "you may not do this" apart from "you are
+ * not in this project" and use the difference to probe.
+ */
+function assertCanSendSetupReminders(databaseProps) {
+    if (databaseProps.isMasterAdmin) {
+        return;
+    }
+    const permissions = DatabaseCommonInteractionPropsUtil.getUserPermissions(databaseProps, PermissionType.Allow).map((userPermission) => {
+        return userPermission.permission;
+    });
+    const isAllowed = permissions.some((permission) => {
+        return SETUP_REMINDER_PERMISSIONS.includes(permission);
+    });
+    if (!isAllowed) {
+        throw new NotAuthorizedException("You are not authorized to access this project's data.");
+    }
+}
+/*
+ * ObjectID's constructor accepts any string, so an unparseable path segment
+ * would otherwise travel all the way to a query that matches nothing and read
+ * as "this policy has no responders" rather than "you sent nonsense".
+ */
+function readObjectIdParam(req, name) {
+    const raw = req.params[name] || "";
+    ObjectID.validateUUID(raw);
+    return new ObjectID(raw);
+}
+/*
+ * The `userIds` array from a POST body, validated before it is believed.
+ *
+ * A request body is a bag of JSON from an untrusted caller, so every layer of
+ * this is checked rather than asserted: that the field is there, that it is an
+ * array, that each element is a string, and that each string is a UUID.
+ * ObjectID's constructor accepts ANY string, so skipping the last check would
+ * push arbitrary caller text into a database query - and, in this case, into the
+ * "not a member of this project" branch of a mail-sending service, where it
+ * would look exactly like an ordinary stale id rather than like nonsense.
+ *
+ * The ceiling is enforced in the service rather than here, because the service
+ * is what the ceiling protects and it must hold for every caller. This route
+ * only has to hand it a well-formed list.
+ */
+function readUserIdsFromBody(req) {
+    const body = (req.body || {});
+    const raw = body["userIds"];
+    if (!Array.isArray(raw)) {
+        throw new BadDataException("userIds is required and must be an array of user ids.");
+    }
+    return raw.map((value) => {
+        if (typeof value !== "string") {
+            throw new BadDataException("Every entry in userIds must be a user id string.");
+        }
+        ObjectID.validateUUID(value);
+        return new ObjectID(value);
+    });
+}
+/*
+ * ObjectID.toJSON() serialises to `{ _type: "ObjectID", value: "..." }`, which
+ * is right for model payloads the client parses back through JSONFunctions but
+ * wrong for a hand-rolled response body. These serialisers flatten every id to
+ * a plain string, the same way TeamComplianceAPI does, so the browser can read
+ * `userId` without knowing about ObjectID at all.
+ */
+function serializeMethod(method) {
+    return {
+        /*
+         * The id of the METHOD ROW, flattened like every other id here.
+         *
+         * It is not sensitive - it is already the foreign key stored on any rule its
+         * owner created - and it is the whole reason an administrator can POINT A
+         * RULE AT a method without READING that method's row. The seven method
+         * models stay scoped to their owner precisely so the raw phone number,
+         * webhook url, device token and chat id behind them never leave the server;
+         * the dropdown an admin uses is built from this id plus the mask below.
+         *
+         * Dropping it does not fail loudly. The payload still looks well-formed and
+         * the readiness page still renders - only the admin's rule form quietly has
+         * nothing to submit. A merge did exactly that, which is why the API test
+         * asserts this field's presence and that it is the METHOD row's id rather
+         * than the user's or the rule's.
+         */
+        methodId: method.methodId.toString(),
+        methodType: method.methodType,
+        // Masked upstream. Never widened here, for any caller, including self.
+        maskedIdentifier: method.maskedIdentifier,
+        isVerified: method.isVerified,
+    };
+}
+function serializeCoverageCell(cell) {
+    return {
+        ruleType: cell.ruleType,
+        /*
+         * Undefined rather than absent for the two go-on-call / go-off-call rule
+         * types, which are not per-severity at all. The client renders one row per
+         * cell and needs to be able to tell "this cell has no severity" from "the
+         * severity failed to load".
+         */
+        severityId: cell.severityId ? cell.severityId.toString() : undefined,
+        severityName: cell.severityName,
+        hasRule: cell.hasRule,
+        isOptOut: cell.isOptOut,
+    };
+}
+function serializeUserReadiness(readiness) {
+    return {
+        userId: readiness.userId.toString(),
+        userName: readiness.userName,
+        userEmail: readiness.userEmail,
+        userProfilePictureId: readiness.userProfilePictureId
+            ? readiness.userProfilePictureId.toString()
+            : undefined,
+        status: readiness.status,
+        methods: readiness.methods.map(serializeMethod),
+        coverage: readiness.coverage.map(serializeCoverageCell),
+        reasons: readiness.reasons,
+        reachedVia: readiness.reachedVia,
+        /*
+         * The teams that page this responder, ids flattened to strings like every other id
+         * here. A team name is already readable by any project member through the team list,
+         * so nothing is disclosed by naming it — and naming it is what lets the readiness
+         * table offer a team filter whose options a reader can actually recognise.
+         */
+        teams: readiness.teams.map((team) => {
+            return {
+                _id: team._id.toString(),
+                name: team.name,
+            };
+        }),
+    };
+}
+/*
+ * One page of a summary. `users` is sliced; nothing else is. See
+ * READINESS_PAGE_SIZE_DEFAULT for why the counts stay whole-scope.
+ */
+function serializeSummaryPage(summary, page) {
+    const totalCount = summary.users.length;
+    const pagedUsers = summary.users.slice(page.skip, page.skip + page.limit);
+    const wire = {
+        projectId: summary.projectId.toString(),
+        onCallDutyPolicyId: summary.onCallDutyPolicyId
+            ? summary.onCallDutyPolicyId.toString()
+            : undefined,
+        readyCount: summary.readyCount,
+        partiallyReadyCount: summary.partiallyReadyCount,
+        notReachableCount: summary.notReachableCount,
+        /*
+         * Both of these are facts about the SCOPE, so they are copied onto every
+         * page of it rather than onto the first. A client that fetched page two
+         * would otherwise be told the answer is complete and the fallback is on.
+         */
+        isFallbackEnabled: summary.isFallbackEnabled,
+        isTruncated: summary.isTruncated,
+        totalCount: totalCount,
+        limit: page.limit,
+        skip: page.skip,
+        /*
+         * Stated rather than left to be derived. `skip + users.length < totalCount`
+         * is the same arithmetic, but a client that gets it slightly wrong stops
+         * paging one page early and silently drops responders - which is the exact
+         * failure mode paging was introduced to avoid.
+         */
+        hasMore: page.skip + pagedUsers.length < totalCount,
+        users: pagedUsers.map(serializeUserReadiness),
+    };
+    return wire;
+}
+/*
+ * Per user, always - even when everything worked.
+ *
+ * The counts alone would be enough to render "5 sent, 2 skipped, 1 failed", and
+ * that sentence is already far better than a tick. The array is here for the
+ * next question the reader has, which is "which one failed?" - and answering
+ * that from the client requires the outcome to be attached to an id it can match
+ * against the row the admin ticked.
+ *
+ * `outcome` is the enum's own string, not a boolean or a status code, because
+ * the four ways of not being sent are four different things to do next and a UI
+ * that cannot tell them apart ends up saying "3 skipped" with no explanation of
+ * why - which reads as a malfunction rather than as a throttle working.
+ *
+ * No user name or address is echoed back. The client already holds both from the
+ * readiness payload it was rendering when the admin made the selection, so
+ * repeating them here would widen what this endpoint discloses in exchange for
+ * nothing.
+ */
+function serializeSetupReminderUserResult(result) {
+    return {
+        userId: result.userId.toString(),
+        outcome: result.outcome,
+        message: result.message,
+    };
+}
+function serializeSetupReminderResult(result) {
+    const wire = {
+        projectId: result.projectId.toString(),
+        requestedCount: result.requestedCount,
+        sentCount: result.sentCount,
+        skippedCount: result.skippedCount,
+        failedCount: result.failedCount,
+        results: result.results.map(serializeSetupReminderUserResult),
+    };
+    return wire;
+}
+/*
+ * Readiness for one policy's effective responder set - direct users, team
+ * members, schedule-layer users and overrides alike. This is what the policy
+ * overview card and the coloured dots on the escalation-rule responder chips
+ * read.
+ *
+ * Paged: `?limit=&skip=`. The chips surface asks about specific responders, so a
+ * policy with more responders than one page holds must be paged through before
+ * every chip can be dotted - a chip whose user is not in the page it has must
+ * render as unknown rather than as ready.
+ */
+router.get("/on-call-readiness/policy/:policyId", UserMiddleware.getUserMiddleware, async (req, res, next) => {
+    try {
+        const databaseProps = await CommonAPI.getDatabaseCommonInteractionProps(req);
+        const projectId = CommonAPI.assertAuthenticatedProjectMember(databaseProps);
+        if (isRefreshRequested(req)) {
+            OnCallReadinessService.clearCache();
+        }
+        const policyId = readObjectIdParam(req, "policyId");
+        const page = readPageRequest(req);
+        /*
+         * The policy id arrives from the caller and the readiness read below runs
+         * as root, so the policy's OWN projectId - not the header - is what has to
+         * agree with the project the caller was authorised for.
+         */
+        const policy = await OnCallDutyPolicyService.findOneById({
+            id: policyId,
+            select: {
+                projectId: true,
+            },
+            props: {
+                isRoot: true,
+            },
+        });
+        CommonAPI.assertResourceBelongsToProject({
+            resourceProjectId: policy === null || policy === void 0 ? void 0 : policy.projectId,
+            projectId: projectId,
+        });
+        const summary = await OnCallReadinessService.getReadinessForPolicy(policyId, projectId);
+        return Response.sendJsonObjectResponse(req, res, serializeSummaryPage(summary, page));
+    }
+    catch (err) {
+        next(err);
+    }
+});
+/*
+ * Readiness across every policy in the project. Backs the On-Call > Readiness
+ * page and the section banner. The project comes from the `tenantid` header
+ * rather than the path, which is why assertAuthenticatedProjectMember - which
+ * checks the caller against that very header - is the whole authorisation story
+ * for this route.
+ *
+ * Paged: `?limit=&skip=`. This is the widest scope in the product - every
+ * responder on every policy - so it is the route that would otherwise serialise
+ * a whole project's coverage grid into one response.
+ */
+router.get("/on-call-readiness/project", UserMiddleware.getUserMiddleware, async (req, res, next) => {
+    try {
+        const databaseProps = await CommonAPI.getDatabaseCommonInteractionProps(req);
+        const projectId = CommonAPI.assertAuthenticatedProjectMember(databaseProps);
+        if (isRefreshRequested(req)) {
+            OnCallReadinessService.clearCache();
+        }
+        const page = readPageRequest(req);
+        const summary = await OnCallReadinessService.getReadinessForProject(projectId);
+        return Response.sendJsonObjectResponse(req, res, serializeSummaryPage(summary, page));
+    }
+    catch (err) {
+        next(err);
+    }
+});
+/*
+ * Readiness for a single responder. Used by the add-responder modal, which asks
+ * about a user the moment they are picked - before they are on any policy, so
+ * this route deliberately does not require the user to be on one.
+ */
+router.get("/on-call-readiness/user/:userId", UserMiddleware.getUserMiddleware, async (req, res, next) => {
+    try {
+        const databaseProps = await CommonAPI.getDatabaseCommonInteractionProps(req);
+        const projectId = CommonAPI.assertAuthenticatedProjectMember(databaseProps);
+        if (isRefreshRequested(req)) {
+            OnCallReadinessService.clearCache();
+        }
+        const userId = readObjectIdParam(req, "userId");
+        await assertUserBelongsToProject(userId, projectId);
+        const readiness = await OnCallReadinessService.getReadinessForUser(userId, projectId);
+        return Response.sendJsonObjectResponse(req, res, serializeUserReadiness(readiness));
+    }
+    catch (err) {
+        next(err);
+    }
+});
+/*
+ * Ask a set of responders to finish their own notification setup.
+ *
+ * The only WRITE on this router, and the only thing in the readiness feature
+ * that reaches outside the product. It exists because the gaps this feature
+ * reports are not gaps an admin can close: a notification method lives on the
+ * responder's own account and has to be verified by them, so "tell them" is
+ * genuinely the whole of the available fix.
+ *
+ * Everything about who is mailed, what the mail says and whether it is sent at
+ * all belongs to OnCallSetupReminderService - including the re-check that each
+ * id is a member of this project, which is duplicated there on purpose so the
+ * service is safe for any caller and not only for this route.
+ *
+ * Two gates, in this order: membership (which project is this, and is the caller
+ * in it) and then permission (may they act in it). Both run before the body is
+ * read, because a route that validates a payload for a caller it is about to
+ * refuse has told that caller something about the payload format.
+ *
+ * The response is a PER-USER array, never a bare success. A caller that ticked
+ * eight responders and got a 200 back has no idea that two were reminded this
+ * morning and one has no address on file, and a UI that renders a green tick
+ * over that has told its user something false about whether a page will reach
+ * somebody. See serializeSetupReminderResult.
+ */
+router.post("/on-call-readiness/send-setup-reminder", UserMiddleware.getUserMiddleware, async (req, res, next) => {
+    try {
+        const databaseProps = await CommonAPI.getDatabaseCommonInteractionProps(req);
+        const projectId = CommonAPI.assertAuthenticatedProjectMember(databaseProps);
+        assertCanSendSetupReminders(databaseProps);
+        const userIds = readUserIdsFromBody(req);
+        const result = await OnCallSetupReminderService.sendSetupReminders({
+            projectId: projectId,
+            userIds: userIds,
+        });
+        return Response.sendJsonObjectResponse(req, res, serializeSetupReminderResult(result));
+    }
+    catch (err) {
+        next(err);
+    }
+});
+export default router;
+//# sourceMappingURL=OnCallReadinessAPI.js.map

package/build/dist/Server/API/OnCallReadinessAPI.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OnCallReadinessAPI.js","sourceRoot":"","sources":["../../../../Server/API/OnCallReadinessAPI.ts"],"names":[],"mappings":"AAAA,OAAO,cAAc,MAAM,iCAAiC,CAAC;AAC7D,OAAO,sBAMN,MAAM,oCAAoC,CAAC;AAC5C,OAAO,uBAAuB,MAAM,qCAAqC,CAAC;AAC1E,OAAO,0BAGN,MAAM,wCAAwC,CAAC;AAChD,OAAO,iBAAiB,MAAM,+BAA+B,CAAC;AAC9D,OAAO,OAKN,MAAM,kBAAkB,CAAC;AAC1B,OAAO,QAAQ,MAAM,mBAAmB,CAAC;AACzC,OAAO,SAAS,MAAM,aAAa,CAAC;AAEpC,OAAO,kCAAkC,EAAE,EACzC,cAAc,GACf,MAAM,6DAA6D,CAAC;AACrE,OAAO,gBAAgB,MAAM,wCAAwC,CAAC;AACtE,OAAO,sBAAsB,MAAM,8CAA8C,CAAC;AAElF,OAAO,QAAQ,MAAM,sBAAsB,CAAC;AAC5C,OAAO,UAA8B,MAAM,wBAAwB,CAAC;AAIpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AACH,MAAM,MAAM,GAAkB,OAAO,CAAC,SAAS,EAAE,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,2BAA2B,GAAW,GAAG,CAAC;AAChD,MAAM,uBAAuB,GAAW,GAAG,CAAC;AA6C5C;;;GAGG;AACH,MAAM,YAAY,GAAW,OAAO,CAAC;AAErC;;;;GAIG;AACH,SAAS,wBAAwB,CAC/B,GAAmB,EACnB,IAAY,EACZ,QAAgB;IAEhB,MAAM,GAAG,GAAuB,GAAG,CAAC,KAAK,CAAC,IAAI,CAAuB,CAAC;IAEtE,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,EAAE,EAAE,CAAC;QACpD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,gBAAgB,CACxB,GAAG,IAAI,uCAAuC,GAAG,IAAI,CACtD,CAAC;IACJ,CAAC;IAED,OAAO,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAS,kBAAkB,CAAC,GAAmB;IAC7C,MAAM,GAAG,GAAwB,GAAG,CAAC,KAAiC,CACpE,SAAS,CACY,CAAC;IAExB,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACtC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,UAAU,GAAW,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAE5D,OAAO,UAAU,KAAK,MAAM,IAAI,UAAU,KAAK,GAAG,CAAC;AACrD,CAAC;AAED,SAAS,eAAe,CAAC,GAAmB;IAC1C,MAAM,KAAK,GAAW,wBAAwB,CAC5C,GAAG,EACH,OAAO,EACP,2BAA2B,CAC5B,CAAC;IACF,MAAM,IAAI,GAAW,wBAAwB,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IAE9D,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,uBAAuB,EAAE,CAAC;QACjD,MAAM,IAAI,gBAAgB,CACxB,+BAA+B,uBAAuB,4CAA4C,CACnG,CAAC;IACJ,CAAC;IAED,OAAO;QACL,KAAK,EAAE,KAAK;QACZ,IAAI,EAAE,IAAI;KACX,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,KAAK,UAAU,0BAA0B,CACvC,MAAgB,EAChB,SAAmB;IAEnB,MAAM,WAAW,GAAsB,MAAM,iBAAiB,CAAC,MAAM,CAAC;QACpE,KAAK,EAAE;YACL,MAAM,EAAE,MAAM;YACd,SAAS,EAAE,SAAS;SACrB;QACD,MAAM,EAAE;YACN,GAAG,EAAE,IAAI;SACV;QACD,KAAK,EAAE,CAAC;QACR,IAAI,EAAE,CAAC;QACP,KAAK,EAAE;YACL,MAAM,EAAE,IAAI;SACb;KACF,CAAC,CAAC;IAEH,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,sBAAsB,CAC9B,uDAAuD,CACxD,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,0BAA0B,GAAsB;IACpD,UAAU,CAAC,YAAY;IACvB,UAAU,CAAC,YAAY;IACvB,UAAU,CAAC,WAAW;IACtB,UAAU,CAAC,2BAA2B;CACvC,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,SAAS,2BAA2B,CAClC,aAA6C;IAE7C,IAAI,aAAa,CAAC,aAAa,EAAE,CAAC;QAChC,OAAO;IACT,CAAC;IAED,MAAM,WAAW,GACf,kCAAkC,CAAC,kBAAkB,CACnD,aAAa,EACb,cAAc,CAAC,KAAK,CACrB,CAAC,GAAG,CAAC,CAAC,cAA8B,EAAc,EAAE;QACnD,OAAO,cAAc,CAAC,UAAU,CAAC;IACnC,CAAC,CAAC,CAAC;IAEL,MAAM,SAAS,GAAY,WAAW,CAAC,IAAI,CACzC,CAAC,UAAsB,EAAW,EAAE;QAClC,OAAO,0BAA0B,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IACzD,CAAC,CACF,CAAC;IAEF,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,sBAAsB,CAC9B,uDAAuD,CACxD,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,iBAAiB,CAAC,GAAmB,EAAE,IAAY;IAC1D,MAAM,GAAG,GAAY,GAAG,CAAC,MAAM,CAAC,IAAI,CAAY,IAAI,EAAE,CAAC;IACvD,QAAQ,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;IAC3B,OAAO,IAAI,QAAQ,CAAC,GAAG,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAS,mBAAmB,CAAC,GAAmB;IAC9C,MAAM,IAAI,GAAe,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAe,CAAC;IAExD,MAAM,GAAG,GAAY,IAAI,CAAC,SAAS,CAAC,CAAC;IAErC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,gBAAgB,CACxB,uDAAuD,CACxD,CAAC;IACJ,CAAC;IAED,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,KAAc,EAAY,EAAE;QAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,MAAM,IAAI,gBAAgB,CACxB,kDAAkD,CACnD,CAAC;QACJ,CAAC;QAED,QAAQ,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QAE7B,OAAO,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,SAAS,eAAe,CAAC,MAAuB;IAC9C,OAAO;QACL;;;;;;;;;;;;;;;WAeG;QACH,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE;QACpC,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,uEAAuE;QACvE,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;QACzC,UAAU,EAAE,MAAM,CAAC,UAAU;KAC9B,CAAC;AACJ,CAAC;AAED,SAAS,qBAAqB,CAAC,IAA2B;IACxD,OAAO;QACL,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB;;;;;WAKG;QACH,UAAU,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,SAAS;QACpE,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,QAAQ,EAAE,IAAI,CAAC,QAAQ;KACxB,CAAC;AACJ,CAAC;AAED,SAAS,sBAAsB,CAAC,SAAwB;IACtD,OAAO;QACL,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,QAAQ,EAAE;QACnC,QAAQ,EAAE,SAAS,CAAC,QAAQ;QAC5B,SAAS,EAAE,SAAS,CAAC,SAAS;QAC9B,oBAAoB,EAAE,SAAS,CAAC,oBAAoB;YAClD,CAAC,CAAC,SAAS,CAAC,oBAAoB,CAAC,QAAQ,EAAE;YAC3C,CAAC,CAAC,SAAS;QACb,MAAM,EAAE,SAAS,CAAC,MAAM;QACxB,OAAO,EAAE,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;QAC/C,QAAQ,EAAE,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,qBAAqB,CAAC;QACvD,OAAO,EAAE,SAAS,CAAC,OAAO;QAC1B,UAAU,EAAE,SAAS,CAAC,UAAU;QAChC;;;;;WAKG;QACH,KAAK,EAAE,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAmB,EAAc,EAAE;YAC7D,OAAO;gBACL,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE;gBACxB,IAAI,EAAE,IAAI,CAAC,IAAI;aAChB,CAAC;QACJ,CAAC,CAAC;KACH,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAS,oBAAoB,CAC3B,OAAyB,EACzB,IAA0B;IAE1B,MAAM,UAAU,GAAW,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC;IAChD,MAAM,UAAU,GAAyB,OAAO,CAAC,KAAK,CAAC,KAAK,CAC1D,IAAI,CAAC,IAAI,EACT,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,CACvB,CAAC;IAEF,MAAM,IAAI,GAA6B;QACrC,SAAS,EAAE,OAAO,CAAC,SAAS,CAAC,QAAQ,EAAE;QACvC,kBAAkB,EAAE,OAAO,CAAC,kBAAkB;YAC5C,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAAC,QAAQ,EAAE;YACvC,CAAC,CAAC,SAAS;QACb,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,mBAAmB,EAAE,OAAO,CAAC,mBAAmB;QAChD,iBAAiB,EAAE,OAAO,CAAC,iBAAiB;QAC5C;;;;WAIG;QACH,iBAAiB,EAAE,OAAO,CAAC,iBAAiB;QAC5C,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,UAAU,EAAE,UAAU;QACtB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf;;;;;WAKG;QACH,OAAO,EAAE,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC,MAAM,GAAG,UAAU;QACnD,KAAK,EAAE,UAAU,CAAC,GAAG,CAAC,sBAAsB,CAAC;KAC9C,CAAC;IAEF,OAAO,IAA6B,CAAC;AACvC,CAAC;AAkBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAS,gCAAgC,CACvC,MAA+B;IAE/B,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE;QAChC,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,OAAO,EAAE,MAAM,CAAC,OAAO;KACxB,CAAC;AACJ,CAAC;AAED,SAAS,4BAA4B,CAAC,MAA2B;IAC/D,MAAM,IAAI,GAA4B;QACpC,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,EAAE;QACtC,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,gCAAgC,CAAC;KAC9D,CAAC;IAEF,OAAO,IAA6B,CAAC;AACvC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,GAAG,CACR,qCAAqC,EACrC,cAAc,CAAC,iBAAiB,EAChC,KAAK,EACH,GAAmB,EACnB,GAAoB,EACpB,IAAkB,EACH,EAAE;IACjB,IAAI,CAAC;QACH,MAAM,aAAa,GACjB,MAAM,SAAS,CAAC,iCAAiC,CAAC,GAAG,CAAC,CAAC;QAEzD,MAAM,SAAS,GACb,SAAS,CAAC,gCAAgC,CAAC,aAAa,CAAC,CAAC;QAE5D,IAAI,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5B,sBAAsB,CAAC,UAAU,EAAE,CAAC;QACtC,CAAC;QAED,MAAM,QAAQ,GAAa,iBAAiB,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;QAE9D,MAAM,IAAI,GAAyB,eAAe,CAAC,GAAG,CAAC,CAAC;QAExD;;;;WAIG;QACH,MAAM,MAAM,GACV,MAAM,uBAAuB,CAAC,WAAW,CAAC;YACxC,EAAE,EAAE,QAAQ;YACZ,MAAM,EAAE;gBACN,SAAS,EAAE,IAAI;aAChB;YACD,KAAK,EAAE;gBACL,MAAM,EAAE,IAAI;aACb;SACF,CAAC,CAAC;QAEL,SAAS,CAAC,8BAA8B,CAAC;YACvC,iBAAiB,EAAE,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,SAAS;YACpC,SAAS,EAAE,SAAS;SACrB,CAAC,CAAC;QAEH,MAAM,OAAO,GACX,MAAM,sBAAsB,CAAC,qBAAqB,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;QAE1E,OAAO,QAAQ,CAAC,sBAAsB,CACpC,GAAG,EACH,GAAG,EACH,oBAAoB,CAAC,OAAO,EAAE,IAAI,CAAC,CACpC,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,GAAG,CAAC,CAAC;IACZ,CAAC;AACH,CAAC,CACF,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,GAAG,CACR,4BAA4B,EAC5B,cAAc,CAAC,iBAAiB,EAChC,KAAK,EACH,GAAmB,EACnB,GAAoB,EACpB,IAAkB,EACH,EAAE;IACjB,IAAI,CAAC;QACH,MAAM,aAAa,GACjB,MAAM,SAAS,CAAC,iCAAiC,CAAC,GAAG,CAAC,CAAC;QAEzD,MAAM,SAAS,GACb,SAAS,CAAC,gCAAgC,CAAC,aAAa,CAAC,CAAC;QAE5D,IAAI,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5B,sBAAsB,CAAC,UAAU,EAAE,CAAC;QACtC,CAAC;QAED,MAAM,IAAI,GAAyB,eAAe,CAAC,GAAG,CAAC,CAAC;QAExD,MAAM,OAAO,GACX,MAAM,sBAAsB,CAAC,sBAAsB,CAAC,SAAS,CAAC,CAAC;QAEjE,OAAO,QAAQ,CAAC,sBAAsB,CACpC,GAAG,EACH,GAAG,EACH,oBAAoB,CAAC,OAAO,EAAE,IAAI,CAAC,CACpC,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,GAAG,CAAC,CAAC;IACZ,CAAC;AACH,CAAC,CACF,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,GAAG,CACR,iCAAiC,EACjC,cAAc,CAAC,iBAAiB,EAChC,KAAK,EACH,GAAmB,EACnB,GAAoB,EACpB,IAAkB,EACH,EAAE;IACjB,IAAI,CAAC;QACH,MAAM,aAAa,GACjB,MAAM,SAAS,CAAC,iCAAiC,CAAC,GAAG,CAAC,CAAC;QAEzD,MAAM,SAAS,GACb,SAAS,CAAC,gCAAgC,CAAC,aAAa,CAAC,CAAC;QAE5D,IAAI,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5B,sBAAsB,CAAC,UAAU,EAAE,CAAC;QACtC,CAAC;QAED,MAAM,MAAM,GAAa,iBAAiB,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QAE1D,MAAM,0BAA0B,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QAEpD,MAAM,SAAS,GACb,MAAM,sBAAsB,CAAC,mBAAmB,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QAEtE,OAAO,QAAQ,CAAC,sBAAsB,CACpC,GAAG,EACH,GAAG,EACH,sBAAsB,CAAC,SAAS,CAAC,CAClC,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,GAAG,CAAC,CAAC;IACZ,CAAC;AACH,CAAC,CACF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,IAAI,CACT,wCAAwC,EACxC,cAAc,CAAC,iBAAiB,EAChC,KAAK,EACH,GAAmB,EACnB,GAAoB,EACpB,IAAkB,EACH,EAAE;IACjB,IAAI,CAAC;QACH,MAAM,aAAa,GACjB,MAAM,SAAS,CAAC,iCAAiC,CAAC,GAAG,CAAC,CAAC;QAEzD,MAAM,SAAS,GACb,SAAS,CAAC,gCAAgC,CAAC,aAAa,CAAC,CAAC;QAE5D,2BAA2B,CAAC,aAAa,CAAC,CAAC;QAE3C,MAAM,OAAO,GAAoB,mBAAmB,CAAC,GAAG,CAAC,CAAC;QAE1D,MAAM,MAAM,GACV,MAAM,0BAA0B,CAAC,kBAAkB,CAAC;YAClD,SAAS,EAAE,SAAS;YACpB,OAAO,EAAE,OAAO;SACjB,CAAC,CAAC;QAEL,OAAO,QAAQ,CAAC,sBAAsB,CACpC,GAAG,EACH,GAAG,EACH,4BAA4B,CAAC,MAAM,CAAC,CACrC,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,GAAG,CAAC,CAAC;IACZ,CAAC;AACH,CAAC,CACF,CAAC;AAEF,eAAe,MAAM,CAAC"}