SECURITY.md

Security Notes

This project is a public hackathon demo. Treat the repo, README, screenshots, and Codex-visible files as public unless explicitly told otherwise.

Do Not Commit Or Expose

• Modal tokens, Hugging Face tokens, API keys, passwords, OAuth credentials, or private SSH keys.
• Local credential files such as .modal.toml, .huggingface/token, .netrc, .env, .envrc, or shell profile exports containing secrets.
• Modal or Hugging Face dashboard pages that include account-private billing, workspace settings, tokens, or secret values.
• Raw user-uploaded photos unless the user explicitly asks to add sample images to the repo.
• Full model outputs if they include private user content, uploaded image details, or long traces that are not needed for debugging.
• Modal Volume contents, downloaded GGUF files, Hugging Face cache directories, or any other large runtime assets.

Endpoint Access

The deployed Modal endpoint URLs are public HTTP entry points at the network level, but every Modal web endpoint must require:

Authorization: Bearer <SNAP2SIM_API_TOKEN>

SNAP2SIM_API_TOKEN must be stored only as:

• Modal secret: snap2sim-api-auth
• Hugging Face Space secret: SNAP2SIM_API_TOKEN

Do not document the live Modal endpoint URLs in public files unless the user explicitly asks. The URLs are not credentials, but keeping them out of public docs reduces casual discovery, and the bearer token is the real protection against credit-spending spam.

The public Hugging Face Space is now under build-small-hackathon/Snap2Sim, served at https://build-small-hackathon-snap2sim.hf.space. Keep GitHub as the source of truth and do not edit files directly on the Space.

The Space endpoints are same-origin browser APIs, not public credentials. Keep the server-side rate limits, upload-size caps, and image decompression-bomb guards in app.py active. These controls reduce abuse of the Space as a trusted Modal proxy but do not replace the Modal bearer token.

Environment Variables

Safe to expose in public docs or .env.example:

• INFERENCE_BACKEND
• MODAL_ANALYZE_URL
• MODAL_GENERATE_URL
• INFERENCE_TIMEOUT_SECONDS
• SNAP2SIM_MODEL_REPO
• SNAP2SIM_GGUF_QUANT
• SNAP2SIM_MMPROJ_FILE
• SNAP2SIM_RUNTIME_GPU

Keep private and configure only through local secret stores, Modal secrets, or Hugging Face Space secrets:

• MODAL_TOKEN_ID
• MODAL_TOKEN_SECRET
• SNAP2SIM_API_TOKEN
• HF_TOKEN
• HUGGING_FACE_HUB_TOKEN
• Any future provider key such as OPENAI_API_KEY, ANTHROPIC_API_KEY, or hosted inference credentials.

GitHub Actions

The GitHub-to-Hugging Face sync workflow uses a GitHub Actions secret named HF_TOKEN. Store that token only in GitHub repository or organization secrets. Do not hardcode it in .github/workflows/sync_to_hf.yml, README files, environment templates, prompts, or local scripts.

The workflow is one-way only: GitHub main pushes to the Hugging Face Space. Do not configure jobs that pull changes back from Hugging Face into GitHub.

Agent Guidance

• Prefer Hugging Face Space variables for public configuration and Space secrets for credentials.
• The index.html / gradio.Server frontend is public client-side code. Never embed SNAP2SIM_API_TOKEN, Modal endpoint URLs, Hugging Face tokens, or any credential-bearing values in HTML, JavaScript, CSS, bundled static assets, browser local storage, or query strings. Browser JS should call same-origin @app.api() endpoints; server-side Python should attach secrets when calling Modal.
• Do not inject model-authored HTML, JavaScript, or A-Frame markup into the DOM. Scene rendering should stay deterministic Three.js built from validated JSON.
• Do not print secret-bearing environment variables in logs.
• Do not paste full Modal or Hugging Face auth files into issues, docs, prompts, or Codex summaries.
• When sharing logs, trim them to the failing stack trace and remove uploaded image payloads, base64 strings, tokens, cookies, and account-private URLs.
• Before adding new dependencies or services, document whether they require credentials and where those credentials should live.

Reporting

For this hackathon repo, report suspected leaks directly to the repository owner or workspace owner. If a token was exposed, rotate it immediately in the provider dashboard and remove the leaked value from git history.