@helyx/module-account-gate 1.0.14 → 1.1.1

package/dist/task-scheduling.js

@@ -0,0 +1,79 @@
+import { HELYX_SERVICE_NAMES, ACCOUNT_GATE_IDENTITY, JOIN_DEADLINE_TASK, SESSION_EXPIRY_TASK, REVIEW_DELIVERY_TASK, TERMINAL_FINALIZATION_TASK, } from "./runtime-dependencies.js";
+export async function scheduleJoinDeadline(services, guildId, memberUserId, generation, deadlineAt) {
+    await services
+        .get(HELYX_SERVICE_NAMES.scheduledTasks)
+        .schedule({
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        taskKind: JOIN_DEADLINE_TASK,
+        guildId,
+        idempotencyKey: `${guildId}:${memberUserId}:join:${generation}`,
+        payload: {
+            guildId,
+            memberUserId,
+        },
+        scheduledFor: deadlineAt,
+    });
+}
+export async function scheduleSessionExpiry(services, input) {
+    await services
+        .get(HELYX_SERVICE_NAMES.scheduledTasks)
+        .schedule({
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        taskKind: SESSION_EXPIRY_TASK,
+        guildId: input.guildId,
+        idempotencyKey: `${input.sessionId}:expiry`,
+        payload: {
+            guildId: input.guildId,
+            userId: input.userId,
+            sessionId: input.sessionId,
+        },
+        scheduledFor: input.expiredAt,
+    });
+}
+export async function scheduleReviewDelivery(services, guildId, reviewId, scheduledFor) {
+    await services
+        .get(HELYX_SERVICE_NAMES.scheduledTasks)
+        .schedule({
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        taskKind: REVIEW_DELIVERY_TASK,
+        guildId,
+        idempotencyKey: `${guildId}:${reviewId}:delivery`,
+        payload: { guildId, reviewId },
+        scheduledFor,
+    });
+}
+export async function scheduleTerminalFinalization(services, guildId, finalizationId, scheduledFor) {
+    await services
+        .get(HELYX_SERVICE_NAMES.scheduledTasks)
+        .schedule({
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        taskKind: TERMINAL_FINALIZATION_TASK,
+        guildId,
+        idempotencyKey: `${guildId}:${finalizationId}:terminal`,
+        payload: { guildId, finalizationId },
+        scheduledFor,
+    });
+}
+export async function armRecordRetention(records, guildId, collection, idField, id, scheduledFor) {
+    await records.updateOne({
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        collection,
+        where: { [idField]: id },
+        expected: { field: idField, value: id },
+        values: { retention_until: scheduledFor },
+        retention: [
+            {
+                collection,
+                where: { guild_id: guildId, [idField]: id },
+                scheduledFor,
+                idempotencyKey: `account-gate-retention:${collection}:${id}`,
+                audit: {
+                    action: `account_gate.${collection}_retention`,
+                    targetType: `account_gate_${collection}`,
+                    targetId: id,
+                },
+            },
+        ],
+    });
+}
+//# sourceMappingURL=task-scheduling.js.map

package/dist/terminal-finalization.d.ts

@@ -0,0 +1,12 @@
+import type { ModuleRecordService, RuntimeContext, ScheduledTaskPayload, ServiceAccess, AccountGateSessionState, AccountGateConfiguration } from "./runtime-dependencies.js";
+export declare function ensureTerminalFinalization(services: ServiceAccess, guildId: string, memberUserId: string, sessionId: string, state: AccountGateSessionState, outcome: "passed" | "failed"): Promise<boolean>;
+export declare function validateTerminalFinalizationPayload(input: unknown): ScheduledTaskPayload;
+export declare function runTerminalFinalizationTask(context: RuntimeContext, task: {
+    payload: ScheduledTaskPayload;
+}): Promise<{
+    outcome: "completed";
+}>;
+export declare function finalizeTerminalFinalization(services: ServiceAccess, guildId: string, finalizationId: string): Promise<void>;
+export declare function finishTerminalRecord(records: ModuleRecordService, row: Readonly<Record<string, unknown>>, status: "completed" | "cancelled"): Promise<void>;
+export declare function applyDurableFailureAction(services: ServiceAccess, configuration: AccountGateConfiguration, guildId: string, memberUserId: string, generation: number, terminal: Readonly<Record<string, unknown>>): Promise<void>;
+//# sourceMappingURL=terminal-finalization.d.ts.map

package/dist/terminal-finalization.js

@@ -0,0 +1,238 @@
+import { HELYX_SERVICE_NAMES, ACCOUNT_GATE_IDENTITY, ACCOUNT_GATE_SESSION_PURPOSE, applyRoleTransition, neutralKickDirectMessage, accountGateRecords, isAccountGateWorkSuppressed, emitAccountGateCompletedLog, emitAccountGateKickLog, successfulKickOutcome, VIOLET, TERMINAL_FINALIZATION_TASK, RETENTION_MS, } from "./runtime-dependencies.js";
+import { loadMemberSummary, markSummaryPassed, recordFailureSummary, setSummaryDecision, } from "./member-summary.js";
+import { createReview } from "./review-store.js";
+import { compensateVerifiedRoleAddition, terminalPassStillCurrent, } from "./workflow-fences.js";
+import { persistPartialTransition } from "./role-recovery.js";
+import { dateValue, numberValue, stringValue } from "./runtime-support.js";
+import { requiredRuntimeConfiguration } from "./setup-presentation.js";
+import { armRecordRetention, scheduleTerminalFinalization, } from "./task-scheduling.js";
+export async function ensureTerminalFinalization(services, guildId, memberUserId, sessionId, state, outcome) {
+    const records = services.get(HELYX_SERVICE_NAMES.records);
+    const summary = await loadMemberSummary(records, guildId, memberUserId);
+    if (!summary ||
+        !["pending", "finalizing"].includes(stringValue(summary.last_decision)))
+        return false;
+    const generation = state.joinGeneration;
+    if (numberValue(summary.join_generation) !== generation)
+        return false;
+    const challenge = outcome === "passed" ? state.chain.at(-1) : state.chain[state.currentStep];
+    if (!challenge)
+        return false;
+    const now = new Date();
+    const retentionUntil = new Date(now.getTime() + RETENTION_MS);
+    const created = await records.appendUnique({
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        collection: "terminal_finalizations",
+        uniqueBy: ["guild_id", "session_id"],
+        values: {
+            finalization_id: sessionId,
+            guild_id: guildId,
+            member_user_id: memberUserId,
+            session_id: sessionId,
+            join_generation: generation,
+            outcome,
+            challenge_type: challenge.type,
+            challenge_types_json: JSON.stringify(state.chain.map(({ type }) => type)),
+            work_created_at: new Date(state.startedAt),
+            status: "pending",
+            revision: 1,
+            retention_until: retentionUntil,
+            created_at: now,
+            updated_at: now,
+        },
+    });
+    if (created.created)
+        await armRecordRetention(records, guildId, "terminal_finalizations", "finalization_id", sessionId, retentionUntil);
+    if (summary.last_decision === "pending") {
+        const revision = numberValue(summary.revision);
+        const claimed = await records.updateOne({
+            moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+            collection: "member_summaries",
+            where: { guild_id: guildId, member_user_id: memberUserId },
+            expected: { field: "revision", value: revision },
+            values: {
+                last_decision: "finalizing",
+                revision: revision + 1,
+                updated_at: now,
+            },
+            schedule: {
+                taskKind: TERMINAL_FINALIZATION_TASK,
+                guildId,
+                idempotencyKey: `${guildId}:${sessionId}:terminal`,
+                payload: { guildId, finalizationId: sessionId },
+                scheduledFor: now,
+            },
+        });
+        if (!claimed.updated)
+            return false;
+    }
+    else {
+        await scheduleTerminalFinalization(services, guildId, sessionId, now);
+    }
+    return true;
+}
+export function validateTerminalFinalizationPayload(input) {
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        throw new Error("Account Gate terminal-finalization payload is invalid");
+    const value = input;
+    if (typeof value.guildId !== "string" ||
+        typeof value.finalizationId !== "string" ||
+        value.finalizationId.length > 100)
+        throw new Error("Account Gate terminal-finalization payload is invalid");
+    return {
+        guildId: value.guildId,
+        finalizationId: value.finalizationId,
+    };
+}
+export async function runTerminalFinalizationTask(context, task) {
+    await finalizeTerminalFinalization(context.services, task.payload.guildId, task.payload.finalizationId);
+    return { outcome: "completed" };
+}
+export async function finalizeTerminalFinalization(services, guildId, finalizationId) {
+    const records = services.get(HELYX_SERVICE_NAMES.records);
+    const row = await records.findOne({
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        collection: "terminal_finalizations",
+        select: accountGateRecords.terminal_finalizations.readableFields,
+        where: { guild_id: guildId, finalization_id: finalizationId },
+    });
+    if (!row || ["completed", "cancelled"].includes(stringValue(row.status)))
+        return;
+    const memberUserId = stringValue(row.member_user_id);
+    const generation = numberValue(row.join_generation);
+    const summary = await loadMemberSummary(records, guildId, memberUserId);
+    const enabled = await services
+        .get(HELYX_SERVICE_NAMES.installations)
+        .isModuleEnabled(guildId, ACCOUNT_GATE_IDENTITY.moduleId);
+    if (!enabled ||
+        !summary ||
+        numberValue(summary.join_generation) !== generation ||
+        !["finalizing", "failed", "passed", "review"].includes(stringValue(summary.last_decision)) ||
+        (await isAccountGateWorkSuppressed(services, guildId, memberUserId, dateValue(row.work_created_at) ?? new Date(0)))) {
+        await finishTerminalRecord(records, row, "cancelled");
+        return;
+    }
+    const configuration = await requiredRuntimeConfiguration(services, guildId);
+    const sessions = services.get(HELYX_SERVICE_NAMES.sessions);
+    if (row.outcome === "passed") {
+        if (summary.last_decision === "passed") {
+            await emitAccountGateCompletedLog(services, guildId, {
+                memberUserId,
+                roleOutcome: "already_applied",
+                idempotencyKey: `account-gate-completed:${finalizationId}`,
+            });
+            await sessions.delete(stringValue(row.session_id));
+            await finishTerminalRecord(records, row, "completed");
+            return;
+        }
+        const transition = await applyRoleTransition({
+            guildId,
+            memberUserId,
+            verifiedRoleId: configuration.verifiedRoleId,
+            temporaryRoleIds: configuration.temporaryRoleIds,
+            resources: services.get(HELYX_SERVICE_NAMES.discordResources),
+            roles: services.get(HELYX_SERVICE_NAMES.memberRoles),
+            revalidate: () => terminalPassStillCurrent(services, guildId, memberUserId, generation, dateValue(row.work_created_at) ?? new Date(0)),
+        });
+        if (transition.outcome === "stale") {
+            await finishTerminalRecord(records, row, "cancelled");
+            return;
+        }
+        if (transition.outcome === "blocked") {
+            await setSummaryDecision(records, guildId, memberUserId, generation, "review", "finalizing");
+            await createReview(services, guildId, memberUserId, "role_assignment_failed", null, generation, JSON.parse(stringValue(row.challenge_types_json)), dateValue(row.work_created_at) ?? new Date(0));
+        }
+        else {
+            if (transition.outcome === "partial")
+                await persistPartialTransition(services, guildId, memberUserId, configuration.verifiedRoleId, transition.pendingRoleIds, dateValue(row.work_created_at) ?? new Date(0));
+            if (!(await markSummaryPassed(records, guildId, memberUserId, new Date(), generation))) {
+                await compensateVerifiedRoleAddition(services, guildId, memberUserId, configuration.verifiedRoleId, transition);
+                await finishTerminalRecord(records, row, "cancelled");
+                return;
+            }
+            await emitAccountGateCompletedLog(services, guildId, {
+                memberUserId,
+                roleOutcome: transition.outcome,
+                idempotencyKey: `account-gate-completed:${finalizationId}`,
+            });
+        }
+    }
+    else {
+        const failures = await recordFailureSummary(records, guildId, memberUserId, new Date(), configuration.retryCooldownSeconds, configuration.attempts, finalizationId, generation);
+        if (failures === null) {
+            await finishTerminalRecord(records, row, "cancelled");
+            return;
+        }
+        await sessions.delete(stringValue(row.session_id));
+        if (failures >= configuration.attempts)
+            await applyDurableFailureAction(services, configuration, guildId, memberUserId, generation, row);
+    }
+    await sessions.delete(stringValue(row.session_id));
+    await finishTerminalRecord(records, row, "completed");
+}
+export async function finishTerminalRecord(records, row, status) {
+    const revision = numberValue(row.revision);
+    await records.updateOne({
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        collection: "terminal_finalizations",
+        where: { finalization_id: stringValue(row.finalization_id) },
+        expected: { field: "revision", value: revision },
+        values: { status, revision: revision + 1, updated_at: new Date() },
+    });
+}
+export async function applyDurableFailureAction(services, configuration, guildId, memberUserId, generation, terminal) {
+    if (configuration.failureAction === "review") {
+        await createReview(services, guildId, memberUserId, "attempt_limit_reached", null, generation, JSON.parse(stringValue(terminal.challenge_types_json)), dateValue(terminal.work_created_at) ?? new Date(0));
+        return;
+    }
+    if (configuration.failureAction !== "kick")
+        return;
+    const records = services.get(HELYX_SERVICE_NAMES.records);
+    const result = await services
+        .get(HELYX_SERVICE_NAMES.memberEnforcement)
+        .kick({
+        guildId,
+        memberUserId,
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        reason: "Access Control final failure",
+        directMessage: {
+            embed: {
+                title: "Removed after incomplete Access Control",
+                description: neutralKickDirectMessage(`Discord server ${guildId}`),
+                color: VIOLET,
+            },
+        },
+        revalidate: async () => {
+            const [enabled, summary, session] = await Promise.all([
+                services
+                    .get(HELYX_SERVICE_NAMES.installations)
+                    .isModuleEnabled(guildId, ACCOUNT_GATE_IDENTITY.moduleId),
+                loadMemberSummary(records, guildId, memberUserId),
+                services
+                    .get(HELYX_SERVICE_NAMES.sessions)
+                    .getFor(guildId, memberUserId, ACCOUNT_GATE_SESSION_PURPOSE),
+            ]);
+            if (!enabled || session !== null || !summary)
+                return false;
+            if (numberValue(summary.join_generation) !== generation ||
+                summary.last_decision !== "failed")
+                return false;
+            try {
+                await requiredRuntimeConfiguration(services, guildId);
+            }
+            catch {
+                return false;
+            }
+            return !(await isAccountGateWorkSuppressed(services, guildId, memberUserId, dateValue(terminal.work_created_at) ?? new Date(0)));
+        },
+    });
+    if (["kicked", "member_missing"].includes(result.outcome))
+        await emitAccountGateKickLog(services, guildId, {
+            memberUserId,
+            outcome: successfulKickOutcome(result.outcome),
+            directMessage: result.directMessage,
+            source: "Failed check",
+            idempotencyKey: `account-gate-kick:terminal:${stringValue(terminal.finalization_id)}`,
+        });
+}
+//# sourceMappingURL=terminal-finalization.js.map

package/dist/workflow-fences.d.ts

@@ -0,0 +1,6 @@
+import type { RoleTransitionResult, ServiceAccess } from "./runtime-dependencies.js";
+export declare function reviewStillCurrent(services: ServiceAccess, guildId: string, memberUserId: string, joinGeneration: number, verifiedRoleId: string, allowVerifiedRole?: boolean): Promise<boolean>;
+export declare function terminalPassStillCurrent(services: ServiceAccess, guildId: string, memberUserId: string, joinGeneration: number, workCreatedAt: Date): Promise<boolean>;
+export declare function compensateVerifiedRoleAddition(services: ServiceAccess, guildId: string, memberUserId: string, verifiedRoleId: string, transition: RoleTransitionResult): Promise<void>;
+export declare function roleRetryStillCurrent(services: ServiceAccess, guildId: string, memberUserId: string, workCreatedAt: Date): Promise<boolean>;
+//# sourceMappingURL=workflow-fences.d.ts.map

package/dist/workflow-fences.js

@@ -0,0 +1,73 @@
+import { HELYX_SERVICE_NAMES, ACCOUNT_GATE_IDENTITY, isAccountGateWorkSuppressed, } from "./runtime-dependencies.js";
+import { loadMemberSummary } from "./member-summary.js";
+import { numberValue, stringValue } from "./runtime-support.js";
+export async function reviewStillCurrent(services, guildId, memberUserId, joinGeneration, verifiedRoleId, allowVerifiedRole = false) {
+    const [enabled, summary, members] = await Promise.all([
+        services
+            .get(HELYX_SERVICE_NAMES.installations)
+            .isModuleEnabled(guildId, ACCOUNT_GATE_IDENTITY.moduleId),
+        loadMemberSummary(services.get(HELYX_SERVICE_NAMES.records), guildId, memberUserId),
+        services
+            .get(HELYX_SERVICE_NAMES.discordResources)
+            .resolveMemberSnapshots({ guildId, userIds: [memberUserId] }),
+    ]);
+    const member = members[0];
+    return (enabled &&
+        summary !== null &&
+        numberValue(summary.join_generation) === joinGeneration &&
+        ["review", "failed", "finalizing"].includes(stringValue(summary.last_decision)) &&
+        member?.exists === true &&
+        !member.isBot &&
+        (allowVerifiedRole || !member.roleIds.includes(verifiedRoleId)));
+}
+export async function terminalPassStillCurrent(services, guildId, memberUserId, joinGeneration, workCreatedAt) {
+    const [enabled, summary, members, suppressed] = await Promise.all([
+        services
+            .get(HELYX_SERVICE_NAMES.installations)
+            .isModuleEnabled(guildId, ACCOUNT_GATE_IDENTITY.moduleId),
+        loadMemberSummary(services.get(HELYX_SERVICE_NAMES.records), guildId, memberUserId),
+        services
+            .get(HELYX_SERVICE_NAMES.discordResources)
+            .resolveMemberSnapshots({ guildId, userIds: [memberUserId] }),
+        isAccountGateWorkSuppressed(services, guildId, memberUserId, workCreatedAt),
+    ]);
+    const member = members[0];
+    return (enabled &&
+        !suppressed &&
+        summary !== null &&
+        numberValue(summary.join_generation) === joinGeneration &&
+        summary.last_decision === "finalizing" &&
+        member?.exists === true &&
+        !member.isBot);
+}
+export async function compensateVerifiedRoleAddition(services, guildId, memberUserId, verifiedRoleId, transition) {
+    if (!transition.accessRoleAdded)
+        return;
+    await services
+        .get(HELYX_SERVICE_NAMES.memberRoles)
+        .removeApprovedRole({
+        guildId,
+        memberUserId,
+        roleId: verifiedRoleId,
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        reason: "Access Control stale-generation compensation",
+    });
+}
+export async function roleRetryStillCurrent(services, guildId, memberUserId, workCreatedAt) {
+    const [enabled, summary, members, suppressed] = await Promise.all([
+        services
+            .get(HELYX_SERVICE_NAMES.installations)
+            .isModuleEnabled(guildId, ACCOUNT_GATE_IDENTITY.moduleId),
+        loadMemberSummary(services.get(HELYX_SERVICE_NAMES.records), guildId, memberUserId),
+        services
+            .get(HELYX_SERVICE_NAMES.discordResources)
+            .resolveMemberSnapshots({ guildId, userIds: [memberUserId] }),
+        isAccountGateWorkSuppressed(services, guildId, memberUserId, workCreatedAt),
+    ]);
+    return (enabled &&
+        !suppressed &&
+        summary?.last_decision === "passed" &&
+        members[0]?.exists === true &&
+        !members[0].isBot);
+}
+//# sourceMappingURL=workflow-fences.js.map

package/manifest.json

@@ -1,9 +1,16 @@
 {
-  "manifestVersion": "0.2",
+  "manifestVersion": "0.4",
   "releaseStatus": "live",
+  "deploymentSupport": "both",
+  "credentialRisk": "none",
+  "deploymentReason": "Uses only the Helyx runtime and Discord capabilities available in hosted and self-hosted installations.",
+  "moduleKind": "customer_feature",
+  "customerSelectable": true,
+  "countsAsInstalledModule": true,
+  "healthExposure": "direct",
   "id": "helyx.account-gate",
   "name": "Access Control",
-  "version": "1.0.14",
+  "version": "1.1.1",
   "description": "Require new members to complete configurable Discord interaction checks before gaining access.",
   "entry": "./dist/index.js",
   "framework": "^0.1.0",

package/migrations/0002_panel_mutation_claims.sql

@@ -0,0 +1,34 @@
+ALTER TABLE account_gate_gate_panels
+  ADD COLUMN IF NOT EXISTS status TEXT NOT NULL DEFAULT 'posted';
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+    FROM pg_constraint
+    WHERE conname = 'account_gate_gate_panels_status'
+      AND conrelid = 'account_gate_gate_panels'::regclass
+  ) THEN
+    ALTER TABLE account_gate_gate_panels
+      ADD CONSTRAINT account_gate_gate_panels_status
+      CHECK (status IN ('posted', 'missing'));
+  END IF;
+END;
+$$;
+
+CREATE TABLE IF NOT EXISTS account_gate_panel_message_cleanup (
+  cleanup_id TEXT PRIMARY KEY,
+  guild_id TEXT NOT NULL,
+  panel_id TEXT NOT NULL,
+  channel_id TEXT NOT NULL,
+  message_id TEXT NOT NULL,
+  attempts INTEGER NOT NULL DEFAULT 0 CHECK (attempts >= 0),
+  next_attempt_at TIMESTAMPTZ NOT NULL,
+  completed_at TIMESTAMPTZ,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  UNIQUE (guild_id, channel_id, message_id)
+);
+
+CREATE INDEX IF NOT EXISTS account_gate_panel_cleanup_pending_idx
+  ON account_gate_panel_message_cleanup (next_attempt_at, cleanup_id)
+  WHERE completed_at IS NULL;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helyx/module-account-gate",
-  "version": "1.0.14",
+  "version": "1.1.1",
   "description": "Require configurable Discord interaction checks before new members gain access.",
   "keywords": [
     "helyx",
@@ -45,10 +45,11 @@
     "./package.json": "./package.json"
   },
   "scripts": {
-    "build": "tsc -b"
+    "build": "tsc -b",
+    "test": "vitest run --root ../.. modules/account-gate/tests"
   },
   "dependencies": {
-    "@helyx/module-manifest": ">=0.7.0 <0.8.0",
-    "@helyx/sdk": ">=0.8.4 <0.9.0"
+    "@helyx/module-manifest": ">=0.8.0 <0.9.0",
+    "@helyx/sdk": ">=0.10.0"
   }
 }