{"id":30718248,"url":"https://github.com/cod-e-codes/terminal-link","last_synced_at":"2025-09-03T09:48:24.792Z","repository":{"id":308939895,"uuid":"1034604114","full_name":"Cod-e-Codes/terminal-link","owner":"Cod-e-Codes","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-08T19:12:03.000Z","size":36,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-08T20:45:24.359Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Cod-e-Codes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2025-08-08T16:59:36.000Z","updated_at":"2025-08-08T19:12:07.000Z","dependencies_parsed_at":"2025-08-08T22:15:23.066Z","dependency_job_id":null,"html_url":"https://github.com/Cod-e-Codes/terminal-link","commit_stats":null,"previous_names":["cod-e-codes/terminal-link"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Cod-e-Codes/terminal-link","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cod-e-Codes%2Fterminal-link","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cod-e-Codes%2Fterminal-link/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cod-e-Codes%2Fterminal-link/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cod-e-Codes%2Fterminal-link/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Cod-e-Codes","download_url":"https://codeload.github.com/Cod-e-Codes/terminal-link/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cod-e-Codes%2Fterminal-link/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273423958,"owners_count":25103146,"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-09-03T02:00:09.631Z","response_time":76,"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-09-03T09:48:23.585Z","updated_at":"2025-09-03T09:48:24.778Z","avatar_url":"https://github.com/Cod-e-Codes.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Terminal-Link MVP\r\n\r\nA LAN-only, secure, terminal-native messaging and file transfer application with end-to-end encryption.\r\n\r\n**Current Release: v0.1.0** - Initial MVP with comprehensive test suite, cross-platform builds, and secure file transfer capabilities.\r\n\r\n## Features\r\n\r\n- **LAN-only operation**: Uses mDNS discovery with manual IP fallback\r\n- **End-to-end encryption**: Noise_XX protocol with X25519 + ChaCha20-Poly1305\r\n- **Simple pairing**: 6-digit verification codes for secure pairing\r\n- **Real-time messaging**: Bidirectional text messaging with timestamps\r\n- **Secure file transfer**: Chunked file transfer with SHA256 verification and resume capability\r\n- **Cross-platform**: Single binary for Linux, macOS, Windows, and Android\r\n\r\n## Quick Start\r\n\r\n### Prerequisites\r\n\r\n- Go 1.21 or later\r\n- Network connectivity between devices\r\n\r\n### Build\r\n\r\n```bash\r\n# Clone and build\r\ngit clone \u003crepository\u003e\r\ncd terminal-link\r\ngo mod tidy\r\n\r\n# Build for current platform\r\ngo build -o terminal-link main.go\r\n\r\n# Or use the Makefile for easier builds\r\nmake build\r\n\r\n# Build for all platforms\r\nmake dist\r\n```\r\n\r\n### Usage\r\n\r\n#### Discovery Mode (Server)\r\n\r\nStart the discovery service to accept incoming connections:\r\n\r\n```bash\r\n# Start discovery on default port 8080\r\ngo run main.go --discover\r\n\r\n# Or specify a custom port\r\ngo run main.go --discover --port 9000\r\n```\r\n\r\n#### Connect Mode (Client)\r\n\r\nConnect to a discovered peer:\r\n\r\n```bash\r\n# Connect to a specific IP and port\r\ngo run main.go --connect 192.168.1.100:8080\r\n\r\n# Connect and immediately send a file\r\ngo run main.go --connect 192.168.1.100:8080 --send-file /path/to/file.txt\r\n```\r\n\r\n### Pairing Process\r\n\r\n1. Start discovery mode on one device\r\n2. Start discovery mode on another device (or connect directly)\r\n3. When devices connect, both will display a 6-digit pairing code\r\n4. Verify the codes match on both devices\r\n5. Begin messaging!\r\n\r\n## Protocol Details\r\n\r\n### Discovery\r\n- Uses mDNS service `_tlnk._tcp` on port 8080 (default)\r\n- Automatically discovers peers on the same LAN\r\n- Manual connection via IP:port as fallback\r\n\r\n### Security\r\n- **Noise_XX handshake**: Ephemeral X25519 key exchange\r\n- **Encryption**: ChaCha20-Poly1305 for message encryption\r\n- **Authentication**: Built into Noise protocol\r\n- **Pairing verification**: 6-digit codes prevent MITM attacks\r\n\r\n### Message Format\r\n\r\n**Text Messages:**\r\n```json\r\n{\r\n  \"type\": \"text\",\r\n  \"content\": \"Hello, World!\",\r\n  \"timestamp\": 1640995200,\r\n  \"id\": \"a1b2c3d4e5f67890\"\r\n}\r\n```\r\n\r\n**File Transfer:**\r\n```json\r\n// File metadata\r\n{\r\n  \"type\": \"file_meta\",\r\n  \"filename\": \"document.pdf\",\r\n  \"size\": 1048576,\r\n  \"sha256\": \"a1b2c3d4e5f67890...\",\r\n  \"chunk_size\": 65536,\r\n  \"id\": \"file123\"\r\n}\r\n\r\n// File chunk\r\n{\r\n  \"type\": \"file_chunk\",\r\n  \"file_id\": \"file123\",\r\n  \"chunk_id\": 0,\r\n  \"data\": \"base64_encoded_chunk_data\",\r\n  \"checksum\": \"chunk_checksum\"\r\n}\r\n```\r\n\r\n## Testing\r\n\r\nRun the unit tests:\r\n\r\n```bash\r\ngo test\r\n```\r\n\r\n### Manual Testing\r\n\r\n1. **Two-terminal test**:\r\n   ```bash\r\n   # Terminal 1\r\n   go run main.go --discover\r\n   \r\n   # Terminal 2  \r\n   go run main.go --connect 127.0.0.1:8080\r\n   ```\r\n\r\n2. **File transfer test**:\r\n   ```bash\r\n   # Terminal 1 - Start discovery\r\n   go run main.go --discover\r\n   \r\n   # Terminal 2 - Connect and send file\r\n   go run main.go --connect 127.0.0.1:8080 --send-file test.txt\r\n   \r\n   # Or use interactive mode\r\n   go run main.go --connect 127.0.0.1:8080\r\n   # Then type: /send test.txt\r\n   ```\r\n\r\n3. **Cross-device test**:\r\n   - Start discovery on device A\r\n   - Find device A's IP address\r\n   - Connect from device B using `--connect \u003cdevice-a-ip\u003e:8080`\r\n\r\n## Architecture\r\n\r\n```\r\nPeer A (Desktop) ←→ LAN ←→ Peer B (Phone)\r\n     ↑                              ↑\r\n  Discovery                    Discovery\r\n     ↓                              ↓\r\n  Noise_XX Handshake ←→ Noise_XX Handshake\r\n     ↓                              ↓\r\n  Encrypted Channel ←→ Encrypted Channel\r\n     ↓                              ↓\r\n  Messaging ←→ Messaging\r\n```\r\n\r\n## Security Considerations\r\n\r\n- **No cloud components**: All communication is peer-to-peer\r\n- **Persistent encrypted keys**: Keys stored encrypted with user password\r\n- **Verification codes**: Manual verification prevents impersonation\r\n- **Secure key storage**: AES-GCM encryption for keyfile with salt and nonce\r\n\r\n## Troubleshooting\r\n\r\n### Common Issues\r\n\r\n1. **Discovery not working**:\r\n   - Check firewall settings\r\n   - Try manual connection with `--connect \u003cip\u003e:\u003cport\u003e`\r\n   - Ensure both devices are on the same LAN\r\n\r\n2. **Connection refused**:\r\n   - Verify the target device is running in discovery mode\r\n   - Check port number (default: 8080)\r\n   - Ensure no firewall blocking\r\n\r\n3. **Handshake fails**:\r\n   - Check network connectivity\r\n   - Verify pairing codes match\r\n   - Restart both applications\r\n\r\n### Debug Mode\r\n\r\nFor troubleshooting, check the console output for:\r\n- Discovery messages showing found peers\r\n- Handshake progress and pairing codes\r\n- Connection status and errors\r\n\r\n## Development\r\n\r\n### Dependencies\r\n\r\n- `github.com/flynn/noise`: Noise protocol implementation\r\n- `github.com/grandcat/zeroconf`: mDNS discovery\r\n- `github.com/charmbracelet/bubbletea`: TUI framework (future)\r\n\r\n### Build System\r\n\r\nThe project includes a comprehensive build system:\r\n\r\n```bash\r\n# Development workflow\r\nmake dev          # Build, test, and lint\r\n\r\n# Build options\r\nmake build        # Build for current platform\r\nmake dist         # Build for all platforms\r\nmake test         # Run tests\r\nmake lint         # Run linter\r\nmake clean        # Clean build artifacts\r\n\r\n# Cross-compilation scripts\r\n./build.sh        # Linux/macOS build script\r\n./build.bat       # Windows build script\r\n```\r\n\r\n### CI/CD Pipeline\r\n\r\nGitHub Actions automatically:\r\n- Runs tests and linting on every push/PR\r\n- Builds binaries for all target platforms\r\n- Creates releases with attached binaries\r\n- Validates binary sizes (\u003c 15MB limit)\r\n\r\n**Supported Platforms:**\r\n- Linux (amd64, arm64) ✅\r\n- Windows (amd64, arm64) ✅\r\n- Android (arm64 via Termux) ✅\r\n- macOS (amd64, arm64) - requires native macOS environment\r\n\r\n### Manual Cross-Compilation\r\n\r\n```bash\r\n# Linux\r\nGOOS=linux GOARCH=amd64 go build -o terminal-link-linux-amd64\r\n\r\n# macOS\r\nGOOS=darwin GOARCH=amd64 go build -o terminal-link-darwin-amd64\r\n\r\n# Windows\r\nGOOS=windows GOARCH=amd64 go build -o terminal-link-windows-amd64.exe\r\n\r\n# Android (for Termux)\r\nGOOS=linux GOARCH=arm64 go build -o terminal-link-android-arm64\r\n```\r\n\r\n## Roadmap\r\n\r\n- [x] File transfer with chunking and SHA256 verification\r\n- [x] Cross-compilation CI/CD with GitHub Actions\r\n- [x] Encrypted keyfile storage for persistent keys\r\n- [x] Comprehensive packaging and release system\r\n- [ ] Resume functionality for interrupted transfers\r\n- [ ] TUI interface with message history\r\n- [ ] Android Termux compatibility\r\n- [ ] Notification forwarding\r\n\r\n## License\r\n\r\nMIT License - see LICENSE file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcod-e-codes%2Fterminal-link","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcod-e-codes%2Fterminal-link","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcod-e-codes%2Fterminal-link/lists"}