@helyx/module-moderation 1.0.1

package/dist/case-actions.js

@@ -0,0 +1,311 @@
+import { AUTOMOD_TIMEOUT_SECONDS, DashboardActionValidationError, HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { appendModerationAudit, emitModerationActionLog, moderationConfiguration, moderationRetentionExpiresAt, scheduleActionReconciliation, } from "./action-support.js";
+import { closeThreadControl, currentThreadActor } from "./components.js";
+import { validateDemotionRoleIds, validateReason } from "./domain.js";
+import { ModerationRepository, } from "./repository.js";
+import { closeViolationThread, releaseViolationThreadAccess, } from "./thread-controls.js";
+import { markAmbiguousThreadControl } from "./thread-reconciliation.js";
+import { MODERATION_CASE_ACTIONS } from "./constants.js";
+export class ModerationCaseActions {
+    moderation;
+    constructor(moderation) {
+        this.moderation = moderation;
+    }
+    async execute(context, moderationCase, actionId, value) {
+        if (!Object.hasOwn(MODERATION_CASE_ACTIONS, actionId))
+            fail("Unknown moderation action.");
+        const action = actionId;
+        const closing = action === "close-thread" || action === "close-and-delete-thread";
+        if (moderationCase.state !== "applied" ||
+            !moderationCase.subjectUserId ||
+            moderationCase.disassociatedAt)
+            fail("This case is not available for a moderation action.");
+        const actorContext = {
+            serverId: context.guildId,
+            userId: context.actor.userId,
+            services: context.services,
+        };
+        const repository = new ModerationRepository(context.services);
+        let bindingRevision = moderationCase.revision;
+        let bindingState = "applied";
+        let deletionConfiguration = null;
+        const revalidate = async () => {
+            if (!(await currentThreadActor(actorContext, MODERATION_CASE_ACTIONS[action])))
+                return false;
+            const current = await repository.findCase(context.guildId, moderationCase.caseId);
+            const binding = deletionConfiguration === null
+                ? null
+                : await repository.findThreadDelivery(context.guildId, moderationCase.caseId);
+            return (current?.revision === bindingRevision &&
+                current.state === bindingState &&
+                current.subjectUserId === moderationCase.subjectUserId &&
+                !current.disassociatedAt &&
+                (deletionConfiguration === null ||
+                    (binding?.threadId === delivery?.threadId &&
+                        binding?.parentChannelId === delivery?.parentChannelId &&
+                        binding?.controlToken === delivery?.controlToken &&
+                        binding?.accessRoleId === delivery?.accessRoleId)) &&
+                (deletionConfiguration === null ||
+                    JSON.stringify(await moderationConfiguration(context.services, context.guildId)) === deletionConfiguration));
+        };
+        if (!(await revalidate()))
+            fail("You no longer have access to this moderation action.");
+        const delivery = await repository.findThreadDelivery(context.guildId, moderationCase.caseId);
+        if (delivery &&
+            (delivery.caseRevision !== moderationCase.revision ||
+                (delivery.resolutionState === "closed" &&
+                    action !== "close-and-delete-thread")))
+            fail("This case or its thread changed. Refresh the case before acting.");
+        if (delivery?.resolutionState === "resolved" && !closing)
+            fail("This case already has a staff resolution.");
+        if ((closing || action === "no-further-action") && !delivery)
+            fail("This case has no violation thread to resolve or close.");
+        if (closing && delivery?.resolutionState === "awaiting_staff")
+            fail("Resolve the case before closing its thread.");
+        const active = delivery?.parentChannelId &&
+            delivery.accessRoleId &&
+            delivery.controlToken
+            ? {
+                ...delivery,
+                parentChannelId: delivery.parentChannelId,
+                accessRoleId: delivery.accessRoleId,
+                controlToken: delivery.controlToken,
+            }
+            : null;
+        if (delivery && !active)
+            fail("This violation thread is no longer available.");
+        const dispatch = actionInput(action, value);
+        const reason = action === "no-further-action" || closing
+            ? `Staff selected ${action.replaceAll("-", " ")} in the dashboard.`
+            : validatedReason(value.reason);
+        const operationKey = `dashboard:${context.correlationId}:${moderationCase.caseId}:${action}`;
+        const configuration = await moderationConfiguration(context.services, context.guildId);
+        if (action === "close-and-delete-thread")
+            deletionConfiguration = JSON.stringify(configuration);
+        const atomic = context.services.get(HELYX_SERVICE_NAMES.atomicModerationCases);
+        const attempt = await atomic.createAdditionalPendingAttempt({
+            guildId: context.guildId,
+            caseId: moderationCase.caseId,
+            expectedRevision: moderationCase.revision,
+            purpose: "thread_control",
+            action: dispatch.type,
+            actorUserId: context.actor.userId,
+            reason,
+            operationKey,
+            occurredAt: new Date(),
+            ...(dispatch.type === "timeout"
+                ? { requestedDurationSeconds: dispatch.durationSeconds }
+                : {}),
+            ...(dispatch.type === "demote"
+                ? { demoteRoleIds: dispatch.roleIds }
+                : {}),
+        });
+        if (attempt.outcome === "rejected")
+            fail("This moderation case changed. Refresh it before acting.");
+        if (attempt.outcome === "replayed") {
+            if (attempt.attemptOutcome === "pending")
+                fail("This moderation action is already in progress. Refresh the case shortly.");
+            return;
+        }
+        bindingRevision = attempt.revision;
+        bindingState = "pending";
+        let effect;
+        let auditConfirmed = false;
+        try {
+            await appendModerationAudit(context.services, {
+                guildId: context.guildId,
+                actorUserId: context.actor.userId,
+                action: "moderation.case.staff-action",
+                source: "dashboard",
+                correlationId: context.correlationId,
+                idempotencyKey: `${operationKey}:audit`,
+                targetType: "moderation_case",
+                targetId: moderationCase.caseId,
+                metadata: { action, caseNumber: moderationCase.caseNumber },
+            });
+            auditConfirmed = true;
+            if (active)
+                await markAmbiguousThreadControl(repository, active, closing
+                    ? action === "close-and-delete-thread"
+                        ? "close_delete"
+                        : "close"
+                    : action === "kick" || action === "ban" || action === "unmute"
+                        ? action
+                        : "resolve", attempt.attemptId);
+            effect = !(await revalidate())
+                ? { outcome: "missing_permission", safeCode: "actor_access_changed" }
+                : closing && active
+                    ? await closeViolationThread(context.services, active, moderationCase.subjectUserId, revalidate, action === "close-and-delete-thread")
+                    : await this.moderation.dispatchAction(context.services, {
+                        guildId: context.guildId,
+                        subjectUserId: moderationCase.subjectUserId,
+                        actorUserId: context.actor.userId,
+                        action: dispatch,
+                        reason: `[Helyx case ${moderationCase.caseNumber}] ${reason}`.slice(0, 512),
+                        operationKey: `${operationKey}:discord`,
+                        revalidate,
+                        protectedRoleIds: [
+                            ...new Set([
+                                configuration.violationAccessRoleId,
+                                active?.accessRoleId,
+                            ].filter((id) => Boolean(id))),
+                        ],
+                    });
+        }
+        catch {
+            effect = auditConfirmed
+                ? { outcome: "ambiguous", safeCode: "staff_action_unconfirmed" }
+                : { outcome: "failed", safeCode: "audit_unavailable" };
+        }
+        const occurredAt = new Date();
+        if (auditConfirmed &&
+            action === "close-and-delete-thread" &&
+            !["succeeded", "already_applied"].includes(effect.outcome))
+            effect = { outcome: "ambiguous", safeCode: "thread_delete_unconfirmed" };
+        const settled = await atomic
+            .settleActionAttempt({
+            guildId: context.guildId,
+            caseId: moderationCase.caseId,
+            attemptId: attempt.attemptId,
+            expectedRevision: attempt.revision,
+            outcome: effect.outcome,
+            operationKey: `${operationKey}:settle`,
+            occurredAt,
+            retentionExpiresAt: moderationRetentionExpiresAt(occurredAt, configuration.caseRetentionDays),
+            ...(effect.safeCode ? { safeCode: effect.safeCode } : {}),
+            ...(effect.removedRoleIds
+                ? { removedRoleIds: effect.removedRoleIds }
+                : {}),
+        })
+            .catch(() => null);
+        if (!settled ||
+            settled.outcome === "rejected" ||
+            effect.outcome === "ambiguous") {
+            await scheduleActionReconciliation(context.services, {
+                guildId: context.guildId,
+                caseId: moderationCase.caseId,
+                attemptId: attempt.attemptId,
+                operationKey,
+            }).catch(() => undefined);
+            fail("The action was not confirmed and needs dashboard review.");
+        }
+        bindingRevision = settled.revision;
+        bindingState = "applied";
+        if (!["succeeded", "already_applied"].includes(effect.outcome)) {
+            if (active) {
+                const current = await repository.findThreadDelivery(context.guildId, moderationCase.caseId);
+                if (current)
+                    await repository.updateThreadDelivery({
+                        deliveryId: current.deliveryId,
+                        expectedFenceToken: current.fenceToken,
+                        values: {
+                            caseRevision: settled.revision,
+                            safeCode: null,
+                            retryAt: null,
+                            updatedAt: new Date(),
+                        },
+                    });
+            }
+            fail("The moderation action was not applied. Check permissions, membership and role hierarchy.");
+        }
+        if (dispatch.type !== "case_only" && dispatch.type !== "delete_message")
+            await emitModerationActionLog(context.services, {
+                guildId: context.guildId,
+                caseId: moderationCase.caseId,
+                caseNumber: moderationCase.caseNumber,
+                subjectUserId: moderationCase.subjectUserId,
+                actorUserId: context.actor.userId,
+                action: dispatch.type,
+                operationKey,
+                ...(dispatch.type === "timeout"
+                    ? { durationSeconds: dispatch.durationSeconds }
+                    : {}),
+            });
+        if (!active)
+            return;
+        await scheduleActionReconciliation(context.services, {
+            guildId: context.guildId,
+            caseId: moderationCase.caseId,
+            attemptId: attempt.attemptId,
+            operationKey,
+        });
+        if ((action === "kick" || action === "ban") &&
+            (await releaseViolationThreadAccess(context.services, active, moderationCase.subjectUserId, action)) === "review_required")
+            fail("The action succeeded, but thread access needs dashboard review.");
+        const currentDelivery = await repository.findThreadDelivery(context.guildId, moderationCase.caseId);
+        if (!currentDelivery ||
+            !(await repository.updateThreadDelivery({
+                deliveryId: active.deliveryId,
+                expectedFenceToken: currentDelivery.fenceToken,
+                values: {
+                    caseRevision: settled.revision,
+                    resolutionState: closing ? "closed" : "resolved",
+                    ...(closing
+                        ? { closeState: "succeeded", safeCode: null, retryAt: null }
+                        : {}),
+                    updatedAt: new Date(),
+                },
+            })))
+            fail("The action succeeded, but the thread state changed. Refresh the case.");
+        if (closing)
+            return;
+        const threads = context.services.get(HELYX_SERVICE_NAMES.violationThreads);
+        if (!threads.editControls || !active.threadId || !active.controlMessageId)
+            fail("Staff resolution recorded, but the thread controls need refresh.");
+        const edited = await threads.editControls({
+            guildId: context.guildId,
+            threadId: active.threadId,
+            messageId: active.controlMessageId,
+            buttons: closeThreadControl(active.controlToken).buttons,
+            operationKey: `${operationKey}:controls`,
+            revalidate,
+        });
+        if (edited.outcome !== "updated")
+            fail("Staff resolution recorded, but the thread controls need refresh.");
+        const refreshed = await repository.findThreadDelivery(context.guildId, moderationCase.caseId);
+        if (refreshed)
+            await repository.updateThreadDelivery({
+                deliveryId: refreshed.deliveryId,
+                expectedFenceToken: refreshed.fenceToken,
+                values: { safeCode: null, retryAt: null, updatedAt: new Date() },
+            });
+    }
+}
+function actionInput(action, value) {
+    if (action === "mute") {
+        const seconds = Number(value.durationSeconds);
+        if (!AUTOMOD_TIMEOUT_SECONDS.some((duration) => duration === seconds))
+            fail("Choose a supported mute duration.");
+        return { type: "timeout", durationSeconds: seconds };
+    }
+    if (action === "unmute")
+        return { type: "timeout_remove" };
+    if (action === "kick")
+        return { type: "kick" };
+    if (action === "ban")
+        return { type: "ban", deleteMessageSeconds: 0 };
+    if (action === "demote") {
+        try {
+            return {
+                type: "demote",
+                roleIds: validateDemotionRoleIds(value.roleIds),
+            };
+        }
+        catch {
+            fail("Choose between 1 and 10 distinct roles to remove.");
+        }
+    }
+    return { type: "case_only" };
+}
+function validatedReason(value) {
+    try {
+        return validateReason(value);
+    }
+    catch {
+        return fail("The reason must be between 10 and 500 characters.");
+    }
+}
+function fail(message) {
+    throw new DashboardActionValidationError(message);
+}
+//# sourceMappingURL=case-actions.js.map

package/dist/case-naming.d.ts

@@ -0,0 +1,4 @@
+import type { ModerationConfiguration } from "./configuration.js";
+export declare function formatModerationCaseNumber(caseNumber: number): string;
+export declare function moderationThreadName(configuration: ModerationConfiguration, caseNumber: number): string;
+//# sourceMappingURL=case-naming.d.ts.map

package/dist/case-naming.js

@@ -0,0 +1,9 @@
+export function formatModerationCaseNumber(caseNumber) {
+    if (!Number.isSafeInteger(caseNumber) || caseNumber < 1)
+        throw new Error("Invalid moderation case number.");
+    return String(caseNumber).padStart(3, "0");
+}
+export function moderationThreadName(configuration, caseNumber) {
+    return `${configuration.violationCaseNamePrefix}-${formatModerationCaseNumber(caseNumber)}`;
+}
+//# sourceMappingURL=case-naming.js.map

package/dist/case-repository.d.ts

@@ -0,0 +1,29 @@
+import type { ModuleRecordService } from "@helyx/sdk";
+import type { ModerationCaseAction, ModerationCaseState } from "./contracts.js";
+import { type StoredModerationAttempt, type StoredModerationCase } from "./repository-model.js";
+export interface ModerationCaseQuery {
+    guildId: string;
+    search?: string;
+    actorUserId?: string;
+    ruleId?: string;
+    repeatOrdinal?: 1 | 2 | 3;
+    action?: ModerationCaseAction;
+    state?: ModerationCaseState;
+    from?: Date;
+    to?: Date;
+    cursor?: string;
+    limit: number;
+}
+export interface ModerationCasePage {
+    items: readonly StoredModerationCase[];
+    nextCursor?: string;
+}
+export declare class ModerationCaseRepository {
+    private readonly records;
+    constructor(records: ModuleRecordService);
+    findCase(guildId: string, caseId: string): Promise<StoredModerationCase | null>;
+    findCaseByNumber(guildId: string, caseNumber: number): Promise<StoredModerationCase | null>;
+    listCases(query: ModerationCaseQuery): Promise<ModerationCasePage>;
+    listAttempts(guildId: string, caseId: string): Promise<readonly StoredModerationAttempt[]>;
+}
+//# sourceMappingURL=case-repository.d.ts.map

package/dist/case-repository.js

@@ -0,0 +1,199 @@
+import { MODERATION_LIMITS, MODERATION_MODULE_ID } from "./constants.js";
+import { ATTEMPT_FIELDS, CASE_FIELDS, mapAttempt, mapCase, } from "./repository-model.js";
+export class ModerationCaseRepository {
+    records;
+    constructor(records) {
+        this.records = records;
+    }
+    async findCase(guildId, caseId) {
+        const row = await this.records.findOne({
+            moduleId: MODERATION_MODULE_ID,
+            collection: "cases",
+            select: CASE_FIELDS,
+            where: { guild_id: guildId, case_id: caseId },
+        });
+        return row ? mapCase(row) : null;
+    }
+    async findCaseByNumber(guildId, caseNumber) {
+        const row = await this.records.findOne({
+            moduleId: MODERATION_MODULE_ID,
+            collection: "cases",
+            select: CASE_FIELDS,
+            where: { guild_id: guildId, case_number: caseNumber },
+        });
+        return row ? mapCase(row) : null;
+    }
+    async listCases(query) {
+        validateCaseQuery(query);
+        const search = query.search?.trim();
+        if (search?.startsWith("#")) {
+            const caseNumber = Number(search.slice(1));
+            const found = Number.isSafeInteger(caseNumber)
+                ? await this.findCaseByNumber(query.guildId, caseNumber)
+                : null;
+            return { items: found && withinDates(found, query) ? [found] : [] };
+        }
+        const binding = queryBinding(query);
+        const decoded = decodeCursor(query.cursor, binding);
+        const snapshotAt = decoded?.snapshotAt ?? new Date().toISOString();
+        const effectiveQuery = withDefaultDateWindow(query, snapshotAt);
+        const where = {
+            guild_id: effectiveQuery.guildId,
+        };
+        if (effectiveQuery.actorUserId)
+            where.actor_user_id = effectiveQuery.actorUserId;
+        if (effectiveQuery.ruleId)
+            where.repeat_rule_id = effectiveQuery.ruleId;
+        if (effectiveQuery.repeatOrdinal)
+            where.repeat_offence_ordinal = effectiveQuery.repeatOrdinal;
+        if (effectiveQuery.action)
+            where.action = effectiveQuery.action;
+        if (effectiveQuery.state)
+            where.state = effectiveQuery.state;
+        if (search)
+            where.subject_user_id = search;
+        const page = await this.records.findMany({
+            moduleId: MODERATION_MODULE_ID,
+            collection: "cases",
+            select: CASE_FIELDS,
+            where,
+            orderBy: [
+                { field: "created_at", direction: "desc" },
+                { field: "case_id", direction: "desc" },
+            ],
+            ...(effectiveQuery.from && effectiveQuery.to
+                ? {
+                    dateRange: {
+                        field: "created_at",
+                        from: effectiveQuery.from,
+                        to: effectiveQuery.to,
+                    },
+                }
+                : {}),
+            ...(decoded ? { cursor: decoded.values } : {}),
+            limit: query.limit,
+        });
+        const items = page.records.map(mapCase);
+        return {
+            items,
+            ...(page.nextCursor
+                ? {
+                    nextCursor: encodeCursor(binding, page.nextCursor, snapshotAt),
+                }
+                : {}),
+        };
+    }
+    async listAttempts(guildId, caseId) {
+        const result = await this.records.findMany({
+            moduleId: MODERATION_MODULE_ID,
+            collection: "action_attempts",
+            select: ATTEMPT_FIELDS,
+            where: { guild_id: guildId, case_id: caseId },
+            orderBy: [
+                { field: "created_at", direction: "asc" },
+                { field: "attempt_id", direction: "asc" },
+            ],
+            limit: 100,
+        });
+        return result.records.map(mapAttempt);
+    }
+}
+function withDefaultDateWindow(query, snapshotAt) {
+    if (query.search || (query.from && query.to))
+        return query;
+    const to = new Date(snapshotAt);
+    if (!Number.isFinite(to.getTime()))
+        throw new Error("The moderation case cursor is invalid.");
+    return {
+        ...query,
+        from: new Date(to.getTime() - MODERATION_LIMITS.caseDateWindowDays * 86_400_000),
+        to,
+    };
+}
+function validateCaseQuery(query) {
+    if (!Number.isInteger(query.limit) ||
+        query.limit < 1 ||
+        query.limit > MODERATION_LIMITS.casePageSize)
+        throw new Error("Moderation case page size is invalid.");
+    if ((query.from && !query.to) || (!query.from && query.to))
+        throw new Error("Moderation case date filters require both dates.");
+    if (query.from && query.to) {
+        const window = query.to.getTime() - query.from.getTime();
+        if (window < 0 ||
+            window > MODERATION_LIMITS.caseDateWindowDays * 86_400_000)
+            throw new Error("Moderation case date filters cannot exceed 31 days.");
+    }
+    for (const value of [
+        query.actorUserId,
+        query.search?.startsWith("#") ? undefined : query.search,
+    ])
+        if (value && !/^\d{17,20}$/u.test(value.trim()))
+            throw new Error("Moderation case member filters require an exact Discord user ID.");
+}
+function withinDates(item, query) {
+    return ((!query.from || item.createdAt >= query.from) &&
+        (!query.to || item.createdAt <= query.to));
+}
+function queryBinding(query) {
+    return JSON.stringify({
+        v: 1,
+        guildId: query.guildId,
+        search: query.search?.trim() ?? null,
+        actorUserId: query.actorUserId ?? null,
+        ruleId: query.ruleId ?? null,
+        repeatOrdinal: query.repeatOrdinal ?? null,
+        action: query.action ?? null,
+        state: query.state ?? null,
+        from: query.from?.toISOString() ?? null,
+        to: query.to?.toISOString() ?? null,
+        order: "created_at_desc_case_id_desc",
+    });
+}
+function encodeCursor(binding, values, snapshotAt) {
+    return Buffer.from(JSON.stringify({
+        v: 1,
+        binding,
+        values: values.map((value) => value instanceof Date ? { date: value.toISOString() } : value),
+        snapshotAt,
+    }), "utf8").toString("base64url");
+}
+function decodeCursor(cursor, binding) {
+    if (!cursor)
+        return null;
+    try {
+        const parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+        if (!isObject(parsed) ||
+            parsed.v !== 1 ||
+            parsed.binding !== binding ||
+            !Array.isArray(parsed.values) ||
+            typeof parsed.snapshotAt !== "string")
+            throw new Error("invalid");
+        const values = parsed.values.map((value) => isObject(value) && typeof value.date === "string"
+            ? validDate(value.date)
+            : validScalar(value));
+        if (values.length !== 2)
+            throw new Error("invalid");
+        return { values, snapshotAt: parsed.snapshotAt };
+    }
+    catch {
+        throw new Error("The moderation case cursor is invalid or belongs to another query.");
+    }
+}
+function isObject(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function validDate(value) {
+    const date = new Date(value);
+    if (!Number.isFinite(date.getTime()))
+        throw new Error("invalid");
+    return date;
+}
+function validScalar(value) {
+    if (typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean" ||
+        value instanceof Date)
+        return value;
+    throw new Error("invalid");
+}
+//# sourceMappingURL=case-repository.js.map

package/dist/channel-actions.d.ts

@@ -0,0 +1,3 @@
+import { type ModuleDashboardAction } from "@helyx/sdk";
+export declare function createModerationChannelActions(): readonly ModuleDashboardAction[];
+//# sourceMappingURL=channel-actions.d.ts.map