Add detailed OAuth documentation and configuration examples

- Updated `ARCHITECTURE.md` with thorough explanations of OAuth Consumer and Provider modes, supported flows, security features, and endpoints.
- Enhanced `.env.template` with environment variables for OAuth Provider mode setup.
- Expanded `README.md` to highlight OAuth Provider mode capabilities and MCP integration features.
- Added OAuth configuration section to `AGENTS.md`, including key settings for both social login and provider mode.

.env.demo

@@ -40,6 +40,12 @@ OAUTH_AUTO_LINK_BY_EMAIL=true
 # OAUTH_GITHUB_CLIENT_ID=your-github-client-id
 # OAUTH_GITHUB_CLIENT_SECRET=your-github-client-secret
 
+# OAuth Provider Mode (Authorization Server for MCP/third-party clients)
+# Set OAUTH_PROVIDER_ENABLED=true to act as an OAuth 2.0 Authorization Server
+OAUTH_PROVIDER_ENABLED=true
+# IMPORTANT: Must be HTTPS in production!
+OAUTH_ISSUER=http://localhost:8000
+
 # Frontend settings
 FRONTEND_PORT=3000
 FRONTEND_URL=http://localhost:3000

.env.template

@@ -40,6 +40,12 @@ OAUTH_AUTO_LINK_BY_EMAIL=true
 # OAUTH_GITHUB_CLIENT_ID=your-github-client-id
 # OAUTH_GITHUB_CLIENT_SECRET=your-github-client-secret
 
+# OAuth Provider Mode (Authorization Server for MCP/third-party clients)
+# Set OAUTH_PROVIDER_ENABLED=true to act as an OAuth 2.0 Authorization Server
+OAUTH_PROVIDER_ENABLED=false
+# IMPORTANT: Must be HTTPS in production!
+OAUTH_ISSUER=http://localhost:8000
+
 # Frontend settings
 FRONTEND_PORT=3000
 FRONTEND_URL=http://localhost:3000

AGENTS.md

@@ -90,6 +90,26 @@ Full OAuth 2.0 Authorization Server for MCP (Model Context Protocol) clients:
 
 **Scopes supported:** `openid`, `profile`, `email`, `read:users`, `write:users`, `admin`
 
+**OAuth Configuration (backend `.env`):**
+```bash
+# OAuth Social Login (as OAuth Consumer)
+OAUTH_ENABLED=true                           # Enable OAuth social login
+OAUTH_AUTO_LINK_BY_EMAIL=true                # Auto-link accounts by email
+OAUTH_STATE_EXPIRE_MINUTES=10                # CSRF state expiration
+
+# Google OAuth
+OAUTH_GOOGLE_CLIENT_ID=your-google-client-id
+OAUTH_GOOGLE_CLIENT_SECRET=your-google-client-secret
+
+# GitHub OAuth
+OAUTH_GITHUB_CLIENT_ID=your-github-client-id
+OAUTH_GITHUB_CLIENT_SECRET=your-github-client-secret
+
+# OAuth Provider Mode (as Authorization Server for MCP)
+OAUTH_PROVIDER_ENABLED=true                  # Enable OAuth provider mode
+OAUTH_ISSUER=https://api.yourdomain.com      # JWT issuer URL (must be HTTPS in production)
+```
+
 ### Database Pattern
 - **Async SQLAlchemy 2.0** with PostgreSQL
 - **Connection pooling**: 20 base connections, 50 max overflow

README.md

@@ -53,12 +53,25 @@ Whether you're building a SaaS, an internal tool, or a side project, PragmaStack
 ### 🔐 **Authentication & Security**
 - JWT-based authentication with access + refresh tokens
 - **OAuth/Social Login** (Google, GitHub) with PKCE support
+- **OAuth 2.0 Authorization Server** (MCP-ready) for third-party integrations
 - Session management with device tracking and revocation
 - Password reset flow (email integration ready)
 - Secure password hashing (bcrypt)
 - CSRF protection, rate limiting, and security headers
 - Comprehensive security tests (JWT algorithm attacks, session hijacking, privilege escalation)
 
+### 🔌 **OAuth Provider Mode (MCP Integration)**
+Full OAuth 2.0 Authorization Server for Model Context Protocol (MCP) and third-party clients:
+- **RFC 7636**: Authorization Code Flow with PKCE (S256 only)
+- **RFC 8414**: Server metadata discovery at `/.well-known/oauth-authorization-server`
+- **RFC 7662**: Token introspection endpoint
+- **RFC 7009**: Token revocation endpoint
+- **JWT access tokens**: Self-contained, configurable lifetime
+- **Opaque refresh tokens**: Secure rotation, database-backed revocation
+- **Consent management**: Users can review and revoke app permissions
+- **Client management**: Admin endpoints for registering OAuth clients
+- **Scopes**: `openid`, `profile`, `email`, `read:users`, `write:users`, `admin`
+
 ### 👥 **Multi-Tenancy & Organizations**
 - Full organization system with role-based access control (Owner, Admin, Member)
 - Invite/remove members, manage permissions

backend/docs/ARCHITECTURE.md

@@ -818,6 +818,84 @@ def add_member(
     pass
 ```
 
+### OAuth Integration
+
+The system supports two OAuth modes:
+
+#### OAuth Consumer Mode (Social Login)
+
+Users can authenticate via Google or GitHub OAuth providers:
+
+```python
+# Get authorization URL with PKCE support
+GET /oauth/authorize/{provider}?redirect_uri=https://yourapp.com/callback
+
+# Handle callback and exchange code for tokens
+POST /oauth/callback/{provider}
+{
+    "code": "authorization_code_from_provider",
+    "state": "csrf_state_token"
+}
+```
+
+**Security Features:**
+- PKCE (S256) for Google
+- State parameter for CSRF protection
+- Nonce for Google OIDC replay attack prevention
+- Google ID token signature verification via JWKS
+- Email normalization to prevent account duplication
+- Auto-linking by email (configurable)
+
+#### OAuth Provider Mode (MCP Integration)
+
+Full OAuth 2.0 Authorization Server for third-party clients (RFC compliant):
+
+```
+┌─────────────┐                              ┌─────────────┐
+│ MCP Client  │                              │   Backend   │
+└──────┬──────┘                              └──────┬──────┘
+       │                                             │
+       │  GET /.well-known/oauth-authorization-server│
+       │─────────────────────────────────────────────>│
+       │                 {metadata}                  │
+       │<─────────────────────────────────────────────│
+       │                                             │
+       │  GET /oauth/provider/authorize              │
+       │  ?response_type=code&client_id=...          │
+       │  &redirect_uri=...&code_challenge=...       │
+       │─────────────────────────────────────────────>│
+       │                                             │
+       │              (User consents)                │
+       │                                             │
+       │  302 redirect_uri?code=AUTH_CODE&state=...  │
+       │<─────────────────────────────────────────────│
+       │                                             │
+       │  POST /oauth/provider/token                 │
+       │  {grant_type=authorization_code,            │
+       │   code=AUTH_CODE, code_verifier=...}        │
+       │─────────────────────────────────────────────>│
+       │                                             │
+       │  {access_token, refresh_token, expires_in}  │
+       │<─────────────────────────────────────────────│
+       │                                             │
+```
+
+**Endpoints:**
+- `GET /.well-known/oauth-authorization-server` - RFC 8414 metadata
+- `GET /oauth/provider/authorize` - Authorization endpoint
+- `POST /oauth/provider/token` - Token endpoint (authorization_code, refresh_token)
+- `POST /oauth/provider/revoke` - RFC 7009 token revocation
+- `POST /oauth/provider/introspect` - RFC 7662 token introspection
+
+**Security Features:**
+- PKCE S256 required for public clients (plain method rejected)
+- Authorization codes are single-use with 10-minute expiry
+- Code reuse detection triggers security incident (all tokens revoked)
+- Refresh token rotation on use
+- Opaque refresh tokens (hashed in database)
+- JWT access tokens with standard claims
+- Consent management per client
+
 ## Error Handling
 
 ### Exception Hierarchy