SNAPKITTYWEST commited on
Commit
e309f34
Β·
verified Β·
1 Parent(s): b7f7f63

Sync with GitHub, license metadata from LICENSE files, commercial license notice

Browse files

metadata license: None -> mit
README: License section kept (already accurate)
README: GitHub source link added

Files changed (1) hide show
  1. README.md +203 -195
README.md CHANGED
@@ -1,195 +1,203 @@
1
- # env-ship
2
-
3
- Verifiable script envelope utility for governed execution.
4
-
5
- [![Envelope Verification](https://github.com/your-org/env-ship/actions/workflows/envelope-verification.yml/badge.svg)](https://github.com/your-org/env-ship/actions/workflows/envelope-verification.yml)
6
-
7
- ## What it does
8
-
9
- Wraps shell scripts in structured JSON envelopes with:
10
- - SHA-256 payload hashes
11
- - Optional Ed25519 signatures
12
- - Proof references (Lean/Isabelle theorem IDs, WORM receipts)
13
- - Schema validation
14
- - Provenance metadata
15
-
16
- ## The goal
17
-
18
- No raw script execution without a receipt.
19
- No deployment without verification.
20
- No action without provenance.
21
-
22
- ## Install
23
-
24
- ```bash
25
- git clone https://github.com/your-org/env-ship.git
26
- cd env-ship
27
- chmod +x bin/*.sh
28
- export PATH="$PWD/bin:$PATH"
29
- ```
30
-
31
- Or install globally:
32
-
33
- ```bash
34
- sudo cp bin/env-ship.sh /usr/local/bin/env-ship
35
- sudo cp bin/validate-envelope.sh /usr/local/bin/validate-envelope
36
- ```
37
-
38
- ## Quick start
39
-
40
- ```bash
41
- # Create a script
42
- cat > deploy.sh <<'EOF'
43
- #!/bin/bash
44
- set -euo pipefail
45
- echo "Deploying..."
46
- EOF
47
- chmod +x deploy.sh
48
-
49
- # Wrap it in an envelope
50
- env-ship encapsulate deploy.sh
51
-
52
- # Verify the envelope
53
- env-ship verify deploy.envelope
54
-
55
- # Extract and run
56
- env-ship extract deploy.envelope verified.sh
57
- ./verified.sh
58
- ```
59
-
60
- ## Commands
61
-
62
- | Command | Description |
63
- |---------|-------------|
64
- | `encapsulate` | Create envelope from script |
65
- | `verify` | Verify envelope integrity |
66
- | `extract` | Extract script from envelope |
67
- | `inspect` | Display envelope metadata |
68
- | `link-proof` | Attach proof reference |
69
- | `sign` | Add Ed25519 signature |
70
- | `batch` | Process all .sh files |
71
-
72
- ## Examples
73
-
74
- ### Basic encapsulation
75
-
76
- ```bash
77
- env-ship encapsulate deploy.sh
78
- # Creates: deploy.envelope
79
- ```
80
-
81
- ### With proof reference
82
-
83
- ```bash
84
- env-ship encapsulate deploy.sh deploy.envelope "lean://Theorems/Conduction.lean"
85
- ```
86
-
87
- ### With signing
88
-
89
- ```bash
90
- # Generate keys
91
- openssl genpkey -algorithm ED25519 -out private.pem
92
- openssl pkey -in private.pem -pubout -out public.pem
93
-
94
- # Sign envelope
95
- env-ship encapsulate deploy.sh deploy.envelope "" private.pem
96
-
97
- # Verify with signature
98
- env-ship verify deploy.envelope --verify-signature public.pem
99
- ```
100
-
101
- ### Batch processing
102
-
103
- ```bash
104
- env-ship batch ./scripts ./proofs private.pem
105
- ```
106
-
107
- ## Configuration
108
-
109
- Override defaults via environment variables:
110
-
111
- ```bash
112
- export ENVELOPE_AUTHOR="your-name"
113
- export ENVELOPE_INFRASTRUCTURE="your-infra"
114
- export TRUST_PROTOCOL="your-protocol"
115
- export ENVELOPE_AUDIT_SPEC="your-uuid"
116
- ```
117
-
118
- ## How it works
119
-
120
- ```
121
- script
122
- β†’ base64 encode
123
- β†’ SHA-256 hash
124
- β†’ JSON envelope
125
- β†’ optional Ed25519 signature
126
- β†’ optional proof reference
127
- β†’ schema validation
128
- β†’ verified extraction
129
- β†’ governed execution
130
- ```
131
-
132
- ## Envelope format
133
-
134
- ```json
135
- {
136
- "envelope_version": "1.0.0",
137
- "envelope_id": "env-a1b2c3d4e5f6g7h8-1720000000",
138
- "author": "your-name",
139
- "infrastructure": "your-infra",
140
- "trust_protocol": "your-protocol",
141
- "audit_spec": "uuid",
142
- "timestamp": "2026-07-05T00:00:00Z",
143
- "hash": "sha256-of-original-script",
144
- "proof_ref": "lean://Theorems/Proof.lean",
145
- "payload_b64": "base64-encoded-script",
146
- "signature": "optional-ed25519-signature"
147
- }
148
- ```
149
-
150
- ## Dependencies
151
-
152
- - `jq` - JSON processing
153
- - `sha256sum` - Hash computation
154
- - `base64` - Payload encoding
155
- - `openssl` - Signature operations
156
-
157
- Install on Ubuntu/Debian:
158
-
159
- ```bash
160
- sudo apt-get install jq coreutils openssl
161
- ```
162
-
163
- Install on macOS:
164
-
165
- ```bash
166
- brew install jq
167
- ```
168
-
169
- ## Interactive Demo
170
-
171
- ```bash
172
- # Run the full interactive walkthrough
173
- ./demo/interactive.sh
174
-
175
- # Or quick one-liner
176
- ./demo/quick.sh
177
- ```
178
-
179
- ## Test Suite
180
-
181
- ```bash
182
- # Run all tests
183
- bash tests/test.sh
184
- ```
185
-
186
- ## CI/CD
187
-
188
- GitHub Actions workflow validates on every push:
189
- - Encapsulate β†’ Verify β†’ Extract β†’ Diff
190
- - Batch processing
191
- - Schema validation
192
-
193
- ## License
194
-
195
- MIT
 
 
 
 
 
 
 
 
 
1
+ ---
2
+ license: mit
3
+ tags:
4
+ - snapkitty
5
+ ---
6
+
7
+ > Source: [github.com/SNAPKITTYWEST/env-ship-public](https://github.com/SNAPKITTYWEST/env-ship-public)
8
+
9
+ # env-ship
10
+
11
+ Verifiable script envelope utility for governed execution.
12
+
13
+ [![Envelope Verification](https://github.com/your-org/env-ship/actions/workflows/envelope-verification.yml/badge.svg)](https://github.com/your-org/env-ship/actions/workflows/envelope-verification.yml)
14
+
15
+ ## What it does
16
+
17
+ Wraps shell scripts in structured JSON envelopes with:
18
+ - SHA-256 payload hashes
19
+ - Optional Ed25519 signatures
20
+ - Proof references (Lean/Isabelle theorem IDs, WORM receipts)
21
+ - Schema validation
22
+ - Provenance metadata
23
+
24
+ ## The goal
25
+
26
+ No raw script execution without a receipt.
27
+ No deployment without verification.
28
+ No action without provenance.
29
+
30
+ ## Install
31
+
32
+ ```bash
33
+ git clone https://github.com/your-org/env-ship.git
34
+ cd env-ship
35
+ chmod +x bin/*.sh
36
+ export PATH="$PWD/bin:$PATH"
37
+ ```
38
+
39
+ Or install globally:
40
+
41
+ ```bash
42
+ sudo cp bin/env-ship.sh /usr/local/bin/env-ship
43
+ sudo cp bin/validate-envelope.sh /usr/local/bin/validate-envelope
44
+ ```
45
+
46
+ ## Quick start
47
+
48
+ ```bash
49
+ # Create a script
50
+ cat > deploy.sh <<'EOF'
51
+ #!/bin/bash
52
+ set -euo pipefail
53
+ echo "Deploying..."
54
+ EOF
55
+ chmod +x deploy.sh
56
+
57
+ # Wrap it in an envelope
58
+ env-ship encapsulate deploy.sh
59
+
60
+ # Verify the envelope
61
+ env-ship verify deploy.envelope
62
+
63
+ # Extract and run
64
+ env-ship extract deploy.envelope verified.sh
65
+ ./verified.sh
66
+ ```
67
+
68
+ ## Commands
69
+
70
+ | Command | Description |
71
+ |---------|-------------|
72
+ | `encapsulate` | Create envelope from script |
73
+ | `verify` | Verify envelope integrity |
74
+ | `extract` | Extract script from envelope |
75
+ | `inspect` | Display envelope metadata |
76
+ | `link-proof` | Attach proof reference |
77
+ | `sign` | Add Ed25519 signature |
78
+ | `batch` | Process all .sh files |
79
+
80
+ ## Examples
81
+
82
+ ### Basic encapsulation
83
+
84
+ ```bash
85
+ env-ship encapsulate deploy.sh
86
+ # Creates: deploy.envelope
87
+ ```
88
+
89
+ ### With proof reference
90
+
91
+ ```bash
92
+ env-ship encapsulate deploy.sh deploy.envelope "lean://Theorems/Conduction.lean"
93
+ ```
94
+
95
+ ### With signing
96
+
97
+ ```bash
98
+ # Generate keys
99
+ openssl genpkey -algorithm ED25519 -out private.pem
100
+ openssl pkey -in private.pem -pubout -out public.pem
101
+
102
+ # Sign envelope
103
+ env-ship encapsulate deploy.sh deploy.envelope "" private.pem
104
+
105
+ # Verify with signature
106
+ env-ship verify deploy.envelope --verify-signature public.pem
107
+ ```
108
+
109
+ ### Batch processing
110
+
111
+ ```bash
112
+ env-ship batch ./scripts ./proofs private.pem
113
+ ```
114
+
115
+ ## Configuration
116
+
117
+ Override defaults via environment variables:
118
+
119
+ ```bash
120
+ export ENVELOPE_AUTHOR="your-name"
121
+ export ENVELOPE_INFRASTRUCTURE="your-infra"
122
+ export TRUST_PROTOCOL="your-protocol"
123
+ export ENVELOPE_AUDIT_SPEC="your-uuid"
124
+ ```
125
+
126
+ ## How it works
127
+
128
+ ```
129
+ script
130
+ β†’ base64 encode
131
+ β†’ SHA-256 hash
132
+ β†’ JSON envelope
133
+ β†’ optional Ed25519 signature
134
+ β†’ optional proof reference
135
+ β†’ schema validation
136
+ β†’ verified extraction
137
+ β†’ governed execution
138
+ ```
139
+
140
+ ## Envelope format
141
+
142
+ ```json
143
+ {
144
+ "envelope_version": "1.0.0",
145
+ "envelope_id": "env-a1b2c3d4e5f6g7h8-1720000000",
146
+ "author": "your-name",
147
+ "infrastructure": "your-infra",
148
+ "trust_protocol": "your-protocol",
149
+ "audit_spec": "uuid",
150
+ "timestamp": "2026-07-05T00:00:00Z",
151
+ "hash": "sha256-of-original-script",
152
+ "proof_ref": "lean://Theorems/Proof.lean",
153
+ "payload_b64": "base64-encoded-script",
154
+ "signature": "optional-ed25519-signature"
155
+ }
156
+ ```
157
+
158
+ ## Dependencies
159
+
160
+ - `jq` - JSON processing
161
+ - `sha256sum` - Hash computation
162
+ - `base64` - Payload encoding
163
+ - `openssl` - Signature operations
164
+
165
+ Install on Ubuntu/Debian:
166
+
167
+ ```bash
168
+ sudo apt-get install jq coreutils openssl
169
+ ```
170
+
171
+ Install on macOS:
172
+
173
+ ```bash
174
+ brew install jq
175
+ ```
176
+
177
+ ## Interactive Demo
178
+
179
+ ```bash
180
+ # Run the full interactive walkthrough
181
+ ./demo/interactive.sh
182
+
183
+ # Or quick one-liner
184
+ ./demo/quick.sh
185
+ ```
186
+
187
+ ## Test Suite
188
+
189
+ ```bash
190
+ # Run all tests
191
+ bash tests/test.sh
192
+ ```
193
+
194
+ ## CI/CD
195
+
196
+ GitHub Actions workflow validates on every push:
197
+ - Encapsulate β†’ Verify β†’ Extract β†’ Diff
198
+ - Batch processing
199
+ - Schema validation
200
+
201
+ ## License
202
+
203
+ MIT