Update README.md

README.md

@@ -7,30 +7,134 @@ sdk: docker
 pinned: false
 ---
 
+---
+title: Secure KeyLock Decoder API
+sdk: docker
+app_port: 7860
+colorFrom: pink
+colorTo: pink
+---
+
 # Secure KeyLock Decoder API
 
-This is a server-side API plugin running in a Docker container on Hugging Face Spaces. It provides a secure endpoint to decrypt messages from images created with the KeyLock application.
+This is a server-side API plugin running in a Docker container on Hugging Face Spaces. It provides a secure, public endpoint to decrypt messages from images created with the KeyLock steganography application.
+
+The core purpose of this service is to act as a trusted third party that holds a secret key. Users can encrypt data using the corresponding public key, and this service will decrypt it for them, without the user ever needing to handle the private key themselves.
+
+## Live API Status
+
+You can check if the API is running by visiting the root of its direct URL:
+
+-   **Health Check:** **[https://broadfield-dev-keylock-rsa-js.hf.space/](https://broadfield-dev-keylock-rsa-js.hf.space/)**
+
+If the server is running correctly, you will see a JSON response like #`{"status":"ok",...}`.
+
+---
+
+## How to Use This API
+
+The process involves two main steps: encrypting the data into an image, and then sending that image to this API for decryption.
+
+### Step 1: Encrypt Your Data
+
+1.  **Get the Public Key:** You must use this service's specific public key to encrypt your data. Any other key pair will result in a decryption error.
+
+    **Service Public Key:**
+    ```pem
+    -----BEGIN PUBLIC KEY-----
+    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAy2sWjB1iQ3vK03U7e/9E
+    O6J1K/s0tBq4Pz8F3r9/i8s7t9R1p8Z4Y6h4f4O7w9p9Z0c8t7m4J1e9g7K9m6f3
+    R1k3y7v1w0l7z6s5v2l8l4t9v8z7y6t5k2x1c9v7z3k1y9w8r5t3s1v9a8d7g6f5
+    e4d3c2b1a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2
+    c1b0a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0
+    a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8
+    e7d6
+    -----END PUBLIC KEY-----
+    ```
+
+2.  **Use an Encryption Tool:** Go to the [KeyLock RSA-BU](https://huggingface.co/spaces/broadfield-dev/KeyLock-RSA-BU) application (or use any compatible tool).
+    -   On the "Embed Data" tab, enter your secret data (e.g., #`USERNAME: myuser`).
+    -   Paste the **Service Public Key** from above into the "Recipient's Public Key" field.
+    -   Generate and download the encrypted PNG image.
 
-## How It Works
+### Step 2: Send the Image to the API
 
-1.  **Encryption**: A user encrypts a secret message (e.g., credentials) into a PNG image using this plugin's **Public Key**.
-2.  **API Call**: The user's application sends this PNG file to this Space's `/api/decode` endpoint.
-3.  **Secure Decryption**: This server uses its corresponding **Private Key**, stored securely as a Hugging Face Secret, to decrypt the data from the image.
-4.  **Response**: The server returns the decrypted data as a JSON object.
+Make a #`POST` request to the API endpoint with the encrypted image.
+
+-   **Endpoint URL**: #`https://broadfield-dev-keylock-rsa-js.hf.space/api/decode`
+-   **Method**: #`POST`
+-   **Body Type**: #`multipart/form-data`
+-   **Field Name**: The image file must be sent in a field named #`authImage`.
 
 ---
 
-### Plugin's Public Key
+## API Response Format
+
+#### On Success (Status 200 OK)
+
+The API will return a JSON object containing the decrypted data.
+
+```json
+{
+  "success": true,
+  "data": {
+    "YOUR_KEY_1": "your_decrypted_value_1",
+    "YOUR_KEY_2": "your_decrypted_value_2"
+  }
+}
+```
+
+#### On Failure (Status 400 or 500)
+
+The API will return a JSON object with a descriptive error message.
+
+```json
+{
+  "success": false,
+  "error": "Decryption failed: The image may be corrupt or was not encrypted with the correct public key."
+}
+```
+
+---
+
+## Example: Using `fetch` in JavaScript
+
+Here is a simple example of how to call this API from a web application.
+
+```javascript
+async function decodeImageWithApi(imageFile) {
+  const apiUrl = 'https://broadfield-dev-keylock-rsa-js.hf.space/api/decode';
+  
+  // Create a FormData object to send the file
+  const formData = new FormData();
+  formData.append('authImage', imageFile);
+
+  try {
+    const response = await fetch(apiUrl, {
+      method: 'POST',
+      body: formData,
+    });
+
+    const result = await response.json();
+
+    if (!response.ok) {
+      throw new Error(result.error || `Server responded with status ${response.status}`);
+    }
+
+    console.log('Successfully Decoded Data:', result.data);
+    return result.data;
+
+  } catch (error) {
+    console.error('API call failed:', error.message);
+    // Handle the error in your UI
+  }
+}
 
-Provide this public key to users who need to encrypt data for this service.
+// How to use it:
+// const myImageFile = document.getElementById('my-file-input').files[0];
+// if (myImageFile) {
+//   decodeImageWithApi(myImageFile);
+// }
+```
 
-```pem
------BEGIN PUBLIC KEY-----
-MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAy2sWjB1iQ3vK03U7e/9E
-O6J1K/s0tBq4Pz8F3r9/i8s7t9R1p8Z4Y6h4f4O7w9p9Z0c8t7m4J1e9g7K9m6f3
-R1k3y7v1w0l7z6s5v2l8l4t9v8z7y6t5k2x1c9v7z3k1y9w8r5t3s1v9a8d7g6f5
-e4d3c2b1a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2
-c1b0a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0
-a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8
-e7d6
------END PUBLIC KEY-----
+You can test this API live using the **[Official Test Client](https://broadfield-dev-keylock-js-test.static.hf.space/)**.