@zhin.js/plugin-content-moderation 1.0.0

package/src/config.ts

@@ -0,0 +1,203 @@
+import {
+  isAction,
+  type Action,
+  type HttpSourceConfig,
+  type LocalSourceConfig,
+  type ModerationConfig,
+  type OnErrorPolicy,
+  type Severity,
+  type SourceConfig,
+} from './types.js';
+
+export const DEFAULT_ACTIONS: Readonly<Record<Severity, readonly Action[]>> = Object.freeze({
+  pass: Object.freeze(['allow'] as const),
+  low: Object.freeze(['log'] as const),
+  medium: Object.freeze(['redact'] as const),
+  high: Object.freeze(['drop'] as const),
+  critical: Object.freeze(['drop', 'recall'] as const),
+});
+
+export const DEFAULT_MODERATION_CONFIG: ModerationConfig = Object.freeze({
+  enabled: true,
+  onError: 'open',
+  maskChar: '*',
+  replyTemplate: '消息含不当内容，已拦截。',
+  masters: Object.freeze([] as string[]),
+  inbound: Object.freeze({
+    enabled: true,
+    bypassMasters: true,
+    whitelist: Object.freeze({
+      userIds: Object.freeze([] as string[]),
+      conversationIds: Object.freeze([] as string[]),
+    }),
+  }),
+  outbound: Object.freeze({
+    enabled: true,
+    bypass: false,
+  }),
+  actions: DEFAULT_ACTIONS,
+  sources: Object.freeze([] as SourceConfig[]),
+});
+
+export function resolveModerationConfig(raw: unknown): ModerationConfig {
+  const input = raw && typeof raw === 'object' ? raw as Record<string, unknown> : {};
+  const inboundRaw = asRecord(input.inbound);
+  const outboundRaw = asRecord(input.outbound);
+  const whitelistRaw = asRecord(inboundRaw.whitelist);
+  const onError = parseOnError(input.onError, DEFAULT_MODERATION_CONFIG.onError);
+  const maskChar = typeof input.maskChar === 'string' && input.maskChar.length > 0
+    ? input.maskChar.slice(0, 4)
+    : DEFAULT_MODERATION_CONFIG.maskChar;
+  const replyTemplate = typeof input.replyTemplate === 'string' && input.replyTemplate.length > 0
+    ? input.replyTemplate
+    : DEFAULT_MODERATION_CONFIG.replyTemplate;
+
+  return Object.freeze({
+    enabled: input.enabled !== false,
+    onError,
+    maskChar,
+    replyTemplate,
+    masters: freezeStrings(input.masters),
+    inbound: Object.freeze({
+      enabled: inboundRaw.enabled !== false,
+      bypassMasters: inboundRaw.bypassMasters !== false,
+      whitelist: Object.freeze({
+        userIds: freezeStrings(whitelistRaw.userIds),
+        conversationIds: freezeStrings(whitelistRaw.conversationIds),
+      }),
+    }),
+    outbound: Object.freeze({
+      enabled: outboundRaw.enabled !== false,
+      bypass: outboundRaw.bypass === true,
+    }),
+    actions: resolveActions(input.actions),
+    sources: Object.freeze(
+      (Array.isArray(input.sources) ? input.sources : [])
+        .map((item) => parseSource(item, onError))
+        .filter((item): item is SourceConfig => item != null),
+    ),
+  });
+}
+
+function resolveActions(raw: unknown): Readonly<Record<Severity, readonly Action[]>> {
+  const input = asRecord(raw);
+  return Object.freeze({
+    pass: resolveActionList(input.pass, DEFAULT_ACTIONS.pass),
+    low: resolveActionList(input.low, DEFAULT_ACTIONS.low),
+    medium: resolveActionList(input.medium, DEFAULT_ACTIONS.medium),
+    high: resolveActionList(input.high, DEFAULT_ACTIONS.high),
+    critical: resolveActionList(input.critical, DEFAULT_ACTIONS.critical),
+  });
+}
+
+function resolveActionList(raw: unknown, fallback: readonly Action[]): readonly Action[] {
+  if (typeof raw === 'string' && isAction(raw)) return Object.freeze([raw]);
+  if (Array.isArray(raw)) {
+    const actions = raw.filter(isAction);
+    if (actions.length > 0) return Object.freeze([...actions]);
+  }
+  return fallback;
+}
+
+function parseSource(raw: unknown, globalOnError: OnErrorPolicy): SourceConfig | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const input = raw as Record<string, unknown>;
+  const id = typeof input.id === 'string' ? input.id.trim() : '';
+  if (!id) return null;
+  const enabled = input.enabled !== false;
+  const onError = parseOnError(input.onError, globalOnError);
+
+  if (input.type === 'local') {
+    const defaultSeverity = parseHitSeverity(input.defaultSeverity ?? input.severity);
+    const local: LocalSourceConfig = Object.freeze({
+      id,
+      type: 'local',
+      enabled,
+      onError,
+      words: freezeLexiconWords(input.words, defaultSeverity),
+      wordFiles: freezeStrings(input.wordFiles),
+      includeBuiltin: input.includeBuiltin !== false,
+      defaultSeverity,
+    });
+    return local;
+  }
+
+  if (input.type === 'http') {
+    const url = typeof input.url === 'string' ? input.url.trim() : '';
+    if (!url) return null;
+    const headersRaw = asRecord(input.headers);
+    const headers: Record<string, string> = {};
+    for (const [key, value] of Object.entries(headersRaw)) {
+      if (typeof value === 'string') headers[key] = value;
+    }
+    const timeoutMs = clampNumber(input.timeoutMs, 5_000, 500, 60_000);
+    const http: HttpSourceConfig = Object.freeze({
+      id,
+      type: 'http',
+      enabled,
+      onError,
+      url,
+      headers: Object.freeze(headers),
+      timeoutMs,
+      forceUpload: input.forceUpload === true,
+    });
+    return http;
+  }
+
+  return null;
+}
+
+function parseHitSeverity(raw: unknown): Exclude<Severity, 'pass'> {
+  if (raw === 'low' || raw === 'medium' || raw === 'high' || raw === 'critical') return raw;
+  return 'high';
+}
+
+function parseOnError(raw: unknown, fallback: OnErrorPolicy): OnErrorPolicy {
+  return raw === 'open' || raw === 'closed' ? raw : fallback;
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : {};
+}
+
+function freezeStrings(value: unknown): readonly string[] {
+  if (!Array.isArray(value)) return Object.freeze([]);
+  return Object.freeze(
+    value.filter((item): item is string => typeof item === 'string' && item.length > 0),
+  );
+}
+
+function freezeLexiconWords(
+  value: unknown,
+  defaultSeverity: Exclude<Severity, 'pass'>,
+): LocalSourceConfig['words'] {
+  if (!Array.isArray(value)) return Object.freeze([]);
+  const out: LocalSourceConfig['words'][number][] = [];
+  for (const item of value) {
+    if (typeof item === 'string') {
+      const word = item.trim();
+      if (word) out.push(Object.freeze({ word, severity: defaultSeverity }));
+      continue;
+    }
+    if (!item || typeof item !== 'object') continue;
+    const record = item as Record<string, unknown>;
+    const word = typeof record.word === 'string'
+      ? record.word.trim()
+      : typeof record.text === 'string'
+        ? record.text.trim()
+        : '';
+    if (!word) continue;
+    out.push(Object.freeze({
+      word,
+      severity: parseHitSeverity(record.severity ?? defaultSeverity),
+    }));
+  }
+  return Object.freeze(out);
+}
+
+function clampNumber(value: unknown, fallback: number, min: number, max: number): number {
+  const n = typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+  return Math.min(max, Math.max(min, Math.trunc(n)));
+}

package/src/engine.ts

@@ -0,0 +1,220 @@
+import { formatCompact, getLogger, type Logger } from '@zhin.js/logger';
+import { resolveModerationConfig } from './config.js';
+import { mergeMatches, type ExtractedContent } from './extract.js';
+import { redactOutboundPayload } from './redact.js';
+import { createProviders } from './providers/registry.js';
+import type { ModerationProvider } from './providers/types.js';
+import {
+  maxSeverity,
+  type Action,
+  type Direction,
+  type MergedResult,
+  type ModerationConfig,
+  type ProviderResult,
+  type ScanInput,
+  type Severity,
+} from './types.js';
+
+export interface ApplyHooks {
+  readonly reply?: (content: string) => Promise<void>;
+  readonly recall?: () => Promise<boolean>;
+  readonly replacePayload?: (payload: unknown) => void;
+  readonly getPayload?: () => unknown;
+}
+
+export interface ApplyResult {
+  readonly continue: boolean;
+  readonly severity: Severity;
+  readonly actions: readonly Action[];
+  readonly merged: MergedResult;
+  readonly redactedPayload?: unknown;
+}
+
+export class ModerationEngine {
+  readonly #logger: Logger;
+  readonly #cwd: string;
+  readonly #fetch?: typeof fetch;
+  #providers: readonly ModerationProvider[] = Object.freeze([]);
+  #config: ModerationConfig = resolveModerationConfig({});
+
+  constructor(options: {
+    readonly logger?: Logger;
+    readonly cwd?: string;
+    readonly fetch?: typeof fetch;
+  } = {}) {
+    this.#logger = options.logger ?? getLogger('content-moderation');
+    this.#cwd = options.cwd ?? process.cwd();
+    this.#fetch = options.fetch;
+  }
+
+  get config(): ModerationConfig {
+    return this.#config;
+  }
+
+  configure(raw: unknown): void {
+    this.#config = resolveModerationConfig(raw);
+    this.#providers = createProviders(this.#config, {
+      cwd: this.#cwd,
+      fetch: this.#fetch,
+    });
+  }
+
+  /** Test helper: inject providers without going through config sources. */
+  setProvidersForTest(providers: readonly ModerationProvider[]): void {
+    this.#providers = Object.freeze([...providers]);
+  }
+
+  async scan(input: ScanInput): Promise<MergedResult> {
+    if (this.#providers.length === 0) {
+      return Object.freeze({
+        severity: 'pass',
+        matches: Object.freeze([]),
+        flaggedImageIndexes: Object.freeze([]),
+        sources: Object.freeze([]),
+      });
+    }
+
+    const results = await Promise.all(
+      this.#providers.map(async (provider) => {
+        try {
+          return await provider.scan(input);
+        } catch (error) {
+          return Object.freeze({
+            sourceId: provider.id,
+            severity: 'pass' as const,
+            error: true,
+            reason: error instanceof Error ? error.message : String(error),
+          }) satisfies ProviderResult;
+        }
+      }),
+    );
+
+    return mergeResults(results);
+  }
+
+  async apply(options: {
+    readonly direction: Direction;
+    readonly extracted: ExtractedContent;
+    readonly scanInput: ScanInput;
+    readonly hooks: ApplyHooks;
+  }): Promise<ApplyResult> {
+    const merged = await this.scan(options.scanInput);
+    const actions = [...this.#config.actions[merged.severity]];
+    const actionSet = new Set<Action>(actions);
+
+    if (merged.severity !== 'pass' || actionSet.has('log')) {
+      this.#logger.info(formatCompact({
+        op: 'moderation',
+        direction: options.direction,
+        severity: merged.severity,
+        actions: actions.join(','),
+        sources: merged.sources.map((s) => `${s.sourceId}:${s.severity}${s.error ? '!' : ''}`).join('|'),
+        conversation: options.scanInput.context.conversationId,
+        sender: options.scanInput.context.sender,
+        reason: merged.reason,
+      }));
+    }
+
+    if (actionSet.has('log') && merged.severity === 'pass') {
+      // already logged above when log is present
+    }
+
+    let redactedPayload: unknown | undefined;
+
+    if (actionSet.has('redact')) {
+      if (options.direction === 'outbound') {
+        const payload = options.hooks.getPayload?.();
+        redactedPayload = redactOutboundPayload(payload, options.extracted, {
+          maskChar: this.#config.maskChar,
+          matches: merged.matches,
+          flaggedImageIndexes: merged.flaggedImageIndexes,
+        });
+        options.hooks.replacePayload?.(redactedPayload);
+      }
+      // inbound redact：Message 只读，无法改写原文；仍 next() 放行
+    }
+
+    if (actionSet.has('reply') && options.direction === 'inbound') {
+      try {
+        await options.hooks.reply?.(this.#config.replyTemplate);
+      } catch (error) {
+        this.#logger.warn(formatCompact({
+          op: 'moderation_reply_failed',
+          error: error instanceof Error ? error.message : String(error),
+        }));
+      }
+    } else if (actionSet.has('reply') && options.direction === 'outbound') {
+      this.#logger.debug(formatCompact({
+        op: 'moderation_reply_skipped',
+        direction: 'outbound',
+      }));
+    }
+
+    if (actionSet.has('recall') && options.direction === 'inbound') {
+      try {
+        const ok = await options.hooks.recall?.();
+        if (!ok) {
+          this.#logger.warn(formatCompact({
+            op: 'moderation_recall_degraded',
+            reason: 'unsupported_or_missing_id',
+          }));
+        }
+      } catch (error) {
+        this.#logger.warn(formatCompact({
+          op: 'moderation_recall_degraded',
+          error: error instanceof Error ? error.message : String(error),
+        }));
+      }
+    }
+
+    const stop = shouldStop(options.direction, actionSet);
+    return Object.freeze({
+      continue: !stop,
+      severity: merged.severity,
+      actions: Object.freeze(actions),
+      merged,
+      ...(redactedPayload !== undefined ? { redactedPayload } : {}),
+    });
+  }
+}
+
+export function mergeResults(results: readonly ProviderResult[]): MergedResult {
+  let severity: Severity = 'pass';
+  const matches = mergeMatches(...results.map((r) => r.matches));
+  const flagged = new Set<number>();
+  const reasons: string[] = [];
+
+  for (const result of results) {
+    severity = maxSeverity(severity, result.severity);
+    for (const idx of result.flaggedImageIndexes ?? []) flagged.add(idx);
+    if (result.reason) reasons.push(`${result.sourceId}: ${result.reason}`);
+  }
+
+  return Object.freeze({
+    severity,
+    matches,
+    flaggedImageIndexes: Object.freeze([...flagged].sort((a, b) => a - b)),
+    sources: Object.freeze([...results]),
+    ...(reasons.length ? { reason: reasons.join('; ') } : {}),
+  });
+}
+
+function shouldStop(direction: Direction, actions: ReadonlySet<Action>): boolean {
+  if (actions.has('drop')) return true;
+  // 入站 recall：尽量撤回后不再进入后续处理（无 allow 时中断）
+  if (direction === 'inbound' && actions.has('recall') && !actions.has('allow')) {
+    return true;
+  }
+  return false;
+}
+
+let sharedEngine: ModerationEngine | null = null;
+
+export function getModerationEngine(): ModerationEngine {
+  if (!sharedEngine) sharedEngine = new ModerationEngine();
+  return sharedEngine;
+}
+
+export function resetModerationEngine(): void {
+  sharedEngine = null;
+}

package/src/extract.ts

@@ -0,0 +1,155 @@
+import type { ExtractedImage, ScanContext, TextMatch } from './types.js';
+
+export interface ExtractedContent {
+  readonly text: string;
+  readonly images: readonly ExtractedImage[];
+  /** Original segment list when payload was structured; undefined for plain string. */
+  readonly segments?: readonly Record<string, unknown>[];
+}
+
+export function extractFromTextAndSegments(
+  content: string,
+  segments: readonly unknown[] | undefined,
+): ExtractedContent {
+  if (Array.isArray(segments) && segments.length > 0) {
+    return extractFromSegments(segments);
+  }
+  return Object.freeze({
+    text: content ?? '',
+    images: Object.freeze([] as ExtractedImage[]),
+  });
+}
+
+export function extractFromOutboundPayload(payload: unknown): ExtractedContent {
+  if (typeof payload === 'string') {
+    return Object.freeze({
+      text: payload,
+      images: Object.freeze([] as ExtractedImage[]),
+    });
+  }
+  if (Array.isArray(payload)) {
+    return extractFromSegments(payload);
+  }
+  if (payload && typeof payload === 'object' && 'type' in payload) {
+    return extractFromSegments([payload]);
+  }
+  return Object.freeze({
+    text: payload == null ? '' : String(payload),
+    images: Object.freeze([] as ExtractedImage[]),
+  });
+}
+
+function extractFromSegments(segments: readonly unknown[]): ExtractedContent {
+  const texts: string[] = [];
+  const images: ExtractedImage[] = [];
+  const normalized: Record<string, unknown>[] = [];
+
+  for (let i = 0; i < segments.length; i++) {
+    const seg = segments[i];
+    if (!seg || typeof seg !== 'object') continue;
+    const record = seg as Record<string, unknown>;
+    normalized.push(record);
+    const type = String(record.type ?? '');
+    const data = asRecord(record.data);
+
+    if (type === 'text') {
+      const text = typeof data.text === 'string' ? data.text : '';
+      if (text) texts.push(text);
+      continue;
+    }
+
+    if (type === 'image') {
+      const media = asRecord(data.media);
+      const image = mediaToImage(images.length, i, media, data);
+      if (image) images.push(image);
+    }
+  }
+
+  return Object.freeze({
+    text: texts.join(''),
+    images: Object.freeze(images),
+    segments: Object.freeze(normalized),
+  });
+}
+
+function mediaToImage(
+  index: number,
+  segmentIndex: number,
+  media: Record<string, unknown>,
+  data: Record<string, unknown>,
+): ExtractedImage | null {
+  // Canonical MediaRef
+  if (typeof media.kind === 'string' && typeof media.value === 'string') {
+    const mime = typeof media.mime_type === 'string' ? media.mime_type : undefined;
+    if (media.kind === 'url') {
+      return Object.freeze({ index, segmentIndex, url: media.value, mime });
+    }
+    if (media.kind === 'base64') {
+      return Object.freeze({ index, segmentIndex, base64: media.value, mime });
+    }
+    if (media.kind === 'path') {
+      return Object.freeze({ index, segmentIndex, path: media.value, mime });
+    }
+    // kind=file: opaque platform ref — no fetchable URL
+    return Object.freeze({ index, segmentIndex, mime });
+  }
+
+  // Legacy wire fields
+  if (typeof data.url === 'string' && data.url) {
+    return Object.freeze({ index, segmentIndex, url: data.url });
+  }
+  if (typeof data.base64 === 'string' && data.base64) {
+    return Object.freeze({ index, segmentIndex, base64: data.base64 });
+  }
+  if (typeof data.file === 'string' && data.file) {
+    const file = data.file;
+    if (/^https?:\/\//i.test(file)) {
+      return Object.freeze({ index, segmentIndex, url: file });
+    }
+    return Object.freeze({ index, segmentIndex, path: file });
+  }
+
+  return null;
+}
+
+export function buildScanContext(input: {
+  readonly adapter?: string;
+  readonly endpoint?: string;
+  readonly conversationKind?: string;
+  readonly conversationId?: string;
+  readonly sender?: string;
+}): ScanContext {
+  return Object.freeze({
+    adapter: input.adapter ?? '',
+    endpoint: input.endpoint ?? '',
+    conversationKind: input.conversationKind ?? '',
+    conversationId: input.conversationId ?? '',
+    ...(input.sender != null ? { sender: input.sender } : {}),
+  });
+}
+
+export function mergeMatches(
+  ...lists: Array<readonly TextMatch[] | undefined>
+): readonly TextMatch[] {
+  const out: TextMatch[] = [];
+  for (const list of lists) {
+    if (!list) continue;
+    for (const m of list) {
+      if (
+        Number.isFinite(m.start)
+        && Number.isFinite(m.end)
+        && m.end > m.start
+        && m.start >= 0
+      ) {
+        out.push({ start: Math.trunc(m.start), end: Math.trunc(m.end) });
+      }
+    }
+  }
+  return Object.freeze(out);
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : {};
+}

package/src/index.ts

@@ -0,0 +1,49 @@
+export {
+  DEFAULT_ACTIONS,
+  DEFAULT_MODERATION_CONFIG,
+  resolveModerationConfig,
+} from './config.js';
+export {
+  shouldBypassInbound,
+  shouldBypassOutbound,
+} from './bypass.js';
+export {
+  extractFromOutboundPayload,
+  extractFromTextAndSegments,
+  buildScanContext,
+} from './extract.js';
+export {
+  redactText,
+  redactOutboundPayload,
+} from './redact.js';
+export {
+  ModerationEngine,
+  getModerationEngine,
+  resetModerationEngine,
+  mergeResults,
+} from './engine.js';
+export type {
+  Severity,
+  Action,
+  OnErrorPolicy,
+  Direction,
+  ModerationConfig,
+  ProviderResult,
+  MergedResult,
+  ScanInput,
+  SourceConfig,
+} from './types.js';
+export { maxSeverity, SEVERITY_RANK } from './types.js';
+export {
+  LocalLexiconProvider,
+  findMatches,
+  findGradedMatches,
+  loadWords,
+  loadLexiconEntries,
+  parseWordFile,
+  parseWordLine,
+} from './providers/local-lexicon.js';
+export { BUILTIN_LEXICON, mergeLexiconEntries } from './providers/builtin-lexicon.js';
+export type { LexiconEntry, LexiconSeverity } from './providers/builtin-lexicon.js';
+export { HttpModerationProvider, parseHttpResult, isPublicHttpUrl } from './providers/http.js';
+export { createProviders } from './providers/registry.js';