@helyx/bot 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.2.2
+
+### Patch Changes
+
+- b0f1932: Cache Discord application owners outside the interaction acknowledgement path
+  so Cloud Connect commands and modals respond reliably during Discord API
+  latency.
+
+  Treat an unreadable local Cloud Connect identity as an actionable recovery
+  state instead of retrying indefinitely. Owners can revoke the old dashboard
+  installation and enrol again with a new one-use code.
+
+  Run bounded cleanup for expired interaction sessions and rate-limit windows.
+
+- Updated dependencies [18265bc]
+  - @helyx/database@0.2.1
+  - @helyx/platform@0.1.5
+
+## 0.2.1
+
+### Patch Changes
+
+- Add explicit Planned, Testing, Beta and Live module lifecycle metadata.
+
+  Propagate lifecycle status through the hosted control contract and permit only
+  Live modules in hosted distributions and generated self-host projects.
+
+- Updated dependencies
+  - @helyx/module-manifest@0.3.0
+  - @helyx/control-protocol@0.1.1
+  - @helyx/core@0.1.4
+  - @helyx/sdk@0.2.4
+  - @helyx/framework@0.1.4
+  - @helyx/platform@0.1.4
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -16,6 +16,6 @@ Gateway intents are derived from installed event contributions. The bot always r
 
 When `HELYX_BOT_CONTROL_SECRET` is configured, the bot also starts a private authenticated HTTP control server on `HELYX_BOT_CONTROL_PORT`. The dashboard API uses this service to obtain real Discord roles and channels and to apply validated module, configuration and permission changes. Only `/health` is unauthenticated; all `/v1` routes require the shared bearer secret. Keep this endpoint on a private service network and do not assign it a public domain.
 
-Optional Helyx Cloud Connect is a separate outbound management path for self-hosted deployments. It is disabled unless `HELYX_CLOUD_CONNECT_ENABLED=true` and requires a separate local `HELYX_DATA_ENCRYPTION_KEY`. The owner-only `/helyx-cloud` command supports connection-code enrolment, status, credential rotation, disconnection and bounded support consent. The bot never sends its Discord token, database URL or connector private key to Helyx Cloud, and local Discord operation continues when Cloud is unavailable.
+Optional Helyx Cloud Connect is a separate outbound management path for self-hosted deployments. It is disabled unless `HELYX_CLOUD_CONNECT_ENABLED=true` and requires a separate local `HELYX_DATA_ENCRYPTION_KEY`. Preserve that key across every restart and deployment. If it is lost or changed, revoke the old installation in the dashboard and use a new one-use code with `/helyx-cloud connect`; the connector stops retrying until that recovery is completed. The owner-only `/helyx-cloud` command supports connection-code enrolment, status, credential rotation, disconnection and bounded support consent. The bot never sends its Discord token, database URL or connector private key to Helyx Cloud, and local Discord operation continues when Cloud is unavailable.
 
 For packaged operation use `helyx start`. `helyx migrate` applies core database migrations without Discord, and read-only `helyx doctor` verifies environment, PostgreSQL migration history, and configured package metadata.

package/dist/cloud-connector.d.ts

@@ -4,7 +4,7 @@ import type { Client } from "discord.js";
 import type { Logger } from "pino";
 import type { ConfiguredModulePackage } from "./modules.js";
 import type { BotControlHandler } from "./control-server.js";
-type ConnectorState = "disabled" | "unpaired" | "connecting" | "online" | "offline" | "revoked" | "stopped";
+type ConnectorState = "disabled" | "unpaired" | "connecting" | "online" | "offline" | "recovery_required" | "revoked" | "stopped";
 export interface CloudConnectorStatus {
     state: ConnectorState;
     installationId?: string;

package/dist/cloud-connector.js

@@ -136,7 +136,8 @@ export class CloudConnectorController {
         if (!this.input.environment.HELYX_CLOUD_CONNECT_ENABLED)
             throw new CloudConnectorUserError("Cloud Connect is disabled in this deployment");
         const existing = await this.#repository.getIdentity();
-        if (existing && !existing.revokedAt)
+        const recoveringIdentity = existing && !existing.revokedAt && this.#state === "recovery_required";
+        if (existing && !existing.revokedAt && !recoveringIdentity)
             throw new CloudConnectorUserError("This Helyx deployment is already connected");
         if (!this.#dataKey)
             throw new CloudConnectorUserError("HELYX_DATA_ENCRYPTION_KEY is not configured");
@@ -183,6 +184,9 @@ export class CloudConnectorController {
         }
         const exchange = exchangeResponseSchema.parse(payload);
         const encrypted = encryptPrivateKey(keyPair.privateKey, this.#dataKey, exchange.installationId);
+        if (recoveringIdentity && !(await this.#repository.revoke())) {
+            throw new CloudConnectorUserError("The previous local Cloud Connect identity could not be reset");
+        }
         this.#identity = await this.#repository.createIdentity({
             installationId: exchange.installationId,
             credentialId: exchange.credentialId,
@@ -196,7 +200,9 @@ export class CloudConnectorController {
         });
         this.#connectionBlocked = false;
         await this.#repository.appendAudit({
-            action: "installation.enrolled",
+            action: recoveringIdentity
+                ? "installation.recovered"
+                : "installation.enrolled",
             source,
             outcome: "succeeded",
         });
@@ -312,6 +318,16 @@ export class CloudConnectorController {
             catch (error) {
                 if (this.#stopping)
                     break;
+                if (error instanceof CloudConnectorIdentityKeyError) {
+                    this.#connectionBlocked = true;
+                    this.#state = "recovery_required";
+                    this.#lastErrorCode = "local_identity_key_mismatch";
+                    this.input.logger.error({
+                        event: "cloud.identity_recovery_required",
+                        reason: this.#lastErrorCode,
+                    }, "Cloud Connect cannot decrypt its local identity. Revoke the old installation in the dashboard, then use a new one-use code with /helyx-cloud connect");
+                    break;
+                }
                 this.#state = "offline";
                 this.#lastErrorCode = safeConnectorError(error);
                 this.input.logger.warn({
@@ -598,13 +614,24 @@ function encryptPrivateKey(privateKey, dataKey, installationId) {
     return { ciphertext, iv, tag: cipher.getAuthTag() };
 }
 function decryptPrivateKey(encrypted, dataKey, installationId) {
-    const decipher = createDecipheriv("aes-256-gcm", dataKey, encrypted.iv);
-    decipher.setAAD(Buffer.from(`helyx-cloud-connector:${installationId}`, "utf8"));
-    decipher.setAuthTag(encrypted.tag);
-    return Buffer.concat([
-        decipher.update(encrypted.ciphertext),
-        decipher.final(),
-    ]).toString("utf8");
+    try {
+        const decipher = createDecipheriv("aes-256-gcm", dataKey, encrypted.iv);
+        decipher.setAAD(Buffer.from(`helyx-cloud-connector:${installationId}`, "utf8"));
+        decipher.setAuthTag(encrypted.tag);
+        return Buffer.concat([
+            decipher.update(encrypted.ciphertext),
+            decipher.final(),
+        ]).toString("utf8");
+    }
+    catch {
+        throw new CloudConnectorIdentityKeyError();
+    }
+}
+class CloudConnectorIdentityKeyError extends Error {
+    constructor() {
+        super("The local Cloud Connect identity cannot be decrypted");
+        this.name = "CloudConnectorIdentityKeyError";
+    }
 }
 function connectedMessage(input) {
     const now = new Date();

package/dist/cloud-management-module.d.ts

@@ -1,6 +1,12 @@
 import { type ModuleDefinition } from "@helyx/sdk";
 import type { Client } from "discord.js";
 import type { CloudConnectorController } from "./cloud-connector.js";
+export declare class DeploymentOwnerAuthorizer {
+    #private;
+    constructor(client: Client, configuredOwnerUserIds: readonly string[]);
+    isOwner(userId: string): boolean;
+    refresh(): Promise<void>;
+}
 export declare function createCloudManagementModule(input: {
     connector: CloudConnectorController;
     client: Client;

package/dist/cloud-management-module.js

@@ -1,4 +1,5 @@
 import { defineModule, } from "@helyx/sdk";
+import { Events } from "discord.js";
 import { CloudConnectorUserError, } from "./cloud-connector.js";
 const CONNECT_MODAL_ID = "helyx.cloud.connect";
 const CONNECT_CODE_FIELD_ID = "helyx.cloud.connect.code";
@@ -13,9 +14,41 @@ const DIAGNOSTICS_ENABLED_FIELD_ID = "helyx.cloud.support.diagnostics";
 const VIOLET = 0x7c3aed;
 const SUCCESS = 0x16a34a;
 const DANGER = 0xdc2626;
+const OWNER_REFRESH_INTERVAL_MS = 15 * 60 * 1_000;
+export class DeploymentOwnerAuthorizer {
+    #client;
+    #configuredOwnerUserIds;
+    #applicationOwnerUserIds = new Set();
+    constructor(client, configuredOwnerUserIds) {
+        this.#client = client;
+        this.#configuredOwnerUserIds = new Set(configuredOwnerUserIds);
+    }
+    isOwner(userId) {
+        return (this.#configuredOwnerUserIds.has(userId) ||
+            this.#applicationOwnerUserIds.has(userId));
+    }
+    async refresh() {
+        const application = this.#client.application;
+        if (!application)
+            return;
+        this.#replaceApplicationOwners(application.owner);
+        const refreshed = await application.fetch();
+        this.#replaceApplicationOwners(refreshed.owner);
+    }
+    #replaceApplicationOwners(owner) {
+        this.#applicationOwnerUserIds = !owner
+            ? new Set()
+            : "members" in owner
+                ? new Set(owner.members.keys())
+                : new Set([owner.id]);
+    }
+}
 export function createCloudManagementModule(input) {
+    const ownerAuthorizer = new DeploymentOwnerAuthorizer(input.client, input.configuredOwnerUserIds);
+    let ownerRefreshInterval;
+    let onClientReady;
     const requireOwner = async (context) => {
-        if (await isDeploymentOwner(input.client, context.userId, input.configuredOwnerUserIds))
+        if (ownerAuthorizer.isOwner(context.userId))
             return true;
         await context.reply({
             ephemeral: true,
@@ -33,6 +66,7 @@ export function createCloudManagementModule(input) {
     return defineModule({
         manifest: {
             manifestVersion: "0.1",
+            releaseStatus: "live",
             id: "helyx.cloud-connect",
             name: "Helyx Cloud Connect",
             version: "0.1.0",
@@ -410,21 +444,37 @@ export function createCloudManagementModule(input) {
                 },
             ],
         },
-        async start() { },
-        async stop() { },
+        start(context) {
+            const refreshOwners = () => {
+                void ownerAuthorizer.refresh().catch((error) => {
+                    context.logger.warn({
+                        event: "cloud.owner_cache_refresh_failed",
+                        error: safeError(error),
+                    }, "Cloud Connect deployment-owner cache refresh failed");
+                });
+            };
+            onClientReady = () => {
+                refreshOwners();
+                ownerRefreshInterval ??= setInterval(refreshOwners, OWNER_REFRESH_INTERVAL_MS);
+                ownerRefreshInterval.unref();
+            };
+            if (input.client.isReady())
+                onClientReady();
+            else
+                input.client.once(Events.ClientReady, onClientReady);
+            return Promise.resolve();
+        },
+        stop() {
+            if (onClientReady)
+                input.client.off(Events.ClientReady, onClientReady);
+            if (ownerRefreshInterval)
+                clearInterval(ownerRefreshInterval);
+            onClientReady = undefined;
+            ownerRefreshInterval = undefined;
+            return Promise.resolve();
+        },
     });
 }
-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",
@@ -432,6 +482,7 @@ function statusResponse(status) {
         connecting: "Connecting securely",
         online: "Connected",
         offline: "Temporarily offline; local operation continues",
+        recovery_required: "Local identity recovery required; revoke the old dashboard installation, then connect with a new code",
         revoked: "Disconnected and revoked",
         stopped: "Stopped",
     };
@@ -487,4 +538,9 @@ function restrictedPolicy() {
         deniedUserIds: [],
     };
 }
+function safeError(error) {
+    return error instanceof Error
+        ? { name: error.name, message: error.message }
+        : { name: "Error", message: String(error) };
+}
 //# 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

@@ -1,6 +1,6 @@
 import { parseBotEnvironment } from "@helyx/config";
 import { safeError, ServiceRegistry } from "@helyx/core";
-import { checkDatabaseConnection, createDatabasePool, runCoreMigrations, runConfiguredModuleMigrations, } from "@helyx/database";
+import { checkDatabaseConnection, createDatabasePool, InteractionSessionRepository, RateLimitRepository, runCoreMigrations, runConfiguredModuleMigrations, } from "@helyx/database";
 import { createRuntime } from "@helyx/framework";
 import { createPlatformServices } from "@helyx/platform";
 import { HELYX_SERVICE_NAMES } from "@helyx/sdk";
@@ -24,6 +24,7 @@ export { loadConfiguredModulePackages } from "./modules.js";
 export { resolveModulePackageSpecifiers } from "./module-configuration.js";
 export * from "./control-server.js";
 const bootstrapLogger = pino({ base: { component: "bot" } });
+const RETENTION_CLEANUP_INTERVAL_MS = 60 * 60 * 1_000;
 export async function startBot(processEnvironment = process.env) {
     const environment = parseBotEnvironment(processEnvironment);
     bootstrapLogger.level = environment.LOG_LEVEL;
@@ -33,6 +34,7 @@ export async function startBot(processEnvironment = process.env) {
         applicationName: "helyx-bot",
     });
     let databaseClosed = false;
+    let retentionCleanupTimer;
     async function closeDatabase() {
         if (databaseClosed)
             return;
@@ -47,6 +49,29 @@ export async function startBot(processEnvironment = process.env) {
             appliedMigrations: migrationResult.applied,
             verifiedMigrationCount: migrationResult.verified.length,
         }, "Core database ready");
+        const cleanupExpiredCoreRecords = async () => {
+            const [sessions, rateLimits] = await Promise.all([
+                new InteractionSessionRepository(database).deleteExpired(),
+                new RateLimitRepository(database).deleteExpired(),
+            ]);
+            if (sessions > 0 || rateLimits > 0) {
+                bootstrapLogger.info({
+                    event: "database.retention_cleaned",
+                    interactionSessions: sessions,
+                    rateLimitWindows: rateLimits,
+                }, "Expired core records removed");
+            }
+        };
+        await cleanupExpiredCoreRecords().catch((error) => {
+            bootstrapLogger.warn({ event: "database.retention_cleanup_failed", error: safeError(error) }, "Expired core record cleanup failed");
+        });
+        retentionCleanupTimer = setInterval(() => void cleanupExpiredCoreRecords().catch((error) => {
+            bootstrapLogger.warn({
+                event: "database.retention_cleanup_failed",
+                error: safeError(error),
+            }, "Expired core record cleanup failed");
+        }), RETENTION_CLEANUP_INTERVAL_MS);
+        retentionCleanupTimer.unref();
         const moduleSpecifiers = await resolveModulePackageSpecifiers(environment.HELYX_MODULE_PACKAGES, undefined, undefined, environment.HELYX_MODULE_CATALOGUE_PATH);
         const modulePackages = await loadConfiguredModulePackages(moduleSpecifiers);
         const moduleMigrationResults = await runConfiguredModuleMigrations(database, modulePackages.map(({ definition, packageRoot }) => ({
@@ -125,6 +150,8 @@ export async function startBot(processEnvironment = process.env) {
             shuttingDown = true;
             process.off("SIGINT", onSigint);
             process.off("SIGTERM", onSigterm);
+            if (retentionCleanupTimer)
+                clearInterval(retentionCleanupTimer);
             bootstrapLogger.info({ event: "bot.shutdown", reason }, "Bot shutdown requested");
             await cloudConnector.stop().catch((error) => {
                 process.exitCode = 1;
@@ -192,6 +219,8 @@ export async function startBot(processEnvironment = process.env) {
         return { shutdown };
     }
     catch (error) {
+        if (retentionCleanupTimer)
+            clearInterval(retentionCleanupTimer);
         await closeDatabase().catch((closeError) => {
             bootstrapLogger.error({ event: "database.close_failed", error: safeError(closeError) }, "Database pool cleanup failed");
         });

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.2.0",
+  "version": "0.2.2",
   "description": "Production Discord runtime for the modular Helyx platform.",
   "keywords": [
     "helyx",
@@ -48,14 +48,14 @@
     "start": "node --env-file-if-exists=../../.env dist/index.js"
   },
   "dependencies": {
-    "@helyx/config": "0.2.0",
-    "@helyx/control-protocol": "0.1.0",
-    "@helyx/core": "0.1.3",
-    "@helyx/database": "0.2.0",
-    "@helyx/framework": "0.1.3",
-    "@helyx/module-manifest": "0.2.0",
-    "@helyx/platform": "0.1.3",
-    "@helyx/sdk": "0.2.3",
+    "@helyx/config": "0.2.1",
+    "@helyx/control-protocol": "0.1.1",
+    "@helyx/core": "0.1.4",
+    "@helyx/database": "0.2.1",
+    "@helyx/framework": "0.1.4",
+    "@helyx/module-manifest": "0.3.0",
+    "@helyx/platform": "0.1.5",
+    "@helyx/sdk": "0.2.4",
     "discord.js": "14.27.0",
     "fastify": "5.10.0",
     "pino": "10.3.1",