nitro-patcher 0.3.0 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nitro-patcher",
-  "version": "0.3.0",
+  "version": "1.0.0",
   "description": "Native Node.js Nintendo DS ROM reader, repacker and ZIP/Xdelta patcher",
   "type": "module",
   "engines": {
@@ -49,6 +49,7 @@
     "@noble/ciphers": "2.4.0",
     "@noble/hashes": "2.4.0",
     "@types/node": "22.20.2",
+    "@types/node-forge": "1.3.14",
     "buffer": "6.0.3",
     "esbuild": "0.28.1",
     "eslint": "10.9.1",
@@ -59,7 +60,9 @@
     "fflate": "0.8.3",
     "globals": "16.5.0",
     "jiti": "2.7.0",
+    "playwright-core": "1.64.1",
     "prettier": "3.9.6",
+    "string_decoder": "1.3.0",
     "tsup": "8.5.1",
     "tsx": "4.23.13",
     "type-fest": "4.41.0",
@@ -73,7 +76,9 @@
     "#browser-aes": "@noble/ciphers/aes.js"
   },
   "dependencies": {
-    "markdansi": "0.3.3"
+    "iconv-lite": "0.7.3",
+    "markdansi": "0.3.3",
+    "node-forge": "1.4.0"
   },
   "scripts": {
     "clean": "tsx scripts/clean.ts",
@@ -81,6 +86,7 @@
     "typecheck": "tsc -p tsconfig.test.json",
     "test": "tsx --test test/*.test.ts",
     "test:reference": "tsx scripts/verify-reference.ts",
+    "test:dsi": "tsx scripts/verify-dsi.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",

package/src/browser/buffer.ts

@@ -1 +1,2 @@
 export { Buffer } from "buffer";
+export const window = globalThis;

package/src/browser.ts

@@ -8,6 +8,7 @@ import {
 } from "./nitro-patch-helper";
 
 export interface PatchMetadata {
+  formatVersion?: number;
   id?: string;
   author?: string;
   name?: string;
@@ -30,11 +31,28 @@ export interface BrowserPatchOptions {
   maxUncompressedSize?: number;
   maxEntries?: number;
 }
+export interface DsiCheck {
+  status: "valid" | "invalid" | "not-applicable";
+  reason?: string;
+}
+export interface DsiVerification {
+  arm9: DsiCheck;
+  arm7: DsiCheck;
+  arm9i: DsiCheck;
+  arm7i: DsiCheck;
+  arm9NoSecure: DsiCheck;
+  banner: DsiCheck;
+  sectors: DsiCheck;
+  blocks: DsiCheck;
+  master: DsiCheck;
+  signature: DsiCheck;
+}
 export interface BrowserPatchResult {
   buffer: Uint8Array<ArrayBuffer>;
   returnValue: "SUCCESS" | "MD5_MISMATCH";
   inputMd5: string;
   outputMd5: string;
+  dsi?: DsiVerification;
 }
 export interface RomInfo {
   gameTitle: string;
@@ -42,10 +60,11 @@ export interface RomInfo {
   size: number;
   fileCount: number;
   checksums: { header: boolean; logo: boolean; secureArea: boolean; banner: boolean };
+  dsi?: DsiVerification;
 }
 /** Parse ROM metadata entirely in memory. No filesystem or Node types required. */
-export const inspectRom = (bytes: Uint8Array): RomInfo => {
-  const rom = new NDSFile(bytes);
+export const inspectRom = (bytes: Uint8Array, options: { dsiMode?: "legacy" | "complete" } = {}): RomInfo => {
+  const rom = new NDSFile(bytes, options);
   return {
     gameTitle: rom.header.gameTitle,
     gameCode: rom.header.gameCode,
@@ -57,6 +76,7 @@ export const inspectRom = (bytes: Uint8Array): RomInfo => {
       secureArea: rom.header.secureCRC,
       banner: rom.banner.bannerCRC,
     },
+    ...(options.dsiMode === "complete" && { dsi: rom.verifyDsi() }),
   };
 };
 /** Synchronous CPU work; call in a Web Worker for responsive browser UIs. */
@@ -77,6 +97,7 @@ export const patchBuffer = (
     returnValue: result.returnValue,
     inputMd5: result.inputMd5,
     outputMd5: result.outputMd5,
+    ...(result.dsi && { dsi: result.dsi }),
   };
 };
 /** Read and validate metadata.json from a patch package entirely in memory. */

package/src/cli.ts

@@ -17,6 +17,7 @@ const help = `nitro-patcher — NDS ROM 补丁工具
 
   --json         结果输出为 JSON 格式
   --dry-run      完整执行补丁流程，但不写入输出 ROM
+  --dsi-mode     extract/inspect 的 DSi 处理模式：legacy 或 complete
   -i, --input    输入 ROM 路径
   -p, --patch    补丁 ZIP 路径
   -o, --output   输出 ROM 或提取目录；试运行时可省略
@@ -29,6 +30,7 @@ interface CommandOptions {
   input: string | undefined;
   patch: string | undefined;
   output: string | undefined;
+  dsiMode: "legacy" | "complete" | undefined;
 }
 
 const sameFile = async (input: string, output: string): Promise<boolean> => {
@@ -79,7 +81,7 @@ const formatMetadata = (metadata: PatchMetadata): string => {
 const extractRom = async (options: CommandOptions): Promise<void> => {
   if (!options.input || !options.output || options.patch !== undefined || options.dryRun) throw new Error(help);
   const destination = join(await realpath(dirname(resolve(options.output))), basename(resolve(options.output)));
-  const rom = new NDSFile(await readFile(options.input));
+  const rom = new NDSFile(await readFile(options.input), { dsiMode: options.dsiMode ?? "legacy" });
   const files = rom.listFiles();
   await mkdir(destination, { recursive: true });
   for (const { path } of files) {
@@ -106,7 +108,7 @@ const inspectRom = async (options: CommandOptions): Promise<void> => {
   if (!options.input || options.patch !== undefined || options.output !== undefined || options.dryRun)
     throw new Error(help);
   const input = await readFile(options.input);
-  const rom = new NDSFile(input);
+  const rom = new NDSFile(input, { dsiMode: options.dsiMode ?? "legacy" });
   const info = {
     gameTitle: rom.header.gameTitle.replace(/\0+$/, ""),
     gameCode: rom.header.gameCode,
@@ -118,6 +120,7 @@ const inspectRom = async (options: CommandOptions): Promise<void> => {
       secureArea: rom.header.secureCRC,
       banner: rom.banner.bannerCRC,
     },
+    ...(options.dsiMode === "complete" && { dsi: rom.verifyDsi() }),
   };
   if (options.json) {
     console.log(JSON.stringify(info));
@@ -134,6 +137,9 @@ const inspectRom = async (options: CommandOptions): Promise<void> => {
 - Logo：${info.checksums.logo ? "通过" : "失败"}
 - Secure Area：${info.checksums.secureArea ? "通过" : "失败"}
 - Banner：${info.checksums.banner ? "通过" : "失败"}`);
+  if (info.dsi)
+    for (const [name, result] of Object.entries(info.dsi))
+      console.log(`- DSi ${name}：${result.status}${result.reason ? ` (${result.reason})` : ""}`);
 };
 
 const main = async (): Promise<void> => {
@@ -144,6 +150,7 @@ const main = async (): Promise<void> => {
       version: { type: "boolean", short: "v" },
       json: { type: "boolean" },
       "dry-run": { type: "boolean" },
+      "dsi-mode": { type: "string" },
       input: { type: "string", short: "i" },
       patch: { type: "string", short: "p" },
       output: { type: "string", short: "o" },
@@ -160,12 +167,16 @@ const main = async (): Promise<void> => {
     console.log(metadata.version);
     return;
   }
+  const dsiMode = values["dsi-mode"];
+  if (dsiMode !== undefined && dsiMode !== "legacy" && dsiMode !== "complete")
+    throw new Error("Invalid --dsi-mode; expected legacy or complete");
   const options: CommandOptions = {
     json: values.json ?? false,
     dryRun: values["dry-run"] ?? false,
     input: values.input,
     patch: values.patch,
     output: values.output,
+    dsiMode,
   };
   const command = positionals.length === 1 ? positionals[0] : undefined;
   if (positionals.length !== 0 && positionals.length !== 1 && positionals.length !== 3) throw new Error(help);
@@ -181,6 +192,7 @@ const main = async (): Promise<void> => {
   }
 
   const dryRun = options.dryRun;
+  if (options.dsiMode !== undefined) throw new Error("patch selects DSi processing from metadata.json formatVersion");
   const usesLegacyPaths = positionals.length === 3;
   if (usesLegacyPaths && (values.input !== undefined || values.patch !== undefined || values.output !== undefined))
     throw new Error(help);
@@ -216,6 +228,7 @@ const main = async (): Promise<void> => {
         outputMd5,
         ...info,
         ...(dryRun && { dryRun: true }),
+        ...(result.dsi && { dsi: result.dsi }),
       }),
     );
     return;

package/src/nitro/blz.ts

@@ -1,4 +1,5 @@
 export interface Arm9Header {
+  nitrocode?: boolean;
   reserved2: Buffer;
   ARM9ramAddress: number;
   ARM9size: number;
@@ -130,22 +131,30 @@ export const compressBLZ = (input: Buffer): Buffer => {
   return out;
 };
 
-export const decompressArm9 = (data: Buffer, header: Arm9Header): { compressed: boolean; data: Buffer } => {
+export const decompressArm9 = (
+  data: Buffer,
+  header: Arm9Header,
+  maxSize = 0x10000000,
+): { compressed: boolean; data: Buffer } => {
   if (data.length < 0x18) throw new Error("ARM9 data too short");
-  const nitro = data.readUInt32LE(0xc) === 0xdec00621 ? 12 : 0;
+  if (data.length > maxSize) throw new RangeError("ARM9 exceeds output size limit");
+  const nitro = (header.nitrocode ?? 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.concat([
+          decompressBLZ(data.subarray(0, data.length - nitro), maxSize - 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 nitro = (header.nitrocode ?? 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)]);

package/src/nitro/crypto.ts

@@ -1,5 +1,7 @@
 import { createAesBlockCipher } from "#nitro-runtime";
 
+import { crc16 } from "./crc";
+
 export interface ModcryptHeader {
   gameCode: string;
   gameTitle: string;
@@ -117,32 +119,37 @@ export const modcryptKey = (header: ModcryptHeader): Buffer => {
   return out;
 };
 
-export const encryptSecureArea = (gameCode: string, input: Buffer): Buffer => {
+export const encryptSecureArea = (gameCode: string, input: Buffer, refreshCrc = false): Buffer =>
+  secureAreaCrypt(gameCode, input, false, refreshCrc);
+export const decryptSecureArea = (gameCode: string, input: Buffer): Buffer => secureAreaCrypt(gameCode, input, true);
+
+const secureAreaCrypt = (gameCode: string, input: Buffer, decrypting: boolean, refreshCrc = false): Buffer => {
   if (typeof gameCode !== "string" || gameCode.length !== 4) throw new Error("Expected four-character game code");
   if (input.length < 0x800) throw new RangeError("Secure area must contain at least 0x800 bytes");
   const output = Buffer.from(input);
+  if (refreshCrc) output.writeUInt16LE(crc16(output.subarray(0x10, 0x800)), 0xe);
   let magic = new Uint32Array(0x412);
   let args: [number, number, number] = [0, 0, 0];
-  function encrypt(a: number, b: number): [number, number] {
+  function crypt(a: number, b: number, reverse = false): [number, number] {
     for (let i = 0; i < 16; i++) {
-      const c = (magic[i] ^ a) >>> 0;
+      const c = (magic[reverse ? 17 - i : i] ^ a) >>> 0;
       const sum = (magic[18 + (c >>> 24)] + magic[274 + ((c >>> 16) & 255)]) >>> 0;
       const f = (magic[786 + (c & 255)] + (magic[530 + ((c >>> 8) & 255)] ^ sum)) >>> 0;
       a = (b ^ f) >>> 0;
       b = c;
     }
-    return [(b ^ magic[17]) >>> 0, (a ^ magic[16]) >>> 0];
+    return [(b ^ magic[reverse ? 0 : 17]) >>> 0, (a ^ magic[reverse ? 1 : 16]) >>> 0];
   }
   function init2() {
-    [args[2], args[1]] = encrypt(args[2], args[1]);
-    [args[1], args[0]] = encrypt(args[1], args[0]);
+    [args[2], args[1]] = crypt(args[2], args[1]);
+    [args[1], args[0]] = crypt(args[1], args[0]);
     const key = Buffer.alloc(12);
     args.forEach((v, i) => key.writeUInt32LE(v, i * 4));
     for (let j = 0; j < 18; j++) magic[j] ^= key.readUInt32BE((j * 4) & 7);
     let a = 0,
       b = 0;
     for (let i = 0; i < 0x412; i += 2) {
-      [a, b] = encrypt(a, b);
+      [a, b] = crypt(a, b);
       magic[i] = a;
       magic[i + 1] = b;
     }
@@ -155,17 +162,28 @@ export const encryptSecureArea = (gameCode: string, input: Buffer): Buffer => {
     init2();
   }
   init1();
+  if (decrypting) {
+    const [b, a] = crypt(output.readUInt32LE(4), output.readUInt32LE(0), true);
+    output.writeUInt32LE(a, 0);
+    output.writeUInt32LE(b, 4);
+  }
   args[1] = (args[1] << 1) >>> 0;
   args[2] >>>= 1;
   init2();
-  for (let p = 8; p < 0x800; p += 8) {
-    const [b, a] = encrypt(output.readUInt32LE(p + 4), output.readUInt32LE(p));
+  for (let p = decrypting ? 0 : 8; p < 0x800; p += 8) {
+    const [b, a] = crypt(output.readUInt32LE(p + 4), output.readUInt32LE(p), decrypting);
     output.writeUInt32LE(a, p);
     output.writeUInt32LE(b, p + 4);
   }
-  let [b, a] = encrypt(0x6a624f79, 0x72636e65);
+  if (decrypting) {
+    if (output.readUInt32LE(0) !== 0x72636e65 || output.readUInt32LE(4) !== 0x6a624f79)
+      throw new Error("Invalid KEY1 secure-area marker");
+    output.writeBigUInt64LE(0xe7ffdeffe7ffdeffn);
+    return output;
+  }
+  let [b, a] = crypt(0x6a624f79, 0x72636e65);
   init1();
-  [b, a] = encrypt(b, a);
+  [b, a] = crypt(b, a);
   output.writeUInt32LE(a, 0);
   output.writeUInt32LE(b, 4);
   return output;

package/src/nitro/filesystem.ts

@@ -1,9 +1,12 @@
 // Based on NitroHelper FNT/FAT/OverlayTable, GPL-3.0.
-import { bytes, range } from "./binary";
+import iconv from "iconv-lite";
 
-/** A file in the original ROM, optionally replaced with new bytes. */
+import { BinaryWriter, bytes, range } from "./binary";
+
+/** Original IDs/offsets describe the input ROM; newly added files use -1 until serialized and reopened. */
 export interface NitroFile {
   name: string;
+  nameBytes?: Buffer;
   id: number;
   offset: number;
   size: number;
@@ -12,11 +15,27 @@ export interface NitroFile {
 
 export interface NitroFolder {
   name: string;
+  nameBytes?: Buffer;
   id: number;
   files: NitroFile[];
   folders: NitroFolder[];
 }
 
+export const encodeName = (name: string): Buffer => {
+  const encoded = iconv.encode(name, "shift_jis");
+  if (new TextDecoder("shift_jis").decode(encoded) !== name)
+    throw new Error(`FNT name cannot be represented in Shift_JIS: ${name}`);
+  if (!encoded.length || encoded.length > 127) throw new Error("FNT name must contain 1 to 127 encoded bytes");
+  return encoded;
+};
+
+export interface FileSystemLayout {
+  fnt: Buffer;
+  files: NitroFile[];
+  ids: Map<NitroFile, number>;
+  sourceIds: Map<number, number>;
+}
+
 export interface FatEntry {
   id: number;
   offset: number;
@@ -72,7 +91,8 @@ export class FileNameTable {
         if (!tag) break;
         const length = tag & 0x7f;
         if (!length) throw new Error("Empty FNT directory name");
-        const filename = decoder.decode(range(table, cursor, length, "FNT filename"));
+        const nameBytes = Buffer.from(range(table, cursor, length, "FNT filename"));
+        const filename = decoder.decode(nameBytes);
         cursor += length;
         if (
           filename.includes("/") ||
@@ -89,13 +109,15 @@ export class FileNameTable {
           const id = range(table, cursor, 2, "FNT directory id").readUInt16LE();
           cursor += 2;
           if (id < 0xf000) throw new Error("Invalid FNT directory id");
-          folder.folders.push(parse(id & 0xfff, filename, depth + 1));
+          const child = parse(id & 0xfff, filename, depth + 1);
+          child.nameBytes = nameBytes;
+          folder.folders.push(child);
         } else {
           const entry = fat.entries[fileId++];
           if (!entry) throw new Error("FNT file id is outside FAT");
           if (fileIds.has(entry.id)) throw new Error(`Duplicate FNT file id: ${entry.id}`);
           fileIds.add(entry.id);
-          folder.files.push({ name: filename, ...entry });
+          folder.files.push({ name: filename, nameBytes, ...entry });
         }
       }
       return folder;
@@ -103,6 +125,67 @@ export class FileNameTable {
     this.root = { name: "root", id: 0xffff, files: [], folders: [parse(0, "data", 0)] };
   }
 
+  serialize(fat: FileAllocationTable, overlays: NitroFile[]): FileSystemLayout {
+    const directories: { folder: NitroFolder; parent: number; firstId: number }[] = [];
+    const named: NitroFile[] = [];
+    const sort = <T extends NitroFile | NitroFolder>(items: T[]): T[] =>
+      [...items].sort((a, b) => Buffer.compare(a.nameBytes ?? encodeName(a.name), b.nameBytes ?? encodeName(b.name)));
+    const visit = (folder: NitroFolder, parent: number): void => {
+      const index = directories.length;
+      directories.push({ folder, parent, firstId: named.length });
+      if (directories.length > 4096) throw new Error("FNT directory count exceeds 4096");
+      named.push(...sort(folder.files));
+      for (const child of sort(folder.folders)) visit(child, 0xf000 + index);
+    };
+    visit(this.root.folders[0], 0xf000);
+    const namedIds = new Set(named.filter((file) => file.id >= 0).map((file) => file.id));
+    const overlayIds = new Set(overlays.map((file) => file.id));
+    const unnamed = fat.entries
+      .filter((entry) => !namedIds.has(entry.id))
+      .map((entry) => ({ ...entry, name: `FAT entry ${entry.id}` }));
+    const files: NitroFile[] = [
+      ...unnamed.filter((entry) => overlayIds.has(entry.id)),
+      ...overlays
+        .filter((file) => file.id < 0)
+        .sort(
+          (a, b) =>
+            Number(a.name.startsWith("overlay7_")) - Number(b.name.startsWith("overlay7_")) ||
+            Number(a.name.slice(a.name.indexOf("_") + 1, -4)) - Number(b.name.slice(b.name.indexOf("_") + 1, -4)),
+        ),
+      ...unnamed.filter((entry) => !overlayIds.has(entry.id)),
+    ];
+    const firstNamed = files.length;
+    files.push(...named);
+    if (files.length > 0xf000) throw new Error("Filesystem file IDs exceed 0xEFFF");
+    const ids = new Map(files.map((file, id) => [file, id]));
+    const sourceIds = new Map(files.filter((file) => file.id >= 0).map((file) => [file.id, ids.get(file)!]));
+    const directoryIds = new Map(directories.map(({ folder }, index) => [folder, 0xf000 + index]));
+    const writer = new BinaryWriter();
+    writer.write(Buffer.alloc(directories.length * 8));
+    for (const [index, { folder, parent, firstId }] of directories.entries()) {
+      const record = Buffer.alloc(8);
+      record.writeUInt32LE(writer.position);
+      record.writeUInt16LE(firstNamed + firstId, 4);
+      record.writeUInt16LE(index === 0 ? directories.length : parent, 6);
+      record.copy(writer.buffer, index * 8);
+      for (const file of sort(folder.files)) {
+        const name = file.nameBytes ?? encodeName(file.name);
+        writer.write(Buffer.from([name.length]));
+        writer.write(name);
+      }
+      for (const child of sort(folder.folders)) {
+        const name = child.nameBytes ?? encodeName(child.name);
+        writer.write(Buffer.from([0x80 | name.length]));
+        writer.write(name);
+        const id = Buffer.alloc(2);
+        id.writeUInt16LE(directoryIds.get(child)!);
+        writer.write(id);
+      }
+      writer.write(Buffer.from([0]));
+    }
+    return { fnt: writer.toBuffer(), files, ids, sourceIds };
+  }
+
   static findFile(id: number, folder: NitroFolder): NitroFile | undefined {
     for (const file of folder.files) if (file.id === id) return file;
     for (const subfolder of folder.folders) {

package/src/nitro/header.ts

@@ -77,6 +77,8 @@ export class Header {
   declare ARM9autoload: number;
   declare ARM7autoload: number;
   declare ROMsize: number;
+  declare ntr_region_end: number;
+  declare twl_region_start: number;
   declare headerSize: number;
   declare logoCRC16: number;
   declare headerCRC16: number;
@@ -219,6 +221,8 @@ field("secureDisable", 0x78, 8, "number");
 field("ROMsize", 0x80, 4, "number");
 field("headerSize", 0x84, 4, "number");
 field("reserved2", 0x88, 56);
+field("ntr_region_end", 0x90, 2, "number");
+field("twl_region_start", 0x92, 2, "number");
 field("logo", 0xc0, 156);
 field("logoCRC16", 0x15c, 2, "number");
 field("headerCRC16", 0x15e, 2, "number");