factorio-clusterio/packages/lib/src/permissions.ts

/**
 * User and permissions library
 *
 * Defines data types for users, roles and permissions.
 *
 * @author Hornwitser
 * @module lib/users
 */
import { Permission, Role } from "./data";


export const permissions = new Map<string, Permission>();

/**
 * Define a new user permission for Clusterio
 *
 * Defines a permission for use in Clusterio.  Defined permissions can be
 * granted to roles, and checked on users.  Name should be `lower_case`
 * style and start with the plugin name followed by a dot.
 *
 * @param def - The definition for the permission.
 * @param def.name - The internal name for the permission.
 * @param def.title - User facing name for permission.
 * @param def.description - User facing description.
 * @param def.grantByDefault -
 *     If true this role is granted by the generated Player role by default.
 *
 */
export function definePermission({
	name,
	title,
	description,
	grantByDefault = false,
}: {
	name: string,
	title: string,
	description: string,
	grantByDefault?: boolean,
}) {
	if (typeof name !== "string" || !name.length) {
		throw new Error("Expected name to be a non-empty string");
	}
	if (typeof title !== "string" || !title.length) {
		throw new Error("Expected title to be a non-empty string");
	}
	if (typeof description !== "string" || !description.length) {
		throw new Error("Expected description to be a non-empty string");
	}
	if (typeof grantByDefault !== "boolean") {
		throw new Error("Expected grantByDefault to be a boolean");
	}

	if (permissions.has(name)) {
		throw new Error(`Permission '${name}' is already defined`);
	}

	permissions.set(name, new Permission(name, title, description, grantByDefault));
}


/**
 * Ensure the default admin role has full access
 *
 * Ensures the role with id 0 exisits and has the core.admin permission.
 *
 * @param roles - role storage to modify.
 * @returns the default admin role
 */
export function ensureDefaultAdminRole(roles: Map<number, Role>) {
	let admin = roles.get(0);
	if (!admin) {
		admin = Role.fromJSON({
			id: 0,
			name: "Cluster Admin",
			description: "Cluster wide administrator.",
			permissions: [],
		});
		roles.set(0, admin);
	}
	admin.permissions.add("core.admin");
	return admin;
}

/**
 * Ensure the default player role has default accesses
 *
 * Ensures the role with id 1 exists and has all the permissions that are
 * assigned by default.  Note that this may not be the same role as the one
 * that is assigned to new users by default.
 *
 * @param roles - role storage to modify.
 */
export function ensureDefaultPlayerRole(roles: Map<number, Role>) {
	let player = roles.get(1);
	if (!player) {
		player = Role.fromJSON({
			id: 1,
			name: "Player",
			description: "Default player role.",
			permissions: [],
		});
		roles.set(1, player);
	}
	player.grantDefaultPermissions();
}


// Definitions for the built in permissions used in Clusterio.
// description should answer "this permission allows you to ___"
definePermission({
	name: "core.admin",
	title: "Administrator",
	description: "Bypass all permission checks.",
});
definePermission({
	name: "core.control.connect",
	title: "Connect to WebSocket",
	description: "Connect to the controller's WebSocket control interface.",
	grantByDefault: true,
});

definePermission({
	name: "core.controller.stop",
	title: "Stop controller",
	description:
		"Stop the Node.js controller process making the cluster inoperable until someone with access to the system " +
		"it runs on manually starts it again.",
});
definePermission({
	name: "core.controller.restart",
	title: "Restart controller",
	description: "Restart the Node.js controller process if the system is set up for restarting.",
});
definePermission({
	name: "core.controller.update",
	title: "Update controller",
	description: "Remotely update the controller if the controller allows for remote updates.",
});
definePermission({
	name: "core.controller.get_config",
	title: "Get controller config",
	description: "Get the config of controller.",
});
definePermission({
	name: "core.controller.update_config",
	title: "Modify controller config",
	description: "Modify the controller config or entries of the controller config.",
});
definePermission({
	name: "core.system.subscribe",
	title: "Subscribe to system updates",
	description:
		"Subscribe to be notified when the system info detailing system specific information along with metrics " +
		"such as cpu, memory and disk usage for the controller and hosts are updated.",
});
definePermission({
	name: "core.host.stop",
	title: "Stop Hosts",
	description:
		"Stop Node.js host processes making the host inaccessible until someone with access to the system " +
		"it runs on manually starts it again.",
});
definePermission({
	name: "core.host.restart",
	title: "Restart Hosts",
	description: "Restart Node.js host processes if the system they run on are set up for restarting.",
});
definePermission({
	name: "core.host.update",
	title: "Update Hosts",
	description: "Remotely update a host if the host allows for remote updates.",
});
definePermission({
	name: "core.host.get_config",
	title: "Get host configs",
	description: "Get the config of hosts.",
});
definePermission({
	name: "core.host.update_config",
	title: "Modify host configs",
	description: "Modify the host config or entries of the host config.",
});
definePermission({
	name: "core.host.list",
	title: "List hosts",
	description: "Get the full list of hosts in the cluster.",
	grantByDefault: true,
});
definePermission({
	name: "core.host.subscribe",
	title: "Subscribe to host updates",
	description: "Subscribe to be notified on updates on the details of hosts.",
	grantByDefault: true,
});
definePermission({
	name: "core.host.generate_token",
	title: "Generate host token",
	description: "Generate tokens for hosts to connect to the cluster with.",
});
definePermission({
	name: "core.host.revoke_token",
	title: "Revoke host token",
	description: "Revoke access token and terminate existing connection for hosts.",
});
definePermission({
	name: "core.host.create_config",
	title: "Create host config",
	description: "Create host configs via the controller.",
});

definePermission({
	name: "core.instance.get",
	title: "Get instance",
	description: "Get the details of an instance in the cluster.",
	grantByDefault: true,
});
definePermission({
	name: "core.instance.list",
	title: "List instances",
	description: "Get the full list of instances in the cluster.",
	grantByDefault: true,
});
definePermission({
	name: "core.instance.subscribe",
	title: "Subscribe to instance updates",
	description: "Subscribe to be notified on updates on the details and status of instances.",
	grantByDefault: true,
});
definePermission({
	name: "core.instance.create",
	title: "Create instance",
	description: "Create new instances on the controller.",
});
definePermission({
	name: "core.instance.get_config",
	title: "Get instance config",
	description: "Get the config of instances.",
});
definePermission({
	name: "core.instance.update_config",
	title: "Modify instance config",
	description: "Modify the config or entries of the config for instances.",
});
definePermission({
	name: "core.instance.assign",
	title: "Assign instance",
	description: "Assign or reassign instances to a host.",
});
definePermission({
	name: "core.instance.save.list",
	title: "List saves",
	description: "List the saves currently on instances.",
});
definePermission({
	name: "core.instance.save.subscribe",
	title: "Subscribe to save updates",
	description: "Subscribe to be notifed on updates to the list of saves of instances.",
});
definePermission({
	name: "core.instance.save.create",
	title: "Create new save",
	description: "Create new savegames on instances.",
});
definePermission({
	name: "core.instance.save.rename",
	title: "Rename save",
	description: "Rename savegames on instances.",
});
definePermission({
	name: "core.instance.save.copy",
	title: "Copy save",
	description: "Create copies of savegames on instances.",
});
definePermission({
	name: "core.instance.save.delete",
	title: "Delete save",
	description: "Delete savegames on instances.",
});
definePermission({
	name: "core.instance.save.upload",
	title: "Upload save",
	description: "Upload savegames to instances.",
});
definePermission({
	name: "core.instance.save.transfer",
	title: "Transfer save",
	description: "Transfer savegames between instances.",
});
definePermission({
	name: "core.instance.save.download",
	title: "Download save",
	description: "Download savegames from instances.",
});
definePermission({
	name: "core.instance.export_data",
	title: "Export locale and icons",
	description: "Export the the locale and icons from an instance and upload it to the controller.",
});
definePermission({
	name: "core.instance.extract_players",
	title: "Extract player stats from running save",
	description: "Run extraction to create a user for each player in the save and set the online time from the save.",
});
definePermission({
	name: "core.instance.start",
	title: "Start instance",
	description: "Start instances.",
});
definePermission({
	name: "core.instance.load_scenario",
	title: "Load scenario",
	description: "Start instances by loading a scenario.",
});
definePermission({
	name: "core.instance.stop",
	title: "Stop instance",
	description: "Stop instances.",
});
definePermission({
	name: "core.instance.kill",
	title: "Kill instance",
	description: "Terminate running instances without saving or cleanup.",
});
definePermission({
	name: "core.instance.delete",
	title: "Delete instance",
	description: "Delete instances (includes config and all files stored like saves and logs).",
});
definePermission({
	name: "core.instance.send_rcon",
	title: "Send RCON",
	description: "Send arbitrary RCON commands to instances.",
});

definePermission({
	name: "core.mod_pack.get",
	title: "Retrieve mod pack",
	description: "Get the details of a mod pack in the cluster.",
	grantByDefault: true,
});
definePermission({
	name: "core.mod_pack.list",
	title: "List mod packs",
	description: "Get the full list of a mod packs in the cluster.",
	grantByDefault: true,
});
definePermission({
	name: "core.mod_pack.subscribe",
	title: "Subscribe to mod pack updates",
	description: "Subscribe to be notified on updates on the details of mod packs.",
	grantByDefault: true,
});
definePermission({
	name: "core.mod_pack.create",
	title: "Create mod pack",
	description: "Create new mod pack in the cluster.",
});
definePermission({
	name: "core.mod_pack.update",
	title: "Update mod pack",
	description: "Edit existing mod pack definition in the cluster.",
});
definePermission({
	name: "core.mod_pack.delete",
	title: "Delete mod pack",
	description: "Delete mod pack definition in the cluster.",
});
definePermission({
	name: "core.mod.get",
	title: "Get mods",
	description: "Get the details of a mod stored in the cluster.",
	grantByDefault: true,
});
definePermission({
	name: "core.mod.list",
	title: "List mods",
	description: "Get the full list of mods stored on the controller.",
	grantByDefault: true,
});
definePermission({
	name: "core.mod.search",
	title: "Search mods",
	description: "Search through the list of mods stored on the controller.",
	grantByDefault: true,
});
definePermission({
	name: "core.mod.search_portal",
	title: "Search mod portal",
	description: "Search for mods on the Factorio mod portal.",
	grantByDefault: true,
});
definePermission({
	name: "core.mod.subscribe",
	title: "Subscribe to mod updates",
	description: "Subscribe to be notified on updates on the details of mods.",
	grantByDefault: true,
});
definePermission({
	name: "core.mod.upload",
	title: "Upload mods",
	description: "Upload mods to the controller.",
});
definePermission({
	name: "core.mod.download",
	title: "Download mod",
	description: "Download mods stored on the controller.",
	grantByDefault: true,
});
definePermission({
	name: "core.mod.delete",
	title: "Delete mod",
	description: "Delete mods stored on the controller.",
});
definePermission({
	name: "core.mod.download_from_portal",
	title: "Download mods from portal",
	description: "Allow downloading mods directly from the Factorio mod portal to the controller.",
	grantByDefault: true,
});

definePermission({
	name: "core.permission.list",
	title: "List permissions",
	description: "Get the full list of permissions in the cluster.",
	grantByDefault: true,
});

definePermission({
	name: "core.role.list",
	title: "List roles",
	description: "Get the full list of roles and their permissions in the cluster.",
	grantByDefault: true,
});
definePermission({
	name: "core.role.create",
	title: "Create role",
	description: "Create new roles with permissions.",
});
definePermission({
	name: "core.role.update",
	title: "Update role",
	description: "Edit existing roles including permissions they grant.",
});
definePermission({
	name: "core.role.delete",
	title: "Delete role",
	description: "Permanently delete roles.",
});

definePermission({
	name: "core.user.get",
	title: "Get user",
	description: "Get the details of a user in the cluster.",
	grantByDefault: true,
});
definePermission({
	name: "core.user.list",
	title: "List users",
	description: "Get the full list of users in the cluster.",
	grantByDefault: true,
});
definePermission({
	name: "core.user.subscribe",
	title: "Subscribe to user updates",
	description: "Subscribe to be notified on updates on the details and status of users.",
	grantByDefault: true,
});
definePermission({
	name: "core.user.create",
	title: "Create users",
	description: "Create user acounts with a given name.",
});
definePermission({
	name: "core.user.revoke_token",
	title: "Revoke user token",
	description: "Revoke access token and terminate all existing control connections for oneself.",
	grantByDefault: true,
});
definePermission({
	name: "core.user.revoke_other_token",
	title: "Revoke other user's token",
	description: "Allow revoking tokens for other users than oneself. Requires Revoke user token.",
});
definePermission({
	name: "core.user.update_roles",
	title: "Update user roles",
	description: "Add or remove any role to any user.",
});
definePermission({
	name: "core.user.set_admin",
	title: "Set user admin status",
	description: "Promote or demote any user to Factorio admin.",
});
definePermission({
	name: "core.user.set_banned",
	title: "Set user ban status",
	description: "Ban or unban any user.",
});
definePermission({
	name: "core.user.set_whitelisted",
	title: "Set user whitelist status",
	description: "Add or remove any user to/from the whitelist.",
});
definePermission({
	name: "core.user.delete",
	title: "Delete user",
	description: "Delete users and all data stored for them.",
});
definePermission({
	name: "core.user.bulk_import",
	title: "Bulk user import",
	description: "Bulk import users including admin, whitelist, and bans." +
	" (Imports types are restricted by other permissions, e.g. core.user.set_admin)",
});
definePermission({
	name: "core.user.bulk_export",
	title: "Bulk user export",
	description: "Bulk export users including admin, whitelist, and bans.",
});
definePermission({
	name: "core.user.bulk_restore",
	title: "Bulk user restore",
	description: "Bulk restore users including admin, whitelist, and bans." +
	" (Restore types are restricted by other permissions, e.g. core.user.set_admin)",
});

definePermission({
	name: "core.log.follow",
	title: "Follow cluster log",
	description: "Receive new entries in the cluster log.  Required to see instance console.",
});
definePermission({
	name: "core.log.query",
	title: "Query cluster log",
	description: "Query past entries in the cluster log.  Required to see past entries in instance console.",
});

definePermission({
	name: "core.plugin.list",
	title: "List plugins",
	description: "List all installed plugins on a machine.",
});
definePermission({
	name: "core.plugin.update",
	title: "Update plugin",
	description: "Remotely update a plugin if the target allows remote updates of plugins.",
});
definePermission({
	name: "core.plugin.install",
	title: "Install plugin",
	description: "Remotely install a plugin if the target allows remote installs of plugins.",
});

definePermission({
	name: "core.debug.dump_ws",
	title: "Dump WebSocket",
	description: "Dump all WebSocket communicatation from the controller.",
});