@helyx/bot 1.3.1 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,102 @@
 # Changelog
 
+## 1.5.0
+
+### Minor Changes
+
+- 7034a9c: Add bounded read-only Channel audit contracts and Discord inspection for Access
+  Control and hosted Verification. The dashboard can explicitly load a narrow
+  channel/role configuration projection and inspect combined role assumptions
+  without enabling the module, changing Discord or saving audit results.
+
+  Cloud Connect uses two explicit negotiated read capabilities for Access Control.
+  Update the hosted API/gateway and self-hosted bot as a coordinated compatible
+  release; older connectors give an explicit unsupported response. No database
+  migration is required. This changeset records future package impact only;
+  versions and publication remain separately controlled.
+
+### Patch Changes
+
+- Updated dependencies [7034a9c]
+  - @helyx/sdk@0.16.0
+  - @helyx/control-protocol@0.8.0
+  - @helyx/module-automod@1.1.1
+  - @helyx/module-moderation@1.1.1
+
+## 1.4.0
+
+### Minor Changes
+
+- Report Discord readiness to owned-message cleanup so module startup cannot consume recovery attempts before bot login.
+
+- Drain active guild tracking and owner observations before closing Discord and
+  database resources; stop scheduling new reconciliation work during shutdown.
+
+- Prepare the coordinated Phase 8 minor release and align internal package dependencies. Existing deployment and database-support restrictions are unchanged.
+
+  Support checksum-only PostgreSQL startup inspection after a dedicated hosted
+  migration job, while preserving automatic migrations as the default and for
+  every Self-Hosted database.
+
+  Keep Server Health report links inside the current Cloud Connect installation for self-hosted bots. Hosted report links retain their existing route.
+
+  Keep hosted leave workers out of self-hosted runtimes and fence revoked
+  blacklist deliveries before a Discord leave. Preserve stopped delivery evidence
+  for review without changing independent leave requests.
+
+  Correct the generated starter's Cloud Connect command and document explicit server-command allowlists, required Discord intents, database TLS modes and the one-database Cloud Connect topology without changing runtime defaults.
+
+  Leave worker-owned server command collections intact when command writes are
+  disabled, including unsharded and sharded startup. Do not replace active module
+  commands with the internal developer root during a restart.
+  Keep public creator-page validation read-only rather than competing with the
+  invite cleanup/create/revoke lock; recheck active ownership before returning.
+
+### Patch Changes
+
+- Patch Fastify to5.12.7 before publication. Keep the reviewed Phase8 minor
+  version and existing Discord/Undici transport compatibility unchanged.
+
+- Updated dependencies
+  - @helyx/config@1.4.0
+  - @helyx/control-protocol@0.7.0
+  - @helyx/core@0.2.0
+  - @helyx/database-contracts@0.2.0
+  - @helyx/database-mysql@0.2.0
+  - @helyx/database@2.4.0
+  - @helyx/framework@0.2.0
+  - @helyx/module-automod@1.1.0
+  - @helyx/module-manifest@0.13.0
+  - @helyx/module-moderation@1.1.0
+  - @helyx/platform@1.3.0
+  - @helyx/sdk@0.15.0
+  - @helyx/status-client@0.3.0
+  - @helyx/verification-contracts@0.4.0
+
+## 1.3.3
+
+### Patch Changes
+
+- Updated dependencies
+  - @helyx/control-protocol@0.6.0
+
+## 1.3.2
+
+### Patch Changes
+
+- Support deferred source-message updates for modal submissions so poll draft
+  edits replace their previous controls instead of creating duplicate messages.
+- Move the complete installed feature-module list to `/dev modules` and show
+  compact names and versions for modules and `/dev bot` core functions.
+- Bound internal dependencies to compatible releases while preserving required
+  minimum API versions.
+- Forward the hosted moderation control credential to shard workers only when
+  hosted moderation is enabled, preserving the existing worker credential boundary.
+- Forward the explicit database-engine selection to shard workers while
+  preserving PostgreSQL as the default.
+- Update the HTTP client to 6.29.0 to include the current WebSocket and retry
+  interceptor security fixes.
+
 ## 1.3.1
 
 ### Patch Changes
@@ -435,34 +532,9 @@
 
 ### Patch Changes
 
-- Reuse active Verification links when available, report their expiry, and allow members to replace them while atomically invalidating the old request.---
-  "@helyx/bot": patch
-  "@helyx/database": patch
-  "@helyx/sdk": patch
-  "@helyx/verification-contracts": patch
-  ---
-
-  Reuse active Verification links when available, report their expiry, and allow members to replace them while atomically invalidating the old request.
-
-- Accept compatible internal Helyx releases within explicit minor-safe pre-1.0 or major-safe stable ranges, preventing dependency-only patch cascades.---
-  "@helyx/bot": patch
-  "@helyx/cli": patch
-  "@helyx/core": patch
-  "@helyx/framework": patch
-  "@helyx/platform": patch
-  "@helyx/sdk": patch
-  "@helyx/module-account-gate": patch
-  "@helyx/module-feedback": patch
-  "@helyx/module-giveaways": patch
-  "@helyx/module-levels": patch
-  "@helyx/module-logging": patch
-  "@helyx/module-polls": patch
-  "@helyx/module-reactionroles": patch
-  "@helyx/module-suggestions": patch
-  "@helyx/module-welcome": patch
-  ---
-
-  Accept compatible internal Helyx releases within explicit minor-safe pre-1.0 or major-safe stable ranges, preventing dependency-only patch cascades.
+- Reuse active Verification links when available, report their expiry, and allow members to replace them while atomically invalidating the old request.
+
+- Accept compatible internal Helyx releases within explicit minor-safe pre-1.0 or major-safe stable ranges, preventing dependency-only patch cascades.
 
 ## 0.4.23
 

package/README.md

@@ -1,6 +1,11 @@
 # Helyx bot
 
-The Helyx Discord runtime validates its environment, verifies and migrates PostgreSQL, validates explicitly configured module packages, applies their migrations, composes platform services, synchronises guild installations and commands, logs in with the non-privileged Guilds intent, and shuts down Discord, modules, and PostgreSQL safely.
+The Helyx Discord runtime validates its environment and explicitly configured
+module packages, loads the selected database adapter, prepares core and module
+migrations, composes platform services, synchronises installations and commands,
+and connects to Discord. Shutdown closes modules, Discord and database resources.
+Hosted services use PostgreSQL; Self-Hosted bots support PostgreSQL or a
+capability-compatible MySQL database with matching module support.
 
 Version-matched public guides, operator runbooks, environment reference
 material, and module-authoring instructions ship at `documentation/README.md`
@@ -21,7 +26,14 @@ for production and self-hosted deployments during migration. Use
 that mode startup publishes only platform globals and migrated customer
 commands come from each guild's command profile and enabled module state.
 
-The built-in global `/helyx` and `/permissions` commands are core infrastructure. `/helyx` gives server owners, administrators and members with Manage Server permission an ephemeral module-management flow. It lists installed feature packages, enables or disables them, stages schema-defined settings, uses native Discord channel and role selectors, validates the complete configuration, and saves through the same versioned configuration and audit services as the dashboard. Dependency rules prevent a required module being disabled or a dependent module being enabled out of order.
+The built-in global `/helyx` and `/permissions` commands are core infrastructure.
+`/helyx modules` gives server owners, administrators and members with Manage
+Server permission an ephemeral module-management flow. It lists installed
+feature packages, enables or disables them, stages schema-defined settings,
+uses native Discord channel and role selectors, validates the complete
+configuration, and saves through the same versioned configuration and audit
+services as the dashboard. Dependency rules prevent a required module being
+disabled or a dependent module being enabled out of order.
 
 `/permissions` uses an owner/administrator-protected select and modal flow with native Discord selectors to manage inherited module policies and command overrides. Feature packages require an explicit allowlist: hosted distributions carry a reviewed `hosted-modules.json` catalogue, generated self-host projects use `HELYX_MODULE_CATALOGUE_PATH`, and `HELYX_MODULE_PACKAGES` remains an intentional comma-separated override. The sources are merged and de-duplicated. A core distribution has no catalogue and runs core-only when both self-host selectors are empty.
 
@@ -32,7 +44,19 @@ to `/helyx` or the dashboard. In platform-only mode, migrated commands are
 included in a guild only when its command profile selects them. Package
 upgrades preserve each server's existing enabled or disabled state.
 
-Gateway intents are derived from installed event contributions. The bot always requests Guilds, adds non-privileged reaction access only for reaction modules, and adds the privileged Server Members intent only when an installed module handles member joins. Deployments containing such a module must enable the matching intent in the Discord Developer Portal before startup.
+Gateway intents are derived from installed contributions and explicit runtime
+settings. The bot always requests Guilds and adds the reaction, message, voice
+and Auto Moderation intents required by the loaded modules. Server Members is
+requested when member events/capabilities require it or
+`HELYX_GUILD_MEMBERS_ENABLED=true`; enable the matching privileged intent in the
+Discord Developer Portal before login. Set that flag when a selected workflow
+requires Helyx to advertise the Guild Members capability as available.
+
+Message Content requires `HELYX_MESSAGE_CONTENT_ENABLED=true` as well as the
+Developer Portal intent and a loaded contribution that needs it. Self-Hosted
+Enhanced Auto Moderation uses this local capability; Hosted Enhanced scanning
+uses the separately operated Ecko adapter. Match intents to the selected
+features rather than enabling every privileged intent.
 
 Moderation integrations use closed, versioned service contracts for native
 Discord Auto Moderation rules, member and message enforcement, restricted
@@ -51,7 +75,16 @@ results before they cross the control boundary.
 
 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. `/health` is unauthenticated. Ordinary `/v1` routes require the shared bearer secret; the narrow `/v1/ecko/*` routes instead require their dedicated rotating HMAC transport key. 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`. 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.
+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 stable local
+`HELYX_DATA_ENCRYPTION_KEY`. Generated starters enable the connector but remain
+unpaired until an authorised owner supplies a one-use code with
+`/helyx cloud connect`. The `/helyx cloud` command group also supports status,
+credential rotation, disconnection and bounded support consent. If the key is
+lost or changed, revoke the old installation and enrol a new identity. 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.
 
 Production Status reporting is opt-in and disabled by default. Set
 `HELYX_STATUS_ENABLED=true` only with the reviewed `HELYX_STATUS_URL`, the
@@ -65,11 +98,11 @@ Giveaways and Invite Tracking also require the existing
 checkpoints and stable invite-member fingerprints without exposing the key to
 a module. Keep it stable across deployments.
 
-Trivia uses questions already imported into PostgreSQL. Multiple Choice and
-Guess both run entirely from the saved question catalogue, and the bot runtime
-does not call an external trivia provider.
+Trivia uses the module's migrated question catalogue in the selected database.
+Multiple Choice, Guess and True or False run locally; gameplay does not call an
+external trivia provider.
 
-The always-available guild-only `/bug` command can be used by any guild member.
+The always-available guild-only `/helyx bug` command can be used by any guild member.
 Hosted deployments submit through the dedicated `HELYX_SUPPORT_SERVICE_SECRET`;
 paired self-hosted deployments use their authenticated Cloud Connect session
 and may receive a one-time link for claiming, tracking and replying to the
@@ -157,8 +190,29 @@ self-hosting is outside the first release.
 Changing the total shard count redistributes guild ownership. Treat it as a
 generation change: drain the old generation before admitting the new one and
 never run both as active owners. Shard-capable code does not authorize hosted
-activation. Phase 10 production activation, replica scaling, or any Railway
-variable change requires separate owner authorization; do not provision a new
+activation. New hosted shard activation, replica scaling, or provider
+configuration changes require separate owner authorization; preserve an existing
+reviewed topology rather than resetting it to the new-install default. Do not provision a new
 Redis or coordinator service for sharding.
 
-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.
+## Packaged operation and database checks
+
+Generated starters install `@helyx/cli` and expose `npm run setup`,
+`npm run doctor`, `npm start`, `npm run update:check` and `npm run update`.
+Follow their README for Node.js, Docker or managed-host commands; the bot
+package itself does not provide the `helyx` executable. Compiled npm packages
+do not require a source build before normal startup.
+
+`helyx start` applies pending core and selected-module migrations by default.
+`helyx migrate` deliberately applies only core migrations without Discord.
+Read-only `helyx doctor` validates environment, database connectivity, existing
+core migration history and configured package metadata; it inspects module
+migration history when core migrations are current. Pending migrations are
+reported without applying them. Startup performs database capability probes
+and the complete runtime/Discord checks that doctor does not perform.
+
+`DATABASE_ENGINE` defaults to `postgresql`; `mysql` selects the optional adapter
+and currently requires `HELYX_SHARD_MODE=off`. Changing the setting does not
+convert existing data between engines. Hosted PostgreSQL deployments may use
+`HELYX_DATABASE_STARTUP_MODE=inspect` after their separate approved migration
+job; Self-Hosted startup keeps automatic `apply` mode.

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

@@ -0,0 +1,7 @@
+import type { ChannelAuditConfiguration, ChannelAuditModuleId } from "@helyx/sdk";
+/** Deliberate allowlist: never return provider state, answers or the saved settings object. */
+export declare function channelAuditConfiguration(moduleId: ChannelAuditModuleId, configuration: {
+    version: number;
+    value: Record<string, unknown>;
+} | null): ChannelAuditConfiguration;
+//# sourceMappingURL=channel-audit-configuration.d.ts.map

package/dist/channel-audit-configuration.js

@@ -0,0 +1,40 @@
+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) {
+    const value = configuration?.value ?? {};
+    const mappedFields = [];
+    const id = (field) => {
+        const candidate = value[field];
+        if (typeof candidate !== "string" || !/^\d{17,20}$/u.test(candidate))
+            return null;
+        mappedFields.push(field);
+        return candidate;
+    };
+    const entryChannelId = id(moduleId === "helyx.account-gate"
+        ? "gateChannelId"
+        : "verificationChannelId");
+    const afterRoleId = id("verifiedRoleId");
+    const reviewChannelId = moduleId === "helyx.account-gate" ? id("reviewChannelId") : null;
+    const configuredRoles = moduleId === "helyx.account-gate" && Array.isArray(value.temporaryRoleIds)
+        ? [
+            ...new Set(value.temporaryRoleIds.filter((role) => typeof role === "string" && /^\d{17,20}$/u.test(role))),
+        ]
+        : [];
+    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);
+    return channelAuditConfigurationSchema.parse({
+        moduleId,
+        version: configuration?.version ?? null,
+        entryChannelId,
+        beforeRoleIds,
+        afterRoleId,
+        reviewChannelId,
+        mappedFields,
+        truncated: configuredRoles.length > CHANNEL_AUDIT_LIMITS.beforeRoles,
+    });
+}
+//# sourceMappingURL=channel-audit-configuration.js.map

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

@@ -0,0 +1,14 @@
+import { type ChannelAuditControl, type GuildAccessPolicy, type ModuleConfigurationService, type ModuleDefinition, type PermissionPolicyService, type ServiceAccess } from "@helyx/sdk";
+import type { BotControlGuildResourceDirectory, BotControlRepositories } from "./control-server.js";
+/** Read-only component: no action, transaction, settings-save or Discord mutation helpers. */
+export declare function createChannelAuditControl(input: {
+    modules: ReadonlyMap<string, ModuleDefinition>;
+    resources: Pick<BotControlGuildResourceDirectory, "resolveActor">;
+    configurations: ModuleConfigurationService;
+    permissions: PermissionPolicyService;
+    services: ServiceAccess;
+    listModules: BotControlRepositories["installations"]["listModules"];
+    readGuildPolicy(guildId: string): Promise<GuildAccessPolicy>;
+    requireAccessible(guildId: string, moduleId: string): Promise<void>;
+}): Required<ChannelAuditControl>;
+//# sourceMappingURL=channel-audit-control.d.ts.map

package/dist/channel-audit-control.js

@@ -0,0 +1,61 @@
+import { canAccessGuildDashboard, canUseCommand } from "@helyx/core";
+import { HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { channelAuditInputSchema, channelAuditModuleIdSchema, channelAuditReportSchema, } from "@helyx/control-protocol/channel-audit";
+import { BotControlForbiddenError, BotControlNotFoundError, BotControlTransportError, } from "./control-errors.js";
+import { safeVersion } from "./control-permissions.js";
+import { channelAuditConfiguration } from "./channel-audit-configuration.js";
+/** Read-only component: no action, transaction, settings-save or Discord mutation helpers. */
+export function createChannelAuditControl(input) {
+    const authorize = async (context) => {
+        channelAuditModuleIdSchema.parse(context.moduleId);
+        const module = input.modules.get(context.moduleId);
+        if (!module)
+            throw new BotControlNotFoundError("Module is not installed");
+        if (!module.manifest.dashboard)
+            throw new BotControlNotFoundError("Module is not dashboard configurable");
+        const [actor, guildAccess, resolvedPolicy, installed] = await Promise.all([
+            input.resources.resolveActor(context.guildId, context.actorUserId),
+            input.readGuildPolicy(context.guildId),
+            input.permissions.getPolicy(context.guildId, context.moduleId),
+            input.listModules(context.guildId),
+        ]);
+        if (!canAccessGuildDashboard(actor, guildAccess) ||
+            !canUseCommand(actor, resolvedPolicy.policy, guildAccess))
+            throw new BotControlForbiddenError("You no longer have permission to inspect this module's channel setup");
+        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 {
+        readChannelAuditConfiguration: async (context) => {
+            await authorize(context);
+            const configuration = await input.configurations.get(context.guildId, context.moduleId);
+            return channelAuditConfiguration(context.moduleId, configuration
+                ? {
+                    version: safeVersion(configuration.version),
+                    value: configuration.value,
+                }
+                : null);
+        },
+        checkChannelAudit: async (context) => {
+            const assumptions = channelAuditInputSchema.parse(context.assumptions);
+            await authorize(context);
+            if (!input.services.has(HELYX_SERVICE_NAMES.discordResources))
+                throw new BotControlTransportError(503, "Channel audit is not supported by this bot's Discord inspection service");
+            const inspection = input.services.get(HELYX_SERVICE_NAMES.discordResources);
+            if (!inspection.inspectChannelAudit)
+                throw new BotControlTransportError(503, "This bot version does not support Channel audit. Update the bot before trying again.");
+            const report = channelAuditReportSchema.parse(await inspection.inspectChannelAudit({
+                guildId: context.guildId,
+                moduleId: context.moduleId,
+                assumptions,
+            }));
+            if (report.guildId !== context.guildId ||
+                report.moduleId !== context.moduleId ||
+                JSON.stringify(report.assumptions) !== JSON.stringify(assumptions))
+                throw new BotControlTransportError(502, "Channel audit returned a different server or module context");
+            return report;
+        },
+    };
+}
+//# sourceMappingURL=channel-audit-control.js.map

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

@@ -0,0 +1,56 @@
+import type { ChannelAuditInput, ChannelAuditModuleId, ChannelAuditReport } from "@helyx/sdk";
+export declare const AUDIT_PERMISSIONS: {
+    readonly Administrator: bigint;
+    readonly ManageGuild: bigint;
+    readonly ViewChannel: bigint;
+    readonly SendMessages: bigint;
+    readonly ReadMessageHistory: bigint;
+    readonly Connect: bigint;
+    readonly Speak: bigint;
+    readonly ManageRoles: bigint;
+    readonly ManageChannels: bigint;
+    readonly KickMembers: bigint;
+    readonly BanMembers: bigint;
+    readonly RequestToSpeak: bigint;
+    readonly SendMessagesInThreads: bigint;
+};
+export interface AuditRoleSnapshot {
+    id: string;
+    permissions: bigint;
+    managed: boolean;
+    assignable: boolean | null;
+    assignmentReason?: string;
+    assignmentPolicyReason?: string;
+}
+export interface AuditChannelSnapshot {
+    id: string;
+    name: string;
+    type: number;
+    obfuscated: boolean;
+    overwrites: Array<{
+        id: string;
+        type: number;
+        allow: bigint;
+        deny: bigint;
+    }>;
+    botPermissions: bigint | null;
+}
+export interface AuditGuildSnapshot {
+    guildId: string;
+    roles: AuditRoleSnapshot[];
+    rolesComplete: boolean;
+    channels: AuditChannelSnapshot[];
+    fetchedChannels: number;
+    totalChannelsKnown: boolean;
+    fetchLimitations: string[];
+    invalidSelectedChannels?: Array<{
+        id: string;
+        reason: "not_found" | "wrong_guild";
+    }>;
+}
+/** Discord's role union, everyone overwrite, then aggregate role deny/allow. */
+export declare function effectiveAuditPermissions(guildId: string, roles: readonly AuditRoleSnapshot[], selectedRoleIds: readonly string[], channel: AuditChannelSnapshot): bigint | null;
+/** Raw bit presence is insufficient: view/connect prerequisites gate actions. */
+export declare function auditActions(permissions: bigint | null, type: number): string[];
+export declare function buildChannelAuditReport(snapshot: AuditGuildSnapshot, moduleId: ChannelAuditModuleId, assumptions: ChannelAuditInput, observedAt: string): ChannelAuditReport;
+//# sourceMappingURL=channel-audit-permissions.d.ts.map