@helyx/bot 1.1.0 → 1.2.0

package/dist/discord-member-enforcement-service.js

@@ -0,0 +1,590 @@
+import { PermissionFlagsBits, RESTJSONErrorCodes, } from "discord.js";
+import { DiscordMemberEnforcementService } from "./events.js";
+import { toReplyOptions } from "./interactions.js";
+const SNOWFLAKE_PATTERN = /^\d{17,20}$/u;
+const MODULE_ID_PATTERN = /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)+$/u;
+const OPERATION_KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$/u;
+const MAX_TIMEOUT_SECONDS = 2_419_200;
+const MAX_DEMOTION_ROLES = 10;
+// Global and rule-specific exemptions can each contain 25 roles. The guild's
+// @everyone role is included separately by the Moderation caller.
+const MAX_PROTECTED_ROLES = 51;
+const DIRECT_MESSAGE_TIMEOUT_MS = 2_000;
+/** Extended Moderation adapter, leaving the legacy enforcement class unchanged. */
+export class DiscordModerationMemberEnforcementAdapter {
+    client;
+    #legacy;
+    constructor(client) {
+        this.client = client;
+        this.#legacy = new DiscordMemberEnforcementService(client);
+    }
+    kick(input) {
+        return this.#legacy.kick(input);
+    }
+    ban(input) {
+        return this.#legacy.ban(input);
+    }
+    async inspectMember(input) {
+        validateSnowflake(input.guildId);
+        validateSnowflake(input.memberUserId);
+        if (input.actorUserId)
+            validateSnowflake(input.actorUserId);
+        const guild = this.#ownedGuild(input.guildId);
+        if (!guild)
+            return { outcome: "failed", safeCode: "guild_not_owned" };
+        const memberInspection = await fetchMemberInspection(guild, input.memberUserId);
+        if (memberInspection.outcome === "missing")
+            return { outcome: "member_missing" };
+        if (memberInspection.outcome === "failed")
+            return { outcome: "failed", safeCode: "member_inspection_failed" };
+        const member = memberInspection.member;
+        const actorInspection = input.actorUserId
+            ? await fetchMemberInspection(guild, input.actorUserId)
+            : null;
+        const actor = actorInspection?.outcome === "present" ? actorInspection.member : null;
+        const me = guild.members.me ?? (await guild.members.fetchMe().catch(() => null));
+        return {
+            outcome: "present",
+            memberUserId: member.id,
+            isGuildOwner: member.id === guild.ownerId,
+            isAdministrator: member.permissions.has(PermissionFlagsBits.Administrator),
+            isBot: member.user.bot,
+            roleIds: [...member.roles.cache.keys()].sort(),
+            effectivePermissionNames: member.permissions.toArray().sort(),
+            actorHierarchy: hierarchy(actor, member, guild.ownerId),
+            helyxHierarchy: hierarchy(me, member, guild.ownerId),
+            timeoutEndsAt: member.communicationDisabledUntil,
+        };
+    }
+    async inspectBan(input) {
+        validateSnowflake(input.guildId);
+        validateSnowflake(input.userId);
+        const guild = this.#ownedGuild(input.guildId);
+        if (!guild)
+            return { outcome: "failed", safeCode: "guild_not_owned" };
+        if (!guild.members.me?.permissions.has(PermissionFlagsBits.BanMembers))
+            return { outcome: "missing_permission", safeCode: "ban_members" };
+        try {
+            const ban = await guild.bans.fetch(input.userId);
+            return ban.user.id === input.userId
+                ? { outcome: "banned", userId: ban.user.id }
+                : { outcome: "failed", safeCode: "ban_identity_mismatch" };
+        }
+        catch (error) {
+            return hasDiscordCode(error, RESTJSONErrorCodes.UnknownBan)
+                ? { outcome: "not_banned" }
+                : { outcome: "failed", safeCode: "ban_inspection_failed" };
+        }
+    }
+    async kickMember(input) {
+        validateModernInput(input);
+        const initial = await this.#inspectKick(input);
+        if (initial.outcome !== "ready")
+            return initial.result;
+        if (!(await safelyRevalidate(() => input.revalidate())))
+            return {
+                outcome: "no_longer_required",
+                directMessage: "not_requested",
+            };
+        // Re-fetch after policy revalidation so a hierarchy, membership or
+        // permission change cannot slip between the check and the Discord effect.
+        const current = await this.#inspectKick(input, true);
+        if (current.outcome !== "ready")
+            return current.result;
+        const directMessage = await this.#directMessage(input.memberUserId, input.directMessage);
+        try {
+            await current.member.kick(auditReason(input));
+            return { outcome: "succeeded", directMessage };
+        }
+        catch (error) {
+            return failure(error, directMessage);
+        }
+    }
+    async banMember(input) {
+        validateModernInput(input);
+        const guild = this.#ownedGuild(input.guildId);
+        if (!guild)
+            return {
+                outcome: "failed",
+                directMessage: "not_requested",
+                safeCode: "guild_not_owned",
+            };
+        if (!guild.members.me?.permissions.has(PermissionFlagsBits.BanMembers))
+            return {
+                outcome: "missing_permission",
+                directMessage: "not_requested",
+                safeCode: "ban_members",
+            };
+        const memberInspection = await fetchMemberInspection(guild, input.memberUserId);
+        if (memberInspection.outcome === "failed")
+            return {
+                outcome: "failed",
+                directMessage: "not_requested",
+                safeCode: "member_inspection_failed",
+            };
+        const member = memberInspection.outcome === "present" ? memberInspection.member : null;
+        if (member && !member.bannable)
+            return { outcome: "hierarchy_blocked", directMessage: "not_requested" };
+        let existingBan;
+        try {
+            existingBan = await fetchBan(guild, input.memberUserId);
+        }
+        catch {
+            return {
+                outcome: "failed",
+                directMessage: "not_requested",
+                safeCode: "ban_inspection_failed",
+            };
+        }
+        if (existingBan)
+            return { outcome: "already_applied", directMessage: "not_requested" };
+        if (!(await safelyRevalidate(() => input.revalidate())))
+            return {
+                outcome: "no_longer_required",
+                directMessage: "not_requested",
+            };
+        const currentBan = await fetchBan(guild, input.memberUserId).catch(() => undefined);
+        if (currentBan === undefined)
+            return {
+                outcome: "failed",
+                directMessage: "not_requested",
+                safeCode: "ban_inspection_failed",
+            };
+        if (currentBan)
+            return { outcome: "already_applied", directMessage: "not_requested" };
+        const currentMember = await fetchMemberInspection(guild, input.memberUserId, true);
+        if (currentMember.outcome === "failed")
+            return {
+                outcome: "failed",
+                directMessage: "not_requested",
+                safeCode: "member_inspection_failed",
+            };
+        if (currentMember.outcome === "present" && !currentMember.member.bannable)
+            return { outcome: "hierarchy_blocked", directMessage: "not_requested" };
+        const directMessage = await this.#directMessage(input.memberUserId, input.directMessage);
+        try {
+            await guild.members.ban(input.memberUserId, {
+                deleteMessageSeconds: input.deleteMessageSeconds,
+                reason: auditReason(input),
+            });
+            return { outcome: "succeeded", directMessage };
+        }
+        catch (error) {
+            return failure(error, directMessage);
+        }
+    }
+    async timeout(input) {
+        validateModernInput(input);
+        if (!Number.isInteger(input.durationSeconds) ||
+            input.durationSeconds < 60 ||
+            input.durationSeconds > MAX_TIMEOUT_SECONDS)
+            throw new Error("Member timeout duration is invalid");
+        const resolved = await this.#moderatableMember(input);
+        if (resolved.outcome)
+            return {
+                outcome: resolved.outcome,
+                directMessage: "not_requested",
+                ...(resolved.safeCode ? { safeCode: resolved.safeCode } : {}),
+            };
+        const expectedEnd = Date.now() + input.durationSeconds * 1_000;
+        if (resolved.member.communicationDisabledUntilTimestamp &&
+            resolved.member.communicationDisabledUntilTimestamp >= expectedEnd - 1_000)
+            return { outcome: "already_applied", directMessage: "not_requested" };
+        if (!(await safelyRevalidate(() => input.revalidate())))
+            return {
+                outcome: "no_longer_required",
+                directMessage: "not_requested",
+            };
+        const current = await this.#moderatableMember(input, true);
+        if (current.outcome)
+            return {
+                outcome: current.outcome,
+                directMessage: "not_requested",
+                ...(current.safeCode ? { safeCode: current.safeCode } : {}),
+            };
+        if (current.member.communicationDisabledUntilTimestamp &&
+            current.member.communicationDisabledUntilTimestamp >= expectedEnd - 1_000)
+            return { outcome: "already_applied", directMessage: "not_requested" };
+        const directMessage = await this.#directMessage(input.memberUserId, input.directMessage);
+        try {
+            await current.member.timeout(input.durationSeconds * 1_000, auditReason(input));
+            return { outcome: "succeeded", directMessage };
+        }
+        catch (error) {
+            return failure(error, directMessage);
+        }
+    }
+    async removeTimeout(input) {
+        validateModernInput(input);
+        const resolved = await this.#moderatableMember(input);
+        if (resolved.outcome)
+            return withoutDirectMessage(resolved);
+        if (!resolved.member.communicationDisabledUntilTimestamp)
+            return { outcome: "already_applied" };
+        if (!(await safelyRevalidate(() => input.revalidate())))
+            return { outcome: "no_longer_required" };
+        const current = await this.#moderatableMember(input, true);
+        if (current.outcome)
+            return withoutDirectMessage(current);
+        if (!current.member.communicationDisabledUntilTimestamp)
+            return { outcome: "already_applied" };
+        try {
+            await current.member.timeout(null, auditReason(input));
+            return { outcome: "succeeded" };
+        }
+        catch (error) {
+            return withoutDirectMessage(failure(error, "not_requested"));
+        }
+    }
+    async unban(input) {
+        validateModernInput({ ...input, memberUserId: input.userId });
+        const guild = this.#ownedGuild(input.guildId);
+        if (!guild)
+            return { outcome: "failed", safeCode: "guild_not_owned" };
+        if (!guild.members.me?.permissions.has(PermissionFlagsBits.BanMembers))
+            return { outcome: "missing_permission", safeCode: "ban_members" };
+        try {
+            if (!(await fetchBan(guild, input.userId)))
+                return { outcome: "already_applied" };
+        }
+        catch {
+            return { outcome: "failed", safeCode: "ban_inspection_failed" };
+        }
+        if (!(await safelyRevalidate(() => input.revalidate())))
+            return { outcome: "no_longer_required" };
+        let currentBan;
+        try {
+            currentBan = await fetchBan(guild, input.userId);
+        }
+        catch {
+            return { outcome: "failed", safeCode: "ban_inspection_failed" };
+        }
+        if (!currentBan)
+            return { outcome: "already_applied" };
+        try {
+            await guild.members.unban(input.userId, auditReason(input));
+            return { outcome: "succeeded" };
+        }
+        catch (error) {
+            return withoutDirectMessage(failure(error, "not_requested"));
+        }
+    }
+    async removeConfiguredRoles(input) {
+        validateModernInput(input);
+        validateRoleRemovalInput(input.roleIds, input.protectedRoleIds);
+        const initial = await this.#inspectRoleRemoval(input);
+        if (initial.outcome !== "ready")
+            return initial.result;
+        if (initial.removableRoleIds.length === 0)
+            return {
+                outcome: "already_applied",
+                removedRoleIds: [],
+                alreadyAbsentRoleIds: initial.alreadyAbsentRoleIds,
+            };
+        if (!(await safelyRevalidate(() => input.revalidate())))
+            return { outcome: "no_longer_required" };
+        // Refresh the member and every selected role after policy revalidation. No
+        // mutation occurs unless the complete second preflight still succeeds.
+        const current = await this.#inspectRoleRemoval(input, true);
+        if (current.outcome !== "ready")
+            return current.result;
+        if (current.removableRoleIds.length === 0)
+            return {
+                outcome: "already_applied",
+                removedRoleIds: [],
+                alreadyAbsentRoleIds: current.alreadyAbsentRoleIds,
+            };
+        try {
+            await current.member.roles.remove(current.removableRoleIds, auditReason(input));
+            return {
+                outcome: "succeeded",
+                removedRoleIds: current.removableRoleIds,
+                alreadyAbsentRoleIds: current.alreadyAbsentRoleIds,
+            };
+        }
+        catch (error) {
+            if (hasDiscordCode(error, RESTJSONErrorCodes.UnknownMember))
+                return { outcome: "member_missing" };
+            if (isMissingPermissionError(error))
+                return { outcome: "missing_permission", safeCode: "manage_roles" };
+            return typeof error === "object" && error !== null && "code" in error
+                ? {
+                    outcome: "failed",
+                    safeCode: `discord_${String(error.code)}`.slice(0, 80),
+                }
+                : { outcome: "ambiguous", safeCode: "discord_transport_unknown" };
+        }
+    }
+    #ownedGuild(guildId) {
+        return this.client.guilds.cache.get(guildId) ?? null;
+    }
+    async #moderatableMember(input, force = false) {
+        const guild = this.#ownedGuild(input.guildId);
+        if (!guild)
+            return { outcome: "failed", safeCode: "guild_not_owned" };
+        if (!guild.members.me?.permissions.has(PermissionFlagsBits.ModerateMembers))
+            return { outcome: "missing_permission", safeCode: "moderate_members" };
+        const inspection = await fetchMemberInspection(guild, input.memberUserId, force);
+        if (inspection.outcome === "missing")
+            return { outcome: "member_missing" };
+        if (inspection.outcome === "failed")
+            return { outcome: "failed", safeCode: "member_inspection_failed" };
+        const member = inspection.member;
+        return member.moderatable
+            ? { outcome: null, member }
+            : { outcome: "hierarchy_blocked" };
+    }
+    async #inspectKick(input, force = false) {
+        const guild = this.#ownedGuild(input.guildId);
+        if (!guild)
+            return {
+                outcome: "blocked",
+                result: {
+                    outcome: "failed",
+                    directMessage: "not_requested",
+                    safeCode: "guild_not_owned",
+                },
+            };
+        const me = guild.members.me ?? (await guild.members.fetchMe().catch(() => null));
+        if (!me?.permissions.has(PermissionFlagsBits.KickMembers))
+            return {
+                outcome: "blocked",
+                result: {
+                    outcome: "missing_permission",
+                    directMessage: "not_requested",
+                    safeCode: "kick_members",
+                },
+            };
+        const inspection = await fetchMemberForRoleRemoval(guild, input.memberUserId, force);
+        if (inspection.outcome === "missing")
+            return {
+                outcome: "blocked",
+                result: { outcome: "member_missing", directMessage: "not_requested" },
+            };
+        if (inspection.outcome === "failed")
+            return {
+                outcome: "blocked",
+                result: {
+                    outcome: "failed",
+                    directMessage: "not_requested",
+                    safeCode: "member_inspection_failed",
+                },
+            };
+        if (!inspection.member.kickable)
+            return {
+                outcome: "blocked",
+                result: {
+                    outcome: "hierarchy_blocked",
+                    directMessage: "not_requested",
+                },
+            };
+        return { outcome: "ready", member: inspection.member };
+    }
+    async #inspectRoleRemoval(input, force = false) {
+        const guild = this.#ownedGuild(input.guildId);
+        if (!guild)
+            return {
+                outcome: "blocked",
+                result: { outcome: "failed", safeCode: "guild_not_owned" },
+            };
+        const me = guild.members.me ?? (await guild.members.fetchMe().catch(() => null));
+        if (!me?.permissions.has(PermissionFlagsBits.ManageRoles))
+            return {
+                outcome: "blocked",
+                result: { outcome: "missing_permission", safeCode: "manage_roles" },
+            };
+        const memberInspection = await fetchMemberForRoleRemoval(guild, input.memberUserId, force);
+        if (memberInspection.outcome === "missing")
+            return { outcome: "blocked", result: { outcome: "member_missing" } };
+        if (memberInspection.outcome === "failed")
+            return {
+                outcome: "blocked",
+                result: { outcome: "failed", safeCode: "member_inspection_failed" },
+            };
+        const member = memberInspection.member;
+        const alreadyAbsentRoleIds = [];
+        const removableRoleIds = [];
+        const blockedRoleIds = [];
+        const protectedRoleIds = new Set(input.protectedRoleIds);
+        for (const roleId of input.roleIds) {
+            if (!member.roles.cache.has(roleId)) {
+                alreadyAbsentRoleIds.push(roleId);
+                continue;
+            }
+            const role = await guild.roles.fetch(roleId).catch(() => null);
+            if (!role ||
+                role.id === guild.roles.everyone.id ||
+                protectedRoleIds.has(role.id) ||
+                role.managed ||
+                !role.editable ||
+                role.comparePositionTo(me.roles.highest) >= 0 ||
+                !member.manageable) {
+                blockedRoleIds.push(roleId);
+                continue;
+            }
+            removableRoleIds.push(roleId);
+        }
+        if (blockedRoleIds.length > 0)
+            return {
+                outcome: "blocked",
+                result: { outcome: "hierarchy_blocked", blockedRoleIds },
+            };
+        return {
+            outcome: "ready",
+            member,
+            removableRoleIds,
+            alreadyAbsentRoleIds,
+        };
+    }
+    async #directMessage(userId, response) {
+        if (!response)
+            return "not_requested";
+        const attempt = async () => {
+            try {
+                const user = await this.client.users.fetch(userId);
+                await user.send(toReplyOptions({
+                    ...response,
+                    ephemeral: false,
+                }));
+                return "sent";
+            }
+            catch (error) {
+                return hasDiscordCode(error, RESTJSONErrorCodes.CannotSendMessagesToThisUser)
+                    ? "closed"
+                    : "failed";
+            }
+        };
+        return await withTimeout(attempt(), DIRECT_MESSAGE_TIMEOUT_MS, "failed");
+    }
+}
+async function fetchMemberInspection(guild, userId, force = false) {
+    try {
+        const member = await guild.members.fetch(force ? { user: userId, force: true } : userId);
+        return member.id === userId && member.guild.id === guild.id
+            ? { outcome: "present", member }
+            : { outcome: "failed" };
+    }
+    catch (error) {
+        return hasDiscordCode(error, RESTJSONErrorCodes.UnknownMember)
+            ? { outcome: "missing" }
+            : { outcome: "failed" };
+    }
+}
+async function fetchMemberForRoleRemoval(guild, userId, force) {
+    try {
+        const member = await guild.members.fetch({ user: userId, force });
+        return member.id === userId && member.guild.id === guild.id
+            ? { outcome: "present", member }
+            : { outcome: "failed" };
+    }
+    catch (error) {
+        return hasDiscordCode(error, RESTJSONErrorCodes.UnknownMember)
+            ? { outcome: "missing" }
+            : { outcome: "failed" };
+    }
+}
+async function fetchBan(guild, userId) {
+    try {
+        return await guild.bans.fetch(userId);
+    }
+    catch (error) {
+        if (hasDiscordCode(error, RESTJSONErrorCodes.UnknownBan))
+            return null;
+        throw error;
+    }
+}
+function hierarchy(actor, target, ownerId) {
+    if (!actor)
+        return "unknown";
+    if (actor.id === ownerId)
+        return "above";
+    return actor.roles.highest.comparePositionTo(target.roles.highest) > 0
+        ? "above"
+        : "equal_or_below";
+}
+function validateModernInput(input) {
+    validateSnowflake(input.guildId);
+    validateSnowflake(input.memberUserId);
+    if (!MODULE_ID_PATTERN.test(input.moduleId) ||
+        !OPERATION_KEY_PATTERN.test(input.operationKey) ||
+        input.reason.trim().length < 1 ||
+        input.reason.length > 400 ||
+        /[\r\n]/u.test(input.reason))
+        throw new Error("Member enforcement metadata is invalid");
+}
+function validateRoleRemovalInput(roleIds, protectedRoleIds) {
+    if (roleIds.length < 1 ||
+        roleIds.length > MAX_DEMOTION_ROLES ||
+        protectedRoleIds.length > MAX_PROTECTED_ROLES ||
+        new Set(roleIds).size !== roleIds.length ||
+        new Set(protectedRoleIds).size !== protectedRoleIds.length)
+        throw new Error("Member role removal selection is invalid");
+    for (const roleId of [...roleIds, ...protectedRoleIds])
+        validateSnowflake(roleId);
+}
+function validateSnowflake(value) {
+    if (!SNOWFLAKE_PATTERN.test(value))
+        throw new Error("Member enforcement Discord identity is invalid");
+}
+function auditReason(input) {
+    return `Helyx ${input.moduleId} ${input.operationKey}: ${input.reason.trim()}`.slice(0, 512);
+}
+async function safelyRevalidate(callback) {
+    try {
+        return await callback();
+    }
+    catch {
+        return false;
+    }
+}
+function failure(error, directMessage) {
+    if (hasDiscordCode(error, RESTJSONErrorCodes.UnknownMember))
+        return { outcome: "already_applied", directMessage };
+    if (typeof error === "object" && error !== null && "code" in error)
+        return {
+            outcome: "failed",
+            directMessage,
+            safeCode: `discord_${String(error.code)}`.slice(0, 80),
+        };
+    return {
+        outcome: "ambiguous",
+        directMessage,
+        safeCode: "discord_transport_unknown",
+    };
+}
+function withoutDirectMessage(input) {
+    return {
+        outcome: input.outcome,
+        ...(input.safeCode ? { safeCode: input.safeCode } : {}),
+    };
+}
+function hasDiscordCode(error, code) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === code);
+}
+function isMissingPermissionError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "status" in error &&
+        error.status === 403);
+}
+async function withTimeout(promise, timeoutMs, fallback) {
+    return await new Promise((resolve) => {
+        let settled = false;
+        const timer = setTimeout(() => {
+            settled = true;
+            resolve(fallback);
+        }, timeoutMs);
+        timer.unref();
+        void promise.then((value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(value);
+        });
+    });
+}
+//# sourceMappingURL=discord-member-enforcement-service.js.map

package/dist/discord-message-enforcement-service.d.ts

@@ -0,0 +1,9 @@
+import type { MessageEnforcementService } from "@helyx/sdk";
+import { type Client } from "discord.js";
+/** Deletes only a positively identified member-authored guild message. */
+export declare class DiscordMessageEnforcementAdapter implements MessageEnforcementService {
+    private readonly client;
+    constructor(client: Client);
+    deleteMemberMessage(input: Parameters<MessageEnforcementService["deleteMemberMessage"]>[0]): ReturnType<MessageEnforcementService["deleteMemberMessage"]>;
+}
+//# sourceMappingURL=discord-message-enforcement-service.d.ts.map