@helyx/bot 0.4.32 → 0.4.33

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.4.33
+
+### Patch Changes
+
+- Add versioned OAuth consumer cleanup contracts, durable and resumable
+  revocation state, least-privilege provider scopes, and Creator Connections
+  cleanup dispatch. Promote the hosted-only Creator Connections module to live
+  availability with clear OAuth activation validation. Ignore shard responses
+  that finish after shutdown has already detached their worker.
+
 ## 0.4.32
 
 ### Patch Changes

package/dist/control-server.d.ts

@@ -1,5 +1,5 @@
 import { type DatabasePool, type GuildShardOwnership } from "@helyx/database";
-import { type DashboardActionResult, type GuildAccessPolicy, type ManagedResourceCreationIntent, type ManagedResourceDetail, type ManagedResourcePage, type ManagedResourceRelationPage, type ManagedResourceValue, type MessageResponse, type ModuleDefinition, type PermissionActor, type PrivacyCapturePage, type PrivacyErasePage, type PrivacyProviderExecutor, type PublicAchievementProjectionPage, type ServiceAccess } from "@helyx/sdk";
+import { type DashboardActionResult, type GuildAccessPolicy, type ManagedResourceCreationIntent, type ManagedResourceDetail, type ManagedResourcePage, type ManagedResourceRelationPage, type ManagedResourceValue, type MessageResponse, type ModuleDefinition, type OAuthConsumerCleanupResult, type PermissionActor, type PrivacyCapturePage, type PrivacyErasePage, type PrivacyProviderExecutor, type PublicAchievementProjectionPage, 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";
@@ -143,6 +143,17 @@ export interface DashboardGuildAccessState extends GuildAccessPolicy {
     updatedAt: string | null;
 }
 export interface BotControlHandler {
+    cleanupOAuthConsumer(input: {
+        consumerBindingId: string;
+        moduleId: string;
+        provider: "youtube" | "twitch";
+        guildId: string;
+        resourceType: string;
+        resourceId: string;
+        subjectUserId: string;
+        contractVersion: number;
+        correlationId: string;
+    }): Promise<OAuthConsumerCleanupResult>;
     sendSupportNotification(input: SupportNotificationInput): Promise<void>;
     listGuildPresence(input: {
         guildIds: readonly string[];
@@ -339,6 +350,17 @@ export declare class BotControlService implements BotControlHandler {
         guildId: string;
         channelId: string;
     } | undefined, presenceOwnership?: GuildShardOwnership | undefined, presenceShardCount?: number | undefined);
+    cleanupOAuthConsumer(input: {
+        consumerBindingId: string;
+        moduleId: string;
+        provider: "youtube" | "twitch";
+        guildId: string;
+        resourceType: string;
+        resourceId: string;
+        subjectUserId: string;
+        contractVersion: number;
+        correlationId: string;
+    }): Promise<OAuthConsumerCleanupResult>;
     listGuildPresence(input: {
         guildIds: readonly string[];
         correlationId: string;

package/dist/control-server.js

@@ -286,6 +286,26 @@ export class BotControlService {
             })
             : []);
     }
+    async cleanupOAuthConsumer(input) {
+        const module = this.#modules.get(input.moduleId);
+        if (!module)
+            throw new BotControlNotFoundError("OAuth consumer module is unavailable");
+        const consumer = module.oauthConsumers?.find((candidate) => candidate.provider === input.provider &&
+            candidate.resourceType === input.resourceType &&
+            candidate.version === input.contractVersion);
+        if (!consumer)
+            throw new BotControlNotFoundError("OAuth consumer cleanup contract is unavailable");
+        return consumer.cleanup({
+            consumerBindingId: input.consumerBindingId,
+            provider: input.provider,
+            guildId: input.guildId,
+            resourceType: input.resourceType,
+            resourceId: input.resourceId,
+            subjectUserId: input.subjectUserId,
+            correlationId: input.correlationId,
+            services: this.#services,
+        });
+    }
     async listGuildPresence(input) {
         const guildIds = [...new Set(input.guildIds)];
         if (guildIds.length > 200)
@@ -1213,6 +1233,23 @@ 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.post("/v1/oauth/consumers/cleanup", async (request) => {
+        const body = z
+            .object({
+            consumerBindingId: z.uuid(),
+            moduleId,
+            provider: z.enum(["youtube", "twitch"]),
+            guildId: snowflake,
+            resourceType: z.string().regex(/^[a-z][a-z0-9_-]*$/u),
+            resourceId,
+            subjectUserId: snowflake,
+            contractVersion: z.number().int().min(1).max(32_767),
+            correlationId: z.string().trim().min(1).max(200),
+        })
+            .strict()
+            .parse(request.body);
+        return input.service.cleanupOAuthConsumer(body);
+    });
     server.get("/v1/shards/health", async (request, reply) => {
         reply.header("Cache-Control", "no-store");
         if (!input.shardHealth)

package/dist/oauth-module.js

@@ -155,9 +155,13 @@ export function createOAuthModule() {
                                 componentsV2: {
                                     text: [
                                         {
-                                            content: result.providerRevocation === "completed"
-                                                ? `${providerName(result.provider)} access has been removed from Helyx. Local credentials were deleted.`
-                                                : `${providerName(result.provider)} access has been removed from Helyx and local credentials were deleted. Helyx could not confirm provider-side revocation, so you may also remove Helyx from your ${providerName(result.provider)} connected-app settings.`,
+                                            content: result.outcome === "processing"
+                                                ? `${providerName(result.provider)} access removal is already in progress. Helyx will finish it automatically.`
+                                                : result.outcome === "cleanup_pending"
+                                                    ? `${providerName(result.provider)} credentials were deleted. Helyx is still removing related roles and connection records.`
+                                                    : result.providerRevocation === "completed"
+                                                        ? `${providerName(result.provider)} access has been removed from Helyx. Local credentials were deleted.`
+                                                        : `${providerName(result.provider)} access has been removed from Helyx and local credentials were deleted. Helyx could not confirm provider-side revocation, so you may also remove Helyx from your ${providerName(result.provider)} connected-app settings.`,
                                         },
                                     ],
                                 },

package/dist/oauth-service.js

@@ -30,7 +30,7 @@ export class HttpOAuthService {
                 "content-type": "application/json",
             },
             body: JSON.stringify(body),
-            signal: AbortSignal.timeout(6_000),
+            signal: AbortSignal.timeout(15_000),
         });
         if (!response.ok)
             throw new Error(`oauth_service_http_${response.status}`);

package/dist/shard-contracts.d.ts

@@ -359,6 +359,20 @@ export declare const shardControlOperationSchema: z.ZodDiscriminatedUnion<[z.Zod
     expectedRevision: z.ZodNumber;
     value: z.ZodRecord<z.ZodString, z.ZodCustom<ManagedResourceValue, ManagedResourceValue>>;
     actorAuthenticatedAt: z.ZodOptional<z.ZodISODateTime>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"oauth.consumer.cleanup">;
+    consumerBindingId: z.ZodUUID;
+    moduleId: z.ZodString;
+    provider: z.ZodEnum<{
+        youtube: "youtube";
+        twitch: "twitch";
+    }>;
+    guildId: z.ZodString;
+    resourceType: z.ZodString;
+    resourceId: z.ZodString;
+    subjectUserId: z.ZodString;
+    contractVersion: z.ZodNumber;
+    correlationId: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"support.notification.send">;
     guildId: z.ZodString;
@@ -698,6 +712,20 @@ export declare const shardControlRequestSchema: z.ZodObject<{
         expectedRevision: z.ZodNumber;
         value: z.ZodRecord<z.ZodString, z.ZodCustom<ManagedResourceValue, ManagedResourceValue>>;
         actorAuthenticatedAt: z.ZodOptional<z.ZodISODateTime>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"oauth.consumer.cleanup">;
+        consumerBindingId: z.ZodUUID;
+        moduleId: z.ZodString;
+        provider: z.ZodEnum<{
+            youtube: "youtube";
+            twitch: "twitch";
+        }>;
+        guildId: z.ZodString;
+        resourceType: z.ZodString;
+        resourceId: z.ZodString;
+        subjectUserId: z.ZodString;
+        contractVersion: z.ZodNumber;
+        correlationId: z.ZodString;
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"support.notification.send">;
         guildId: z.ZodString;
@@ -1542,6 +1570,20 @@ export declare const supervisorMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObje
         expectedRevision: z.ZodNumber;
         value: z.ZodRecord<z.ZodString, z.ZodCustom<ManagedResourceValue, ManagedResourceValue>>;
         actorAuthenticatedAt: z.ZodOptional<z.ZodISODateTime>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"oauth.consumer.cleanup">;
+        consumerBindingId: z.ZodUUID;
+        moduleId: z.ZodString;
+        provider: z.ZodEnum<{
+            youtube: "youtube";
+            twitch: "twitch";
+        }>;
+        guildId: z.ZodString;
+        resourceType: z.ZodString;
+        resourceId: z.ZodString;
+        subjectUserId: z.ZodString;
+        contractVersion: z.ZodNumber;
+        correlationId: z.ZodString;
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"support.notification.send">;
         guildId: z.ZodString;

package/dist/shard-contracts.js

@@ -425,6 +425,20 @@ export const shardControlOperationSchema = z.discriminatedUnion("kind", [
         ...mutationContext.shape,
     })
         .strict(),
+    z
+        .object({
+        kind: z.literal("oauth.consumer.cleanup"),
+        consumerBindingId: z.uuid(),
+        moduleId,
+        provider: z.enum(["youtube", "twitch"]),
+        guildId: snowflake,
+        resourceType,
+        resourceId,
+        subjectUserId: snowflake,
+        contractVersion: z.number().int().min(1).max(32_767),
+        correlationId: z.string().trim().min(1).max(200),
+    })
+        .strict(),
     z
         .object({
         kind: z.literal("support.notification.send"),
@@ -1111,6 +1125,18 @@ export async function executeShardControlOperation(handler, operation) {
                     ? { actorAuthenticatedAt: operation.actorAuthenticatedAt }
                     : {}),
             });
+        case "oauth.consumer.cleanup":
+            return handler.cleanupOAuthConsumer({
+                consumerBindingId: operation.consumerBindingId,
+                moduleId: operation.moduleId,
+                provider: operation.provider,
+                guildId: operation.guildId,
+                resourceType: operation.resourceType,
+                resourceId: operation.resourceId,
+                subjectUserId: operation.subjectUserId,
+                contractVersion: operation.contractVersion,
+                correlationId: operation.correlationId,
+            });
         case "support.notification.send": {
             return handler.sendSupportNotification({
                 notificationId: operation.notificationId,

package/dist/shard-router.d.ts

@@ -15,6 +15,7 @@ export declare class ShardControlRouter implements BotControlHandler {
         coordinator?: ShardCoordinator;
         notificationGuildId?: string;
     });
+    cleanupOAuthConsumer(input: Parameters<BotControlHandler["cleanupOAuthConsumer"]>[0]): ReturnType<BotControlHandler["cleanupOAuthConsumer"]>;
     getGuildState(guildId: string): ReturnType<BotControlHandler["getGuildState"]>;
     canAccessDashboard(input: Parameters<BotControlHandler["canAccessDashboard"]>[0]): ReturnType<BotControlHandler["canAccessDashboard"]>;
     getGuildAccessPolicy(input: Parameters<BotControlHandler["getGuildAccessPolicy"]>[0]): ReturnType<BotControlHandler["getGuildAccessPolicy"]>;

package/dist/shard-router.js

@@ -12,6 +12,9 @@ export class ShardControlRouter {
     constructor(input) {
         this.input = input;
     }
+    cleanupOAuthConsumer(input) {
+        return this.#route({ kind: "oauth.consumer.cleanup", ...input });
+    }
     getGuildState(guildId) {
         return this.#route({ kind: "guild.state.get", guildId });
     }

package/dist/shard-supervisor.js

@@ -651,7 +651,22 @@ export async function startShardSupervisor(environment, processEnvironment, work
             }
         }
         assertShardMessageSize(response);
-        await workers.get(shardId)?.send(response);
+        await sendWorkerResponse(shardId, response);
+    }
+    async function sendWorkerResponse(shardId, response) {
+        if (shuttingDown)
+            return;
+        const worker = workers.get(shardId);
+        if (!worker?.process)
+            return;
+        try {
+            await worker.send(response);
+        }
+        catch (error) {
+            if (shuttingDown || !worker.process)
+                return;
+            throw error;
+        }
     }
     async function handleWorkerMessage(shardId, raw) {
         if (serializedBytes(raw) > SHARD_CONTROL_MAX_BYTES)
@@ -709,7 +724,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
             const response = leaderLease
                 ? await executeLeaderCloud(message.data)
                 : await routeCloudToLeader(message.data);
-            await workers.get(shardId)?.send(response);
+            await sendWorkerResponse(shardId, response);
             return;
         }
         if (message.data.type === "helyx.operations.health.request") {
@@ -720,7 +735,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
                 health: boundedOperationalHealth(await buildHealth()),
             };
             assertShardMessageSize(response);
-            await workers.get(shardId)?.send(response);
+            await sendWorkerResponse(shardId, response);
         }
     }
     function dispatchLocal(shardId, request) {
@@ -1392,9 +1407,14 @@ export function buildShardWorkerEnvironment(source, identity, restartCount) {
         "HELYX_SUPPORT_STAFF_CHANNEL_ID",
         "HELYX_MODULE_PACKAGES",
         "HELYX_MESSAGE_CONTENT_ENABLED",
+        "HELYX_GUILD_MEMBERS_ENABLED",
+        "HELYX_GUILD_RECONCILIATION_INTERVAL_SECONDS",
         "HELYX_MODULE_CATALOGUE_PATH",
         "HELYX_CLOUD_CONNECT_ENABLED",
+        "HELYX_CLOUD_API_URL",
         "HELYX_OWNER_USER_IDS",
+        "HELYX_OAUTH_ENABLED",
+        "HELYX_OAUTH_INTERNAL_SECRET",
         "HELYX_VERIFICATION_ENABLED",
         "HELYX_VERIFICATION_INSTALLATION_ID",
         "HELYX_VERIFICATION_URL",

package/package.json

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