@mytechtoday/augment-extensions 0.1.0 → 0.1.1

package/augment-extensions/domain-rules/security/rules/encryption.md

@@ -0,0 +1,208 @@
+# Encryption and Data Protection
+
+Best practices for encrypting and protecting sensitive data.
+
+## Data at Rest Encryption
+
+### Symmetric Encryption (AES-256-GCM)
+
+```typescript
+import crypto from 'crypto';
+
+// Encrypt data
+const encrypt = (data: string, key: Buffer): { encrypted: string; iv: string; authTag: string } => {
+  const iv = crypto.randomBytes(16);
+  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+  
+  let encrypted = cipher.update(data, 'utf8', 'hex');
+  encrypted += cipher.final('hex');
+  
+  return {
+    encrypted,
+    iv: iv.toString('hex'),
+    authTag: cipher.getAuthTag().toString('hex')
+  };
+};
+
+// Decrypt data
+const decrypt = (encrypted: string, key: Buffer, iv: string, authTag: string): string => {
+  const decipher = crypto.createDecipheriv('aes-256-gcm', key, Buffer.from(iv, 'hex'));
+  decipher.setAuthTag(Buffer.from(authTag, 'hex'));
+  
+  let decrypted = decipher.update(encrypted, 'hex', 'utf8');
+  decrypted += decipher.final('utf8');
+  
+  return decrypted;
+};
+
+// Generate encryption key
+const key = crypto.randomBytes(32); // 256 bits
+// Store key securely (e.g., AWS KMS, Azure Key Vault, environment variable)
+```
+
+### Database Encryption
+
+```typescript
+// Good - Encrypt sensitive fields
+const encryptedData = encrypt(user.ssn, encryptionKey);
+
+await db.users.create({
+  email: user.email,
+  ssn: encryptedData.encrypted,
+  ssnIv: encryptedData.iv,
+  ssnAuthTag: encryptedData.authTag
+});
+
+// Decrypt when needed
+const user = await db.users.findOne(userId);
+const ssn = decrypt(user.ssn, encryptionKey, user.ssnIv, user.ssnAuthTag);
+```
+
+## Data in Transit Encryption
+
+### HTTPS/TLS
+
+```typescript
+// Good - Force HTTPS
+app.use((req, res, next) => {
+  if (!req.secure && process.env.NODE_ENV === 'production') {
+    return res.redirect(301, `https://${req.headers.host}${req.url}`);
+  }
+  next();
+});
+
+// Good - HSTS header
+app.use((req, res, next) => {
+  res.setHeader('Strict-Transport-Security', 'max-age=31536000; includeSubDomains; preload');
+  next();
+});
+
+// Good - TLS configuration
+import https from 'https';
+import fs from 'fs';
+
+const options = {
+  key: fs.readFileSync('private-key.pem'),
+  cert: fs.readFileSync('certificate.pem'),
+  minVersion: 'TLSv1.2',  // Minimum TLS 1.2
+  ciphers: 'ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384'
+};
+
+https.createServer(options, app).listen(443);
+```
+
+## Key Management
+
+### Environment Variables
+
+```bash
+# .env (never commit to git)
+ENCRYPTION_KEY=hex_encoded_32_byte_key
+JWT_SECRET=strong_random_secret
+DATABASE_PASSWORD=strong_password
+
+# .gitignore
+.env
+.env.local
+```
+
+### Key Rotation
+
+```typescript
+// Support multiple encryption keys for rotation
+const ENCRYPTION_KEYS = {
+  current: process.env.ENCRYPTION_KEY_V2,
+  previous: process.env.ENCRYPTION_KEY_V1
+};
+
+// Encrypt with current key
+const encrypted = encrypt(data, Buffer.from(ENCRYPTION_KEYS.current, 'hex'));
+
+// Decrypt with appropriate key version
+const decrypt = (encrypted: string, keyVersion: string, iv: string, authTag: string): string => {
+  const key = ENCRYPTION_KEYS[keyVersion];
+  // ... decrypt logic
+};
+
+// Re-encrypt old data with new key
+const migrateEncryption = async () => {
+  const users = await db.users.findMany({ keyVersion: 'previous' });
+  
+  for (const user of users) {
+    const decrypted = decrypt(user.ssn, 'previous', user.ssnIv, user.ssnAuthTag);
+    const reencrypted = encrypt(decrypted, Buffer.from(ENCRYPTION_KEYS.current, 'hex'));
+    
+    await db.users.update(user.id, {
+      ssn: reencrypted.encrypted,
+      ssnIv: reencrypted.iv,
+      ssnAuthTag: reencrypted.authTag,
+      keyVersion: 'current'
+    });
+  }
+};
+```
+
+## Hashing
+
+### One-Way Hashing
+
+```typescript
+import crypto from 'crypto';
+
+// Good - SHA-256 for non-password data
+const hash = crypto.createHash('sha256').update(data).digest('hex');
+
+// Good - HMAC for message authentication
+const hmac = crypto.createHmac('sha256', secret).update(data).digest('hex');
+
+// Verify HMAC
+const isValid = crypto.timingSafeEqual(
+  Buffer.from(receivedHmac, 'hex'),
+  Buffer.from(expectedHmac, 'hex')
+);
+```
+
+## Secure Random Generation
+
+```typescript
+// Good - Cryptographically secure random
+const token = crypto.randomBytes(32).toString('hex');
+const uuid = crypto.randomUUID();
+
+// Bad - Not cryptographically secure
+const token = Math.random().toString(36);  // ❌ Don't use for security
+```
+
+## Data Masking
+
+```typescript
+// Mask sensitive data in logs
+const maskEmail = (email: string): string => {
+  const [local, domain] = email.split('@');
+  return `${local.slice(0, 2)}***@${domain}`;
+};
+
+const maskCreditCard = (card: string): string => {
+  return `****-****-****-${card.slice(-4)}`;
+};
+
+// Log with masked data
+logger.info('User registered', {
+  email: maskEmail(user.email),
+  ip: req.ip
+});
+```
+
+## Best Practices
+
+1. **Use AES-256-GCM** - For symmetric encryption
+2. **Always use HTTPS** - Encrypt data in transit
+3. **Secure key storage** - Use key management services
+4. **Rotate keys** - Periodically change encryption keys
+5. **Hash passwords** - Use bcrypt/Argon2, not encryption
+6. **Use crypto.randomBytes** - For secure random generation
+7. **Encrypt at rest** - Sensitive database fields
+8. **Mask in logs** - Don't log sensitive data
+9. **Use HSTS** - Force HTTPS
+10. **TLS 1.2+** - Minimum TLS version
+

package/augment-extensions/domain-rules/security/rules/input-validation.md

@@ -0,0 +1,294 @@
+# Input Validation and Sanitization
+
+Best practices for validating and sanitizing user input.
+
+## Validation Libraries
+
+### Zod (TypeScript)
+
+```typescript
+import { z } from 'zod';
+
+// Define schema
+const userSchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(12).max(100),
+  age: z.number().int().min(18).max(120),
+  role: z.enum(['admin', 'user', 'guest']),
+  website: z.string().url().optional()
+});
+
+// Validate input
+app.post('/users', async (req, res) => {
+  try {
+    const validatedData = userSchema.parse(req.body);
+    // Use validatedData (type-safe)
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      return res.status(422).json({
+        error: 'Validation failed',
+        details: error.errors
+      });
+    }
+  }
+});
+```
+
+### Joi (JavaScript)
+
+```javascript
+const Joi = require('joi');
+
+const schema = Joi.object({
+  email: Joi.string().email().required(),
+  password: Joi.string().min(12).max(100).required(),
+  age: Joi.number().integer().min(18).max(120),
+  tags: Joi.array().items(Joi.string()).max(10)
+});
+
+const { error, value } = schema.validate(req.body);
+if (error) {
+  return res.status(422).json({ error: error.details });
+}
+```
+
+## SQL Injection Prevention
+
+```typescript
+// Bad - SQL injection vulnerability
+const query = `SELECT * FROM users WHERE email = '${req.body.email}'`;  // ❌
+
+// Good - Parameterized query
+const query = 'SELECT * FROM users WHERE email = $1';
+const result = await db.query(query, [req.body.email]);
+
+// Good - ORM (Prisma)
+const user = await prisma.user.findUnique({
+  where: { email: req.body.email }
+});
+
+// Good - Query builder (Knex)
+const users = await knex('users')
+  .where('email', req.body.email)
+  .select('*');
+```
+
+## NoSQL Injection Prevention
+
+```typescript
+// Bad - NoSQL injection
+const user = await db.users.findOne({
+  email: req.body.email,  // Could be: { $ne: null }
+  password: req.body.password
+});
+
+// Good - Validate input type
+if (typeof req.body.email !== 'string' || typeof req.body.password !== 'string') {
+  return res.status(400).json({ error: 'Invalid input' });
+}
+
+const user = await db.users.findOne({
+  email: req.body.email,
+  password: req.body.password
+});
+
+// Good - Use schema validation
+const loginSchema = z.object({
+  email: z.string().email(),
+  password: z.string()
+});
+
+const { email, password } = loginSchema.parse(req.body);
+```
+
+## XSS Prevention
+
+```typescript
+// Bad - Rendering user input directly
+res.send(`<h1>Welcome ${req.query.name}</h1>`);  // ❌ XSS vulnerability
+
+// Good - Use template engine with auto-escaping
+res.render('welcome', { name: req.query.name });  // Handlebars, EJS, etc.
+
+// Good - Sanitize HTML
+import DOMPurify from 'isomorphic-dompurify';
+
+const clean = DOMPurify.sanitize(req.body.html);
+
+// Good - Content Security Policy
+app.use((req, res, next) => {
+  res.setHeader(
+    'Content-Security-Policy',
+    "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'"
+  );
+  next();
+});
+```
+
+## Command Injection Prevention
+
+```typescript
+// Bad - Command injection
+const { exec } = require('child_process');
+exec(`ping ${req.query.host}`);  // ❌ Vulnerable
+
+// Good - Validate input
+const host = req.query.host;
+if (!/^[a-zA-Z0-9.-]+$/.test(host)) {
+  return res.status(400).json({ error: 'Invalid host' });
+}
+
+// Better - Use safe library
+import { ping } from 'ping';
+const result = await ping.promise.probe(req.query.host);
+
+// Good - Use execFile with array
+import { execFile } from 'child_process';
+execFile('ping', ['-c', '4', host], (error, stdout) => {
+  // ...
+});
+```
+
+## Path Traversal Prevention
+
+```typescript
+// Bad - Path traversal vulnerability
+const filePath = path.join(__dirname, 'uploads', req.query.file);  // ❌
+res.sendFile(filePath);
+
+// Good - Validate filename
+import path from 'path';
+
+const filename = path.basename(req.query.file);  // Remove directory components
+const filePath = path.join(__dirname, 'uploads', filename);
+
+// Ensure file is within uploads directory
+const realPath = fs.realpathSync(filePath);
+const uploadsPath = fs.realpathSync(path.join(__dirname, 'uploads'));
+
+if (!realPath.startsWith(uploadsPath)) {
+  return res.status(400).json({ error: 'Invalid file path' });
+}
+
+res.sendFile(realPath);
+```
+
+## Email Validation
+
+```typescript
+// Good - Email validation
+const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+if (!emailRegex.test(email)) {
+  return res.status(400).json({ error: 'Invalid email' });
+}
+
+// Better - Use validation library
+import { z } from 'zod';
+const email = z.string().email().parse(req.body.email);
+
+// Best - Verify email ownership
+const verificationToken = crypto.randomBytes(32).toString('hex');
+await sendVerificationEmail(email, verificationToken);
+```
+
+## URL Validation
+
+```typescript
+// Good - URL validation
+const validateUrl = (url: string): boolean => {
+  try {
+    const parsed = new URL(url);
+    return ['http:', 'https:'].includes(parsed.protocol);
+  } catch {
+    return false;
+  }
+};
+
+// Good - Whitelist domains
+const allowedDomains = ['example.com', 'api.example.com'];
+
+const url = new URL(req.body.url);
+if (!allowedDomains.includes(url.hostname)) {
+  return res.status(400).json({ error: 'Domain not allowed' });
+}
+```
+
+## File Upload Validation
+
+```typescript
+import multer from 'multer';
+import path from 'path';
+
+// Good - Validate file type and size
+const upload = multer({
+  storage: multer.diskStorage({
+    destination: 'uploads/',
+    filename: (req, file, cb) => {
+      const uniqueSuffix = Date.now() + '-' + crypto.randomBytes(6).toString('hex');
+      cb(null, uniqueSuffix + path.extname(file.originalname));
+    }
+  }),
+  limits: {
+    fileSize: 5 * 1024 * 1024  // 5MB
+  },
+  fileFilter: (req, file, cb) => {
+    const allowedTypes = ['image/jpeg', 'image/png', 'image/gif'];
+    
+    if (!allowedTypes.includes(file.mimetype)) {
+      return cb(new Error('Invalid file type'));
+    }
+    
+    cb(null, true);
+  }
+});
+
+// Verify file content (not just extension)
+import fileType from 'file-type';
+
+const type = await fileType.fromFile(filePath);
+if (!type || !['image/jpeg', 'image/png'].includes(type.mime)) {
+  fs.unlinkSync(filePath);
+  return res.status(400).json({ error: 'Invalid file type' });
+}
+```
+
+## Integer Validation
+
+```typescript
+// Good - Validate integers
+const validateInteger = (value: any, min?: number, max?: number): number => {
+  const num = parseInt(value, 10);
+  
+  if (isNaN(num) || !Number.isInteger(num)) {
+    throw new Error('Must be an integer');
+  }
+  
+  if (min !== undefined && num < min) {
+    throw new Error(`Must be at least ${min}`);
+  }
+  
+  if (max !== undefined && num > max) {
+    throw new Error(`Must be at most ${max}`);
+  }
+  
+  return num;
+};
+
+// Usage
+const age = validateInteger(req.body.age, 18, 120);
+```
+
+## Best Practices
+
+1. **Validate all input** - Never trust user input
+2. **Use validation libraries** - Zod, Joi, etc.
+3. **Whitelist, don't blacklist** - Define what's allowed
+4. **Parameterized queries** - Prevent SQL injection
+5. **Type checking** - Prevent NoSQL injection
+6. **Sanitize HTML** - Use DOMPurify
+7. **Validate file uploads** - Type, size, content
+8. **Validate URLs** - Check protocol and domain
+9. **Prevent path traversal** - Use path.basename
+10. **Fail securely** - Reject invalid input
+