@helyx/bot 0.4.11 → 0.4.14

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 0.4.14
+
+### Patch Changes
+
+- Updated dependencies
+  - @helyx/control-protocol@0.3.1
+
+## 0.4.13
+
+### Patch Changes
+
+- Add the hosted-only Stage 11 Verification foundation: bounded signed challenge
+  contracts, restricted persistence and privacy traversal, shard-safe bot
+  delivery, delegated investigation permissions, verifier configuration and
+  health, and explicit exclusion from every self-hosted composition.
+- Updated dependencies
+  - @helyx/control-protocol@0.3.0
+  - @helyx/module-manifest@0.6.0
+  - @helyx/config@0.5.0
+  - @helyx/database@0.6.0
+  - @helyx/sdk@0.5.0
+  - @helyx/platform@0.4.0
+  - @helyx/core@0.1.12
+  - @helyx/framework@0.1.12
+
+## 0.4.12
+
+### Patch Changes
+
+- Repair hosted guild presence after removal, restart and shard reassignment with
+  bounded fenced reconciliation and customer-safe dashboard states.
+- Exit with failure after an unexpected coordinated-shard lease shutdown so the
+  service orchestrator replaces the stopped supervisor automatically.
+- Retry one transient lease-renewal transport failure within the existing
+  fencing window while still failing closed on an actual ownership mismatch.
+- Updated dependencies
+  - @helyx/config@0.4.4
+  - @helyx/database@0.5.1
+  - @helyx/platform@0.3.1
+
 ## 0.4.11
 
 ### Patch Changes

package/dist/control-server.d.ts

@@ -1,5 +1,6 @@
-import { type DatabasePool } from "@helyx/database";
+import { type DatabasePool, type GuildShardOwnership } from "@helyx/database";
 import { type DashboardActionResult, type ManagedResourceCreationIntent, type ManagedResourceDetail, type ManagedResourcePage, type ManagedResourceRelationPage, type ManagedResourceValue, type MessageResponse, type ModuleDefinition, type PermissionActor, type PrivacyCapturePage, type PrivacyErasePage, type PrivacyProviderExecutor, type ServiceAccess } from "@helyx/sdk";
+import { type ActionReceipt, type SignedAssessmentEnvelope } from "@helyx/verification-contracts";
 import { type Client } from "discord.js";
 import { type FastifyInstance } from "fastify";
 import { type ShardHealthSnapshot } from "./shard-contracts.js";
@@ -63,7 +64,7 @@ export interface BotControlGuildResources {
     channels: Array<{
         id: string;
         name: string;
-        type: "guild_text" | "guild_announcement";
+        type: "guild_text" | "guild_announcement" | "guild_category";
     }>;
     roles: Array<{
         id: string;
@@ -71,7 +72,14 @@ export interface BotControlGuildResources {
         colour: string;
     }>;
 }
+export type BotGuildPresenceState = "installed" | "not_installed" | "unknown" | "unavailable";
+export interface BotGuildPresenceObservation {
+    guildId: string;
+    state: BotGuildPresenceState;
+    observedAt: string;
+}
 export interface BotControlGuildResourceDirectory {
+    listGuildPresence(guildIds: readonly string[]): Promise<BotGuildPresenceObservation[]>;
     getGuildResources(guildId: string): Promise<BotControlGuildResources>;
     sendToChannel(channelId: string, response: MessageResponse): Promise<{
         messageId: string;
@@ -85,6 +93,7 @@ export interface BotControlGuildResourceDirectory {
 export declare class DiscordGuildResourceDirectory implements BotControlGuildResourceDirectory {
     private readonly client;
     constructor(client: Client);
+    listGuildPresence(guildIds: readonly string[]): Promise<BotGuildPresenceObservation[]>;
     getGuildResources(guildId: string): Promise<BotControlGuildResources>;
     sendToChannel(channelId: string, response: MessageResponse): Promise<{
         messageId: string;
@@ -120,7 +129,18 @@ export interface BotControlState {
 }
 export interface BotControlHandler {
     sendSupportNotification(input: SupportNotificationInput): Promise<void>;
+    listGuildPresence(input: {
+        guildIds: readonly string[];
+        correlationId: string;
+    }): Promise<BotGuildPresenceObservation[]>;
     getGuildState(guildId: string): Promise<BotControlState>;
+    canAccessManagedResource(input: {
+        guildId: string;
+        moduleId: string;
+        resourceType: string;
+        operation: "list" | "read";
+        actorUserId: string;
+    }): Promise<boolean>;
     setModuleStatus(input: {
         guildId: string;
         moduleId: string;
@@ -242,6 +262,7 @@ export interface BotControlHandler {
         correlationId: string;
         actorAuthenticatedAt?: string;
     }): Promise<ManagedResourceDetail | null>;
+    acceptVerificationResult(envelope: SignedAssessmentEnvelope): Promise<ActionReceipt>;
     listPrivacyProviders(): Promise<readonly {
         id: string;
         version: number;
@@ -273,11 +294,18 @@ export declare class BotControlService implements BotControlHandler {
     private readonly database;
     private readonly resources;
     private readonly supportNotifications?;
+    private readonly presenceOwnership?;
+    private readonly presenceShardCount?;
     constructor(database: DatabasePool, modules: readonly ModuleDefinition[], resources: BotControlGuildResourceDirectory, services: ServiceAccess, privacyExecutor?: PrivacyProviderExecutor, supportNotifications?: {
         guildId: string;
         channelId: string;
-    } | undefined);
+    } | undefined, presenceOwnership?: GuildShardOwnership | undefined, presenceShardCount?: number | undefined);
+    listGuildPresence(input: {
+        guildIds: readonly string[];
+        correlationId: string;
+    }): Promise<BotGuildPresenceObservation[]>;
     sendSupportNotification(input: SupportNotificationInput): Promise<void>;
+    acceptVerificationResult(envelopeInput: SignedAssessmentEnvelope): Promise<ActionReceipt>;
     listPrivacyProviders(): Promise<readonly {
         id: string;
         version: number;
@@ -300,6 +328,13 @@ export declare class BotControlService implements BotControlHandler {
         cursor?: string;
     }): Promise<PrivacyErasePage>;
     getGuildState(guildId: string): Promise<BotControlState>;
+    canAccessManagedResource(input: {
+        guildId: string;
+        moduleId: string;
+        resourceType: string;
+        operation: "list" | "read";
+        actorUserId: string;
+    }): Promise<boolean>;
     setModuleStatus(input: {
         guildId: string;
         moduleId: string;

package/dist/control-server.js

@@ -1,5 +1,6 @@
 import { AuditRepository, InstallationRepository, ModuleLoggingPolicyRepository, OptimisticConcurrencyError, PermissionPolicyRepository, withTransaction, } from "@helyx/database";
 import { DashboardActionValidationError, HELYX_SERVICE_NAMES, ModuleStateValidationError, } from "@helyx/sdk";
+import { actionReceiptSchema, signedAssessmentEnvelopeSchema, } from "@helyx/verification-contracts";
 import { canUseCommand } from "@helyx/core";
 import { ChannelType, PermissionFlagsBits } from "discord.js";
 import Fastify, {} from "fastify";
@@ -49,7 +50,7 @@ const resourceCursor = z.string().min(1).max(2_048);
 const resourceActionId = z.string().regex(/^[a-z][a-z0-9_-]*$/u);
 const managedResourceFilters = z
     .record(z.string().regex(/^[a-z][a-zA-Z0-9_]*$/u), z.string().trim().min(1).max(100))
-    .refine((value) => Object.keys(value).length <= 5);
+    .refine((value) => Object.keys(value).length <= 8);
 const managedResourceValue = z.custom((value) => isBoundedManagedResourceValue(value), "Managed resource value exceeds the transport limits");
 const managedResourceObject = z
     .record(z.string().min(1).max(100), managedResourceValue)
@@ -98,6 +99,24 @@ export class DiscordGuildResourceDirectory {
     constructor(client) {
         this.client = client;
     }
+    listGuildPresence(guildIds) {
+        const observedAt = new Date().toISOString();
+        const ready = this.client.isReady();
+        return Promise.resolve(guildIds.map((guildId) => {
+            const guild = this.client.guilds.cache.get(guildId);
+            return {
+                guildId,
+                state: !ready
+                    ? "unknown"
+                    : !guild
+                        ? "not_installed"
+                        : guild.available
+                            ? "installed"
+                            : "unavailable",
+                observedAt,
+            };
+        }));
+    }
     async getGuildResources(guildId) {
         try {
             const guild = await this.client.guilds.fetch(guildId);
@@ -108,13 +127,16 @@ export class DiscordGuildResourceDirectory {
             return {
                 channels: [...channels.values()]
                     .filter((channel) => channel?.type === ChannelType.GuildText ||
-                    channel?.type === ChannelType.GuildAnnouncement)
+                    channel?.type === ChannelType.GuildAnnouncement ||
+                    channel?.type === ChannelType.GuildCategory)
                     .map((channel) => ({
                     id: channel.id,
                     name: channel.name,
                     type: channel.type === ChannelType.GuildAnnouncement
                         ? "guild_announcement"
-                        : "guild_text",
+                        : channel.type === ChannelType.GuildCategory
+                            ? "guild_category"
+                            : "guild_text",
                 }))
                     .sort((left, right) => left.name.localeCompare(right.name)),
                 roles: [...roles.values()]
@@ -201,6 +223,8 @@ export class BotControlService {
     database;
     resources;
     supportNotifications;
+    presenceOwnership;
+    presenceShardCount;
     #modules;
     #dashboardModules;
     #configurations;
@@ -208,10 +232,12 @@ export class BotControlService {
     #permissions;
     #services;
     #privacyProviders;
-    constructor(database, modules, resources, services, privacyExecutor, supportNotifications) {
+    constructor(database, modules, resources, services, privacyExecutor, supportNotifications, presenceOwnership, presenceShardCount) {
         this.database = database;
         this.resources = resources;
         this.supportNotifications = supportNotifications;
+        this.presenceOwnership = presenceOwnership;
+        this.presenceShardCount = presenceShardCount;
         this.#modules = new Map(modules.map((module) => [module.manifest.id, module]));
         this.#dashboardModules = modules
             .filter((module) => module.manifest.dashboard !== undefined)
@@ -229,6 +255,40 @@ export class BotControlService {
             })
             : []);
     }
+    async listGuildPresence(input) {
+        const guildIds = [...new Set(input.guildIds)];
+        if (guildIds.length > 200)
+            throw new BotControlValidationError("Guild presence requests cannot exceed 200 guilds");
+        const observations = await this.resources.listGuildPresence(guildIds);
+        const returned = new Set(observations.map(({ guildId }) => guildId));
+        const complete = guildIds.map((guildId) => observations.find((item) => item.guildId === guildId) ?? {
+            guildId,
+            state: "unknown",
+            observedAt: new Date().toISOString(),
+        });
+        if (observations.some(({ guildId }) => !guildIds.includes(guildId)) ||
+            returned.size !== observations.length)
+            throw new BotControlTransportError(502, "The guild presence response was invalid");
+        const absent = complete
+            .filter(({ state }) => state === "not_installed")
+            .map(({ guildId }) => guildId);
+        if (absent.length > 0) {
+            const repository = new InstallationRepository(this.database);
+            if (this.presenceOwnership)
+                await repository.adoptGuildsForReconciliation({
+                    guildIds: absent,
+                    ownership: this.presenceOwnership,
+                    shardCount: this.presenceShardCount,
+                });
+            await repository.markGuildsRemovedForReconciliation({
+                guildIds: absent,
+                ...(this.presenceOwnership
+                    ? { ownership: this.presenceOwnership }
+                    : {}),
+            });
+        }
+        return complete;
+    }
     async sendSupportNotification(input) {
         if (!this.supportNotifications)
             throw new BotControlNotFoundError("The support notification channel is not configured");
@@ -263,6 +323,15 @@ export class BotControlService {
             },
         }, input.notificationId);
     }
+    acceptVerificationResult(envelopeInput) {
+        if (!this.#services.has(HELYX_SERVICE_NAMES.verification))
+            throw new BotControlTransportError(503, "Verification result handling is unavailable");
+        const envelope = signedAssessmentEnvelopeSchema.parse(envelopeInput);
+        return this.#services
+            .get(HELYX_SERVICE_NAMES.verification)
+            .acceptResult(envelope)
+            .then((receipt) => actionReceiptSchema.parse(receipt));
+    }
     listPrivacyProviders() {
         return Promise.resolve([...this.#privacyProviders.values()]
             .map((provider) => ({
@@ -345,6 +414,19 @@ export class BotControlService {
             logging,
         };
     }
+    async canAccessManagedResource(input) {
+        try {
+            const { module } = await this.#prepareManagedResource(input);
+            this.#requireManagedResourceOperation(module, input.resourceType, input.operation);
+            await this.#authorizeAction(input.guildId, module, input.actorUserId, managedResourcePermissionId(module, input.resourceType, input.operation));
+            return true;
+        }
+        catch (error) {
+            if (error instanceof BotControlForbiddenError)
+                return false;
+            throw error;
+        }
+    }
     async #inspectRuntimeCapabilities() {
         if (!this.#services.has(HELYX_SERVICE_NAMES.discordResources))
             return { messageContent: false };
@@ -894,6 +976,7 @@ export async function createBotControlServer(input) {
     }
     server.get("/health", (_request, reply) => readiness(reply));
     server.get("/v1/health", (_request, reply) => readiness(reply));
+    server.post("/v1/verification/results", async (request) => input.service.acceptVerificationResult(signedAssessmentEnvelopeSchema.parse(request.body)));
     server.get("/v1/shards/health", async (request, reply) => {
         reply.header("Cache-Control", "no-store");
         if (!input.shardHealth)
@@ -958,6 +1041,18 @@ export async function createBotControlServer(input) {
         await input.service.sendSupportNotification(body);
         return reply.code(204).send();
     });
+    server.post("/v1/guilds/presence", async (request) => {
+        const body = z
+            .object({
+            guildIds: z.array(snowflake).min(1).max(200),
+            correlationId: z.uuid(),
+        })
+            .strict()
+            .parse(request.body);
+        return {
+            items: await input.service.listGuildPresence(body),
+        };
+    });
     server.post("/v1/privacy/capture", async (request) => {
         const body = z
             .object({
@@ -966,11 +1061,13 @@ export async function createBotControlServer(input) {
             requestId: z.uuid(),
             subjectUserId: snowflake,
             cutoffAt: z.coerce.date(),
+            operation: z.enum(["capture", "residual_scan"]).optional(),
             cursor: z.string().min(1).max(2_048).optional(),
         })
             .strict()
             .parse(request.body);
-        const { cursor, ...value } = body;
+        const { cursor, operation: _operation, ...value } = body;
+        void _operation;
         return input.service.capturePrivacy({
             ...value,
             ...(cursor ? { cursor } : {}),
@@ -998,6 +1095,28 @@ export async function createBotControlServer(input) {
         const { guildId } = z.object({ guildId: snowflake }).parse(request.params);
         return input.service.getGuildState(guildId);
     });
+    server.post("/v1/guilds/:guildId/modules/:moduleId/resources/:resourceType/access", async (request) => {
+        const params = z
+            .object({
+            guildId: snowflake,
+            moduleId,
+            resourceType: z.string().regex(/^[a-z][a-z0-9-]*$/u),
+        })
+            .parse(request.params);
+        const body = z
+            .object({
+            operation: z.enum(["list", "read"]),
+            actorUserId: snowflake,
+        })
+            .strict()
+            .parse(request.body);
+        return {
+            allowed: await input.service.canAccessManagedResource({
+                ...params,
+                ...body,
+            }),
+        };
+    });
     server.put("/v1/guilds/:guildId/modules/:moduleId/status", async (request) => {
         const params = z
             .object({ guildId: snowflake, moduleId })

package/dist/events.d.ts

@@ -1,4 +1,5 @@
-import type { DiscordChannelAudienceInspection, DiscordChannelInspection, DiscordEmojiInspection, DiscordMessageInspection, DiscordGuildCapabilityInspection, DiscordGuildChannelAudienceInspection, DiscordResourceInspectionService, DiscordRoleInspection, DiscordMessageService, MemberEnforcementService, MemberRoleService, ModuleDefinition, ServiceAccess } from "@helyx/sdk";
+import type { DiscordChannelAudienceInspection, DiscordChannelInspection, DiscordEmojiInspection, DiscordMessageInspection, DiscordGuildCapabilityInspection, DiscordGuildChannelAudienceInspection, DiscordResourceInspectionService, DiscordRoleInspection, DiscordMessageService, MemberEnforcementService, MemberRoleService, ModuleDefinition, ServiceAccess, VerificationMemberService, VerificationSetupGuildInspection, VerificationSetupPreview, VerificationSetupRequest, VerificationSetupService } from "@helyx/sdk";
+import type { VerificationSetupRepository } from "@helyx/database";
 import { type Client, type MessageReaction, type PartialMessageReaction } from "discord.js";
 import { type InteractionLogger } from "./interactions.js";
 export declare function installModuleEvents(client: Client, modules: readonly ModuleDefinition[], logger: InteractionLogger, services: ServiceAccess): ModuleEventHandle;
@@ -26,7 +27,34 @@ export declare class DiscordMemberEnforcementService implements MemberEnforcemen
     private readonly client;
     constructor(client: Client);
     kick(input: Parameters<MemberEnforcementService["kick"]>[0]): ReturnType<MemberEnforcementService["kick"]>;
+    ban(input: Parameters<MemberEnforcementService["ban"]>[0]): ReturnType<MemberEnforcementService["ban"]>;
 }
+export declare class DiscordVerificationMemberService implements VerificationMemberService {
+    private readonly client;
+    constructor(client: Client);
+    captureSnapshot(input: Parameters<VerificationMemberService["captureSnapshot"]>[0]): ReturnType<VerificationMemberService["captureSnapshot"]>;
+    isCurrentlyBanned(input: Parameters<VerificationMemberService["isCurrentlyBanned"]>[0]): ReturnType<VerificationMemberService["isCurrentlyBanned"]>;
+}
+/**
+ * The single Discord mutation boundary for Verification setup. It deliberately
+ * exposes a preview/apply protocol rather than raw role or overwrite writes.
+ */
+export declare class DiscordVerificationSetupService implements VerificationSetupService {
+    #private;
+    private readonly client;
+    private readonly persistence;
+    constructor(client: Client, persistence: VerificationSetupPersistence);
+    inspect(input: {
+        guildId: string;
+    }): Promise<VerificationSetupGuildInspection>;
+    preview(input: VerificationSetupRequest): Promise<VerificationSetupPreview>;
+    apply(input: VerificationSetupRequest & {
+        previewFingerprint: string;
+        confirmed: true;
+    }): Promise<Awaited<ReturnType<VerificationSetupService["apply"]>>>;
+    hideVerificationChannelForVerifiedMember(input: Parameters<VerificationSetupService["hideVerificationChannelForVerifiedMember"]>[0]): ReturnType<VerificationSetupService["hideVerificationChannelForVerifiedMember"]>;
+}
+export type VerificationSetupPersistence = Pick<VerificationSetupRepository, "begin" | "checkpointResources" | "checkpointOverwrites" | "complete" | "abort">;
 export declare class DiscordMemberRoleService implements MemberRoleService {
     private readonly client;
     constructor(client: Client);