zip-wasm
ZIP create / extract in the browser — Rust + WebAssembly, with Shift_JIS / UTF-8 filename detection and password-protected ZIP (ZipCrypto / AES-256).
Live demo: WebTool Free – ZIP Tool · 日本語 README
Why
- Mojibake (文字化け) is still a real problem. ZIPs created on Japanese Windows store filenames in Shift_JIS (CP932) without the UTF-8 flag, while macOS and modern tools use UTF-8. Opening one on the "wrong" OS turns filenames into garbage.
- Uploading files to an online converter is a privacy risk. This engine runs entirely inside the browser; files and passwords are never sent anywhere.
- Password-protected ZIPs are awkward on phones and locked-down PCs. A browser is all you need.
Features
- Create / extract ZIP with multiple files (Deflate)
- Filename encoding on extract:
auto (UTF-8 / Shift_JIS / CP437 fallback) or a manual override
- Create ZIPs with Shift_JIS filenames for legacy Windows compatibility
- Password ZIP: ZipCrypto (opens with Windows Explorer) and AES-256 (WinZip AE-x)
- Wrong / missing password is reported with stable error prefixes (
ERR_PASSWORD_REQUIRED, ERR_BAD_PASSWORD)
- Entry names are sanitized on extract (
.., ., drive letters and empty segments are dropped; \ becomes /)
- No server upload — pure client-side WebAssembly
How filename encoding detection works
For auto mode the raw filename bytes of each entry (name_raw) are decoded as follows
(src/filename.rs, decode_name):
- If the bytes are valid UTF-8 → UTF-8 (ASCII-only names fall here too).
- Else if they decode as Shift_JIS without any invalid sequence → Shift_JIS.
- Else → the name as interpreted by the
zip crate (CP437 when the UTF-8 flag is absent).
Notes:
- The general purpose flag bit 11 (EFS) and the Info-ZIP Unicode Path extra field (
0x7075)
are not inspected explicitly by this engine yet. Pure-UTF-8 detection by byte validity covers
the common cases, but a Shift_JIS name that happens to be valid UTF-8 is a theoretical misdetection;
use the manual override in that case.
- When creating, UTF-8 names set bit 11 only if the name is non-ASCII; Shift_JIS names never set it.
- AES-256 cannot be combined with Shift_JIS names (rejected with an error); use UTF-8 or ZipCrypto.
Details: docs/encoding.md
Usage
Build the package (see below), then:
import init, { compress_with_options, extract_ex, list_entries } from "./pkg/zip_wasm.js";
await init();
// files: [{ name: string, data: Uint8Array }, ...]
const zip = compress_with_options(files, "sjis", "secret", "zipcrypto");
// ^ "utf8" | "sjis"
// ^ "" = no password
// ^ "aes256" | "zipcrypto"
const entries = list_entries(zip); // [{ name, size, compressedSize, isDir, encrypted }]
const out = extract_ex(zip, "auto", "secret"); // [{ name, data, size }] ("auto" | "utf8" | "sjis" | "cp437")
| Function | Purpose |
|---|
compress(files) | UTF-8 names, no password |
compress_with_options(files, nameEncoding, password, encryption) | Full control |
extract(zip) / extract_ex(zip, encoding, password) | Extract (auto-detect / explicit) |
list_entries(zip) / list_entries_ex(zip, encoding) | List entries without extracting |
Build
cargo install wasm-pack
wasm-pack build --target web --release
cargo test
Test fixtures
test-fixtures/ contains small ZIPs (Shift_JIS, UTF-8, ZipCrypto, AES-256; password is password)
that you can use to test your own ZIP tools. They are generated by:
cargo test -- --ignored generate_fixtures
Verify that nothing is uploaded
- Open DevTools (F12) → Network tab.
- Compress or extract a file on the demo site.
- Confirm there is no request carrying your file.
Security notes
- ZipCrypto is a legacy scheme with known weaknesses. Use AES-256 for anything sensitive. ZipCrypto is offered only because Windows Explorer can open it.
- Filenames are not encrypted in either scheme.
- Passwords are handled only in memory inside the WebAssembly module.
- ZipCrypto cannot always tell a wrong password from corrupt data; both are reported as
ERR_BAD_PASSWORD.
Other browser-based tools by the same author
- WebTool Free — PDF, image and file-conversion tools that also run locally in the browser
Acknowledgements
Built on these open-source crates:
License
Licensed under either of Apache License 2.0 or MIT license at your option.
