koishi-plugin-new-auth 0.1.0

package/README.md

@@ -0,0 +1,69 @@
+# koishi-plugin-new-auth
+
+`koishi-plugin-new-auth` is a conservative role and scope based command permission layer for Koishi.
+
+It implements the first usable version described in `newauth.md`:
+
+- commands are registered into a permission table;
+- newly discovered commands are `pending` by default;
+- pending commands are executable only by Bot administrators;
+- Koishi's legacy `authority` value is recorded as a suggestion, not used as the final grant;
+- policies are evaluated by `scope + role + command`;
+- guild owner/admin/member roles are separated from Bot administrator;
+- custom roles and role members can be managed from Koishi commands.
+
+## Configuration
+
+```ts
+export default {
+  plugins: {
+    'new-auth': {
+      botAdmins: ['onebot:10000'],
+    },
+  },
+}
+```
+
+`botAdmins` are explicit Koishi instance administrators. Platform guild owners are not treated as Bot administrators.
+
+The plugin also has a compatibility fallback for existing Koishi installations: users with `authority >= legacyAdminAuthority` are treated as Bot administrators when `trustLegacyAuthorityAsAdmin` is enabled.
+
+## Commands
+
+All management commands are under `newauth`.
+
+```txt
+newauth.commands --pending
+newauth.roles
+newauth.allow <roleId> <command> [scope]
+newauth.deny <roleId> <command> [scope]
+newauth.inherit <roleId> <command> [scope]
+newauth.disable <command>
+newauth.enable <command>
+newauth.admin.add <uid>
+newauth.admin.remove <uid>
+newauth.role.create <id> <name> [scopeType]
+newauth.member.add <roleId> <uid> [scope]
+newauth.member.remove <roleId> <uid> [scope]
+```
+
+`uid` uses `platform:userId`, for example `onebot:10000`.
+
+`scope` can be:
+
+- `global`
+- `guild:<platform>:<guildId>`
+
+When `scope` is omitted, policy commands use `global`.
+
+## Built-In Roles
+
+```txt
+bot-admin
+guild-owner
+guild-admin
+guild-member
+guest
+```
+
+Custom roles do not inherit from other roles. To give a custom role access to a command, add an explicit policy with `newauth.allow`.

package/lib/index.d.ts

@@ -0,0 +1,151 @@
+import { Command, Context, Schema, Session } from 'koishi';
+import type { Argv } from 'koishi';
+export declare const name = "new-auth";
+export declare const inject: string[];
+type RoleType = 'builtin' | 'custom';
+type ScopeType = 'global' | 'guild';
+type CommandStatus = 'pending' | 'configured' | 'disabled';
+type PolicyState = 'inherit' | 'allow' | 'deny';
+export interface NewAuthCommandRecord {
+    id: string;
+    name: string;
+    commandPath: string;
+    aliases: string[];
+    plugin: string;
+    description: string;
+    legacyAuthority: number;
+    status: CommandStatus;
+    allowGuildOverride: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface NewAuthRoleRecord {
+    id: string;
+    name: string;
+    type: RoleType;
+    scopeType: ScopeType;
+    builtin: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface NewAuthRoleMemberRecord {
+    roleId: string;
+    platform: string;
+    userId: string;
+    scope: string;
+    createdAt: Date;
+}
+export interface NewAuthPolicyRecord {
+    scope: string;
+    roleId: string;
+    commandId: string;
+    state: PolicyState;
+    updatedAt: Date;
+}
+declare module 'koishi' {
+    interface Tables {
+        new_auth_command: NewAuthCommandRecord;
+        new_auth_role: NewAuthRoleRecord;
+        new_auth_role_member: NewAuthRoleMemberRecord;
+        new_auth_policy: NewAuthPolicyRecord;
+    }
+    interface Context {
+        newauth: NewAuthService;
+    }
+}
+export interface Config {
+    botAdmins: string[];
+    trustLegacyAuthorityAsAdmin: boolean;
+    legacyAdminAuthority: number;
+    ownerRoleNames: string[];
+    adminRoleNames: string[];
+    allowGuildOverrideAuthorityMax: number;
+    deniedMessage: string;
+    grantRuntimeCommandPermission: boolean;
+    raiseLegacyAuthority: boolean;
+}
+export declare const Config: Schema<Config>;
+export declare function apply(ctx: Context, config: Config): void;
+export declare class NewAuthService {
+    private ctx;
+    private config;
+    private commandCache;
+    private adminSet;
+    private ownerRoleNames;
+    private adminRoleNames;
+    constructor(ctx: Context, config: Config);
+    start(): Promise<void>;
+    registerCommand(command: Command): Promise<string | undefined>;
+    intercept(argv: Argv): Promise<string | undefined>;
+    canExecute(session: Session, commandId: string): Promise<{
+        allowed: boolean;
+        reason: "command_missing";
+        command?: undefined;
+        roles?: undefined;
+        matchedRole?: undefined;
+        matchedScope?: undefined;
+    } | {
+        allowed: boolean;
+        reason: "command_disabled";
+        command: NewAuthCommandRecord;
+        roles?: undefined;
+        matchedRole?: undefined;
+        matchedScope?: undefined;
+    } | {
+        allowed: boolean;
+        reason: "bot_admin";
+        command: NewAuthCommandRecord;
+        roles: string[];
+        matchedRole?: undefined;
+        matchedScope?: undefined;
+    } | {
+        allowed: boolean;
+        reason: "command_pending";
+        command: NewAuthCommandRecord;
+        roles: string[];
+        matchedRole?: undefined;
+        matchedScope?: undefined;
+    } | {
+        allowed: boolean;
+        reason: "role_policy";
+        command: NewAuthCommandRecord;
+        roles: string[];
+        matchedRole: string;
+        matchedScope: string;
+    } | {
+        allowed: boolean;
+        reason: "no_policy";
+        command: NewAuthCommandRecord;
+        roles: string[];
+        matchedRole?: undefined;
+        matchedScope?: undefined;
+    }>;
+    resolveRoles(session: Session): Promise<string[]>;
+    isBotAdmin(session: Session): Promise<boolean>;
+    listCommands(options?: {
+        pending?: boolean;
+        all?: boolean;
+        query?: string;
+    }): Promise<NewAuthCommandRecord[]>;
+    listRoles(): Promise<NewAuthRoleRecord[]>;
+    addBotAdmin(uid: string): Promise<void>;
+    removeBotAdmin(uid: string): Promise<void>;
+    createCustomRole(id: string, name: string, scopeType?: ScopeType): Promise<void>;
+    addRoleMember(roleId: string, uid: string, scope?: string): Promise<void>;
+    removeRoleMember(roleId: string, uid: string, scope?: string): Promise<void>;
+    setCommandStatus(input: string, status: CommandStatus): Promise<NewAuthCommandRecord>;
+    setCommandPolicy(scope: string, roleId: string, input: string, state: PolicyState): Promise<NewAuthCommandRecord>;
+    getCommand(input: string): Promise<NewAuthCommandRecord>;
+    private ensureBuiltinRoles;
+    private createCommandRecord;
+    private getDescription;
+    private resolveCommandInput;
+    private setPolicy;
+    private getEffectivePolicy;
+    private ensureRoleMember;
+    private hasPlatformRole;
+    private grantRuntimeCommandPermission;
+    private getCommandList;
+    private isSelfCommand;
+}
+export {};