@babylonjs-toolkit/server 0.0.0-stage → 9.35.0

package/lib/admin/AdminApiRouter.d.ts

@@ -0,0 +1,202 @@
+import type { AdminCallerKind, AdminPermission } from "./AdminApiTypes.js";
+import type { AdminUserRecord, ConsoleSessionRecord } from "./AdminRecords.js";
+import { AdminRequestGate } from "./AdminRequestGate.js";
+import { type AdminResult } from "./AdminResponses.js";
+import type { AdminServices } from "./AdminServices.js";
+export type { AdminResult } from "./AdminResponses.js";
+/** What the router endpoint passes the handler (the better-call context, narrowed). */
+export interface RouterEndpointContext {
+    /** The Fetch request (the router always sets it; better-call types it optional for direct calls). */
+    request?: Request;
+    /** The router's path parameters. */
+    params?: Record<string, unknown>;
+}
+/** Who is calling (after authentication). */
+export interface AdminCaller {
+    kind: AdminCallerKind;
+    /** userId, keyId, "legacy", "cli" or "system". */
+    id: string;
+    /** Display name, key name, "legacy admin token", "CLI" or "system". */
+    name: string;
+    /** What the caller may do. */
+    permissions: ReadonlySet<AdminPermission>;
+    /** The console session, for cookie callers. */
+    session: ConsoleSessionRecord | null;
+    /** The account, for cookie callers. */
+    user: AdminUserRecord | null;
+}
+/** One API request after parsing. */
+export interface AdminRequest {
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    /** The path after ADMIN_API_PREFIX, without query, e.g. "sessions/abc/close". */
+    apiPath: string;
+    /** The named parts of the matched pattern, e.g. { roomId: "abc" }. */
+    params: Record<string, string>;
+    query: URLSearchParams;
+    headers: Headers;
+    /** The parsed JSON body of a POST or PUT, or null. */
+    body: unknown;
+    clientAddress: string;
+    /** scheme://host of the console, from the Host header and the D9 scheme rule. */
+    consoleOrigin: string;
+    /** True for TLS, or HTTPS at a trusted proxy (R9). */
+    isSecure: boolean;
+    /** True when the D9 rule accepts this connection. */
+    isTransportSafe: boolean;
+    /** The authenticated caller, or null. */
+    caller: AdminCaller | null;
+}
+/** One route of the table (R8: fields may depend on the request). */
+export interface AdminRouteDefinition {
+    method: AdminRequest["method"];
+    /** Pattern after ADMIN_API_PREFIX with :name parts, e.g. "sessions/:roomId/close". */
+    pattern: string;
+    /** "public" routes need no caller (sign-in, setup, methods); "signedIn" needs any caller. */
+    permission: AdminPermission | "public" | "signedIn" | ((request: AdminRequest) => AdminPermission);
+    /** Requires a second-factor check within STEP_UP_WINDOW_MS (spec 1 dangerous actions). */
+    requiresStepUp: boolean | ((request: AdminRequest) => boolean);
+    /** Audit action name, e.g. "session.close"; null = not audited (reads). */
+    auditAction: string | null | ((request: AdminRequest) => string);
+    /** False for routes API keys may not call (auth/*, account/*). Default true. */
+    allowsApiKeys?: boolean;
+    /**
+     * Runs the route.
+     * @param request The parsed, authorized request.
+     * @returns The result the router turns into a response.
+     */
+    handler(request: AdminRequest): Promise<AdminResult>;
+}
+/** Thrown by handlers for an expected refusal; the router turns it into { error, detail? } with the status. */
+export declare class AdminRequestError extends Error {
+    /** HTTP status. */
+    readonly status: number;
+    /** Extra detail (for example the missing permission name), or null. */
+    readonly detail: string | null;
+    /**
+     * Creates the refusal.
+     * @param status HTTP status.
+     * @param message The error sentence shown to the admin.
+     * @param detail Extra detail, or null.
+     */
+    constructor(status: number, message: string, detail?: string | null);
+}
+/** The admin API dispatcher (D6). */
+export declare class AdminApiRouter {
+    /** The shared services. */
+    private readonly services;
+    /** The network restriction and transport rule. */
+    private readonly gate;
+    /** Whether the API answers at all (D30, R6). */
+    private readonly isApiAvailable;
+    /** Every registered route. */
+    private readonly routes;
+    /**
+     * Creates an empty route table.
+     * @param services The shared services.
+     * @param gate The network restriction and transport rule.
+     * @param isApiAvailable Whether the API answers at all (D30, R6).
+     */
+    constructor(services: AdminServices, gate: AdminRequestGate, isApiAvailable: () => Promise<boolean>);
+    /**
+     * Adds a route.
+     * @param route The route.
+     * @throws Error when the same method and pattern are already registered.
+     */
+    register(route: AdminRouteDefinition): void;
+    /**
+     * Runs one API request through the pipeline (DR §6.3) and builds its single-buffer response (D5).
+     * @param context The router context.
+     * @returns The response.
+     */
+    handle(context: RouterEndpointContext): Promise<Response>;
+    /**
+     * The pipeline up to the response: each step answers or goes on.
+     * @param httpRequest The Fetch request.
+     * @param isSecure True for a secure request (R9).
+     * @param consoleOrigin The console origin.
+     * @returns The result to answer with.
+     */
+    private run;
+    /**
+     * Audits a call of an audited route (DR §6.3 step 11): successes and refusals of a known caller, and every call of
+     * a public route (sign-in attempts). Calls refused before authentication are not audited.
+     * @param route The route.
+     * @param request The request.
+     * @param result The answer.
+     */
+    private audit;
+    /**
+     * Finds the route of a method and path; among several matches the one with the most literal segments wins.
+     * @param method The HTTP method.
+     * @param apiPath The path after ADMIN_API_PREFIX.
+     * @returns The route and its parameters, "wrongMethod" when only other methods match, or "none".
+     */
+    private match;
+    /**
+     * Finds the caller (DR §6.3 step 6): a bearer value (the legacy admin token, a full-access key, D18), else the
+     * session cookie (timeouts applied, D10), else nobody.
+     * @param request The request.
+     * @returns The caller, or null.
+     */
+    private authenticate;
+    /**
+     * The caller of a bearer value: an API key (`bgsk_`), the legacy admin token, or nobody.
+     * @param bearer The bearer value.
+     * @param request The request.
+     * @returns The caller, or null.
+     */
+    private authenticateBearer;
+    /**
+     * Checks that the caller may run the route (DR §6.3 steps 6–8): a caller for non-public routes, signed-in admins
+     * only where API keys are not allowed, the CSRF token and Origin of cookie callers, then the permission.
+     * @param route The route.
+     * @param request The request with its caller.
+     * @throws AdminRequestError 401 without a caller, 403 for a key on an account route, a CSRF failure or a missing
+     *     permission.
+     */
+    private authorize;
+    /**
+     * The CSRF and Origin rule of cookie callers (D10, DR §6.3 step 7): a state-changing request must send the
+     * session's CSRF token and no Origin, or the console's own.
+     * @param request The request.
+     * @param caller The cookie caller.
+     * @throws AdminRequestError 403 when the token is missing or wrong or the Origin is foreign.
+     */
+    private checkCsrf;
+    /**
+     * The step-up rule of dangerous routes (DR §6.3 step 9): a signed-in admin must have passed a second factor within
+     * STEP_UP_WINDOW_MS; API keys and the legacy token count as stepped up.
+     * @param route The route.
+     * @param request The request with its caller.
+     * @throws AdminRequestError 403 with detail "stepUp" when the check is too old.
+     */
+    private checkStepUp;
+    /**
+     * Turns a thrown error into its answer (DR §6.3 step 10).
+     * @param error What the pipeline or handler threw.
+     * @param route The matched route (for the log).
+     * @returns The error result.
+     */
+    private errorToResult;
+}
+/**
+ * The Fetch request of a router context.
+ * @param context The router context.
+ * @returns The request.
+ * @throws Error when the endpoint was called without one (only a direct, non-router call can do that).
+ */
+export declare function requestOf(context: RouterEndpointContext): Request;
+/**
+ * The bearer token of a request.
+ * @param headers The request headers.
+ * @returns The token, or null when there is no bearer Authorization header.
+ */
+export declare function bearerTokenOf(headers: Headers): string | null;
+/**
+ * An error result: { error, detail? }.
+ * @param status HTTP status.
+ * @param message The error sentence.
+ * @param detail Extra detail, or null.
+ * @returns The result.
+ */
+export declare function errorResult(status: number, message: string, detail?: string | null): AdminResult;

package/lib/admin/AdminApiRouter.js

@@ -0,0 +1,465 @@
+// The admin API dispatcher (game-server-admin-console D6, DR §6.3): one router endpoint hands every
+// /game-server/admin/api/* request here, and every security check runs in this one pipeline.
+import { getLogger } from "../GameServerLogger.js";
+import { hasAdminToken } from "../ServerEndpoints.js";
+import { ADMIN_API_PREFIX, ADMIN_MAX_BODY_BYTES, STEP_UP_WINDOW_MS } from "./AdminConstants.js";
+import { textsMatch } from "./AdminCrypto.js";
+import { ROLE_PERMISSIONS, hasPermission } from "./AdminPermissions.js";
+import { AdminRequestGate } from "./AdminRequestGate.js";
+import { buildAdminResponse, consoleOriginOf, sessionCookieName } from "./AdminResponses.js";
+import { AdminConflictError } from "./AdminStore.js";
+import { API_KEY_PREFIX } from "./ApiKeys.js";
+/** HTTP statuses of the pipeline's own answers. */
+const HTTP_BAD_REQUEST = 400;
+const HTTP_UNAUTHORIZED = 401;
+const HTTP_FORBIDDEN = 403;
+const HTTP_NOT_FOUND = 404;
+const HTTP_METHOD_NOT_ALLOWED = 405;
+const HTTP_CONFLICT = 409;
+const HTTP_PAYLOAD_TOO_LARGE = 413;
+const HTTP_INTERNAL_ERROR = 500;
+/** Scheme word of a bearer Authorization header. */
+const BEARER_PREFIX = "Bearer ";
+/** Methods whose body is read as JSON. */
+const BODY_METHODS = new Set(["POST", "PUT"]);
+/** Methods that change state, so cookie callers must send the CSRF token (D10). */
+const STATE_CHANGING_METHODS = new Set(["POST", "PUT", "DELETE"]);
+/** The header that carries the session's CSRF token (D10). */
+const CSRF_HEADER = "x-admin-csrf";
+/** Methods the API accepts. */
+const API_METHODS = new Set(["GET", "POST", "PUT", "DELETE"]);
+/** Marks a named pattern segment. */
+const PARAMETER_MARKER = ":";
+/** Lowest status that is not a success. */
+const FIRST_FAILURE_STATUS = 400;
+/** The actor of an audited public call without a caller (a sign-in attempt). */
+const ANONYMOUS_ACTOR = { kind: "user", id: "anonymous", name: "anonymous" };
+/** Thrown by handlers for an expected refusal; the router turns it into { error, detail? } with the status. */
+export class AdminRequestError extends Error {
+    /** HTTP status. */
+    status;
+    /** Extra detail (for example the missing permission name), or null. */
+    detail;
+    /**
+     * Creates the refusal.
+     * @param status HTTP status.
+     * @param message The error sentence shown to the admin.
+     * @param detail Extra detail, or null.
+     */
+    constructor(status, message, detail = null) {
+        super(message);
+        this.name = "AdminRequestError";
+        this.status = status;
+        this.detail = detail;
+    }
+}
+/** The admin API dispatcher (D6). */
+export class AdminApiRouter {
+    /** The shared services. */
+    services;
+    /** The network restriction and transport rule. */
+    gate;
+    /** Whether the API answers at all (D30, R6). */
+    isApiAvailable;
+    /** Every registered route. */
+    routes = [];
+    /**
+     * Creates an empty route table.
+     * @param services The shared services.
+     * @param gate The network restriction and transport rule.
+     * @param isApiAvailable Whether the API answers at all (D30, R6).
+     */
+    constructor(services, gate, isApiAvailable) {
+        this.services = services;
+        this.gate = gate;
+        this.isApiAvailable = isApiAvailable;
+    }
+    /**
+     * Adds a route.
+     * @param route The route.
+     * @throws Error when the same method and pattern are already registered.
+     */
+    register(route) {
+        const duplicate = this.routes.some((existing) => existing.definition.method === route.method && existing.definition.pattern === route.pattern);
+        if (duplicate)
+            throw new Error("admin route " + route.method + " " + route.pattern + " is registered twice");
+        const segments = route.pattern.split("/");
+        const literalCount = segments.filter((segment) => !segment.startsWith(PARAMETER_MARKER)).length;
+        this.routes.push({ definition: route, segments: segments, literalCount: literalCount });
+    }
+    /**
+     * Runs one API request through the pipeline (DR §6.3) and builds its single-buffer response (D5).
+     * @param context The router context.
+     * @returns The response.
+     */
+    async handle(context) {
+        const httpRequest = requestOf(context);
+        const headers = httpRequest.headers;
+        const isSecure = this.gate.isSecureRequest(headers);
+        const consoleOrigin = consoleOriginOf(headers, isSecure);
+        const result = await this.run(httpRequest, isSecure, consoleOrigin);
+        return buildAdminResponse(result, { consoleOrigin: consoleOrigin });
+    }
+    /**
+     * The pipeline up to the response: each step answers or goes on.
+     * @param httpRequest The Fetch request.
+     * @param isSecure True for a secure request (R9).
+     * @param consoleOrigin The console origin.
+     * @returns The result to answer with.
+     */
+    async run(httpRequest, isSecure, consoleOrigin) {
+        const headers = httpRequest.headers;
+        const clientAddress = AdminRequestGate.clientAddressOf(headers);
+        if (!this.gate.isNetworkAllowed(clientAddress))
+            return errorResult(HTTP_NOT_FOUND, "not found");
+        if (!(await this.isApiAvailable()))
+            return errorResult(HTTP_NOT_FOUND, "not found");
+        const url = new URL(httpRequest.url);
+        const apiPath = url.pathname.startsWith(ADMIN_API_PREFIX) ? url.pathname.substring(ADMIN_API_PREFIX.length) : "";
+        const method = httpRequest.method.toUpperCase();
+        const match = this.match(method, apiPath);
+        if (match.kind === "none")
+            return errorResult(HTTP_NOT_FOUND, "no such admin route");
+        if (match.kind === "wrongMethod")
+            return errorResult(HTTP_METHOD_NOT_ALLOWED, "this admin route does not take " + method);
+        const isTransportSafe = this.gate.isTransportSafe(headers, clientAddress);
+        if (!isTransportSafe)
+            return errorResult(HTTP_FORBIDDEN, "the console needs HTTPS");
+        let request = null;
+        let result;
+        try {
+            const body = await readJsonBody(httpRequest, method);
+            request = {
+                method: method,
+                apiPath: apiPath,
+                params: match.params,
+                query: url.searchParams,
+                headers: headers,
+                body: body,
+                clientAddress: clientAddress,
+                consoleOrigin: consoleOrigin,
+                isSecure: isSecure,
+                isTransportSafe: isTransportSafe,
+                caller: null
+            };
+            request.caller = await this.authenticate(request);
+            this.authorize(match.route.definition, request);
+            this.checkStepUp(match.route.definition, request);
+            result = await match.route.definition.handler(request);
+        }
+        catch (error) {
+            result = this.errorToResult(error, match.route.definition);
+        }
+        if (request != null)
+            await this.audit(match.route.definition, request, result);
+        return result;
+    }
+    /**
+     * Audits a call of an audited route (DR §6.3 step 11): successes and refusals of a known caller, and every call of
+     * a public route (sign-in attempts). Calls refused before authentication are not audited.
+     * @param route The route.
+     * @param request The request.
+     * @param result The answer.
+     */
+    async audit(route, request, result) {
+        if (route.auditAction == null)
+            return;
+        if (request.caller == null && route.permission !== "public")
+            return;
+        const action = (typeof route.auditAction === "function") ? route.auditAction(request) : route.auditAction;
+        const succeeded = result.status < FIRST_FAILURE_STATUS;
+        const caller = request.caller;
+        const callerActor = (caller != null) ? { kind: caller.kind, id: caller.id, name: caller.name } : ANONYMOUS_ACTOR;
+        const actor = (succeeded ? result.audit?.actor : undefined) ?? callerActor;
+        const paramValues = Object.values(request.params);
+        await this.services.audit.recordSafely({
+            actor: actor,
+            clientAddress: request.clientAddress,
+            processId: this.services.processId(),
+            action: action,
+            target: result.audit?.target ?? paramValues[0] ?? null,
+            parameters: result.audit?.parameters ?? Object.assign({}, request.params),
+            result: { ok: succeeded, detail: succeeded ? null : errorTextOf(result) }
+        });
+    }
+    /**
+     * Finds the route of a method and path; among several matches the one with the most literal segments wins.
+     * @param method The HTTP method.
+     * @param apiPath The path after ADMIN_API_PREFIX.
+     * @returns The route and its parameters, "wrongMethod" when only other methods match, or "none".
+     */
+    match(method, apiPath) {
+        if (!API_METHODS.has(method))
+            return { kind: "wrongMethod" };
+        const pathSegments = apiPath.split("/");
+        let best = null;
+        let pathMatched = false;
+        for (const route of this.routes) {
+            const params = matchSegments(route.segments, pathSegments);
+            if (params == null)
+                continue;
+            pathMatched = true;
+            if (route.definition.method !== method)
+                continue;
+            if (best == null || route.literalCount > best.route.literalCount)
+                best = { route: route, params: params };
+        }
+        if (best != null)
+            return { kind: "found", route: best.route, params: best.params };
+        return pathMatched ? { kind: "wrongMethod" } : { kind: "none" };
+    }
+    /**
+     * Finds the caller (DR §6.3 step 6): a bearer value (the legacy admin token, a full-access key, D18), else the
+     * session cookie (timeouts applied, D10), else nobody.
+     * @param request The request.
+     * @returns The caller, or null.
+     */
+    async authenticate(request) {
+        const bearer = bearerTokenOf(request.headers);
+        if (bearer != null)
+            return this.authenticateBearer(bearer, request);
+        const cookieValue = cookieValueOf(request.headers, sessionCookieName(request.isSecure));
+        if (cookieValue == null || cookieValue === "")
+            return null;
+        const resolved = await this.services.sessions.resolve(cookieValue);
+        if (resolved == null)
+            return null;
+        return { kind: "user", id: resolved.user.userId, name: resolved.user.displayName, permissions: ROLE_PERMISSIONS[resolved.user.role], session: resolved.record, user: resolved.user };
+    }
+    /**
+     * The caller of a bearer value: an API key (`bgsk_`), the legacy admin token, or nobody.
+     * @param bearer The bearer value.
+     * @param request The request.
+     * @returns The caller, or null.
+     */
+    async authenticateBearer(bearer, request) {
+        if (bearer.startsWith(API_KEY_PREFIX))
+            return this.services.apiKeys.verify(bearer, request.clientAddress);
+        const sentToken = { getHeader: (name) => request.headers.get(name) };
+        return hasAdminToken(this.services.state, sentToken) ? this.services.apiKeys.legacyCaller() : null;
+    }
+    /**
+     * Checks that the caller may run the route (DR §6.3 steps 6–8): a caller for non-public routes, signed-in admins
+     * only where API keys are not allowed, the CSRF token and Origin of cookie callers, then the permission.
+     * @param route The route.
+     * @param request The request with its caller.
+     * @throws AdminRequestError 401 without a caller, 403 for a key on an account route, a CSRF failure or a missing
+     *     permission.
+     */
+    authorize(route, request) {
+        if (route.permission === "public")
+            return;
+        const caller = request.caller;
+        if (caller == null)
+            throw new AdminRequestError(HTTP_UNAUTHORIZED, "sign in first");
+        if (route.allowsApiKeys === false && caller.kind !== "user")
+            throw new AdminRequestError(HTTP_FORBIDDEN, "this route needs a signed-in admin, not an API key");
+        if (caller.kind === "user")
+            this.checkCsrf(request, caller);
+        if (route.permission === "signedIn")
+            return;
+        const required = (typeof route.permission === "function") ? route.permission(request) : route.permission;
+        if (!hasPermission(caller.permissions, required))
+            throw new AdminRequestError(HTTP_FORBIDDEN, "you do not have permission for this", required);
+    }
+    /**
+     * The CSRF and Origin rule of cookie callers (D10, DR §6.3 step 7): a state-changing request must send the
+     * session's CSRF token and no Origin, or the console's own.
+     * @param request The request.
+     * @param caller The cookie caller.
+     * @throws AdminRequestError 403 when the token is missing or wrong or the Origin is foreign.
+     */
+    checkCsrf(request, caller) {
+        if (!STATE_CHANGING_METHODS.has(request.method) || caller.session == null)
+            return;
+        const sentToken = request.headers.get(CSRF_HEADER);
+        const origin = request.headers.get("origin");
+        const tokenMatches = sentToken != null && textsMatch(sentToken, caller.session.csrfToken);
+        const originMatches = origin == null || origin === request.consoleOrigin;
+        if (!tokenMatches || !originMatches)
+            throw new AdminRequestError(HTTP_FORBIDDEN, "refused: missing or wrong CSRF token");
+    }
+    /**
+     * The step-up rule of dangerous routes (DR §6.3 step 9): a signed-in admin must have passed a second factor within
+     * STEP_UP_WINDOW_MS; API keys and the legacy token count as stepped up.
+     * @param route The route.
+     * @param request The request with its caller.
+     * @throws AdminRequestError 403 with detail "stepUp" when the check is too old.
+     */
+    checkStepUp(route, request) {
+        const requiresStepUp = (typeof route.requiresStepUp === "function") ? route.requiresStepUp(request) : route.requiresStepUp;
+        const session = request.caller?.session ?? null;
+        if (!requiresStepUp || request.caller?.kind !== "user" || session == null)
+            return;
+        const sinceSecondFactor = this.services.clock.now() - Date.parse(session.secondFactorAt);
+        if (sinceSecondFactor > STEP_UP_WINDOW_MS)
+            throw new AdminRequestError(HTTP_FORBIDDEN, "confirm with your second factor", "stepUp");
+    }
+    /**
+     * Turns a thrown error into its answer (DR §6.3 step 10).
+     * @param error What the pipeline or handler threw.
+     * @param route The matched route (for the log).
+     * @returns The error result.
+     */
+    errorToResult(error, route) {
+        if (error instanceof AdminRequestError)
+            return errorResult(error.status, error.message, error.detail);
+        if (error instanceof AdminConflictError)
+            return { status: HTTP_CONFLICT, body: { error: "changed by someone else", current: error.current } };
+        getLogger().error("admin route failed", { route: route.method + " " + route.pattern, error: String(error) });
+        return errorResult(HTTP_INTERNAL_ERROR, "internal error");
+    }
+}
+/**
+ * The Fetch request of a router context.
+ * @param context The router context.
+ * @returns The request.
+ * @throws Error when the endpoint was called without one (only a direct, non-router call can do that).
+ */
+export function requestOf(context) {
+    if (context.request == null)
+        throw new Error("the admin endpoint was called without a request");
+    return context.request;
+}
+/**
+ * Matches a pattern's segments against a path's.
+ * @param patternSegments The pattern ("sessions", ":roomId", "close").
+ * @param pathSegments The request path's segments.
+ * @returns The named parameters (URI-decoded), or null when the path does not match.
+ */
+function matchSegments(patternSegments, pathSegments) {
+    if (patternSegments.length !== pathSegments.length)
+        return null;
+    const params = {};
+    for (let i = 0; i < patternSegments.length; i++) {
+        const patternSegment = patternSegments[i];
+        const pathSegment = pathSegments[i];
+        if (!patternSegment.startsWith(PARAMETER_MARKER)) {
+            if (patternSegment !== pathSegment)
+                return null;
+            continue;
+        }
+        if (pathSegment === "")
+            return null;
+        const decoded = decodeSegment(pathSegment);
+        if (decoded == null)
+            return null;
+        params[patternSegment.substring(PARAMETER_MARKER.length)] = decoded;
+    }
+    return params;
+}
+/**
+ * URI-decodes a path segment.
+ * @param segment The raw segment.
+ * @returns The decoded text, or null when it is malformed.
+ */
+function decodeSegment(segment) {
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The bearer token of a request.
+ * @param headers The request headers.
+ * @returns The token, or null when there is no bearer Authorization header.
+ */
+export function bearerTokenOf(headers) {
+    const authorization = headers.get("authorization");
+    if (authorization == null || !authorization.startsWith(BEARER_PREFIX))
+        return null;
+    return authorization.substring(BEARER_PREFIX.length).trim();
+}
+/**
+ * The error sentence of a failed result, with its detail.
+ * @param result The result.
+ * @returns "<status> <error> (<detail>)".
+ */
+function errorTextOf(result) {
+    const body = (result.body != null && typeof result.body === "object") ? result.body : {};
+    const detail = (typeof body.detail === "string") ? " (" + body.detail + ")" : "";
+    return result.status + " " + String(body.error ?? "") + detail;
+}
+/**
+ * A cookie's value from a request's Cookie header.
+ * @param headers The request headers.
+ * @param cookieName The cookie name.
+ * @returns The value, or null when the cookie is not sent.
+ */
+function cookieValueOf(headers, cookieName) {
+    const cookieHeader = headers.get("cookie");
+    if (cookieHeader == null)
+        return null;
+    for (const part of cookieHeader.split(";")) {
+        const separatorIndex = part.indexOf("=");
+        if (separatorIndex < 0)
+            continue;
+        if (part.substring(0, separatorIndex).trim() === cookieName)
+            return part.substring(separatorIndex + 1).trim();
+    }
+    return null;
+}
+/**
+ * Reads a POST or PUT body as JSON, at most ADMIN_MAX_BODY_BYTES (DR §6.3 step 5). Other methods have no body.
+ * @param httpRequest The Fetch request.
+ * @param method The HTTP method.
+ * @returns The parsed body, or null when there is none.
+ * @throws AdminRequestError 413 when too large, 400 when not JSON.
+ */
+async function readJsonBody(httpRequest, method) {
+    if (!BODY_METHODS.has(method))
+        return null;
+    const text = await readBodyText(httpRequest, ADMIN_MAX_BODY_BYTES);
+    if (text.trim() === "")
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "the body must be JSON");
+    }
+}
+/**
+ * Reads a request body, stopping as soon as it grows past the cap.
+ * @param httpRequest The Fetch request.
+ * @param maximumBytes The cap.
+ * @returns The body text.
+ * @throws AdminRequestError 413 past the cap.
+ */
+async function readBodyText(httpRequest, maximumBytes) {
+    const tooLarge = new AdminRequestError(HTTP_PAYLOAD_TOO_LARGE, "the body is larger than " + maximumBytes + " bytes");
+    if (Number(httpRequest.headers.get("content-length") ?? 0) > maximumBytes)
+        throw tooLarge;
+    if (httpRequest.body == null)
+        return "";
+    const reader = httpRequest.body.getReader();
+    const chunks = [];
+    let totalBytes = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        totalBytes += value.byteLength;
+        if (totalBytes > maximumBytes) {
+            await reader.cancel();
+            throw tooLarge;
+        }
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+/**
+ * An error result: { error, detail? }.
+ * @param status HTTP status.
+ * @param message The error sentence.
+ * @param detail Extra detail, or null.
+ * @returns The result.
+ */
+export function errorResult(status, message, detail = null) {
+    const body = { error: message };
+    if (detail != null)
+        body.detail = detail;
+    return { status: status, body: body };
+}