first commit

README.md

@@ -1,2 +1,98 @@
-# vaultwarden-ssh-agent
+# Vaultwarden SSH Agent Script
 
+A PowerShell script that automatically loads SSH keys from your Vaultwarden vault into your SSH agent. This script provides a secure way to manage and load your SSH keys by storing them in your Vaultwarden vault and loading them into your SSH agent when needed.
+
+## Prerequisites
+
+- PowerShell 5.1 or later
+- [Bitwarden CLI](https://bitwarden.com/help/cli/) installed and available in PATH
+- SSH agent running on your system
+- A Vaultwarden (self-hosted Bitwarden) instance
+
+## Installation
+
+1. Download the script file (`vaultwarden-ssh-agent.ps1`) to your preferred location
+2. Ensure you have the Bitwarden CLI installed:
+
+```powershell
+winget install Bitwarden.CLI
+# or
+choco install bitwarden-cli
+```
+
+## Configuration
+
+### Initial Setup
+
+Create a folder named 'ssh-agent' in your Vaultwarden vault
+
+For each SSH key you want to manage:
+- Create a new item in the 'ssh-agent' folder
+- Paste the public key in the notes field
+- Attach the private key as a file attachment
+
+Note: If you haven't configured the Bitwarden CLI for your Vaultwarden instance yet, don't worry! The script will automatically prompt you for your server URL during the first run.
+
+### Key Item Structure
+
+Each SSH key in Vaultwarden should be structured as follows:
+- Folder: Must be in the 'ssh-agent' folder
+- Name: A descriptive name for your SSH key
+- Notes: Contains the public key (required)
+- Attachment: The private key file (required)
+
+### Usage
+- Basic Usage: `.\vaultwarden-ssh-agent.ps1`
+- To run with detailed debugging information use `-Debug` switch.
+
+### Session Management:
+
+- Reuses existing sessions when available
+- Automatically handles login/unlock operations
+- Stores session token as environment variable
+
+### Key Validation: 
+- Validates both public and private key formats
+- Secure Memory Handling: Implements secure handling for sensitive data
+- Detailed Reporting: Provides summary of successful and failed key additions
+
+### Security Features
+- Secure handling of private keys using `SecureString`
+- Proper cleanup of sensitive data from memory
+- Session token management
+- Key format validation before loading
+
+### Error Handling
+The script includes comprehensive error handling:
+- Validates Vaultwarden configuration
+- Verifies key formats
+- Reports failed operations
+- Provides detailed debug output when needed
+- Troubleshooting
+
+## Common Issues
+
+"ssh-agent folder not found"
+
+- Create a folder named ssh-agent in your Vaultwarden vault
+
+"Failed to add key"
+
+- Verify the SSH agent is running
+- Check key format
+- Run with -Debug flag for more information
+
+## Note on Security
+Never share your private keys
+Keep your Vaultwarden master password secure
+Regularly rotate your SSH keys
+Monitor SSH agent contents with `ssh-add -l`
+
+## Contributing
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Support
+If you encounter any issues or have questions, please open an issue in the repository.
+
+## License
+This script is available under the MIT License. See the LICENSE file for more details.