@helyx/bot 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 1.1.0
+
+### Minor Changes
+
+- Add the hosted-server safety projection, durable leave delivery, owner
+  observation, hosted blacklist enforcement, internal moderation commands, and
+  the explicitly disabled self-host environment contract.
+- Enforce the private Bot Invite incident gate for new hosted guild joins,
+  including fail-closed API handling and bounded leave retries.
+
+### Patch Changes
+
+- Resolve bounded member display-name sets from cache first and use one Gateway
+  batch for remaining IDs when the Guild Members capability is available.
+- Updated dependencies
+  - @helyx/database@2.1.0
+  - @helyx/config@1.1.0
+
 ## 1.0.1
 
 ### Patch Changes

package/README.md

@@ -111,13 +111,23 @@ production budget.
 exact internal guild. `APPROVED_ROLES` is a de-duplicated, comma-separated
 list of at most 100 Discord role IDs. A caller must have Discord's
 Administrator permission or at least one approved role; role names are never
-used for authorization. Every response is ephemeral and read-only:
+used for authorization. Every response is ephemeral. The default diagnostic
+paths are read-only:
 
 - `/dev shards` reports bounded shard health, including the unsharded
   compatibility baseline;
 - `/dev bot` reports the bot build and bounded installed-module versions;
 - `/dev proc` reports safe metrics for the process handling the command.
 
+On the official hosted bot only,
+`HELYX_HOSTED_MODERATION_ENABLED=true` adds `/dev leave` and `/dev blacklist`.
+They require the existing bot-control secret, a valid target snowflake and a
+bounded private reason. The API records the action and delivers it durably;
+there is no `/dev unblacklist`. The same hosted-only boundary enforces the
+private Bot Invite incident gate before a newly joined server is initialised.
+Self-hosted deployments must keep the default `false` value and never contact
+the hosted Admin control plane.
+
 No `/dev` command exposes tokens, URLs, Redis keys, database details,
 environment variables or process arguments. Future developer subcommands must
 extend this guild-only `/dev` root and reuse the same authorization boundary.

package/dist/developer-operations-module.d.ts

@@ -1,6 +1,7 @@
 import { type ModuleDefinition } from "@helyx/sdk";
 import { type ShardHealthSnapshot } from "./shard-contracts.js";
 import type { TriviaDataProvider } from "./trivia-data-provider.js";
+import type { DeveloperServerModeration } from "./hosted-server-moderation.js";
 export interface ShardHealthProvider {
     getHealth(): Promise<ShardHealthSnapshot>;
 }
@@ -19,6 +20,7 @@ export interface DeveloperOperationsInput {
     processLabel: string;
     health: ShardHealthProvider;
     triviaData: TriviaDataProvider;
+    moderation?: DeveloperServerModeration;
 }
 export declare function createDeveloperOperationsModule(input: DeveloperOperationsInput): ModuleDefinition;
 export declare class WorkerShardHealthProvider implements ShardHealthProvider {

package/dist/developer-operations-module.js

@@ -4,7 +4,7 @@ import { SHARD_CONTROL_TIMEOUT_MS, assertShardMessageSize, shardOperationsHealth
 import { INTERNAL_MODULE_MANIFEST_FIELDS } from "./internal-module-manifest.js";
 const DEVELOPER_MODULE_ID = "helyx.developer-operations";
 const DEVELOPER_MODULE_NAME = "Helyx Developer Operations";
-const DEVELOPER_MODULE_VERSION = "0.2.0";
+const DEVELOPER_MODULE_VERSION = "0.3.0";
 const MAX_MODULE_LINES = 8;
 export function createDeveloperOperationsModule(input) {
     const approvedRoles = new Set(input.approvedRoleIds);
@@ -15,13 +15,24 @@ export function createDeveloperOperationsModule(input) {
             id: DEVELOPER_MODULE_ID,
             name: DEVELOPER_MODULE_NAME,
             version: DEVELOPER_MODULE_VERSION,
-            description: "Private read-only development operations for Helyx support.",
+            description: "Private development and hosted-server operations for Helyx staff.",
             entry: "./dist/developer-operations-module.js",
             framework: "^0.1.0",
             dependencies: [],
             permissions: [],
             contributions: { commands: ["dev"], events: [] },
         },
+        defaultPermissions: {
+            module: restrictedPolicy(),
+            commands: Object.fromEntries([
+                "dev.shards",
+                "dev.bot",
+                "dev.proc",
+                "dev.trivia-data",
+                "dev.leave",
+                "dev.blacklist",
+            ].map((id) => [id, restrictedPolicy()])),
+        },
         interactions: {
             commands: [
                 {
@@ -33,6 +44,7 @@ export function createDeveloperOperationsModule(input) {
                     subcommands: [
                         {
                             name: "shards",
+                            permissionId: "dev.shards",
                             description: "Show bounded read-only shard health",
                             acknowledgement: "deferred-ephemeral",
                             authorization: "self-authorized",
@@ -83,6 +95,7 @@ export function createDeveloperOperationsModule(input) {
                         },
                         {
                             name: "bot",
+                            permissionId: "dev.bot",
                             description: "Show the bot build and installed module versions",
                             acknowledgement: "immediate-response",
                             authorization: "self-authorized",
@@ -137,6 +150,7 @@ export function createDeveloperOperationsModule(input) {
                         },
                         {
                             name: "proc",
+                            permissionId: "dev.proc",
                             description: "Show safe process resource and uptime information",
                             acknowledgement: "immediate-response",
                             authorization: "self-authorized",
@@ -171,6 +185,7 @@ export function createDeveloperOperationsModule(input) {
                         },
                         {
                             name: "trivia-data",
+                            permissionId: "dev.trivia-data",
                             description: "Show question counts from the Trivia database",
                             acknowledgement: "deferred-ephemeral",
                             authorization: "self-authorized",
@@ -220,6 +235,100 @@ export function createDeveloperOperationsModule(input) {
                                 });
                             },
                         },
+                        ...(input.moderation
+                            ? ["leave", "blacklist"].map((action) => ({
+                                name: action,
+                                permissionId: `dev.${action}`,
+                                description: action === "leave"
+                                    ? "Make hosted Helyx leave a server"
+                                    : "Blacklist a server and make hosted Helyx leave",
+                                acknowledgement: "deferred-ephemeral",
+                                authorization: "self-authorized",
+                                rateLimit: {
+                                    scope: "user",
+                                    limit: 3,
+                                    windowSeconds: 60,
+                                },
+                                options: [
+                                    {
+                                        type: "string",
+                                        name: "server_id",
+                                        description: "Discord server ID",
+                                        required: true,
+                                        minLength: 17,
+                                        maxLength: 20,
+                                    },
+                                    {
+                                        type: "string",
+                                        name: "reason",
+                                        description: "Private reason for this action",
+                                        required: true,
+                                        minLength: 3,
+                                        maxLength: 500,
+                                    },
+                                ],
+                                async execute(context) {
+                                    if (!(await authorizeDeveloperCommand(context)))
+                                        return;
+                                    const guildId = context
+                                        .getStringOption("server_id")
+                                        ?.trim();
+                                    const reason = context.getStringOption("reason")?.trim();
+                                    if (!guildId ||
+                                        !/^\d{17,20}$/u.test(guildId) ||
+                                        !reason ||
+                                        reason.length < 3 ||
+                                        reason.length > 500 ||
+                                        /[\r\n\0]/u.test(reason)) {
+                                        await context.reply({
+                                            ephemeral: true,
+                                            componentsV2: {
+                                                accentColor: 0xdc2626,
+                                                text: [
+                                                    {
+                                                        content: "The server ID or private reason is invalid.",
+                                                    },
+                                                ],
+                                            },
+                                        });
+                                        return;
+                                    }
+                                    try {
+                                        const result = await input.moderation.moderate({
+                                            action,
+                                            guildId,
+                                            actorUserId: context.userId,
+                                            reason,
+                                            idempotencyKey: `discord:${context.interactionId}`,
+                                        });
+                                        await context.reply({
+                                            ephemeral: true,
+                                            componentsV2: {
+                                                accentColor: 0x2563eb,
+                                                text: [
+                                                    {
+                                                        content: `## Hosted server ${action}\n${moderationOutcome(result.outcome)}\nOperation: \`${result.operationId}\`${result.paidSlotsReleased ? `\nPremium slots released: ${result.paidSlotsReleased}` : ""}`,
+                                                    },
+                                                ],
+                                            },
+                                        });
+                                    }
+                                    catch {
+                                        await context.reply({
+                                            ephemeral: true,
+                                            componentsV2: {
+                                                accentColor: 0xdc2626,
+                                                text: [
+                                                    {
+                                                        content: "The hosted moderation service is unavailable. The request was not reported as complete; retry with the same command when service is restored.",
+                                                    },
+                                                ],
+                                            },
+                                        });
+                                    }
+                                },
+                            }))
+                            : []),
                     ],
                 },
             ],
@@ -247,6 +356,31 @@ export function createDeveloperOperationsModule(input) {
         return false;
     }
 }
+function restrictedPolicy() {
+    return {
+        everyone: false,
+        requiredPermissions: ["ADMINISTRATOR"],
+        allowedRoleIds: [],
+        deniedRoleIds: [],
+        allowedUserIds: [],
+        deniedUserIds: [],
+    };
+}
+function moderationOutcome(outcome) {
+    if (outcome === "queued")
+        return "Accepted. Helyx will leave through the durable delivery queue.";
+    if (outcome === "already_blacklisted")
+        return "No new blacklist was created; this server is already blacklisted.";
+    if (outcome === "not_currently_installed")
+        return "Recorded. Helyx is not currently installed in that server.";
+    if (outcome === "accepted_for_retry")
+        return "Accepted for a safe retry.";
+    if (outcome === "requires_review")
+        return "Recorded and flagged for staff review.";
+    if (outcome === "completed")
+        return "Completed.";
+    return "The request was recorded but did not complete.";
+}
 function safeInlineCode(value) {
     return `\`${value.replaceAll("`", "'").slice(0, 120)}\``;
 }

package/dist/events.js

@@ -1504,19 +1504,46 @@ export class DiscordResourceInspection {
     }
     async resolveMembers(input) {
         const guild = await this.#resolveMemberGuild(input);
-        return Promise.all(input.userIds.map(async (userId) => {
-            const member = await fetchExactMember(guild, userId, "member").catch((error) => {
+        const members = new Map();
+        for (const userId of input.userIds) {
+            const cached = guild.members.cache?.get(userId);
+            if (cached)
+                members.set(userId, cached);
+        }
+        const missing = input.userIds.filter((userId) => !members.has(userId));
+        const canBulkResolve = this.client.options?.intents?.has(GatewayIntentBits.GuildMembers);
+        if (missing.length > 0 && canBulkResolve) {
+            const fetched = await guild.members
+                .fetch({ user: missing, time: 5_000 })
+                .catch(() => null);
+            if (fetched)
+                for (const member of fetched.values())
+                    if (missing.includes(member.id))
+                        members.set(member.id, member);
+        }
+        else if (missing.length > 0) {
+            const fetched = await Promise.all(missing.map((userId) => fetchExactMember(guild, userId, "member").catch((error) => {
                 if (isUnknownMember(error))
                     return null;
                 throw error;
-            });
+            })));
+            for (const member of fetched)
+                if (member)
+                    members.set(member.id, member);
+        }
+        return input.userIds.map((userId) => {
+            const member = members.get(userId) ?? null;
+            const cachedUser = this.client.users?.cache?.get(userId);
             const avatarUrl = memberAvatarUrl(member);
             return {
                 userId,
-                displayName: member?.displayName ?? null,
+                displayName: member?.displayName ??
+                    cachedUser?.globalName ??
+                    cachedUser?.username ??
+                    null,
                 ...(avatarUrl ? { avatarUrl } : {}),
             };
-        }));
+        });
     }
     async searchMembers(input) {
         validateSnowflake(input.guildId, "guild");

package/dist/guilds.d.ts

@@ -2,6 +2,7 @@ import { type DatabasePool, type GuildShardOwnership } from "@helyx/database";
 import type { ModuleDefinition } from "@helyx/sdk";
 import { type Client } from "discord.js";
 import type { InteractionLogger } from "./interactions.js";
+import type { HostedBotInviteGate, HostedGuildSafety } from "./hosted-server-moderation.js";
 export interface GuildReconciliationHealth {
     status: "pending" | "running" | "healthy" | "failed" | "stopped";
     lastStartedAt?: string;
@@ -21,5 +22,5 @@ export interface GuildTrackingPreparation {
     health(): GuildReconciliationHealth;
     stop(): void;
 }
-export declare function installGuildTracking(client: Client, database: DatabasePool, modules: readonly ModuleDefinition[], logger: InteractionLogger, enabledByDefaultModuleIds?: ReadonlySet<string>, ownership?: GuildShardOwnership, reconciliationIntervalMs?: number, shardCount?: number, applicationId?: string): GuildTrackingPreparation;
+export declare function installGuildTracking(client: Client, database: DatabasePool, modules: readonly ModuleDefinition[], logger: InteractionLogger, enabledByDefaultModuleIds?: ReadonlySet<string>, ownership?: GuildShardOwnership, reconciliationIntervalMs?: number, shardCount?: number, applicationId?: string, hostedSafety?: HostedGuildSafety, hostedInviteGate?: HostedBotInviteGate): GuildTrackingPreparation;
 //# sourceMappingURL=guilds.d.ts.map

package/dist/guilds.js

@@ -3,7 +3,7 @@ import { safeError } from "@helyx/core";
 import { Events } from "discord.js";
 const RECONCILIATION_PAGE_SIZE = 250;
 const DEFAULT_RECONCILIATION_INTERVAL_MS = 15 * 60 * 1_000;
-export function installGuildTracking(client, database, modules, logger, enabledByDefaultModuleIds = new Set(), ownership, reconciliationIntervalMs = DEFAULT_RECONCILIATION_INTERVAL_MS, shardCount, applicationId) {
+export function installGuildTracking(client, database, modules, logger, enabledByDefaultModuleIds = new Set(), ownership, reconciliationIntervalMs = DEFAULT_RECONCILIATION_INTERVAL_MS, shardCount, applicationId, hostedSafety, hostedInviteGate) {
     if (!Number.isSafeInteger(reconciliationIntervalMs) ||
         reconciliationIntervalMs < 60_000)
         throw new Error("Guild reconciliation interval must be at least one minute");
@@ -12,6 +12,11 @@ export function installGuildTracking(client, database, modules, logger, enabledB
     let stopped = false;
     let reconciliation;
     let timer;
+    const admissionRetries = new Map();
+    const inviteGateRejections = new Map();
+    const ownerObservations = hostedSafety
+        ? new OwnerObservationQueue(hostedSafety, logger)
+        : undefined;
     let health = {
         status: "pending",
         examinedRows: 0,
@@ -57,17 +62,102 @@ export function installGuildTracking(client, database, modules, logger, enabledB
             await withTransaction(database, persist);
         else
             await persist(database);
+        ownerObservations?.enqueue(guild);
+    }
+    async function leaveInviteRejectedGuild(guild) {
+        const reasonCode = inviteGateRejections.get(guild.id);
+        if (!reasonCode)
+            return;
+        await guild.leave();
+        logger.info({
+            event: "guild.invite_gate_enforced",
+            guildId: guild.id,
+            reasonCode,
+        }, "New guild was rejected by the Bot Invite gate");
+    }
+    async function admitAndSync(guild, firstObservation) {
+        if (inviteGateRejections.has(guild.id)) {
+            await leaveInviteRejectedGuild(guild);
+            return;
+        }
+        const [blacklist, inviteGate] = await Promise.allSettled([
+            hostedSafety
+                ? hostedSafety.isBlacklisted(guild.id)
+                : Promise.resolve(false),
+            hostedInviteGate ? hostedInviteGate.isEnabled() : Promise.resolve(true),
+        ]);
+        if (hostedSafety && blacklist.status === "fulfilled" && blacklist.value) {
+            const enforcement = await Promise.allSettled([
+                hostedSafety.recordAutomaticLeave(guild.id),
+                guild.leave(),
+            ]);
+            if (enforcement.some((result) => result.status === "rejected"))
+                throw new Error("Blacklisted guild enforcement was unavailable");
+            logger.info({ event: "guild.blacklist_enforced", guildId: guild.id }, "Blacklisted guild was rejected before initialization");
+            return;
+        }
+        if (inviteGate.status === "rejected") {
+            inviteGateRejections.set(guild.id, "gate_unavailable");
+            logger.warn({
+                event: "guild.invite_gate_check_failed",
+                guildId: guild.id,
+                reasonCode: "gate_unavailable",
+            }, "Bot Invite gate was unavailable; the new guild will be rejected");
+            await leaveInviteRejectedGuild(guild);
+            return;
+        }
+        if (!inviteGate.value) {
+            inviteGateRejections.set(guild.id, "gate_paused");
+            await leaveInviteRejectedGuild(guild);
+            return;
+        }
+        if (blacklist.status === "rejected")
+            throw new Error("Hosted guild safety lookup was unavailable");
+        await syncGuild(guild, firstObservation);
+        const retry = admissionRetries.get(guild.id);
+        if (retry)
+            clearTimeout(retry);
+        admissionRetries.delete(guild.id);
+    }
+    function scheduleAdmissionRetry(guild) {
+        if (stopped || admissionRetries.has(guild.id))
+            return;
+        const retry = setTimeout(() => {
+            admissionRetries.delete(guild.id);
+            if (stopped || !guild.available)
+                return;
+            void admitAndSync(guild, true).catch(() => {
+                logger.error({
+                    event: "guild.admission_retry_failed",
+                    guildId: guild.id,
+                    reasonCode: "admission_unavailable",
+                }, "Guild admission retry failed");
+                scheduleAdmissionRetry(guild);
+            });
+        }, 30_000);
+        retry.unref();
+        admissionRetries.set(guild.id, retry);
     }
     client.on(Events.GuildCreate, (guild) => {
-        void syncGuild(guild, true).catch((error) => {
+        void admitAndSync(guild, true).catch(() => {
             logger.error({
-                event: "guild.sync_failed",
+                event: "guild.admission_failed",
                 guildId: guild.id,
-                error: safeError(error),
-            }, "Guild installation sync failed");
+                reasonCode: "admission_unavailable",
+            }, "Guild admission failed closed");
+            scheduleAdmissionRetry(guild);
         });
     });
+    client.on(Events.GuildUpdate, (_previous, guild) => {
+        if (!inviteGateRejections.has(guild.id))
+            ownerObservations?.enqueue(guild);
+    });
     client.on(Events.GuildDelete, (guild) => {
+        const retry = admissionRetries.get(guild.id);
+        if (retry)
+            clearTimeout(retry);
+        admissionRetries.delete(guild.id);
+        inviteGateRejections.delete(guild.id);
         void repository
             .markGuildRemoved(guild.id, ownership)
             .then(async (changed) => {
@@ -110,9 +200,23 @@ export function installGuildTracking(client, database, modules, logger, enabledB
             const observedGuildIds = new Set(client.guilds.cache.keys());
             const unavailableGuilds = [...client.guilds.cache.values()].filter((guild) => !guild.available).length;
             try {
+                const blacklistedGuildIds = new Set();
+                if (hostedSafety) {
+                    const observed = [...observedGuildIds];
+                    for (let offset = 0; offset < observed.length; offset += RECONCILIATION_PAGE_SIZE) {
+                        const page = await hostedSafety.blacklistedGuildIds(observed.slice(offset, offset + RECONCILIATION_PAGE_SIZE));
+                        for (const guildId of page)
+                            blacklistedGuildIds.add(guildId);
+                    }
+                }
                 for (const guild of client.guilds.cache.values()) {
                     if (stopped)
                         return;
+                    if (blacklistedGuildIds.has(guild.id)) {
+                        await hostedSafety.recordAutomaticLeave(guild.id);
+                        await guild.leave();
+                        continue;
+                    }
                     await syncGuild(guild);
                     refreshedGuilds += 1;
                 }
@@ -211,8 +315,57 @@ export function installGuildTracking(client, database, modules, logger, enabledB
         if (timer)
             clearInterval(timer);
         timer = undefined;
+        for (const retry of admissionRetries.values())
+            clearTimeout(retry);
+        admissionRetries.clear();
+        inviteGateRejections.clear();
+        ownerObservations?.stop();
         health = { ...health, status: "stopped", nextScheduledAt: undefined };
     };
     return prepare;
 }
+class OwnerObservationQueue {
+    safety;
+    logger;
+    #pending = new Map();
+    #active = 0;
+    #stopped = false;
+    constructor(safety, logger) {
+        this.safety = safety;
+        this.logger = logger;
+    }
+    enqueue(guild) {
+        if (this.#stopped)
+            return;
+        this.#pending.set(guild.id, guild);
+        this.#drain();
+    }
+    stop() {
+        this.#stopped = true;
+        this.#pending.clear();
+    }
+    #drain() {
+        while (!this.#stopped && this.#active < 2 && this.#pending.size > 0) {
+            const next = this.#pending.entries().next().value;
+            if (!next)
+                return;
+            const [guildId, guild] = next;
+            this.#pending.delete(guildId);
+            this.#active += 1;
+            void this.safety
+                .observeOwner(guild)
+                .catch(() => {
+                this.logger.warn({
+                    event: "guild.owner_observation_failed",
+                    guildId,
+                    reasonCode: "owner_identity_unavailable",
+                }, "Guild owner identity observation was deferred");
+            })
+                .finally(() => {
+                this.#active -= 1;
+                this.#drain();
+            });
+        }
+    }
+}
 //# sourceMappingURL=guilds.js.map

package/dist/hosted-server-moderation.d.ts

@@ -0,0 +1,89 @@
+import { type DatabasePool } from "@helyx/database";
+import type { Client, Guild } from "discord.js";
+import { z } from "zod";
+import type { InteractionLogger } from "./interactions.js";
+declare const resultSchema: z.ZodObject<{
+    operationId: z.ZodUUID;
+    guildId: z.ZodString;
+    action: z.ZodEnum<{
+        leave: "leave";
+        blacklist: "blacklist";
+    }>;
+    outcome: z.ZodEnum<{
+        completed: "completed";
+        requires_review: "requires_review";
+        failed: "failed";
+        queued: "queued";
+        already_blacklisted: "already_blacklisted";
+        not_currently_installed: "not_currently_installed";
+        accepted_for_retry: "accepted_for_retry";
+    }>;
+    paidSlotsReleased: z.ZodNumber;
+}, z.core.$loose>;
+export interface DeveloperServerModeration {
+    moderate(input: {
+        action: "leave" | "blacklist";
+        guildId: string;
+        actorUserId: string;
+        reason: string;
+        idempotencyKey: string;
+    }): Promise<{
+        operationId: string;
+        outcome: z.infer<typeof resultSchema>["outcome"];
+        paidSlotsReleased: number;
+    }>;
+}
+export declare class HostedServerModerationClient implements DeveloperServerModeration {
+    private readonly apiUrl;
+    private readonly secret;
+    constructor(apiUrl: string, secret: string);
+    moderate(input: {
+        action: "leave" | "blacklist";
+        guildId: string;
+        actorUserId: string;
+        reason: string;
+        idempotencyKey: string;
+    }): Promise<{
+        operationId: string;
+        outcome: "completed" | "requires_review" | "failed" | "queued" | "already_blacklisted" | "not_currently_installed" | "accepted_for_retry";
+        paidSlotsReleased: number;
+    }>;
+}
+export interface HostedBotInviteGate {
+    isEnabled(): Promise<boolean>;
+}
+export declare class HostedBotInviteGateClient implements HostedBotInviteGate {
+    private readonly apiUrl;
+    private readonly secret;
+    constructor(apiUrl: string, secret: string);
+    isEnabled(): Promise<boolean>;
+}
+export interface HostedGuildSafety {
+    isBlacklisted(guildId: string): Promise<boolean>;
+    blacklistedGuildIds(guildIds: readonly string[]): Promise<Set<string>>;
+    recordAutomaticLeave(guildId: string): Promise<string>;
+    observeOwner(guild: Guild): Promise<void>;
+}
+export declare class PostgresHostedGuildSafety implements HostedGuildSafety {
+    #private;
+    constructor(database: DatabasePool);
+    isBlacklisted(guildId: string): Promise<boolean>;
+    blacklistedGuildIds(guildIds: readonly string[]): Promise<Set<string>>;
+    recordAutomaticLeave(guildId: string): Promise<string>;
+    observeOwner(guild: Guild): Promise<void>;
+}
+export declare class HostedServerLeaveWorker {
+    #private;
+    private readonly client;
+    private readonly logger;
+    private readonly shardScope?;
+    constructor(database: DatabasePool, client: Client, logger: InteractionLogger, shardScope?: {
+        shardId: number;
+        shardCount: number;
+    } | undefined);
+    start(): void;
+    runOnce(): Promise<void>;
+    stop(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=hosted-server-moderation.d.ts.map

package/dist/hosted-server-moderation.js

@@ -0,0 +1,198 @@
+import { HostedServerSafetyRepository, } from "@helyx/database";
+import { z } from "zod";
+const resultSchema = z
+    .object({
+    operationId: z.uuid(),
+    guildId: z.string().regex(/^\d{17,20}$/u),
+    action: z.enum(["leave", "blacklist"]),
+    outcome: z.enum([
+        "queued",
+        "completed",
+        "already_blacklisted",
+        "not_currently_installed",
+        "accepted_for_retry",
+        "requires_review",
+        "failed",
+    ]),
+    paidSlotsReleased: z.number().int().nonnegative(),
+})
+    .passthrough();
+const botInviteGateSchema = z.object({ enabled: z.boolean() }).strict();
+export class HostedServerModerationClient {
+    apiUrl;
+    secret;
+    constructor(apiUrl, secret) {
+        this.apiUrl = apiUrl;
+        this.secret = secret;
+    }
+    async moderate(input) {
+        const response = await fetch(new URL(`/v1/internal/hosted-server-moderation/${input.action}`, this.apiUrl), {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${this.secret}`,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({
+                guildId: input.guildId,
+                actorUserId: input.actorUserId,
+                reason: input.reason,
+                idempotencyKey: input.idempotencyKey,
+            }),
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!response.ok)
+            throw new Error(`Hosted moderation request failed with ${response.status}`);
+        const result = resultSchema.parse(await response.json());
+        if (result.guildId !== input.guildId || result.action !== input.action)
+            throw new Error("Hosted moderation response did not match the request");
+        return {
+            operationId: result.operationId,
+            outcome: result.outcome,
+            paidSlotsReleased: result.paidSlotsReleased,
+        };
+    }
+}
+export class HostedBotInviteGateClient {
+    apiUrl;
+    secret;
+    constructor(apiUrl, secret) {
+        this.apiUrl = apiUrl;
+        this.secret = secret;
+    }
+    async isEnabled() {
+        const response = await fetch(new URL("/v1/internal/incident-gates/bot-invites", this.apiUrl), {
+            headers: { authorization: `Bearer ${this.secret}` },
+            signal: AbortSignal.timeout(3_000),
+        });
+        if (!response.ok)
+            throw new Error(`Bot Invite gate request failed with ${response.status}`);
+        return botInviteGateSchema.parse(await response.json()).enabled;
+    }
+}
+export class PostgresHostedGuildSafety {
+    #repository;
+    constructor(database) {
+        this.#repository = new HostedServerSafetyRepository(database);
+    }
+    async isBlacklisted(guildId) {
+        return (await this.#repository.getState(guildId)).blacklisted;
+    }
+    blacklistedGuildIds(guildIds) {
+        return this.#repository.getBlacklistedGuildIds(guildIds);
+    }
+    recordAutomaticLeave(guildId) {
+        return this.#repository.enqueueAutomaticLeave(guildId);
+    }
+    async observeOwner(guild) {
+        const cached = guild.members.cache.get(guild.ownerId)?.user;
+        const user = cached ?? (await guild.client.users.fetch(guild.ownerId));
+        await this.#repository.observeOwner({
+            guildId: guild.id,
+            ownerUserId: guild.ownerId,
+            username: user.username,
+        });
+    }
+}
+export class HostedServerLeaveWorker {
+    client;
+    logger;
+    shardScope;
+    #repository;
+    #timer;
+    #active;
+    #stopped = false;
+    constructor(database, client, logger, shardScope) {
+        this.client = client;
+        this.logger = logger;
+        this.shardScope = shardScope;
+        this.#repository = new HostedServerSafetyRepository(database);
+    }
+    start() {
+        if (this.#timer || this.#stopped)
+            return;
+        this.#runSoon();
+        this.#timer = setInterval(() => this.#runSoon(), 15_000);
+        this.#timer.unref();
+    }
+    async runOnce() {
+        if (this.#stopped || this.#active)
+            return this.#active;
+        this.#active = this.#drain().finally(() => {
+            this.#active = undefined;
+        });
+        return this.#active;
+    }
+    async stop() {
+        this.#stopped = true;
+        if (this.#timer)
+            clearInterval(this.#timer);
+        this.#timer = undefined;
+        await this.#active;
+    }
+    async #drain() {
+        const claims = await this.#repository.claimLeaveDeliveries({
+            limit: 10,
+            leaseSeconds: 30,
+            ...(this.shardScope ?? {}),
+        });
+        await Promise.all(claims.map((claim) => this.#deliver(claim)));
+    }
+    #runSoon() {
+        void this.runOnce().catch(() => {
+            this.logger.error({
+                event: "hosted_moderation.leave_claim_failed",
+                reasonCode: "database_unavailable",
+            }, "Hosted server leave claims are temporarily unavailable");
+        });
+    }
+    async #deliver(claim) {
+        const guild = this.client.guilds.cache.get(claim.guildId);
+        if (!guild) {
+            await this.#repository.completeLeaveDelivery(claim, "not_currently_installed");
+            return;
+        }
+        try {
+            await guild.leave();
+            await this.#repository.completeLeaveDelivery(claim, "completed");
+            this.logger.info({
+                event: "hosted_moderation.leave_completed",
+                guildId: claim.guildId,
+                operationId: claim.operationId,
+            }, "Hosted server leave completed");
+        }
+        catch (error) {
+            const failureCode = classifyLeaveFailure(error);
+            if (failureCode === "discord_not_installed") {
+                await this.#repository.completeLeaveDelivery(claim, "not_currently_installed");
+                return;
+            }
+            const outcome = await this.#repository.failLeaveDelivery({
+                claim,
+                failureCode,
+                retryAfterSeconds: Math.min(3_600, 15 * 2 ** claim.attemptCount),
+            });
+            this.logger.warn({
+                event: "hosted_moderation.leave_deferred",
+                guildId: claim.guildId,
+                operationId: claim.operationId,
+                failureCode,
+                outcome,
+            }, "Hosted server leave will be retried or reviewed");
+        }
+    }
+}
+function classifyLeaveFailure(error) {
+    if (typeof error !== "object" || error === null)
+        return "discord_transient";
+    const candidate = error;
+    const code = candidate.code;
+    if (code === 10_004 || code === 50_001)
+        return "discord_not_installed";
+    const status = candidate.status;
+    if (status === 401 || status === 403)
+        return "discord_authentication";
+    if (status === 429)
+        return "discord_rate_limited";
+    return "discord_transient";
+}
+//# sourceMappingURL=hosted-server-moderation.js.map

package/dist/index.js

@@ -1,7 +1,7 @@
 import { parseBotEnvironment } from "@helyx/config";
 import { StatusHeartbeatReporter } from "@helyx/status-client";
 import { safeError, ServiceRegistry } from "@helyx/core";
-import { checkDatabaseConnection, createDatabasePool, AuditRepository, GuildCommandRepository, InteractionSessionRepository, PremiumAllocationRepository, RateLimitRepository, runCoreMigrations, runConfiguredModuleMigrations, } from "@helyx/database";
+import { checkDatabaseConnection, createDatabasePool, AuditRepository, GuildCommandRepository, HostedServerSafetyRepository, InteractionSessionRepository, PremiumAllocationRepository, RateLimitRepository, runCoreMigrations, runConfiguredModuleMigrations, } from "@helyx/database";
 import { createRuntime } from "@helyx/framework";
 import { createPlatformServices, gamingStatisticsRecordOwner, achievementContributionRecordOwner, PostgresPrivacyProviderExecutor, PlatformMemberRoleGrantOwnershipService, PostgresMemberRoleGrantOwnershipStore, } from "@helyx/platform";
 import { HELYX_SERVICE_NAMES, } from "@helyx/sdk";
@@ -50,6 +50,7 @@ import { discordRestOptions } from "./discord-rest.js";
 import { discordBotStatusService } from "./status-producer.js";
 import { assertReviewedPremiumCatalogue, requirePremiumProviderEnvironment, } from "./premium-access.js";
 import { enforcePremiumCatalogue, PREMIUM_CATALOGUE_ENFORCEMENT_INTERVAL_MS, } from "./premium-catalogue-enforcement.js";
+import { HostedBotInviteGateClient, HostedServerLeaveWorker, HostedServerModerationClient, PostgresHostedGuildSafety, } from "./hosted-server-moderation.js";
 export { loadConfiguredModulePackages } from "./modules.js";
 export { resolveModulePackageSpecifiers } from "./module-configuration.js";
 export * from "./control-server.js";
@@ -119,6 +120,15 @@ async function startUnshardedBot(processEnvironment) {
         sslMode: environment.DATABASE_SSL,
         applicationName: "helyx-bot",
     });
+    const hostedSafety = environment.HELYX_HOSTED_MODERATION_ENABLED
+        ? new PostgresHostedGuildSafety(database)
+        : undefined;
+    const developerModeration = environment.HELYX_HOSTED_MODERATION_ENABLED
+        ? new HostedServerModerationClient(environment.HELYX_CLOUD_API_URL, environment.HELYX_BOT_CONTROL_SECRET)
+        : undefined;
+    const hostedInviteGate = environment.HELYX_HOSTED_MODERATION_ENABLED
+        ? new HostedBotInviteGateClient(environment.HELYX_CLOUD_API_URL, environment.HELYX_BOT_CONTROL_SECRET)
+        : undefined;
     const privacyDatabase = environment.HELYX_PRIVACY_ENABLED &&
         environment.HELYX_PRIVACY_EXECUTOR_DATABASE_URL &&
         environment.HELYX_PRIVACY_EXECUTOR_DATABASE_SSL
@@ -153,11 +163,12 @@ async function startUnshardedBot(processEnvironment) {
             verifiedMigrationCount: migrationResult.verified.length,
         }, "Core database ready");
         const cleanupExpiredCoreRecords = async () => {
-            const [sessions, rateLimits, verificationAudit, commandRecords] = await Promise.all([
+            const [sessions, rateLimits, verificationAudit, commandRecords, hostedLeaveDeliveries,] = await Promise.all([
                 new InteractionSessionRepository(database).deleteExpired(),
                 new RateLimitRepository(database).deleteExpired(),
                 new AuditRepository(database).deleteModuleEventsOlderThanMonths("helyx.verification", 12),
                 new GuildCommandRepository(database).deleteExpired(12),
+                new HostedServerSafetyRepository(database).deleteTerminalLeaveDeliveriesOlderThanMonths(24),
             ]);
             const commandRecordCount = commandRecords.history +
                 commandRecords.idempotencyKeys +
@@ -166,13 +177,15 @@ async function startUnshardedBot(processEnvironment) {
             if (sessions > 0 ||
                 rateLimits > 0 ||
                 verificationAudit > 0 ||
-                commandRecordCount > 0) {
+                commandRecordCount > 0 ||
+                hostedLeaveDeliveries > 0) {
                 bootstrapLogger.info({
                     event: "database.retention_cleaned",
                     interactionSessions: sessions,
                     rateLimitWindows: rateLimits,
                     verificationAuditEvents: verificationAudit,
                     commandRecords: commandRecordCount,
+                    hostedLeaveDeliveries,
                 }, "Expired core records removed");
             }
         };
@@ -339,6 +352,7 @@ async function startUnshardedBot(processEnvironment) {
                 health: {
                     getHealth: buildHealth,
                 },
+                ...(developerModeration ? { moderation: developerModeration } : {}),
             })
             : undefined;
         const modules = [
@@ -402,7 +416,10 @@ async function startUnshardedBot(processEnvironment) {
             ...(cloudManagementModule ? [cloudManagementModule.manifest.id] : []),
             ...(operationsModule ? [operationsModule.manifest.id] : []),
         ]);
-        const prepareGuilds = installGuildTracking(client, database, publicModules, bootstrapLogger, enabledCoreModuleIds, undefined, environment.HELYX_GUILD_RECONCILIATION_INTERVAL_SECONDS * 1_000, undefined, environment.DISCORD_CLIENT_ID);
+        const prepareGuilds = installGuildTracking(client, database, publicModules, bootstrapLogger, enabledCoreModuleIds, undefined, environment.HELYX_GUILD_RECONCILIATION_INTERVAL_SECONDS * 1_000, undefined, environment.DISCORD_CLIENT_ID, hostedSafety, hostedInviteGate);
+        const hostedLeaveWorker = hostedSafety
+            ? new HostedServerLeaveWorker(database, client, bootstrapLogger)
+            : undefined;
         const commandsReady = installInteractions(client, modules, {
             globalCommandMode: environment.HELYX_GLOBAL_COMMAND_MODE,
             ...(environment.DISCORD_INTERNAL_GUILD_ID
@@ -449,6 +466,7 @@ async function startUnshardedBot(processEnvironment) {
                 return;
             shuttingDown = true;
             prepareGuilds.stop();
+            await hostedLeaveWorker?.stop();
             process.off("SIGINT", onSigint);
             process.off("SIGTERM", onSigterm);
             if (retentionCleanupTimer)
@@ -513,6 +531,7 @@ async function startUnshardedBot(processEnvironment) {
             await runtime.start();
             await client.login(environment.DISCORD_TOKEN);
             await commandsReady;
+            hostedLeaveWorker?.start();
             scheduledTasks = createScheduledTaskRunner({
                 database,
                 modules: publicModules,

package/dist/premium-activation-module.js

@@ -479,6 +479,8 @@ function successResponse(action, slot) {
     return message(`## Premium activated\nSlot ${String(slot.ordinal)} now supplies Premium to this server.`, GREEN);
 }
 function safeFailure(code) {
+    if (code === "target_blacklisted")
+        return message("Premium cannot be assigned to this server. No slot changes were made.", RED);
     if (code === "target_admin_override")
         return message("This server is already covered by an Admin override. No paid slot was used.", GREEN);
     if (code === "target_already_paid")

package/dist/shard-supervisor.js

@@ -1,5 +1,5 @@
 import { safeError, ServiceRegistry } from "@helyx/core";
-import { checkDatabaseConnection, createDatabasePool, AuditRepository, GuildCommandRepository, InteractionSessionRepository, PremiumAllocationRepository, RateLimitRepository, runConfiguredModuleMigrations, runCoreMigrations, RuntimeStateRepository, } from "@helyx/database";
+import { checkDatabaseConnection, createDatabasePool, AuditRepository, GuildCommandRepository, HostedServerSafetyRepository, InteractionSessionRepository, PremiumAllocationRepository, RateLimitRepository, runConfiguredModuleMigrations, runCoreMigrations, RuntimeStateRepository, } from "@helyx/database";
 import { createPlatformServices, gamingStatisticsRecordOwner, achievementContributionRecordOwner, PostgresPrivacyProviderExecutor, } from "@helyx/platform";
 import { HELYX_SERVICE_NAMES } from "@helyx/sdk";
 import { Client, ShardingManager } from "discord.js";
@@ -1697,11 +1697,12 @@ function failedCloud(requestId, message) {
 }
 async function cleanupExpiredCoreRecords(database, logger) {
     try {
-        const [sessions, rateLimits, verificationAudit, commandRecords] = await Promise.all([
+        const [sessions, rateLimits, verificationAudit, commandRecords, hostedLeaveDeliveries,] = await Promise.all([
             new InteractionSessionRepository(database).deleteExpired(),
             new RateLimitRepository(database).deleteExpired(),
             new AuditRepository(database).deleteModuleEventsOlderThanMonths("helyx.verification", 12),
             new GuildCommandRepository(database).deleteExpired(12),
+            new HostedServerSafetyRepository(database).deleteTerminalLeaveDeliveriesOlderThanMonths(24),
         ]);
         const commandRecordCount = commandRecords.history +
             commandRecords.idempotencyKeys +
@@ -1710,13 +1711,15 @@ async function cleanupExpiredCoreRecords(database, logger) {
         if (sessions > 0 ||
             rateLimits > 0 ||
             verificationAudit > 0 ||
-            commandRecordCount > 0)
+            commandRecordCount > 0 ||
+            hostedLeaveDeliveries > 0)
             logger.info({
                 event: "database.retention_cleaned",
                 interactionSessions: sessions,
                 rateLimitWindows: rateLimits,
                 verificationAuditEvents: verificationAudit,
                 commandRecords: commandRecordCount,
+                hostedLeaveDeliveries,
             }, "Expired core records removed");
     }
     catch (error) {

package/dist/shard-worker.d.ts

@@ -35,6 +35,7 @@ export declare function parseShardWorkerEnvironment(processEnvironment: NodeJS.P
     HELYX_MODULE_PACKAGES: string[];
     HELYX_MODULE_CATALOGUE_PATH: string | undefined;
     HELYX_DASHBOARD_PUBLIC_URL: string;
+    HELYX_HOSTED_MODERATION_ENABLED: boolean;
     HELYX_SUPPORT_STAFF_CHANNEL_ID: string | undefined;
     HELYX_VERIFICATION_ENABLED: boolean;
     HELYX_VERIFICATION_SIGNING_PUBLIC_KEYS: Record<string, string>;

package/dist/shard-worker.js

@@ -32,6 +32,7 @@ import { PostgresTriviaDataProvider } from "./trivia-data-provider.js";
 import { createDeveloperOperationsModule, WorkerShardHealthProvider, } from "./developer-operations-module.js";
 import { assertShardMessageSize, controlOperationGuildId, executeShardControlOperation, guildIdToShardId, SHARD_LEASE_HEARTBEAT_TIMEOUT_MS, shardIdentitySchema, supervisorMessageSchema, } from "./shard-contracts.js";
 import { gatewayIntentsForModules, readBotVersion, } from "./index.js";
+import { HostedBotInviteGateClient, HostedServerLeaveWorker, HostedServerModerationClient, PostgresHostedGuildSafety, } from "./hosted-server-moderation.js";
 import { createSupportModule } from "./support-module.js";
 import { createOAuthModule } from "./oauth-module.js";
 import { createPrivacyModule } from "./privacy-module.js";
@@ -79,6 +80,15 @@ export async function startShardWorker(processEnvironment = process.env, identit
             ? {}
             : { maxConnections: environment.HELYX_SHARD_WORKER_DATABASE_POOL_MAX }),
     });
+    const hostedSafety = environment.HELYX_HOSTED_MODERATION_ENABLED
+        ? new PostgresHostedGuildSafety(database)
+        : undefined;
+    const developerModeration = environment.HELYX_HOSTED_MODERATION_ENABLED
+        ? new HostedServerModerationClient(environment.HELYX_CLOUD_API_URL, environment.HELYX_BOT_CONTROL_SECRET)
+        : undefined;
+    const hostedInviteGate = environment.HELYX_HOSTED_MODERATION_ENABLED
+        ? new HostedBotInviteGateClient(environment.HELYX_CLOUD_API_URL, environment.HELYX_BOT_CONTROL_SECRET)
+        : undefined;
     const eventLoopDelay = monitorEventLoopDelay({ resolution: 20 });
     eventLoopDelay.enable();
     let status = "starting";
@@ -90,6 +100,7 @@ export async function startShardWorker(processEnvironment = process.env, identit
     let client;
     let cloudProxy;
     let shardHealthProvider;
+    let hostedLeaveWorker;
     let leaseHeartbeatWatchdog;
     let forcedLeaseExit;
     let numericWriteBehind;
@@ -99,6 +110,7 @@ export async function startShardWorker(processEnvironment = process.env, identit
         shuttingDown = true;
         status = "stopped";
         guildTracking?.stop();
+        await hostedLeaveWorker?.stop();
         if (healthTimer)
             clearInterval(healthTimer);
         leaseHeartbeatWatchdog?.stop();
@@ -192,6 +204,7 @@ export async function startShardWorker(processEnvironment = process.env, identit
                 processLabel: `shard worker ${identity.shardId}`,
                 triviaData: new PostgresTriviaDataProvider(database),
                 health: shardHealthProvider,
+                ...(developerModeration ? { moderation: developerModeration } : {}),
             })
             : undefined;
         const modules = [
@@ -265,8 +278,14 @@ export async function startShardWorker(processEnvironment = process.env, identit
             shardId: identity.shardId,
             fencingToken: BigInt(identity.fencingToken),
         };
-        const prepareGuilds = installGuildTracking(client, database, publicModules, logger, enabledCoreModuleIds, shardOwnership, environment.HELYX_GUILD_RECONCILIATION_INTERVAL_SECONDS * 1_000, identity.shardCount, environment.DISCORD_CLIENT_ID);
+        const prepareGuilds = installGuildTracking(client, database, publicModules, logger, enabledCoreModuleIds, shardOwnership, environment.HELYX_GUILD_RECONCILIATION_INTERVAL_SECONDS * 1_000, identity.shardCount, environment.DISCORD_CLIENT_ID, hostedSafety, hostedInviteGate);
         guildTracking = prepareGuilds;
+        hostedLeaveWorker = hostedSafety
+            ? new HostedServerLeaveWorker(database, client, logger, {
+                shardId: identity.shardId,
+                shardCount: identity.shardCount,
+            })
+            : undefined;
         const commandsReady = installInteractions(client, modules, shardWorkerCommandRegistration({
             ...(environment.DISCORD_INTERNAL_GUILD_ID
                 ? { internalGuildId: environment.DISCORD_INTERNAL_GUILD_ID }
@@ -358,6 +377,7 @@ export async function startShardWorker(processEnvironment = process.env, identit
         runtimeStarted = true;
         await client.login(environment.DISCORD_TOKEN);
         await commandsReady;
+        hostedLeaveWorker?.start();
         healthTimer = setInterval(() => sendHealth(identity, health(identity, client, status, eventLoopDelay.mean, moduleEvents?.queueDepth() ?? 0)), HEALTH_INTERVAL_MS);
         healthTimer.unref();
         process.once("SIGTERM", () => void shutdown("SIGTERM"));

package/documentation/examples/.env.example

@@ -65,6 +65,7 @@ HELYX_SHARD_MODE=off
 # HELYX_BOT_CONTROL_SECRET=replace-with-a-base64-encoded-32-byte-key
 # HELYX_BOT_CONTROL_PORT=3001
 # HELYX_GUILD_RECONCILIATION_INTERVAL_SECONDS=900
+HELYX_HOSTED_MODERATION_ENABLED=false
 
 # Guild command writes remain off until explicitly enabled for known guild IDs.
 HELYX_GUILD_COMMAND_WRITES_ENABLED=false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helyx/bot",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Production Discord runtime for the modular Helyx platform.",
   "keywords": [
     "helyx",