Update README.md

README.md

@@ -9,4 +9,107 @@ app_file: app.py
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+"""
+Secure KeyLock Decoder API Server
+
+This script deploys a secure Gradio application that acts as a server-side API
+for decrypting and retrieving JSON data hidden within PNG images.
+
+================================================================================
+▶️ DEPLOYMENT GUIDE
+================================================================================
+
+---
+OPTION 1: DEPLOY TO HUGGING FACE SPACES (RECOMMENDED)
+---
+This is the easiest and most secure way to deploy this application.
+
+1.  **Generate RSA Keys:**
+    First, you need a private/public RSA key pair. Use OpenSSL on your local machine:
+    ```bash
+    # Generate a 4096-bit private key (stronger)
+    openssl genpkey -algorithm RSA -out keylock_priv.pem -pkeyopt rsa_keygen_bits:4096
+
+    # Extract the public key from the private key
+    openssl rsa -pubout -in keylock_priv.pem -out keylock_pub.pem
+    ```
+    This will create two files: `keylock_priv.pem` (keep this secret!) and `keylock_pub.pem` (this is safe to share).
+
+2.  **Create a Hugging Face Space:**
+    - Go to Hugging Face and create a new "Space".
+    - Choose the "Gradio" SDK.
+    - Give it a name (e.g., "my-keylock-decoder").
+
+3.  **Upload Files to the Space Repository:**
+    - Rename this script to `app.py`.
+    - Create a `requirements.txt` file with the following content:
+      ```
+      gradio
+      numpy
+      Pillow
+      cryptography
+      ```
+    - Upload `app.py`, `requirements.txt`, and the public key `keylock_pub.pem` to your Space's repository.
+    - **DO NOT UPLOAD THE PRIVATE KEY (`keylock_priv.pem`)!**
+
+4.  **Set the Private Key as a Secret:**
+    - In your Space, go to the "Settings" tab.
+    - Find the "Repository secrets" section.
+    - Click "New secret".
+    - **Name:** `KEYLOCK_PRIV_KEY` (this name must be exact).
+    - **Value:** Open `keylock_priv.pem` on your local machine, copy its ENTIRE content (including `-----BEGIN PRIVATE KEY-----` and `-----END PRIVATE KEY-----`), and paste it into the value field.
+    - The application will now automatically and securely load this key at runtime.
+
+---
+OPTION 2: RUN LOCALLY FOR DEVELOPMENT
+---
+Use this for testing on your own computer.
+
+1.  **Generate Keys:** Follow Step 1 from the Hugging Face guide.
+
+2.  **Install Dependencies:**
+    ```bash
+    pip install gradio numpy Pillow cryptography
+    ```
+
+3.  **Set Environment Variable:**
+    You must provide the private key as an environment variable.
+    - Open `keylock_priv.pem`, copy its entire content into your clipboard.
+    - In your terminal (Linux/macOS):
+      ```bash
+      export KEYLOCK_PRIV_KEY='PASTE_THE_ENTIRE_KEY_CONTENT_HERE'
+      python app.py
+      ```
+    - In Windows PowerShell:
+      ```powershell
+      $env:KEYLOCK_PRIV_KEY='PASTE_THE_ENTIRE_KEY_CONTENT_HERE'
+      python app.py
+      ```
+
+4.  **Run the Script:** The app will be available at `http://127.0.0.1:7860`.
+
+---
+OPTION 3: DEPLOY TO A SELF-HOSTED SERVER
+---
+For advanced users deploying on their own VPS or server.
+
+1.  **Generate Keys & Install Dependencies:** Follow steps 1 & 2 from the local guide.
+
+2.  **Launch the App:**
+    Modify the `demo.launch()` line at the bottom of this script to bind to all network interfaces:
+    `demo.launch(server_name="0.0.0.0", server_port=7860)`
+
+3.  **Manage Environment Variable:**
+    Set the `KEYLOCK_PRIV_KEY` environment variable using a production-safe method like a `.env` file with `python-dotenv`, systemd service files, or your container orchestration platform (e.g., Docker, Kubernetes).
+
+4.  **Use a Reverse Proxy (CRITICAL):**
+    Do not expose the Gradio port directly to the internet. Place the application behind a reverse proxy like Nginx or Caddy. The proxy will handle SSL/TLS termination (HTTPS), provide better security, and manage traffic.
+
+================================================================================
+
+This application implements a hybrid security model:
+1.  **Steganography (LSB):** The encrypted payload is hidden in the least significant
+    bits (LSB) of the image's pixel data.
+2.  **Hybrid Encryption (RSA-KEM + AES-GCM):** The actual JSON payload is encrypted
+    with a one-time AES key, which itself is encrypted with the server's RSA public key.
+"""