tigerstyle-scent/README.md

# 👃 TigerStyle Scent

**Enterprise OAuth2 Authentication - Leave Your Digital Scent Trail**

*Just like cats authenticate each other through scent, TigerStyle Scent provides secure OAuth2 authentication for your WordPress territory.*

[![Version](https://img.shields.io/badge/version-1.0.0-orange.svg?style=for-the-badge)](https://github.com/tigerstyle/scent)
[![WordPress](https://img.shields.io/badge/WordPress-5.0%2B-blue.svg?style=for-the-badge)](https://wordpress.org)
[![PHP](https://img.shields.io/badge/PHP-7.4%2B-purple.svg?style=for-the-badge)](https://php.net)
[![OAuth2](https://img.shields.io/badge/OAuth2-RFC%206749-green.svg?style=for-the-badge)](https://tools.ietf.org/html/rfc6749)

---

## 🐾 Why TigerStyle Scent?

**Because authentication should be as natural as a cat's instincts!**

In the feline world, cats use scent to:
- 🏠 **Mark Territory** - Establish ownership and boundaries
- 👥 **Recognize Friends** - Identify trusted companions vs strangers  
- 📍 **Navigate Safely** - Follow familiar scent trails to safe locations
- ⚡ **Communicate Status** - Share information about hierarchy and access

TigerStyle Scent brings this same intuitive approach to digital authentication:

- **👃 Scent-Based Authentication**: OAuth2 tokens work like digital pheromones - unique signatures that identify and authorize users
- **🏰 Territory Control**: Secure access management for your WordPress domain with fine-grained permissions
- **🤝 Trust Verification**: Multi-layered authentication like cat social bonds - from basic recognition to deep trust relationships
- **⚡ Cat-Quick Response**: Lightning-fast OAuth2 flows with feline reflexes - sub-100ms token validation

---

## 🚀 Key Features

### 🐯 **OAuth2 Authorization Server**
Transform your WordPress site into a complete OAuth2 provider:
- ✅ **Territory Code Flow** (Authorization Code) with PKCE support
- ✅ **Client Scent Credentials Flow** for machine-to-machine auth
- ✅ **Refresh Scent Flow** for long-term access
- ✅ **Scent Analysis** (Token Introspection) for real-time validation
- ✅ **OpenID Connect** discovery endpoint

### 🏰 **Territory Management**
- **Scent Profiles**: Manage OAuth2 clients like cat identity cards
- **Territory Codes**: Temporary access codes (authorization codes)
- **Scent Tokens**: Long-lived access tokens with scope control
- **Refresh Scents**: Extended authentication for trusted clients

### 🔒 **Enterprise Security**
- **Multi-factor Scent Recognition**: Layered authentication mechanisms
- **Territory Boundaries**: Configurable redirect URI validation
- **Scent Trail Monitoring**: Comprehensive audit logging
- **Access Control Lists**: Fine-grained permission management

### 🎨 **Developer Experience**
- **Cat-Themed API**: Intuitive endpoints with feline metaphors
- **WordPress Integration**: Seamless WP REST API authentication
- **Plugin Architecture**: Extensible authenticator system
- **Debug Scent Trails**: Comprehensive logging and monitoring

---

## 📋 Installation

### Prerequisites
- WordPress 5.0 or higher
- PHP 7.4 or higher  
- MySQL 5.7 or higher
- HTTPS enabled (recommended for production)

### Quick Setup

1. **Clone the repository:**
   ```bash
   git clone https://github.com/tigerstyle/scent.git wp-content/plugins/tigerstyle-scent
   ```

2. **Activate the plugin:**
   - Go to WordPress Admin → Plugins
   - Find "🐯 TigerStyle Scent" 
   - Click "Activate"

3. **Configure your territory:**
   - Navigate to **TigerStyle Scent** in admin menu
   - Set your territory preferences
   - Create your first scent profile (OAuth2 client)

---

## 🎯 Quick Start Guide

### Creating Your First Scent Profile

1. **Add New Scent Profile:**
   ```
   WordPress Admin → TigerStyle Scent → Scent Profiles → Add New
   ```

2. **Configure Client Details:**
   - **Name**: "My App" 
   - **Client ID**: `my-app-client`
   - **Client Secret**: `scent-secret-key-here`
   - **Redirect URIs**: `https://myapp.com/callback`
   - **Scopes**: `basic profile email`

3. **Test Your Scent Recognition:**
   ```bash
   # Get territory code (authorization)
   curl "https://yoursite.com/oauth/authorize?response_type=code&client_id=my-app-client&redirect_uri=https://myapp.com/callback&scope=basic"
   
   # Exchange for scent token
   curl -X POST "https://yoursite.com/oauth/token" \
     -d "grant_type=authorization_code" \
     -d "code=TERRITORY_CODE" \
     -d "client_id=my-app-client" \
     -d "client_secret=scent-secret-key-here"
   ```

### Using Scent Tokens

```bash
# TigerStyle way (cat-themed) 🐯
curl -H "Authorization: ScentBearer YOUR_SCENT_TOKEN" \
     "https://yoursite.com/wp-json/wp/v2/users/me"

# Standard OAuth2 way (still works!) ✅  
curl -H "Authorization: Bearer YOUR_SCENT_TOKEN" \
     "https://yoursite.com/wp-json/wp/v2/users/me"
```

---

## 🛠️ API Reference

### OAuth2 Endpoints (Scent Detection Points)

| Endpoint | Purpose | Cat Metaphor |
|----------|---------|--------------|
| `/oauth/authorize` | Territory authorization | "May I enter your territory?" |
| `/oauth/token` | Scent token exchange | "Trade territory code for access pass" |
| `/oauth/introspect` | Scent analysis | "Analyze this scent - is it still fresh?" |
| `/oauth/revoke` | Scent removal | "Remove this scent from territory" |

### TigerStyle Custom Endpoints

| Endpoint | Purpose | Description |
|----------|---------|-------------|
| `/tigerstyle/scent-analysis` | Token introspection | Analyze scent token validity |
| `/tigerstyle/territory-status` | Server status | Check territory health |

### Scent Token Response

```json
{
  "access_token": "scent_abc123...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "refresh_xyz789...",
  "scope": "basic profile",
  "tigerstyle_token_type": "ScentBearer",
  "scent_strength": "strong"
}
```

**🎯 Backward Compatibility**: Returns standard OAuth2 `Bearer` token type for compatibility, but includes TigerStyle extensions. Both `Bearer` and `ScentBearer` headers work!

---

## 🔧 Configuration

### Plugin Settings

```php
// Territory security level
define('TIGERSTYLE_SCENT_SECURITY', 'high'); // low, medium, high

// Debug scent trails  
define('TIGERSTYLE_SCENT_DEBUG', true);

// Require HTTPS for production territory
define('TIGERSTYLE_SCENT_REQUIRE_HTTPS', true);
```

### WordPress Integration

```php
// Get current scent user
$user_id = tigerstyle_scent()->authenticate_user(0);

// Check territory access
$has_access = tigerstyle_scent_verify_access('profile');

// Log scent events
do_action('tigerstyle_scent_log', 'user_login', $user_data);
```

---

## 🧪 Testing Your Territory

### Manual Testing
```bash
# Test authorization flow
curl "https://yoursite.com/oauth/authorize?response_type=code&client_id=test&redirect_uri=https://httpbin.org/anything&scope=basic"

# Validate scent token
curl -X POST "https://yoursite.com/tigerstyle/scent-analysis" \
  -d "token=YOUR_SCENT_TOKEN"
```

---

## 🎨 Customization

### Custom Scent Authenticators

Create your own scent detection methods:

```php
class MyCustomScent implements TigerStyleScent_AuthenticatorInterface {
    public function authenticate() {
        // Custom authentication logic
        return $user_id ?: false;
    }
    
    public function get_type(): string {
        return 'custom_scent';
    }
    
    public function get_priority(): int {
        return 15; // Priority in authentication chain
    }
    
    public function can_handle_request(): bool {
        return isset($_SERVER['HTTP_X_CUSTOM_AUTH']);
    }
}

// Register your authenticator
add_filter('tigerstyle_scent_authenticators', function($authenticators) {
    $authenticators['custom'] = new MyCustomScent();
    return $authenticators;
});
```

### Territory Hooks

```php
// Before scent authentication
add_action('tigerstyle_scent_before_auth', function($token) {
    // Pre-authentication logic
});

// Successful scent recognition
add_action('tigerstyle_scent_authenticated', function($user_id, $client_id) {
    // Log successful authentication
});

// Failed authentication attempt
add_action('tigerstyle_scent_auth_failed', function($token) {
    // Handle failed authentication
});
```

---

## 🔍 Troubleshooting

### Common Issues

**🚫 "Territory access denied"**
- Check client credentials match exactly
- Verify redirect URI is registered
- Ensure HTTPS if required

**❌ "Invalid scent token"**  
- Token may have expired (default: 1 hour)
- Try both formats: `Bearer TOKEN_HERE` or `ScentBearer TOKEN_HERE`
- Verify database connection

**🔄 "Territory code expired"**
- Authorization codes expire in 10 minutes
- Don't reuse codes (one-time use only)
- Check system time synchronization

### Debug Mode

Enable scent trail debugging:

```php
define('TIGERSTYLE_SCENT_DEBUG', true);
```

Check WordPress debug logs for detailed scent analysis.

---

## 📄 License

TigerStyle Scent is licensed under the GPL v2 or later.

```
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.
```

---

## 🙏 Acknowledgments

- **WordPress Core Team** - For the amazing platform
- **OAuth2 Working Group** - For the OAuth2 specification  
- **The Feline Community** - For inspiration on territorial behavior
- **TigerStyle Team** - For making enterprise auth purr-fect

---

<div align="center">

**🐯 Made with ❤️ by TigerStyle**

*Authentication that's as natural as a cat's instinct*

[Website](https://tigerstyle.com) • [Documentation](https://docs.tigerstyle.com) • [Support](https://support.tigerstyle.com)

</div>