Koma

A prompt-injection firewall for Node.js.

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

npm install koma-gate

中文版

Security primitives distilled from a real AI application. — How Koma was built

What It Stops

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.

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 →

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

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

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