@helyx/module-account-gate 1.0.14 → 1.1.1

package/dist/review-store.js

@@ -0,0 +1,94 @@
+import { randomUUID, HELYX_SERVICE_NAMES, ACCOUNT_GATE_IDENTITY, isAccountGateWorkSuppressed, emitLog, REVIEW_DELIVERY_TASK, RETENTION_MS, } from "./runtime-dependencies.js";
+import { loadMemberSummary } from "./member-summary.js";
+import { dateValue, numberValue, stringValue } from "./runtime-support.js";
+import { armRecordRetention, scheduleReviewDelivery, } from "./task-scheduling.js";
+export async function createReview(services, guildId, memberUserId, reasonCode, state, expectedJoinGeneration, boundedChallengeTypes, workCreatedAtOverride) {
+    const records = services.get(HELYX_SERVICE_NAMES.records);
+    const summary = await loadMemberSummary(records, guildId, memberUserId);
+    if (!summary)
+        return;
+    const joinGeneration = numberValue(summary.join_generation);
+    if (expectedJoinGeneration !== undefined &&
+        joinGeneration !== expectedJoinGeneration)
+        return;
+    const workCreatedAt = workCreatedAtOverride ?? (state ? new Date(state.startedAt) : new Date());
+    if (await isAccountGateWorkSuppressed(services, guildId, memberUserId, workCreatedAt))
+        return;
+    const now = new Date();
+    const retentionUntil = new Date(now.getTime() + RETENTION_MS);
+    const reviewId = randomUUID();
+    const created = await records.appendUnique({
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        collection: "reviews",
+        uniqueBy: ["pending_key"],
+        values: {
+            review_id: reviewId,
+            pending_key: `pending:${guildId}:${memberUserId}`,
+            guild_id: guildId,
+            member_user_id: memberUserId,
+            join_generation: joinGeneration,
+            status: "pending",
+            delivery_status: "pending",
+            reason_code: reasonCode,
+            challenge_types_json: JSON.stringify(boundedChallengeTypes ?? state?.chain.map(({ type }) => type) ?? []),
+            failed_attempts: 0,
+            expired_attempts: 0,
+            revision: 1,
+            retention_until: retentionUntil,
+            created_at: now,
+            updated_at: now,
+        },
+        schedule: {
+            taskKind: REVIEW_DELIVERY_TASK,
+            guildId,
+            idempotencyKey: `${guildId}:${reviewId}:delivery`,
+            payload: { guildId, reviewId },
+            scheduledFor: now,
+        },
+    });
+    if (created.created)
+        await armRecordRetention(records, guildId, "reviews", "review_id", reviewId, retentionUntil);
+    const pending = created.created
+        ? { review_id: reviewId }
+        : await records.findOne({
+            moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+            collection: "reviews",
+            select: ["review_id", "delivery_status"],
+            where: { pending_key: `pending:${guildId}:${memberUserId}` },
+        });
+    if (!created.created && pending && pending.delivery_status !== "sent")
+        await scheduleReviewDelivery(services, guildId, stringValue(pending.review_id), now);
+    await emitLog(services, guildId, {
+        eventId: "account-gate-review-created",
+        summary: "An Access Control check requires staff review.",
+        details: [
+            { label: "Member ID", value: memberUserId },
+            { label: "Reason", value: reasonCode },
+        ],
+    });
+}
+export async function finalizeReviewClaim(records, guildId, reviewId, claimRevision, status, row, expiredOnly = true) {
+    const now = new Date();
+    return (await records.updateOne({
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        collection: "reviews",
+        where: { guild_id: guildId, review_id: reviewId },
+        expected: { field: "revision", value: claimRevision },
+        ...(expiredOnly
+            ? { dateAtOrBeforeNow: { field: "claim_expires_at" } }
+            : {}),
+        values: {
+            pending_key: `resolved:${reviewId}`,
+            status,
+            claim_action: "",
+            claim_expires_at: new Date(0),
+            decided_by_user_id: typeof row.decided_by_user_id === "string"
+                ? row.decided_by_user_id
+                : "system",
+            decided_at: dateValue(row.decided_at) ?? now,
+            revision: claimRevision + 1,
+            updated_at: now,
+        },
+    })).updated;
+}
+//# sourceMappingURL=review-store.js.map

package/dist/role-recovery.d.ts

@@ -0,0 +1,23 @@
+import type { RuntimeContext, ScheduledTaskPayload, ServiceAccess } from "./runtime-dependencies.js";
+export declare function validateRoleRetryPayload(input: unknown): ScheduledTaskPayload;
+export declare function retryRoleTransition(context: RuntimeContext, task: {
+    payload: ScheduledTaskPayload;
+}): Promise<{
+    outcome: "completed";
+    safeCode?: never;
+    delayMs?: never;
+} | {
+    outcome: "requires_review";
+    safeCode: string;
+    delayMs?: never;
+} | {
+    outcome: "deferred";
+    delayMs: number;
+    safeCode: string;
+} | {
+    outcome: "retry";
+    delayMs: number;
+    safeCode: string;
+}>;
+export declare function persistPartialTransition(services: ServiceAccess, guildId: string, memberUserId: string, verifiedRoleId: string, pendingRoleIds: readonly string[], workCreatedAt?: Date): Promise<void>;
+//# sourceMappingURL=role-recovery.d.ts.map

package/dist/role-recovery.js

@@ -0,0 +1,176 @@
+import { randomUUID, HELYX_SERVICE_NAMES, ACCOUNT_GATE_IDENTITY, applyRoleTransition, accountGateRecords, isAccountGateWorkSuppressed, ROLE_RETRY_TASK, } from "./runtime-dependencies.js";
+import { roleRetryStillCurrent } from "./workflow-fences.js";
+import { dateValue, numberValue, stringValue } from "./runtime-support.js";
+export function validateRoleRetryPayload(input) {
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        throw new Error("Account Gate role retry payload is invalid");
+    const value = input;
+    if (typeof value.guildId !== "string" ||
+        typeof value.transitionId !== "string" ||
+        value.transitionId.length > 100)
+        throw new Error("Account Gate role retry payload is invalid");
+    return { guildId: value.guildId, transitionId: value.transitionId };
+}
+export async function retryRoleTransition(context, task) {
+    const records = context.services.get(HELYX_SERVICE_NAMES.records);
+    const row = await records.findOne({
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        collection: "role_transitions",
+        select: accountGateRecords.role_transitions.readableFields,
+        where: {
+            guild_id: task.payload.guildId,
+            transition_id: task.payload.transitionId,
+        },
+    });
+    if (!row || row.status === "completed")
+        return { outcome: "completed" };
+    if (row.status === "review")
+        return {
+            outcome: "requires_review",
+            safeCode: "role-transition-blocked",
+        };
+    if (await isAccountGateWorkSuppressed(context.services, stringValue(row.guild_id), stringValue(row.member_user_id), dateValue(row.created_at) ?? new Date(0)))
+        return { outcome: "completed" };
+    const now = new Date();
+    const nextRetryAt = dateValue(row.next_retry_at);
+    if (nextRetryAt && nextRetryAt.getTime() > now.getTime())
+        return {
+            outcome: "deferred",
+            delayMs: Math.max(100, nextRetryAt.getTime() - now.getTime()),
+            safeCode: "role-transition-not-due",
+        };
+    const revision = numberValue(row.revision);
+    const claimExpiresAt = new Date(now.getTime() + 2 * 60_000);
+    const claimed = await records.updateOne({
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        collection: "role_transitions",
+        where: { transition_id: task.payload.transitionId },
+        expected: { field: "revision", value: revision },
+        ...(nextRetryAt ? { dateAtOrBeforeNow: { field: "next_retry_at" } } : {}),
+        values: {
+            status: "pending",
+            revision: revision + 1,
+            next_retry_at: claimExpiresAt,
+            updated_at: now,
+        },
+    });
+    if (!claimed.updated)
+        return {
+            outcome: "retry",
+            delayMs: 5_000,
+            safeCode: "role-transition-claim-conflict",
+        };
+    const claimRevision = revision + 1;
+    const transition = await applyRoleTransition({
+        guildId: stringValue(row.guild_id),
+        memberUserId: stringValue(row.member_user_id),
+        verifiedRoleId: stringValue(row.verified_role_id),
+        temporaryRoleIds: JSON.parse(stringValue(row.pending_remove_role_ids_json)),
+        resources: context.services.get(HELYX_SERVICE_NAMES.discordResources),
+        roles: context.services.get(HELYX_SERVICE_NAMES.memberRoles),
+        revalidate: () => roleRetryStillCurrent(context.services, stringValue(row.guild_id), stringValue(row.member_user_id), dateValue(row.created_at) ?? new Date(0)),
+    });
+    const finishedAt = new Date();
+    const finalized = await records.updateOne({
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        collection: "role_transitions",
+        where: { transition_id: task.payload.transitionId },
+        expected: { field: "revision", value: claimRevision },
+        values: {
+            pending_remove_role_ids_json: JSON.stringify(transition.pendingRoleIds),
+            status: ["completed", "stale"].includes(transition.outcome)
+                ? "completed"
+                : transition.outcome === "blocked"
+                    ? "review"
+                    : "partial",
+            revision: claimRevision + 1,
+            next_retry_at: transition.outcome === "partial"
+                ? new Date(finishedAt.getTime() + 30_000)
+                : new Date(0),
+            completed_at: ["completed", "stale"].includes(transition.outcome)
+                ? finishedAt
+                : new Date(0),
+            updated_at: finishedAt,
+        },
+    });
+    if (!finalized.updated)
+        return {
+            outcome: "retry",
+            delayMs: 5_000,
+            safeCode: "role-transition-finalize-conflict",
+        };
+    return transition.outcome === "partial"
+        ? {
+            outcome: "retry",
+            delayMs: 30_000,
+            safeCode: "role-removal-pending",
+        }
+        : transition.outcome === "blocked"
+            ? {
+                outcome: "requires_review",
+                safeCode: "role-transition-blocked",
+            }
+            : { outcome: "completed" };
+}
+export async function persistPartialTransition(services, guildId, memberUserId, verifiedRoleId, pendingRoleIds, workCreatedAt = new Date()) {
+    if (await isAccountGateWorkSuppressed(services, guildId, memberUserId, workCreatedAt))
+        return;
+    const now = new Date();
+    const records = services.get(HELYX_SERVICE_NAMES.records);
+    const existing = await records.findOne({
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        collection: "role_transitions",
+        select: accountGateRecords.role_transitions.readableFields,
+        where: { guild_id: guildId, member_user_id: memberUserId },
+    });
+    const id = existing ? stringValue(existing.transition_id) : randomUUID();
+    const revision = existing ? numberValue(existing.revision) + 1 : 1;
+    const scheduledFor = new Date(now.getTime() + 30_000);
+    const schedule = {
+        taskKind: ROLE_RETRY_TASK,
+        guildId,
+        idempotencyKey: `${guildId}:${memberUserId}:role-transition:${revision}`,
+        payload: { guildId, transitionId: id },
+        scheduledFor,
+    };
+    const stored = existing
+        ? await records.updateOne({
+            moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+            collection: "role_transitions",
+            where: { guild_id: guildId, transition_id: id },
+            expected: {
+                field: "revision",
+                value: numberValue(existing.revision),
+            },
+            values: {
+                verified_role_id: verifiedRoleId,
+                pending_remove_role_ids_json: JSON.stringify(pendingRoleIds),
+                status: "partial",
+                revision,
+                next_retry_at: scheduledFor,
+                updated_at: now,
+            },
+            schedule,
+        })
+        : await records.appendUnique({
+            moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+            collection: "role_transitions",
+            uniqueBy: ["guild_id", "member_user_id"],
+            values: {
+                transition_id: id,
+                guild_id: guildId,
+                member_user_id: memberUserId,
+                verified_role_id: verifiedRoleId,
+                pending_remove_role_ids_json: JSON.stringify(pendingRoleIds),
+                status: "partial",
+                revision,
+                next_retry_at: scheduledFor,
+                created_at: now,
+                updated_at: now,
+            },
+            schedule,
+        });
+    if (!("updated" in stored ? stored.updated : stored.created))
+        return;
+}
+//# sourceMappingURL=role-recovery.js.map

package/dist/runtime-dependencies.d.ts

@@ -0,0 +1,32 @@
+import { randomUUID } from "node:crypto";
+export { randomUUID };
+export { DashboardActionValidationError, HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+export type { CommandInteractionContext, DiscordResourceInspectionService, DiscordMessageService, DirectMessageOutcome, InteractionSessionService, InstallationService, MemberEnforcementService, MemberEnforcementOutcome, MemberRoleService, MessageReactionAddContext, MessageResponse, ModalCapableInteractionContext, ModalInteractionContext, ModuleConfigurationService, ModuleRecordService, ModuleRecordValue, PrivilegedMessageCreateContext, ResourceAuthorizationService, RuntimeContext, ScheduledTaskPayload, ScheduledTaskService, SecureRandomService, ServiceAccess, } from "@helyx/sdk";
+export { generateChallengeChain, validateServerQuestion, } from "./challenges.js";
+export { ACCOUNT_GATE_COMPONENTS, ACCOUNT_GATE_IDENTITY, ACCOUNT_GATE_SESSION_PURPOSE, } from "./contracts.js";
+export type { AccountGateSessionState, Challenge, RandomSource, ServerQuestion, } from "./contracts.js";
+export { generatedChallengePool, isStrictModeActive, parseAccountGateConfiguration, validateRuntimeCapabilities, } from "./configuration.js";
+export type { AccountGateConfiguration } from "./configuration.js";
+export { applyRoleTransition, neutralKickDirectMessage, } from "./enforcement.js";
+export type { RoleTransitionResult } from "./enforcement.js";
+export { verifyPasswordEntry } from "./password-entry.js";
+export { accountGateRecords } from "./records.js";
+export { getGatePanelRuntime, hasPasswordGatePanel } from "./panel-resource.js";
+export { isAccountGateWorkSuppressed } from "./privacy.js";
+export { applyChallengeAction, createAccountGateSessionState, parseAccountGateSessionState, rerollForAccessibility, } from "./workflow.js";
+export type { ChallengeAction, WorkflowResult } from "./workflow.js";
+export { emitAccountGateCompletedLog, emitAccountGateKickLog, emitLog, successfulKickOutcome, } from "./logging.js";
+export declare const VIOLET = 8141549;
+export declare const GREEN = 1483594;
+export declare const RED = 14427686;
+export declare const STRICT_EXPIRY_TASK = "account-gate.strict-expiry";
+export declare const ROLE_RETRY_TASK = "account-gate.role-transition-retry";
+export declare const JOIN_DEADLINE_TASK = "account-gate.join-deadline";
+export declare const SESSION_EXPIRY_TASK = "account-gate.session-expiry";
+export declare const REVIEW_DELIVERY_TASK = "account-gate.review-delivery";
+export declare const REVIEW_CLAIM_RECOVERY_TASK = "account-gate.review-claim-recovery";
+export declare const TERMINAL_FINALIZATION_TASK = "account-gate.terminal-finalization";
+export declare const LEAVE_RETENTION_TASK = "account-gate.leave-retention";
+export declare const REVOCATION_RECONCILE_TASK = "account-gate.revocation-reconcile";
+export declare const RETENTION_MS: number;
+//# sourceMappingURL=runtime-dependencies.d.ts.map

package/dist/runtime-dependencies.js

@@ -0,0 +1,27 @@
+import { randomUUID } from "node:crypto";
+export { randomUUID };
+export { DashboardActionValidationError, HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+export { generateChallengeChain, validateServerQuestion, } from "./challenges.js";
+export { ACCOUNT_GATE_COMPONENTS, ACCOUNT_GATE_IDENTITY, ACCOUNT_GATE_SESSION_PURPOSE, } from "./contracts.js";
+export { generatedChallengePool, isStrictModeActive, parseAccountGateConfiguration, validateRuntimeCapabilities, } from "./configuration.js";
+export { applyRoleTransition, neutralKickDirectMessage, } from "./enforcement.js";
+export { verifyPasswordEntry } from "./password-entry.js";
+export { accountGateRecords } from "./records.js";
+export { getGatePanelRuntime, hasPasswordGatePanel } from "./panel-resource.js";
+export { isAccountGateWorkSuppressed } from "./privacy.js";
+export { applyChallengeAction, createAccountGateSessionState, parseAccountGateSessionState, rerollForAccessibility, } from "./workflow.js";
+export { emitAccountGateCompletedLog, emitAccountGateKickLog, emitLog, successfulKickOutcome, } from "./logging.js";
+export const VIOLET = 0x7c3aed;
+export const GREEN = 0x16a34a;
+export const RED = 0xdc2626;
+export const STRICT_EXPIRY_TASK = "account-gate.strict-expiry";
+export const ROLE_RETRY_TASK = "account-gate.role-transition-retry";
+export const JOIN_DEADLINE_TASK = "account-gate.join-deadline";
+export const SESSION_EXPIRY_TASK = "account-gate.session-expiry";
+export const REVIEW_DELIVERY_TASK = "account-gate.review-delivery";
+export const REVIEW_CLAIM_RECOVERY_TASK = "account-gate.review-claim-recovery";
+export const TERMINAL_FINALIZATION_TASK = "account-gate.terminal-finalization";
+export const LEAVE_RETENTION_TASK = "account-gate.leave-retention";
+export const REVOCATION_RECONCILE_TASK = "account-gate.revocation-reconcile";
+export const RETENTION_MS = 90 * 24 * 60 * 60 * 1_000;
+//# sourceMappingURL=runtime-dependencies.js.map

package/dist/runtime-support.d.ts

@@ -0,0 +1,19 @@
+import type { MessageResponse, ServiceAccess, RandomSource } from "./runtime-dependencies.js";
+export declare function secureRandom(services: ServiceAccess): RandomSource;
+export declare function replyError(context: {
+    reply(response: MessageResponse): Promise<void>;
+}, description: string): Promise<void>;
+export declare function stringValue(value: unknown): string;
+export declare function numberValue(value: unknown): number;
+export declare function dateValue(value: unknown): Date | null;
+export declare function canonicalEmojiKey(value: string): string;
+export interface ComponentBinding {
+    sessionId: string;
+    version: bigint;
+    step: number;
+    value?: string;
+}
+export declare function boundComponentId(prefix: string, binding: ComponentBinding): string;
+export declare function parseComponentBinding(customId: string | undefined, prefix: string): ComponentBinding | null;
+export declare function staticResumeMessage(guildId: string, gateChannelId: string): MessageResponse;
+//# sourceMappingURL=runtime-support.d.ts.map

package/dist/runtime-support.js

@@ -0,0 +1,74 @@
+import { HELYX_SERVICE_NAMES, VIOLET, RED } from "./runtime-dependencies.js";
+export function secureRandom(services) {
+    const random = services.get(HELYX_SERVICE_NAMES.secureRandom);
+    return {
+        integer(maximumExclusive, operationContext) {
+            return random.boundedInteger({ maximumExclusive, operationContext })
+                .value;
+        },
+    };
+}
+export async function replyError(context, description) {
+    await context.reply({
+        ephemeral: true,
+        componentsV2: {
+            accentColor: RED,
+            text: [
+                { content: "## Account gate unavailable" },
+                { content: description, markdown: false },
+            ],
+        },
+    });
+}
+export function stringValue(value) {
+    if (typeof value !== "string")
+        throw new Error("Account Gate record is invalid");
+    return value;
+}
+export function numberValue(value) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value))
+        throw new Error("Account Gate record is invalid");
+    return value;
+}
+export function dateValue(value) {
+    return value instanceof Date ? value : null;
+}
+export function canonicalEmojiKey(value) {
+    if (/^(?:custom|unicode):/u.test(value))
+        return value.normalize("NFKC");
+    const custom = /^([A-Za-z0-9_]{2,32}):(\d{17,20})$/u.exec(value);
+    return custom ? `custom:${custom[2]}` : `unicode:${value.normalize("NFKC")}`;
+}
+export function boundComponentId(prefix, binding) {
+    return `${prefix}${binding.sessionId}:${String(binding.version)}:${binding.step}${binding.value === undefined ? "" : `:${binding.value}`}`;
+}
+export function parseComponentBinding(customId, prefix) {
+    if (!customId?.startsWith(prefix))
+        return null;
+    const [sessionId, version, step, value] = customId
+        .slice(prefix.length)
+        .split(":");
+    if (!sessionId ||
+        !version ||
+        !/^\d+$/u.test(version) ||
+        !step ||
+        !/^\d+$/u.test(step))
+        return null;
+    return {
+        sessionId,
+        version: BigInt(version),
+        step: Number(step),
+        ...(value === undefined ? {} : { value }),
+    };
+}
+export function staticResumeMessage(guildId, gateChannelId) {
+    return {
+        embed: {
+            title: "Continue your Access Control check",
+            description: `Your existing check for Discord server ${guildId} is ready to continue. Return to <#${gateChannelId}> and press **Start check** to resume it.`,
+            color: VIOLET,
+        },
+        allowedUserMentionIds: [],
+    };
+}
+//# sourceMappingURL=runtime-support.js.map

package/dist/setup-presentation.d.ts

@@ -0,0 +1,15 @@
+import type { MessageResponse, ServiceAccess, AccountGateSessionState, ServerQuestion, AccountGateConfiguration } from "./runtime-dependencies.js";
+export declare function configurationForPanel(configuration: AccountGateConfiguration, accessType: "challenges" | "password" | "emoji"): AccountGateConfiguration;
+export declare function reviewMessage(memberUserId: string, reasonCode: string): MessageResponse;
+export declare function validateAccountGateSetup(services: ServiceAccess, guildId: string, configuration: AccountGateConfiguration, throwOnError?: boolean, allowMissingPanel?: boolean): Promise<readonly string[]>;
+export declare function challengeMessage(state: AccountGateSessionState, binding: {
+    sessionId: string;
+    version: bigint;
+}, options?: {
+    redactRecallCode?: boolean;
+}): MessageResponse;
+export declare function loadQuestions(services: ServiceAccess, guildId: string): Promise<readonly ServerQuestion[]>;
+export declare function currentStrictMode(services: ServiceAccess, guildId: string): Promise<boolean>;
+export declare function getConfiguration(services: ServiceAccess, guildId: string): Promise<AccountGateConfiguration | null>;
+export declare function requiredRuntimeConfiguration(services: ServiceAccess, guildId: string): Promise<AccountGateConfiguration>;
+//# sourceMappingURL=setup-presentation.d.ts.map