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.

---

🐾 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

Latest release: v1.0.0 · All releases

Prerequisites

• WordPress 5.0+
• PHP 7.4+
• MySQL 5.7+
• HTTPS strongly recommended (required for production OAuth2 flows)

Via WordPress Admin (GUI)

1. Download tigerstyle-scent-1.0.0.zip
2. In WordPress admin: Plugins → Add New → Upload Plugin, pick the ZIP
3. Click Activate Plugin — settings appear under TigerStyle Scent in the sidebar
4. Configure your territory: navigate to TigerStyle Scent → Scent Profiles → Add New

Via WP-CLI (terminal)

wp plugin install \
  https://git.supported.systems/tigerstyle/tigerstyle-scent/releases/download/v1.0.0/tigerstyle-scent-1.0.0.zip \
  --activate

---

🎯 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:

   # 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

# 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

{
  "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

// 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

// 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

# 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:

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

// 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:

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

---

🐯 Made with ❤️ by TigerStyle

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

Website • Documentation • Support