wowdump 0.0.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Follenfang
+
+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

@@ -1 +1,132 @@
 # wowdump
+
+`wowdump` is a build-aware World of Warcraft runtime analysis MCP server. It exposes Frida process control, focused Lua/C++ tracing, bounded data watches, build profile validation, and verified data readers over the MCP `2026-07-28` protocol.
+
+The package supports multiple WoW flavors and builds. `retail` is a flavor in a build key such as `retail@12.0.7.68974`; it is not part of the product name.
+
+## Install
+
+Run directly from an MCP client:
+
+```json
+{
+  "mcpServers": {
+    "wowdump": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "wowdump",
+        "--game-root",
+        "D:\\Game\\World of Warcraft"
+      ]
+    }
+  }
+}
+```
+
+Or install it globally:
+
+```powershell
+npm install --global wowdump
+wowdump --game-root "D:\Game\World of Warcraft"
+```
+
+The `wowdump` executable only starts the stdio MCP server. It is not a separate interactive CLI.
+
+## Game Directories
+
+Game directories are resolved once when the MCP server starts. The first non-empty source wins:
+
+1. Repeatable `--game-root <path>` arguments.
+2. `WOWDUMP_GAME_ROOTS` as a semicolon-separated list on Windows.
+3. `game_roots` in the TOML file selected by `--config <path>`.
+4. `%LOCALAPPDATA%\wowdump\config.toml`.
+5. Automatic detection from verified Battle.net Agent installation metadata, followed by common Windows installation locations.
+
+Example persistent configuration:
+
+```toml
+game_roots = [
+  "D:/Game/World of Warcraft",
+  "E:/World of Warcraft"
+]
+
+broker_idle_ms = 1200000
+```
+
+`WOW_ROOT` remains a deprecated compatibility fallback. Invalid selected paths are reported on stderr and are not silently replaced by a lower-priority source.
+
+PID, build, module base, Frida sessions, Hook IDs, and runtime addresses are never persisted in TOML. They are discovered and validated for the current process.
+
+## Selecting A Target
+
+Use these read-only tools before starting a dynamic session:
+
+- `wow_install_list`: installed game directories and flavors.
+- `wow_build_list`: detected build keys and versions.
+- `wow_target_list`: running Wow.exe PIDs matched to an installation and build.
+
+Focused and trace operations accept an explicit `pid` and `buildKey`. The server rejects PID/build mismatches and does not reuse a historical PID or module base.
+
+## MCP Tools
+
+The primary tool groups are:
+
+- `frida_command`: generic Frida read, write, script, Hook, process, and session operations.
+- `wow_lua_trace_*` and `wow_cpp_trace_*`: build-aware bounded trace sessions.
+- `wow_focus_*`, `wow_watch_*`, and `wow_session_checkpoint`: explicit before/during/after analysis windows.
+- `wow_data_source_*`, `wow_data_read`, and `wow_build_profile_validate`: verified build data and readers.
+- `wow_broker_*`: Broker status, start, reconnect, and stop.
+- `wow_analysis_coverage` and `wow_analysis_checkpoint`: static profile coverage and checkpoints.
+
+The server rejects legacy MCP handshakes. Protocol output is written only to stdout; diagnostics are written to stderr.
+
+## Runtime Layout
+
+Production uses three distinct directory roles:
+
+- Package `resources/builds`: read-only, build-specific profiles and signatures.
+- `%LOCALAPPDATA%\wowdump`: writable Broker ledgers, focused sessions, logs, and cache.
+- Repository `analyze/vm`: offline analysis inputs and intermediate evidence; it is not required by the installed package.
+
+Stable overrides can be placed in TOML:
+
+```toml
+profile_root = "D:/wowdump-profiles"
+runtime_root = "C:/Users/ACCOUNT/AppData/Local/wowdump"
+log_level = "info"
+broker_idle_ms = 1200000
+```
+
+The MCP process does not own Frida sessions. A single per-user `wowdump-broker` process owns attach/detach, scripts, Hooks, Interceptors, request forwarding, and cleanup. Requests refresh its idle timer; the default idle timeout is 20 minutes.
+
+## Packaged Builds
+
+This release includes a verified profile for:
+
+- `retail@12.0.7.68974`
+
+Every build has its own RVA profile, entry signatures, data sources, and manifest hashes. A new build must be relocated and validated; old RVAs are not automatically reused.
+
+## Development
+
+```powershell
+npm install
+npm run typecheck
+npm test
+npm run build
+npm run bundle:verify
+npm run package:verify
+```
+
+To regenerate the packaged bundle from the repository-only analysis workspace:
+
+```powershell
+npm run bundle:build
+```
+
+`npm run package:verify` enforces the npm file whitelist, creates a real tarball, installs it in a temporary directory, starts the installed `wowdump` bin, and performs an MCP `2026-07-28` handshake.
+
+## License
+
+MIT

package/dist/adapters.js

@@ -0,0 +1,101 @@
+const UNSUPPORTED_REASON = "No verified read-only adapter is registered for this build";
+function normalizeBuildKey(buildKey) {
+    return buildKey.trim();
+}
+function cloneCapabilities(capabilities) {
+    return Object.freeze({
+        errorMessage: capabilities.errorMessage,
+        sourceLocation: capabilities.sourceLocation,
+        stackTrace: capabilities.stackTrace,
+        vmMetadata: capabilities.vmMetadata
+    });
+}
+function cloneAdapter(adapter) {
+    return Object.freeze({
+        ...adapter,
+        buildKey: normalizeBuildKey(adapter.buildKey),
+        capabilities: cloneCapabilities(adapter.capabilities)
+    });
+}
+function assertAdapter(adapter) {
+    if (!adapter || typeof adapter !== "object") {
+        throw new TypeError("adapter must be an object");
+    }
+    if (typeof adapter.buildKey !== "string" || !normalizeBuildKey(adapter.buildKey)) {
+        throw new TypeError("adapter.buildKey must be a non-empty string");
+    }
+    if (typeof adapter.name !== "string" || !adapter.name.trim()) {
+        throw new TypeError("adapter.name must be a non-empty string");
+    }
+    if (typeof adapter.verification !== "string" || !adapter.verification.trim()) {
+        throw new TypeError("adapter.verification must identify the verification proof");
+    }
+    if (adapter.fridaPrelude !== undefined) {
+        if (typeof adapter.fridaPrelude !== "string") {
+            throw new TypeError("adapter.fridaPrelude must be a string when provided");
+        }
+        if (Buffer.byteLength(adapter.fridaPrelude, "utf8") > 1024 * 1024) {
+            throw new TypeError("adapter.fridaPrelude exceeds the 1 MiB limit");
+        }
+    }
+    const capabilities = adapter.capabilities;
+    if (!capabilities || typeof capabilities !== "object") {
+        throw new TypeError("adapter.capabilities must be provided");
+    }
+    for (const field of ["errorMessage", "sourceLocation", "stackTrace", "vmMetadata"]) {
+        if (typeof capabilities[field] !== "boolean") {
+            throw new TypeError(`adapter.capabilities.${field} must be boolean`);
+        }
+    }
+}
+/**
+ * Create an immutable registry from verified definitions.
+ *
+ * The default is intentionally empty: until a build-specific read-only proof
+ * is supplied, every build is reported as unsupported.
+ */
+export function createBuildAdapterRegistry(definitions = []) {
+    const adapters = new Map();
+    for (const definition of definitions) {
+        assertAdapter(definition);
+        const adapter = cloneAdapter(definition);
+        if (adapters.has(adapter.buildKey)) {
+            throw new Error(`Duplicate adapter for build key ${adapter.buildKey}`);
+        }
+        adapters.set(adapter.buildKey, adapter);
+    }
+    return Object.freeze({
+        lookup(buildKey) {
+            const key = normalizeBuildKey(buildKey);
+            const adapter = adapters.get(key);
+            if (!adapter) {
+                return Object.freeze({
+                    buildKey: key,
+                    status: "unsupported",
+                    reason: UNSUPPORTED_REASON
+                });
+            }
+            return Object.freeze({
+                buildKey: key,
+                status: "verified",
+                adapter
+            });
+        },
+        list() {
+            return Object.freeze([...adapters.values()]);
+        }
+    });
+}
+/** Empty-by-default registry used by callers that have no verified builds. */
+export const buildAdapterRegistry = createBuildAdapterRegistry();
+/** Look up a build in the default empty registry. */
+export function getBuildAdapter(buildKey) {
+    return buildAdapterRegistry.lookup(buildKey);
+}
+/**
+ * Convert a discovered install to an adapter lookup without widening the
+ * registry API or introducing build-specific assumptions.
+ */
+export function getBuildAdapterForBuild(build) {
+    return getBuildAdapter(build.buildKey);
+}