74 lines
4.9 KiB
Markdown
74 lines
4.9 KiB
Markdown
# 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
|
|
|
|
Binary reads use checked offset arithmetic and bounded cursors. gzip CRC-32 is
|
|
updated incrementally during decompression; temporary previews and downloads
|
|
use explicitly revoked shared Blob URL leases.
|
|
|
|
- Inspect ZIP and ZIP64 central directories, TAR/USTAR/PAX archives, gzip streams and tar.gz archives.
|
|
- Structurally inspect 7z start/next headers and RAR4/RAR5 plaintext headers under fixed header/count bounds. Header CRCs are checked before metadata is accepted; entry content is never decoded.
|
|
- 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.
|
|
- Read and create password-protected ZIP entries with local ZipCrypto or WinZip AES support. AES-256 is the recommended creation mode; legacy ZipCrypto is clearly labelled weak.
|
|
- Create deterministic unencrypted ZIP, TAR/PAX and tar.gz output from local files with sorted paths and normalized metadata. Encrypted ZIPs use fresh random salt and are intentionally not byte-reproducible.
|
|
- 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.
|
|
|
|
Bounded GNU TAR long-name and long-link records and concatenated gzip members are supported. For 7z, the start-header offsets/sizes and both CRC-32 fields are validated; a plain FilesInfo header can expose names and empty-file/directory markers, while encoded headers are reported without decoding. For RAR4/RAR5, block framing and header CRCs are validated and plaintext file headers expose names, sizes, compression method identifiers, encryption and split-volume flags. Encrypted headers stop inspection.
|
|
|
|
Split/multipart ZIPs, nested archive expansion, GNU sparse files, symlinks, hardlinks, devices and FIFOs remain unsupported for restoration. 7z/RAR codec chains, solid dictionaries, passwords, recovery data, decompression and extraction are explicitly unsupported; their inventories are evidence, not proof that packed file data is intact.
|
|
|
|
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 |
|
|
| Concatenated gzip members | 256 |
|
|
| Password | 1,024 UTF-8 bytes |
|
|
| One 7z/RAR metadata header | 16 MiB |
|
|
| RAR header blocks | 40,000 |
|
|
| 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, or a locally encrypted AES-256/ZipCrypto ZIP. 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.2.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).
|