@babylonjs-toolkit/server 0.0.0-stage → 9.35.0

package/lib/admin/PlayerRoutes.js

@@ -0,0 +1,676 @@
+// The player and ban routes (game-server-admin-console DR §6.11 players, lobby and bans rows, DR §7.4, §7.5, §13 R29,
+// R30): fleet-wide player search, a player's page, kick, notes, lobby kick and every bans/* route, plus this
+// instance's searchPlayers, disconnectBanned and kickFromLobby fleet commands (R15).
+import { randomUUID } from "node:crypto";
+import { BlockList, isIP } from "node:net";
+import { addNetworkEntry, isAddressInList, normalizeAddress } from "../NetworkAddresses.js";
+import { AdminRequestError } from "./AdminApiRouter.js";
+import { SHARED_ADDRESS_PLAYER_THRESHOLD } from "./AdminConstants.js";
+import { hasPermission } from "./AdminPermissions.js";
+import { bodyObject, booleanField, numberField, optionalStringField, stringField } from "./AdminRequestBodies.js";
+import { RECORD_QUERY_MAX_LIMIT } from "./AdminStore.js";
+import { BanList, banRefusalDetail, isBanActive } from "./BanList.js";
+import { noticeTextField } from "./FleetRoutes.js";
+import { canViewAddresses, pageItems, pageOf } from "./SessionRoutes.js";
+/** HTTP status of a successful read or change. */
+const HTTP_OK = 200;
+/** HTTP status of a created ban or note. */
+const HTTP_CREATED = 201;
+/** HTTP status of an invalid request. */
+const HTTP_BAD_REQUEST = 400;
+/** HTTP status of a missing permission. */
+const HTTP_FORBIDDEN = 403;
+/** HTTP status of an unknown player or ban. */
+const HTTP_NOT_FOUND = 404;
+/** HTTP status of a ban that needs a confirmation. */
+const HTTP_CONFLICT = 409;
+/** Milliseconds per second. */
+const MILLISECONDS_PER_SECOND = 1000;
+/** Longest player note, in characters. */
+const PLAYER_NOTE_MAX_LENGTH = 2000;
+/** Most past sessions a player page lists. */
+const PLAYER_HISTORY_LIMIT = 20;
+/** Subject prefix of a player known by user id. */
+const USER_SUBJECT_PREFIX = "user:";
+/** Subject prefix of a player known by address. */
+const ADDRESS_SUBJECT_PREFIX = "address:";
+/** Ban kinds the API accepts. */
+const BAN_KINDS = new Set(["user", "address", "network"]);
+/** The version of the bans.json format (R30). */
+const BAN_FILE_VERSION = 1;
+/** The refusal of a user-id ban while player authentication is off (DR §7.5). */
+const USER_BAN_NEEDS_AUTH_MESSAGE = "bans by user id need player authentication (auth.enabled)";
+/** The refusal of a ban that may hit a shared proxy (DR §7.5). */
+const SHARED_ADDRESS_MESSAGE = "this address may be a proxy shared by many players";
+/**
+ * Registers the players/*, lobby/kick and bans/* routes.
+ * @param router The admin API router.
+ * @param services The shared services.
+ */
+export function registerPlayerRoutes(router, services) {
+    const routes = [
+        { method: "GET", pattern: "players", permission: "players.view", requiresStepUp: false, auditAction: null, handler: async (request) => ({ status: HTTP_OK, body: await searchFleetPlayers(services, request) }) },
+        { method: "GET", pattern: "players/detail", permission: "players.view", requiresStepUp: false, auditAction: null, handler: async (request) => ({ status: HTTP_OK, body: await describePlayer(services, request) }) },
+        { method: "POST", pattern: "players/kick", permission: "players.manage", requiresStepUp: false, auditAction: "player.kick", handler: async (request) => kickPlayer(services, request) },
+        { method: "POST", pattern: "players/notes", permission: "players.notes", requiresStepUp: false, auditAction: "player.note", handler: async (request) => addNote(services, request) },
+        { method: "POST", pattern: "lobby/kick", permission: "players.manage", requiresStepUp: false, auditAction: "lobby.kick", handler: async (request) => kickFromLobby(services, request) },
+        { method: "GET", pattern: "bans", permission: "bans.view", requiresStepUp: false, auditAction: null, handler: async (request) => ({ status: HTTP_OK, body: await listBans(services, request) }) },
+        { method: "POST", pattern: "bans", permission: "bans.manage", requiresStepUp: false, auditAction: "ban.create", handler: async (request) => createBan(services, request) },
+        { method: "GET", pattern: "bans/export", permission: "bans.view", requiresStepUp: false, auditAction: null, handler: async () => exportBans(services) },
+        { method: "POST", pattern: "bans/import", permission: "bans.manage", requiresStepUp: true, auditAction: "ban.import", handler: async (request) => importBans(services, request) },
+        { method: "PUT", pattern: "bans/:banId", permission: "bans.manage", requiresStepUp: false, auditAction: "ban.update", handler: async (request) => updateBan(services, request) },
+        { method: "DELETE", pattern: "bans/:banId", permission: "bans.manage", requiresStepUp: false, auditAction: "ban.remove", handler: async (request) => removeBan(services, request) }
+    ];
+    for (const route of routes)
+        router.register(route);
+}
+/**
+ * Registers this instance's searchPlayers, disconnectBanned and kickFromLobby fleet commands (R15).
+ * @param services The shared services.
+ */
+export function registerPlayerCommands(services) {
+    services.fleet.handle("searchPlayers", async (command) => searchLocalPlayers(services.state, command.search, command.includeAddresses));
+    services.fleet.handle("disconnectBanned", async (command) => ({ disconnected: await disconnectLocalBanned(services, command.banIds, command.message) }));
+    services.fleet.handle("kickFromLobby", async (command) => ({ disconnected: kickLocalLobbyClients(services.state, command) }));
+}
+/**
+ * Reads every stored ban into this instance's BanList (at start and on every "bans" change announcement, D15).
+ * @param services The shared services.
+ * @returns Every stored ban.
+ */
+export async function reloadBanList(services) {
+    const stored = await services.store.listDocuments("bans");
+    const records = stored.map((document) => document.value);
+    services.banList.reload(records);
+    return records;
+}
+/**
+ * The players of this instance's sessions that match a search: user id, display name, session name, the exact player
+ * id, and the address when addresses may be shown.
+ * @param state The server state.
+ * @param search The search text ("" for every player).
+ * @param includeAddresses True to match and return addresses.
+ * @returns The players.
+ */
+function searchLocalPlayers(state, search, includeAddresses) {
+    const needle = search.trim().toLowerCase();
+    const rows = [];
+    for (const room of state.sessionRooms) {
+        const session = room.adminDescribe(true);
+        for (const player of session.playerList) {
+            if (!playerMatches(player, session.sessionName, needle, includeAddresses))
+                continue;
+            rows.push({
+                roomId: session.roomId,
+                sessionName: session.sessionName,
+                processId: session.processId,
+                playerId: player.playerId,
+                userId: player.userId,
+                displayName: player.displayName,
+                clientAddress: includeAddresses ? player.clientAddress : null,
+                transport: player.transport,
+                joinedAt: player.joinedAt
+            });
+        }
+    }
+    return rows;
+}
+/**
+ * Whether a player matches a search.
+ * @param player The player.
+ * @param sessionName Its session.
+ * @param needle The lower-case search ("" matches everyone).
+ * @param includeAddresses True to also match the address.
+ * @returns True on a match.
+ */
+function playerMatches(player, sessionName, needle, includeAddresses) {
+    if (needle === "")
+        return true;
+    const texts = [player.userId, player.displayName, sessionName, includeAddresses ? player.clientAddress : null];
+    if (texts.some((text) => text != null && text.toLowerCase().includes(needle)))
+        return true;
+    return String(player.playerId) === needle;
+}
+/**
+ * Disconnects this instance's playing clients that the named bans match (R15). The BanList is reloaded from the store
+ * first, so every instance enforces the new ban for fresh joins too; ranges are matched here (CIDR bans).
+ * @param services The shared services.
+ * @param banIds The new or changed bans.
+ * @param message Shown to the disconnected players.
+ * @returns How many clients were disconnected.
+ */
+async function disconnectLocalBanned(services, banIds, message) {
+    const records = await reloadBanList(services);
+    const matcher = new BanList(() => services.clock.now());
+    matcher.reload(records.filter((record) => banIds.includes(record.banId)));
+    let disconnected = 0;
+    for (const room of Array.from(services.state.sessionRooms))
+        disconnected += disconnectRoomBanned(room, matcher, message);
+    return disconnected;
+}
+/**
+ * Disconnects the clients of one room that a ban list matches.
+ * @param room The room.
+ * @param matcher The bans to apply.
+ * @param message Shown to the disconnected players.
+ * @returns How many clients were disconnected.
+ */
+function disconnectRoomBanned(room, matcher, message) {
+    const banned = room.adminDescribe(true).playerList.filter((player) => matcher.playerBan(player.userId, player.clientAddress ?? "") != null);
+    if (banned.length === 0)
+        return 0;
+    const userIds = banned.map((player) => player.userId).filter((userId) => userId != null);
+    const addresses = banned.map((player) => player.clientAddress ?? "");
+    return room.adminDisconnectBanned(userIds, addresses, message);
+}
+/**
+ * Removes matching clients from this instance's lobby rooms.
+ * @param state The server state.
+ * @param request The user id and address to remove.
+ * @returns How many clients were removed.
+ */
+function kickLocalLobbyClients(state, request) {
+    const userIds = (request.userId != null) ? [request.userId] : [];
+    const addresses = (request.address != null) ? [request.address] : [];
+    return Array.from(state.lobbyRooms).reduce((total, room) => total + room.adminKickMatching(userIds, addresses), 0);
+}
+/**
+ * Every player of the fleet that matches a search.
+ * @param services The shared services.
+ * @param search The search text.
+ * @param includeAddresses True to match and return addresses.
+ * @returns The players, unsorted.
+ */
+async function fleetPlayers(services, search, includeAddresses) {
+    const found = await services.fleet.runOnAll("searchPlayers", { search: search, includeAddresses: includeAddresses });
+    return found.results.flatMap((entry) => entry.result);
+}
+/**
+ * GET players: the fleet's players matching the search, by session and player id.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The page.
+ */
+async function searchFleetPlayers(services, request) {
+    const players = await fleetPlayers(services, request.query.get("search") ?? "", canViewAddresses(request));
+    players.sort((left, right) => left.sessionName.localeCompare(right.sessionName) || left.playerId - right.playerId);
+    return pageItems(players, pageOf(request));
+}
+/**
+ * GET players/detail?userId= or ?address=: where the player is online, its recent sessions, its bans and (with
+ * players.notes) its notes and kicks.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The player page.
+ * @throws AdminRequestError 400 without userId or address, 403 for an address without players.viewAddresses.
+ */
+async function describePlayer(services, request) {
+    const userId = nonEmpty(request.query.get("userId"));
+    const address = nonEmpty(request.query.get("address"));
+    if (userId == null && address == null)
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "userId or address is needed");
+    const includeAddresses = canViewAddresses(request);
+    if (address != null && !includeAddresses)
+        throw new AdminRequestError(HTTP_FORBIDDEN, "you do not have permission for this", "players.viewAddresses");
+    const subject = playerSubject(userId, address);
+    const online = (await fleetPlayers(services, userId ?? address ?? "", true))
+        .filter((player) => (userId != null) ? player.userId === userId : normalizeAddress(player.clientAddress ?? "") === normalizeAddress(address ?? ""))
+        .map((player) => Object.assign({}, player, { clientAddress: includeAddresses ? player.clientAddress : null }));
+    const seesNotes = request.caller != null && hasPermission(request.caller.permissions, "players.notes");
+    return {
+        userId: userId,
+        address: address,
+        // Verified claims stay inside the rooms; the player page shows identity through the online rows.
+        claims: null,
+        online: online,
+        recentSessions: await recentSessionsOf(services, userId, address),
+        bans: (await storedBans(services)).filter((stored) => banMatchesSubject(stored.value, userId, address)).map((stored) => toBanView(stored, services.clock.now())),
+        notes: seesNotes ? await notesOf(services, subject) : [],
+        kicks: seesNotes ? await kicksOf(services, subject) : []
+    };
+}
+/**
+ * A player's recent sessions from the playerHistory stream, newest first.
+ * @param services The shared services.
+ * @param userId The user id, or null.
+ * @param address The address, or null.
+ * @returns At most PLAYER_HISTORY_LIMIT sessions.
+ */
+async function recentSessionsOf(services, userId, address) {
+    // The newest records are read, then walked oldest first so each leave closes its join.
+    const records = (await services.store.readRecords("playerHistory", { limit: RECORD_QUERY_MAX_LIMIT, newestFirst: true })).reverse();
+    const sessions = new Map();
+    for (const record of records) {
+        const event = record.value;
+        const isSubject = (userId != null) ? event.userId === userId : normalizeAddress(event.clientAddress) === normalizeAddress(address ?? "");
+        if (!isSubject)
+            continue;
+        const key = event.processId + "/" + event.roomId + "/" + event.playerId;
+        const joined = sessions.get(key);
+        if (event.kind === "joined")
+            sessions.set(key, { roomId: event.roomId, sessionName: event.sessionName, processId: event.processId, playerId: event.playerId, joinedAt: event.at, leftAt: null });
+        else if (joined != null)
+            joined.leftAt = event.at;
+    }
+    return Array.from(sessions.values()).sort((left, right) => right.joinedAt.localeCompare(left.joinedAt)).slice(0, PLAYER_HISTORY_LIMIT);
+}
+/**
+ * The notes on a subject, newest first.
+ * @param services The shared services.
+ * @param subject "user:<id>" or "address:<address>".
+ * @returns The notes.
+ */
+async function notesOf(services, subject) {
+    const stored = await services.store.listDocuments("playerNotes");
+    return stored.map((document) => document.value).filter((note) => note.subject === subject).sort((left, right) => right.at.localeCompare(left.at));
+}
+/**
+ * The audited kicks of a subject (the kick route audits its target as the player's subject).
+ * @param services The shared services.
+ * @param subject "user:<id>" or "address:<address>".
+ * @returns The kick records.
+ */
+async function kicksOf(services, subject) {
+    const page = await services.audit.query({ action: "player.kick", target: subject }, 1);
+    return page.items.filter((record) => record.target === subject);
+}
+/**
+ * POST players/kick (DR §7.4).
+ * @param services The shared services.
+ * @param request The request.
+ * @returns ok.
+ * @throws AdminRequestError 404 when the session or the connected player does not exist.
+ */
+async function kickPlayer(services, request) {
+    const body = bodyObject(request.body);
+    const roomId = stringField(body, "roomId");
+    const playerId = numberField(body, "playerId");
+    const message = noticeTextField(body, "message") ?? "";
+    const allowRejoin = (body.allowRejoin == null) ? false : booleanField(body, "allowRejoin");
+    const session = await services.roomClient.describe(roomId, true);
+    const player = session.playerList.find((candidate) => candidate.playerId === playerId);
+    const kicked = player != null && await services.roomClient.kick(roomId, playerId, message, allowRejoin);
+    if (player == null || !kicked)
+        throw new AdminRequestError(HTTP_NOT_FOUND, "no such player in this session");
+    services.extensions.callHook("onPlayerKicked", { roomId: roomId, playerId: playerId, userId: player.userId, message: message, by: callerName(request) });
+    const parameters = { roomId: roomId, sessionName: session.sessionName, playerId: playerId, message: message, allowRejoin: allowRejoin };
+    return { status: HTTP_OK, body: { ok: true }, audit: { target: playerSubject(player.userId, player.clientAddress), parameters: parameters } };
+}
+/**
+ * Calls the onBanCreated admin hook (R29).
+ * @param services The shared services.
+ * @param record The new ban.
+ * @param by The admin who created it.
+ */
+function callBanCreatedHook(services, record, by) {
+    services.extensions.callHook("onBanCreated", { banId: record.banId, kind: record.kind, value: record.value, expiresAt: record.expiresAt, by: by });
+}
+/**
+ * POST players/notes: a note on a user id or an address.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The note.
+ */
+async function addNote(services, request) {
+    const body = bodyObject(request.body);
+    const subjectValue = stringField(body, "subject").trim();
+    const text = stringField(body, "text").trim();
+    if (subjectValue === "" || text === "")
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "subject and text must not be empty");
+    if (text.length > PLAYER_NOTE_MAX_LENGTH)
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "text is longer than " + PLAYER_NOTE_MAX_LENGTH + " characters");
+    const isAddress = isIP(normalizeAddress(subjectValue)) !== 0;
+    const subject = isAddress ? playerSubject(null, subjectValue) : playerSubject(subjectValue, null);
+    const note = { noteId: randomUUID(), subject: subject, text: text, by: callerName(request), at: new Date(services.clock.now()).toISOString() };
+    await services.store.putDocument("playerNotes", note.noteId, note, 0);
+    return { status: HTTP_CREATED, body: note, audit: { target: subject, parameters: { noteId: note.noteId } } };
+}
+/**
+ * POST lobby/kick: removes matching clients from every instance's lobby.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns How many clients were removed.
+ * @throws AdminRequestError 400 without a user id or an address.
+ */
+async function kickFromLobby(services, request) {
+    const body = bodyObject(request.body);
+    const command = { userId: nonEmpty(optionalStringField(body, "userId")), address: nonEmpty(optionalStringField(body, "address")) };
+    if (command.userId == null && command.address == null)
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "userId or address is needed");
+    const kicked = await services.fleet.runOnAll("kickFromLobby", command);
+    const disconnected = kicked.results.reduce((total, entry) => total + entry.result.disconnected, 0);
+    return { status: HTTP_OK, body: { disconnected: disconnected }, audit: { target: playerSubject(command.userId, command.address), parameters: { disconnected: disconnected } } };
+}
+/**
+ * GET bans?search&kind&active, newest first.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The bans.
+ */
+async function listBans(services, request) {
+    const search = (request.query.get("search") ?? "").toLowerCase();
+    const kind = nonEmpty(request.query.get("kind"));
+    const active = nonEmpty(request.query.get("active"));
+    const views = (await storedBans(services)).map((stored) => toBanView(stored, services.clock.now()));
+    return views
+        .filter((ban) => search === "" || [ban.value, ban.reason, ban.note].some((text) => text.toLowerCase().includes(search)))
+        .filter((ban) => kind == null || ban.kind === kind)
+        .filter((ban) => active == null || ban.active === (active === "true"))
+        .sort((left, right) => right.createdAt.localeCompare(left.createdAt));
+}
+/**
+ * POST bans (DR §7.5): validates, refuses a likely shared proxy address without confirmation, stores the ban and makes
+ * every instance enforce it and disconnect matching players.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The ban.
+ * @throws AdminRequestError 400 for an invalid ban or a user-id ban with auth off, 409 for an unconfirmed shared address.
+ */
+async function createBan(services, request) {
+    const body = bodyObject(request.body);
+    const kind = banKindField(body);
+    const value = banValueOf(services, kind, stringField(body, "value"));
+    const durationSeconds = (body.durationSeconds == null) ? null : numberField(body, "durationSeconds");
+    if (durationSeconds != null && durationSeconds <= 0)
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "durationSeconds must be more than 0, or null for a permanent ban");
+    if (kind !== "user" && body.confirmSharedAddress !== true)
+        await refuseSharedAddress(services, value);
+    const now = services.clock.now();
+    const expiresAt = (durationSeconds != null) ? new Date(now + durationSeconds * MILLISECONDS_PER_SECOND).toISOString() : null;
+    const record = newBanRecord(services, request, { kind: kind, value: value, reason: optionalStringField(body, "reason") ?? "", note: optionalStringField(body, "note") ?? "", expiresAt: expiresAt }, "created");
+    const stored = await services.store.putDocument("bans", record.banId, record, 0);
+    await applyBanChange(services, [record.banId], banRefusalDetail(record));
+    callBanCreatedHook(services, record, callerName(request));
+    return { status: HTTP_CREATED, body: toBanView(stored, now), audit: { target: record.banId, parameters: { kind: kind, value: value, expiresAt: expiresAt, reason: record.reason } } };
+}
+/**
+ * PUT bans/:banId: a new end time, reason or note, with an optimistic revision.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The ban.
+ * @throws AdminRequestError 404 for an unknown ban, 400 for a bad end time; AdminConflictError when the revision moved.
+ */
+async function updateBan(services, request) {
+    const body = bodyObject(request.body);
+    const stored = await requireBan(services, request.params.banId);
+    const expiresAt = optionalStringField(body, "expiresAt");
+    if (expiresAt != null && !Number.isFinite(Date.parse(expiresAt)))
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "expiresAt must be an ISO time or null");
+    const now = services.clock.now();
+    const updated = Object.assign({}, stored.value, {
+        expiresAt: (expiresAt != null) ? new Date(expiresAt).toISOString() : null,
+        reason: optionalStringField(body, "reason") ?? stored.value.reason,
+        note: optionalStringField(body, "note") ?? stored.value.note,
+        history: stored.value.history.concat([{ at: new Date(now).toISOString(), by: callerName(request), change: "updated" }])
+    });
+    const saved = await services.store.putDocument("bans", stored.id, updated, numberField(body, "expectedRevision"));
+    await applyBanChange(services, [updated.banId], banRefusalDetail(updated));
+    return { status: HTTP_OK, body: toBanView(saved, now), audit: { target: updated.banId, parameters: { expiresAt: updated.expiresAt, reason: updated.reason } } };
+}
+/**
+ * DELETE bans/:banId: every instance admits the player again.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns ok.
+ * @throws AdminRequestError 404 for an unknown ban.
+ */
+async function removeBan(services, request) {
+    const stored = await requireBan(services, request.params.banId);
+    await services.store.deleteDocument("bans", stored.id);
+    await reloadBanList(services);
+    await services.fleet.announceChange("bans");
+    services.extensions.callHook("onBanRemoved", { banId: stored.id, by: callerName(request) });
+    return { status: HTTP_OK, body: { ok: true }, audit: { target: stored.id, parameters: { kind: stored.value.kind, value: stored.value.value } } };
+}
+/**
+ * GET bans/export: the active bans as bans.json (R30).
+ * @param services The shared services.
+ * @returns The download.
+ */
+async function exportBans(services) {
+    const now = services.clock.now();
+    const active = (await storedBans(services)).map((stored) => stored.value).filter((record) => isBanActive(record, now));
+    const file = {
+        version: BAN_FILE_VERSION,
+        exportedAt: new Date(now).toISOString(),
+        bans: active.map((record) => ({ kind: record.kind, value: record.value, reason: record.reason, note: record.note, expiresAt: record.expiresAt }))
+    };
+    const bytes = new TextEncoder().encode(JSON.stringify(file, null, 2));
+    return { status: HTTP_OK, body: null, download: { bytes: bytes, contentType: "application/json", fileName: "bans.json" } };
+}
+/**
+ * POST bans/import: adds the bans of a bans.json file; expired entries, duplicates of an active ban, invalid entries and
+ * user-id bans while auth is off are skipped (R30).
+ * @param services The shared services.
+ * @param request The request.
+ * @returns How many were imported and skipped.
+ * @throws AdminRequestError 400 for a file of another format.
+ */
+async function importBans(services, request) {
+    const body = bodyObject(request.body);
+    if (body.version !== BAN_FILE_VERSION || !Array.isArray(body.bans))
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "the body must be a bans.json file (version 1)");
+    const now = services.clock.now();
+    const activeKeys = new Set((await storedBans(services)).map((stored) => stored.value).filter((record) => isBanActive(record, now)).map(banKeyOf));
+    const importedIds = [];
+    for (const entry of body.bans) {
+        const record = importedBanRecord(services, request, entry, now);
+        if (record == null || activeKeys.has(banKeyOf(record)))
+            continue;
+        activeKeys.add(banKeyOf(record));
+        await services.store.putDocument("bans", record.banId, record, 0);
+        importedIds.push(record.banId);
+        callBanCreatedHook(services, record, callerName(request));
+    }
+    if (importedIds.length > 0)
+        await applyBanChange(services, importedIds, "you are banned");
+    const result = { imported: importedIds.length, skipped: body.bans.length - importedIds.length };
+    return { status: HTTP_OK, body: result, audit: { target: "bans", parameters: result } };
+}
+/**
+ * The ban record of one bans.json entry.
+ * @param services The shared services.
+ * @param request The request (its caller is the creator).
+ * @param entry The entry.
+ * @param now The current time.
+ * @returns The record, or null when the entry is invalid, expired or a user-id ban while auth is off.
+ */
+function importedBanRecord(services, request, entry, now) {
+    if (entry == null || typeof entry !== "object")
+        return null;
+    const fields = entry;
+    const expiresAt = (typeof fields.expiresAt === "string") ? fields.expiresAt : null;
+    if (expiresAt != null && !(Date.parse(expiresAt) > now))
+        return null;
+    try {
+        const kind = banKindField(fields);
+        const value = banValueOf(services, kind, stringField(fields, "value"));
+        const reason = (typeof fields.reason === "string") ? fields.reason : "";
+        const note = (typeof fields.note === "string") ? fields.note : "";
+        return newBanRecord(services, request, { kind: kind, value: value, reason: reason, note: note, expiresAt: expiresAt }, "imported");
+    }
+    catch (error) {
+        if (error instanceof AdminRequestError)
+            return null;
+        throw error;
+    }
+}
+/**
+ * Makes every instance enforce changed bans: this instance reloads at once, the change is announced, and every
+ * instance disconnects the playing clients the bans match (DR §7.5 steps 3–4).
+ * @param services The shared services.
+ * @param banIds The new or changed bans.
+ * @param message Shown to the disconnected players.
+ */
+async function applyBanChange(services, banIds, message) {
+    await reloadBanList(services);
+    await services.fleet.announceChange("bans");
+    await services.fleet.runOnAll("disconnectBanned", { banIds: banIds, message: message });
+}
+/**
+ * Refuses an address or network ban that matches an address more than SHARED_ADDRESS_PLAYER_THRESHOLD live players
+ * share, unless the server trusts a proxy (then addresses are the players' own, DR §7.5).
+ * @param services The shared services.
+ * @param value The banned address or range.
+ * @throws AdminRequestError 409 with detail "confirmSharedAddress".
+ */
+async function refuseSharedAddress(services, value) {
+    if (services.config.trustProxy)
+        return;
+    const matcher = new BlockList();
+    addNetworkEntry(matcher, value);
+    const playersByAddress = new Map();
+    for (const player of await fleetPlayers(services, "", true)) {
+        const address = normalizeAddress(player.clientAddress ?? "");
+        playersByAddress.set(address, (playersByAddress.get(address) ?? 0) + 1);
+    }
+    for (const [address, players] of playersByAddress) {
+        if (players > SHARED_ADDRESS_PLAYER_THRESHOLD && isAddressInList(matcher, address))
+            throw new AdminRequestError(HTTP_CONFLICT, SHARED_ADDRESS_MESSAGE, "confirmSharedAddress");
+    }
+}
+/**
+ * A new ban record.
+ * @param services The shared services.
+ * @param request The request (its caller is the creator).
+ * @param fields What the ban matches, why, and until when.
+ * @param change The history entry ("created" or "imported").
+ * @returns The record.
+ */
+function newBanRecord(services, request, fields, change) {
+    const at = new Date(services.clock.now()).toISOString();
+    const by = callerName(request);
+    return Object.assign({ banId: randomUUID(), createdBy: by, createdAt: at, history: [{ at: at, by: by, change: change }] }, fields);
+}
+/**
+ * The kind field of a ban.
+ * @param body The body or file entry.
+ * @returns The kind.
+ * @throws AdminRequestError 400 for another value.
+ */
+function banKindField(body) {
+    const kind = String(body.kind ?? "");
+    if (!BAN_KINDS.has(kind))
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "kind must be user, address or network");
+    return kind;
+}
+/**
+ * Validates and normalizes a ban's value.
+ * @param services The shared services.
+ * @param kind The ban kind.
+ * @param rawValue The value sent.
+ * @returns The value stored (addresses normalized).
+ * @throws AdminRequestError 400 for a user-id ban with auth off, an empty user id, or a bad address or range.
+ */
+function banValueOf(services, kind, rawValue) {
+    const value = rawValue.trim();
+    if (kind === "user") {
+        if (!services.config.auth.enabled)
+            throw new AdminRequestError(HTTP_BAD_REQUEST, USER_BAN_NEEDS_AUTH_MESSAGE);
+        if (value === "")
+            throw new AdminRequestError(HTTP_BAD_REQUEST, "value must be a user id");
+        return value;
+    }
+    if (kind === "address") {
+        const address = normalizeAddress(value);
+        if (isIP(address) === 0)
+            throw new AdminRequestError(HTTP_BAD_REQUEST, "value must be an IP address");
+        return address;
+    }
+    if (!value.includes("/") || !addNetworkEntry(new BlockList(), value))
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "value must be a CIDR range such as 203.0.113.0/24");
+    return value;
+}
+/**
+ * Whether a ban applies to a player page's subject.
+ * @param record The ban.
+ * @param userId The user id, or null.
+ * @param address The address, or null.
+ * @returns True when it matches.
+ */
+function banMatchesSubject(record, userId, address) {
+    if (record.kind === "user")
+        return userId != null && record.value === userId;
+    if (address == null)
+        return false;
+    const matcher = new BlockList();
+    return addNetworkEntry(matcher, record.value) && isAddressInList(matcher, address);
+}
+/**
+ * Every stored ban.
+ * @param services The shared services.
+ * @returns The documents.
+ */
+async function storedBans(services) {
+    return services.store.listDocuments("bans");
+}
+/**
+ * A stored ban.
+ * @param services The shared services.
+ * @param banId The ban.
+ * @returns The document.
+ * @throws AdminRequestError 404 when it does not exist.
+ */
+async function requireBan(services, banId) {
+    const stored = await services.store.getDocument("bans", banId);
+    if (stored == null)
+        throw new AdminRequestError(HTTP_NOT_FOUND, "no such ban");
+    return stored;
+}
+/**
+ * The console view of a stored ban.
+ * @param stored The document.
+ * @param now The current time (whether it is still active).
+ * @returns The view.
+ */
+function toBanView(stored, now) {
+    const record = stored.value;
+    return {
+        banId: record.banId,
+        kind: record.kind,
+        value: record.value,
+        reason: record.reason,
+        note: record.note,
+        expiresAt: record.expiresAt,
+        createdBy: record.createdBy,
+        createdAt: record.createdAt,
+        active: isBanActive(record, now),
+        revision: stored.revision,
+        history: record.history.slice()
+    };
+}
+/**
+ * The duplicate key of a ban: its kind and value.
+ * @param record The ban.
+ * @returns The key.
+ */
+function banKeyOf(record) {
+    return record.kind + "\u0000" + record.value;
+}
+/**
+ * The subject a note, a kick and a lobby kick are filed under: "user:<id>" when the player has a user id, else
+ * "address:<address>".
+ * @param userId The user id, or null.
+ * @param address The address, or null.
+ * @returns The subject.
+ */
+function playerSubject(userId, address) {
+    return (userId != null) ? USER_SUBJECT_PREFIX + userId : ADDRESS_SUBJECT_PREFIX + normalizeAddress(address ?? "");
+}
+/**
+ * The display name of the request's caller, for history entries and notes.
+ * @param request The request.
+ * @returns The name.
+ */
+function callerName(request) {
+    const caller = request.caller;
+    return (caller != null) ? caller.name : "unknown";
+}
+/**
+ * A query or body value that counts only when it is non-empty text.
+ * @param value The value.
+ * @returns The text, or null.
+ */
+function nonEmpty(value) {
+    return (value != null && value.trim() !== "") ? value.trim() : null;
+}