wxapkg

https://github.com/wux1an/wxapkg
Admin
wxapkg is a desktop tool built with Wails that decrypts and unpacks WeChat Mini Program (.wxapkg)...
Tokens:3,999
Snippets:31
Trust Score:7.4
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Wails CLI and Go Dependencies

Source: https://github.com/wux1an/wxapkg/blob/main/README.md

Install the Wails CLI, which automatically handles Go dependencies. This is a prerequisite for building and developing Wails applications.

```bash
go install github.com/wailsapp/wails/v2/cmd/wails@latest
```

--------------------------------

### Install Frontend Dependencies

Source: https://github.com/wux1an/wxapkg/blob/main/README.md

Navigate to the frontend directory and install necessary npm packages. This step is required before building or running the application in development mode.

```bash
cd frontend && npm install && cd ..
```

--------------------------------

### Create Unpacker and Unpack with Status Callback

Source: https://context7.com/wux1an/wxapkg/llms.txt

Initializes a wxapkg unpacker with item and options, then starts the asynchronous unpacking process. A callback function is invoked for status updates, including progress, completion, or errors.

```go
item := &wechat.WxapkgItem{
    UUID:       uuid.New().String(),
    Location:   "/path/to/wx1a2b3c4d5e6f7a8b",
    EncryptKey: "wx1a2b3c4d5e6f7a8b",
    IsDir:      true,
}
opts := &wechat.UnpackOptions{
    EnableDecrypt:      true,
    EnableJsonBeautify: true,
    EnableJsBeautify:   true,
    EnableHtmlBeautify: false,
    OutputDir:          "/tmp/output",
    SavePath:           "/tmp/output/wx1a2b3c4d5e6f7a8b_unpacked",
}

wechat.NewUnpacker(item, opts).UnpackWithStatusCallback(func(i *wechat.WxapkgItem) {
    switch i.UnpackStatus {
    case wechat.StatusTypeRunning:
        fmt.Printf("进度: %.1f%%  当前文件: %s\n", i.UnpackProgress, i.UnpackCurrentFile)
    case wechat.StatusTypeFinished:
        fmt.Printf("✓ 解包完成，共 %d 个文件，输出至: %s\n", i.UnpackTotal, i.UnpackSavePath)
    case wechat.StatusTypeError:
        fmt.Printf("✗ 解包失败: %s\n", i.UnpackErrorMessage)
    }
})
```

--------------------------------

### Build and Run Wails Project

Source: https://context7.com/wux1an/wxapkg/llms.txt

These bash commands outline the process for setting up and running a Wails project. It includes installing the Wails CLI, installing frontend dependencies, and running the project in development or build mode.

```bash
# 安装 Wails CLI 和前端依赖
go install github.com/wailsapp/wails/v2/cmd/wails@latest
cd frontend && npm install && cd ..

# 开发模式（热更新）
wails dev

# 生产构建（输出到 build/bin/）
wails build
```

--------------------------------

### Build wxapkg Tool

Source: https://github.com/wux1an/wxapkg/blob/main/README.md

Build the wxapkg tool for distribution. The compiled binary will be placed in the build/bin/ directory.

```bash
wails build
```

--------------------------------

### Frontend Unpack Flow with Progress Events

Source: https://context7.com/wux1an/wxapkg/llms.txt

This TypeScript code demonstrates the complete frontend call flow for unpacking a wxapkg file. It includes setting up an event listener for progress updates and initiating the unpack process with specified options. Ensure necessary imports from Wails runtime and Go services are present.

```typescript
import * as AppService from '../../wailsjs/go/main/AppService';
import { EventsOn } from '../../wailsjs/runtime/runtime';
import { wechat } from '../../wailsjs/go/models';

// 1. 监听进度事件
EventsOn("unpack:progress-changed", async (uuid: string) => {
    const latest = await AppService.GetWxapkgItem(uuid);
    if (!latest) return;
    console.log(`进度: ${latest.UnpackProgress.toFixed(1)}%  文件: ${latest.UnpackCurrentFile}`);
    if (latest.UnpackStatus === "finished") {
        console.log(`完成！输出目录: ${latest.UnpackSavePath}`);
    }
    if (latest.UnpackStatus === "error") {
        console.error(`错误: ${latest.UnpackErrorMessage}`);
    }
});

// 2. 启动解包
const item: wechat.WxapkgItem = { ...selectedItem, EncryptKey: "wx1a2b3c4d5e6f7a8b" };
const options: wechat.UnpackOptions = {
    EnableDecrypt:      true,
    EnableJsonBeautify: true,
    EnableJsBeautify:   true,
    EnableHtmlBeautify: false,
    OutputDir:          "/Users/alice/output",
    SavePath:           await AppService.ComputeSavePath("/Users/alice/output", item.Location),
};
await AppService.UnpackWxapkgItem(item, options);
// UnpackWxapkgItem 立即返回，进度通过事件异步推送
```

--------------------------------

### Run wxapkg Tool in Development Mode

Source: https://github.com/wux1an/wxapkg/blob/main/README.md

Run the wxapkg tool in development mode for active development. This mode typically includes features like hot-reloading for faster iteration.

```bash
wails dev
```

--------------------------------

### AppService.OpenDirectoryDialog

Source: https://context7.com/wux1an/wxapkg/llms.txt

Opens the operating system's native directory selection dialog.

```APIDOC
## AppService.OpenDirectoryDialog

### Description
Opens the operating system's native directory selection dialog, allowing the user to choose a directory.

### Method
GET (assumed, as it triggers a UI interaction)

### Endpoint
/AppService/OpenDirectoryDialog

### Parameters
#### Query Parameters
- **title** (string) - Required - The title displayed in the dialog window.
- **defaultPath** (string) - Optional - The initial directory path to display in the dialog.

### Response
#### Success Response (200)
- (string) - The full path to the selected directory, or an empty string if the dialog was cancelled.
```

--------------------------------

### AppService.UnpackWxapkgItem

Source: https://context7.com/wux1an/wxapkg/llms.txt

Initiates an asynchronous unpacking process for a Wxapkg item. Progress is reported via the 'unpack:progress-changed' event, and the latest status can be fetched using GetWxapkgItem(uuid).

```APIDOC
## AppService.UnpackWxapkgItem

### Description
Initiates an asynchronous unpacking process for a Wxapkg item. Progress is reported via the 'unpack:progress-changed' event, and the latest status can be fetched using GetWxapkgItem(uuid).

### Method
POST (assumed, as it modifies state and takes complex objects)

### Endpoint
/AppService/UnpackWxapkgItem

### Parameters
#### Request Body
- **item** (WxapkgItem) - Required - The Wxapkg item to unpack.
- **options** (UnpackOptions) - Required - Options for the unpacking process.

### Request Example
```typescript
const item = { ...selectedItem, EncryptKey: "wx1a2b3c4d5e6f7a8b" };
const options = {
    EnableDecrypt: true,
    EnableJsonBeautify: true,
    EnableJsBeautify: true,
    EnableHtmlBeautify: false,
    OutputDir: "/Users/alice/output",
    SavePath: await AppService.ComputeSavePath("/Users/alice/output", item.Location),
};
await AppService.UnpackWxapkgItem(item, options);
```

### Response
This method returns immediately, with progress communicated via events.
```

--------------------------------

### Open Directory Dialog

Source: https://context7.com/wux1an/wxapkg/llms.txt

This TypeScript code shows how to open a native operating system directory selection dialog. It returns the selected path string, or an empty string if the user cancels.

```typescript
// 选择输出目录
const dir = await AppService.OpenDirectoryDialog("选择输出目录", "/Users/alice");
// 返回用户选择的路径字符串，取消时返回 ""
```

--------------------------------

### Analyze wxapkg Binary File Structure

Source: https://context7.com/wux1an/wxapkg/llms.txt

Parses the binary format of a .wxapkg file, including magic number validation, reading the file index table, and implementing safeguards against directory traversal and oversized files.

```go
if firstMark != 0xBE || lastMark != 0xED {
    return nil, errors.New("wxapkg 文件结构不合法")
}
if fileCount > 102400 {
    return nil, errors.Errorf("文件总数量 %d 超出上限 102400", fileCount)
}
// 目录穿越防护：
if !strings.HasPrefix(item.savePath, unpackSavePath) {
    return nil, errors.Errorf("文件名 %s 会导致目录穿越", item.name)
}
// 重名文件自动重命名：a.js → a-1.js → a-2.js
```

--------------------------------

### Code Beautification Functions

Source: https://context7.com/wux1an/wxapkg/llms.txt

Provides functions to format source code files after unpacking. Supports JSON, HTML (including inline <script> blocks), and JavaScript.

```go
// JSON 格式化
formatted := wechat.PrettyJson([]byte(`{"name":"hello","version":"1.0"}`))
// 输出：
// {
//   "name": "hello",
//   "version": "1.0"
// }
```

```go
// JavaScript 格式化
minified := []byte(`function add(a,b){return a+b;}var x=add(1,2);console.log(x);`)
formatted = wechat.PrettyJavaScript(minified)
// 输出：
// function add(a, b) {
//   return a + b;
// }
// var x = add(1, 2);
// console.log(x);
```

```go
// HTML 格式化（同时美化内联 <script>）
raw := []byte(`<view><text>hello</text><script>function f(){return 1}</script></view>`)
formatted = wechat.PrettyHtml(raw)
```

--------------------------------

### Compute Output Save Path

Source: https://context7.com/wux1an/wxapkg/llms.txt

Automatically determines the final output directory name based on the root output directory and the source file path. It removes the extension and appends '_unpacked'.

```go
savePath := appService.ComputeSavePath("/Users/alice/output", "/path/to/app.wxapkg")
// 返回：/Users/alice/output/app_unpacked
```

```go
savePath = appService.ComputeSavePath("C:\\output", "C:\\wechat\\wx1234\\__APP__.wxapkg")
// 返回：C:\output\__APP___unpacked
```

```javascript
// 前端调用
const savePath = await AppService.ComputeSavePath(outputDir, item.Location);
```

--------------------------------

### AppService.OpenFileDialog

Source: https://context7.com/wux1an/wxapkg/llms.txt

Opens the operating system's native file selection dialog with support for file type filtering.

```APIDOC
## AppService.OpenFileDialog

### Description
Opens the operating system's native file selection dialog, allowing the user to choose a file. Supports filtering by file type.

### Method
GET (assumed, as it triggers a UI interaction)

### Endpoint
/AppService/OpenFileDialog

### Parameters
#### Query Parameters
- **title** (string) - Required - The title displayed in the dialog window.
- **defaultPath** (string) - Optional - The initial directory path to display in the dialog.
- **fileFilters** (Array<Object>) - Optional - An array of objects, where each object defines a file filter with `DisplayName` and `Pattern` properties.
  - **DisplayName** (string) - The user-friendly name for the file type.
  - **Pattern** (string) - The file pattern to filter by (e.g., "*.wxapkg").

### Response
#### Success Response (200)
- (string) - The full path to the selected file, or an empty string if the dialog was cancelled.
```

--------------------------------

### AppService.GetWxapkgItem

Source: https://context7.com/wux1an/wxapkg/llms.txt

Fetches the latest status of a Wxapkg unpacking process using its UUID. This is used in conjunction with the 'unpack:progress-changed' event.

```APIDOC
## AppService.GetWxapkgItem

### Description
Fetches the latest status of a Wxapkg unpacking process using its UUID. This is used in conjunction with the 'unpack:progress-changed' event.

### Method
GET (assumed, as it retrieves data)

### Endpoint
/AppService/GetWxapkgItem

### Parameters
#### Query Parameters
- **uuid** (string) - Required - The unique identifier for the unpacking task.

### Response
#### Success Response (200)
- **UnpackProgress** (number) - The current progress percentage of the unpacking.
- **UnpackCurrentFile** (string) - The name of the file currently being processed.
- **UnpackStatus** (string) - The current status of the unpacking ('finished', 'error', etc.).
- **UnpackSavePath** (string) - The directory where the unpacked files are saved (if finished).
- **UnpackErrorMessage** (string) - An error message if the unpacking failed.
```

--------------------------------

### AES-CBC Decryption of wxapkg File

Source: https://context7.com/wux1an/wxapkg/llms.txt

Decrypts the first 1030 bytes of an encrypted wxapkg file using AES-CBC. The decryption key is derived using PBKDF2, and the remaining bytes are XORed with a key derived from the WxId.

```go
// 解密密钥推导：
dk := pbkdf2.Key([]byte(wxid), []byte("saltiest"), 1000, 32, sha1.New)
// CBC 解密头部 1024 字节：
block, _ := aes.NewCipher(dk)
blockMode := cipher.NewCBCDecrypter(block, []byte("the iv: 16 bytes"))
originData := make([]byte, 1024)
blockMode.CryptBlocks(originData, dataByte[6:1024+6])
// 尾部 XOR 还原：
xorKey := wxid[len(wxid)-2]  // 取 WxId 倒数第二个字节
for i, b := range dataByte[1024+6:] {
    afData[i] = b ^ xorKey
}
// 调用入口（传入 wxid 和原始加密字节）：
decrypted, err := decryptWxapkgFile("wx1a2b3c4d5e6f7a8b", encryptedBytes)
if err != nil {
    log.Fatal("解密失败:", err)
}
```

--------------------------------

### Open File Dialog with Filter

Source: https://context7.com/wux1an/wxapkg/llms.txt

This TypeScript code demonstrates opening a native file selection dialog with a specific file type filter. It returns the full path of the selected file.

```typescript
// 选择单个 .wxapkg 文件
const file = await AppService.OpenFileDialog(
    "选择小程序包",
    "/Users/alice",
    [{ DisplayName: "微信小程序包 (*.wxapkg)", Pattern: "*.wxapkg" }]
);
// 返回选中文件的完整路径
```
Tokens:
Raw