metadata

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.

Generate RSA Keys: First, you need a private/public RSA key pair. Use OpenSSL on your local machine:

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

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").
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)!
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.

Generate Keys: Follow Step 1 from the Hugging Face guide.

Install Dependencies:

pip install gradio numpy Pillow cryptography

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):
```
export KEYLOCK_PRIV_KEY='PASTE_THE_ENTIRE_KEY_CONTENT_HERE'
python app.py
```
- In Windows PowerShell:
```
$env:KEYLOCK_PRIV_KEY='PASTE_THE_ENTIRE_KEY_CONTENT_HERE'
python app.py
```
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.

Generate Keys & Install Dependencies: Follow steps 1 & 2 from the local guide.
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)
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).
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:

Steganography (LSB): The encrypted payload is hidden in the least significant bits (LSB) of the image's pixel data.
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. """