Define permissions on PluginDeclaration (#988)

Adds a permissions array to PluginDeclaration, a type-level Permissions
registry that plugins extend with module augmentation, and
registerPluginPermissions() called from all entrypoints. checkPermission
and the web UI hasPermission helpers now take PermissionName so typos are
compile errors. Core definitions move into a corePermissions array that
the interface derives its keys from.

Closes #987

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: Cooldude2606 <25043174+Cooldude2606@users.noreply.github.com>
This commit is contained in:
authored and GitHub committed 2026-09-11 23:28:30 +01:00
1 parent 2aee5379b5
commit 8c03ac15ab
23 files changed
+758 -575

No files matched your search

+1
View File
@@ -402,6 +402,7 @@ async function initialize(): Promise<InitializeParameters> {
logger.info("Loading Plugin info");
const pluginInfos = await lib.loadPluginInfos(pluginList);
lib.registerPluginMessages(pluginInfos);
lib.registerPluginPermissions(pluginInfos);
lib.addPluginConfigFields(pluginInfos);
const controllerConfigPath = args.config;
+1 -1
View File
@@ -169,7 +169,7 @@ export default class ControlConnection extends BaseConnection {
}
if (typeof permission === "string") {
this.user.checkPermission(permission);
this.user.checkPermission(permission as lib.PermissionName);
return;
}
+2 -2
View File
@@ -1,7 +1,7 @@
import {
IUser, Role, SubscribableDatastore,
PermissionError, permissions,
PermissionError, PermissionName, permissions,
} from "@clusterio/lib";
import UserRecord from "./UserRecord.js";
@@ -126,7 +126,7 @@ export default class User extends UserRecord implements IUser {
this.saveRecord();
}
checkPermission(permission: string) {
checkPermission(permission: PermissionName) {
if (!permissions.has(permission)) {
throw new Error(`permission ${permission} does not exist`);
}
+37 -32
View File
@@ -1,38 +1,6 @@
import * as lib from "@clusterio/lib";
//%if multi_context
import Messages from "./messages.js";
lib.definePermission({
name: "__plugin_name__.example.permission.event",
title: "Example permission event",
description: "Example Description. Event. Change me in index.js",
grantByDefault: true,
});
lib.definePermission({
name: "__plugin_name__.example.permission.request",
title: "Example permission request",
description: "Example Description. Request. Change me in index.js",
grantByDefault: true,
});
//%endif
//%if controller & web // Subscribing requires web content and the controller
lib.definePermission({
name: "__plugin_name__.example.permission.subscribe",
title: "Example permission subscribe",
description: "Example Description. Subscribe. Change me in index.js",
grantByDefault: true,
});
//%endif
//%if web
lib.definePermission({
name: "__plugin_name__.page.view",
title: "Example page view permission",
description: "Example Description. View. Change me in index.js",
grantByDefault: true,
});
//%endif
export const plugin = {
@@ -115,6 +83,43 @@ export const plugin = {
//%if multi_context // Subscribing requires multi context
],
//%endif
//%if multi_context | web
permissions: [
//%endif
//%if multi_context
{
name: "__plugin_name__.example.permission.event",
title: "Example permission event",
description: "Example Description. Event. Change me in index.js",
grantByDefault: true,
},
{
name: "__plugin_name__.example.permission.request",
title: "Example permission request",
description: "Example Description. Request. Change me in index.js",
grantByDefault: true,
},
//%endif
//%if controller & web // Subscribing requires web content and the controller
{
name: "__plugin_name__.example.permission.subscribe",
title: "Example permission subscribe",
description: "Example Description. Subscribe. Change me in index.js",
grantByDefault: true,
},
//%endif
//%if web
{
name: "__plugin_name__.page.view",
title: "Example page view permission",
description: "Example Description. View. Change me in index.js",
grantByDefault: true,
},
//%endif
//%if multi_context | web
],
//%endif
//%if web // Web content template has an example route which is the plugin name
webEntrypoint: "./web",
@@ -57,7 +57,7 @@ export class WebPlugin extends BaseWebPlugin {
permission: "__plugin_name__.example.permission.subscribe",
//%endif
//%if !controller
permission: "__plugin_name__.example.permission.view",
permission: "__plugin_name__.page.view",
//%endif
content: <MyTemplatePage/>,
},
+55 -34
View File
@@ -1,40 +1,8 @@
import * as lib from "@clusterio/lib";
//%if multi_context
import * as Messages from "./messages.js";
lib.definePermission({
name: "__plugin_name__.example.permission.event",
title: "Example permission event",
description: "Example Description. Event. Change me in index.ts",
grantByDefault: true,
});
lib.definePermission({
name: "__plugin_name__.example.permission.request",
title: "Example permission request",
description: "Example Description. Request. Change me in index.ts",
grantByDefault: true,
});
//%endif
//%if controller & web // Subscribing requires web content and the controller
lib.definePermission({
name: "__plugin_name__.example.permission.subscribe",
title: "Example permission subscribe",
description: "Example Description. Subscribe. Change me in index.ts",
grantByDefault: true,
});
//%endif
//%if web
lib.definePermission({
name: "__plugin_name__.page.view",
title: "Example page view permission",
description: "Example Description. View. Change me in index.ts",
grantByDefault: true,
});
//%endif
//%if config
//%if config | multi_context | web
declare module "@clusterio/lib" {
//%endif
@@ -58,7 +26,23 @@ declare module "@clusterio/lib" {
"__plugin_name__.myControlField": string;
}
//%endif
//%if config
//%if multi_context | web
export interface Permissions {
//%endif
//%if multi_context
"__plugin_name__.example.permission.event": never;
"__plugin_name__.example.permission.request": never;
//%endif
//%if controller & web // Subscribing requires web content and the controller
"__plugin_name__.example.permission.subscribe": never;
//%endif
//%if web
"__plugin_name__.page.view": never;
//%endif
//%if multi_context | web
}
//%endif
//%if config | multi_context | web
}
//%endif
@@ -143,6 +127,43 @@ export const plugin: lib.PluginDeclaration = {
//%if multi_context // Subscribing requires multi context
],
//%endif
//%if multi_context | web
permissions: [
//%endif
//%if multi_context
{
name: "__plugin_name__.example.permission.event",
title: "Example permission event",
description: "Example Description. Event. Change me in index.ts",
grantByDefault: true,
},
{
name: "__plugin_name__.example.permission.request",
title: "Example permission request",
description: "Example Description. Request. Change me in index.ts",
grantByDefault: true,
},
//%endif
//%if controller & web // Subscribing requires web content and the controller
{
name: "__plugin_name__.example.permission.subscribe",
title: "Example permission subscribe",
description: "Example Description. Subscribe. Change me in index.ts",
grantByDefault: true,
},
//%endif
//%if web
{
name: "__plugin_name__.page.view",
title: "Example page view permission",
description: "Example Description. View. Change me in index.ts",
grantByDefault: true,
},
//%endif
//%if multi_context | web
],
//%endif
//%if web // Web content template has an example route which is the plugin name
webEntrypoint: "./web",
@@ -9,5 +9,5 @@
"noEmitOnError": true,
"outDir": "${configDir}/dist/browser",
},
"include": [ "web/**/*.tsx", "web/**/*.ts", "messages.ts", "package.json" ],
"include": [ "web/**/*.tsx", "web/**/*.ts", "index.ts", "messages.ts", "package.json" ],
}
@@ -57,7 +57,7 @@ export class WebPlugin extends BaseWebPlugin {
permission: "__plugin_name__.example.permission.subscribe",
//%endif
//%if !controller
permission: "__plugin_name__.example.permission.view",
permission: "__plugin_name__.page.view",
//%endif
content: <MyTemplatePage/>,
},
+1
View File
@@ -108,6 +108,7 @@ export class Control extends lib.Link {
async function loadPlugins(pluginList: Map<string, string>) {
let pluginInfos = await lib.loadPluginInfos(pluginList);
lib.registerPluginMessages(pluginInfos);
lib.registerPluginPermissions(pluginInfos);
lib.addPluginConfigFields(pluginInfos);
let ctlPlugins = new Map<string, BaseCtlPlugin>();
+1
View File
@@ -163,6 +163,7 @@ async function startHost() {
logger.info("Loading Plugin info");
let pluginInfos = await lib.loadPluginInfos(pluginList);
lib.registerPluginMessages(pluginInfos);
lib.registerPluginPermissions(pluginInfos);
lib.addPluginConfigFields(pluginInfos);
const hostConfigPath = args.config;
+2 -2
View File
@@ -1,5 +1,5 @@
import { Static, Type } from "@sinclair/typebox";
import type { PermissionName } from "../permissions.js";
import PlayerStats from "./PlayerStats.js";
/** Represents a user in the cluster */
@@ -164,5 +164,5 @@ export interface IUser extends UserDetails {
* @throws {Error} If the given permission does not exist.
* @throws {libErrors.PermissionError} if the user does noh have the given permission.
*/
checkPermission(permission: string): void
checkPermission(permission: PermissionName): void
}
File diff suppressed because it is too large. Load diff
+2 -1
View File
@@ -5,9 +5,9 @@
import * as libHelpers from "./helpers.js";
import type { Logger } from "./logging.js";
import type { FieldDefinition } from "./config/index.js";
import type { PermissionDefinition } from "./permissions.js";
import type { PlayerStats } from "./data/index.js";
export const PluginFeatureFlags = [
/** The plugin requires module code to be patched into the save */
"SavePatching",
@@ -37,6 +37,7 @@ export type PluginDeclaration = {
features?: (typeof PluginFeatureFlags)[number][];
messages?: any[];
permissions?: PermissionDefinition[];
routes?: string[];
}
+2 -1
View File
@@ -2,6 +2,7 @@ import { Type, Static } from "@sinclair/typebox";
import { Link, Event, EventClass, RequestHandler, WebSocketBaseConnector } from "./link/index.js";
import { Address, MessageRequest, IUser, JsonBoolean, StringEnum } from "./data/index.js";
import isDeepStrictEqual from "#is_deep_strict_equal";
import type { PermissionName } from "./permissions.js";
import { RequestError } from "./errors.js";
import { logger } from "./logging.js";
@@ -155,7 +156,7 @@ export class SubscriptionRequest {
const entry = Link._eventsByName.get(data[0]);
if (entry && entry.Event.permission) {
if (typeof entry.Event.permission === "string") {
user.checkPermission(entry.Event.permission);
user.checkPermission(entry.Event.permission as PermissionName);
} else {
entry.Event.permission(user, message);
}
+5 -5
View File
@@ -1,5 +1,5 @@
import type React from "react";
import type { AccountRole, FieldDefinition, Logger, PluginWebpackEnvInfo } from "@clusterio/lib";
import type { AccountRole, FieldDefinition, Logger, PermissionName, PluginWebpackEnvInfo } from "@clusterio/lib";
import type { Control } from "./util/websocket";
/**
@@ -37,11 +37,11 @@ export type UserAccount = {
/** Roles of the corrently logged in account. */
roles: AccountRole[];
/** Check if the currently logged in account has the given permission. */
hasPermission: (permission: string) => boolean | null;
hasPermission: (permission: PermissionName) => boolean | null;
/** Check if the currently logged in account has any of the given permissions. */
hasAnyPermission: (...permissions: string[]) => boolean | null;
hasAnyPermission: (...permissions: PermissionName[]) => boolean | null;
/** Check if the currently logged in account has all of given permissions. */
hasAllPermission: (...permissions: string[]) => boolean | null;
hasAllPermission: (...permissions: PermissionName[]) => boolean | null;
/** Logs out of the web interface. */
logOut: () => void;
};
@@ -75,7 +75,7 @@ export interface PluginPage {
/**
* Permission to access page. function are expected to throw an error if access is deny.
*/
permission?: string | ((account: UserAccount) => (boolean|null));
permission?: PermissionName | ((account: UserAccount) => (boolean|null));
};
/**
+1
View File
@@ -136,6 +136,7 @@ export default async function bootstrap() {
}));
let [pluginInfos, pluginSetKey] = await loadPluginInfos();
lib.registerPluginMessages(pluginInfos);
lib.registerPluginPermissions(pluginInfos);
lib.addPluginConfigFields(pluginInfos);
let wsUrl = new URL(webRoot, document.location.href);
+5 -5
View File
@@ -22,13 +22,13 @@ export function useAccount(): UserAccount {
};
}, [control]);
function checkPermissionExists(permission: string) {
function checkPermissionExists(permission: lib.PermissionName) {
if (!lib.permissions.has(permission)) {
throw new Error(`permission ${permission} does not exist`);
}
}
function hasPermission(permission: string): boolean {
function hasPermission(permission: lib.PermissionName): boolean {
for (let role of roles) {
if (role.permissions.includes("core.admin") || role.permissions.includes(permission)) {
return true;
@@ -40,14 +40,14 @@ export function useAccount(): UserAccount {
return {
name,
roles,
hasPermission(permission: string): boolean | null {
hasPermission(permission: lib.PermissionName): boolean | null {
if (!roles) {
return null;
}
checkPermissionExists(permission);
return hasPermission(permission);
},
hasAnyPermission(...permissions: string[]): boolean | null {
hasAnyPermission(...permissions: lib.PermissionName[]): boolean | null {
if (!roles) {
return null;
}
@@ -61,7 +61,7 @@ export function useAccount(): UserAccount {
}
return false;
},
hasAllPermission(...permissions: string[]): boolean | null {
hasAllPermission(...permissions: lib.PermissionName[]): boolean | null {
if (!roles) {
return null;
}