@helyx/bot 0.1.3 → 0.2.1

package/dist/cloud-connector.js

@@ -0,0 +1,671 @@
+import { CLOUD_DEFAULT_REQUEST_TIMEOUT_MS, CLOUD_PROTOCOL_VERSION, ConnectionSequenceGuard, assertCloudMessageSize, cloudControlResponsePayloadSchema, connectedCloudMessageSchema, connectorAcceptedSchema, connectorChallengeSchema, connectorCredentialActionSchema, connectorHelloSchema, connectorRejectedSchema, generateConnectorKeyPair, signConnectorCredentialAction, signConnectorChallenge, } from "@helyx/control-protocol";
+import { CloudConnectorRepository, } from "@helyx/database";
+import { createCipheriv, createDecipheriv, createHash, randomBytes, randomUUID, } from "node:crypto";
+import { readFile, rm } from "node:fs/promises";
+import { resolve } from "node:path";
+import WebSocket from "ws";
+import { z } from "zod";
+import { CloudControlDeniedError, CloudControlDispatcher, } from "./cloud-control-dispatcher.js";
+const enrolmentFileSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    enrolmentToken: z.string().trim().min(19).max(100),
+})
+    .strict();
+const exchangeResponseSchema = z
+    .object({
+    installationId: z.uuid(),
+    credentialId: z.uuid(),
+    credentialGeneration: z.number().int().positive(),
+    cloudEndpointId: z.string().min(1).max(200),
+})
+    .strict();
+const rotationResponseSchema = z
+    .object({
+    credentialId: z.uuid(),
+    credentialGeneration: z.number().int().positive(),
+})
+    .strict();
+const supportConsentInputSchema = z
+    .object({
+    supportInspectionEnabled: z.boolean(),
+    supportDataClasses: z
+        .array(z.enum([
+        "module_inventory",
+        "configuration",
+        "permissions",
+        "logging",
+        "health",
+    ]))
+        .max(5)
+        .transform((values) => [...new Set(values)]),
+    diagnosticsEnabled: z.boolean(),
+})
+    .strict();
+export class CloudConnectorController {
+    input;
+    #repository;
+    #dataKey;
+    #dispatcher;
+    #identity;
+    #socket;
+    #state;
+    #lastErrorCode;
+    #stopping = false;
+    #connectionBlocked = false;
+    #loop;
+    constructor(input) {
+        this.input = input;
+        this.#repository = new CloudConnectorRepository(input.database);
+        this.#state = input.environment.HELYX_CLOUD_CONNECT_ENABLED
+            ? "unpaired"
+            : "disabled";
+        this.#dataKey = input.environment.HELYX_DATA_ENCRYPTION_KEY
+            ? Buffer.from(input.environment.HELYX_DATA_ENCRYPTION_KEY, "base64")
+            : undefined;
+    }
+    setControlHandler(handler) {
+        this.#dispatcher = new CloudControlDispatcher(this.input.database, handler);
+    }
+    async start() {
+        if (!this.input.environment.HELYX_CLOUD_CONNECT_ENABLED)
+            return;
+        await this.#repository.cleanupAudit({
+            ordinaryRetentionDays: this.input.environment.HELYX_CLOUD_AUDIT_RETENTION_DAYS,
+            credentialRetentionDays: this.input.environment.HELYX_CLOUD_CREDENTIAL_AUDIT_RETENTION_DAYS,
+        });
+        this.#identity = (await this.#repository.getIdentity()) ?? undefined;
+        if (this.#identity?.revokedAt) {
+            this.#state = "revoked";
+            return;
+        }
+        if (!this.#identity) {
+            const bootstrap = await this.#readBootstrap();
+            if (bootstrap.conflict) {
+                this.#state = "unpaired";
+                this.#lastErrorCode = "bootstrap_sources_conflict";
+                this.input.logger.error({ event: "cloud.bootstrap_conflict" }, "Cloud Connect enrolment sources conflict");
+                return;
+            }
+            if (bootstrap.token) {
+                await this.enrol(bootstrap.token, bootstrap.source ?? "startup");
+                if (bootstrap.filePath)
+                    await rm(bootstrap.filePath, { force: true }).catch(() => undefined);
+            }
+        }
+        if (this.#identity)
+            this.#ensureLoop();
+    }
+    status() {
+        return {
+            state: this.#state,
+            ...(this.#identity
+                ? {
+                    installationId: this.#identity.installationId,
+                    ...(this.#identity.lastConnectedAt
+                        ? { lastConnectedAt: this.#identity.lastConnectedAt }
+                        : {}),
+                }
+                : {}),
+            ...(this.#lastErrorCode ? { lastErrorCode: this.#lastErrorCode } : {}),
+        };
+    }
+    getSupportConsent() {
+        return this.#repository.getConsent();
+    }
+    async updateSupportConsent(input) {
+        const accepted = supportConsentInputSchema.parse(input);
+        const consent = await this.#repository.getConsent();
+        const updated = await this.#repository.updateConsent({
+            policyVersion: consent.policyVersion + 1,
+            supportInspectionEnabled: accepted.supportInspectionEnabled,
+            supportDataClasses: accepted.supportInspectionEnabled
+                ? accepted.supportDataClasses
+                : [],
+            diagnosticsEnabled: accepted.diagnosticsEnabled,
+        });
+        await this.#repository.appendAudit({
+            action: "support.consent.updated",
+            source: "discord",
+            outcome: "succeeded",
+            dataClasses: updated.supportDataClasses,
+        });
+        return updated;
+    }
+    async enrol(rawToken, source) {
+        if (!this.input.environment.HELYX_CLOUD_CONNECT_ENABLED)
+            throw new CloudConnectorUserError("Cloud Connect is disabled in this deployment");
+        const existing = await this.#repository.getIdentity();
+        if (existing && !existing.revokedAt)
+            throw new CloudConnectorUserError("This Helyx deployment is already connected");
+        if (!this.#dataKey)
+            throw new CloudConnectorUserError("HELYX_DATA_ENCRYPTION_KEY is not configured");
+        const token = normalizeEnrolmentToken(rawToken);
+        const keyPair = generateConnectorKeyPair();
+        const application = await this.input.client.application?.fetch();
+        const botUser = this.input.client.user;
+        if (!application || !botUser)
+            throw new CloudConnectorUserError("Discord must be connected before Cloud Connect enrolment");
+        let response;
+        try {
+            response = await fetch(`${this.input.environment.HELYX_CLOUD_API_URL.replace(/\/$/u, "")}/v1/cloud-connect/enrolments/exchange`, {
+                method: "POST",
+                headers: {
+                    Accept: "application/json",
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    enrolmentToken: token,
+                    publicKey: keyPair.publicKey,
+                    publicKeyFingerprint: keyPair.fingerprint,
+                    protocolVersion: CLOUD_PROTOCOL_VERSION,
+                    coreVersion: this.input.coreVersion,
+                    botApplicationId: application.id,
+                    botUserId: botUser.id,
+                    displayName: botUser.username,
+                }),
+                signal: AbortSignal.timeout(CLOUD_DEFAULT_REQUEST_TIMEOUT_MS),
+            });
+        }
+        catch {
+            this.#lastErrorCode = "enrolment_unavailable";
+            throw new CloudConnectorUserError("Helyx Cloud is temporarily unavailable");
+        }
+        const payload = await response.json().catch(() => null);
+        if (!response.ok) {
+            const message = z
+                .object({ message: z.string().min(1).max(300) })
+                .safeParse(payload);
+            this.#lastErrorCode = "enrolment_rejected";
+            throw new CloudConnectorUserError(message.success
+                ? message.data.message
+                : "The Cloud Connect code was rejected");
+        }
+        const exchange = exchangeResponseSchema.parse(payload);
+        const encrypted = encryptPrivateKey(keyPair.privateKey, this.#dataKey, exchange.installationId);
+        this.#identity = await this.#repository.createIdentity({
+            installationId: exchange.installationId,
+            credentialId: exchange.credentialId,
+            cloudEndpointId: exchange.cloudEndpointId,
+            publicKey: keyPair.publicKey,
+            publicKeyFingerprint: keyPair.fingerprint,
+            privateKey: encrypted,
+            credentialGeneration: exchange.credentialGeneration,
+            protocolVersion: CLOUD_PROTOCOL_VERSION,
+            enrolledAt: new Date(),
+        });
+        this.#connectionBlocked = false;
+        await this.#repository.appendAudit({
+            action: "installation.enrolled",
+            source,
+            outcome: "succeeded",
+        });
+        this.#state = "offline";
+        this.#lastErrorCode = undefined;
+        this.#ensureLoop();
+        return this.status();
+    }
+    async disconnect() {
+        if (!this.#identity)
+            throw new CloudConnectorUserError("This Helyx deployment is not connected");
+        await this.#performCredentialAction({
+            protocolVersion: CLOUD_PROTOCOL_VERSION,
+            action: "revoke",
+            installationId: this.#identity.installationId,
+            credentialId: this.#identity.credentialId,
+            credentialGeneration: this.#identity.credentialGeneration,
+            nonce: randomBytes(32).toString("base64url"),
+            issuedAt: new Date().toISOString(),
+        });
+        const revokedAt = new Date();
+        this.#identity = {
+            ...this.#identity,
+            revokedAt,
+        };
+        this.#connectionBlocked = true;
+        this.#state = "revoked";
+        this.#socket?.close(1000, "Local owner disconnected Cloud Connect");
+        await this.#repository.revoke();
+        await this.#repository.appendAudit({
+            action: "installation.disconnected",
+            source: "discord",
+            outcome: "succeeded",
+        });
+    }
+    async rotate() {
+        const identity = this.#identity;
+        if (!identity || identity.revokedAt)
+            throw new CloudConnectorUserError("This Helyx deployment is not connected");
+        if (!this.#dataKey)
+            throw new CloudConnectorUserError("HELYX_DATA_ENCRYPTION_KEY is not configured");
+        const nextKeyPair = generateConnectorKeyPair();
+        const result = rotationResponseSchema.parse(await this.#performCredentialAction({
+            protocolVersion: CLOUD_PROTOCOL_VERSION,
+            action: "rotate",
+            installationId: identity.installationId,
+            credentialId: identity.credentialId,
+            credentialGeneration: identity.credentialGeneration,
+            nonce: randomBytes(32).toString("base64url"),
+            issuedAt: new Date().toISOString(),
+            newPublicKey: nextKeyPair.publicKey,
+            newPublicKeyFingerprint: nextKeyPair.fingerprint,
+        }));
+        this.#socket?.close(1012, "Connector credential rotated");
+        let updated;
+        try {
+            updated = await this.#repository.rotateIdentity({
+                credentialId: result.credentialId,
+                publicKey: nextKeyPair.publicKey,
+                publicKeyFingerprint: nextKeyPair.fingerprint,
+                privateKey: encryptPrivateKey(nextKeyPair.privateKey, this.#dataKey, identity.installationId),
+                expectedGeneration: identity.credentialGeneration,
+                newGeneration: result.credentialGeneration,
+            });
+        }
+        catch {
+            await this.#recordRotationRecovery(identity);
+            throw new CloudConnectorUserError("The cloud credential changed but could not be saved locally. Revoke this installation in the dashboard, then connect it again");
+        }
+        if (!updated)
+            await this.#recordRotationRecovery(identity);
+        if (!updated)
+            throw new CloudConnectorUserError("The cloud credential changed while the local identity was being updated. Revoke this installation in the dashboard, then connect it again");
+        this.#identity = updated;
+        this.#connectionBlocked = false;
+        await this.#repository.appendAudit({
+            action: "credential.rotated",
+            source: "discord",
+            outcome: "succeeded",
+        });
+        this.#state = "connecting";
+        return this.status();
+    }
+    async stop() {
+        this.#stopping = true;
+        this.#state = "stopped";
+        this.#socket?.close(1001, "Helyx bot shutting down");
+        await this.#loop?.catch(() => undefined);
+    }
+    #ensureLoop() {
+        if (this.#loop || this.#stopping || this.#connectionBlocked)
+            return;
+        this.#loop = this.#runLoop().finally(() => {
+            this.#loop = undefined;
+            if (!this.#stopping &&
+                !this.#connectionBlocked &&
+                this.#identity &&
+                !this.#identity.revokedAt)
+                this.#ensureLoop();
+        });
+    }
+    async #runLoop() {
+        let attempt = 0;
+        while (!this.#stopping &&
+            !this.#connectionBlocked &&
+            this.#identity &&
+            !this.#identity.revokedAt) {
+            this.#state = "connecting";
+            try {
+                await this.#connectOnce(this.#identity);
+                attempt = 0;
+            }
+            catch (error) {
+                if (this.#stopping)
+                    break;
+                this.#state = "offline";
+                this.#lastErrorCode = safeConnectorError(error);
+                this.input.logger.warn({
+                    event: "cloud.connection_failed",
+                    reason: this.#lastErrorCode,
+                }, "Cloud Connect is offline; local bot operation continues");
+                const delay = Math.min(1_000 * 2 ** attempt, 30_000);
+                attempt = Math.min(attempt + 1, 5);
+                await wait(delay + Math.floor(Math.random() * Math.max(250, delay / 4)));
+            }
+        }
+    }
+    async #connectOnce(identity) {
+        if (!this.#dispatcher)
+            throw new Error("cloud_dispatcher_unavailable");
+        if (!this.#dataKey)
+            throw new Error("data_encryption_key_unavailable");
+        const endpoint = new URL(this.input.environment.HELYX_CLOUD_ENDPOINT);
+        endpoint.searchParams.set("installation_id", identity.installationId);
+        const socket = new WebSocket(endpoint);
+        this.#socket = socket;
+        let incomingGuard;
+        let outgoingSequence = 0;
+        let heartbeat;
+        let plannedReconnect;
+        const privateKey = decryptPrivateKey(identity.privateKey, this.#dataKey, identity.installationId);
+        const finished = new Promise((resolveFinished, rejectFinished) => {
+            const fail = (error) => {
+                clearInterval(heartbeat);
+                clearTimeout(plannedReconnect);
+                rejectFinished(error instanceof Error ? error : new Error("websocket_failed"));
+            };
+            socket.once("error", fail);
+            socket.once("close", () => {
+                clearInterval(heartbeat);
+                clearTimeout(plannedReconnect);
+                this.#socket = undefined;
+                if (this.#stopping)
+                    resolveFinished();
+                else
+                    rejectFinished(new Error("connection_closed"));
+            });
+            socket.on("message", (raw) => {
+                void (async () => {
+                    try {
+                        const bytes = rawDataBuffer(raw);
+                        assertCloudMessageSize(bytes);
+                        const payload = JSON.parse(bytes.toString("utf8"));
+                        const challenge = connectorChallengeSchema.safeParse(payload);
+                        if (challenge.success) {
+                            await this.#sendHello(socket, identity, privateKey, challenge.data);
+                            return;
+                        }
+                        const accepted = connectorAcceptedSchema.safeParse(payload);
+                        if (accepted.success) {
+                            incomingGuard = new ConnectionSequenceGuard(identity.installationId, accepted.data.connectionEpoch);
+                            this.#state = "online";
+                            this.#lastErrorCode = undefined;
+                            await this.#repository.markConnected();
+                            this.#identity = {
+                                ...identity,
+                                lastConnectedAt: new Date(),
+                            };
+                            heartbeat = setInterval(() => {
+                                if (socket.readyState !== WebSocket.OPEN)
+                                    return;
+                                socket.send(JSON.stringify(connectedMessage({
+                                    type: "connector.heartbeat",
+                                    installationId: identity.installationId,
+                                    connectionEpoch: accepted.data.connectionEpoch,
+                                    sequence: ++outgoingSequence,
+                                    payload: { state: "online" },
+                                })));
+                            }, accepted.data.heartbeatIntervalSeconds * 1_000);
+                            plannedReconnect = setTimeout(() => socket.close(1012, "Planned Cloud Connect session rotation"), accepted.data.reconnectBeforeSeconds * 1_000);
+                            return;
+                        }
+                        const rejected = connectorRejectedSchema.safeParse(payload);
+                        if (rejected.success) {
+                            this.#lastErrorCode = rejected.data.code;
+                            if (!rejected.data.retryable) {
+                                this.#connectionBlocked = true;
+                                if (rejected.data.code === "revoked" ||
+                                    rejected.data.code === "invalid_credential") {
+                                    await this.#repository.revoke();
+                                    this.#identity = {
+                                        ...identity,
+                                        revokedAt: new Date(),
+                                    };
+                                    this.#state = "revoked";
+                                }
+                                else {
+                                    this.#state = "offline";
+                                }
+                            }
+                            socket.close(1008, rejected.data.code);
+                            return;
+                        }
+                        const message = connectedCloudMessageSchema.parse(payload);
+                        incomingGuard?.accept(message);
+                        if (message.type !== "control.request")
+                            return;
+                        const response = await this.#dispatch(message.payload, message.correlationId);
+                        if (socket.readyState === WebSocket.OPEN)
+                            socket.send(JSON.stringify(connectedMessage({
+                                type: "control.response",
+                                installationId: identity.installationId,
+                                connectionEpoch: message.connectionEpoch,
+                                sequence: ++outgoingSequence,
+                                correlationId: message.correlationId,
+                                payload: response,
+                            })));
+                    }
+                    catch (error) {
+                        this.input.logger.warn({
+                            event: "cloud.message_rejected",
+                            reason: safeConnectorError(error),
+                        }, "Cloud Connect message was rejected");
+                        socket.close(1008, "Protocol message rejected");
+                    }
+                })();
+            });
+        });
+        return finished;
+    }
+    async #sendHello(socket, identity, privateKey, challenge) {
+        if (challenge.installationId !== identity.installationId)
+            throw new Error("challenge_installation_mismatch");
+        const application = await this.input.client.application?.fetch();
+        const botUser = this.input.client.user;
+        if (!application || !botUser)
+            throw new Error("discord_not_ready");
+        const guilds = this.input.client.guilds.cache.map((guild) => ({
+            guildId: guild.id,
+            name: guild.name,
+            ownerUserId: guild.ownerId || null,
+        }));
+        const capabilities = connectorCapabilities();
+        const hello = connectorHelloSchema.parse({
+            protocolVersion: CLOUD_PROTOCOL_VERSION,
+            type: "connector.hello",
+            messageId: randomUUID(),
+            installationId: identity.installationId,
+            credentialId: identity.credentialId,
+            credentialGeneration: identity.credentialGeneration,
+            challengeId: challenge.challengeId,
+            signature: signConnectorChallenge(privateKey, challenge),
+            coreVersion: this.input.coreVersion,
+            botApplicationId: application.id,
+            botUserId: botUser.id,
+            capabilities,
+            modules: this.input.modules.map(({ specifier, definition }) => ({
+                id: definition.manifest.id,
+                package: specifier,
+                version: definition.manifest.version,
+                manifestSchemaVersion: 1,
+                configurationSchemaVersion: definition.configuration?.schemaVersion ?? 1,
+            })),
+            guilds,
+        });
+        socket.send(JSON.stringify(hello));
+    }
+    async #dispatch(request, correlationId) {
+        try {
+            const result = await this.#dispatcher.execute(request, correlationId);
+            return cloudControlResponsePayloadSchema.parse({
+                operation: request.operation,
+                ok: true,
+                result,
+            });
+        }
+        catch (error) {
+            const denied = error instanceof CloudControlDeniedError;
+            return cloudControlResponsePayloadSchema.parse({
+                operation: request.operation,
+                ok: false,
+                error: {
+                    code: denied ? "forbidden" : mapControlError(error),
+                    message: denied
+                        ? "The self-hoster has not allowed this support view"
+                        : safeControlMessage(error),
+                    retryable: !denied && mapControlError(error) === "temporarily_unavailable",
+                },
+            });
+        }
+    }
+    async #readBootstrap() {
+        const environmentToken = this.input.environment.HELYX_CLOUD_ENROLMENT_TOKEN;
+        const filePath = resolve(process.cwd(), this.input.environment.HELYX_CLOUD_ENROLMENT_FILE);
+        let fileToken;
+        try {
+            const file = enrolmentFileSchema.parse(JSON.parse(await readFile(filePath, "utf8")));
+            fileToken = file.enrolmentToken;
+        }
+        catch (error) {
+            if (!isMissingFile(error)) {
+                this.input.logger.warn({ event: "cloud.enrolment_file_invalid" }, "Cloud Connect enrolment file was invalid");
+            }
+        }
+        if (environmentToken && fileToken)
+            return { conflict: true };
+        if (environmentToken)
+            return { token: environmentToken, source: "startup", conflict: false };
+        if (fileToken)
+            return { token: fileToken, source: "file", filePath, conflict: false };
+        return { conflict: false };
+    }
+    async #performCredentialAction(unsigned) {
+        const identity = this.#identity;
+        if (!identity || !this.#dataKey)
+            throw new CloudConnectorUserError("This Helyx deployment has no active Cloud Connect identity");
+        const privateKey = decryptPrivateKey(identity.privateKey, this.#dataKey, identity.installationId);
+        const action = connectorCredentialActionSchema.parse({
+            ...unsigned,
+            signature: signConnectorCredentialAction(privateKey, unsigned),
+        });
+        let response;
+        try {
+            response = await fetch(`${this.input.environment.HELYX_CLOUD_API_URL.replace(/\/$/u, "")}/v1/cloud-connect/credentials/action`, {
+                method: "POST",
+                headers: {
+                    Accept: "application/json",
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify(action),
+                signal: AbortSignal.timeout(CLOUD_DEFAULT_REQUEST_TIMEOUT_MS),
+            });
+        }
+        catch {
+            throw new CloudConnectorUserError("Helyx Cloud is unavailable, so the credential was not changed");
+        }
+        const payload = await response.json().catch(() => null);
+        if (!response.ok)
+            throw new CloudConnectorUserError("Helyx Cloud rejected the credential change");
+        return payload;
+    }
+    async #recordRotationRecovery(identity) {
+        this.#connectionBlocked = true;
+        this.#state = "revoked";
+        this.#identity = { ...identity, revokedAt: new Date() };
+        await Promise.allSettled([
+            this.#repository.revoke(),
+            this.#repository.appendAudit({
+                action: "credential.rotation_recovery_required",
+                source: "system",
+                outcome: "failed",
+                safeReasonCode: "local_identity_update_failed",
+            }),
+        ]);
+    }
+}
+export class CloudConnectorUserError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CloudConnectorUserError";
+    }
+}
+function connectorCapabilities() {
+    return [
+        "installation.health.read.v1",
+        "guild.state.read.v1",
+        "guild.module.status.write.v1",
+        "guild.module.configuration.write.v1",
+        "guild.module.permissions.write.v1",
+        "guild.module.logging.write.v1",
+        "guild.module.action.execute.v1",
+        "support.guild.snapshot.read.v1",
+    ];
+}
+function normalizeEnrolmentToken(value) {
+    const normalized = value.trim().toUpperCase();
+    if (!/^[A-Z2-9]{4}(?:-[A-Z2-9]{4}){4}$/u.test(normalized))
+        throw new CloudConnectorUserError("Enter the complete Cloud Connect code shown in the dashboard");
+    return normalized;
+}
+function encryptPrivateKey(privateKey, dataKey, installationId) {
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", dataKey, iv);
+    cipher.setAAD(Buffer.from(`helyx-cloud-connector:${installationId}`, "utf8"));
+    const ciphertext = Buffer.concat([
+        cipher.update(privateKey, "utf8"),
+        cipher.final(),
+    ]);
+    return { ciphertext, iv, tag: cipher.getAuthTag() };
+}
+function decryptPrivateKey(encrypted, dataKey, installationId) {
+    const decipher = createDecipheriv("aes-256-gcm", dataKey, encrypted.iv);
+    decipher.setAAD(Buffer.from(`helyx-cloud-connector:${installationId}`, "utf8"));
+    decipher.setAuthTag(encrypted.tag);
+    return Buffer.concat([
+        decipher.update(encrypted.ciphertext),
+        decipher.final(),
+    ]).toString("utf8");
+}
+function connectedMessage(input) {
+    const now = new Date();
+    return connectedCloudMessageSchema.parse({
+        protocolVersion: CLOUD_PROTOCOL_VERSION,
+        type: input.type,
+        messageId: randomUUID(),
+        correlationId: input.correlationId ?? randomUUID(),
+        installationId: input.installationId,
+        connectionEpoch: input.connectionEpoch,
+        sequence: input.sequence,
+        sentAt: now.toISOString(),
+        expiresAt: new Date(now.getTime() + CLOUD_DEFAULT_REQUEST_TIMEOUT_MS).toISOString(),
+        payload: input.payload,
+    });
+}
+function mapControlError(error) {
+    const name = error instanceof Error ? error.name : "";
+    if (name.includes("NotFound"))
+        return "not_found";
+    if (name.includes("Concurrency") || name.includes("Conflict"))
+        return "conflict";
+    if (name.includes("Validation"))
+        return "bad_request";
+    if (name.includes("Unavailable"))
+        return "temporarily_unavailable";
+    return "internal_error";
+}
+function safeControlMessage(error) {
+    const code = mapControlError(error);
+    if (code === "not_found")
+        return "The requested Helyx resource was not found";
+    if (code === "conflict")
+        return "The setting changed elsewhere. Refresh and try again";
+    if (code === "bad_request")
+        return error instanceof Error
+            ? error.message.slice(0, 300)
+            : "The requested change was not valid";
+    if (code === "temporarily_unavailable")
+        return "The self-hosted bot is temporarily unavailable";
+    return "The self-hosted bot could not complete the request";
+}
+function safeConnectorError(error) {
+    if (!(error instanceof Error))
+        return "unknown_error";
+    return createHash("sha256")
+        .update(`${error.name}:${error.message}`, "utf8")
+        .digest("hex")
+        .slice(0, 16);
+}
+function isMissingFile(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        error.code === "ENOENT");
+}
+function wait(milliseconds) {
+    return new Promise((resolveWait) => setTimeout(resolveWait, milliseconds));
+}
+function rawDataBuffer(raw) {
+    if (Array.isArray(raw))
+        return Buffer.concat(raw);
+    return Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+}
+//# sourceMappingURL=cloud-connector.js.map

package/dist/cloud-control-dispatcher.d.ts

@@ -0,0 +1,16 @@
+import { type CloudControlRequestPayload } from "@helyx/control-protocol";
+import { type DatabasePool } from "@helyx/database";
+import type { BotControlHandler, BotControlState } from "./control-server.js";
+export declare class CloudControlDispatcher {
+    #private;
+    private readonly database;
+    private readonly control;
+    constructor(database: DatabasePool, control: BotControlHandler);
+    execute(request: CloudControlRequestPayload, correlationId: string): Promise<unknown>;
+}
+export declare class CloudControlDeniedError extends Error {
+    readonly safeReasonCode: string;
+    constructor(safeReasonCode: string);
+}
+export declare function buildSupportSnapshot(state: BotControlState, dataClasses: string[], guildId: string): unknown;
+//# sourceMappingURL=cloud-control-dispatcher.d.ts.map