@babylonjs-toolkit/server 0.0.0-stage → 9.35.1

package/lib/admin/AdminCrypto.js

@@ -0,0 +1,29 @@
+// Small crypto helpers the admin services share: random tokens, SHA-256 ids and constant-time comparison.
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+/**
+ * A random token, URL-safe.
+ * @param byteCount Random bytes in the token.
+ * @returns base64url text.
+ */
+export function randomToken(byteCount) {
+    return randomBytes(byteCount).toString("base64url");
+}
+/**
+ * The SHA-256 of a text, as stored ids of secrets (session cookies, pending tokens, key secrets).
+ * @param text The text.
+ * @returns Lower-case hex.
+ */
+export function sha256Hex(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+/**
+ * Compares two texts in constant time when their lengths are equal.
+ * @param left One text.
+ * @param right The other.
+ * @returns True when equal.
+ */
+export function textsMatch(left, right) {
+    const leftBytes = Buffer.from(left);
+    const rightBytes = Buffer.from(right);
+    return leftBytes.length === rightBytes.length && timingSafeEqual(leftBytes, rightBytes);
+}

package/lib/admin/AdminExtensionsHost.d.ts

@@ -0,0 +1,176 @@
+import type { AdminCaller } from "./AdminApiRouter.js";
+import type { AdminActionField, AdminActionResult, AdminActionTarget, AdminActionTargetIds, AdminAlertSeverity, AdminPanelContent, AdminPanelPlacement, AdminPanelView, AdminPermission, BanKind, ExtensionsView } from "./AdminApiTypes.js";
+/** What a custom action handler receives. */
+export interface AdminActionContext {
+    /** The typed inputs: each field's value, or its default. */
+    inputs: Record<string, string | number | boolean>;
+    /** The target ids: instance processId, session roomId, or { roomId, playerId, userId }. */
+    target: AdminActionTargetIds;
+    /** Who runs the action. */
+    caller: {
+        kind: AdminCaller["kind"];
+        id: string;
+        name: string;
+    };
+}
+/** A custom admin action registered from code (D25). */
+export interface AdminActionDefinition {
+    /** Unique, /^[a-z][a-zA-Z0-9-]{2,40}$/. */
+    name: string;
+    label: string;
+    description: string;
+    target: AdminActionTarget;
+    fields: AdminActionField[];
+    /** "operators": everyone with extensions.run (default); "developer": extensions.runDeveloper. */
+    audience?: "operators" | "developer";
+    /** Asks for confirmation before running. Default true. */
+    confirm?: boolean;
+    /**
+     * Runs the action.
+     * @param context The inputs, target and caller.
+     * @returns The outcome shown in the console.
+     */
+    handler(context: AdminActionContext): Promise<AdminActionResult>;
+}
+/** A read-only custom panel registered from code. */
+export interface AdminPanelDefinition {
+    /** Unique, /^[a-z][a-zA-Z0-9-]{2,40}$/. */
+    name: string;
+    title: string;
+    placement: AdminPanelPlacement;
+    /**
+     * Returns a table or key/value data for the panel.
+     * @param context The target ids of the page that shows it.
+     * @returns The content.
+     */
+    handler(context: {
+        target: AdminActionTargetIds;
+    }): Promise<AdminPanelContent>;
+}
+/** Admin events a developer can mirror (spec 13). Hooks are called after the action succeeded; a throw is logged. */
+export interface AdminEventHooks {
+    onPlayerKicked?(event: {
+        roomId: string;
+        playerId: number;
+        userId: string | null;
+        message: string;
+        by: string;
+    }): void;
+    onBanCreated?(event: {
+        banId: string;
+        kind: BanKind;
+        value: string;
+        expiresAt: string | null;
+        by: string;
+    }): void;
+    onBanRemoved?(event: {
+        banId: string;
+        by: string;
+    }): void;
+    onMaintenanceChanged?(event: {
+        enabled: boolean;
+        scope: "fleet" | string;
+        message: string | null;
+        by: string;
+    }): void;
+    onAlertFired?(event: {
+        alertId: string;
+        ruleId: string;
+        severity: AdminAlertSeverity;
+        summary: string;
+    }): void;
+}
+/** GameServerOptions.admin (D25). */
+export interface AdminExtensions {
+    actions?: AdminActionDefinition[];
+    panels?: AdminPanelDefinition[];
+    hooks?: AdminEventHooks;
+}
+/** The event a hook receives. */
+export type AdminHookEvent<Name extends keyof AdminEventHooks> = Parameters<NonNullable<AdminEventHooks[Name]>>[0];
+/** Checks, lists and runs the extensions of one server. */
+export declare class AdminExtensionsHost {
+    /** Actions by name. */
+    private readonly actions;
+    /** Panels by name. */
+    private readonly panels;
+    /** The event hooks. */
+    private readonly hooks;
+    /**
+     * Checks the definitions and keeps them.
+     * @param extensions GameServerOptions.admin (empty when none).
+     * @throws Error "admin extension <name>: <problem>" for a duplicate or badly named action or panel, a bad target,
+     *     duplicate or badly typed fields, or a select without options.
+     */
+    constructor(extensions: AdminExtensions);
+    /**
+     * The permission an action needs: extensions.runDeveloper for the developer audience, else extensions.run.
+     * @param actionName The action (an unknown one needs extensions.run, then answers 404).
+     * @returns The permission.
+     */
+    permissionFor(actionName: string): AdminPermission;
+    /**
+     * The actions a caller may run and every panel (GET extensions).
+     * @param caller The caller.
+     * @returns The actions and panels.
+     */
+    listFor(caller: AdminCaller): ExtensionsView;
+    /**
+     * The panels shown at a placement, or every panel.
+     * @param placement The placement, or null for all.
+     * @returns The panels.
+     */
+    panelViews(placement: AdminPanelPlacement | null): AdminPanelView[];
+    /**
+     * Runs an action after checking its target and inputs; the router has already checked its permission.
+     * @param actionName The action.
+     * @param target The target ids.
+     * @param inputs The raw inputs.
+     * @param caller The caller.
+     * @returns The handler's outcome.
+     * @throws AdminRequestError 404 for an unknown action, 400 for a missing target id or a missing or mistyped input,
+     *     500 when the handler throws.
+     */
+    run(actionName: string, target: AdminActionTargetIds, inputs: Record<string, unknown>, caller: AdminCaller): Promise<AdminActionResult>;
+    /**
+     * The audit parameters of an action call: the inputs without its secret fields (D25).
+     * @param actionName The action.
+     * @param inputs The raw inputs.
+     * @returns The inputs that may be audited.
+     */
+    auditParametersOf(actionName: string, inputs: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * A panel's content.
+     * @param panelName The panel.
+     * @param target The target ids of the page.
+     * @returns The content.
+     * @throws AdminRequestError 404 for an unknown panel, 500 when the handler throws.
+     */
+    panel(panelName: string, target: AdminActionTargetIds): Promise<AdminPanelContent>;
+    /**
+     * Calls an admin event hook. A throw is logged as "admin hook <name> threw" and a returned promise's rejection is
+     * caught and logged, never awaited (matching SessionRoom.callHook's policy).
+     * @param name The hook.
+     * @param event Its event.
+     */
+    callHook<Name extends keyof AdminEventHooks>(name: Name, event: AdminHookEvent<Name>): void;
+    /**
+     * Checks and adds an action.
+     * @param action The definition.
+     * @throws Error naming the problem.
+     */
+    private addAction;
+    /**
+     * Checks and adds a panel.
+     * @param panel The definition.
+     * @throws Error naming the problem.
+     */
+    private addPanel;
+    /**
+     * A registered action.
+     * @param actionName The action.
+     * @returns The definition.
+     * @throws AdminRequestError 404 when there is none.
+     */
+    private requireAction;
+}

package/lib/admin/AdminExtensionsHost.js

@@ -0,0 +1,307 @@
+// Developer extensions of the admin console (game-server-admin-console D25, DR §6.10): custom actions, read-only panels
+// and admin event hooks registered from code through GameServerOptions.admin. Definitions are checked when the server is
+// created; actions run only with their built-in permission, with typed inputs, and are audited without secret fields.
+import { getLogger } from "../GameServerLogger.js";
+import { AdminRequestError } from "./AdminApiRouter.js";
+import { hasPermission } from "./AdminPermissions.js";
+/** HTTP statuses of the host's refusals. */
+const HTTP_BAD_REQUEST = 400;
+const HTTP_NOT_FOUND = 404;
+const HTTP_INTERNAL_ERROR = 500;
+/** The name rule of actions and panels (DR §6.10). */
+const EXTENSION_NAME_PATTERN = /^[a-z][a-zA-Z0-9-]{2,40}$/;
+/** Action targets. */
+const ACTION_TARGETS = new Set(["server", "instance", "session", "player"]);
+/** Field types. */
+const FIELD_TYPES = new Set(["text", "number", "boolean", "select", "secret"]);
+/** Panel placements. */
+const PANEL_PLACEMENTS = new Set(["overview", "session", "player"]);
+/** The permission of operator actions and of developer actions (D25). */
+const OPERATOR_ACTION_PERMISSION = "extensions.run";
+const DEVELOPER_ACTION_PERMISSION = "extensions.runDeveloper";
+/** Checks, lists and runs the extensions of one server. */
+export class AdminExtensionsHost {
+    /** Actions by name. */
+    actions = new Map();
+    /** Panels by name. */
+    panels = new Map();
+    /** The event hooks. */
+    hooks;
+    /**
+     * Checks the definitions and keeps them.
+     * @param extensions GameServerOptions.admin (empty when none).
+     * @throws Error "admin extension <name>: <problem>" for a duplicate or badly named action or panel, a bad target,
+     *     duplicate or badly typed fields, or a select without options.
+     */
+    constructor(extensions) {
+        for (const action of extensions.actions ?? [])
+            this.addAction(action);
+        for (const panel of extensions.panels ?? [])
+            this.addPanel(panel);
+        this.hooks = extensions.hooks ?? {};
+    }
+    /**
+     * The permission an action needs: extensions.runDeveloper for the developer audience, else extensions.run.
+     * @param actionName The action (an unknown one needs extensions.run, then answers 404).
+     * @returns The permission.
+     */
+    permissionFor(actionName) {
+        return (this.actions.get(actionName)?.audience === "developer") ? DEVELOPER_ACTION_PERMISSION : OPERATOR_ACTION_PERMISSION;
+    }
+    /**
+     * The actions a caller may run and every panel (GET extensions).
+     * @param caller The caller.
+     * @returns The actions and panels.
+     */
+    listFor(caller) {
+        const actions = Array.from(this.actions.values())
+            .filter((action) => hasPermission(caller.permissions, this.permissionFor(action.name)))
+            .map(actionView);
+        return { actions: actions, panels: this.panelViews(null) };
+    }
+    /**
+     * The panels shown at a placement, or every panel.
+     * @param placement The placement, or null for all.
+     * @returns The panels.
+     */
+    panelViews(placement) {
+        return Array.from(this.panels.values())
+            .filter((panel) => placement == null || panel.placement === placement)
+            .map((panel) => ({ name: panel.name, title: panel.title, placement: panel.placement }));
+    }
+    /**
+     * Runs an action after checking its target and inputs; the router has already checked its permission.
+     * @param actionName The action.
+     * @param target The target ids.
+     * @param inputs The raw inputs.
+     * @param caller The caller.
+     * @returns The handler's outcome.
+     * @throws AdminRequestError 404 for an unknown action, 400 for a missing target id or a missing or mistyped input,
+     *     500 when the handler throws.
+     */
+    async run(actionName, target, inputs, caller) {
+        const action = this.requireAction(actionName);
+        requireTargetIds(action.target, target);
+        const typedInputs = typedInputsOf(action, inputs);
+        try {
+            return await action.handler({ inputs: typedInputs, target: target, caller: { kind: caller.kind, id: caller.id, name: caller.name } });
+        }
+        catch (error) {
+            getLogger().error("admin action " + actionName + " threw", { error: String(error) });
+            throw new AdminRequestError(HTTP_INTERNAL_ERROR, "the action " + actionName + " failed: " + ((error instanceof Error) ? error.message : String(error)));
+        }
+    }
+    /**
+     * The audit parameters of an action call: the inputs without its secret fields (D25).
+     * @param actionName The action.
+     * @param inputs The raw inputs.
+     * @returns The inputs that may be audited.
+     */
+    auditParametersOf(actionName, inputs) {
+        const action = this.actions.get(actionName);
+        if (action == null)
+            return {};
+        const parameters = {};
+        for (const field of action.fields) {
+            if (field.type !== "secret" && Object.hasOwn(inputs, field.name))
+                parameters[field.name] = inputs[field.name];
+        }
+        return parameters;
+    }
+    /**
+     * A panel's content.
+     * @param panelName The panel.
+     * @param target The target ids of the page.
+     * @returns The content.
+     * @throws AdminRequestError 404 for an unknown panel, 500 when the handler throws.
+     */
+    async panel(panelName, target) {
+        const panel = this.panels.get(panelName);
+        if (panel == null)
+            throw new AdminRequestError(HTTP_NOT_FOUND, "no such panel");
+        try {
+            return await panel.handler({ target: target });
+        }
+        catch (error) {
+            getLogger().error("admin panel " + panelName + " threw", { error: String(error) });
+            throw new AdminRequestError(HTTP_INTERNAL_ERROR, "the panel " + panelName + " failed: " + ((error instanceof Error) ? error.message : String(error)));
+        }
+    }
+    /**
+     * Calls an admin event hook. A throw is logged as "admin hook <name> threw" and a returned promise's rejection is
+     * caught and logged, never awaited (matching SessionRoom.callHook's policy).
+     * @param name The hook.
+     * @param event Its event.
+     */
+    callHook(name, event) {
+        const hook = this.hooks[name];
+        if (hook == null)
+            return;
+        const logThrow = (error) => getLogger().error("admin hook " + name + " threw", { error: String(error) });
+        try {
+            const returned = hook.call(this.hooks, event);
+            if (returned instanceof Promise)
+                returned.catch(logThrow);
+        }
+        catch (error) {
+            logThrow(error);
+        }
+    }
+    /**
+     * Checks and adds an action.
+     * @param action The definition.
+     * @throws Error naming the problem.
+     */
+    addAction(action) {
+        const problem = actionProblemOf(action, this.actions.has(action.name));
+        if (problem != null)
+            throw new Error("admin extension " + action.name + ": " + problem);
+        this.actions.set(action.name, action);
+    }
+    /**
+     * Checks and adds a panel.
+     * @param panel The definition.
+     * @throws Error naming the problem.
+     */
+    addPanel(panel) {
+        const problem = panelProblemOf(panel, this.panels.has(panel.name));
+        if (problem != null)
+            throw new Error("admin extension " + panel.name + ": " + problem);
+        this.panels.set(panel.name, panel);
+    }
+    /**
+     * A registered action.
+     * @param actionName The action.
+     * @returns The definition.
+     * @throws AdminRequestError 404 when there is none.
+     */
+    requireAction(actionName) {
+        const action = this.actions.get(actionName);
+        if (action == null)
+            throw new AdminRequestError(HTTP_NOT_FOUND, "no such action");
+        return action;
+    }
+}
+/**
+ * An action as the console sees it.
+ * @param action The definition.
+ * @returns The view.
+ */
+function actionView(action) {
+    return {
+        name: action.name,
+        label: action.label,
+        description: action.description,
+        target: action.target,
+        fields: action.fields.map((field) => Object.assign({}, field)),
+        confirm: action.confirm !== false
+    };
+}
+/**
+ * What is wrong with an action definition.
+ * @param action The definition.
+ * @param isDuplicate True when the name is already registered.
+ * @returns The problem, or null.
+ */
+function actionProblemOf(action, isDuplicate) {
+    if (isDuplicate)
+        return "an action with this name is already registered";
+    if (!EXTENSION_NAME_PATTERN.test(action.name))
+        return "the name must match " + EXTENSION_NAME_PATTERN.source;
+    if (!ACTION_TARGETS.has(action.target))
+        return "target must be server, instance, session or player";
+    if (typeof action.handler !== "function")
+        return "handler must be a function";
+    const fieldNames = new Set();
+    for (const field of action.fields) {
+        if (fieldNames.has(field.name))
+            return "the field " + field.name + " is defined twice";
+        fieldNames.add(field.name);
+        if (!FIELD_TYPES.has(field.type))
+            return "the field " + field.name + " has an unknown type " + field.type;
+        if (field.type === "select" && (field.options == null || field.options.length === 0))
+            return "the select field " + field.name + " needs options";
+    }
+    return null;
+}
+/**
+ * What is wrong with a panel definition.
+ * @param panel The definition.
+ * @param isDuplicate True when the name is already registered.
+ * @returns The problem, or null.
+ */
+function panelProblemOf(panel, isDuplicate) {
+    if (isDuplicate)
+        return "a panel with this name is already registered";
+    if (!EXTENSION_NAME_PATTERN.test(panel.name))
+        return "the name must match " + EXTENSION_NAME_PATTERN.source;
+    if (!PANEL_PLACEMENTS.has(panel.placement))
+        return "placement must be overview, session or player";
+    if (typeof panel.handler !== "function")
+        return "handler must be a function";
+    return null;
+}
+/**
+ * Checks that a target names what the action's target kind needs.
+ * @param kind The action's target kind.
+ * @param target The target ids.
+ * @throws AdminRequestError 400 for a missing id.
+ */
+function requireTargetIds(kind, target) {
+    const needsRoom = kind === "session" || kind === "player";
+    if (kind === "instance" && typeof target.processId !== "string")
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "target.processId is required");
+    if (needsRoom && typeof target.roomId !== "string")
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "target.roomId is required");
+    if (kind === "player" && typeof target.playerId !== "number")
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "target.playerId is required");
+}
+/**
+ * The typed inputs of an action call: each field's value (or default), checked against its type. Inputs no field names
+ * are dropped.
+ * @param action The action.
+ * @param inputs The raw inputs.
+ * @returns The typed inputs.
+ * @throws AdminRequestError 400 for a missing required field or a value of the wrong type.
+ */
+function typedInputsOf(action, inputs) {
+    const typed = {};
+    for (const field of action.fields) {
+        const value = inputs[field.name] ?? field.defaultValue;
+        if (value == null || value === "") {
+            if (field.required)
+                throw new AdminRequestError(HTTP_BAD_REQUEST, field.label + " is required", field.name);
+            continue;
+        }
+        typed[field.name] = typedValueOf(field, value);
+    }
+    return typed;
+}
+/**
+ * One input checked against its field's type.
+ * @param field The field.
+ * @param value The raw value.
+ * @returns The typed value.
+ * @throws AdminRequestError 400 when the value does not fit the type.
+ */
+function typedValueOf(field, value) {
+    const wrongType = (expected) => new AdminRequestError(HTTP_BAD_REQUEST, field.label + " must be " + expected, field.name);
+    switch (field.type) {
+        case "number":
+            if (typeof value !== "number" || !Number.isFinite(value))
+                throw wrongType("a number");
+            return value;
+        case "boolean":
+            if (typeof value !== "boolean")
+                throw wrongType("true or false");
+            return value;
+        case "select":
+            if (typeof value !== "string" || !(field.options ?? []).includes(value))
+                throw wrongType("one of " + (field.options ?? []).join(", "));
+            return value;
+        default:
+            if (typeof value !== "string")
+                throw wrongType("text");
+            return value;
+    }
+}

package/lib/admin/AdminPasswords.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Hashes a password: `scrypt$16384$8$1$<salt base64>$<hash base64>` (D8).
+ * @param password The password.
+ * @returns The stored hash.
+ */
+export declare function hashPassword(password: string): Promise<string>;
+/**
+ * Checks a password against a stored hash, in constant time for keys of equal length.
+ * @param password The password given.
+ * @param storedHash The stored hash.
+ * @returns True when it matches; false for a malformed hash.
+ */
+export declare function verifyPassword(password: string, storedHash: string): Promise<boolean>;
+/**
+ * A hash of an unknowable random password, with the same scrypt parameters as real hashes. A sign-in for an unknown,
+ * disabled or password-less account checks against it, so every refused sign-in costs one scrypt and the answer time
+ * does not reveal whether the username exists. Made once, on first use.
+ * @returns The hash.
+ */
+export declare function timingEqualizerPasswordHash(): Promise<string>;
+/**
+ * How many password checks ran scrypt in this process, so tests can prove a refused sign-in paid for one without
+ * measuring time.
+ * @returns The count since the process started.
+ */
+export declare function passwordVerificationCount(): number;
+/**
+ * The first rule a new password breaks (D8), as a sentence for the admin.
+ * @param password The new password.
+ * @param username The account's username.
+ * @returns The problem, or null when the password is acceptable.
+ */
+export declare function passwordProblem(password: string, username: string): string | null;

package/lib/admin/AdminPasswords.js

@@ -0,0 +1,92 @@
+// Admin password hashing and rules (game-server-admin-console D8, DR §8): Node's scrypt, constant-time checks.
+import { randomBytes, scrypt, timingSafeEqual } from "node:crypto";
+import { MINIMUM_PASSWORD_LENGTH, SCRYPT_BLOCK_SIZE, SCRYPT_COST, SCRYPT_KEY_BYTES, SCRYPT_PARALLELISM, SCRYPT_SALT_BYTES } from "./AdminConstants.js";
+import { COMMON_PASSWORDS } from "./CommonPasswords.js";
+/** First field of a stored hash. */
+const HASH_SCHEME = "scrypt";
+/** Separator of the stored hash fields. */
+const HASH_SEPARATOR = "$";
+/** Fields of a stored hash: scheme, N, r, p, salt, key. */
+const HASH_FIELD_COUNT = 6;
+/** Memory scrypt may use, in bytes (N = 16384, r = 8 needs 16 MiB). */
+const SCRYPT_MAX_MEMORY_BYTES = 64 * 1024 * 1024;
+/** Random bytes of the password behind the timing-equalizer hash (nobody knows it, so it never matches). */
+const TIMING_EQUALIZER_PASSWORD_BYTES = 32;
+/** The timing-equalizer hash, made once on first use. */
+let timingEqualizerHash = null;
+/** How many password checks ran scrypt in this process. */
+let passwordVerificationTotal = 0;
+/**
+ * Runs scrypt as a promise.
+ * @param password The password.
+ * @param salt The salt.
+ * @param keyLength The key length in bytes.
+ * @param options The cost parameters.
+ * @returns The derived key.
+ */
+function deriveKey(password, salt, keyLength, options) {
+    return new Promise((resolve, reject) => {
+        scrypt(password.normalize("NFKC"), salt, keyLength, options, (error, key) => (error != null) ? reject(error) : resolve(key));
+    });
+}
+/**
+ * Hashes a password: `scrypt$16384$8$1$<salt base64>$<hash base64>` (D8).
+ * @param password The password.
+ * @returns The stored hash.
+ */
+export async function hashPassword(password) {
+    const salt = randomBytes(SCRYPT_SALT_BYTES);
+    const key = await deriveKey(password, salt, SCRYPT_KEY_BYTES, { N: SCRYPT_COST, r: SCRYPT_BLOCK_SIZE, p: SCRYPT_PARALLELISM, maxmem: SCRYPT_MAX_MEMORY_BYTES });
+    return [HASH_SCHEME, SCRYPT_COST, SCRYPT_BLOCK_SIZE, SCRYPT_PARALLELISM, salt.toString("base64"), key.toString("base64")].join(HASH_SEPARATOR);
+}
+/**
+ * Checks a password against a stored hash, in constant time for keys of equal length.
+ * @param password The password given.
+ * @param storedHash The stored hash.
+ * @returns True when it matches; false for a malformed hash.
+ */
+export async function verifyPassword(password, storedHash) {
+    const fields = storedHash.split(HASH_SEPARATOR);
+    if (fields.length !== HASH_FIELD_COUNT || fields[0] !== HASH_SCHEME)
+        return false;
+    const [, costText, blockSizeText, parallelismText, saltText, keyText] = fields;
+    const expectedKey = Buffer.from(keyText, "base64");
+    const options = { N: Number(costText), r: Number(blockSizeText), p: Number(parallelismText), maxmem: SCRYPT_MAX_MEMORY_BYTES };
+    passwordVerificationTotal++;
+    const actualKey = await deriveKey(password, Buffer.from(saltText, "base64"), expectedKey.length, options);
+    return actualKey.length === expectedKey.length && timingSafeEqual(actualKey, expectedKey);
+}
+/**
+ * A hash of an unknowable random password, with the same scrypt parameters as real hashes. A sign-in for an unknown,
+ * disabled or password-less account checks against it, so every refused sign-in costs one scrypt and the answer time
+ * does not reveal whether the username exists. Made once, on first use.
+ * @returns The hash.
+ */
+export function timingEqualizerPasswordHash() {
+    timingEqualizerHash ??= hashPassword(randomBytes(TIMING_EQUALIZER_PASSWORD_BYTES).toString("base64"));
+    return timingEqualizerHash;
+}
+/**
+ * How many password checks ran scrypt in this process, so tests can prove a refused sign-in paid for one without
+ * measuring time.
+ * @returns The count since the process started.
+ */
+export function passwordVerificationCount() {
+    return passwordVerificationTotal;
+}
+/**
+ * The first rule a new password breaks (D8), as a sentence for the admin.
+ * @param password The new password.
+ * @param username The account's username.
+ * @returns The problem, or null when the password is acceptable.
+ */
+export function passwordProblem(password, username) {
+    if (password.length < MINIMUM_PASSWORD_LENGTH)
+        return "use at least " + MINIMUM_PASSWORD_LENGTH + " characters";
+    const lowerCase = password.toLowerCase();
+    if (COMMON_PASSWORDS.has(lowerCase))
+        return "this password is too common";
+    if (username !== "" && lowerCase.includes(username.toLowerCase()))
+        return "the password must not contain your username";
+    return null;
+}

package/lib/admin/AdminPermissions.d.ts

@@ -0,0 +1,28 @@
+import type { AdminPermission, AdminRole } from "./AdminApiTypes.js";
+/** Every action the console and API can check (D17), in the order of the AdminPermission union. */
+export declare const ADMIN_PERMISSIONS: readonly AdminPermission[];
+/** The fixed roles (D17), highest first. */
+export declare const ADMIN_ROLES: readonly AdminRole[];
+/** What each role may do (spec 1 role table, R24). */
+export declare const ROLE_PERMISSIONS: Record<AdminRole, ReadonlySet<AdminPermission>>;
+/** What the configured admin.token may do as an API key: everything except users.manage and audit.retention (D18). */
+export declare const LEGACY_TOKEN_PERMISSIONS: ReadonlySet<AdminPermission>;
+/**
+ * True when a role or key with these permissions may perform the action.
+ * @param granted The permissions the caller holds.
+ * @param required The permission the route needs.
+ * @returns Whether it is allowed.
+ */
+export declare function hasPermission(granted: ReadonlySet<AdminPermission>, required: AdminPermission): boolean;
+/**
+ * Whether a text names a permission (API key requests and the CLI pass names as text).
+ * @param name The text.
+ * @returns True for one of ADMIN_PERMISSIONS.
+ */
+export declare function isAdminPermission(name: string): name is AdminPermission;
+/**
+ * Whether a text names a role.
+ * @param name The text.
+ * @returns True for one of ADMIN_ROLES.
+ */
+export declare function isAdminRole(name: string): name is AdminRole;