Ryan Malloy
120f0b616d
- Add .distignore (operator-private files excluded) - Add build.sh for WordPress-installable release ZIPs - Update CLAUDE.md references (now operator-private only)
162 lines
5.1 KiB
Markdown
162 lines
5.1 KiB
Markdown
# TigerStyle Scent OAuth2 Documentation Site
|
|
|
|
## 🎯 Overview
|
|
|
|
This is the documentation site for TigerStyle Scent OAuth2 - the WordPress community's security exemplar. Built with Astro + Starlight + Alpine.js, it demonstrates enterprise-grade documentation practices that match the quality of our OAuth2 plugin.
|
|
|
|
## 🏗️ Architecture
|
|
|
|
- **Framework**: Astro + Starlight
|
|
- **Interactivity**: Alpine.js (no heavy JavaScript frameworks)
|
|
- **Content Structure**: Diataxis framework
|
|
- **Deployment**: Caddy static file server with Docker Compose
|
|
- **Domain**: `scent.$DOMAIN` via Caddy Docker Proxy
|
|
|
|
## 📚 Content Structure (Diataxis Framework)
|
|
|
|
### 📖 Tutorials (Learning-oriented)
|
|
- **Your First OAuth2 Server** - 45-minute hands-on tutorial
|
|
- *Future*: Building Client Applications, PKCE Implementation, Advanced Security
|
|
|
|
### 🔧 How-to Guides (Problem-solving)
|
|
- **Fix SQL Injection Vulnerabilities** - Practical security remediation
|
|
- *Future*: Rate Limiting Setup, CSRF Protection, Production Deployment
|
|
|
|
### 🧠 Explanations (Understanding-oriented)
|
|
- **OAuth2 Security Architecture** - Deep dive into 7-layer security model
|
|
- *Future*: WordPress Integration Philosophy, Threat Landscape Evolution
|
|
|
|
### 📋 Reference (Information-oriented)
|
|
- **Authorization Endpoint API** - Complete technical specification
|
|
- *Future*: Token Endpoint, Introspection Endpoint, Error Codes
|
|
|
|
## ⚡ Interactive Features
|
|
|
|
### OAuth2 Flow Demo
|
|
- Step-by-step interactive walkthrough
|
|
- Live code examples for each flow step
|
|
- Visual progress tracking with Alpine.js
|
|
|
|
### Security Checklist
|
|
- Dynamic progress tracking
|
|
- Critical vs. optional security features
|
|
- Real-time security score calculation
|
|
|
|
## 🚀 Development
|
|
|
|
### Local Development
|
|
```bash
|
|
# Start development server
|
|
npm run dev
|
|
|
|
# Build for production
|
|
npm run build
|
|
|
|
# Deploy to Docker environment
|
|
./deploy.sh
|
|
```
|
|
|
|
### Docker Deployment
|
|
```bash
|
|
# Start documentation site
|
|
docker compose --profile with-docs up -d docs-site
|
|
|
|
# Check status
|
|
docker compose ps
|
|
docker compose logs docs-site
|
|
```
|
|
|
|
## 🌐 Access
|
|
|
|
- **Local Development**: http://localhost:4331/
|
|
- **Docker Environment**: Available at `scent.$DOMAIN` via Caddy Docker Proxy
|
|
- **Health Check**: `curl http://docs-site/health`
|
|
|
|
## 🎨 Design System
|
|
|
|
### TigerStyle Branding
|
|
- **Primary Color**: `#ff6b35` (TigerStyle Orange)
|
|
- **Accent Colors**: Gold (`#ffd700`), Amber (`#ffb347`)
|
|
- **Security Colors**: Green (`#28a745`), Red (`#dc3545`), Blue (`#007bff`)
|
|
|
|
### Cat-Themed Elements
|
|
- **Border Radius**: `--cat-paw-radius: 12px`
|
|
- **Interactive Elements**: Paw print indicators
|
|
- **Terminology**: Scent Tokens, Territory Codes, Pride Authentication
|
|
|
|
### Component Library
|
|
- `OAuth2FlowDemo.astro` - Interactive flow demonstration
|
|
- `SecurityChecklist.astro` - Dynamic security checklist
|
|
- Custom CSS variables for consistent theming
|
|
|
|
## 📊 Performance Features
|
|
|
|
- **Static Site Generation**: Lightning-fast loading
|
|
- **Search Integration**: Pagefind for instant content search
|
|
- **Responsive Design**: Mobile-first approach
|
|
- **Compression**: Gzip enabled via Caddy
|
|
- **Caching**: Optimized cache headers for assets
|
|
|
|
## 🔐 Security Headers
|
|
|
|
All pages include comprehensive security headers:
|
|
- `X-Frame-Options: DENY`
|
|
- `X-XSS-Protection: 1; mode=block`
|
|
- `X-Content-Type-Options: nosniff`
|
|
- `Content-Security-Policy` for documentation sites
|
|
- Custom `X-Security-Exemplar` header
|
|
|
|
## 🛠️ Technology Stack
|
|
|
|
- **Astro 5.13.8**: Modern static site generator
|
|
- **Starlight 0.35.3**: Documentation theme
|
|
- **Alpine.js 3.15.0**: Lightweight JavaScript interactivity
|
|
- **Tailwind CSS 6.0.2**: Utility-first styling
|
|
- **Caddy**: High-performance web server
|
|
- **Docker Compose**: Container orchestration
|
|
|
|
## 📈 Analytics & Monitoring
|
|
|
|
- **Built-in Search**: Pagefind indexing
|
|
- **Health Monitoring**: `/health` endpoint
|
|
- **Access Logs**: Caddy logging to `/var/log/caddy/`
|
|
- **Performance Metrics**: Pagespeed optimized
|
|
|
|
## 🚀 Future Enhancements
|
|
|
|
### Content Expansion
|
|
- [ ] Complete all Diataxis sections (16 planned pages)
|
|
- [ ] Video tutorials for complex OAuth2 flows
|
|
- [ ] Interactive security testing tools
|
|
- [ ] WordPress plugin integration examples
|
|
|
|
### Technical Improvements
|
|
- [ ] Multi-language support
|
|
- [ ] Advanced search with filters
|
|
- [ ] Progressive Web App features
|
|
- [ ] Analytics dashboard integration
|
|
|
|
### Community Features
|
|
- [ ] Contribution guidelines
|
|
- [ ] Community showcase
|
|
- [ ] Security vulnerability reporting
|
|
- [ ] Plugin ecosystem integration
|
|
|
|
## 🦸♂️ Mission: Security Exemplar
|
|
|
|
This documentation site serves as proof that the WordPress community can achieve enterprise-grade standards in both:
|
|
|
|
1. **Security Implementation** (the OAuth2 plugin)
|
|
2. **Documentation Quality** (this site)
|
|
|
|
By setting these standards, we demonstrate what's possible when developers prioritize user protection and community education over shortcuts and convenience.
|
|
|
|
## 📞 Support
|
|
|
|
- **GitHub Issues**: Report bugs and feature requests
|
|
- **Security Issues**: Responsible disclosure via security@tigerstyle.dev
|
|
- **Community**: WordPress OAuth2 Security Discussion Forum
|
|
|
|
---
|
|
|
|
**🎉 The WordPress community deserves this level of excellence. We've delivered it.** 🦸♂️📚 |