@sdxc/spam 2026.10.16 → 2026.10.17

package/README.md

@@ -76,6 +76,21 @@ Local checks run first, in order. Remote checks run in parallel only while the s
 the spam threshold, and a check that fails or overruns `timeout` adds nothing and is listed in
 `assessment.failures`.
 
+### Score a form before the handler
+
+```typescript
+import { spam } from "@sdxc/spam/middleware";
+
+router.post(routes.contact.action, {
+	middleware: [spam(filter, { fields: { content: "message", email: "email" } })],
+	handler: (ctx) => saveMessage(ctx.formData, ctx.spamAssessment.verdict === "unsure"),
+});
+```
+
+Each entry in `fields` names a form field, and the middleware reads its value from the submitted
+form. A spam verdict is answered with a 422 before the handler runs; the handler reads every other
+assessment from `ctx.spamAssessment`.
+
 ### Learn from moderators
 
 ```typescript
@@ -238,6 +253,20 @@ a ham answer `workers-ai.ham` at `-(hamScore × confidence)` (default 5), with t
 cut to `maxReasonLength` (200) as the detail. Content is cut to `maxContentLength` (4000).
 `model` defaults to `DEFAULT_WORKERS_AI_MODEL`, and takes any text model with JSON mode.
 
+### `@sdxc/spam/middleware`
+
+#### `spam(filter: SpamFilter, options: SpamMiddlewareOptions): Middleware`
+
+Router middleware scoring every request other than GET, HEAD and OPTIONS before the handler.
+`fields` names the form fields to read: `content` (one name, or several joined by line breaks),
+and the author's `name`, `email` and `url`. `format` and `languages` pass through. The
+submission also carries `ctx.ip` from `@sdxc/get-client-ip/middleware`, the raw header from
+`ctx.userAgent` (`@sdxc/user-agent/middleware`) and the render time `honeypot()` from
+`@sdxc/honeypot/middleware` verified, each when that middleware runs earlier.
+A `spam` verdict answers a plain 422 unless `onSpam(assessment, ctx)` returns its own `Response`,
+or `null` to continue. Every assessment is published as `ctx.spamAssessment`
+(`SpamAssessmentKey`), and the body stays readable.
+
 ### `@sdxc/spam/memory`
 
 #### `new MemoryCheck(options?: MemoryCheck.Options)`
@@ -253,27 +282,20 @@ say otherwise. A call answers the next queued outcome, else `signals`.
 ## Pattern: Refuse bots before scoring
 
 [`@sdxc/honeypot`](https://www.npmjs.com/package/@sdxc/honeypot) refuses what no person
-produces before any rule runs, and hands the signed render time the `timing` rule reads.
+produces before any rule runs, and `spam()` hands its signed render time to the `timing` rule.
 
 ```typescript
 import { Honeypot } from "@sdxc/honeypot";
 import { honeypot } from "@sdxc/honeypot/middleware";
-import { unwrap } from "@sdxc/result";
 import { createSpamFilter, DEFAULT_RULES } from "@sdxc/spam";
+import { spam } from "@sdxc/spam/middleware";
 
 let trap = new Honeypot({ secret: env.HONEYPOT_SECRET });
 let filter = createSpamFilter({ checks: DEFAULT_RULES });
 
 router.post(routes.comments.create, {
-	middleware: [honeypot(trap)],
-	async handler(ctx) {
-		let form = await ctx.request.formData();
-		let assessment = await filter.check({
-			content: String(form.get("content") ?? ""),
-			renderedAt: unwrap(ctx.honeypotOutcome).renderedAt,
-		});
-		return saveComment(form, assessment);
-	},
+	middleware: [honeypot(trap), spam(filter, { fields: { content: "content" } })],
+	handler: (ctx) => saveComment(ctx.formData, ctx.spamAssessment),
 });
 ```
 

package/dist/middleware.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Router middleware that scores every form submission with a spam filter before the handler
+ * runs, refusing a spam verdict and publishing the assessment as `ctx.spamAssessment`, so a
+ * handler only saves what it received and holds the `unsure` ones.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Middleware, RequestContext } from "remix/router";
+import type { Submission } from "./check.js";
+import type { SpamFilter } from "./filter.js";
+/**
+ * Declared in an imported module, so a project types `ctx.spamAssessment` by importing this
+ * middleware.
+ */
+declare module "remix/router" {
+    interface RequestContext {
+        /**
+         * The filter's assessment of this submission, published for every method other than GET,
+         * HEAD and OPTIONS. A `spam` verdict reaches the handler only when `onSpam` answered `null`.
+         */
+        spamAssessment: SpamFilter.Assessment;
+    }
+}
+/**
+ * The submission's assessment, for code that reads it by key rather than `ctx.spamAssessment`.
+ * The type is written out because an exported key needs a nameable type to reach a declaration file.
+ */
+export declare const SpamAssessmentKey: {
+    defaultValue?: SpamFilter.Assessment;
+};
+/**
+ * Form field names, each value read from the submitted form. A missing field or a file reads as
+ * empty, so a form that leaves an author field out scores on its content alone.
+ */
+export interface SpamMiddlewareFields {
+    /** What the visitor wrote; several names are scored as one text, joined by line breaks. */
+    content: string | readonly string[];
+    name?: string;
+    email?: string;
+    /** The website the author entered, as a comment form's "website" field collects it. */
+    url?: string;
+}
+/** Options for {@link spam}. */
+export interface SpamMiddlewareOptions {
+    /** The names of the form fields the submission is read from. */
+    fields: SpamMiddlewareFields;
+    /** @default "text" */
+    format?: Submission["format"];
+    /** The languages the form expects, as BCP 47 tags. */
+    languages?: string[];
+    /**
+     * Answers a `spam` verdict: a `Response` refuses the request with it, `null` continues to the
+     * handler with the assessment published on `ctx.spamAssessment`.
+     *
+     * @default a plain-text 422 response
+     */
+    onSpam?: (assessment: SpamFilter.Assessment, ctx: RequestContext) => Response | null | Promise<Response | null>;
+}
+/**
+ * Scores every submission with `filter`: the form fields named in `options.fields`, plus
+ * `ctx.ip`, `ctx.userAgent` and the honeypot's verified render time when their middleware ran
+ * earlier. The body stays readable; with `formData()` installed, the parsed form is reused.
+ *
+ * @param filter - The filter that scores each submission
+ * @param options - Where the submission's fields are and how a spam verdict is answered
+ * @returns The middleware
+ * @example router.post(routes.contact.action, { middleware: [spam(filter, { fields: { content: "message" } })], handler })
+ */
+export declare function spam(filter: SpamFilter, options: SpamMiddlewareOptions): Middleware;

package/dist/middleware.js

@@ -0,0 +1,84 @@
+import { ClientIP } from "@sdxc/get-client-ip/middleware";
+import { HoneypotOutcomeKey } from "@sdxc/honeypot/middleware";
+import { isSuccess } from "@sdxc/result";
+import { CurrentUserAgent } from "@sdxc/user-agent/middleware";
+import { createContextKey } from "remix/router";
+/**
+ * The submission's assessment, for code that reads it by key rather than `ctx.spamAssessment`.
+ * The type is written out because an exported key needs a nameable type to reach a declaration file.
+ */
+export const SpamAssessmentKey = createContextKey();
+/** Methods that render a form rather than submit one, which pass through unscored. */
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+/** Content types a browser form submits. */
+const FORM_CONTENT_TYPES = ["application/x-www-form-urlencoded", "multipart/form-data"];
+/**
+ * Scores every submission with `filter`: the form fields named in `options.fields`, plus
+ * `ctx.ip`, `ctx.userAgent` and the honeypot's verified render time when their middleware ran
+ * earlier. The body stays readable; with `formData()` installed, the parsed form is reused.
+ *
+ * @param filter - The filter that scores each submission
+ * @param options - Where the submission's fields are and how a spam verdict is answered
+ * @returns The middleware
+ * @example router.post(routes.contact.action, { middleware: [spam(filter, { fields: { content: "message" } })], handler })
+ */
+export function spam(filter, options) {
+    return async (ctx, next) => {
+        if (SAFE_METHODS.has(ctx.request.method))
+            return next();
+        let form = (await readForm(ctx)) ?? new FormData();
+        let assessment = await filter.check({
+            content: [options.fields.content]
+                .flat()
+                .map((name) => field(form, name) ?? "")
+                .join("\n"),
+            format: options.format,
+            languages: options.languages,
+            renderedAt: renderedAt(ctx),
+            author: {
+                name: field(form, options.fields.name),
+                email: field(form, options.fields.email),
+                url: field(form, options.fields.url),
+                ip: ctx.get(ClientIP)?.toString(),
+                userAgent: ctx.get(CurrentUserAgent).raw || undefined,
+            },
+        });
+        ctx.set(SpamAssessmentKey, assessment, { property: "spamAssessment" });
+        if (assessment.verdict !== "spam")
+            return next();
+        let answer = await (options.onSpam ?? refuse)(assessment, ctx);
+        return answer ?? next();
+    };
+}
+/** The text of the field named `name`, or `undefined` when it is unnamed, missing or a file. */
+function field(form, name) {
+    let value = name === undefined ? null : form.get(name);
+    return typeof value === "string" ? value : undefined;
+}
+/** When the honeypot middleware verified this form was rendered, if it ran and passed. */
+function renderedAt(ctx) {
+    let outcome = ctx.has(HoneypotOutcomeKey) ? ctx.get(HoneypotOutcomeKey) : undefined;
+    return outcome !== undefined && isSuccess(outcome) ? outcome.data.renderedAt : undefined;
+}
+/**
+ * The submitted form, or `null` when the body is not one. Reads `formData()`'s parsed form when
+ * present, and otherwise a clone of the request, leaving the original body for the handler.
+ */
+async function readForm(ctx) {
+    let parsed = ctx.has(FormData) ? ctx.get(FormData) : undefined;
+    if (parsed !== undefined)
+        return parsed;
+    let contentType = ctx.request.headers.get("Content-Type") ?? "";
+    if (!FORM_CONTENT_TYPES.some((type) => contentType.includes(type)))
+        return null;
+    try {
+        return await ctx.request.clone().formData();
+    }
+    catch {
+        return null;
+    }
+}
+/** The default answer to spam: a 422, since the submission was understood and refused. */
+function refuse() {
+    return new Response("Submission refused as spam", { status: 422 });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sdxc/spam",
-	"version": "2026.10.16",
+	"version": "2026.10.17",
 	"description": "Spam scoring for user content: local rules, reputation checks and a classifier",
 	"license": "MIT",
 	"type": "module",
@@ -12,17 +12,21 @@
 		"./link-blocklist": "./dist/link-blocklist.js",
 		"./akismet": "./dist/akismet.js",
 		"./bayes": "./dist/bayes.js",
-		"./workers-ai": "./dist/workers-ai.js"
+		"./workers-ai": "./dist/workers-ai.js",
+		"./middleware": "./dist/middleware.js"
 	},
 	"dependencies": {
 		"@sdxc/doh": "2026.10.16",
 		"@sdxc/email-address": "2026.10.16",
-		"@sdxc/result": "2026.10.13"
+		"@sdxc/get-client-ip": "2026.10.16",
+		"@sdxc/honeypot": "2026.10.16",
+		"@sdxc/result": "2026.10.13",
+		"@sdxc/user-agent": "2026.10.17"
 	},
 	"peerDependencies": {
 		"remix": "3.0.0"
 	},
-	"gitHead": "1e547d8431568f5ed9bdb079ca3046c936240fde",
+	"gitHead": "4f4bce453e9afe69f53194368af9e9739d73a876",
 	"publishConfig": {
 		"access": "public"
 	},