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

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
• Gemini API processes your data per their terms
• Check Gemini API Terms

---

🛡️ Best Practices

For Users:

1. Get Your Own API Key

   • Visit Google AI Studio
   • 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
   • 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

# NEVER do this in public code
GEMINI_API_KEY = "AIzaSy..."  # ❌ Hard-coded key

❌ DON'T: Add Secret to Public Space

# In HuggingFace Settings → Repository Secrets
# If Space is PUBLIC:
GEMINI_API_KEY: AIzaSy...  # ❌ Everyone uses your key!

✅ DO: Let Users Provide Keys

# This is what Character Forge does:
st.session_state.gemini_api_key = user_input  # ✅ Per-user key

✅ DO: Use Environment Variables Locally

# 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
   • 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