@helyx/bot 0.1.3 → 0.2.1

package/dist/cloud-management-module.js

@@ -0,0 +1,491 @@
+import { defineModule, } from "@helyx/sdk";
+import { CloudConnectorUserError, } from "./cloud-connector.js";
+const CONNECT_MODAL_ID = "helyx.cloud.connect";
+const CONNECT_CODE_FIELD_ID = "helyx.cloud.connect.code";
+const DISCONNECT_MODAL_ID = "helyx.cloud.disconnect";
+const DISCONNECT_CONFIRM_FIELD_ID = "helyx.cloud.disconnect.confirm";
+const ROTATE_MODAL_ID = "helyx.cloud.rotate";
+const ROTATE_CONFIRM_FIELD_ID = "helyx.cloud.rotate.confirm";
+const SUPPORT_MODAL_ID = "helyx.cloud.support";
+const SUPPORT_ENABLED_FIELD_ID = "helyx.cloud.support.enabled";
+const SUPPORT_DATA_FIELD_ID = "helyx.cloud.support.data";
+const DIAGNOSTICS_ENABLED_FIELD_ID = "helyx.cloud.support.diagnostics";
+const VIOLET = 0x7c3aed;
+const SUCCESS = 0x16a34a;
+const DANGER = 0xdc2626;
+export function createCloudManagementModule(input) {
+    const requireOwner = async (context) => {
+        if (await isDeploymentOwner(input.client, context.userId, input.configuredOwnerUserIds))
+            return true;
+        await context.reply({
+            ephemeral: true,
+            componentsV2: {
+                accentColor: DANGER,
+                text: [
+                    {
+                        content: "## Deployment owner required\nOnly the Discord application owner, an application team member, or a user listed in `HELYX_OWNER_USER_IDS` can change Cloud Connect.",
+                    },
+                ],
+            },
+        });
+        return false;
+    };
+    return defineModule({
+        manifest: {
+            manifestVersion: "0.1",
+            releaseStatus: "live",
+            id: "helyx.cloud-connect",
+            name: "Helyx Cloud Connect",
+            version: "0.1.0",
+            description: "Links this self-hosted Helyx deployment to the hosted dashboard.",
+            entry: "./dist/cloud-management-module.js",
+            framework: "^0.1.0",
+            dependencies: [],
+            permissions: [],
+            contributions: { commands: ["helyx-cloud"], events: [] },
+        },
+        defaultPermissions: {
+            module: restrictedPolicy(),
+            commands: {
+                "helyx-cloud.connect": restrictedPolicy(),
+                "helyx-cloud.status": restrictedPolicy(),
+                "helyx-cloud.disconnect": restrictedPolicy(),
+                "helyx-cloud.rotate": restrictedPolicy(),
+                "helyx-cloud.support": restrictedPolicy(),
+            },
+        },
+        interactions: {
+            commands: [
+                {
+                    name: "helyx-cloud",
+                    description: "Manage this self-hosted bot's Helyx Cloud connection",
+                    registration: "global",
+                    contexts: ["guild", "bot_dm"],
+                    integrationTypes: ["guild_install"],
+                    subcommands: [
+                        {
+                            name: "connect",
+                            description: "Connect this deployment using a one-use code",
+                            rateLimit: { scope: "user", limit: 5, windowSeconds: 60 },
+                            async execute(context) {
+                                if (!(await requireOwner(context)))
+                                    return;
+                                await context.showModal({
+                                    customId: CONNECT_MODAL_ID,
+                                    title: "Connect to Helyx Cloud",
+                                    text: [
+                                        {
+                                            content: "Create a short-lived connection code in `app.helyx.gg`, then paste it below. The code is used once and is not stored.",
+                                        },
+                                    ],
+                                    fields: [
+                                        {
+                                            customId: CONNECT_CODE_FIELD_ID,
+                                            label: "Cloud Connect code",
+                                            description: "Five groups of four letters and numbers.",
+                                            style: "short",
+                                            required: true,
+                                            minLength: 24,
+                                            maxLength: 24,
+                                            placeholder: "ABCD-EFGH-JKLM-NPQR-STUV",
+                                        },
+                                    ],
+                                });
+                            },
+                        },
+                        {
+                            name: "status",
+                            description: "Show this deployment's Cloud Connect status",
+                            rateLimit: { scope: "user", limit: 20, windowSeconds: 60 },
+                            async execute(context) {
+                                if (!(await requireOwner(context)))
+                                    return;
+                                await context.reply(statusResponse(input.connector.status()));
+                            },
+                        },
+                        {
+                            name: "disconnect",
+                            description: "Revoke this deployment's Cloud Connect identity",
+                            rateLimit: { scope: "user", limit: 5, windowSeconds: 60 },
+                            async execute(context) {
+                                if (!(await requireOwner(context)))
+                                    return;
+                                await context.showModal({
+                                    customId: DISCONNECT_MODAL_ID,
+                                    title: "Disconnect Helyx Cloud",
+                                    text: [
+                                        {
+                                            content: "This revokes the saved connector identity. A new dashboard code will be required to reconnect.",
+                                        },
+                                    ],
+                                    fields: [
+                                        {
+                                            type: "string-select",
+                                            customId: DISCONNECT_CONFIRM_FIELD_ID,
+                                            label: "Confirm disconnection",
+                                            required: true,
+                                            minValues: 1,
+                                            maxValues: 1,
+                                            options: [
+                                                {
+                                                    label: "Keep Cloud Connect",
+                                                    value: "keep",
+                                                    default: true,
+                                                },
+                                                {
+                                                    label: "Disconnect and revoke",
+                                                    value: "disconnect",
+                                                },
+                                            ],
+                                        },
+                                    ],
+                                });
+                            },
+                        },
+                        {
+                            name: "rotate",
+                            description: "Replace the saved Cloud Connect credential",
+                            rateLimit: { scope: "user", limit: 3, windowSeconds: 60 },
+                            async execute(context) {
+                                if (!(await requireOwner(context)))
+                                    return;
+                                await context.showModal({
+                                    customId: ROTATE_MODAL_ID,
+                                    title: "Rotate Cloud credential",
+                                    text: [
+                                        {
+                                            content: "Rotation replaces the encrypted connector key and immediately reconnects the bot. Local Discord features keep running.",
+                                        },
+                                    ],
+                                    fields: [
+                                        {
+                                            type: "string-select",
+                                            customId: ROTATE_CONFIRM_FIELD_ID,
+                                            label: "Confirm credential rotation",
+                                            required: true,
+                                            minValues: 1,
+                                            maxValues: 1,
+                                            options: [
+                                                {
+                                                    label: "Cancel",
+                                                    value: "cancel",
+                                                    default: true,
+                                                },
+                                                {
+                                                    label: "Rotate credential",
+                                                    value: "rotate",
+                                                },
+                                            ],
+                                        },
+                                    ],
+                                });
+                            },
+                        },
+                        {
+                            name: "support",
+                            description: "Choose what Helyx support may inspect",
+                            rateLimit: { scope: "user", limit: 5, windowSeconds: 60 },
+                            async execute(context) {
+                                if (!(await requireOwner(context)))
+                                    return;
+                                const consent = await input.connector.getSupportConsent();
+                                await context.showModal({
+                                    customId: SUPPORT_MODAL_ID,
+                                    title: "Cloud support access",
+                                    text: [
+                                        {
+                                            content: "Support inspection is off by default. Submitted message content, secrets and arbitrary logs are never included.",
+                                        },
+                                    ],
+                                    fields: [
+                                        {
+                                            type: "string-select",
+                                            customId: SUPPORT_ENABLED_FIELD_ID,
+                                            label: "Allow bounded support inspection",
+                                            required: true,
+                                            minValues: 1,
+                                            maxValues: 1,
+                                            options: [
+                                                {
+                                                    label: "No",
+                                                    value: "no",
+                                                    default: !consent.supportInspectionEnabled,
+                                                },
+                                                {
+                                                    label: "Yes",
+                                                    value: "yes",
+                                                    default: consent.supportInspectionEnabled,
+                                                },
+                                            ],
+                                        },
+                                        {
+                                            type: "string-select",
+                                            customId: SUPPORT_DATA_FIELD_ID,
+                                            label: "Allowed support data",
+                                            description: "Select only the bounded metadata support may inspect.",
+                                            required: false,
+                                            minValues: 0,
+                                            maxValues: 5,
+                                            options: [
+                                                ["Module inventory", "module_inventory"],
+                                                ["Redacted configuration", "configuration"],
+                                                ["Permission summaries", "permissions"],
+                                                ["Logging policy", "logging"],
+                                                ["Connector health", "health"],
+                                            ].map(([label, value]) => ({
+                                                label,
+                                                value,
+                                                default: consent.supportDataClasses.includes(value),
+                                            })),
+                                        },
+                                        {
+                                            type: "string-select",
+                                            customId: DIAGNOSTICS_ENABLED_FIELD_ID,
+                                            label: "Allow bounded diagnostics",
+                                            required: true,
+                                            minValues: 1,
+                                            maxValues: 1,
+                                            options: [
+                                                {
+                                                    label: "No",
+                                                    value: "no",
+                                                    default: !consent.diagnosticsEnabled,
+                                                },
+                                                {
+                                                    label: "Yes",
+                                                    value: "yes",
+                                                    default: consent.diagnosticsEnabled,
+                                                },
+                                            ],
+                                        },
+                                    ],
+                                });
+                            },
+                        },
+                    ],
+                },
+            ],
+            modals: [
+                {
+                    customId: CONNECT_MODAL_ID,
+                    async execute(context) {
+                        if (!(await requireOwner(context)))
+                            return;
+                        await context.deferReply?.(true);
+                        try {
+                            const status = await input.connector.enrol(context.getField(CONNECT_CODE_FIELD_ID), "discord");
+                            await context.reply({
+                                ephemeral: true,
+                                componentsV2: {
+                                    accentColor: SUCCESS,
+                                    text: [
+                                        {
+                                            content: `## Cloud Connect saved\nInstallation \`${status.installationId ?? "pending"}\` has been enrolled. The bot is establishing its secure outbound connection now.`,
+                                        },
+                                    ],
+                                },
+                            });
+                        }
+                        catch (error) {
+                            await context.reply(connectorErrorResponse(error));
+                        }
+                    },
+                },
+                {
+                    customId: DISCONNECT_MODAL_ID,
+                    async execute(context) {
+                        if (!(await requireOwner(context)))
+                            return;
+                        const confirmation = context.getStringSelectValues(DISCONNECT_CONFIRM_FIELD_ID)[0];
+                        if (confirmation !== "disconnect") {
+                            await context.reply({
+                                ephemeral: true,
+                                componentsV2: {
+                                    accentColor: VIOLET,
+                                    text: [
+                                        {
+                                            content: "## Cloud Connect kept\nNo connection or credential changes were made.",
+                                        },
+                                    ],
+                                },
+                            });
+                            return;
+                        }
+                        await context.deferReply?.(true);
+                        try {
+                            await input.connector.disconnect();
+                            await context.reply({
+                                ephemeral: true,
+                                componentsV2: {
+                                    accentColor: SUCCESS,
+                                    text: [
+                                        {
+                                            content: "## Cloud Connect disconnected\nThe local connector identity has been revoked. This bot continues to work locally.",
+                                        },
+                                    ],
+                                },
+                            });
+                        }
+                        catch (error) {
+                            await context.reply(connectorErrorResponse(error));
+                        }
+                    },
+                },
+                {
+                    customId: ROTATE_MODAL_ID,
+                    async execute(context) {
+                        if (!(await requireOwner(context)))
+                            return;
+                        if (context.getStringSelectValues(ROTATE_CONFIRM_FIELD_ID)[0] !==
+                            "rotate") {
+                            await context.reply({
+                                ephemeral: true,
+                                componentsV2: {
+                                    accentColor: VIOLET,
+                                    text: [
+                                        {
+                                            content: "## Rotation cancelled\nThe connector credential was not changed.",
+                                        },
+                                    ],
+                                },
+                            });
+                            return;
+                        }
+                        await context.deferReply?.(true);
+                        try {
+                            await input.connector.rotate();
+                            await context.reply({
+                                ephemeral: true,
+                                componentsV2: {
+                                    accentColor: SUCCESS,
+                                    text: [
+                                        {
+                                            content: "## Credential rotated\nThe previous key was revoked and Cloud Connect is reconnecting with its new encrypted identity.",
+                                        },
+                                    ],
+                                },
+                            });
+                        }
+                        catch (error) {
+                            await context.reply(connectorErrorResponse(error));
+                        }
+                    },
+                },
+                {
+                    customId: SUPPORT_MODAL_ID,
+                    async execute(context) {
+                        if (!(await requireOwner(context)))
+                            return;
+                        await context.deferReply?.(true);
+                        try {
+                            const enabled = context.getStringSelectValues(SUPPORT_ENABLED_FIELD_ID)[0] ===
+                                "yes";
+                            const updated = await input.connector.updateSupportConsent({
+                                supportInspectionEnabled: enabled,
+                                supportDataClasses: [
+                                    ...context.getStringSelectValues(SUPPORT_DATA_FIELD_ID),
+                                ],
+                                diagnosticsEnabled: context.getStringSelectValues(DIAGNOSTICS_ENABLED_FIELD_ID)[0] === "yes",
+                            });
+                            await context.reply({
+                                ephemeral: true,
+                                componentsV2: {
+                                    accentColor: SUCCESS,
+                                    text: [
+                                        {
+                                            content: [
+                                                "## Support consent saved",
+                                                `**Inspection:** ${updated.supportInspectionEnabled ? "Allowed" : "Off"}`,
+                                                `**Allowed data:** ${updated.supportDataClasses.length ? updated.supportDataClasses.join(", ") : "None"}`,
+                                                `**Diagnostics:** ${updated.diagnosticsEnabled ? "Allowed" : "Off"}`,
+                                            ].join("\n"),
+                                        },
+                                    ],
+                                },
+                            });
+                        }
+                        catch (error) {
+                            await context.reply(connectorErrorResponse(error));
+                        }
+                    },
+                },
+            ],
+        },
+        async start() { },
+        async stop() { },
+    });
+}
+async function isDeploymentOwner(client, userId, configuredOwnerUserIds) {
+    if (configuredOwnerUserIds.includes(userId))
+        return true;
+    const application = await client.application?.fetch();
+    const owner = application?.owner;
+    if (!owner)
+        return false;
+    if ("members" in owner)
+        return owner.members.has(userId);
+    return owner.id === userId;
+}
+function statusResponse(status) {
+    const labels = {
+        disabled: "Disabled by deployment configuration",
+        unpaired: "Ready for a connection code",
+        connecting: "Connecting securely",
+        online: "Connected",
+        offline: "Temporarily offline; local operation continues",
+        revoked: "Disconnected and revoked",
+        stopped: "Stopped",
+    };
+    return {
+        ephemeral: true,
+        componentsV2: {
+            accentColor: status.state === "online"
+                ? SUCCESS
+                : status.state === "revoked"
+                    ? DANGER
+                    : VIOLET,
+            text: [
+                {
+                    content: [
+                        "## Helyx Cloud Connect",
+                        `**Status:** ${labels[status.state]}`,
+                        status.installationId
+                            ? `**Installation:** \`${status.installationId}\``
+                            : undefined,
+                        status.lastConnectedAt
+                            ? `**Last connected:** <t:${Math.floor(status.lastConnectedAt.getTime() / 1_000)}:R>`
+                            : undefined,
+                    ]
+                        .filter(Boolean)
+                        .join("\n"),
+                },
+            ],
+        },
+    };
+}
+function connectorErrorResponse(error) {
+    return {
+        ephemeral: true,
+        componentsV2: {
+            accentColor: DANGER,
+            text: [
+                {
+                    content: `## Cloud Connect could not complete that request\n${error instanceof CloudConnectorUserError
+                        ? error.message
+                        : "Cloud Connect is temporarily unavailable. The local bot continues to work normally."}`,
+                },
+            ],
+        },
+    };
+}
+function restrictedPolicy() {
+    return {
+        everyone: false,
+        requiredPermissions: ["MANAGE_GUILD"],
+        allowedRoleIds: [],
+        deniedRoleIds: [],
+        allowedUserIds: [],
+        deniedUserIds: [],
+    };
+}
+//# sourceMappingURL=cloud-management-module.js.map

package/dist/control-server.d.ts

@@ -34,6 +34,7 @@ interface DashboardModuleDefinition {
     category: string;
     icon: string;
     availability: "available";
+    releaseStatus: "planned" | "testing" | "beta" | "live";
     requiredPermissions: string[];
     settings: readonly unknown[];
     commands: DashboardCommandDefinition[];

package/dist/control-server.js

@@ -575,6 +575,7 @@ function mapDashboardModule(module) {
         category: dashboard.category[0].toUpperCase() + dashboard.category.slice(1),
         icon: dashboard.icon,
         availability: "available",
+        releaseStatus: module.manifest.releaseStatus,
         requiredPermissions: [...module.manifest.permissions],
         settings: dashboard.settings,
         commands: dashboardCommands(module),

package/dist/index.js

@@ -6,8 +6,11 @@ import { createPlatformServices } from "@helyx/platform";
 import { HELYX_SERVICE_NAMES } from "@helyx/sdk";
 import { Client, Events, GatewayIntentBits, Partials } from "discord.js";
 import pino from "pino";
+import { createRequire } from "node:module";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
+import { CloudConnectorController } from "./cloud-connector.js";
+import { createCloudManagementModule } from "./cloud-management-module.js";
 import { installInteractions } from "./interactions.js";
 import { installGuildTracking } from "./guilds.js";
 import { loadConfiguredModulePackages } from "./modules.js";
@@ -66,9 +69,29 @@ export async function startBot(processEnvironment = process.env) {
             allowedMentions: { parse: [] },
         });
         const guildResources = new DiscordGuildResourceDirectory(client);
+        const cloudConnector = new CloudConnectorController({
+            environment,
+            database,
+            client,
+            modules: modulePackages,
+            coreVersion: readBotVersion(),
+            logger: bootstrapLogger,
+        });
         const permissionsModule = createPermissionsModule(featureModules);
         const managementModule = createManagementModule(featureModules, guildResources);
-        const modules = [managementModule, permissionsModule, ...featureModules];
+        const cloudManagementModule = environment.HELYX_CLOUD_CONNECT_ENABLED
+            ? createCloudManagementModule({
+                connector: cloudConnector,
+                client,
+                configuredOwnerUserIds: environment.HELYX_OWNER_USER_IDS,
+            })
+            : undefined;
+        const modules = [
+            managementModule,
+            permissionsModule,
+            ...(cloudManagementModule ? [cloudManagementModule] : []),
+            ...featureModules,
+        ];
         const platformServices = new Map(createPlatformServices(database, modules));
         if (featureModules.some(({ manifest }) => manifest.id === "helyx.logging")) {
             platformServices.set(HELYX_SERVICE_NAMES.moduleLogging, new DiscordModuleLoggingService(client, database, modules, bootstrapLogger));
@@ -79,7 +102,12 @@ export async function startBot(processEnvironment = process.env) {
             logger: bootstrapLogger,
             services: platformServices,
         });
-        const prepareGuilds = installGuildTracking(client, database, modules, bootstrapLogger, new Set([managementModule.manifest.id, permissionsModule.manifest.id]));
+        const enabledCoreModuleIds = new Set([
+            managementModule.manifest.id,
+            permissionsModule.manifest.id,
+            ...(cloudManagementModule ? [cloudManagementModule.manifest.id] : []),
+        ]);
+        const prepareGuilds = installGuildTracking(client, database, modules, bootstrapLogger, enabledCoreModuleIds);
         const commandsReady = installInteractions(client, modules, {
             ...(environment.DISCORD_INTERNAL_GUILD_ID
                 ? { internalGuildId: environment.DISCORD_INTERNAL_GUILD_ID }
@@ -87,6 +115,8 @@ export async function startBot(processEnvironment = process.env) {
             prepare: prepareGuilds,
         }, bootstrapLogger, serviceAccess);
         installModuleEvents(client, modules, bootstrapLogger, serviceAccess);
+        const controlService = new BotControlService(database, modules, guildResources, serviceAccess);
+        cloudConnector.setControlHandler(controlService);
         let controlServer;
         let shuttingDown = false;
         async function shutdown(reason = "programmatic") {
@@ -96,6 +126,10 @@ export async function startBot(processEnvironment = process.env) {
             process.off("SIGINT", onSigint);
             process.off("SIGTERM", onSigterm);
             bootstrapLogger.info({ event: "bot.shutdown", reason }, "Bot shutdown requested");
+            await cloudConnector.stop().catch((error) => {
+                process.exitCode = 1;
+                bootstrapLogger.error({ event: "cloud.stop_failed", error: safeError(error) }, "Cloud Connect shutdown failed");
+            });
             if (controlServer)
                 await controlServer.close().catch((error) => {
                     process.exitCode = 1;
@@ -122,9 +156,10 @@ export async function startBot(processEnvironment = process.env) {
             await runtime.start();
             await client.login(environment.DISCORD_TOKEN);
             await commandsReady;
+            await cloudConnector.start();
             if (environment.HELYX_BOT_CONTROL_SECRET) {
                 controlServer = await createBotControlServer({
-                    service: new BotControlService(database, modules, guildResources, serviceAccess),
+                    service: controlService,
                     secret: environment.HELYX_BOT_CONTROL_SECRET,
                     logger: { level: environment.LOG_LEVEL },
                 });
@@ -142,6 +177,7 @@ export async function startBot(processEnvironment = process.env) {
             }
         }
         catch (error) {
+            await cloudConnector.stop().catch(() => undefined);
             if (controlServer)
                 await controlServer.close().catch(() => undefined);
             try {
@@ -162,6 +198,14 @@ export async function startBot(processEnvironment = process.env) {
         throw error;
     }
 }
+function readBotVersion() {
+    const metadata = createRequire(import.meta.url)("../package.json");
+    if (typeof metadata !== "object" ||
+        metadata === null ||
+        typeof metadata.version !== "string")
+        throw new Error("Bot package version is unavailable");
+    return metadata.version;
+}
 export function gatewayIntentsForModules(modules) {
     const intents = [GatewayIntentBits.Guilds];
     if (modules.some((module) => module.events?.messageReactionAdd?.length)) {

package/dist/management-module.js

@@ -28,6 +28,7 @@ export function createManagementModule(configurableModules, resources) {
     return defineModule({
         manifest: {
             manifestVersion: "0.1",
+            releaseStatus: "live",
             id: "helyx.management",
             name: "Helyx management",
             version: "0.1.0",

package/dist/permissions-module.js

@@ -23,6 +23,7 @@ export function createPermissionsModule(configurableModules) {
     return defineModule({
         manifest: {
             manifestVersion: "0.1",
+            releaseStatus: "live",
             id: "helyx.permissions",
             name: "Permissions",
             version: "0.1.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helyx/bot",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Production Discord runtime for the modular Helyx platform.",
   "keywords": [
     "helyx",
@@ -48,16 +48,21 @@
     "start": "node --env-file-if-exists=../../.env dist/index.js"
   },
   "dependencies": {
-    "@helyx/config": "0.1.2",
-    "@helyx/core": "0.1.2",
-    "@helyx/database": "0.1.1",
-    "@helyx/framework": "0.1.2",
-    "@helyx/module-manifest": "0.1.1",
-    "@helyx/platform": "0.1.2",
-    "@helyx/sdk": "0.2.2",
+    "@helyx/config": "0.2.1",
+    "@helyx/control-protocol": "0.1.1",
+    "@helyx/core": "0.1.4",
+    "@helyx/database": "0.2.0",
+    "@helyx/framework": "0.1.4",
+    "@helyx/module-manifest": "0.3.0",
+    "@helyx/platform": "0.1.4",
+    "@helyx/sdk": "0.2.4",
     "discord.js": "14.27.0",
     "fastify": "5.10.0",
     "pino": "10.3.1",
+    "ws": "8.21.1",
     "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@types/ws": "8.18.1"
   }
 }