`DW-Agents/dw-agents/global-auth-system/README.md`

261 lines
# 🔐 DW Global Authentication System

**Complete Google OAuth SSO with SMS 2FA for all DW-Agents**

## Quick Start

```bash
cd /root/DW-Agents/global-auth-system
./quick-start.sh
```

## What You Get

✅ **Google OAuth 2.0** - Secure single sign-on
✅ **SMS 2FA** - Required after 4 hours
✅ **Session Tracking** - Monitor all user activity
✅ **Security Alerts** - Automatic threat detection
✅ **Legal Compliance** - Terms acceptance + email verification
✅ **Admin Dashboard** - User management interface
✅ **Error Tracking** - Session errors assigned to agents
✅ **Blocked Users** - Automatic suspicious account blocking

## Access

- **Login Portal**: http://45.61.58.125:9999/login
- **Security Dashboard**: http://45.61.58.125:9892/ (Security Agent)

## Features

### Authentication Flow
1. Google OAuth login
2. Terms acceptance
3. 4-hour session created
4. After 4 hours: SMS verification required
5. Session extends for 4 more hours

### Session Management
- **Duration**: 4 hours maximum
- **Extension**: SMS verification required
- **Tracking**: IP, user agent, accessed agents, error logs
- **Auto-logout**: Expired sessions cleaned up automatically

### Security Monitoring
- All login attempts logged
- Failed authentication tracking
- Suspicious activity alerts
- Blocked user access attempts
- Session error aggregation

### Legal Compliance
- Terms of Service acceptance required
- Email verification notice
- SMS consent for 2FA
- Double authentication (email + SMS)

## Setup Requirements

### Required
- Google OAuth credentials (Client ID + Secret)
- Admin email addresses

### Optional (Recommended)
- Twilio account for SMS (dev mode available without)

## Configuration

1. **Copy environment template**:
   ```bash
   cp .env.example .env
   ```

2. **Edit .env with your credentials**:
   ```bash
   nano .env
   ```

3. **Required values**:
   - `GOOGLE_CLIENT_ID`
   - `GOOGLE_CLIENT_SECRET`
   - `ADMIN_EMAILS`

4. **Optional values**:
   - `TWILIO_ACCOUNT_SID`
   - `TWILIO_AUTH_TOKEN`
   - `TWILIO_PHONE_NUMBER`

## Google OAuth Setup

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create project → Enable Google+ API
3. Create OAuth 2.0 credentials
4. Add redirect URI: `http://45.61.58.125:9999/auth/google/callback`
5. Copy Client ID and Secret to `.env`

## Integration with Agents

### Shared Auth Middleware

```typescript
import { requireGlobalAuth } from '../shared-global-auth';

app.get('/', requireGlobalAuth, (req, res) => {
  // User is authenticated
  // Access user info via req.user
});
```

### Or Simple Redirect

```typescript
app.get('/', (req, res) => {
  if (!req.cookies.dw_session) {
    return res.redirect('http://45.61.58.125:9999/login');
  }
  // ... your code
});
```

## API Validation

```typescript
// Validate session from any agent
const response = await fetch(
  `http://localhost:9999/api/validate-session?session=${sessionId}`
);
const result = await response.json();

if (result.valid) {
  // User is authenticated
  console.log(result.user.email);
} else if (result.requiresSMS) {
  // Redirect to SMS verification
} else {
  // Redirect to login
}
```

## Security Features

### Automatic Blocking
- Multiple failed logins (3+ in 15 min)
- Blocked email list in `.env`
- Suspicious access patterns

### Activity Tracking
- Login/logout times
- Session duration
- Agents accessed per session
- Error logs per session
- IP address history

### Security Alerts
- Multiple failures
- Blocked user attempts
- Session expiry notices
- Unusual access patterns

## Administration

### View Active Sessions
```bash
curl http://localhost:9999/api/sessions | jq
```

### Access Logs
```bash
cat data/access-logs.json | jq
```

### Security Alerts
```bash
cat data/security-alerts.json | jq
```

### PM2 Management
```bash
pm2 logs dw-global-auth    # View logs
pm2 restart dw-global-auth # Restart
pm2 stop dw-global-auth    # Stop
```

## Data Storage

All data stored in `data/` directory:
- `users.json` - User profiles
- `sessions.json` - Active sessions
- `access-logs.json` - All access attempts
- `security-alerts.json` - Security incidents
- `sms-verifications.json` - Pending SMS codes

## Development Mode

Without Twilio credentials, the system runs in dev mode:
- SMS code is always `123456`
- Code logged to console
- Perfect for testing

## Production Checklist

- [ ] Google OAuth credentials configured
- [ ] Twilio SMS configured (or accept dev mode)
- [ ] Admin emails set in `.env`
- [ ] Session secret changed from default
- [ ] Blocked users list updated
- [ ] HTTPS enabled (update `cookie.secure`)
- [ ] Firewall allows port 9999
- [ ] PM2 configured for auto-restart
- [ ] Daily backups of `data/` directory

## File Structure

```
global-auth-system/
├── auth-server.ts         # Main server (port 9999)
├── session-manager.ts     # Session handling
├── sms-verifier.ts        # SMS 2FA system
├── types.ts               # Type definitions
├── package.json           # Dependencies
├── .env                   # Configuration
├── data/                  # Runtime data
├── quick-start.sh         # Setup script
├── SETUP.md               # Detailed setup guide
└── README.md              # This file
```

## Troubleshooting

**Google OAuth errors**
→ Check credentials in `.env`
→ Verify redirect URI in Google Console

**SMS not sending**
→ Check Twilio credentials
→ Or use dev mode (code: 123456)

**Session not persisting**
→ Check `data/` directory permissions
→ Clear browser cookies

**Port already in use**
→ Kill existing process: `fuser -k 9999/tcp`
→ Or change port in `.env`

## Documentation

- **Setup Guide**: [SETUP.md](./SETUP.md)
- **Type Definitions**: [types.ts](./types.ts)
- **Session Manager**: [session-manager.ts](./session-manager.ts)
- **SMS Verifier**: [sms-verifier.ts](./sms-verifier.ts)

## Support

1. Check logs: `pm2 logs dw-global-auth`
2. Review [SETUP.md](./SETUP.md)
3. Test in dev mode first
4. Verify `.env` configuration

---

**Built for Designer Wallcoverings** | January 2025