@babylonjs-toolkit/server 0.0.0-stage → 9.35.0

package/lib/admin/AdminApiTypes.js

@@ -0,0 +1,4 @@
+// The admin API contract (game-server-admin-console DR §6.11): every request and response body of
+// /game-server/admin/api/*. This file has no imports (DR §13 R1), so the console app type-checks against it without
+// server, Colyseus or Node types. Times are ISO 8601 strings and ids are strings unless a field says otherwise.
+export {};

package/lib/admin/AdminAudit.d.ts

@@ -0,0 +1,113 @@
+import type { ActivityItemView, AuditRecordView, AuditVerifyView } from "./AdminApiTypes.js";
+import type { AdminClock } from "./AdminClock.js";
+import type { AdminStore } from "./AdminStore.js";
+/** What a caller passes to record(): the record without its sequence, time and hashes. */
+export type AuditEntry = Omit<AuditRecordView, "sequence" | "at" | "previousHash" | "hash">;
+/** Audit filters (R32). */
+export interface AuditQuery {
+    /** Actor name or id contains this (any case). */
+    actor?: string;
+    /** Action starts with this. */
+    action?: string;
+    /** Target contains this (any case). */
+    target?: string;
+    /** Only successes or only failures. */
+    result?: "ok" | "failed";
+    /** Records at or after this ISO time. */
+    from?: string;
+    /** Records at or before this ISO time. */
+    to?: string;
+}
+/** The audit log of the admin store. */
+export declare class AdminAudit {
+    /** The admin store. */
+    private readonly store;
+    /** The clock of retention cutoffs. */
+    private readonly clock;
+    /** This instance's process id ("cli" for the CLI). */
+    private readonly processId;
+    /**
+     * Creates the audit log.
+     * @param store The admin store.
+     * @param clock The clock.
+     * @param processId This instance's process id.
+     */
+    constructor(store: AdminStore, clock: AdminClock, processId: () => string);
+    /**
+     * Appends an audited action, linked to the newest record by its hash (D19), and an activity item for a success.
+     * @param entry The action.
+     * @returns The stored record.
+     */
+    record(entry: AuditEntry): Promise<AuditRecordView>;
+    /**
+     * Records an action and logs instead of throwing when the store fails, so an audit problem never fails the action.
+     * @param entry The action.
+     */
+    recordSafely(entry: AuditEntry): Promise<void>;
+    /**
+     * Checks the hash chain from the oldest remaining record (D19).
+     * @returns ok, how many records were checked, and the first broken sequence.
+     */
+    verifyChain(): Promise<AuditVerifyView>;
+    /**
+     * Removes records older than the retention (settings/auditRetention, default DEFAULT_AUDIT_RETENTION_DAYS) and audits
+     * the cut as the system actor.
+     * @returns How many records were removed.
+     */
+    applyRetention(): Promise<number>;
+    /**
+     * The retention in days.
+     * @returns The stored setting, or DEFAULT_AUDIT_RETENTION_DAYS.
+     */
+    retentionDays(): Promise<number>;
+    /**
+     * Stores a new retention.
+     * @param days Whole days, at least 1.
+     */
+    setRetentionDays(days: number): Promise<void>;
+    /**
+     * One page of matching records, newest first.
+     * @param filters The filters.
+     * @param page The page, from 1.
+     * @returns The page's records and the number of matches.
+     */
+    query(filters: AuditQuery, page: number): Promise<{
+        items: AuditRecordView[];
+        total: number;
+    }>;
+    /**
+     * Every matching record as a file, oldest first.
+     * @param format "csv" (CSV_COLUMNS) or "jsonl" (one record per line).
+     * @param filters The filters.
+     * @returns The file bytes.
+     */
+    export(format: "csv" | "jsonl", filters: AuditQuery): Promise<Uint8Array<ArrayBuffer>>;
+    /**
+     * The newest activity items.
+     * @param limit How many.
+     * @returns The items, newest first.
+     */
+    activity(limit: number): Promise<ActivityItemView[]>;
+    /**
+     * Appends the activity item of a successful action: "<actor> <action> <target>".
+     * @param record The audit record.
+     */
+    private recordActivity;
+    /**
+     * The records that match the filters, oldest first.
+     * @param filters The filters.
+     * @returns The records.
+     */
+    private matching;
+    /**
+     * Every audit record, oldest first, read in pages of RECORD_QUERY_MAX_LIMIT.
+     * @returns The records.
+     */
+    private readAll;
+}
+/**
+ * JSON with object keys sorted at every level, so the same record always hashes the same.
+ * @param value The value.
+ * @returns The canonical JSON.
+ */
+export declare function canonicalJson(value: unknown): string;

package/lib/admin/AdminAudit.js

@@ -0,0 +1,266 @@
+// The admin audit log (game-server-admin-console D19, DR §8): an append-only stream whose records are linked by a
+// SHA-256 hash chain, with retention, filtered queries, CSV/JSON-lines export and the activity feed.
+import { getLogger } from "../GameServerLogger.js";
+import { ADMIN_PAGE_SIZE, AUDIT_CHAIN_SEED, DEFAULT_AUDIT_RETENTION_DAYS } from "./AdminConstants.js";
+import { sha256Hex } from "./AdminCrypto.js";
+import { RECORD_QUERY_MAX_LIMIT } from "./AdminStore.js";
+/** The settings document holding the retention in days. */
+const RETENTION_SETTINGS_ID = "auditRetention";
+/** Milliseconds per day. */
+const MILLISECONDS_PER_DAY = 86400000;
+/** Columns of the CSV export, in order. */
+const CSV_COLUMNS = ["sequence", "at", "actorKind", "actorName", "clientAddress", "processId", "action", "target", "result", "detail"];
+/** Characters that make a CSV field need quotes. */
+const CSV_SPECIAL_CHARACTERS = /[",\r\n]/;
+/** The audit log of the admin store. */
+export class AdminAudit {
+    /** The admin store. */
+    store;
+    /** The clock of retention cutoffs. */
+    clock;
+    /** This instance's process id ("cli" for the CLI). */
+    processId;
+    /**
+     * Creates the audit log.
+     * @param store The admin store.
+     * @param clock The clock.
+     * @param processId This instance's process id.
+     */
+    constructor(store, clock, processId) {
+        this.store = store;
+        this.clock = clock;
+        this.processId = processId;
+    }
+    /**
+     * Appends an audited action, linked to the newest record by its hash (D19), and an activity item for a success.
+     * @param entry The action.
+     * @returns The stored record.
+     */
+    async record(entry) {
+        const stored = await this.store.appendChainedRecord("audit", (previous, sequence, at) => {
+            const previousHash = previous?.value.hash ?? AUDIT_CHAIN_SEED;
+            const unhashed = Object.assign({ sequence: sequence, at: at }, entry);
+            return Object.assign({}, unhashed, { previousHash: previousHash, hash: auditHash(previousHash, unhashed) });
+        });
+        if (entry.result.ok)
+            await this.recordActivity(stored.value);
+        return stored.value;
+    }
+    /**
+     * Records an action and logs instead of throwing when the store fails, so an audit problem never fails the action.
+     * @param entry The action.
+     */
+    async recordSafely(entry) {
+        try {
+            await this.record(entry);
+        }
+        catch (error) {
+            getLogger().error("admin audit record failed", { action: entry.action, error: String(error) });
+        }
+    }
+    /**
+     * Checks the hash chain from the oldest remaining record (D19).
+     * @returns ok, how many records were checked, and the first broken sequence.
+     */
+    async verifyChain() {
+        let checked = 0;
+        let expectedPrevious = null;
+        for (const record of await this.readAll()) {
+            const value = record.value;
+            const { previousHash, hash, ...unhashed } = value;
+            const linkBroken = expectedPrevious != null && previousHash !== expectedPrevious;
+            const hashBroken = auditHash(previousHash, unhashed) !== hash || value.sequence !== record.sequence;
+            if (linkBroken || hashBroken)
+                return { ok: false, checked: checked, brokenAtSequence: record.sequence };
+            expectedPrevious = hash;
+            checked++;
+        }
+        return { ok: true, checked: checked, brokenAtSequence: null };
+    }
+    /**
+     * Removes records older than the retention (settings/auditRetention, default DEFAULT_AUDIT_RETENTION_DAYS) and audits
+     * the cut as the system actor.
+     * @returns How many records were removed.
+     */
+    async applyRetention() {
+        const days = await this.retentionDays();
+        const cutoff = new Date(this.clock.now() - days * MILLISECONDS_PER_DAY);
+        const removed = await this.store.trimRecordsBefore("audit", cutoff);
+        if (removed > 0) {
+            await this.record({ actor: { kind: "system", id: "system", name: "system" }, clientAddress: null, processId: this.processId(), action: "audit.retentionApplied", target: null, parameters: { days: days, removed: removed }, result: { ok: true, detail: null } });
+        }
+        return removed;
+    }
+    /**
+     * The retention in days.
+     * @returns The stored setting, or DEFAULT_AUDIT_RETENTION_DAYS.
+     */
+    async retentionDays() {
+        const stored = await this.store.getDocument("settings", RETENTION_SETTINGS_ID);
+        return stored?.value.days ?? DEFAULT_AUDIT_RETENTION_DAYS;
+    }
+    /**
+     * Stores a new retention.
+     * @param days Whole days, at least 1.
+     */
+    async setRetentionDays(days) {
+        await this.store.putDocument("settings", RETENTION_SETTINGS_ID, { days: days }, null);
+    }
+    /**
+     * One page of matching records, newest first.
+     * @param filters The filters.
+     * @param page The page, from 1.
+     * @returns The page's records and the number of matches.
+     */
+    async query(filters, page) {
+        const matching = (await this.matching(filters)).reverse();
+        const firstIndex = (Math.max(1, Math.floor(page)) - 1) * ADMIN_PAGE_SIZE;
+        return { items: matching.slice(firstIndex, firstIndex + ADMIN_PAGE_SIZE), total: matching.length };
+    }
+    /**
+     * Every matching record as a file, oldest first.
+     * @param format "csv" (CSV_COLUMNS) or "jsonl" (one record per line).
+     * @param filters The filters.
+     * @returns The file bytes.
+     */
+    async export(format, filters) {
+        const records = await this.matching(filters);
+        const lines = (format === "csv")
+            ? [CSV_COLUMNS.join(",")].concat(records.map(csvRow))
+            : records.map((record) => JSON.stringify(record));
+        return new TextEncoder().encode(lines.map((line) => line + "\n").join(""));
+    }
+    /**
+     * The newest activity items.
+     * @param limit How many.
+     * @returns The items, newest first.
+     */
+    async activity(limit) {
+        const records = await this.store.readRecords("events", { limit: limit, newestFirst: true });
+        return records.map((record) => record.value);
+    }
+    /**
+     * Appends the activity item of a successful action: "<actor> <action> <target>".
+     * @param record The audit record.
+     */
+    async recordActivity(record) {
+        const text = [record.actor.name, record.action, record.target ?? ""].join(" ").trim();
+        const item = { at: record.at, kind: "admin", text: text, processId: record.processId };
+        await this.store.appendRecord("events", item);
+    }
+    /**
+     * The records that match the filters, oldest first.
+     * @param filters The filters.
+     * @returns The records.
+     */
+    async matching(filters) {
+        const records = await this.readAll();
+        return records.map((record) => record.value).filter((record) => matchesQuery(record, filters));
+    }
+    /**
+     * Every audit record, oldest first, read in pages of RECORD_QUERY_MAX_LIMIT.
+     * @returns The records.
+     */
+    async readAll() {
+        const records = [];
+        let afterSequence = 0;
+        for (;;) {
+            const page = await this.store.readRecords("audit", { afterSequence: afterSequence, limit: RECORD_QUERY_MAX_LIMIT, newestFirst: false });
+            records.push(...page);
+            if (page.length < RECORD_QUERY_MAX_LIMIT)
+                return records;
+            afterSequence = page[page.length - 1].sequence;
+        }
+    }
+}
+/**
+ * The hash of an audit record: sha256(previousHash + canonicalJson(record without its hashes)) (DR §8).
+ * @param previousHash The previous record's hash (AUDIT_CHAIN_SEED for the first).
+ * @param unhashed The record without previousHash and hash.
+ * @returns Lower-case hex.
+ */
+function auditHash(previousHash, unhashed) {
+    const covered = {
+        sequence: unhashed.sequence,
+        at: unhashed.at,
+        actor: unhashed.actor,
+        clientAddress: unhashed.clientAddress,
+        processId: unhashed.processId,
+        action: unhashed.action,
+        target: unhashed.target,
+        parameters: unhashed.parameters,
+        result: unhashed.result
+    };
+    return sha256Hex(previousHash + canonicalJson(covered));
+}
+/**
+ * JSON with object keys sorted at every level, so the same record always hashes the same.
+ * @param value The value.
+ * @returns The canonical JSON.
+ */
+export function canonicalJson(value) {
+    if (Array.isArray(value))
+        return "[" + value.map(canonicalJson).join(",") + "]";
+    if (value !== null && typeof value === "object") {
+        const entries = Object.entries(value).filter(([, item]) => item !== undefined);
+        entries.sort(([left], [right]) => compareCodePoints(left, right));
+        return "{" + entries.map(([key, item]) => JSON.stringify(key) + ":" + canonicalJson(item)).join(",") + "}";
+    }
+    return JSON.stringify(value) ?? "null";
+}
+/**
+ * Orders two texts by code point (locale-independent, so every instance sorts keys the same).
+ * @param left One text.
+ * @param right The other.
+ * @returns Negative, zero or positive.
+ */
+function compareCodePoints(left, right) {
+    if (left < right)
+        return -1;
+    if (left > right)
+        return 1;
+    return 0;
+}
+/**
+ * Whether a record passes the filters.
+ * @param record The record.
+ * @param filters The filters.
+ * @returns True when it matches every filter given.
+ */
+function matchesQuery(record, filters) {
+    const actorText = (record.actor.name + " " + record.actor.id + " " + record.actor.kind).toLowerCase();
+    if (filters.actor != null && !actorText.includes(filters.actor.toLowerCase()))
+        return false;
+    if (filters.action != null && !record.action.startsWith(filters.action))
+        return false;
+    if (filters.target != null && !(record.target ?? "").toLowerCase().includes(filters.target.toLowerCase()))
+        return false;
+    if (filters.result != null && record.result.ok !== (filters.result === "ok"))
+        return false;
+    if (filters.from != null && record.at < filters.from)
+        return false;
+    if (filters.to != null && record.at > filters.to)
+        return false;
+    return true;
+}
+/**
+ * One CSV row of a record (CSV_COLUMNS).
+ * @param record The record.
+ * @returns The row.
+ */
+function csvRow(record) {
+    const actorKind = record.actor.kind;
+    const fields = [
+        String(record.sequence), record.at, actorKind, record.actor.name, record.clientAddress ?? "", record.processId,
+        record.action, record.target ?? "", record.result.ok ? "ok" : "failed", record.result.detail ?? ""
+    ];
+    return fields.map(csvField).join(",");
+}
+/**
+ * Quotes a CSV field when it needs it.
+ * @param field The text.
+ * @returns The CSV field.
+ */
+function csvField(field) {
+    return CSV_SPECIAL_CHARACTERS.test(field) ? "\"" + field.replace(/"/g, "\"\"") + "\"" : field;
+}

package/lib/admin/AdminCli.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Runs `babylon-game-server admin <command> …` and sets the exit code: 0 on success, 2 on a usage or config problem,
+ * 1 otherwise.
+ * @param argumentList The arguments after `admin`.
+ * @param environment The process environment.
+ */
+export declare function runAdminCommand(argumentList: string[], environment: NodeJS.ProcessEnv): Promise<void>;