odac 0.9.0

package/docs/backend/10-authentication/06-candy-login-forms.md

@@ -0,0 +1,596 @@
+# Candy Login Forms
+
+The `<candy:login>` component provides a zero-configuration way to create secure login forms. Simply write HTML, and CandyPack handles validation, security, authentication, and session management automatically.
+
+## Quick Start
+
+### 1. Configure Database (config.json)
+
+```json
+{
+  "mysql": {
+    "host": "localhost",
+    "user": "root",
+    "password": "",
+    "database": "your_database"
+  }
+}
+```
+
+That's all you need! The `auth` configuration is optional.
+
+### 2. Create Your Form (view/content/login.html)
+
+```html
+<candy:login redirect="/dashboard">
+  <candy:field name="email" type="email" placeholder="Email">
+    <candy:validate rule="required|email" message="Please enter a valid email"/>
+  </candy:field>
+  
+  <candy:field name="password" type="password" placeholder="Password">
+    <candy:validate rule="required" message="Password is required"/>
+  </candy:field>
+  
+  <candy:submit>Login</candy:submit>
+</candy:login>
+```
+
+That's it! No JavaScript, no controller code needed. The form automatically:
+- Validates input (client-side and server-side)
+- Authenticates the user
+- Creates a secure session
+- Redirects to the specified page
+
+### 3. Optional: Customize Auth Configuration
+
+If you want to customize table names or primary key:
+
+```json
+{
+  "mysql": {
+    "host": "localhost",
+    "user": "root",
+    "password": "",
+    "database": "your_database"
+  },
+  "auth": {
+    "table": "users",           // Optional: User table name (default: "users")
+    "key": "id",                // Optional: Primary key (default: "id")
+    "token": "candy_auth"       // Optional: Token table (default: "candy_auth")
+  }
+}
+```
+
+## Form Attributes
+
+### `<candy:login>`
+
+Main form container with configuration options:
+
+```html
+<candy:login 
+  redirect="/dashboard">    <!-- Redirect URL after successful login -->
+  <!-- fields here -->
+</candy:login>
+```
+
+**Attributes:**
+- `redirect` - URL to redirect after successful login (required)
+
+## Field Types
+
+### `<candy:field>`
+
+Defines an input field with validation rules:
+
+```html
+<candy:field 
+  name="email"              <!-- Field name (required) -->
+  type="email"              <!-- Input type (default: text) -->
+  placeholder="Email"       <!-- Placeholder text -->
+  label="Email Address"     <!-- Label text (optional) -->
+  class="form-input"        <!-- CSS class (optional) -->
+  id="email-field">         <!-- HTML ID (optional) -->
+  
+  <candy:validate rule="required|email" message="Valid email required"/>
+</candy:field>
+```
+
+**Attributes:**
+- `name` - Field name (required)
+- `type` - Input type: text, email, password, number, checkbox
+- `placeholder` - Placeholder text
+- `label` - Label text
+- `class` - CSS class for styling
+- `id` - HTML ID attribute
+
+**Supported Input Types:**
+- `text` - Text input
+- `email` - Email input (with HTML5 validation)
+- `password` - Password input
+- `number` - Number input
+- `checkbox` - Checkbox input (for "remember me" functionality)
+
+## Validation Rules
+
+### `<candy:validate>`
+
+Defines validation rules for a field:
+
+```html
+<candy:validate 
+  rule="required|minlen:4"
+  message="This field is required and must be at least 4 characters"/>
+```
+
+**Attributes:**
+- `rule` - Validation rules (pipe-separated)
+- `message` - Error message to display
+
+### Available Rules
+
+**Basic Rules:**
+- `required` - Field is required
+- `email` - Valid email format
+- `numeric` - Only numbers
+- `alpha` - Only letters
+- `alphanumeric` - Letters and numbers only
+
+**Length Rules:**
+- `minlen:X` - Minimum length
+- `maxlen:X` - Maximum length
+- `len:X` - Exact length
+
+**Number Rules:**
+- `min:X` - Minimum value
+- `max:X` - Maximum value
+
+**Pattern Rules:**
+- `regex:pattern` - Custom regex pattern
+
+### Multiple Validation Rules
+
+You can add multiple `<candy:validate>` tags for different error messages:
+
+```html
+<candy:field name="email" type="email">
+  <candy:validate rule="required" message="Email is required"/>
+  <candy:validate rule="email" message="Please enter a valid email address"/>
+</candy:field>
+```
+
+Or combine rules in a single tag:
+
+```html
+<candy:field name="email" type="email">
+  <candy:validate 
+    rule="required|email" 
+    message="Please enter a valid email address"/>
+</candy:field>
+```
+
+## Message Placeholders
+
+Use placeholders in error messages for dynamic values:
+
+```html
+<candy:field name="username" type="text">
+  <candy:validate 
+    rule="minlen:4" 
+    message="Username '{value}' is too short. Minimum {min} characters required"/>
+</candy:field>
+```
+
+**Available Placeholders:**
+- `{value}` - User's input value
+- `{field}` - Field name
+- `{label}` - Field label or placeholder
+- `{min}` - Minimum value (for minlen, min rules)
+- `{max}` - Maximum value (for maxlen, max rules)
+- `{len}` - Required length (for len rule)
+
+## Submit Button
+
+### `<candy:submit>`
+
+Defines the submit button:
+
+```html
+<candy:submit 
+  text="Login"                    <!-- Button text -->
+  loading="Logging in..."         <!-- Loading state text -->
+  class="btn btn-primary"         <!-- CSS class -->
+  id="login-button">              <!-- HTML ID -->
+</candy:submit>
+```
+
+Or use content as button text:
+
+```html
+<candy:submit>Login</candy:submit>
+```
+
+## Complete Examples
+
+### Basic Login Form
+
+```html
+<candy:login redirect="/dashboard">
+  
+  <!-- Email Field -->
+  <candy:field name="email" type="email" placeholder="Email Address">
+    <candy:validate rule="required" message="Email is required"/>
+    <candy:validate rule="email" message="Please enter a valid email address"/>
+  </candy:field>
+  
+  <!-- Password Field -->
+  <candy:field name="password" type="password" placeholder="Password">
+    <candy:validate rule="required" message="Password is required"/>
+  </candy:field>
+  
+  <!-- Submit Button -->
+  <candy:submit text="Login" loading="Logging in..."/>
+  
+</candy:login>
+```
+
+### Login with Username
+
+```html
+<candy:login redirect="/dashboard">
+  
+  <!-- Username Field -->
+  <candy:field name="username" type="text" placeholder="Username">
+    <candy:validate rule="required" message="Username is required"/>
+    <candy:validate rule="minlen:4" message="Username must be at least {min} characters"/>
+  </candy:field>
+  
+  <!-- Password Field -->
+  <candy:field name="password" type="password" placeholder="Password">
+    <candy:validate rule="required" message="Password is required"/>
+  </candy:field>
+  
+  <!-- Submit Button -->
+  <candy:submit>Login</candy:submit>
+  
+</candy:login>
+```
+
+### Login with Remember Me
+
+```html
+<candy:login redirect="/dashboard">
+  
+  <!-- Email Field -->
+  <candy:field name="email" type="email" placeholder="Email">
+    <candy:validate rule="required|email" message="Please enter a valid email"/>
+  </candy:field>
+  
+  <!-- Password Field -->
+  <candy:field name="password" type="password" placeholder="Password">
+    <candy:validate rule="required" message="Password is required"/>
+  </candy:field>
+  
+  <!-- Remember Me Checkbox -->
+  <candy:field name="remember" type="checkbox" label="Remember me">
+  </candy:field>
+  
+  <!-- Submit Button -->
+  <candy:submit>Login</candy:submit>
+  
+</candy:login>
+```
+
+### Styled Login Form
+
+```html
+<div class="login-container">
+  <h2>Welcome Back</h2>
+  
+  <candy:login redirect="/dashboard">
+    
+    <div class="form-group">
+      <candy:field 
+        name="email" 
+        type="email" 
+        placeholder="Email Address"
+        class="form-control">
+        <candy:validate rule="required|email" message="Please enter a valid email"/>
+      </candy:field>
+      <span class="candy-form-error" candy-form-error="email"></span>
+    </div>
+    
+    <div class="form-group">
+      <candy:field 
+        name="password" 
+        type="password" 
+        placeholder="Password"
+        class="form-control">
+        <candy:validate rule="required" message="Password is required"/>
+      </candy:field>
+      <span class="candy-form-error" candy-form-error="password"></span>
+    </div>
+    
+    <div class="form-group">
+      <candy:field name="remember" type="checkbox" label="Remember me" class="form-check-input">
+      </candy:field>
+    </div>
+    
+    <candy:submit class="btn btn-primary btn-block" text="Login" loading="Logging in..."/>
+    
+    <span class="candy-form-error" candy-form-error="_candy_form"></span>
+    
+  </candy:login>
+  
+  <p class="text-center mt-3">
+    <a href="/forgot-password">Forgot password?</a>
+  </p>
+</div>
+```
+
+## Security Features
+
+### Automatic Security
+
+CandyPack automatically handles:
+
+1. **CSRF Protection** - Form tokens prevent cross-site attacks
+2. **Password Verification** - Passwords are verified against bcrypt hashes
+3. **SQL Injection Prevention** - All queries are parameterized
+4. **XSS Protection** - Input is sanitized
+5. **Field Whitelisting** - Only defined fields are processed
+6. **Token Expiration** - Form tokens expire after 30 minutes
+7. **Session Security** - Secure session management with token rotation
+
+### Token System
+
+Each form gets a unique token when rendered:
+- Token is stored server-side with field whitelist
+- Token expires after 30 minutes
+- Only fields defined in the view are accepted
+- Session validation prevents token hijacking
+
+## HTML5 Validation
+
+CandyPack automatically adds HTML5 validation attributes for better UX:
+
+```html
+<!-- This field -->
+<candy:field name="email" type="email">
+  <candy:validate rule="required|email"/>
+</candy:field>
+
+<!-- Generates this HTML -->
+<input 
+  type="email" 
+  name="email" 
+  required>
+```
+
+**Automatic HTML5 Attributes:**
+- `required` - For required fields
+- `minlength` / `maxlength` - For length validation
+- `min` / `max` - For number validation
+- `pattern` - For alphanumeric, numeric, alpha rules
+- `type="email"` - Native email validation
+
+This provides instant feedback to users before form submission.
+
+## Error Handling
+
+### Display Errors
+
+Error messages are automatically displayed in `<span>` elements with `candy-form-error` attribute:
+
+```html
+<!-- Errors appear here automatically -->
+<span class="candy-form-error" candy-form-error="email" style="display:none;"></span>
+<span class="candy-form-error" candy-form-error="password" style="display:none;"></span>
+<span class="candy-form-error" candy-form-error="_candy_form" style="display:none;"></span>
+```
+
+### Success Messages
+
+Success messages appear in elements with `candy-form-success` class:
+
+```html
+<!-- Success message appears here -->
+<span class="candy-form-success" style="display:none;"></span>
+```
+
+### Custom Styling
+
+Style error and success messages with CSS:
+
+```css
+.candy-form-error {
+  color: red;
+  font-size: 0.875rem;
+  margin-top: 0.25rem;
+  display: block;
+}
+
+.candy-form-success {
+  color: green;
+  font-size: 1rem;
+  padding: 1rem;
+  background: #d4edda;
+  border: 1px solid #c3e6cb;
+  border-radius: 0.25rem;
+}
+
+input._candy_error {
+  border-color: red;
+}
+```
+
+## Configuration Reference
+
+### Required Configuration
+
+Only MySQL configuration is required:
+
+```json
+{
+  "mysql": {
+    "host": "localhost",
+    "user": "root",
+    "password": "",
+    "database": "your_database"
+  }
+}
+```
+
+### Optional Auth Configuration
+
+Customize table names and primary key if needed:
+
+```json
+{
+  "auth": {
+    "table": "users",           // User table name (default: "users")
+    "key": "id",                // Primary key column (default: "id")
+    "token": "user_tokens"      // Session token table (default: "user_tokens")
+  }
+}
+```
+
+**Default Values:**
+- If `auth` is not specified, defaults are used
+- Table: `users`
+- Primary key: `id`
+- Token table: `candy_auth`
+
+### Database Schema
+
+The users table should have been created during registration. If you need to create it manually:
+
+```sql
+CREATE TABLE `users` (
+  `id` INT NOT NULL AUTO_INCREMENT,
+  `email` VARCHAR(255) NOT NULL UNIQUE,
+  `username` VARCHAR(255) NULL UNIQUE,
+  `password` VARCHAR(255) NOT NULL,
+  `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  `updated_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  PRIMARY KEY (`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+```
+
+**Important:**
+- Password field must be `VARCHAR(255)` to store bcrypt hashes
+- Email or username should have `UNIQUE` constraint
+
+### Token Table
+
+The token table is created automatically on first login, but you can create it manually:
+
+```sql
+CREATE TABLE `candy_auth` (
+  `id` INT NOT NULL AUTO_INCREMENT,
+  `user` INT NOT NULL,
+  `token_x` VARCHAR(255) NOT NULL,
+  `token_y` VARCHAR(255) NOT NULL,
+  `browser` VARCHAR(255) NOT NULL,
+  `ip` VARCHAR(255) NOT NULL,
+  `date` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  `active` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+```
+
+## Authentication Methods
+
+The login form supports multiple authentication methods:
+
+### Email + Password
+
+```html
+<candy:login redirect="/dashboard">
+  <candy:field name="email" type="email" placeholder="Email">
+    <candy:validate rule="required|email"/>
+  </candy:field>
+  <candy:field name="password" type="password" placeholder="Password">
+    <candy:validate rule="required"/>
+  </candy:field>
+  <candy:submit>Login</candy:submit>
+</candy:login>
+```
+
+### Username + Password
+
+```html
+<candy:login redirect="/dashboard">
+  <candy:field name="username" type="text" placeholder="Username">
+    <candy:validate rule="required"/>
+  </candy:field>
+  <candy:field name="password" type="password" placeholder="Password">
+    <candy:validate rule="required"/>
+  </candy:field>
+  <candy:submit>Login</candy:submit>
+</candy:login>
+```
+
+### Email or Username + Password
+
+```html
+<candy:login redirect="/dashboard">
+  <candy:field name="identifier" type="text" placeholder="Email or Username">
+    <candy:validate rule="required"/>
+  </candy:field>
+  <candy:field name="password" type="password" placeholder="Password">
+    <candy:validate rule="required"/>
+  </candy:field>
+  <candy:submit>Login</candy:submit>
+</candy:login>
+```
+
+## Best Practices
+
+1. **Always use HTTPS** - Login forms should only be served over HTTPS
+2. **Validate on both client and server** - CandyPack does this automatically
+3. **Provide clear error messages** - Don't reveal whether email/username exists
+4. **Add "Forgot Password" link** - Help users recover their accounts
+5. **Consider rate limiting** - Prevent brute force attacks (implement in controller)
+6. **Use strong password requirements** - Enforce during registration
+7. **Test form expiration** - Forms expire after 30 minutes
+
+## Troubleshooting
+
+### Form Not Submitting
+
+- Check that `config.json` has MySQL configuration
+- Verify database table exists
+- Check browser console for JavaScript errors
+- Ensure CSRF token is valid
+
+### Validation Not Working
+
+- Ensure validation rules are spelled correctly
+- Check that field names match between `<candy:field>` and validation
+- Verify HTML5 validation isn't blocking submission
+
+### Login Failing
+
+- Verify user exists in database
+- Check that password was hashed with bcrypt during registration
+- Ensure auth table name in config matches your database
+- Check that credentials match exactly (case-sensitive)
+
+### Token Expired
+
+- Forms expire after 30 minutes
+- User needs to refresh the page to get a new token
+- Consider adding a message about session expiration
+
+### Redirect Not Working
+
+- Ensure `redirect` attribute is set on `<candy:login>`
+- Check that the redirect URL is valid
+- Verify user has permission to access the redirect page
+
+## Related Documentation
+
+- [Candy Register Forms](04-candy-register-forms.md) - Create registration forms
+- [Session Management](05-session-management.md) - Understanding sessions
+- [Authentication Overview](00-authentication-overview.md) - Auth system basics

package/docs/backend/11-mail/01-the-mail-service.md

@@ -0,0 +1,42 @@
+## ✉️ The `Mail` Service
+
+The `Candy.Mail` service is your friendly neighborhood postal worker. It provides a super simple way to send emails using the mail server settings you've already configured in the CandyPack core.
+
+#### How to Send an Email
+
+`Candy.Mail.send(to, subject, htmlBody)`
+
+*   `to`: The email address of the person you're sending it to.
+*   `subject`: The subject line for your email.
+*   `htmlBody`: The main content of your email. You can even use HTML tags to make it look fancy!
+
+Just like the database service, `send` is an `async` method, so using it with `async/await` is the way to go.
+
+#### Example: A Simple Contact Form
+
+Let's imagine you have a controller that handles a contact form on your website.
+
+```javascript
+module.exports = async function (Candy) {
+  const { recipient, subject, message } = Candy.Request.post;
+
+  // It's always a good idea to check your data first!
+  if (!recipient || !subject || !message) {
+    return { error: 'Oops! You missed a required field.' };
+  }
+
+  try {
+    // Let's try to send the email
+    await Candy.Mail.send(recipient, subject, `<p>${message}</p>`);
+
+    // If we get here, it worked!
+    return { success: true, message: 'Email sent successfully!' };
+  } catch (error) {
+    // If something went wrong...
+    console.error('Oh no, the email failed to send:', error);
+    return { error: 'Something went wrong while trying to send the email.' };
+  }
+}
+```
+
+And that's all there is to it. You're now a master of email!