| --- |
| license: agpl-3.0 |
| tags: |
| - snapkitty |
| - cryptography |
| - python |
| --- |
| > Source: [github.com/SNAPKITTYWEST/env-ship-public](https://github.com/SNAPKITTYWEST/env-ship-public) |
|
|
| # env-ship |
|
|
| Verifiable script envelope utility for governed execution. |
|
|
| [](https://github.com/your-org/env-ship/actions/workflows/envelope-verification.yml) |
|
|
| ## What it does |
|
|
| Wraps shell scripts in structured JSON envelopes with: |
| - SHA-256 payload hashes |
| - Optional Ed25519 signatures |
| - Proof references (Lean/Isabelle theorem IDs, WORM receipts) |
| - Schema validation |
| - Provenance metadata |
|
|
| ## The goal |
|
|
| No raw script execution without a receipt. |
| No deployment without verification. |
| No action without provenance. |
|
|
| ## Install |
|
|
| ```bash |
| git clone https://github.com/your-org/env-ship.git |
| cd env-ship |
| chmod +x bin/*.sh |
| export PATH="$PWD/bin:$PATH" |
| ``` |
|
|
| Or install globally: |
|
|
| ```bash |
| sudo cp bin/env-ship.sh /usr/local/bin/env-ship |
| sudo cp bin/validate-envelope.sh /usr/local/bin/validate-envelope |
| ``` |
|
|
| ## Quick start |
|
|
| ```bash |
| # Create a script |
| cat > deploy.sh <<'EOF' |
| #!/bin/bash |
| set -euo pipefail |
| echo "Deploying..." |
| EOF |
| chmod +x deploy.sh |
| |
| # Wrap it in an envelope |
| env-ship encapsulate deploy.sh |
| |
| # Verify the envelope |
| env-ship verify deploy.envelope |
| |
| # Extract and run |
| env-ship extract deploy.envelope verified.sh |
| ./verified.sh |
| ``` |
|
|
| ## Commands |
|
|
| | Command | Description | |
| |---------|-------------| |
| | `encapsulate` | Create envelope from script | |
| | `verify` | Verify envelope integrity | |
| | `extract` | Extract script from envelope | |
| | `inspect` | Display envelope metadata | |
| | `link-proof` | Attach proof reference | |
| | `sign` | Add Ed25519 signature | |
| | `batch` | Process all .sh files | |
|
|
| ## Examples |
|
|
| ### Basic encapsulation |
|
|
| ```bash |
| env-ship encapsulate deploy.sh |
| # Creates: deploy.envelope |
| ``` |
|
|
| ### With proof reference |
|
|
| ```bash |
| env-ship encapsulate deploy.sh deploy.envelope "lean://Theorems/Conduction.lean" |
| ``` |
|
|
| ### With signing |
|
|
| ```bash |
| # Generate keys |
| openssl genpkey -algorithm ED25519 -out private.pem |
| openssl pkey -in private.pem -pubout -out public.pem |
| |
| # Sign envelope |
| env-ship encapsulate deploy.sh deploy.envelope "" private.pem |
| |
| # Verify with signature |
| env-ship verify deploy.envelope --verify-signature public.pem |
| ``` |
|
|
| ### Batch processing |
|
|
| ```bash |
| env-ship batch ./scripts ./proofs private.pem |
| ``` |
|
|
| ## Configuration |
|
|
| Override defaults via environment variables: |
|
|
| ```bash |
| export ENVELOPE_AUTHOR="your-name" |
| export ENVELOPE_INFRASTRUCTURE="your-infra" |
| export TRUST_PROTOCOL="your-protocol" |
| export ENVELOPE_AUDIT_SPEC="your-uuid" |
| ``` |
|
|
| ## How it works |
|
|
| ``` |
| script |
| → base64 encode |
| → SHA-256 hash |
| → JSON envelope |
| → optional Ed25519 signature |
| → optional proof reference |
| → schema validation |
| → verified extraction |
| → governed execution |
| ``` |
|
|
| ## Envelope format |
|
|
| ```json |
| { |
| "envelope_version": "1.0.0", |
| "envelope_id": "env-a1b2c3d4e5f6g7h8-1720000000", |
| "author": "your-name", |
| "infrastructure": "your-infra", |
| "trust_protocol": "your-protocol", |
| "audit_spec": "uuid", |
| "timestamp": "2026-07-05T00:00:00Z", |
| "hash": "sha256-of-original-script", |
| "proof_ref": "lean://Theorems/Proof.lean", |
| "payload_b64": "base64-encoded-script", |
| "signature": "optional-ed25519-signature" |
| } |
| ``` |
|
|
| ## Dependencies |
|
|
| - `jq` - JSON processing |
| - `sha256sum` - Hash computation |
| - `base64` - Payload encoding |
| - `openssl` - Signature operations |
|
|
| Install on Ubuntu/Debian: |
|
|
| ```bash |
| sudo apt-get install jq coreutils openssl |
| ``` |
|
|
| Install on macOS: |
|
|
| ```bash |
| brew install jq |
| ``` |
|
|
| ## Interactive Demo |
|
|
| ```bash |
| # Run the full interactive walkthrough |
| ./demo/interactive.sh |
| |
| # Or quick one-liner |
| ./demo/quick.sh |
| ``` |
|
|
| ## Test Suite |
|
|
| ```bash |
| # Run all tests |
| bash tests/test.sh |
| ``` |
|
|
| ## CI/CD |
|
|
| GitHub Actions workflow validates on every push: |
| - Encapsulate → Verify → Extract → Diff |
| - Batch processing |
| - Schema validation |
|
|
| ## License |
|
|
| Licensed under **AGPL-3.0**. Full text: [LICENSE](LICENSE). |
|
|
| Releases published before 2026-10-07 were licensed under MIT; copies obtained under those terms keep them. |
|
|
| ### 💼 Commercial License |
|
|
| SnapKitty code is free and open under **AGPL-3.0** for open-source use. Building a commercial product or service? A **proprietary commercial license** from Snapkitty Collective LLC lets you ship this code without the AGPL's source-sharing and network-use obligations. |
|
|
| **[→ Get a commercial license](mailto:A.parr@belespritdaccord.uk?subject=Commercial%20license:%20env-ship-public)** · A.parr@belespritdaccord.uk |
|
|
