Skip to content

Commit c5e1720

Browse files
author
Bruno Baumgartner
committed
Add ZIP bundle export
1 parent 40fabb9 commit c5e1720

6 files changed

Lines changed: 1059 additions & 34 deletions

File tree

‎README.md‎

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# VSC — Versioned State Commit
22

3-
**v1.16 — Evidence Bundle Verification**
3+
**v1.17 — ZIP Bundle Export**
44

55
Research prototype / proof-of-concept. Not production-ready.
66

@@ -336,6 +336,41 @@ Result: PASS
336336

337337
---
338338

339+
## VSC v1.17 ZIP Bundle Export
340+
341+
VSC v1.17 adds **ZIP Bundle Export** — a command to package an existing evidence bundle directory into a shareable ZIP archive.
342+
343+
```bash
344+
npm run vsc -- zip-bundle output\json-event-bundles\vsc-json-event-bundle-408C8C13C4D4-to-ED9566562A13
345+
```
346+
347+
**What it does:**
348+
- Creates a `.zip` file from the bundle folder
349+
- Outputs to `output/zips/<bundle-name>.zip`
350+
- Preserves the bundle directory structure inside the ZIP
351+
- Does not modify the source bundle
352+
353+
**Expected output:**
354+
```
355+
VSC v1.17 — ZIP Bundle Export
356+
...
357+
ZIP path: output\zips\vsc-json-event-bundle-408C8C13C4D4-to-ED9566562A13.zip
358+
Files included: 108
359+
ZIP size: 245.6 KB
360+
Result: PASS
361+
```
362+
363+
**Use cases:**
364+
- **Email distribution** — Share bundles as single-file attachments
365+
- **Archive storage** — Compress bundles for long-term storage
366+
- **Distribution packaging** — Prepare bundles for download/release
367+
368+
**Note:** The ZIP file is created in `output/zips/` and is not committed to Git (see `.gitignore`).
369+
370+
→ [Full ZIP Bundle Export documentation](docs/vsc-v1-17-zip-bundle-export.md)
371+
372+
---
373+
339374
## VSC v1.10 Static Showcase
340375

341376
VSC v1.10 adds a static showcase export. One command generates a portable `showcase/` folder with the SVG seals, demo metrics, verification summary, and gallery — no server required, opens in any browser.

‎docs/vsc-v1-17-zip-bundle-export.md‎

Lines changed: 257 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,257 @@
1+
# VSC v1.17 — ZIP Bundle Export
2+
3+
**Release Date:** v1.17
4+
**Status:** Research prototype / proof-of-concept
5+
6+
---
7+
8+
## Overview
9+
10+
VSC v1.17 adds **ZIP Bundle Export** — a command to package an existing evidence bundle directory into a shareable ZIP archive without modifying the source bundle.
11+
12+
This feature completes the bundle lifecycle:
13+
- **v1.14** — Export evidence bundles
14+
- **v1.15** — Export JSON event evidence bundles
15+
- **v1.16** — Verify exported bundles
16+
- **v1.17** — Package bundles into ZIP archives (this release)
17+
18+
---
19+
20+
## Command
21+
22+
```bash
23+
npm run vsc -- zip-bundle <bundle-folder>
24+
```
25+
26+
### Examples
27+
28+
```bash
29+
# ZIP a generic evidence bundle
30+
npm run vsc -- zip-bundle output\bundles\vsc-bundle-21A8390BFA3F-to-954BEB0FF3AA
31+
32+
# ZIP a JSON event evidence bundle
33+
npm run vsc -- zip-bundle output\json-event-bundles\vsc-json-event-bundle-408C8C13C4D4-to-ED9566562A13
34+
35+
# ZIP with relative path
36+
npm run vsc -- zip-bundle .\output\bundles\vsc-bundle-21A8390BFA3F-to-954BEB0FF3AA
37+
```
38+
39+
---
40+
41+
## What It Does
42+
43+
1. **Validates input** — Checks the bundle folder exists and is a directory
44+
2. **Counts files** — Calculates the number of files to be included
45+
3. **Creates output directory** — Ensures `output/zips/` exists
46+
4. **Creates ZIP archive** — Uses `archiver` package with maximum compression
47+
5. **Preserves structure** — The bundle directory becomes the root inside the ZIP
48+
6. **Reports results** — Prints ZIP path, file count, and size
49+
50+
---
51+
52+
## Expected Output
53+
54+
### Successful Export
55+
56+
```
57+
╔════════════════════════════════════════════════════════════╗
58+
║ VSC v1.17 — ZIP Bundle Export ║
59+
╚════════════════════════════════════════════════════════════╝
60+
61+
Bundle path: C:\Users\...\vsc-json-event-bundle-408C8C13C4D4-to-ED9566562A13
62+
Files to include: 108
63+
64+
╔════════════════════════════════════════════════════════════╗
65+
║ ZIP EXPORT COMPLETE ║
66+
╚════════════════════════════════════════════════════════════╝
67+
68+
ZIP path: output\zips\vsc-json-event-bundle-408C8C13C4D4-to-ED9566562A13.zip
69+
Files included: 108
70+
ZIP size: 245.6 KB
71+
Source bundle: C:\Users\...\vsc-json-event-bundle-408C8C13C4D4-to-ED9566562A13
72+
73+
Result: PASS
74+
75+
✓ ZIP bundle created successfully.
76+
77+
Next steps:
78+
1. Inspect: cd output\zips\
79+
2. Extract: unzip vsc-json-event-bundle-408C8C13C4D4-to-ED9566562A13.zip
80+
3. Share: Distribute the ZIP file
81+
```
82+
83+
### Failed Export
84+
85+
```
86+
✗ Bundle not found: output\does-not-exist
87+
```
88+
89+
---
90+
91+
## Exit Codes
92+
93+
| Code | Meaning |
94+
|------|---------|
95+
| `0` | ZIP export successful |
96+
| `1` | Export failed — bundle not found, not a directory, or archive error |
97+
98+
---
99+
100+
## Output Location
101+
102+
ZIP files are created in:
103+
```
104+
output/zips/<bundle-name>.zip
105+
```
106+
107+
For example:
108+
- Bundle: `output/bundles/vsc-bundle-ABC-to-XYZ/`
109+
- ZIP: `output/zips/vsc-bundle-ABC-to-XYZ.zip`
110+
111+
---
112+
113+
## ZIP Structure
114+
115+
The ZIP archive contains the bundle directory as its root:
116+
117+
```
118+
vsc-bundle-21A8390BFA3F-to-954BEB0FF3AA.zip
119+
└── vsc-bundle-21A8390BFA3F-to-954BEB0FF3AA/
120+
├── README.md
121+
├── manifest.json
122+
├── chain-token.json
123+
├── base-token.json
124+
├── verification-summary.json
125+
├── checksums.sha256
126+
├── delta-tokens/
127+
│ ├── delta-1.json
128+
│ └── delta-2.json
129+
├── reports/
130+
│ └── chain-report.md
131+
└── seals/
132+
├── base.svg
133+
├── chain.svg
134+
└── delta-1.svg
135+
```
136+
137+
---
138+
139+
## Use Cases
140+
141+
### Email Distribution
142+
143+
Share bundles as single-file attachments:
144+
145+
```bash
146+
npm run vsc -- bundle:json
147+
npm run vsc -- zip-bundle output\json-event-bundles\vsc-json-event-bundle-*
148+
# Attach output\zips\vsc-json-event-bundle-*.zip to email
149+
```
150+
151+
### Archive Storage
152+
153+
Compress bundles for long-term storage:
154+
155+
```bash
156+
# Create dated archive
157+
npm run vsc -- zip-bundle output\bundles\vsc-bundle-ABC-to-XYZ
158+
mv output\zips\vsc-bundle-ABC-to-XYZ.zip archives\vsc-bundle-$(date +%Y%m%d).zip
159+
```
160+
161+
### Distribution Packaging
162+
163+
Prepare bundles for download/release:
164+
165+
```bash
166+
# CI/CD pipeline
167+
npm run vsc -- bundle:json
168+
npm run vsc -- verify-bundle output\json-event-bundles\vsc-json-event-bundle-* || exit 1
169+
npm run vsc -- zip-bundle output\json-event-bundles\vsc-json-event-bundle-*
170+
# Upload output/zips/*.zip as release artifact
171+
```
172+
173+
---
174+
175+
## No Mutation Guarantee
176+
177+
The `zip-bundle` command does **not** modify the source bundle:
178+
179+
- ✅ Reads files from the bundle directory
180+
- ✅ Creates new ZIP file in `output/zips/`
181+
- ✅ Leaves source bundle unchanged
182+
183+
It does **not**:
184+
- ❌ Modify any files in the source bundle
185+
- ❌ Update `manifest.json`
186+
- ❌ Rewrite `checksums.sha256`
187+
- ❌ Change any token files
188+
189+
---
190+
191+
## Dependencies
192+
193+
This feature uses the `archiver` npm package:
194+
195+
```json
196+
"archiver": "^7.0.0"
197+
```
198+
199+
Archiver is a popular, well-maintained library for creating ZIP archives in Node.js.
200+
201+
---
202+
203+
## Git Safety
204+
205+
ZIP files in `output/zips/` are excluded from Git by default (via `.gitignore`).
206+
207+
Do not commit generated ZIP files — they can be regenerated from the source bundles.
208+
209+
---
210+
211+
## Verification Checklist
212+
213+
When reviewing this feature:
214+
215+
- [ ] Run `npm run vsc -- bundle:json` to create a bundle
216+
- [ ] Run `npm run vsc -- zip-bundle <path>` on the exported bundle
217+
- [ ] Confirm output shows `Result: PASS`
218+
- [ ] Confirm ZIP file exists in `output/zips/`
219+
- [ ] Extract the ZIP and verify bundle structure is preserved
220+
- [ ] Run `npm run vsc -- verify-bundle <extracted-path>` and confirm `Result: PASS`
221+
- [ ] Confirm the source bundle was not modified (checksums still valid)
222+
- [ ] Run `npm run vsc -- verify-all` and confirm `FAIL: 0`
223+
- [ ] Confirm no generated ZIP files were committed
224+
225+
---
226+
227+
## Limitations
228+
229+
- **Single bundle per ZIP** — Each ZIP contains one bundle directory
230+
- **Maximum compression** — Uses zlib level 9 (slower but smaller)
231+
- **Windows paths** — Primary testing on Windows; Unix paths should work
232+
- **No encryption** — ZIP files are not password-protected
233+
- **No streaming** — Entire archive created in memory before writing
234+
- **Research prototype** — Not enterprise-hardened archival software
235+
236+
---
237+
238+
## Relationship to Other Commands
239+
240+
| Command | Purpose | Creates ZIP? | Mutates source? |
241+
|---------|---------|------------|-----------------|
242+
| `bundle` | Export generic evidence bundle | ❌ No | ❌ No |
243+
| `bundle:json` | Export JSON event evidence bundle | ❌ No | ❌ No |
244+
| `verify-bundle` | Verify exported bundle | ❌ No | ❌ No |
245+
| `zip-bundle` | Package bundle into ZIP | ✅ Yes | ❌ No |
246+
247+
---
248+
249+
## See Also
250+
251+
- [VSC v1.16 — Evidence Bundle Verification](vsc-v1-16-verify-evidence-bundle.md)
252+
- [VSC v1.15 — JSON Event Evidence Bundle](vsc-v1-15-json-event-evidence-bundle.md)
253+
- [VSC v1.14 — Evidence Bundle Export](vsc-v1-14-evidence-bundle-export.md)
254+
255+
---
256+
257+
*VSC v1.17 — ZIP Bundle Export*

0 commit comments

Comments
 (0)