@helyx/module-moderation 1.0.1

package/dist/tasks.js

@@ -0,0 +1,391 @@
+import { DashboardActionValidationError, HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { MODERATION_MODULE_ID, MODERATION_TASK_KINDS } from "./constants.js";
+import { ModerationRepository } from "./repository.js";
+import { retryRequestedThreadDeletion } from "./thread-deletion-recovery.js";
+import { moderationConfiguration, moderationRetentionExpiresAt, } from "./action-support.js";
+import { finalizeThreadControlRecovery, inspectThreadControlEffect, recoveryMarker, } from "./thread-reconciliation.js";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+export function createModerationTasks(runtime, health) {
+    return [
+        {
+            kind: MODERATION_TASK_KINDS.threadDelivery,
+            version: 1,
+            delivery: "one-shot",
+            attemptLimit: 6,
+            validatePayload: validateThreadDeliveryPayload,
+            execute(context, task) {
+                const payload = validateThreadDeliveryPayload(task.payload);
+                return trackTask(health, MODERATION_TASK_KINDS.threadDelivery, () => runtime.deliverPendingThread(context.services, {
+                    guildId: requiredGuild(task.guildId),
+                    caseId: payload.caseId,
+                }));
+            },
+        },
+        {
+            kind: MODERATION_TASK_KINDS.actionReconcile,
+            version: 1,
+            delivery: "one-shot",
+            attemptLimit: 4,
+            validatePayload: validateActionReconcilePayload,
+            execute(context, task) {
+                const payload = validateActionReconcilePayload(task.payload);
+                return trackTask(health, MODERATION_TASK_KINDS.actionReconcile, () => runtime.reconcileAction(context.services, {
+                    guildId: requiredGuild(task.guildId),
+                    caseId: payload.caseId,
+                    attemptId: payload.attemptId,
+                }));
+            },
+        },
+        {
+            kind: MODERATION_TASK_KINDS.threadAccessReconcile,
+            version: 1,
+            delivery: "coalesced",
+            minimumIntervalMs: 5_000,
+            attemptLimit: 6,
+            validatePayload: validateEmptyPayload,
+            execute(context, task) {
+                validateEmptyPayload(task.payload);
+                return trackTask(health, MODERATION_TASK_KINDS.threadAccessReconcile, () => runtime.reconcileThreadAccess(context.services, {
+                    guildId: requiredGuild(task.guildId),
+                }));
+            },
+        },
+    ];
+}
+export function validateThreadDeliveryPayload(input) {
+    const value = exactRecord(input, ["caseId"]);
+    return { caseId: uuid(value.caseId, "caseId") };
+}
+export function validateActionReconcilePayload(input) {
+    const value = exactRecord(input, ["caseId", "attemptId"]);
+    return {
+        caseId: uuid(value.caseId, "caseId"),
+        attemptId: uuid(value.attemptId, "attemptId"),
+    };
+}
+export function validateEmptyPayload(input) {
+    exactRecord(input, []);
+    return {};
+}
+export async function reconcileModerationAction(services, input) {
+    const atomic = services.get(HELYX_SERVICE_NAMES.atomicModerationCases);
+    const repository = new ModerationRepository(services);
+    const page = await atomic.listReconciliationCandidates({
+        guildId: input.guildId,
+        updatedBefore: new Date(Date.now() - 1_000),
+        limit: 50,
+    });
+    const candidate = page.items.find((item) => item.caseId === input.caseId && item.latestAttemptId === input.attemptId);
+    if (!candidate) {
+        const [delivery, storedCase] = await Promise.all([
+            repository.findThreadDelivery(input.guildId, input.caseId),
+            repository.findCase(input.guildId, input.caseId),
+        ]);
+        const recovery = recoveryMarker(delivery);
+        if (!recovery)
+            return storedCase?.state === "applied"
+                ? synchronizeAwaitingThreadRevision(services, input, storedCase.revision)
+                : { outcome: "completed" };
+        if (recovery.attemptId !== input.attemptId.toLowerCase())
+            return {
+                outcome: "requires_review",
+                safeCode: "recovery_attempt_mismatch",
+            };
+        if (!storedCase?.subjectUserId || storedCase.state !== "applied")
+            return { outcome: "requires_review", safeCode: "case_not_applied" };
+        await retryRequestedThreadDeletion(services, input, recovery, storedCase, delivery);
+        const inspection = recovery.action === "resolve"
+            ? "applied"
+            : await inspectThreadControlEffect(services, {
+                guildId: input.guildId,
+                caseId: input.caseId,
+                subjectUserId: storedCase.subjectUserId,
+                action: recovery.action,
+            });
+        if (inspection === "unknown")
+            return { outcome: "retry", delayMs: 2_000, safeCode: "effect_unknown" };
+        if (inspection !== "applied")
+            return { outcome: "requires_review", safeCode: "effect_not_provable" };
+        return finalizeThreadControlRecovery(services, {
+            guildId: input.guildId,
+            caseId: input.caseId,
+            caseRevision: storedCase.revision,
+            subjectUserId: storedCase.subjectUserId,
+            action: recovery.action,
+        });
+    }
+    const [storedCase, delivery] = await Promise.all([
+        repository.findCase(input.guildId, input.caseId),
+        repository.findThreadDelivery(input.guildId, input.caseId),
+    ]);
+    if (!storedCase)
+        return { outcome: "requires_review", safeCode: "case_missing" };
+    const retentionDays = (await moderationConfiguration(services, input.guildId))
+        .caseRetentionDays;
+    if (!candidate.subjectUserId)
+        return { outcome: "requires_review", safeCode: "case_disassociated" };
+    const recovery = recoveryMarker(delivery);
+    if (recovery &&
+        recovery.attemptId !== candidate.latestAttemptId.toLowerCase())
+        return {
+            outcome: "requires_review",
+            safeCode: "recovery_attempt_mismatch",
+        };
+    const threadAction = recovery?.action ?? null;
+    if (recovery)
+        await retryRequestedThreadDeletion(services, input, recovery, storedCase, delivery);
+    const threadInspection = threadAction && threadAction !== "resolve"
+        ? await inspectThreadControlEffect(services, {
+            guildId: input.guildId,
+            caseId: input.caseId,
+            subjectUserId: candidate.subjectUserId,
+            action: threadAction,
+        })
+        : null;
+    if (threadInspection === "unknown")
+        return { outcome: "retry", delayMs: 2_000, safeCode: "effect_unknown" };
+    const outcome = threadAction && threadAction !== "resolve"
+        ? threadInspection === "applied"
+            ? "already_applied"
+            : "review_required"
+        : await inspectEffect(services, input.guildId, {
+            ...candidate,
+            subjectUserId: candidate.subjectUserId,
+        });
+    if (candidate.latestAttemptOutcome === "pending" &&
+        storedCase.state === "pending") {
+        const occurredAt = new Date();
+        const settled = await atomic.settleActionAttempt({
+            operationKey: `recover-pending:${candidate.latestAttemptId}`,
+            guildId: input.guildId,
+            caseId: input.caseId,
+            attemptId: candidate.latestAttemptId,
+            expectedRevision: candidate.revision,
+            outcome,
+            safeCode: outcome === "already_applied"
+                ? "state_inspected"
+                : "pending_effect_not_provable",
+            retentionExpiresAt: moderationRetentionExpiresAt(occurredAt, retentionDays),
+            occurredAt,
+        });
+        if (settled.outcome === "rejected")
+            return settled.code === "revision_conflict" ||
+                settled.code === "attempt_not_pending"
+                ? { outcome: "completed" }
+                : { outcome: "requires_review", safeCode: settled.code };
+        return outcome === "already_applied"
+            ? threadAction
+                ? finalizeThreadRecovery(services, input, candidate.subjectUserId, threadAction, settled.revision)
+                : synchronizeAwaitingThreadRevision(services, input, settled.revision)
+            : {
+                outcome: "requires_review",
+                safeCode: "pending_effect_not_provable",
+            };
+    }
+    if (outcome === "review_required")
+        return { outcome: "requires_review", safeCode: "effect_not_provable" };
+    const operationKey = input.operationKey ?? `reconcile:${input.attemptId}`;
+    const additional = await atomic.createAdditionalPendingAttempt({
+        operationKey,
+        guildId: input.guildId,
+        caseId: input.caseId,
+        expectedRevision: candidate.revision,
+        purpose: "reconciliation",
+        action: candidate.latestAttemptAction,
+        ...(candidate.latestAttemptAction === "timeout" &&
+            candidate.requestedDurationSeconds !== null
+            ? { requestedDurationSeconds: candidate.requestedDurationSeconds }
+            : {}),
+        ...(candidate.latestAttemptAction === "demote"
+            ? { demoteRoleIds: candidate.demoteRoleIds }
+            : {}),
+        actorUserId: input.actorUserId ?? null,
+        reason: "System reconciliation of an ambiguous Discord result.",
+        occurredAt: new Date(),
+    });
+    if (additional.outcome === "rejected")
+        return additional.code === "revision_conflict"
+            ? { outcome: "deferred", delayMs: 2_000, safeCode: "revision_changed" }
+            : { outcome: "requires_review", safeCode: additional.code };
+    if (additional.outcome === "replayed" &&
+        additional.attemptOutcome !== "pending")
+        return additional.attemptOutcome === "succeeded" ||
+            additional.attemptOutcome === "already_applied"
+            ? threadAction
+                ? finalizeThreadRecovery(services, input, candidate.subjectUserId, threadAction, additional.revision)
+                : synchronizeAwaitingThreadRevision(services, input, additional.revision)
+            : { outcome: "requires_review", safeCode: "reconciliation_replayed" };
+    const occurredAt = new Date();
+    const settled = await atomic.settleActionAttempt({
+        operationKey: `${operationKey}:settle`,
+        guildId: input.guildId,
+        caseId: input.caseId,
+        attemptId: additional.attemptId,
+        expectedRevision: additional.revision,
+        outcome,
+        safeCode: "state_inspected",
+        retentionExpiresAt: moderationRetentionExpiresAt(occurredAt, retentionDays),
+        occurredAt,
+    });
+    if (settled.outcome === "rejected")
+        return { outcome: "requires_review", safeCode: settled.code };
+    return threadAction
+        ? finalizeThreadRecovery(services, input, candidate.subjectUserId, threadAction, settled.revision)
+        : synchronizeAwaitingThreadRevision(services, input, settled.revision);
+}
+async function synchronizeAwaitingThreadRevision(services, input, revision) {
+    const repository = new ModerationRepository(services);
+    const [item, delivery] = await Promise.all([
+        repository.findCase(input.guildId, input.caseId),
+        repository.findThreadDelivery(input.guildId, input.caseId),
+    ]);
+    if (!delivery ||
+        delivery.resolutionState !== "awaiting_staff" ||
+        delivery.caseRevision === revision)
+        return { outcome: "completed" };
+    if (!item ||
+        item.state !== "applied" ||
+        item.revision !== revision ||
+        !item.subjectUserId ||
+        item.disassociatedAt ||
+        recoveryMarker(delivery))
+        return {
+            outcome: "requires_review",
+            safeCode: "thread_case_binding_changed",
+        };
+    return (await repository.updateThreadDelivery({
+        deliveryId: delivery.deliveryId,
+        expectedFenceToken: delivery.fenceToken,
+        values: { caseRevision: revision, updatedAt: new Date() },
+    }))
+        ? { outcome: "completed" }
+        : {
+            outcome: "retry",
+            delayMs: 2_000,
+            safeCode: "thread_delivery_revision_changed",
+        };
+}
+function finalizeThreadRecovery(services, input, subjectUserId, action, caseRevision) {
+    return finalizeThreadControlRecovery(services, {
+        guildId: input.guildId,
+        caseId: input.caseId,
+        caseRevision,
+        subjectUserId,
+        action,
+    });
+}
+async function trackTask(health, taskKind, execute) {
+    try {
+        const result = await execute();
+        if (result.outcome === "completed")
+            health?.recordTaskSuccess(taskKind);
+        else
+            health?.recordTaskFailure(taskKind, "safeCode" in result && result.safeCode
+                ? result.safeCode
+                : `task_${result.outcome}`);
+        return result;
+    }
+    catch (error) {
+        health?.recordTaskFailure(taskKind, "task_exception");
+        throw error;
+    }
+}
+async function inspectEffect(services, guildId, candidate) {
+    const enforcement = services.get(HELYX_SERVICE_NAMES.memberEnforcement);
+    if (candidate.latestAttemptAction === "ban") {
+        const ban = await enforcement.inspectBan({
+            guildId,
+            userId: candidate.subjectUserId,
+        });
+        return ban.outcome === "banned" ? "already_applied" : "review_required";
+    }
+    if (candidate.latestAttemptAction === "unban") {
+        const ban = await enforcement.inspectBan({
+            guildId,
+            userId: candidate.subjectUserId,
+        });
+        return ban.outcome === "not_banned" ? "already_applied" : "review_required";
+    }
+    const member = await enforcement.inspectMember({
+        guildId,
+        memberUserId: candidate.subjectUserId,
+    });
+    if (candidate.latestAttemptAction === "timeout")
+        return member.outcome === "present" &&
+            candidate.requestedDurationSeconds !== null &&
+            member.timeoutEndsAt &&
+            member.timeoutEndsAt.getTime() >=
+                candidate.latestAttemptCreatedAt.getTime() +
+                    candidate.requestedDurationSeconds * 1_000 -
+                    5_000
+            ? "already_applied"
+            : "review_required";
+    if (candidate.latestAttemptAction === "timeout_remove")
+        return member.outcome === "present" && !member.timeoutEndsAt
+            ? "already_applied"
+            : "review_required";
+    if (candidate.latestAttemptAction === "demote")
+        return member.outcome === "present" &&
+            candidate.demoteRoleIds.every((roleId) => !member.roleIds.includes(roleId))
+            ? "already_applied"
+            : "review_required";
+    if (candidate.latestAttemptAction === "warn")
+        return "already_applied";
+    if (candidate.latestAttemptAction === "case_only")
+        return "already_applied";
+    return "review_required";
+}
+function exactRecord(input, keys) {
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        throw new Error("Moderation scheduled-task payload is invalid.");
+    const value = input;
+    const actual = Object.keys(value).sort();
+    const expected = [...keys].sort();
+    if (actual.length !== expected.length ||
+        actual.some((key, index) => key !== expected[index]))
+        throw new Error("Moderation scheduled-task payload is invalid.");
+    return value;
+}
+function uuid(input, field) {
+    if (typeof input !== "string" || !UUID.test(input))
+        throw new Error(`Moderation scheduled-task ${field} is invalid.`);
+    return input;
+}
+function requiredGuild(guildId) {
+    if (!guildId)
+        throw new Error("Moderation tasks require a Discord server.");
+    return guildId;
+}
+export async function scheduleModerationThreadRetry(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.threadDelivery,
+        guildId: input.guildId,
+        idempotencyKey: `${input.operationKey}:thread-retry`,
+        payload: { caseId: input.caseId },
+        scheduledFor: new Date(Date.now() + 5_000),
+    });
+}
+export async function reconcileDashboardCase(input) {
+    const repository = new ModerationRepository(input.services);
+    const item = await repository.findCase(input.guildId, input.caseId);
+    if (!item || item.revision !== input.expectedRevision)
+        throw new DashboardActionValidationError("This moderation case changed.");
+    const latest = (await repository.listAttempts(input.guildId, input.caseId)).at(-1);
+    if (!latest)
+        throw new DashboardActionValidationError("This case has no action attempt.");
+    const result = await reconcileModerationAction(input.services, {
+        guildId: input.guildId,
+        caseId: input.caseId,
+        attemptId: latest.attemptId,
+        actorUserId: input.actorUserId,
+        operationKey: input.operationKey,
+    });
+    if (result.outcome !== "completed")
+        throw new DashboardActionValidationError("This case still needs manual review.");
+}
+//# sourceMappingURL=tasks.js.map

package/dist/thread-controls.d.ts

@@ -0,0 +1,23 @@
+import { type ModalCapableInteractionContext, type ModerationActionAttemptTerminalOutcome, type ServiceAccess } from "@helyx/sdk";
+import { type ModerationThreadControlRuntime } from "./components.js";
+import { type StoredModerationThreadDelivery } from "./repository.js";
+import type { ModerationService } from "./service.js";
+type ThreadAction = "kick" | "ban" | "unmute" | "no_further_action" | "close" | "close_delete";
+type ActiveThreadDelivery = StoredModerationThreadDelivery & {
+    parentChannelId: string;
+    accessRoleId: string;
+    controlToken: string;
+};
+export declare class ModerationThreadControls implements ModerationThreadControlRuntime {
+    #private;
+    private readonly moderation;
+    constructor(moderation: ModerationService);
+    executeControl(context: ModalCapableInteractionContext, action: ThreadAction, token: string): Promise<void>;
+}
+export declare function closeViolationThread(services: ServiceAccess, delivery: ActiveThreadDelivery, subjectUserId: string, revalidate: () => Promise<boolean>, deleteThread?: boolean): Promise<{
+    outcome: ModerationActionAttemptTerminalOutcome;
+    safeCode?: string;
+}>;
+export declare function releaseViolationThreadAccess(services: ServiceAccess, delivery: ActiveThreadDelivery, subjectUserId: string, reason: string): Promise<"released" | "review_required">;
+export {};
+//# sourceMappingURL=thread-controls.d.ts.map