Release Archive Tools 0.1.0

2026-09-01 02:42:42 +02:00
commit a49ec6b17a
77 changed files with 11528 additions and 0 deletions
@@ -0,0 +1,61 @@
+# Archive Tools
+
+Inspect, create, compare and safely extract archives locally.
+
+Archive Tools is a standalone local-first application in the [add·ideas Toolbox](https://git.add-ideas.de/lotobo/toolbox-portal). Inputs are processed in the browser and are not uploaded.
+
+## Version 0.1 scope
+
+- Inspect ZIP and ZIP64 central directories, TAR/USTAR/PAX archives, gzip streams and tar.gz archives.
+- List normalized paths, kinds, sizes, compression, timestamps, ZIP64 state, CRC-32 values and policy diagnostics.
+- Preview bounded UTF-8 text, hexadecimal bytes and static JPEG/PNG/WebP images. HTML and SVG are shown as text, never rendered as active content.
+- Select regular safe files, verify their bytes and CRC where available, and repackage them into a newly created ZIP. Archive paths are never restored directly to a filesystem.
+- Create deterministic ZIP, TAR/PAX and tar.gz output from local files with sorted paths and normalized metadata.
+- Compare two archive inventories by collision-safe path, entry kind, expanded size and CRC-32, independent of container format and timestamps.
+- Download machine-readable inspection and comparison reports.
+
+Encryption, split/multipart ZIPs, nested archive expansion, GNU TAR extensions, symlinks, hardlinks, devices and FIFOs are intentionally unsupported. Those entry kinds are either rejected or listed as blocked; they are never restored.
+
+The application treats every imported file as untrusted, applies explicit count/path/expanded-byte/compression-ratio limits, and never executes imported active content. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) and [docs/PRIVACY-SECURITY.md](docs/PRIVACY-SECURITY.md).
+
+## Safety limits
+
+| Resource                   |                           Limit |
+| -------------------------- | ------------------------------: |
+| Source archive             |                         512 MiB |
+| Entries inspected          |                          20,000 |
+| Entries displayed at once  |                           5,000 |
+| Expanded archive bytes     |                         512 MiB |
+| One expanded entry         |                         256 MiB |
+| Compression ratio          |                           200:1 |
+| Path                       | 4,096 UTF-8 bytes / 64 segments |
+| Creation                   |           5,000 files / 512 MiB |
+| Text / hex / image preview |        2 MiB / 128 KiB / 24 MiB |
+
+These are application-level ceilings, not a promise that every device can comfortably process files near the maximum.
+
+## Using the workspaces
+
+1. **Inspect & extract** opens one archive, displays its safety inventory and previews eligible files. Select safe regular files and choose **Verify & download safe ZIP** to create a fresh archive.
+2. **Create** accepts local files and produces reproducible ZIP, TAR or tar.gz output. Browser file selection exposes relative paths only when the browser supplies them.
+3. **Compare** opens two archives and reports same, changed, type-changed and one-sided entries.
+
+## Development
+
+Requires Node.js 22 and npm 11.
+
+```sh
+npm ci
+npm run check
+npm run test:browser
+```
+
+Runtime dependencies are exactly pinned. `npm audit` should be checked with every dependency update.
+
+## Release
+
+`npm run release:artifact` creates a deterministic `release/archive-tools-0.1.0.zip` and checksum sidecar.
+
+## Licence
+
+GPL-3.0-or-later. Runtime dependencies retain their own licences; see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).