@helyx/bot 1.5.2 → 1.5.4

package/dist/guild-message-protection-deletion.js

@@ -0,0 +1,138 @@
+import { captureCachedMessageDeletionAuthority, } from "./cached-message-deletion-authority.js";
+/** Separate lexical scope: queued grants never capture an execute/Message environment. */
+export function createProtectionDeliveryLifetime() {
+    let stopped = false;
+    return Object.freeze({
+        isStopped: () => stopped,
+        stop: () => {
+            stopped = true;
+        },
+    });
+}
+/** Explicit private composition only; never derive configuration from mutable client identity. */
+export function createMessageProtectionAuthorityFactory(client, expectedApplicationId, eligibility, deletion) {
+    if (expectedApplicationId === undefined)
+        return undefined;
+    if (typeof expectedApplicationId !== "string" ||
+        !/^\d{17,20}$/u.test(expectedApplicationId))
+        throw new TypeError("Invalid protection application identity");
+    if (!eligibility || !deletion)
+        return undefined;
+    return (source, isStopped) => captureCachedMessageDeletionAuthority({
+        client,
+        expectedApplicationId,
+        eligibility,
+        isStopped,
+        source,
+    });
+}
+const expired = Promise.resolve(Object.freeze({ outcome: "expired-event", issued: false, attempts: 0 }));
+const unavailable = Promise.resolve(Object.freeze({ outcome: "unavailable", issued: false, attempts: 0 }));
+const unknownFailure = Promise.resolve(Object.freeze({ outcome: "failed", issued: "unknown", attempts: null }));
+/** Handler-local owner; only its content-free grant is handed to the queue. */
+export function createProtectionDeletionOperation(input, deletion, strict, captured, isActive) {
+    let owned = captured ? ownOnce(captured) : undefined;
+    let result;
+    let entering = false;
+    let inspecting = false;
+    const releaseUnused = () => {
+        const unused = owned;
+        owned = undefined;
+        unused?.stop();
+    };
+    return Object.freeze({
+        releaseUnused,
+        invoke: () => {
+            if (inspecting)
+                return unavailable;
+            let active = false;
+            try {
+                inspecting = true;
+                active = isActive() === true;
+            }
+            catch {
+                /* Unknown event admission fails closed. */
+            }
+            finally {
+                inspecting = false;
+            }
+            if (!active) {
+                releaseUnused();
+                return expired;
+            }
+            if (result)
+                return result;
+            if (entering)
+                return unavailable;
+            if (!deletion || (strict && !owned)) {
+                releaseUnused();
+                return (result = unavailable);
+            }
+            const provided = owned;
+            owned = undefined;
+            entering = true;
+            try {
+                const handle = deletion.enqueueCaptured(input, provided);
+                // Store before releasing unused authority: stop may synchronously reenter.
+                result = handle.result;
+                if (!handle.retainedProvidedAuthority)
+                    provided?.stop();
+                return result;
+            }
+            catch {
+                // The actual queue returns a safely fulfilled shared result; this is a sync port failure.
+                result = unknownFailure;
+                provided?.stop();
+                return result;
+            }
+            finally {
+                entering = false;
+            }
+        },
+    });
+}
+function ownOnce(captured) {
+    try {
+        const original = captured.scope;
+        const scope = Object.freeze({
+            guildId: original.guildId,
+            moduleId: original.moduleId,
+            channelId: original.channelId,
+            messageId: original.messageId,
+            admissionToken: original.admissionToken,
+        });
+        const current = captured.isCurrent, stop = captured.stop;
+        if (typeof current !== "function" || typeof stop !== "function")
+            return undefined;
+        let released = false;
+        return Object.freeze({
+            scope,
+            isCurrent: () => {
+                if (released)
+                    return false;
+                try {
+                    const valid = current();
+                    return !released && valid === true;
+                }
+                catch {
+                    return false;
+                }
+            },
+            stop: () => {
+                if (released)
+                    return;
+                released = true;
+                try {
+                    stop();
+                }
+                catch {
+                    /* Cleanup cannot replace an actual outcome. */
+                }
+            },
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=guild-message-protection-deletion.js.map

package/dist/guild-message-protection-delivery.d.ts

@@ -0,0 +1,41 @@
+import { type GuildMessageCreateContribution, type ServiceAccess } from "@helyx/sdk";
+import type { Message } from "discord.js";
+import type { EmergencyDeletionDispatcher } from "./emergency-deletion-dispatcher.js";
+import { type MessageProtectionAuthorityFactory } from "./guild-message-protection-deletion.js";
+/** Trusted runtime memory only. No SQL, Redis or network fallback is permitted. */
+export interface MessageProtectionEligibility {
+    read(this: void, guildId: string, moduleId: string): {
+        state: "enabled";
+        generation: string;
+    } | {
+        state: "disabled" | "unavailable";
+    };
+    isCurrent(this: void, generation: string): boolean;
+}
+interface Recipient {
+    moduleId: string;
+    classificationRequested: boolean;
+    deletionAllowed: boolean;
+    contribution: GuildMessageCreateContribution;
+}
+interface Admission {
+    recipient: Recipient;
+    generation: string;
+}
+/** Owns the exact-event lifetime; never exposes the private source object. */
+export declare class GuildMessageProtectionDelivery {
+    #private;
+    private readonly eligibility;
+    private readonly services;
+    private readonly contentIntent;
+    private readonly ownUserId;
+    private readonly ownApplicationId;
+    private readonly deletion?;
+    private readonly authorityFactory?;
+    constructor(eligibility: MessageProtectionEligibility | undefined, services: ServiceAccess, contentIntent: boolean, ownUserId: () => string | undefined, ownApplicationId: () => string | undefined, deletion?: EmergencyDeletionDispatcher | undefined, authorityFactory?: MessageProtectionAuthorityFactory | undefined);
+    select(message: Message, recipients: readonly Recipient[]): Admission[];
+    execute(message: Message, admissions: readonly Admission[], onError: (moduleId: string, error: unknown) => void): Promise<void>;
+    stop(): void;
+}
+export {};
+//# sourceMappingURL=guild-message-protection-delivery.d.ts.map

package/dist/guild-message-protection-delivery.js

@@ -0,0 +1,223 @@
+import { HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { snapshotProtectionAuthorRoles } from "./guild-message-protection-author-roles.js";
+import { createProtectionDeletionOperation, createProtectionDeliveryLifetime, } from "./guild-message-protection-deletion.js";
+import { summarizeProtectionMessage, unavailableProtectionSnapshot, } from "./message-protection-summary.js";
+/** Owns the exact-event lifetime; never exposes the private source object. */
+export class GuildMessageProtectionDelivery {
+    eligibility;
+    services;
+    contentIntent;
+    ownUserId;
+    ownApplicationId;
+    deletion;
+    authorityFactory;
+    #lifetime = createProtectionDeliveryLifetime();
+    #revoke = new Set();
+    constructor(eligibility, services, contentIntent, ownUserId, ownApplicationId, deletion, authorityFactory) {
+        this.eligibility = eligibility;
+        this.services = services;
+        this.contentIntent = contentIntent;
+        this.ownUserId = ownUserId;
+        this.ownApplicationId = ownApplicationId;
+        this.deletion = deletion;
+        this.authorityFactory = authorityFactory;
+    }
+    select(message, recipients) {
+        if (!this.#safeSource(message))
+            return [];
+        return recipients.flatMap((recipient) => {
+            const options = recipient.contribution.protection;
+            if (!options ||
+                (message.webhookId
+                    ? !options.webhooks
+                    : message.author.bot && !options.otherBots))
+                return [];
+            const generation = this.#generation(message.guildId, recipient.moduleId);
+            return generation ? [{ recipient, generation }] : [];
+        });
+    }
+    async execute(message, admissions, onError) {
+        const guildId = message.guildId;
+        let snapshot;
+        for (const { recipient, generation } of admissions) {
+            const current = () => !this.#lifetime.isStopped() &&
+                Boolean(guildId) &&
+                this.#generation(guildId, recipient.moduleId) === generation;
+            if (!this.#safeSource(message) || !current())
+                continue;
+            const { moduleId, contribution, classificationRequested } = recipient;
+            let source = message;
+            let active = true;
+            let deletionOperation;
+            const revoke = () => {
+                active = false;
+                source = undefined;
+                deletionOperation?.releaseUnused();
+            };
+            this.#revoke.add(revoke);
+            try {
+                const { channelId, id: messageId } = message;
+                const authorId = message.author.id;
+                const webhook = Boolean(message.webhookId);
+                const authorRoles = snapshotProtectionAuthorRoles(message, webhook);
+                const thread = message.channel.isThread();
+                const parentChannelId = thread
+                    ? (message.channel.parentId ?? undefined)
+                    : undefined;
+                const categoryId = thread
+                    ? (message.channel.parent?.parentId ?? undefined)
+                    : "parentId" in message.channel
+                        ? (message.channel.parentId ?? undefined)
+                        : undefined;
+                const context = {
+                    serverId: guildId,
+                    channelId,
+                    messageId,
+                    ...(parentChannelId ? { parentChannelId } : {}),
+                    ...(categoryId ? { categoryId } : {}),
+                    isReply: Boolean(message.reference?.messageId),
+                    authorId,
+                    authorDisplayName: (message.member?.displayName ??
+                        message.author.globalName ??
+                        message.author.username).slice(0, 128),
+                    ...authorRoles,
+                    authorIsBot: message.author.bot,
+                    authorIsWebhook: webhook,
+                    authorIsSystem: false,
+                    mentionedUserIds: Object.freeze(boundedIds(message.mentions.users.keys(), 25)),
+                    classification: Object.freeze({
+                        available: false,
+                        kinds: [],
+                    }),
+                    createdAt: new Date(message.createdAt.getTime()),
+                    services: this.services,
+                    addAuthorRole: async (roleId) => {
+                        await this.services
+                            .get(HELYX_SERVICE_NAMES.memberRoles)
+                            .addApprovedRole({
+                            guildId: guildId,
+                            memberUserId: authorId,
+                            roleId,
+                            moduleId,
+                            reason: "Guild message contribution author role addition",
+                        });
+                    },
+                    removeAuthorRole: async (roleId) => {
+                        await this.services
+                            .get(HELYX_SERVICE_NAMES.memberRoles)
+                            .removeApprovedRole({
+                            guildId: guildId,
+                            memberUserId: authorId,
+                            roleId,
+                            moduleId,
+                            reason: "Guild message contribution author role removal",
+                        });
+                    },
+                    sendToChannel: (targetChannelId, response) => this.services
+                        .get(HELYX_SERVICE_NAMES.discordMessages)
+                        .send({
+                        guildId: guildId,
+                        channelId: targetChannelId,
+                        response,
+                    }),
+                };
+                if (contribution.protection?.summary)
+                    context.getProtectionSnapshot = () => {
+                        if (!active || !source || !current()) {
+                            revoke();
+                            return unavailableProtectionSnapshot("expired-event");
+                        }
+                        if (!classificationRequested || !this.contentIntent)
+                            return unavailableProtectionSnapshot("capability-unavailable");
+                        snapshot ??= summarizeProtectionMessage(source);
+                        return snapshot;
+                    };
+                if (contribution.protection?.deleteMessage &&
+                    recipient.deletionAllowed) {
+                    const input = Object.freeze({
+                        guildId: guildId,
+                        moduleId,
+                        channelId,
+                        messageId,
+                        admissionToken: generation,
+                    });
+                    let authority;
+                    if (this.authorityFactory && this.deletion) {
+                        try {
+                            if (message.inGuild())
+                                authority = this.authorityFactory(Object.freeze({ ...input, channel: message.channel }), this.#lifetime.isStopped);
+                        }
+                        catch {
+                            /* Strict capture failure never falls back to primitive-only enqueue. */
+                        }
+                    }
+                    deletionOperation = createProtectionDeletionOperation(input, this.deletion, this.authorityFactory !== undefined, authority, () => active && current());
+                    context.deleteMessage = deletionOperation.invoke;
+                }
+                if (!current())
+                    continue;
+                await contribution.execute(Object.freeze(context));
+            }
+            catch (error) {
+                onError(moduleId, error);
+            }
+            finally {
+                revoke();
+                this.#revoke.delete(revoke);
+            }
+        }
+    }
+    stop() {
+        this.#lifetime.stop();
+        for (const revoke of this.#revoke)
+            revoke();
+        this.#revoke.clear();
+    }
+    #generation(guildId, moduleId) {
+        try {
+            if (this.#lifetime.isStopped())
+                return undefined;
+            const admission = this.eligibility?.read(guildId, moduleId);
+            if (this.#lifetime.isStopped() || admission?.state !== "enabled")
+                return undefined;
+            const generation = admission.generation;
+            const current = generation && this.eligibility?.isCurrent(generation);
+            return !this.#lifetime.isStopped() && current === true
+                ? generation
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    #safeSource(message) {
+        const ownId = this.ownUserId();
+        const applicationId = this.ownApplicationId();
+        return Boolean(!this.#lifetime.isStopped() &&
+            ownId &&
+            applicationId &&
+            message.guildId &&
+            message.author?.id &&
+            typeof message.author.bot === "boolean" &&
+            typeof message.author.system === "boolean" &&
+            typeof message.system === "boolean" &&
+            (message.webhookId === null || typeof message.webhookId === "string") &&
+            (message.applicationId === null ||
+                typeof message.applicationId === "string") &&
+            !message.author.system &&
+            !message.system &&
+            message.author.id !== ownId &&
+            message.applicationId !== applicationId &&
+            message.webhookId !== applicationId);
+    }
+}
+function boundedIds(ids, limit) {
+    const result = [];
+    for (const id of ids) {
+        if (result.length === limit)
+            break;
+        result.push(id);
+    }
+    return result;
+}
+//# sourceMappingURL=guild-message-protection-delivery.js.map

package/dist/guild-message-update-metadata.d.ts

@@ -0,0 +1,32 @@
+import type { GuildMessageUpdateMetadataContext, GuildMessageUpdateMetadataContribution } from "@helyx/sdk";
+import type { Client, Message, PartialMessage } from "discord.js";
+import type { MessageProtectionEligibility } from "./guild-message-protection-delivery.js";
+interface Recipient {
+    readonly moduleId: string;
+    readonly contribution: GuildMessageUpdateMetadataContribution;
+}
+interface Admission extends Recipient {
+    readonly generation: string;
+}
+interface Capture {
+    readonly context: Readonly<GuildMessageUpdateMetadataContext>;
+    current(): boolean;
+}
+/** Dormant metadata only. Queued tasks never retain the mutable source Message. */
+export declare class GuildMessageUpdateMetadataDelivery {
+    #private;
+    private readonly client;
+    private readonly expectedApplicationId;
+    private readonly eligibility;
+    constructor(client: Client, expectedApplicationId: string | undefined, eligibility: MessageProtectionEligibility | undefined);
+    prepare(message: Message | PartialMessage, recipients: readonly Recipient[], onError: (moduleId: string, error: unknown) => void): {
+        guildId: string;
+        run(this: void): Promise<void>;
+    } | undefined;
+    execute(capture: Capture, admissions: readonly Admission[], onError: (moduleId: string, error: unknown) => void): Promise<void>;
+    stop(): void;
+    private generation;
+    private capture;
+}
+export {};
+//# sourceMappingURL=guild-message-update-metadata.d.ts.map

package/dist/guild-message-update-metadata.js

@@ -0,0 +1,255 @@
+import { ChannelType } from "discord.js";
+import { snapshotProtectionAuthorRoles } from "./guild-message-protection-author-roles.js";
+const snowflake = /^\d{17,20}$/u;
+/** Dormant metadata only. Queued tasks never retain the mutable source Message. */
+export class GuildMessageUpdateMetadataDelivery {
+    client;
+    expectedApplicationId;
+    eligibility;
+    #stopped = false;
+    constructor(client, expectedApplicationId, eligibility) {
+        this.client = client;
+        this.expectedApplicationId = expectedApplicationId;
+        this.eligibility = eligibility;
+    }
+    prepare(message, recipients, onError) {
+        if (this.#stopped || !recipients.length)
+            return undefined;
+        const capture = this.capture(message);
+        if (!capture)
+            return undefined;
+        const admissions = [];
+        for (const recipient of recipients) {
+            const metadata = recipient.contribution.metadata;
+            if (metadata?.version !== 1)
+                continue;
+            if (capture.context.authorIsWebhook
+                ? metadata.webhooks !== true
+                : capture.context.authorIsBot && metadata.otherBots !== true)
+                continue;
+            const generation = this.generation(capture.context.serverId, recipient.moduleId);
+            if (generation)
+                admissions.push({ ...recipient, generation });
+        }
+        return admissions.length
+            ? task(this, capture, admissions, onError)
+            : undefined;
+    }
+    async execute(capture, admissions, onError) {
+        for (const { moduleId, contribution, generation } of admissions) {
+            if (this.generation(capture.context.serverId, moduleId) !== generation ||
+                !capture.current())
+                continue;
+            try {
+                await contribution.execute(capture.context);
+            }
+            catch (error) {
+                onError(moduleId, error);
+            }
+        }
+    }
+    stop() {
+        this.#stopped = true;
+    }
+    generation(guildId, moduleId) {
+        try {
+            if (this.#stopped)
+                return undefined;
+            const observed = this.eligibility?.read(guildId, moduleId);
+            if (this.#stopped ||
+                observed?.state !== "enabled" ||
+                typeof observed.generation !== "string" ||
+                !observed.generation.length ||
+                observed.generation.length > 256)
+                return undefined;
+            const current = this.eligibility?.isCurrent(observed.generation);
+            return !this.#stopped && current === true
+                ? observed.generation
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    capture(message) {
+        try {
+            const expected = this.expectedApplicationId;
+            const ownUserId = this.client.user?.id;
+            // Pinned Discord.js partial getter reads content. Check its data-property
+            // shape without invoking content accessors or inspecting/retaining text.
+            const contentShape = Object.getOwnPropertyDescriptor(message, "content");
+            if (!expected ||
+                !snowflake.test(expected) ||
+                !ownUserId ||
+                !snowflake.test(ownUserId) ||
+                !contentShape ||
+                !("value" in contentShape) ||
+                typeof contentShape.value !== "string" ||
+                message.client !== this.client ||
+                !message.guildId ||
+                !snowflake.test(message.guildId) ||
+                !snowflake.test(message.channelId) ||
+                !snowflake.test(message.id))
+                return undefined;
+            const guild = message.guild, channel = message.channel, author = message.author;
+            if (!guild ||
+                !channel ||
+                channel.isDMBased() ||
+                !author ||
+                !snowflake.test(author.id) ||
+                typeof author.bot !== "boolean" ||
+                author.system !== false ||
+                message.system !== false ||
+                (message.webhookId !== null &&
+                    (typeof message.webhookId !== "string" ||
+                        !snowflake.test(message.webhookId))) ||
+                (message.applicationId !== null &&
+                    (typeof message.applicationId !== "string" ||
+                        !snowflake.test(message.applicationId))) ||
+                author.id === ownUserId ||
+                message.applicationId === expected ||
+                message.webhookId === expected)
+                return undefined;
+            const roles = snapshotProtectionAuthorRoles(message, Boolean(message.webhookId));
+            if (roles.authorRolesResolved !== true)
+                return undefined;
+            const created = timestamp(message.createdTimestamp), updated = timestamp(message.editedTimestamp);
+            if (!created || !updated || updated < created)
+                return undefined;
+            const parent = channel.isThread() ? channel.parent : undefined;
+            if (channel.isThread() && !parent)
+                return undefined;
+            const categoryId = parent ? parent.parentId : channel.parentId;
+            const category = categoryId
+                ? guild.channels.cache.get(categoryId)
+                : undefined;
+            if (categoryId &&
+                (!snowflake.test(categoryId) ||
+                    !category ||
+                    category.type !== ChannelType.GuildCategory))
+                return undefined;
+            const current = combineWitnesses(relationships(this.client, expected, ownUserId, guild, channel, parent, category), roleWitness(this.client, guild, author.id, Boolean(message.webhookId), roles.authorRoleIds));
+            if (!current() ||
+                message.guildId !== guild.id ||
+                message.channelId !== channel.id)
+                return undefined;
+            return Object.freeze({
+                context: Object.freeze({
+                    serverId: guild.id,
+                    channelId: channel.id,
+                    messageId: message.id,
+                    ...(parent ? { parentChannelId: parent.id } : {}),
+                    ...(categoryId ? { categoryId } : {}),
+                    authorId: author.id,
+                    authorRoleIds: roles.authorRoleIds,
+                    authorRolesResolved: true,
+                    authorIsBot: author.bot,
+                    authorIsWebhook: Boolean(message.webhookId),
+                    authorIsSystem: false,
+                    partial: false,
+                    createdAt: created,
+                    updatedAt: updated,
+                }),
+                current,
+            });
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+function timestamp(value) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
+        return undefined;
+    const date = new Date(value);
+    if (!Number.isFinite(date.getTime()))
+        return undefined;
+    const result = date.toISOString();
+    return result.length === 24 ? result : undefined;
+}
+function combineWitnesses(...witnesses) {
+    return () => witnesses.every((current) => current());
+}
+/** Current cached assignment proof. This closure never captures Message. */
+function roleWitness(client, guild, authorId, webhook, ids) {
+    if (webhook)
+        return () => true;
+    const member = guild.members.cache.get(authorId);
+    if (!member)
+        return () => false;
+    const assigned = Reflect.get(member, "_roles");
+    if (!Array.isArray(assigned) || assigned.length > 250)
+        return () => false;
+    const snapshot = [];
+    for (let index = 0, length = assigned.length; index < length; index++)
+        snapshot.push(assigned[index]);
+    const roles = ids.map((id) => ({ id, role: guild.roles.cache.get(id) }));
+    return () => {
+        try {
+            return (guild.members.cache.get(authorId) === member &&
+                member.guild === guild &&
+                member.client === client &&
+                member.id === authorId &&
+                member.user.id === authorId &&
+                member.partial === false &&
+                Reflect.get(member, "_roles") === assigned &&
+                assigned.length === snapshot.length &&
+                snapshot.every((id, index) => assigned[index] === id) &&
+                roles.every(({ id, role }) => Boolean(role &&
+                    guild.roles.cache.get(id) === role &&
+                    role.id === id &&
+                    role.guild === guild &&
+                    role.client === client)));
+        }
+        catch {
+            return false;
+        }
+    };
+}
+/** Own lexical scope contains cached relationship witnesses, never Message. */
+function relationships(client, expected, ownUserId, guild, channel, parent, category) {
+    const channelId = channel.id, guildId = guild.id, parentId = parent?.id, categoryId = category?.id;
+    return () => {
+        try {
+            return Boolean(client.isReady() === true &&
+                client.user?.id === ownUserId &&
+                client.application?.id === expected &&
+                client.guilds.cache.get(guildId) === guild &&
+                guild.id === guildId &&
+                guild.client === client &&
+                guild.available === true &&
+                channel.guild === guild &&
+                channel.client === client &&
+                channel.id === channelId &&
+                guild.channels.cache.get(channelId) === channel &&
+                client.channels.cache.get(channelId) === channel &&
+                (!parent ||
+                    (parent.guild === guild &&
+                        parent.client === client &&
+                        parent.id === parentId &&
+                        guild.channels.cache.get(parentId) === parent)) &&
+                (!category ||
+                    (category.guild === guild &&
+                        category.client === client &&
+                        category.id === categoryId &&
+                        guild.channels.cache.get(categoryId) === category)) &&
+                (channel.isThread()
+                    ? channel.parentId === parentId &&
+                        parent &&
+                        "parentId" in parent &&
+                        parent.parentId === (categoryId ?? null)
+                    : channel.parentId === (categoryId ?? null)));
+        }
+        catch {
+            return false;
+        }
+    };
+}
+/** Queue closure is created outside the capture scope, with no source Message. */
+function task(delivery, capture, admissions, onError) {
+    return Object.freeze({
+        guildId: capture.context.serverId,
+        run: () => delivery.execute(capture, admissions, onError),
+    });
+}
+//# sourceMappingURL=guild-message-update-metadata.js.map