nitro-patcher 0.1.0

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "nitro-patcher",
+  "version": "0.1.0",
+  "description": "Native Node.js Nintendo DS ROM reader, repacker and ZIP/Xdelta patcher",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "GPL-3.0-only",
+  "bin": {
+    "nitro-patcher": "dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./nitro-helper": {
+      "types": "./dist/nitro-helper.d.ts",
+      "import": "./dist/nitro-helper.js"
+    },
+    "./nitro-patch-helper": {
+      "types": "./dist/nitro-patch-helper.d.ts",
+      "import": "./dist/nitro-patch-helper.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE",
+    "NOTICE.md",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Xzonn/nitro-patcher.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@noble/ciphers": "2.4.0",
+    "@noble/hashes": "2.4.0",
+    "@types/node": "22.20.2",
+    "buffer": "6.0.3",
+    "esbuild": "0.27.3",
+    "eslint": "10.9.1",
+    "eslint-config-prettier": "10.1.8",
+    "fflate": "0.8.3",
+    "globals": "16.5.0",
+    "jiti": "2.7.0",
+    "prettier": "3.9.6",
+    "tsup": "8.5.1",
+    "tsx": "4.23.13",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.70.0"
+  },
+  "imports": {
+    "#nitro-runtime": "./src/runtime/node.ts",
+    "#browser-hashes": "@noble/hashes/legacy.js",
+    "#browser-hmac": "@noble/hashes/hmac.js",
+    "#browser-aes": "@noble/ciphers/aes.js"
+  },
+  "scripts": {
+    "clean": "tsx scripts/clean.ts",
+    "build": "pnpm run build:node && pnpm run build:browser",
+    "typecheck": "tsc -p tsconfig.test.json",
+    "test": "tsx --test test/*.test.ts",
+    "test:reference": "tsx scripts/verify-reference.ts",
+    "check": "pnpm run typecheck && pnpm run lint && pnpm run format:check && pnpm test && pnpm run build && pnpm run test:browser",
+    "test:package": "tsx scripts/verify-package.ts",
+    "lint": "eslint . --max-warnings 0",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "build:node": "tsup src/index.ts src/nitro-helper.ts src/nitro-patch-helper.ts src/cli.ts --format esm --platform node --target node22 --splitting --sourcemap --dts --clean",
+    "build:browser": "tsx scripts/build-browser.ts",
+    "test:browser": "tsx scripts/verify-browser.ts"
+  }
+}

package/src/browser/buffer.ts

@@ -0,0 +1 @@
+export { Buffer } from 'buffer';

package/src/browser.ts

@@ -0,0 +1,60 @@
+import { NDSFile } from './nitro/nds-file';
+import { patchBuffer as patch } from './nitro-patch-helper';
+
+export interface BrowserPatchOptions {
+  maxOutputSize?: number;
+  maxWindowSize?: number;
+  maxUncompressedSize?: number;
+  maxEntries?: number;
+}
+export interface BrowserPatchResult {
+  buffer: Uint8Array<ArrayBuffer>;
+  returnValue: 'SUCCESS' | 'MD5_MISMATCH';
+  inputMd5: string;
+  outputMd5: string;
+}
+export interface RomInfo {
+  gameTitle: string;
+  gameCode: string;
+  size: number;
+  fileCount: number;
+  checksums: { header: boolean; logo: boolean; secureArea: boolean; banner: boolean };
+}
+/** Parse ROM metadata entirely in memory. No filesystem or Node types required. */
+export const inspectRom = (bytes: Uint8Array): RomInfo => {
+  const rom = new NDSFile(bytes);
+  return {
+    gameTitle: rom.header.gameTitle,
+    gameCode: rom.header.gameCode,
+    size: bytes.byteLength,
+    fileCount: rom.listFiles().length,
+    checksums: {
+      header: rom.header.headerCRC,
+      logo: rom.header.logoCRC,
+      secureArea: rom.header.secureCRC,
+      banner: rom.banner.bannerCRC,
+    },
+  };
+};
+/** Synchronous CPU work; call in a Web Worker for responsive browser UIs. */
+export const patchBuffer = (
+  original: Uint8Array,
+  archive: Uint8Array,
+  options: BrowserPatchOptions = {},
+): BrowserPatchResult => {
+  const result = patch(original, archive, options);
+  // Return a plain transferable typed array, never a Node Buffer in public types.
+  const buffer = new Uint8Array(
+    result.buffer.buffer as ArrayBuffer,
+    result.buffer.byteOffset,
+    result.buffer.byteLength,
+  );
+  return {
+    buffer,
+    returnValue: result.returnValue,
+    inputMd5: result.inputMd5,
+    outputMd5: result.outputMd5,
+  };
+};
+export const PatchHelper = Object.freeze({ patchBuffer });
+export const NitroHelper = Object.freeze({ inspectRom });

package/src/cli.ts

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import { mkdtemp, readFile, realpath, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { patchIt } from './nitro-patch-helper';
+
+const help = `nitro-patcher — 原生 Node.js NDS ROM 补丁工具
+
+用法：nitro-patcher [--json] <原始ROM> <补丁ZIP> <输出ROM>
+
+  --json        输出 JSON 状态和 MD5
+  -h, --help    显示帮助
+  -v, --version 显示版本`;
+
+const sameFile = async (input: string, output: string): Promise<boolean> => {
+  if (resolve(input) === resolve(output)) return true;
+  const original = await stat(input);
+  try {
+    const destination = await stat(output);
+    return original.dev === destination.dev && original.ino === destination.ino;
+  } catch (error) {
+    if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) throw error;
+    return false;
+  }
+};
+
+const main = async (): Promise<void> => {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      help: { type: 'boolean', short: 'h' },
+      version: { type: 'boolean', short: 'v' },
+      json: { type: 'boolean' },
+    },
+  });
+  if (values.help) {
+    process.stdout.write(help);
+    return;
+  }
+  if (values.version) {
+    const metadata: unknown = JSON.parse(
+      await readFile(new URL('../package.json', import.meta.url), 'utf8'),
+    );
+    if (
+      !metadata ||
+      typeof metadata !== 'object' ||
+      !('version' in metadata) ||
+      typeof metadata.version !== 'string'
+    )
+      throw new Error('Invalid package version metadata');
+    console.log(metadata.version);
+    return;
+  }
+  if (positionals.length !== 3) throw new Error(help);
+  const [original, patch, output] = positionals;
+  if ((await sameFile(original, output)) || (await sameFile(patch, output)))
+    throw new Error('输出路径不能覆盖原始 ROM 或补丁包。');
+  const result = await patchIt(original, patch);
+  const destination = join(await realpath(dirname(resolve(output))), basename(output));
+  const temporary = await mkdtemp(join(dirname(destination), '.nitro-patcher-'));
+  try {
+    const file = join(temporary, 'output.nds');
+    await writeFile(file, result.buffer);
+    await rename(file, destination);
+  } finally {
+    await rm(temporary, { recursive: true, force: true });
+  }
+  const { returnValue, inputMd5, outputMd5 } = result;
+  if (values.json) console.log(JSON.stringify({ returnValue, inputMd5, outputMd5 }));
+  else console.log(`${returnValue}\n\n原始 ROM 的 MD5：${inputMd5}\n生成 ROM 的 MD5：${outputMd5}`);
+};
+
+main().catch((error: unknown) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './nitro-helper';
+export * from './nitro-patch-helper';

package/src/nitro/banner.ts

@@ -0,0 +1,77 @@
+// Port of NitroHelper/Banner.cs. Copyright Xzonn and upstream contributors, GPL-3.0.
+import { bytes, range } from './binary';
+import { crc16 } from './crc';
+
+const titles = [
+  'japaneseTitle',
+  'englishTitle',
+  'frenchTitle',
+  'germanTitle',
+  'italianTitle',
+  'spanishTitle',
+  'chineseTitle',
+  'koreanTitle',
+] as const;
+export class Banner {
+  version: number;
+  raw: Buffer;
+  bannerCRC: boolean;
+  tileData: Buffer;
+  palette: Buffer;
+  japaneseTitle = '';
+  englishTitle = '';
+  frenchTitle = '';
+  germanTitle = '';
+  italianTitle = '';
+  spanishTitle = '';
+  chineseTitle = '';
+  koreanTitle = '';
+  constructor(input: Uint8Array, offset = 0, hardSize = 0) {
+    const data = bytes(input, 'banner');
+    this.version = range(data, offset, 2, 'banner').readUInt16LE();
+    let size = this.getDefSize(hardSize);
+    if (this.version >>> 8 === 1)
+      size = hardSize > 0 && hardSize !== 0xffffffff ? Math.min(hardSize, 0x23c0) : 0x23c0;
+    this.raw = Buffer.from(range(data, offset, size, 'banner'));
+    this.bannerCRC = crc16(this.raw.subarray(0x20, 0x840)) === this.raw.readUInt16LE(2);
+    this.tileData = Buffer.from(this.raw.subarray(0x20, 0x220));
+    this.palette = Buffer.from(this.raw.subarray(0x220, 0x240));
+    for (const [i, title] of titles.entries())
+      this[title] =
+        i < this.titleCount
+          ? this.raw
+              .subarray(0x240 + i * 0x100, 0x340 + i * 0x100)
+              .toString('utf16le')
+              .split('\0')[0]
+          : '';
+  }
+  get titleCount() {
+    return this.version >= 3 ? 8 : this.version >= 2 ? 7 : 6;
+  }
+  getDefSize(hardSize = 0) {
+    if (this.version === 2) return 0x940;
+    if (this.version === 3) return 0xa40;
+    if (this.version === 0x103) return hardSize > 0 && hardSize !== 0xffffffff ? hardSize : 0x23c0;
+    return 0x840;
+  }
+  toBuffer() {
+    const output = Buffer.from(this.raw);
+    output.writeUInt16LE(this.version);
+    if (this.tileData.length !== 512 || this.palette.length !== 32)
+      throw new RangeError('Invalid banner icon size');
+    this.tileData.copy(output, 0x20);
+    this.palette.copy(output, 0x220);
+    for (let i = 0; i < this.titleCount; i++) {
+      const text = Buffer.from(this[titles[i]], 'utf16le');
+      if (text.length > 256)
+        throw new RangeError(`Banner ${titles[i]} exceeds 128 UTF-16 code units`);
+      output.fill(0, 0x240 + i * 256, 0x340 + i * 256);
+      text.copy(output, 0x240 + i * 256);
+    }
+    output.writeUInt16LE(crc16(output.subarray(0x20, 0x840)), 2);
+    if (this.version >= 2) output.writeUInt16LE(crc16(output.subarray(0x20, 0x940)), 4);
+    if (this.version >= 3) output.writeUInt16LE(crc16(output.subarray(0x20, 0xa40)), 6);
+    if (this.version >>> 8 >= 1) output.writeUInt16LE(crc16(output.subarray(0x1240, 0x23c0)), 8);
+    return output;
+  }
+}

package/src/nitro/binary.ts

@@ -0,0 +1,80 @@
+export const DEFAULT_MAX_SIZE = 0x40000000;
+
+export const bytes = (value: Uint8Array, name = 'input'): Buffer => {
+  if (!(value instanceof Uint8Array)) throw new TypeError(`${name} must be a Buffer or Uint8Array`);
+  return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+};
+
+export const range = (
+  buffer: Buffer,
+  offset: number,
+  size: number,
+  name = 'binary data',
+): Buffer => {
+  if (
+    !Number.isSafeInteger(offset) ||
+    !Number.isSafeInteger(size) ||
+    offset < 0 ||
+    size < 0 ||
+    offset + size > buffer.length
+  ) {
+    throw new RangeError(
+      `Invalid ${name} range: offset=${offset}, size=${size}, available=${buffer.length}`,
+    );
+  }
+  return buffer.subarray(offset, offset + size);
+};
+
+export const align = (value: number, alignment = 0x200): number => {
+  return Math.ceil(value / alignment) * alignment;
+};
+
+/** Seekable, bounded in-memory writer; unwritten gaps have MemoryStream's zero fill. */
+export class BinaryWriter {
+  readonly maxSize: number;
+  buffer: Buffer;
+  position: number;
+  length: number;
+  constructor(initialSize = 65536, maxSize = DEFAULT_MAX_SIZE) {
+    if (!Number.isSafeInteger(maxSize) || maxSize < 1 || maxSize > 0xffffffff)
+      throw new RangeError('Invalid output size limit');
+    this.maxSize = maxSize;
+    this.buffer = Buffer.alloc(Math.min(initialSize, maxSize));
+    this.position = 0;
+    this.length = 0;
+  }
+
+  ensure(end: number) {
+    if (!Number.isSafeInteger(end) || end < 0 || end > this.maxSize)
+      throw new RangeError(`Output exceeds size limit (${this.maxSize} bytes)`);
+    if (end <= this.buffer.length) return;
+    const next = Buffer.alloc(Math.min(this.maxSize, Math.max(end, this.buffer.length * 2, 1024)));
+    this.buffer.copy(next, 0, 0, this.length);
+    this.buffer = next;
+  }
+
+  write(data: Uint8Array) {
+    data = bytes(data);
+    if (!Number.isSafeInteger(this.position) || this.position < 0)
+      throw new RangeError('Invalid writer position');
+    this.ensure(this.position + data.length);
+    bytes(data).copy(this.buffer, this.position);
+    this.position += data.length;
+    this.length = Math.max(this.length, this.position);
+  }
+
+  fillTo(end: number, fill = 0xff) {
+    this.ensure(end);
+    if (end <= this.position) return;
+    this.buffer.fill(fill, this.position, end);
+    this.position = end;
+    this.length = Math.max(this.length, end);
+  }
+
+  pad(alignment: number, fill = 0xff) {
+    this.fillTo(align(this.position, alignment), fill);
+  }
+  toBuffer() {
+    return this.buffer.subarray(0, this.length);
+  }
+}

package/src/nitro/blz.ts

@@ -0,0 +1,163 @@
+export interface Arm9Header {
+  reserved2: Buffer;
+  ARM9ramAddress: number;
+  ARM9size: number;
+}
+
+// Native port of Xzonn/BlzHelper BLZ.cs (MIT), including overwrite-safe prefix.
+// Compression returns an empty Buffer when no smaller representation exists.
+export const decompressBLZ = (input: Buffer, maxSize = 0x10000000): Buffer => {
+  if (input.length < 8) throw new Error('BLZ footer is truncated');
+  const diff = input.readUInt32LE(input.length - 4);
+  const packed = input.readUInt32LE(input.length - 8),
+    header = packed >>> 24,
+    length = packed & 0xffffff;
+  const size = input.length + diff,
+    prefix = input.length - length;
+  if (header < 8 || header > length || length > input.length || size > maxSize)
+    throw new Error('Invalid BLZ size or footer');
+  const out = Buffer.alloc(size);
+  input.copy(out, 0, 0, prefix);
+  let src = input.length - header,
+    dst = size;
+  while (src > prefix) {
+    const flags = input[--src];
+    for (let bit = 128; bit && src > prefix; bit >>= 1) {
+      if (!(flags & bit)) {
+        if (dst <= prefix) throw new Error('BLZ output overflow');
+        out[--dst] = input[--src];
+      } else {
+        if (src - 2 < prefix) throw new Error('Truncated BLZ reference');
+        const high = input[--src],
+          low = input[--src];
+        const count = (high >>> 4) + 3,
+          offset = (((high & 15) << 8) | low) + 3;
+        if (dst - count < prefix || dst - 1 + offset >= size)
+          throw new Error('Invalid BLZ reference');
+        for (let j = 0; j < count; j++) {
+          --dst;
+          out[dst] = out[dst + offset];
+        }
+      }
+    }
+  }
+  if (dst !== prefix) throw new Error('BLZ decompressed size mismatch');
+  return out;
+};
+
+export const compressBLZ = (input: Buffer): Buffer => {
+  if (input.length > 0xffffff) throw new Error('BLZ input exceeds 24-bit format limit');
+  const temp = Buffer.alloc(input.length);
+  let src = input.length,
+    dst = input.length;
+  // Linked candidate lists retain upstream nearest-match tie breaking without
+  // scanning every byte of the 4 KiB search window for each literal.
+  const heads = new Int32Array(256).fill(-1);
+  const next = new Int32Array(input.length);
+  let indexedFrom = input.length;
+  while (src > 0) {
+    if (dst < 1) return Buffer.alloc(0);
+    const flagPos = --dst;
+    let flags = 0;
+    for (let bit = 0; bit < 8; bit++) {
+      flags <<= 1;
+      if (!src) continue;
+      while (indexedFrom > src) {
+        const p = --indexedFrom;
+        next[p] = heads[input[p]];
+        heads[input[p]] = p;
+      }
+      const maxCount = Math.min(src, 18);
+      let best = 0,
+        offset = 0;
+      for (let p = heads[input[src - 1]]; p >= 0; p = next[p]) {
+        const d = p - src + 1;
+        if (d > 0x1002) break;
+        let n = 0;
+        const limit = Math.min(d, maxCount);
+        while (n < limit && input[src - 1 - n] === input[src + d - 1 - n]) n++;
+        if (n > best) {
+          best = n;
+          offset = d;
+          if (best === maxCount) break;
+        }
+      }
+      if (best < 3) {
+        if (dst < 1) return Buffer.alloc(0);
+        temp[--dst] = input[--src];
+      } else {
+        if (dst < 2) return Buffer.alloc(0);
+        src -= best;
+        dst -= 2;
+        temp[dst] = (offset - 3) & 255;
+        temp[dst + 1] = ((best - 3) << 4) | ((offset - 3) >>> 8);
+        flags |= 1;
+      }
+    }
+    temp[flagPos] = flags;
+  }
+  let packed = temp.subarray(dst),
+    sourcePos = input.length,
+    compressedPos = packed.length,
+    prefix = 0,
+    skip = 0;
+  outer: while (sourcePos > 0) {
+    const flags = packed[--compressedPos];
+    for (let bit = 128; bit && sourcePos > 0; bit >>= 1) {
+      if (!(flags & bit)) {
+        compressedPos--;
+        sourcePos--;
+      } else {
+        sourcePos -= (packed[compressedPos - 1] >>> 4) + 3;
+        compressedPos -= 2;
+        if (sourcePos < compressedPos) {
+          prefix = sourcePos;
+          skip = compressedPos;
+          break outer;
+        }
+      }
+    }
+  }
+  packed = Buffer.concat([input.subarray(0, prefix), packed.subarray(skip)]);
+  const aligned = Math.ceil(packed.length / 4) * 4,
+    finalSize = aligned + 8;
+  if (finalSize >= input.length) return Buffer.alloc(0);
+  const out = Buffer.alloc(finalSize, 255);
+  packed.copy(out);
+  const header = finalSize - packed.length,
+    length = packed.length - prefix + header;
+  out.writeUInt32LE(((header << 24) | length) >>> 0, finalSize - 8);
+  out.writeUInt32LE(input.length - finalSize, finalSize - 4);
+  return out;
+};
+
+export const decompressArm9 = (
+  data: Buffer,
+  header: Arm9Header,
+): { compressed: boolean; data: Buffer } => {
+  if (data.length < 0x18) throw new Error('ARM9 data too short');
+  const nitro = data.readUInt32LE(0xc) === 0xdec00621 ? 12 : 0;
+  const init = header.reserved2.readUInt32LE(0) & 0x3fff;
+  const ptr = init ? data.readUInt32LE(init + 0x14) : header.ARM9ramAddress + header.ARM9size;
+  const compressed =
+    ptr > header.ARM9ramAddress && ptr + nitro >= header.ARM9ramAddress + data.length;
+  return {
+    compressed,
+    data: compressed
+      ? Buffer.concat([
+          decompressBLZ(data.subarray(0, data.length - nitro)),
+          data.subarray(data.length - nitro),
+        ])
+      : Buffer.from(data),
+  };
+};
+export const compressArm9 = (data: Buffer, header: Arm9Header, postSize = 0): Buffer => {
+  if (data.length < 0x4000) throw new Error('ARM9 secure area is truncated');
+  const nitro = data.readUInt32LE(0xc) === 0xdec00621 ? 12 : 0;
+  const packed = compressBLZ(data.subarray(0x4000, data.length - nitro));
+  if (!packed.length) throw new Error('ARM9 BLZ compression produced no smaller representation');
+  const out = Buffer.concat([data.subarray(0, 0x4000), packed, data.subarray(data.length - nitro)]);
+  const init = header.reserved2.readUInt32LE(0) & 0x3fff;
+  if (init) out.writeUInt32LE(out.length - postSize + header.ARM9ramAddress, init + 0x14);
+  return out;
+};

package/src/nitro/crc.ts

@@ -0,0 +1,23 @@
+// CRCs used by the Nintendo DS header and banner (NitroHelper, GPL-3.0).
+const table16 = new Uint16Array(256);
+const table32 = new Uint32Array(256);
+for (let i = 0; i < 256; i++) {
+  let a = i,
+    b = i;
+  for (let bit = 0; bit < 8; bit++) {
+    a = (a >>> 1) ^ (a & 1 ? 0xa001 : 0);
+    b = (b >>> 1) ^ (b & 1 ? 0xedb88320 : 0);
+  }
+  table16[i] = a;
+  table32[i] = b;
+}
+export const crc16 = (data: Uint8Array, initial = 0xffff) => {
+  let crc = initial;
+  for (const byte of data) crc = (crc >>> 8) ^ table16[(crc ^ byte) & 0xff];
+  return crc;
+};
+export const crc32 = (data: Uint8Array) => {
+  let crc = 0xffffffff;
+  for (const byte of data) crc = (crc >>> 8) ^ table32[(crc ^ byte) & 0xff];
+  return (crc ^ 0xffffffff) >>> 0;
+};