# @bloomneo/appkit - Security Module ๐
[](https://www.npmjs.com/package/@bloomneo/appkit)
[](https://opensource.org/licenses/MIT)
> Ultra-simple enterprise security that just works
**One function** returns a security object with enterprise-grade protection.
Zero configuration needed, production-ready by default, with built-in CSRF
protection, rate limiting, input sanitization, and AES-256-GCM encryption.
> **See also:** [AGENTS.md](../../AGENTS.md) (agent rules) ยท [llms.txt](../../llms.txt) (full API reference) ยท [examples/security.ts](../../examples/security.ts) ยท cookbook: [api-key-service.ts](../../cookbook/api-key-service.ts)
## ๐ Why Choose This?
- **โก One Function** - Just `securityClass.get()`, everything else is automatic
- **๐ Enterprise Security** - Production-grade CSRF, rate limiting, encryption
- **๐ง Zero Configuration** - Smart defaults with environment variable override
- **๐ Environment-First** - Auto-detects from `BLOOM_SECURITY_*` variables
- **๐ก๏ธ Complete Protection** - CSRF, XSS, rate limiting, data encryption
- **๐ฏ Framework Ready** - Express middleware with proper headers
- **๐ค AI-Ready** - Optimized for LLM code generation
## ๐ฆ Installation
```bash
npm install @bloomneo/appkit
```
## ๐โโ๏ธ Quick Start (30 seconds)
### 1. Environment Variables
```bash
# Essential security configuration
BLOOM_SECURITY_CSRF_SECRET=your-csrf-secret-key-2024-minimum-32-chars
BLOOM_SECURITY_ENCRYPTION_KEY=64-char-hex-key-for-aes256-encryption
```
### 2. Basic Setup
```typescript
import express from 'express';
import session from 'express-session';
import { securityClass } from '@bloomneo/appkit/security';
const app = express();
const security = securityClass.get();
// Session middleware (required for CSRF)
app.use(session({ secret: process.env.SESSION_SECRET }));
// Security middleware
app.use(security.forms()); // CSRF protection
app.use('/api', security.requests()); // Rate limiting
// Secure route
app.post('/profile', (req, res) => {
const safeName = security.input(req.body.name);
const safeBio = security.html(req.body.bio, { allowedTags: ['p', 'b'] });
const encryptedSSN = security.encrypt(req.body.ssn);
// Save to database...
res.json({ success: true });
});
```
## ๐ง Mental Model
### Security Layer Architecture
```
Request โ CSRF Check โ Rate Limit โ Input Sanitization โ Business Logic
```
### Protection Types
```typescript
// Form Protection (CSRF)
security.forms(); // Prevents cross-site request forgery
// Traffic Protection (Rate Limiting)
security.requests(); // Prevents abuse and brute force
// โ ๏ธ In-memory only โ NOT distributed across replicas. If your app runs
// behind a load balancer with multiple processes/pods, this counts requests
// per process. For multi-process rate limiting, put a shared rate limiter in
// front of your app (nginx limit_req, Cloudflare Rate Limiting, envoy). See
// "Rate limiting โ in-memory caveat" below.
// Input Protection (XSS Prevention)
security.input(text); // Cleans user text input
security.html(content); // Sanitizes HTML content
// Data Protection (Encryption)
security.encrypt(data); // AES-256-GCM encryption
security.decrypt(data); // Authenticated decryption
```
## ๐ค LLM Quick Reference - Copy These Patterns
### **Basic Security Setup (Copy Exactly)**
```typescript
// โ
CORRECT - Complete security setup
import { securityClass } from '@bloomneo/appkit/security';
const security = securityClass.get();
// Required order
app.use(session({ secret: process.env.SESSION_SECRET }));
app.use(security.forms()); // CSRF protection
app.use('/api', security.requests()); // Rate limiting
// Form with CSRF token
app.get('/form', (req, res) => {
const csrfToken = req.csrfToken();
res.render('form', { csrfToken });
});
// Secure input processing
app.post('/form', (req, res) => {
const clean = security.input(req.body.data);
const safeHtml = security.html(req.body.content, { allowedTags: ['p'] });
const encrypted = security.encrypt(req.body.sensitive);
// Process...
});
```
### **Different Rate Limits (Copy These)**
```typescript
// โ
CORRECT - Endpoint-specific limits
app.use('/api', security.requests(100, 900000)); // 100/15min
app.use('/auth', security.requests(5, 3600000)); // 5/hour
app.post('/upload', security.requests(10), handler); // 10/15min
```
### **Input Sanitization (Copy These)**
```typescript
// โ
CORRECT - Clean all user input
const safeName = security.input(req.body.name, { maxLength: 50 });
const safeEmail = security.input(req.body.email?.toLowerCase());
const safeContent = security.html(req.body.content, {
allowedTags: ['p', 'b', 'i', 'a'],
});
const safeDisplay = security.escape(userText);
```
### **Encryption Patterns (Copy These)**
```typescript
// โ
CORRECT - Encrypt sensitive data
const encryptedSSN = security.encrypt(user.ssn);
const encryptedPhone = security.encrypt(user.phone);
// โ
CORRECT - Decrypt for authorized access
const originalSSN = security.decrypt(encryptedSSN);
const originalPhone = security.decrypt(encryptedPhone);
// โ
CORRECT - Generate keys
const newKey = security.generateKey(); // For production use
```
## โ ๏ธ Common LLM Mistakes - Avoid These
### **Wrong Middleware Order**
```typescript
// โ WRONG - CSRF without sessions
app.use(security.forms());
app.use(session(config)); // Too late!
// โ
CORRECT - Sessions first
app.use(session(config));
app.use(security.forms());
```
### **Raw Input Storage**
```typescript
// โ WRONG - Store raw user input
await db.save({ content: req.body.content });
// โ
CORRECT - Clean first
const clean = security.input(req.body.content);
await db.save({ content: clean });
```
### **Missing CSRF Tokens**
```typescript
// โ WRONG - Form without CSRF
res.send('