open-safety-guard 1.0.0

package/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: Node.js CI
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x, 22.x]
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+    - run: npm ci
+    - run: npm test

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# open-safety-guard
+
+**A high-speed, structural LLM classification engine for Trust & Safety AI.**
+
+[![Node.js CI](https://github.com/anatolyben/open-safety-guard/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/anatolyben/open-safety-guard/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+`open-safety-guard` is a Node.js framework optimized for executing real-time content moderation using ultra-fast LLMs like Groq. It ships with built-in policies for **Spam**, **Conduct**, and **Topics**, and provides a simple Express middleware for protecting your application routes out of the box.
+
+## The Problem
+
+Traditional content moderation relies heavily on regex pattern matching, legacy blocklists, or slow, expensive Machine Learning models. These approaches are often bypassed by bad actors using slight text variations or lack context when moderating nuanced conversation (e.g. distinguishing between a heated debate and a personal attack).
+
+By leveraging ultra-fast, structured LLM inference (using providers like Groq), we can now execute high-quality semantic moderation in milliseconds. `open-safety-guard` forces the LLM to output deterministic JSON schemas, meaning you get a fast, structured, programmatic safety report for every message, making it easy to block unwanted content reliably.
+
+## Installation
+
+```bash
+npm install open-safety-guard
+```
+
+Ensure your Groq API key is available in your environment:
+```bash
+export GROQ_API_KEY="gsk_..."
+```
+
+## Programmatic Usage
+
+You can use the core logic directly in any Node.js application to evaluate a string of text across multiple guards.
+
+```javascript
+import { ModerateText, SpamGuard, ConductGuard } from 'open-safety-guard';
+
+async function checkMessage() {
+  const input = "Click here to win a free iPhone! http://scam.link";
+
+  // Evaluate the input across the configured guards
+  const result = await ModerateText(input, [
+    new SpamGuard({ sensitivity: 'high' }),
+    new ConductGuard()
+  ]);
+
+  console.log(result);
+  /* 
+  {
+    flagged: true,
+    reasons: [ "[SpamGuard] The message promotes a scam." ],
+    results: {
+      SpamGuard: { flagged: true, is_spam: true, category: "scam", confidence: 0.95, ... },
+      ConductGuard: { flagged: false, violation: false, ... }
+    }
+  }
+  */
+}
+
+checkMessage();
+```
+
+## Express Middleware Usage
+
+Want to protect your APIs instantly? Use the included Express middleware to build "Moderation as a Service" directly into your app.
+
+```javascript
+import express from 'express';
+import { contentFilter, SpamGuard, ConductGuard } from 'open-safety-guard';
+
+const app = express();
+app.use(express.json());
+
+// Protect the route using open-safety-guard
+app.post(
+  '/api/comments', 
+  contentFilter({
+    guards: [new SpamGuard(), new ConductGuard()],
+    // Optional: tell the middleware how to extract text from the request
+    extractText: (req) => req.body.comment
+  }), 
+  (req, res) => {
+    // If we reach here, the comment passed moderation!
+    res.json({ success: true, message: "Comment saved!" });
+  }
+);
+
+app.listen(3000, () => console.log('Server is running on port 3000'));
+```
+
+## Custom Guards
+
+You can easily build custom LLM guards by providing your own system prompt and JSON schema. This is incredibly powerful for evaluating highly specific business rules or custom content policies.
+
+```javascript
+import { CustomGuard, ModerateText } from 'open-safety-guard';
+
+const MedicalAdviceGuard = new CustomGuard({
+  name: "MedicalAdviceGuard",
+  flagField: "is_medical_advice",
+  systemPrompt: `You are a medical safety assistant. Determine if the user is providing unauthorized medical advice.
+Respond with JSON only.
+Schema: {"is_medical_advice": boolean, "confidence": number, "reason": string}`
+});
+
+const result = await ModerateText("You should definitely take 400mg of ibuprofen for that.", [MedicalAdviceGuard]);
+
+if (result.flagged) {
+  console.log("Blocked for unauthorized medical advice!");
+}
+```
+
+## Fallback & Circuit Breaker (Fail-Open)
+
+Content moderation APIs should never break your main application loop. `open-safety-guard` is built with a strict **fail-open** philosophy. If your LLM API key is missing, rate limits are hit, or the provider has an outage, the package gracefully bypasses classification (evaluating to `flagged: false`) so your application stays online.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "open-safety-guard",
+  "version": "1.0.0",
+  "description": "High-speed, structural LLM classification engine for trust & safety AI moderation.",
+  "type": "module",
+  "main": "src/index.js",
+  "scripts": {
+    "start": "node src/server.js",
+    "test": "node --test"
+  },
+  "keywords": [
+    "moderation",
+    "trust and safety",
+    "llm",
+    "groq",
+    "spam",
+    "conduct",
+    "classification",
+    "express"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "express": "^4.21.2",
+    "openai": "^4.79.0"
+  },
+  "devDependencies": {
+    "supertest": "^7.0.0"
+  }
+}

package/src/core/classifier.js

@@ -0,0 +1,93 @@
+import OpenAI from "openai";
+
+export const DEFAULT_LLM_MODEL = "llama-3.1-8b-instant";
+export const DEFAULT_GROQ_BASE_URL = "https://api.groq.com/openai/v1";
+
+/** Confidence a positive verdict must clear, per operator sensitivity. */
+export const SENSITIVITY_THRESHOLDS = Object.freeze({
+  low: 0.9,
+  medium: 0.75,
+  high: 0.6,
+});
+
+export function resolveThreshold(sensitivity) {
+  return SENSITIVITY_THRESHOLDS[sensitivity] ?? SENSITIVITY_THRESHOLDS.medium;
+}
+
+export function clampConfidence(value) {
+  return Math.min(1, Math.max(0, value));
+}
+
+export function meetsThreshold(confidence, sensitivity) {
+  return confidence >= resolveThreshold(sensitivity);
+}
+
+/**
+ * Ensures we have an API key configured (fail-open)
+ */
+export function ensureGroqKey(tag, apiKey) {
+  if (!apiKey) {
+    console.warn(`[${tag}] API key not provided or set in environment — skipping classification`);
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Run one deterministic JSON classification.
+ */
+export async function runJsonClassification({
+  tag,
+  label,
+  systemPrompt,
+  userPrompt,
+  config
+}) {
+  const apiKey = config?.apiKey || process.env.GROQ_API_KEY;
+  if (!ensureGroqKey(tag, apiKey)) return null;
+
+  const client = new OpenAI({
+    apiKey,
+    baseURL: config?.baseURL || process.env.GROQ_BASE_URL || DEFAULT_GROQ_BASE_URL,
+  });
+
+  try {
+    const response = await client.chat.completions.create({
+      model: config?.model || process.env.LLM_MODEL || DEFAULT_LLM_MODEL,
+      messages: [
+        { role: "system", content: systemPrompt },
+        { role: "user", content: userPrompt },
+      ],
+      response_format: { type: "json_object" },
+      temperature: 0,
+      max_tokens: config?.maxTokens || 128,
+    });
+    return response.choices?.[0]?.message?.content ?? "";
+  } catch (err) {
+    // Fail-open strategy
+    console.warn(`[${tag}] ${label} error — fail-open:`, err?.message ?? err);
+    return null;
+  }
+}
+
+/**
+ * Parse the verdict envelope every guard shares.
+ */
+export function parseVerdictEnvelope(raw, flagField) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+
+  if (typeof parsed?.[flagField] !== "boolean") return null;
+  if (typeof parsed.confidence !== "number") return null;
+
+  return {
+    parsed,
+    flagged: parsed[flagField],
+    confidence: clampConfidence(parsed.confidence),
+    reason: typeof parsed.reason === "string" ? parsed.reason.trim() : "",
+  };
+}

package/src/core/moderate.js

@@ -0,0 +1,39 @@
+export async function ModerateText(text, guards = [], config = {}) {
+  const results = {};
+
+  const validGuards = guards.map((guard) => {
+    // Determine if guard is a class constructor or an instance
+    const guardInstance = typeof guard === 'function' ? new guard() : guard;
+    
+    if (typeof guardInstance.evaluate !== 'function') {
+      throw new Error(`Invalid guard: ${guardInstance?.name || 'unknown'} must implement an evaluate() method.`);
+    }
+    return guardInstance;
+  });
+
+  const evalPromises = validGuards.map(async (guardInstance) => {
+    const result = await guardInstance.evaluate(text, config);
+    results[guardInstance.name || guardInstance.constructor.name] = result;
+  });
+
+  await Promise.allSettled(evalPromises);
+
+  // Compile a summarized safety report
+  const report = {
+    flagged: false,
+    results,
+    reasons: []
+  };
+
+  for (const [name, result] of Object.entries(results)) {
+    // 'null' means skipped or fail-open allowed
+    if (result && result.flagged) {
+      report.flagged = true;
+      if (result.reason) {
+        report.reasons.push(`[${name}] ${result.reason}`);
+      }
+    }
+  }
+
+  return report;
+}

package/src/express/contentFilter.js

@@ -0,0 +1,47 @@
+import { ModerateText } from '../core/moderate.js';
+
+/**
+ * Express middleware for 'Moderation as a Service'.
+ * Intercepts incoming requests, extracts text, runs LLM classifiers,
+ * and blocks the request (403) if policy is violated.
+ *
+ * @param {Object} options
+ * @param {Array} options.guards - Array of Guard instances to evaluate.
+ * @param {Function} [options.extractText] - Function to extract text from request (default: req => req.body.text).
+ * @param {Object} [options.config] - Global configuration to pass to ModerateText (e.g. apiKey).
+ */
+export function contentFilter(options = {}) {
+  const { 
+    guards = [], 
+    extractText = (req) => req.body?.text, 
+    config = {} 
+  } = options;
+
+  return async (req, res, next) => {
+    try {
+      const text = extractText(req);
+      
+      if (!text) {
+        return next();
+      }
+
+      const report = await ModerateText(text, guards, config);
+      
+      if (report.flagged) {
+        return res.status(403).json({
+          error: "Content violated safety policy",
+          reasons: report.reasons,
+          report
+        });
+      }
+
+      // Attach report to request for downstream handlers if they need it
+      req.moderationReport = report;
+      next();
+    } catch (err) {
+      console.error("[contentFilter] Middleware error:", err);
+      // Fail-open strategy: if moderation fails, allow request to proceed
+      next();
+    }
+  };
+}

package/src/guards/ConductGuard.js

@@ -0,0 +1,74 @@
+import {
+  runJsonClassification,
+  parseVerdictEnvelope,
+  meetsThreshold
+} from "../core/classifier.js";
+
+const VIOLATION_TYPES = [
+  "harassment",
+  "personal_attack",
+  "threat",
+  "hate_speech",
+  "other",
+];
+
+const MAX_TEXT_CHARS = 800;
+const MAX_RULE_CHARS = 2000;
+
+const SYSTEM_PROMPT = `You are a community conduct moderation assistant. Your only job is to decide whether a message violates the operator-defined community conduct rules.
+Respond with JSON only — no markdown, no explanation outside the JSON.
+Schema: {"violation":boolean,"violation_type":string|null,"confidence":number,"reason":string}
+Rules:
+- Judge strictly against the operator-provided conduct rules. Do not apply your own assumptions.
+- violation_type must be one of: "harassment", "personal_attack", "threat", "hate_speech", "other", or null when violation is false.
+- confidence is a number from 0 to 1 (1 = certain).
+- reason is one short sentence (max 20 words). Keep it factual.
+- Disagreements, criticism of ideas, sarcasm, and venting frustration are NOT violations unless they target a specific person with hostility.
+- Borderline or ambiguous messages should be marked as violation=false with low confidence.`;
+
+function buildUserPrompt(text, rules) {
+  const parts = [];
+  if (rules?.trim()) {
+    parts.push(`COMMUNITY CONDUCT RULES:\n${String(rules).slice(0, MAX_RULE_CHARS)}`);
+  } else {
+    parts.push(`COMMUNITY CONDUCT RULES:\nBe respectful. No harassment, personal attacks, threats, or hate speech.`);
+  }
+  parts.push(`MESSAGE TO EVALUATE:\n${String(text).slice(0, MAX_TEXT_CHARS)}`);
+  return parts.join("\n\n");
+}
+
+export class ConductGuard {
+  constructor(opts = {}) {
+    this.name = 'ConductGuard';
+    this.opts = opts;
+  }
+
+  async evaluate(text, config = {}) {
+    if (!text?.trim()) return null;
+
+    const sensitivity = this.opts.sensitivity ?? config.sensitivity ?? "medium";
+
+    const raw = await runJsonClassification({
+      tag: "conduct-guard",
+      label: "classifyConduct",
+      systemPrompt: SYSTEM_PROMPT,
+      userPrompt: buildUserPrompt(text, this.opts.rules),
+      config
+    });
+
+    if (raw === null) return null; // fail-open
+
+    const envelope = parseVerdictEnvelope(raw, "violation");
+    if (!envelope) return null;
+    
+    const { parsed, flagged, confidence, reason } = envelope;
+    const rawType = parsed.violation_type;
+    const violation_type = VIOLATION_TYPES.includes(rawType) ? rawType : null;
+
+    if (!flagged || !meetsThreshold(confidence, sensitivity)) {
+      return { flagged: false, violation: false, violation_type: null, confidence, reason };
+    }
+
+    return { flagged: true, violation: true, violation_type, confidence, reason };
+  }
+}

package/src/guards/CustomGuard.js

@@ -0,0 +1,55 @@
+import {
+  runJsonClassification,
+  parseVerdictEnvelope,
+  meetsThreshold
+} from "../core/classifier.js";
+
+export class CustomGuard {
+  /**
+   * Create a custom guard with your own schema and prompt.
+   * 
+   * @param {Object} opts 
+   * @param {string} opts.name - Name of the guard.
+   * @param {string} opts.systemPrompt - The prompt containing instructions and JSON schema.
+   * @param {string} opts.flagField - The boolean field in the JSON response that indicates a violation (e.g. 'is_violation').
+   * @param {Function} [opts.buildUserPrompt] - Optional function to build user prompt `(text) => string`.
+   */
+  constructor(opts) {
+    if (!opts.name || !opts.systemPrompt || !opts.flagField) {
+      throw new Error("CustomGuard requires 'name', 'systemPrompt', and 'flagField'");
+    }
+    this.name = opts.name;
+    this.opts = opts;
+  }
+
+  async evaluate(text, config = {}) {
+    if (!text?.trim()) return null;
+
+    const sensitivity = this.opts.sensitivity ?? config.sensitivity ?? "medium";
+
+    const userPrompt = this.opts.buildUserPrompt 
+      ? this.opts.buildUserPrompt(text) 
+      : `MESSAGE TO EVALUATE:\n${text}`;
+
+    const raw = await runJsonClassification({
+      tag: `custom-${this.name}`,
+      label: "evaluate",
+      systemPrompt: this.opts.systemPrompt,
+      userPrompt,
+      config
+    });
+
+    if (raw === null) return null; // fail-open
+
+    const envelope = parseVerdictEnvelope(raw, this.opts.flagField);
+    if (!envelope) return null;
+    
+    const { parsed, flagged, confidence, reason } = envelope;
+
+    if (!flagged || !meetsThreshold(confidence, sensitivity)) {
+      return { flagged: false, confidence, reason, ...parsed };
+    }
+
+    return { flagged: true, confidence, reason, ...parsed };
+  }
+}

package/src/guards/SpamGuard.js

@@ -0,0 +1,98 @@
+import {
+  runJsonClassification,
+  parseVerdictEnvelope,
+  meetsThreshold
+} from "../core/classifier.js";
+
+const SPAM_CATEGORIES = [
+  "scam",
+  "phishing",
+  "crypto",
+  "adult",
+  "gambling",
+  "impersonation",
+  "promotion",
+  "other",
+];
+
+const MAX_TEXT_CHARS = 800;
+const MAX_DEFINITION_CHARS = 2000;
+const CATEGORY_LIST = SPAM_CATEGORIES.map((c) => `"${c}"`).join(", ");
+
+const SYSTEM_PROMPT = `You are a spam moderation assistant for a group chat. Your only job is to decide whether a message is spam, judged against the operator's definition of spam for THIS community.
+Respond with JSON only — no markdown, no explanation outside the JSON.
+Schema: {"is_spam":boolean,"category":string|null,"confidence":number,"reason":string}
+Rules:
+- Judge primarily against the operator-provided spam definition. Do not apply your own assumptions about what the community wants.
+- category must be one of: ${CATEGORY_LIST}, or null when is_spam is false.
+- confidence is a number from 0 to 1 (1 = certain).
+- reason is one short sentence (max 20 words). Keep it factual.
+- On-topic discussion, questions, opinions, and a member sharing their own relevant work are NOT spam.
+- Borderline or ambiguous messages should be marked is_spam=false with low confidence.`;
+
+function buildUserPrompt(text, spamDefinition) {
+  const parts = [];
+  if (spamDefinition?.trim()) {
+    parts.push(
+      `WHAT COUNTS AS SPAM IN THIS COMMUNITY:\n${String(spamDefinition).slice(0, MAX_DEFINITION_CHARS)}`,
+    );
+  } else {
+    parts.push(
+      "WHAT COUNTS AS SPAM IN THIS COMMUNITY:\nUse general good judgement — scams, phishing, crypto shilling, adult bots, gambling, impersonation, and unsolicited promotion or advertising.",
+    );
+  }
+  parts.push(`MESSAGE TO EVALUATE:\n${String(text).slice(0, MAX_TEXT_CHARS)}`);
+  return parts.join("\n\n");
+}
+
+export function normalizeEnabledCategories(enabledCategories) {
+  if (!enabledCategories) return null;
+  if (Array.isArray(enabledCategories)) {
+    return enabledCategories.length ? new Set(enabledCategories) : null;
+  }
+  if (typeof enabledCategories === "object") {
+    const on = Object.entries(enabledCategories)
+      .filter(([, v]) => v)
+      .map(([k]) => k);
+    if (Object.keys(enabledCategories).length === 0) return null;
+    return new Set(on);
+  }
+  return null;
+}
+
+export class SpamGuard {
+  constructor(opts = {}) {
+    this.name = 'SpamGuard';
+    this.opts = opts;
+  }
+
+  async evaluate(text, config = {}) {
+    if (!text?.trim()) return null;
+
+    const sensitivity = this.opts.sensitivity ?? config.sensitivity ?? "medium";
+    const enabledSet = normalizeEnabledCategories(this.opts.enabledCategories);
+
+    const raw = await runJsonClassification({
+      tag: "spam-guard",
+      label: "classifySpam",
+      systemPrompt: SYSTEM_PROMPT,
+      userPrompt: buildUserPrompt(text, this.opts.spamDefinition),
+      config
+    });
+
+    if (raw === null) return null; // fail-open
+
+    const envelope = parseVerdictEnvelope(raw, "is_spam");
+    if (!envelope) return null;
+    
+    const { parsed, flagged, confidence, reason } = envelope;
+    const rawCat = parsed.category;
+    const category = SPAM_CATEGORIES.includes(rawCat) ? rawCat : "other";
+
+    if (!flagged || !meetsThreshold(confidence, sensitivity) || (enabledSet && !enabledSet.has(category))) {
+      return { flagged: false, is_spam: false, category: null, confidence, reason };
+    }
+
+    return { flagged: true, is_spam: true, category, confidence, reason };
+  }
+}

package/src/guards/TopicGuard.js

@@ -0,0 +1,82 @@
+import {
+  runJsonClassification,
+  parseVerdictEnvelope,
+  meetsThreshold
+} from "../core/classifier.js";
+
+const MAX_TEXT_CHARS = 800;
+const MAX_EXAMPLE_CHARS = 200;
+const MAX_EXAMPLES = 5;
+
+const SYSTEM_PROMPT = `You are a community moderation assistant. Your only job is to decide whether a message belongs in the operator-defined group topic.
+Respond with JSON only — no markdown, no explanation outside the JSON.
+Schema: {"on_topic":boolean,"confidence":number,"reason":string}
+Rules:
+- Judge strictly against the operator-provided topic description and examples. Do not use the group name or your own assumptions.
+- Brief greetings, thanks, emoji-only messages, and casual banter are on_topic unless they clearly derail discussion.
+- confidence is a number from 0 to 1 (1 = certain).
+- reason is one short sentence (max 20 words). Keep it factual.`;
+
+function buildUserPrompt(text, topic = {}) {
+  const parts = [];
+  if (topic.topic_title) {
+    parts.push(`GROUP TOPIC: ${topic.topic_title}`);
+  }
+  if (topic.topic_description) {
+    parts.push(`DESCRIPTION: ${topic.topic_description}`);
+  }
+
+  const allowed = (topic.allowed_examples ?? []).slice(0, MAX_EXAMPLES);
+  if (allowed.length > 0) {
+    parts.push(
+      `ON-TOPIC EXAMPLES:\n${allowed.map((e) => `- ${String(e).slice(0, MAX_EXAMPLE_CHARS)}`).join("\n")}`,
+    );
+  }
+
+  const offTopic = (topic.off_topic_examples ?? []).slice(0, MAX_EXAMPLES);
+  if (offTopic.length > 0) {
+    parts.push(
+      `OFF-TOPIC EXAMPLES:\n${offTopic.map((e) => `- ${String(e).slice(0, MAX_EXAMPLE_CHARS)}`).join("\n")}`,
+    );
+  }
+
+  parts.push(`MESSAGE TO EVALUATE:\n${String(text).slice(0, MAX_TEXT_CHARS)}`);
+  return parts.join("\n\n");
+}
+
+export class TopicGuard {
+  constructor(opts = {}) {
+    this.name = 'TopicGuard';
+    this.opts = opts;
+  }
+
+  async evaluate(text, config = {}) {
+    if (!text?.trim()) return null;
+
+    const sensitivity = this.opts.sensitivity ?? config.sensitivity ?? "medium";
+
+    const raw = await runJsonClassification({
+      tag: "topic-guard",
+      label: "classifyMessage",
+      systemPrompt: SYSTEM_PROMPT,
+      userPrompt: buildUserPrompt(text, this.opts.topic),
+      config
+    });
+
+    if (raw === null) return null; // fail-open
+
+    const envelope = parseVerdictEnvelope(raw, "on_topic");
+    if (!envelope) return null;
+    
+    const { flagged: onTopic, confidence, reason } = envelope;
+
+    if (onTopic) return { flagged: false, on_topic: true, confidence, reason };
+
+    // Off-topic call only stands if it clears sensitivity bar
+    if (!meetsThreshold(confidence, sensitivity)) {
+      return { flagged: false, on_topic: true, confidence, reason };
+    }
+
+    return { flagged: true, on_topic: false, confidence, reason };
+  }
+}

package/src/index.js

@@ -0,0 +1,6 @@
+export { ModerateText } from './core/moderate.js';
+export { SpamGuard } from './guards/SpamGuard.js';
+export { ConductGuard } from './guards/ConductGuard.js';
+export { TopicGuard } from './guards/TopicGuard.js';
+export { CustomGuard } from './guards/CustomGuard.js';
+export { contentFilter } from './express/contentFilter.js';

package/src/server.js

@@ -0,0 +1,41 @@
+import express from 'express';
+import { SpamGuard } from './guards/SpamGuard.js';
+import { ConductGuard } from './guards/ConductGuard.js';
+import { ModerateText } from './core/moderate.js';
+
+const app = express();
+app.use(express.json());
+
+// Setup default guards for the microservice
+const defaultGuards = [
+  new SpamGuard(),
+  new ConductGuard()
+];
+
+// Standalone REST API endpoint
+app.post('/api/moderate', async (req, res) => {
+  const { text } = req.body;
+  if (!text) {
+    return res.status(400).json({ error: "Missing 'text' in JSON payload" });
+  }
+
+  try {
+    const report = await ModerateText(text, defaultGuards);
+    res.json(report);
+  } catch (err) {
+    console.error("[Server Error]", err);
+    res.status(500).json({ error: "Internal Server Error" });
+  }
+});
+
+const PORT = process.env.PORT || 3000;
+
+// Start server if not imported as a module (for testing)
+const isMain = process.argv[1] && process.argv[1].endsWith('server.js');
+if (isMain || process.env.NODE_ENV === 'development') {
+  app.listen(PORT, () => {
+    console.log(`open-safety-guard Microservice running on port ${PORT}`);
+  });
+}
+
+export default app;

package/test/core.test.js

@@ -0,0 +1,39 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import { ModerateText } from '../src/core/moderate.js';
+import { CustomGuard } from '../src/guards/CustomGuard.js';
+
+test('ModerateText - Fail-open behavior when API keys are missing', async () => {
+  const dummyGuard = new CustomGuard({
+    name: "TestGuard",
+    systemPrompt: "Dummy prompt",
+    flagField: "is_bad"
+  });
+
+  // Call without any environment API keys
+  // It should quickly fail-open and not crash
+  const report = await ModerateText("Hello world", [dummyGuard], { apiKey: '' });
+
+  assert.strictEqual(report.flagged, false);
+});
+
+test('ModerateText - Rejects invalid guards', async () => {
+  const invalidGuard = { name: "BadGuard" }; // missing evaluate()
+  
+  await assert.rejects(
+    ModerateText("Hello", [invalidGuard]),
+    /Invalid guard: BadGuard must implement an evaluate\(\) method./
+  );
+});
+
+test('CustomGuard - Returns correct fail-open on invalid response', async () => {
+  const guard = new CustomGuard({
+    name: "TestGuard",
+    systemPrompt: "Dummy",
+    flagField: "is_bad"
+  });
+  
+  // Since we don't have a valid API key, evaluate should fail-open
+  const result = await guard.evaluate("Test", { apiKey: '' });
+  assert.strictEqual(result, null);
+});

package/test/express.test.js

@@ -0,0 +1,49 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import request from 'supertest';
+import express from 'express';
+import { contentFilter } from '../src/express/contentFilter.js';
+
+test('Express Middleware - Passes text when no policy violations occur', async () => {
+  const app = express();
+  app.use(express.json());
+  
+  // A dummy guard that fails-open or always allows
+  const mockGuard = {
+    name: "MockGuard",
+    evaluate: async () => ({ flagged: false, reason: "" })
+  };
+
+  app.post('/test', contentFilter({ guards: [mockGuard] }), (req, res) => {
+    res.status(200).json({ success: true });
+  });
+
+  const response = await request(app)
+    .post('/test')
+    .send({ text: "Hello world" })
+    .expect(200);
+
+  assert.strictEqual(response.body.success, true);
+});
+
+test('Express Middleware - Blocks text when policy violated', async () => {
+  const app = express();
+  app.use(express.json());
+  
+  const mockGuard = {
+    name: "MockGuard",
+    evaluate: async () => ({ flagged: true, reason: "Mock failure" })
+  };
+
+  app.post('/test', contentFilter({ guards: [mockGuard] }), (req, res) => {
+    res.status(200).json({ success: true });
+  });
+
+  const response = await request(app)
+    .post('/test')
+    .send({ text: "Bad content" })
+    .expect(403);
+
+  assert.strictEqual(response.body.error, "Content violated safety policy");
+  assert.deepStrictEqual(response.body.reasons, ["[MockGuard] Mock failure"]);
+});