odac 0.9.0

package/docs/backend/09-validation/01-the-validator-service.md

@@ -0,0 +1,424 @@
+## ✅ The `Validator` Service
+
+The Validator service provides a fluent, chainable API for validating user input. It's automatically available in your controllers through `Candy.Validator`.
+
+#### Basic Usage
+
+The validator uses a method-chaining pattern:
+
+```javascript
+const validator = Candy.Validator
+validator.post('email').check('required|email').message('Valid email required')
+validator.post('password').check('required|minlen:8').message('Password must be at least 8 characters')
+
+if (await validator.error()) {
+  return validator.result('Validation failed')
+}
+```
+
+#### Available Methods
+
+- `post(key)` - Validate a POST field
+- `get(key)` - Validate a GET field
+- `var(name, value)` - Validate a custom variable
+- `file(name)` - Validate a file upload
+- `check(rules)` - Define validation rules (pipe-separated)
+- `message(text)` - Set custom error message
+- `error()` - Returns true if validation failed (async)
+- `result(message, data)` - Returns formatted result object (async)
+- `success(callback)` - Returns success result with data
+- `brute(maxAttempts)` - Enable brute force protection (default: 5 attempts)
+
+#### Validation Rules
+
+**Type Validation:**
+- `required` - Field cannot be empty
+- `accepted` - Must be 1, 'on', 'yes', or true
+- `numeric` - Must be a number
+- `alpha` - Only alphabetic characters
+- `alphaspace` - Alphabetic characters and spaces
+- `alphanumeric` - Alphanumeric characters only
+- `alphanumericspace` - Alphanumeric characters and spaces
+- `username` - Alphanumeric username (no spaces or special chars)
+- `email` - Valid email address
+- `ip` - Valid IP address
+- `float` - Floating point number
+- `mac` - Valid MAC address
+- `domain` - Valid domain name
+- `url` - Valid URL
+- `array` - Must be an array
+- `date` - Valid date format
+
+**Length Validation:**
+- `len:X` - Exact length must be X
+- `minlen:X` - Minimum length of X characters
+- `maxlen:X` - Maximum length of X characters
+
+**Value Validation:**
+- `min:X` - Minimum value of X
+- `max:X` - Maximum value of X
+- `equal:value` - Must equal specific value
+- `not:value` - Must not equal specific value
+- `same:field` - Must match another field
+- `different:field` - Must differ from another field
+
+**Date Validation:**
+- `mindate:date` - Must be after specified date
+- `maxdate:date` - Must be before specified date
+
+**String Validation:**
+- `in:substring` - Must contain substring
+- `notin:substring` - Must not contain substring
+- `regex:pattern` - Must match regex pattern
+
+**Security:**
+- `xss` - Check for HTML tags (XSS protection)
+- `usercheck` - User must be authenticated
+- `user:field` - Must match authenticated user's field value
+
+**Inverse Rules:**
+Use `!` prefix to invert any rule: `!required`, `!email`, etc.
+
+#### Example: User Registration
+
+```javascript
+module.exports = async function (Candy) {
+  const validator = Candy.Validator
+
+  validator.post('username').check('required|username|minlen:4|maxlen:20').message('Username must be 4-20 alphanumeric characters')
+  validator.post('email').check('required|email').message('Valid email address required')
+  validator.post('password').check('required|minlen:8').message('Password must be at least 8 characters')
+  validator.post('password_confirm').check('required|same:password').message('Passwords must match')
+
+  if (await validator.error()) {
+    return validator.result('Validation failed')
+  }
+
+  return validator.success('User registered successfully')
+}
+```
+
+#### Example: Login with Brute Force Protection
+
+```javascript
+module.exports = async function (Candy) {
+  const validator = Candy.Validator
+
+  validator.post('email').check('required|email').message('Email required')
+  validator.post('password').check('required').message('Password required')
+  validator.brute(5)
+
+  if (await validator.error()) {
+    return validator.result('Login failed')
+  }
+
+  return validator.success({token: 'abc123'})
+}
+```
+
+#### Example: Custom Variable Validation
+
+```javascript
+module.exports = async function (Candy) {
+  const validator = Candy.Validator
+  const customValue = calculateSomething()
+
+  validator.var('calculated_value', customValue).check('numeric|min:100|max:1000').message('Value must be between 100 and 1000')
+
+  if (await validator.error()) {
+    return validator.result('Invalid calculation')
+  }
+
+  return validator.success('Calculation valid')
+}
+```
+
+#### Multiple Checks Per Field
+
+You can chain multiple `check()` calls for the same field, each with its own specific error message. The validator will return the first error it encounters:
+
+```javascript
+module.exports = async function (Candy) {
+  const validator = Candy.Validator
+
+  validator
+    .post('password')
+    .check('required').message('Password is required')
+    .check('minlen:8').message('Password must be at least 8 characters')
+    .check('maxlen:50').message('Password cannot exceed 50 characters')
+    .check('regex:[A-Z]').message('Password must contain at least one uppercase letter')
+    .check('regex:[0-9]').message('Password must contain at least one number')
+
+  if (await validator.error()) {
+    return validator.result('Validation failed')
+  }
+
+  return validator.success('Password is strong')
+}
+```
+
+#### Example: Complex Form Validation
+
+```javascript
+module.exports = async function (Candy) {
+  const validator = Candy.Validator
+
+  validator
+    .post('username')
+    .check('required').message('Username is required')
+    .check('username').message('Username can only contain letters and numbers')
+    .check('minlen:3').message('Username must be at least 3 characters')
+    .check('maxlen:20').message('Username cannot exceed 20 characters')
+
+  validator
+    .post('email')
+    .check('required').message('Email is required')
+    .check('email').message('Please enter a valid email address')
+
+  validator
+    .post('age')
+    .check('required').message('Age is required')
+    .check('numeric').message('Age must be a number')
+    .check('min:18').message('You must be at least 18 years old')
+    .check('max:120').message('Please enter a valid age')
+
+  validator
+    .post('website')
+    .check('!required').message('Website is optional')
+    .check('url').message('Please enter a valid URL')
+
+  validator
+    .post('bio')
+    .check('maxlen:500').message('Bio cannot exceed 500 characters')
+    .check('xss').message('Bio contains invalid HTML tags')
+
+  if (await validator.error()) {
+    return validator.result('Please fix the errors')
+  }
+
+  return validator.success('Profile updated successfully')
+}
+```
+
+#### Example: Date Range Validation
+
+```javascript
+module.exports = async function (Candy) {
+  const validator = Candy.Validator
+
+  validator
+    .post('start_date')
+    .check('required').message('Start date is required')
+    .check('date').message('Invalid date format')
+    .check('mindate:2024-01-01').message('Start date must be after January 1, 2024')
+
+  validator
+    .post('end_date')
+    .check('required').message('End date is required')
+    .check('date').message('Invalid date format')
+    .check('maxdate:2025-12-31').message('End date must be before December 31, 2025')
+
+  if (await validator.error()) {
+    return validator.result('Invalid date range')
+  }
+
+  return validator.success('Date range is valid')
+}
+```
+
+#### Example: Conditional Validation with Custom Variables
+
+```javascript
+module.exports = async function (Candy) {
+  const validator = Candy.Validator
+  const userRole = Candy.Auth.user('role')
+  const userCredits = Candy.Auth.user('credits') || 0
+
+  validator.post('title').check('required').message('Title is required')
+  validator.post('content').check('required').message('Content is required')
+
+  if (userRole !== 'premium') {
+    validator
+      .var('user_credits', userCredits)
+      .check('numeric').message('Invalid credits value')
+      .check('min:10').message('You need at least 10 credits to publish')
+
+    validator
+      .post('content')
+      .check('maxlen:1000').message('Free users are limited to 1000 characters')
+  }
+
+  validator
+    .var('role_check', userRole)
+    .check('!equal:banned').message('Your account has been banned')
+
+  if (await validator.error()) {
+    return validator.result('Validation failed')
+  }
+
+  return validator.success('Article published')
+}
+```
+
+#### Example: User Authentication Validation
+
+```javascript
+module.exports = async function (Candy) {
+  const validator = Candy.Validator
+
+  validator
+    .post('current_password')
+    .check('required').message('Current password is required')
+    .check('user:password').message('Current password is incorrect')
+
+  validator
+    .post('new_password')
+    .check('required').message('New password is required')
+    .check('minlen:8').message('New password must be at least 8 characters')
+    .check('different:current_password').message('New password must be different from current')
+
+  if (await validator.error()) {
+    return validator.result('Password change failed')
+  }
+
+  return validator.success('Password changed successfully')
+}
+```
+
+#### Example: Boolean Function Results
+
+You can use boolean values directly in `check()` for custom validation logic:
+
+```javascript
+module.exports = async function (Candy) {
+  const validator = Candy.Validator
+  const userId = await Candy.request('user_id')
+  
+  const isOwner = await checkIfUserOwnsResource(userId)
+  const hasPermission = await checkUserPermission('edit')
+  const isWithinLimit = await checkDailyLimit(userId)
+
+  validator.post('title').check('required').message('Title is required')
+  
+  validator
+    .var('ownership', null)
+    .check(isOwner).message('You do not own this resource')
+  
+  validator
+    .var('permission', null)
+    .check(hasPermission).message('You do not have permission to edit')
+  
+  validator
+    .var('limit', null)
+    .check(isWithinLimit).message('You have reached your daily edit limit')
+
+  if (await validator.error()) {
+    return validator.result('Validation failed')
+  }
+
+  return validator.success('Resource updated')
+}
+```
+
+#### Example: Chained Validation (Single Statement)
+
+```javascript
+module.exports = async function (Candy) {
+  return await Candy.Validator
+    .post('email').check('required').message('Email required').check('email').message('Invalid email')
+    .post('password').check('required').message('Password required').check('minlen:8').message('Min 8 chars')
+    .post('age').check('required').message('Age required').check('numeric').message('Must be number').check('min:18').message('Must be 18+')
+    .success('Registration successful')
+}
+```
+
+#### Example: Admin-Only Action with User Check
+
+```javascript
+module.exports = async function (Candy) {
+  const validator = Candy.Validator
+
+  validator
+    .var('auth_check', null)
+    .check('usercheck').message('You must be logged in')
+
+  validator
+    .var('admin_role', null)
+    .check('user:role').message('Admin access required')
+    .check('equal:admin').message('Only admins can perform this action')
+
+  validator.post('action').check('required').message('Action is required')
+
+  if (await validator.error()) {
+    return validator.result('Access denied')
+  }
+
+  return validator.success('Action completed')
+}
+```
+
+#### Frontend Integration
+
+When using `Candy.form()` on the frontend, validation errors are automatically displayed:
+
+**Automatic Error Display:**
+- Each field's error message appears below the input with attribute `[candy-form-error="fieldname"]`
+- Invalid inputs get the `_candy_error` CSS class automatically
+- Errors fade out when the user focuses on the input
+
+**Success Messages:**
+- Success messages appear in elements with `[candy-form-success]` attribute
+- Automatically fades in when validation passes
+
+**Auto-Redirect:**
+- If you pass a URL as the second parameter to `Candy.form()`, successful submissions automatically redirect:
+  ```javascript
+  Candy.form('myForm', '/dashboard') // Redirects to /dashboard on success
+  ```
+
+**Example HTML:**
+```html
+<form candy-form="register" action="/api/register" method="POST">
+  <input type="email" name="email" placeholder="Email">
+  <span candy-form-error="email"></span>
+  
+  <input type="password" name="password" placeholder="Password">
+  <span candy-form-error="password"></span>
+  
+  <button type="submit">Register</button>
+  
+  <span candy-form-success></span>
+</form>
+
+<script>
+  Candy.form('register', '/dashboard') // Auto-redirect on success
+</script>
+```
+
+#### Response Format
+
+The `result()` method returns a standardized response:
+
+**Success:**
+```json
+{
+  "result": {
+    "success": true,
+    "message": "Operation successful"
+  },
+  "data": null
+}
+```
+
+**Error:**
+```json
+{
+  "result": {
+    "success": false
+  },
+  "errors": {
+    "email": "Valid email address required",
+    "password": "Password must be at least 8 characters"
+  }
+}
+```

package/docs/backend/10-authentication/01-user-logins-with-authjs.md

@@ -0,0 +1,53 @@
+## 🔐 User Logins with `Auth.js`
+
+The `Candy.Auth` service is your bouncer, managing who gets in and who stays out. It handles user login sessions for you.
+
+#### Letting a User In
+
+`Candy.Auth.login(userId, userData)`
+
+*   `userId`: A unique ID for the user (like their database ID).
+*   `userData`: An object with any user info you want to remember, like their username or role.
+
+When you call this, `Auth` creates a secure session for the user.
+
+#### Checking the Guest List
+
+*   `Candy.Auth.isLogin()`: Is the current user logged in? Returns `true` or `false`.
+*   `Candy.Auth.getId()`: Gets the ID of the logged-in user.
+*   `Candy.Auth.get('some-key')`: Grabs a specific piece of info from the `userData` you stored.
+
+#### Showing a User Out
+
+*   `Candy.Auth.logout()`: Ends the user's session and logs them out.
+
+#### Example: A Login Flow
+```javascript
+// Controller for your login form
+module.exports = async function (Candy) {
+    const { username, password } = Candy.Request.post;
+
+    // IMPORTANT: You need to write your own code to find the user in your database!
+    const user = await yourDatabase.findUser(username, password);
+
+    if (user) {
+        // User is valid! Log them in.
+        Candy.Auth.login(user.id, { username: user.username });
+        return Candy.direct('/dashboard'); // Send them to their dashboard
+    } else {
+        // Bad credentials, send them back to the login page
+        return Candy.direct('/login?error=1');
+    }
+}
+
+// A protected dashboard page
+module.exports = function (Candy) {
+    // If they're not logged in, kick them back to the login page.
+    if (!Candy.Auth.isLogin()) {
+        return Candy.direct('/login');
+    }
+
+    const username = Candy.Auth.get('username');
+    return `Welcome back, ${username}!`;
+}
+```

package/docs/backend/10-authentication/02-foiling-villains-with-csrf-protection.md

@@ -0,0 +1,55 @@
+## 🛡️ Foiling Villains with CSRF Protection
+
+Cross-Site Request Forgery (CSRF) is a scary-sounding attack where a bad guy tries to trick your users into submitting forms they didn't mean to. The `Candy.Token` service is your shield against this!
+
+#### How it Works
+
+The idea is simple:
+1.  When you show a form, you generate a secret, one-time-use token.
+2.  You put this token in a hidden field in the form.
+3.  When the user submits the form, you check if the token they sent back matches the one you generated.
+
+If they don't match, it's a trap!
+
+#### Generating and Checking Tokens
+
+*   `Candy.Token.get()`: Creates a new secret token.
+*   `Candy.Token.check(theToken)`: Checks if `theToken` is valid.
+
+#### Example: Securing a Form
+
+**1. Add the token to your form view:**
+```html
+<form action="/some-action" method="post">
+    <!-- Add the secret token here! -->
+    <input type="hidden" name="csrf_token" value="{{ csrfToken }}">
+
+    <!-- ... your other form fields ... -->
+    <button type="submit">Submit</button>
+</form>
+```
+
+**2. Your controller that shows the form:**
+```javascript
+module.exports = function (Candy) {
+    // Get a token and pass it to the view
+    const token = Candy.Token.get();
+    return Candy.View.render('your_form_view', { csrfToken: token });
+}
+```
+
+**3. Your controller that handles the form submission:**
+```javascript
+module.exports = function (Candy) {
+    const submittedToken = Candy.Request.post.csrf_token;
+
+    // Check the token!
+    if (!Candy.Token.check(submittedToken)) {
+        // If it's bad, stop right here.
+        return Candy.return('Invalid CSRF Token!').status(403);
+    }
+
+    // If we get here, the token was good!
+    // ...you can now safely process the form...
+}
+```

package/docs/backend/10-authentication/03-register.md

@@ -0,0 +1,134 @@
+# User Registration
+
+The `Candy.Auth.register()` method provides a secure and user-friendly way to create new user accounts with automatic password hashing, duplicate checking, and optional auto-login.
+
+## Basic Usage
+
+```javascript
+module.exports = async function (Candy) {
+  const result = await Candy.Auth.register({
+    email: 'user@example.com',
+    username: 'johndoe',
+    password: 'securePassword123',
+    name: 'John Doe'
+  })
+  
+  if (result.success) {
+    return {message: 'Registration successful', user: result.user}
+  } else {
+    return {error: result.error}
+  }
+}
+```
+
+## Advanced Options
+
+```javascript
+const result = await Candy.Auth.register(
+  {
+    email: 'user@example.com',
+    username: 'johndoe',
+    password: 'securePassword123',
+    name: 'John Doe',
+    role: 'user'
+  },
+  {
+    passwordField: 'password',      // Field name for password (default: 'password')
+    uniqueFields: ['email', 'username'], // Fields to check for duplicates (default: ['email'])
+    autoLogin: true                 // Auto-login after registration (default: true)
+  }
+)
+```
+
+## Response Format
+
+### Success Response
+
+```javascript
+{
+  success: true,
+  user: {
+    id: 123,
+    email: 'user@example.com',
+    username: 'johndoe',
+    // ... other user fields
+  }
+}
+```
+
+### Error Response
+
+```javascript
+{
+  success: false,
+  error: 'email already exists',
+  field: 'email'  // Only present for duplicate field errors
+}
+```
+
+## Features
+
+- **Automatic Password Hashing**: Passwords are automatically hashed using bcrypt
+- **Duplicate Prevention**: Checks for existing users with the same email/username
+- **Auto-Login**: Optionally logs in the user immediately after registration
+- **Flexible Configuration**: Customize password field name and unique fields
+- **Detailed Error Messages**: Returns specific error information for better UX
+
+## Example Controller
+
+```javascript
+module.exports = async function (Candy) {
+  const validator = Candy.Validator
+
+  // Validate input
+  validator.post('email').check('required|email').message('A valid email is required')
+  validator.post('username').check('required|minlen:4').message('Username must be at least 4 characters')
+  validator.post('password').check('required|minlen:8').message('Password must be at least 8 characters')
+
+  if (await validator.error()) {
+    return validator.result('Please fix the errors below')
+  }
+
+  // Get validated data
+  const email = await Candy.request('email')
+  const username = await Candy.request('username')
+  const password = await Candy.request('password')
+  const name = await Candy.request('name')
+  
+  // Register user
+  const result = await Candy.Auth.register(
+    {email, username, password, name},
+    {uniqueFields: ['email', 'username']}
+  )
+  
+  if (result.success) {
+    // User is now registered and logged in
+    return Candy.direct('/dashboard')
+  } else {
+    // Show error message
+    return {error: result.error}
+  }
+}
+```
+
+## Configuration
+
+Make sure your `config.json` has the auth configuration:
+
+```json
+{
+  "auth": {
+    "table": "users",
+    "key": "id",
+    "token": "user_tokens"
+  }
+}
+```
+
+## Security Notes
+
+- Passwords are automatically hashed with bcrypt before storage
+- The system automatically detects already-hashed passwords (bcrypt pattern) to prevent double-hashing
+- Never store plain text passwords
+- Use HTTPS in production to protect credentials in transit
+- Consider adding rate limiting to prevent brute force attacks