README.md

---
title: KeyLock Auth Server
emoji: 🌍
colorFrom: pink
colorTo: purple
sdk: gradio
sdk_version: 5.33.0
app_file: app.py
pinned: false
---

# 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.
"""