docs/SECURITY.md

# Security model

This public Space accepts untrusted images, sends normalized image content to a
configured external LLM provider, and renders generated procedural code in a
visitor's browser. The controls and remaining limitations are explicit below.

## Upload boundary

`app/image_guard.py` and `app/main.py` enforce:

- A 10 MiB default byte cap while reading, before image decode.
- Pillow content sniffing; filename, extension, and declared MIME type are not
  treated as proof of format.
- PNG, JPEG, WebP, GIF (first frame), and BMP only. SVG is rejected because it
  is scriptable XML.
- Pillow decompression-bomb protection, a 40 MP default pixel cap, and an
  8192 px longest-side decode cap.
- EXIF orientation normalization followed by RGB PNG re-encoding, which strips
  original metadata. The normalized image is downscaled to at most 1024 px
  before forge/LLM processing.
- Server-generated job IDs and artifact names. The artifact route uses an
  explicit filename allowlist and verifies that the resolved file remains
  directly inside its job directory.
- Community publication is opt-out and disclosed before submission. It copies
  only the normalized reference and the generated artifact allowlist; original
  filenames and image metadata are not retained.

The normalized image is sent to the operator-configured LLM endpoint. Users
must treat that provider as a data processor; this Space does not make a local
model privacy claim.

## Generated code and browser isolation

- The LLM authors JSON spec values, not executable TypeScript. A deterministic
  vendored generator emits code and JSON-escapes spec-derived literals.
- The hosted compiler accepts only its implemented primitive allowlist and
  rejects parent cycles. Generation fails if a TODO fallback is detected; an
  unsupported primitive is never silently represented as a placeholder box.
- The interactive viewer runs in `<iframe sandbox="allow-scripts">` without
  `allow-same-origin`. It has an opaque origin and cannot access parent cookies,
  storage, or same-origin DOM. Parent/iframe communication is `postMessage`;
  the parent validates `event.source`.
- Normal application responses use a restrictive policy including
  `default-src 'self'`, `script-src 'self' blob:`, `object-src 'none'`, and
  `base-uri 'none'`. `/static/viewer.html` receives a separate explicit CSP
  permitting only its required inline bootstrap and blob module import. Its
  frame-ancestor list permits this Space itself and the canonical
  `https://huggingface.co` embedding page, but no arbitrary third-party origin.
- Generated artifacts are served as files. Standalone HTML base64-embeds the
  bundle, creates a blob URL, and accesses module exports through
  `await import(url)` rather than assuming export aliases are local bindings.

Browser sandboxing limits access to the Space origin; it is not a proof that
arbitrary generated code is harmless in every browser implementation. Keep the
sandbox and CSP in place when embedding or modifying the viewer.

## Server-side process boundary

Forge, esbuild, and the isolated gallery publisher run with:

- list-form argv and `shell=False`;
- per-call timeouts and bounded captured output;
- a scrubbed child environment that omits `LLM_*` and `ANTHROPIC_*` variables;
- server-controlled files inside a per-job temporary directory.

The strict-validated original spec remains locked and unreviewed. A deep-copied
`hosted-unreviewed-preview` manifest is used only to compile all supported
components for inspection. It carries no reviewer, screenshot, comparison
image, score, or upstream `continue` decision.

## Persistent community gallery

- The private Hugging Face Bucket is mounted read/write at `/data`; the app
  serves published entries through strict gallery routes rather than exposing
  the Bucket directly.
- An opted-out job and every failed job stay in ephemeral job storage and are
  never published.
- Publication copies to a staging directory and makes the completed item
  visible only after its metadata manifest is atomically committed.
- Bucket copying runs in a scrubbed child process with a separate bounded
  deadline. Cancellation terminates and reaps that process, so a stalled mount
  cannot hold a conversion slot indefinitely.
- Gallery IDs use the same full-entropy server-generated format as jobs.
  Listing ignores malformed/incomplete entries. Artifact routes enforce an
  explicit allowlist plus direct-parent containment.
- Gallery entries intentionally persist across app restarts. Users should not
  upload images they are unwilling to publish while the share toggle is on.

## Secrets and deployment

- Runtime credentials are read from environment variables at startup and are
  never logged or returned by `/api/config`.
- Hugging Face injects Space Secrets at runtime; no credential is a Docker
  build argument or image layer.
- `scripts/deploy_space.py` uses the authenticated local `hf` CLI store, stages
  a deterministic file allowlist, and performs one upload from that sanitized
  directory.
- Environment-derived secret values are written only to a temporary mode-0600
  secrets file, passed via `hf spaces secrets add --secrets-file`, and removed
  in a `finally` block. Logs and process arguments contain secret names only.

## Abuse and resource control

- The default per-client limit is 10 accepted jobs per hour with
  `Retry-After`. The in-memory client map has an LRU size bound.
- Client identity comes from the ASGI socket peer as resolved by the trusted
  Uvicorn proxy configuration. Application code does not reinterpret a raw,
  caller-controlled `X-Forwarded-For` header.
- Two jobs run concurrently by default and queued plus running jobs are capped
  at eight. A full queue returns `queue_full` with `Retry-After`; queued uploads
  therefore cannot pin unbounded memory.
- The conversion deadline starts when a job is accepted, includes queue time,
  and ends only after the browser bundle is complete. Queue, model, generator,
  bundler, and publisher waits emit elapsed-only feedback rather than invented
  percentages. Optional Bucket publication has its own shorter deadline.
- Provider retries apply only to transient statuses, not 400/401/403.
- Terminal jobs have a two-hour default TTL. The reaper does not delete a
  running job solely because it was created a long time ago.

All abuse controls are process-local. They reduce accidental/public-demo load;
they are not a distributed quota system.

## Container boundary

- The service runs as non-root UID 1000 under `tini` on
  `python:3.12-slim-bookworm` and binds to `0.0.0.0:7860`.
- The final Docker stage copies only runtime dependencies, `app/`, required
  `forge/` code, and `LICENSE`.
- `.dockerignore`, the runtime COPY allowlist, and Docker verification exclude
  VCS state, virtual environments, rollouts, caches, tests, scripts,
  `upstream-src`, and local verification artifacts from the final image.
- Rebuild the image regularly to pick up base-image security updates.

## Accepted limitations

- A single image does not reveal hidden geometry. Results are approximate and
  hidden sides are inferred, not observed or measured.
- A strict-valid spec is not visually approved. The hosted result is explicitly
  unreviewed; production use requires the upstream screenshot/comparison review
  loop.
- Opted-out/failed job artifacts live in ephemeral `/tmp` and expire. Their
  hard-to-guess URLs are unlisted, not access-controlled. Published
  gallery entries persist in the mounted Bucket; this release does not provide
  a public deletion or moderation API.
- Rate limiting and job state reset when the single process restarts.