shim
----

small static site host for archive uploads.

what it does
  - users upload one archive, app publishes it under a slug
  - public routes: /s/<slug>/... and /_site/<slug>/...

quick start (assumes POSIX)
  - python3 -m venv .venv
  - source .venv/bin/activate
  - pip install -r requirements.txt
  - python3 server.py
  - open http://127.0.0.1:8585/app

production service (gunicorn)
  - gunicorn server:app --bind 0.0.0.0:8585 --workers 4 --threads 8 --timeout 60 --graceful-timeout 30 --keep-alive 5 --access-logfile - --error-logfile -

config
  - edit values directly in shim_app.py constants
  - common constants: APP_NAME, BIND_HOST, PORT
  - upload/session limits: SESSION_TTL_SECONDS, MAX_UPLOAD_BYTES, MAX_EXTRACTED_BYTES, MAX_EXTRACTED_FILES, MAX_FORM_MEMORY_SIZE
  - sqlite tuning: SQLITE_TIMEOUT_SECONDS, SQLITE_BUSY_TIMEOUT_MS, SQLITE_CACHE_SIZE_KIB, SQLITE_MMAP_SIZE_BYTES, SQLITE_WAL_AUTOCHECKPOINT_PAGES

env vars
  - SECRET_KEY: external secret injection for production
  - ENFORCE_APP_REQUEST_GUARDS: optional same-origin/csrf enforcement toggle for authenticated mutating /app/ requests

security hardening
  - archive handling is restricted to common archive suffixes and secure extraction checks (no traversal, no symlinks/devices, file count cap, extracted size cap)
  - request path sanitization blocks suspicious dot-segments and null-byte paths before routing
  - slug and uuid inputs are validated before db operations
  - auth uses challenge encryption via local mojicrypt; passwords are never stored in plaintext
  - username validation supports strict ascii handles or normalized emails only
  - sessions are server-side, random-token based, ttl-limited, and expired sessions are cleaned during auth reads
  - setup/login rotates any existing session token to reduce session fixation risk
  - admin password reset revokes active sessions for the target user
  - app shell responses include nonce-based CSP and additional security headers (frame/referrer/permissions/content-type protections)
  - sqlite hardening includes foreign key enforcement, extension loading disabled, trusted_schema off, and WAL-based runtime tuning
  - cookie handling uses httponly + samesite for session and active-site cookies, with secure flag applied automatically on https/proxied-https
  - ENFORCE_APP_REQUEST_GUARDS behavior
     - this is the only security toggle
     - when true: authenticated mutating requests under /app/ must pass same-origin verification and csrf token verification
     - when false: those same-origin/csrf request guards are skipped (useful behind some proxy/kubernetes setups)
     - all other hardening listed above remains enabled

data paths
  - db: data/shim.db
  - site files: data/sites/