Spaces:
Sleeping
Sleeping
| # 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 | |