@helyx/module-account-gate 1.0.1

package/dist/records.js

@@ -0,0 +1,456 @@
+export const accountGateRecords = {
+    gate_panels: {
+        table: "account_gate_gate_panels",
+        fields: {
+            panel_id: { type: "string" },
+            guild_id: { type: "string" },
+            channel_id: { type: "string" },
+            message_id: { type: "string" },
+            message_body: { type: "string" },
+            access_type: { type: "string" },
+            password_hash: { type: "string", optional: true },
+            password_ignore_case: { type: "boolean", optional: true },
+            password_trim_whitespace: { type: "boolean", optional: true },
+            revision: { type: "number" },
+            created_at: { type: "date" },
+            updated_at: { type: "date" },
+        },
+        uniqueKeys: [["panel_id"], ["guild_id", "panel_id"]],
+        readableFields: [
+            "panel_id",
+            "guild_id",
+            "channel_id",
+            "message_id",
+            "message_body",
+            "access_type",
+            "password_hash",
+            "password_ignore_case",
+            "password_trim_whitespace",
+            "revision",
+            "created_at",
+            "updated_at",
+        ],
+        writableFields: [
+            "channel_id",
+            "message_id",
+            "message_body",
+            "access_type",
+            "password_hash",
+            "password_ignore_case",
+            "password_trim_whitespace",
+            "revision",
+            "updated_at",
+        ],
+        orderKeys: [["guild_id", "created_at", "panel_id"]],
+    },
+    public_channels: {
+        table: "account_gate_public_channels",
+        fields: {
+            guild_id: { type: "string" },
+            channel_id: { type: "string" },
+            created_at: { type: "date" },
+        },
+        uniqueKeys: [["guild_id", "channel_id"]],
+        readableFields: ["guild_id", "channel_id", "created_at"],
+        orderKeys: [["guild_id", "channel_id"]],
+    },
+    questions: {
+        table: "account_gate_questions",
+        fields: {
+            question_id: { type: "string" },
+            guild_id: { type: "string" },
+            question_text: { type: "string" },
+            answers_json: { type: "string" },
+            correct_option_index: { type: "number" },
+            enabled: { type: "boolean" },
+            sort_order: { type: "number" },
+            revision: { type: "number" },
+            created_at: { type: "date" },
+            updated_at: { type: "date" },
+        },
+        uniqueKeys: [["question_id"], ["guild_id", "question_id"]],
+        readableFields: [
+            "question_id",
+            "guild_id",
+            "question_text",
+            "answers_json",
+            "correct_option_index",
+            "enabled",
+            "sort_order",
+            "revision",
+            "created_at",
+            "updated_at",
+        ],
+        writableFields: [
+            "question_text",
+            "answers_json",
+            "correct_option_index",
+            "enabled",
+            "sort_order",
+            "revision",
+            "updated_at",
+        ],
+        orderKeys: [["guild_id", "sort_order", "question_id"]],
+        searchableFields: ["question_text"],
+        groupableFields: ["guild_id", "enabled"],
+    },
+    question_creators: {
+        table: "account_gate_question_creators",
+        fields: {
+            attribution_id: { type: "string" },
+            question_id: { type: "string" },
+            guild_id: { type: "string" },
+            creator_user_id: { type: "string" },
+            created_at: { type: "date" },
+        },
+        uniqueKeys: [["attribution_id"], ["question_id"]],
+        readableFields: [
+            "attribution_id",
+            "question_id",
+            "guild_id",
+            "creator_user_id",
+            "created_at",
+        ],
+        orderKeys: [["creator_user_id", "created_at", "attribution_id"]],
+    },
+    password_secrets: {
+        table: "account_gate_password_secrets",
+        fields: {
+            guild_id: { type: "string" },
+            encoded_hash: { type: "string" },
+            ignore_case: { type: "boolean" },
+            trim_whitespace: { type: "boolean" },
+            revision: { type: "number" },
+            created_at: { type: "date" },
+            updated_at: { type: "date" },
+        },
+        uniqueKeys: [["guild_id"]],
+        readableFields: [
+            "guild_id",
+            "encoded_hash",
+            "ignore_case",
+            "trim_whitespace",
+            "revision",
+            "created_at",
+            "updated_at",
+        ],
+        writableFields: [
+            "encoded_hash",
+            "ignore_case",
+            "trim_whitespace",
+            "revision",
+            "updated_at",
+        ],
+        orderKeys: [["guild_id"]],
+    },
+    attempts: {
+        table: "account_gate_attempts",
+        fields: {
+            attempt_id: { type: "string" },
+            guild_id: { type: "string" },
+            member_user_id: { type: "string" },
+            session_id: { type: "string" },
+            challenge_type: { type: "string" },
+            outcome: { type: "string" },
+            reason_code: { type: "string" },
+            duration_ms: { type: "number" },
+            retention_until: { type: "date" },
+            created_at: { type: "date" },
+        },
+        uniqueKeys: [
+            ["attempt_id"],
+            ["guild_id", "attempt_id"],
+            ["guild_id", "session_id", "challenge_type"],
+        ],
+        readableFields: [
+            "attempt_id",
+            "guild_id",
+            "member_user_id",
+            "session_id",
+            "challenge_type",
+            "outcome",
+            "reason_code",
+            "duration_ms",
+            "retention_until",
+            "created_at",
+        ],
+        writableFields: ["retention_until"],
+        orderKeys: [["guild_id", "created_at", "attempt_id"]],
+        groupableFields: [
+            "guild_id",
+            "member_user_id",
+            "challenge_type",
+            "outcome",
+        ],
+    },
+    member_summaries: {
+        table: "account_gate_member_summaries",
+        fields: {
+            summary_id: { type: "string" },
+            guild_id: { type: "string" },
+            member_user_id: { type: "string" },
+            previous_success_at: { type: "date", optional: true },
+            failure_count: { type: "number" },
+            lockout_until: { type: "date", optional: true },
+            rejoin_count: { type: "number" },
+            join_generation: { type: "number" },
+            account_created_at: { type: "date" },
+            joined_at: { type: "date" },
+            deadline_at: { type: "date" },
+            pending_reason: { type: "string" },
+            last_failure_terminal_id: { type: "string", optional: true },
+            left_at: { type: "date", optional: true },
+            last_decision: { type: "string" },
+            revision: { type: "number" },
+            retention_until: { type: "date" },
+            created_at: { type: "date" },
+            updated_at: { type: "date" },
+        },
+        uniqueKeys: [["summary_id"], ["guild_id", "member_user_id"]],
+        readableFields: [
+            "summary_id",
+            "guild_id",
+            "member_user_id",
+            "previous_success_at",
+            "failure_count",
+            "lockout_until",
+            "rejoin_count",
+            "join_generation",
+            "account_created_at",
+            "joined_at",
+            "deadline_at",
+            "pending_reason",
+            "last_failure_terminal_id",
+            "left_at",
+            "last_decision",
+            "revision",
+            "retention_until",
+            "created_at",
+            "updated_at",
+        ],
+        writableFields: [
+            "previous_success_at",
+            "failure_count",
+            "lockout_until",
+            "rejoin_count",
+            "join_generation",
+            "account_created_at",
+            "joined_at",
+            "deadline_at",
+            "pending_reason",
+            "last_failure_terminal_id",
+            "left_at",
+            "last_decision",
+            "revision",
+            "retention_until",
+            "updated_at",
+        ],
+        orderKeys: [["guild_id", "member_user_id"]],
+        groupableFields: ["guild_id", "last_decision"],
+    },
+    reviews: {
+        table: "account_gate_reviews",
+        fields: {
+            review_id: { type: "string" },
+            pending_key: { type: "string" },
+            guild_id: { type: "string" },
+            member_user_id: { type: "string" },
+            join_generation: { type: "number" },
+            status: { type: "string" },
+            delivery_status: { type: "string" },
+            claim_action: { type: "string", optional: true },
+            claim_expires_at: { type: "date", optional: true },
+            reason_code: { type: "string" },
+            challenge_types_json: { type: "string" },
+            failed_attempts: { type: "number" },
+            expired_attempts: { type: "number" },
+            review_channel_id: { type: "string", optional: true },
+            review_message_id: { type: "string", optional: true },
+            decided_by_user_id: { type: "string", optional: true },
+            decided_at: { type: "date", optional: true },
+            revision: { type: "number" },
+            retention_until: { type: "date" },
+            created_at: { type: "date" },
+            updated_at: { type: "date" },
+        },
+        uniqueKeys: [["review_id"], ["pending_key"], ["guild_id", "review_id"]],
+        readableFields: [
+            "review_id",
+            "pending_key",
+            "guild_id",
+            "member_user_id",
+            "join_generation",
+            "status",
+            "delivery_status",
+            "claim_action",
+            "claim_expires_at",
+            "reason_code",
+            "challenge_types_json",
+            "failed_attempts",
+            "expired_attempts",
+            "review_channel_id",
+            "review_message_id",
+            "decided_by_user_id",
+            "decided_at",
+            "revision",
+            "retention_until",
+            "created_at",
+            "updated_at",
+        ],
+        writableFields: [
+            "pending_key",
+            "status",
+            "delivery_status",
+            "claim_action",
+            "claim_expires_at",
+            "review_channel_id",
+            "review_message_id",
+            "decided_by_user_id",
+            "decided_at",
+            "revision",
+            "retention_until",
+            "updated_at",
+        ],
+        orderKeys: [["guild_id", "created_at", "review_id"]],
+        searchableFields: ["member_user_id"],
+        groupableFields: ["guild_id", "status", "reason_code"],
+    },
+    terminal_finalizations: {
+        table: "account_gate_terminal_finalizations",
+        fields: {
+            finalization_id: { type: "string" },
+            guild_id: { type: "string" },
+            member_user_id: { type: "string" },
+            session_id: { type: "string" },
+            join_generation: { type: "number" },
+            outcome: { type: "string" },
+            challenge_type: { type: "string" },
+            challenge_types_json: { type: "string" },
+            work_created_at: { type: "date" },
+            status: { type: "string" },
+            revision: { type: "number" },
+            retention_until: { type: "date" },
+            created_at: { type: "date" },
+            updated_at: { type: "date" },
+        },
+        uniqueKeys: [["finalization_id"], ["guild_id", "session_id"]],
+        readableFields: [
+            "finalization_id",
+            "guild_id",
+            "member_user_id",
+            "session_id",
+            "join_generation",
+            "outcome",
+            "challenge_type",
+            "challenge_types_json",
+            "work_created_at",
+            "status",
+            "revision",
+            "retention_until",
+            "created_at",
+            "updated_at",
+        ],
+        writableFields: ["status", "revision", "retention_until", "updated_at"],
+        orderKeys: [["guild_id", "created_at", "finalization_id"]],
+        groupableFields: ["guild_id", "status", "outcome"],
+    },
+    role_transitions: {
+        table: "account_gate_role_transitions",
+        fields: {
+            transition_id: { type: "string" },
+            guild_id: { type: "string" },
+            member_user_id: { type: "string" },
+            verified_role_id: { type: "string" },
+            pending_remove_role_ids_json: { type: "string" },
+            status: { type: "string" },
+            revision: { type: "number" },
+            next_retry_at: { type: "date", optional: true },
+            completed_at: { type: "date", optional: true },
+            created_at: { type: "date" },
+            updated_at: { type: "date" },
+        },
+        uniqueKeys: [
+            ["transition_id"],
+            ["guild_id", "transition_id"],
+            ["guild_id", "member_user_id"],
+        ],
+        readableFields: [
+            "transition_id",
+            "guild_id",
+            "member_user_id",
+            "verified_role_id",
+            "pending_remove_role_ids_json",
+            "status",
+            "revision",
+            "next_retry_at",
+            "completed_at",
+            "created_at",
+            "updated_at",
+        ],
+        writableFields: [
+            "verified_role_id",
+            "pending_remove_role_ids_json",
+            "status",
+            "revision",
+            "next_retry_at",
+            "completed_at",
+            "updated_at",
+        ],
+        orderKeys: [["guild_id", "updated_at", "transition_id"]],
+        groupableFields: ["guild_id", "status"],
+    },
+    strict_modes: {
+        table: "account_gate_strict_modes",
+        fields: {
+            guild_id: { type: "string" },
+            status: { type: "string" },
+            ends_at: { type: "date" },
+            generation: { type: "number" },
+            activated_by_user_id: { type: "string", optional: true },
+            revision: { type: "number" },
+            created_at: { type: "date" },
+            updated_at: { type: "date" },
+        },
+        uniqueKeys: [["guild_id"]],
+        readableFields: [
+            "guild_id",
+            "status",
+            "ends_at",
+            "generation",
+            "activated_by_user_id",
+            "revision",
+            "created_at",
+            "updated_at",
+        ],
+        writableFields: [
+            "status",
+            "ends_at",
+            "generation",
+            "activated_by_user_id",
+            "revision",
+            "updated_at",
+        ],
+        orderKeys: [["guild_id"]],
+        groupableFields: ["status"],
+    },
+    privacy_suppressions: {
+        table: "account_gate_privacy_suppressions",
+        fields: {
+            suppression_id: { type: "string" },
+            guild_id: { type: "string" },
+            member_user_id: { type: "string" },
+            suppressed_at: { type: "date" },
+            created_at: { type: "date" },
+        },
+        uniqueKeys: [["suppression_id"], ["guild_id", "member_user_id"]],
+        readableFields: [
+            "suppression_id",
+            "guild_id",
+            "member_user_id",
+            "suppressed_at",
+            "created_at",
+        ],
+        orderKeys: [["guild_id", "member_user_id"]],
+    },
+};
+//# sourceMappingURL=records.js.map

package/dist/workflow.d.ts

@@ -0,0 +1,43 @@
+import type { AccountGateSessionState, Challenge, GeneratedChallengeType, RandomSource } from "./contracts.js";
+export type ChallengeAction = {
+    type: "option";
+    option: number;
+} | {
+    type: "sequence";
+    value: "red" | "blue" | "green";
+} | {
+    type: "recall";
+    value: string;
+} | {
+    type: "static-failed";
+    challenge: "password_entry" | "emoji_entry";
+} | {
+    type: "static-complete";
+    challenge: "password_entry" | "emoji_entry";
+};
+export type WorkflowResult = {
+    outcome: "advanced";
+    state: AccountGateSessionState;
+} | {
+    outcome: "progress";
+    state: AccountGateSessionState;
+} | {
+    outcome: "passed";
+    state: AccountGateSessionState;
+} | {
+    outcome: "failed";
+    state: AccountGateSessionState;
+} | {
+    outcome: "stale";
+    state: AccountGateSessionState;
+};
+export declare function createAccountGateSessionState(chain: readonly Challenge[], joinGeneration: number, startedAt?: Date, panelId?: string): AccountGateSessionState;
+export declare function applyChallengeAction(state: AccountGateSessionState, action: ChallengeAction): WorkflowResult;
+export declare function rerollForAccessibility(input: {
+    state: AccountGateSessionState;
+    enabledTypes: readonly GeneratedChallengeType[];
+    random: RandomSource;
+    operationContext: string;
+}): AccountGateSessionState | null;
+export declare function parseAccountGateSessionState(input: unknown): AccountGateSessionState;
+//# sourceMappingURL=workflow.d.ts.map

package/dist/workflow.js

@@ -0,0 +1,167 @@
+import { generateChallenge } from "./challenges.js";
+export function createAccountGateSessionState(chain, joinGeneration, startedAt = new Date(), panelId) {
+    if (chain.length < 1 || chain.length > 4) {
+        throw new Error("Access Control session requires one to four challenges");
+    }
+    if (!Number.isSafeInteger(joinGeneration) || joinGeneration < 1)
+        throw new Error("Access Control session requires a valid join generation");
+    if (panelId !== undefined &&
+        (panelId.length < 1 || panelId.length > 100 || panelId.includes(":")))
+        throw new Error("Access Control session requires a valid panel ID");
+    return {
+        schemaVersion: 1,
+        status: "active",
+        chain,
+        step: 0,
+        currentStep: 0,
+        accessibilityRerollUsed: false,
+        joinGeneration,
+        ...(panelId === undefined ? {} : { panelId }),
+        startedAt: startedAt.toISOString(),
+    };
+}
+export function applyChallengeAction(state, action) {
+    if (state.status !== "active")
+        return { outcome: "stale", state };
+    const challenge = state.chain[state.currentStep];
+    if (!challenge)
+        return { outcome: "stale", state };
+    const result = evaluate(challenge, action);
+    if (result.outcome === "stale")
+        return { outcome: "stale", state };
+    if (result.outcome === "failed") {
+        return {
+            outcome: "failed",
+            state: { ...state, status: "failed" },
+        };
+    }
+    if (result.outcome === "progress") {
+        const chain = [...state.chain];
+        chain[state.currentStep] = result.challenge;
+        return { outcome: "progress", state: { ...state, chain } };
+    }
+    const nextStep = state.currentStep + 1;
+    if (nextStep >= state.chain.length) {
+        return {
+            outcome: "passed",
+            state: {
+                ...state,
+                status: "passed",
+                step: nextStep,
+                currentStep: nextStep,
+            },
+        };
+    }
+    return {
+        outcome: "advanced",
+        state: { ...state, step: nextStep, currentStep: nextStep },
+    };
+}
+export function rerollForAccessibility(input) {
+    if (input.state.status !== "active" || input.state.accessibilityRerollUsed) {
+        return null;
+    }
+    const current = input.state.chain[input.state.currentStep];
+    if (!current)
+        return null;
+    const alreadyUsed = new Set(input.state.chain.map(({ type }) => type));
+    const candidates = input.enabledTypes.filter((type) => type !== current.type && !alreadyUsed.has(type));
+    if (candidates.length < 1)
+        return null;
+    const replacementType = candidates[input.random.integer(candidates.length, `${input.operationContext}:replacement`)];
+    const replacement = generateChallenge(replacementType, input.random, `${input.operationContext}:challenge`);
+    const chain = [...input.state.chain];
+    chain[input.state.currentStep] = replacement;
+    return {
+        ...input.state,
+        chain,
+        accessibilityRerollUsed: true,
+    };
+}
+export function parseAccountGateSessionState(input) {
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+        throw new Error("Access Control session state is invalid");
+    }
+    const state = input;
+    if (state.schemaVersion !== 1 ||
+        !["active", "passed", "failed", "cancelled"].includes(state.status ?? "") ||
+        !Array.isArray(state.chain) ||
+        state.chain.length < 1 ||
+        state.chain.length > 4 ||
+        !Number.isInteger(state.currentStep) ||
+        !Number.isInteger(state.step) ||
+        state.step !== state.currentStep ||
+        state.currentStep < 0 ||
+        state.currentStep > state.chain.length ||
+        typeof state.accessibilityRerollUsed !== "boolean" ||
+        !Number.isSafeInteger(state.joinGeneration) ||
+        state.joinGeneration < 1 ||
+        (state.panelId !== undefined &&
+            (typeof state.panelId !== "string" ||
+                state.panelId.length < 1 ||
+                state.panelId.length > 100 ||
+                state.panelId.includes(":"))) ||
+        typeof state.startedAt !== "string" ||
+        Number.isNaN(Date.parse(state.startedAt))) {
+        throw new Error("Access Control session state is invalid");
+    }
+    return state;
+}
+function evaluate(challenge, action) {
+    switch (challenge.type) {
+        case "quick_sum":
+        case "symbol_match":
+        case "server_question":
+            if (action.type !== "option")
+                return { outcome: "stale" };
+            return {
+                outcome: action.option === challenge.expectedOption ? "complete" : "failed",
+            };
+        case "number_order": {
+            if (action.type !== "option")
+                return { outcome: "stale" };
+            if (action.option !== challenge.expectedSequence[challenge.progress]) {
+                return { outcome: "failed" };
+            }
+            const progress = challenge.progress + 1;
+            return progress === challenge.expectedSequence.length
+                ? { outcome: "complete" }
+                : { outcome: "progress", challenge: { ...challenge, progress } };
+        }
+        case "button_sequence": {
+            if (action.type !== "sequence")
+                return { outcome: "stale" };
+            if (action.value !== challenge.expectedSequence[challenge.progress]) {
+                return { outcome: "failed" };
+            }
+            const progress = challenge.progress + 1;
+            return progress === challenge.expectedSequence.length
+                ? { outcome: "complete" }
+                : { outcome: "progress", challenge: { ...challenge, progress } };
+        }
+        case "modal_recall":
+            if (action.type !== "recall")
+                return { outcome: "stale" };
+            return {
+                outcome: normalizeRecall(action.value) ===
+                    normalizeRecall(challenge.expectedText)
+                    ? "complete"
+                    : "failed",
+            };
+        case "password_entry":
+        case "emoji_entry":
+            if (action.type === "static-failed" &&
+                action.challenge === challenge.type) {
+                return { outcome: "failed" };
+            }
+            if (action.type !== "static-complete" ||
+                action.challenge !== challenge.type) {
+                return { outcome: "stale" };
+            }
+            return { outcome: "complete" };
+    }
+}
+function normalizeRecall(value) {
+    return value.trim().toLocaleUpperCase("en-GB");
+}
+//# sourceMappingURL=workflow.js.map