@helyx/bot 1.5.1 → 1.5.3

package/dist/cached-message-deletion-authority.js

@@ -0,0 +1,288 @@
+import { ChannelType, PermissionFlagsBits, PermissionsBitField, } from "discord.js";
+const snowflake = /^\d{17,20}$/u;
+const messageTypes = new Set([
+    ChannelType.GuildText,
+    ChannelType.GuildAnnouncement,
+    ChannelType.GuildVoice,
+    ChannelType.GuildStageVoice,
+    ChannelType.PublicThread,
+    ChannelType.AnnouncementThread,
+    ChannelType.PrivateThread,
+]);
+const maximumAssignedRoles = 1024; // Engineering bound, not a Discord product limit.
+/** Called only by future Core exact-event capture. Cache membership alone is not event provenance. */
+export function captureCachedMessageDeletionAuthority(options) {
+    let stopped = false, checking = false;
+    try {
+        const { client, expectedApplicationId, eligibility, isStopped } = options;
+        const source = { ...options.source };
+        const { channel } = source;
+        const scope = Object.freeze({
+            guildId: source.guildId,
+            moduleId: source.moduleId,
+            channelId: source.channelId,
+            messageId: source.messageId,
+            admissionToken: source.admissionToken,
+        });
+        if (!snowflake.test(expectedApplicationId) ||
+            ![scope.guildId, scope.channelId, scope.messageId].every((id) => typeof id === "string" && snowflake.test(id)) ||
+            typeof scope.moduleId !== "string" ||
+            !/^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)+$/u.test(scope.moduleId) ||
+            scope.moduleId.length > 128 ||
+            typeof scope.admissionToken !== "string" ||
+            !/^[A-Za-z0-9._:-]{1,256}$/u.test(scope.admissionToken) ||
+            typeof isStopped !== "function" ||
+            typeof eligibility?.read !== "function" ||
+            typeof eligibility.isCurrent !== "function")
+            return undefined;
+        const readEligibility = eligibility.read, tokenCurrent = eligibility.isCurrent;
+        const hold = () => {
+            stopped = true;
+            return false;
+        };
+        const running = () => {
+            if (stopped)
+                return false;
+            try {
+                const external = isStopped();
+                return !stopped && external === false ? true : hold();
+            }
+            catch {
+                return hold();
+            }
+        };
+        const eligible = () => {
+            if (!running())
+                return false;
+            const observed = readEligibility(scope.guildId, scope.moduleId);
+            if (!running() ||
+                observed.state !== "enabled" ||
+                observed.generation !== scope.admissionToken)
+                return hold();
+            const current = tokenCurrent(scope.admissionToken);
+            return running() && current === true ? true : hold();
+        };
+        const ready = () => {
+            if (!running())
+                return false;
+            const current = client.isReady();
+            if (!running() || current !== true)
+                return hold();
+            const user = client.user, application = client.application;
+            return running() &&
+                user?.id === expectedApplicationId &&
+                application?.id === expectedApplicationId
+                ? true
+                : hold();
+        };
+        if (!eligible() || !ready())
+            return undefined;
+        const guild = client.guilds.cache.get(scope.guildId);
+        if (!running() ||
+            !guild ||
+            guild.id !== scope.guildId ||
+            guild.client !== client ||
+            guild.available !== true ||
+            guild.channels.cache.get(scope.channelId) !== channel ||
+            channel.id !== scope.channelId ||
+            !supported(channel))
+            return undefined;
+        const bindings = captureBindings(guild, channel, client);
+        if (!running() || !bindings)
+            return undefined;
+        const authority = Object.freeze({
+            scope,
+            stop: () => {
+                stopped = true;
+            },
+            isCurrent: () => {
+                if (stopped)
+                    return false;
+                if (checking)
+                    return hold();
+                checking = true;
+                try {
+                    if (!eligible() || !ready())
+                        return hold();
+                    if (client.guilds.cache.get(scope.guildId) !== guild ||
+                        guild.id !== scope.guildId ||
+                        guild.client !== client ||
+                        guild.available !== true ||
+                        !running())
+                        return hold();
+                    for (const binding of bindings) {
+                        if (!running() || !sameBinding(guild, binding, client))
+                            return hold();
+                    }
+                    if (!running() || !supported(channel))
+                        return hold();
+                    const member = guild.members.cache.get(expectedApplicationId);
+                    if (!running() ||
+                        !member ||
+                        member.id !== expectedApplicationId ||
+                        member.user.id !== expectedApplicationId ||
+                        member.guild !== guild ||
+                        member.client !== client ||
+                        member.partial !== false)
+                        return hold();
+                    if (!running() || !completeRoles(guild, member, client, running))
+                        return hold();
+                    if (channel.type === ChannelType.PrivateThread) {
+                        if (!running() || !channel.isThread())
+                            return hold();
+                        const joined = channel.members.cache.get(expectedApplicationId);
+                        if (!running() ||
+                            !joined ||
+                            joined.id !== expectedApplicationId ||
+                            joined.thread !== channel ||
+                            joined.client !== client ||
+                            joined.partial !== false ||
+                            typeof joined.joinedTimestamp !== "number" ||
+                            !Number.isFinite(joined.joinedTimestamp) ||
+                            joined.joinedTimestamp < 0)
+                            return hold();
+                    }
+                    if (!running())
+                        return hold();
+                    const permissions = channel.permissionsFor(member);
+                    if (!running() || !(permissions instanceof PermissionsBitField))
+                        return hold();
+                    const allowed = permissions.has([
+                        PermissionFlagsBits.ViewChannel,
+                        PermissionFlagsBits.ManageMessages,
+                    ]);
+                    if (!running() || allowed !== true)
+                        return hold();
+                    const administrator = permissions.has(PermissionFlagsBits.Administrator, false);
+                    if (!running())
+                        return hold();
+                    const until = member.communicationDisabledUntilTimestamp;
+                    if (!running() ||
+                        (until !== null &&
+                            (typeof until !== "number" ||
+                                !Number.isFinite(until) ||
+                                until < 0)))
+                        return hold();
+                    if (!administrator && until !== null) {
+                        const now = Date.now();
+                        if (!running() || !Number.isFinite(now) || now < 0 || until > now)
+                            return hold();
+                    }
+                    if (!eligible() || !running())
+                        return hold();
+                    return true;
+                }
+                catch {
+                    return hold();
+                }
+                finally {
+                    checking = false;
+                }
+            },
+        });
+        return authority.isCurrent() ? authority : undefined;
+    }
+    catch {
+        stopped = true;
+        return undefined;
+    }
+}
+function supported(channel) {
+    return (messageTypes.has(channel.type) &&
+        channel.partial === false &&
+        channel.isTextBased() &&
+        !channel.isDMBased());
+}
+function sameBinding(guild, binding, client) {
+    const channel = binding.channel;
+    return (channel.id === binding.id &&
+        guild.channels.cache.get(binding.id) === channel &&
+        channel.guild === guild &&
+        channel.guildId === guild.id &&
+        channel.client === client &&
+        channel.type === binding.type &&
+        channel.parentId === binding.parentId &&
+        channel.partial === false);
+}
+function captureBindings(guild, channel, client) {
+    const result = [];
+    const bind = (value) => {
+        const binding = Object.freeze({
+            channel: value,
+            id: value.id,
+            type: value.type,
+            parentId: value.parentId,
+        });
+        if (!(binding.parentId === null ||
+            (typeof binding.parentId === "string" &&
+                snowflake.test(binding.parentId))) ||
+            !sameBinding(guild, binding, client))
+            return false;
+        result.push(binding);
+        return true;
+    };
+    if (!bind(channel))
+        return undefined;
+    let categoryId = channel.parentId;
+    if (channel.isThread()) {
+        if (!categoryId)
+            return undefined;
+        const parent = guild.channels.cache.get(categoryId);
+        const allowed = channel.type === ChannelType.AnnouncementThread
+            ? [ChannelType.GuildAnnouncement]
+            : channel.type === ChannelType.PrivateThread
+                ? [ChannelType.GuildText]
+                : [
+                    ChannelType.GuildText,
+                    ChannelType.GuildForum,
+                    ChannelType.GuildMedia,
+                ];
+        if (!parent || !allowed.includes(parent.type) || !bind(parent))
+            return undefined;
+        categoryId = parent.parentId;
+    }
+    if (categoryId) {
+        const category = guild.channels.cache.get(categoryId);
+        if (!category ||
+            category.type !== ChannelType.GuildCategory ||
+            category.parentId !== null ||
+            !bind(category))
+            return undefined;
+    }
+    return Object.freeze(result);
+}
+function completeRoles(guild, member, client, running) {
+    const ids = Reflect.get(member, "_roles");
+    if (!running() || !Array.isArray(ids) || ids.length > maximumAssignedRoles)
+        return false;
+    const length = ids.length;
+    const roleIds = new Set();
+    for (let index = 0; index < length; index++) {
+        const id = ids[index];
+        if (!running() ||
+            typeof id !== "string" ||
+            !snowflake.test(id) ||
+            roleIds.has(id))
+            return false;
+        roleIds.add(id);
+    }
+    if (ids.length !== length)
+        return false;
+    roleIds.add(guild.id);
+    for (const id of roleIds) {
+        if (!running())
+            return false;
+        const role = guild.roles.cache.get(id);
+        if (!running() ||
+            !role ||
+            role.id !== id ||
+            role.guild !== guild ||
+            role.client !== client ||
+            !(role.permissions instanceof PermissionsBitField) ||
+            typeof role.permissions.bitfield !== "bigint" ||
+            role.permissions.bitfield < 0n)
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=cached-message-deletion-authority.js.map

package/dist/channel-audit-configuration.d.ts

@@ -3,5 +3,15 @@ import type { ChannelAuditConfiguration, ChannelAuditModuleId } from "@helyx/sdk
 export declare function channelAuditConfiguration(moduleId: ChannelAuditModuleId, configuration: {
     version: number;
     value: Record<string, unknown>;
-} | null): ChannelAuditConfiguration;
+} | null, welcome?: {
+    status: "loaded";
+    version: number | null;
+    enabled: boolean;
+    roleId: string | null;
+} | {
+    status: "unavailable";
+    version: null;
+    enabled: null;
+    roleId: null;
+}): ChannelAuditConfiguration;
 //# sourceMappingURL=channel-audit-configuration.d.ts.map

package/dist/channel-audit-configuration.js

@@ -1,6 +1,6 @@
 import { CHANNEL_AUDIT_LIMITS, channelAuditConfigurationSchema, } from "@helyx/control-protocol/channel-audit";
 /** Deliberate allowlist: never return provider state, answers or the saved settings object. */
-export function channelAuditConfiguration(moduleId, configuration) {
+export function channelAuditConfiguration(moduleId, configuration, welcome) {
     const value = configuration?.value ?? {};
     const mappedFields = [];
     const id = (field) => {
@@ -13,7 +13,7 @@ export function channelAuditConfiguration(moduleId, configuration) {
     const entryChannelId = id(moduleId === "helyx.account-gate"
         ? "gateChannelId"
         : "verificationChannelId");
-    const afterRoleId = id("verifiedRoleId");
+    const configuredAfterRoleId = id("verifiedRoleId");
     const reviewChannelId = moduleId === "helyx.account-gate" ? id("reviewChannelId") : null;
     const configuredRoles = moduleId === "helyx.account-gate" && Array.isArray(value.temporaryRoleIds)
         ? [
@@ -23,18 +23,40 @@ export function channelAuditConfiguration(moduleId, configuration) {
     if (configuredRoles.length)
         mappedFields.push("temporaryRoleIds");
     const suggested = moduleId === "helyx.verification" ? id("roleToRemoveId") : null;
-    const beforeRoleIds = suggested
-        ? [suggested]
-        : configuredRoles.slice(0, CHANNEL_AUDIT_LIMITS.beforeRoles);
+    const configuredRemovedRoleIds = suggested ? [suggested] : configuredRoles;
+    // An existing invalid save can grant and remove the same role. Do not
+    // project that as a usable journey: require the owner to select the grant
+    // role again while preserving the configured removal evidence.
+    const afterRoleId = configuredRemovedRoleIds.includes(configuredAfterRoleId ?? "")
+        ? null
+        : configuredAfterRoleId;
+    const welcomeRoleId = welcome?.status === "loaded" && welcome.enabled ? welcome.roleId : null;
+    const reserveWelcomeSlot = welcomeRoleId !== null &&
+        !configuredRemovedRoleIds
+            .slice(0, CHANNEL_AUDIT_LIMITS.beforeRoles)
+            .includes(welcomeRoleId);
+    const boundedRemovedRoleIds = configuredRemovedRoleIds.slice(0, CHANNEL_AUDIT_LIMITS.beforeRoles - (reserveWelcomeSlot ? 1 : 0));
+    const removedRoleIds = welcomeRoleId &&
+        configuredRemovedRoleIds.includes(welcomeRoleId) &&
+        !boundedRemovedRoleIds.includes(welcomeRoleId)
+        ? [...boundedRemovedRoleIds, welcomeRoleId]
+        : boundedRemovedRoleIds;
+    const beforeRoleIds = [
+        ...new Set([...removedRoleIds, ...(welcomeRoleId ? [welcomeRoleId] : [])]),
+    ].slice(0, CHANNEL_AUDIT_LIMITS.beforeRoles);
     return channelAuditConfigurationSchema.parse({
         moduleId,
         version: configuration?.version ?? null,
         entryChannelId,
         beforeRoleIds,
+        removedRoleIds,
         afterRoleId,
         reviewChannelId,
+        ...(welcome ? { welcome } : {}),
         mappedFields,
-        truncated: configuredRoles.length > CHANNEL_AUDIT_LIMITS.beforeRoles,
+        truncated: configuredRemovedRoleIds.length > removedRoleIds.length ||
+            new Set([...removedRoleIds, ...(welcomeRoleId ? [welcomeRoleId] : [])])
+                .size > CHANNEL_AUDIT_LIMITS.beforeRoles,
     });
 }
 //# sourceMappingURL=channel-audit-configuration.js.map

package/dist/channel-audit-control.js

@@ -25,17 +25,57 @@ export function createChannelAuditControl(input) {
         if (!installed.some((item) => item.moduleId === context.moduleId))
             throw new BotControlNotFoundError("This module is not installed for this server");
         await input.requireAccessible(context.guildId, context.moduleId);
+        return { actor, guildAccess, installed };
+    };
+    const unavailableWelcome = () => ({
+        status: "unavailable",
+        version: null,
+        enabled: null,
+        roleId: null,
+    });
+    const readWelcome = async (context, authority) => {
+        const moduleId = "helyx.welcome";
+        const installation = authority.installed.find((item) => item.moduleId === moduleId);
+        const module = input.modules.get(moduleId);
+        if (!installation || !module?.manifest.dashboard)
+            return unavailableWelcome();
+        try {
+            const resolvedPolicy = await input.permissions.getPolicy(context.guildId, moduleId);
+            if (!canAccessGuildDashboard(authority.actor, authority.guildAccess) ||
+                !canUseCommand(authority.actor, resolvedPolicy.policy, authority.guildAccess))
+                return unavailableWelcome();
+            await input.requireAccessible(context.guildId, moduleId);
+        }
+        catch {
+            return unavailableWelcome();
+        }
+        try {
+            const configuration = await input.configurations.get(context.guildId, moduleId);
+            const candidate = configuration?.value.roleId;
+            return {
+                status: "loaded",
+                version: configuration ? safeVersion(configuration.version) : null,
+                enabled: installation.enabled,
+                roleId: typeof candidate === "string" && /^\d{17,20}$/u.test(candidate)
+                    ? candidate
+                    : null,
+            };
+        }
+        catch {
+            return unavailableWelcome();
+        }
     };
     return {
         readChannelAuditConfiguration: async (context) => {
-            await authorize(context);
+            const authority = await authorize(context);
             const configuration = await input.configurations.get(context.guildId, context.moduleId);
+            const welcome = await readWelcome(context, authority);
             return channelAuditConfiguration(context.moduleId, configuration
                 ? {
                     version: safeVersion(configuration.version),
                     value: configuration.value,
                 }
-                : null);
+                : null, welcome);
         },
         checkChannelAudit: async (context) => {
             const assumptions = channelAuditInputSchema.parse(context.assumptions);

package/dist/channel-audit-permissions.js

@@ -93,6 +93,9 @@ export function buildChannelAuditReport(snapshot, moduleId, assumptions, observe
     const channels = [];
     const add = (finding) => findings.push(finding);
     const roles = new Map(snapshot.roles.map((role) => [role.id, role]));
+    const removedRoleIds = assumptions.removedRoleIds ?? assumptions.beforeRoleIds;
+    const retainedBeforeRoleIds = assumptions.beforeRoleIds.filter((roleId) => !removedRoleIds.includes(roleId));
+    const afterRoleIds = [assumptions.afterRoleId, ...retainedBeforeRoleIds];
     const requiredRoles = new Set([
         ...assumptions.beforeRoleIds,
         assumptions.afterRoleId,
@@ -124,7 +127,7 @@ export function buildChannelAuditReport(snapshot, moduleId, assumptions, observe
             detail: afterRole.assignmentPolicyReason,
             roleId: afterRole.id,
         });
-    for (const roleId of assumptions.beforeRoleIds) {
+    for (const roleId of removedRoleIds) {
         const beforeRole = roles.get(roleId);
         if (beforeRole?.assignmentPolicyReason)
             add({
@@ -198,6 +201,7 @@ export function buildChannelAuditReport(snapshot, moduleId, assumptions, observe
     const selectedIds = new Set([
         assumptions.entryChannelId,
         ...assumptions.allowedChannelIds,
+        ...(assumptions.requiredAfterChannelIds ?? []),
         ...(assumptions.reviewChannelId ? [assumptions.reviewChannelId] : []),
     ]);
     const ordered = [...snapshot.channels].sort((left, right) => Number(selectedIds.has(right.id)) - Number(selectedIds.has(left.id)) ||
@@ -220,7 +224,7 @@ export function buildChannelAuditReport(snapshot, moduleId, assumptions, observe
         }
         const before = effectiveAuditPermissions(snapshot.guildId, snapshot.roles, assumptions.beforeRoleIds, channel);
         const everyone = effectiveAuditPermissions(snapshot.guildId, snapshot.roles, [], channel);
-        const after = effectiveAuditPermissions(snapshot.guildId, snapshot.roles, [assumptions.afterRoleId], channel);
+        const after = effectiveAuditPermissions(snapshot.guildId, snapshot.roles, afterRoleIds, channel);
         const retained = effectiveAuditPermissions(snapshot.guildId, snapshot.roles, [...assumptions.beforeRoleIds, assumptions.afterRoleId], channel);
         const row = {
             id: channel.id,
@@ -291,6 +295,47 @@ export function buildChannelAuditReport(snapshot, moduleId, assumptions, observe
                         channelId: channel.id,
                     });
             }
+            if (assumptions.entryAfter && assumptions.entryAfter !== "either") {
+                if (after === null)
+                    add({
+                        code: "entry_after_unknown",
+                        category: "unknown",
+                        title: "Could not verify entrance visibility after the check",
+                        detail: "One or more roles needed for the after-check view are unavailable. This is not evidence that the expected transition works.",
+                        channelId: channel.id,
+                    });
+                else {
+                    const visible = has(after, AUDIT_PERMISSIONS.ViewChannel);
+                    const expectedVisible = assumptions.entryAfter === "visible";
+                    add(visible === expectedVisible
+                        ? {
+                            code: expectedVisible
+                                ? "entry_after_visible"
+                                : "entry_after_hidden",
+                            category: "working",
+                            title: expectedVisible
+                                ? "Entrance remains visible after the check"
+                                : "Entrance is hidden after the check",
+                            detail: expectedVisible
+                                ? "The granted role plus every before role not selected for removal can view the entrance."
+                                : "The granted role plus every before role not selected for removal cannot view the entrance.",
+                            channelId: channel.id,
+                        }
+                        : {
+                            code: expectedVisible
+                                ? "entry_after_not_visible"
+                                : "entry_after_still_visible",
+                            category: "blocked",
+                            title: expectedVisible
+                                ? "Entrance is not visible after the check"
+                                : "Entrance remains visible after the check",
+                            detail: expectedVisible
+                                ? "The configured after-check role set cannot view the entrance."
+                                : "The granted role or a retained before role keeps the entrance visible after the transition.",
+                            channelId: channel.id,
+                        });
+                }
+            }
             const publishing = AUDIT_PERMISSIONS.ViewChannel | AUDIT_PERMISSIONS.SendMessages;
             if (channel.botPermissions === null)
                 add({
@@ -321,6 +366,32 @@ export function buildChannelAuditReport(snapshot, moduleId, assumptions, observe
                 detail: "Review this explicitly selected staff-review destination separately from entrance visibility.",
                 channelId: channel.id,
             });
+        if ((assumptions.requiredAfterChannelIds ?? []).includes(channel.id)) {
+            if (after === null)
+                add({
+                    code: "required_after_channel_unknown",
+                    category: "unknown",
+                    title: "Required after-check channel could not be verified",
+                    detail: "One or more roles needed for the after-check view are unavailable. This required channel is not counted as passing.",
+                    channelId: channel.id,
+                });
+            else if (has(after, AUDIT_PERMISSIONS.ViewChannel))
+                add({
+                    code: "required_after_channel_visible",
+                    category: "working",
+                    title: "Required after-check channel is visible",
+                    detail: "The granted role plus every before role not selected for removal can view this required channel.",
+                    channelId: channel.id,
+                });
+            else
+                add({
+                    code: "required_after_channel_hidden",
+                    category: "blocked",
+                    title: "Required after-check channel is not visible",
+                    detail: "The configured after-check role set cannot view this required channel.",
+                    channelId: channel.id,
+                });
+        }
     }
     for (const channelId of selectedIds) {
         const invalid = snapshot.invalidSelectedChannels?.find((item) => item.id === channelId);
@@ -373,7 +444,9 @@ export function buildChannelAuditReport(snapshot, moduleId, assumptions, observe
         moduleId === "helyx.account-gate"
             ? "Access Control grants the access role, then attempts removal of its configured temporary roles. Selected before roles are assumptions, and delivery can be partial."
             : "Verification grants the verified role and removes its configured removal role when present. It does not assign the before roles, and other member roles can remain.",
-        "After-check view assumes selected before roles were removed; the retained view shows their combination with the after role. Actual transitions can differ or partially complete.",
+        assumptions.removedRoleIds
+            ? "After-check view grants the selected after role, removes only the explicitly selected removal roles, and retains every other before role. Actual transitions can differ or partially complete."
+            : "Legacy after-check view assumes every selected before role was removed; the retained view shows their combination with the after role. Actual transitions can differ or partially complete.",
         "The retained view includes all selected before roles; it does not enumerate every partially retained role combination.",
         ...snapshot.fetchLimitations,
     ];

package/dist/cloud-command-policy-sync.d.ts

@@ -0,0 +1,26 @@
+import { type CommandPolicyDeliverySession, type CommandPolicyOwnerToken, type CommandPolicyPull } from "@helyx/database-contracts";
+import type { CommandPolicyDeliveryService } from "@helyx/platform";
+/** One authenticated socket, one bounded transfer, no customer policy authority. */
+export declare class CloudCommandPolicySynchronizer {
+    #private;
+    private readonly input;
+    constructor(input: {
+        applicationId: string;
+        owner: CommandPolicyOwnerToken;
+        session: CommandPolicyDeliverySession;
+        delivery: CommandPolicyDeliveryService;
+        send(correlationId: string, pull: CommandPolicyPull): void;
+        isOwnerCurrent?(): Promise<boolean>;
+        onHeld(): void;
+        intervalMs?: number;
+        timeoutMs?: number;
+    });
+    start(): Promise<void>;
+    runOnce(): Promise<void>;
+    /** Caller must first pass the current accepted envelope's sequence/epoch guard. */
+    accept(correlationId: string, payload: unknown, expiresAt: string): void;
+    /** Stop local activity before an atomic receipt-first identity transition. */
+    cancel(): void;
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=cloud-command-policy-sync.d.ts.map