@helyx/bot 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # 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

package/README.md

@@ -18,4 +18,10 @@ When `HELYX_BOT_CONTROL_SECRET` is configured, the bot also starts a private aut
 
 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/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

@@ -2,7 +2,7 @@ import { parseBotEnvironment } from "@helyx/config";
 import { safeError, ServiceRegistry } from "@helyx/core";
 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";
@@ -33,16 +33,32 @@ 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",
@@ -140,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;
@@ -227,6 +249,15 @@ export async function startBot(processEnvironment = process.env) {
         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.2",
+  "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.1",
-    "@helyx/framework": "0.1.4",
-    "@helyx/module-manifest": "0.3.0",
-    "@helyx/platform": "0.1.5",
-    "@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",