@helyx/bot 1.1.0 → 1.2.0

package/dist/transient-violation-evidence.js

@@ -0,0 +1,132 @@
+import { VIOLATION_THREAD_LIMITS, } from "@helyx/sdk";
+import { randomUUID } from "node:crypto";
+const MAX_EVIDENCE_ENTRIES = 10_000;
+const MAX_EVIDENCE_TOTAL_BYTES = 16 * 1_024 * 1_024;
+/**
+ * Bot-private, memory-only hand-off for message content. The opaque reference is
+ * safe to cross module boundaries; the content and this vault are not.
+ */
+export class TransientViolationEvidenceStore {
+    now;
+    createKey;
+    #records = new Map();
+    #maximumEntries;
+    #maximumTotalBytes;
+    #totalBytes = 0;
+    constructor(now = Date.now, createKey = randomUUID, limits = {}) {
+        this.now = now;
+        this.createKey = createKey;
+        this.#maximumEntries = boundedPositiveInteger(limits.entries ?? MAX_EVIDENCE_ENTRIES, MAX_EVIDENCE_ENTRIES, "entry limit");
+        this.#maximumTotalBytes = boundedPositiveInteger(limits.totalBytes ?? MAX_EVIDENCE_TOTAL_BYTES, MAX_EVIDENCE_TOTAL_BYTES, "byte limit");
+    }
+    capture(input) {
+        validateIdentity(input.guildId);
+        validateIdentity(input.channelId);
+        if (input.messageId !== null)
+            validateIdentity(input.messageId);
+        validateIdentity(input.authorUserId);
+        validateBinding(input.sourceEventId, "source event");
+        if (input.source === "enhanced_scanner")
+            validateBinding(input.configurationRevision, "configuration revision");
+        const contentBytes = Buffer.byteLength(input.content, "utf8");
+        if (input.content.length < 1 ||
+            input.content.length > VIOLATION_THREAD_LIMITS.evidenceCharacters ||
+            contentBytes > VIOLATION_THREAD_LIMITS.evidenceUtf8Bytes)
+            return null;
+        this.#pruneExpired();
+        if (this.#records.size >= this.#maximumEntries ||
+            this.#totalBytes + contentBytes > this.#maximumTotalBytes)
+            return null;
+        const key = this.createKey();
+        if (this.#records.has(key))
+            return null;
+        const base = {
+            key,
+            sourceEventId: input.sourceEventId,
+            guildId: input.guildId,
+            channelId: input.channelId,
+            messageId: input.messageId,
+            authorUserId: input.authorUserId,
+        };
+        const reference = Object.freeze(input.source === "enhanced_scanner"
+            ? {
+                ...base,
+                source: input.source,
+                configurationRevision: input.configurationRevision,
+            }
+            : { ...base, source: input.source });
+        this.#records.set(reference.key, {
+            reference,
+            content: input.content,
+            bytes: contentBytes,
+            expiresAt: this.now() + VIOLATION_THREAD_LIMITS.evidenceLifetimeSeconds * 1_000,
+        });
+        this.#totalBytes += contentBytes;
+        return reference;
+    }
+    consume(reference) {
+        const result = this.read(reference);
+        if (result.outcome === "available")
+            this.discard(reference);
+        return result;
+    }
+    /** Read without discarding so a failed Discord send can be retried. */
+    read(reference) {
+        const record = this.#records.get(reference.key);
+        if (!record)
+            return { outcome: "unavailable" };
+        if (record.expiresAt <= this.now()) {
+            this.#delete(reference.key, record);
+            return { outcome: "unavailable" };
+        }
+        if (!sameReference(record.reference, reference))
+            return { outcome: "mismatch" };
+        return { outcome: "available", content: record.content };
+    }
+    discard(reference) {
+        const record = this.#records.get(reference.key);
+        if (record && sameReference(record.reference, reference))
+            this.#delete(reference.key, record);
+    }
+    get size() {
+        this.#pruneExpired();
+        return this.#records.size;
+    }
+    #pruneExpired() {
+        const now = this.now();
+        for (const [key, record] of this.#records)
+            if (record.expiresAt <= now)
+                this.#delete(key, record);
+    }
+    #delete(key, record) {
+        if (!this.#records.delete(key))
+            return;
+        this.#totalBytes = Math.max(0, this.#totalBytes - record.bytes);
+    }
+}
+function boundedPositiveInteger(value, maximum, subject) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > maximum)
+        throw new RangeError(`Violation evidence ${subject} is invalid`);
+    return value;
+}
+function sameReference(left, right) {
+    return (left.source === right.source &&
+        left.key === right.key &&
+        left.sourceEventId === right.sourceEventId &&
+        left.guildId === right.guildId &&
+        left.channelId === right.channelId &&
+        left.messageId === right.messageId &&
+        left.authorUserId === right.authorUserId &&
+        (left.source !== "enhanced_scanner" ||
+            (right.source === "enhanced_scanner" &&
+                left.configurationRevision === right.configurationRevision)));
+}
+function validateIdentity(value) {
+    if (!/^\d{17,20}$/u.test(value))
+        throw new Error("Violation evidence identity is invalid");
+}
+function validateBinding(value, subject) {
+    if (value.trim().length < 1 || value.length > 160 || /[\r\n]/u.test(value))
+        throw new Error(`Violation evidence ${subject} is invalid`);
+}
+//# sourceMappingURL=transient-violation-evidence.js.map

package/documentation/README.md

@@ -20,6 +20,8 @@ and module guides.
 - [Build an independent module](modules/building-a-module.md)
 - [Test a module](modules/testing-a-module.md)
 - [Prepare a module package](modules/publishing-a-module.md)
+- [Operate the Moderation module](modules/moderation.md)
+- [Operate the Auto Moderation module](modules/auto-moderation.md)
 
 The complete working example is published separately as
 `@helyx/module-example`. It is intentionally independent: module-specific

package/documentation/examples/.env.example

@@ -1,11 +1,23 @@
 # REQUIRED — EDIT THESE VALUES
 
+HELYX_RUNTIME_PROFILE=self-hosted
+HELYX_DEPLOYMENT_ENVIRONMENT=self-hosted
+
 # Discord
 DISCORD_TOKEN=replace-me
 DISCORD_CLIENT_ID=12345678901234567
 # Explicit privileged gateway opt-in. Keep false unless a reviewed loaded module
 # requires message content and it is enabled in the Discord developer portal.
 HELYX_MESSAGE_CONTENT_ENABLED=false
+# Enhanced Auto Moderation stays inside this bot process. One worker is the
+# recommended default; increase only after measuring local CPU and memory.
+HELYX_AUTOMOD_EMBEDDED_WORKERS=1
+# Optional conservative queue overrides (hard ceilings: 5000 items, 64 MiB,
+# 100 items per server). Defaults are used when these remain commented.
+# HELYX_AUTOMOD_EMBEDDED_QUEUE_ITEMS=5000
+# HELYX_AUTOMOD_EMBEDDED_QUEUE_BYTES=67108864
+# HELYX_AUTOMOD_EMBEDDED_QUEUE_ITEMS_PER_GUILD=100
+# HELYX_AUTOMOD_EMBEDDED_REFRESH_SECONDS=300
 # Enable only when member inspection modules are loaded and the Discord Server
 # Members Intent is enabled in the Discord developer portal.
 HELYX_GUILD_MEMBERS_ENABLED=false

package/documentation/guides/self-hosting.md

@@ -23,6 +23,21 @@ project is the source of truth for its pinned public packages and module
 catalogue. Do not copy source trees from the Helyx repository into an
 installation.
 
+### Enhanced Auto Moderation resources
+
+Enhanced Auto Moderation remains inside the existing bot process and uses the
+installation's existing PostgreSQL database. It does not require Helyx Ecko,
+Redis, another bot, another database, a public endpoint or a Premium heartbeat.
+Standard mode starts no scanning worker.
+
+Enhanced mode requires the privileged Message Content intent in both the Discord
+developer portal and `HELYX_MESSAGE_CONTENT_ENABLED=true`. Start with the default
+single worker and measure process CPU, memory, queue depth and module health on
+the real host before considering two to four workers. Queue overflow, stale
+configuration or repeated worker failure falls back to Discord-native Standard
+coverage; it does not make unsafe actions on delayed content. Use `npm run doctor`
+after environment changes and the dashboard module-health view for diagnosis.
+
 Every implemented catalogue entry carries a manifest-backed deployment label
 and credential-risk label. A planned entry without a canonical v0.4 manifest
 is explicitly `unclassified`; that label makes no promise about its future
@@ -47,7 +62,8 @@ downloaded manifest.
 
 - Run `npm run doctor` after configuration or package changes.
 - Watch process health, database capacity, command deployment errors, and module
-  health.
+  health. When Enhanced Auto Moderation is active, also watch CPU, memory,
+  scanner queue pressure and Standard-fallback guidance.
 - Back up both PostgreSQL and the environment or key material needed to decrypt
   its records.
 - Test recovery in a disposable environment.

package/documentation/modules/auto-moderation.md

@@ -0,0 +1,51 @@
+# Auto Moderation module
+
+Auto Moderation is an unpublished Testing module that manages Helyx-owned Discord Auto Moderation rules and optional Enhanced matching. It supports Hosted and Self-Hosted Helyx, but version `1.0.0` must be explicitly included in a reviewed test composition and is not available from the public npm catalogue.
+
+## Supported Self-Hosted shape
+
+Use the same Helyx bot process and PostgreSQL database as the rest of the installation. Standard mode starts no content-scanning worker. Enhanced starts a bounded worker pool inside the bot process. Self-hosters do not deploy Helyx Ecko, Redis, a second bot connection or any Helyx-hosted scanner.
+
+The matching engine is the deliberate `@helyx/module-automod/engine` package export. Hosted Ecko and the embedded worker use the same versioned engine and result contract; module code remains free of Discord.js, database, network and environment access.
+
+## Discord setup
+
+Grant **Manage Server** so Helyx can inspect and manage only its mapped rules. Grant **Moderate Members** when a native rule uses Discord timeout. Standard consumes Discord's Auto Moderation configuration and execution Gateway events and does not require Message Content.
+
+Enhanced requires Message Content. In the Discord Developer Portal for the Self-Hosted application, enable the **Message Content Intent**, set `HELYX_MESSAGE_CONTENT_ENABLED=true` in the supported environment file and restart the bot. Keep it false when only Standard is used. Do not expose the bot token or use Message Content for unrelated modules.
+
+## Standard and Enhanced
+
+Only one mode is effective at a time. Standard delegates content evaluation to Discord native rules. Enhanced also evaluates eligible Gateway message observations using deterministic exact, phrase, wildcard, reviewed normalisation and explicitly opted-in bounded fuzzy matching. Custom regex remains on Discord's native Rust engine.
+
+Self-Hosted Enhanced is locally included and never requires a Helyx Premium slot. Hosted Enhanced is a Premium feature inside the free module and uses private Ecko. Losing Enhanced capability falls back to Standard without deleting saved rules or thresholds.
+
+## Resource profile and backpressure
+
+Enhanced compiles immutable rule snapshots into bounded process memory. Terms, phrases, allow lists and observation text disappear on invalidation, eviction and stop. The worker pool preserves per-server ordering, limits queue size, applies a circuit breaker after worker failure and rejects overflow into effective Standard fallback. It performs no REST fetch for missing message content.
+
+Size the bot for actual Enhanced traffic and begin with Balanced confidence. Watch event-loop delay, queue depth, rejected work, scan latency and memory. A degraded worker must not prevent Discord-native rules from enforcing Standard coverage.
+
+## Data and privacy
+
+PostgreSQL stores logical rules, Discord mapping/fingerprint, structural action receipts, durable enforcement claims and anonymous daily counts. It never stores matched content, matched terms, bodies, attachments, embeds or transient evidence. Native receipts expire after 90 days; settled claim/count history is bounded to 365 days.
+
+Discord native alerts and optional Moderation violation-thread evidence are Discord-owned content. Restrict those channels separately. Logging, Audit, metrics and traces must remain content-free.
+
+## Health and recovery
+
+External Discord edits mark a rule Drifted; deletion marks it Missing. Adopt or restore only after review, and never silently recreate a missing rule. Disabling the module disables mapped owned rules while retaining definitions and privacy/recovery records.
+
+The module is unhealthy when required records, configuration, installation, Discord Auto Moderation or authorisation services are unavailable. Optional Moderation or Logging failure degrades only that integration. Enhanced worker failure reports degraded effective mode and preserves Standard coverage.
+
+## Verify a test installation
+
+1. Confirm the private Testing module is present in the test catalogue.
+2. Apply migrations with the migration role and start the bot with Standard.
+3. Publish one fictional native rule and verify block/alert plus a content-free receipt.
+4. Enable Message Content, switch to Enhanced and test one obfuscated phrase plus one safe near-match.
+5. Restart the bot and confirm snapshots rebuild without retained message content.
+6. Exercise worker failure or overflow and confirm effective Standard fallback.
+7. If Moderation is installed, prove duplicate native and Enhanced results create one claim, ordinal, case and action.
+
+For the current Hosted customer workflow, see <https://docs.helyx.gg/modules/auto-moderation/>.

package/documentation/modules/moderation.md

@@ -0,0 +1,42 @@
+# Moderation module
+
+Moderation is an unpublished Testing module for accountable Discord staff actions. It supports Hosted and Self-Hosted Helyx, but version `1.0.0` must be explicitly included in a reviewed test composition and is not available from the public npm catalogue.
+
+## Supported Self-Hosted shape
+
+Run the normal Helyx bot process and PostgreSQL only. Moderation needs no Redis, scanner service, Cloud Connect or Helyx-hosted dependency. Install its migrations through the normal reviewed module lifecycle; never run migration credentials in the bot process.
+
+## Discord setup
+
+Grant only the permissions used by your enabled workflows: **Moderate Members**, **Kick Members**, **Ban Members**, **Manage Roles**, and the channel/thread permissions needed for violation conversations. Helyx does not need Administrator, Message Content or a privileged intent for Moderation.
+
+For violation threads, choose a normal text channel and a manageable low-privilege access role. Use the dashboard's **Check channel** action before **Configure channel**. The role grants parent visibility; private-thread membership grants case access. Thread visibility never grants staff action controls.
+
+## Commands and authority
+
+Moderation contributes `/mod warn`, `/mod timeout`, `/mod timeout-remove`, `/mod kick`, `/mod ban`, `/mod demote`, `/mod unban` and `/mod history`. Each path has a separate Helyx permission and defaults to Administrators. Configure policies through the dashboard or the paired Cloud Connect dashboard; there is no command that bypasses module policy.
+
+Kick, ban, demotion, unban and timeouts longer than 24 hours require an actor-bound 60-second confirmation. Every action rechecks current target state, moderator hierarchy, bot hierarchy and Discord permission immediately before dispatch.
+
+## Data and recovery
+
+The module creates a pending numbered case and immutable attempt before changing Discord. An ambiguous outcome enters Review and must be reconciled from current Discord state; do not blindly repeat the action. Warning DMs and violation-thread delivery are secondary and cannot roll back a successful case.
+
+PostgreSQL stores case, action, identity, safe outcome and Discord-reference metadata. It does not store offending message bodies. Transient evidence can be copied directly to a Discord-owned private thread with mentions disabled and is never persisted or queued.
+
+Settled retention is configurable from 30 to 730 days. Dashboard disassociation clears the subject and future repeat-count association while preserving an anonymous tombstone. It is not hard deletion or Privacy Service erasure.
+
+## Health and shutdown
+
+Health is unhealthy while the module is stopped or a required platform boundary is missing. Durable review or delivery recovery can make it degraded without invalidating already applied cases. Disabling stops new commands and automation while retaining cases, privacy visibility and protected recovery state. Existing Discord punishments and threads remain.
+
+## Verify a test installation
+
+1. Confirm the module is private, Testing and explicitly selected in the test catalogue.
+2. Apply the current database baseline and module migrations with the migration role.
+3. Start the bot and verify module health.
+4. Test a warning, a confirmed high-impact action, a hierarchy rejection and a case history read with fictional accounts.
+5. Exercise channel inspection, one private violation thread, staff-control denial for the affected user and safe Close visibility.
+6. Restart the bot and reconcile one deliberately interrupted test outcome.
+
+For the current Hosted customer workflow, see <https://docs.helyx.gg/modules/moderation/>.

package/documentation/reference/environment.md

@@ -16,12 +16,23 @@ also replace the example PostgreSQL password consistently in `PGPASSWORD` and
 
 ## Safe defaults
 
+The generated Self-Hosted environment fixes `HELYX_RUNTIME_PROFILE` to
+`self-hosted`. Keep that value unchanged: it selects the embedded scanning
+boundary and prevents Hosted-only Helyx Ecko calls from entering the local
+runtime.
+
 Privileged Discord intents, privacy execution, hosted OAuth, status reporting,
 guild command writes, and advanced sharding stay disabled until their complete
 requirements are deliberately configured. An empty variable still counts as a
 configured value in many environments, so leave unused optional lines
 commented.
 
+`HELYX_AUTOMOD_EMBEDDED_WORKERS` controls only the in-process Self-Hosted
+Enhanced Auto Moderation pool. Keep the default of one unless local measurement
+justifies a value from two through four. Its queue settings may be lowered but
+cannot exceed 5,000 items, 64 MiB total or 100 queued items per server. These
+settings never create or contact a Hosted Ecko service.
+
 `HELYX_CLOUD_CONNECT_ENABLED=true` makes an installation ready to be paired; it
 does not pair the installation by itself. Keep official endpoint overrides
 commented unless Helyx support directs otherwise.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helyx/bot",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Production Discord runtime for the modular Helyx platform.",
   "keywords": [
     "helyx",
@@ -51,14 +51,14 @@
   },
   "dependencies": {
     "@helyx/config": ">=1.0.0 <2.0.0",
-    "@helyx/control-protocol": ">=0.4.0 <0.5.0",
+    "@helyx/control-protocol": ">=0.5.0 <0.6.0",
     "@helyx/core": ">=0.1.0 <0.2.0",
     "@helyx/database": ">=2.0.0 <3.0.0",
     "@helyx/framework": ">=0.1.0 <0.2.0",
-    "@helyx/module-manifest": ">=0.9.0 <0.10.0",
+    "@helyx/module-manifest": ">=0.10.0 <0.11.0",
     "@helyx/platform": ">=1.0.0 <2.0.0",
-    "@helyx/sdk": ">=0.11.0 <0.12.0",
-    "@helyx/status-client": ">=0.1.0 <0.2.0",
+    "@helyx/sdk": ">=0.12.0 <0.13.0",
+    "@helyx/status-client": ">=0.2.0 <0.3.0",
     "@helyx/verification-contracts": ">=0.3.0 <0.4.0",
     "discord.js": "14.27.0",
     "fastify": "5.12.3",
@@ -68,6 +68,18 @@
     "ws": "8.21.1",
     "zod": "4.4.3"
   },
+  "peerDependencies": {
+    "@helyx/module-automod": ">=1.0.0 <2.0.0",
+    "@helyx/module-moderation": ">=1.0.0 <2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@helyx/module-automod": {
+      "optional": true
+    },
+    "@helyx/module-moderation": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/ws": "8.18.1"
   }