Upload documentation/INTEGRATION_GUIDE.md with huggingface_hub

documentation/INTEGRATION_GUIDE.md

@@ -0,0 +1,106 @@
+# Integration Guide: Adding Secure Signing to Coldstar SOL
+
+This guide shows how to integrate the Rust secure signer into your existing Python Coldstar SOL CLI.
+
+## Overview
+
+The Rust signing core will replace Python-based key handling with secure, memory-locked operations. The integration is designed to be minimally invasive to your existing codebase.
+
+## Integration Strategy
+
+```
+Before (Insecure):
+┌─────────────────────────────────────────┐
+│  Python CLI                              │
+│  ├─ Load key from file                  │
+│  ├─ Key in Python memory (INSECURE)     │
+│  └─ Sign transaction in Python          │
+└─────────────────────────────────────────┘
+
+After (Secure):
+┌─────────────────────────────────────────┐
+│  Python CLI                              │
+│  ├─ Load encrypted container            │
+│  └─ Call Rust signer ──────────┐        │
+└─────────────────────────────────┼────────┘
+                                  ▼
+                    ┌─────────────────────────┐
+                    │  Rust Signing Core      │
+                    │  ├─ Decrypt in locked   │
+                    │  │   memory              │
+                    │  ├─ Sign transaction    │
+                    │  └─ Zeroize & return    │
+                    └─────────────────────────┘
+```
+
+
+## Security Checklist
+
+After integration, verify:
+
+- [ ] Plaintext keys are deleted (or securely backed up offline)
+- [ ] Encrypted containers are created with strong passphrases (12+ characters)
+- [ ] Passphrase prompts use `getpass` (not visible on screen)
+- [ ] No plaintext keys are logged or printed
+- [ ] File permissions on encrypted containers are restrictive (`chmod 600`)
+- [ ] Backup encrypted containers securely
+- [ ] Test signing with correct and incorrect passphrases
+
+## Rollback Plan
+
+If you need to rollback to the old system:
+
+1. Keep your original `keypair.json` backed up (securely!)
+2. Keep the old wallet/transaction code in a separate branch
+3. Test thoroughly before deleting plaintext keys
+
+## Performance Considerations
+
+- **FFI mode**: ~0.1ms overhead per signature (negligible)
+- **CLI mode**: ~10-50ms overhead per signature (process startup)
+
+For production with high throughput, use FFI mode. For development or occasional use, CLI mode is fine.
+
+## Troubleshooting
+
+### "Secure signer not available"
+
+The Rust library isn't built or not found. Build it:
+
+```bash
+cd rust_signer
+cargo build --release
+```
+
+### "Failed to lock memory"
+
+Your system may have limits on locked memory. Increase the limit:
+
+```bash
+# Temporary (current session)
+ulimit -l unlimited
+
+# Permanent (add to /etc/security/limits.conf)
+* soft memlock unlimited
+* hard memlock unlimited
+```
+
+### "Decryption failed"
+
+- Check that you're using the correct passphrase
+- Verify the encrypted container file isn't corrupted
+- Try recreating the container from the original key
+
+## Next Steps
+
+1. **Integrate with UI**: Add passphrase prompts to your UI
+2. **Key Rotation**: Implement periodic key rotation
+3. **Multi-Sig**: Extend for multi-signature support
+4. **Hardware Integration**: Consider HSM integration for production
+
+## Support
+
+For issues or questions:
+- Check the README.md and SECURITY.md
+- Review the example code in python_signer_example.py
+- Open an issue with detailed logs and steps to reproduce