@bitsocial/wordfilter-challenge 0.1.1

package/README.md

@@ -0,0 +1,250 @@
+# @bitsocial/wordfilter-challenge
+
+A [pkc-js](https://github.com/pkcprotocol/pkc-js) challenge that makes community wordfilters a real rule instead of a cosmetic display filter.
+
+> **Status: implemented.** This README is the spec, and `src/` follows it. Tracked in [pkc-js#281](https://github.com/pkcprotocol/pkc-js/issues/281).
+
+## What it does
+
+A community configures a list of replacements, for example `plebbit` becomes `bitcoin`. Publishing clients apply those replacements before signing, so the signed comment, its CID, and what every client renders all contain `bitcoin`. The original text does not exist anywhere.
+
+The community node does not do the replacing. It only checks: if a publication still contains a filtered word, it is rejected.
+
+## Why clients have to do the replacing
+
+This is the part that surprises people coming from imageboard software, so it is worth being explicit.
+
+On a traditional imageboard the server owns the post text and rewrites it freely at submission time. [jschan](https://gitgud.io/fatchan/jschan/-/blob/master/lib/post/filteractions.js) mutates `req.body` before the insert; vichan calls `wordfilters($post['body'])` in `post.php` before `body_nomarkup` is even derived. Neither keeps the pre-filter original.
+
+pkc-js cannot work that way. The author signs the publication, and the signature covers `content`. If the community rewrote `content` afterwards, the signature would no longer verify and every client would reject the comment as forged.
+
+So the replacement has to happen on the side holding the signing key, which is the publishing client. The community's only available action is to accept or reject. In other words this package does not implement a wordfilter, it implements **a proof that a wordfilter was applied**.
+
+A client that does not implement the replacement cannot publish unfiltered text. It simply gets rejected, which is the intended failure mode.
+
+## For UI client developers
+
+This is the section that matters if you are building a frontend that publishes to communities using this challenge.
+
+### 1. Read the rules off the community
+
+The rules are published in the community record, in the challenge's `publicOptions`. Collect them from every wordfilter challenge the community has configured, in challenge order.
+
+The challenge's `name` is **not** in the published record: `path`, `name` and `options` are all stripped when `community.settings.challenges[i]` becomes `community.challenges[i]`. The presence of a `wordfilters` public option is the only thing a client can key off, which is exactly why the challenge requires it to be published.
+
+```js
+function getWordfilterConfigs(community) {
+    return (community.challenges ?? [])
+        .filter((challenge) => challenge.publicOptions?.wordfilters)
+        .map((challenge) => {
+            try {
+                return {
+                    rules: JSON.parse(challenge.publicOptions.wordfilters),
+                    fieldNames: challenge.publicOptions.fieldNames
+                        ? JSON.parse(challenge.publicOptions.fieldNames)
+                        : ["content", "title", "author.displayName"]
+                };
+            } catch {
+                // A rule set you cannot parse is skipped, never fatal. Worst case the community
+                // rejects the publication with a readable error.
+                return undefined;
+            }
+        })
+        .filter(Boolean);
+}
+```
+
+Skip anything you cannot parse. Never throw, and never refuse to load the community: a malformed rule set must cost the filter, not the whole board.
+
+### 2. Apply the rules, looping until the text stops changing
+
+**Do not apply the rules once.** A replacement can create a new match by joining with the text around it. With rules `[{src: "ab", dst: "c"}, {src: "x", dst: "b"}]`, the input `"ax"` becomes `"ab"` in a single pass, which still contains a filtered word, and the community will reject it.
+
+Loop until the output is stable:
+
+```js
+const escapeRegExp = (str) => str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+// The `() => dst` replacer, not a plain `dst`: `String.replace` reads `$&` and friends out of a string
+// replacement, and rules are literal on both sides.
+const applyOnce = (text, rules) =>
+    rules.reduce((acc, { src, dst }) => acc.replace(new RegExp(escapeRegExp(src), "gi"), () => dst), text);
+
+export function applyWordfilters(text, rules, maxPasses = 8) {
+    let out = text;
+    for (let pass = 0; pass < maxPasses; pass++) {
+        const next = applyOnce(out, rules);
+        if (next === out) return out;
+        out = next;
+    }
+    throw new Error("wordfilter rules did not stabilise");
+}
+```
+
+Stable output contains no filtered word by definition, which is exactly what the community checks for.
+
+Copying that function is the expected path: your client sees the challenge through `community.challenges` and has no reason to depend on the package that produced it. If you do already bundle npm packages, the same function is exported as `applyWordfilters` from `@bitsocial/wordfilter-challenge`, with nothing from pkc-js behind it.
+
+### 3. Apply it before creating the publication
+
+Filter the text before it reaches `pkc.createComment()`, so the transformation happens before any signature exists. Nothing needs to re-sign, and there is no window where an unfiltered draft is signed.
+
+```js
+const configs = getWordfilterConfigs(community);
+for (const { rules, fieldNames } of configs) {
+    if (fieldNames.includes("content") && content) content = applyWordfilters(content, rules);
+    if (fieldNames.includes("title") && title) title = applyWordfilters(title, rules);
+}
+const comment = await pkc.createComment({ content, title, communityAddress, signer });
+await comment.publish();
+```
+
+`fieldNames` entries are dot-notation paths on the publication, the same convention `publication-match` uses for `propertyName`. So `content` covers both a comment and a comment edit without the config naming publication types.
+
+### 4. Show the user what happened
+
+Nothing in the protocol requires it, but the author is signing text they did not type. Showing the filtered result before publishing, or a note afterwards, avoids the surprise. This is a UX decision, not a correctness one.
+
+### 5. Handle rejection
+
+Your copy of the community record can be older than the community's current settings. An owner who adds a rule starts enforcing it immediately, while your client keeps publishing against the rules it last saw.
+
+When that happens the publication is rejected with the challenge's `error` message. Refresh the community, re-apply, and let the author retry. **Do not re-sign automatically:** that would silently publish text the author never reviewed, which is the exact failure this design exists to prevent.
+
+## Requirements
+
+- pkc-js `>=0.0.85`, for `publicOptions` ([pkc-js#282](https://github.com/pkcprotocol/pkc-js/issues/282)) and `validateChallengeSettings` ([pkc-js#283](https://github.com/pkcprotocol/pkc-js/issues/283))
+- Node.js `>=22`
+- ESM-only environment
+
+## Install
+
+### With bitsocial-cli
+
+```bash
+bitsocial challenge install @bitsocial/wordfilter-challenge
+```
+
+```bash
+bitsocial community edit your-community.bso \
+  '--settings.challenges[0].name' @bitsocial/wordfilter-challenge \
+  '--settings.challenges[0].options.wordfilters' '[{"src":"plebbit","dst":"bitcoin"}]' \
+  '--settings.challenges[0].publicOptions[0]' wordfilters
+```
+
+### With pkc-js over RPC
+
+Install the challenge on the RPC server, then set it on your community by name. Nothing has to be installed on the client side:
+
+```bash
+bitsocial challenge install @bitsocial/wordfilter-challenge
+```
+
+### With pkc-js (TypeScript)
+
+Running your own node locally, without RPC:
+
+```bash
+npm install @bitsocial/wordfilter-challenge
+```
+
+```ts
+import PKC from "@pkcprotocol/pkc-js";
+import { wordfilterChallenge } from "@bitsocial/wordfilter-challenge";
+
+PKC.challenges["@bitsocial/wordfilter-challenge"] = wordfilterChallenge;
+```
+
+## Configuration
+
+For community owners, set in `settings.challenges`:
+
+```js
+await community.edit({
+    settings: {
+        challenges: [
+            {
+                name: "@bitsocial/wordfilter-challenge",
+                options: {
+                    wordfilters: JSON.stringify([
+                        { src: "plebbit", dst: "bitcoin" },
+                        { src: "spamword", dst: "" }
+                    ]),
+                    fieldNames: JSON.stringify(["content", "title", "author.displayName"]),
+                    error: "This board replaces certain words. Please repost with the replacements applied."
+                },
+                publicOptions: ["wordfilters", "fieldNames", "error"]
+            }
+        ]
+    }
+});
+```
+
+`publicOptions` is **required**, not decorative. Options are private by default in pkc-js, and a client that cannot read the rules cannot satisfy them. The challenge's `validateChallengeSettings` hook rejects the edit if `wordfilters` is missing from `publicOptions`, so the failure surfaces when you save rather than when every author starts getting rejected.
+
+### Options
+
+| Option | Required | Must be in `publicOptions` | Description |
+|---|---|---|---|
+| `wordfilters` | yes | yes | JSON array of `{ src, dst }`, applied in array order, cascading |
+| `fieldNames` | no | when set | JSON array of dot-notation paths. Defaults to `content`, `title`, `author.displayName` |
+| `error` | no | owner's call | Message shown to the author when a publication is rejected |
+
+An option has to be public when a client cannot satisfy the challenge without reading it. That covers `wordfilters` always, and `fieldNames` whenever the owner sets it: a client filtering the three default fields cannot satisfy a community checking a different set, and nothing in the published record would explain the rejections. `error` is returned in the rejection itself, so publishing it is transparency rather than a requirement.
+
+### Validation
+
+`validateChallengeSettings` rejects at edit time:
+
+- `wordfilters` missing from `publicOptions`, or unparseable JSON, or not an array of `{ src, dst }` strings
+- an empty `src`
+- `src === dst`
+- the same `src` in more than one rule
+- any `dst` containing any `src`
+- more than 64 rules, or a `src` or `dst` longer than 128 characters
+- `fieldNames`, when set, unparseable, not an array of non-empty strings, or missing from `publicOptions`
+
+The `src === dst`, duplicate `src` and `dst`-contains-`src` checks all compare case-insensitively, because matching is case-insensitive: `{src: "LOL", dst: "lol"}` replaces nothing just as surely as `{src: "lol", dst: "lol"}` does.
+
+The `dst` containing `src` rule is what guarantees the client's loop terminates. Without it a rule like `lol` becomes `lolol` produces output that always contains a filtered word, making every post permanently unpublishable.
+
+## Matching semantics
+
+- **Literal, never regex.** vichan supports arbitrary PCRE, but only because its config is a server-local file the operator wrote. Here the rules ship inside a signed record that every browser client downloads and executes, so patterns are literal strings.
+- **Case-insensitive**, following vichan's `str_ireplace`. `plebbit`, `Plebbit`, and `PLEBBIT` are all replaced. Casing is not preserved: all three become `bitcoin`.
+- **Cascading in array order**, and rules from multiple wordfilter challenges compose in challenge order.
+- **Absent fields pass cleanly.** A vote has no `content`, and that is not a failure. (`publication-match` treats a missing property as a failure, which would reject every vote. Do not copy that.)
+
+## What this does not catch
+
+Deliberate evasion. `p l e b b i t`, `plebbıt`, and zero-width-joined variants pass straight through.
+
+That is a hard limit, not an oversight. jschan has a `strictFiltering` mode that matches against NFD-stripped, zero-width-stripped and alphanumeric-only permutations of the post, and it is necessarily **detect-only**: normalisation is not invertible, so once you have matched a normalised form you no longer know where in the original text to splice a replacement. Evasion-resistant matching and replacement are mutually exclusive.
+
+For blocking evasive spam and slurs outright, use pkc-js's built-in `publication-match` challenge. Rejecting a publication does not require knowing where the match was. Note that `exclude` can skip a challenge for moderators or high-karma authors, which applies to this package too.
+
+## Prior art
+
+- jschan, which powers soyjak.party: [`checkfilters.js`](https://gitgud.io/fatchan/jschan/-/blob/master/lib/post/checkfilters.js), [`filteractions.js`](https://gitgud.io/fatchan/jschan/-/blob/master/lib/post/filteractions.js), [`getfilterstrings.js`](https://gitgud.io/fatchan/jschan/-/blob/master/lib/post/getfilterstrings.js)
+- vichan: [`wordfilters()`](https://github.com/vichan-devel/vichan/blob/master/inc/functions.php#L1798)
+
+Both rewrite server-side at post time and keep no copy of the original.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+```
+
+| Path | What it is |
+|---|---|
+| `src/wordfilter-challenge.ts` | The `ChallengeFileFactory`: `optionInputs`, `getChallenge`, `validateChallengeSettings` |
+| `src/apply-wordfilters.ts` | The client-side replacement loop. Imports nothing, so it bundles for a browser |
+| `src/types.ts` | Re-exports of the pkc-js challenge types |
+
+## License
+
+GPL-3.0-or-later, the same as pkc-js.

package/dist/apply-wordfilters.d.ts

@@ -0,0 +1,22 @@
+export interface WordfilterRule {
+    /** The literal string to look for. Never a regex, and matched case-insensitively. */
+    src: string;
+    /** What to replace it with. May be empty, which deletes the match. */
+    dst: string;
+}
+export declare const DEFAULT_FIELD_NAMES: readonly string[];
+export declare const DEFAULT_MAX_PASSES = 8;
+export declare const escapeRegExp: (str: string) => string;
+/**
+ * Apply `rules` to `text` until the output stops changing.
+ *
+ * A single pass is not enough: a replacement can join with the text around it to create a new match,
+ * so `[{src: "ab", dst: "c"}, {src: "x", dst: "b"}]` turns `"ax"` into `"ab"` in one pass, which the
+ * community still rejects. Stable output contains no filtered word by definition, which is exactly what
+ * the community checks for.
+ *
+ * @throws if the rules never stabilise. `validateChallengeSettings` rejects the rule sets that can cause
+ * this (no `dst` may contain any `src`), so a community configured through pkc-js 0.0.85+ cannot produce
+ * one, but a client should still not spin forever on a hostile record.
+ */
+export declare function applyWordfilters(text: string, rules: readonly WordfilterRule[], maxPasses?: number): string;

package/dist/apply-wordfilters.js

@@ -0,0 +1,36 @@
+// The client side of the challenge. A community can only accept or reject, so the replacement has to
+// happen on the side holding the signing key. This file is the loop that side has to run, kept free of
+// any pkc-js import so it can be pulled into a browser bundle on its own.
+//
+// Most frontends will never install this package: they discover the challenge through
+// `community.challenges[i].publicOptions` and have no reason to know which package produced it. The
+// README carries this same loop as a copy-pasteable snippet for them, and that snippet is the contract.
+// This export exists for the minority that does bundle the package, and must stay behaviourally
+// identical to the README's version.
+export const DEFAULT_FIELD_NAMES = ["content", "title", "author.displayName"];
+export const DEFAULT_MAX_PASSES = 8;
+export const escapeRegExp = (str) => str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const applyOnce = (text, rules) => rules.reduce((acc, { src, dst }) => acc.replace(new RegExp(escapeRegExp(src), "gi"), () => dst), text);
+/**
+ * Apply `rules` to `text` until the output stops changing.
+ *
+ * A single pass is not enough: a replacement can join with the text around it to create a new match,
+ * so `[{src: "ab", dst: "c"}, {src: "x", dst: "b"}]` turns `"ax"` into `"ab"` in one pass, which the
+ * community still rejects. Stable output contains no filtered word by definition, which is exactly what
+ * the community checks for.
+ *
+ * @throws if the rules never stabilise. `validateChallengeSettings` rejects the rule sets that can cause
+ * this (no `dst` may contain any `src`), so a community configured through pkc-js 0.0.85+ cannot produce
+ * one, but a client should still not spin forever on a hostile record.
+ */
+export function applyWordfilters(text, rules, maxPasses = DEFAULT_MAX_PASSES) {
+    let out = text;
+    for (let pass = 0; pass < maxPasses; pass++) {
+        const next = applyOnce(out, rules);
+        if (next === out)
+            return out;
+        out = next;
+    }
+    throw new Error("wordfilter rules did not stabilise");
+}
+//# sourceMappingURL=apply-wordfilters.js.map

package/dist/apply-wordfilters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-wordfilters.js","sourceRoot":"","sources":["../src/apply-wordfilters.ts"],"names":[],"mappings":"AAAA,qGAAqG;AACrG,uGAAuG;AACvG,0EAA0E;AAC1E,EAAE;AACF,sFAAsF;AACtF,oGAAoG;AACpG,wGAAwG;AACxG,gGAAgG;AAChG,qCAAqC;AASrC,MAAM,CAAC,MAAM,mBAAmB,GAAsB,CAAC,SAAS,EAAE,OAAO,EAAE,oBAAoB,CAAC,CAAC;AAEjG,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAEpC,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,GAAW,EAAU,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;AAEhG,MAAM,SAAS,GAAG,CAAC,IAAY,EAAE,KAAgC,EAAU,EAAE,CAC3E,KAAK,CAAC,MAAM,CACV,CAAC,GAAG,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,EAClF,IAAI,CACL,CAAC;AAEJ;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAY,EACZ,KAAgC,EAChC,YAAoB,kBAAkB;IAEtC,IAAI,GAAG,GAAG,IAAI,CAAC;IACf,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,SAAS,EAAE,IAAI,EAAE,EAAE,CAAC;QAC5C,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACnC,IAAI,IAAI,KAAK,GAAG;YAAE,OAAO,GAAG,CAAC;QAC7B,GAAG,GAAG,IAAI,CAAC;IACb,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;AACxD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { default as wordfilterChallenge } from "./wordfilter-challenge.js";
+export { default } from "./wordfilter-challenge.js";
+export * from "./wordfilter-challenge.js";
+export * from "./apply-wordfilters.js";
+export * from "./types.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { default as wordfilterChallenge } from "./wordfilter-challenge.js";
+export { default } from "./wordfilter-challenge.js";
+export * from "./wordfilter-challenge.js";
+export * from "./apply-wordfilters.js";
+export * from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAC3E,OAAO,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AACpD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,YAAY,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,6 @@
+export type { ChallengeFileInput, ChallengeInput, ChallengeResultInput, GetChallengeArgsInput, CommunityChallengeSetting } from "@pkcprotocol/pkc-js/challenges";
+import type { GetChallengeArgsInput } from "@pkcprotocol/pkc-js/challenges";
+export type LocalCommunity = GetChallengeArgsInput["community"];
+export type PKC = LocalCommunity["_pkc"];
+type ChallengeRequestMessage = GetChallengeArgsInput["challengeRequestMessage"];
+export type PublicationWithCommunityAuthorFromDecryptedChallengeRequest = NonNullable<ChallengeRequestMessage["vote"] | ChallengeRequestMessage["comment"] | ChallengeRequestMessage["commentEdit"] | ChallengeRequestMessage["commentModeration"] | ChallengeRequestMessage["communityEdit"]>;

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/wordfilter-challenge.d.ts

@@ -0,0 +1,12 @@
+import type { ChallengeFileInput, ChallengeResultInput, CommunityChallengeSetting, GetChallengeArgsInput } from "./types.js";
+declare const description = "Publications must already have the community's word replacements applied. The community does not rewrite text, it only rejects text that still contains a filtered word.";
+declare const optionInputs: NonNullable<ChallengeFileInput["optionInputs"]>;
+declare const getChallenge: ({ challengeSettings, challengeRequestMessage }: GetChallengeArgsInput) => Promise<ChallengeResultInput>;
+declare const validateChallengeSettings: ({ challengeSettings }: {
+    challengeSettings: CommunityChallengeSetting;
+}) => void;
+declare function ChallengeFileFactory(_args: {
+    challengeSettings: CommunityChallengeSetting;
+}): ChallengeFileInput;
+export { description, optionInputs, getChallenge, validateChallengeSettings };
+export default ChallengeFileFactory;

package/dist/wordfilter-challenge.js

@@ -0,0 +1,206 @@
+import { DEFAULT_FIELD_NAMES } from "./apply-wordfilters.js";
+const MAX_RULES = 64;
+const MAX_RULE_STRING_LENGTH = 128;
+const DEFAULT_ERROR = "This community replaces certain words. Please repost with the replacements applied.";
+const description = "Publications must already have the community's word replacements applied. The community does not rewrite text, it only rejects text that still contains a filtered word.";
+const type = "text/plain";
+const optionInputs = [
+    {
+        option: "wordfilters",
+        label: "Wordfilters",
+        default: "[]",
+        description: "JSON array of {src, dst} replacements, applied in array order, cascading. Matched literally and case-insensitively. Must be listed in publicOptions so publishing clients can read and apply it.",
+        placeholder: '[{"src":"plebbit","dst":"bitcoin"},{"src":"spamword","dst":""}]',
+        required: true
+    },
+    {
+        option: "fieldNames",
+        label: "Field Names",
+        default: JSON.stringify(DEFAULT_FIELD_NAMES),
+        description: "JSON array of dot-notation paths on the publication to check, the same convention publication-match uses for propertyName. Must be listed in publicOptions when set. Defaults to content, title and author.displayName.",
+        placeholder: '["content","title","author.displayName"]'
+    },
+    {
+        option: "error",
+        label: "Error",
+        default: DEFAULT_ERROR,
+        description: "The error to display to the author when a publication still contains a filtered word.",
+        placeholder: DEFAULT_ERROR
+    }
+];
+const publicationFieldNames = [
+    "comment",
+    "vote",
+    "commentEdit",
+    "commentModeration",
+    "communityEdit"
+];
+const derivePublicationFromChallengeRequest = (challengeRequestMessage) => {
+    for (const fieldName of publicationFieldNames) {
+        const publication = challengeRequestMessage[fieldName];
+        if (publication) {
+            return publication;
+        }
+    }
+    return undefined;
+};
+// Dot-notation lookup, the same convention publication-match uses for `propertyName`, so `content`
+// covers a comment and a comment edit without the config naming publication types.
+const getValueAtPath = (publication, path) => {
+    let current = publication;
+    for (const segment of path.split(".")) {
+        if (typeof current !== "object" || current === null) {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+};
+const parseRules = (wordfilters) => {
+    // Only an absent option means "no rules". An empty string satisfies core's `required` check but is not
+    // valid JSON, so it falls through to the parse error rather than silently disabling the filter.
+    if (wordfilters === undefined)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(wordfilters);
+    }
+    catch (e) {
+        throw new Error(`wordfilters is not valid JSON: ${e.message}`);
+    }
+    if (!Array.isArray(parsed)) {
+        throw new Error("wordfilters must be a JSON array of {src, dst} objects");
+    }
+    return parsed.map((rule, index) => {
+        if (typeof rule !== "object" || rule === null || Array.isArray(rule)) {
+            throw new Error(`wordfilters[${index}] must be an object with src and dst`);
+        }
+        const { src, dst } = rule;
+        if (typeof src !== "string") {
+            throw new Error(`wordfilters[${index}].src must be a string`);
+        }
+        if (typeof dst !== "string") {
+            throw new Error(`wordfilters[${index}].dst must be a string`);
+        }
+        return { src, dst };
+    });
+};
+const parseFieldNames = (fieldNames) => {
+    if (fieldNames === undefined)
+        return [...DEFAULT_FIELD_NAMES];
+    let parsed;
+    try {
+        parsed = JSON.parse(fieldNames);
+    }
+    catch (e) {
+        throw new Error(`fieldNames is not valid JSON: ${e.message}`);
+    }
+    if (!Array.isArray(parsed)) {
+        throw new Error("fieldNames must be a JSON array of dot-notation property paths");
+    }
+    return parsed.map((fieldName, index) => {
+        if (typeof fieldName !== "string" || !fieldName) {
+            throw new Error(`fieldNames[${index}] must be a non-empty string`);
+        }
+        return fieldName;
+    });
+};
+const getChallenge = async ({ challengeSettings, challengeRequestMessage }) => {
+    const publication = derivePublicationFromChallengeRequest(challengeRequestMessage);
+    if (!publication) {
+        return { success: false, error: "Could not derive publication from challenge request." };
+    }
+    // validateChallengeSettings rejects an unparseable config at edit time, so reaching this catch means a
+    // config that predates the hook. Fail loudly rather than passing everything: a wordfilter that silently
+    // stops filtering is worse than one that visibly breaks.
+    let rules;
+    let fieldNames;
+    try {
+        rules = parseRules(challengeSettings?.options?.["wordfilters"]);
+        fieldNames = parseFieldNames(challengeSettings?.options?.["fieldNames"]);
+    }
+    catch (e) {
+        return { success: false, error: `Invalid wordfilter challenge settings: ${e.message}` };
+    }
+    if (!rules.length) {
+        return { success: true };
+    }
+    const error = challengeSettings?.options?.["error"] || DEFAULT_ERROR;
+    for (const fieldName of fieldNames) {
+        const value = getValueAtPath(publication, fieldName);
+        // Absent fields pass cleanly. A vote has no content, and that is not a failure. publication-match
+        // treats a missing property as a failure, which would reject every vote. Do not copy that.
+        if (typeof value !== "string") {
+            continue;
+        }
+        const lowerCasedValue = value.toLowerCase();
+        for (const rule of rules) {
+            if (lowerCasedValue.includes(rule.src.toLowerCase())) {
+                return { success: false, error };
+            }
+        }
+    }
+    return { success: true };
+};
+// Everything here is a mistake that would otherwise surface as every author being rejected, long after the
+// owner saved the config. Sync and no network, per docs/protocol/challenge-authoring.md.
+const validateChallengeSettings = ({ challengeSettings }) => {
+    // A client that cannot read the rules cannot satisfy them, so publication is required rather than the
+    // owner's call. See "Require publication when clients need to read it" in challenge-authoring.md.
+    if (!challengeSettings.publicOptions?.includes("wordfilters")) {
+        throw new Error("wordfilters must be listed in publicOptions: publishing clients apply the replacements before signing, and a client that cannot read the rules cannot satisfy them");
+    }
+    const rules = parseRules(challengeSettings.options?.["wordfilters"]);
+    if (rules.length > MAX_RULES) {
+        throw new Error(`wordfilters has ${rules.length} rules, the maximum is ${MAX_RULES}`);
+    }
+    const seenSources = new Map();
+    for (const [index, { src, dst }] of rules.entries()) {
+        if (!src) {
+            throw new Error(`wordfilters[${index}].src must not be empty`);
+        }
+        if (src.length > MAX_RULE_STRING_LENGTH) {
+            throw new Error(`wordfilters[${index}].src is ${src.length} characters, the maximum is ${MAX_RULE_STRING_LENGTH}`);
+        }
+        if (dst.length > MAX_RULE_STRING_LENGTH) {
+            throw new Error(`wordfilters[${index}].dst is ${dst.length} characters, the maximum is ${MAX_RULE_STRING_LENGTH}`);
+        }
+        // Matching is case-insensitive, so "AB" and "ab" are the same rule and the same no-op.
+        const lowerCasedSrc = src.toLowerCase();
+        if (lowerCasedSrc === dst.toLowerCase()) {
+            throw new Error(`wordfilters[${index}].src and dst are both '${src}', which replaces nothing`);
+        }
+        const firstIndex = seenSources.get(lowerCasedSrc);
+        if (firstIndex !== undefined) {
+            throw new Error(`wordfilters[${index}].src ('${src}') is already the src of wordfilters[${firstIndex}]: the second rule can never match`);
+        }
+        seenSources.set(lowerCasedSrc, index);
+    }
+    // The rule that guarantees the client's replacement loop terminates. Without it a rule like
+    // lol -> lolol produces output that always contains a filtered word, making every post permanently
+    // unpublishable. Cross-rule, because rule A's dst is fed to rule B on the next pass.
+    for (const [index, { dst }] of rules.entries()) {
+        const lowerCasedDst = dst.toLowerCase();
+        for (const [otherIndex, { src }] of rules.entries()) {
+            if (lowerCasedDst.includes(src.toLowerCase())) {
+                throw new Error(`wordfilters[${index}].dst ('${dst}') contains wordfilters[${otherIndex}].src ('${src}'): the replacement would itself be filtered, so no text could ever pass`);
+            }
+        }
+    }
+    // Same reasoning as wordfilters: a client that checks the default fields while the community checks a
+    // different set rejects every author, with nothing in the record explaining why.
+    if (challengeSettings.options?.["fieldNames"] !== undefined) {
+        parseFieldNames(challengeSettings.options["fieldNames"]);
+        if (!challengeSettings.publicOptions?.includes("fieldNames")) {
+            throw new Error("fieldNames must be listed in publicOptions when it is set: a client filtering the default fields cannot satisfy a community checking different ones");
+        }
+    }
+};
+function ChallengeFileFactory(_args) {
+    // Deliberately cheap and non-throwing: the factory runs on load as well as on edit, so throwing here
+    // would fail community startup rather than the offending edit.
+    return { getChallenge, optionInputs, type, description, validateChallengeSettings };
+}
+export { description, optionInputs, getChallenge, validateChallengeSettings };
+export default ChallengeFileFactory;
+//# sourceMappingURL=wordfilter-challenge.js.map

package/dist/wordfilter-challenge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wordfilter-challenge.js","sourceRoot":"","sources":["../src/wordfilter-challenge.ts"],"names":[],"mappings":"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"}