@helyx/module-moderation 1.0.1

package/dist/thread-controls.js

@@ -0,0 +1,376 @@
+import { HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { closeThreadControl, currentThreadActor, privateThreadControlMessage, } from "./components.js";
+import { MODERATION_MODULE_ID } from "./constants.js";
+import { appendModerationAudit, moderationConfiguration, moderationRetentionExpiresAt, scheduleActionReconciliation, } from "./action-support.js";
+import { ModerationRepository, } from "./repository.js";
+import { markAmbiguousThreadControl } from "./thread-reconciliation.js";
+export class ModerationThreadControls {
+    moderation;
+    constructor(moderation) {
+        this.moderation = moderation;
+    }
+    async executeControl(context, action, token) {
+        try {
+            const repository = new ModerationRepository(context.services);
+            const delivery = await repository.findThreadDeliveryByControlToken(token);
+            if (!delivery ||
+                !isActiveDelivery(delivery) ||
+                !context.serverId ||
+                delivery.guildId !== context.serverId ||
+                delivery.threadId !== context.channelId ||
+                delivery.controlMessageId !== context.messageId)
+                throw new Error("This moderation control is no longer valid.");
+            const moderationCase = await repository.findCase(delivery.guildId, delivery.caseId);
+            if (!moderationCase ||
+                moderationCase.revision !== delivery.caseRevision ||
+                moderationCase.state !== "applied" ||
+                !moderationCase.subjectUserId)
+                throw new Error("This moderation case changed. Refresh the case before acting.");
+            const permissionId = isClosingAction(action)
+                ? action === "close_delete"
+                    ? "moderation.threads.close-delete"
+                    : "moderation.threads.close"
+                : "moderation.threads.act";
+            const actor = await currentThreadActor(context, permissionId);
+            if (!actor)
+                throw new Error("You no longer have access to this control.");
+            if (delivery.resolutionState === "closed" && action !== "close_delete")
+                throw new Error("This violation thread is already closed.");
+            if (isClosingAction(action) &&
+                delivery.resolutionState === "awaiting_staff")
+                throw new Error("Resolve the case before closing this thread.");
+            if (!isClosingAction(action) && delivery.resolutionState === "resolved") {
+                await showCloseControl(context, delivery);
+                await context.reply(privateThreadControlMessage("This case already has a staff resolution. Close is now available."));
+                return;
+            }
+            if (!isClosingAction(action) &&
+                delivery.resolutionState !== "awaiting_staff")
+                throw new Error("This case already has a staff resolution.");
+            await this.#apply(context, repository, delivery, moderationCase, actor.userId, action);
+        }
+        catch (error) {
+            await context.reply(privateThreadControlMessage(error instanceof Error && safeControlError(error.message)
+                ? error.message
+                : "The moderation control is temporarily unavailable."));
+        }
+    }
+    async #apply(context, repository, delivery, moderationCase, actorUserId, action) {
+        const subjectUserId = moderationCase.subjectUserId;
+        if (!subjectUserId)
+            throw new Error("This case is disassociated.");
+        const caseAction = action === "unmute"
+            ? "timeout_remove"
+            : action === "no_further_action" || isClosingAction(action)
+                ? "case_only"
+                : action;
+        const configuration = await moderationConfiguration(context.services, delivery.guildId);
+        const retentionDays = configuration.caseRetentionDays;
+        const attempt = await atomic(context.services).createAdditionalPendingAttempt({
+            operationKey: `thread:${delivery.controlToken}:${action}`,
+            guildId: delivery.guildId,
+            caseId: delivery.caseId,
+            expectedRevision: moderationCase.revision,
+            purpose: "thread_control",
+            action: caseAction,
+            actorUserId,
+            reason: `Staff selected ${action.replaceAll("_", " ")} in the violation thread.`,
+            occurredAt: new Date(),
+        });
+        if (attempt.outcome === "rejected")
+            throw new Error("This moderation case changed.");
+        if (attempt.outcome === "replayed") {
+            await context.reply(privateThreadControlMessage("This moderation control was already processed."));
+            return;
+        }
+        try {
+            await appendModerationAudit(context.services, {
+                guildId: delivery.guildId,
+                actorUserId,
+                action: "moderation.thread-control",
+                source: "discord",
+                correlationId: context.interactionId,
+                idempotencyKey: `thread:${delivery.controlToken}:${action}:audit`,
+                targetType: "moderation_case",
+                targetId: delivery.caseId,
+                metadata: { action, caseNumber: moderationCase.caseNumber },
+            });
+        }
+        catch {
+            await settle(context.services, delivery, attempt, "failed", "audit_unavailable", retentionDays);
+            throw new Error("Audit is unavailable. No Discord action was taken.");
+        }
+        await markAmbiguousThreadControl(repository, delivery, action === "no_further_action" ? "resolve" : action, attempt.attemptId);
+        const currentDelivery = await repository.findThreadDeliveryByControlToken(delivery.controlToken);
+        if (!currentDelivery || !isActiveDelivery(currentDelivery))
+            throw new Error("This moderation control is no longer valid.");
+        delivery = currentDelivery;
+        const revalidate = async () => {
+            if (!(await currentThreadActor(context, isClosingAction(action)
+                ? action === "close_delete"
+                    ? "moderation.threads.close-delete"
+                    : "moderation.threads.close"
+                : "moderation.threads.act")))
+                return false;
+            const current = await repository.findCase(delivery.guildId, delivery.caseId);
+            const binding = action === "close_delete"
+                ? await repository.findThreadDeliveryByControlToken(delivery.controlToken)
+                : delivery;
+            return (current?.state === "pending" &&
+                current.revision === attempt.revision &&
+                current.subjectUserId === subjectUserId &&
+                !current.disassociatedAt &&
+                binding?.guildId === delivery.guildId &&
+                binding.threadId === delivery.threadId &&
+                binding.parentChannelId === delivery.parentChannelId &&
+                binding.accessRoleId === delivery.accessRoleId &&
+                (action !== "close_delete" ||
+                    JSON.stringify(await moderationConfiguration(context.services, delivery.guildId)) === JSON.stringify(configuration)));
+        };
+        let effect = await (!(await revalidate())
+            ? Promise.resolve({
+                outcome: "missing_permission",
+                safeCode: "actor_or_case_changed",
+            })
+            : isClosingAction(action)
+                ? closeViolationThread(context.services, delivery, subjectUserId, revalidate, action === "close_delete")
+                : this.moderation.dispatchAction(context.services, {
+                    guildId: delivery.guildId,
+                    subjectUserId,
+                    actorUserId,
+                    action: action === "kick"
+                        ? { type: "kick" }
+                        : action === "ban"
+                            ? { type: "ban", deleteMessageSeconds: 0 }
+                            : action === "unmute"
+                                ? { type: "timeout_remove" }
+                                : { type: "case_only" },
+                    reason: `[Helyx case ${moderationCase.caseNumber}] Violation thread staff action`,
+                    operationKey: `thread:${delivery.controlToken}:${action}:discord`,
+                    protectedRoleIds: [delivery.accessRoleId],
+                    revalidate,
+                })).catch(() => ({
+            outcome: "ambiguous",
+            safeCode: "enforcement_unavailable",
+        }));
+        if (action === "close_delete" &&
+            !["succeeded", "already_applied"].includes(effect.outcome))
+            effect = { outcome: "ambiguous", safeCode: "thread_delete_unconfirmed" };
+        const result = await settle(context.services, delivery, attempt, effect.outcome, effect.safeCode, retentionDays).catch(() => null);
+        if (!result || effect.outcome === "ambiguous")
+            await scheduleActionReconciliation(context.services, {
+                guildId: delivery.guildId,
+                caseId: delivery.caseId,
+                attemptId: attempt.attemptId,
+                operationKey: `thread:${delivery.controlToken}:${action}`,
+            }).catch(() => undefined);
+        if (!result ||
+            (effect.outcome !== "succeeded" && effect.outcome !== "already_applied"))
+            throw new Error("The action was not confirmed and needs dashboard review.");
+        await scheduleActionReconciliation(context.services, {
+            guildId: delivery.guildId,
+            caseId: delivery.caseId,
+            attemptId: attempt.attemptId,
+            operationKey: `thread:${delivery.controlToken}:${action}`,
+        }).catch(() => undefined);
+        if ((action === "kick" || action === "ban") &&
+            (await releaseViolationThreadAccess(context.services, delivery, subjectUserId, action)) === "review_required") {
+            await repository.updateThreadDelivery({
+                deliveryId: delivery.deliveryId,
+                expectedFenceToken: delivery.fenceToken,
+                values: {
+                    retryAt: new Date(),
+                    updatedAt: new Date(),
+                },
+            });
+            throw new Error("The action was applied, but thread access needs dashboard review.");
+        }
+        const changed = await repository.updateThreadDelivery({
+            deliveryId: delivery.deliveryId,
+            expectedFenceToken: delivery.fenceToken,
+            values: {
+                caseRevision: result.revision,
+                resolutionState: isClosingAction(action) ? "closed" : "resolved",
+                closeState: isClosingAction(action) ? "succeeded" : delivery.closeState,
+                ...(isClosingAction(action) ? { safeCode: null, retryAt: null } : {}),
+                updatedAt: new Date(),
+            },
+        });
+        if (!changed)
+            throw new Error("The thread state changed. Refresh it before acting.");
+        if (!isClosingAction(action))
+            await showCloseControl(context, delivery);
+        if (!isClosingAction(action)) {
+            const refreshed = await repository.findThreadDeliveryByControlToken(delivery.controlToken);
+            if (refreshed)
+                await repository.updateThreadDelivery({
+                    deliveryId: refreshed.deliveryId,
+                    expectedFenceToken: refreshed.fenceToken,
+                    values: { safeCode: null, retryAt: null, updatedAt: new Date() },
+                });
+        }
+        await context.reply(privateThreadControlMessage(isClosingAction(action)
+            ? action === "close_delete"
+                ? "Violation thread closed and deleted. Case records retained."
+                : "Violation thread closed."
+            : "Staff resolution recorded. Close is now available."));
+    }
+}
+function safeControlError(message) {
+    return SAFE_CONTROL_ERRORS.has(message);
+}
+const SAFE_CONTROL_ERRORS = new Set([
+    "This moderation control is no longer valid.",
+    "This moderation case changed. Refresh the case before acting.",
+    "You no longer have access to this control.",
+    "This violation thread is already closed.",
+    "Resolve the case before closing this thread.",
+    "This case already has a staff resolution.",
+    "This case is disassociated.",
+    "This moderation case changed.",
+    "Audit is unavailable. No Discord action was taken.",
+    "The action was not confirmed and needs dashboard review.",
+    "The action was applied, but thread access needs dashboard review.",
+    "The thread state changed. Refresh it before acting.",
+    "Staff resolution recorded, but the controls could not be refreshed. Click a staff button again to show Close.",
+]);
+async function showCloseControl(context, delivery) {
+    try {
+        const threadService = threads(context.services);
+        if (threadService.editControls &&
+            delivery.threadId &&
+            delivery.controlMessageId) {
+            const result = await threadService.editControls({
+                guildId: delivery.guildId,
+                threadId: delivery.threadId,
+                messageId: delivery.controlMessageId,
+                buttons: closeThreadControl(delivery.controlToken).buttons,
+                operationKey: `thread:${delivery.controlToken}:show-close`,
+                revalidate: () => currentThreadActor(context, "moderation.threads.act").then(Boolean),
+            });
+            if (result.outcome !== "updated")
+                throw new Error("control_edit_failed");
+            return;
+        }
+        if (!context.editSourceMessage)
+            throw new Error("source_edit_unavailable");
+        await context.editSourceMessage(closeThreadControl(delivery.controlToken));
+    }
+    catch {
+        throw new Error("Staff resolution recorded, but the controls could not be refreshed. Click a staff button again to show Close.");
+    }
+}
+async function settle(services, delivery, attempt, outcome, safeCode, retentionDays) {
+    const occurredAt = new Date();
+    const result = await atomic(services).settleActionAttempt({
+        operationKey: `thread:${delivery.controlToken}:${attempt.attemptId}:settle`,
+        guildId: delivery.guildId,
+        caseId: delivery.caseId,
+        attemptId: attempt.attemptId,
+        expectedRevision: attempt.revision,
+        outcome,
+        ...(safeCode ? { safeCode } : {}),
+        ...(retentionDays
+            ? {
+                retentionExpiresAt: moderationRetentionExpiresAt(occurredAt, retentionDays),
+            }
+            : {}),
+        occurredAt,
+    });
+    return result.outcome === "rejected" ? null : result;
+}
+export async function closeViolationThread(services, delivery, subjectUserId, revalidate, deleteThread = false) {
+    if (!delivery.threadId)
+        return { outcome: "review_required", safeCode: "thread_missing" };
+    if (!(await revalidate()))
+        return { outcome: "missing_permission", safeCode: "actor_access_changed" };
+    const inspection = deleteThread
+        ? await threads(services).reconcile({
+            guildId: delivery.guildId,
+            parentChannelId: delivery.parentChannelId,
+            threadId: delivery.threadId,
+            operationKey: `thread:${delivery.controlToken}:delete-inspect`,
+            requireBotOwner: true,
+        })
+        : null;
+    if (inspection?.outcome === "unknown")
+        return { outcome: "ambiguous", safeCode: "delete_inspection_unknown" };
+    const removed = inspection?.outcome === "absent"
+        ? { outcome: "already_exists" }
+        : await threads(services).removeMember({
+            guildId: delivery.guildId,
+            threadId: delivery.threadId,
+            memberUserId: subjectUserId,
+            operationKey: `thread:${delivery.controlToken}:remove-member`,
+        });
+    if (!["created", "already_exists", "member_missing"].includes(removed.outcome))
+        return {
+            outcome: "review_required",
+            safeCode: `member_${removed.outcome}`,
+        };
+    if (!(await revalidate()))
+        return { outcome: "missing_permission", safeCode: "actor_access_changed" };
+    if ((await releaseViolationThreadAccess(services, delivery, subjectUserId, "close")) === "review_required")
+        return { outcome: "review_required", safeCode: "role_release_review" };
+    const closed = await threads(services).close({
+        guildId: delivery.guildId,
+        threadId: delivery.threadId,
+        operationKey: `thread:${delivery.controlToken}:${deleteThread ? "close-delete" : "close"}`,
+        ...(deleteThread
+            ? { deleteThread: true, parentChannelId: delivery.parentChannelId }
+            : {}),
+        revalidate,
+    });
+    if (deleteThread &&
+        (closed.outcome === "created" || closed.outcome === "already_exists")) {
+        const verified = await threads(services).reconcile({
+            guildId: delivery.guildId,
+            parentChannelId: delivery.parentChannelId,
+            threadId: delivery.threadId,
+            requireBotOwner: true,
+            operationKey: `thread:${delivery.controlToken}:delete-verify`,
+        });
+        return verified.outcome === "absent"
+            ? { outcome: "succeeded" }
+            : { outcome: "ambiguous", safeCode: "thread_delete_unconfirmed" };
+    }
+    return closed.outcome === "created" || closed.outcome === "already_exists"
+        ? { outcome: "succeeded" }
+        : {
+            outcome: deleteThread || closed.outcome === "ambiguous"
+                ? "ambiguous"
+                : "review_required",
+            safeCode: closed.outcome,
+        };
+}
+export async function releaseViolationThreadAccess(services, delivery, subjectUserId, reason) {
+    const result = await services
+        .get(HELYX_SERVICE_NAMES.memberRoleGrants)
+        .release({
+        guildId: delivery.guildId,
+        memberUserId: subjectUserId,
+        roleId: delivery.accessRoleId,
+        sourceModuleId: MODERATION_MODULE_ID,
+        sourceId: delivery.caseId,
+        sourceScopeId: delivery.caseId,
+        operationKey: `thread:${delivery.controlToken}:release:${reason}`,
+        occurredAt: delivery.createdAt,
+        reason: `Violation thread access release after ${reason}`,
+    });
+    return result.outcome === "committed" && result.deliveryState === "delivered"
+        ? "released"
+        : "review_required";
+}
+function atomic(services) {
+    return services.get(HELYX_SERVICE_NAMES.atomicModerationCases);
+}
+function threads(services) {
+    return services.get(HELYX_SERVICE_NAMES.violationThreads);
+}
+function isActiveDelivery(delivery) {
+    return Boolean(delivery.parentChannelId && delivery.accessRoleId && delivery.controlToken);
+}
+function isClosingAction(action) {
+    return action === "close" || action === "close_delete";
+}
+//# sourceMappingURL=thread-controls.js.map

package/dist/thread-deletion-recovery.d.ts

@@ -0,0 +1,13 @@
+import type { ServiceAccess } from "@helyx/sdk";
+import { ModerationRepository } from "./repository.js";
+import { type RecoverableThreadAction } from "./thread-reconciliation.js";
+export declare function retryRequestedThreadDeletion(services: ServiceAccess, input: {
+    guildId: string;
+    caseId: string;
+    attemptId: string;
+    actorUserId?: string | null;
+}, recovery: {
+    action: RecoverableThreadAction;
+    attemptId: string;
+}, item: Awaited<ReturnType<ModerationRepository["findCase"]>>, delivery: Awaited<ReturnType<ModerationRepository["findThreadDelivery"]>>): Promise<void>;
+//# sourceMappingURL=thread-deletion-recovery.d.ts.map

package/dist/thread-deletion-recovery.js

@@ -0,0 +1,46 @@
+import { moderationConfiguration } from "./action-support.js";
+import { currentThreadActor } from "./components.js";
+import { ModerationRepository } from "./repository.js";
+import { closeViolationThread } from "./thread-controls.js";
+import { recoveryMarker, } from "./thread-reconciliation.js";
+export async function retryRequestedThreadDeletion(services, input, recovery, item, delivery) {
+    if (recovery.action !== "close_delete" ||
+        !input.actorUserId ||
+        !item?.subjectUserId ||
+        !delivery?.parentChannelId ||
+        !delivery.accessRoleId ||
+        !delivery.controlToken ||
+        recovery.attemptId !== input.attemptId.toLowerCase())
+        return;
+    const configuration = JSON.stringify(await moderationConfiguration(services, input.guildId));
+    const revalidate = async () => {
+        if (!(await currentThreadActor({ serverId: input.guildId, userId: input.actorUserId, services }, "moderation.cases.close-and-delete-thread")))
+            return false;
+        const repository = new ModerationRepository(services);
+        const [current, binding] = await Promise.all([
+            repository.findCase(input.guildId, input.caseId),
+            repository.findThreadDelivery(input.guildId, input.caseId),
+        ]);
+        return (current?.revision === item.revision &&
+            current.subjectUserId === item.subjectUserId &&
+            !current.disassociatedAt &&
+            binding?.threadId === delivery.threadId &&
+            binding.parentChannelId === delivery.parentChannelId &&
+            binding.accessRoleId === delivery.accessRoleId &&
+            binding.controlToken === delivery.controlToken &&
+            current.state === item.state &&
+            recoveryMarker(binding)?.action === "close_delete" &&
+            recoveryMarker(binding)?.attemptId === recovery.attemptId &&
+            JSON.stringify(await moderationConfiguration(services, input.guildId)) ===
+                configuration);
+    };
+    if (!(await revalidate()))
+        return;
+    await closeViolationThread(services, {
+        ...delivery,
+        parentChannelId: delivery.parentChannelId,
+        accessRoleId: delivery.accessRoleId,
+        controlToken: delivery.controlToken,
+    }, item.subjectUserId, revalidate, true);
+}
+//# sourceMappingURL=thread-deletion-recovery.js.map

package/dist/thread-delivery.d.ts

@@ -0,0 +1,11 @@
+import { type ScheduledTaskExecutionResult, type ServiceAccess } from "@helyx/sdk";
+import type { ModerationThreadRuntime } from "./service.js";
+export declare class ModerationThreadDelivery implements ModerationThreadRuntime {
+    deliver(input: Parameters<ModerationThreadRuntime["deliver"]>[0]): ReturnType<ModerationThreadRuntime["deliver"]>;
+    deliverPending(services: ServiceAccess, input: {
+        guildId: string;
+        caseId: string;
+    }): Promise<ScheduledTaskExecutionResult>;
+    reconcileAccess(services: ServiceAccess, guildId: string): Promise<ScheduledTaskExecutionResult>;
+}
+//# sourceMappingURL=thread-delivery.d.ts.map