@helyx/bot 1.1.0 → 1.2.0

package/dist/moderation-case-disassociation.js

@@ -0,0 +1,83 @@
+import { AUTOMOD_CASE_LINK_CONTRACT_VERSION, AUTOMOD_CASE_LINK_PROVIDER_ID, HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+const AUTOMOD_MODULE_ID = "helyx.automod";
+/** Adds Auto Moderation unlinking after the authoritative case transition. */
+export function decorateModerationCaseDisassociation(input) {
+    const provider = caseLinkProvider(input.modules);
+    if (!provider)
+        return input.service;
+    const service = input.service;
+    return {
+        createPendingCase: (request) => service.createPendingCase(request),
+        createConfirmedAutoModerationOffenceCase: (request) => service.createConfirmedAutoModerationOffenceCase(request),
+        createAdditionalPendingAttempt: (request) => service.createAdditionalPendingAttempt(request),
+        createCorrectionCase: (request) => service.createCorrectionCase(request),
+        settleActionAttempt: (request) => service.settleActionAttempt(request),
+        recordObservedAction: (request) => service.recordObservedAction(request),
+        listReconciliationCandidates: (request) => service.listReconciliationCandidates(request),
+        async disassociateCase(request) {
+            const result = await service.disassociateCase(request);
+            if (result.outcome !== "disassociated" &&
+                result.outcome !== "already_disassociated")
+                return result;
+            // Deliberately pass no former subject identity across the module boundary.
+            await provider.disassociateCase({ services: input.services }, {
+                guildId: request.guildId,
+                moderationCaseId: result.caseId,
+                occurredAt: request.occurredAt,
+            });
+            if (input.services.has(HELYX_SERVICE_NAMES.memberRoleGrants)) {
+                const grants = input.services.get(HELYX_SERVICE_NAMES.memberRoleGrants);
+                let cursor;
+                do {
+                    const released = await grants.releaseOwned({
+                        sourceModuleId: "helyx.moderation",
+                        selector: {
+                            kind: "scope",
+                            guildId: request.guildId,
+                            sourceScopeId: result.caseId,
+                        },
+                        batchKey: `${request.operationKey}:release-access`,
+                        occurredAt: request.occurredAt,
+                        reason: "Moderation case disassociated",
+                        limit: 100,
+                        ...(cursor ? { cursor } : {}),
+                    });
+                    cursor = released.nextCursor;
+                } while (cursor);
+            }
+            return result;
+        },
+        executeRetention: (request) => service.executeRetention(request),
+    };
+}
+function caseLinkProvider(modules) {
+    const providers = modules.flatMap((module) => module.autoModerationCaseLinkProvider
+        ? [
+            {
+                moduleId: module.manifest.id,
+                provider: module.autoModerationCaseLinkProvider,
+            },
+        ]
+        : []);
+    if (providers.length > 1)
+        throw new Error("Auto Moderation case-link ownership is ambiguous");
+    const registered = providers[0];
+    if (!registered)
+        return null;
+    if (registered.moduleId !== AUTOMOD_MODULE_ID ||
+        registered.provider.providerId !== AUTOMOD_CASE_LINK_PROVIDER_ID ||
+        registered.provider.contractVersion !== AUTOMOD_CASE_LINK_CONTRACT_VERSION)
+        throw new Error("Auto Moderation case-link registration is invalid");
+    return registered.provider;
+}
+export function installModerationCaseDisassociation(input) {
+    const current = input.services.get(HELYX_SERVICE_NAMES.atomicModerationCases);
+    if (!current)
+        return;
+    input.services.set(HELYX_SERVICE_NAMES.atomicModerationCases, decorateModerationCaseDisassociation({
+        modules: input.modules,
+        services: input.serviceAccess,
+        service: current,
+    }));
+}
+//# sourceMappingURL=moderation-case-disassociation.js.map

package/dist/moderation-platform-services.d.ts

@@ -0,0 +1,27 @@
+import type { ModuleDefinition, ServiceAccess } from "@helyx/sdk";
+import type { Client } from "discord.js";
+import { BotAutoModerationScannerRegistry } from "./auto-moderation-scanner-registry.js";
+import { EmbeddedAutoModerationScanner } from "./embedded-auto-moderation-scanner.js";
+import { TransientViolationEvidenceStore } from "./transient-violation-evidence.js";
+export interface ModerationPlatformServiceHandle {
+    evidenceStore: TransientViolationEvidenceStore;
+    scannerRegistry: BotAutoModerationScannerRegistry;
+    embeddedScanner?: EmbeddedAutoModerationScanner;
+}
+/** Installs bounded moderation adapters; no module or Ecko lifecycle starts here. */
+export declare function installModerationPlatformServices(input: {
+    services: Map<string, unknown>;
+    serviceAccess: ServiceAccess;
+    client: Client;
+    modules: readonly ModuleDefinition[];
+    runtimeProfile: "hosted" | "self-hosted";
+    deploymentEnvironment?: string;
+    embedded?: {
+        workers: number;
+        maximumItems: number;
+        maximumBytes: number;
+        maximumItemsPerGuild: number;
+        refreshIntervalMs: number;
+    };
+}): ModerationPlatformServiceHandle;
+//# sourceMappingURL=moderation-platform-services.d.ts.map

package/dist/moderation-platform-services.js

@@ -0,0 +1,47 @@
+import { HELYX_SERVICE_NAMES } from "@helyx/sdk";
+import { BotAutoModerationScannerRegistry } from "./auto-moderation-scanner-registry.js";
+import { DiscordAutoModerationAdapter } from "./discord-auto-moderation-service.js";
+import { DiscordMessageEnforcementAdapter } from "./discord-message-enforcement-service.js";
+import { DiscordViolationEvidenceDeliveryAdapter, DiscordViolationThreadAdapter, } from "./discord-violation-thread-service.js";
+import { BotModerationActionRegistry } from "./moderation-action-registry.js";
+import { EmbeddedAutoModerationScanner } from "./embedded-auto-moderation-scanner.js";
+import { TransientViolationEvidenceStore } from "./transient-violation-evidence.js";
+import { installModerationCaseDisassociation } from "./moderation-case-disassociation.js";
+/** Installs bounded moderation adapters; no module or Ecko lifecycle starts here. */
+export function installModerationPlatformServices(input) {
+    const evidenceStore = new TransientViolationEvidenceStore();
+    installModerationCaseDisassociation({
+        modules: input.modules,
+        services: input.services,
+        serviceAccess: input.serviceAccess,
+    });
+    const scannerRegistry = new BotAutoModerationScannerRegistry(input.modules, input.serviceAccess, input.runtimeProfile, evidenceStore, input.deploymentEnvironment);
+    const evidenceDelivery = new DiscordViolationEvidenceDeliveryAdapter(input.client, evidenceStore);
+    input.services.set(HELYX_SERVICE_NAMES.discordAutoModeration, new DiscordAutoModerationAdapter(input.client));
+    input.services.set(HELYX_SERVICE_NAMES.messageEnforcement, new DiscordMessageEnforcementAdapter(input.client));
+    input.services.set(HELYX_SERVICE_NAMES.violationThreads, new DiscordViolationThreadAdapter(input.client));
+    input.services.set(HELYX_SERVICE_NAMES.moderationActions, new BotModerationActionRegistry(input.modules, input.serviceAccess, evidenceDelivery));
+    input.services.set(HELYX_SERVICE_NAMES.automodScannerProvider, scannerRegistry);
+    const embeddedScanner = input.runtimeProfile === "self-hosted"
+        ? new EmbeddedAutoModerationScanner({
+            registry: scannerRegistry,
+            evidenceStore,
+            environment: input.deploymentEnvironment ?? "self-hosted",
+            poolLimits: {
+                workers: input.embedded?.workers ?? 1,
+                maximumItems: input.embedded?.maximumItems ?? 5_000,
+                maximumBytes: input.embedded?.maximumBytes ?? 64 * 1_024 * 1_024,
+                maximumItemsPerGuild: input.embedded?.maximumItemsPerGuild ?? 100,
+            },
+            refreshIntervalMs: input.embedded?.refreshIntervalMs ?? 300_000,
+        })
+        : undefined;
+    if (embeddedScanner)
+        input.services.set(HELYX_SERVICE_NAMES.automodScannerObservations, embeddedScanner);
+    return {
+        evidenceStore,
+        scannerRegistry,
+        ...(embeddedScanner ? { embeddedScanner } : {}),
+    };
+}
+//# sourceMappingURL=moderation-platform-services.js.map

package/dist/modules.d.ts

@@ -12,6 +12,10 @@ export interface ConfiguredModulePackage extends LoadedDefinition {
 }
 export declare const secureRandomSelectionWorkerKeyName = "HELYX_INTERNAL_SECURE_RANDOM_SELECTION_KEY";
 interface PlatformServiceEnvironment extends Pick<BotEnvironment, "HELYX_DATA_ENCRYPTION_KEY"> {
+    HELYX_RUNTIME_PROFILE?: BotEnvironment["HELYX_RUNTIME_PROFILE"];
+    HELYX_MESSAGE_CONTENT_ENABLED?: boolean;
+    HELYX_GUILD_MEMBERS_ENABLED?: boolean;
+    HELYX_ECKO_TRANSPORT_SECRET?: string | undefined;
     DISCORD_CLIENT_ID?: string;
     HELYX_DASHBOARD_PUBLIC_URL?: string;
     HELYX_INTERNAL_SECURE_RANDOM_SELECTION_KEY?: string;
@@ -22,6 +26,8 @@ export declare function platformServiceOptions(environment: PlatformServiceEnvir
     secureRandomSelectionKey?: Uint8Array;
     inviteFingerprintKey?: Uint8Array;
     dashboardBaseUrl?: string;
+    runtimeProfile: "hosted" | "self-hosted";
+    availableDiscordCapabilities: readonly ("guild-members" | "message-content")[];
 };
 export declare function deriveInviteFingerprintKey(selectionKey: Uint8Array): Uint8Array;
 export declare function loadConfiguredModules(specifiers: readonly string[], importer?: ModuleImporter): Promise<ModuleDefinition[]>;

package/dist/modules.js

@@ -31,12 +31,28 @@ export function platformServiceOptions(environment, modules) {
     const urls = environment.HELYX_DASHBOARD_PUBLIC_URL
         ? { dashboardBaseUrl: environment.HELYX_DASHBOARD_PUBLIC_URL }
         : {};
+    const runtimeProfile = environment.HELYX_RUNTIME_PROFILE ?? "hosted";
+    const featureAccess = {
+        runtimeProfile,
+        availableDiscordCapabilities: [
+            ...(environment.HELYX_GUILD_MEMBERS_ENABLED
+                ? ["guild-members"]
+                : []),
+            ...((runtimeProfile === "hosted" &&
+                environment.HELYX_ECKO_TRANSPORT_SECRET !== undefined) ||
+                (runtimeProfile === "self-hosted" &&
+                    environment.HELYX_MESSAGE_CONTENT_ENABLED)
+                ? ["message-content"]
+                : []),
+        ],
+    };
     const internalSelectionKey = environment.HELYX_INTERNAL_SECURE_RANDOM_SELECTION_KEY;
     if (internalSelectionKey) {
         const selectionKey = decodeSecureRandomSelectionKey(internalSelectionKey, secureRandomSelectionWorkerKeyName);
         return {
             ...application,
             ...urls,
+            ...featureAccess,
             secureRandomSelectionKey: selectionKey,
             inviteFingerprintKey: deriveInviteFingerprintKey(selectionKey),
         };
@@ -48,12 +64,13 @@ export function platformServiceOptions(environment, modules) {
         if (keyRequired) {
             throw new Error("HELYX_DATA_ENCRYPTION_KEY is required when Giveaways or Invite Tracking is loaded");
         }
-        return { ...application, ...urls };
+        return { ...application, ...urls, ...featureAccess };
     }
     const selectionKey = deriveSecureRandomSelectionKey(encodedKey);
     return {
         ...application,
         ...urls,
+        ...featureAccess,
         secureRandomSelectionKey: selectionKey,
         inviteFingerprintKey: deriveInviteFingerprintKey(selectionKey),
     };
@@ -162,6 +179,11 @@ export function validateContributionParity(definition) {
     }
     const executableEvents = [
         ...(definition.events?.privilegedMessageCreate ?? []),
+        ...(definition.events?.privilegedMessageUpdate ?? []),
+        ...(definition.events?.discordAutoModerationRuleCreate ?? []),
+        ...(definition.events?.discordAutoModerationRuleUpdate ?? []),
+        ...(definition.events?.discordAutoModerationRuleDelete ?? []),
+        ...(definition.events?.discordAutoModerationActionExecution ?? []),
         ...(definition.events?.guildMessageCreate ?? []),
         ...(definition.events?.guildVoiceSession ?? []),
         ...(definition.events?.messageReactionAdd ?? []),
@@ -180,6 +202,20 @@ export function validateContributionParity(definition) {
         ...(definition.events?.guildEmojiDelete ?? []),
         ...(definition.events?.guildEmojiUpdate ?? []),
     ].map(({ type }) => type);
+    const manifestFeatureIds = new Set(definition.manifest.manifestVersion === "0.5"
+        ? definition.manifest.features.map(({ id }) => id)
+        : []);
+    for (const contribution of [
+        ...(definition.events?.privilegedMessageCreate ?? []),
+        ...(definition.events?.privilegedMessageUpdate ?? []),
+    ]) {
+        if (contribution.featureId &&
+            !manifestFeatureIds.has(contribution.featureId))
+            throw new Error(`Module ${definition.manifest.id} message event binds undeclared feature ${contribution.featureId}`);
+        if (definition.manifest.id === "helyx.automod" &&
+            contribution.featureId !== "automod.enhanced-scanning")
+            throw new Error("Auto Moderation privileged message events require the Enhanced feature binding");
+    }
     const executableLogs = (definition.logging?.events ?? []).map(({ id }) => id);
     const executableSchedulableActions = [
         ...new Set((definition.schedulableActions ?? []).map(({ id }) => id)),
@@ -192,9 +228,16 @@ export function validateContributionParity(definition) {
     assertSameContributionIds(definition.manifest.contributions.schedulableActions ?? [], executableSchedulableActions, "schedulable actions");
     assertSameContributionIds(definition.manifest.dashboard?.actions?.map(({ id }) => id) ?? [], executableDashboardActions, "dashboard actions");
     assertSameContributionIds(definition.manifest.dashboard?.resources?.map(({ id }) => id) ?? [], executableManagedResources, "dashboard resources");
-    if (definition.manifest.manifestVersion === "0.4") {
+    if (definition.manifest.manifestVersion === "0.4" ||
+        definition.manifest.manifestVersion === "0.5") {
         assertCommandPathContract(definition);
     }
+    if (definition.manifest.manifestVersion === "0.5") {
+        assertSameContributionIds(definition.manifest.permissionOperations.map(({ id }) => id), (definition.permissionOperations ?? []).map(({ id }) => id), "permission operations");
+    }
+    else if ((definition.permissionOperations?.length ?? 0) > 0) {
+        throw new Error("Module permission operations require manifest version 0.5 or later");
+    }
     validatePrivacyParity(definition);
 }
 function validatePrivacyParity(definition) {
@@ -219,6 +262,7 @@ function validatePrivacyParity(definition) {
         const privacyFields = [
             collectionDeclaration.createdAtField,
             ...collectionDeclaration.subjectFields.map(({ field }) => field),
+            ...(collectionDeclaration.subjectRelationships ?? []).map(({ localField }) => localField),
             ...(collectionDeclaration.contentFields ?? []).map(({ field }) => field),
         ];
         for (const field of privacyFields) {
@@ -226,16 +270,34 @@ function validatePrivacyParity(definition) {
                 throw new Error(`Module privacy field is not declared in record collection ${collectionDeclaration.name}: ${field}`);
             }
         }
+        for (const relationship of collectionDeclaration.subjectRelationships ??
+            []) {
+            const target = definition.records?.[relationship.targetCollection];
+            const localField = collection.fields[relationship.localField];
+            const targetField = target?.fields[relationship.targetField];
+            if (target === undefined || targetField === undefined) {
+                throw new Error(`Module privacy relationship target is not declared: ${relationship.targetCollection}.${relationship.targetField}`);
+            }
+            if (localField?.type !== targetField.type) {
+                throw new Error(`Module privacy relationship fields have incompatible types: ${collectionDeclaration.name}.${relationship.localField}`);
+            }
+        }
     }
     const subjectFieldsByCollection = new Map(definition.manifest.privacy.collections.map((collection) => [
         collection.name,
         new Set(collection.subjectFields.map(({ field }) => field)),
     ]));
+    const relationshipFieldsByCollection = new Map(definition.manifest.privacy.collections.map((collection) => [
+        collection.name,
+        new Set((collection.subjectRelationships ?? []).map(({ localField }) => localField)),
+    ]));
     for (const [collectionName, collection] of Object.entries(definition.records ?? {})) {
         const declaredSubjectFields = subjectFieldsByCollection.get(collectionName);
+        const relationshipFields = relationshipFieldsByCollection.get(collectionName);
         for (const field of Object.keys(collection.fields)) {
             if (isDiscordIdentityRecordField(field) &&
-                !declaredSubjectFields?.has(field)) {
+                !declaredSubjectFields?.has(field) &&
+                !relationshipFields?.has(field)) {
                 throw new Error(`Module record field containing a Discord identity is not declared for privacy access: ${collectionName}.${field}`);
             }
         }

package/dist/privileged-message-metadata-cache.d.ts

@@ -0,0 +1,35 @@
+import type { PrivilegedMessageSourceContext } from "@helyx/sdk";
+/**
+ * Process-local, content-free metadata used only to resolve partial message edits.
+ * Map insertion order provides deterministic least-recently-used eviction.
+ */
+export declare class PrivilegedMessageMetadataCache {
+    #private;
+    private readonly maximumEntries;
+    private readonly ttlMs;
+    private readonly now;
+    constructor(maximumEntries?: number, ttlMs?: number, now?: () => number);
+    remember(input: {
+        guildId: string;
+        channelId: string;
+        messageId: string;
+        source: Extract<PrivilegedMessageSourceContext, {
+            resolved: true;
+        }>;
+    }): void;
+    resolve(input: {
+        guildId: string;
+        channelId: string;
+        messageId: string;
+    }): Extract<PrivilegedMessageSourceContext, {
+        resolved: true;
+    }> | null;
+    delete(input: {
+        guildId: string;
+        channelId: string;
+        messageId: string;
+    }): void;
+    clear(): void;
+    size(): number;
+}
+//# sourceMappingURL=privileged-message-metadata-cache.d.ts.map

package/dist/privileged-message-metadata-cache.js

@@ -0,0 +1,70 @@
+const DEFAULT_MAX_ENTRIES = 10_000;
+const DEFAULT_TTL_MS = 10 * 60 * 1_000;
+/**
+ * Process-local, content-free metadata used only to resolve partial message edits.
+ * Map insertion order provides deterministic least-recently-used eviction.
+ */
+export class PrivilegedMessageMetadataCache {
+    maximumEntries;
+    ttlMs;
+    now;
+    #entries = new Map();
+    constructor(maximumEntries = DEFAULT_MAX_ENTRIES, ttlMs = DEFAULT_TTL_MS, now = Date.now) {
+        this.maximumEntries = maximumEntries;
+        this.ttlMs = ttlMs;
+        this.now = now;
+        if (!Number.isInteger(maximumEntries) || maximumEntries < 1)
+            throw new Error("Privileged message cache size is invalid");
+        if (!Number.isInteger(ttlMs) || ttlMs < 1)
+            throw new Error("Privileged message cache TTL is invalid");
+    }
+    remember(input) {
+        const key = cacheKey(input);
+        this.#entries.delete(key);
+        this.#entries.set(key, {
+            expiresAt: this.now() + this.ttlMs,
+            source: input.source,
+        });
+        this.#evictExpiredAndOverflow();
+    }
+    resolve(input) {
+        const key = cacheKey(input);
+        const entry = this.#entries.get(key);
+        if (!entry)
+            return null;
+        if (entry.expiresAt <= this.now()) {
+            this.#entries.delete(key);
+            return null;
+        }
+        this.#entries.delete(key);
+        this.#entries.set(key, entry);
+        return entry.source;
+    }
+    delete(input) {
+        this.#entries.delete(cacheKey(input));
+    }
+    clear() {
+        this.#entries.clear();
+    }
+    size() {
+        return this.#entries.size;
+    }
+    #evictExpiredAndOverflow() {
+        const now = this.now();
+        for (const [key, entry] of this.#entries) {
+            if (entry.expiresAt > now)
+                continue;
+            this.#entries.delete(key);
+        }
+        while (this.#entries.size > this.maximumEntries) {
+            const oldest = this.#entries.keys().next().value;
+            if (!oldest)
+                break;
+            this.#entries.delete(oldest);
+        }
+    }
+}
+function cacheKey(input) {
+    return `${input.guildId}:${input.channelId}:${input.messageId}`;
+}
+//# sourceMappingURL=privileged-message-metadata-cache.js.map

package/dist/scheduled-task-runner.js

@@ -1,5 +1,5 @@
 import { CORE_RECORD_RETENTION_TASK, MODULE_ACTIVATION_RECOVERY_TASK, ScheduledTaskRepository, } from "@helyx/database";
-import { getModuleScheduledTaskContribution, HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { getModuleScheduledTaskContribution, HELYX_SERVICE_NAMES, MODERATION_CASE_RETENTION_TASK, } from "@helyx/sdk";
 import { randomUUID } from "node:crypto";
 import { canAccessModule } from "./premium-access.js";
 const DEFAULT_POLL_INTERVAL_MS = 1_000;
@@ -296,6 +296,7 @@ export function createScheduledTaskRunner(input) {
                 taskVersion: contribution.version,
                 delivery: contribution.delivery,
             }))),
+            MODERATION_CASE_RETENTION_TASK,
         ],
         ...(input.workerId === undefined ? {} : { workerId: input.workerId }),
     });
@@ -310,6 +311,28 @@ export function schedulerOperationalHealth(health) {
 export function createLocalScheduledTaskRoute(input) {
     const modules = new Map(input.modules.map((module) => [module.manifest.id, module]));
     return async (task, signal) => {
+        if (task.moduleId === MODERATION_CASE_RETENTION_TASK.moduleId &&
+            task.taskKind === MODERATION_CASE_RETENTION_TASK.taskKind &&
+            task.taskVersion === MODERATION_CASE_RETENTION_TASK.taskVersion &&
+            task.delivery === MODERATION_CASE_RETENTION_TASK.delivery) {
+            const { guildId, caseId } = task.payload;
+            if (Object.keys(task.payload).length !== 2 ||
+                typeof guildId !== "string" ||
+                !/^\d{17,20}$/u.test(guildId) ||
+                typeof caseId !== "string" ||
+                !/^[0-9a-f]{8}-[0-9a-f-]{27}$/iu.test(caseId))
+                return { outcome: "requires_review", safeCode: "payload_invalid" };
+            const result = await input.services
+                .get(HELYX_SERVICE_NAMES.atomicModerationCases)
+                .executeRetention({ guildId, caseId, occurredAt: new Date() });
+            return result.outcome === "deferred"
+                ? {
+                    outcome: "deferred",
+                    delayMs: Math.max(100, Math.min(86_400_000, result.deferredUntil.getTime() - Date.now())),
+                    safeCode: `retention_${result.code}`,
+                }
+                : { outcome: "completed" };
+        }
         if (task.moduleId === CORE_RECORD_RETENTION_TASK.moduleId &&
             task.taskKind === CORE_RECORD_RETENTION_TASK.taskKind &&
             task.taskVersion === CORE_RECORD_RETENTION_TASK.taskVersion &&