@babylonjs-toolkit/server 0.0.0-stage → 9.35.0

package/lib/admin/SessionRoutes.js

@@ -0,0 +1,386 @@
+// The session routes (game-server-admin-console DR §6.11 sessions and notices rows, DR §6.6, §13 R17, R18): the
+// fleet-wide session list, a session's page and inspector, close, close-all, lock and notices, plus the room admin
+// client every room action goes through and this instance's describeSessions and sendNotice fleet commands.
+import { ErrorCode, matchMaker, ServerError } from "colyseus";
+import { AdminRequestError } from "./AdminApiRouter.js";
+import { ADMIN_PAGE_SIZE, ROOM_CALL_TIMEOUT_MS, ROOM_STOP_TIMEOUT_MS } from "./AdminConstants.js";
+import { hasPermission } from "./AdminPermissions.js";
+import { bodyObject, booleanField, numberField, optionalStringField } from "./AdminRequestBodies.js";
+import { createNoticePayload, noticeTextField, sendLocalNotice } from "./FleetRoutes.js";
+/** The only SessionRoom methods the admin API may call through remoteRoomCall (D11). */
+export const SESSION_ROOM_ADMIN_METHODS = {
+    describe: "adminDescribe",
+    inspect: "adminInspect",
+    kick: "adminKickPlayer",
+    close: "adminClose",
+    lock: "adminSetLocked",
+    notice: "adminSendNotice",
+    stop: "adminStopDedicated",
+    disconnectBanned: "adminDisconnectBanned"
+};
+/** HTTP status of a successful read or change. */
+const HTTP_OK = 200;
+/** HTTP status of an invalid request. */
+const HTTP_BAD_REQUEST = 400;
+/** HTTP status of an unknown session. */
+const HTTP_NOT_FOUND = 404;
+/** HTTP status of a room call that got no answer. */
+const HTTP_GATEWAY_TIMEOUT = 504;
+/** The text close-all must be confirmed with. */
+const CLOSE_ALL_CONFIRMATION = "close all sessions";
+/** Notice severities the API accepts. */
+const NOTICE_SEVERITIES = new Set(["info", "warning", "critical"]);
+/** Notice scopes the API accepts. */
+const NOTICE_SCOPES = new Set(["fleet", "instance", "session", "player"]);
+/** Session list fields the sort query may name (a leading "-" sorts descending). */
+const SESSION_SORT_FIELDS = new Set(["sessionName", "gameMode", "players", "createdAt", "bytesPerSecond", "processId"]);
+/** The sort of the session list when the query names none. */
+const DEFAULT_SESSION_SORT = "sessionName";
+/** Prefix of a descending sort. */
+const DESCENDING_PREFIX = "-";
+/** The playerId of "every player of the session". */
+const EVERY_PLAYER = 0;
+/** Every room action of the API, on whichever instance owns the room (R17). Only fixed method names are passed (D11). */
+export class RoomAdminClient {
+    /**
+     * A session's page.
+     * @param roomId The room.
+     * @param includeAddresses False hides player addresses.
+     * @returns The page.
+     */
+    describe(roomId, includeAddresses) {
+        return this.call(roomId, SESSION_ROOM_ADMIN_METHODS.describe, [includeAddresses]);
+    }
+    /**
+     * A session's network objects.
+     * @param roomId The room.
+     * @returns The inspector view.
+     */
+    inspect(roomId) {
+        return this.call(roomId, SESSION_ROOM_ADMIN_METHODS.inspect, []);
+    }
+    /**
+     * Kicks a player (D12).
+     * @param roomId The room.
+     * @param playerId The player.
+     * @param message Shown to the player.
+     * @param allowRejoin True to skip the kick block.
+     * @returns False when the room has no connected player with that id.
+     */
+    kick(roomId, playerId, message, allowRejoin) {
+        return this.call(roomId, SESSION_ROOM_ADMIN_METHODS.kick, [playerId, message, allowRejoin]);
+    }
+    /**
+     * Closes a session, telling its players GameClosed (D12).
+     * @param roomId The room.
+     * @param message Shown to the players.
+     */
+    async close(roomId, message) {
+        await this.call(roomId, SESSION_ROOM_ADMIN_METHODS.close, [message]);
+    }
+    /**
+     * Locks or unlocks a session.
+     * @param roomId The room.
+     * @param locked True to lock.
+     */
+    async setLocked(roomId, locked) {
+        await this.call(roomId, SESSION_ROOM_ADMIN_METHODS.lock, [locked]);
+    }
+    /**
+     * Sends a notice to one player of a session or to all of them.
+     * @param roomId The room.
+     * @param notice The notice.
+     * @param playerId The player, or 0 for everyone.
+     * @returns How many players were targeted.
+     */
+    sendNotice(roomId, notice, playerId) {
+        return this.call(roomId, SESSION_ROOM_ADMIN_METHODS.notice, [notice, playerId]);
+    }
+    /**
+     * Stops a dedicated session, telling its players GameClosed (D23). The room answers before it disconnects (R17).
+     * @param roomId The room.
+     * @param message Shown to the players.
+     * @returns What a restart under the same name needs.
+     * @throws AdminRequestError 404 when the room runs no dedicated runner.
+     */
+    async stopDedicated(roomId, message) {
+        const restartOptions = await this.call(roomId, SESSION_ROOM_ADMIN_METHODS.stop, [message], ROOM_STOP_TIMEOUT_MS);
+        if (restartOptions == null)
+            throw new AdminRequestError(HTTP_NOT_FOUND, "no such dedicated session");
+        return restartOptions;
+    }
+    /**
+     * Calls a fixed admin method of a room on its instance.
+     * @param roomId The room.
+     * @param method The method (from SESSION_ROOM_ADMIN_METHODS).
+     * @param methodArguments Its arguments.
+     * @param timeoutMs How long its instance has to answer (ROOM_CALL_TIMEOUT_MS unless the call says).
+     * @returns The method's result.
+     * @throws AdminRequestError 404 for an unknown room, 504 when its instance does not answer.
+     */
+    async call(roomId, method, methodArguments, timeoutMs = ROOM_CALL_TIMEOUT_MS) {
+        if (await matchMaker.getRoomById(roomId) == null)
+            throw new AdminRequestError(HTTP_NOT_FOUND, "no such session");
+        try {
+            return await matchMaker.remoteRoomCall(roomId, method, methodArguments, timeoutMs);
+        }
+        catch (error) {
+            if (error instanceof ServerError && error.code === ErrorCode.MATCHMAKE_UNHANDLED)
+                throw new AdminRequestError(HTTP_GATEWAY_TIMEOUT, "the session's instance did not answer");
+            throw error;
+        }
+    }
+}
+/**
+ * Registers the sessions/* and notices routes.
+ * @param router The admin API router.
+ * @param services The shared services.
+ */
+export function registerSessionRoutes(router, services) {
+    const routes = [
+        { method: "GET", pattern: "sessions", permission: "sessions.view", requiresStepUp: false, auditAction: null, handler: async (request) => ({ status: HTTP_OK, body: await listSessions(services, request) }) },
+        { method: "GET", pattern: "sessions/:roomId", permission: "sessions.view", requiresStepUp: false, auditAction: null, handler: async (request) => ({ status: HTTP_OK, body: await services.roomClient.describe(request.params.roomId, canViewAddresses(request)) }) },
+        { method: "GET", pattern: "sessions/:roomId/inspect", permission: "sessions.inspect", requiresStepUp: false, auditAction: null, handler: async (request) => ({ status: HTTP_OK, body: await services.roomClient.inspect(request.params.roomId) }) },
+        { method: "POST", pattern: "sessions/:roomId/close", permission: "sessions.manage", requiresStepUp: false, auditAction: "session.close", handler: async (request) => closeSession(services, request) },
+        { method: "POST", pattern: "sessions/close-all", permission: "sessions.manage", requiresStepUp: true, auditAction: "session.closeAll", handler: async (request) => closeAllSessions(services, request) },
+        { method: "POST", pattern: "sessions/:roomId/lock", permission: "sessions.manage", requiresStepUp: false, auditAction: "session.lock", handler: async (request) => lockSession(services, request) },
+        { method: "POST", pattern: "notices", permission: "sessions.manage", requiresStepUp: isFleetNotice, auditAction: "notice.send", handler: async (request) => sendNotice(services, request) }
+    ];
+    for (const route of routes)
+        router.register(route);
+}
+/**
+ * Registers this instance's describeSessions and sendNotice fleet commands (R15).
+ * @param services The shared services.
+ */
+export function registerSessionCommands(services) {
+    services.fleet.handle("describeSessions", async () => Array.from(services.state.sessionRooms).map((room) => room.adminSummary()));
+    services.fleet.handle("sendNotice", async (command) => ({ targetedPlayers: sendLocalNotice(services.state, command.roomId, command.playerId, command.notice) }));
+}
+/**
+ * Every session of the fleet (R18), described by each instance in-process.
+ * @param services The shared services.
+ * @returns The sessions, unsorted.
+ */
+export async function describeFleetSessions(services) {
+    const described = await services.fleet.runOnAll("describeSessions", null);
+    return described.results.flatMap((entry) => entry.result);
+}
+/**
+ * Whether the caller may see player addresses.
+ * @param request The request.
+ * @returns True with players.viewAddresses.
+ */
+export function canViewAddresses(request) {
+    return request.caller != null && hasPermission(request.caller.permissions, "players.viewAddresses");
+}
+/**
+ * The page number of a list query (1-based).
+ * @param request The request.
+ * @returns The page, 1 when missing or invalid.
+ */
+export function pageOf(request) {
+    const page = Number(request.query.get("page") ?? "1");
+    return (Number.isInteger(page) && page >= 1) ? page : 1;
+}
+/**
+ * One page of a list (ADMIN_PAGE_SIZE rows).
+ * @param items Every row, sorted.
+ * @param page The 1-based page.
+ * @returns The page and the total.
+ */
+export function pageItems(items, page) {
+    const start = (page - 1) * ADMIN_PAGE_SIZE;
+    return { items: items.slice(start, start + ADMIN_PAGE_SIZE), total: items.length };
+}
+/**
+ * Whether a notice request is fleet-wide (step-up applies to fleet notices only, R8).
+ * @param request The request.
+ * @returns True for scope "fleet".
+ */
+function isFleetNotice(request) {
+    return bodyObject(request.body).scope === "fleet";
+}
+/**
+ * GET sessions: filtered, sorted and paged on this instance (R18).
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The page.
+ */
+async function listSessions(services, request) {
+    const sessions = (await describeFleetSessions(services)).filter(sessionFilter(request.query));
+    sessions.sort(sessionComparator(request.query.get("sort") ?? DEFAULT_SESSION_SORT));
+    return pageItems(sessions, pageOf(request));
+}
+/**
+ * The filter of the session list query: search (session name or room id), gameMode, processId, dedicated, locked and
+ * minPlayers.
+ * @param query The query.
+ * @returns The filter.
+ */
+function sessionFilter(query) {
+    const search = (query.get("search") ?? "").toLowerCase();
+    const gameMode = query.get("gameMode");
+    const processId = query.get("processId");
+    const dedicated = query.get("dedicated");
+    const locked = query.get("locked");
+    const minPlayers = Number(query.get("minPlayers") ?? "0");
+    return (session) => {
+        if (search !== "" && !session.sessionName.toLowerCase().includes(search) && !session.roomId.toLowerCase().includes(search))
+            return false;
+        if (gameMode != null && gameMode !== "" && session.gameMode !== gameMode)
+            return false;
+        if (processId != null && processId !== "" && session.processId !== processId)
+            return false;
+        if (dedicated != null && dedicated !== "" && (session.dedicatedScene != null) !== (dedicated === "true"))
+            return false;
+        if (locked != null && locked !== "" && session.locked !== (locked === "true"))
+            return false;
+        return !(Number.isFinite(minPlayers) && session.players < minPlayers);
+    };
+}
+/**
+ * The comparator of a sort query.
+ * @param sort A field of SESSION_SORT_FIELDS, with a leading "-" for descending.
+ * @returns The comparator (by session name for an unknown field).
+ */
+function sessionComparator(sort) {
+    const descending = sort.startsWith(DESCENDING_PREFIX);
+    const requestedField = descending ? sort.substring(DESCENDING_PREFIX.length) : sort;
+    const field = (SESSION_SORT_FIELDS.has(requestedField) ? requestedField : DEFAULT_SESSION_SORT);
+    const direction = descending ? -1 : 1;
+    return (left, right) => direction * compareValues(left[field], right[field]);
+}
+/**
+ * Compares two list values: numbers by size, anything else as text (null last).
+ * @param left The first value.
+ * @param right The second value.
+ * @returns Negative, zero or positive.
+ */
+function compareValues(left, right) {
+    if (typeof left === "number" && typeof right === "number")
+        return left - right;
+    if (left == null)
+        return (right == null) ? 0 : 1;
+    if (right == null)
+        return -1;
+    return String(left).localeCompare(String(right));
+}
+/**
+ * POST sessions/:roomId/close: the players are told GameClosed with the message (D12).
+ * @param services The shared services.
+ * @param request The request.
+ * @returns ok.
+ */
+async function closeSession(services, request) {
+    const message = noticeTextField(bodyObject(request.body), "message") ?? "";
+    await services.roomClient.close(request.params.roomId, message);
+    return { status: HTTP_OK, body: { ok: true }, audit: { target: request.params.roomId, parameters: { message: message } } };
+}
+/**
+ * POST sessions/close-all: closes every session of the fleet, confirmed by typing "close all sessions".
+ * @param services The shared services.
+ * @param request The request.
+ * @returns How many sessions were closed.
+ * @throws AdminRequestError 400 without the confirmation.
+ */
+async function closeAllSessions(services, request) {
+    const body = bodyObject(request.body);
+    if (body.confirmText !== CLOSE_ALL_CONFIRMATION)
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "type '" + CLOSE_ALL_CONFIRMATION + "' to confirm");
+    const message = noticeTextField(body, "message") ?? "";
+    const sessions = await describeFleetSessions(services);
+    let closed = 0;
+    for (const session of sessions) {
+        try {
+            await services.roomClient.close(session.roomId, message);
+            closed += 1;
+        }
+        catch (error) {
+            // A session that ended meanwhile, or whose instance did not answer, is not counted.
+            if (!(error instanceof AdminRequestError))
+                throw error;
+        }
+    }
+    return { status: HTTP_OK, body: { closed: closed }, audit: { target: "fleet", parameters: { message: message, closed: closed } } };
+}
+/**
+ * POST sessions/:roomId/lock.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns ok.
+ */
+async function lockSession(services, request) {
+    const locked = booleanField(bodyObject(request.body), "locked");
+    await services.roomClient.setLocked(request.params.roomId, locked);
+    return { status: HTTP_OK, body: { ok: true }, audit: { target: request.params.roomId, parameters: { locked: locked } } };
+}
+/**
+ * POST notices: to one player, a session, an instance or everyone (fleet scope through runOnAll).
+ * @param services The shared services.
+ * @param request The request.
+ * @returns How many players were targeted.
+ * @throws AdminRequestError 400 for a bad scope, severity, text or target.
+ */
+async function sendNotice(services, request) {
+    const body = bodyObject(request.body);
+    const scope = String(body.scope ?? "");
+    if (!NOTICE_SCOPES.has(scope))
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "scope must be fleet, instance, session or player");
+    const notice = noticeOf(services, body);
+    const sent = { targetedPlayers: await deliverNotice(services, scope, body, notice) };
+    const target = (scope === "fleet") ? "fleet" : String(body.roomId ?? body.processId ?? "");
+    return { status: HTTP_OK, body: sent, audit: { target: target, parameters: { scope: scope, text: notice.text, severity: notice.severity, playerId: body.playerId ?? null } } };
+}
+/**
+ * The notice of a POST notices body.
+ * @param services The shared services.
+ * @param body The body.
+ * @returns The notice.
+ * @throws AdminRequestError 400 for an empty or long text, an unknown severity or a bad countdown.
+ */
+function noticeOf(services, body) {
+    const text = noticeTextField(body, "text");
+    if (text == null || text === "")
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "text must be text");
+    const severity = String(body.severity ?? "info");
+    if (!NOTICE_SEVERITIES.has(severity))
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "severity must be info, warning or critical");
+    const countdownSeconds = (body.countdownSeconds == null) ? null : numberField(body, "countdownSeconds");
+    return createNoticePayload(services, text, severity, countdownSeconds);
+}
+/**
+ * Delivers a notice to its scope.
+ * @param services The shared services.
+ * @param scope "fleet", "instance", "session" or "player".
+ * @param body The body (processId, roomId, playerId).
+ * @param notice The notice.
+ * @returns How many players were targeted.
+ */
+async function deliverNotice(services, scope, body, notice) {
+    if (scope === "fleet") {
+        const sent = await services.fleet.runOnAll("sendNotice", { roomId: null, playerId: EVERY_PLAYER, notice: notice });
+        return sent.results.reduce((total, entry) => total + entry.result.targetedPlayers, 0);
+    }
+    if (scope === "instance") {
+        const processId = requiredField(body, "processId");
+        const sent = await services.fleet.runOn(processId, "sendNotice", { roomId: null, playerId: EVERY_PLAYER, notice: notice });
+        return sent.targetedPlayers;
+    }
+    const roomId = requiredField(body, "roomId");
+    const playerId = (scope === "player") ? numberField(body, "playerId") : EVERY_PLAYER;
+    return services.roomClient.sendNotice(roomId, notice, playerId);
+}
+/**
+ * A required, non-empty text field.
+ * @param body The body.
+ * @param name The field.
+ * @returns The text.
+ * @throws AdminRequestError 400 when missing.
+ */
+function requiredField(body, name) {
+    const value = optionalStringField(body, name);
+    if (value == null || value === "")
+        throw new AdminRequestError(HTTP_BAD_REQUEST, name + " must be text");
+    return value;
+}

package/lib/admin/UserRoutes.d.ts

@@ -0,0 +1,8 @@
+import { type AdminApiRouter } from "./AdminApiRouter.js";
+import type { AdminServices } from "./AdminServices.js";
+/**
+ * Registers every users/* route.
+ * @param router The admin API router.
+ * @param services The shared services.
+ */
+export declare function registerUserRoutes(router: AdminApiRouter, services: AdminServices): void;

package/lib/admin/UserRoutes.js

@@ -0,0 +1,214 @@
+// The admin user routes (game-server-admin-console DR §6.11 users/* rows, DR §5 owner rules): only an owner manages
+// owners, and the last enabled owner can never be removed, demoted or disabled.
+import { AdminRequestError } from "./AdminApiRouter.js";
+import { isAdminRole } from "./AdminPermissions.js";
+import { bodyObject, booleanField, numberField, optionalStringField, stringField } from "./AdminRequestBodies.js";
+/** HTTP status of a successful read or change. */
+const HTTP_OK = 200;
+/** HTTP status of a created account. */
+const HTTP_CREATED = 201;
+/** HTTP status of an invalid request. */
+const HTTP_BAD_REQUEST = 400;
+/** HTTP status of an owner rule refusal. */
+const HTTP_FORBIDDEN = 403;
+/** HTTP status of an unknown account. */
+const HTTP_NOT_FOUND = 404;
+/** HTTP status of the last-owner rule. */
+const HTTP_CONFLICT = 409;
+/** The permission every change here needs. */
+const MANAGE_PERMISSION = "users.manage";
+/** The owner role. */
+const OWNER_ROLE = "owner";
+/** The last-owner refusal (DR §5). */
+const LAST_OWNER_MESSAGE = "the last owner cannot be removed";
+/** The owner-rule refusal (DR §5). */
+const OWNER_ONLY_MESSAGE = "only an owner can create, change or delete an owner";
+/**
+ * Registers every users/* route.
+ * @param router The admin API router.
+ * @param services The shared services.
+ */
+export function registerUserRoutes(router, services) {
+    const routes = [
+        { method: "GET", pattern: "users", permission: "users.view", requiresStepUp: false, auditAction: null, handler: async () => ({ status: HTTP_OK, body: await listUsers(services) }) },
+        { method: "POST", pattern: "users", permission: MANAGE_PERMISSION, requiresStepUp: true, auditAction: "user.create", handler: async (request) => createUser(services, request) },
+        { method: "PUT", pattern: "users/:userId", permission: MANAGE_PERMISSION, requiresStepUp: true, auditAction: "user.update", handler: async (request) => updateUser(services, request) },
+        { method: "POST", pattern: "users/:userId/reset-second-factor", permission: MANAGE_PERMISSION, requiresStepUp: true, auditAction: "user.resetSecondFactor", handler: async (request) => resetSecondFactor(services, request) },
+        { method: "POST", pattern: "users/:userId/unlock", permission: MANAGE_PERMISSION, requiresStepUp: false, auditAction: "user.unlock", handler: async (request) => unlockUser(services, request) },
+        { method: "POST", pattern: "users/:userId/end-sessions", permission: MANAGE_PERMISSION, requiresStepUp: false, auditAction: "user.endSessions", handler: async (request) => endSessions(services, request) },
+        { method: "DELETE", pattern: "users/:userId", permission: MANAGE_PERMISSION, requiresStepUp: true, auditAction: "user.delete", handler: async (request) => deleteUser(services, request) }
+    ];
+    for (const route of routes)
+        router.register(route);
+}
+/**
+ * GET users.
+ * @param services The shared services.
+ * @returns Every account, by username.
+ */
+async function listUsers(services) {
+    const users = await services.store.listDocuments("users");
+    users.sort((left, right) => left.value.username.localeCompare(right.value.username));
+    return users.map((stored) => services.accounts.toUserView(stored));
+}
+/**
+ * POST users: an account with a temporary password; it enrols its authenticator at its first sign-in.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The new account.
+ */
+async function createUser(services, request) {
+    const body = bodyObject(request.body);
+    const role = roleField(body);
+    if (role === OWNER_ROLE)
+        requireOwnerCaller(request);
+    const user = await services.accounts.createUser({
+        username: stringField(body, "username"),
+        displayName: optionalStringField(body, "displayName") ?? "",
+        email: optionalStringField(body, "email"),
+        role: role,
+        password: stringField(body, "temporaryPassword"),
+        oidcSubject: null
+    });
+    const stored = await requireUser(services, user.userId);
+    return { status: HTTP_CREATED, body: services.accounts.toUserView(stored), audit: { target: user.username, parameters: { role: role } } };
+}
+/**
+ * PUT users/:userId: display name, email, role or disabled, with the owner rules.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The updated account.
+ */
+async function updateUser(services, request) {
+    const body = bodyObject(request.body);
+    const stored = await requireUser(services, request.params.userId);
+    const updated = Object.assign({}, stored.value);
+    if (body.displayName !== undefined)
+        updated.displayName = stringField(body, "displayName");
+    if (body.email !== undefined)
+        updated.email = optionalStringField(body, "email");
+    if (body.role !== undefined)
+        updated.role = roleField(body);
+    if (body.disabled !== undefined)
+        updated.disabled = booleanField(body, "disabled");
+    const touchesOwner = stored.value.role === OWNER_ROLE || updated.role === OWNER_ROLE;
+    if (touchesOwner)
+        requireOwnerCaller(request);
+    const losesOwner = stored.value.role === OWNER_ROLE && !stored.value.disabled && (updated.role !== OWNER_ROLE || updated.disabled);
+    if (losesOwner)
+        await requireAnotherOwner(services, stored.value.userId);
+    const saved = await services.store.putDocument("users", stored.id, updated, numberField(body, "expectedRevision"));
+    if (updated.disabled)
+        await services.sessions.endAllFor(updated.userId);
+    const changes = Object.assign({}, body);
+    delete changes.expectedRevision;
+    return { status: HTTP_OK, body: services.accounts.toUserView(saved), audit: { target: updated.username, parameters: changes } };
+}
+/**
+ * POST users/:userId/reset-second-factor.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns ok.
+ */
+async function resetSecondFactor(services, request) {
+    const stored = await requireUser(services, request.params.userId);
+    if (stored.value.role === OWNER_ROLE)
+        requireOwnerCaller(request);
+    await services.accounts.resetSecondFactor(stored.id);
+    await services.sessions.endAllFor(stored.id);
+    return okResult(stored.value.username);
+}
+/**
+ * POST users/:userId/unlock.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns ok.
+ */
+async function unlockUser(services, request) {
+    const stored = await requireUser(services, request.params.userId);
+    await services.accounts.unlock(stored.id);
+    return okResult(stored.value.username);
+}
+/**
+ * POST users/:userId/end-sessions.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns How many sessions ended.
+ */
+async function endSessions(services, request) {
+    const stored = await requireUser(services, request.params.userId);
+    if (stored.value.role === OWNER_ROLE)
+        requireOwnerCaller(request);
+    const ended = await services.sessions.endAllFor(stored.id);
+    return { status: HTTP_OK, body: { ended: ended }, audit: { target: stored.value.username, parameters: {} } };
+}
+/**
+ * DELETE users/:userId, with the owner rules.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns ok.
+ */
+async function deleteUser(services, request) {
+    const stored = await requireUser(services, request.params.userId);
+    if (stored.value.role === OWNER_ROLE) {
+        requireOwnerCaller(request);
+        if (!stored.value.disabled)
+            await requireAnotherOwner(services, stored.id);
+    }
+    await services.sessions.endAllFor(stored.id);
+    await services.store.deleteDocument("users", stored.id);
+    return okResult(stored.value.username);
+}
+/**
+ * An ok answer audited against an account.
+ * @param username The account's username.
+ * @returns The result.
+ */
+function okResult(username) {
+    return { status: HTTP_OK, body: { ok: true }, audit: { target: username, parameters: {} } };
+}
+/**
+ * The role field of a body.
+ * @param body The body object.
+ * @returns The role.
+ * @throws AdminRequestError 400 for an unknown role.
+ */
+function roleField(body) {
+    const role = stringField(body, "role");
+    if (!isAdminRole(role))
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "unknown role " + role);
+    return role;
+}
+/**
+ * Reads an account that must exist.
+ * @param services The shared services.
+ * @param userId The account id.
+ * @returns The stored account.
+ * @throws AdminRequestError 404 when it does not exist.
+ */
+async function requireUser(services, userId) {
+    const stored = await services.accounts.getUser(userId);
+    if (stored == null)
+        throw new AdminRequestError(HTTP_NOT_FOUND, "no such admin user");
+    return stored;
+}
+/**
+ * Only a signed-in owner may create, change or delete an owner (an admin holds users.manage but cannot grant owner).
+ * @param request The request.
+ * @throws AdminRequestError 403 naming users.manage otherwise.
+ */
+function requireOwnerCaller(request) {
+    const caller = request.caller;
+    if (caller?.user?.role !== OWNER_ROLE)
+        throw new AdminRequestError(HTTP_FORBIDDEN, OWNER_ONLY_MESSAGE, MANAGE_PERMISSION);
+}
+/**
+ * Refuses to remove the last enabled owner (DR §5).
+ * @param services The shared services.
+ * @param ownerId The owner being removed, demoted or disabled.
+ * @throws AdminRequestError 409 when no other enabled owner exists.
+ */
+async function requireAnotherOwner(services, ownerId) {
+    if (!(await services.accounts.hasAnotherEnabledOwner(ownerId)))
+        throw new AdminRequestError(HTTP_CONFLICT, LAST_OWNER_MESSAGE);
+}

package/lib/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};