@helyx/bot 1.3.1 → 1.5.0

package/dist/channel-audit-permissions.js

@@ -0,0 +1,417 @@
+import { CHANNEL_AUDIT_LIMITS } from "@helyx/control-protocol/channel-audit";
+export const AUDIT_PERMISSIONS = {
+    Administrator: 1n << 3n,
+    ManageGuild: 1n << 5n,
+    ViewChannel: 1n << 10n,
+    SendMessages: 1n << 11n,
+    ReadMessageHistory: 1n << 16n,
+    Connect: 1n << 20n,
+    Speak: 1n << 21n,
+    ManageRoles: 1n << 28n,
+    ManageChannels: 1n << 4n,
+    KickMembers: 1n << 1n,
+    BanMembers: 1n << 2n,
+    RequestToSpeak: 1n << 32n,
+    SendMessagesInThreads: 1n << 38n,
+};
+/** Discord's role union, everyone overwrite, then aggregate role deny/allow. */
+export function effectiveAuditPermissions(guildId, roles, selectedRoleIds, channel) {
+    if (channel.obfuscated)
+        return null;
+    const selected = new Set([guildId, ...selectedRoleIds]);
+    const roleMap = new Map(roles.map((role) => [role.id, role]));
+    let permissions = 0n;
+    for (const id of selected) {
+        const role = roleMap.get(id);
+        if (!role)
+            return null;
+        permissions |= role.permissions;
+    }
+    if (has(permissions, AUDIT_PERMISSIONS.Administrator))
+        return (1n << 64n) - 1n;
+    const everyone = channel.overwrites.find((overwrite) => overwrite.type === 0 && overwrite.id === guildId);
+    if (everyone)
+        permissions = (permissions & ~everyone.deny) | everyone.allow;
+    let allow = 0n, deny = 0n;
+    for (const overwrite of channel.overwrites) {
+        if (overwrite.type !== 0 ||
+            overwrite.id === guildId ||
+            !selected.has(overwrite.id))
+            continue;
+        allow |= overwrite.allow;
+        deny |= overwrite.deny;
+    }
+    return (permissions & ~deny) | allow;
+}
+function has(permissions, permission) {
+    return permissions !== null && (permissions & permission) === permission;
+}
+const channelTypes = new Map([
+    [0, "Text"],
+    [5, "Announcement"],
+    [15, "Forum"],
+    [16, "Media"],
+    [2, "Voice"],
+    [13, "Stage"],
+    [4, "Category"],
+    [10, "Announcement thread"],
+    [11, "Public thread"],
+    [12, "Private thread"],
+]);
+const activityTypes = new Set([0, 5, 15, 16, 2, 13]);
+/** Raw bit presence is insufficient: view/connect prerequisites gate actions. */
+export function auditActions(permissions, type) {
+    if (!activityTypes.has(type) ||
+        !has(permissions, AUDIT_PERMISSIONS.ViewChannel))
+        return [];
+    const actions = ["View"];
+    if ([0, 5].includes(type)) {
+        if (has(permissions, AUDIT_PERMISSIONS.ReadMessageHistory))
+            actions.push("Read existing panel");
+        if (has(permissions, AUDIT_PERMISSIONS.SendMessages))
+            actions.push("Post messages");
+    }
+    else if ([15, 16].includes(type)) {
+        if (has(permissions, AUDIT_PERMISSIONS.SendMessages))
+            actions.push("Create posts");
+        if (has(permissions, AUDIT_PERMISSIONS.SendMessagesInThreads))
+            actions.push("Reply in accessible threads");
+    }
+    else if (has(permissions, AUDIT_PERMISSIONS.Connect)) {
+        actions.push("Connect");
+        if (type === 2 && has(permissions, AUDIT_PERMISSIONS.Speak))
+            actions.push("Speak");
+        if (type === 13 && has(permissions, AUDIT_PERMISSIONS.RequestToSpeak))
+            actions.push("Request to speak");
+    }
+    return actions;
+}
+const panelUsable = (permissions, type) => [0, 5].includes(type) &&
+    has(permissions, AUDIT_PERMISSIONS.ViewChannel | AUDIT_PERMISSIONS.ReadMessageHistory);
+export function buildChannelAuditReport(snapshot, moduleId, assumptions, observedAt) {
+    const findings = [];
+    const channels = [];
+    const add = (finding) => findings.push(finding);
+    const roles = new Map(snapshot.roles.map((role) => [role.id, role]));
+    const requiredRoles = new Set([
+        ...assumptions.beforeRoleIds,
+        assumptions.afterRoleId,
+    ]);
+    for (const roleId of requiredRoles) {
+        if (!roles.has(roleId))
+            add(snapshot.rolesComplete
+                ? {
+                    code: "role_not_in_guild",
+                    category: "blocked",
+                    title: "Selected role is not in this server",
+                    detail: "The fresh server role list does not contain this role. Select a current role from this server.",
+                    roleId,
+                }
+                : {
+                    code: "role_unknown",
+                    category: "unknown",
+                    title: "Could not inspect a selected role",
+                    detail: "The current server role list could not be fetched. This is not evidence that the role was deleted.",
+                    roleId,
+                });
+    }
+    const afterRole = roles.get(assumptions.afterRoleId);
+    if (afterRole?.assignmentPolicyReason)
+        add({
+            code: "after_role_policy_blocked",
+            category: "blocked",
+            title: "Helyx's safety policy blocks the after-check role",
+            detail: afterRole.assignmentPolicyReason,
+            roleId: afterRole.id,
+        });
+    for (const roleId of assumptions.beforeRoleIds) {
+        const beforeRole = roles.get(roleId);
+        if (beforeRole?.assignmentPolicyReason)
+            add({
+                code: "before_role_removal_policy_risk",
+                category: "review",
+                title: "Safety policy may prevent removing a before-check role",
+                detail: `${beforeRole.assignmentPolicyReason} If the entry workflow removes this role, that removal is also blocked.`,
+                roleId,
+            });
+        if (beforeRole?.assignable === false)
+            add({
+                code: "before_role_removal_risk",
+                category: "review",
+                title: "Review removal of a selected before-check role",
+                detail: `${beforeRole.assignmentReason ?? "Helyx cannot currently manage this role."} If the entry workflow is configured to remove it, that transition may fail.`,
+                roleId,
+            });
+        else if (beforeRole?.assignable === null)
+            add({
+                code: "before_role_removal_unknown",
+                category: "unknown",
+                title: "Before-role removal capability is unknown",
+                detail: "Helyx's current role-management capability could not be established. No removal is attempted by this audit.",
+                roleId,
+            });
+    }
+    if (afterRole &&
+        (afterRole.assignable === false ||
+            afterRole.managed ||
+            afterRole.id === snapshot.guildId))
+        add({
+            code: "after_role_unassignable",
+            category: "blocked",
+            title: "Helyx cannot assign the after-check role",
+            detail: afterRole.assignmentReason ??
+                "The role is managed, everyone, above Helyx, or Helyx lacks Manage Roles. This audit changes none of them.",
+            roleId: afterRole.id,
+        });
+    else if (afterRole?.assignable === null)
+        add({
+            code: "after_role_unknown",
+            category: "unknown",
+            title: "Role assignment capability could not be checked",
+            detail: "Helyx's current member and role-management permissions are unavailable.",
+            roleId: afterRole.id,
+        });
+    const dangerous = Object.entries(AUDIT_PERMISSIONS).filter(([name]) => [
+        "Administrator",
+        "ManageGuild",
+        "ManageRoles",
+        "ManageChannels",
+        "KickMembers",
+        "BanMembers",
+    ].includes(name));
+    for (const roleId of new Set([snapshot.guildId, ...requiredRoles])) {
+        const role = roles.get(roleId);
+        const names = role
+            ? dangerous
+                .filter(([, bit]) => has(role.permissions, bit))
+                .map(([name]) => name)
+            : [];
+        if (names.length)
+            add({
+                code: "high_impact_role",
+                category: "review",
+                title: "Review elevated role permissions",
+                detail: `Role grants ${names.join(", ")}. These permissions can undermine a restricted entrance.`,
+                roleId,
+            });
+    }
+    const selectedIds = new Set([
+        assumptions.entryChannelId,
+        ...assumptions.allowedChannelIds,
+        ...(assumptions.reviewChannelId ? [assumptions.reviewChannelId] : []),
+    ]);
+    const ordered = [...snapshot.channels].sort((left, right) => Number(selectedIds.has(right.id)) - Number(selectedIds.has(left.id)) ||
+        left.id.localeCompare(right.id));
+    const inspected = ordered.slice(0, CHANNEL_AUDIT_LIMITS.channels);
+    let unknownChannels = 0, unsupportedChannels = 0, broadAccess = 0;
+    const rolePaths = assumptions.beforeRoleIds.map((roleId) => ({
+        roleId,
+        entranceUsable: null,
+        visibleChannels: 0,
+    }));
+    for (const channel of inspected) {
+        if (channel.obfuscated) {
+            unknownChannels += 1;
+            continue;
+        }
+        if (!activityTypes.has(channel.type)) {
+            unsupportedChannels += 1;
+            continue;
+        }
+        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 retained = effectiveAuditPermissions(snapshot.guildId, snapshot.roles, [...assumptions.beforeRoleIds, assumptions.afterRoleId], channel);
+        const row = {
+            id: channel.id,
+            name: channel.name.slice(0, 100),
+            type: channelTypes.get(channel.type) ?? "Unsupported",
+            beforeActions: auditActions(before, channel.type),
+            afterActions: auditActions(after, channel.type),
+            retainedActions: auditActions(retained, channel.type),
+            limitations: [],
+        };
+        if (before === null || after === null)
+            row.limitations.push("Selected role assumptions could not all be evaluated.");
+        if (channel.overwrites.some((overwrite) => overwrite.type === 1))
+            row.limitations.push("Member-specific overwrites can change an individual's access.");
+        if ([15, 16].includes(channel.type))
+            row.limitations.push("Thread membership, archive/lock and thread-specific state are not inspected.");
+        if (channels.length < CHANNEL_AUDIT_LIMITS.reportChannels)
+            channels.push(row);
+        for (const path of rolePaths) {
+            const permissions = effectiveAuditPermissions(snapshot.guildId, snapshot.roles, [path.roleId], channel);
+            if (has(permissions, AUDIT_PERMISSIONS.ViewChannel))
+                path.visibleChannels += 1;
+            if (channel.id === assumptions.entryChannelId)
+                path.entranceUsable =
+                    permissions === null ? null : panelUsable(permissions, channel.type);
+        }
+        if (channel.id === assumptions.entryChannelId) {
+            if (before === null || everyone === null)
+                add({
+                    code: "entrance_unknown",
+                    category: "unknown",
+                    title: "Could not evaluate the entrance",
+                    detail: "One or more required role assumptions are unavailable.",
+                    channelId: channel.id,
+                });
+            else if (!panelUsable(before, channel.type))
+                add({
+                    code: "entrance_unusable",
+                    category: "blocked",
+                    title: "Assumed entrants cannot reliably reach the panel",
+                    detail: "A supported text or announcement entrance needs View Channel and Read Message History. Send Messages is not required to press a panel button.",
+                    channelId: channel.id,
+                });
+            else if (assumptions.entrance === "public" &&
+                !panelUsable(everyone, channel.type))
+                add({
+                    code: "public_entrance_unusable",
+                    category: "blocked",
+                    title: "Everyone cannot use the intended public entrance",
+                    detail: "The public path needs View Channel and Read Message History without relying on selected extra roles.",
+                    channelId: channel.id,
+                });
+            else {
+                add({
+                    code: "entrance_working",
+                    category: "working",
+                    title: "Entrance is reachable under the selected assumptions",
+                    detail: "Role-only permissions allow reading the entrance. This does not prove a panel exists, is active or will accept a particular member.",
+                    channelId: channel.id,
+                });
+                if (assumptions.entrance === "restricted" &&
+                    has(everyone, AUDIT_PERMISSIONS.ViewChannel))
+                    add({
+                        code: "entrance_public",
+                        category: "review",
+                        title: "The restricted entrance is visible to everyone",
+                        detail: "Review whether the selected public/restricted intent matches your server design. No lockdown or permission change is applied.",
+                        channelId: channel.id,
+                    });
+            }
+            const publishing = AUDIT_PERMISSIONS.ViewChannel | AUDIT_PERMISSIONS.SendMessages;
+            if (channel.botPermissions === null)
+                add({
+                    code: "bot_publish_unknown",
+                    category: "unknown",
+                    title: "Helyx publishing access could not be checked",
+                    detail: "Current bot-specific permissions are unavailable.",
+                    channelId: channel.id,
+                });
+            else if (!has(channel.botPermissions, publishing))
+                add({
+                    code: "bot_cannot_publish",
+                    category: "blocked",
+                    title: "Helyx cannot publish an entrance panel here",
+                    detail: "Helyx needs View Channel and Send Messages in the selected entrance. Existing publication safeguards still apply.",
+                    channelId: channel.id,
+                });
+        }
+        else if (has(before, AUDIT_PERMISSIONS.ViewChannel) &&
+            !assumptions.allowedChannelIds.includes(channel.id))
+            broadAccess += 1;
+        if (channel.id === assumptions.reviewChannelId &&
+            has(before, AUDIT_PERMISSIONS.ViewChannel))
+            add({
+                code: "review_exposure",
+                category: "review",
+                title: "Assumed entrants can view the selected staff-review channel",
+                detail: "Review this explicitly selected staff-review destination separately from entrance visibility.",
+                channelId: channel.id,
+            });
+    }
+    for (const channelId of selectedIds) {
+        const invalid = snapshot.invalidSelectedChannels?.find((item) => item.id === channelId);
+        if (invalid) {
+            add({
+                code: "selected_channel_invalid",
+                category: "blocked",
+                title: "Selected channel is unavailable in this server",
+                detail: invalid.reason === "wrong_guild"
+                    ? "The fresh channel lookup identified a different server. Choose a channel from this server."
+                    : "Discord returned Unknown Channel for this selected ID. It may be deleted or invalid; this does not establish when or why it became unavailable.",
+                channelId,
+            });
+            continue;
+        }
+        const channel = inspected.find((item) => item.id === channelId);
+        if (!channel || channel.obfuscated)
+            add({
+                code: "selected_channel_unknown",
+                category: "unknown",
+                title: "A selected channel could not be inspected",
+                detail: "Discord may omit or obfuscate channels Helyx cannot view. Absence from this inspection is not proof of deletion or of entrant denial.",
+                channelId,
+            });
+        else if (!activityTypes.has(channel.type))
+            add({
+                code: "selected_channel_unsupported",
+                category: "unknown",
+                title: "Selected channel type is outside this audit",
+                detail: "Categories, individual threads and other unsupported types are not counted as a usable entrance or as a pass.",
+                channelId,
+            });
+    }
+    if (broadAccess)
+        add({
+            code: "wider_access",
+            category: "review",
+            title: "Review wider before-check access",
+            detail: `The combined before-role assumption can view ${broadAccess} inspected channels beyond the entrance and allowed exceptions. Wider access is advisory.`,
+        });
+    if (!assumptions.reviewChannelId)
+        add({
+            code: "review_context_unknown",
+            category: "unknown",
+            title: "Staff-review exposure has no selected context",
+            detail: "Select a staff-review channel or explicitly Load config to assess that destination. Hidden channels are not assumed to be staff-only.",
+        });
+    const limitations = [
+        "Role assumptions exclude member overwrites, screening, timeouts and actual member assignment; no member directory or messages are read.",
+        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.",
+        "The retained view includes all selected before roles; it does not enumerate every partially retained role combination.",
+        ...snapshot.fetchLimitations,
+    ];
+    if (!snapshot.totalChannelsKnown)
+        limitations.push("Coverage is limited to Discord's bot-visible channel list and known inventory; other inaccessible channels may be omitted and their total is unknown.");
+    const channelsTruncated = snapshot.channels.length > inspected.length ||
+        inspected.filter((channel) => !channel.obfuscated && activityTypes.has(channel.type)).length > channels.length;
+    if (unknownChannels || unsupportedChannels || channelsTruncated)
+        add({
+            code: "coverage_incomplete",
+            category: "unknown",
+            title: "Some channel coverage is incomplete",
+            detail: `${unknownChannels} observed channels are unknown/obfuscated; ${unsupportedChannels} types are unsupported. ${channelsTruncated ? "Inspection or displayed channel rows were capped." : "Unsupported channels are not passed."}`,
+        });
+    // Keep failures and uncertainty before successful findings if the output cap is reached.
+    const priority = { blocked: 0, unknown: 1, review: 2, working: 3 };
+    findings.sort((left, right) => priority[left.category] - priority[right.category]);
+    return {
+        guildId: snapshot.guildId,
+        moduleId,
+        observedAt,
+        assumptions: structuredClone(assumptions),
+        simulation: false,
+        findings: findings.slice(0, CHANNEL_AUDIT_LIMITS.findings),
+        channels,
+        rolePaths,
+        coverage: {
+            fetchedChannels: snapshot.fetchedChannels,
+            totalChannelsKnown: snapshot.totalChannelsKnown,
+            inspectedChannels: inspected.length,
+            returnedChannels: channels.length,
+            unknownChannels,
+            unsupportedChannels,
+            channelsTruncated,
+            findingsTruncated: findings.length > CHANNEL_AUDIT_LIMITS.findings,
+            roleOnly: true,
+            limitations: limitations.slice(0, 12),
+        },
+    };
+}
+//# sourceMappingURL=channel-audit-permissions.js.map

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

@@ -0,0 +1,4 @@
+import type { ChannelAuditControl } from "@helyx/sdk";
+import type { FastifyInstance } from "fastify";
+export declare function registerChannelAuditRoutes(server: FastifyInstance, control: ChannelAuditControl): void;
+//# sourceMappingURL=channel-audit-routes.d.ts.map

package/dist/channel-audit-routes.js

@@ -0,0 +1,42 @@
+import { channelAuditModuleIdSchema, channelAuditInputSchema, channelAuditConfigurationSchema, channelAuditReportSchema, } from "@helyx/control-protocol/channel-audit";
+import { z } from "zod";
+import { BotControlTransportError } from "./control-errors.js";
+const parameters = z
+    .object({
+    guildId: z.string().regex(/^\d{17,20}$/u),
+    moduleId: channelAuditModuleIdSchema,
+})
+    .strict();
+const actor = z
+    .object({
+    actorUserId: z.string().regex(/^\d{17,20}$/u),
+    correlationId: z.uuid(),
+})
+    .strict();
+export function registerChannelAuditRoutes(server, control) {
+    server.post("/v1/guilds/:guildId/modules/:moduleId/channel-audit/config", async (request) => {
+        const input = {
+            ...parameters.parse(request.params),
+            ...actor.parse(request.body),
+        };
+        if (!control.readChannelAuditConfiguration)
+            throw unsupported();
+        return channelAuditConfigurationSchema.parse(await control.readChannelAuditConfiguration(input));
+    });
+    server.post("/v1/guilds/:guildId/modules/:moduleId/channel-audit/check", async (request) => {
+        const input = {
+            ...parameters.parse(request.params),
+            ...actor
+                .extend({ assumptions: channelAuditInputSchema })
+                .strict()
+                .parse(request.body),
+        };
+        if (!control.checkChannelAudit)
+            throw unsupported();
+        return channelAuditReportSchema.parse(await control.checkChannelAudit(input));
+    });
+}
+function unsupported() {
+    return new BotControlTransportError(503, "This bot version does not support Channel audit. Update the bot before trying again.");
+}
+//# sourceMappingURL=channel-audit-routes.js.map

package/dist/cloud-connector.d.ts

@@ -4,6 +4,8 @@ import { type CloudConnectorConsentRecord, type DatabasePool } from "@helyx/data
 import type { Client } from "discord.js";
 import type { Logger } from "pino";
 import type { ConfiguredModulePackage } from "./modules.js";
+import type { GuildCommandReadHandler } from "./guild-command-read-service.js";
+import { type CloudConnectorStore } from "./cloud-control-dispatcher.js";
 import { type BotControlHandler } from "./control-server.js";
 type ConnectorState = "disabled" | "unpaired" | "connecting" | "online" | "offline" | "recovery_required" | "revoked" | "stopped";
 export interface CloudConnectorStatus {
@@ -27,7 +29,7 @@ export interface CloudDiscordDirectory {
     snapshot(): Promise<CloudDiscordSnapshot>;
 }
 export interface CloudConnector {
-    setControlHandler(handler: BotControlHandler): void;
+    setControlHandler(handler: BotControlHandler, commands?: GuildCommandReadHandler): void;
     start(): Promise<void>;
     status(): CloudConnectorStatus;
     getSupportConsent(): Promise<CloudConnectorConsentRecord>;
@@ -54,13 +56,18 @@ export declare class CloudConnectorController implements CloudConnector {
     private readonly input;
     constructor(input: {
         environment: BotEnvironment;
-        database: DatabasePool;
         discord: CloudDiscordDirectory;
         modules: readonly ConfiguredModulePackage[];
         coreVersion: string;
         logger: Logger;
-    });
-    setControlHandler(handler: BotControlHandler): void;
+    } & ({
+        database: DatabasePool;
+        repository?: never;
+    } | {
+        repository: CloudConnectorStore;
+        database?: never;
+    }));
+    setControlHandler(handler: BotControlHandler, commands?: GuildCommandReadHandler): void;
     start(): Promise<void>;
     status(): CloudConnectorStatus;
     getSupportConsent(): Promise<CloudConnectorConsentRecord>;

package/dist/cloud-connector.js

@@ -87,7 +87,8 @@ export class CloudConnectorController {
     #pendingSupport = new Map();
     constructor(input) {
         this.input = input;
-        this.#repository = new CloudConnectorRepository(input.database);
+        this.#repository =
+            input.repository ?? new CloudConnectorRepository(input.database);
         this.#state = input.environment.HELYX_CLOUD_CONNECT_ENABLED
             ? "unpaired"
             : "disabled";
@@ -95,8 +96,10 @@ export class CloudConnectorController {
             ? Buffer.from(input.environment.HELYX_DATA_ENCRYPTION_KEY, "base64")
             : undefined;
     }
-    setControlHandler(handler) {
-        this.#dispatcher = new CloudControlDispatcher(this.input.database, handler);
+    setControlHandler(handler, commands) {
+        this.#dispatcher = this.input.database
+            ? new CloudControlDispatcher(this.input.database, handler, commands)
+            : new CloudControlDispatcher({ repository: this.#repository }, handler, commands);
     }
     async start() {
         if (!this.input.environment.HELYX_CLOUD_CONNECT_ENABLED)
@@ -414,6 +417,8 @@ export class CloudConnectorController {
         let outgoingSequence = 0;
         let heartbeat;
         let plannedReconnect;
+        let activeControlRequests = 0;
+        let draining = false;
         const privateKey = decryptPrivateKey(identity.privateKey, this.#dataKey, identity.installationId);
         const finished = new Promise((resolveFinished, rejectFinished) => {
             const fail = (error) => {
@@ -475,10 +480,32 @@ export class CloudConnectorController {
                                     installationId: identity.installationId,
                                     connectionEpoch: accepted.data.connectionEpoch,
                                     sequence: ++outgoingSequence,
-                                    payload: { state: "online" },
+                                    payload: { state: draining ? "draining" : "online" },
                                 })));
                             }, accepted.data.heartbeatIntervalSeconds * 1_000);
-                            plannedReconnect = setTimeout(() => socket.close(1012, "Planned Cloud Connect session rotation"), accepted.data.reconnectBeforeSeconds * 1_000);
+                            plannedReconnect = setTimeout(() => {
+                                if (socket.readyState !== WebSocket.OPEN)
+                                    return;
+                                draining = true;
+                                socket.send(JSON.stringify(connectedMessage({
+                                    type: "connector.draining",
+                                    installationId: identity.installationId,
+                                    connectionEpoch: accepted.data.connectionEpoch,
+                                    sequence: ++outgoingSequence,
+                                    payload: { reason: "session_rotation" },
+                                })));
+                                const deadline = Date.now() + 45_000;
+                                const closeWhenIdle = () => {
+                                    if (socket.readyState !== WebSocket.OPEN)
+                                        return;
+                                    if (activeControlRequests === 0 || Date.now() >= deadline) {
+                                        socket.close(1012, "Planned Cloud Connect session rotation");
+                                        return;
+                                    }
+                                    plannedReconnect = setTimeout(closeWhenIdle, 250);
+                                };
+                                plannedReconnect = setTimeout(closeWhenIdle, 1_000);
+                            }, accepted.data.reconnectBeforeSeconds * 1_000);
                             return;
                         }
                         const rejected = connectorRejectedSchema.safeParse(payload);
@@ -518,16 +545,22 @@ export class CloudConnectorController {
                         }
                         if (message.type !== "control.request")
                             return;
-                        const response = await this.#dispatch(message.payload, message.correlationId);
-                        if (socket.readyState === WebSocket.OPEN)
-                            socket.send(JSON.stringify(connectedMessage({
-                                type: "control.response",
-                                installationId: identity.installationId,
-                                connectionEpoch: message.connectionEpoch,
-                                sequence: ++outgoingSequence,
-                                correlationId: message.correlationId,
-                                payload: response,
-                            })));
+                        activeControlRequests += 1;
+                        try {
+                            const response = await this.#dispatch(message.payload, message.correlationId);
+                            if (socket.readyState === WebSocket.OPEN)
+                                socket.send(JSON.stringify(connectedMessage({
+                                    type: "control.response",
+                                    installationId: identity.installationId,
+                                    connectionEpoch: message.connectionEpoch,
+                                    sequence: ++outgoingSequence,
+                                    correlationId: message.correlationId,
+                                    payload: response,
+                                })));
+                        }
+                        finally {
+                            activeControlRequests -= 1;
+                        }
                     }
                     catch (error) {
                         this.input.logger.warn({
@@ -722,10 +755,16 @@ function connectorCapabilities() {
         "guild.dashboard.access.read.v1",
         "guild.access-policy.read.v1",
         "guild.access-policy.write.v1",
+        "guild.commands.status.read.v1",
+        "guild.commands.history.read.v1",
+        "guild.commands.status.refresh.v1",
+        "guild.commands.rebuild.v1",
         "guild.module.public.read.v1",
         "guild.module.status.write.v1",
         "guild.module.configuration.write.v1",
         "guild.module.configuration.preview.v1",
+        "guild.module.channel-audit.config.read.v1",
+        "guild.module.channel-audit.check.v1",
         "guild.module.permissions.write.v1",
         "guild.module.logging.write.v1",
         "guild.module.action.execute.v1",

package/dist/cloud-control-dispatcher.d.ts

@@ -1,11 +1,16 @@
 import { type CloudControlRequestPayload } from "@helyx/control-protocol";
-import { type DatabasePool } from "@helyx/database";
+import { CloudConnectorRepository, type DatabasePool } from "@helyx/database";
 import type { BotControlHandler, BotControlState } from "./control-server.js";
+import type { GuildCommandReadHandler } from "./guild-command-read-service.js";
+export type CloudConnectorStore = Pick<CloudConnectorRepository, "getIdentity" | "createIdentity" | "rotateIdentity" | "markConnected" | "revoke" | "getConsent" | "updateConsent" | "appendAudit" | "cleanupAudit">;
 export declare class CloudControlDispatcher {
     #private;
-    private readonly database;
     private readonly control;
-    constructor(database: DatabasePool, control: BotControlHandler);
+    private readonly commands?;
+    constructor(database: DatabasePool, control: BotControlHandler, commands?: GuildCommandReadHandler);
+    constructor(input: {
+        repository: CloudConnectorStore;
+    }, control: BotControlHandler, commands?: GuildCommandReadHandler);
     execute(request: CloudControlRequestPayload, correlationId: string): Promise<unknown>;
 }
 export declare class CloudControlDeniedError extends Error {