@helyx/module-moderation 1.0.1

package/dist/service.js

@@ -0,0 +1,329 @@
+import { HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { MODERATION_MODULE_ID } from "./constants.js";
+import { appendModerationAudit, atomicCases as cases, moderationApplied as isApplied, moderationAuditReason as auditReason, moderationConfiguration as getConfiguration, moderationEnabled as moduleEnabled, emitModerationActionLog, moderationEnforcement as memberEnforcement, moderationRetentionExpiresAt as retentionExpiresAt, scheduleActionReconciliation, sendWarningDirectMessage, staffAction, } from "./action-support.js";
+export class ModerationService {
+    #threads = null;
+    attachThreadRuntime(runtime) {
+        this.#threads = runtime;
+    }
+    canExecuteStaffAction(services, draft) {
+        return this.#revalidateStaffAction(services, draft);
+    }
+    async executeStaffAction(services, draft) {
+        if (!(await this.#revalidateStaffAction(services, draft)))
+            return { outcome: "rejected", safeCode: "authorization_changed" };
+        const configuration = await getConfiguration(services, draft.guildId);
+        const occurredAt = new Date();
+        const pending = await cases(services).createPendingCase({
+            operationKey: draft.operationKey,
+            guildId: draft.guildId,
+            subjectUserId: draft.subjectUserId,
+            actorUserId: draft.actor.userId,
+            source: "staff_command",
+            sourceModuleId: MODERATION_MODULE_ID,
+            action: draft.action,
+            reason: draft.reason,
+            occurredAt,
+            ...(draft.privateNote ? { privateNote: draft.privateNote } : {}),
+            ...(draft.evidenceMessage
+                ? { evidenceMessage: draft.evidenceMessage }
+                : {}),
+            ...(draft.requestedDurationSeconds
+                ? { requestedDurationSeconds: draft.requestedDurationSeconds }
+                : {}),
+            ...(draft.deleteMessageSeconds !== undefined
+                ? { deleteMessageSeconds: draft.deleteMessageSeconds }
+                : {}),
+            ...(draft.demoteRoleIds ? { demoteRoleIds: draft.demoteRoleIds } : {}),
+        });
+        if (pending.outcome === "rejected")
+            return { outcome: "rejected", safeCode: pending.code };
+        if (pending.outcome === "replayed") {
+            if (pending.attemptOutcome === "pending" ||
+                pending.attemptOutcome === "ambiguous")
+                await scheduleActionReconciliation(services, {
+                    guildId: draft.guildId,
+                    caseId: pending.caseId,
+                    attemptId: pending.attemptId,
+                    operationKey: draft.operationKey,
+                });
+            return {
+                outcome: pending.attemptOutcome === "succeeded" ||
+                    pending.attemptOutcome === "already_applied"
+                    ? "applied"
+                    : pending.attemptOutcome === "pending" ||
+                        pending.attemptOutcome === "ambiguous" ||
+                        pending.attemptOutcome === "review_required"
+                        ? "review_required"
+                        : "failed",
+                caseId: pending.caseId,
+                caseNumber: pending.caseNumber,
+                revision: pending.revision,
+                safeCode: `replayed_${pending.attemptOutcome}`,
+            };
+        }
+        try {
+            await appendModerationAudit(services, {
+                guildId: draft.guildId,
+                actorUserId: draft.actor.userId,
+                action: "moderation.action-attempt",
+                source: "discord",
+                correlationId: draft.operationKey,
+                idempotencyKey: `${draft.operationKey}:audit`,
+                targetType: "moderation_case",
+                targetId: pending.caseId,
+                metadata: { action: draft.action, caseNumber: pending.caseNumber },
+            });
+        }
+        catch {
+            const settledAt = new Date();
+            await cases(services).settleActionAttempt({
+                operationKey: `${draft.operationKey}:audit-failed`,
+                guildId: draft.guildId,
+                caseId: pending.caseId,
+                attemptId: pending.attemptId,
+                expectedRevision: pending.revision,
+                outcome: "failed",
+                safeCode: "audit_unavailable",
+                retentionExpiresAt: retentionExpiresAt(settledAt, configuration.caseRetentionDays),
+                occurredAt: settledAt,
+            });
+            return {
+                outcome: "failed",
+                caseId: pending.caseId,
+                caseNumber: pending.caseNumber,
+                safeCode: "audit_unavailable",
+            };
+        }
+        const effect = await this.dispatchAction(services, {
+            guildId: draft.guildId,
+            subjectUserId: draft.subjectUserId,
+            actorUserId: draft.actor.userId,
+            action: staffAction(draft),
+            reason: auditReason(pending.caseNumber, draft.reason),
+            operationKey: `${draft.operationKey}:discord`,
+            protectedRoleIds: configuration.violationAccessRoleId
+                ? [configuration.violationAccessRoleId]
+                : [],
+            revalidate: () => this.#revalidateStaffAction(services, draft),
+        }).catch(() => ({
+            outcome: "ambiguous",
+            safeCode: "enforcement_unavailable",
+        }));
+        const settledAt = new Date();
+        const settlement = await cases(services)
+            .settleActionAttempt({
+            operationKey: `${draft.operationKey}:settle`,
+            guildId: draft.guildId,
+            caseId: pending.caseId,
+            attemptId: pending.attemptId,
+            expectedRevision: pending.revision,
+            outcome: effect.outcome,
+            ...(effect.safeCode ? { safeCode: effect.safeCode } : {}),
+            ...("removedRoleIds" in effect && effect.removedRoleIds
+                ? { removedRoleIds: effect.removedRoleIds }
+                : {}),
+            retentionExpiresAt: retentionExpiresAt(settledAt, configuration.caseRetentionDays),
+            occurredAt: settledAt,
+        })
+            .catch(() => null);
+        if (!settlement) {
+            await scheduleActionReconciliation(services, {
+                guildId: draft.guildId,
+                caseId: pending.caseId,
+                attemptId: pending.attemptId,
+                operationKey: draft.operationKey,
+            }).catch(() => undefined);
+            return {
+                outcome: "review_required",
+                caseId: pending.caseId,
+                caseNumber: pending.caseNumber,
+                safeCode: "settlement_unavailable",
+            };
+        }
+        if (settlement.outcome === "rejected")
+            return {
+                outcome: "review_required",
+                caseId: pending.caseId,
+                caseNumber: pending.caseNumber,
+                safeCode: `settlement_${settlement.code}`,
+            };
+        if (effect.outcome === "ambiguous")
+            await scheduleActionReconciliation(services, {
+                guildId: draft.guildId,
+                caseId: pending.caseId,
+                attemptId: pending.attemptId,
+                operationKey: draft.operationKey,
+            });
+        if (draft.action === "warn" && isApplied(effect.outcome))
+            await sendWarningDirectMessage(services, {
+                guildId: draft.guildId,
+                caseId: pending.caseId,
+                caseNumber: pending.caseNumber,
+                subjectUserId: draft.subjectUserId,
+            }).catch(() => undefined);
+        if (isApplied(effect.outcome)) {
+            await emitModerationActionLog(services, {
+                guildId: draft.guildId,
+                action: draft.action,
+                caseId: pending.caseId,
+                caseNumber: pending.caseNumber,
+                subjectUserId: draft.subjectUserId,
+                actorUserId: draft.actor.userId,
+                ...(draft.requestedDurationSeconds
+                    ? { durationSeconds: draft.requestedDurationSeconds }
+                    : {}),
+                operationKey: draft.operationKey,
+            });
+            await this.deliverViolationThread({
+                services,
+                guildId: draft.guildId,
+                caseId: pending.caseId,
+                caseNumber: pending.caseNumber,
+                caseRevision: settlement.revision,
+                subjectUserId: draft.subjectUserId,
+                severity: "medium",
+                operationKey: draft.operationKey,
+            }).catch(() => "review_required");
+        }
+        return {
+            outcome: isApplied(effect.outcome)
+                ? "applied"
+                : effect.outcome === "ambiguous" || effect.outcome === "review_required"
+                    ? "review_required"
+                    : "failed",
+            caseId: pending.caseId,
+            caseNumber: pending.caseNumber,
+            revision: settlement.revision,
+            safeCode: effect.safeCode ?? effect.outcome,
+        };
+    }
+    async dispatchAction(services, input) {
+        const enforcement = memberEnforcement(services);
+        const common = {
+            guildId: input.guildId,
+            memberUserId: input.subjectUserId,
+            ...(input.actorUserId ? { actorUserId: input.actorUserId } : {}),
+            moduleId: MODERATION_MODULE_ID,
+            reason: input.reason,
+            operationKey: input.operationKey,
+            revalidate: () => input.revalidate(),
+        };
+        if (input.action.type === "case_only" || input.action.type === "warn")
+            return { outcome: "succeeded" };
+        if (input.action.type === "timeout")
+            return enforcement.timeout({
+                ...common,
+                durationSeconds: input.action.durationSeconds,
+            });
+        if (input.action.type === "timeout_remove")
+            return enforcement.removeTimeout(common);
+        if (input.action.type === "kick")
+            return enforcement.kickMember(common);
+        if (input.action.type === "ban")
+            return enforcement.banMember({
+                ...common,
+                deleteMessageSeconds: input.action.deleteMessageSeconds,
+            });
+        if (input.action.type === "unban")
+            return enforcement.unban({
+                guildId: input.guildId,
+                userId: input.subjectUserId,
+                ...(input.actorUserId ? { actorUserId: input.actorUserId } : {}),
+                moduleId: MODERATION_MODULE_ID,
+                reason: input.reason,
+                operationKey: input.operationKey,
+                revalidate: () => input.revalidate(),
+            });
+        if (input.action.type === "demote") {
+            const result = await enforcement.removeConfiguredRoles({
+                ...common,
+                roleIds: input.action.roleIds,
+                protectedRoleIds: [...new Set(input.protectedRoleIds)],
+            });
+            return "removedRoleIds" in result
+                ? { outcome: result.outcome, removedRoleIds: result.removedRoleIds }
+                : result;
+        }
+        if (input.action.type === "delete_message") {
+            const source = input.sourceMessage;
+            if (!source?.messageId)
+                return { outcome: "review_required", safeCode: "source_missing" };
+            const result = await services
+                .get(HELYX_SERVICE_NAMES.messageEnforcement)
+                .deleteMemberMessage({
+                guildId: input.guildId,
+                channelId: source.channelId,
+                messageId: source.messageId,
+                expectedAuthorUserId: input.subjectUserId,
+                callerModuleId: MODERATION_MODULE_ID,
+                reason: input.reason,
+                operationKey: input.operationKey,
+                revalidate: () => input.revalidate(),
+            });
+            return {
+                outcome: result.outcome === "deleted"
+                    ? "succeeded"
+                    : result.outcome === "already_absent"
+                        ? "already_applied"
+                        : result.outcome === "ambiguous"
+                            ? "ambiguous"
+                            : "failed",
+                ...(result.safeCode ? { safeCode: result.safeCode } : {}),
+            };
+        }
+        return { outcome: "review_required", safeCode: "unsupported_action" };
+    }
+    async #revalidateStaffAction(services, draft) {
+        if (!(await moduleEnabled(services, draft.guildId)))
+            return false;
+        const enforcement = memberEnforcement(services);
+        const actor = await enforcement.inspectMember({
+            guildId: draft.guildId,
+            memberUserId: draft.actor.userId,
+        });
+        if (actor.outcome !== "present")
+            return false;
+        const authorised = await services
+            .get(HELYX_SERVICE_NAMES.resourceAuthorization)
+            .canUse({
+            guildId: draft.guildId,
+            moduleId: MODERATION_MODULE_ID,
+            permissionId: draft.permissionId,
+            actor: {
+                userId: draft.actor.userId,
+                roleIds: actor.roleIds,
+                permissions: actor.effectivePermissionNames,
+                isServerOwner: actor.isGuildOwner,
+                isAdministrator: actor.isAdministrator,
+            },
+        });
+        if (!authorised || draft.subjectUserId === draft.actor.userId)
+            return false;
+        if (draft.action === "unban")
+            return true;
+        const subject = await enforcement.inspectMember({
+            guildId: draft.guildId,
+            memberUserId: draft.subjectUserId,
+            actorUserId: draft.actor.userId,
+        });
+        if (draft.action === "ban" && subject.outcome === "member_missing")
+            return true;
+        if (subject.outcome !== "present")
+            return false;
+        if (subject.isGuildOwner ||
+            subject.helyxHierarchy !== "above" ||
+            subject.actorHierarchy !== "above")
+            return false;
+        if (draft.action === "timeout" &&
+            (subject.isAdministrator || subject.isBot))
+            return false;
+        return true;
+    }
+    deliverViolationThread(input) {
+        return this.#threads
+            ? this.#threads.deliver(input)
+            : Promise.resolve("review_required");
+    }
+}
+//# sourceMappingURL=service.js.map

package/dist/tasks.d.ts

@@ -0,0 +1,49 @@
+import type { ModuleScheduledTaskContribution, ScheduledTaskExecutionResult, ServiceAccess } from "@helyx/sdk";
+export interface ModerationTaskRuntime {
+    deliverPendingThread(services: ServiceAccess, input: {
+        guildId: string;
+        caseId: string;
+    }): Promise<ScheduledTaskExecutionResult>;
+    reconcileAction(services: ServiceAccess, input: {
+        guildId: string;
+        caseId: string;
+        attemptId: string;
+    }): Promise<ScheduledTaskExecutionResult>;
+    reconcileThreadAccess(services: ServiceAccess, input: {
+        guildId: string;
+    }): Promise<ScheduledTaskExecutionResult>;
+}
+export interface ModerationTaskHealth {
+    recordTaskSuccess(taskKind: string): void;
+    recordTaskFailure(taskKind: string, safeCode: string): void;
+}
+export declare function createModerationTasks(runtime: ModerationTaskRuntime, health?: ModerationTaskHealth): readonly ModuleScheduledTaskContribution[];
+export declare function validateThreadDeliveryPayload(input: unknown): {
+    caseId: string;
+};
+export declare function validateActionReconcilePayload(input: unknown): {
+    caseId: string;
+    attemptId: string;
+};
+export declare function validateEmptyPayload(input: unknown): {};
+export declare function reconcileModerationAction(services: ServiceAccess, input: {
+    guildId: string;
+    caseId: string;
+    attemptId: string;
+    actorUserId?: string | null;
+    operationKey?: string;
+}): Promise<ScheduledTaskExecutionResult>;
+export declare function scheduleModerationThreadRetry(services: ServiceAccess, input: {
+    guildId: string;
+    caseId: string;
+    operationKey: string;
+}): Promise<void>;
+export declare function reconcileDashboardCase(input: {
+    guildId: string;
+    caseId: string;
+    expectedRevision: number;
+    actorUserId: string;
+    operationKey: string;
+    services: ServiceAccess;
+}): Promise<void>;
+//# sourceMappingURL=tasks.d.ts.map