@mytechtoday/augment-extensions 0.1.0 → 0.1.2

package/augment-extensions/domain-rules/api-design/rules/versioning.md

@@ -0,0 +1,268 @@
+# API Versioning
+
+Strategies for versioning APIs to maintain backward compatibility.
+
+## Versioning Strategies
+
+### URL Versioning (Recommended for REST)
+
+Include version in the URL path.
+
+```
+# Good - Version in URL
+GET /api/v1/users
+GET /api/v2/users
+
+# Advantages:
+- Clear and explicit
+- Easy to route
+- Easy to cache
+- Easy to test different versions
+
+# Disadvantages:
+- URL changes between versions
+- Can lead to code duplication
+```
+
+### Header Versioning
+
+Use custom header for version.
+
+```
+# Request
+GET /api/users
+Accept-Version: v1
+
+# Or using Accept header
+GET /api/users
+Accept: application/vnd.myapi.v1+json
+
+# Advantages:
+- Clean URLs
+- Follows REST principles
+
+# Disadvantages:
+- Less visible
+- Harder to test in browser
+- Caching complexity
+```
+
+### Query Parameter Versioning
+
+Include version as query parameter.
+
+```
+# Request
+GET /api/users?version=1
+
+# Advantages:
+- Simple to implement
+- Easy to test
+
+# Disadvantages:
+- Pollutes query parameters
+- Less clean than URL versioning
+```
+
+## Semantic Versioning
+
+Use semantic versioning for API versions.
+
+```
+# Format: MAJOR.MINOR.PATCH
+
+v1.0.0 - Initial release
+v1.1.0 - Added new endpoints (backward compatible)
+v1.1.1 - Bug fixes (backward compatible)
+v2.0.0 - Breaking changes (not backward compatible)
+
+# In URLs, typically use only MAJOR version
+/api/v1/users  (represents v1.x.x)
+/api/v2/users  (represents v2.x.x)
+```
+
+## Breaking vs Non-Breaking Changes
+
+### Non-Breaking Changes (Safe)
+
+```
+✅ Adding new endpoints
+✅ Adding new optional fields to requests
+✅ Adding new fields to responses
+✅ Adding new query parameters (optional)
+✅ Making required fields optional
+✅ Relaxing validation rules
+✅ Adding new enum values (if clients handle unknown values)
+
+# Example: Adding optional field
+# v1.0.0
+POST /api/v1/users
+{
+  "name": "John",
+  "email": "john@example.com"
+}
+
+# v1.1.0 (backward compatible)
+POST /api/v1/users
+{
+  "name": "John",
+  "email": "john@example.com",
+  "phone": "555-1234"  # New optional field
+}
+```
+
+### Breaking Changes (Require New Version)
+
+```
+❌ Removing endpoints
+❌ Removing fields from responses
+❌ Removing query parameters
+❌ Renaming fields
+❌ Changing field types
+❌ Making optional fields required
+❌ Changing URL structure
+❌ Changing authentication method
+❌ Stricter validation rules
+
+# Example: Breaking change requires v2
+# v1
+GET /api/v1/users/123
+{
+  "id": "123",
+  "name": "John Doe"
+}
+
+# v2 (breaking: renamed field)
+GET /api/v2/users/123
+{
+  "id": "123",
+  "fullName": "John Doe"  # Renamed from 'name'
+}
+```
+
+## Deprecation Strategy
+
+Gracefully deprecate old versions.
+
+```
+# 1. Announce deprecation
+GET /api/v1/users
+Response Headers:
+  Deprecation: true
+  Sunset: Sat, 31 Dec 2024 23:59:59 GMT
+  Link: </api/v2/users>; rel="successor-version"
+
+# 2. Response body warning
+{
+  "data": [...],
+  "warnings": [
+    {
+      "code": "DEPRECATED_VERSION",
+      "message": "API v1 is deprecated. Please migrate to v2 by Dec 31, 2024.",
+      "link": "https://docs.example.com/migration-guide"
+    }
+  ]
+}
+
+# 3. Deprecation timeline
+Month 0:  Announce v2, v1 still supported
+Month 3:  Add deprecation warnings to v1
+Month 6:  v1 in maintenance mode (bug fixes only)
+Month 12: v1 sunset (no longer available)
+```
+
+## Version Migration
+
+Provide migration paths.
+
+```
+# Good - Support both versions during transition
+# v1 endpoint (deprecated)
+GET /api/v1/users/123
+{
+  "id": "123",
+  "name": "John Doe",
+  "email": "john@example.com"
+}
+
+# v2 endpoint (current)
+GET /api/v2/users/123
+{
+  "id": "123",
+  "firstName": "John",
+  "lastName": "Doe",
+  "email": "john@example.com",
+  "profile": {
+    "avatar": "https://..."
+  }
+}
+
+# Provide migration guide
+# docs/migration/v1-to-v2.md
+- 'name' field split into 'firstName' and 'lastName'
+- Added 'profile' object with nested fields
+- All dates now in ISO 8601 format
+```
+
+## GraphQL Versioning
+
+GraphQL uses schema evolution instead of versioning.
+
+```graphql
+# Good - Deprecate fields, don't remove
+type User {
+  id: ID!
+  name: String! @deprecated(reason: "Use firstName and lastName instead")
+  firstName: String!
+  lastName: String!
+}
+
+# Good - Add new fields
+type User {
+  id: ID!
+  email: String!
+  phone: String  # New optional field
+}
+
+# Bad - Breaking change (don't do this)
+type User {
+  id: ID!
+  # Removed 'name' field without deprecation period
+  firstName: String!
+  lastName: String!
+}
+```
+
+## Best Practices
+
+1. **Use URL versioning** - For REST APIs (most explicit)
+2. **Version only on breaking changes** - Use semantic versioning
+3. **Support multiple versions** - During transition period
+4. **Deprecate gracefully** - Give clients time to migrate
+5. **Document changes** - Maintain changelog
+6. **Provide migration guides** - Help clients upgrade
+7. **Use sunset headers** - Communicate deprecation timeline
+8. **Test all versions** - Ensure backward compatibility
+9. **Monitor usage** - Track version adoption
+10. **Plan deprecation** - Have clear timeline
+11. **Avoid micro-versions** - Don't version every change
+12. **Use feature flags** - For gradual rollouts
+13. **Keep v1 simple** - Don't over-engineer first version
+14. **Version documentation** - Docs for each version
+15. **Automate testing** - Test all supported versions
+
+## Version Support Policy
+
+```
+# Example policy
+- Current version (v3): Full support
+- Previous version (v2): Maintenance mode (12 months)
+- Older versions (v1): Deprecated (6 months notice before sunset)
+
+# Timeline example
+2024-01-01: v3 released, v2 enters maintenance, v1 deprecated
+2024-07-01: v1 sunset (removed)
+2025-01-01: v4 released, v3 enters maintenance, v2 deprecated
+2025-07-01: v2 sunset (removed)
+```
+

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

@@ -0,0 +1,41 @@
+# Security Guidelines
+
+Comprehensive security guidelines for building secure applications.
+
+## Overview
+
+This module provides detailed security guidelines based on OWASP Top 10 and industry best practices, covering authentication, encryption, input validation, and common vulnerabilities.
+
+## Key Benefits
+
+- **OWASP Coverage**: Address OWASP Top 10 vulnerabilities
+- **Secure Authentication**: Proper auth implementation
+- **Data Protection**: Encryption and data security
+- **Input Validation**: Prevent injection attacks
+- **Best Practices**: Industry-standard security patterns
+
+## Installation
+
+```bash
+augx link domain-rules/security
+```
+
+## Contents
+
+### Rules
+
+- **owasp-top-10.md** - OWASP Top 10 vulnerabilities and mitigations
+- **authentication-security.md** - Secure authentication patterns
+- **encryption.md** - Encryption and data protection
+- **input-validation.md** - Input validation and sanitization
+- **secure-coding.md** - Secure coding practices
+- **web-security.md** - Web-specific security (XSS, CSRF, etc.)
+
+## Character Count
+
+~38,000 characters
+
+## Version
+
+1.0.0
+

package/augment-extensions/domain-rules/security/module.json

@@ -0,0 +1,28 @@
+{
+  "name": "security",
+  "version": "1.0.0",
+  "displayName": "Security Guidelines",
+  "description": "Comprehensive security guidelines including OWASP best practices, authentication, encryption, and secure coding",
+  "type": "domain-rules",
+  "author": "Augment Extensions",
+  "license": "MIT",
+  "augment": {
+    "characterCount": 38000,
+    "priority": "high",
+    "category": "domain-rules"
+  },
+  "installation": {
+    "required": false,
+    "dependencies": []
+  },
+  "tags": [
+    "security",
+    "owasp",
+    "authentication",
+    "encryption",
+    "xss",
+    "csrf",
+    "sql-injection"
+  ]
+}
+

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

@@ -0,0 +1,361 @@
+# Authentication Security
+
+Best practices for secure authentication implementation.
+
+## Password Security
+
+### Password Hashing
+
+Always hash passwords with strong algorithms.
+
+```typescript
+import bcrypt from 'bcrypt';
+import argon2 from 'argon2';
+
+// Good - bcrypt (recommended)
+const saltRounds = 10;
+const hashedPassword = await bcrypt.hash(password, saltRounds);
+
+// Good - Argon2 (more secure, slower)
+const hashedPassword = await argon2.hash(password);
+
+// Verify password
+const isValid = await bcrypt.compare(inputPassword, hashedPassword);
+const isValid = await argon2.verify(hashedPassword, inputPassword);
+
+// Bad - Weak hashing
+const hashedPassword = crypto.createHash('md5').update(password).digest('hex');  // ❌
+const hashedPassword = crypto.createHash('sha1').update(password).digest('hex'); // ❌
+```
+
+### Password Requirements
+
+Enforce strong password policies.
+
+```typescript
+// Good - Strong password validation
+const validatePassword = (password: string): { valid: boolean; errors: string[] } => {
+  const errors: string[] = [];
+  
+  if (password.length < 12) {
+    errors.push('Password must be at least 12 characters');
+  }
+  
+  if (!/[a-z]/.test(password)) {
+    errors.push('Password must contain lowercase letter');
+  }
+  
+  if (!/[A-Z]/.test(password)) {
+    errors.push('Password must contain uppercase letter');
+  }
+  
+  if (!/\d/.test(password)) {
+    errors.push('Password must contain number');
+  }
+  
+  if (!/[@$!%*?&]/.test(password)) {
+    errors.push('Password must contain special character');
+  }
+  
+  // Check against common passwords
+  if (commonPasswords.includes(password.toLowerCase())) {
+    errors.push('Password is too common');
+  }
+  
+  return { valid: errors.length === 0, errors };
+};
+```
+
+### Password Reset
+
+Implement secure password reset flow.
+
+```typescript
+// Good - Secure password reset
+import crypto from 'crypto';
+
+// Generate reset token
+const resetToken = crypto.randomBytes(32).toString('hex');
+const resetTokenHash = crypto.createHash('sha256').update(resetToken).digest('hex');
+
+await db.users.update(userId, {
+  resetToken: resetTokenHash,
+  resetTokenExpiry: Date.now() + 3600000 // 1 hour
+});
+
+// Send email with reset link
+await sendEmail({
+  to: user.email,
+  subject: 'Password Reset',
+  body: `Reset your password: https://example.com/reset?token=${resetToken}`
+});
+
+// Verify reset token
+const tokenHash = crypto.createHash('sha256').update(req.query.token).digest('hex');
+const user = await db.users.findOne({
+  resetToken: tokenHash,
+  resetTokenExpiry: { $gt: Date.now() }
+});
+
+if (!user) {
+  return res.status(400).json({ error: 'Invalid or expired token' });
+}
+```
+
+## Multi-Factor Authentication (MFA)
+
+### TOTP (Time-based One-Time Password)
+
+```typescript
+import speakeasy from 'speakeasy';
+import qrcode from 'qrcode';
+
+// Generate MFA secret
+const secret = speakeasy.generateSecret({
+  name: `MyApp (${user.email})`
+});
+
+await db.users.update(userId, {
+  mfaSecret: secret.base32,
+  mfaEnabled: false  // User must verify first
+});
+
+// Generate QR code for user to scan
+const qrCodeUrl = await qrcode.toDataURL(secret.otpauth_url);
+
+// Verify MFA code
+const verified = speakeasy.totp.verify({
+  secret: user.mfaSecret,
+  encoding: 'base32',
+  token: req.body.mfaCode,
+  window: 2  // Allow 2 time steps before/after
+});
+
+if (verified) {
+  await db.users.update(userId, { mfaEnabled: true });
+}
+```
+
+### Backup Codes
+
+Provide backup codes for MFA recovery.
+
+```typescript
+// Generate backup codes
+const generateBackupCodes = (): string[] => {
+  const codes: string[] = [];
+  for (let i = 0; i < 10; i++) {
+    codes.push(crypto.randomBytes(4).toString('hex'));
+  }
+  return codes;
+};
+
+const backupCodes = generateBackupCodes();
+const hashedCodes = await Promise.all(
+  backupCodes.map(code => bcrypt.hash(code, 10))
+);
+
+await db.users.update(userId, {
+  backupCodes: hashedCodes
+});
+
+// Verify backup code
+const isValidBackupCode = async (inputCode: string, user: User): Promise<boolean> => {
+  for (let i = 0; i < user.backupCodes.length; i++) {
+    const isValid = await bcrypt.compare(inputCode, user.backupCodes[i]);
+    if (isValid) {
+      // Remove used backup code
+      user.backupCodes.splice(i, 1);
+      await db.users.update(user.id, { backupCodes: user.backupCodes });
+      return true;
+    }
+  }
+  return false;
+};
+```
+
+## Session Management
+
+### Secure Session Configuration
+
+```typescript
+import session from 'express-session';
+import RedisStore from 'connect-redis';
+
+// Good - Secure session configuration
+app.use(session({
+  store: new RedisStore({ client: redisClient }),
+  secret: process.env.SESSION_SECRET,  // Strong random secret
+  resave: false,
+  saveUninitialized: false,
+  name: 'sessionId',  // Don't use default name
+  cookie: {
+    secure: true,        // HTTPS only
+    httpOnly: true,      // Prevent XSS
+    sameSite: 'strict',  // Prevent CSRF
+    maxAge: 3600000,     // 1 hour
+    domain: '.example.com'
+  }
+}));
+```
+
+### Session Invalidation
+
+```typescript
+// Logout - destroy session
+app.post('/logout', (req, res) => {
+  req.session.destroy((err) => {
+    if (err) {
+      return res.status(500).json({ error: 'Logout failed' });
+    }
+    res.clearCookie('sessionId');
+    res.json({ message: 'Logged out successfully' });
+  });
+});
+
+// Invalidate all sessions on password change
+await db.sessions.deleteMany({ userId: user.id });
+```
+
+## JWT Security
+
+### Secure JWT Implementation
+
+```typescript
+import jwt from 'jsonwebtoken';
+
+// Generate JWT
+const accessToken = jwt.sign(
+  {
+    sub: user.id,
+    email: user.email,
+    role: user.role
+  },
+  process.env.JWT_SECRET,
+  {
+    expiresIn: '15m',
+    issuer: 'myapp.com',
+    audience: 'myapp.com'
+  }
+);
+
+// Verify JWT
+try {
+  const decoded = jwt.verify(token, process.env.JWT_SECRET, {
+    issuer: 'myapp.com',
+    audience: 'myapp.com'
+  });
+} catch (error) {
+  if (error.name === 'TokenExpiredError') {
+    return res.status(401).json({ error: 'Token expired' });
+  }
+  return res.status(401).json({ error: 'Invalid token' });
+}
+```
+
+### Refresh Token Pattern
+
+```typescript
+// Generate tokens
+const accessToken = generateAccessToken(user);  // 15 minutes
+const refreshToken = generateRefreshToken(user); // 7 days
+
+// Store refresh token (hashed)
+const refreshTokenHash = crypto.createHash('sha256').update(refreshToken).digest('hex');
+await db.refreshTokens.create({
+  userId: user.id,
+  token: refreshTokenHash,
+  expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)
+});
+
+// Refresh access token
+app.post('/auth/refresh', async (req, res) => {
+  const { refreshToken } = req.body;
+  
+  const tokenHash = crypto.createHash('sha256').update(refreshToken).digest('hex');
+  const storedToken = await db.refreshTokens.findOne({
+    token: tokenHash,
+    expiresAt: { $gt: new Date() }
+  });
+  
+  if (!storedToken) {
+    return res.status(401).json({ error: 'Invalid refresh token' });
+  }
+  
+  const user = await db.users.findOne(storedToken.userId);
+  const newAccessToken = generateAccessToken(user);
+  
+  res.json({ accessToken: newAccessToken });
+});
+```
+
+## Brute Force Protection
+
+### Rate Limiting
+
+```typescript
+import rateLimit from 'express-rate-limit';
+
+// Login rate limiting
+const loginLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 5,
+  skipSuccessfulRequests: true,
+  message: 'Too many login attempts'
+});
+
+app.post('/login', loginLimiter, async (req, res) => {
+  // Login logic
+});
+```
+
+### Account Lockout
+
+```typescript
+const MAX_ATTEMPTS = 5;
+const LOCKOUT_DURATION = 15 * 60 * 1000; // 15 minutes
+
+// Check if account is locked
+if (user.lockoutUntil && user.lockoutUntil > Date.now()) {
+  return res.status(429).json({
+    error: 'Account locked',
+    retryAfter: Math.ceil((user.lockoutUntil - Date.now()) / 1000)
+  });
+}
+
+// Failed login
+if (!isValidPassword) {
+  const attempts = user.loginAttempts + 1;
+  
+  if (attempts >= MAX_ATTEMPTS) {
+    await db.users.update(user.id, {
+      loginAttempts: attempts,
+      lockoutUntil: Date.now() + LOCKOUT_DURATION
+    });
+    return res.status(429).json({ error: 'Account locked' });
+  }
+  
+  await db.users.update(user.id, { loginAttempts: attempts });
+  return res.status(401).json({ error: 'Invalid credentials' });
+}
+
+// Successful login - reset attempts
+await db.users.update(user.id, {
+  loginAttempts: 0,
+  lockoutUntil: null
+});
+```
+
+## Best Practices
+
+1. **Hash passwords** - Use bcrypt or Argon2
+2. **Strong passwords** - Enforce complexity requirements
+3. **Secure reset flow** - Time-limited tokens
+4. **Implement MFA** - TOTP or SMS
+5. **Secure sessions** - httpOnly, secure, sameSite cookies
+6. **Short-lived tokens** - 15-minute access tokens
+7. **Refresh tokens** - For obtaining new access tokens
+8. **Rate limiting** - Prevent brute force
+9. **Account lockout** - After failed attempts
+10. **Log auth events** - Monitor suspicious activity
+