@helyx/bot 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## 0.3.0
+
+### Minor Changes
+
+- 0229cb1: Add the versioned Helyx privacy-provider contract, strict write and nullable
+  read boundaries, guarded attribution migrations, bounded hosted and self-hosted
+  provider execution, and the Privacy Centre runtime configuration.
+
+### Patch Changes
+
+- Updated dependencies [0229cb1]
+  - @helyx/module-manifest@0.4.0
+  - @helyx/sdk@0.3.0
+  - @helyx/database@0.3.0
+  - @helyx/platform@0.2.0
+  - @helyx/config@0.3.0
+  - @helyx/core@0.1.5
+  - @helyx/framework@0.1.5
+
+## 0.2.3
+
+### Patch Changes
+
+- Updated dependencies
+  - @helyx/config@0.2.2
+  - @helyx/database@0.2.2
+  - @helyx/platform@0.1.6
+
+## 0.2.2
+
+### Patch Changes
+
+- b0f1932: Cache Discord application owners outside the interaction acknowledgement path
+  so Cloud Connect commands and modals respond reliably during Discord API
+  latency.
+
+  Treat an unreadable local Cloud Connect identity as an actionable recovery
+  state instead of retrying indefinitely. Owners can revoke the old dashboard
+  installation and enrol again with a new one-use code.
+
+  Run bounded cleanup for expired interaction sessions and rate-limit windows.
+
+- Updated dependencies [18265bc]
+  - @helyx/database@0.2.1
+  - @helyx/platform@0.1.5
+
 ## 0.2.1
 
 ### Patch Changes

package/README.md

@@ -16,6 +16,12 @@ Gateway intents are derived from installed event contributions. The bot always r
 
 When `HELYX_BOT_CONTROL_SECRET` is configured, the bot also starts a private authenticated HTTP control server on `HELYX_BOT_CONTROL_PORT`. The dashboard API uses this service to obtain real Discord roles and channels and to apply validated module, configuration and permission changes. Only `/health` is unauthenticated; all `/v1` routes require the shared bearer secret. Keep this endpoint on a private service network and do not assign it a public domain.
 
-Optional Helyx Cloud Connect is a separate outbound management path for self-hosted deployments. It is disabled unless `HELYX_CLOUD_CONNECT_ENABLED=true` and requires a separate local `HELYX_DATA_ENCRYPTION_KEY`. The owner-only `/helyx-cloud` command supports connection-code enrolment, status, credential rotation, disconnection and bounded support consent. The bot never sends its Discord token, database URL or connector private key to Helyx Cloud, and local Discord operation continues when Cloud is unavailable.
+Optional Helyx Cloud Connect is a separate outbound management path for self-hosted deployments. It is disabled unless `HELYX_CLOUD_CONNECT_ENABLED=true` and requires a separate local `HELYX_DATA_ENCRYPTION_KEY`. Preserve that key across every restart and deployment. If it is lost or changed, revoke the old installation in the dashboard and use a new one-use code with `/helyx-cloud connect`; the connector stops retrying until that recovery is completed. The owner-only `/helyx-cloud` command supports connection-code enrolment, status, credential rotation, disconnection and bounded support consent. The bot never sends its Discord token, database URL or connector private key to Helyx Cloud, and local Discord operation continues when Cloud is unavailable.
+
+Privacy providers ship in the same hosted and self-hosted module packages.
+`HELYX_PRIVACY_ENABLED` defaults to `false`; enabling it requires the private
+bot-control endpoint and a separate least-privilege PostgreSQL executor
+credential. The bot refuses Privacy execution when that credential resolves to
+the ordinary runtime database role.
 
 For packaged operation use `helyx start`. `helyx migrate` applies core database migrations without Discord, and read-only `helyx doctor` verifies environment, PostgreSQL migration history, and configured package metadata.

package/dist/cloud-connector.d.ts

@@ -4,7 +4,7 @@ import type { Client } from "discord.js";
 import type { Logger } from "pino";
 import type { ConfiguredModulePackage } from "./modules.js";
 import type { BotControlHandler } from "./control-server.js";
-type ConnectorState = "disabled" | "unpaired" | "connecting" | "online" | "offline" | "revoked" | "stopped";
+type ConnectorState = "disabled" | "unpaired" | "connecting" | "online" | "offline" | "recovery_required" | "revoked" | "stopped";
 export interface CloudConnectorStatus {
     state: ConnectorState;
     installationId?: string;

package/dist/cloud-connector.js

@@ -136,7 +136,8 @@ export class CloudConnectorController {
         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)
+        const recoveringIdentity = existing && !existing.revokedAt && this.#state === "recovery_required";
+        if (existing && !existing.revokedAt && !recoveringIdentity)
             throw new CloudConnectorUserError("This Helyx deployment is already connected");
         if (!this.#dataKey)
             throw new CloudConnectorUserError("HELYX_DATA_ENCRYPTION_KEY is not configured");
@@ -183,6 +184,9 @@ export class CloudConnectorController {
         }
         const exchange = exchangeResponseSchema.parse(payload);
         const encrypted = encryptPrivateKey(keyPair.privateKey, this.#dataKey, exchange.installationId);
+        if (recoveringIdentity && !(await this.#repository.revoke())) {
+            throw new CloudConnectorUserError("The previous local Cloud Connect identity could not be reset");
+        }
         this.#identity = await this.#repository.createIdentity({
             installationId: exchange.installationId,
             credentialId: exchange.credentialId,
@@ -196,7 +200,9 @@ export class CloudConnectorController {
         });
         this.#connectionBlocked = false;
         await this.#repository.appendAudit({
-            action: "installation.enrolled",
+            action: recoveringIdentity
+                ? "installation.recovered"
+                : "installation.enrolled",
             source,
             outcome: "succeeded",
         });
@@ -312,6 +318,16 @@ export class CloudConnectorController {
             catch (error) {
                 if (this.#stopping)
                     break;
+                if (error instanceof CloudConnectorIdentityKeyError) {
+                    this.#connectionBlocked = true;
+                    this.#state = "recovery_required";
+                    this.#lastErrorCode = "local_identity_key_mismatch";
+                    this.input.logger.error({
+                        event: "cloud.identity_recovery_required",
+                        reason: this.#lastErrorCode,
+                    }, "Cloud Connect cannot decrypt its local identity. Revoke the old installation in the dashboard, then use a new one-use code with /helyx-cloud connect");
+                    break;
+                }
                 this.#state = "offline";
                 this.#lastErrorCode = safeConnectorError(error);
                 this.input.logger.warn({
@@ -598,13 +614,24 @@ function encryptPrivateKey(privateKey, dataKey, installationId) {
     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");
+    try {
+        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");
+    }
+    catch {
+        throw new CloudConnectorIdentityKeyError();
+    }
+}
+class CloudConnectorIdentityKeyError extends Error {
+    constructor() {
+        super("The local Cloud Connect identity cannot be decrypted");
+        this.name = "CloudConnectorIdentityKeyError";
+    }
 }
 function connectedMessage(input) {
     const now = new Date();

package/dist/cloud-management-module.d.ts

@@ -1,6 +1,12 @@
 import { type ModuleDefinition } from "@helyx/sdk";
 import type { Client } from "discord.js";
 import type { CloudConnectorController } from "./cloud-connector.js";
+export declare class DeploymentOwnerAuthorizer {
+    #private;
+    constructor(client: Client, configuredOwnerUserIds: readonly string[]);
+    isOwner(userId: string): boolean;
+    refresh(): Promise<void>;
+}
 export declare function createCloudManagementModule(input: {
     connector: CloudConnectorController;
     client: Client;

package/dist/cloud-management-module.js

@@ -1,4 +1,5 @@
 import { defineModule, } from "@helyx/sdk";
+import { Events } from "discord.js";
 import { CloudConnectorUserError, } from "./cloud-connector.js";
 const CONNECT_MODAL_ID = "helyx.cloud.connect";
 const CONNECT_CODE_FIELD_ID = "helyx.cloud.connect.code";
@@ -13,9 +14,41 @@ const DIAGNOSTICS_ENABLED_FIELD_ID = "helyx.cloud.support.diagnostics";
 const VIOLET = 0x7c3aed;
 const SUCCESS = 0x16a34a;
 const DANGER = 0xdc2626;
+const OWNER_REFRESH_INTERVAL_MS = 15 * 60 * 1_000;
+export class DeploymentOwnerAuthorizer {
+    #client;
+    #configuredOwnerUserIds;
+    #applicationOwnerUserIds = new Set();
+    constructor(client, configuredOwnerUserIds) {
+        this.#client = client;
+        this.#configuredOwnerUserIds = new Set(configuredOwnerUserIds);
+    }
+    isOwner(userId) {
+        return (this.#configuredOwnerUserIds.has(userId) ||
+            this.#applicationOwnerUserIds.has(userId));
+    }
+    async refresh() {
+        const application = this.#client.application;
+        if (!application)
+            return;
+        this.#replaceApplicationOwners(application.owner);
+        const refreshed = await application.fetch();
+        this.#replaceApplicationOwners(refreshed.owner);
+    }
+    #replaceApplicationOwners(owner) {
+        this.#applicationOwnerUserIds = !owner
+            ? new Set()
+            : "members" in owner
+                ? new Set(owner.members.keys())
+                : new Set([owner.id]);
+    }
+}
 export function createCloudManagementModule(input) {
+    const ownerAuthorizer = new DeploymentOwnerAuthorizer(input.client, input.configuredOwnerUserIds);
+    let ownerRefreshInterval;
+    let onClientReady;
     const requireOwner = async (context) => {
-        if (await isDeploymentOwner(input.client, context.userId, input.configuredOwnerUserIds))
+        if (ownerAuthorizer.isOwner(context.userId))
             return true;
         await context.reply({
             ephemeral: true,
@@ -411,21 +444,37 @@ export function createCloudManagementModule(input) {
                 },
             ],
         },
-        async start() { },
-        async stop() { },
+        start(context) {
+            const refreshOwners = () => {
+                void ownerAuthorizer.refresh().catch((error) => {
+                    context.logger.warn({
+                        event: "cloud.owner_cache_refresh_failed",
+                        error: safeError(error),
+                    }, "Cloud Connect deployment-owner cache refresh failed");
+                });
+            };
+            onClientReady = () => {
+                refreshOwners();
+                ownerRefreshInterval ??= setInterval(refreshOwners, OWNER_REFRESH_INTERVAL_MS);
+                ownerRefreshInterval.unref();
+            };
+            if (input.client.isReady())
+                onClientReady();
+            else
+                input.client.once(Events.ClientReady, onClientReady);
+            return Promise.resolve();
+        },
+        stop() {
+            if (onClientReady)
+                input.client.off(Events.ClientReady, onClientReady);
+            if (ownerRefreshInterval)
+                clearInterval(ownerRefreshInterval);
+            onClientReady = undefined;
+            ownerRefreshInterval = undefined;
+            return Promise.resolve();
+        },
     });
 }
-async function isDeploymentOwner(client, userId, configuredOwnerUserIds) {
-    if (configuredOwnerUserIds.includes(userId))
-        return true;
-    const application = await client.application?.fetch();
-    const owner = application?.owner;
-    if (!owner)
-        return false;
-    if ("members" in owner)
-        return owner.members.has(userId);
-    return owner.id === userId;
-}
 function statusResponse(status) {
     const labels = {
         disabled: "Disabled by deployment configuration",
@@ -433,6 +482,7 @@ function statusResponse(status) {
         connecting: "Connecting securely",
         online: "Connected",
         offline: "Temporarily offline; local operation continues",
+        recovery_required: "Local identity recovery required; revoke the old dashboard installation, then connect with a new code",
         revoked: "Disconnected and revoked",
         stopped: "Stopped",
     };
@@ -488,4 +538,9 @@ function restrictedPolicy() {
         deniedUserIds: [],
     };
 }
+function safeError(error) {
+    return error instanceof Error
+        ? { name: error.name, message: error.message }
+        : { name: "Error", message: String(error) };
+}
 //# sourceMappingURL=cloud-management-module.js.map

package/dist/control-server.d.ts

@@ -1,5 +1,5 @@
 import { type DatabasePool } from "@helyx/database";
-import { type DashboardActionResult, type MessageResponse, type ModuleDefinition, type ServiceAccess } from "@helyx/sdk";
+import { type DashboardActionResult, type MessageResponse, type ModuleDefinition, type PrivacyCapturePage, type PrivacyErasePage, type PrivacyProviderExecutor, type ServiceAccess } from "@helyx/sdk";
 import { type Client } from "discord.js";
 import { type FastifyInstance } from "fastify";
 interface DashboardPermissionPolicy {
@@ -139,12 +139,54 @@ export interface BotControlHandler {
         actorUserId: string;
         correlationId: string;
     }): Promise<DashboardActionResult>;
+    listPrivacyProviders(): Promise<readonly {
+        id: string;
+        version: number;
+        containsPersonalData: boolean;
+    }[]>;
+    capturePrivacy(input: {
+        providerId: string;
+        providerVersion: number;
+        requestId: string;
+        subjectUserId: string;
+        cutoffAt: Date;
+        cursor?: string;
+    }): Promise<PrivacyCapturePage>;
+    erasePrivacy(input: {
+        providerId: string;
+        providerVersion: number;
+        requestId: string;
+        subjectUserId: string;
+        executeThrough: Date;
+        cursor?: string;
+    }): Promise<PrivacyErasePage>;
 }
 export declare class BotControlService implements BotControlHandler {
     #private;
     private readonly database;
     private readonly resources;
-    constructor(database: DatabasePool, modules: readonly ModuleDefinition[], resources: BotControlGuildResourceDirectory, services: ServiceAccess);
+    constructor(database: DatabasePool, modules: readonly ModuleDefinition[], resources: BotControlGuildResourceDirectory, services: ServiceAccess, privacyExecutor?: PrivacyProviderExecutor);
+    listPrivacyProviders(): Promise<readonly {
+        id: string;
+        version: number;
+        containsPersonalData: boolean;
+    }[]>;
+    capturePrivacy(input: {
+        providerId: string;
+        providerVersion: number;
+        requestId: string;
+        subjectUserId: string;
+        cutoffAt: Date;
+        cursor?: string;
+    }): Promise<PrivacyCapturePage>;
+    erasePrivacy(input: {
+        providerId: string;
+        providerVersion: number;
+        requestId: string;
+        subjectUserId: string;
+        executeThrough: Date;
+        cursor?: string;
+    }): Promise<PrivacyErasePage>;
     getGuildState(guildId: string): Promise<BotControlState>;
     setModuleStatus(input: {
         guildId: string;

package/dist/control-server.js

@@ -96,7 +96,8 @@ export class BotControlService {
     #installations;
     #permissions;
     #services;
-    constructor(database, modules, resources, services) {
+    #privacyProviders;
+    constructor(database, modules, resources, services, privacyExecutor) {
         this.database = database;
         this.resources = resources;
         this.#modules = new Map(modules.map((module) => [module.manifest.id, module]));
@@ -107,6 +108,41 @@ export class BotControlService {
         this.#installations = services.get(HELYX_SERVICE_NAMES.installations);
         this.#permissions = services.get(HELYX_SERVICE_NAMES.permissions);
         this.#services = services;
+        this.#privacyProviders = new Map(privacyExecutor
+            ? modules
+                .filter((module) => module.privacy !== undefined)
+                .map((module) => {
+                const provider = module.privacy.create(privacyExecutor);
+                return [provider.id, provider];
+            })
+            : []);
+    }
+    listPrivacyProviders() {
+        return Promise.resolve([...this.#privacyProviders.values()]
+            .map((provider) => ({
+            id: provider.id,
+            version: provider.version,
+            containsPersonalData: provider.describe().containsPersonalData,
+        }))
+            .sort((left, right) => left.id.localeCompare(right.id)));
+    }
+    capturePrivacy(input) {
+        const provider = this.#privacyProvider(input.providerId, input.providerVersion);
+        return provider.captureAccess({
+            requestId: input.requestId,
+            discordUserId: input.subjectUserId,
+            cutoffAt: input.cutoffAt,
+            ...(input.cursor ? { cursor: input.cursor } : {}),
+        });
+    }
+    erasePrivacy(input) {
+        const provider = this.#privacyProvider(input.providerId, input.providerVersion);
+        return provider.erase({
+            requestId: input.requestId,
+            discordUserId: input.subjectUserId,
+            executeThrough: input.executeThrough,
+            ...(input.cursor ? { cursor: input.cursor } : {}),
+        });
     }
     async getGuildState(guildId) {
         const [resources, installedModules, storedLoggingPolicies] = await Promise.all([
@@ -367,6 +403,14 @@ export class BotControlService {
             throw new BotControlNotFoundError("Module is not dashboard configurable");
         return module;
     }
+    #privacyProvider(providerId, providerVersion) {
+        const provider = this.#privacyProviders.get(providerId);
+        if (!provider)
+            throw new BotControlNotFoundError("Privacy provider is not available");
+        if (provider.version !== providerVersion)
+            throw new BotControlValidationError("Privacy provider version does not match");
+        return provider;
+    }
     async #getPermissionState(guildId, module) {
         const commands = dashboardCommands(module);
         const modulePolicy = await this.#permissions.getPolicy(guildId, module.manifest.id);
@@ -462,6 +506,43 @@ export async function createBotControlServer(input) {
     });
     server.get("/health", () => ({ status: "ok" }));
     server.get("/v1/health", () => ({ status: "ok" }));
+    server.get("/v1/privacy/providers", () => input.service.listPrivacyProviders());
+    server.post("/v1/privacy/capture", async (request) => {
+        const body = z
+            .object({
+            providerId: moduleId,
+            providerVersion: z.number().int().positive(),
+            requestId: z.uuid(),
+            subjectUserId: snowflake,
+            cutoffAt: z.coerce.date(),
+            cursor: z.string().min(1).max(2_048).optional(),
+        })
+            .strict()
+            .parse(request.body);
+        const { cursor, ...value } = body;
+        return input.service.capturePrivacy({
+            ...value,
+            ...(cursor ? { cursor } : {}),
+        });
+    });
+    server.post("/v1/privacy/erase", async (request) => {
+        const body = z
+            .object({
+            providerId: moduleId,
+            providerVersion: z.number().int().positive(),
+            requestId: z.uuid(),
+            subjectUserId: snowflake,
+            executeThrough: z.coerce.date(),
+            cursor: z.string().min(1).max(2_048).optional(),
+        })
+            .strict()
+            .parse(request.body);
+        const { cursor, ...value } = body;
+        return input.service.erasePrivacy({
+            ...value,
+            ...(cursor ? { cursor } : {}),
+        });
+    });
     server.get("/v1/guilds/:guildId/state", async (request) => {
         const { guildId } = z.object({ guildId: snowflake }).parse(request.params);
         return input.service.getGuildState(guildId);

package/dist/index.js

@@ -1,8 +1,8 @@
 import { parseBotEnvironment } from "@helyx/config";
 import { safeError, ServiceRegistry } from "@helyx/core";
-import { checkDatabaseConnection, createDatabasePool, runCoreMigrations, runConfiguredModuleMigrations, } from "@helyx/database";
+import { checkDatabaseConnection, createDatabasePool, InteractionSessionRepository, RateLimitRepository, runCoreMigrations, runConfiguredModuleMigrations, } from "@helyx/database";
 import { createRuntime } from "@helyx/framework";
-import { createPlatformServices } from "@helyx/platform";
+import { createPlatformServices, PostgresPrivacyProviderExecutor, } from "@helyx/platform";
 import { HELYX_SERVICE_NAMES } from "@helyx/sdk";
 import { Client, Events, GatewayIntentBits, Partials } from "discord.js";
 import pino from "pino";
@@ -24,6 +24,7 @@ export { loadConfiguredModulePackages } from "./modules.js";
 export { resolveModulePackageSpecifiers } from "./module-configuration.js";
 export * from "./control-server.js";
 const bootstrapLogger = pino({ base: { component: "bot" } });
+const RETENTION_CLEANUP_INTERVAL_MS = 60 * 60 * 1_000;
 export async function startBot(processEnvironment = process.env) {
     const environment = parseBotEnvironment(processEnvironment);
     bootstrapLogger.level = environment.LOG_LEVEL;
@@ -32,21 +33,61 @@ export async function startBot(processEnvironment = process.env) {
         sslMode: environment.DATABASE_SSL,
         applicationName: "helyx-bot",
     });
+    const privacyDatabase = environment.HELYX_PRIVACY_ENABLED &&
+        environment.HELYX_PRIVACY_EXECUTOR_DATABASE_URL &&
+        environment.HELYX_PRIVACY_EXECUTOR_DATABASE_SSL
+        ? createDatabasePool({
+            connectionString: environment.HELYX_PRIVACY_EXECUTOR_DATABASE_URL,
+            sslMode: environment.HELYX_PRIVACY_EXECUTOR_DATABASE_SSL,
+            applicationName: "helyx-bot-privacy-executor",
+            maxConnections: 2,
+        })
+        : undefined;
     let databaseClosed = false;
+    let retentionCleanupTimer;
     async function closeDatabase() {
         if (databaseClosed)
             return;
         databaseClosed = true;
+        if (privacyDatabase)
+            await privacyDatabase.end();
         await database.end();
     }
     try {
         await checkDatabaseConnection(database);
+        if (privacyDatabase) {
+            await checkDatabaseConnection(privacyDatabase);
+            await assertDistinctDatabaseRoles(database, privacyDatabase);
+        }
         const migrationResult = await runCoreMigrations(database);
         bootstrapLogger.info({
             event: "database.ready",
             appliedMigrations: migrationResult.applied,
             verifiedMigrationCount: migrationResult.verified.length,
         }, "Core database ready");
+        const cleanupExpiredCoreRecords = async () => {
+            const [sessions, rateLimits] = await Promise.all([
+                new InteractionSessionRepository(database).deleteExpired(),
+                new RateLimitRepository(database).deleteExpired(),
+            ]);
+            if (sessions > 0 || rateLimits > 0) {
+                bootstrapLogger.info({
+                    event: "database.retention_cleaned",
+                    interactionSessions: sessions,
+                    rateLimitWindows: rateLimits,
+                }, "Expired core records removed");
+            }
+        };
+        await cleanupExpiredCoreRecords().catch((error) => {
+            bootstrapLogger.warn({ event: "database.retention_cleanup_failed", error: safeError(error) }, "Expired core record cleanup failed");
+        });
+        retentionCleanupTimer = setInterval(() => void cleanupExpiredCoreRecords().catch((error) => {
+            bootstrapLogger.warn({
+                event: "database.retention_cleanup_failed",
+                error: safeError(error),
+            }, "Expired core record cleanup failed");
+        }), RETENTION_CLEANUP_INTERVAL_MS);
+        retentionCleanupTimer.unref();
         const moduleSpecifiers = await resolveModulePackageSpecifiers(environment.HELYX_MODULE_PACKAGES, undefined, undefined, environment.HELYX_MODULE_CATALOGUE_PATH);
         const modulePackages = await loadConfiguredModulePackages(moduleSpecifiers);
         const moduleMigrationResults = await runConfiguredModuleMigrations(database, modulePackages.map(({ definition, packageRoot }) => ({
@@ -115,7 +156,13 @@ export async function startBot(processEnvironment = process.env) {
             prepare: prepareGuilds,
         }, bootstrapLogger, serviceAccess);
         installModuleEvents(client, modules, bootstrapLogger, serviceAccess);
-        const controlService = new BotControlService(database, modules, guildResources, serviceAccess);
+        const controlService = new BotControlService(database, modules, guildResources, serviceAccess, privacyDatabase
+            ? new PostgresPrivacyProviderExecutor({
+                readPool: database,
+                executorPool: privacyDatabase,
+                modules: featureModules,
+            })
+            : undefined);
         cloudConnector.setControlHandler(controlService);
         let controlServer;
         let shuttingDown = false;
@@ -125,6 +172,8 @@ export async function startBot(processEnvironment = process.env) {
             shuttingDown = true;
             process.off("SIGINT", onSigint);
             process.off("SIGTERM", onSigterm);
+            if (retentionCleanupTimer)
+                clearInterval(retentionCleanupTimer);
             bootstrapLogger.info({ event: "bot.shutdown", reason }, "Bot shutdown requested");
             await cloudConnector.stop().catch((error) => {
                 process.exitCode = 1;
@@ -192,12 +241,23 @@ export async function startBot(processEnvironment = process.env) {
         return { shutdown };
     }
     catch (error) {
+        if (retentionCleanupTimer)
+            clearInterval(retentionCleanupTimer);
         await closeDatabase().catch((closeError) => {
             bootstrapLogger.error({ event: "database.close_failed", error: safeError(closeError) }, "Database pool cleanup failed");
         });
         throw error;
     }
 }
+async function assertDistinctDatabaseRoles(runtime, privacy) {
+    const [runtimeIdentity, privacyIdentity] = await Promise.all([
+        runtime.query("SELECT current_user::text AS current_user"),
+        privacy.query("SELECT current_user::text AS current_user"),
+    ]);
+    if (runtimeIdentity.rows[0]?.current_user ===
+        privacyIdentity.rows[0]?.current_user)
+        throw new Error("Privacy executor must use a distinct least-privilege database role");
+}
 function readBotVersion() {
     const metadata = createRequire(import.meta.url)("../package.json");
     if (typeof metadata !== "object" ||

package/dist/modules.js

@@ -66,6 +66,53 @@ export function validateContributionParity(definition) {
     assertSameContributionIds(definition.manifest.contributions.events, executableEvents, "events");
     assertSameContributionIds(definition.manifest.contributions.logs ?? [], executableLogs, "logs");
     assertSameContributionIds(definition.manifest.dashboard?.actions?.map(({ id }) => id) ?? [], executableDashboardActions, "dashboard actions");
+    validatePrivacyParity(definition);
+}
+function validatePrivacyParity(definition) {
+    if (definition.manifest.manifestVersion === "0.1") {
+        if (definition.privacy !== undefined) {
+            throw new Error("Module executable privacy provider requires manifest version 0.2");
+        }
+        return;
+    }
+    if (definition.privacy === undefined) {
+        throw new Error("Module manifest privacy declaration has no executable provider");
+    }
+    if (definition.privacy.providerVersion !==
+        definition.manifest.privacy.providerVersion) {
+        throw new Error("Module manifest privacy provider version does not match executable provider");
+    }
+    for (const collectionDeclaration of definition.manifest.privacy.collections) {
+        const collection = definition.records?.[collectionDeclaration.name];
+        if (collection === undefined) {
+            throw new Error(`Module privacy collection is not declared as a record collection: ${collectionDeclaration.name}`);
+        }
+        const privacyFields = [
+            collectionDeclaration.createdAtField,
+            ...collectionDeclaration.subjectFields.map(({ field }) => field),
+            ...(collectionDeclaration.contentFields ?? []).map(({ field }) => field),
+        ];
+        for (const field of privacyFields) {
+            if (collection.fields[field] === undefined) {
+                throw new Error(`Module privacy field is not declared in record collection ${collectionDeclaration.name}: ${field}`);
+            }
+        }
+    }
+    const unavailable = () => {
+        throw new Error("Privacy provider executor is unavailable during loading");
+    };
+    const executor = {
+        captureAccess: unavailable,
+        erase: unavailable,
+        assessCorrection: unavailable,
+    };
+    const provider = definition.privacy.create(executor);
+    if (provider.id !== definition.manifest.id ||
+        provider.version !== definition.manifest.privacy.providerVersion ||
+        JSON.stringify(provider.describe()) !==
+            JSON.stringify(definition.manifest.privacy)) {
+        throw new Error("Module manifest privacy declaration does not match executable provider");
+    }
 }
 function assertSameContributionIds(declared, executable, label) {
     if (new Set(executable).size !== executable.length) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helyx/bot",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Production Discord runtime for the modular Helyx platform.",
   "keywords": [
     "helyx",
@@ -48,14 +48,14 @@
     "start": "node --env-file-if-exists=../../.env dist/index.js"
   },
   "dependencies": {
-    "@helyx/config": "0.2.1",
+    "@helyx/config": "0.3.0",
     "@helyx/control-protocol": "0.1.1",
-    "@helyx/core": "0.1.4",
-    "@helyx/database": "0.2.0",
-    "@helyx/framework": "0.1.4",
-    "@helyx/module-manifest": "0.3.0",
-    "@helyx/platform": "0.1.4",
-    "@helyx/sdk": "0.2.4",
+    "@helyx/core": "0.1.5",
+    "@helyx/database": "0.3.0",
+    "@helyx/framework": "0.1.5",
+    "@helyx/module-manifest": "0.4.0",
+    "@helyx/platform": "0.2.0",
+    "@helyx/sdk": "0.3.0",
     "discord.js": "14.27.0",
     "fastify": "5.10.0",
     "pino": "10.3.1",