@helyx/module-moderation 1.0.1

package/README.md

@@ -0,0 +1,107 @@
+# @helyx/module-moderation
+
+Moderation lets authorised Discord staff apply accountable member actions, keep durable case history, and recover safely from ambiguous Discord outcomes.
+
+## Availability and deployment
+
+Moderation is a Live module distributed under HSAL-1.0. It supports Hosted and Self-Hosted Helyx installations, requires no third-party credentials, and does not depend on Auto Moderation.
+
+Package installation does not enable the module for a server.
+
+## What it does
+
+- Creates an immutable, server-numbered case before each Discord mutation.
+- Supports warnings, timeouts, timeout removal, kicks, bans, configured-role demotion, unbans, and bounded member history.
+- Records typed action attempts so succeeded, failed, ambiguous, and review-required outcomes can be distinguished without raw Discord errors.
+- Opens optional user-visible private violation threads and keeps their evidence delivery outside the punitive-action transaction.
+- Lets authorised dashboard users reconcile, correct, disassociate, or reveal a private note without rewriting the original action.
+
+Moderation does not classify messages, own keyword rules, or scan content. Auto Moderation can use its closed action provider when both modules are enabled, but each remains independently useful.
+
+## Commands and interactions
+
+| Command path          | Default access | Outcome                                                        |
+| --------------------- | -------------- | -------------------------------------------------------------- |
+| `/mod warn`           | Administrators | Records a warning and optionally attempts a direct message.    |
+| `/mod timeout`        | Administrators | Applies a timeout from one minute to 28 days.                  |
+| `/mod timeout-remove` | Administrators | Removes an active timeout.                                     |
+| `/mod kick`           | Administrators | Removes the member from the server.                            |
+| `/mod ban`            | Administrators | Bans the member with a bounded message-deletion choice.        |
+| `/mod demote`         | Administrators | Removes every eligible configured role in a list of up to ten. |
+| `/mod unban`          | Administrators | Removes a ban by user ID.                                      |
+| `/mod history`        | Administrators | Shows a bounded case history privately.                        |
+
+All commands are enabled-guild, server-only commands with deferred ephemeral acknowledgement and one unique `moderation.*` permission identity per executable path. Staff actions require a trimmed 10–500 character reason. An optional same-server message link stores channel and message IDs only; an optional private note is limited to 1,000 characters.
+
+Kick, ban, demotion, unban, and timeouts longer than 24 hours require a 60-second actor/server/revision-bound confirmation with an explicit cancel path. Before dispatch, Helyx rechecks current module access, staff authority, target state, role hierarchy, and its own Discord permissions.
+
+Violation-thread controls are Kick, Ban, Unmute when currently timed out, and No Further Action. Close and the separately permission-checked Close and delete appear only after one of those staff resolutions succeeds. Close archives and locks the thread; Close and delete additionally permanently deletes that case's Discord thread and messages, not its moderation records. Each control resolves a durable opaque case token, then fresh-authorises the clicking staff member and rechecks the case revision.
+
+## Dashboard configuration
+
+**Case name prefix** controls new violation-thread names. Helyx appends the case number, padded to at least three digits (for example, `moderation-case-001` or `violation-012`), without an operation-hash suffix. Existing thread names are not changed when the prefix is edited. The default applies to older saved configurations automatically.
+
+Settings cover the optional warning direct message, 30–730 day settled-case retention, the violation-thread parent and access role, up to ten moderator notification roles and ten individual notification users, and an opening message. The channel, access role and case prefix share one half-width group; staff role/user notifications occupy the other, with mobile stacking and the opening message below. Enter each staff member's Discord user ID and select **Add user**. Current human server membership is checked before settings are saved; an empty list is valid. Existing configurations default to no individual notifications.
+
+Individual notification users are mentioned as staff and invited to new private threads. **Check channel** previews their minimum parent access; **Configure channel** can apply View Channel, Read Message History and Send Messages in Threads member overwrites, never Manage Threads or moderation powers. Notification selection does not grant Helyx action permissions. Removing a selection stops future notifications but does not remove existing Discord overwrites or membership; review these separately when staff leave. Notification IDs stay in server configuration until removed or erased through the core privacy workflow and are hidden from support disclosure. The fixed core configuration privacy provider covers these associations even when the module is disabled or removed, exports only the requesting user's membership, and preserves other recipients and settings during erasure.
+
+Auto Moderation owns each rule's decision to open a thread; there is no second severity gate in Moderation. Channel and role selections can be saved during setup, and Configure channel can create the access role. Active warning delivery requires a non-empty template; thread delivery requires complete channel/role configuration and an opening message.
+
+The **Cases / offences** resource lists at most 50 cases with exact case/member search, bounded filters, a maximum 31-day date window, stable newest-first cursors, and revision-checked detail. It has no dashboard create, update, delete, or export operation.
+
+- **Reconcile** inspects current Discord state before settling or retrying recovery work.
+- **Correct** creates a linked correction case; it never edits the original action.
+- **Disassociate user** is a one-click authorised action with no reason or confirmation. It clears the subject association and repeat count eligibility while preserving the case number and anonymous action history.
+- **Reveal private note** is separately authorised and audited. Notes remain concealed in ordinary list and detail responses.
+
+Case detail also offers separately permission-checked **Mute**, **Unmute**, **Kick**, **Ban**, **Demote** and **No Further Action**. **Close thread** and **Close and delete** appear only after a successful staff resolution; Close and delete also remains available for an already-closed thread. Punitive dashboard actions require a reason and confirmation; No Further Action and Close need no reason. Dashboard Close and delete requires confirmation but no reason. The initial case facts stay immutable: subsequent staff actions are additional audited attempts, not new offences. Timeout and demotion parameters are persisted by additive migration `0002_staff_attempt_parameters.sql` for restart recovery.
+
+Private notes come from the optional `private-note` input on staff `/mod` commands that offer it; automatic cases normally have no note. The dashboard states whether a concealed note exists.
+
+**Thread message layout** selects Three containers, Single container, Compact incident, Conversation + evidence, or Spoiler evidence. A fictional dashboard preview changes with the selector without performing any moderation action. New threads place configured staff/user mentions, the opening message, rule name, confidence, original channel, escaped original message and staff buttons on one first message. Evidence exceeding Discord's aggregate display limit is delivered in a separate full evidence card without truncation. Refreshing buttons preserves the chosen containers and does not ping members again. Existing threads retain their layout when settings change and are not bulk-reformatted.
+
+**Check channel** is read-only. **Configure channel** requires the checked revision and applies only the previewed minimum role/overwrite changes without removing unrelated Discord configuration.
+
+## Discord requirements
+
+Helyx may need **View Channel**, **Read Message History**, **Send Messages in Threads**, **Create Private Threads**, **Manage Threads**, **Manage Channels**, **Manage Messages**, **Manage Roles**, **Moderate Members**, **Kick Members**, and **Ban Members**. Each operation checks only the permissions it needs at execution time; the manifest union is not proof of current authority and the module never requests Administrator.
+
+Moderation consumes structural channel-delete, channel-update, guild-role-delete, and guild-role-update events for configuration and thread-access reconciliation. It does not require Message Content or a privileged Developer Portal intent.
+
+## Data, privacy and retention
+
+| Record category         | Retained data                                                                                                                                                                |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Cases                   | Case/server identity, nullable subject and actor IDs, immutable action/reason fields, message-reference IDs, repeat metadata, state, safe outcome, revision, and timestamps. |
+| Attempts                | Case, operation and actor IDs, action/reason, typed outcome, safe code, removed-role IDs, and timestamps.                                                                    |
+| Operation receipts      | Content-free idempotency input hash, case/attempt outcome references, and timestamp.                                                                                         |
+| Direct-message receipts | Case/template revision, delivery state, safe code, optional Discord message ID, and timestamps.                                                                              |
+| Thread deliveries       | Case/configuration IDs, private-thread/control message IDs, opaque control token, staged delivery states, fence/retry metadata, safe code, and timestamps.                   |
+
+No offending message body, matched fragment, attachment, embed, or content-derived evidence is written to PostgreSQL, Logging, Audit, metrics, or traces. When transient evidence is available, it is delivered directly to Discord with mentions suppressed; absence never invalidates the case.
+
+The versioned privacy provider covers cases directly and attempts, direct-message receipts, operation receipts, and thread deliveries through their case relationship, including while Moderation is disabled. Subject and actor associations can be detached; reasons, private notes, referenced Discord artefacts, and active safety constraints enter the declared manual-review or retention path. Disassociation is an operational correction, not a privacy erasure or hard delete.
+
+Settled cases use the configured retention window. Active bans and open review cases remain protected; expiry removes attribution or private content without falsifying the anonymous safety history. Discord-owned threads and messages require separately tracked best-effort cleanup.
+
+## Operations and failure behavior
+
+Case number allocation, pending case creation, and the first immutable attempt commit atomically before Discord mutation. Exact replay returns the original outcome; reused operation identities with different canonical input fail closed. Ambiguous Discord results are never blindly replayed: a bounded reconciliation inspects current state and either settles the case or leaves it for review.
+
+Warning direct messages and violation-thread delivery are best effort and cannot roll back an applied moderation action. Thread creation, evidence, member addition, notification, control rendering, close, and access cleanup have typed retry/review states. Scheduled action reconciliation, thread delivery, and thread-access reconciliation use durable platform tasks with bounded attempts and `requires_review` exhaustion.
+
+Close and delete requires Manage Threads and verifies the exact server, parent, private-thread identity and bot creator before deletion. An already-missing bound thread is idempotent completion. Failed or uncertain deletion is not reported as success: its durable recovery marker remains available for **Reconcile case**. Automatic recovery inspects state without blindly repeating deletion; an authorised dashboard reconciliation can retry the same audited deletion after fresh staff, configuration and binding checks. Records, case numbers and immutable action history are retained.
+
+Disabling Moderation stops new commands, automated provider requests, and behavioural tasks without deleting cases. Health is unhealthy while stopped or when a required runtime service is missing, and degraded when durable recovery needs staff attention.
+
+Before release, run formatting, lint, type checks, focused tests, module contracts, packed lifecycle checks, and the repository release dry run. Live Discord behaviour remains unclaimed until the credentialed smoke matrix passes.
+
+## Documentation and support
+
+- [Moderation overview](https://docs.helyx.gg/modules/moderation/)
+- [Moderation permissions](https://docs.helyx.gg/modules/moderation/permissions/)
+- [Moderation troubleshooting](https://docs.helyx.gg/modules/moderation/troubleshooting/)
+- [Moderation FAQ](https://docs.helyx.gg/modules/moderation/faq/)
+- [Report an issue](https://github.com/ZyC0R3/Helyx/issues)
+
+Publication, licensing, release-state promotion, push, deployment, and production changes require explicit owner approval.

package/dist/action-support.d.ts

@@ -0,0 +1,48 @@
+import { type AuditService, type AtomicModerationCaseService, type InteractionSessionService, type ModalCapableInteractionContext, type ModerationActionAttemptTerminalOutcome, type ModerationEnforcementAction, type ModerationMemberEnforcementService, type ServiceAccess } from "@helyx/sdk";
+import type { ModerationDispatchAction, ModerationStaffDraft } from "./service.js";
+export declare function staffAction(draft: ModerationStaffDraft): ModerationDispatchAction;
+export declare function claimModerationConfirmation(context: ModalCapableInteractionContext, session: NonNullable<Awaited<ReturnType<InteractionSessionService["get"]>>>, purpose: string): Promise<void>;
+export declare function moderationPermissionForAction(action: ModerationStaffDraft["action"]): ModerationStaffDraft["permissionId"];
+export declare function atomicCases(services: ServiceAccess): AtomicModerationCaseService;
+export declare function moderationEnforcement(services: ServiceAccess): ModerationMemberEnforcementService;
+export declare function moderationEnabled(services: ServiceAccess, guildId: string): Promise<boolean>;
+export declare function protectedViolationRoleIds(services: ServiceAccess, guildId: string): Promise<readonly string[]>;
+export declare function moderationConfiguration(services: ServiceAccess, guildId: string): Promise<import("./configuration.js").ModerationConfiguration>;
+export declare function moderationAuditReason(caseNumber: number, reason: string): string;
+export declare function moderationApplied(outcome: ModerationActionAttemptTerminalOutcome): boolean;
+export declare function moderationRetentionExpiresAt(occurredAt: Date, retentionDays: number): Date;
+export declare function scheduleActionReconciliation(services: ServiceAccess, input: {
+    guildId: string;
+    caseId: string;
+    attemptId: string;
+    operationKey: string;
+}): Promise<void>;
+export declare function sendWarningDirectMessage(services: ServiceAccess, input: {
+    guildId: string;
+    caseId: string;
+    caseNumber: number;
+    subjectUserId: string;
+}): Promise<void>;
+export declare function emitModerationActionLog(services: ServiceAccess, input: {
+    guildId: string;
+    action: ModerationStaffDraft["action"];
+    caseId: string;
+    caseNumber: number;
+    subjectUserId: string;
+    actorUserId: string;
+    durationSeconds?: number;
+    operationKey: string;
+}): Promise<void>;
+export declare function emitAutomaticModerationActionLog(services: ServiceAccess, input: {
+    guildId: string;
+    action: ModerationEnforcementAction;
+    caseId: string;
+    caseNumber: number;
+    subjectUserId: string;
+    operationKey: string;
+}): Promise<void>;
+export declare function appendModerationAudit(services: ServiceAccess, input: Parameters<AuditService["append"]>[0]): Promise<{
+    eventId: bigint;
+    createdAt: Date;
+}>;
+//# sourceMappingURL=action-support.d.ts.map

package/dist/action-support.js

@@ -0,0 +1,201 @@
+import { randomUUID } from "node:crypto";
+import { HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { DEFAULT_MODERATION_CONFIGURATION, parseModerationConfiguration, } from "./configuration.js";
+import { MODERATION_COMMAND_IDS, MODERATION_MODULE_ID, MODERATION_TASK_KINDS, } from "./constants.js";
+import { ModerationRepository } from "./repository.js";
+export function staffAction(draft) {
+    if (draft.action === "warn")
+        return { type: "warn" };
+    if (draft.action === "timeout")
+        return {
+            type: "timeout",
+            durationSeconds: draft.requestedDurationSeconds,
+        };
+    if (draft.action === "kick")
+        return { type: "kick" };
+    if (draft.action === "ban")
+        return {
+            type: "ban",
+            deleteMessageSeconds: draft.deleteMessageSeconds ?? 0,
+        };
+    if (draft.action === "demote")
+        return { type: "demote", roleIds: draft.demoteRoleIds ?? [] };
+    if (draft.action === "timeout_remove")
+        return { type: "timeout_remove" };
+    if (draft.action === "unban")
+        return { type: "unban" };
+    return { type: "case_only" };
+}
+export async function claimModerationConfirmation(context, session, purpose) {
+    await context.services
+        .get(HELYX_SERVICE_NAMES.sessions)
+        .advance({
+        sessionId: session.sessionId,
+        guildId: session.guildId,
+        userId: session.userId,
+        purpose,
+        expectedVersion: session.version,
+        expectedStep: 0,
+        nextStep: 1,
+        state: { ...session.state, step: 1 },
+    });
+}
+export function moderationPermissionForAction(action) {
+    return action === "timeout_remove"
+        ? MODERATION_COMMAND_IDS.timeoutRemove
+        : MODERATION_COMMAND_IDS[action];
+}
+export function atomicCases(services) {
+    return services.get(HELYX_SERVICE_NAMES.atomicModerationCases);
+}
+export function moderationEnforcement(services) {
+    return services.get(HELYX_SERVICE_NAMES.memberEnforcement);
+}
+export async function moderationEnabled(services, guildId) {
+    return services.has(HELYX_SERVICE_NAMES.installations)
+        ? services
+            .get(HELYX_SERVICE_NAMES.installations)
+            .isModuleEnabled(guildId, MODERATION_MODULE_ID)
+        : false;
+}
+export async function protectedViolationRoleIds(services, guildId) {
+    if (!services.has(HELYX_SERVICE_NAMES.configuration))
+        return [];
+    const current = await services
+        .get(HELYX_SERVICE_NAMES.configuration)
+        .get(guildId, MODERATION_MODULE_ID);
+    const configuration = current
+        ? parseModerationConfiguration(current.value)
+        : DEFAULT_MODERATION_CONFIGURATION;
+    return configuration.violationAccessRoleId
+        ? [configuration.violationAccessRoleId]
+        : [];
+}
+export async function moderationConfiguration(services, guildId) {
+    if (!services.has(HELYX_SERVICE_NAMES.configuration))
+        return DEFAULT_MODERATION_CONFIGURATION;
+    const current = await services
+        .get(HELYX_SERVICE_NAMES.configuration)
+        .get(guildId, MODERATION_MODULE_ID);
+    return current
+        ? parseModerationConfiguration(current.value)
+        : DEFAULT_MODERATION_CONFIGURATION;
+}
+export function moderationAuditReason(caseNumber, reason) {
+    return `[Helyx case ${caseNumber}] ${reason}`.slice(0, 512);
+}
+export function moderationApplied(outcome) {
+    return outcome === "succeeded" || outcome === "already_applied";
+}
+export function moderationRetentionExpiresAt(occurredAt, retentionDays) {
+    return new Date(occurredAt.getTime() + retentionDays * 86_400_000);
+}
+export async function scheduleActionReconciliation(services, input) {
+    if (!services.has(HELYX_SERVICE_NAMES.scheduledTasks))
+        return;
+    await services
+        .get(HELYX_SERVICE_NAMES.scheduledTasks)
+        .schedule({
+        moduleId: MODERATION_MODULE_ID,
+        taskKind: MODERATION_TASK_KINDS.actionReconcile,
+        guildId: input.guildId,
+        idempotencyKey: `${input.operationKey}:reconcile`,
+        payload: { caseId: input.caseId, attemptId: input.attemptId },
+        scheduledFor: new Date(Date.now() + 2_000),
+    });
+}
+export async function sendWarningDirectMessage(services, input) {
+    const configuration = await moderationConfiguration(services, input.guildId);
+    if (!configuration.warningDirectMessageEnabled)
+        return;
+    const attemptedAt = new Date();
+    let delivery = { outcome: "failed" };
+    if (services.has(HELYX_SERVICE_NAMES.discordMessages)) {
+        const content = configuration.warningDirectMessageTemplate
+            .replaceAll("{{caseNumber}}", String(input.caseNumber))
+            .replaceAll("{{serverName}}", "this server");
+        delivery = await services
+            .get(HELYX_SERVICE_NAMES.discordMessages)
+            .sendDirect({
+            userId: input.subjectUserId,
+            response: {
+                componentsV2: { text: [{ content, markdown: false }] },
+                allowedRoleMentionIds: [],
+                allowedUserMentionIds: [],
+                suppressEmbeds: true,
+            },
+        })
+            .catch(() => ({ outcome: "failed" }));
+    }
+    const now = new Date();
+    await new ModerationRepository(services)
+        .upsertDmReceipt({
+        receiptId: randomUUID(),
+        guildId: input.guildId,
+        caseId: input.caseId,
+        templateRevision: 1,
+        deliveryState: delivery.outcome === "sent" ? "succeeded" : "failed",
+        safeCode: delivery.outcome === "sent" ? null : `dm_${delivery.outcome}`,
+        messageId: delivery.outcome === "sent" ? delivery.messageId : null,
+        attemptedAt,
+        createdAt: now,
+        updatedAt: now,
+    })
+        .catch(() => undefined);
+}
+export async function emitModerationActionLog(services, input) {
+    await emitLog(services, input, input.action);
+}
+export async function emitAutomaticModerationActionLog(services, input) {
+    await emitLog(services, input, input.action.type);
+}
+async function emitLog(services, input, action) {
+    const eventId = actionLogEvent(action);
+    if (!eventId || !services.has(HELYX_SERVICE_NAMES.moduleLogging))
+        return;
+    await services
+        .get(HELYX_SERVICE_NAMES.moduleLogging)
+        .emit({
+        guildId: input.guildId,
+        moduleId: MODERATION_MODULE_ID,
+        eventId,
+        summary: `Moderation case ${input.caseNumber} was applied.`,
+        details: [
+            { label: "Case", value: input.caseId },
+            { label: "Member", value: input.subjectUserId },
+            { label: "Action", value: action },
+            ...(input.actorUserId
+                ? [{ label: "Actor", value: input.actorUserId }]
+                : []),
+            ...(input.durationSeconds
+                ? [
+                    {
+                        label: "Duration seconds",
+                        value: String(input.durationSeconds),
+                    },
+                ]
+                : []),
+        ],
+        idempotencyKey: `${input.operationKey}:log`,
+    })
+        .catch(() => undefined);
+}
+function actionLogEvent(action) {
+    return {
+        warn: "member-warned",
+        timeout: "member-timed-out",
+        timeout_remove: "member-unmuted",
+        kick: "member-kicked",
+        ban: "member-banned",
+        demote: "member-demoted",
+        unban: "member-unbanned",
+        delete_message: null,
+        case_only: null,
+    }[action];
+}
+export function appendModerationAudit(services, input) {
+    return services
+        .get(HELYX_SERVICE_NAMES.audit)
+        .append({ ...input, moduleId: MODERATION_MODULE_ID });
+}
+//# sourceMappingURL=action-support.js.map

package/dist/case-actions.d.ts

@@ -0,0 +1,9 @@
+import { type ManagedResourceContext } from "@helyx/sdk";
+import { type StoredModerationCase } from "./repository.js";
+import type { ModerationService } from "./service.js";
+export declare class ModerationCaseActions {
+    private readonly moderation;
+    constructor(moderation: ModerationService);
+    execute(context: ManagedResourceContext, moderationCase: StoredModerationCase, actionId: string, value: Readonly<Record<string, unknown>>): Promise<void>;
+}
+//# sourceMappingURL=case-actions.d.ts.map