outlet-orm 6.5.0 → 9.0.0

package/docs/skills/outlet-orm/SECURITY.md

@@ -0,0 +1,386 @@
+# Outlet ORM - Security Best Practices
+
+[← Back to Index](SKILL.md) | [Previous: API](API.md)
+
+> 🔐 **Security**: This guide covers backend security practices when using Outlet ORM.
+
+---
+
+## Security Checklist
+
+### 🔴 Critical Priority
+
+| Action | Description | Outlet ORM Feature |
+|--------|-------------|-------------------|
+|`.env`in`.gitignore`| Never commit secrets | Auto-connect from .env |
+| Password hashing | Bcrypt with 10+ rounds | Use`utils/hash.js`|
+| SQL Injection protection | Use ORM queries | ✅ Built-in protection |
+| XSS protection | Sanitize inputs/outputs | Use middleware |
+| Input validation | Validate ALL user data |`static rules`+ middleware |
+
+### 🟠 Important Priority
+
+| Action | Description |
+|--------|-------------|
+| Secure JWT | Short expiration, refresh tokens |
+| Rate limiting | Limit requests per IP |
+| Security headers | Use Helmet.js |
+| CSRF protection | Token for forms |
+| CORS setup | Whitelist origins |
+
+---
+
+## Secure Project Structure (Layered Architecture)
+
+```
+my-project/
+├── .env                       # ⚠️ NEVER commit
+├── .env.example               # Template without secrets
+├── .gitignore
+├── src/
+│   ├── controllers/           # 🎮 HTTP handling only
+│   ├── services/              # ⚙️ Business logic
+│   ├── repositories/          # 📦 Data access layer
+│   ├── models/                # 📊 outlet-orm models
+│   ├── middlewares/           # 🔒 CRITICAL for security
+│   │   ├── auth.js            # JWT authentication
+│   │   ├── authorization.js   # RBAC permissions
+│   │   ├── rateLimiter.js     # Anti-DDoS
+│   │   ├── validator.js       # Input validation
+│   │   └── errorHandler.js    # Error handling
+│   ├── config/                # 🔒 Centralized config
+│   │   └── security.js        # Rate limit, helmet, CORS
+│   ├── utils/                 # 🔒 Security utilities
+│   │   ├── hash.js            # Bcrypt password hashing
+│   │   └── token.js           # JWT token generation
+│   └── validators/            # 🔒 Validation schemas
+├── public/                    # ✅ Only public folder
+├── logs/                      # 📋 Not versioned
+└── tests/
+```
+```
+
+---
+
+## Outlet ORM Built-in Security
+
+### ✅ SQL Injection Protection
+
+```javascript
+// ✅ SECURE - Parameters automatically escaped
+const users = await User.where('email', userInput).get();
+
+// ✅ SECURE - whereIn with array
+const users = await User.whereIn('id', [1, 2, 3]).get();
+
+// ⚠️ CAUTION with whereRaw - escape manually
+const users = await User.whereRaw('email = ?', [userInput]).get();
+```
+
+### ✅ Mass Assignment Protection
+
+```javascript
+class User extends Model {
+// 🔒 Only these fields can be mass-assigned
+static fillable = ['name', 'email'];
+  
+// 'role', 'is_admin' excluded = cannot be modified via create/fill
+}
+
+// ✅ SECURE - role is ignored even if in req.body
+const user = await User.create(req.body);
+```
+
+### ✅ Hidden Attributes
+
+```javascript
+class User extends Model {
+// 🔒 Never exposed in JSON
+static hidden = ['password', 'refresh_token', 'reset_token'];
+}
+
+const user = await User.find(1);
+console.log(user.toJSON());
+// { id: 1, name: "John", email: "..." }
+// password is NOT included
+```
+
+---
+
+## Secure Model Example
+
+```javascript
+const { Model } = require('outlet-orm');
+const { hashPassword, verifyPassword } = require('../utils/hash');
+
+class User extends Model {
+static table = 'users';
+  
+// 🔒 Mass assignment protection
+static fillable = ['name', 'email', 'password'];
+  
+// 🔒 Never expose sensitive data
+static hidden = ['password', 'refresh_token', 'reset_token'];
+  
+// Type casting
+static casts = {
+id: 'int',
+email_verified: 'boolean',
+created_at: 'date'
+};
+  
+// 🔒 Validation rules
+static rules = {
+name: 'required|string|min:2|max:100',
+email: 'required|email',
+password: 'required|min:8'
+};
+
+// 🔒 Hash password before saving
+static boot() {
+this.creating(async (user) => {
+const password = user.getAttribute('password');
+if (password) {
+user.setAttribute('password', await hashPassword(password));
+}
+});
+
+this.updating(async (user) => {
+const password = user.getAttribute('password');
+// Only hash if password changed
+if (password && !password.startsWith('$2b$')) {
+user.setAttribute('password', await hashPassword(password));
+}
+});
+}
+
+// 🔒 Password verification method
+async checkPassword(password) {
+return verifyPassword(password, this.getAttribute('password'));
+}
+}
+
+module.exports = User;
+```
+
+---
+
+## Authentication Middleware
+
+```javascript
+// middlewares/auth.js
+const jwt = require('jsonwebtoken');
+const { User } = require('../models');
+
+const authenticate = async (req, res, next) => {
+try {
+const authHeader = req.headers.authorization;
+if (!authHeader || !authHeader.startsWith('Bearer ')) {
+return res.status(401).json({ error: 'Token missing' });
+}
+
+const token = authHeader.split(' ')[1];
+const decoded = jwt.verify(token, process.env.JWT_SECRET);
+
+const user = await User.find(decoded.userId);
+if (!user) {
+return res.status(401).json({ error: 'User not found' });
+}
+
+req.user = user;
+next();
+} catch (error) {
+if (error.name === 'TokenExpiredError') {
+return res.status(401).json({ error: 'Token expired' });
+}
+return res.status(401).json({ error: 'Invalid token' });
+}
+};
+
+const authorize = (...roles) => {
+return (req, res, next) => {
+if (!req.user) {
+return res.status(401).json({ error: 'Not authenticated' });
+}
+
+const userRole = req.user.getAttribute('role');
+if (!roles.includes(userRole)) {
+return res.status(403).json({ error: 'Access denied' });
+}
+
+next();
+};
+};
+
+module.exports = { authenticate, authorize };
+```
+
+---
+
+## Secure Route Example
+
+```javascript
+const express = require('express');
+const { body } = require('express-validator');
+const { authenticate, authorize } = require('../middlewares/auth');
+const { validate } = require('../middlewares/validator');
+const UserController = require('../controllers/UserController');
+
+const router = express.Router();
+
+// 🔒 Public routes with strict rate limiting
+router.post('/register',
+validate([
+body('name').trim().isLength({ min: 2, max: 100 }).escape(),
+body('email').isEmail().normalizeEmail(),
+body('password').isLength({ min: 8 }),
+]),
+UserController.register
+);
+
+// 🔒 Protected routes
+router.get('/profile',
+authenticate,
+UserController.getProfile
+);
+
+// 🔒 Admin only
+router.delete('/users/:id',
+authenticate,
+authorize('admin'),
+UserController.deleteUser
+);
+
+module.exports = router;
+```
+
+---
+
+## Security Utilities
+
+### utils/hash.js
+
+```javascript
+const bcrypt = require('bcrypt');
+
+const SALT_ROUNDS = 12;
+
+const hashPassword = async (password) => {
+return bcrypt.hash(password, SALT_ROUNDS);
+};
+
+const verifyPassword = async (password, hash) => {
+return bcrypt.compare(password, hash);
+};
+
+module.exports = { hashPassword, verifyPassword };
+```
+
+### utils/token.js
+
+```javascript
+const jwt = require('jsonwebtoken');
+const crypto = require('crypto');
+
+const generateAccessToken = (userId) => {
+return jwt.sign(
+{ userId },
+process.env.JWT_SECRET,
+{ expiresIn: process.env.JWT_EXPIRES_IN || '15m' }
+);
+};
+
+const generateRefreshToken = () => {
+return crypto.randomBytes(64).toString('hex');
+};
+
+module.exports = { generateAccessToken, generateRefreshToken };
+```
+
+---
+
+## Security Configuration
+
+### config/security.js
+
+```javascript
+module.exports = {
+// Rate limiting
+rateLimit: {
+windowMs: 15 * 60 * 1000, // 15 minutes
+max: 100,
+message: { error: 'Too many requests' }
+},
+  
+// Strict rate limit for auth
+authRateLimit: {
+windowMs: 15 * 60 * 1000,
+max: 5,
+message: { error: 'Too many login attempts' }
+},
+  
+// CORS
+cors: {
+origin: process.env.CORS_ORIGIN,
+credentials: true,
+methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH']
+},
+  
+// JWT
+jwt: {
+secret: process.env.JWT_SECRET,
+expiresIn: '15m'
+}
+};
+```
+
+---
+
+## Required Dependencies
+
+```bash
+npm install helmet express-rate-limit xss-clean hpp bcrypt jsonwebtoken express-validator
+```
+
+---
+
+## Common Security Mistakes
+
+### ❌ DON'T
+
+```javascript
+// ❌ Never store passwords in plain text
+user.setAttribute('password', req.body.password);
+
+// ❌ Never expose sensitive data
+static hidden = []; // Empty!
+
+// ❌ Never use raw queries with user input
+await db.execute(`SELECT * FROM users WHERE email = '${email}'`);
+
+// ❌ Never commit .env
+// .gitignore missing .env
+```
+
+### ✅ DO
+
+```javascript
+// ✅ Hash passwords
+user.setAttribute('password', await hashPassword(req.body.password));
+
+// ✅ Hide sensitive fields
+static hidden = ['password', 'refresh_token'];
+
+// ✅ Use parameterised queries
+await User.where('email', email).first();
+
+// ✅ Use .env.example for templates
+```
+
+---
+
+## References
+
+- [Full Security Guide](../../../docs/SECURITY.md)
+- [Validation](ADVANCED.md#validation)
+- [Events/Hooks](ADVANCED.md#events)

package/docs/skills/outlet-orm/SEEDS.md

@@ -0,0 +1,98 @@
+# Outlet ORM - Seeders
+
+[← Back to Index](SKILL.md) | [Previous: Migrations](MIGRATIONS.md)
+
+## When to use seeders
+
+Use seeders to:
+
+- bootstrap reference data;
+- prepare local development environments quickly;
+- initializes integration test fixtures.
+
+## CLI commands
+
+```bash
+# Create a seeder file
+outlet-migrate make:seed UserSeeder
+
+# Run all seeders (DatabaseSeeder is prioritised)
+outlet-migrate seed
+
+# Laravel-style alias
+outlet-migrate db:seed
+
+# Run one specific seeder
+outlet-migrate seed --class UserSeeder
+outlet-migrate seed -c UserSeeder
+```
+
+## Folder convention
+
+```text
+database/
+├── migrations/
+└── seeds/
+    ├── DatabaseSeeder.js
+    ├── RoleSeeder.js
+    └── UserSeeder.js
+```
+
+## Seeder API quick reference
+
+-`this.insert(table, rowOrRows)`inserts one row or many rows;
+-`this.call('OtherSeeder')`runs another seeder;
+-`this.truncate(table)`clears a table before re-seeding.
+
+## Seeder example
+
+```javascript
+const { Seeder } = require('outlet-orm');
+
+class RoleSeeder extends Seeder {
+  async run() {
+    await this.insert('roles', [
+      { name: 'admin' },
+      { name: 'editor' }
+    ]);
+  }
+}
+
+module.exports = RoleSeeder;
+```
+
+## DatabaseSeeder orchestration
+
+```javascript
+const { Seeder } = require('outlet-orm');
+
+class DatabaseSeeder extends Seeder {
+  async run() {
+    await this.call('RoleSeeder');
+    await this.call('UserSeeder');
+  }
+}
+
+module.exports = DatabaseSeeder;
+```
+
+## Recommended flow
+
+```bash
+outlet-migrate migrate
+outlet-migrate seed
+```
+
+For a clean local reset:
+
+```bash
+outlet-migrate fresh --yes
+outlet-migrate seed
+```
+
+## Best practice
+
+- Keep seeders deterministic and idempotent.
+- Control FK order explicitly in`DatabaseSeeder`.
+- Keep heavy bulk data in dedicated import scripts.
+- Prefer unique constraints to prevent duplicate seed data.

package/docs/skills/outlet-orm/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: outlet-orm-best-practices
+description: Outlet ORM is a Laravel Eloquent-inspired ORM for Node.js with MySQL, PostgreSQL, and SQLite support. Use this skill when working with Outlet ORM models, queries, relationships, migrations, backup, and database operations. v6.0.0 adds a full Backup module (BackupManager, BackupScheduler, AES-256-GCM encryption, TCP daemon).
+license: MIT
+metadata:
+author: omgbwa-yasse
+version: "6.0.0"
+source: https://github.com/omgbwa-yasse/outlet-orm
+npm: https://www.npmjs.com/package/outlet-orm
+---
+
+# Outlet ORM Best Practices
+
+Comprehensive guide for using Outlet ORM - a Laravel Eloquent-inspired ORM for Node.js/TypeScript with support for MySQL, PostgreSQL, and SQLite.
+
+> 🆕 **v7.0.0**: AI Integration — MCP Server (Model Context Protocol), AI Safety Guardrails, Prompt-based project initialization. See [AI.md](AI.md).
+>
+> 🔖 **v6.5.0**: Accessors & Mutators, firstOrCreate/firstOrNew/updateOrCreate, upsert, Observer pattern, cursor/stream.
+>
+> 🔖 **v6.0.0**: Full Backup module — `BackupManager`, `BackupScheduler`, AES-256-GCM `BackupEncryption`, `BackupSocketServer` TCP daemon, `BackupSocketClient` with remote restore. See [BACKUP.md](BACKUP.md).
+>
+> 🔖 **v5.0.0**: Full TypeScript support with Generic Model, typed Schema Builder, MigrationInterface and Copilot Skills integration.
+
+## Documentation Index
+
+| Document | Description |
+|----------|-------------|
+| **[MODELS.md](MODELS.md)** | Model definition, CRUD, casts, timestamps, connections |
+| **[QUERIES.md](QUERIES.md)** | Query Builder, WHERE clauses, joins, pagination |
+| **[RELATIONS.md](RELATIONS.md)** | Relationships, Eager Loading, polymorphic, naming conventions |
+| **[MIGRATIONS.md](MIGRATIONS.md)** | Schema Builder, CLI tools, column types, foreign keys |
+| **[ADVANCED.md](ADVANCED.md)** | Transactions, Soft Deletes, Events, Validation, Best Practices |
+| **[TYPESCRIPT.md](TYPESCRIPT.md)** | TypeScript types, generics, typed models, migrations |
+| **[SECURITY.md](SECURITY.md)** | 🔐 Security best practices, authentication, authorisation |
+| **[BACKUP.md](BACKUP.md)** | 🗄️ Backups, scheduling, AES-256-GCM encryption, TCP daemon, restore |
+| **[AI.md](AI.md)** | 🤖 MCP Server, AI Safety Guardrails, Prompt-based Init |
+| **[API.md](API.md)** | Complete API Reference |
+
+---
+
+## When to Apply
+
+Reference these guidelines when:
+- Defining models and table schemas  [MODELS.md](MODELS.md)
+- Building database queries  [QUERIES.md](QUERIES.md)
+- Implementing relationships  [RELATIONS.md](RELATIONS.md)
+- Using Eager Loading  [RELATIONS.md](RELATIONS.md)
+- Setting up migrations  [MIGRATIONS.md](MIGRATIONS.md)
+- Implementing transactions, soft deletes, events  [ADVANCED.md](ADVANCED.md)
+- Using TypeScript with typed models  [TYPESCRIPT.md](TYPESCRIPT.md)
+- Securing your backend application  [SECURITY.md](SECURITY.md)
+- Scheduling or encrypting database backups  [BACKUP.md](BACKUP.md)
+- Restoring a database from a backup file  [BACKUP.md](BACKUP.md)
+- Running a long-lived backup daemon over TCP  [BACKUP.md](BACKUP.md)
+- Exposing the ORM to AI agents via MCP  [AI.md](AI.md)
+- Generating projects from natural language prompts  [AI.md](AI.md)
+- Protecting against AI-initiated destructive operations  [AI.md](AI.md)
+
+---
+
+## Prerequisites
+
+- **Node.js**: >= 18 (required)
+- **Database Drivers** (install only needed):
+- MySQL/MariaDB:`npm install mysql2`
+- PostgreSQL:`npm install pg`
+- SQLite:`npm install sqlite3`
+
+```bash
+npm install outlet-orm
+```
+
+---
+
+## Recommended Project Structure (Layered Architecture)
+
+When using Outlet ORM, organise your project following the **Layered Architecture** pattern:
+
+> 🔐 **Security**: See the [Security Guide](../../../docs/SECURITY.md) for best practices.
+
+```
+my-project/
+├── .env                           # ⚠️ NEVER commit (in .gitignore)
+├── .env.example                   # Template without secrets
+├── .gitignore
+├── package.json
+├── src/
+│   ├── index.js                   # Entry point
+│   ├── controllers/               # 🎮 Presentation Layer
+│   │   └── UserController.js
+│   ├── services/                  # ⚙️ Business Logic Layer
+│   │   └── UserService.js
+│   ├── repositories/              # 📦 Data Access Layer
+│   │   └── UserRepository.js
+│   ├── models/                    # 📊 Models Layer (outlet-orm)
+│   │   └── User.js
+│   ├── middlewares/               # 🔒 Auth, validation, rate limit
+│   │   ├── auth.js
+│   │   ├── validator.js
+│   │   └── errorHandler.js
+│   ├── routes/                    # 🛤️ Route definitions
+│   │   └── index.js
+│   ├── config/                    # 🔒 Configuration
+│   │   ├── database.js
+│   │   └── security.js
+│   └── utils/                     # 🔒 Hash, tokens, helpers
+│       └── helpers.js
+├── database/
+│   ├── config.js                  # Migration CLI config
+│   ├── migrations/
+│   ├── seeds/
+│   └── backups/                   # 🗄️ Backup files (full / partial / journal)
+├── public/                        # ✅ Static files only
+├── logs/                          # 📋 Not versioned
+└── tests/
+    ├── unit/
+    └── integration/
+```
+
+### Architecture Flow
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        HTTP REQUEST                         │
+└─────────────────────────┬───────────────────────────────────┘
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│  🛤️ ROUTES          Route to correct controller             │
+└─────────────────────────┬───────────────────────────────────┘
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│  🔒 MIDDLEWARES      Validation, Auth, Rate Limiting        │
+└─────────────────────────┬───────────────────────────────────┘
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│  🎮 CONTROLLERS      HTTP handling (req/res) only           │
+└─────────────────────────┬───────────────────────────────────┘
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│  ⚙️ SERVICES         Business logic, business rules         │
+└─────────────────────────┬───────────────────────────────────┘
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│  📦 REPOSITORIES     Data access abstraction (CRUD)         │
+└─────────────────────────┬───────────────────────────────────┘
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│  📊 MODELS           outlet-orm (User, Post, etc.)          │
+└─────────────────────────┬───────────────────────────────────┘
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│                        DATABASE                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Layer Responsibilities
+
+| Layer | Files | Responsibility | Security |
+|-------|-------|----------------|----------|
+| **Controllers** |`src/controllers/`| HTTP only (req/res) | Input validation |
+| **Services** |`src/services/`| Business logic, rules | Authorisation |
+| **Repositories** |`src/repositories/`| DB abstraction, queries | Sanitisation |
+| **Models** |`src/models/`| Data structure, relationships | Fillable/Hidden |
+| **Middlewares** |`src/middlewares/`| Auth, validation, errors | 🔒 **Critical** |
+| **Config** |`src/config/`| Environment variables | 🔒 Reads .env |
+| **Utils** |`src/utils/`| Hash, tokens, helpers | 🔒 Never expose |
+| **Backups** |`database/backups/`| Backup files (.sql, .json, .enc) | 🗄️ Encrypted at rest |
+
+### Quick Setup Commands
+
+```bash
+# Initialise project structure
+outlet-init
+
+# Create a migration
+outlet-migrate make create_users_table
+
+# Run migrations
+outlet-migrate migrate
+```
+
+---
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Document |
+|----------|----------|--------|----------|
+| 1 | Model Definition | CRITICAL | [MODELS.md](MODELS.md) |
+| 2 | Query Building | CRITICAL | [QUERIES.md](QUERIES.md) |
+| 3 | Relationships | HIGH | [RELATIONS.md](RELATIONS.md) |
+| 4 | Eager Loading | HIGH | [RELATIONS.md](RELATIONS.md) |
+| 5 | Transactions | MEDIUM-HIGH | [ADVANCED.md](ADVANCED.md) |
+| 6 | Soft Deletes | MEDIUM | [ADVANCED.md](ADVANCED.md) |
+| 7 | Validation & Events | MEDIUM | [ADVANCED.md](ADVANCED.md) |
+| 8 | Migrations & CLI | LOW-MEDIUM | [MIGRATIONS.md](MIGRATIONS.md) |
+| 9 | Backup & Restore | MEDIUM | [BACKUP.md](BACKUP.md) |
+| 10 | AI / MCP Integration | MEDIUM | [AI.md](AI.md) |
+
+---
+
+## References
+
+- <https://github.com/omgbwa-yasse/outlet-orm>
+- <https://www.npmjs.com/package/outlet-orm>
+- <https://github.com/omgbwa-yasse/outlet-orm/blob/main/docs/INDEX.md>