{"id":31943482,"url":"https://github.com/dspearson/sss","last_synced_at":"2025-10-14T09:57:05.447Z","repository":{"id":317047058,"uuid":"1065784350","full_name":"dspearson/sss","owner":"dspearson","description":"Secure String Substitution 🐍","archived":false,"fork":false,"pushed_at":"2025-09-28T13:44:49.000Z","size":89,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-28T14:41:54.346Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dspearson.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-28T12:26:33.000Z","updated_at":"2025-09-28T12:40:42.000Z","dependencies_parsed_at":"2025-09-28T14:42:01.774Z","dependency_job_id":null,"html_url":"https://github.com/dspearson/sss","commit_stats":null,"previous_names":["dspearson/sss"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/dspearson/sss","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dspearson%2Fsss","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dspearson%2Fsss/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dspearson%2Fsss/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dspearson%2Fsss/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dspearson","download_url":"https://codeload.github.com/dspearson/sss/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dspearson%2Fsss/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279018554,"owners_count":26086405,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-14T02:00:06.444Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-14T09:57:03.322Z","updated_at":"2025-10-14T09:57:05.442Z","avatar_url":"https://github.com/dspearson.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SSS - Secret String Substitution\n\nSSS is a command-line tool for transparent encryption and decryption of text within files using XChaCha20Poly1305 with a modern multi-user architecture. It enables seamless protection of sensitive data embedded in configuration files, scripts, and other text documents.\n\n## Features\n\n- **🔒 Secure Encryption**: Uses XChaCha20Poly1305 authenticated encryption with cryptographically secure random nonces\n- **👥 Multi-User Support**: Asymmetric encryption for team collaboration with individual private keys\n- **🔑 Advanced Key Management**: Integrated keystore with password-protected private keys\n- **📁 Transparent Operation**: Works with any text file format\n- **🛡️ Cross-Platform**: Supports Windows, macOS, and Linux\n- **⚡ High Performance**: Optimised with static regex compilation and buffered I/O\n- **🛡️ Enhanced Security**: Comprehensive input validation, rate limiting, and path traversal protection\n- **⚙️ Flexible Configuration**: Layered configuration system with user settings persistence\n- **🧪 Well-Tested**: Comprehensive test suite\n\n## Quick Start\n\n### Installation\n\n#### Build from Source\n\n```bash\ngit clone https://github.com/dspearson/sss.git\ncd sss\ncargo build --release\n```\n\n### Basic Usage\n\n1. **Initialise a new project**:\n   ```bash\n   sss init\n   # You'll be prompted to enter a username and passphrase for your private key\n   ```\n\n2. **Generate a keypair** (if needed):\n   ```bash\n   sss keys generate\n   # Creates a new keypair with passphrase protection\n   ```\n\n3. **Encrypt sensitive data in a file**:\n   ```bash\n   # Mark sensitive data with ⊕{content} or o+{content}\n   echo \"password=⊕{my-secret-password}\" \u003e config.txt\n\n   # Encrypt marked content\n   sss --user yourname config.txt \u003e config.encrypted.txt\n   ```\n\n4. **Decrypt for viewing**:\n   ```bash\n   sss --user yourname config.encrypted.txt\n   ```\n\n5. **Edit files with automatic encryption/decryption**:\n   ```bash\n   ssse config.encrypted.txt\n   # Uses your system username automatically\n   ```\n\n## String Patterns\n\n- **Plaintext markers**:\n  - `⊕{content}` - UTF-8 marker (default output)\n  - `o+{content}` - ASCII alternative for compatibility\n- **Ciphertext marker**: `⊠{content}` - Indicates encrypted content (always UTF-8)\n\n## Multi-User Architecture\n\n### Key Concepts\n\n- **Private Keys**: Individual Ed25519 keypairs stored encrypted in local keystore\n- **Repository Keys**: Symmetric keys for file encryption, sealed for each project user\n- **Project Configuration**: `.sss.toml` file containing user public keys and sealed repository keys\n\n### Team Collaboration Workflow\n\n1. **Project Owner** initialises project:\n   ```bash\n   sss init alice\n   # Creates project with alice as initial user\n   ```\n\n2. **Add team members**:\n   ```bash\n   # Bob generates his keypair\n   sss keys generate\n   sss keys pubkey \u003e bob-pubkey.txt\n\n   # Alice adds Bob to the project\n   sss users add bob bob-pubkey.txt\n   ```\n\n3. **Team members can now access files**:\n   ```bash\n   # Bob can encrypt/decrypt using his private key\n   sss --user bob secrets.txt\n   ```\n\n## Commands\n\n### Core Commands\n\n```bash\n# Initialise new project\nsss init [username]\n\n# Process files (encrypt/decrypt)\nsss --user \u003cusername\u003e \u003cfile\u003e\nsss --user \u003cusername\u003e --in-place \u003cfile\u003e\nsss --user \u003cusername\u003e --edit \u003cfile\u003e\nsss --user \u003cusername\u003e --render \u003cfile\u003e  # Decrypt and strip markers to plain text\n```\n\n### Key Management\n\n```bash\n# Generate new keypair\nsss keys generate [--force]\n\n# List your private keys\nsss keys list\n\n# Show public key\nsss keys pubkey [--fingerprint]\n\n# Show or set current keypair\nsss keys current [key-id]\n\n# Delete a private key\nsss keys delete \u003ckey-id\u003e\n```\n\n### User Management\n\n```bash\n# Add user to project\nsss users add \u003cusername\u003e \u003cpublic-key-file-or-key\u003e\n\n# Remove user from project\nsss users remove \u003cusername\u003e\n\n# List project users\nsss users list\n\n# Show user information\nsss users info \u003cusername\u003e\n```\n\n### Settings Management\n\n```bash\n# Show current settings\nsss settings show\n\n# Set default username\nsss settings set --username \u003cusername\u003e\n\n# Set preferred editor\nsss settings set --editor \u003ceditor\u003e\n\n# Enable/disable coloured output\nsss settings set --coloured true/false\n\n# Reset all settings to defaults\nsss settings reset --confirm\n\n# Show configuration file locations\nsss settings location\n```\n\n### `ssse` - Editor Command\n\n```bash\n# Edit with automatic decryption/encryption\nssse filename\n```\n\n**Note**: `ssse` uses your system username ($USER/$USERNAME). Create a symlink: `ln -sf sss ssse`\n\nThe editor:\n1. Decrypts all `⊠{}` patterns to `⊕{}` for editing\n2. Launches `$EDITOR` (fallback to `$VISUAL`, then sensible defaults)\n3. Re-encrypts all `⊕{}` and `o+{}` patterns to `⊠{}` on save/exit\n\n## Security Properties\n\n### Cryptographic Security\n\n1. **Authenticated Encryption**: XChaCha20Poly1305 provides both confidentiality and integrity\n2. **Large Nonce Space**: 192-bit random nonces eliminate collision concerns in practice\n3. **Cryptographically Secure Randomness**: Nonces generated using libsodium's CSPRNG\n4. **Forward Security**: Changing keys invalidates all previous ciphertexts\n5. **Unique Ciphertexts**: Random nonces ensure identical plaintexts produce different ciphertexts\n\n### Key Management Security\n\n1. **Asymmetric Architecture**: Private keys never shared between users\n2. **Password Protection**: Private keys encrypted with user passphrases using Argon2id\n3. **Sealed Repository Keys**: Symmetric keys encrypted for each user individually\n4. **Local Keystore**: Private keys stored locally, never transmitted\n5. **Memory Protection**: Cryptographic material securely cleared from memory\n\n### Additional Security Features\n\n1. **Input Validation**: Comprehensive validation with size limits (prevents DoS)\n2. **Rate Limiting**: Password attempt limiting to prevent brute force attacks\n3. **Path Traversal Protection**: File paths validated and canonicalised\n4. **Error Handling**: Sensitive information not leaked in error messages\n5. **Secure Temporary Files**: Created with restrictive permissions (0600 on Unix)\n6. **Memory Safety**: Cryptographic material securely cleared from memory using zeroize\n7. **Custom Error Types**: Structured error handling with specific error categories\n\n## Editor Integrations\n\n### 📝 Emacs Package\n\nSSS includes a comprehensive Emacs package providing seamless integration with powerful features:\n\n#### Features\n- **🔐 Interactive Operations**: Encrypt/decrypt regions, toggle patterns at point, process entire buffers\n- **👥 Multi-User Support**: Project management, user switching, team collaboration\n- **🎨 Syntax Highlighting**: Visual distinction of `⊕{}`, `o+{}`, and `⊠{}` patterns\n- **⚡ Auto-Processing**: Automatic encrypt/decrypt on file open/save\n- **🔥 Doom Integration**: Full Evil operator support, leader keys, text objects\n- **🎯 Smart UI**: Transient menus, completion, password caching\n\n#### Quick Setup\n\n**Standard Emacs:**\n```elisp\n(add-to-list 'load-path \"/path/to/sss/plugins/emacs\")\n(require 'sss)\n(require 'sss-mode)\n(sss-setup-auto-mode)\n```\n\n**Doom Emacs:**\n```elisp\n;; packages.el\n(package! sss :recipe (:local-repo \"/path/to/sss/plugins/emacs\"))\n\n;; config.el\n(use-package! sss\n  :commands sss-mode\n  :config (require 'sss-doom))\n```\n\n#### Key Bindings\n- **Standard**: `C-c s e/d/t` (encrypt/decrypt/toggle)\n- **Doom**: `SPC e e/d/t` + Evil operators `g e/d/t`\n- **Evil Text Objects**: `i s`/`a s` (inner/outer SSS pattern)\n\nSee [`plugins/emacs/README.md`](plugins/emacs/README.md) for complete documentation.\n\n### 🔧 Other Editors\n\nSSS works with any editor through the `ssse` command:\n\n```bash\n# Edit with automatic encrypt/decrypt\nssse myfile.conf\n\n# Or set your preferred editor\nexport EDITOR=vim\nssse myfile.conf\n```\n\n## Configuration\n\n### Project Configuration (`.sss.toml`)\n\n```toml\n# Project metadata\nversion = \"1.0\"\ncreated = \"2025-01-01T00:00:00Z\"\n\n# Users and their sealed repository keys\n[alice]\npublic = \"base64_encoded_public_key\"\nsealed_key = \"base64_encoded_sealed_repository_key\"\nadded = \"2025-01-01T00:00:00Z\"\n\n[bob]\npublic = \"base64_encoded_public_key\"\nsealed_key = \"base64_encoded_sealed_repository_key\"\nadded = \"2025-01-01T00:00:00Z\"\n```\n\n### User Settings\n\nSSS supports layered configuration with the following precedence (highest to lowest):\n\n1. Command-line arguments\n2. Environment variables\n3. User configuration file (`~/.config/sss/settings.toml`)\n4. System defaults\n\nUser settings include:\n- Default username for operations\n- Preferred editor for `ssse` command\n- Coloured output preferences\n\n### Environment Variables\n\n- `EDITOR`: Preferred text editor for `ssse`\n- `VISUAL`: Alternative text editor\n- `SSS_USER`: Default username (overrides config file setting)\n\n## Examples\n\n### Project Setup\n\n```bash\n# Create new project\nsss init alice\n# Enter passphrase when prompted\n\n# Add team member\n# (Bob first generates keypair and shares public key)\nsss users add bob bob-public-key.txt\n\n# Process files\nsss --user alice config.txt\nsss --user bob config.txt  # Both can access same files\n```\n\n### Key Management\n\n```bash\n# View your keys\nsss keys list\nsss keys pubkey\n\n# Generate new keypair\nsss keys generate --force  # Overwrites existing\n\n# Set current keypair\nsss keys current my-key-id\n```\n\n### Advanced Usage\n\n```bash\n# Edit file in-place with encryption\nsss --user alice --in-place secrets.conf\n\n# Render encrypted file to raw plaintext\nsss --user alice --render encrypted.txt \u003e plaintext.txt\n\n# Use SSS_USER environment variable for convenience\nexport SSS_USER=alice\nsss config.txt\n```\n\n## Building\n\n### Requirements\n\n- Rust 1.70+\n- libsodium (automatically handled by libsodium-sys)\n\n### Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/dspearson/sss.git\ncd sss\n\n# Run unit tests (119 tests total)\ncargo test\n\n# Run specific test suites\ncargo test --lib                        # Unit tests\ncargo test --test command_integration   # Command integration tests\ncargo test --test crypto_properties     # Property-based crypto tests\ncargo test --test editor_integration    # Editor integration tests\n\n# Run all tests including ignored ones (requires interaction)\ncargo test -- --include-ignored\n\n# Check code quality\ncargo clippy -- -D warnings\n\n# Build for your platform\ncargo build --release\n\n# Cross-compile for other platforms (requires cross)\ncargo install cross\ncross build --target x86_64-unknown-linux-musl --release\n```\n\n### Code Structure\n\nThe codebase is organised into well-defined modules:\n\n- `src/main.rs` - CLI interface and command routing\n- `src/commands/` - Modular command handlers\n  - `init.rs` - Project initialisation\n  - `keys.rs` - Key management operations\n  - `users.rs` - User management for multi-user projects\n  - `process.rs` - File processing (encrypt/decrypt/edit)\n  - `settings.rs` - Configuration and user settings management\n- `src/crypto.rs` - Core cryptographic operations\n- `src/keystore.rs` - Private key storage and management\n- `src/config_manager.rs` - Layered configuration management system\n- `src/validation.rs` - Input validation and sanitisation\n- `src/rate_limiter.rs` - Password attempt rate limiting for security\n- `src/processor.rs` - File content processing with optimised regex patterns\n- `src/project.rs` - Project configuration handling\n- `src/error.rs` - Custom error types and structured error handling\n- `src/secure_memory.rs` - Secure memory handling utilities\n- `tests/` - Comprehensive test suite with unit and integration tests\n\n## Contributing\n\nContributions are welcome! Please ensure all tests pass and follow the existing code style.\n\n### Development Guidelines\n\n- Use British English spelling in all documentation and user-facing text\n- Follow Rust conventions and run `cargo clippy` before submitting\n- Add tests for new functionality\n- Update documentation for any API changes\n\n## Licence\n\nThis project is licensed under the ISC Licence - see the [LICENCE](LICENCE) file for details.\n\n## Acknowledgements\n\n- Built with [libsodium](https://libsodium.gitbook.io/) for cryptographic operations\n- Uses modern Rust cryptography patterns and best practices\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdspearson%2Fsss","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdspearson%2Fsss","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdspearson%2Fsss/lists"}