# Security Setup Instructions

## Summary

All security improvements have been successfully committed and pushed to GitHub. Follow the instructions below to complete the deployment to HuggingFace and set up your environment variables.

## What Was Fixed

### Security Improvements ✅
- Removed hardcoded ADMIN123 token (now environment-based with auto-generation)
- Rotated Flask secret key with fail-fast validation
- Added rate limiting to authentication endpoints
- Removed exposed HuggingFace token from git config
- Created comprehensive SECURITY.md documentation

### HuggingFace Deployment Fixes ✅
- Fixed TRANSFORMERS_CACHE deprecation warning
- Resolved matplotlib permission errors
- Improved SQLite database locking issues
- Fixed sentence text display in PDF exports

---

## Step 1: Push to HuggingFace

Since you revoked the old HuggingFace token, you need to authenticate with your new token:

```bash
cd /home/thadillo/MyProjects/participatory_planner

# Push to HuggingFace (you'll be prompted for credentials)
git push hf feature/sentence-level-categorization:main
```

When prompted:
- **Username**: `thadillo`
- **Password**: Enter your **NEW HuggingFace write token** (starts with `hf_...`)

The credentials will be stored in git credential helper for future pushes.

---

## Step 2: Configure HuggingFace Spaces Secrets

Go to your HuggingFace Space settings and add these **Repository Secrets**:

https://huggingface.co/spaces/thadillo/participatory-planner/settings

### Required Secrets:

1. **FLASK_SECRET_KEY** (Critical - for session security)
   ```
   Generate a new one with:
   python -c "import secrets; print(secrets.token_hex(32))"

   Example output (DO NOT USE THIS - generate your own):
   c5eafdcbd348d3176bf1fcf52d90357575f7bc1986b7baeb67bb9d140f401881
   ```

2. **ADMIN_TOKEN** (Critical - for admin access)
   ```
   Generate a new one with:
   python -c "import secrets; print(secrets.token_urlsafe(16))"

   Example output (DO NOT USE THIS - generate your own):
   xulmKoajFS07akF9Eos9Tg
   ```

   **SAVE THIS TOKEN SECURELY** - You'll need it to log in to the admin panel!

### How to Add Secrets in HuggingFace:

1. Go to your Space: https://huggingface.co/spaces/thadillo/participatory-planner
2. Click **Settings** tab
3. Scroll to **Repository Secrets** section
4. Click **New Secret**
5. Add each secret:
   - Name: `FLASK_SECRET_KEY`
   - Value: (paste the generated secret key)
   - Click **Add**
6. Repeat for `ADMIN_TOKEN`

---

## Step 3: Configure Local Development Environment

Update your local `.env` file with the **SAME** values you set in HuggingFace:

```bash
cd /home/thadillo/MyProjects/participatory_planner

# Edit your .env file
nano .env
```

Your `.env` file should contain:

```env
# Flask Configuration
FLASK_SECRET_KEY=<PASTE THE SAME VALUE YOU USED IN HUGGINGFACE>
FLASK_ENV=development

# Model Configuration
MODELS_DIR=models/finetuned
CUDA_VISIBLE_DEVICES=-1

# Admin Token (must match HuggingFace secret)
ADMIN_TOKEN=<PASTE THE SAME VALUE YOU USED IN HUGGINGFACE>
```

**Important**: Use the **EXACT SAME** values for `FLASK_SECRET_KEY` and `ADMIN_TOKEN` that you set in HuggingFace. This ensures your local environment matches production.

---

## Step 4: Verify Local Setup

Test that your local environment works correctly:

```bash
cd /home/thadillo/MyProjects/participatory_planner

# Start the application
./start.sh
```

You should see output like:
```
🔐 Admin token: Check startup logs or set ADMIN_TOKEN in .env
🚀 Starting application...
```

If you didn't set `ADMIN_TOKEN` in `.env`, a random token will be generated and displayed **ONCE** in the logs. Save it immediately!

---

## Step 5: Test Admin Access

### Local Testing:
1. Start the application: `./start.sh`
2. Go to: http://localhost:5000/generate
3. Generate a new token using your **ADMIN_TOKEN**
4. Use the generated token to test the application

### HuggingFace Testing:
1. Wait for HuggingFace to rebuild (after pushing changes)
2. Go to: https://thadillo-participatory-planner.hf.space/generate
3. Generate a new token using your **ADMIN_TOKEN**
4. Verify the application works without the previous errors

---

## Step 6: Verify HuggingFace Deployment

After pushing to HuggingFace, monitor the build logs:

https://huggingface.co/spaces/thadillo/participatory-planner/logs

**Check for these confirmations:**
1. ✅ No TRANSFORMERS_CACHE deprecation warning
2. ✅ No matplotlib permission errors
3. ✅ No SQLite database locking errors
4. ✅ Application starts successfully

---

## Security Best Practices Going Forward

### DO:
✅ Keep `.env` file local and never commit it to git
✅ Use different secrets for development and production
✅ Rotate secrets periodically (every 3-6 months)
✅ Store production secrets only in HuggingFace Spaces secrets
✅ Use strong, randomly generated tokens (via `secrets` module)

### DON'T:
❌ Never commit `.env` to git
❌ Never hardcode secrets in code
❌ Never share your ADMIN_TOKEN publicly
❌ Never use simple passwords like "ADMIN123"
❌ Never include tokens in git remote URLs

---

## Quick Reference Commands

### Generate Flask Secret Key:
```bash
python -c "import secrets; print(secrets.token_hex(32))"
```

### Generate Admin Token:
```bash
python -c "import secrets; print(secrets.token_urlsafe(16))"
```

### Push to HuggingFace:
```bash
git push hf feature/sentence-level-categorization:main
```

### Start Local Server:
```bash
./start.sh
```

### View HuggingFace Logs:
https://huggingface.co/spaces/thadillo/participatory-planner/logs

### View HuggingFace Settings:
https://huggingface.co/spaces/thadillo/participatory-planner/settings

---

## Troubleshooting

### If HuggingFace deployment fails:
1. Check the build logs for error messages
2. Verify all secrets are set correctly in HuggingFace settings
3. Ensure `FLASK_SECRET_KEY` and `ADMIN_TOKEN` are set

### If you get "database is locked" errors:
- The new retry logic should handle this automatically
- If it persists, check HuggingFace logs for concurrent request issues

### If you forget your ADMIN_TOKEN:
1. Generate a new one: `python -c "import secrets; print(secrets.token_urlsafe(16))"`
2. Update it in HuggingFace Spaces secrets
3. Update it in your local `.env` file
4. Restart the application

### If authentication fails:
- Ensure you're using the correct ADMIN_TOKEN
- Check that rate limiting hasn't blocked you (wait 1 hour)
- Verify the token in HuggingFace secrets matches your local `.env`

---

## Next Steps

1. **Immediate**: Push to HuggingFace using the command above
2. **Immediate**: Set up HuggingFace Spaces secrets (FLASK_SECRET_KEY, ADMIN_TOKEN)
3. **Immediate**: Update your local `.env` file
4. **Soon**: Test the application on HuggingFace to verify all errors are resolved
5. **Optional**: Consider merging `feature/sentence-level-categorization` to `main` branch

---

## Files Modified

All changes have been committed to git. Here's what was changed:

- [app/__init__.py](app/__init__.py) - Secure token generation, secret key validation, rate limiter
- [app/routes/auth.py](app/routes/auth.py) - Rate limiting on login/generate endpoints
- [app/routes/admin.py](app/routes/admin.py) - Removed hardcoded ADMIN123 references
- [requirements.txt](requirements.txt) - Added Flask-Limiter
- [.env.example](.env.example) - Updated with new structure
- [Dockerfile](Dockerfile) - Fixed HuggingFace deployment issues
- [SECURITY.md](SECURITY.md) - New comprehensive security documentation
- Multiple markdown files - Documentation cleanup

---

## Support

For questions or issues:
- Review [SECURITY.md](SECURITY.md) for detailed security information
- Check HuggingFace build logs for deployment errors
- Verify environment variables are set correctly

**Remember**: Save your ADMIN_TOKEN securely - it's shown only once when auto-generated!