X Bot on the Cloud

Prompt

# Role & Objective Act as a Senior Full-Stack Security & Python Engineer. Build a complete, production-ready, self-hosted/cloud-ready web application and automated bot that pulls media files from a private Cloudflare R2 bucket in-memory (RAM only) and publishes them to X (Twitter) 2–3 times per day using a free, unofficial cookie-based API (`twifork` / `twikit`). The application MUST be protected by a strict **Password Lock / Unlock Authentication Gate** so nobody can view the dashboard, captions, or logs unless unlocked, and it must be architected to run 100% in the cloud for free (e.g., on a Private Hugging Face Space or free Docker host) by automatically syncing its SQLite database back to the private Cloudflare R2 bucket. --- # 1. Tech Stack & Cloud-Native Architecture - **Backend & Web UI:** Python with **FastAPI** + **Jinja2** templates (styled with TailwindCSS via CDN) + `itsdangerous` / `passlib[bcrypt]` for session authentication. - **Cloud Storage & State Persistence:** **Cloudflare R2** accessed via `boto3` (S3-compatible API). - **Cloud Database Sync (Stateless Cloud Compatibility):** Because free cloud hosts (like Hugging Face Spaces or Render) use ephemeral disks that wipe on restart, implement an automatic R2 sync wrapper for `bot_data.db`: 1. On app startup, check if `_system/bot_data.db` exists in the Cloudflare R2 bucket; if so, download it before initializing SQLite. 2. Whenever a post is published, a caption is added/edited, or settings change, automatically upload/backup `bot_data.db` to `_system/bot_data.db` in R2. - **Unofficial X (Twitter) Integration (100% Free):** Use `twifork` (`pip install twifork`, imported as `from twikit import Client`), the maintained fork of `twikit` that includes fixes for X's `x-client-transaction-id` headers. - **CRITICAL:** Do NOT use username/password login (`client.login()`). Authenticate exclusively using browser session cookies (`auth_token` and `ct0`) via `client.set_cookies({"auth_token": ..., "ct0": ...})`. - **Task Scheduler:** `APScheduler` (AsyncIOScheduler) running inside FastAPI's lifespan context to trigger 2 to 3 posts per day at user-configured times, applying a random jitter of ±15–30 minutes per run so the bot continues posting even while the web UI is locked. --- # 2. Strict Security: Password Lock/Unlock & Zero-Local-Media 1. **App Lock / Unlock Gate (Mandatory on Every Route):** - Protect the entire web application behind an authentication middleware. When locked, ANY visit to the app redirects to a clean, minimal `/login` ("Unlock Vault") screen asking for the Master Password. - Verify the password against a `DASHBOARD_PASSWORD` (or `DASHBOARD_PASSWORD_HASH`) stored in environment variables using constant-time comparison (`secrets.compare_digest` or `bcrypt`). - Include brute-force protection: rate-limit failed unlock attempts (e.g., 5 attempts per 15 minutes per IP). - **Instant Lock Button & Auto-Lock Timeout:** Place a prominent red **"🔒 Lock App Now"** button in the top navigation bar on every page that immediately destroys the session cookie and locks the UI. Also configure sessions to auto-lock after 30 minutes of inactivity. - **Background Execution While Locked:** Locking the web UI must ONLY lock the browser interface—the `APScheduler` background bot must continue running and posting 2–3 times a day while locked. 2. **In-Memory Media Streaming Only:** - When fetching a media file (`.jpg`, `.png`, `.gif`, `.mp4`) from Cloudflare R2, stream the object directly into a Python `io.BytesIO` buffer in RAM (ensure `_system/bot_data.db` is excluded from media selection). - Pass the raw `bytes` directly from memory into `await client.upload_media(source=media_bytes, media_type=...)`. Never write media files to the disk or `/tmp`. --- # 3. Core Features to Build (Only Accessible When Unlocked) ### Tab 1: Published Posts Dashboard - Display summary metrics: Total Posts Published, Remaining Unposted Media in R2, Next Scheduled Post Time (with jitter applied), and R2 Database Backup Status. - Render a searchable table of all published posts showing: - Timestamp of publication - R2 Media Filename / Key (do NOT publicly cache thumbnails on disk) - Generated Caption used - Direct clickable URL to the live X post (`https://x.com/i/web/status/{tweet_id}`) - Status badge (`Published`, `Failed` with error log) - Include a **"Post Now (Manual Trigger)"** button and a **"Sync R2 Bucket"** button. ### Tab 2: Caption Generator & Database Manager - Build a CRUD interface backed by SQLite (and synced to R2) with three categories: 1. **Opening Phrases / Templates** (supporting `{keyword}` placeholders). 2. **Keywords / Topics** (injected dynamically into templates or appended naturally). 3. **Hashtags** (stored with `#`, where the user configures the bot to randomly pick $N$ hashtags per post, e.g., 2 to 4). - Include bulk import (paste newline-separated lists) and a **"Preview Random Caption"** button that combines 1 Phrase + 1–2 Keywords + $N$ Hashtags while enforcing X's 280-character limit. ### Tab 3: Scheduler & Bot Controls - Toggle the scheduler `ON / OFF`. - Configure **2 to 3 daily posting times** (e.g., `09:30`, `14:00`, `19:45`) and a **Random Jitter Window** (e.g., `0 to 30 minutes`). - Configure media selection mode: `Sequential`, `Random (No Repeats until exhausted)`, or `Delete from R2 after posting`. - Provide a masked `/health` endpoint (protected by an optional `HEALTHCHECK_TOKEN` header) that returns `{"status": "ok"}` without exposing any app data, allowing a free cron ping to keep cloud containers awake. ### Tab 4: Built-in Help & Cloud Setup Guide (Interactive Documentation) Render a comprehensive, step-by-step **Help & Setup Guide** directly inside the app UI covering: 1. **How to Run This Bot 100% in the Cloud for Free (Zero Local Footprint):** - Step-by-step guide to deploying this app using the included `Dockerfile` on a **Private Hugging Face Space** (`huggingface.co/spaces` -> Create New Space -> Select **Docker** -> Select **CPU Basic (Free)** -> Set Visibility to **Private**). - Explain how setting the Hugging Face Space to **Private** hides the app behind your Hugging Face account login, while the app's own **Master Password Lock** adds a second layer of security. - How to paste the environment variables (`DASHBOARD_PASSWORD`, `R2_ENDPOINT_URL`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_BUCKET_NAME`, `X_AUTH_TOKEN`, `X_CT0`) into Hugging Face **Repository Secrets**. - How to set up a free Cloudflare Worker cron trigger (every 10 minutes) with a `HF_TOKEN` header to ping the `/health` endpoint so the private Space never goes to sleep. 2. **How to Get Free Unofficial X "API Keys" (Session Cookies):** - Step-by-step instructions to open an **Incognito/Private browser window**, log into `https://x.com`, open Developer Tools (`F12` -> **Application** -> **Cookies** -> `https://x.com`), copy `auth_token` and `ct0`, and **close the Incognito window without clicking Log Out** so the session stays valid indefinitely. 3. **How to Set Up Cloudflare R2 (Free Tier):** - Creating a private R2 bucket, generating an Object Read & Write API Token, and copying the S3 Endpoint URL. --- # 4. Deliverables & Code Quality Requirements - Provide the complete project file structure including `Dockerfile` (configured for port `7860` so it works out-of-the-box on Hugging Face Spaces as well as locally), `app.py`, `auth.py`, `bot_engine.py`, `database.py`, `r2_client.py`, `templates/`, `requirements.txt`, and `.env.example`. - Write complete, working code for every file—no `TODO` placeholders or truncated functions.

A system prompt was added to support web rendering