libwz 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021-present Toyobayashi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,165 @@
+# libwz
+
+> ⚠️ **Vibe Coding / Clean-room Reimplementation / Under Development**
+> This project was developed with significant AI assistance (GitHub Copilot).
+> It is an independent C++ reimplementation — no code was copied from the
+> C# reference (included as a submodule for test data only).
+
+A native C++ library for reading and parsing **MapleStory `.wz` game data files**.
+Provides C API for FFI consumers and JNI bindings for Java/Kotlin.
+
+<!-- [![Build & Publish](https://github.com/toyobayashi/libwz/actions/workflows/build.yml/badge.svg)](https://github.com/toyobayashi/libwz/actions/workflows/build.yml) -->
+
+## Features
+
+- Decrypt and parse PKG1-format `.wz` archives across all major MapleStory
+  regions (GMS, EMS, BMS, Classic, Custom)
+- Support for 32-bit and 64-bit WZ file versions
+- Hierarchical directory/image traversal with all 16 property types
+- Image decompression: DXT3, DXT5, BGRA4444, ARGB1555, RGB565, Form517
+- UOL (link) property resolution with cross-file traversal
+- Audio extraction (MP3/WAV) from Sound properties
+- Lua script decoding
+- PNG export from Canvas properties
+- C API (`wz_api.h`) for FFI consumers (Python, Node.js, etc.)
+- JNI bindings for Java/Kotlin consumers
+- Java wrapper classes with `AutoCloseable` resource management
+- Node.js native addon and WebAssembly package entries for JavaScript users
+
+## Requirements
+
+- **C++23** compiler with `<expected>` support
+- **CMake 3.16+**
+- **Git** (for submodules)
+
+## Quick Start — C++
+
+```bash
+git clone --recurse-submodules https://github.com/toyobayashi/libwz.git
+cd libwz
+
+cmake -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build
+
+# Run tests
+cmake -B build -DBUILD_TESTS=ON
+cmake --build build
+ctest --test-dir build
+```
+
+## Quick Start — Java (Maven)
+
+Add the dependency (available on Maven Central):
+
+```xml
+<dependency>
+    <groupId>io.github.toyobayashi</groupId>
+    <artifactId>libwz</artifactId>
+    <version>0.1.0</version>
+</dependency>
+```
+
+Alternatively, from GitHub Packages (requires authentication):
+
+```xml
+<repository>
+    <id>github</id>
+    <url>https://maven.pkg.github.com/toyobayashi/libwz</url>
+</repository>
+```
+
+Authenticate with a [GitHub personal access token](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry#authenticating-to-github-packages):
+
+```xml
+<!-- ~/.m2/settings.xml -->
+<server>
+    <id>github</id>
+    <username>YOUR_GITHUB_USERNAME</username>
+    <password>YOUR_GITHUB_TOKEN</password>
+</server>
+```
+
+The JAR bundles native libraries for **Windows x86_64**, **Linux x86_64**,
+and **macOS ARM64 (Apple Silicon)**. `NativeLibraryLoader` automatically
+extracts the correct one at runtime.
+
+## Quick Start — JavaScript / Wasm
+
+The root `libwz` package entry uses the native Node addon in Node.js and the
+Wasm build through the package `browser` export in browser bundlers. Both
+entries export the same classes and constants, plus one async `init()` function
+for the Wasm runtime.
+
+Node.js requires `^20.19.0 || >=22.12.0`. `process.getBuiltinModule()` exists
+in Node.js 20.16.0 and 22.3.0, but the package also relies on the modern
+`require(esm)` interoperability that is available by default from Node.js
+20.19.0 and 22.12.0; Node.js 24.x is covered by the `>=22.12.0` range.
+
+```js
+import { init, MapleVersion, WzFile } from "libwz";
+
+await init();
+using file = new WzFile("Character.wz", MapleVersion.GMS);
+file.parseWzFile();
+```
+
+Pass a custom Wasm URL or path when your bundler or CDN serves the binary from
+a different location.
+
+```js
+import { init } from "libwz";
+
+await init(new URL("./assets/libwz.wasm", import.meta.url));
+```
+
+Use `getWzBindingType()` to inspect whether the active backend is `"native"` or
+`"wasm"`. If the native addon cannot be loaded, `init()` falls back to Wasm.
+In Node.js, pass a Wasm URL or `{ forceWasm: true }` to force the Wasm backend
+even when the native addon is available. Path-based APIs still accept normal
+host filesystem paths; the Wasm runtime maps them internally.
+
+The package publishes one Wasm binary, `dist/libwz.wasm`, and no synchronous or
+main-thread Worker wrapper entry.
+
+## Build Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `BUILD_TESTS` | `ON` | Build Google Test unit tests |
+| `BUILD_CAPI` | `ON` | Build C ABI wrapper (`libwz_capi`) |
+| `BUILD_JNI` | `OFF` | Build JNI shared library (`libwz_jni`) |
+
+## Targets
+
+| Target | Type | Description |
+|--------|------|-------------|
+| `wz` | Static | Core WZ parsing engine |
+| `wz_capi` | Static | C ABI layer for FFI consumers |
+| `wz_jni` | Shared | JNI native library for Java |
+
+## Code Map
+
+| Directory | Purpose |
+|-----------|---------|
+| `include/wz/` | Public C++ headers |
+| `include/wz/Properties/` | 16 property type headers |
+| `include/wz/Util/` | Binary reader, key gen, path utils |
+| `include/wz/wz_api.h` | C ABI (opaque handles, no STL) |
+| `src/` | C++ implementation files |
+| `src/capi/` | C API implementation |
+| `src/jni/` | JNI bindings (`wz_jni.cpp`) |
+| `java/` | Java wrapper classes + Maven project |
+| `tests/` | Google Test unit tests |
+| `Harepacker-resurrected/` | C# reference (submodule, test data only) |
+
+## Dependencies
+
+- [tiny-AES-c](https://github.com/kokke/tiny-AES-c) — AES-256-ECB decryption
+- [zlib](https://github.com/madler/zlib) — Image data decompression
+- [Google Test](https://github.com/google/googletest) — Unit tests
+
+## License
+
+MIT. The `Harepacker-resurrected/` submodule (test data reference, not part of
+libwz source) contains code under MPL-2.0 and GPL-3.0 — see respective
+LICENSE files in that submodule.

package/binding.gyp

@@ -0,0 +1,149 @@
+{
+  "targets": [
+    {
+      "target_name": "tiny_aes",
+      "type": "static_library",
+      "sources": [
+        "deps/tiny-aes/aes.c"
+      ],
+      "include_dirs": [
+        "deps/tiny-aes"
+      ],
+      "defines": [
+        "AES256=1"
+      ],
+      "msvs_settings": {
+        "VCCLCompilerTool": {
+          "AdditionalOptions": [
+            "/utf-8"
+          ]
+        }
+      }
+    },
+    {
+      "target_name": "zlibstatic",
+      "type": "static_library",
+      "sources": [
+        "deps/zlib/adler32.c",
+        "deps/zlib/compress.c",
+        "deps/zlib/crc32.c",
+        "deps/zlib/deflate.c",
+        "deps/zlib/gzclose.c",
+        "deps/zlib/gzlib.c",
+        "deps/zlib/gzread.c",
+        "deps/zlib/gzwrite.c",
+        "deps/zlib/infback.c",
+        "deps/zlib/inffast.c",
+        "deps/zlib/inflate.c",
+        "deps/zlib/inftrees.c",
+        "deps/zlib/trees.c",
+        "deps/zlib/uncompr.c",
+        "deps/zlib/zutil.c"
+      ],
+      "include_dirs": [
+        "deps/zlib"
+      ],
+      "conditions": [
+        [
+          "OS=='win'",
+          {
+            "defines": [
+              "_CRT_SECURE_NO_DEPRECATE",
+              "_CRT_NONSTDC_NO_DEPRECATE"
+            ]
+          }
+        ],
+        [
+          "OS!='win'",
+          {
+            "defines": [
+              "HAVE_UNISTD_H"
+            ]
+          }
+        ]
+      ]
+    },
+    {
+      "target_name": "wz",
+      "sources": [
+        "src/node/binding.cpp",
+        "src/WzEnums.cpp",
+        "src/WzAESConstant.cpp",
+        "src/Util/WzMutableKey.cpp",
+        "src/Util/WzKeyGenerator.cpp",
+        "src/Util/WzBinaryReader.cpp",
+        "src/Util/WzDataSource.cpp",
+        "src/Util/WzStream.cpp",
+        "src/Util/WzBinaryWriter.cpp",
+        "src/Util/WzBlobDataSource.cpp",
+        "src/Util/WzTool.cpp",
+        "src/Util/ListFileParser.cpp",
+        "src/PngUtility.cpp",
+        "src/Properties/WzNullProperty.cpp",
+        "src/Properties/WzShortProperty.cpp",
+        "src/Properties/WzIntProperty.cpp",
+        "src/Properties/WzLongProperty.cpp",
+        "src/Properties/WzFloatProperty.cpp",
+        "src/Properties/WzDoubleProperty.cpp",
+        "src/Properties/WzStringProperty.cpp",
+        "src/Properties/WzSubProperty.cpp",
+        "src/Properties/WzCanvasProperty.cpp",
+        "src/Properties/WzPngProperty.cpp",
+        "src/Properties/WzVectorProperty.cpp",
+        "src/Properties/WzConvexProperty.cpp",
+        "src/Properties/WzBinaryProperty.cpp",
+        "src/Properties/WzUOLProperty.cpp",
+        "src/Properties/WzLuaProperty.cpp",
+        "src/Properties/WzRawDataProperty.cpp",
+        "src/Properties/WzVideoProperty.cpp",
+        "src/WzFile.cpp",
+        "src/WzDirectory.cpp",
+        "src/WzImage.cpp",
+        "src/WzImageProperty.cpp",
+        "src/WzObject.cpp",
+        "src/WzPropertyCollection.cpp",
+      ],
+      "include_dirs": [
+        "include",
+        "deps/tiny-aes",
+        "deps/zlib"
+      ],
+      "dependencies": [
+        "tiny_aes",
+        "zlibstatic"
+      ],
+      "defines": [
+        "NAPI_DISABLE_CPP_EXCEPTIONS",
+        "AES256=1",
+        "_HAS_EXCEPTIONS=0"
+      ],
+      "cflags_cc!": [
+        "-std=c++20"
+      ],
+      "cflags_cc": [
+        "-std=c++23",
+        "-fno-exceptions",
+        "-fno-rtti"
+      ],
+      "xcode_settings": {
+        "CLANG_CXX_LANGUAGE_STANDARD": "c++23"
+      },
+      "msvs_settings": {
+        "VCCLCompilerTool": {
+          "ExceptionHandling": 0,
+          "RuntimeTypeInfo": "false",
+          "AdditionalOptions!": [
+            "-std:c++20",
+            "/std:c++20"
+          ],
+          "AdditionalOptions": [
+            "/std:c++latest",
+            "/utf-8",
+            "/EHs-c-",
+            "/GR-"
+          ]
+        }
+      }
+    }
+  ]
+}

package/deps/tiny-aes/.github/workflows/c-cpp.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+  schedule:
+    # Run CI nightly (midnight)
+    - cron: "0 0 * * *"
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: make clean
+      run: make clean
+    - name: make
+      run: make
+    - name: make test
+      run: make test

package/deps/tiny-aes/CMakeLists.txt

@@ -0,0 +1,17 @@
+cmake_minimum_required(VERSION 3.12)
+
+project(tiny-aes C)
+
+add_library(${PROJECT_NAME} "")
+target_sources(${PROJECT_NAME}
+    PRIVATE
+        ${CMAKE_CURRENT_LIST_DIR}/aes.c
+    INTERFACE
+        ${CMAKE_CURRENT_LIST_DIR}/aes.h
+        ${CMAKE_CURRENT_LIST_DIR}/aes.hpp
+)
+
+target_include_directories(${PROJECT_NAME}
+    INTERFACE
+        ${CMAKE_CURRENT_LIST_DIR}
+)

package/deps/tiny-aes/Makefile

@@ -0,0 +1,61 @@
+#CC           = avr-gcc
+#CFLAGS       = -Wall -mmcu=atmega16 -Os -Wl,-Map,test.map
+#OBJCOPY      = avr-objcopy
+CC           = gcc
+LD           = gcc
+AR           = ar
+ARFLAGS      = rcs
+CFLAGS       = -Wall -Os -c
+LDFLAGS      = -Wall -Os -Wl,-Map,test.map
+ifdef AES192
+CFLAGS += -DAES192=1
+endif
+ifdef AES256
+CFLAGS += -DAES256=1
+endif
+
+OBJCOPYFLAGS = -j .text -O ihex
+OBJCOPY      = objcopy
+
+# include path to AVR library
+INCLUDE_PATH = /usr/lib/avr/include
+# splint static check
+SPLINT       = splint test.c aes.c -I$(INCLUDE_PATH) +charindex -unrecog
+
+default: test.elf
+
+.SILENT:
+.PHONY:  lint clean
+
+test.hex : test.elf
+	echo copy object-code to new image and format in hex
+	$(OBJCOPY) ${OBJCOPYFLAGS} $< $@
+
+test.o : test.c aes.h aes.o
+	echo [CC] $@ $(CFLAGS)
+	$(CC) $(CFLAGS) -o  $@ $<
+
+aes.o : aes.c aes.h
+	echo [CC] $@ $(CFLAGS)
+	$(CC) $(CFLAGS) -o $@ $<
+
+test.elf : aes.o test.o
+	echo [LD] $@
+	$(LD) $(LDFLAGS) -o $@ $^
+
+aes.a : aes.o
+	echo [AR] $@
+	$(AR) $(ARFLAGS) $@ $^
+
+lib : aes.a
+
+clean:
+	rm -f *.OBJ *.LST *.o *.gch *.out *.hex *.map *.elf *.a
+
+test:
+	make clean && make && ./test.elf
+	make clean && make AES192=1 && ./test.elf
+	make clean && make AES256=1 && ./test.elf
+
+lint:
+	$(call SPLINT)

package/deps/tiny-aes/README.md

@@ -0,0 +1,83 @@
+![CI](https://github.com/kokke/tiny-AES-c/actions/workflows/c-cpp.yml/badge.svg)
+### Tiny AES in C
+
+This is a small and portable implementation of the AES [ECB](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Electronic_Codebook_.28ECB.29), [CTR](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Counter_.28CTR.29) and [CBC](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Cipher_Block_Chaining_.28CBC.29) encryption algorithms written in C.
+
+You can override the default key-size of 128 bit with 192 or 256 bit by defining the symbols AES192 or AES256 in [`aes.h`](https://github.com/kokke/tiny-AES-c/blob/master/aes.h).
+
+The API is very simple and looks like this (I am using C99 `<stdint.h>`-style annotated types):
+
+```C
+/* Initialize context calling one of: */
+void AES_init_ctx(struct AES_ctx* ctx, const uint8_t* key);
+void AES_init_ctx_iv(struct AES_ctx* ctx, const uint8_t* key, const uint8_t* iv);
+
+/* ... or reset IV at random point: */
+void AES_ctx_set_iv(struct AES_ctx* ctx, const uint8_t* iv);
+
+/* Then start encrypting and decrypting with the functions below: */
+void AES_ECB_encrypt(const struct AES_ctx* ctx, uint8_t* buf);
+void AES_ECB_decrypt(const struct AES_ctx* ctx, uint8_t* buf);
+
+void AES_CBC_encrypt_buffer(struct AES_ctx* ctx, uint8_t* buf, size_t length);
+void AES_CBC_decrypt_buffer(struct AES_ctx* ctx, uint8_t* buf, size_t length);
+
+/* Same function for encrypting as for decrypting in CTR mode */
+void AES_CTR_xcrypt_buffer(struct AES_ctx* ctx, uint8_t* buf, size_t length);
+```
+
+Important notes: 
+ * No padding is provided so for CBC and ECB all buffers should be multiples of 16 bytes. For padding [PKCS7](https://en.wikipedia.org/wiki/Padding_(cryptography)#PKCS7) is recommendable.
+ * ECB mode is considered unsafe for most uses and is not implemented in streaming mode. If you need this mode, call the function for every block of 16 bytes you need encrypted. See [wikipedia's article on ECB](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Electronic_Codebook_(ECB)) for more details.
+ * This library is designed for small code size and simplicity, intended for cases where small binary size, low memory footprint and portability is more important than high performance. If speed is a concern, you can try more complex libraries, e.g. [Mbed TLS](https://tls.mbed.org/), [OpenSSL](https://www.openssl.org/) etc.
+
+You can choose to use any or all of the modes-of-operations, by defining the symbols CBC, CTR or ECB in [`aes.h`](https://github.com/kokke/tiny-AES-c/blob/master/aes.h) (read the comments for clarification).
+
+C++ users should `#include` [aes.hpp](https://github.com/kokke/tiny-AES-c/blob/master/aes.hpp) instead of [aes.h](https://github.com/kokke/tiny-AES-c/blob/master/aes.h)
+
+There is no built-in error checking or protection from out-of-bounds memory access errors as a result of malicious input.
+
+The module uses less than 200 bytes of RAM and 1-2K ROM when compiled for ARM, but YMMV depending on which modes are enabled.
+
+It is one of the smallest implementations in C I've seen yet, but do contact me if you know of something smaller (or have improvements to the code here). 
+
+I've successfully used the code on 64bit x86, 32bit ARM and 8 bit AVR platforms.
+
+
+GCC size output when only CTR mode is compiled for ARM:
+
+    $ arm-none-eabi-gcc -Os -DCBC=0 -DECB=0 -DCTR=1 -c aes.c
+    $ size aes.o
+       text    data     bss     dec     hex filename
+       1171       0       0    1171     493 aes.o
+
+.. and when compiling for the THUMB instruction set, we end up well below 1K in code size.
+
+    $ arm-none-eabi-gcc -Os -mthumb -DCBC=0 -DECB=0 -DCTR=1 -c aes.c
+    $ size aes.o
+       text    data     bss     dec     hex filename
+        903       0       0     903     387 aes.o
+
+
+I am using the Free Software Foundation, ARM GCC compiler:
+
+    $ arm-none-eabi-gcc --version
+    arm-none-eabi-gcc (4.8.4-1+11-1) 4.8.4 20141219 (release)
+    Copyright (C) 2013 Free Software Foundation, Inc.
+    This is free software; see the source for copying conditions.  There is NO
+    warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+
+
+
+
+This implementation is verified against the data in:
+
+[National Institute of Standards and Technology Special Publication 800-38A 2001 ED](http://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38a.pdf) Appendix F: Example Vectors for Modes of Operation of the AES.
+
+The other appendices in the document are valuable for implementation details on e.g. padding, generation of IVs and nonces in CTR-mode etc.
+
+
+A heartfelt thank-you to [all the nice people](https://github.com/kokke/tiny-AES-c/graphs/contributors) out there who have contributed to this project.
+
+
+All material in this repository is in the public domain.