@helyx/bot 0.4.11 → 0.4.13

package/dist/events.js

@@ -1,7 +1,8 @@
 import { HELYX_SERVICE_NAMES } from "@helyx/sdk";
-import { ChannelType, Events, GatewayIntentBits, 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 } from "node:crypto";
+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) => ({
@@ -758,6 +759,44 @@ export class DiscordMemberEnforcementService {
             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 {
@@ -789,6 +828,751 @@ export class DiscordMemberEnforcementService {
         });
     }
 }
+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) {