@babylonjs-toolkit/server 0.0.0-stage → 9.35.0

package/lib/admin/AlertRoutes.d.ts

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

package/lib/admin/AlertRoutes.js

@@ -0,0 +1,180 @@
+// The alerts, maintenance windows and rolling update routes (game-server-admin-console DR §6.11 alerts/*,
+// maintenance/windows* and rollouts* rows, D24).
+import { AdminRequestError } from "./AdminApiRouter.js";
+import { bodyObject, booleanField, numberField, optionalStringField, stringField, stringListField } from "./AdminRequestBodies.js";
+import { noticeTextField, nonNegativeNumberField, requireScaledOut } from "./FleetRoutes.js";
+/** HTTP status of a successful answer. */
+const HTTP_OK = 200;
+/** HTTP status of an invalid request. */
+const HTTP_BAD_REQUEST = 400;
+/** The ok body of an answer with nothing else to say. */
+const OK_BODY = { ok: true };
+/** The alert states the history can be filtered by. */
+const ALERT_STATES = new Set(["firing", "resolved"]);
+/**
+ * Registers every alerts/*, maintenance/windows* and rollouts* route.
+ * @param router The admin API router.
+ * @param services The shared services.
+ */
+export function registerAlertRoutes(router, services) {
+    const routes = [
+        { method: "GET", pattern: "alerts/rules", permission: "alerts.view", requiresStepUp: false, auditAction: null, handler: async () => ok(await services.alerts.listRules()) },
+        { method: "PUT", pattern: "alerts/rules/:ruleId", permission: "alerts.manage", requiresStepUp: false, auditAction: "alert.rule", handler: async (request) => updateRule(services, request) },
+        { method: "POST", pattern: "alerts/rules/:ruleId/silence", permission: "alerts.manage", requiresStepUp: false, auditAction: "alert.silence", handler: async (request) => silenceRule(services, request) },
+        { method: "GET", pattern: "alerts/channels", permission: "alerts.view", requiresStepUp: false, auditAction: null, handler: async () => ok(await services.alerts.listChannels()) },
+        { method: "POST", pattern: "alerts/channels", permission: "alerts.manage", requiresStepUp: true, auditAction: "alert.channelCreate", handler: async (request) => createChannel(services, request) },
+        { method: "DELETE", pattern: "alerts/channels/:channelId", permission: "alerts.manage", requiresStepUp: false, auditAction: "alert.channelDelete", handler: async (request) => okAfter(services.alerts.deleteChannel(request.params.channelId)) },
+        { method: "POST", pattern: "alerts/channels/:channelId/test", permission: "alerts.manage", requiresStepUp: false, auditAction: "alert.channelTest", handler: async (request) => ok(await services.alerts.testChannel(request.params.channelId)) },
+        { method: "GET", pattern: "alerts/history", permission: "alerts.view", requiresStepUp: false, auditAction: null, handler: async (request) => ok(await services.alerts.listAlerts(alertStateOf(request.query), pageOf(request.query))) },
+        { method: "POST", pattern: "alerts/history/:alertId/acknowledge", permission: "alerts.manage", requiresStepUp: false, auditAction: "alert.acknowledge", handler: async (request) => acknowledgeAlert(services, request) },
+        { method: "GET", pattern: "maintenance/windows", permission: "fleet.view", requiresStepUp: false, auditAction: null, handler: async () => ok(await services.maintenanceWindows.list()) },
+        { method: "POST", pattern: "maintenance/windows", permission: "fleet.manage", requiresStepUp: true, auditAction: "maintenance.schedule", handler: async (request) => createWindow(services, request) },
+        { method: "DELETE", pattern: "maintenance/windows/:windowId", permission: "fleet.manage", requiresStepUp: false, auditAction: "maintenance.cancel", handler: async (request) => okAfter(services.maintenanceWindows.cancel(request.params.windowId)) },
+        { method: "GET", pattern: "rollouts", permission: "fleet.view", requiresStepUp: false, auditAction: null, handler: async () => ok(await services.rollouts.list()) },
+        { method: "POST", pattern: "rollouts", permission: "fleet.manage", requiresStepUp: true, auditAction: "rollout.start", handler: async (request) => startRollout(services, request) },
+        { method: "POST", pattern: "rollouts/:rolloutId/:command", permission: "fleet.manage", requiresStepUp: false, auditAction: (request) => "rollout." + request.params.command, handler: async (request) => ok(await services.rollouts.command(request.params.rolloutId, request.params.command)) }
+    ];
+    for (const route of routes)
+        router.register(route);
+}
+/**
+ * A 200 answer.
+ * @param body The JSON body.
+ * @returns The result.
+ */
+function ok(body) {
+    return { status: HTTP_OK, body: body };
+}
+/**
+ * Waits for an action, then answers ok.
+ * @param action The action.
+ * @returns The ok result.
+ */
+async function okAfter(action) {
+    await action;
+    return ok(OK_BODY);
+}
+/**
+ * PUT alerts/rules/:ruleId.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The rule.
+ */
+async function updateRule(services, request) {
+    const body = bodyObject(request.body);
+    const update = {
+        enabled: booleanField(body, "enabled"),
+        threshold: (body.threshold == null) ? null : numberField(body, "threshold"),
+        forMinutes: nonNegativeNumberField(body, "forMinutes"),
+        severity: stringField(body, "severity"),
+        channelIds: (body.channelIds == null) ? [] : stringListField(body, "channelIds")
+    };
+    const ruleId = request.params.ruleId;
+    return { status: HTTP_OK, body: await services.alerts.updateRule(ruleId, update), audit: { target: ruleId, parameters: { ...update } } };
+}
+/**
+ * POST alerts/rules/:ruleId/silence.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The rule.
+ */
+async function silenceRule(services, request) {
+    const minutes = nonNegativeNumberField(bodyObject(request.body), "minutes");
+    const ruleId = request.params.ruleId;
+    return { status: HTTP_OK, body: await services.alerts.silenceRule(ruleId, minutes), audit: { target: ruleId, parameters: { minutes: minutes } } };
+}
+/**
+ * POST alerts/channels: the audit record leaves out the URL and routing key (secrets).
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The channel, secrets masked.
+ */
+async function createChannel(services, request) {
+    const body = bodyObject(request.body);
+    const channel = {
+        kind: stringField(body, "kind"),
+        name: stringField(body, "name"),
+        url: optionalStringField(body, "url"),
+        routingKey: optionalStringField(body, "routingKey")
+    };
+    const view = await services.alerts.createChannel(channel, callerNameOf(request));
+    return { status: HTTP_OK, body: view, audit: { target: view.channelId, parameters: { kind: channel.kind, name: channel.name } } };
+}
+/**
+ * POST alerts/history/:alertId/acknowledge.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The alert.
+ */
+async function acknowledgeAlert(services, request) {
+    const alert = await services.alerts.acknowledge(request.params.alertId, callerNameOf(request));
+    return { status: HTTP_OK, body: alert, audit: { target: alert.alertId, parameters: { ruleId: alert.ruleId } } };
+}
+/**
+ * POST maintenance/windows.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The window.
+ */
+async function createWindow(services, request) {
+    const body = bodyObject(request.body);
+    const window = {
+        startsAt: stringField(body, "startsAt"),
+        endsAt: stringField(body, "endsAt"),
+        message: noticeTextField(body, "message") ?? "",
+        warningMinutes: (body.warningMinutes == null) ? null : nonNegativeNumberField(body, "warningMinutes"),
+        allowUserIds: (body.allowUserIds == null) ? [] : stringListField(body, "allowUserIds"),
+        allowAddresses: (body.allowAddresses == null) ? [] : stringListField(body, "allowAddresses"),
+        leaveReadiness: (body.leaveReadiness == null) ? false : booleanField(body, "leaveReadiness")
+    };
+    const view = await services.maintenanceWindows.create(window, callerNameOf(request));
+    return { status: HTTP_OK, body: view, audit: { target: view.windowId, parameters: { ...window } } };
+}
+/**
+ * POST rollouts: needs Redis (R33) and at least two live instances (DR §7.8).
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The rollout.
+ */
+async function startRollout(services, request) {
+    requireScaledOut(services);
+    const body = bodyObject(request.body);
+    const rollout = {
+        noticeText: noticeTextField(body, "noticeText"),
+        noticeLeadSeconds: (body.noticeLeadSeconds == null) ? 0 : nonNegativeNumberField(body, "noticeLeadSeconds"),
+        perInstanceTimeoutMinutes: numberField(body, "perInstanceTimeoutMinutes")
+    };
+    const view = await services.rollouts.start(rollout, callerNameOf(request));
+    return { status: HTTP_OK, body: view, audit: { target: view.rolloutId, parameters: { ...rollout } } };
+}
+/**
+ * The name of the admin making a request, for createdBy and acknowledgedBy fields.
+ * @param request The request.
+ * @returns The caller's name.
+ */
+function callerNameOf(request) {
+    return request.caller?.name ?? "unknown";
+}
+/**
+ * The state filter of GET alerts/history.
+ * @param query The query.
+ * @returns "firing", "resolved" or null for both.
+ * @throws AdminRequestError 400 for another value.
+ */
+function alertStateOf(query) {
+    const state = query.get("state");
+    if (state == null || state === "")
+        return null;
+    if (!ALERT_STATES.has(state))
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "state must be firing or resolved");
+    return state;
+}
+/**
+ * The page of a query string.
+ * @param query The query.
+ * @returns The page, from 1.
+ */
+function pageOf(query) {
+    const page = Number(query.get("page") ?? 1);
+    return (Number.isInteger(page) && page >= 1) ? page : 1;
+}

package/lib/admin/ApiKeyRoutes.d.ts

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

package/lib/admin/ApiKeyRoutes.js

@@ -0,0 +1,53 @@
+// The API key routes of the admin API (game-server-admin-console DR §6.11 api-keys/* rows, D18).
+import { AdminRequestError } from "./AdminApiRouter.js";
+import { bodyObject, optionalStringField, stringField, stringListField } from "./AdminRequestBodies.js";
+/** HTTP status of a successful read or revoke. */
+const HTTP_OK = 200;
+/** HTTP status of a created key. */
+const HTTP_CREATED = 201;
+/** HTTP status of a caller without an identity (never reached: the route needs a caller). */
+const HTTP_UNAUTHORIZED = 401;
+/**
+ * Registers every api-keys/* route.
+ * @param router The admin API router.
+ * @param services The shared services.
+ */
+export function registerApiKeyRoutes(router, services) {
+    const routes = [
+        { method: "GET", pattern: "api-keys", permission: "apiKeys.manage", requiresStepUp: false, auditAction: null, handler: async () => ({ status: HTTP_OK, body: (await services.apiKeys.list()).map((key) => services.apiKeys.toView(key)) }) },
+        { method: "POST", pattern: "api-keys", permission: "apiKeys.manage", requiresStepUp: true, auditAction: "apiKey.create", handler: async (request) => createKey(services, request) },
+        { method: "DELETE", pattern: "api-keys/:keyId", permission: "apiKeys.manage", requiresStepUp: true, auditAction: "apiKey.revoke", handler: async (request) => revokeKey(services, request) }
+    ];
+    for (const route of routes)
+        router.register(route);
+}
+/**
+ * POST api-keys: the secret is in this answer only.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The key and its secret.
+ */
+async function createKey(services, request) {
+    const caller = request.caller;
+    if (caller == null)
+        throw new AdminRequestError(HTTP_UNAUTHORIZED, "sign in first");
+    const body = bodyObject(request.body);
+    const created = await services.apiKeys.create({
+        name: stringField(body, "name"),
+        permissions: stringListField(body, "permissions"),
+        expiresAt: optionalStringField(body, "expiresAt"),
+        allowedNetworks: (body.allowedNetworks != null) ? stringListField(body, "allowedNetworks") : []
+    }, caller.id, caller.permissions);
+    const view = { key: services.apiKeys.toView(created.record), secret: created.secret };
+    return { status: HTTP_CREATED, body: view, audit: { target: created.record.name, parameters: { keyId: created.record.keyId, permissions: created.record.permissions } } };
+}
+/**
+ * DELETE api-keys/:keyId: refused at once from then on.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns ok.
+ */
+async function revokeKey(services, request) {
+    const revoked = await services.apiKeys.revoke(request.params.keyId);
+    return { status: HTTP_OK, body: { ok: true }, audit: { target: revoked.name, parameters: { keyId: revoked.keyId } } };
+}

package/lib/admin/ApiKeys.d.ts

@@ -0,0 +1,63 @@
+import { type AdminCaller } from "./AdminApiRouter.js";
+import type { AdminPermission, ApiKeyView, CreateApiKeyRequest } from "./AdminApiTypes.js";
+import type { AdminClock } from "./AdminClock.js";
+import type { ApiKeyRecord } from "./AdminRecords.js";
+import type { AdminStore } from "./AdminStore.js";
+/** Prefix of every API key bearer value. */
+export declare const API_KEY_PREFIX: string;
+/** The API keys of the admin store. */
+export declare class ApiKeys {
+    /** The admin store. */
+    private readonly store;
+    /** The clock of expiries and lastUsedAt. */
+    private readonly clock;
+    /**
+     * Creates the key service.
+     * @param store The admin store.
+     * @param clock The clock.
+     */
+    constructor(store: AdminStore, clock: AdminClock);
+    /**
+     * Creates a key; its secret is returned once and only its hash is stored.
+     * @param request The key's name, permissions, expiry and networks.
+     * @param createdBy The creating user's id, or "cli".
+     * @param creatorPermissions What the creator may do; a key never gets more.
+     * @returns The stored key and the full bearer value.
+     * @throws AdminRequestError 400 for an invalid request, 403 for a permission the creator lacks.
+     */
+    create(request: CreateApiKeyRequest, createdBy: string, creatorPermissions: ReadonlySet<AdminPermission>): Promise<{
+        record: ApiKeyRecord;
+        secret: string;
+    }>;
+    /**
+     * The caller of a `bgsk_` bearer value: the key must exist, match, be unrevoked, unexpired and allow the address.
+     * lastUsedAt is written at most once per API_KEY_TOUCH_INTERVAL_MS.
+     * @param bearer The bearer value.
+     * @param clientAddress The client address.
+     * @returns The caller, or null.
+     */
+    verify(bearer: string, clientAddress: string): Promise<AdminCaller | null>;
+    /**
+     * Revokes a key at once.
+     * @param keyId The key.
+     * @returns The revoked key.
+     * @throws AdminRequestError 404 for an unknown key.
+     */
+    revoke(keyId: string): Promise<ApiKeyRecord>;
+    /**
+     * Every key, newest first.
+     * @returns The keys.
+     */
+    list(): Promise<ApiKeyRecord[]>;
+    /**
+     * The configured admin.token as a full-access key (D18).
+     * @returns Its caller.
+     */
+    legacyCaller(): AdminCaller;
+    /**
+     * The console's view of a key (never its hash).
+     * @param key The key.
+     * @returns The view.
+     */
+    toView(key: ApiKeyRecord): ApiKeyView;
+}

package/lib/admin/ApiKeys.js

@@ -0,0 +1,167 @@
+// Scoped API keys of the admin API (game-server-admin-console D18): `bgsk_<keyId>_<secret>` bearer values whose secret
+// is stored only as a SHA-256 hash, each with a permission subset, an optional expiry and optional allowed networks.
+import { randomBytes } from "node:crypto";
+import { BlockList } from "node:net";
+import { addNetworkEntry, createNetworkList, isAddressInList } from "../NetworkAddresses.js";
+import { AdminRequestError } from "./AdminApiRouter.js";
+import { API_KEY_TOUCH_INTERVAL_MS } from "./AdminConstants.js";
+import { randomToken, sha256Hex, textsMatch } from "./AdminCrypto.js";
+import { LEGACY_TOKEN_PERMISSIONS, isAdminPermission } from "./AdminPermissions.js";
+/** Prefix of every API key bearer value. */
+export const API_KEY_PREFIX = "bgsk_";
+/** Random bytes of a key id (hex, so 12 characters without "_"). */
+const KEY_ID_BYTES = 6;
+/** Characters of a key id. */
+const KEY_ID_LENGTH = 12;
+/** Random bytes of a key secret. */
+const SECRET_BYTES = 32;
+/** HTTP status of an invalid key request. */
+const HTTP_BAD_REQUEST = 400;
+/** HTTP status of a key granting more than its creator holds. */
+const HTTP_FORBIDDEN = 403;
+/** HTTP status of an unknown key. */
+const HTTP_NOT_FOUND = 404;
+/** The API keys of the admin store. */
+export class ApiKeys {
+    /** The admin store. */
+    store;
+    /** The clock of expiries and lastUsedAt. */
+    clock;
+    /**
+     * Creates the key service.
+     * @param store The admin store.
+     * @param clock The clock.
+     */
+    constructor(store, clock) {
+        this.store = store;
+        this.clock = clock;
+    }
+    /**
+     * Creates a key; its secret is returned once and only its hash is stored.
+     * @param request The key's name, permissions, expiry and networks.
+     * @param createdBy The creating user's id, or "cli".
+     * @param creatorPermissions What the creator may do; a key never gets more.
+     * @returns The stored key and the full bearer value.
+     * @throws AdminRequestError 400 for an invalid request, 403 for a permission the creator lacks.
+     */
+    async create(request, createdBy, creatorPermissions) {
+        const name = request.name.trim();
+        if (name === "")
+            throw new AdminRequestError(HTTP_BAD_REQUEST, "the key needs a name");
+        const unknown = request.permissions.find((permission) => !isAdminPermission(permission));
+        if (unknown != null)
+            throw new AdminRequestError(HTTP_BAD_REQUEST, "unknown permission " + unknown);
+        const beyondCreator = request.permissions.find((permission) => !creatorPermissions.has(permission));
+        if (beyondCreator != null)
+            throw new AdminRequestError(HTTP_FORBIDDEN, "you cannot grant a permission you do not hold", beyondCreator);
+        if (request.expiresAt != null && Number.isNaN(Date.parse(request.expiresAt)))
+            throw new AdminRequestError(HTTP_BAD_REQUEST, "expiresAt must be an ISO time or null");
+        const probeList = new BlockList();
+        const badNetwork = request.allowedNetworks.find((entry) => !addNetworkEntry(probeList, entry));
+        if (badNetwork != null)
+            throw new AdminRequestError(HTTP_BAD_REQUEST, "not an address or CIDR range: " + badNetwork);
+        const keyId = randomBytes(KEY_ID_BYTES).toString("hex");
+        const secretPart = randomToken(SECRET_BYTES);
+        const record = {
+            keyId: keyId,
+            name: name,
+            secretHash: sha256Hex(secretPart),
+            permissions: Array.from(new Set(request.permissions)),
+            expiresAt: request.expiresAt,
+            allowedNetworks: request.allowedNetworks,
+            createdBy: createdBy,
+            createdAt: new Date(this.clock.now()).toISOString(),
+            lastUsedAt: null,
+            revoked: false
+        };
+        await this.store.putDocument("apiKeys", keyId, record, 0);
+        return { record: record, secret: API_KEY_PREFIX + keyId + "_" + secretPart };
+    }
+    /**
+     * The caller of a `bgsk_` bearer value: the key must exist, match, be unrevoked, unexpired and allow the address.
+     * lastUsedAt is written at most once per API_KEY_TOUCH_INTERVAL_MS.
+     * @param bearer The bearer value.
+     * @param clientAddress The client address.
+     * @returns The caller, or null.
+     */
+    async verify(bearer, clientAddress) {
+        const parsed = parseKey(bearer);
+        if (parsed == null)
+            return null;
+        const stored = await this.store.getDocument("apiKeys", parsed.keyId);
+        if (stored == null)
+            return null;
+        const key = stored.value;
+        const now = this.clock.now();
+        if (!textsMatch(sha256Hex(parsed.secretPart), key.secretHash) || key.revoked)
+            return null;
+        if (key.expiresAt != null && Date.parse(key.expiresAt) <= now)
+            return null;
+        if (key.allowedNetworks.length > 0 && !isAddressInList(createNetworkList(key.allowedNetworks), clientAddress))
+            return null;
+        if (key.lastUsedAt == null || now - Date.parse(key.lastUsedAt) >= API_KEY_TOUCH_INTERVAL_MS) {
+            await this.store.putDocument("apiKeys", key.keyId, Object.assign({}, key, { lastUsedAt: new Date(now).toISOString() }), null);
+        }
+        return { kind: "apiKey", id: key.keyId, name: key.name, permissions: new Set(key.permissions), session: null, user: null };
+    }
+    /**
+     * Revokes a key at once.
+     * @param keyId The key.
+     * @returns The revoked key.
+     * @throws AdminRequestError 404 for an unknown key.
+     */
+    async revoke(keyId) {
+        const stored = await this.store.getDocument("apiKeys", keyId);
+        if (stored == null)
+            throw new AdminRequestError(HTTP_NOT_FOUND, "no such API key");
+        const revoked = Object.assign({}, stored.value, { revoked: true });
+        await this.store.putDocument("apiKeys", keyId, revoked, stored.revision);
+        return revoked;
+    }
+    /**
+     * Every key, newest first.
+     * @returns The keys.
+     */
+    async list() {
+        const keys = await this.store.listDocuments("apiKeys");
+        return keys.map((stored) => stored.value).sort((left, right) => right.createdAt.localeCompare(left.createdAt));
+    }
+    /**
+     * The configured admin.token as a full-access key (D18).
+     * @returns Its caller.
+     */
+    legacyCaller() {
+        return { kind: "legacyToken", id: "legacy", name: "legacy admin token", permissions: LEGACY_TOKEN_PERMISSIONS, session: null, user: null };
+    }
+    /**
+     * The console's view of a key (never its hash).
+     * @param key The key.
+     * @returns The view.
+     */
+    toView(key) {
+        return {
+            keyId: key.keyId,
+            name: key.name,
+            permissions: key.permissions,
+            expiresAt: key.expiresAt,
+            allowedNetworks: key.allowedNetworks,
+            createdBy: key.createdBy,
+            createdAt: key.createdAt,
+            lastUsedAt: key.lastUsedAt,
+            revoked: key.revoked
+        };
+    }
+}
+/**
+ * Splits a bearer value into its key id and secret.
+ * @param bearer `bgsk_<keyId>_<secret>`.
+ * @returns The parts, or null when the value is not a key.
+ */
+function parseKey(bearer) {
+    if (!bearer.startsWith(API_KEY_PREFIX))
+        return null;
+    const rest = bearer.substring(API_KEY_PREFIX.length);
+    if (rest.length <= KEY_ID_LENGTH + 1 || rest[KEY_ID_LENGTH] !== "_")
+        return null;
+    return { keyId: rest.substring(0, KEY_ID_LENGTH), secretPart: rest.substring(KEY_ID_LENGTH + 1) };
+}

package/lib/admin/AuditRoutes.d.ts

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

package/lib/admin/AuditRoutes.js

@@ -0,0 +1,106 @@
+// The audit and activity routes of the admin API (game-server-admin-console DR §6.11 audit/* and activity rows, D19).
+// There is deliberately no route that edits or deletes an audit record.
+import { AdminRequestError } from "./AdminApiRouter.js";
+import { bodyObject, numberField } from "./AdminRequestBodies.js";
+/** HTTP status of a successful answer. */
+const HTTP_OK = 200;
+/** HTTP status of an invalid request. */
+const HTTP_BAD_REQUEST = 400;
+/** Activity items answered when the query names no limit. */
+const DEFAULT_ACTIVITY_LIMIT = 20;
+/** Most activity items one call answers. */
+const MAXIMUM_ACTIVITY_LIMIT = 200;
+/** Content types of the export formats. */
+const EXPORT_CONTENT_TYPES = { csv: "text/csv; charset=utf-8", jsonl: "application/jsonl; charset=utf-8" };
+/**
+ * Registers every audit/* route and activity.
+ * @param router The admin API router.
+ * @param services The shared services.
+ */
+export function registerAuditRoutes(router, services) {
+    const routes = [
+        { method: "GET", pattern: "audit", permission: "audit.view", requiresStepUp: false, auditAction: null, handler: async (request) => ok(await services.audit.query(auditQueryOf(request.query), pageOf(request.query))) },
+        { method: "GET", pattern: "audit/export", permission: "audit.view", requiresStepUp: false, auditAction: "audit.export", handler: async (request) => exportAudit(services, request) },
+        { method: "GET", pattern: "audit/verify", permission: "audit.view", requiresStepUp: false, auditAction: null, handler: async () => ok(await services.audit.verifyChain()) },
+        { method: "PUT", pattern: "audit/retention", permission: "audit.retention", requiresStepUp: true, auditAction: "audit.retention", handler: async (request) => setRetention(services, request) },
+        { method: "GET", pattern: "activity", permission: "fleet.view", requiresStepUp: false, auditAction: null, handler: async (request) => ok(await services.audit.activity(activityLimitOf(request.query))) }
+    ];
+    for (const route of routes)
+        router.register(route);
+}
+/**
+ * A 200 answer.
+ * @param body The JSON body.
+ * @returns The result.
+ */
+function ok(body) {
+    return { status: HTTP_OK, body: body };
+}
+/**
+ * GET audit/export: a CSV or JSON-lines download of the matching records.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The download.
+ * @throws AdminRequestError 400 for an unknown format.
+ */
+async function exportAudit(services, request) {
+    const format = request.query.get("format") ?? "csv";
+    if (format !== "csv" && format !== "jsonl")
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "format must be csv or jsonl");
+    const bytes = await services.audit.export(format, auditQueryOf(request.query));
+    return { status: HTTP_OK, body: null, download: { bytes: bytes, contentType: EXPORT_CONTENT_TYPES[format], fileName: "audit." + format }, audit: { target: "audit." + format, parameters: { format: format } } };
+}
+/**
+ * PUT audit/retention.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The stored retention.
+ * @throws AdminRequestError 400 unless days is a whole number of at least 1.
+ */
+async function setRetention(services, request) {
+    const days = numberField(bodyObject(request.body), "days");
+    if (!Number.isInteger(days) || days < 1)
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "days must be a whole number of at least 1");
+    await services.audit.setRetentionDays(days);
+    return { status: HTTP_OK, body: { days: days }, audit: { target: "audit", parameters: { days: days } } };
+}
+/**
+ * The audit filters of a query string.
+ * @param query The query.
+ * @returns The filters given.
+ * @throws AdminRequestError 400 for a result other than ok or failed.
+ */
+function auditQueryOf(query) {
+    const filters = {};
+    const result = query.get("result");
+    if (result != null && result !== "ok" && result !== "failed")
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "result must be ok or failed");
+    if (result != null)
+        filters.result = result;
+    for (const name of ["actor", "action", "target", "from", "to"]) {
+        const value = query.get(name);
+        if (value != null && value !== "")
+            filters[name] = value;
+    }
+    return filters;
+}
+/**
+ * The page of a query string.
+ * @param query The query.
+ * @returns The page, from 1.
+ */
+function pageOf(query) {
+    const page = Number(query.get("page") ?? 1);
+    return (Number.isInteger(page) && page >= 1) ? page : 1;
+}
+/**
+ * The activity limit of a query string.
+ * @param query The query.
+ * @returns 1 to MAXIMUM_ACTIVITY_LIMIT.
+ */
+function activityLimitOf(query) {
+    const limit = Number(query.get("limit") ?? DEFAULT_ACTIVITY_LIMIT);
+    if (!Number.isInteger(limit) || limit < 1)
+        return DEFAULT_ACTIVITY_LIMIT;
+    return Math.min(limit, MAXIMUM_ACTIVITY_LIMIT);
+}

package/lib/admin/AuthToolRoutes.d.ts

@@ -0,0 +1,13 @@
+import { type AdminApiRouter } from "./AdminApiRouter.js";
+import type { AdminServices } from "./AdminServices.js";
+/**
+ * Registers the auth-tools/* routes.
+ * @param router The admin API router.
+ * @param services The shared services.
+ */
+export declare function registerAuthToolRoutes(router: AdminApiRouter, services: AdminServices): void;
+/**
+ * Registers this instance's reloadAuthKeys fleet command (R15).
+ * @param services The shared services.
+ */
+export declare function registerAuthToolCommands(services: AdminServices): void;