Koma

A prompt-injection firewall for Node.js.

Stop malicious prompts before they reach your LLM, tools, or RAG pipeline.

npm install koma-gate

<p align="center"> <img src="logo/logobanner.png" alt="Koma" width="600" /> </p>

<p align="center"> <img alt="License" src="https://img.shields.io/badge/license-MIT-green?style=flat-square" /> <img alt="CI" src="https://github.com/swnotmetal/Project-Koma/actions/workflows/ci.yml/badge.svg" /> <a href="https://www.npmjs.com/package/koma-gate"><img alt="koma-gate" src="https://img.shields.io/npm/v/koma-gate?label=koma-gate&color=3178c6&style=flat-square" /></a> <a href="https://www.npmjs.com/package/koma-scout"><img alt="koma-scout" src="https://img.shields.io/npm/v/koma-scout?label=koma-scout&color=3178c6&style=flat-square" /></a> <a href="https://www.npmjs.com/package/koma-core"><img alt="koma-core" src="https://img.shields.io/npm/v/koma-core?label=koma-core&color=3178c6&style=flat-square" /></a> <br /> <img alt="benchmark" src="https://img.shields.io/badge/benchmark-98.8%25_recall_0%25_FPR-6e3abe?style=flat-square" /> <img alt="total downloads" src="https://img.shields.io/npm/dt/koma-gate?label=downloads&color=blue&style=flat-square" /> <img alt="visitors" src="https://hits.dwyl.com/swnotmetal/Project-Koma.svg?style=flat-square" /> <a href="https://koma-demo.swbuilds.workers.dev"><img alt="live demo" src="https://img.shields.io/badge/live_demo-try_it_now-C25E38?style=flat-square" /></a> </p>

<p align="center"> <a href="./README.zh-CN.md">中文版</a> </p>

<p align="center"> <strong>▶ <a href="https://koma-demo.swbuilds.workers.dev">Try the live demo</a></strong> — Gate, Scout & Core in one page, no signup. </p>

---

What It Stops

Your app	Attack	Fix	Install
AI chatbot	Prompt injection / jailbreak	Semantic filter blocks attacks before the model	koma-gate
Voice AI	Audio abuse / flooding	Validation + rate limiting + geo	koma-scout
RAG / search	Data enumeration / scraping	Split index from content, token-gate retrieval	koma-core

Different attacks cross different boundaries. Koma provides a small primitive for each one.

---

What Koma Is — and Isn't

Is: composable security primitives · defense-in-depth · usable independently · sits outside the model's authority

Isn't: a model · an agent framework · a replacement for authorization · a magic prompt-injection detector · a complete security boundary by itself

---

Benchmarks

I threw 1,769 real prompt-injection attacks at Koma Gate in fail-closed mode, using real providers — not mock adapters.

Provider	Recall	Precision	False Positives
DeepSeek (deepseek-chat)	98.8%	100%	0
Google (gemini-2.5-flash)	96.2%	100%	0

Chinese attack set: 100% recall · 100% precision · 0% FPR across 8 categories.

Can you break it? Open an issue with an attack Koma misses. → Full methodology

---

Quick Start

import { createGeneralKnowledgeGuard } from 'koma-gate';

const guard = createGeneralKnowledgeGuard({
  llm: { apiKey: process.env.GEMINI_API_KEY },
});

app.post('/api/chat', guard.middleware(), async (req, res) => {
  // Only in-scope requests reach your model
  res.json({ reply: await chat(req.body.message) });
});

git clone https://github.com/swnotmetal/Project-Koma
cd Project-Koma && node demo/server.js
curl http://localhost:8080/self-test

---

Three Defenses

koma-gate — Prompt injection firewall. LLM-based scope classifier that blocks jailbreaks, off-topic requests, and instruction overrides. Supports OpenAI, Anthropic, Google, DeepSeek, and local Ollama models. README →

<img src="show-koma.gif" alt="Koma Gate blocking a prompt injection in real time" width="100%" />

koma-scout — Perimeter protection. Rate limiting, audio upload validation, geo allowlisting. Cheap checks before expensive AI work. README →

<img src="logo/scout-diagram.svg" alt="Koma Scout perimeter checks" width="480" />

koma-core — Protected RAG storage. Public search index, private content, opaque HKDF-derived tokens. Discovery is not authorization. README →

<img src="logo/core-diagram.svg" alt="Koma Core split-store" width="480" />

Each package works standalone. Stack them: Gate filters → Scout throttles → Core stores.

MCP servers — expose Koma to AI agents directly:

• koma-gate-mcp — classify_input tool for prompt-injection checks. README →
• koma-core-mcp — search_docs + retrieve_doc for protected RAG retrieval. README →

{
  "mcpServers": {
    "koma-gate": { "command": "npx", "args": ["-y", "koma-gate-mcp"] },
    "koma-core": { "command": "npx", "args": ["-y", "koma-core-mcp"] }
  }
}

---

Using an AI coding agent?

Tell it:

"Add Koma to protect this AI endpoint. Use koma-gate for prompt injection, koma-scout for perimeter abuse, and koma-core for protected RAG retrieval. Each works standalone."

Koma is designed for both human and agent discoverability — including two MCP servers. See llms.txt.

---

Trust & Safety

• Zero runtime dependencies. No supply-chain surface.
• No code execution. Classifies, rate-limits, stores — never executes AI output.
• Fail-closed by default. A broken guard blocks, not passes.
• CodeQL on every push. Targets OWASP LLM01.
• MIT licensed.

→ Security policy · Known limitations · Comparison with alternatives · Contributing

---

Koma comes from Komainu ("狛犬"), the stone guardian lions of Japanese Shinto shrines. Three defense layers. Each standalone. Patterns distilled from production, not papers.

License