@helyx/module-account-gate 1.0.15 → 1.1.3

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 1.1.3
+
+### Patch Changes
+
+- Updated dependencies [1dfbf5b]
+  - @helyx/module-manifest@0.9.0
+
+## 1.1.2
+
+### Patch Changes
+
+- Republish the current shared platform and Account Gate artifacts so their
+  immutable npm packages match the reviewed runtime permission contracts.
+
+## 1.1.1
+
+### Patch Changes
+
+- Updated dependencies [bbc4eee]
+  - @helyx/sdk@0.10.0
+
+## 1.1.0
+
+### Minor Changes
+
+- Add declared command-operation permission targets, project them through both permission-management surfaces, and harden module lifecycle, health, visibility, bounded-work, optional-side-effect, command-permission, and Forms durable-workflow behavior. Preserve existing FAQ, Access Control, Achievements, Giveaways and Levels overrides through additive migrations while assigning every slash-command path its own permission identity.
+
 ## 1.0.15
 
 ### Patch Changes

package/README.md

@@ -1,90 +1,55 @@
-# Access Control
-
-Access Control asks a joining member to complete short Discord interaction checks
-before Helyx grants the configured access role. It is a local
-human-interaction check: it can deter basic automated accounts, but it does not
-detect devices, network risk, alternate accounts or ban evasion.
-
-The default flow uses two different generated challenges and allows three
-attempts. Eight challenge types are implemented: Quick Sum, Button Sequence,
-Number Order, Symbol Match, Modal Recall, Server Question, Password Entry and
-Emoji Entry. Password Entry and Emoji Entry are static gates and are excluded
-from generated challenge allocation. A server selects one access type:
-generated Challenges, Password Entry or Emoji Entry.
-
-## Permissions and Discord configuration
-
-Access Control requires View Channel, Send Messages, Embed Links, Read Message
-History and Manage Roles. Kick Members is required only when final failure is
-configured to kick. Password Entry also requires Manage Messages, Guild
-Messages and the privileged Message Content intent; its channel health check
-explicitly requires View Channel, Read Message History and Manage Messages.
-Emoji Entry may require Add Reactions and the Guild Message Reactions intent.
-
-Helyx must be above the access role and every temporary role it removes. The
-module adds the access role before removing temporary roles so a partial
-Discord failure does not remove the member's only access route.
-
-Discord channel permissions are the sole authority for which channels pending
-members can see. Access Control validates its configured gate, Password Entry,
-Emoji Entry and staff-review channels, but it does not maintain a second
-dashboard allowlist of every other visible server channel. Administrators
-should configure the temporary pre-gate role's Discord permissions directly.
-The managed Start panel may be absent during the initial
-activation-and-publish flow, but runtime joins fail closed until its saved
-message exists. Enabling Server Question likewise requires at least one
-enabled managed question.
-
-The review-channel audience check rejects `@everyone` and every configured
-temporary pre-gate role. The current Discord inspection contract only reports
-roles explicitly requested by the module and Access Control has no configured
-staff-role allowlist, so it cannot prove that every other visible role is a
-staff role; administrators must keep that channel staff-only.
-
-## Failure and strict-mode behaviour
-
-Staff review is the default final-failure action. When kick is deliberately
-selected, Helyx first makes a best-effort attempt to send a neutral direct
-message explaining that Access Control was not completed. It then rechecks
-the current decision and kicks as soon as possible; a closed direct-message
-channel does not prevent the kick. The target is within 30 seconds and there is
-no deliberate delay.
-
-Authorised Access Control managers may activate temporary strict mode. It lasts
-15 minutes by default, can be configured from 5 to 60 minutes, adds one
-generated challenge without exceeding four, and expires automatically. It does
-not reduce attempts or enable kicking, Password Entry or Emoji Entry.
-
-Join deadlines and active-check expiry use durable one-shot tasks with exact
-join generations and session versions. Restarted or duplicate workers cannot
-enforce an old join or expire a newer check. A failed challenge applies the
-configured retry cooldown monotonically; passing or an authorised Approve or
-Retry decision clears it. Account age uses Discord's account-created and joined
-timestamps, and accepts the exact configured age boundary.
-
-Returning members are restored only when a prior success is retained, restore
-is enabled, re-verification is disabled, and the current access role is still
-assignable. Otherwise they enter a fresh pending generation. Adaptive chains
-add a generated challenge for a prior-failure or young-account signal, while
-temporary strict mode may add one more, capped at four.
-
-Password Entry and Emoji Entry are single-step access types rather than members
-of a generated challenge chain. Helyx sends answer-free private resume guidance
-that identifies the Discord server and gate channel. Closed direct messages
-never cause user-specific controls or answers to be posted publicly; the member
-can use the panel or `/access control start` to resume the persisted check.
-
-## Stored data
-
-The module stores server questions, safe attempt outcomes, member summaries,
-staff-review decisions, recoverable role transitions and strict-mode
-activations. Raw Password Entry messages are never retained. Active challenge
-answers use the shared expiring Helyx session service rather than a module-owned
-session table. A versioned Privacy Service provider supports bounded access and
-erasure.
-
-## Release state
-
-Access Control is a Live Helyx module. Runtime enforcement rechecks module
-state, member state, kick permission and role hierarchy immediately before
-every kick.
+# @helyx/module-account-gate
+
+Access Control keeps joining members in a Discord-managed restricted area until they complete a configured interaction, password, emoji, or server-question gate and Helyx safely grants the access role.
+
+## Availability and deployment
+
+Access Control is Live and supported by Hosted Helyx and Helyx Self-Hosted. It uses Helyx runtime and Discord capabilities only and requires no external provider credentials. It cannot be enabled alongside Verification because both own the server entry-role workflow.
+
+## What it does
+
+Managers choose generated Challenges, Password Entry, or Emoji Entry. Generated flows can combine quick sums, button sequences, number ordering, symbol matching, modal recall, and managed server questions. The module also supports bounded attempts and cooldowns, account-age rules, returning-member restoration, staff review, join deadlines, and temporary strict mode.
+
+Access Control is a Discord-native human-interaction gate. It can deter basic automated joins, but it does not assess devices, network risk, alternate accounts, or ban evasion. Discord channel permissions remain the authority for what pending members can see.
+
+## Commands and interactions
+
+| Path or control                  | Default access | Purpose                                                  |
+| -------------------------------- | -------------- | -------------------------------------------------------- |
+| `/access control start`          | Everyone       | Start or resume the caller's current pending check.      |
+| `/access control reset`          | Manage Roles   | Revoke the caller's access and begin a fresh generation. |
+| `/access control status`         | Manage Roles   | Inspect setup health and temporary strict-mode state.    |
+| `/access control strict`         | Manage Roles   | Add one generated challenge for a bounded period.        |
+| Published gate panel             | Everyone       | Start the configured member flow.                        |
+| Password message or emoji action | Pending member | Complete the selected single-step gate.                  |
+| Dashboard and review actions     | Manage Roles   | Approve, retry, kick, dismiss, or revoke a current case. |
+
+Every slash-command path has its own permission identity and dashboard override. Responses are private and server-only. Start is limited to five uses per member per minute; Reset is limited to ten.
+
+## Dashboard configuration
+
+Settings cover access type, roles, gate and staff-review channels, attempt and timing controls, account age, returning-member behavior, final-failure action, and optional strict mode. Managed resources publish, edit, repair, or repost gate panels and maintain server questions. The Members resource exposes bounded current state and guarded review or revoke actions.
+
+Activation validates the selected roles, channels, Discord capabilities, published panel, and at least one enabled question when Server Questions is used. Helyx does not maintain a second allowlist for every channel visible to a pending role; managers configure those Discord overwrites directly.
+
+## Discord requirements
+
+The ordinary flow needs View Channel, Send Messages, Embed Links, Read Message History, and Manage Roles. Kick Members is required only when final failure is configured to kick. Password Entry additionally needs Manage Messages, Guild Messages, and Message Content. Emoji Entry may require Add Reactions and the Guild Message Reactions capability. Helyx must sit above the access role and each temporary role it removes.
+
+The staff-review channel must not be visible to `@everyone` or configured temporary roles. Helyx validates the audiences it can inspect, but managers remain responsible for keeping every other visible role staff-only.
+
+## Data, privacy and retention
+
+The module stores question-creator references, bounded attempt outcomes, member summaries, staff-review decisions, terminal finalisations, recoverable role transitions, strict-mode activations, and privacy suppression state. Raw Password Entry messages and generated answers are never retained; active challenge answers use the shared expiring interaction-session service.
+
+The registered privacy provider supports bounded access and erasure even while the module is disabled. Subject erasure removes or detaches declared member and actor records and uses suppression state to prevent in-flight work from recreating deleted personal data.
+
+## Operations and failure behavior
+
+Join deadlines, challenge expiry, strict-mode expiry, and recovery use durable versioned tasks. Exact join generations, session versions, write fences, and terminal receipts prevent restarted or duplicate workers from enforcing stale work. Helyx adds the access role before removing temporary roles, so a partial Discord failure does not remove the member's only access route.
+
+Final kick decisions recheck current module, member, permission, and role state immediately before enforcement. A failed direct message does not block a configured kick. Optional Logging cannot reverse a committed decision, and health exposes bounded setup or recovery state without raw answers or exception details.
+
+## Documentation and support
+
+See the [Access Control guide](https://docs.helyx.gg/modules/access-control/), [settings](https://docs.helyx.gg/modules/access-control/settings/), [commands](https://docs.helyx.gg/modules/access-control/commands/), [permissions](https://docs.helyx.gg/modules/access-control/permissions/), [resources](https://docs.helyx.gg/modules/access-control/resources/), [members](https://docs.helyx.gg/modules/access-control/members/), [logging](https://docs.helyx.gg/modules/access-control/logging/), and [FAQ](https://docs.helyx.gg/modules/access-control/faq/).

package/dist/challenge-interactions.d.ts

@@ -0,0 +1,12 @@
+import type { ModalCapableInteractionContext, ModalInteractionContext, Challenge, ChallengeAction, WorkflowResult } from "./runtime-dependencies.js";
+import type { ComponentBinding } from "./runtime-support.js";
+export declare function processAction(context: ModalCapableInteractionContext | ModalInteractionContext, action: ChallengeAction, binding: ComponentBinding): Promise<void>;
+export declare function finaliseAttempt(context: ModalCapableInteractionContext | ModalInteractionContext, sessionId: string, result: Extract<WorkflowResult, {
+    outcome: "passed" | "failed";
+}>, challengeType: Challenge["type"]): Promise<void>;
+export declare function rerollChallenge(context: ModalCapableInteractionContext): Promise<void>;
+export declare function openRecallModal(context: ModalCapableInteractionContext): Promise<void>;
+export declare function submitRecallModal(context: ModalInteractionContext): Promise<void>;
+export declare function processBoundOption(context: ModalCapableInteractionContext): Promise<void>;
+export declare function processBoundSequence(context: ModalCapableInteractionContext): Promise<void>;
+//# sourceMappingURL=challenge-interactions.d.ts.map

package/dist/challenge-interactions.js

@@ -0,0 +1,238 @@
+import { HELYX_SERVICE_NAMES, ACCOUNT_GATE_COMPONENTS, ACCOUNT_GATE_SESSION_PURPOSE, generatedChallengePool, isAccountGateWorkSuppressed, applyChallengeAction, parseAccountGateSessionState, rerollForAccessibility, GREEN, RED, } from "./runtime-dependencies.js";
+import { isCurrentPendingMember } from "./member-summary.js";
+import { recordAccountGateAttempt } from "./member-restart.js";
+import { boundComponentId, parseComponentBinding, replyError, secureRandom, } from "./runtime-support.js";
+import { challengeMessage, requiredRuntimeConfiguration, } from "./setup-presentation.js";
+import { scheduleSessionExpiry } from "./task-scheduling.js";
+import { ensureTerminalFinalization, finalizeTerminalFinalization, } from "./terminal-finalization.js";
+export async function processAction(context, action, binding) {
+    if (!context.serverId) {
+        await replyError(context, "This Access Control interaction is unavailable.");
+        return;
+    }
+    const sessions = context.services.get(HELYX_SERVICE_NAMES.sessions);
+    const session = await sessions.getFor(context.serverId, context.userId, ACCOUNT_GATE_SESSION_PURPOSE);
+    if (!session) {
+        await replyError(context, "This check has expired. Start a new check.");
+        return;
+    }
+    if (session.sessionId !== binding.sessionId ||
+        session.version !== binding.version ||
+        parseAccountGateSessionState(session.state).step !== binding.step) {
+        await replyError(context, "That control belongs to an older check or challenge step.");
+        return;
+    }
+    const configuration = await requiredRuntimeConfiguration(context.services, context.serverId);
+    if (!(await isCurrentPendingMember(context.services, context.serverId, context.userId, configuration.verifiedRoleId))) {
+        await sessions.delete(session.sessionId);
+        await replyError(context, "This pending Access Control check is no longer valid.");
+        return;
+    }
+    const state = parseAccountGateSessionState(session.state);
+    const result = applyChallengeAction(state, action);
+    if (result.outcome === "stale") {
+        await replyError(context, "That interaction is no longer part of your current check.");
+        return;
+    }
+    if (result.outcome === "progress") {
+        const updated = await sessions.update({
+            sessionId: session.sessionId,
+            expectedVersion: session.version,
+            state: result.state,
+        });
+        await scheduleSessionExpiry(context.services, {
+            guildId: context.serverId,
+            userId: context.userId,
+            sessionId: session.sessionId,
+            expiredAt: session.expiresAt,
+        });
+        await context.reply(challengeMessage(result.state, {
+            sessionId: session.sessionId,
+            version: updated.version,
+        }));
+        return;
+    }
+    const advanced = await sessions.advance({
+        sessionId: session.sessionId,
+        guildId: context.serverId,
+        userId: context.userId,
+        purpose: ACCOUNT_GATE_SESSION_PURPOSE,
+        expectedVersion: session.version,
+        expectedStep: state.step,
+        nextStep: state.step + 1,
+        state: { ...result.state, step: state.step + 1 },
+    });
+    await scheduleSessionExpiry(context.services, {
+        guildId: context.serverId,
+        userId: context.userId,
+        sessionId: session.sessionId,
+        expiredAt: session.expiresAt,
+    });
+    if (result.outcome === "advanced") {
+        await context.reply(challengeMessage(result.state, {
+            sessionId: session.sessionId,
+            version: advanced.version,
+        }));
+        return;
+    }
+    await finaliseAttempt(context, session.sessionId, result, state.chain[state.currentStep].type);
+}
+export async function finaliseAttempt(context, sessionId, result, challengeType) {
+    const guildId = context.serverId;
+    await requiredRuntimeConfiguration(context.services, guildId);
+    if (await isAccountGateWorkSuppressed(context.services, guildId, context.userId, new Date(result.state.startedAt))) {
+        await context.services
+            .get(HELYX_SERVICE_NAMES.sessions)
+            .delete(sessionId);
+        await replyError(context, "This check can no longer be completed. Start a new check if you still require access.");
+        return;
+    }
+    const records = context.services.get(HELYX_SERVICE_NAMES.records);
+    await recordAccountGateAttempt(records, guildId, context.userId, sessionId, result.state, challengeType, result.outcome);
+    if (!(await ensureTerminalFinalization(context.services, guildId, context.userId, sessionId, result.state, result.outcome)))
+        return;
+    await finalizeTerminalFinalization(context.services, guildId, sessionId);
+    await context.reply({
+        ephemeral: true,
+        componentsV2: {
+            accentColor: result.outcome === "passed" ? GREEN : RED,
+            text: [
+                {
+                    content: result.outcome === "passed"
+                        ? "## Check submitted"
+                        : "## Attempt submitted",
+                },
+                {
+                    content: result.outcome === "passed"
+                        ? "Your result is being finalized. If access is not applied, the server team will receive a review."
+                        : "That answer was not correct. Start a new check when the cooldown ends if another attempt is available.",
+                    markdown: false,
+                },
+            ],
+        },
+    });
+}
+export async function rerollChallenge(context) {
+    if (!context.serverId)
+        return replyError(context, "This check is unavailable.");
+    const sessions = context.services.get(HELYX_SERVICE_NAMES.sessions);
+    const session = await sessions.getFor(context.serverId, context.userId, ACCOUNT_GATE_SESSION_PURPOSE);
+    if (!session)
+        return replyError(context, "This check has expired.");
+    const binding = parseComponentBinding(context.customId, ACCOUNT_GATE_COMPONENTS.rerollPrefix);
+    if (!binding ||
+        binding.sessionId !== session.sessionId ||
+        binding.version !== session.version ||
+        binding.step !== parseAccountGateSessionState(session.state).step)
+        return replyError(context, "That reroll control is no longer current.");
+    const configuration = await requiredRuntimeConfiguration(context.services, context.serverId);
+    const currentState = parseAccountGateSessionState(session.state);
+    if (await isAccountGateWorkSuppressed(context.services, context.serverId, context.userId, new Date(currentState.startedAt))) {
+        await sessions.delete(session.sessionId);
+        await replyError(context, "This check can no longer be changed. Start a new check if you still require access.");
+        return;
+    }
+    const state = rerollForAccessibility({
+        state: currentState,
+        enabledTypes: generatedChallengePool(configuration),
+        random: secureRandom(context.services),
+        operationContext: `${context.serverId}:${context.userId}:reroll`,
+    });
+    if (!state) {
+        await replyError(context, "A different challenge is not available for this check.");
+        return;
+    }
+    const updated = await sessions.update({
+        sessionId: session.sessionId,
+        expectedVersion: session.version,
+        state,
+    });
+    await scheduleSessionExpiry(context.services, {
+        guildId: context.serverId,
+        userId: context.userId,
+        sessionId: session.sessionId,
+        expiredAt: session.expiresAt,
+    });
+    await context.reply(challengeMessage(state, {
+        sessionId: session.sessionId,
+        version: updated.version,
+    }));
+}
+export async function openRecallModal(context) {
+    if (!context.serverId)
+        return replyError(context, "This check is unavailable.");
+    const binding = parseComponentBinding(context.customId, ACCOUNT_GATE_COMPONENTS.recallOpenPrefix);
+    if (!binding)
+        return replyError(context, "This recall challenge has expired.");
+    await context.showModal({
+        customId: boundComponentId(ACCOUNT_GATE_COMPONENTS.recallSubmitPrefix, binding),
+        title: "Enter the recalled code",
+        fields: [
+            {
+                customId: "code",
+                label: "Recall code",
+                description: "Letter case and surrounding spaces are ignored.",
+                style: "short",
+                required: true,
+                minLength: 5,
+                maxLength: 8,
+            },
+        ],
+    });
+    let session;
+    try {
+        session = await context.services
+            .get(HELYX_SERVICE_NAMES.sessions)
+            .getFor(context.serverId, context.userId, ACCOUNT_GATE_SESSION_PURPOSE);
+    }
+    catch {
+        return;
+    }
+    const state = session ? parseAccountGateSessionState(session.state) : null;
+    if (!session ||
+        !state ||
+        binding.sessionId !== session.sessionId ||
+        binding.version !== session.version ||
+        binding.step !== state.step ||
+        state.chain[state.currentStep]?.type !== "modal_recall") {
+        return;
+    }
+    await context
+        .editSourceMessage?.(challengeMessage(state, {
+        sessionId: session.sessionId,
+        version: session.version,
+    }, { redactRecallCode: true }))
+        .catch(() => undefined);
+}
+export async function submitRecallModal(context) {
+    const binding = parseComponentBinding(context.customId, ACCOUNT_GATE_COMPONENTS.recallSubmitPrefix);
+    if (!binding) {
+        await replyError(context, "This recall challenge is no longer current.");
+        return;
+    }
+    await processAction(context, {
+        type: "recall",
+        value: context.getField("code"),
+    }, binding);
+}
+export async function processBoundOption(context) {
+    const binding = parseComponentBinding(context.customId, ACCOUNT_GATE_COMPONENTS.answerPrefix);
+    const option = binding ? Number(binding.value) : -1;
+    if (!binding || !Number.isInteger(option) || option < 0 || option > 3) {
+        await replyError(context, "This answer control is invalid.");
+        return;
+    }
+    await processAction(context, { type: "option", option }, binding);
+}
+export async function processBoundSequence(context) {
+    const binding = parseComponentBinding(context.customId, ACCOUNT_GATE_COMPONENTS.sequencePrefix);
+    if (!binding || !["red", "blue", "green"].includes(binding.value ?? "")) {
+        await replyError(context, "This sequence control is invalid.");
+        return;
+    }
+    await processAction(context, {
+        type: "sequence",
+        value: binding.value,
+    }, binding);
+}
+//# sourceMappingURL=challenge-interactions.js.map

package/dist/commands.js

@@ -5,6 +5,7 @@ export function accountGateCommands(handlers) {
             path: "control.start",
             description: "Start or resume your Access Control check",
             acknowledgement: "deferred-ephemeral",
+            permissionId: "account-gate.start",
             rateLimit: { scope: "user", limit: 5, windowSeconds: 60 },
             execute: handlers.start,
         },
@@ -22,7 +23,7 @@ export function accountGateCommands(handlers) {
             path: "control.status",
             description: "Show Access Control health and strict-mode status",
             acknowledgement: "deferred-ephemeral",
-            permissionId: "account-gate.manage",
+            permissionId: "account-gate.status",
             execute: handlers.status,
         },
         {
@@ -30,7 +31,7 @@ export function accountGateCommands(handlers) {
             path: "control.strict",
             description: "Activate temporary strict mode",
             acknowledgement: "deferred-ephemeral",
-            permissionId: "account-gate.manage",
+            permissionId: "account-gate.strict",
             execute: handlers.strict,
         },
     ];

package/dist/contracts.d.ts

@@ -2,7 +2,7 @@ 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.15";
+    readonly version: "1.1.3";
     readonly releaseStatus: "live";
     readonly category: "safety";
     readonly icon: "shield-check";

package/dist/contracts.js

@@ -2,7 +2,7 @@ export const ACCOUNT_GATE_IDENTITY = {
     packageName: "@helyx/module-account-gate",
     moduleId: "helyx.account-gate",
     name: "Access Control",
-    version: "1.0.15",
+    version: "1.1.3",
     releaseStatus: "live",
     category: "safety",
     icon: "shield-check",

package/dist/expiry-workflows.d.ts

@@ -0,0 +1,32 @@
+import type { RuntimeContext, ScheduledTaskPayload } from "./runtime-dependencies.js";
+export declare function validateJoinDeadlinePayload(input: unknown): ScheduledTaskPayload;
+export declare function validateLeaveRetentionPayload(input: unknown): ScheduledTaskPayload;
+export declare function runLeaveRetention(context: RuntimeContext, task: {
+    payload: ScheduledTaskPayload;
+}): Promise<{
+    outcome: "completed";
+    delayMs?: never;
+    safeCode?: never;
+} | {
+    outcome: "deferred";
+    delayMs: number;
+    safeCode: string;
+}>;
+export declare function enforceJoinDeadline(context: RuntimeContext, task: {
+    payload: ScheduledTaskPayload;
+}): Promise<{
+    outcome: "completed";
+    delayMs?: never;
+    safeCode?: never;
+} | {
+    outcome: "deferred";
+    delayMs: number;
+    safeCode: string;
+}>;
+export declare function validateSessionExpiryPayload(input: unknown): ScheduledTaskPayload;
+export declare function expireSession(context: RuntimeContext, task: {
+    payload: ScheduledTaskPayload;
+}): Promise<{
+    outcome: "completed";
+}>;
+//# sourceMappingURL=expiry-workflows.d.ts.map