# BaseCloud Shield

[![WordPress Plugin Version](https://img.shields.io/badge/version-1.5.0-blue.svg)](https://github.com/BaseCloudGlobal/BaseCloudShield)
[![License](https://img.shields.io/badge/license-GPL--2.0-green.svg)](https://www.gnu.org/licenses/gpl-2.0.html)
[![WordPress](https://img.shields.io/badge/wordpress-5.0%2B-blue.svg)](https://wordpress.org/)
[![PHP](https://img.shields.io/badge/php-7.4%2B-purple.svg)](https://www.php.net/)

Enterprise-grade Two-Factor Authentication (2FA) plugin for WordPress with support for standard Email, SendGrid API, and BaseCloud CRM Webhooks.

## 🛡️ Features

### Core Security
- ✅ **Two-Factor Authentication (2FA)** - Protects all WordPress logins with OTP codes
- ✅ **6-Digit OTP Codes** - Secure one-time passwords that automatically expire
- ✅ **Browser Trust** - "Remember this device" functionality reduces friction
- ✅ **Configurable Validity** - Set OTP expiration time (1-30 minutes)

### Delivery Methods
- 📧 **Standard WordPress Email** - Works out of the box with `wp_mail()`
- 🚀 **SendGrid API V3** - Premium email delivery with improved reliability
- 🔗 **BaseCloud CRM Webhooks** - Connect to external systems for SMS, WhatsApp, etc.

### Advanced Features
- 👤 **Central Manager Email** - Route ALL login OTPs to a single administrator email
- 🎨 **Professional Interface** - Beautiful admin panel and OTP verification screen
- ⚡ **Zero Bloat** - Lightweight and fast, focused on core functionality
- 🔧 **Agency-Friendly** - Perfect for managing multiple client sites

## 📸 Screenshots

![Settings Panel](assets/screenshot-1.png)
*Professional settings interface with all configuration options*

![OTP Verification](assets/screenshot-2.png)
*Clean, user-friendly OTP verification screen*

## 🚀 Installation

### From WordPress.org (Recommended)
1. Go to WordPress admin → Plugins → Add New
2. Search for "BaseCloud Shield"
3. Click "Install Now" and then "Activate"
4. Go to "BC Shield" in the admin menu to configure

### Manual Installation
1. Download the latest release from [GitHub Releases](https://github.com/BaseCloudGlobal/BaseCloudShield/releases)
2. Upload the `basecloud-shield` folder to `/wp-content/plugins/`
3. Activate the plugin through the WordPress Plugins menu
4. Configure settings under "BC Shield" menu

### From Source (Development)
```bash
git clone https://github.com/BaseCloudGlobal/BaseCloudShield.git
cd BaseCloudShield
# Copy to WordPress plugins directory
```

## ⚙️ Configuration

### Basic Setup (Standard Email)
1. Navigate to **BC Shield** in WordPress admin
2. Toggle **Enable 2FA** to ON
3. Select **Standard WP Email** as delivery method
4. Save Configuration

That's it! 2FA is now active for all user logins.

### Central Manager Email (Agency Mode)
Perfect for agencies managing client sites:

1. Go to **BC Shield** settings
2. Enter your **Manager Email** (e.g., `admin@agency.com`)
3. Save Configuration

Now ALL login OTPs from this site will be sent to your central email, regardless of which user is logging in.

### SendGrid Integration
For improved email deliverability:

1. Create a SendGrid account at [sendgrid.com](https://sendgrid.com)
2. Generate an API key with "Mail Send" permissions
3. In **BC Shield** settings:
   - Select **SendGrid API** as delivery method
   - Enter your **SendGrid API Key**
   - Set **From Email Address** (must be verified in SendGrid)
4. Save Configuration

### BaseCloud CRM Webhook
For advanced automation (SMS, WhatsApp, logging):

1. Set up your webhook endpoint (must accept POST requests)
2. In **BC Shield** settings:
   - Select **BaseCloud CRM Webhook** as delivery method
   - Enter your **Webhook URL**
3. Save Configuration

**Webhook Payload:**
```json
{
  "site_name": "Example Site",
  "username": "john_doe",
  "email": "user@example.com",
  "otp_code": "123456",
  "timestamp": "2026-01-19 12:00:00"
}
```

## 🔐 How It Works

### Authentication Flow

```
User enters credentials
         ↓
WordPress authenticates
         ↓
BaseCloud Shield intercepts
         ↓
Generates 6-digit OTP
         ↓
Sends via selected method
         ↓
User enters OTP
         ↓
Verification successful
         ↓
Access granted
```

### Browser Trust System
Once a user successfully verifies their OTP, a secure cookie is set for 12 hours. During this time, they won't need to enter an OTP again from that browser.

**Security Notes:**
- Cookie is device-specific
- Uses MD5 hash of user ID + salt
- Automatically expires after 12 hours
- Can be cleared by logging out

## 📋 Requirements

- **WordPress**: 5.0 or higher
- **PHP**: 7.4 or higher
- **MySQL**: 5.6 or higher

### Optional Requirements
- **SendGrid Account**: For SendGrid API integration
- **Webhook Endpoint**: For CRM webhook integration
- **HTTPS**: Strongly recommended for security

## 🛠️ Development

### Repository Structure
```
BaseCloudShield/
├── basecloud-shield.php    # Main plugin file
├── readme.txt              # WordPress.org readme
├── package.json            # NPM scripts for deployment
├── deploy.ps1              # PowerShell deployment script
├── deploy.php              # PHP deployment script
├── deploy.bat              # Batch deployment script
├── version-helper.php      # Version management utilities
├── DEPLOYMENT.md           # Deployment documentation
├── ASSETS.md               # Asset management guide
├── assets/                 # WordPress.org assets
│   ├── icon-128x128.png
│   ├── icon-256x256.png
│   ├── banner-772x250.png
│   └── banner-1544x500.png
└── svn-repo/              # WordPress.org SVN checkout
    ├── assets/
    ├── trunk/
    └── tags/
```

### Deployment

See [DEPLOYMENT.md](DEPLOYMENT.md) for complete deployment guide.

**Quick Deploy:**
```powershell
# Patch version (1.0.0 → 1.0.1)
.\deploy.ps1 patch

# Minor version (1.0.0 → 1.1.0)
.\deploy.ps1 minor

# Major version (1.0.0 → 2.0.0)
.\deploy.ps1 major
```

### Coding Standards
- Follows WordPress Coding Standards
- PSR-4 autoloading compatible
- Secure by default (input sanitization, output escaping)
- Well-documented code

## 🔌 Compatibility

### WordPress Environments
- ✅ Standard WordPress installations
- ✅ Multisite networks
- ✅ WooCommerce
- ✅ Custom login pages
- ✅ REST API authentication

### Email Services
- ✅ WordPress default mail
- ✅ SendGrid API
- ✅ Most SMTP plugins (WP Mail SMTP, Easy WP SMTP, etc.)
- ✅ Custom mail handlers

### Tested With
- WordPress 5.0 - 6.9
- PHP 7.4 - 8.3
- MySQL 5.6 - 8.0
- Major hosting providers (SiteGround, WP Engine, Kinsta, etc.)

## 🚨 Security Considerations

### Best Practices
1. **Always use HTTPS** - Protects OTP codes in transit
2. **Use strong passwords** - 2FA is an additional layer, not a replacement
3. **Keep WordPress updated** - Security patches are critical
4. **Verify SendGrid sender** - Required for SendGrid API
5. **Secure webhook endpoints** - Use HTTPS and authentication

### Privacy & Data
- **OTP codes** are stored temporarily (10 minutes by default)
- **No passwords** are ever stored or transmitted
- **Email addresses** are only sent to configured services
- **Browser trust cookies** use hashed identifiers

### External Services
This plugin may connect to:
- **SendGrid API** - Only if configured (optional)
- **Custom Webhooks** - Only if configured (optional)
- **WordPress email** - Default functionality

See [readme.txt](readme.txt) for full external services disclosure.

## 🆘 Troubleshooting

### I'm locked out!
If you lose access to your email or the delivery method fails:

1. Access your site via FTP/SFTP
2. Navigate to `/wp-content/plugins/`
3. Rename `basecloud-shield` to `basecloud-shield-disabled`
4. Log in normally
5. Fix the issue and re-enable the plugin

### OTP emails not arriving
1. **Check spam folder** - OTP emails may be filtered
2. **Test WordPress email** - Try the WP Mail SMTP Test feature
3. **Verify SendGrid API key** - Ensure permissions are correct
4. **Check manager email** - If set, OTPs go there, not user email
5. **Review email logs** - Check hosting provider logs

### SendGrid integration not working
1. **Verify API key** - Ensure "Mail Send" permission is granted
2. **Verify sender email** - Must be verified in SendGrid
3. **Check SendGrid dashboard** - Review activity logs
4. **Test API key** - Use SendGrid's API testing tools

### Webhook not receiving data
1. **Verify URL** - Ensure endpoint is accessible
2. **Check HTTPS** - Some servers require secure connections
3. **Review webhook logs** - Check your endpoint's logs
4. **Test with RequestBin** - Use a service like RequestBin to debug

## 📞 Support

### Community Support
- **WordPress.org Forums**: [Plugin Support](https://wordpress.org/support/plugin/basecloud-shield/)
- **GitHub Issues**: [Report Bugs](https://github.com/BaseCloudGlobal/BaseCloudShield/issues)

### Professional Support
- **Website**: [basecloudglobal.com](https://www.basecloudglobal.com/)
- **Email**: support@basecloudglobal.com

### Documentation
- [DEPLOYMENT.md](DEPLOYMENT.md) - Deployment guide
- [ASSETS.md](ASSETS.md) - Asset management
- [readme.txt](readme.txt) - WordPress.org readme

## 🗺️ Roadmap

### Version 1.1
- [ ] User-specific 2FA settings (enable/disable per user)
- [ ] Backup codes for emergency access
- [ ] Rate limiting for OTP attempts
- [ ] Activity logs and audit trail

### Version 1.2
- [ ] Mobile app support (TOTP)
- [ ] SMS integration via Twilio
- [ ] WhatsApp Business API integration
- [ ] Custom OTP templates

### Version 2.0
- [ ] Biometric authentication support
- [ ] Multi-factor options (OTP + Security questions)
- [ ] Advanced admin controls
- [ ] White-label capabilities

## 🤝 Contributing

We welcome contributions! Here's how you can help:

1. **Report bugs** - Open an issue on GitHub
2. **Suggest features** - Discuss ideas in Issues
3. **Submit pull requests** - Fork, code, and PR
4. **Improve documentation** - Fix typos, add examples
5. **Translate** - Help translate the plugin

### Development Setup
```bash
git clone https://github.com/BaseCloudGlobal/BaseCloudShield.git
cd BaseCloudShield
# Make your changes
git checkout -b feature/your-feature-name
git commit -m "Add your feature"
git push origin feature/your-feature-name
# Open a pull request
```

## 📄 License

This plugin is licensed under the [GPL v2 or later](https://www.gnu.org/licenses/gpl-2.0.html).

```
BaseCloud Shield - Enterprise 2FA Security for WordPress
Copyright (C) 2026 BaseCloud Team

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
```

## 🌟 Credits

**Developed by**: [BaseCloud Team](https://www.basecloudglobal.com/)  
**Contributors**: See [GitHub Contributors](https://github.com/BaseCloudGlobal/BaseCloudShield/graphs/contributors)

### Built With
- WordPress Plugin API
- SendGrid API V3
- Modern PHP practices
- Love ❤️ and coffee ☕

## 📊 Statistics

- **Active Installations**: Coming soon
- **Average Rating**: ⭐⭐⭐⭐⭐ (Be the first to review!)
- **Downloads**: Track on WordPress.org
- **Latest Version**: 1.5.0

---

**Made with ❤️ by BaseCloud Team**

*Secure your WordPress. Protect your users. Deploy with confidence.*