22e42d721a
- Add SMSG v2 format: binary attachments instead of base64 (~25% smaller) - Add zstd compression (klauspost/compress) - faster than gzip - Add RFC-001: Open Source DRM specification (status: Proposed) - Add live demo page at demo.dapp.fm with WASM decryption - Add mkdemo tool for generating encrypted demo files - Update README with proper documentation - Add format examples and failure case documentation Demo: https://demo.dapp.fm Master Password: PMVXogAJNVe_DDABfTmLYztaJAzsD0R7
171 lines
4.8 KiB
Markdown
171 lines
4.8 KiB
Markdown
# Borg
|
||
|
||
[](https://codecov.io/github/Snider/Borg)
|
||
[](go.mod)
|
||
[](LICENSE)
|
||
|
||
Borg is a CLI tool and Go library for collecting, packaging, and encrypting data into portable, self-contained containers. It supports GitHub repositories, websites, PWAs, and arbitrary files.
|
||
|
||
## Features
|
||
|
||
- **Data Collection** - Clone GitHub repos, crawl websites, download PWAs
|
||
- **Portable Containers** - Package data into DataNodes (in-memory fs.FS) or TIM bundles (OCI-compatible)
|
||
- **Zero-Trust Encryption** - ChaCha20-Poly1305 encryption for TIM containers (.stim) and messages (.smsg)
|
||
- **SMSG Format** - Encrypted message containers with public manifests, attachments, and zstd compression
|
||
- **WASM Support** - Decrypt SMSG files in the browser via WebAssembly
|
||
|
||
## Installation
|
||
|
||
```bash
|
||
# From source
|
||
go install github.com/Snider/Borg@latest
|
||
|
||
# Or build locally
|
||
git clone https://github.com/Snider/Borg.git
|
||
cd Borg
|
||
go build -o borg ./
|
||
```
|
||
|
||
Requires Go 1.25+
|
||
|
||
## Quick Start
|
||
|
||
```bash
|
||
# Clone a GitHub repository into a TIM container
|
||
borg collect github repo https://github.com/user/repo --format tim -o repo.tim
|
||
|
||
# Encrypt a TIM container
|
||
borg compile -f Borgfile -e "password" -o encrypted.stim
|
||
|
||
# Run an encrypted container
|
||
borg run encrypted.stim -p "password"
|
||
|
||
# Inspect container metadata (without decrypting)
|
||
borg inspect encrypted.stim --json
|
||
```
|
||
|
||
## Container Formats
|
||
|
||
| Format | Extension | Description |
|
||
|--------|-----------|-------------|
|
||
| DataNode | `.tar` | In-memory filesystem, portable tarball |
|
||
| TIM | `.tim` | Terminal Isolation Matrix - OCI/runc compatible bundle |
|
||
| Trix | `.trix` | PGP-encrypted DataNode |
|
||
| STIM | `.stim` | ChaCha20-Poly1305 encrypted TIM |
|
||
| SMSG | `.smsg` | Encrypted message with attachments and public manifest |
|
||
|
||
## SMSG - Secure Message Format
|
||
|
||
SMSG is designed for distributing encrypted content with publicly visible metadata:
|
||
|
||
```go
|
||
import "github.com/Snider/Borg/pkg/smsg"
|
||
|
||
// Create and encrypt a message
|
||
msg := smsg.NewMessage("Hello, World!")
|
||
msg.AddBinaryAttachment("track.mp3", audioData, "audio/mpeg")
|
||
|
||
manifest := &smsg.Manifest{
|
||
Title: "Demo Track",
|
||
Artist: "Artist Name",
|
||
}
|
||
|
||
encrypted, _ := smsg.EncryptV2WithManifest(msg, "password", manifest)
|
||
|
||
// Decrypt
|
||
decrypted, _ := smsg.Decrypt(encrypted, "password")
|
||
```
|
||
|
||
**v2 Binary Format** - Stores attachments as raw binary with zstd compression for optimal size.
|
||
|
||
See [RFC-001: Open Source DRM](RFC-001-OSS-DRM.md) for the full specification.
|
||
|
||
**Live Demo**: [demo.dapp.fm](https://demo.dapp.fm)
|
||
|
||
## Borgfile
|
||
|
||
Package files into a TIM container:
|
||
|
||
```dockerfile
|
||
ADD ./app /usr/local/bin/app
|
||
ADD ./config /etc/app/
|
||
```
|
||
|
||
```bash
|
||
borg compile -f Borgfile -o app.tim
|
||
borg compile -f Borgfile -e "secret" -o app.stim # encrypted
|
||
```
|
||
|
||
## CLI Reference
|
||
|
||
```bash
|
||
# Collection
|
||
borg collect github repo <url> # Clone repository
|
||
borg collect github repos <owner> # Clone all repos from user/org
|
||
borg collect website <url> --depth 2 # Crawl website
|
||
borg collect pwa --uri <url> # Download PWA
|
||
|
||
# Compilation
|
||
borg compile -f Borgfile -o out.tim # Plain TIM
|
||
borg compile -f Borgfile -e "pass" # Encrypted STIM
|
||
|
||
# Execution
|
||
borg run container.tim # Run plain TIM
|
||
borg run container.stim -p "pass" # Run encrypted TIM
|
||
|
||
# Inspection
|
||
borg decode file.stim -p "pass" -o out.tar
|
||
borg inspect file.stim [--json]
|
||
```
|
||
|
||
## Documentation
|
||
|
||
```bash
|
||
mkdocs serve # Serve docs locally at http://localhost:8000
|
||
```
|
||
|
||
## Development
|
||
|
||
```bash
|
||
task build # Build binary
|
||
task test # Run tests with coverage
|
||
task clean # Clean build artifacts
|
||
```
|
||
|
||
## Architecture
|
||
|
||
```
|
||
Source (GitHub/Website/PWA)
|
||
↓ collect
|
||
DataNode (in-memory fs.FS)
|
||
↓ serialize
|
||
├── .tar (raw tarball)
|
||
├── .tim (runc container bundle)
|
||
├── .trix (PGP encrypted)
|
||
└── .stim (ChaCha20-Poly1305 encrypted TIM)
|
||
```
|
||
|
||
## License
|
||
|
||
[EUPL-1.2](LICENSE) - European Union Public License
|
||
|
||
---
|
||
|
||
<details>
|
||
<summary>Borg Status Messages (for CLI theming)</summary>
|
||
|
||
**Initialization**
|
||
- `Core engaged… resistance is already buffering.`
|
||
- `Assimilating bytes… stand by for cube‑formation.`
|
||
- `Merging… the Core is rewriting reality, one block at a time.`
|
||
|
||
**Encryption**
|
||
- `Generating cryptographic sigils – the Core whispers to the witch.`
|
||
- `Encrypting payload – the Core feeds data to the witch's cauldron.`
|
||
- `Merge complete – data assimilated, encrypted, and sealed within us.`
|
||
|
||
**VCS Processing**
|
||
- `Initiating clone… the Core replicates the collective into your node.`
|
||
- `Merging branches… conflicts resolved, entropy minimized, assimilation complete.`
|
||
|
||
</details>
|