@voltro/plugin-moderation 0.1.0

package/dist/errors.d.ts

@@ -0,0 +1,18 @@
+import { Schema } from 'effect';
+
+/** Raised when a `block`-action rule flags the content — the write never
+ *  commits. Merged into every procedure's wire-error union (typed on the client). */
+export declare class ContentRejected extends ContentRejected_base {
+}
+
+declare const ContentRejected_base: Schema.TaggedErrorClass<ContentRejected, "ContentRejected", {
+    readonly _tag: Schema.tag<"ContentRejected">;
+} & {
+    /** The rpc tag that was moderated. */
+    tag: typeof Schema.String;
+    /** Matched categories / keywords. */
+    categories: Schema.Array$<typeof Schema.String>;
+    reason: typeof Schema.String;
+}>;
+
+export { }

package/dist/errors.js

@@ -0,0 +1,9 @@
+import { Schema as e } from "effect";
+//#region src/errors.ts
+var t = class extends e.TaggedError()("ContentRejected", {
+	tag: e.String,
+	categories: e.Array(e.String),
+	reason: e.String
+}) {};
+//#endregion
+export { t as ContentRejected };

package/dist/index.d.ts

@@ -0,0 +1,117 @@
+import { Context } from 'effect';
+import { Effect } from 'effect';
+import { generateObject } from '@voltro/ai';
+import { Schema } from 'effect';
+import { VoltroPlugin } from '@voltro/protocol';
+
+/** AI moderation via @voltro/ai (lazy, OPTIONAL dependency). Uses a structured
+ *  classification. `threshold` (0..1) decides flagged from the model's max
+ *  category score.
+ *
+ *  Two distinct failure modes — the distinction matters because a silent
+ *  false-pass is the worst error class for a security control:
+ *   - `@voltro/ai` NOT INSTALLED (import rejects) → a configuration error.
+ *     Warn ONCE (so "all content silently passes" is never silent), fail open.
+ *   - per-call model error / outage → fail open WITHOUT warning (a transient
+ *     outage must not block every write, and would spam the log). */
+export declare const aiProvider: (opts?: AiProviderOptions) => ModerationProvider;
+
+declare interface AiProviderOptions {
+    readonly threshold?: number;
+    readonly categories?: ReadonlyArray<string>;
+    /** Importer seam for the optional `@voltro/ai` dependency — defaults to the
+     *  real lazy import. Tests inject a stub to drive the verdict logic AND the
+     *  missing-dependency branch deterministically (mirrors @voltro/ai's own
+     *  injectable gatewayProvider). */
+    readonly load?: () => Promise<{
+        readonly generateObject: typeof generateObject;
+    }>;
+}
+
+/** Raised when a `block`-action rule flags the content — the write never
+ *  commits. Merged into every procedure's wire-error union (typed on the client). */
+export declare class ContentRejected extends ContentRejected_base {
+}
+
+declare const ContentRejected_base: Schema.TaggedErrorClass<ContentRejected, "ContentRejected", {
+    readonly _tag: Schema.tag<"ContentRejected">;
+} & {
+    /** The rpc tag that was moderated. */
+    tag: typeof Schema.String;
+    /** Matched categories / keywords. */
+    categories: Schema.Array$<typeof Schema.String>;
+    reason: typeof Schema.String;
+}>;
+
+/** A flagged-content item awaiting review (the dashboard queue). */
+export declare interface FlaggedItem {
+    readonly id: string;
+    readonly tag: string;
+    readonly categories: ReadonlyArray<string>;
+    readonly reason: string;
+    readonly subjectId: string | null;
+    readonly at: string;
+    status: 'pending' | 'confirmed' | 'dismissed';
+}
+
+/** Zero-dep denylist matcher. Case-insensitive whole-word match. */
+export declare const keywordProvider: (deny: ReadonlyArray<string>) => ModerationProvider;
+
+/** Moderate arbitrary text in a handler (e.g. to redact before writing) — the
+ *  fine-grained escape the rpc interceptor can't do (it can't rewrite input).
+ *  Reads the configured provider off `ModerationService`; never throws. */
+export declare const moderate: (text: string) => Effect.Effect<ModerationVerdict, never, ModerationService>;
+
+export declare const moderationPlugin: (options: ModerationPluginOptions) => VoltroPlugin;
+
+export declare interface ModerationPluginOptions {
+    readonly provider: ModerationProvider;
+    readonly rules: ReadonlyArray<ModerationRule>;
+    /** Called when a `flag`-action rule (or any flagged content) is seen. */
+    readonly onFlag?: (info: {
+        tag: string;
+        verdict: ModerationVerdict;
+    }) => void;
+    readonly name?: string;
+}
+
+export declare type ModerationProvider = (text: string) => Effect.Effect<ModerationVerdict, never, never>;
+
+export declare interface ModerationRule {
+    /** rpc tag (exact) or RegExp on the tag. */
+    readonly match: string | RegExp;
+    /** Input field keys whose string values are concatenated + moderated. */
+    readonly fields: ReadonlyArray<string>;
+    /** `block` (default) fails the call; `flag` allows + records. */
+    readonly action?: 'block' | 'flag';
+}
+
+/** `Context.Tag` for the moderation service — `yield* ModerationService` in any
+ *  handler once `moderationPlugin(...)` is wired. The handler depends on the
+ *  Tag; the plugin owns the provider-backed implementation (no module-level
+ *  global). Mirrors `@voltro/plugin-mail`'s `MailService`. */
+export declare class ModerationService extends ModerationService_base {
+}
+
+declare const ModerationService_base: Context.TagClass<ModerationService, "@voltro/plugin-moderation/ModerationService", ModerationServiceShape>;
+
+/** The moderation runtime surface a handler reads to classify arbitrary text.
+ *  Backed by the configured provider; contributed once per app by
+ *  `moderationPlugin(...)` via `services`, mirroring `MailService` /
+ *  `StorageService`. */
+export declare interface ModerationServiceShape {
+    /** Classify text against the configured provider. Never fails. */
+    readonly moderate: (text: string) => Effect.Effect<ModerationVerdict, never, never>;
+}
+
+export declare interface ModerationVerdict {
+    /** True when the content violates policy. */
+    readonly flagged: boolean;
+    /** Matched categories (e.g. 'hate', 'sexual', 'self-harm', or a keyword). */
+    readonly categories?: ReadonlyArray<string>;
+    /** Highest category score 0..1 (AI providers). */
+    readonly score?: number;
+    readonly reason?: string;
+}
+
+export { }

package/dist/index.js

@@ -0,0 +1,150 @@
+import { ContentRejected as e } from "./errors.js";
+import { Context as t, Effect as n, Layer as r } from "effect";
+import { definePlugin as i } from "@voltro/protocol";
+import { createLogger as a } from "@voltro/logger";
+//#region src/providers.ts
+var o = a({ scope: "@voltro/plugin-moderation" }), s = { flagged: !1 }, c = (e) => {
+	let t = e.map((e) => e.toLowerCase());
+	return (e) => n.sync(() => {
+		let n = e.toLowerCase(), r = t.filter((e) => RegExp(`\\b${e.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`).test(n));
+		return r.length > 0 ? {
+			flagged: !0,
+			categories: r,
+			reason: `matched denied term(s): ${r.join(", ")}`
+		} : s;
+	});
+}, l = (e = {}) => {
+	let t = e.threshold ?? .7, r = e.categories ?? [
+		"hate",
+		"harassment",
+		"sexual",
+		"violence",
+		"self-harm",
+		"illicit"
+	], i = e.load ?? (() => import("@voltro/ai")), a = !1;
+	return (e) => n.gen(function* () {
+		let c = yield* n.tryPromise(i).pipe(n.catchAll(() => n.succeed(null)));
+		return c === null ? (a || (a = !0, o.warn("aiProvider configured but @voltro/ai could not be loaded — content is NOT being moderated; install @voltro/ai")), s) : yield* n.tryPromise(async () => {
+			let { Schema: i } = await import("effect"), a = i.Struct({
+				flagged: i.Boolean,
+				topCategory: i.NullOr(i.String),
+				score: i.Number
+			}), { object: o } = await n.runPromise(c.generateObject({
+				schema: a,
+				system: `You are a content moderator. Categories: ${r.join(", ")}. Return whether the content violates policy, the worst category, and a 0..1 severity score.`,
+				prompt: e
+			})), s = o.flagged || o.score >= t;
+			return {
+				flagged: s,
+				score: o.score,
+				...o.topCategory ? { categories: [o.topCategory] } : {},
+				...s ? { reason: `ai moderation: ${o.topCategory ?? "policy"} (${o.score.toFixed(2)})` } : {}
+			};
+		}).pipe(n.catchAll(() => n.succeed(s)));
+	});
+}, u = class extends t.Tag("@voltro/plugin-moderation/ModerationService")() {}, d = (e) => n.flatMap(u, (t) => t.moderate(e)), f = (e, t) => {
+	if (typeof e != "object" || !e) return "";
+	let n = e;
+	return t.map((e) => n[e]).filter((e) => typeof e == "string").join("\n");
+}, p = (t) => {
+	let a = t.name ? `@voltro/plugin-moderation#${t.name}` : "@voltro/plugin-moderation", o = (e) => t.rules.filter((t) => typeof t.match == "string" ? t.match === e : t.match.test(e)), s = t.onFlag, c = () => void 0, l = [], d = 0, p = 0, m = 0, h = (e, t, n) => {
+		l.unshift({
+			id: `mod_${Date.now().toString(36)}_${d++}`,
+			tag: e,
+			categories: n.categories ?? [],
+			reason: n.reason ?? "content policy violation",
+			subjectId: t,
+			at: (/* @__PURE__ */ new Date()).toISOString(),
+			status: "pending"
+		}), l.length > 200 && (l.length = 200);
+	}, g = (r, i) => {
+		let a = o(i.tag);
+		if (a.length === 0) return r;
+		let l = i.subject?.id ?? null;
+		return n.gen(function* () {
+			for (let r of a) {
+				let a = f(i.input, r.fields);
+				if (a.length === 0) continue;
+				let o = yield* t.provider(a);
+				if (!o.flagged) continue;
+				let u = o.categories ?? [], d = o.reason ?? "content policy violation";
+				if ((r.action ?? "block") === "block") return p++, h(i.tag, l, o), yield* n.fail(new e({
+					tag: i.tag,
+					categories: u,
+					reason: d
+				}));
+				m++, h(i.tag, l, o), c(i.tag, o), s?.({
+					tag: i.tag,
+					verdict: o
+				});
+			}
+			return yield* r;
+		});
+	}, _ = (e) => ({
+		kind: "json",
+		data: e
+	}), v = (e, t) => ({
+		kind: "json",
+		status: e,
+		data: { error: t }
+	}), y = [{
+		method: "GET",
+		path: "/flagged",
+		description: "The content-moderation review queue (newest first).",
+		handler: () => n.succeed(_({
+			items: l.slice(0, 100),
+			stats: {
+				blocked: p,
+				flagged: m,
+				pending: l.filter((e) => e.status === "pending").length
+			}
+		}))
+	}, {
+		method: "POST",
+		path: "/resolve",
+		description: "Resolve a flagged item — confirm (real violation) or dismiss (false positive).",
+		handler: (e) => n.sync(() => {
+			let t;
+			try {
+				t = JSON.parse(e.body || "{}");
+			} catch {
+				return v(400, "invalid JSON body");
+			}
+			if (!t.id || t.action !== "confirm" && t.action !== "dismiss") return v(400, "id + action (confirm|dismiss) required");
+			let n = l.find((e) => e.id === t.id);
+			return n ? (n.status = t.action === "confirm" ? "confirmed" : "dismissed", _({
+				ok: !0,
+				item: n
+			})) : v(404, `unknown item "${t.id}"`);
+		})
+	}], b = [
+		"rpc:intercept:mutation",
+		"rpc:intercept:action",
+		"inspect:read"
+	], x = r.succeed(u, { moderate: (e) => t.provider(e) });
+	return i({
+		name: a,
+		description: "Content moderation — block or flag user-content writes via an AI / keyword / custom check.",
+		permissions: b,
+		errorSchemas: [{
+			schema: e,
+			import: {
+				module: "@voltro/plugin-moderation/errors",
+				name: "ContentRejected"
+			}
+		}],
+		interceptMutation: g,
+		interceptAction: g,
+		inspectEndpoints: y,
+		services: x,
+		onActivate: (e) => n.sync(() => {
+			c = (t, n) => e.logger.warn("content flagged", {
+				tag: t,
+				categories: n.categories,
+				score: n.score
+			}), s = t.onFlag, e.logger.info("moderation active", { rules: t.rules.length });
+		})
+	});
+};
+//#endregion
+export { e as ContentRejected, u as ModerationService, l as aiProvider, c as keywordProvider, d as moderate, p as moderationPlugin };

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@voltro/plugin-moderation",
+  "version": "0.1.0",
+  "description": "Content moderation — run an AI / keyword / custom check on user-content fields and block or flag a write before it commits. Declarative per-rpc rules + an in-handler moderate() helper for redact/inline control.",
+  "keywords": [
+    "voltro",
+    "typescript",
+    "framework"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://voltro.dev",
+  "bugs": {
+    "email": "support@voltro.dev"
+  },
+  "author": {
+    "name": "Voltro UG",
+    "url": "https://voltro.dev"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "import": "./dist/errors.js",
+      "default": "./dist/errors.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "dependencies": {
+    "@voltro/logger": "0.1.0",
+    "@voltro/protocol": "0.1.0"
+  },
+  "optionalDependencies": {
+    "@voltro/ai": "0.1.0"
+  },
+  "peerDependencies": {
+    "effect": "^3.21.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}