@helyx/module-automod 1.0.1

package/dist/engine/similar-message-window.d.ts

@@ -0,0 +1,68 @@
+import { type CompiledEnhancedConfiguration, type EnhancedScanResult } from "./contracts.js";
+export interface SimilarMessageWindowOptions {
+    ttlMs: number;
+    occurrenceThreshold: number;
+    similarityThreshold: number;
+    maximumMembers: number;
+    maximumFingerprints: number;
+    maximumBytes: number;
+    maximumFeaturesPerMessage: number;
+}
+export interface SimilarMessageWindowMetrics {
+    members: number;
+    fingerprints: number;
+    bytes: number;
+    evictions: number;
+    overflows: number;
+}
+export declare class SimilarMessageWindow {
+    #private;
+    constructor(secret: Uint8Array, options?: Partial<SimilarMessageWindowOptions>);
+    observe(input: {
+        guildId: string;
+        memberId: string;
+        channelId: string;
+        content: string;
+        observedAtMs: number;
+    }): {
+        outcome: "recorded";
+        count: number;
+    } | {
+        outcome: "similar_message";
+        count: number;
+        similarity: number;
+        confidenceScore: number;
+    } | {
+        outcome: "ignored";
+        reason: "insufficient_content" | "message_size_limit";
+    };
+    metrics(): SimilarMessageWindowMetrics;
+    clear(): void;
+}
+export declare function scanSimilarMessage(configuration: CompiledEnhancedConfiguration, window: SimilarMessageWindow, input: {
+    guildId: string;
+    memberId: string;
+    channelId: string;
+    parentChannelId: string | null;
+    memberRoleIds: readonly string[];
+    content: string;
+    observedAtMs: number;
+    source: "user" | "bot" | "webhook" | "system" | "unknown";
+}): EnhancedScanResult;
+/**
+ * Runs the stateless detectors and the bounded cross-channel window for the
+ * same observation. Contextual state is updated even when a stronger direct
+ * match wins, so Hosted Ecko and the embedded scanner retain identical spam
+ * semantics.
+ */
+export declare function scanEnhancedMessageWithContext(configuration: CompiledEnhancedConfiguration, window: SimilarMessageWindow, input: {
+    guildId: string;
+    memberId: string;
+    channelId: string;
+    parentChannelId: string | null;
+    memberRoleIds: readonly string[];
+    content: string;
+    observedAtMs: number;
+    source: "user" | "bot" | "webhook" | "system" | "unknown";
+}): EnhancedScanResult;
+//# sourceMappingURL=similar-message-window.d.ts.map

package/dist/engine/similar-message-window.js

@@ -0,0 +1,259 @@
+import { createHmac } from "node:crypto";
+import { canonicaliseText } from "./canonicalisation.js";
+import { confidenceClass } from "./confidence.js";
+import { scanEnhancedMessage } from "./matcher.js";
+import { ENHANCED_ENGINE_LIMITS, } from "./contracts.js";
+const DEFAULT_OPTIONS = Object.freeze({
+    ttlMs: 5 * 60_000,
+    occurrenceThreshold: 3,
+    similarityThreshold: 0.8,
+    maximumMembers: 10_000,
+    maximumFingerprints: 50_000,
+    maximumBytes: 32 * 1_024 * 1_024,
+    maximumFeaturesPerMessage: 64,
+});
+export class SimilarMessageWindow {
+    #secret;
+    #options;
+    #members = new Map();
+    #sequence = 0;
+    #fingerprints = 0;
+    #bytes = 0;
+    #evictions = 0;
+    #overflows = 0;
+    constructor(secret, options = {}) {
+        if (secret.byteLength < 32)
+            throw new Error("Similar-message fingerprint keys require 32 bytes.");
+        this.#secret = new Uint8Array(secret);
+        this.#options = validateOptions({ ...DEFAULT_OPTIONS, ...options });
+    }
+    observe(input) {
+        this.#prune(input.observedAtMs);
+        if (input.content.length > ENHANCED_ENGINE_LIMITS.messageCharacters ||
+            new TextEncoder().encode(input.content).byteLength >
+                ENHANCED_ENGINE_LIMITS.messageUtf8Bytes)
+            return { outcome: "ignored", reason: "message_size_limit" };
+        const canonical = canonicaliseText(input.content).normalisedTokens;
+        const rawFeatures = shingles(canonical, this.#options.maximumFeaturesPerMessage);
+        if (!rawFeatures.length)
+            return { outcome: "ignored", reason: "insufficient_content" };
+        const features = rawFeatures.map((feature) => this.#hash(`f:${feature}`));
+        const digest = this.#hash(`m:${canonical.join(" ")}`);
+        const channelDigest = this.#hash(`c:${input.channelId}`);
+        const memberKey = this.#hash(`s:${input.guildId}:${input.memberId}`);
+        const window = this.#members.get(memberKey) ?? {
+            key: memberKey,
+            records: [],
+            accessed: 0,
+        };
+        const comparable = window.records
+            .map((record) => ({
+            record,
+            similarity: record.digest === digest ? 1 : jaccard(record.features, features),
+        }))
+            .filter(({ similarity }) => similarity >= this.#options.similarityThreshold);
+        const highest = comparable.reduce((maximum, item) => Math.max(maximum, item.similarity), 0);
+        const record = this.#record(digest, features, channelDigest, input.observedAtMs);
+        window.records.push(record);
+        window.accessed = record.accessed;
+        this.#members.set(memberKey, window);
+        this.#fingerprints += 1;
+        this.#bytes += record.bytes;
+        this.#evictToBounds();
+        const count = comparable.length + 1;
+        const channelCount = new Set([
+            channelDigest,
+            ...comparable.map(({ record }) => record.channelDigest),
+        ]).size;
+        return count >= this.#options.occurrenceThreshold && channelCount >= 2
+            ? {
+                outcome: "similar_message",
+                count,
+                similarity: highest,
+                confidenceScore: Math.min(95, Math.max(60, Math.round(highest * 100))),
+            }
+            : { outcome: "recorded", count };
+    }
+    metrics() {
+        return {
+            members: this.#members.size,
+            fingerprints: this.#fingerprints,
+            bytes: this.#bytes,
+            evictions: this.#evictions,
+            overflows: this.#overflows,
+        };
+    }
+    clear() {
+        this.#members.clear();
+        this.#fingerprints = 0;
+        this.#bytes = 0;
+    }
+    #hash(value) {
+        return createHmac("sha256", this.#secret)
+            .update(value)
+            .digest("base64url")
+            .slice(0, 22);
+    }
+    #record(digest, features, channelDigest, observedAtMs) {
+        return {
+            digest,
+            features,
+            channelDigest,
+            observedAtMs,
+            accessed: ++this.#sequence,
+            bytes: 64 + digest.length + channelDigest.length + features.length * 22,
+        };
+    }
+    #prune(observedAtMs) {
+        for (const [memberKey, window] of this.#members) {
+            const retained = [];
+            for (const record of window.records)
+                if (record.observedAtMs + this.#options.ttlMs > observedAtMs)
+                    retained.push(record);
+                else
+                    this.#removeRecord(record);
+            if (retained.length)
+                window.records = retained;
+            else
+                this.#members.delete(memberKey);
+        }
+    }
+    #evictToBounds() {
+        while (this.#members.size > this.#options.maximumMembers ||
+            this.#fingerprints > this.#options.maximumFingerprints ||
+            this.#bytes > this.#options.maximumBytes) {
+            this.#overflows += 1;
+            const oldest = [...this.#members.values()].sort((left, right) => left.accessed - right.accessed || left.key.localeCompare(right.key))[0];
+            if (!oldest)
+                return;
+            const record = oldest.records.shift();
+            if (record)
+                this.#removeRecord(record);
+            if (!oldest.records.length)
+                this.#members.delete(oldest.key);
+            else
+                oldest.accessed = oldest.records[0].accessed;
+            this.#evictions += 1;
+        }
+    }
+    #removeRecord(record) {
+        this.#fingerprints -= 1;
+        this.#bytes -= record.bytes;
+    }
+}
+export function scanSimilarMessage(configuration, window, input) {
+    if (input.source !== "user")
+        return { outcome: "not_scannable", reason: `source_${input.source}` };
+    const detectors = configuration.rules.flatMap((rule) => rule.terms
+        .filter((term) => term.kind === "similar_message")
+        .map((term) => ({ rule, term })));
+    const eligible = detectors.flatMap(({ rule, term }) => ruleExempt(rule, input) ? [] : [{ rule, term }]);
+    if (!eligible.length)
+        return detectors.length
+            ? { outcome: "exempt", reason: "all_rules_exempt" }
+            : { outcome: "not_detected", reason: "no_similar_message_rule" };
+    const observed = window.observe(input);
+    if (observed.outcome !== "similar_message")
+        return {
+            outcome: observed.outcome === "ignored" ? "not_scannable" : "not_detected",
+            reason: observed.outcome === "ignored" ? observed.reason : "window_not_met",
+        };
+    const detections = eligible
+        .map(({ rule, term }) => ({
+        rule,
+        term,
+        threshold: Math.max(configuration.source.categoryThresholds[rule.severity], term.minimumConfidence ?? 60),
+    }))
+        .filter(({ threshold }) => observed.confidenceScore >= threshold)
+        .sort((left, right) => severityRank(right.rule.severity) - severityRank(left.rule.severity) ||
+        left.rule.ruleId.localeCompare(right.rule.ruleId) ||
+        left.term.termId.localeCompare(right.term.termId));
+    const selected = detections[0];
+    if (!selected)
+        return { outcome: "not_detected", reason: "below_threshold" };
+    return {
+        outcome: "detected",
+        detection: {
+            ruleId: selected.rule.ruleId,
+            categoryId: selected.rule.categoryId,
+            termId: selected.term.termId,
+            severity: selected.rule.severity,
+            method: "similar_message",
+            confidenceScore: observed.confidenceScore,
+            confidenceClass: confidenceClass(observed.confidenceScore),
+            effectiveThreshold: selected.threshold,
+            nativeCoverage: "spam",
+            evidence: [],
+        },
+    };
+}
+/**
+ * Runs the stateless detectors and the bounded cross-channel window for the
+ * same observation. Contextual state is updated even when a stronger direct
+ * match wins, so Hosted Ecko and the embedded scanner retain identical spam
+ * semantics.
+ */
+export function scanEnhancedMessageWithContext(configuration, window, input) {
+    const direct = scanEnhancedMessage(configuration, input);
+    const contextual = scanSimilarMessage(configuration, window, input);
+    return direct.outcome === "detected" ? direct : contextual;
+}
+function shingles(tokens, maximum) {
+    if (!tokens.length)
+        return [];
+    const values = new Set();
+    for (let index = 0; index < tokens.length; index += 1) {
+        values.add(tokens[index]);
+        if (index + 1 < tokens.length)
+            values.add(`${tokens[index]} ${tokens[index + 1]}`);
+        if (values.size >= maximum)
+            break;
+    }
+    return [...values].sort().slice(0, maximum);
+}
+function jaccard(left, right) {
+    const leftSet = new Set(left);
+    const rightSet = new Set(right);
+    let intersection = 0;
+    for (const value of leftSet)
+        if (rightSet.has(value))
+            intersection += 1;
+    const union = leftSet.size + rightSet.size - intersection;
+    return union ? intersection / union : 0;
+}
+function validateOptions(options) {
+    if (!Number.isInteger(options.ttlMs) ||
+        options.ttlMs < 1 ||
+        options.ttlMs > 10 * 60_000 ||
+        !Number.isInteger(options.occurrenceThreshold) ||
+        options.occurrenceThreshold < 2 ||
+        options.similarityThreshold < 0.5 ||
+        options.similarityThreshold > 1 ||
+        !Number.isInteger(options.maximumMembers) ||
+        options.maximumMembers < 1 ||
+        !Number.isInteger(options.maximumFingerprints) ||
+        options.maximumFingerprints < options.maximumMembers ||
+        !Number.isInteger(options.maximumBytes) ||
+        options.maximumBytes < 1_024 ||
+        !Number.isInteger(options.maximumFeaturesPerMessage) ||
+        options.maximumFeaturesPerMessage < 1 ||
+        options.maximumFeaturesPerMessage > 128)
+        throw new Error("Similar-message window bounds are invalid.");
+    return Object.freeze(options);
+}
+function ruleExempt(rule, input) {
+    return (rule.exemptChannelIds.includes(input.channelId) ||
+        (input.parentChannelId !== null &&
+            rule.exemptChannelIds.includes(input.parentChannelId)) ||
+        input.memberRoleIds.some((roleId) => rule.exemptRoleIds.includes(roleId)));
+}
+function severityRank(value) {
+    return value === "critical"
+        ? 4
+        : value === "high"
+            ? 3
+            : value === "medium"
+                ? 2
+                : 1;
+}
+//# sourceMappingURL=similar-message-window.js.map

package/dist/engine/term-import.d.ts

@@ -0,0 +1,15 @@
+export interface EnhancedTermImportResult {
+    accepted: readonly string[];
+    duplicateCount: number;
+    rejected: readonly {
+        sourceIndex: number;
+        value: string;
+        code: "term_too_long" | "term_limit" | "empty_canonical_term";
+    }[];
+}
+export declare function parseEnhancedTermImport(content: string, options?: {
+    maximumBytes?: number;
+    maximumTerms?: number;
+    maximumTermCharacters?: number;
+}): EnhancedTermImportResult;
+//# sourceMappingURL=term-import.d.ts.map

package/dist/engine/term-import.js

@@ -0,0 +1,43 @@
+import { canonicalTermKey } from "./canonicalisation.js";
+export function parseEnhancedTermImport(content, options = {}) {
+    const maximumBytes = options.maximumBytes ?? 4_000;
+    const maximumTerms = options.maximumTerms ?? 1_000;
+    const maximumTermCharacters = options.maximumTermCharacters ?? 60;
+    if (new TextEncoder().encode(content).byteLength > maximumBytes)
+        throw new Error("The import exceeds the configured UTF-8 byte limit.");
+    const accepted = [];
+    const rejected = [];
+    const seen = new Set();
+    let duplicateCount = 0;
+    const entries = content.split(/\r?\n|,/u);
+    for (const [sourceIndex, raw] of entries.entries()) {
+        const value = raw.trim();
+        if (!value)
+            continue;
+        const canonical = canonicalTermKey(value.replaceAll("*", ""));
+        if (!canonical) {
+            rejected.push({ sourceIndex, value, code: "empty_canonical_term" });
+            continue;
+        }
+        if (value.length > maximumTermCharacters) {
+            rejected.push({ sourceIndex, value, code: "term_too_long" });
+            continue;
+        }
+        if (seen.has(canonical)) {
+            duplicateCount += 1;
+            continue;
+        }
+        seen.add(canonical);
+        if (accepted.length >= maximumTerms) {
+            rejected.push({ sourceIndex, value, code: "term_limit" });
+            continue;
+        }
+        accepted.push(value);
+    }
+    return {
+        accepted: Object.freeze(accepted),
+        duplicateCount,
+        rejected: Object.freeze(rejected),
+    };
+}
+//# sourceMappingURL=term-import.js.map

package/dist/enhanced-configuration.d.ts

@@ -0,0 +1,16 @@
+import type { AutoModerationScannerConfigurationV1 } from "@helyx/sdk";
+import type { AutoModerationConfiguration } from "./configuration.js";
+import type { AutoModerationRuleDraft } from "./domain.js";
+export interface EnhancedConfigurationRuleSource {
+    ruleId: string;
+    draft: AutoModerationRuleDraft;
+}
+export declare function buildEnhancedScannerConfiguration(input: {
+    guildId: string;
+    configurationRevision: string;
+    configuration: AutoModerationConfiguration;
+    rules: readonly EnhancedConfigurationRuleSource[];
+    refreshAfter: string;
+    expiresAt: string;
+}): AutoModerationScannerConfigurationV1;
+//# sourceMappingURL=enhanced-configuration.d.ts.map

package/dist/enhanced-configuration.js

@@ -0,0 +1,91 @@
+import { createHash } from "node:crypto";
+import { ENHANCED_ENGINE_VERSION, ENHANCED_SCORING_VERSION, confidenceThresholds, } from "./engine/index.js";
+export function buildEnhancedScannerConfiguration(input) {
+    const rules = input.rules
+        .filter(({ draft }) => draft.kind === "keyword" || draft.kind === "spam")
+        .map(({ ruleId, draft }) => scannerRule(ruleId, draft, input.configuration))
+        .sort((left, right) => left.ruleId.localeCompare(right.ruleId));
+    const categoryThresholds = confidenceThresholds({
+        profile: input.configuration.enhancedSensitivityProfile,
+        custom: input.configuration.enhancedMinimumConfidence,
+        overridesEnabled: input.configuration.enhancedCategoryOverridesEnabled,
+        overrides: {
+            low: input.configuration.enhancedLowMinimumConfidence,
+            medium: input.configuration.enhancedMediumMinimumConfidence,
+            high: input.configuration.enhancedHighMinimumConfidence,
+            critical: input.configuration.enhancedCriticalMinimumConfidence,
+        },
+    });
+    const canonical = {
+        guildId: input.guildId,
+        configurationRevision: input.configurationRevision,
+        engineVersion: ENHANCED_ENGINE_VERSION,
+        scoringVersion: ENHANCED_SCORING_VERSION,
+        categoryThresholds,
+        rules,
+    };
+    return {
+        ...canonical,
+        fingerprint: createHash("sha256")
+            .update(JSON.stringify(canonical))
+            .digest("hex"),
+        refreshAfter: input.refreshAfter,
+        expiresAt: input.expiresAt,
+    };
+}
+function scannerRule(ruleId, draft, configuration) {
+    const terms = draft.kind === "spam"
+        ? [similarMessageTerm(ruleId)]
+        : [...draft.keywordFilter, ...draft.regexPatterns]
+            .map((value, index) => {
+            const kind = index >= draft.keywordFilter.length
+                ? "safe_regex"
+                : termKind(value);
+            return {
+                termId: stableTermId(ruleId, kind, value),
+                kind,
+                value,
+                allowList: [...draft.allowList].sort(),
+                normalisedMatching: draft.enhancedNormalisedMatching !== false,
+                fuzzyMatching: (kind === "word" || kind === "phrase") &&
+                    draft.enhancedFuzzyMatching === true,
+            };
+        })
+            .sort((left, right) => left.termId.localeCompare(right.termId));
+    return {
+        ruleId,
+        name: draft.name,
+        categoryId: draft.category,
+        severity: draft.category,
+        terms,
+        exemptRoleIds: merged(configuration.defaultExemptRoleIds, draft.ignoredRoleIds),
+        exemptChannelIds: merged(configuration.defaultExemptChannelIds, draft.ignoredChannelIds),
+        actionPolicy: draft.actionPolicy,
+        openViolationThread: draft.openViolationThread,
+    };
+}
+function similarMessageTerm(ruleId) {
+    return {
+        termId: stableTermId(ruleId, "similar_message", "cross-channel-similar-message"),
+        kind: "similar_message",
+        value: "cross-channel-similar-message",
+        allowList: [],
+        normalisedMatching: false,
+        fuzzyMatching: false,
+    };
+}
+function termKind(value) {
+    if (value.startsWith("*") || value.endsWith("*"))
+        return "wildcard";
+    return /\s/u.test(value.trim()) ? "phrase" : "word";
+}
+function stableTermId(ruleId, kind, value) {
+    return createHash("sha256")
+        .update(JSON.stringify([ruleId, kind, value]))
+        .digest("hex")
+        .slice(0, 24);
+}
+function merged(left, right) {
+    return [...new Set([...left, ...right])].sort();
+}
+//# sourceMappingURL=enhanced-configuration.js.map

package/dist/events.d.ts

@@ -0,0 +1,4 @@
+import { type EventContributions } from "@helyx/sdk";
+import type { AutoModerationPublicationService } from "./publication.js";
+export declare function createAutoModerationEvents(publication: AutoModerationPublicationService): EventContributions;
+//# sourceMappingURL=events.d.ts.map