# Atmosvere (Formerly Atmosvere) for WordPress

Protect your pages from bots and scrapers—fully in the background and invisible to visitors. Strong protection based on request data and real-time user behaviour. Works for guests and logged-in users alike; for communities, you can tell whether a user is real or not.

- **Invisible**: No CAPTCHAs or steps for legitimate users; protection runs before and after the page loads.
- **Request + behaviour**: Each request is checked by the Trusted API (allow / challenge / block, usually under 50 ms); on the page, our SDK sends behaviour data for additional real-time security.
- **For everyone**: Applies to anonymous traffic and to logged-in users and whole communities (real vs. fake).

## 🚀 Features

- **Bot & Scraper Protection**: Request check before the page loads; allow, challenge, or block—typically under 50 ms.
- **Real-Time Behaviour**: SDK on the page sends behaviour data to the Trusted API for additional security.
- **Works for All Traffic**: Protects guests and logged-in users; for communities, distinguishes real vs. fake users.
- **Admin Panel**: Deep insights into bots and scrapers on your site. Try it without setup: [**Admin Panel Demo**](https://admin.atmosvere.eu/home?demo=true).
- **User Validation**: Automatic user validation for logged-in users.

## Who is it for?

Content sites, communities, membership areas, and SaaS: anyone who wants to stop bots and scrapers without affecting real visitors.

## How protection works

The request hits your server; the plugin forwards the check to Atmosvere. We respond with **Allow**, **Block**, or **Challenge**—usually in under 50 ms. On allow, the visitor gets the page; there the SDK sends behaviour data to our API for additional real-time security.

```mermaid
flowchart TB
    Visitor[Visitor] --> CustomerServer[Your Server]
    CustomerServer -->|Send request| TrustedAPI[Atmosvere API]
    TrustedAPI -->|Allow / Block / Challenge in under 50 ms| CustomerServer
    CustomerServer -->|Allow| Page[User gets page]
    CustomerServer -->|Block| Block[Block]
    CustomerServer -->|Challenge| Challenge[Challenge]
    Page --> SDK[SDK on page]
    SDK -->|Behaviour data for additional security| TrustedAPI
```

With the plugin, you protect your WordPress pages from bots and scrapers using request checks and real-time behaviour—without changing the experience for real visitors.

## 📋 Requirements

- WordPress 5.0 or higher
- PHP 7.2 or higher
- Atmosvere API keys (Publishable Key and Secret Key)

## 🛠️ Installation

1. Upload the plugin files to `/wp-content/plugins/trusted-accounts/`
2. Activate the plugin through the 'Plugins' menu in WordPress
3. Configure your API keys and protection options
4. Optionally set up user validation

## ⚙️ Configuration

### Basic Configuration (API keys & protection)

1. Enter your **Publishable Key** and **Secret Key** from the [Admin Panel](https://admin.atmosvere.eu/register).
2. **Bot Detection**: Load the SDK on the frontend to detect bots and collect analytics (detection only).
3. **Bot Protection**: Block or challenge bots, scrapers and abusive traffic before the page loads (request check; typically under 50 ms).
4. **Excluded routes**: Paths that skip bot protection (e.g. `/wp-admin`, `/wp-login.php`).

#### Verifying that the request check runs (Bot Protection)

- **Admin test**: In **Atmosvere → Settings → Basic Configuration**, use the **Test Bot Protection** button (below the Bot Protection checkbox). It calls the same check-request API used on each front-end page load and shows whether the API is reachable and your Secret Key is accepted. Success means the plugin can reach the API; when Bot Protection is enabled, the same call runs before every non-excluded page visit.
- **How it works**: The plugin runs the check on the `template_redirect` hook (before the page is rendered) for every front-end request that is not in the excluded routes and not admin/AJAX/cron/REST. The request is sent from your server to `https://api.trustedaccounts.org/api/v1/check-request` as a POST with a JSON body (headers object; sensitive headers excluded); the visitor's browser does not call the API directly.
- **Debug logging**: With `WP_DEBUG` and `WP_DEBUG_LOG` enabled, connection or non-200 API errors are written to your debug log (e.g. `wp-content/debug.log`) so you can confirm behaviour when the API fails or times out (the plugin fails open and allows the request).

### User validation & verification

- **User Validation**: Enable automatic user validation and session binding for logged-in users.

### File Structure
```
trusted-accounts/
├── trusted-accounts.php              # Main plugin file
├── includes/                         # Core classes
│   ├── class-trusted-accounts-loader.php
│   ├── class-trusted-accounts-authentication.php
│   ├── class-trusted-accounts-user-manager.php
│   ├── class-trusted-accounts-frontend.php
│   ├── class-trusted-accounts-shortcodes.php
│   ├── class-trusted-accounts-settings.php
│   ├── class-trusted-accounts-user-validation.php
│   └── class-trusted-accounts-admin.php
├── admin/                           # Admin interface
│   └── views/                       # Admin view templates
├── assets/                          # Static assets
│   ├── css/                         # Stylesheets
│   ├── js/                          # JavaScript files
│   └── img/                         # Images and icons
└── languages/                       # Translation files
```

## 🔧 Development

### Local API (localhost)

To point the plugin at a local API (e.g. `http://localhost:3001`) instead of `https://api.trustedaccounts.org`, define this in `wp-config.php` **before** the “That’s all, stop editing!” line:

```php
define('TRUSTED_ACCOUNTS_API_BASE_URL', 'http://localhost:3001');
```

Request check, traffic (bind/check), and frontend SDK URL all use this base. When WordPress runs in Docker, the container uses `host.docker.internal` to reach the host, but the SDK runs in the **browser**, which cannot resolve that hostname. Set `TRUSTED_ACCOUNTS_SDK_SERVER_URL` to the URL the browser can reach (e.g. `http://localhost:3001`):

```php
define('TRUSTED_ACCOUNTS_SDK_SERVER_URL', 'http://localhost:3001');
```

If your SDK script is served from a different URL (e.g. a local dev server on port 8080), you can override only the script URL:

```php
define('TRUSTED_ACCOUNTS_SDK_SCRIPT_URL', 'http://localhost:8080/dist/index-obfuscated.global.js');
```

Omit the trailing slash on `TRUSTED_ACCOUNTS_API_BASE_URL`. When the API base URL is local (e.g. localhost or host.docker.internal), challenge and blocked redirects automatically use `http://localhost:3003/pages/challenge.html` and `http://localhost:3003/pages/blocked.html` (e.g. [trusted-redirect-pages](https://gitlab.com/trusted-accounts/trusted-redirect-pages) on port 3003). You only need to define `TRUSTED_ACCOUNTS_CHALLENGE_PAGE_URL` or `TRUSTED_ACCOUNTS_BLOCKED_PAGE_URL` if you use a different port or host.

### Adding New Features

1. **Create New Class** (if needed)
   ```php
   // includes/class-trusted-accounts-new-feature.php
   class Trusted_Accounts_New_Feature {
       protected static $instance = null;
       
       public static function get_instance() {
           if (null === self::$instance) {
               self::$instance = new self();
           }
           return self::$instance;
       }
       
       private function __construct() {
           $this->init_hooks();
       }
   }
   ```

2. **Update Loader**
   ```php
   // In class-trusted-accounts-loader.php
   private function load_dependencies() {
       require_once TA_PLUGIN_DIR . 'includes/class-trusted-accounts-new-feature.php';
   }
   
   private function init_components() {
       Trusted_Accounts_New_Feature::get_instance();
   }
   ```

3. **Add Documentation**
   - Update README.md
   - Add inline PHPDoc comments
   - Update changelog

### Testing

#### Local Testing
```bash
# Test plugin activation
wp plugin activate trusted-accounts

# Test OAuth flow
# Test user verification
# Test shortcodes
# Test admin interface
```

#### WordPress Coding Standards
```bash
# Install PHP_CodeSniffer
composer require --dev squizlabs/php_codesniffer

# Install WordPress Coding Standards
composer require --dev wp-coding-standards/wpcs

# Run checks
phpcs --standard=WordPress includes/
phpcs --standard=WordPress trusted-accounts.php
```

## 🚀 Deployment Process

### 1. Run Translation
```bash
# Generate POT file
wp i18n make-pot . languages/trusted-accounts.pot

# Update translations using Poedit
# 1. Open Poedit
# 2. File → Open → Select .po file
# 3. Catalog → Update from .POT file
# 4. Select generated /languages/trusted-accounts.pot file
# 5. Update translations and save (automatically generates .mo file)
```

### 2. Prepare for Deployment

#### Update Version Numbers
- Update version in `trusted-accounts.php` (line 8)
- Update stable version tag in `readme.txt` (line 7)
- Update changelog in `readme.txt`

#### Code Quality Checks
- Run PHP linting: `php -l trusted-accounts.php`
- Check all includes files: `php -l includes/*.php`
- Verify WordPress coding standards compliance
- Test plugin activation/deactivation

#### Asset Optimization
- Minify JavaScript files in `assets/js/`
- Optimize CSS files in `assets/css/`
- Compress images in `assets/img/`

### 3. Deploy to WordPress.org

#### SVN Repository
```bash
# Navigate to SVN local directory
cd ~/dev/wordpress/trusted-accounts #/path/to/trusted-accounts-svn

# Copy new files to trunk folder
cp ~/dev/wordpress-plugin/* trunk/ #-r /path/to/refactored-plugin/* trunk/

# Commit changes
svn add trunk/*
svn commit -m "Version 4.0.0: Complete refactoring with improved architecture and freatures"
```

#### Git Repository (if using Git)
```bash
# Add all changes
git add .

# Commit with descriptive message
git commit -m "Version 3.0.3: Complete refactoring with improved architecture

- Modular class structure
- Enhanced security
- Improved error handling
- New admin interface
- Better documentation"

# Tag the release
git tag -a v3.0.3 -m "Version 3.0.3"

# Push to remote
git push origin main
git push origin v3.0.3
```

## 📊 Version Management

### Version Numbering
- **Major.Minor.Patch** (e.g., 3.0.3)
- **Major**: Breaking changes
- **Minor**: New features, backward compatible
- **Patch**: Bug fixes, backward compatible

### Changelog Format
```markdown
= 3.0.3 =
* Complete code refactoring and architecture improvement
* Enhanced security with nonce verification
* Improved error handling and logging
* New admin interface with dashboard
* Enhanced shortcodes with better attributes
```

## 🔒 Security Checklist

- [ ] All forms use nonce verification
- [ ] All inputs are sanitized
- [ ] Proper capability checking
- [ ] No sensitive data in error logs
- [ ] Secure OAuth implementation
- [ ] Input validation on all endpoints

## ⚡ Performance Checklist

- [ ] Efficient database queries
- [ ] Minimal hook usage
- [ ] Optimized asset loading
- [ ] Cache-friendly structure
- [ ] No unnecessary file includes

## 📚 Documentation Checklist

- [ ] README.md updated
- [ ] Inline PHPDoc comments
- [ ] Changelog updated
- [ ] Migration guide (if needed)
- [ ] Code examples provided

## ✅ Deployment Checklist

- [ ] Version numbers updated
- [ ] Translation files generated
- [ ] Assets optimized
- [ ] Code quality checks passed
- [ ] Local testing completed
- [ ] Documentation updated
- [ ] Git/SVN committed and tagged

## 🎣 Hooks and Filters

### Actions

#### `ta_user_verified`
Fired when a user is successfully verified.

```php
add_action('ta_user_verified', function($user_id, $verification_data) {
    // Custom logic after user verification
}, 10, 2);
```

#### `ta_user_verification_failed`
Fired when user verification fails.

```php
add_action('ta_user_verification_failed', function($user_id, $error) {
    // Handle verification failure
}, 10, 2);
```

### Filters

#### `ta_verification_button_text`
Modify the verification button text.

```php
add_filter('ta_verification_button_text', function($text) {
    return 'Custom Verification Text';
});
```

#### `ta_verification_requirements`
Modify verification requirements.

```php
add_filter('ta_verification_requirements', function($requirements) {
    $requirements['custom_check'] = true;
    return $requirements;
});
```

## 🐛 Troubleshooting

### Common Issues

#### OAuth Configuration
**Problem**: OAuth flow not working
**Solution**: Verify client ID, secret, and redirect URI in settings

#### Shortcode Not Displaying
**Problem**: Shortcodes not rendering
**Solution**: Check if shortcodes are registered and theme compatibility

#### User Verification Issues
**Problem**: Users not being verified
**Solution**: Check OAuth flow and error logs

### Debug Mode

Enable debug mode by adding to `wp-config.php`:
```php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
```

Check logs at `/wp-content/debug.log`

### Support

For support and issues:
- WordPress.org plugin support forum
- GitHub issues (if using Git)
- Atmosvere documentation

## 📄 License

This plugin is licensed under the GPL v2 or later.

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Follow WordPress coding standards
5. Test thoroughly
6. Submit a pull request

## 📈 Changelog

### 3.0.3
- Complete code refactoring and architecture improvement
- Enhanced security with nonce verification and input sanitization
- Improved error handling and comprehensive logging
- New admin interface with dashboard and statistics
- Enhanced shortcodes with better attributes and error handling
- Modular class structure for better maintainability
- Comprehensive documentation and inline code comments
- Performance optimizations and efficient database queries
- Better internationalization support
- Enhanced user management with bulk actions

### 3.0.2
- Fixed developer console linking

### 3.0.1
- User verification information in user list
- User verification details in user profile
- Added email validation
- Added browser fingerprints
- Added VoIP checks
- Simplified user verification flow

### 2.0.4
- Plugin Description Updated

### 2.0.3
- Fixed Branding for Login with Trusted
- Plugin Description Updated

### 2.0.2
- Release fixes

### 2.0.1
- Update verification styling
- Custom platform branding added
- Get email of verified user

### 1.5.22
- Readme updated
- Wording & Links Updated

### 1.5.21
- Readme updated
- Translations updated
- Login form updated

### 1.5.20
- "Login with Trusted" toggle added
- Fixed verification button in user profile
- Design update

### 1.5.19
- Registration process improved
- Design update

### 1.5.18
- Login link fixed
- Design improvements

### 1.5.17
- "Reply to" bug fix
- Translations

### 1.5.16
- Design bug fixes

### 1.5.15
- Design bug fixes

### 1.5.14
- Initial Setup added
- Login with Trusted flow
- Register with Trusted added
- Design bug fixes

### 1.5.13
- Improved UX

### 1.5.12
- Bugfix comment reply
- Stylings

### 1.5.11
- Enabled direct verification
- Improved UX
- Design update

### 1.5.10
- New user navigation feature added
- Styling

### 1.5.8
- Mobile setup dialog fixes
- User flow improvements

### 1.5.7
- Login with Trusted added
- Set up profile popup added
- Bugfixes & Styling

### 1.5.6
- Bugfix for usernames
- Updated designs

### 1.5.5
- Added translations
- Updated designs

### 1.5.4
- Improved Login flow
- Updated user flows
- Updated designs

### 1.5.3
- Fixed Success Message
- Improved setup flow
- Wording updated
- Added Dark Mode

### 1.5.2
- Bugfixes
- Design update

### 1.5.0
- Bugfixes
- Stable version
- Design update
- Easier user verification process

### 1.4.2
- Bugfixes
- Stable version

### 1.4.1
- Compatible with forums
- Only allow Trusted registration added
- Bugfixes
- Refactoring

### 1.3.4
- Bugfixes
- Refactoring

### 1.3.3
- Stylings
- Bugfixes

### 1.3.2
- Feature complete
- Battle tested

## 🔗 Links

- [WordPress.org Plugin Page](https://wordpress.org/plugins/trusted-accounts/)
- [Atmosvere Documentation](https://docs.trustedaccounts.com)
- [Support Forum](https://wordpress.org/support/plugin/trusted-accounts/)

## Enhanced Status Message System

The plugin now provides a comprehensive status message system that offers:

### Success Messages
- **Verification Successful**: Confirms successful identity verification
- **Account Restrictions Lifted**: Notifies when account restrictions are removed after verification

### Error Messages
- **Verification Failed**: General verification failure with retry option
- **Authentication Error**: OAuth-specific authentication errors
- **Network Error**: Connection issues with retry guidance
- **Timeout Error**: Request timeout with retry option
- **Configuration Error**: Setup issues requiring admin attention
- **Server Error**: Atmosvere service issues
- **Access Denied**: Permission-related errors

### Warning Messages
- **Account Already Verified**: When Trusted Account is already in use
- **Login Not Available**: When login with Trusted is disabled
- **Service Temporarily Unavailable**: Maintenance notifications

### Information Messages
- **Verification Cancelled**: User-initiated cancellation
- **Request Timeout**: Timeout notifications with retry options

### Features
- **Auto-hide**: Messages automatically disappear after appropriate timeouts
- **Manual Close**: Users can dismiss messages manually
- **Action Buttons**: Contextual actions like "Try Again" or "Go Home"
- **Mobile Responsive**: Optimized for mobile devices
- **Accessibility**: Proper ARIA labels and keyboard navigation
- **Smooth Animations**: Slide-in/out animations for better UX

## 📄 License

This plugin is licensed under the GPL v2 or later.

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Follow WordPress coding standards
5. Test thoroughly
6. Submit a pull request

## 📈 Changelog

### Version 3.0.3
- Enhanced status message system with specific error handling
- Improved UX with modern message design
- Added auto-hide functionality for status messages
- Better mobile responsiveness
- Comprehensive error categorization
- Action buttons for better user guidance