secure-ish

app.py

@@ -5,6 +5,8 @@ import uuid
 from datetime import datetime
 from typing import Dict, List, Optional, Tuple
 import hashlib
+import hmac
+import time
 from pathlib import Path
 
 # Create data directories
@@ -16,6 +18,123 @@ IMAGES_DIR = DATA_DIR / "images"
 for dir_path in [DATA_DIR, PICLETS_DIR, COLLECTIONS_DIR, IMAGES_DIR]:
     dir_path.mkdir(exist_ok=True)
 
+# Secret key for verification (in production, use environment variable)
+SECRET_KEY = os.getenv("PICLET_SECRET_KEY", "piclets-dev-key-change-in-production")
+
+class PicletVerification:
+    """Handles Piclet authenticity verification"""
+    
+    @staticmethod
+    def create_signature(piclet_data: dict, timestamp: int, generation_data: dict = None) -> str:
+        """
+        Create a cryptographic signature for a Piclet
+        Uses HMAC-SHA256 with the secret key
+        """
+        # Create deterministic string from core Piclet data
+        core_data = {
+            "name": piclet_data.get("name", ""),
+            "primaryType": piclet_data.get("primaryType", ""),
+            "baseStats": piclet_data.get("baseStats", {}),
+            "movepool": piclet_data.get("movepool", []),
+            "timestamp": timestamp
+        }
+        
+        # Add generation metadata if provided
+        if generation_data:
+            core_data["generation_data"] = generation_data
+        
+        # Create deterministic JSON string (sorted keys)
+        data_string = json.dumps(core_data, sort_keys=True, separators=(',', ':'))
+        
+        # Create HMAC signature
+        signature = hmac.new(
+            SECRET_KEY.encode('utf-8'),
+            data_string.encode('utf-8'),
+            hashlib.sha256
+        ).hexdigest()
+        
+        return signature
+    
+    @staticmethod
+    def verify_signature(piclet_data: dict, provided_signature: str, timestamp: int, generation_data: dict = None) -> bool:
+        """
+        Verify a Piclet's signature
+        Returns True if signature is valid
+        """
+        try:
+            expected_signature = PicletVerification.create_signature(piclet_data, timestamp, generation_data)
+            return hmac.compare_digest(expected_signature, provided_signature)
+        except Exception as e:
+            print(f"Signature verification error: {e}")
+            return False
+    
+    @staticmethod
+    def create_verification_data(piclet_data: dict, image_caption: str = None, concept_string: str = None) -> dict:
+        """
+        Create complete verification data for a Piclet
+        Includes signature, timestamp, and generation metadata
+        """
+        timestamp = int(time.time())
+        
+        # Generation metadata
+        generation_data = {
+            "image_caption": image_caption or "",
+            "concept_string": concept_string or "",
+            "generation_method": "official_app"
+        }
+        
+        # Create signature
+        signature = PicletVerification.create_signature(piclet_data, timestamp, generation_data)
+        
+        return {
+            "signature": signature,
+            "timestamp": timestamp,
+            "generation_data": generation_data,
+            "verification_version": "1.0"
+        }
+    
+    @staticmethod
+    def is_verified_piclet(piclet_data: dict) -> Tuple[bool, str]:
+        """
+        Check if a Piclet has valid verification
+        Returns: (is_verified, status_message)
+        """
+        try:
+            # Check for verification data
+            if "verification" not in piclet_data:
+                return False, "No verification data found"
+            
+            verification = piclet_data["verification"]
+            required_fields = ["signature", "timestamp", "generation_data"]
+            
+            for field in required_fields:
+                if field not in verification:
+                    return False, f"Missing verification field: {field}"
+            
+            # Verify signature
+            is_valid = PicletVerification.verify_signature(
+                piclet_data,
+                verification["signature"],
+                verification["timestamp"],
+                verification["generation_data"]
+            )
+            
+            if not is_valid:
+                return False, "Invalid signature - Piclet may be modified or fake"
+            
+            # Check timestamp (reject if too old - 24 hours)
+            current_time = int(time.time())
+            piclet_time = verification["timestamp"]
+            
+            # Allow some flexibility for testing (24 hours)
+            if current_time - piclet_time > 86400:  # 24 hours
+                return False, "Piclet signature is too old (>24 hours)"
+            
+            return True, "Verified authentic Piclet"
+            
+        except Exception as e:
+            return False, f"Verification error: {str(e)}"
+
 class PicletStorage:
     """Handles saving and retrieving Piclet data using file-based storage"""
     
@@ -107,7 +226,8 @@ class PicletStorage:
                         "primaryType": data.get("primaryType"),
                         "tier": data.get("tier"),
                         "created_at": data.get("created_at"),
-                        "has_image": "image_filename" in data
+                        "has_image": "image_filename" in data,
+                        "verified": data.get("verified", False)
                     }
                     piclets.append(summary)
                     
@@ -142,7 +262,7 @@ class PicletStorage:
             print(f"Error getting image for {piclet_id}: {e}")
             return None
 
-def save_piclet_api(piclet_json: str, image_file=None) -> str:
+def save_piclet_api(piclet_json: str, signature: str = "", image_file=None) -> str:
     """
     API endpoint to save a Piclet
     """
@@ -159,6 +279,20 @@ def save_piclet_api(piclet_json: str, image_file=None) -> str:
                     "error": f"Missing required field: {field}"
                 })
         
+        # Verify Piclet authenticity
+        is_verified, verification_message = PicletVerification.is_verified_piclet(piclet_data)
+        
+        if not is_verified:
+            return json.dumps({
+                "success": False,
+                "error": f"Verification failed: {verification_message}",
+                "verification_required": True
+            })
+        
+        # Add verification status to stored data
+        piclet_data["verified"] = True
+        piclet_data["verification_message"] = verification_message
+        
         # Save the Piclet
         success, result = PicletStorage.save_piclet(piclet_data, image_file)
         
@@ -166,7 +300,8 @@ def save_piclet_api(piclet_json: str, image_file=None) -> str:
             return json.dumps({
                 "success": True,
                 "piclet_id": result,
-                "message": "Piclet saved successfully"
+                "message": "Verified Piclet saved successfully",
+                "verified": True
             })
         else:
             return json.dumps({
@@ -257,6 +392,87 @@ def get_piclet_image_api(piclet_id: str):
         print(f"Error in get_piclet_image_api: {e}")
         return None
 
+def sign_piclet_api(piclet_json: str, image_caption: str = "", concept_string: str = "") -> str:
+    """
+    API endpoint to sign a Piclet (for static frontend integration)
+    This allows static sites to generate verified Piclets without exposing the secret key
+    """
+    try:
+        # Parse the JSON data
+        piclet_data = json.loads(piclet_json)
+        
+        # Validate required fields
+        required_fields = ["name", "primaryType", "baseStats", "movepool"]
+        for field in required_fields:
+            if field not in piclet_data:
+                return json.dumps({
+                    "success": False,
+                    "error": f"Missing required field: {field}"
+                })
+        
+        # Create verification data using server's secret key
+        verification_data = PicletVerification.create_verification_data(
+            piclet_data,
+            image_caption=image_caption,
+            concept_string=concept_string
+        )
+        
+        # Add verification to Piclet data
+        verified_piclet = {**piclet_data, "verification": verification_data}
+        
+        return json.dumps({
+            "success": True,
+            "verified_piclet": verified_piclet,
+            "signature": verification_data["signature"],
+            "message": "Piclet signed successfully - ready for storage"
+        })
+        
+    except json.JSONDecodeError:
+        return json.dumps({
+            "success": False,
+            "error": "Invalid JSON format"
+        })
+    except Exception as e:
+        return json.dumps({
+            "success": False,
+            "error": f"Signing error: {str(e)}"
+        })
+
+def sign_and_save_piclet_api(piclet_json: str, image_caption: str = "", concept_string: str = "", image_file=None) -> str:
+    """
+    API endpoint to sign AND save a Piclet in one step (convenience method)
+    Perfect for static frontends - no secret key needed on client side
+    """
+    try:
+        # First, sign the Piclet
+        sign_result_json = sign_piclet_api(piclet_json, image_caption, concept_string)
+        sign_result = json.loads(sign_result_json)
+        
+        if not sign_result["success"]:
+            return sign_result_json
+        
+        # Then save the verified Piclet
+        verified_piclet_json = json.dumps(sign_result["verified_piclet"])
+        save_result_json = save_piclet_api(verified_piclet_json, sign_result["signature"], image_file)
+        save_result = json.loads(save_result_json)
+        
+        if save_result["success"]:
+            return json.dumps({
+                "success": True,
+                "piclet_id": save_result["piclet_id"],
+                "message": "Piclet signed and saved successfully",
+                "verified": True,
+                "signature": sign_result["signature"]
+            })
+        else:
+            return save_result_json
+            
+    except Exception as e:
+        return json.dumps({
+            "success": False,
+            "error": f"Sign and save error: {str(e)}"
+        })
+
 # Create example Piclet data for testing
 def create_example_piclet() -> str:
     """Create an example Piclet for testing"""
@@ -330,9 +546,86 @@ with gr.Blocks(title="Piclets Server API", theme=gr.themes.Soft()) as app:
     """)
     
     with gr.Tabs():
-        # Save Piclet Tab
-        with gr.Tab("💾 Save Piclet"):
-            gr.Markdown("### Save a new Piclet with optional image")
+        # Sign and Save Tab (For Static Frontends)
+        with gr.Tab("✍️ Sign & Save Piclet"):
+            gr.Markdown("### Sign and Save a Piclet (One Step - Perfect for Static Sites)")
+            gr.Markdown("🌟 **For Static Frontends**: No secret key needed! Server signs your Piclet automatically.")
+            
+            with gr.Row():
+                with gr.Column(scale=2):
+                    unsigned_json_input = gr.Textbox(
+                        label="Unsigned Piclet JSON Data",
+                        placeholder="Paste your unsigned Piclet JSON here...",
+                        lines=12,
+                        value=create_example_piclet()
+                    )
+                    
+                    with gr.Row():
+                        caption_input = gr.Textbox(
+                            label="Image Caption",
+                            placeholder="AI-generated image description...",
+                            lines=2
+                        )
+                        concept_input = gr.Textbox(
+                            label="Concept String", 
+                            placeholder="Creature concept from AI...",
+                            lines=2
+                        )
+                
+                with gr.Column(scale=1):
+                    sign_save_image_input = gr.File(
+                        label="Piclet Image (Optional)",
+                        file_types=["image"]
+                    )
+                    
+                    sign_save_btn = gr.Button("✍️ Sign & Save Piclet", variant="primary")
+                    
+                    sign_save_output = gr.JSON(label="Sign & Save Result")
+            
+            sign_save_btn.click(
+                fn=sign_and_save_piclet_api,
+                inputs=[unsigned_json_input, caption_input, concept_input, sign_save_image_input],
+                outputs=sign_save_output
+            )
+        
+        # Sign Only Tab
+        with gr.Tab("🔏 Sign Only"):
+            gr.Markdown("### Sign a Piclet (Two-Step Process)")
+            gr.Markdown("📝 **Advanced**: Sign first, then save separately. Useful for batch operations.")
+            
+            with gr.Row():
+                with gr.Column(scale=2):
+                    sign_json_input = gr.Textbox(
+                        label="Unsigned Piclet JSON Data",
+                        placeholder="Paste your unsigned Piclet JSON here...",
+                        lines=10,
+                        value=create_example_piclet()
+                    )
+                    
+                    with gr.Row():
+                        sign_caption_input = gr.Textbox(
+                            label="Image Caption",
+                            placeholder="AI-generated image description..."
+                        )
+                        sign_concept_input = gr.Textbox(
+                            label="Concept String",
+                            placeholder="Creature concept from AI..."
+                        )
+                
+                with gr.Column(scale=2):
+                    sign_btn = gr.Button("🔏 Sign Piclet", variant="secondary")
+                    sign_output = gr.JSON(label="Signing Result")
+            
+            sign_btn.click(
+                fn=sign_piclet_api,
+                inputs=[sign_json_input, sign_caption_input, sign_concept_input],
+                outputs=sign_output
+            )
+        
+        # Save Piclet Tab (For Pre-Signed)
+        with gr.Tab("💾 Save Pre-Signed"):
+            gr.Markdown("### Save a Pre-Signed Piclet")
+            gr.Markdown("⚠️ **For Advanced Users**: Save a Piclet that was already signed elsewhere.")
             
             with gr.Row():
                 with gr.Column(scale=2):
@@ -428,17 +721,75 @@ with gr.Blocks(title="Piclets Server API", theme=gr.themes.Soft()) as app:
                 outputs=image_output
             )
         
+        # Generate Verified Example Tab
+        with gr.Tab("✅ Generate Verified Example"):
+            gr.Markdown("""
+            ### Generate a Verified Example Piclet
+            
+            This creates a properly signed example Piclet that will pass verification.
+            Use this to test the verification system or as a template.
+            """)
+            
+            generate_btn = gr.Button("✅ Generate Verified Example", variant="primary")
+            verified_output = gr.Textbox(
+                label="Verified Piclet JSON",
+                lines=20,
+                show_copy_button=True
+            )
+            
+            generate_btn.click(
+                fn=create_verified_example_api,
+                outputs=verified_output
+            )
+        
         # API Documentation Tab
-        with gr.Tab("📖 API Documentation"):
+        with gr.Tab("📖 API Documentation & Verification"):
             gr.Markdown("""
+            ## 🔐 Verification System
+            
+            **All Piclets must be verified to prevent fake or modified creatures.**
+            
+            ### How Verification Works:
+            1. **HMAC-SHA256 Signature**: Each Piclet is signed with a secret key
+            2. **Timestamp Validation**: Signatures expire after 24 hours
+            3. **Generation Metadata**: Includes image caption and concept string
+            4. **Tamper Detection**: Any modification invalidates the signature
+            
+            ### Required Verification Format:
+            ```json
+            {
+              "verification": {
+                "signature": "abc123...",
+                "timestamp": 1690123456,
+                "generation_data": {
+                  "image_caption": "AI-generated description",
+                  "concept_string": "Creature concept",
+                  "generation_method": "official_app"
+                },
+                "verification_version": "1.0"
+              }
+            }
+            ```
+            
             ## API Endpoints
             
-            This Gradio interface provides the following API endpoints that can be accessed programmatically:
+            ### 1. Sign & Save Piclet (Recommended for Static Sites)
+            - **Function**: `sign_and_save_piclet_api(piclet_json, image_caption, concept_string, image_file=None)`
+            - **Input**: Unsigned Piclet JSON, image caption, concept string, optional image file
+            - **Output**: JSON response with success status and Piclet ID
+            - **✅ Perfect for**: Static sites (no secret key needed)
+            
+            ### 2. Sign Only
+            - **Function**: `sign_piclet_api(piclet_json, image_caption, concept_string)`
+            - **Input**: Unsigned Piclet JSON, image caption, concept string
+            - **Output**: JSON response with verified Piclet and signature
+            - **Use case**: Two-step process, batch operations
             
-            ### 1. Save Piclet
-            - **Function**: `save_piclet_api(piclet_json, image_file=None)`
-            - **Input**: JSON string with Piclet data, optional image file
+            ### 3. Save Pre-Signed Piclet
+            - **Function**: `save_piclet_api(piclet_json, signature, image_file=None)`
+            - **Input**: Signed Piclet JSON, signature string, optional image file
             - **Output**: JSON response with success status and Piclet ID
+            - **⚠️ Requires**: Valid verification signature
             
             ### 2. Get Piclet
             - **Function**: `get_piclet_api(piclet_id)`
@@ -496,27 +847,62 @@ with gr.Blocks(title="Piclets Server API", theme=gr.themes.Soft()) as app:
             }
             ```
             
-            ## Usage from Frontend
+            ## Frontend Integration (JavaScript)
+            
+            ### Include Verification Helper
+            ```html
+            <!-- Include crypto-js for HMAC generation -->
+            <script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.1.1/crypto-js.min.js"></script>
+            <script src="verification_helper.js"></script>
+            ```
             
+            ### Static Site Usage (Recommended)
             ```javascript
             // Connect to this Gradio space
             const client = await window.gradioClient.Client.connect("your-space-name");
             
-            // Save a Piclet
-            const saveResult = await client.predict("/save_piclet_api", [
-                JSON.stringify(picletData),  // Piclet JSON
-                imageFile  // Optional image file
+            // Sign and save in one step (NO SECRET KEY NEEDED!)
+            const result = await client.predict("/sign_and_save_piclet_api", [
+                JSON.stringify(picletData),     // Unsigned Piclet data
+                imageCaption,                   // AI-generated caption
+                conceptString,                  // Creature concept
+                imageFile                       // Optional image
             ]);
             
-            // Get a Piclet
-            const getResult = await client.predict("/get_piclet_api", [
-                picletId  // Piclet ID string
-            ]);
+            const response = JSON.parse(result.data[0]);
+            if (response.success) {
+                console.log(`Piclet saved with ID: ${response.piclet_id}`);
+            } else {
+                console.error(`Save failed: ${response.error}`);
+            }
             
-            // List Piclets
-            const listResult = await client.predict("/list_piclets_api", [
-                20  // Maximum results
+            // Two-step process (sign first, then save)
+            const signResult = await client.predict("/sign_piclet_api", [
+                JSON.stringify(picletData),
+                imageCaption,
+                conceptString
             ]);
+            
+            const signResponse = JSON.parse(signResult.data[0]);
+            if (signResponse.success) {
+                const saveResult = await client.predict("/save_piclet_api", [
+                    JSON.stringify(signResponse.verified_piclet),
+                    signResponse.signature,
+                    imageFile
+                ]);
+            }
+            ```
+            
+            ### Secret Key Management (Server Only)
+            ```bash
+            # Set environment variable on server (HuggingFace Spaces)
+            PICLET_SECRET_KEY=your-super-secret-64-char-hex-key
+            
+            # Generate secure key:
+            openssl rand -hex 32
+            
+            # ✅ Frontend doesn't need the secret key anymore!
+            # Server handles all signing securely
             ```
             
             ## Storage Structure
@@ -527,6 +913,29 @@ with gr.Blocks(title="Piclets Server API", theme=gr.themes.Soft()) as app:
             - **Collections**: `./data/collections/*.json` (future feature)
             
             All data is stored locally in the Hugging Face Space persistent storage.
+            
+            ## Security Features
+            
+            ### ✅ Verified Piclets
+            - Generated through official app only
+            - Cryptographically signed with HMAC-SHA256
+            - Include generation metadata (image caption, concept)
+            - Tamper-proof (any modification breaks signature)
+            
+            ### ❌ Rejected Piclets
+            - Missing verification data
+            - Invalid or expired signatures
+            - Modified after generation
+            - Created outside official app
+            
+            ### Environment Variables
+            - `PICLET_SECRET_KEY`: Secret key for verification (change in production)
+            
+            ### Files Included
+            - `app.py`: Main server application
+            - `verification_helper.js`: Frontend helper functions
+            - `requirements.txt`: Python dependencies
+            - `API_DOCUMENTATION.md`: Complete documentation
             """)
 
 # Launch the app

verification_helper.js

@@ -0,0 +1,192 @@
+/**
+ * Piclet Verification Helper for Frontend
+ * Use this in your Svelte game to generate verified Piclets
+ */
+
+// This should match the server's secret key
+const PICLET_SECRET_KEY = "piclets-dev-key-change-in-production";
+
+/**
+ * Create HMAC-SHA256 signature (requires crypto-js or similar)
+ * For browser compatibility, you'll need to include crypto-js:
+ * npm install crypto-js
+ * or include via CDN: https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.1.1/crypto-js.min.js
+ */
+async function createHMAC(message, key) {
+    // Browser-native crypto API version (modern browsers)
+    if (window.crypto && window.crypto.subtle) {
+        const encoder = new TextEncoder();
+        const keyData = encoder.encode(key);
+        const messageData = encoder.encode(message);
+        
+        const cryptoKey = await window.crypto.subtle.importKey(
+            'raw',
+            keyData,
+            { name: 'HMAC', hash: 'SHA-256' },
+            false,
+            ['sign']
+        );
+        
+        const signature = await window.crypto.subtle.sign('HMAC', cryptoKey, messageData);
+        const hashArray = Array.from(new Uint8Array(signature));
+        return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
+    }
+    
+    // Fallback: Use crypto-js if available
+    if (window.CryptoJS) {
+        return CryptoJS.HmacSHA256(message, key).toString();
+    }
+    
+    throw new Error("No crypto implementation available. Include crypto-js or use modern browser.");
+}
+
+/**
+ * Create verification data for a Piclet
+ * Call this when generating a Piclet in your game
+ */
+async function createPicletVerification(picletData, imageCaption = "", conceptString = "") {
+    const timestamp = Math.floor(Date.now() / 1000);
+    
+    // Core data used for signature
+    const coreData = {
+        name: picletData.name || "",
+        primaryType: picletData.primaryType || "",
+        baseStats: picletData.baseStats || {},
+        movepool: picletData.movepool || [],
+        timestamp: timestamp
+    };
+    
+    // Generation metadata
+    const generationData = {
+        image_caption: imageCaption,
+        concept_string: conceptString,
+        generation_method: "official_app"
+    };
+    
+    // Add generation data to core data
+    coreData.generation_data = generationData;
+    
+    // Create deterministic JSON string
+    const dataString = JSON.stringify(coreData, null, 0);
+    
+    // Create signature
+    const signature = await createHMAC(dataString, PICLET_SECRET_KEY);
+    
+    return {
+        signature: signature,
+        timestamp: timestamp,
+        generation_data: generationData,
+        verification_version: "1.0"
+    };
+}
+
+/**
+ * Add verification to a Piclet before saving
+ * Use this in your PicletGenerator component
+ */
+async function verifyAndPreparePiclet(picletData, imageCaption = "", conceptString = "") {
+    try {
+        // Create verification data
+        const verification = await createPicletVerification(picletData, imageCaption, conceptString);
+        
+        // Add verification to Piclet data
+        const verifiedPiclet = {
+            ...picletData,
+            verification: verification
+        };
+        
+        return {
+            success: true,
+            piclet: verifiedPiclet,
+            signature: verification.signature
+        };
+        
+    } catch (error) {
+        return {
+            success: false,
+            error: error.message
+        };
+    }
+}
+
+/**
+ * Save a verified Piclet to the server
+ * Use this instead of direct API calls
+ */
+async function saveVerifiedPiclet(gradioClient, picletData, imageFile = null, imageCaption = "", conceptString = "") {
+    try {
+        // Create verified Piclet
+        const verificationResult = await verifyAndPreparePiclet(picletData, imageCaption, conceptString);
+        
+        if (!verificationResult.success) {
+            return {
+                success: false,
+                error: `Verification failed: ${verificationResult.error}`
+            };
+        }
+        
+        // Save to server
+        const result = await gradioClient.predict("/save_piclet_api", [
+            JSON.stringify(verificationResult.piclet),
+            verificationResult.signature,
+            imageFile
+        ]);
+        
+        return JSON.parse(result.data[0]);
+        
+    } catch (error) {
+        return {
+            success: false,
+            error: `Save failed: ${error.message}`
+        };
+    }
+}
+
+/**
+ * Example usage in your Svelte component:
+ * 
+ * // In PicletGenerator.svelte or similar component
+ * import { saveVerifiedPiclet } from './verification_helper.js';
+ * 
+ * async function savePiclet() {
+ *     const picletData = {
+ *         name: generatedName,
+ *         primaryType: detectedType,
+ *         baseStats: calculatedStats,
+ *         movepool: generatedMoves,
+ *         // ... other data
+ *     };
+ *     
+ *     const result = await saveVerifiedPiclet(
+ *         gradioClient,
+ *         picletData,
+ *         uploadedImageFile,
+ *         imageCaption,
+ *         conceptString
+ *     );
+ *     
+ *     if (result.success) {
+ *         console.log(`Piclet saved with ID: ${result.piclet_id}`);
+ *     } else {
+ *         console.error(`Save failed: ${result.error}`);
+ *     }
+ * }
+ */
+
+// Export for ES modules
+if (typeof module !== 'undefined' && module.exports) {
+    module.exports = {
+        createPicletVerification,
+        verifyAndPreparePiclet,
+        saveVerifiedPiclet
+    };
+}
+
+// Global functions for script tag usage
+if (typeof window !== 'undefined') {
+    window.PicletVerification = {
+        createPicletVerification,
+        verifyAndPreparePiclet,
+        saveVerifiedPiclet
+    };
+}