SECURITY.md

# Security & Privacy - Character Forge

## 🔒 API Key Security

### How API Keys Work

Character Forge is designed to be deployed as a **public HuggingFace Space** where each user provides their own Gemini API key.

**✅ SECURE: Each user's API key stays in THEIR session only**

- API keys are stored in Streamlit's `session_state`
- Session state is **isolated per browser session**
- Your API key is **NEVER shared** with other users
- Your API key is **NEVER stored** on the server
- Your API key is **NEVER logged** or saved to disk

### Deployment Configuration

**For Public Spaces (Recommended):**

❌ **DO NOT** add `GEMINI_API_KEY` to HuggingFace Repository Secrets

If you add your API key as a secret, ALL users will use YOUR key and you'll pay for their usage!

Instead:
- Leave Repository Secrets empty
- Each user enters their own API key in the sidebar
- Users get their own free API key from [Google AI Studio](https://aistudio.google.com/app/apikey)

**For Private Spaces (Your Personal Use):**

✅ **DO** add `GEMINI_API_KEY` to Repository Secrets

If your Space is set to Private:
- Only you (and people you invite) can access it
- Safe to add your API key as a secret
- Convenient - no need to enter it each time

---

## 🔐 Privacy & Data Handling

### What Data is Processed?

When you generate images:
1. **Your input images** are sent to Google's Gemini API
2. **Your text prompts** are sent to Google's Gemini API
3. **Generated images** are returned to your browser
4. **Nothing is stored** on HuggingFace servers (files are temporary)

### Where Does Data Go?

```
Your Browser
    ↓ (upload image + prompt)
HuggingFace Space (temporary processing)
    ↓ (forward to API)
Google Gemini API (image generation)
    ↓ (return generated image)
HuggingFace Space (temporary)
    ↓ (download image)
Your Browser (you save it)
```

### Data Retention

**On HuggingFace:**
- Generated images are stored in `/tmp/` (deleted after session ends)
- No permanent storage
- No logs of your generations

**On Google Gemini API:**
- Review [Google's Privacy Policy](https://policies.google.com/privacy)
- Gemini API processes your data per their terms
- Check [Gemini API Terms](https://ai.google.dev/terms)

---

## 🛡️ Best Practices

### For Users:

1. **Get Your Own API Key**
   - Visit [Google AI Studio](https://aistudio.google.com/app/apikey)
   - Create a free API key
   - Enter it in the Character Forge sidebar
   - Keep it private (don't share screenshots with your key visible)

2. **Monitor Your Usage**
   - Check your usage at [Google AI Studio](https://aistudio.google.com/)
   - Free tier: 15 requests/minute, 1500/day
   - Paid tier: ~$0.03 per image

3. **Protect Your Key**
   - Never share your API key publicly
   - Don't commit it to git repositories
   - Use environment variables for local development

### For Space Owners:

1. **Public Space = No Secrets**
   - Don't add `GEMINI_API_KEY` to Repository Secrets
   - Let users provide their own keys
   - Zero cost to you!

2. **Private Space = Secrets OK**
   - Add your key as a secret if Space is private
   - Only you and invited users can access
   - You control who uses your key

3. **Monitor Your Space**
   - Check HuggingFace Space logs for errors
   - Monitor unusual activity
   - Consider adding rate limiting if needed

---

## 🔍 Code Audit

The security model is implemented in these files:

### Session State Isolation
- **File**: `character_forge_image/app.py`
- **Lines**: 40-41, 118-119
- **Behavior**: API key stored in `st.session_state.gemini_api_key`
- **Isolation**: Streamlit guarantees session state is per-user

### API Key Retrieval
- **File**: `character_forge_image/config/settings.py`
- **Lines**: 54-61
- **Behavior**: Checks environment variable, falls back to None
- **Safe**: If no env var, users must provide their own

### API Key Usage
- **File**: `character_forge_image/core/gemini_client.py`
- **Lines**: 35-46
- **Behavior**: API key passed to Google's SDK
- **Safe**: Never logged, never stored

---

## ⚠️ Common Mistakes to Avoid

### ❌ DON'T: Share Your API Key
```python
# NEVER do this in public code
GEMINI_API_KEY = "AIzaSy..."  # ❌ Hard-coded key
```

### ❌ DON'T: Add Secret to Public Space
```yaml
# In HuggingFace Settings → Repository Secrets
# If Space is PUBLIC:
GEMINI_API_KEY: AIzaSy...  # ❌ Everyone uses your key!
```

### ✅ DO: Let Users Provide Keys
```python
# This is what Character Forge does:
st.session_state.gemini_api_key = user_input  # ✅ Per-user key
```

### ✅ DO: Use Environment Variables Locally
```bash
# For local development:
export GEMINI_API_KEY="your-key-here"
streamlit run app.py
```

---

## 📊 Cost Implications

### Public Space (Users Provide Keys)
- **Your Cost**: $0
- **User Cost**: Their own API usage
- **Benefit**: Scalable, no abuse risk

### Public Space (You Provide Key) ❌ NOT RECOMMENDED
- **Your Cost**: Unlimited! Users can drain your account
- **Risk**: High abuse potential
- **Benefit**: None

### Private Space (You Provide Key)
- **Your Cost**: Only your usage
- **Risk**: Low (only you and invited users)
- **Benefit**: Convenient

---

## 🚨 Security Incident Response

If you suspect your API key has been compromised:

1. **Revoke the key immediately**
   - Go to [Google AI Studio](https://aistudio.google.com/)
   - Delete the compromised key

2. **Create a new key**
   - Generate a fresh API key
   - Update your local environment

3. **Review usage**
   - Check your API usage logs
   - Look for unusual activity

4. **Update security**
   - Ensure key isn't in git history
   - Update `.gitignore` if needed
   - Rotate keys regularly

---

## ✅ Verification

To verify the security model is working:

1. **Open two different browsers** (e.g., Chrome and Firefox)
2. **Visit your Space** in both browsers
3. **Enter different API keys** in each browser
4. **Generate images** in both
5. **Verify**: Each browser uses its own key (check Google API usage)

If both browsers share the same key → **SECURITY ISSUE**
If each browser has its own key → **WORKING CORRECTLY ✅**

---

## 📞 Reporting Security Issues

If you find a security vulnerability:

1. **DO NOT** create a public GitHub issue
2. **Email**: gk@ghmk.de
3. **Subject**: "Character Forge Security Issue"
4. **Include**:
   - Description of the vulnerability
   - Steps to reproduce
   - Potential impact

We'll respond within 48 hours.

---

## 📜 License & Compliance

Character Forge is licensed under **GNU AGPL v3.0**

This means:
- ✅ Free to use
- ✅ Open source
- ✅ Modifications must be shared
- ❌ Cannot be integrated into proprietary software

For security audits, the full source code is available at:
https://huggingface.co/spaces/ghmk/character_forge

---

**Last Updated**: 2025-01-12
**Version**: 1.0.0