orion/docs/frontend/storefront/authentication-pages.md

# Storefront Authentication Pages

## Overview

This document details the implementation of customer authentication pages in the storefront frontend. All pages use Tailwind CSS, Alpine.js, and integrate with the multi-theme system for a branded, consistent experience across all stores.

## Implementation Date
2025-11-24

---

## 📄 Available Pages

### 1. Login Page
**Location:** `app/templates/storefront/account/login.html`
**Route:** `/storefront/account/login`

#### Features
- Two-column layout with store branding on the left
- Email and password fields with validation
- Password visibility toggle
- "Remember me" checkbox
- Links to register and forgot password pages
- Error and success message alerts
- Loading states with animated spinner
- Theme-aware colors using CSS variables
- Full dark mode support
- Mobile responsive design

#### Alpine.js Component
```javascript
function customerLogin() {
    return {
        credentials: { email: '', password: '' },
        rememberMe: false,
        showPassword: false,
        loading: false,
        errors: {},
        alert: { show: false, type: 'error', message: '' },
        dark: false,

        async handleLogin() {
            // Validates input
            // Calls POST /api/v1/storefront/auth/login
            // Stores token in localStorage
            // Redirects to account page or return URL
        }
    }
}
```

#### API Integration
- **Endpoint:** `POST /api/v1/storefront/auth/login`
- **Request:** `{ email_or_username: string, password: string }`
- **Response:** `{ access_token: string, user: object }`

---

### 2. Register Page
**Location:** `app/templates/storefront/account/register.html`
**Route:** `/storefront/account/register`

#### Features
- Two-column layout with store branding
- Form fields:
  - First name (required)
  - Last name (required)
  - Email (required, validated)
  - Phone (optional)
  - Password (required, min 8 chars, 1 letter, 1 number)
  - Confirm password (required, must match)
  - Marketing consent checkbox
- Real-time client-side validation
- Password visibility toggle
- Password strength requirements displayed
- Theme-aware styling
- Loading states with spinner
- Success/error message handling
- Redirects to login page after successful registration

#### Validation Rules
- **First Name:** Required, non-empty
- **Last Name:** Required, non-empty
- **Email:** Required, valid email format
- **Password:** Minimum 8 characters, at least one letter, at least one number
- **Confirm Password:** Must match password field

#### Alpine.js Component
```javascript
function customerRegistration() {
    return {
        formData: {
            first_name: '',
            last_name: '',
            email: '',
            phone: '',
            password: '',
            marketing_consent: false
        },
        confirmPassword: '',
        showPassword: false,
        loading: false,
        errors: {},

        validateForm() {
            // Validates all fields
            // Sets this.errors for invalid fields
            // Returns true if all valid
        },

        async handleRegister() {
            // Validates form
            // Calls POST /api/v1/storefront/auth/register
            // Shows success message
            // Redirects to login with ?registered=true
        }
    }
}
```

#### API Integration
- **Endpoint:** `POST /api/v1/storefront/auth/register`
- **Request:** `{ first_name: string, last_name: string, email: string, phone?: string, password: string, marketing_consent: boolean }`
- **Response:** `{ message: string }`

---

### 3. Forgot Password Page
**Location:** `app/templates/storefront/account/forgot-password.html`
**Route:** `/storefront/account/forgot-password`

#### Features
- Two-column layout with store branding
- Email input field
- Two-state interface:
  1. **Form State:** Email input with submit button
  2. **Success State:** Confirmation message with checkmark icon
- Success state displays:
  - Checkmark icon
  - "Check Your Email" heading
  - Email sent confirmation
  - Instructions to check inbox
  - Option to retry if email not received
- Theme-aware styling
- Links back to login and storefront homepage
- Dark mode support
- Mobile responsive

#### Alpine.js Component
```javascript
function forgotPassword() {
    return {
        email: '',
        emailSent: false,
        loading: false,
        errors: {},
        alert: { show: false, type: 'error', message: '' },
        dark: false,

        async handleSubmit() {
            // Validates email
            // Calls POST /api/v1/storefront/auth/forgot-password
            // Sets emailSent = true on success
            // Shows confirmation message
        }
    }
}
```

#### API Integration
- **Endpoint:** `POST /api/v1/storefront/auth/forgot-password`
- **Request:** `{ email: string }`
- **Response:** `{ message: string }`

---

## 🎨 Theme Integration

All authentication pages inject the store's theme CSS variables for consistent branding:

```html
<style id="store-theme-variables">
    :root {
        {% for key, value in theme.css_variables.items() %}
        {{ key }}: {{ value }};
        {% endfor %}
    }

    /* Theme-aware button and focus colors */
    .btn-primary-theme {
        background-color: var(--color-primary);
    }
    .btn-primary-theme:hover:not(:disabled) {
        background-color: var(--color-primary-dark, var(--color-primary));
        filter: brightness(0.9);
    }
    .focus-primary:focus {
        border-color: var(--color-primary);
        box-shadow: 0 0 0 3px rgba(var(--color-primary-rgb, 124, 58, 237), 0.1);
    }
</style>
```

### Themed Elements

| Element | CSS Variable | Usage |
|---------|-------------|--------|
| Left panel background | `var(--color-primary)` | Brand color fills entire left column |
| Submit buttons | `var(--color-primary)` | Primary action buttons |
| Links | `var(--color-primary)` | Forgot password, register, login links |
| Checkboxes | `var(--color-primary)` | Remember me, marketing consent |
| Focus states | `var(--color-primary)` | Input field focus rings |
| Store logo | `theme.branding.logo` | Displayed in left column |

### Benefits
- ✅ Each store's auth pages automatically match their brand
- ✅ Consistent with main storefront design
- ✅ Dark mode adapts to store colors
- ✅ Professional, polished appearance
- ✅ No custom CSS needed per store

---

## 📱 Responsive Design

### Mobile (<640px)
- Vertical layout (branding on top, form below)
- Smaller h-32 branding section
- Full-width buttons
- Reduced padding (p-6 instead of p-12)
- Touch-friendly input fields
- Stacked form elements

### Tablet (640px-1024px)
- Side-by-side layout begins (md:flex-row)
- Branding section grows (md:h-auto md:w-1/2)
- Form section gets more space (md:w-1/2)
- Comfortable padding (sm:p-12)

### Desktop (>1024px)
- Full two-column layout
- Max width container (max-w-4xl)
- Centered on page with margins
- Larger brand imagery
- Optimal form spacing

---

## 🔒 Security Features

### Client-Side Security
- Input validation before API submission
- Password visibility toggle (not plain text by default)
- HTTPS required (enforced by deployment)
- No sensitive data in URLs or query params
- Tokens stored in localStorage (not cookies)
- Form autocomplete attributes for password managers

### Server-Side Security (API)
- Password hashing with bcrypt
- Email validation and sanitization
- Rate limiting on auth endpoints
- CSRF protection
- SQL injection prevention via ORM
- JWT token-based authentication
- Secure password reset tokens

---

## 🎯 Design Principles

### Consistency
- All three pages share the same layout structure
- Identical styling patterns and spacing
- Consistent error/success message handling
- Same loading state indicators

### User Experience
- Clear visual hierarchy
- Immediate feedback on actions
- Helpful error messages
- Loading states prevent duplicate submissions
- Success states confirm actions
- Links to related pages (login ↔ register ↔ forgot password)

### Accessibility
- Semantic HTML
- Proper form labels
- Focus states visible
- Keyboard navigation support
- Screen reader friendly
- Sufficient color contrast

### Performance
- Minimal JavaScript (Alpine.js only)
- Tailwind CSS from CDN with local fallback
- No external dependencies beyond Alpine.js
- Fast page loads
- Inline SVG icons (no image requests)

---

## 🔗 Navigation Flow

```
Storefront Homepage
    ↓
Login Page ←→ Register Page
    ↓              ↓
Forgot Password    |
    ↓              ↓
Check Email   Account/Cart
```

### Link Structure
- **Login Page:**
  - "Forgot password?" → `/storefront/account/forgot-password`
  - "Create an account" → `/storefront/account/register`
  - "← Continue shopping" → `/storefront/`

- **Register Page:**
  - "Already have an account? Sign in instead" → `/storefront/account/login`

- **Forgot Password Page:**
  - "Remember your password? Sign in" → `/storefront/account/login`
  - "← Continue shopping" → `/storefront/`

All links use `{{ base_url }}` for multi-access routing support.

---

## 🛠️ Customization Guide

### For Developers

#### Adding New Fields
1. Add field to HTML form
2. Add field to Alpine.js data
3. Update validation logic
4. Update API request body
5. Update backend endpoint

#### Changing Validation Rules
Edit the `validateForm()` method in Alpine.js component:

```javascript
validateForm() {
    this.clearAllErrors();
    let isValid = true;

    // Add/modify validation rules
    if (!this.formData.field_name.trim()) {
        this.errors.field_name = 'Field is required';
        isValid = false;
    }

    return isValid;
}
```

#### Customizing Theme Variables
Stores can customize colors in their theme configuration:

```python
theme = {
    "colors": {
        "primary": "#6366f1",  # Changes all primary elements
        "secondary": "#8b5cf6",
        "accent": "#ec4899"
    }
}
```

### For Stores
Stores can customize:
- Primary brand color (buttons, links, left panel)
- Logo (displayed in left column)
- Custom CSS (additional styling)
- Dark mode logo variant

No code changes needed - all controlled via theme configuration.

---

## 📊 File Locations

```
app/
├── templates/storefront/account/
│   ├── login.html              ← Customer login page
│   ├── register.html           ← Customer registration page
│   └── forgot-password.html    ← Password reset page
│
└── api/v1/storefront/
    └── auth.py                 ← Authentication endpoints

static/shared/css/
├── base.css                    ← Base CSS (optional reference)
└── auth.css                    ← Auth CSS (optional reference)

Note: Templates use Tailwind CSS classes directly, not the CSS files above.
```

---

## ✅ Testing Checklist

### Functionality
- [ ] Login form submits correctly
- [ ] Register form creates new account
- [ ] Forgot password sends email
- [ ] Validation errors display properly
- [ ] Success messages show correctly
- [ ] Loading states appear during API calls
- [ ] Redirects work after success
- [ ] Remember me checkbox persists
- [ ] Password visibility toggle works

### Theme Integration
- [ ] Store colors apply correctly
- [ ] Store logo displays
- [ ] Dark mode works with store colors
- [ ] Custom fonts load
- [ ] Left panel uses primary color
- [ ] Buttons use primary color

### Responsive Design
- [ ] Mobile layout works (<640px)
- [ ] Tablet layout works (640-1024px)
- [ ] Desktop layout works (>1024px)
- [ ] Touch targets are adequate
- [ ] Forms are usable on mobile

### Security
- [ ] Passwords are masked by default
- [ ] No sensitive data in URLs
- [ ] API calls use HTTPS
- [ ] Tokens stored securely
- [ ] Input validation works

### Accessibility
- [ ] Keyboard navigation works
- [ ] Focus states visible
- [ ] Form labels present
- [ ] Error messages announced
- [ ] Color contrast sufficient

---

## 🚀 Future Enhancements

Possible additions:
- Social login (Google, Facebook)
- Two-factor authentication (2FA)
- Password strength meter
- Email verification flow
- OAuth integration
- Account recovery via phone
- Security questions
- Biometric authentication

---

## 📚 Related Documentation

- [Storefront Frontend Architecture](./architecture.md)
- [Page Template Guide](./page-templates.md)
- [Theme System Overview](../../architecture/theme-system/overview.md)
- [Theme Presets](../../architecture/theme-system/presets.md)
- [API Authentication Documentation](../../api/authentication.md)

---

**Last Updated:** 2025-11-24
**Status:** ✅ Production Ready
**Maintainer:** Development Team