@helyx/bot 0.4.9 → 0.4.13

package/dist/events.js

@@ -1,7 +1,23 @@
 import { HELYX_SERVICE_NAMES } from "@helyx/sdk";
-import { ChannelType, Events, PermissionFlagsBits, RESTJSONErrorCodes, } from "discord.js";
+import { VerificationSetupLeaseLostError } from "@helyx/database";
+import { ChannelType, Events, GatewayIntentBits, GuildMemberFlags, GuildOnboardingMode, PermissionFlagsBits, RESTJSONErrorCodes, UserFlags, } from "discord.js";
 import { toReplyOptions } from "./interactions.js";
+import { createHash, randomUUID } from "node:crypto";
+import { classifyGuildMessage, unavailableGuildMessageClassification, } from "./message-classification.js";
 export function installModuleEvents(client, modules, logger, services) {
+    const privilegedMessageContributions = modules.flatMap((module) => (module.events?.privilegedMessageCreate ?? []).map((contribution) => ({
+        moduleId: module.manifest.id,
+        contribution,
+    })));
+    const guildMessageContributions = modules.flatMap((module) => (module.events?.guildMessageCreate ?? []).map((contribution) => ({
+        moduleId: module.manifest.id,
+        classificationRequested: module.requiredDiscordCapabilities?.includes("message-content") ??
+            false,
+        contribution,
+    })));
+    const messageClassificationRequested = modules.some((module) => module.requiredDiscordCapabilities?.includes("message-content"));
+    const messageClassificationAvailable = messageClassificationRequested &&
+        client.options.intents.has(GatewayIntentBits.MessageContent);
     const reactionContributions = modules.flatMap((module) => (module.events?.messageReactionAdd ?? []).map((contribution) => ({
         moduleId: module.manifest.id,
         contribution,
@@ -18,6 +34,10 @@ export function installModuleEvents(client, modules, logger, services) {
         moduleId: module.manifest.id,
         contribution,
     })));
+    const memberRemoveContributions = modules.flatMap((module) => (module.events?.guildMemberRemove ?? []).map((contribution) => ({
+        moduleId: module.manifest.id,
+        contribution,
+    })));
     const guildRoleDeleteContributions = modules.flatMap((module) => (module.events?.guildRoleDelete ?? []).map((contribution) => ({
         moduleId: module.manifest.id,
         contribution,
@@ -42,10 +62,13 @@ export function installModuleEvents(client, modules, logger, services) {
         moduleId: module.manifest.id,
         contribution,
     })));
-    if (reactionContributions.length === 0 &&
+    if (privilegedMessageContributions.length === 0 &&
+        guildMessageContributions.length === 0 &&
+        reactionContributions.length === 0 &&
         reactionRemoveContributions.length === 0 &&
         messageDeleteContributions.length === 0 &&
         memberAddContributions.length === 0 &&
+        memberRemoveContributions.length === 0 &&
         guildRoleDeleteContributions.length === 0 &&
         guildRoleUpdateContributions.length === 0 &&
         channelDeleteContributions.length === 0 &&
@@ -54,6 +77,59 @@ export function installModuleEvents(client, modules, logger, services) {
         guildEmojiUpdateContributions.length === 0)
         return { stop: () => Promise.resolve(), queueDepth: () => 0 };
     const queue = new BoundedGuildEventQueue(logger);
+    const privilegedEligibilityQueue = privilegedMessageContributions.length > 0
+        ? new BoundedGuildEventQueue(logger)
+        : null;
+    const guildMessageQueue = guildMessageContributions.length > 0
+        ? new BoundedGuildEventQueue(logger)
+        : null;
+    if (privilegedMessageContributions.length > 0) {
+        client.on(Events.MessageCreate, (message) => {
+            if (!message.guildId || !privilegedEligibilityQueue)
+                return;
+            privilegedEligibilityQueue.enqueue(message.guildId, async () => {
+                const installations = services.get(HELYX_SERVICE_NAMES.installations);
+                const eligible = [];
+                for (const item of privilegedMessageContributions) {
+                    try {
+                        if ((await installations.isModuleEnabled(message.guildId, item.moduleId)) &&
+                            (await item.contribution.isEligible({
+                                serverId: message.guildId,
+                                channelId: message.channelId,
+                                services,
+                            }))) {
+                            eligible.push(item);
+                        }
+                    }
+                    catch (error) {
+                        logger.warn({
+                            event: "module.privileged_message_eligibility_failed",
+                            moduleId: item.moduleId,
+                            error: safeError(error),
+                            guildId: message.guildId,
+                            channelId: message.channelId,
+                        }, "Module privileged message eligibility failed");
+                    }
+                }
+                if (eligible.length > 0) {
+                    queue.enqueue(message.guildId, () => handlePrivilegedMessageCreate(message, eligible));
+                }
+            });
+        });
+    }
+    if (guildMessageContributions.length > 0) {
+        client.on(Events.MessageCreate, (message) => {
+            if (!message.guildId ||
+                !guildMessageQueue ||
+                message.author.bot ||
+                message.author.system ||
+                Boolean(message.webhookId) ||
+                message.system) {
+                return;
+            }
+            guildMessageQueue.enqueue(message.guildId, () => handleGuildMessageCreate(message));
+        });
+    }
     if (reactionContributions.length > 0) {
         client.on(Events.MessageReactionAdd, (reaction, user, details) => {
             const guildId = reaction.message.guildId;
@@ -79,6 +155,11 @@ export function installModuleEvents(client, modules, logger, services) {
             queue.enqueue(member.guild.id, () => handleMemberAdd(member));
         });
     }
+    if (memberRemoveContributions.length > 0) {
+        client.on(Events.GuildMemberRemove, (member) => {
+            queue.enqueue(member.guild.id, () => handleMemberRemove(member));
+        });
+    }
     if (guildRoleDeleteContributions.length > 0) {
         client.on(Events.GuildRoleDelete, (role) => {
             queue.enqueue(role.guild.id, () => handleResourceLifecycle(guildRoleDeleteContributions, role.guild.id, "roleId", role.id, "guild_role_delete"));
@@ -137,6 +218,116 @@ export function installModuleEvents(client, modules, logger, services) {
             }
         }
     }
+    async function handlePrivilegedMessageCreate(message, contributions) {
+        if (!message.guildId || !message.channelId)
+            return;
+        for (const { moduleId, contribution } of contributions) {
+            try {
+                await contribution.execute({
+                    serverId: message.guildId,
+                    channelId: message.channelId,
+                    messageId: message.id,
+                    userId: message.author.id,
+                    userIsBot: message.author.bot,
+                    webhookId: message.webhookId,
+                    content: message.content,
+                    services,
+                    deleteSource: async () => {
+                        await message.delete();
+                    },
+                });
+            }
+            catch (error) {
+                logger.warn({
+                    event: "module.privileged_message_create_failed",
+                    moduleId,
+                    error: safeError(error),
+                    messageId: message.id,
+                    guildId: message.guildId,
+                }, "Module privileged message-create event failed");
+            }
+        }
+    }
+    async function handleGuildMessageCreate(message) {
+        if (!message.guildId || !message.channelId)
+            return;
+        const installations = services.get(HELYX_SERVICE_NAMES.installations);
+        const parentChannelId = message.channel.isThread()
+            ? (message.channel.parentId ?? undefined)
+            : undefined;
+        const authorRoleIds = message.member
+            ? [...message.member.roles.cache.keys()].sort((left, right) => left.localeCompare(right, "en"))
+            : [];
+        const authorDisplayName = message.member?.displayName ??
+            message.author.globalName ??
+            message.author.username;
+        let classifiedMessage;
+        for (const { moduleId, classificationRequested, contribution, } of guildMessageContributions) {
+            try {
+                if (!(await installations.isModuleEnabled(message.guildId, moduleId))) {
+                    continue;
+                }
+                await contribution.execute({
+                    serverId: message.guildId,
+                    channelId: message.channelId,
+                    ...(parentChannelId ? { parentChannelId } : {}),
+                    messageId: message.id,
+                    authorId: message.author.id,
+                    authorDisplayName,
+                    authorRoleIds,
+                    authorIsBot: false,
+                    authorIsWebhook: false,
+                    authorIsSystem: false,
+                    get classification() {
+                        if (!classificationRequested || !messageClassificationAvailable)
+                            return unavailableGuildMessageClassification;
+                        classifiedMessage ??= classifyGuildMessage(message);
+                        return classifiedMessage;
+                    },
+                    createdAt: message.createdAt,
+                    services,
+                    addAuthorRole: async (roleId) => {
+                        await services
+                            .get(HELYX_SERVICE_NAMES.memberRoles)
+                            .addApprovedRole({
+                            guildId: message.guildId,
+                            memberUserId: message.author.id,
+                            roleId,
+                            moduleId,
+                            reason: "Guild message contribution author role addition",
+                        });
+                    },
+                    removeAuthorRole: async (roleId) => {
+                        await services
+                            .get(HELYX_SERVICE_NAMES.memberRoles)
+                            .removeApprovedRole({
+                            guildId: message.guildId,
+                            memberUserId: message.author.id,
+                            roleId,
+                            moduleId,
+                            reason: "Guild message contribution author role removal",
+                        });
+                    },
+                    sendToChannel: (channelId, response) => services
+                        .get(HELYX_SERVICE_NAMES.discordMessages)
+                        .send({
+                        guildId: message.guildId,
+                        channelId,
+                        response,
+                    }),
+                });
+            }
+            catch (error) {
+                logger.warn({
+                    event: "module.guild_message_create_failed",
+                    moduleId,
+                    error: safeError(error),
+                    messageId: message.id,
+                    guildId: message.guildId,
+                }, "Module guild message-create event failed");
+            }
+        }
+    }
     async function handleReaction(receivedReaction, receivedUser, burst) {
         try {
             const user = receivedUser.partial
@@ -197,6 +388,8 @@ export function installModuleEvents(client, modules, logger, services) {
         }
     }
     async function handleMemberAdd(member) {
+        if (!member.joinedAt)
+            throw new Error("Discord member join timestamp is unavailable");
         const installations = services.get(HELYX_SERVICE_NAMES.installations);
         for (const { moduleId, contribution } of memberAddContributions) {
             try {
@@ -209,6 +402,8 @@ export function installModuleEvents(client, modules, logger, services) {
                     memberId: member.id,
                     memberDisplayName: member.displayName,
                     memberIsBot: member.user.bot,
+                    accountCreatedAt: member.user.createdAt,
+                    joinedAt: member.joinedAt,
                     services,
                     assignRole: (roleId) => assignMemberRole(member, roleId),
                     sendToChannel: (channelId, response) => sendToGuildChannel(member, channelId, response),
@@ -225,6 +420,33 @@ export function installModuleEvents(client, modules, logger, services) {
             }
         }
     }
+    async function handleMemberRemove(member) {
+        const installations = services.get(HELYX_SERVICE_NAMES.installations);
+        for (const { moduleId, contribution } of memberRemoveContributions) {
+            try {
+                if (!(await installations.isModuleEnabled(member.guild.id, moduleId))) {
+                    continue;
+                }
+                await contribution.execute({
+                    serverId: member.guild.id,
+                    memberId: member.id,
+                    memberIsBot: member.user.bot,
+                    accountCreatedAt: member.user.createdAt,
+                    joinedAt: member.joinedAt,
+                    services,
+                });
+            }
+            catch (error) {
+                logger.warn({
+                    event: "module.member_remove_failed",
+                    moduleId,
+                    error: safeError(error),
+                    memberId: member.id,
+                    guildId: member.guild.id,
+                }, "Module member-remove event failed");
+            }
+        }
+    }
     async function handleReactionRemove(receivedReaction, receivedUser, burst) {
         try {
             if (receivedUser.bot)
@@ -293,7 +515,16 @@ export function installModuleEvents(client, modules, logger, services) {
             }
         }
     }
-    return { stop: () => queue.stop(), queueDepth: () => queue.queueDepth() };
+    return {
+        stop: async () => {
+            await privilegedEligibilityQueue?.stop();
+            await guildMessageQueue?.stop();
+            await queue.stop();
+        },
+        queueDepth: () => queue.queueDepth() +
+            (privilegedEligibilityQueue?.queueDepth() ?? 0) +
+            (guildMessageQueue?.queueDepth() ?? 0),
+    };
 }
 class BoundedGuildEventQueue {
     logger;
@@ -405,11 +636,966 @@ const dangerousRolePermissionNames = new Set([
     "MUTE_MEMBERS",
     "VIEW_AUDIT_LOG",
 ]);
+const directMessageAttemptTimeoutMs = 5_000;
+const guildChannelAudienceInspectionLimit = 500;
+export class DiscordMessageDeliveryService {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async send(input) {
+        validateSnowflake(input.guildId, "guild");
+        validateSnowflake(input.channelId, "channel");
+        const guild = await this.client.guilds.fetch(input.guildId);
+        if (guild.id !== input.guildId)
+            throw new Error("Discord guild validation failed");
+        const channel = await guild.channels.fetch(input.channelId);
+        if (!channel ||
+            channel.guild.id !== guild.id ||
+            !channel.isSendable() ||
+            channel.isDMBased()) {
+            throw new Error("Discord message channel is unavailable");
+        }
+        const me = guild.members.me ?? (await guild.members.fetchMe());
+        const effective = channel.permissionsFor(me);
+        if (!effective?.has(PermissionFlagsBits.ViewChannel) ||
+            !effective.has(PermissionFlagsBits.SendMessages)) {
+            throw new Error("Discord message channel permissions are unavailable");
+        }
+        const options = {
+            ...toReplyOptions({ ...input.response, ephemeral: false }),
+        };
+        if (input.idempotencyKey) {
+            const nonce = createHash("sha256")
+                .update(input.idempotencyKey)
+                .digest("hex")
+                .slice(0, 24);
+            options.nonce = nonce;
+            options.enforceNonce = true;
+        }
+        const message = await channel.send(options);
+        if (message.guildId !== guild.id ||
+            message.channelId !== channel.id ||
+            !discordSnowflake.test(message.id)) {
+            throw new Error("Discord sent message validation failed");
+        }
+        return { messageId: message.id };
+    }
+    async sendDirect(input) {
+        validateSnowflake(input.userId, "user");
+        try {
+            const user = await this.client.users.fetch(input.userId);
+            if (user.id !== input.userId)
+                throw new Error("Discord user validation failed");
+            const options = toReplyOptions({ ...input.response, ephemeral: false });
+            const message = await user.send(options);
+            if (!discordSnowflake.test(message.id)) {
+                return { outcome: "failed" };
+            }
+            return { outcome: "sent", messageId: message.id };
+        }
+        catch (error) {
+            return {
+                outcome: isClosedDirectMessage(error) ? "closed" : "failed",
+            };
+        }
+    }
+}
+export class DiscordMemberEnforcementService {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async kick(input) {
+        validateEnforcementMetadata(input);
+        const directMessage = input.directMessage
+            ? await this.#sendBestEffortDirectMessage(input.memberUserId, input.directMessage)
+            : "not_requested";
+        const guild = await this.client.guilds
+            .fetch(input.guildId)
+            .catch(() => null);
+        if (!guild)
+            return { outcome: "failed", directMessage };
+        if (guild.id !== input.guildId)
+            throw new Error("Discord guild validation failed");
+        let member;
+        try {
+            member = await guild.members.fetch(input.memberUserId);
+        }
+        catch (error) {
+            if (isUnknownMember(error))
+                return { outcome: "member_missing", directMessage };
+            return { outcome: "failed", directMessage };
+        }
+        if (!member)
+            return { outcome: "member_missing", directMessage };
+        if (member.id !== input.memberUserId || member.guild.id !== guild.id)
+            throw new Error("Discord member validation failed");
+        const me = guild.members.me ?? (await guild.members.fetchMe());
+        if (!me.permissions.has(PermissionFlagsBits.KickMembers)) {
+            return { outcome: "missing_permission", directMessage };
+        }
+        if (!member.kickable) {
+            return { outcome: "hierarchy_blocked", directMessage };
+        }
+        let stillRequired;
+        try {
+            stillRequired = await input.revalidate();
+        }
+        catch {
+            return { outcome: "failed", directMessage };
+        }
+        if (!stillRequired) {
+            return { outcome: "no_longer_required", directMessage };
+        }
+        try {
+            await member.kick(discordAuditReason(input));
+            return { outcome: "kicked", directMessage };
+        }
+        catch (error) {
+            if (isUnknownMember(error)) {
+                return { outcome: "member_missing", directMessage };
+            }
+            return { outcome: "failed", directMessage };
+        }
+    }
+    async ban(input) {
+        validateEnforcementMetadata(input);
+        const directMessage = input.directMessage
+            ? await this.#sendBestEffortDirectMessage(input.memberUserId, input.directMessage)
+            : "not_requested";
+        const guild = await this.client.guilds
+            .fetch(input.guildId)
+            .catch(() => null);
+        if (!guild)
+            return { outcome: "failed", directMessage };
+        const me = guild.members.me ?? (await guild.members.fetchMe());
+        if (!me.permissions.has(PermissionFlagsBits.BanMembers))
+            return { outcome: "missing_permission", directMessage };
+        const member = await guild.members
+            .fetch(input.memberUserId)
+            .catch(() => null);
+        if (member && !member.bannable)
+            return { outcome: "hierarchy_blocked", directMessage };
+        let stillRequired;
+        try {
+            stillRequired = await input.revalidate();
+        }
+        catch {
+            return { outcome: "failed", directMessage };
+        }
+        if (!stillRequired)
+            return { outcome: "no_longer_required", directMessage };
+        try {
+            await guild.members.ban(input.memberUserId, {
+                deleteMessageSeconds: 0,
+                reason: discordAuditReason(input),
+            });
+            return { outcome: "banned", directMessage };
+        }
+        catch {
+            return { outcome: "failed", directMessage };
+        }
+    }
+    async #sendBestEffortDirectMessage(memberUserId, response) {
+        const attempt = async () => {
+            try {
+                const user = await this.client.users.fetch(memberUserId);
+                if (user.id !== memberUserId)
+                    throw new Error("Discord user validation failed");
+                const options = toReplyOptions({ ...response, ephemeral: false });
+                await user.send(options);
+                return "sent";
+            }
+            catch (error) {
+                return isClosedDirectMessage(error) ? "closed" : "failed";
+            }
+        };
+        return new Promise((resolve) => {
+            let settled = false;
+            const timer = setTimeout(() => {
+                settled = true;
+                resolve("failed");
+            }, directMessageAttemptTimeoutMs);
+            timer.unref();
+            void attempt().then((result) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolve(result);
+            });
+        });
+    }
+}
+const reviewedPublicFlags = [
+    [UserFlags.Staff, "staff"],
+    [UserFlags.Partner, "partner"],
+    [UserFlags.Hypesquad, "hypesquad"],
+    [UserFlags.BugHunterLevel1, "bug_hunter_level_1"],
+    [UserFlags.BugHunterLevel2, "bug_hunter_level_2"],
+    [UserFlags.VerifiedDeveloper, "verified_bot_developer"],
+    [UserFlags.ActiveDeveloper, "active_developer"],
+];
+const reviewedMemberFlags = [
+    [GuildMemberFlags.DidRejoin, "did_rejoin"],
+    [GuildMemberFlags.CompletedOnboarding, "completed_onboarding"],
+    [GuildMemberFlags.BypassesVerification, "bypasses_verification"],
+    [GuildMemberFlags.StartedOnboarding, "started_onboarding"],
+];
+export class DiscordVerificationMemberService {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async captureSnapshot(input) {
+        validateSnowflake(input.guildId, "guild");
+        validateSnowflake(input.userId, "user");
+        validateSnowflake(input.verifiedRoleId, "verified role");
+        const guild = await this.client.guilds.fetch(input.guildId);
+        const [member, verifiedRole] = await Promise.all([
+            guild.members.fetch(input.userId),
+            guild.roles.fetch(input.verifiedRoleId),
+        ]);
+        if (!verifiedRole || verifiedRole.guild.id !== guild.id)
+            throw new Error("The configured verified role is unavailable");
+        const me = guild.members.me ?? (await guild.members.fetchMe());
+        const publicFlags = await member.user.fetchFlags(true);
+        const publicBitfield = BigInt(publicFlags.bitfield);
+        const memberBitfield = BigInt(member.flags.bitfield);
+        const publicKnownMask = reviewedPublicFlags.reduce((mask, [flag]) => mask | BigInt(flag), 0n);
+        const memberKnownMask = reviewedMemberFlags.reduce((mask, [flag]) => mask | BigInt(flag), 0n);
+        const unknownPublic = publicBitfield & ~publicKnownMask;
+        const unknownMember = memberBitfield & ~memberKnownMask;
+        return {
+            sourceClassification: input.sourceClassification,
+            capturedAt: new Date().toISOString(),
+            safeDisplayName: (member.displayName || member.user.username)
+                .normalize("NFC")
+                .slice(0, 100),
+            guildOwnerId: guild.ownerId,
+            accountCreatedAt: member.user.createdAt.toISOString(),
+            joinedAt: member.joinedAt?.toISOString() ?? null,
+            publicFlags: reviewedPublicFlags
+                .filter(([flag]) => publicFlags.has(flag))
+                .map(([, name]) => name),
+            memberFlags: reviewedMemberFlags
+                .filter(([flag]) => member.flags.has(flag))
+                .map(([, name]) => name),
+            ...(unknownPublic === 0n
+                ? {}
+                : { unknownPublicFlagsBitset: unknownPublic.toString() }),
+            ...(unknownMember === 0n
+                ? {}
+                : { unknownMemberFlagsBitset: unknownMember.toString() }),
+            screeningPending: member.pending,
+            rejoined: member.flags.has(GuildMemberFlags.DidRejoin),
+            nameQuarantined: member.flags.has(GuildMemberFlags.AutomodQuarantinedUsernameOrGuildNickname),
+            memberRoleIds: [...member.roles.cache.keys()].slice(0, 100),
+            memberHighestRolePosition: member.roles.highest.position,
+            botHighestRolePosition: me.roles.highest.position,
+            verifiedRolePosition: verifiedRole.position,
+            verifiedRoleManageable: verifiedRole.editable,
+            isBot: member.user.bot,
+            isSystem: member.user.system ?? false,
+        };
+    }
+    async isCurrentlyBanned(input) {
+        validateSnowflake(input.guildId, "guild");
+        validateSnowflake(input.userId, "user");
+        const guild = await this.client.guilds.fetch(input.guildId);
+        try {
+            const ban = await guild.bans.fetch(input.userId);
+            return ban.user.id === input.userId;
+        }
+        catch (error) {
+            if (typeof error === "object" &&
+                error !== null &&
+                "code" in error &&
+                error.code === RESTJSONErrorCodes.UnknownBan)
+                return false;
+            throw error;
+        }
+    }
+}
+const verificationSetupMaximumAccessTargets = 50;
+const verificationSetupLeaseMs = 120_000;
+const verificationRoleNameMaximum = 100;
+const verificationChannelNamePattern = /^[a-z0-9][a-z0-9-_]{0,99}$/u;
+const verificationMembershipScreeningFeature = "MEMBER_VERIFICATION_GATE_ENABLED";
+/**
+ * The single Discord mutation boundary for Verification setup. It deliberately
+ * exposes a preview/apply protocol rather than raw role or overwrite writes.
+ */
+export class DiscordVerificationSetupService {
+    client;
+    persistence;
+    #guildLocks = new Map();
+    constructor(client, persistence) {
+        this.client = client;
+        this.persistence = persistence;
+    }
+    async inspect(input) {
+        validateSnowflake(input.guildId, "guild");
+        const guild = await this.client.guilds.fetch(input.guildId);
+        if (guild.id !== input.guildId)
+            throw new Error("Discord guild validation failed");
+        const me = guild.members.me ?? (await guild.members.fetchMe());
+        const permissions = {
+            viewChannel: me.permissions.has(PermissionFlagsBits.ViewChannel),
+            sendMessages: me.permissions.has(PermissionFlagsBits.SendMessages),
+            embedLinks: me.permissions.has(PermissionFlagsBits.EmbedLinks),
+            manageRoles: me.permissions.has(PermissionFlagsBits.ManageRoles),
+            manageChannels: me.permissions.has(PermissionFlagsBits.ManageChannels),
+            kickMembers: me.permissions.has(PermissionFlagsBits.KickMembers),
+            banMembers: me.permissions.has(PermissionFlagsBits.BanMembers),
+            administrator: me.permissions.has(PermissionFlagsBits.Administrator),
+        };
+        const membershipScreeningEnabled = guild.features.includes(verificationMembershipScreeningFeature);
+        try {
+            const onboarding = await guild.fetchOnboarding();
+            return {
+                guildId: guild.id,
+                permissions,
+                onboarding: {
+                    status: onboarding.enabled ? "enabled" : "disabled",
+                    mode: onboarding.mode === GuildOnboardingMode.OnboardingDefault
+                        ? "default"
+                        : onboarding.mode === GuildOnboardingMode.OnboardingAdvanced
+                            ? "advanced"
+                            : "unknown",
+                    membershipScreeningEnabled,
+                    defaultChannelIds: [...onboarding.defaultChannels.keys()]
+                        .slice(0, verificationSetupMaximumAccessTargets)
+                        .sort((left, right) => left.localeCompare(right, "en")),
+                    unverifiedInteractionChannelRecommended: onboarding.enabled || membershipScreeningEnabled,
+                },
+            };
+        }
+        catch {
+            return {
+                guildId: guild.id,
+                permissions,
+                onboarding: {
+                    status: "unavailable",
+                    mode: "unknown",
+                    membershipScreeningEnabled,
+                    defaultChannelIds: [],
+                    unverifiedInteractionChannelRecommended: membershipScreeningEnabled,
+                },
+            };
+        }
+    }
+    async preview(input) {
+        validateVerificationSetupRequest(input);
+        const guild = await this.client.guilds.fetch(input.guildId);
+        if (guild.id !== input.guildId)
+            throw new Error("Discord guild validation failed");
+        const me = guild.members.me ?? (await guild.members.fetchMe());
+        const [inspection, verifiedRole, verificationChannel] = await Promise.all([
+            this.inspect({ guildId: guild.id }),
+            resolveSetupRole(guild, me, input.verifiedRole),
+            resolveSetupChannel(guild, me, input.verificationChannel),
+        ]);
+        const accessOverwrites = await Promise.all(input.accessTargetIds.map(async (targetId) => {
+            const channel = await fetchVerificationAccessTarget(guild, targetId);
+            const current = verifiedRole.role
+                ? viewChannelOverwrite(channel, verifiedRole.role.id)
+                : null;
+            return {
+                targetId: channel.id,
+                targetType: verificationAccessTargetType(channel),
+                action: current === true
+                    ? "unchanged"
+                    : "set_verified_view",
+            };
+        }));
+        const missingPermissions = verificationSetupMissingPermissions({
+            inspection,
+            me,
+            verificationChannel,
+            needsManageChannels: verificationChannel.action === "create" ||
+                accessOverwrites.some(({ action }) => action !== "unchanged"),
+        });
+        const unsigned = {
+            inspection,
+            missingPermissions,
+            verifiedRole: {
+                action: verifiedRole.action,
+                name: verifiedRole.name,
+                ...(verifiedRole.role ? { roleId: verifiedRole.role.id } : {}),
+                manageable: verifiedRole.manageable,
+            },
+            verificationChannel: {
+                action: verificationChannel.action,
+                name: verificationChannel.name,
+                ...(verificationChannel.channel
+                    ? { channelId: verificationChannel.channel.id }
+                    : {}),
+                usable: verificationChannel.usable,
+            },
+            accessOverwrites,
+        };
+        return {
+            fingerprint: verificationSetupFingerprint(input, unsigned),
+            ...unsigned,
+        };
+    }
+    async apply(input) {
+        if (input.confirmed !== true)
+            throw new Error("Verification setup requires explicit confirmation");
+        if (!/^[a-f0-9]{64}$/u.test(input.previewFingerprint))
+            throw new Error("Verification setup preview fingerprint is invalid");
+        return this.#withGuildLock(input.guildId, async () => {
+            const request = {
+                guildId: input.guildId,
+                verifiedRole: input.verifiedRole,
+                verificationChannel: input.verificationChannel,
+                accessTargetIds: input.accessTargetIds,
+            };
+            const preview = await this.preview(request);
+            if (preview.fingerprint !== input.previewFingerprint)
+                throw new Error("Verification setup changed after preview; review the new plan");
+            if (preview.missingPermissions.length > 0)
+                throw new Error(`Verification setup is missing permissions: ${preview.missingPermissions.join(", ")}`);
+            if (!preview.verifiedRole.manageable)
+                throw new Error("The verified role cannot be managed safely by Helyx");
+            if (!preview.verificationChannel.usable)
+                throw new Error("The verification channel is not usable by Helyx");
+            const guild = await this.client.guilds.fetch(input.guildId);
+            const reason = "Helyx Verification: confirmed setup plan";
+            const leaseOwner = `hosted-bot:${randomUUID()}`;
+            for (let claimAttempt = 0; claimAttempt < 2; claimAttempt += 1) {
+                const claim = await this.persistence.begin({
+                    guildId: input.guildId,
+                    fingerprint: input.previewFingerprint,
+                    selectedTargetIds: input.accessTargetIds,
+                    leaseOwner,
+                    leaseMs: verificationSetupLeaseMs,
+                });
+                if (claim.kind === "applied")
+                    return claim.result;
+                if (claim.kind === "busy")
+                    throw new Error("Another Verification setup operation is in progress");
+                if (claim.kind === "recover") {
+                    await this.#recoverSetup(guild, claim.state, reason);
+                    await this.persistence.abort(claim.state);
+                    continue;
+                }
+                return this.#applyClaimedSetup(guild, preview, claim.state, reason);
+            }
+            throw new Error("Verification setup recovery did not converge");
+        });
+    }
+    async #applyClaimedSetup(guild, preview, initialState, reason) {
+        let state = initialState;
+        let uncheckpointedRole = null;
+        let uncheckpointedChannel = null;
+        try {
+            let role = state.roleId ? await guild.roles.fetch(state.roleId) : null;
+            if (!role) {
+                if (preview.verifiedRole.action === "create") {
+                    role = await findPendingVerificationRole(guild, state.requestedFingerprint);
+                    if (!role)
+                        try {
+                            role = await guild.roles.create({
+                                name: verificationPendingRoleName(state.requestedFingerprint),
+                                permissions: [],
+                                reason,
+                            });
+                        }
+                        catch (error) {
+                            role = await findPendingVerificationRole(guild, state.requestedFingerprint);
+                            if (!role)
+                                throw error;
+                        }
+                    uncheckpointedRole = role;
+                    state = await this.persistence.checkpointResources(state, { roleId: role.id, createdRole: true }, verificationSetupLeaseMs);
+                    uncheckpointedRole = null;
+                    if (role.name !== preview.verifiedRole.name)
+                        role = await role.setName(preview.verifiedRole.name, reason);
+                }
+                else {
+                    role = await guild.roles.fetch(preview.verifiedRole.roleId);
+                    if (role)
+                        state = await this.persistence.checkpointResources(state, { roleId: role.id, createdRole: false }, verificationSetupLeaseMs);
+                }
+            }
+            if (!role || role.guild.id !== guild.id)
+                throw new Error("The verified role became unavailable during setup");
+            let channel = state.channelId
+                ? await fetchVerificationTextChannel(guild, state.channelId)
+                : null;
+            if (!channel) {
+                if (preview.verificationChannel.action === "create") {
+                    channel = await findPendingVerificationChannel(guild, state.requestedFingerprint);
+                    if (!channel)
+                        try {
+                            channel = await guild.channels.create({
+                                name: verificationPendingChannelName(state.requestedFingerprint),
+                                type: ChannelType.GuildText,
+                                reason,
+                            });
+                        }
+                        catch (error) {
+                            channel = await findPendingVerificationChannel(guild, state.requestedFingerprint);
+                            if (!channel)
+                                throw error;
+                        }
+                    uncheckpointedChannel = channel;
+                    state = await this.persistence.checkpointResources(state, { channelId: channel.id, createdChannel: true }, verificationSetupLeaseMs);
+                    uncheckpointedChannel = null;
+                    if (channel.name !== preview.verificationChannel.name)
+                        channel = await channel.setName(preview.verificationChannel.name, reason);
+                }
+                else {
+                    channel = await fetchVerificationTextChannel(guild, preview.verificationChannel.channelId);
+                    if (channel)
+                        state = await this.persistence.checkpointResources(state, { channelId: channel.id, createdChannel: false }, verificationSetupLeaseMs);
+                }
+            }
+            if (!channel || channel.guild.id !== guild.id)
+                throw new Error("The verification channel became unavailable during setup");
+            const desiredKeys = new Set(state.selectedTargetIds.map((targetId) => verificationManagedOverwriteKey(targetId, role.id)));
+            const removesPreviousManagedOverwrite = state.managedOverwrites.some((overwrite) => !desiredKeys.has(verificationManagedOverwriteKey(overwrite.targetId, overwrite.roleId)));
+            await assertVerificationSetupStillSafe(guild, role, channel, {
+                needsManageChannels: state.createdChannel ||
+                    removesPreviousManagedOverwrite ||
+                    preview.accessOverwrites.some(({ action }) => action !== "unchanged"),
+            });
+            for (const overwrite of [...state.managedOverwrites]) {
+                const key = verificationManagedOverwriteKey(overwrite.targetId, overwrite.roleId);
+                if (desiredKeys.has(key))
+                    continue;
+                state = await this.#checkpointOverwriteState(state, {
+                    ...overwrite,
+                    status: "restoring",
+                });
+                await restoreVerificationViewOverwrite(guild, overwrite, reason);
+                state = await this.#removeCheckpointedOverwrite(state, key);
+            }
+            for (const targetId of state.selectedTargetIds) {
+                const target = await fetchVerificationAccessTarget(guild, targetId);
+                const key = verificationManagedOverwriteKey(target.id, role.id);
+                let tracked = state.managedOverwrites.find((overwrite) => verificationManagedOverwriteKey(overwrite.targetId, overwrite.roleId) === key);
+                const current = viewChannelOverwrite(target, role.id);
+                if (!tracked && current === true)
+                    continue;
+                if (!tracked) {
+                    tracked = {
+                        targetId: target.id,
+                        roleId: role.id,
+                        previousView: current,
+                        status: "planned",
+                    };
+                    state = await this.#checkpointOverwriteState(state, tracked);
+                }
+                else if (tracked.status !== "planned" && current !== true) {
+                    tracked = { ...tracked, status: "planned" };
+                    state = await this.#checkpointOverwriteState(state, tracked);
+                }
+                if (current !== true) {
+                    await target.permissionOverwrites.edit(role, { ViewChannel: true }, { reason });
+                }
+                tracked = { ...tracked, status: "applied" };
+                state = await this.#checkpointOverwriteState(state, tracked, current === true ? undefined : target.id);
+            }
+            return this.persistence.complete(state, {
+                verifiedRoleId: role.id,
+                verificationChannelId: channel.id,
+                createdRole: state.createdRole,
+                createdChannel: state.createdChannel,
+                changedAccessTargetIds: state.changedTargetIds,
+            });
+        }
+        catch (error) {
+            if (error instanceof VerificationSetupLeaseLostError)
+                throw error;
+            const rollbackFailures = [];
+            for (const resource of [uncheckpointedChannel, uncheckpointedRole]) {
+                if (!resource)
+                    continue;
+                try {
+                    await resource.delete(`${reason} rollback`);
+                }
+                catch (rollbackError) {
+                    rollbackFailures.push(rollbackError);
+                }
+            }
+            try {
+                await this.#recoverSetup(guild, state, `${reason} rollback`);
+                await this.persistence.abort(state);
+            }
+            catch (rollbackError) {
+                rollbackFailures.push(rollbackError);
+            }
+            if (rollbackFailures.length > 0)
+                throw new AggregateError(rollbackFailures, "Verification setup failed and rollback was incomplete", { cause: error });
+            throw error;
+        }
+    }
+    async #recoverSetup(guild, state, reason) {
+        const applied = new Map(state.appliedManagedOverwrites.map((overwrite) => [
+            verificationManagedOverwriteKey(overwrite.targetId, overwrite.roleId),
+            overwrite,
+        ]));
+        for (const pending of state.managedOverwrites) {
+            const key = verificationManagedOverwriteKey(pending.targetId, pending.roleId);
+            if (applied.has(key)) {
+                await setVerificationViewOverwrite(guild, pending.targetId, pending.roleId, true, reason);
+                applied.delete(key);
+            }
+            else {
+                await restoreVerificationViewOverwrite(guild, pending, reason);
+            }
+        }
+        for (const previous of applied.values()) {
+            await setVerificationViewOverwrite(guild, previous.targetId, previous.roleId, true, reason);
+        }
+        const appliedResult = state.appliedResult;
+        if (state.createdChannel &&
+            state.channelId &&
+            state.channelId !== appliedResult?.verificationChannelId) {
+            const createdChannel = await guild.channels.fetch(state.channelId);
+            if (createdChannel)
+                await createdChannel.delete(reason);
+        }
+        if (state.createdRole &&
+            state.roleId &&
+            state.roleId !== appliedResult?.verifiedRoleId) {
+            const createdRole = await guild.roles.fetch(state.roleId);
+            if (createdRole)
+                await createdRole.delete(reason);
+        }
+        const pendingChannel = await findPendingVerificationChannel(guild, state.requestedFingerprint);
+        if (pendingChannel &&
+            pendingChannel.id !== appliedResult?.verificationChannelId)
+            await pendingChannel.delete(reason);
+        const pendingRole = await findPendingVerificationRole(guild, state.requestedFingerprint);
+        if (pendingRole && pendingRole.id !== appliedResult?.verifiedRoleId)
+            await pendingRole.delete(reason);
+    }
+    async #checkpointOverwriteState(state, overwrite, changedTargetId) {
+        const key = verificationManagedOverwriteKey(overwrite.targetId, overwrite.roleId);
+        const next = state.managedOverwrites.filter((existing) => verificationManagedOverwriteKey(existing.targetId, existing.roleId) !==
+            key);
+        next.push(overwrite);
+        const changed = changedTargetId
+            ? [...new Set([...state.changedTargetIds, changedTargetId])]
+            : state.changedTargetIds;
+        return this.persistence.checkpointOverwrites(state, next, changed, verificationSetupLeaseMs);
+    }
+    #removeCheckpointedOverwrite(state, key) {
+        return this.persistence.checkpointOverwrites(state, state.managedOverwrites.filter((overwrite) => verificationManagedOverwriteKey(overwrite.targetId, overwrite.roleId) !== key), state.changedTargetIds, verificationSetupLeaseMs);
+    }
+    async hideVerificationChannelForVerifiedMember(input) {
+        validateMutationMetadata({
+            guildId: input.guildId,
+            memberUserId: input.memberUserId,
+            roleId: input.verifiedRoleId,
+            moduleId: input.moduleId,
+            reason: input.reason,
+        });
+        validateSnowflake(input.channelId, "channel");
+        const guild = await this.client.guilds.fetch(input.guildId);
+        const [member, role, fetchedChannel] = await Promise.all([
+            guild.members.fetch(input.memberUserId),
+            guild.roles.fetch(input.verifiedRoleId),
+            guild.channels.fetch(input.channelId),
+        ]);
+        if (!role || role.guild.id !== guild.id)
+            throw new Error("The verified role is unavailable");
+        if (!fetchedChannel ||
+            fetchedChannel.guild.id !== guild.id ||
+            fetchedChannel.type !== ChannelType.GuildText)
+            throw new Error("The verification channel is unavailable");
+        if (!member.roles.cache.has(role.id))
+            throw new Error("The member does not hold the verified role");
+        const me = guild.members.me ?? (await guild.members.fetchMe());
+        if (!me.permissions.has(PermissionFlagsBits.ManageChannels))
+            throw new Error("Helyx requires Manage Channels to hide this channel");
+        if (!verificationRoleManageable(role, guild, me))
+            throw new Error("The verified role cannot be managed safely by Helyx");
+        if (viewChannelOverwrite(fetchedChannel, role.id) === false)
+            return { changed: false };
+        await fetchedChannel.permissionOverwrites.edit(role, { ViewChannel: false }, { reason: discordAuditReason(input) });
+        return { changed: true };
+    }
+    async #withGuildLock(guildId, operation) {
+        validateSnowflake(guildId, "guild");
+        const previous = this.#guildLocks.get(guildId) ?? Promise.resolve();
+        let release;
+        const gate = new Promise((resolve) => {
+            release = resolve;
+        });
+        const current = previous.catch(() => undefined).then(() => gate);
+        this.#guildLocks.set(guildId, current);
+        await previous.catch(() => undefined);
+        try {
+            return await operation();
+        }
+        finally {
+            release();
+            if (this.#guildLocks.get(guildId) === current)
+                this.#guildLocks.delete(guildId);
+        }
+    }
+}
+async function resolveSetupRole(guild, me, selection) {
+    if (selection.mode === "create") {
+        const role = selection.trackedRoleId
+            ? await guild.roles.fetch(selection.trackedRoleId)
+            : null;
+        if (!role)
+            return {
+                action: "create",
+                name: selection.name,
+                role: null,
+                manageable: me.permissions.has(PermissionFlagsBits.ManageRoles),
+            };
+        return {
+            action: "reuse",
+            name: role.name,
+            role,
+            manageable: verificationRoleManageable(role, guild, me),
+        };
+    }
+    const role = await guild.roles.fetch(selection.roleId);
+    if (!role || role.guild.id !== guild.id)
+        throw new Error("The selected verified role is unavailable");
+    return {
+        action: "select",
+        name: role.name,
+        role,
+        manageable: verificationRoleManageable(role, guild, me),
+    };
+}
+async function resolveSetupChannel(guild, me, selection) {
+    if (selection.mode === "create") {
+        const fetched = selection.trackedChannelId
+            ? await guild.channels.fetch(selection.trackedChannelId)
+            : null;
+        if (!fetched)
+            return {
+                action: "create",
+                name: selection.name,
+                channel: null,
+                usable: me.permissions.has(PermissionFlagsBits.ViewChannel) &&
+                    me.permissions.has(PermissionFlagsBits.SendMessages) &&
+                    me.permissions.has(PermissionFlagsBits.EmbedLinks) &&
+                    me.permissions.has(PermissionFlagsBits.ManageChannels),
+            };
+        if (fetched.type !== ChannelType.GuildText)
+            throw new Error("The tracked verification channel is not a text channel");
+        return {
+            action: "reuse",
+            name: fetched.name,
+            channel: fetched,
+            usable: verificationChannelUsable(fetched, me),
+        };
+    }
+    const fetched = await guild.channels.fetch(selection.channelId);
+    if (!fetched || fetched.guild.id !== guild.id)
+        throw new Error("The selected verification channel is unavailable");
+    if (fetched.type !== ChannelType.GuildText)
+        throw new Error("The selected verification channel is not a text channel");
+    return {
+        action: "select",
+        name: fetched.name,
+        channel: fetched,
+        usable: verificationChannelUsable(fetched, me),
+    };
+}
+function verificationChannelUsable(channel, me) {
+    const effective = channel.permissionsFor(me);
+    return Boolean(effective?.has(PermissionFlagsBits.ViewChannel) &&
+        effective.has(PermissionFlagsBits.SendMessages) &&
+        effective.has(PermissionFlagsBits.EmbedLinks));
+}
+function verificationRoleManageable(role, guild, me) {
+    return (role.guild.id === guild.id &&
+        role.id !== guild.id &&
+        !role.managed &&
+        !role.permissions.has(PermissionFlagsBits.Administrator) &&
+        me.permissions.has(PermissionFlagsBits.ManageRoles) &&
+        role.comparePositionTo(me.roles.highest) < 0);
+}
+async function fetchVerificationAccessTarget(guild, targetId) {
+    const channel = await guild.channels.fetch(targetId);
+    if (!channel || channel.guild.id !== guild.id)
+        throw new Error("A selected verification access target is unavailable");
+    if (channel.type !== ChannelType.GuildText &&
+        channel.type !== ChannelType.GuildAnnouncement &&
+        channel.type !== ChannelType.GuildCategory)
+        throw new Error("Verification access targets must be text channels or categories");
+    return channel;
+}
+async function fetchVerificationTextChannel(guild, channelId) {
+    const channel = await guild.channels.fetch(channelId);
+    return channel?.guild.id === guild.id &&
+        channel.type === ChannelType.GuildText
+        ? channel
+        : null;
+}
+function verificationPendingRoleName(fingerprint) {
+    return `Helyx verify pending ${fingerprint.slice(0, 12)}`;
+}
+function verificationPendingChannelName(fingerprint) {
+    return `helyx-verify-pending-${fingerprint.slice(0, 12)}`;
+}
+async function findPendingVerificationRole(guild, fingerprint) {
+    const expectedName = verificationPendingRoleName(fingerprint);
+    const roles = await guild.roles.fetch();
+    return roles.find((role) => role.name === expectedName) ?? null;
+}
+async function findPendingVerificationChannel(guild, fingerprint) {
+    const expectedName = verificationPendingChannelName(fingerprint);
+    const channels = await guild.channels.fetch();
+    const channel = channels.find((candidate) => candidate !== null &&
+        candidate.type === ChannelType.GuildText &&
+        candidate.name === expectedName);
+    return channel?.type === ChannelType.GuildText ? channel : null;
+}
+function verificationManagedOverwriteKey(targetId, roleId) {
+    return `${targetId}:${roleId}`;
+}
+async function restoreVerificationViewOverwrite(guild, overwrite, reason) {
+    await setVerificationViewOverwrite(guild, overwrite.targetId, overwrite.roleId, overwrite.previousView, reason);
+}
+async function setVerificationViewOverwrite(guild, targetId, roleId, viewChannel, reason) {
+    const [fetched, role] = await Promise.all([
+        guild.channels.fetch(targetId),
+        guild.roles.fetch(roleId),
+    ]);
+    if (!fetched || !role)
+        return;
+    if (fetched.guild.id !== guild.id ||
+        (fetched.type !== ChannelType.GuildText &&
+            fetched.type !== ChannelType.GuildAnnouncement &&
+            fetched.type !== ChannelType.GuildCategory))
+        throw new Error("A tracked verification access target is invalid");
+    if (viewChannelOverwrite(fetched, roleId) === viewChannel)
+        return;
+    await fetched.permissionOverwrites.edit(roleId, { ViewChannel: viewChannel }, { reason });
+}
+function verificationAccessTargetType(channel) {
+    if (channel.type === ChannelType.GuildCategory)
+        return "category";
+    if (channel.type === ChannelType.GuildAnnouncement)
+        return "announcement";
+    return "text";
+}
+function viewChannelOverwrite(channel, roleId) {
+    const overwrite = channel.permissionOverwrites.cache.get(roleId);
+    if (!overwrite)
+        return null;
+    if (overwrite.allow.has(PermissionFlagsBits.ViewChannel))
+        return true;
+    if (overwrite.deny.has(PermissionFlagsBits.ViewChannel))
+        return false;
+    return null;
+}
+function verificationSetupMissingPermissions(input) {
+    const missing = [];
+    const effective = input.verificationChannel.channel?.permissionsFor(input.me);
+    const has = (permission, guildFallback) => effective ? effective.has(permission) : guildFallback;
+    if (!has(PermissionFlagsBits.ViewChannel, input.inspection.permissions.viewChannel))
+        missing.push("ViewChannel");
+    if (!has(PermissionFlagsBits.SendMessages, input.inspection.permissions.sendMessages))
+        missing.push("SendMessages");
+    if (!has(PermissionFlagsBits.EmbedLinks, input.inspection.permissions.embedLinks))
+        missing.push("EmbedLinks");
+    if (!input.inspection.permissions.manageRoles)
+        missing.push("ManageRoles");
+    if (input.needsManageChannels && !input.inspection.permissions.manageChannels)
+        missing.push("ManageChannels");
+    return missing;
+}
+async function assertVerificationSetupStillSafe(guild, role, channel, input) {
+    const me = guild.members.me ?? (await guild.members.fetchMe());
+    if (!verificationRoleManageable(role, guild, me))
+        throw new Error("The verified role is no longer manageable by Helyx");
+    if (!verificationChannelUsable(channel, me))
+        throw new Error("The verification channel is no longer usable by Helyx");
+    if (input.needsManageChannels &&
+        !me.permissions.has(PermissionFlagsBits.ManageChannels))
+        throw new Error("Helyx no longer has Manage Channels");
+}
+function validateVerificationSetupRequest(input) {
+    validateSnowflake(input.guildId, "guild");
+    if (input.verifiedRole.mode === "existing")
+        validateSnowflake(input.verifiedRole.roleId, "verified role");
+    else {
+        validateVerificationRoleName(input.verifiedRole.name);
+        if (input.verifiedRole.trackedRoleId)
+            validateSnowflake(input.verifiedRole.trackedRoleId, "tracked role");
+    }
+    if (input.verificationChannel.mode === "existing")
+        validateSnowflake(input.verificationChannel.channelId, "verification channel");
+    else {
+        if (!verificationChannelNamePattern.test(input.verificationChannel.name))
+            throw new Error("Verification channel name is invalid");
+        if (input.verificationChannel.trackedChannelId)
+            validateSnowflake(input.verificationChannel.trackedChannelId, "tracked channel");
+    }
+    if (input.accessTargetIds.length > verificationSetupMaximumAccessTargets ||
+        new Set(input.accessTargetIds).size !== input.accessTargetIds.length)
+        throw new Error("Verification access targets must be unique and bounded");
+    for (const targetId of input.accessTargetIds)
+        validateSnowflake(targetId, "access target");
+}
+function validateVerificationRoleName(name) {
+    const normalized = name.trim();
+    if (normalized.length === 0 ||
+        normalized.length > verificationRoleNameMaximum ||
+        /[\r\n]/u.test(normalized) ||
+        normalized === "@everyone" ||
+        normalized === "@here")
+        throw new Error("Verification role name is invalid");
+}
+function verificationSetupFingerprint(request, preview) {
+    return createHash("sha256")
+        .update(stableVerificationSetupJson({
+        protocol: "helyx-verification-setup-v1",
+        request,
+        preview,
+    }))
+        .digest("hex");
+}
+function stableVerificationSetupJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableVerificationSetupJson).join(",")}]`;
+    const record = value;
+    return `{${Object.keys(record)
+        .sort((left, right) => left.localeCompare(right, "en"))
+        .map((key) => `${JSON.stringify(key)}:${stableVerificationSetupJson(record[key])}`)
+        .join(",")}}`;
+}
 export class DiscordMemberRoleService {
     client;
     constructor(client) {
         this.client = client;
     }
+    async createApprovedRole(input) {
+        validateRoleCreationMetadata(input);
+        const guild = await this.client.guilds.fetch(input.guildId);
+        if (guild.id !== input.guildId)
+            throw new Error("Discord guild validation failed");
+        const me = guild.members.me ?? (await guild.members.fetchMe());
+        if (!me.permissions.has(PermissionFlagsBits.ManageRoles))
+            throw new Error("Helyx requires Manage Roles to create this reward role");
+        const role = await guild.roles.create({
+            name: input.name,
+            permissions: [],
+            reason: discordAuditReason(input),
+        });
+        if (role.guild.id !== guild.id)
+            throw new Error("Created Discord role did not belong to this guild");
+        await fetchSafeRole(guild, role.id);
+        return { roleId: role.id, name: role.name };
+    }
     async getCurrentRoleIds(input) {
         const { member } = await this.fetchGuildAndMember(input);
         return [...member.roles.cache.keys()];
@@ -452,10 +1638,10 @@ export class DiscordMemberRoleService {
         const addedRoles = addedIds.map((roleId) => approvedRoles.get(roleId));
         const removedRoles = removedIds.map((roleId) => approvedRoles.get(roleId));
         const reason = discordAuditReason(input);
-        if (removedRoles.length > 0)
-            await member.roles.remove(removedRoles, reason);
         if (addedRoles.length > 0)
             await member.roles.add(addedRoles, reason);
+        if (removedRoles.length > 0)
+            await member.roles.remove(removedRoles, reason);
         return { added: addedIds, removed: removedIds };
     }
     async fetchGuildAndMember(input) {
@@ -475,6 +1661,32 @@ export class DiscordResourceInspection {
     constructor(client) {
         this.client = client;
     }
+    async inspectGuildCapabilities(input) {
+        validateSnowflake(input.guildId, "guild");
+        const guild = await this.client.guilds.fetch(input.guildId);
+        if (guild.id !== input.guildId)
+            throw new Error("Discord guild validation failed");
+        const me = guild.members.me ?? (await guild.members.fetchMe());
+        const effectivePermissionNames = me.permissions
+            .toArray()
+            .map(normalizePermissionName)
+            .sort();
+        return {
+            guildId: guild.id,
+            effectivePermissionNames,
+            manageRoles: me.permissions.has(PermissionFlagsBits.ManageRoles),
+            kickMembers: me.permissions.has(PermissionFlagsBits.KickMembers),
+        };
+    }
+    inspectRuntimeCapabilities() {
+        const intents = this.client.options.intents;
+        return Promise.resolve({
+            guildMembers: intents.has(GatewayIntentBits.GuildMembers),
+            guildMessages: intents.has(GatewayIntentBits.GuildMessages),
+            guildMessageReactions: intents.has(GatewayIntentBits.GuildMessageReactions),
+            messageContent: intents.has(GatewayIntentBits.MessageContent),
+        });
+    }
     async resolveMemberSnapshots(input) {
         const guild = await this.#resolveMemberGuild(input);
         return Promise.all(input.userIds.map(async (userId) => {
@@ -502,12 +1714,41 @@ export class DiscordResourceInspection {
                     return null;
                 throw error;
             });
+            const avatarUrl = memberAvatarUrl(member);
             return {
                 userId,
                 displayName: member?.displayName ?? null,
+                ...(avatarUrl ? { avatarUrl } : {}),
             };
         }));
     }
+    async searchMembers(input) {
+        validateSnowflake(input.guildId, "guild");
+        const query = input.query.trim();
+        if (query.length < 1 || query.length > 100)
+            throw new Error("Discord member search query is invalid");
+        if (!Number.isSafeInteger(input.limit) ||
+            input.limit < 1 ||
+            input.limit > 25)
+            throw new Error("Discord member search limit is invalid");
+        const guild = await this.client.guilds.fetch(input.guildId);
+        if (guild.id !== input.guildId)
+            throw new Error("Discord guild validation failed");
+        const members = await guild.members.search({
+            query,
+            limit: input.limit,
+            cache: false,
+        });
+        return [...members.values()].map((member) => {
+            const avatarUrl = memberAvatarUrl(member);
+            return {
+                userId: member.id,
+                displayName: member.displayName,
+                ...(avatarUrl ? { avatarUrl } : {}),
+                isBot: member.user.bot,
+            };
+        });
+    }
     async #resolveMemberGuild(input) {
         validateSnowflake(input.guildId, "guild");
         if (input.userIds.length > 50 ||
@@ -640,6 +1881,7 @@ export class DiscordResourceInspection {
                 sendMessages: false,
                 addReactions: false,
                 readMessageHistory: false,
+                manageMessages: false,
             };
         const guildMatches = channel.guild.id === guild.id;
         const me = guild.members.me ?? (await guild.members.fetchMe());
@@ -665,8 +1907,198 @@ export class DiscordResourceInspection {
                 (effective?.has(PermissionFlagsBits.AddReactions) ?? false),
             readMessageHistory: guildMatches &&
                 (effective?.has(PermissionFlagsBits.ReadMessageHistory) ?? false),
+            manageMessages: guildMatches &&
+                (effective?.has(PermissionFlagsBits.ManageMessages) ?? false),
         };
     }
+    async inspectMessage(input) {
+        validateSnowflake(input.guildId, "guild");
+        validateSnowflake(input.channelId, "channel");
+        validateSnowflake(input.messageId, "message");
+        const guild = await this.client.guilds.fetch(input.guildId);
+        if (guild.id !== input.guildId)
+            throw new Error("Discord guild validation failed");
+        const channel = await guild.channels.fetch(input.channelId);
+        if (!channel ||
+            channel.guild.id !== guild.id ||
+            !channel.isTextBased() ||
+            channel.isDMBased()) {
+            return missingMessageInspection(input, false);
+        }
+        const message = await channel.messages
+            .fetch(input.messageId)
+            .catch((error) => {
+            if (isUnknownMessage(error))
+                return null;
+            throw error;
+        });
+        if (!message)
+            return missingMessageInspection(input, true);
+        const guildMatches = message.guildId === guild.id;
+        const channelMatches = message.channelId === channel.id;
+        return {
+            guildId: guild.id,
+            channelId: channel.id,
+            messageId: message.id,
+            exists: guildMatches && channelMatches && message.id === input.messageId,
+            guildMatches,
+            channelMatches,
+            authorUserId: message.author.id,
+        };
+    }
+    async inspectChannelAudience(input) {
+        validateSnowflake(input.guildId, "guild");
+        validateSnowflake(input.channelId, "channel");
+        validateBoundedRoleSet(input.roleIds, "audience");
+        const guild = await this.client.guilds.fetch(input.guildId);
+        if (guild.id !== input.guildId)
+            throw new Error("Discord guild validation failed");
+        const roles = await Promise.all(input.roleIds.map(async (roleId) => ({
+            roleId,
+            role: await guild.roles.fetch(roleId),
+        })));
+        const channel = await guild.channels.fetch(input.channelId);
+        if (!channel) {
+            return {
+                guildId: guild.id,
+                channelId: input.channelId,
+                exists: false,
+                guildMatches: false,
+                everyoneCanView: false,
+                roles: roles.map(({ roleId, role }) => ({
+                    roleId,
+                    exists: role !== null && role.guild.id === guild.id,
+                    canView: false,
+                })),
+            };
+        }
+        const guildMatches = channel.guild.id === guild.id;
+        return {
+            guildId: guild.id,
+            channelId: channel.id,
+            exists: true,
+            guildMatches,
+            everyoneCanView: guildMatches &&
+                (channel
+                    .permissionsFor(guild.roles.everyone)
+                    ?.has(PermissionFlagsBits.ViewChannel) ??
+                    false),
+            roles: roles.map(({ roleId, role }) => {
+                const exists = role !== null && role.guild.id === guild.id;
+                return {
+                    roleId,
+                    exists,
+                    canView: guildMatches &&
+                        role !== null &&
+                        role.guild.id === guild.id &&
+                        (channel
+                            .permissionsFor(role)
+                            ?.has(PermissionFlagsBits.ViewChannel) ??
+                            false),
+                };
+            }),
+        };
+    }
+    async inspectGuildChannelAudience(input) {
+        validateSnowflake(input.guildId, "guild");
+        validateBoundedRoleSet(input.roleIds, "audience");
+        const guild = await this.client.guilds.fetch(input.guildId);
+        if (guild.id !== input.guildId)
+            throw new Error("Discord guild validation failed");
+        const resolvedRoles = await Promise.all(input.roleIds.map(async (roleId) => ({
+            roleId,
+            role: await guild.roles.fetch(roleId),
+        })));
+        const missingRoleIds = resolvedRoles
+            .filter(({ role }) => role === null || role.guild.id !== guild.id)
+            .map(({ roleId }) => roleId);
+        const fetched = await guild.channels.fetch();
+        const relevant = [];
+        for (const channel of fetched.values()) {
+            if (channel &&
+                (channel.type === ChannelType.GuildText ||
+                    channel.type === ChannelType.GuildAnnouncement)) {
+                if (channel.guild.id !== guild.id)
+                    throw new Error("Discord channel guild validation failed");
+                relevant.push(channel);
+            }
+        }
+        relevant.sort((left, right) => left.id.localeCompare(right.id, "en"));
+        const truncated = relevant.length > guildChannelAudienceInspectionLimit;
+        const channels = relevant
+            .slice(0, guildChannelAudienceInspectionLimit)
+            .map((channel) => {
+            const everyoneCanView = channel
+                .permissionsFor(guild.roles.everyone)
+                ?.has(PermissionFlagsBits.ViewChannel) ?? false;
+            const visibleRoleIds = resolvedRoles
+                .filter(({ role }) => role !== null &&
+                role.guild.id === guild.id &&
+                (channel
+                    .permissionsFor(role)
+                    ?.has(PermissionFlagsBits.ViewChannel) ??
+                    false))
+                .map(({ roleId }) => roleId);
+            return {
+                channelId: channel.id,
+                type: channel.type === ChannelType.GuildText
+                    ? "guild_text"
+                    : "guild_announcement",
+                everyoneCanView,
+                visibleRoleIds,
+            };
+        })
+            .filter(({ everyoneCanView, visibleRoleIds }) => everyoneCanView || visibleRoleIds.length > 0);
+        return {
+            guildId: guild.id,
+            channels,
+            missingRoleIds,
+            truncated,
+        };
+    }
+    async seedMessageReaction(input) {
+        validateSnowflake(input.guildId, "guild");
+        validateSnowflake(input.channelId, "channel");
+        validateSnowflake(input.messageId, "message");
+        const guild = await this.client.guilds.fetch(input.guildId);
+        if (guild.id !== input.guildId)
+            throw new Error("Discord guild validation failed");
+        const channel = await guild.channels.fetch(input.channelId);
+        if (!channel ||
+            channel.guild.id !== guild.id ||
+            !channel.isTextBased() ||
+            channel.isDMBased()) {
+            throw new Error("Discord reaction message channel is unavailable");
+        }
+        const message = await channel.messages.fetch(input.messageId);
+        if (message.id !== input.messageId ||
+            message.guildId !== guild.id ||
+            message.channelId !== channel.id) {
+            throw new Error("Discord reaction message validation failed");
+        }
+        const emoji = await this.inspectEmoji({
+            guildId: guild.id,
+            emojiIdentifier: input.emojiIdentifier,
+        });
+        if (!emoji.exists || !emoji.guildMatches || !emoji.usable) {
+            throw new Error("Discord reaction emoji is unavailable");
+        }
+        const cacheKey = emoji.kind === "custom" ? emoji.emojiId : (emoji.name ?? "");
+        if (message.reactions.cache.get(cacheKey)?.me)
+            return { added: false };
+        const resolvedEmoji = emoji.kind === "custom"
+            ? await guild.emojis.fetch(emoji.emojiId)
+            : emoji.name;
+        if (!resolvedEmoji)
+            throw new Error("Discord reaction emoji is unavailable");
+        await message.react(resolvedEmoji);
+        return { added: true };
+    }
+}
+function memberAvatarUrl(member) {
+    return member && typeof member.displayAvatarURL === "function"
+        ? member.displayAvatarURL({ extension: "webp", size: 64 })
+        : "";
 }
 async function fetchSafeRole(guild, roleId) {
     validateSnowflake(roleId, "role");
@@ -710,6 +2142,24 @@ function missingRoleInspection(input, hierarchy) {
         dangerousPermissionNames: [],
     };
 }
+function missingMessageInspection(input, channelMatches) {
+    return {
+        ...input,
+        exists: false,
+        guildMatches: channelMatches,
+        channelMatches,
+    };
+}
+function validateEnforcementMetadata(input) {
+    validateSnowflake(input.guildId, "guild");
+    validateSnowflake(input.memberUserId, "member");
+    if (input.moduleId.length > 100 || !moduleIdentifier.test(input.moduleId))
+        throw new Error("Member enforcement requires a valid Helyx module ID");
+    if (input.reason.trim().length === 0 ||
+        input.reason.length > 400 ||
+        /[\r\n]/u.test(input.reason))
+        throw new Error("Member enforcement requires a bounded audit reason");
+}
 function validateMutationMetadata(input) {
     validateSnowflake(input.guildId, "guild");
     validateSnowflake(input.memberUserId, "member");
@@ -722,6 +2172,22 @@ function validateMutationMetadata(input) {
         /[\r\n]/u.test(input.reason))
         throw new Error("Role mutation requires a bounded audit reason");
 }
+function validateRoleCreationMetadata(input) {
+    validateSnowflake(input.guildId, "guild");
+    if (input.name.trim() !== input.name ||
+        input.name.length < 1 ||
+        input.name.length > 100 ||
+        /[\r\n\0]/u.test(input.name) ||
+        input.name.toLowerCase() === "@everyone" ||
+        input.name.toLowerCase() === "@here")
+        throw new Error("Role creation requires a safe name from 1 to 100 characters");
+    if (input.moduleId.length > 100 || !moduleIdentifier.test(input.moduleId))
+        throw new Error("Role creation requires a valid Helyx module ID");
+    if (input.reason.trim().length === 0 ||
+        input.reason.length > 400 ||
+        /[\r\n]/u.test(input.reason))
+        throw new Error("Role creation requires a bounded audit reason");
+}
 async function fetchExactMember(guild, memberUserId, label) {
     validateSnowflake(memberUserId, label);
     const member = await guild.members.fetch(memberUserId);
@@ -735,6 +2201,18 @@ function isUnknownMember(error) {
         "code" in error &&
         error.code === RESTJSONErrorCodes.UnknownMember);
 }
+function isUnknownMessage(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === RESTJSONErrorCodes.UnknownMessage);
+}
+function isClosedDirectMessage(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === RESTJSONErrorCodes.CannotSendMessagesToThisUser);
+}
 function validateBoundedRoleSet(roleIds, label) {
     if (roleIds.length > 100 || new Set(roleIds).size !== roleIds.length)
         throw new Error(`${label} role IDs must be unique and bounded`);