@sdxc/spam 0.0.0-pre.1

package/dist/link-blocklist.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The link-blocklist check: looks each linked domain up in DNS URI blocklists (Spamhaus DBL,
+ * SURBL, URIBL) over DNS-over-HTTPS, so a domain reported by the wider mail and web community
+ * scores here even when the submission's text looks innocent.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { DoH } from "@sdxc/doh";
+import type { SpamCheck } from "./check.js";
+/**
+ * Scores the content's links and the author's URL by DNS blocklist listings. Each distinct
+ * domain, up to `maxHosts`, is looked up in every zone in parallel; IP literals are skipped.
+ * When any lookup finds a listing the signals are returned; otherwise a refused or failed
+ * lookup fails the check, so an incomplete answer never passes for a clean one.
+ *
+ * @example linkBlocklist({ dqsKey: env.SPAMHAUS_DQS_KEY })
+ */
+export declare function linkBlocklist(options?: linkBlocklist.Options): SpamCheck;
+/** The options {@link linkBlocklist} takes. */
+export declare namespace linkBlocklist {
+    /** A supported blocklist: Spamhaus DBL, SURBL `multi` or URIBL `multi`. */
+    type Zone = "spamhaus" | "surbl" | "uribl";
+    /** Zones, credentials and weights for the link-blocklist check. */
+    interface Options {
+        /**
+         * The zones to query. Spamhaus refuses queries relayed by public resolvers, so it needs
+         * `dqsKey` and is included by default only when one is given.
+         *
+         * @default ["surbl", "uribl"], plus "spamhaus" first when `dqsKey` is set
+         */
+        zones?: readonly Zone[];
+        /** A Spamhaus Data Query Service key, which the DBL query name embeds. */
+        dqsKey?: string;
+        /**
+         * The DoH resolver every query goes through; point it at a resolver the zones accept when
+         * the default one is refused.
+         *
+         * @default Cloudflare's 1.1.1.1
+         */
+        resolver?: DoH.Resolver;
+        /**
+         * Distinct domains looked up per submission, bounding the queries a link-stuffed post costs.
+         *
+         * @default 10
+         */
+        maxHosts?: number;
+        /**
+         * The score of each zone listing a domain.
+         *
+         * @default 6
+         */
+        listedScore?: number;
+        /**
+         * The score of a low-confidence listing: URIBL grey, or a Spamhaus listing of an abused
+         * legitimate domain.
+         *
+         * @default 2
+         */
+        weakScore?: number;
+        /** @default 12 */
+        maxScore?: number;
+    }
+}

package/dist/link-blocklist.js

@@ -0,0 +1,202 @@
+import { NameNotFoundError, resolve } from "@sdxc/doh";
+import { failure, isFailure, success } from "@sdxc/result";
+import { SpamCheckError } from "./check.js";
+import { extractLinks } from "./lib/text.js";
+/**
+ * Second-level labels under a country-code TLD that registries sell names beneath, such as
+ * `co.uk` or `com.br`, so `shop.example.co.uk` reduces to `example.co.uk`.
+ */
+const SECOND_LEVEL_LABELS = new Set([
+    "ac",
+    "co",
+    "com",
+    "edu",
+    "gob",
+    "gov",
+    "go",
+    "ltd",
+    "me",
+    "ne",
+    "net",
+    "nom",
+    "or",
+    "org",
+    "plc",
+]);
+/**
+ * Spamhaus DBL categories by the last octet of `127.0.1.x`; the same code plus 100 (`127.0.1.102`
+ * and on) is that category on a legitimate domain that was abused, a weaker reason to hold a post.
+ */
+const SPAMHAUS_CODES = {
+    2: "spam",
+    3: "spammed redirector",
+    4: "phishing",
+    5: "malware",
+    6: "botnet C&C",
+};
+/** SURBL `multi` list bits in the last octet. */
+const SURBL_BITS = [
+    [8, "phishing"],
+    [16, "malware"],
+    [64, "abuse"],
+    [128, "cracked site"],
+];
+/** URIBL `multi` list bits in the last octet; black and red are listings, grey is weak. */
+const URIBL_BITS = [
+    [2, "black"],
+    [4, "grey"],
+    [8, "red"],
+];
+/**
+ * The supported zones. Every one answers NXDOMAIN for a clean name and a 127.0.0.0/8 address
+ * for a listed one, and each reserves some of those addresses to say the query itself was
+ * refused, which reads as a misconfiguration rather than a listing.
+ */
+const ZONES = {
+    spamhaus: {
+        title: "Spamhaus DBL",
+        queryName: (host, dqsKey) => `${host}.${dqsKey}.dbl.dq.spamhaus.net`,
+        read([, second, third, fourth]) {
+            if (second === 255 && third === 255)
+                return { kind: "error" };
+            if (third !== 1 || fourth === 255)
+                return { kind: "error" };
+            let label = SPAMHAUS_CODES[(fourth ?? 0) % 100] ?? "listed";
+            if ((fourth ?? 0) >= 100)
+                return { kind: "listed", strength: "weak", label: `abused ${label}` };
+            return { kind: "listed", strength: "listed", label };
+        },
+    },
+    surbl: {
+        title: "SURBL",
+        queryName: (host) => `${host}.multi.surbl.org`,
+        read([, second, third, fourth]) {
+            if (second !== 0 || third !== 0 || fourth === 1)
+                return { kind: "error" };
+            let labels = bitLabels(fourth ?? 0, SURBL_BITS);
+            return { kind: "listed", strength: "listed", label: labels || "listed" };
+        },
+    },
+    uribl: {
+        title: "URIBL",
+        queryName: (host) => `${host}.multi.uribl.com`,
+        read([, second, third, fourth]) {
+            if (second !== 0 || third !== 0 || fourth === 1)
+                return { kind: "error" };
+            let bits = fourth ?? 0;
+            let strength = (bits & 0b1010) !== 0 ? "listed" : "weak";
+            return { kind: "listed", strength, label: bitLabels(bits, URIBL_BITS) || "listed" };
+        },
+    },
+};
+/**
+ * Scores the content's links and the author's URL by DNS blocklist listings. Each distinct
+ * domain, up to `maxHosts`, is looked up in every zone in parallel; IP literals are skipped.
+ * When any lookup finds a listing the signals are returned; otherwise a refused or failed
+ * lookup fails the check, so an incomplete answer never passes for a clean one.
+ *
+ * @example linkBlocklist({ dqsKey: env.SPAMHAUS_DQS_KEY })
+ */
+export function linkBlocklist(options = {}) {
+    let zones = options.zones ?? (options.dqsKey ? ["spamhaus", "surbl", "uribl"] : ["surbl", "uribl"]);
+    let maxHosts = options.maxHosts ?? 10;
+    let listedScore = options.listedScore ?? 6;
+    let weakScore = options.weakScore ?? 2;
+    let maxScore = options.maxScore ?? 12;
+    return {
+        name: "link-blocklist",
+        stage: "remote",
+        async check(submission, { signal }) {
+            if (zones.includes("spamhaus") && !options.dqsKey) {
+                return failure(new SpamCheckError("misconfigured", "Spamhaus DBL needs a dqsKey"));
+            }
+            let links = extractLinks(`${submission.content} ${submission.author?.url ?? ""}`);
+            let hosts = [...new Set(links.flatMap((url) => registrableHost(url.hostname) ?? []))];
+            hosts = hosts.slice(0, maxHosts);
+            if (hosts.length === 0 || zones.length === 0)
+                return success([]);
+            let lookups = await Promise.all(hosts.flatMap((host) => zones.map(async (zone) => ({
+                host,
+                zone,
+                outcome: await lookUp(ZONES[zone], zone, host, options, signal),
+            }))));
+            let signals = [];
+            let total = 0;
+            let firstError = null;
+            for (let { host, zone, outcome } of lookups) {
+                if (isFailure(outcome)) {
+                    firstError ??= outcome.error;
+                    continue;
+                }
+                if (outcome.data === null)
+                    continue;
+                let base = outcome.data.strength === "listed" ? listedScore : weakScore;
+                let score = Math.min(base, maxScore - total);
+                if (score <= 0)
+                    continue;
+                total += score;
+                signals.push({
+                    check: `link-blocklist.${zone}`,
+                    score,
+                    detail: `${host} is listed by ${ZONES[zone].title} (${outcome.data.label})`,
+                });
+            }
+            if (signals.length === 0 && firstError !== null)
+                return failure(firstError);
+            return success(signals);
+        },
+    };
+}
+/**
+ * Queries one zone for one host. NXDOMAIN and an answer with no address mean not listed
+ * (`null`); a reserved error code is `misconfigured`, an address outside 127.0.0.0/8 is
+ * `invalid-response`, and a resolver failure is `unavailable`.
+ */
+async function lookUp(spec, zone, host, options, signal) {
+    let answer = await resolve(spec.queryName(host, options.dqsKey), "A", {
+        resolver: options.resolver,
+        signal,
+    });
+    if (isFailure(answer)) {
+        if (answer.error instanceof NameNotFoundError)
+            return success(null);
+        return failure(new SpamCheckError("unavailable", `${zone}: ${answer.error.message}`));
+    }
+    let strongest = null;
+    for (let record of answer.data.records) {
+        let octets = record.address.split(".").map(Number);
+        if (octets[0] !== 127) {
+            return failure(new SpamCheckError("invalid-response", `${zone} answered ${record.address}`));
+        }
+        let reading = spec.read(octets);
+        if (reading.kind === "error") {
+            return failure(new SpamCheckError("misconfigured", `${zone} refused the query (${record.address})`));
+        }
+        if (strongest === null || reading.strength === "listed")
+            strongest = reading;
+    }
+    return success(strongest);
+}
+/**
+ * The domain a blocklist indexes for `hostname`: its last two labels, or three under a
+ * registry second level such as `co.uk`. IP literals and single-label names give `null`.
+ */
+function registrableHost(hostname) {
+    let host = hostname.toLowerCase().replace(/\.$/, "");
+    if (host.startsWith("[") || /^\d{1,3}(?:\.\d{1,3}){3}$/.test(host))
+        return null;
+    let labels = host.split(".");
+    if (labels.length < 2)
+        return null;
+    let tld = labels[labels.length - 1] ?? "";
+    let second = labels[labels.length - 2] ?? "";
+    let keep = labels.length > 2 && tld.length === 2 && SECOND_LEVEL_LABELS.has(second) ? 3 : 2;
+    return labels.slice(-keep).join(".");
+}
+/** The names of the bits set in `value`, comma-separated. */
+function bitLabels(value, bits) {
+    return bits
+        .filter(([bit]) => (value & bit) !== 0)
+        .map(([, label]) => label)
+        .join(", ");
+}

package/dist/memory.d.ts

@@ -0,0 +1,71 @@
+/**
+ * A scriptable check for testing code that uses a spam filter: a test queues the signals or
+ * failure the next call answers and asserts on the submissions and reports it received, with no
+ * provider involved.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { Label, Signal, SpamCheck, Submission } from "./check.js";
+import { SpamCheckError } from "./check.js";
+/**
+ * Answers each call with the next queued outcome, or with its default signals once the queue is
+ * empty. Every call and report is recorded in order.
+ *
+ * @example let check = new MemoryCheck().failNext("unavailable");
+ */
+export declare class MemoryCheck implements SpamCheck {
+    #private;
+    readonly name: string;
+    readonly stage: SpamCheck.Stage;
+    /** Every submission checked, oldest first. */
+    readonly calls: Submission[];
+    /** Every report received, oldest first. */
+    readonly reports: MemoryCheck.Report[];
+    /** @param options - The check's name, stage and default signals */
+    constructor(options?: MemoryCheck.Options);
+    /** The most recent submission checked, or `undefined` before the first call. */
+    get last(): Submission | undefined;
+    /**
+     * Queues the signals the next call answers.
+     *
+     * @returns This check, so calls chain
+     */
+    signalNext(signals: Signal[]): this;
+    /**
+     * Queues a failure for the next call.
+     *
+     * @returns This check, so calls chain
+     */
+    failNext(code: SpamCheck.ErrorCode, message?: string): this;
+    /**
+     * Makes every later report fail with `code` until {@link reset}.
+     *
+     * @returns This check, so calls chain
+     */
+    failReports(code: SpamCheck.ErrorCode): this;
+    /** Forgets calls, reports, queued outcomes and report failures, keeping the default signals. */
+    reset(): void;
+    /** Records the call and answers the next queued outcome, else the default signals. */
+    check(submission: Submission): Promise<Result<Signal[], SpamCheckError>>;
+    /** Records the report, failing when {@link failReports} asked it to. */
+    report(submission: Submission, label: Label): Promise<Result<void, SpamCheckError>>;
+}
+/** The types a {@link MemoryCheck} takes and records. */
+export declare namespace MemoryCheck {
+    /** How a scripted check is built. */
+    interface Options {
+        /** @default "memory" */
+        name?: string;
+        /** @default "remote" */
+        stage?: SpamCheck.Stage;
+        /** What a call answers when nothing is queued. @default [] */
+        signals?: Signal[];
+    }
+    /** One recorded moderator decision. */
+    interface Report {
+        submission: Submission;
+        label: Label;
+    }
+}

package/dist/memory.js

@@ -0,0 +1,73 @@
+import { failure, success } from "@sdxc/result";
+import { SpamCheckError } from "./check.js";
+/**
+ * Answers each call with the next queued outcome, or with its default signals once the queue is
+ * empty. Every call and report is recorded in order.
+ *
+ * @example let check = new MemoryCheck().failNext("unavailable");
+ */
+export class MemoryCheck {
+    name;
+    stage;
+    /** Every submission checked, oldest first. */
+    calls = [];
+    /** Every report received, oldest first. */
+    reports = [];
+    #signals;
+    #queue = [];
+    #reportFailure = null;
+    /** @param options - The check's name, stage and default signals */
+    constructor(options = {}) {
+        this.name = options.name ?? "memory";
+        this.stage = options.stage ?? "remote";
+        this.#signals = options.signals ?? [];
+    }
+    /** The most recent submission checked, or `undefined` before the first call. */
+    get last() {
+        return this.calls.at(-1);
+    }
+    /**
+     * Queues the signals the next call answers.
+     *
+     * @returns This check, so calls chain
+     */
+    signalNext(signals) {
+        this.#queue.push(success(signals));
+        return this;
+    }
+    /**
+     * Queues a failure for the next call.
+     *
+     * @returns This check, so calls chain
+     */
+    failNext(code, message) {
+        this.#queue.push(failure(new SpamCheckError(code, message)));
+        return this;
+    }
+    /**
+     * Makes every later report fail with `code` until {@link reset}.
+     *
+     * @returns This check, so calls chain
+     */
+    failReports(code) {
+        this.#reportFailure = new SpamCheckError(code);
+        return this;
+    }
+    /** Forgets calls, reports, queued outcomes and report failures, keeping the default signals. */
+    reset() {
+        this.calls.length = 0;
+        this.reports.length = 0;
+        this.#queue = [];
+        this.#reportFailure = null;
+    }
+    /** Records the call and answers the next queued outcome, else the default signals. */
+    async check(submission) {
+        this.calls.push(submission);
+        return this.#queue.shift() ?? success(this.#signals);
+    }
+    /** Records the report, failing when {@link failReports} asked it to. */
+    async report(submission, label) {
+        this.reports.push({ submission, label });
+        return this.#reportFailure === null ? success(undefined) : failure(this.#reportFailure);
+    }
+}

package/dist/rules/author-name.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The author-name rule: a person's name is a few words, while spam uses the name field as one
+ * more place to put a domain or a string of search keywords.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { SpamCheck } from "../check.js";
+/**
+ * Scores an author name containing a URL or domain, and a name longer than `maxWords` words or
+ * `maxLength` characters.
+ *
+ * @example authorName({ maxWords: 8 })
+ */
+export declare function authorName(options?: authorName.Options): SpamCheck;
+/** The options {@link authorName} takes. */
+export declare namespace authorName {
+    /** Limits and weights for the author-name rule. */
+    interface Options {
+        /** @default 5 */
+        domainScore?: number;
+        /** @default 2 */
+        lengthScore?: number;
+        /** @default 5 */
+        maxWords?: number;
+        /** @default 50 */
+        maxLength?: number;
+    }
+}

package/dist/rules/author-name.js

@@ -0,0 +1,39 @@
+/** A URL or a bare domain such as `casino.example`. */
+const DOMAIN = /https?:\/\/|\b[a-z0-9-]+\.(?:[a-z]{2,24})\b/i;
+/**
+ * Scores an author name containing a URL or domain, and a name longer than `maxWords` words or
+ * `maxLength` characters.
+ *
+ * @example authorName({ maxWords: 8 })
+ */
+export function authorName(options = {}) {
+    let domainScore = options.domainScore ?? 5;
+    let lengthScore = options.lengthScore ?? 2;
+    let maxWords = options.maxWords ?? 5;
+    let maxLength = options.maxLength ?? 50;
+    return {
+        name: "author-name",
+        stage: "local",
+        check(submission) {
+            let name = submission.author?.name?.trim();
+            if (!name)
+                return [];
+            let signals = [];
+            if (DOMAIN.test(name)) {
+                signals.push({
+                    check: "author-name.domain",
+                    score: domainScore,
+                    detail: "a domain in the name",
+                });
+            }
+            if (name.split(/\s+/).length > maxWords || name.length > maxLength) {
+                signals.push({
+                    check: "author-name.length",
+                    score: lengthScore,
+                    detail: "a name longer than a person's",
+                });
+            }
+            return signals;
+        },
+    };
+}

package/dist/rules/contact-bait.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The contact-bait rule: scams move the conversation off the site, so they post a messaging
+ * handle, a phone number or a wallet address to pay into. A phone number alone scores low, since
+ * support requests carry them too.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { SpamCheck } from "../check.js";
+/**
+ * Scores a messaging-app handle, an international phone number and a cryptocurrency wallet, each
+ * once.
+ *
+ * @example contactBait({ phoneScore: 0 }) // for a form that asks for a phone number
+ */
+export declare function contactBait(options?: contactBait.Options): SpamCheck;
+/** The options {@link contactBait} takes. */
+export declare namespace contactBait {
+    /** Weights for the contact-bait rule. */
+    interface Options {
+        /** @default 4 */
+        messagingScore?: number;
+        /** @default 2 */
+        phoneScore?: number;
+        /** @default 4 */
+        walletScore?: number;
+    }
+}

package/dist/rules/contact-bait.js

@@ -0,0 +1,43 @@
+/** A Telegram or WhatsApp link, or either app named next to a handle or number. */
+const MESSAGING = /\b(?:t\.me|wa\.me|telegram\.me)\/\w|\b(?:telegram|whatsapp|signal|wechat|viber)\b[^.\n]{0,20}?(?:@\w{3,}|\+?\d[\d\s-]{6,})/i;
+/** An international phone number: a `+`, a country code and at least eight more digits. */
+const PHONE = /\+\d{1,3}[\s.-]?(?:\(?\d{1,4}\)?[\s.-]?){2,5}\d{2,4}\b/;
+/** Ethereum-style, Bitcoin bech32 and Tron addresses. */
+const WALLET = /\b0x[a-fA-F0-9]{40}\b|\bbc1[a-z0-9]{25,59}\b|\bT[1-9A-HJ-NP-Za-km-z]{33}\b/;
+/**
+ * Scores a messaging-app handle, an international phone number and a cryptocurrency wallet, each
+ * once.
+ *
+ * @example contactBait({ phoneScore: 0 }) // for a form that asks for a phone number
+ */
+export function contactBait(options = {}) {
+    let messagingScore = options.messagingScore ?? 4;
+    let phoneScore = options.phoneScore ?? 2;
+    let walletScore = options.walletScore ?? 4;
+    return {
+        name: "contact-bait",
+        stage: "local",
+        check(submission) {
+            let content = submission.content;
+            let signals = [];
+            if (MESSAGING.test(content)) {
+                signals.push({
+                    check: "contact-bait.messaging",
+                    score: messagingScore,
+                    detail: "a messaging-app handle",
+                });
+            }
+            if (PHONE.test(content)) {
+                signals.push({ check: "contact-bait.phone", score: phoneScore, detail: "a phone number" });
+            }
+            if (WALLET.test(content)) {
+                signals.push({
+                    check: "contact-bait.wallet",
+                    score: walletScore,
+                    detail: "a cryptocurrency wallet address",
+                });
+            }
+            return signals;
+        },
+    };
+}

package/dist/rules/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The default rule set: every local rule at its default weights, tuned together against the
+ * labelled corpus so a submission needs several kinds of evidence to reach the spam threshold.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { SpamCheck } from "../check.js";
+import { authorName } from "./author-name.js";
+import { contactBait } from "./contact-bait.js";
+import { language } from "./language.js";
+import { linkSyntax } from "./link-syntax.js";
+import { linkTargets } from "./link-targets.js";
+import { links } from "./links.js";
+import { shouting } from "./shouting.js";
+import { timing } from "./timing.js";
+import { unicode } from "./unicode.js";
+/**
+ * Every built-in local rule with its default options. To reweight one, build the list from the
+ * rule functions instead: `[links({ freeLinks: 3 }), unicode(), …]`.
+ */
+export declare const DEFAULT_RULES: readonly SpamCheck[];
+export { authorName, contactBait, language, links, linkSyntax, linkTargets, shouting, timing, unicode, };
+export { ABUSED_TLDS, URL_SHORTENERS } from "./link-targets.js";

package/dist/rules/index.js

@@ -0,0 +1,26 @@
+import { authorName } from "./author-name.js";
+import { contactBait } from "./contact-bait.js";
+import { language } from "./language.js";
+import { linkSyntax } from "./link-syntax.js";
+import { linkTargets } from "./link-targets.js";
+import { links } from "./links.js";
+import { shouting } from "./shouting.js";
+import { timing } from "./timing.js";
+import { unicode } from "./unicode.js";
+/**
+ * Every built-in local rule with its default options. To reweight one, build the list from the
+ * rule functions instead: `[links({ freeLinks: 3 }), unicode(), …]`.
+ */
+export const DEFAULT_RULES = [
+    timing(),
+    links(),
+    linkSyntax(),
+    linkTargets(),
+    unicode(),
+    contactBait(),
+    shouting(),
+    language(),
+    authorName(),
+];
+export { authorName, contactBait, language, links, linkSyntax, linkTargets, shouting, timing, unicode, };
+export { ABUSED_TLDS, URL_SHORTENERS } from "./link-targets.js";

package/dist/rules/language.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The language rule: a site written in one language rarely receives genuine comments in a
+ * writing system none of its languages use, and SEO spam is often posted everywhere unchanged.
+ * It compares scripts rather than detecting languages, which needs no model or word list.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { SpamCheck } from "../check.js";
+/**
+ * Scores content whose letters are mostly (over `ratio` of at least `minLetters`) in scripts none
+ * of {@link Submission.languages} is written in. A submission without `languages`, or with a tag
+ * whose script is unknown, draws nothing.
+ *
+ * @example language({ ratio: 0.8 })
+ */
+export declare function language(options?: language.Options): SpamCheck;
+/** The options {@link language} takes. */
+export declare namespace language {
+    /** Limits and weight for the language rule. */
+    interface Options {
+        /** @default 0.5 */
+        ratio?: number;
+        /** @default 20 */
+        minLetters?: number;
+        /** @default 5 */
+        score?: number;
+    }
+}