picpeak/backend/SAFE_AUTH_ACTIVATION_PLAN.md

# Safe Authentication Security Activation Plan

## Current Situation Analysis

### ✅ What's Already Protected:
- **SQL Injection**: Fully protected with parameterized queries
- **Rate Limiting**: Basic rate limiting active (5 attempts/15 min on /auth)
- **Password Hashing**: Bcrypt in use
- **CORS**: Properly configured

### ❌ What's NOT Protected:
- **No Account Lockout**: After rate limit, users can keep trying
- **No Audit Trail**: Can't track attack patterns
- **No Session Invalidation**: Can't force logout
- **Limited Token Security**: Basic JWT validation only

## Potential Problems & Solutions

### Problem 1: Existing User Sessions
**Risk**: Users might get logged out unexpectedly
**Solution**: 
- Enhanced auth accepts old tokens (backward compatible)
- Tokens remain valid until natural expiration
- Only new features (IP check, password change detection) are additions

### Problem 2: Accidental Lockouts
**Risk**: Legitimate users locked out due to typos
**Solution**:
- 5 attempts is reasonable (not too strict)
- 30-minute lockout (not permanent)
- Clear lockout message with retry time
- Admin bypass SQL query ready

### Problem 3: Database Migration Failure
**Risk**: Schema changes could fail
**Solution**:
- Migrations only ADD tables/columns (no modifications)
- Automatic backup before migration
- Rollback plan ready
- SQLite is forgiving with schema changes

### Problem 4: Performance Impact
**Risk**: Login tracking could slow down auth
**Solution**:
- Indexed columns for performance
- Automatic cleanup of old records
- Async logging (non-blocking)

## Step-by-Step Activation Plan

### Phase 1: Pre-Flight Checks (NOW)
```bash
# Run safety check script
cd backend
node scripts/safe-auth-deployment.js
```
This will:
- ✓ Check database health
- ✓ Count active sessions
- ✓ Create backup
- ✓ Test enhanced auth modules

### Phase 2: Database Preparation (SAFE)
```bash
# Run in Docker
docker exec wedding-photo-sharing-backend-1 npx knex migrate:latest
```
Creates:
- `login_attempts` table (new)
- Security columns in `admin_users` (nullable)

### Phase 3: Test Without Activation
```bash
# Test enhanced auth endpoints
chmod +x scripts/test-auth-deployment.sh
./scripts/test-auth-deployment.sh
```
Verifies enhanced auth works before switching

### Phase 4: Gradual Activation

#### Option A: Canary Deployment (SAFEST)
Add temporary route to test:
```javascript
// In server.js, add both temporarily
app.use('/api/auth', authRoutes);  // Original
app.use('/api/auth-new', authEnhancedRoutes);  // Test enhanced
```

Test with `/api/auth-new/admin/login` first

#### Option B: Feature Flag (RECOMMENDED)
```javascript
// In server.js
const useEnhancedAuth = process.env.USE_ENHANCED_AUTH === 'true';
const authRoutes = useEnhancedAuth 
  ? require('./src/routes/auth-enhanced')
  : require('./src/routes/auth');
```

Then activate with environment variable

#### Option C: Direct Switch (FASTER)
```javascript
// Change in server.js
const authRoutes = require('./src/routes/auth-enhanced');

// Add after DB init
const { initializeCleanupJob } = require('./src/utils/authSecurity');
initializeCleanupJob();
```

### Phase 5: Monitor After Activation
```bash
# Run monitoring script
node scripts/monitor-auth-health.js
```

Watch for:
- Sudden spike in failures
- Multiple lockouts
- Low success rate

## Rollback Procedures

### Quick Rollback (< 30 seconds):
```bash
# In server.js, revert to:
const authRoutes = require('./src/routes/auth');

# Restart
docker-compose restart backend
```

### Clear All Lockouts:
```bash
docker exec wedding-photo-sharing-backend-1 node -e "
  const {db} = require('./src/database/db');
  db('login_attempts').where('success', false).delete()
    .then(() => console.log('Lockouts cleared'))
    .then(() => db.destroy());
"
```

### Emergency Admin Access:
```sql
-- If admin is locked out
DELETE FROM login_attempts WHERE identifier = 'admin';
```

## Success Criteria

After activation, you should see:
1. ✅ Failed login attempts recorded in database
2. ✅ Account lockout after 5 failures
3. ✅ Logout endpoint working
4. ✅ No increase in auth errors
5. ✅ Existing users still able to login

## Timeline Recommendation

**Day 1 (Now)**: 
- Run migrations ✓
- Deploy code ✓
- Test endpoints

**Day 2**: 
- Monitor current auth patterns
- Run test script during low traffic

**Day 3**: 
- Activate with feature flag
- Monitor closely for 2 hours
- Full activation if stable

**Day 4+**: 
- Review login_attempts data
- Adjust thresholds if needed
- Plan 2FA implementation

## Commands Reference

```bash
# Activate enhanced auth
docker exec -it wedding-photo-sharing-backend-1 /bin/sh
vi server.js  # Make changes
exit
docker-compose restart backend

# Monitor
docker-compose logs -f backend | grep -i auth

# Check lockouts
docker exec wedding-photo-sharing-backend-1 node -e "
  const {db} = require('./src/database/db');
  db('login_attempts')
    .select('identifier')
    .where('success', false)
    .where('attempt_time', '>', new Date(Date.now() - 15*60*1000).toISOString())
    .groupBy('identifier')
    .havingRaw('COUNT(*) >= 5')
    .then(locked => console.log('Locked accounts:', locked))
    .then(() => db.destroy());
"
```

## Final Safety Notes

1. **It's been tested**: 10/10 unit tests pass
2. **It's backward compatible**: Old tokens work
3. **It's gradual**: Can activate features separately  
4. **It's reversible**: Quick rollback available
5. **It's monitored**: Health checking included

The enhanced auth is designed to be transparent to users while significantly improving security. The only visible change is lockout messages after failed attempts.