@amxts/perms 0.0.0-stage → 0.1.0

package/src/players.ts

@@ -0,0 +1,186 @@
+/**
+ * The players on the server: who each one is in the permissions, what he
+ * may do, and AMX Mod X's flags written from his `amxx.*` nodes, so Pawn
+ * plugins' `access` and `cmd_access` keep working.
+ */
+import { Cvar, Player, clearTimeout, server, setTimeout } from "@amxts/core";
+import { Hash_Sha256 } from "@amxts/core/constants";
+import { admins_flush, admins_push, hash_string, read_flags, remove_user_flags, set_user_flags } from "@amxts/core/natives";
+import type { User } from "./model";
+import { allUsers, answer, nextExpiry, primaryGroup, sourcesOf, userWith } from "./model";
+
+/** AMX Mod X's admin flags: the `amxx.<name>` node and its letter in `users.ini`. */
+export interface AdminFlag {
+	name: string;
+	letter: string;
+}
+
+export const FLAGS: AdminFlag[] = [
+	{ name: "immunity", letter: "a" },
+	{ name: "reservation", letter: "b" },
+	{ name: "kick", letter: "c" },
+	{ name: "ban", letter: "d" },
+	{ name: "slay", letter: "e" },
+	{ name: "map", letter: "f" },
+	{ name: "cvar", letter: "g" },
+	{ name: "cfg", letter: "h" },
+	{ name: "chat", letter: "i" },
+	{ name: "vote", letter: "j" },
+	{ name: "password", letter: "k" },
+	{ name: "rcon", letter: "l" },
+	{ name: "levelA", letter: "m" },
+	{ name: "levelB", letter: "n" },
+	{ name: "levelC", letter: "o" },
+	{ name: "levelD", letter: "p" },
+	{ name: "levelE", letter: "q" },
+	{ name: "levelF", letter: "r" },
+	{ name: "levelG", letter: "s" },
+	{ name: "levelH", letter: "t" },
+	{ name: "menu", letter: "u" },
+	{ name: "banTemp", letter: "v" },
+	{ name: "admin", letter: "y" },
+];
+
+// The cvars admin.amxx registers, which server configs set.
+const mode = new Cvar("amx_mode", "1");
+const passwordField = new Cvar("amx_password_field", "_pw");
+const defaultAccess = new Cvar("amx_default_access", "z");
+
+interface PlayerPerms {
+	user: User | null;
+	sources: Map<string, boolean>[];
+	/** What the sources answered, for "change": the flags and the group; the nodes are asked fresh. */
+	signature: string;
+}
+
+const online = new Map<number, PlayerPerms>();
+const listeners: ((player: Player) => void)[] = [];
+let writesFlags = true;
+let expiry = 0;
+
+export function onChange(listener: (player: Player) => void) {
+	listeners.push(listener);
+}
+
+/** Whether the module writes the players' flags; not while admin.amxx does. */
+export function setWritesFlags(on: boolean) {
+	writesFlags = on;
+}
+
+export function sha256(text: string) {
+	return `sha256:${hash_string(text, Hash_Sha256)}`;
+}
+
+/**
+ * The player's entry: by SteamID, then IP, then name with the password his
+ * info carries. With `amx_mode 2`, as admin.amxx does, a player without an
+ * entry - or with a name entry's wrong password - is kicked; otherwise he
+ * plays with the default group's rights.
+ */
+function identify(player: Player) {
+	const entry = entryOf(player);
+	if (entry != null || mode.number != 2) return entry;
+
+	player.kick("You have no entry on this server");
+	return null;
+}
+
+function entryOf(player: Player) {
+	const bySteam = player.steamId.startsWith("STEAM_") && !player.steamId.includes("LAN") ? userWith(player.steamId) : null;
+	if (bySteam != null) return bySteam;
+
+	const byIp = userWith(`ip:${player.ip}`);
+	if (byIp != null) return byIp;
+
+	const byName = userWith(`name:${player.name}`);
+	if (byName == null) return null;
+	if (byName.password == "" || sha256(player.info.get(passwordField.value)) == byName.password) return byName;
+
+	player.print(`[perms] Wrong password for this name: set it with setinfo ${passwordField.value} <password>`, "console");
+	return null;
+}
+
+/** The letters of the player's `amxx.*` nodes; `amx_default_access` when he has none. */
+function lettersOf(sources: Map<string, boolean>[]) {
+	const letters = FLAGS.filter(flag => answer(sources, `amxx.${flag.name}`)).map<string>(flag => flag.letter).join("");
+	return letters != "" ? letters : defaultAccess.value;
+}
+
+/** Works out a player's permissions again, writes his flags, and tells the listeners when anything changed. */
+export function refresh(player: Player) {
+	if (!player.isConnected) return;
+
+	const now = Date.now();
+	const user = mode.number == 0 ? null : identify(player);
+	if (!player.isConnected) return;
+
+	const sources = sourcesOf(user, now);
+	const letters = lettersOf(sources);
+	const signature = `${letters}|${primaryGroup(user, now)}|${JSON.stringify(sources.map<string[]>(source => sourceKeys(source)))}`;
+	const before = online.get(player.id);
+	online.set(player.id, { user, sources, signature });
+
+	if (writesFlags) {
+		remove_user_flags(player.id);
+		set_user_flags(player.id, read_flags(letters));
+	}
+	if (before == null || before.signature != signature) listeners.forEach(listener => listener(player));
+}
+
+function sourceKeys(source: Map<string, boolean>) {
+	const keys: string[] = [];
+	source.forEach((value, node) => keys.push(value ? node : `-${node}`));
+	return keys;
+}
+
+export function refreshAll() {
+	server.players.forEach(refresh);
+	fillAdminCache();
+	scheduleExpiry();
+}
+
+export function forget(id: number) {
+	online.delete(id);
+}
+
+export function has(player: Player, node: string) {
+	const state = online.get(player.id);
+	return answer(state != null ? state.sources : sourcesOf(null, Date.now()), node);
+}
+
+export function userOf(player: Player) {
+	return online.get(player.id)?.user ?? null;
+}
+
+/** The player's entry id, or the id his entry would get: his SteamID, or his IP when he has none. */
+export function idOf(player: Player) {
+	const user = userOf(player);
+	if (user != null) return user.id;
+	return player.steamId.startsWith("STEAM_") && !player.steamId.includes("LAN") ? player.steamId : `ip:${player.ip}`;
+}
+
+/** AMX Mod X's own list of admins, as admin.amxx fills it, for plugins that read it with admins_lookup. */
+function fillAdminCache() {
+	if (!writesFlags) return;
+
+	admins_flush();
+	const now = Date.now();
+	for (const user of allUsers()) {
+		const letters = lettersOf(sourcesOf(user, now));
+		const kind = user.id.startsWith("ip:") ? "d" : user.id.startsWith("name:") ? "" : "c";
+		const auth = user.id.startsWith("STEAM_") ? user.id : user.id.substring(user.id.indexOf(":") + 1);
+		admins_push(auth, user.password, read_flags(letters), read_flags(user.password == "" ? `${kind}e` : kind));
+	}
+}
+
+/** Wakes up when the nearest grant of an online player or a group ends, and works it out then. */
+function scheduleExpiry() {
+	if (expiry != 0) clearTimeout(expiry);
+
+	const users: User[] = [];
+	online.forEach((state) => {
+		if (state.user != null) users.push(state.user);
+	});
+	const next = nextExpiry(users, Date.now());
+	expiry = next == 0 ? 0 : setTimeout(() => refreshAll(), Math.min(next - Date.now() + 50, 24 * 3600 * 1000));
+}

package/src/server.ts

@@ -0,0 +1,62 @@
+/**
+ * The module on the server: the store opened with the project's options and
+ * `.env`, players worked out as they join and rename, the commands, and
+ * admin.amxx's commands for the configs and plugins that use them.
+ */
+import { env, game, server } from "@amxts/core";
+import { find_plugin_byfile } from "@amxts/core/natives";
+import type { PermsOptions } from "./types";
+import { declare, setThisServer } from "./model";
+import { DEFAULT_STORE, setStore } from "./editor";
+import { run } from "./commands";
+import { forget, refresh, refreshAll, setWritesFlags } from "./players";
+import { open, reload } from "./state";
+
+/** Plugins that write the players' flags themselves. */
+const ADMIN_PLUGINS = ["admin.amxx", "admin_sql.amxx"];
+
+/** A player who joined the game; one only connecting is worked out when he joins. */
+function refreshSlot(id: number) {
+	const player = server.players.find(each => each.id == id);
+	if (player != null) refresh(player);
+}
+
+/** The words of a command; the engine splits a line at `:`, so `STEAM_0 : 1 : 5` is put back into `STEAM_0:1:5`. */
+function splitWords(text: string) {
+	return text.replace(/\s*:\s*/g, ":").trim().split(" ").filter(each => each != "");
+}
+
+export function start(options: PermsOptions) {
+	setThisServer(env("PERMS_SERVER", ""));
+	const editor = env("PERMS_EDITOR_URL", "");
+	setStore(editor != "" ? editor : options.editor != "" ? options.editor : DEFAULT_STORE);
+	declare("perms.view", "See groups and permissions with the perms commands in the game", false, false);
+
+	server.addEventListener("init", () => {
+		const running = ADMIN_PLUGINS.filter(file => find_plugin_byfile(file) >= 0);
+		if (running.length > 0) {
+			setWritesFlags(false);
+			console.error(`[perms] ${running.join(", ")} is running and gives the players' flags itself - perms does not; comment it out in plugins.ini`);
+		}
+		open(options.file, env("PERMS_DB", ""));
+	});
+
+	server.addEventListener("authorized", event => refreshSlot(event.player.id));
+	server.addEventListener("putInServer", event => refreshSlot(event.player.id));
+	server.addEventListener("disconnected", event => forget(event.player.id));
+	game.addEventListener("changeName", event => refresh(event.player), true);
+
+	server.addServerCommand("perms [args]", ({ args }) => {
+		run(null, splitWords(args ?? ""), line => console.log(line));
+	});
+	server.addCommand("perms [args]", ({ player, args }) => {
+		run(player, splitWords(args ?? ""), line => player.print(line, "console"));
+	});
+	server.addCommand("/perms [args]", ({ player, args }) => {
+		run(player, splitWords(args ?? ""), line => player.print(line, "console"));
+	});
+	server.addServerCommand("amx_reloadadmins", () => {
+		reload();
+	});
+	server.addEventListener("configsExecuted", () => refreshAll());
+}

package/src/state.ts

@@ -0,0 +1,102 @@
+/**
+ * Where the permissions live - the file or MySQL - and the one way they
+ * change: `commit(changes)` applies them to the model, writes them to the
+ * store and works the online players out again.
+ */
+import { setInterval } from "@amxts/core";
+import type { Change, SkipCode } from "./model";
+import { apply, dropExpired, reasonOf } from "./model";
+import * as database from "./db-store";
+import { filePath, readFile, setFile, writeFile } from "./file-store";
+import { refreshAll } from "./players";
+
+/** A change the model refused, and why. */
+export interface Skipped {
+	change: Change;
+	code: SkipCode;
+	reason: string;
+}
+
+export interface Committed {
+	done: Change[];
+	skipped: Skipped[];
+}
+
+const POLL_MS = 5000;
+
+/** Starts the store: MySQL when `url` is given, else the file; reads it. */
+export async function open(file: string, url: string) {
+	setFile(file);
+	if (url == "") {
+		reloadFromFile();
+		return;
+	}
+
+	database.useDatabase(url);
+	try {
+		await database.createTables();
+		await database.readDatabase();
+		console.log("[perms] permissions read from MySQL");
+	} catch (error) {
+		console.error(`[perms] MySQL: ${error.message} - trying again every ${POLL_MS / 1000} s`);
+	}
+	refreshAll();
+	setInterval(() => pollDatabase(), POLL_MS);
+}
+
+function reloadFromFile() {
+	if (!readFile()) {
+		console.error(`[perms] ${filePath()} could not be read - the permissions read before stay`);
+		return;
+	}
+	refreshAll();
+}
+
+async function pollDatabase() {
+	try {
+		if (!(await database.changedElsewhere())) return;
+		await database.readDatabase();
+		refreshAll();
+	} catch (error) {
+		console.error(`[perms] MySQL: ${error.message}`);
+	}
+}
+
+/** Reads the store again: `perms reload`, `amx_reloadadmins`. */
+export async function reload() {
+	if (!database.usesDatabase()) {
+		reloadFromFile();
+		return;
+	}
+
+	await database.readDatabase();
+	refreshAll();
+}
+
+/** Applies changes in order, writes those that applied, and works the players out again. */
+export async function commit(changes: Change[]) {
+	const committed: Committed = { done: [], skipped: [] };
+	for (const change of changes) {
+		const code = apply(change);
+		if (code == "") committed.done.push(change);
+		else committed.skipped.push({ change, code, reason: reasonOf(code, change) });
+	}
+	if (committed.done.length == 0) return committed;
+
+	dropExpired(Date.now());
+	if (database.usesDatabase()) await database.writeChanges(committed.done);
+	else writeFile();
+	refreshAll();
+	return committed;
+}
+
+/** Writes the whole model to the store, after an import. */
+export async function writeEverything() {
+	if (database.usesDatabase()) await database.writeAll();
+	else writeFile();
+	refreshAll();
+}
+
+export function storageName() {
+	return database.usesDatabase() ? "mysql" : "file";
+}

package/src/time.ts

@@ -0,0 +1,48 @@
+/** Moments and durations as files, commands and the editor write them. */
+
+const UNITS = new Map<string, number>([["s", 1], ["m", 60], ["h", 3600], ["d", 86400], ["w", 604800]]);
+
+/** Seconds in `30d`, `12h`, `90m`, `45s`, `2w`; -1 for anything else. */
+export function durationSeconds(text: string) {
+	const unit = UNITS.get(text.substring(text.length - 1).toLowerCase()) ?? 0;
+	const amount = Number(text.substring(0, text.length - 1));
+	if (unit == 0 || text.length < 2 || isNaN(amount) || amount <= 0) return -1;
+	return amount * unit;
+}
+
+/** `2026-12-01`, `2026-12-01T00:00`, `2026-12-01T00:00:00Z` (UTC) as ms since 1970; 0 for empty or unreadable text. */
+export function momentOf(text: string) {
+	const date = text.trim().replace(" ", "T").replace("Z", "");
+	const halves = `${date}T00:00`.split("T");
+	const parts = halves[0].split("-");
+	const clock = halves[1].split(":");
+	if (parts.length != 3 || clock.length < 2) return 0;
+
+	const year = Number(parts[0]);
+	const month = Number(parts[1]);
+	const dayOfMonth = Number(parts[2]);
+	const hours = Number(clock[0]);
+	const minutes = Number(clock[1]);
+	const seconds = clock.length > 2 ? Number(clock[2]) : 0;
+	if ([year, month, dayOfMonth, hours, minutes, seconds].some(value => isNaN(value))) return 0;
+	return Date.UTC(year, month - 1, dayOfMonth, hours, minutes, Math.floor(seconds));
+}
+
+/** A moment as the file and the editor write it, `2026-12-01T00:00:00Z`; "" for 0. */
+export function textOf(moment: number) {
+	if (moment == 0) return "";
+	return `${new Date(moment).toISOString().substring(0, 19)}Z`;
+}
+
+/** What is left of a moment, for the console: `29d 4h`, `3h 10m`, `5m`; "" for 0. */
+export function leftOf(moment: number, now: number) {
+	if (moment == 0) return "";
+
+	const seconds = Math.max(0, Math.floor((moment - now) / 1000));
+	const days = Math.floor(seconds / 86400);
+	const hours = Math.floor((seconds % 86400) / 3600);
+	const minutes = Math.floor((seconds % 3600) / 60);
+	if (days > 0) return `${days}d ${hours}h`;
+	if (hours > 0) return `${hours}h ${minutes}m`;
+	return `${minutes}m`;
+}

package/src/types.ts

@@ -0,0 +1,36 @@
+import type { Player } from "@amxts/core";
+
+/** The module's options in `amxts.config.ts`, under `perms`. */
+export interface PermsOptions {
+	/** The file under `configs/` the permissions are kept in, without its extension; `"perms"` reads `perms.yaml` (or `.json`). */
+	file: string;
+	/** The editor's store; `PERMS_EDITOR_URL` in `.env` overrides it. */
+	editor: string;
+}
+
+/** A permission a plugin declares, for the web editor and `perms nodes`. */
+export interface PermissionInfo {
+	/** What it lets a player do, as the editor shows it: `"Kick players"`. */
+	description: string;
+	/** Whether a player no group or grant says anything about has it; `false` by default. */
+	everyone?: boolean;
+}
+
+/** How long a grant or a group lasts, and where. */
+export interface GrantOptions {
+	/** Seconds from now; left out, it is permanent. */
+	for?: number;
+	/** The server it counts on (`PERMS_SERVER`); left out, every server. */
+	server?: string;
+}
+
+/** A player's permissions changed: he joined, a command or the editor changed them, or one expired. */
+export interface PermsChangeEvent {
+	player: Player;
+}
+
+declare module "@amxts/core" {
+	interface ModuleOptions {
+		perms?: Partial<PermsOptions>;
+	}
+}

package/testing/index.ts

@@ -0,0 +1,72 @@
+// Perms' test kit: the AMX Mod X natives the module calls that the fake
+// server leaves out - a player's flags written, AMX Mod X's admin list,
+// hash_string, find_plugin_byfile - and what a test reads back:
+//
+//   import { setup } from "@amxts/core/test-utils";
+//   import { permsOf } from "@amxts/perms/testing";
+//
+//   const server = await setup({ files: { "addons/amxmodx/configs/perms.yaml": "..." } });
+//   const bob = server.join("Bob", { steamId: "STEAM_0:1:5" });
+//   bob.flags;                                  // what set_user_flags wrote
+//   permsOf(server).admins;                     // what admins_push gave AMX Mod X
+import type { FakeServer } from "@amxts/core/test-utils";
+import { createHash } from "node:crypto";
+import { defineTestKit } from "@amxts/core/test-utils";
+
+/** An entry of AMX Mod X's admin list, as admins_push gave it. */
+export interface PushedAdmin {
+	auth: string;
+	password: string;
+	access: number;
+	flags: number;
+}
+
+export interface PermsKit {
+	/** AMX Mod X's admin list. */
+	admins: PushedAdmin[];
+	/** The plugin files find_plugin_byfile finds, as if they were loaded: `["admin.amxx"]`. */
+	loadedPlugins: string[];
+}
+
+const HASH_SHA256 = 3;
+
+const kits = new WeakMap<FakeServer, PermsKit>();
+
+function install(server: FakeServer): PermsKit {
+	const kit: PermsKit = { admins: [], loadedPlugins: [] };
+	kits.set(server, kit);
+
+	server.defineNative("set_user_flags", (call, [id, flags]) => {
+		const player = call.server.player(id);
+		if (player) player.flags |= flags;
+		return 0;
+	});
+	server.defineNative("remove_user_flags", (call, [id, flags]) => {
+		const player = call.server.player(id);
+		if (player) player.flags &= ~flags;
+		return 0;
+	});
+	server.defineNative("admins_flush", () => {
+		kit.admins.length = 0;
+		return 0;
+	});
+	server.defineNative("admins_push", (call, [auth, password, access, flags]) => {
+		kit.admins.push({ auth: call.memory.text(auth), password: call.memory.text(password), access, flags });
+		return 0;
+	});
+	server.defineNative("hash_string", (call, [text, type, out, length]) => {
+		if (type !== HASH_SHA256) throw new Error(`hash_string: the test kit hashes SHA-256 only, not type ${type}`);
+		return call.memory.setText(out, length, createHash("sha256").update(call.memory.text(text)).digest("hex"));
+	});
+	server.defineNative("find_plugin_byfile", (call, [file]) => kit.loadedPlugins.indexOf(call.memory.text(file)));
+	return kit;
+}
+
+export default defineTestKit({ install });
+
+/** The kit of a server Perms runs on. */
+export function permsOf(server: FakeServer) {
+	const kit = kits.get(server);
+	if (!kit) throw new Error("Perms' test kit is not on this server: load @amxts/perms (or call setup()) first");
+	return kit;
+}