@helyx/module-account-gate 1.0.1

package/dist/contracts.d.ts

@@ -0,0 +1,82 @@
+export declare const ACCOUNT_GATE_IDENTITY: {
+    readonly packageName: "@helyx/module-account-gate";
+    readonly moduleId: "helyx.account-gate";
+    readonly name: "Access Control";
+    readonly version: "1.0.0";
+    readonly releaseStatus: "testing";
+    readonly category: "safety";
+    readonly icon: "shield-check";
+};
+export declare const ACCOUNT_GATE_SESSION_PURPOSE = "helyx.account-gate.check";
+export declare const ACCOUNT_GATE_COMPONENTS: {
+    readonly start: "helyx.account-gate.start";
+    readonly startPrefix: "helyx.account-gate.start:";
+    readonly rerollPrefix: "helyx.account-gate.reroll:";
+    readonly recallOpenPrefix: "helyx.account-gate.recall.open:";
+    readonly recallSubmitPrefix: "helyx.account-gate.recall.submit:";
+    readonly answerPrefix: "helyx.account-gate.answer:";
+    readonly sequencePrefix: "helyx.account-gate.sequence:";
+    readonly reroll: "helyx.account-gate.reroll";
+    readonly recallOpen: "helyx.account-gate.recall.open";
+    readonly recallSubmit: "helyx.account-gate.recall.submit";
+    readonly answers: readonly ["helyx.account-gate.answer.0", "helyx.account-gate.answer.1", "helyx.account-gate.answer.2", "helyx.account-gate.answer.3"];
+    readonly sequence: readonly ["helyx.account-gate.sequence.red", "helyx.account-gate.sequence.blue", "helyx.account-gate.sequence.green"];
+    readonly review: {
+        readonly approve: "helyx.account-gate.review.approve";
+        readonly retry: "helyx.account-gate.review.retry";
+        readonly kick: "helyx.account-gate.review.kick";
+        readonly dismiss: "helyx.account-gate.review.dismiss";
+    };
+};
+export declare const GENERATED_CHALLENGE_TYPES: readonly ["quick_sum", "button_sequence", "number_order", "symbol_match", "modal_recall", "server_question"];
+export declare const STATIC_CHALLENGE_TYPES: readonly ["password_entry", "emoji_entry"];
+export declare const CHALLENGE_TYPES: readonly ["quick_sum", "button_sequence", "number_order", "symbol_match", "modal_recall", "server_question", "password_entry", "emoji_entry"];
+export type GeneratedChallengeType = (typeof GENERATED_CHALLENGE_TYPES)[number];
+export type StaticChallengeType = (typeof STATIC_CHALLENGE_TYPES)[number];
+export type ChallengeType = (typeof CHALLENGE_TYPES)[number];
+export type Challenge = {
+    type: "quick_sum" | "symbol_match" | "server_question";
+    prompt: string;
+    options: readonly string[];
+    expectedOption: number;
+} | {
+    type: "button_sequence";
+    prompt: string;
+    expectedSequence: readonly ("red" | "blue" | "green")[];
+    progress: number;
+} | {
+    type: "number_order";
+    prompt: string;
+    options: readonly string[];
+    expectedSequence: readonly number[];
+    progress: number;
+} | {
+    type: "modal_recall";
+    prompt: string;
+    expectedText: string;
+} | {
+    type: "password_entry" | "emoji_entry";
+    prompt: string;
+};
+export interface AccountGateSessionState extends Record<string, unknown> {
+    schemaVersion: 1;
+    status: "active" | "passed" | "failed" | "cancelled";
+    chain: readonly Challenge[];
+    step: number;
+    currentStep: number;
+    accessibilityRerollUsed: boolean;
+    joinGeneration: number;
+    panelId?: string;
+    startedAt: string;
+}
+export interface ServerQuestion {
+    id: string;
+    question: string;
+    answers: readonly string[];
+    correctOption: number;
+}
+export interface RandomSource {
+    integer(maximumExclusive: number, context: string): number;
+}
+export type FailureAction = "restricted" | "review" | "kick";
+//# sourceMappingURL=contracts.d.ts.map

package/dist/contracts.js

@@ -0,0 +1,56 @@
+export const ACCOUNT_GATE_IDENTITY = {
+    packageName: "@helyx/module-account-gate",
+    moduleId: "helyx.account-gate",
+    name: "Access Control",
+    version: "1.0.0",
+    releaseStatus: "testing",
+    category: "safety",
+    icon: "shield-check",
+};
+export const ACCOUNT_GATE_SESSION_PURPOSE = "helyx.account-gate.check";
+export const ACCOUNT_GATE_COMPONENTS = {
+    start: "helyx.account-gate.start",
+    startPrefix: "helyx.account-gate.start:",
+    rerollPrefix: "helyx.account-gate.reroll:",
+    recallOpenPrefix: "helyx.account-gate.recall.open:",
+    recallSubmitPrefix: "helyx.account-gate.recall.submit:",
+    answerPrefix: "helyx.account-gate.answer:",
+    sequencePrefix: "helyx.account-gate.sequence:",
+    reroll: "helyx.account-gate.reroll",
+    recallOpen: "helyx.account-gate.recall.open",
+    recallSubmit: "helyx.account-gate.recall.submit",
+    answers: [
+        "helyx.account-gate.answer.0",
+        "helyx.account-gate.answer.1",
+        "helyx.account-gate.answer.2",
+        "helyx.account-gate.answer.3",
+    ],
+    sequence: [
+        "helyx.account-gate.sequence.red",
+        "helyx.account-gate.sequence.blue",
+        "helyx.account-gate.sequence.green",
+    ],
+    review: {
+        approve: "helyx.account-gate.review.approve",
+        retry: "helyx.account-gate.review.retry",
+        kick: "helyx.account-gate.review.kick",
+        dismiss: "helyx.account-gate.review.dismiss",
+    },
+};
+export const GENERATED_CHALLENGE_TYPES = [
+    "quick_sum",
+    "button_sequence",
+    "number_order",
+    "symbol_match",
+    "modal_recall",
+    "server_question",
+];
+export const STATIC_CHALLENGE_TYPES = [
+    "password_entry",
+    "emoji_entry",
+];
+export const CHALLENGE_TYPES = [
+    ...GENERATED_CHALLENGE_TYPES,
+    ...STATIC_CHALLENGE_TYPES,
+];
+//# sourceMappingURL=contracts.js.map

package/dist/enforcement.d.ts

@@ -0,0 +1,19 @@
+import type { DiscordResourceInspectionService, MemberRoleService } from "@helyx/sdk";
+export interface RoleTransitionResult {
+    outcome: "completed" | "partial" | "blocked" | "stale";
+    accessRoleAdded: boolean;
+    removedRoleIds: readonly string[];
+    pendingRoleIds: readonly string[];
+    safeCode?: string;
+}
+export declare function applyRoleTransition(input: {
+    guildId: string;
+    memberUserId: string;
+    verifiedRoleId: string;
+    temporaryRoleIds: readonly string[];
+    resources: DiscordResourceInspectionService;
+    roles: MemberRoleService;
+    revalidate: () => Promise<boolean>;
+}): Promise<RoleTransitionResult>;
+export declare function neutralKickDirectMessage(serverName: string): string;
+//# sourceMappingURL=enforcement.d.ts.map

package/dist/enforcement.js

@@ -0,0 +1,110 @@
+import { ACCOUNT_GATE_IDENTITY } from "./contracts.js";
+export async function applyRoleTransition(input) {
+    const accessRole = await input.resources.inspectRole({
+        guildId: input.guildId,
+        roleId: input.verifiedRoleId,
+    });
+    if (!accessRole.exists || !accessRole.assignable) {
+        return {
+            outcome: "blocked",
+            accessRoleAdded: false,
+            removedRoleIds: [],
+            pendingRoleIds: input.temporaryRoleIds,
+            safeCode: `access_role_${accessRole.hierarchy}`,
+        };
+    }
+    let currentRoles = await input.roles.getCurrentRoleIds({
+        guildId: input.guildId,
+        memberUserId: input.memberUserId,
+    });
+    if (!(await input.revalidate()))
+        return staleResult(input.temporaryRoleIds, false);
+    const accessRoleAdded = !currentRoles.includes(input.verifiedRoleId);
+    if (accessRoleAdded) {
+        await input.roles.addApprovedRole({
+            guildId: input.guildId,
+            memberUserId: input.memberUserId,
+            roleId: input.verifiedRoleId,
+            moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+            reason: "Access Control completed",
+        });
+        if (!(await input.revalidate())) {
+            await compensateAccessRole(input);
+            return staleResult(input.temporaryRoleIds, false);
+        }
+        currentRoles = await input.roles.getCurrentRoleIds({
+            guildId: input.guildId,
+            memberUserId: input.memberUserId,
+        });
+    }
+    const removed = [];
+    const pending = [];
+    for (const roleId of input.temporaryRoleIds) {
+        if (!currentRoles.includes(roleId)) {
+            removed.push(roleId);
+            continue;
+        }
+        const role = await input.resources.inspectRole({
+            guildId: input.guildId,
+            roleId,
+        });
+        if (!role.exists) {
+            removed.push(roleId);
+            continue;
+        }
+        if (!role.assignable) {
+            pending.push(roleId);
+            continue;
+        }
+        if (!(await input.revalidate())) {
+            if (accessRoleAdded)
+                await compensateAccessRole(input);
+            return staleResult(input.temporaryRoleIds.filter((candidate) => !removed.includes(candidate)), false);
+        }
+        try {
+            await input.roles.removeApprovedRole({
+                guildId: input.guildId,
+                memberUserId: input.memberUserId,
+                roleId,
+                moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+                reason: "Access Control completed",
+            });
+            removed.push(roleId);
+        }
+        catch {
+            pending.push(roleId);
+        }
+    }
+    return {
+        outcome: pending.length > 0 ? "partial" : "completed",
+        accessRoleAdded,
+        removedRoleIds: removed,
+        pendingRoleIds: pending,
+        ...(pending.length > 0
+            ? { safeCode: "temporary_role_removal_failed" }
+            : {}),
+    };
+}
+async function compensateAccessRole(input) {
+    await input.roles.removeApprovedRole({
+        guildId: input.guildId,
+        memberUserId: input.memberUserId,
+        roleId: input.verifiedRoleId,
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        reason: "Access Control stale-generation compensation",
+    });
+}
+function staleResult(pendingRoleIds, accessRoleAdded) {
+    return {
+        outcome: "stale",
+        accessRoleAdded,
+        removedRoleIds: [],
+        pendingRoleIds,
+        safeCode: "join_generation_stale",
+    };
+}
+export function neutralKickDirectMessage(serverName) {
+    const safeServerName = serverName.trim().slice(0, 100);
+    return `You were removed from ${safeServerName || "a Discord server"} because its Access Control check was not completed. You may contact the server team if you believe this was a mistake.`;
+}
+//# sourceMappingURL=enforcement.js.map

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+import type { MessageResponse, ModuleRecordService, ModuleRecordValue, ServiceAccess } from "@helyx/sdk";
+import { generateChallengeChain, validateServerQuestion } from "./challenges.js";
+import { ACCOUNT_GATE_IDENTITY } from "./contracts.js";
+import type { AccountGateSessionState, Challenge } from "./contracts.js";
+import { parseAccountGateConfiguration, validateRuntimeCapabilities } from "./configuration.js";
+import type { AccountGateConfiguration } from "./configuration.js";
+import { accountGateRecords } from "./records.js";
+import { applyChallengeAction, createAccountGateSessionState } from "./workflow.js";
+export declare const accountGateModule: import("@helyx/sdk").ModuleDefinition;
+export default accountGateModule;
+export { ACCOUNT_GATE_IDENTITY, accountGateRecords, applyChallengeAction, createAccountGateSessionState, generateChallengeChain, parseAccountGateConfiguration, validateRuntimeCapabilities, validateServerQuestion, };
+export declare function isAccountTooYoung(accountCreatedAt: Date, joinedAt: Date, minimumAccountAgeDays: number): boolean;
+export declare function hasPreviousSuccess(value: unknown): boolean;
+export declare function resumeRevokedMember(services: ServiceAccess, guildId: string, memberUserId: string, summary: Readonly<Record<string, ModuleRecordValue>>, configuration: AccountGateConfiguration, correlationId: string, now?: Date): Promise<Readonly<Record<string, ModuleRecordValue>> | null>;
+export declare function recordAccountGateAttempt(records: ModuleRecordService, guildId: string, memberUserId: string, sessionId: string, state: AccountGateSessionState, challengeType: Challenge["type"], outcome: "passed" | "failed", now?: Date): Promise<void>;
+export declare function ensureTerminalFinalization(services: ServiceAccess, guildId: string, memberUserId: string, sessionId: string, state: AccountGateSessionState, outcome: "passed" | "failed"): Promise<boolean>;
+export declare function validateAccountGateSetup(services: ServiceAccess, guildId: string, configuration: AccountGateConfiguration, throwOnError?: boolean, allowMissingPanel?: boolean): Promise<readonly string[]>;
+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=index.d.ts.map