@helyx/module-account-gate 1.0.1

package/dist/panel-resource.js

@@ -0,0 +1,527 @@
+import { DashboardActionValidationError, HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { ACCOUNT_GATE_COMPONENTS, ACCOUNT_GATE_IDENTITY } from "./contracts.js";
+import { parseAccountGateConfiguration } from "./configuration.js";
+import { managedResourceSummary } from "./managed-resource-summary.js";
+import { hashPasswordEntryPhrase } from "./password-entry.js";
+import { accountGateRecords } from "./records.js";
+const VIOLET = 0x7c3aed;
+const MAX_GATE_PANELS = 10;
+const DEFAULT_PANEL_MESSAGES = {
+    challenges: "Complete a short human-interaction check to access the server. Press the button below when you are ready.",
+    password: "Enter the password for this gate in the Password Entry channel. Never enter your Discord password or authentication code.",
+    emoji: "React with the configured emoji on the Emoji Entry message to continue.",
+};
+export const gatePanelResource = {
+    id: "gate-panel",
+    availableWhileDisabled: true,
+    async list(context) {
+        const page = await records(context).findMany({
+            moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+            collection: "gate_panels",
+            select: accountGateRecords.gate_panels.readableFields,
+            where: { guild_id: context.guildId },
+            orderBy: [
+                { field: "guild_id", direction: "asc" },
+                { field: "created_at", direction: "asc" },
+                { field: "panel_id", direction: "asc" },
+            ],
+            limit: MAX_GATE_PANELS,
+        });
+        const details = await Promise.all(page.records.map((row) => inspectedDetail(context, row)));
+        return { items: details.map(managedResourceSummary) };
+    },
+    async read(context, resourceId) {
+        const row = await records(context).findOne({
+            moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+            collection: "gate_panels",
+            select: accountGateRecords.gate_panels.readableFields,
+            where: { guild_id: context.guildId, panel_id: resourceId },
+        });
+        return row ? inspectedDetail(context, row) : null;
+    },
+    async preview(context, value) {
+        const accessType = await configuredAccessType(context);
+        return panelMessage(panelMessageFromValue(value, DEFAULT_PANEL_MESSAGES[accessType]), accessType, "preview");
+    },
+    async create(context, value) {
+        return post(context, value);
+    },
+    async update(context, input) {
+        const current = await currentPanel(context, input.resourceId);
+        assertRevision(current, input.expectedRevision);
+        const password = await panelPasswordForUpdate(context, current, input.value);
+        return writePanelMessage(context, current, panelMessageFromValue(input.value, savedPanelMessage(current)), panelAccessType(current), password, "updated");
+    },
+    async delete(context, input) {
+        const row = await currentPanelOrNull(context, input.resourceId);
+        if (!row)
+            return { deleted: false };
+        assertRevision(row, input.expectedRevision);
+        await context.deleteChannelMessage(stringValue(row.channel_id), stringValue(row.message_id));
+        const result = await records(context).deleteMany({
+            moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+            collection: "gate_panels",
+            where: { guild_id: context.guildId, panel_id: input.resourceId },
+            limit: 1,
+        });
+        return { deleted: result.deleted === 1 };
+    },
+    async executeAction(context, input) {
+        if (input.actionId !== "repair" && input.actionId !== "repost") {
+            throw new DashboardActionValidationError("That Gate panel action is unavailable.");
+        }
+        const current = await currentPanel(context, input.resourceId);
+        assertRevision(current, input.expectedRevision);
+        if (input.actionId === "repost") {
+            return replacePanel(context, current, "reposted", savedPanelMessage(current), panelAccessType(current), panelPasswordFromRow(current));
+        }
+        return repairPanel(context, current);
+    },
+};
+async function repairPanel(context, current) {
+    return writePanelMessage(context, current, savedPanelMessage(current), panelAccessType(current), panelPasswordFromRow(current), "repaired");
+}
+async function writePanelMessage(context, current, messageBody, accessType, password, action) {
+    const inspection = await context.services
+        .get(HELYX_SERVICE_NAMES.discordResources)
+        .inspectMessage({
+        guildId: context.guildId,
+        channelId: stringValue(current.channel_id),
+        messageId: stringValue(current.message_id),
+    });
+    if (!inspection.exists ||
+        !inspection.guildMatches ||
+        !inspection.channelMatches) {
+        return replacePanel(context, current, action, messageBody, accessType, password);
+    }
+    try {
+        await context.editChannelMessage(stringValue(current.channel_id), stringValue(current.message_id), panelMessage(messageBody, accessType, stringValue(current.panel_id)));
+    }
+    catch {
+        return replacePanel(context, current, action, messageBody, accessType, password);
+    }
+    return persistPanelRevision(context, current, {
+        channelId: stringValue(current.channel_id),
+        messageId: stringValue(current.message_id),
+        messageBody,
+        accessType,
+        password,
+        action,
+    });
+}
+async function replacePanel(context, current, action, messageBody, accessType, password) {
+    const configured = await context.services
+        .get(HELYX_SERVICE_NAMES.configuration)
+        .get(context.guildId, ACCOUNT_GATE_IDENTITY.moduleId);
+    if (!configured) {
+        throw new DashboardActionValidationError("Save Access Control settings before posting the panel.");
+    }
+    const configuration = parseAccountGateConfiguration(configured.value);
+    const sent = await context.sendToChannel(configuration.gateChannelId, panelMessage(messageBody, accessType, stringValue(current.panel_id)));
+    try {
+        const detail = await persistPanelRevision(context, current, {
+            channelId: configuration.gateChannelId,
+            messageId: sent.messageId,
+            messageBody,
+            accessType,
+            password,
+            action,
+        });
+        try {
+            await context.deleteChannelMessage(stringValue(current.channel_id), stringValue(current.message_id));
+        }
+        catch {
+            // The replacement is authoritative even when the old message is gone.
+        }
+        return detail;
+    }
+    catch (error) {
+        await context
+            .deleteChannelMessage(configuration.gateChannelId, sent.messageId)
+            .catch(() => undefined);
+        throw error;
+    }
+}
+async function persistPanelRevision(context, current, input) {
+    const revision = numberValue(current.revision) + 1;
+    const updatedAt = new Date();
+    const result = await records(context).updateOne({
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        collection: "gate_panels",
+        where: {
+            guild_id: context.guildId,
+            panel_id: stringValue(current.panel_id),
+        },
+        expected: { field: "revision", value: numberValue(current.revision) },
+        values: {
+            channel_id: input.channelId,
+            message_id: input.messageId,
+            message_body: input.messageBody,
+            access_type: input.accessType,
+            ...(input.password
+                ? {
+                    password_hash: input.password.encodedHash,
+                    password_ignore_case: input.password.ignoreCase,
+                    password_trim_whitespace: input.password.trimWhitespace,
+                }
+                : {}),
+            revision,
+            updated_at: updatedAt,
+        },
+        audit: {
+            guildId: context.guildId,
+            actorUserId: context.actor.userId,
+            action: `account_gate.panel_${input.action}`,
+            source: "dashboard",
+            correlationId: context.correlationId,
+            idempotencyKey: context.correlationId,
+            targetType: "account_gate_panel",
+            targetId: stringValue(current.panel_id),
+            metadata: { revision },
+        },
+    });
+    if (!result.updated) {
+        throw new DashboardActionValidationError("The Gate panel changed in another session. Reload and try again.");
+    }
+    return detail({
+        ...current,
+        channel_id: input.channelId,
+        message_id: input.messageId,
+        message_body: input.messageBody,
+        access_type: input.accessType,
+        password_hash: input.password?.encodedHash ?? null,
+        password_ignore_case: input.password?.ignoreCase ?? true,
+        password_trim_whitespace: input.password?.trimWhitespace ?? true,
+        revision,
+        updated_at: updatedAt,
+    }, "posted");
+}
+async function currentPanel(context, resourceId) {
+    const current = await currentPanelOrNull(context, resourceId);
+    if (!current) {
+        throw new DashboardActionValidationError("The Access Control panel was not found.");
+    }
+    return current;
+}
+async function currentPanelOrNull(context, resourceId) {
+    return records(context).findOne({
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        collection: "gate_panels",
+        select: accountGateRecords.gate_panels.readableFields,
+        where: { guild_id: context.guildId, panel_id: resourceId },
+    });
+}
+function assertRevision(current, expectedRevision) {
+    if (numberValue(current.revision) !== expectedRevision) {
+        throw new DashboardActionValidationError("The Gate panel changed in another session. Reload and try again.");
+    }
+}
+async function post(context, value = {}) {
+    const configured = await context.services
+        .get(HELYX_SERVICE_NAMES.configuration)
+        .get(context.guildId, ACCOUNT_GATE_IDENTITY.moduleId);
+    if (!configured)
+        throw new DashboardActionValidationError("Save Access Control settings before posting the panel.");
+    const configuration = parseAccountGateConfiguration(configured.value);
+    const store = records(context);
+    const existing = await currentPanelOrNull(context, context.correlationId);
+    if (existing)
+        return inspectedDetail(context, existing);
+    const panelCount = await store.count({
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        collection: "gate_panels",
+        where: { guild_id: context.guildId },
+    });
+    if (panelCount >= MAX_GATE_PANELS) {
+        throw panelLimitError();
+    }
+    const accessType = configuration.accessType;
+    const messageBody = panelMessageFromValue(value, DEFAULT_PANEL_MESSAGES[accessType]);
+    const password = await panelPasswordForCreate(configuration, accessType, value);
+    const panelId = context.correlationId;
+    const sent = await context.sendToChannel(configuration.gateChannelId, panelMessage(messageBody, accessType, panelId));
+    const now = new Date();
+    const row = {
+        panel_id: panelId,
+        guild_id: context.guildId,
+        channel_id: configuration.gateChannelId,
+        message_id: sent.messageId,
+        message_body: messageBody,
+        access_type: accessType,
+        ...(password
+            ? {
+                password_hash: password.encodedHash,
+                password_ignore_case: password.ignoreCase,
+                password_trim_whitespace: password.trimWhitespace,
+            }
+            : {}),
+        revision: 1,
+        created_at: now,
+        updated_at: now,
+    };
+    try {
+        const created = await store.appendUnique({
+            moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+            collection: "gate_panels",
+            uniqueBy: ["panel_id"],
+            values: row,
+        });
+        if (!created.created) {
+            await context
+                .deleteChannelMessage(configuration.gateChannelId, sent.messageId)
+                .catch(() => undefined);
+            const concurrent = await currentPanelOrNull(context, context.correlationId);
+            if (concurrent)
+                return inspectedDetail(context, concurrent);
+            throw new DashboardActionValidationError("That gate-panel request was already handled. Reload the resources list.");
+        }
+    }
+    catch (error) {
+        await context
+            .deleteChannelMessage(configuration.gateChannelId, sent.messageId)
+            .catch(() => undefined);
+        const concurrent = await currentPanelOrNull(context, context.correlationId);
+        if (concurrent)
+            return inspectedDetail(context, concurrent);
+        if ((await store.count({
+            moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+            collection: "gate_panels",
+            where: { guild_id: context.guildId },
+        })) >= MAX_GATE_PANELS) {
+            throw panelLimitError();
+        }
+        throw error;
+    }
+    return detail({
+        ...row,
+        guild_id: context.guildId,
+        channel_id: configuration.gateChannelId,
+        message_id: sent.messageId,
+        message_body: messageBody,
+    }, "posted");
+}
+function panelMessage(messageBody, accessType, panelId) {
+    if (accessType === "emoji") {
+        return {
+            allowedUserMentionIds: [],
+            componentsV2: {
+                text: [
+                    {
+                        content: messageBody,
+                        markdown: false,
+                    },
+                ],
+            },
+        };
+    }
+    return {
+        allowedUserMentionIds: [],
+        componentsV2: {
+            ...(accessType === "challenges" ? { accentColor: VIOLET } : {}),
+            text: [
+                ...(accessType === "challenges"
+                    ? [{ content: "## Complete Access Control" }]
+                    : []),
+                {
+                    content: messageBody,
+                    markdown: false,
+                },
+            ],
+        },
+        buttons: [
+            {
+                type: "button",
+                customId: `${ACCOUNT_GATE_COMPONENTS.startPrefix}${panelId}`,
+                label: "Start check",
+                style: "primary",
+            },
+        ],
+    };
+}
+async function configuredAccessType(context) {
+    const configured = await context.services
+        .get(HELYX_SERVICE_NAMES.configuration)
+        .get(context.guildId, ACCOUNT_GATE_IDENTITY.moduleId);
+    if (!configured)
+        return "challenges";
+    return parseAccountGateConfiguration(configured.value).accessType;
+}
+async function inspectedDetail(context, row) {
+    const inspected = await context.services
+        .get(HELYX_SERVICE_NAMES.discordResources)
+        .inspectMessage({
+        guildId: context.guildId,
+        channelId: stringValue(row.channel_id),
+        messageId: stringValue(row.message_id),
+    });
+    return detail(row, inspected.exists && inspected.guildMatches && inspected.channelMatches
+        ? "posted"
+        : "missing");
+}
+function detail(row, status) {
+    const updatedAt = row.updated_at instanceof Date ? row.updated_at : new Date(0);
+    const accessType = panelAccessType(row);
+    const panelTitles = {
+        challenges: "Challenge gate panel",
+        password: "Password Entry instructions",
+        emoji: "Emoji Entry instructions",
+    };
+    return {
+        id: stringValue(row.panel_id),
+        revision: numberValue(row.revision),
+        status,
+        title: panelTitles[accessType],
+        description: status === "posted"
+            ? "Published and currently available."
+            : "The saved panel message is missing. Repost it to repair the panel.",
+        attributes: {
+            channelId: stringValue(row.channel_id),
+            messageId: stringValue(row.message_id),
+            accessType,
+            passwordConfigured: accessType === "password" && panelPasswordFromRow(row) !== null,
+        },
+        value: {
+            channelId: stringValue(row.channel_id),
+            messageId: stringValue(row.message_id),
+            accessType,
+            messageBody: savedPanelMessage(row),
+            replacementPhrase: "",
+        },
+        updatedAt: updatedAt.toISOString(),
+    };
+}
+function panelAccessType(row) {
+    const value = row.access_type;
+    if (value === "password" || value === "emoji")
+        return value;
+    return "challenges";
+}
+function panelMessageFromValue(value, fallback) {
+    const candidate = value.messageBody;
+    if (candidate === undefined)
+        return fallback;
+    if (typeof candidate !== "string") {
+        throw new DashboardActionValidationError("Enter a valid Access Control panel message.");
+    }
+    const normalized = candidate.trim();
+    if (normalized.length < 1 || normalized.length > 1000) {
+        throw new DashboardActionValidationError("The Access Control panel message must be between 1 and 1000 characters.");
+    }
+    return normalized;
+}
+function savedPanelMessage(row) {
+    const message = row.message_body;
+    return typeof message === "string" && message.length > 0
+        ? message
+        : DEFAULT_PANEL_MESSAGES[panelAccessType(row)];
+}
+export async function getGatePanelRuntime(store, guildId, panelId) {
+    const row = await store.findOne({
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        collection: "gate_panels",
+        select: accountGateRecords.gate_panels.readableFields,
+        where: { guild_id: guildId, panel_id: panelId },
+    });
+    if (!row)
+        return null;
+    return {
+        accessType: panelAccessType(row),
+        password: panelPasswordFromRow(row),
+    };
+}
+export async function hasPasswordGatePanel(store, guildId) {
+    const page = await store.findMany({
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        collection: "gate_panels",
+        select: accountGateRecords.gate_panels.readableFields,
+        where: { guild_id: guildId, access_type: "password" },
+        orderBy: [
+            { field: "guild_id", direction: "asc" },
+            { field: "created_at", direction: "asc" },
+            { field: "panel_id", direction: "asc" },
+        ],
+        limit: MAX_GATE_PANELS,
+    });
+    return page.records.some((row) => panelPasswordFromRow(row) !== null);
+}
+async function panelPasswordForCreate(configuration, accessType, value) {
+    if (accessType !== "password")
+        return null;
+    const phrase = replacementPhrase(value, true);
+    return {
+        encodedHash: await hashPasswordEntryPhrase(phrase, {
+            ignoreCase: configuration.passwordIgnoreCase,
+            trimWhitespace: configuration.passwordTrimWhitespace,
+        }),
+        ignoreCase: configuration.passwordIgnoreCase,
+        trimWhitespace: configuration.passwordTrimWhitespace,
+    };
+}
+async function panelPasswordForUpdate(context, current, value) {
+    if (panelAccessType(current) !== "password")
+        return null;
+    const existing = panelPasswordFromRow(current);
+    const phrase = replacementPhrase(value, false);
+    if (!phrase) {
+        if (existing)
+            return existing;
+        throw new DashboardActionValidationError("Enter a password containing 4 to 200 characters before publishing this panel.");
+    }
+    const configured = await context.services
+        .get(HELYX_SERVICE_NAMES.configuration)
+        .get(context.guildId, ACCOUNT_GATE_IDENTITY.moduleId);
+    if (!configured) {
+        throw new DashboardActionValidationError("Save Access Control settings before changing this password.");
+    }
+    const configuration = parseAccountGateConfiguration(configured.value);
+    return {
+        encodedHash: await hashPasswordEntryPhrase(phrase, {
+            ignoreCase: configuration.passwordIgnoreCase,
+            trimWhitespace: configuration.passwordTrimWhitespace,
+        }),
+        ignoreCase: configuration.passwordIgnoreCase,
+        trimWhitespace: configuration.passwordTrimWhitespace,
+    };
+}
+function panelPasswordFromRow(row) {
+    if (typeof row.password_hash !== "string" || row.password_hash.length < 1) {
+        return null;
+    }
+    return {
+        encodedHash: row.password_hash,
+        ignoreCase: typeof row.password_ignore_case === "boolean"
+            ? row.password_ignore_case
+            : true,
+        trimWhitespace: typeof row.password_trim_whitespace === "boolean"
+            ? row.password_trim_whitespace
+            : true,
+    };
+}
+function replacementPhrase(value, required) {
+    const candidate = value.replacementPhrase;
+    if ((candidate === undefined || candidate === "") && !required)
+        return "";
+    if (typeof candidate !== "string" ||
+        candidate.length < 4 ||
+        candidate.length > 200) {
+        throw new DashboardActionValidationError("Enter a password containing 4 to 200 characters.");
+    }
+    return candidate;
+}
+function panelLimitError() {
+    return new DashboardActionValidationError("You have reached your limit of 10 gate panels. Delete an unused gate before publishing another.");
+}
+function records(context) {
+    return context.services.get(HELYX_SERVICE_NAMES.records);
+}
+function stringValue(value) {
+    if (typeof value !== "string")
+        throw new Error("Access Control panel record is invalid");
+    return value;
+}
+function numberValue(value) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value))
+        throw new Error("Access Control panel record is invalid");
+    return value;
+}
+//# sourceMappingURL=panel-resource.js.map

package/dist/password-entry.d.ts

@@ -0,0 +1,8 @@
+export interface PasswordComparisonRules {
+    ignoreCase: boolean;
+    trimWhitespace: boolean;
+}
+export declare function hashPasswordEntryPhrase(phrase: string, rules: PasswordComparisonRules): Promise<string>;
+export declare function verifyPasswordEntry(input: string, encodedHash: string, rules: PasswordComparisonRules): Promise<boolean>;
+export declare function normalizePasswordEntry(phrase: string, rules: PasswordComparisonRules): string;
+//# sourceMappingURL=password-entry.d.ts.map

package/dist/password-entry.js

@@ -0,0 +1,59 @@
+import { randomBytes, scrypt, timingSafeEqual } from "node:crypto";
+const KEY_LENGTH = 32;
+const MAXIMUM_PHRASE_LENGTH = 200;
+export async function hashPasswordEntryPhrase(phrase, rules) {
+    const normalized = normalizePasswordEntry(phrase, rules);
+    validatePhrase(normalized);
+    const salt = randomBytes(16);
+    const key = await deriveKey(normalized, salt);
+    return `scrypt$16384$8$1$${salt.toString("base64url")}$${key.toString("base64url")}`;
+}
+export async function verifyPasswordEntry(input, encodedHash, rules) {
+    const parts = encodedHash.split("$");
+    if (parts.length !== 6 ||
+        parts[0] !== "scrypt" ||
+        parts[1] !== "16384" ||
+        parts[2] !== "8" ||
+        parts[3] !== "1") {
+        return false;
+    }
+    const normalized = normalizePasswordEntry(input, rules);
+    if (normalized.length < 1 || normalized.length > MAXIMUM_PHRASE_LENGTH) {
+        return false;
+    }
+    try {
+        const salt = Buffer.from(parts[4] ?? "", "base64url");
+        const expected = Buffer.from(parts[5] ?? "", "base64url");
+        if (salt.length !== 16 || expected.length !== KEY_LENGTH)
+            return false;
+        const actual = await deriveKey(normalized, salt);
+        return timingSafeEqual(actual, expected);
+    }
+    catch {
+        return false;
+    }
+}
+export function normalizePasswordEntry(phrase, rules) {
+    let normalized = phrase.normalize("NFKC");
+    if (rules.trimWhitespace)
+        normalized = normalized.trim();
+    if (rules.ignoreCase)
+        normalized = normalized.toLocaleLowerCase("en-GB");
+    return normalized;
+}
+function validatePhrase(phrase) {
+    if (phrase.length < 4 || phrase.length > MAXIMUM_PHRASE_LENGTH) {
+        throw new Error("Shared phrase must contain 4 to 200 characters");
+    }
+}
+function deriveKey(input, salt) {
+    return new Promise((resolve, reject) => {
+        scrypt(input, salt, KEY_LENGTH, { N: 16_384, r: 8, p: 1 }, (error, derivedKey) => {
+            if (error)
+                reject(error);
+            else
+                resolve(derivedKey);
+        });
+    });
+}
+//# sourceMappingURL=password-entry.js.map

package/dist/password-resource.d.ts

@@ -0,0 +1,8 @@
+import type { ModuleManagedResource, ModuleRecordService } from "@helyx/sdk";
+export declare const passwordEntryPhraseResource: ModuleManagedResource;
+export declare function getPasswordSecret(records: ModuleRecordService, guildId: string): Promise<{
+    encodedHash: string;
+    ignoreCase: boolean;
+    trimWhitespace: boolean;
+} | null>;
+//# sourceMappingURL=password-resource.d.ts.map