nitro-patcher 0.3.0 → 1.1.0

package/dist/twl-complete-B2is30H0.d.ts

@@ -0,0 +1,201 @@
+declare const UnitCode: Readonly<{
+    NDS: 0;
+    NDS_DSi: 2;
+    DSi: 3;
+}>;
+declare class Header {
+    raw: Buffer;
+    trimmedRom: boolean;
+    doublePadding: boolean;
+    nitrocode: boolean;
+    decrypted: boolean;
+    headerCRC: boolean;
+    logoCRC: boolean;
+    secureCRC: boolean;
+    dlp_signature: Buffer;
+    ARM9romOffset: number;
+    ARM9entryAddress: number;
+    ARM9ramAddress: number;
+    ARM9size: number;
+    ARM7romOffset: number;
+    ARM7entryAddress: number;
+    ARM7ramAddress: number;
+    ARM7size: number;
+    FNToffset: number;
+    FNTsize: number;
+    FAToffset: number;
+    FATsize: number;
+    ARM9overlayOffset: number;
+    ARM9overlaySize: number;
+    ARM7overlayOffset: number;
+    ARM7overlaySize: number;
+    flagsRead: number;
+    flagsInit: number;
+    bannerOffset: number;
+    dsi9_rom_offset: number;
+    offset_0x1C4: number;
+    dsi9_ram_address: number;
+    dsi9_size: number;
+    dsi7_rom_offset: number;
+    offset_0x1D4: number;
+    dsi7_ram_address: number;
+    dsi7_size: number;
+    digest_ntr_start: number;
+    digest_ntr_size: number;
+    digest_twl_start: number;
+    digest_twl_size: number;
+    sector_hashtable_start: number;
+    sector_hashtable_size: number;
+    block_hashtable_start: number;
+    block_hashtable_size: number;
+    digest_sector_size: number;
+    digest_block_sectorcount: number;
+    banner_size: number;
+    offset_0x20C: number;
+    total_rom_size: number;
+    offset_0x214: number;
+    offset_0x218: number;
+    offset_0x21C: number;
+    modcrypt1_start: number;
+    modcrypt1_size: number;
+    modcrypt2_start: number;
+    modcrypt2_size: number;
+    tid_low: number;
+    tid_high: number;
+    public_sav_size: number;
+    private_sav_size: number;
+    unitCode: number;
+    encryptionSeed: number;
+    twlInternalFlags: number;
+    permitsFlags: number;
+    ROMversion: number;
+    internalFlags: number;
+    secureCRC16: number;
+    ROMtimeout: number;
+    ARM9autoload: number;
+    ARM7autoload: number;
+    ROMsize: number;
+    ntr_region_end: number;
+    twl_region_start: number;
+    headerSize: number;
+    logoCRC16: number;
+    headerCRC16: number;
+    debug_romOffset: number;
+    debug_size: number;
+    debug_ramAddress: number;
+    reserved3: number;
+    mbk9_wramcnt_setting: number;
+    region_flags: number;
+    access_control: number;
+    scfg_ext_mask: number;
+    gameTitle: string;
+    gameCode: string;
+    makerCode: string;
+    reserved: Buffer;
+    reserved2: Buffer;
+    logo: Buffer;
+    appflags: Buffer;
+    hmac_arm9: Buffer;
+    hmac_arm7: Buffer;
+    hmac_digest_master: Buffer;
+    hmac_icon_title: Buffer;
+    hmac_arm9i: Buffer;
+    hmac_arm7i: Buffer;
+    hmac_arm9_no_secure: Buffer;
+    rsa_signature: Buffer;
+    secureDisable: bigint;
+    constructor(input: Uint8Array);
+    get size(): number;
+    set size(value: number);
+    toBuffer(): Buffer<ArrayBuffer>;
+    toString(): string;
+}
+
+interface Arm9Header {
+    nitrocode?: boolean;
+    reserved2: Buffer;
+    ARM9ramAddress: number;
+    ARM9size: number;
+}
+declare const decompressBLZ: (input: Buffer, maxSize?: number) => Buffer;
+declare const compressBLZ: (input: Buffer) => Buffer;
+declare const decompressArm9: (data: Buffer, header: Arm9Header, maxSize?: number) => {
+    compressed: boolean;
+    data: Buffer;
+};
+declare const compressArm9: (data: Buffer, header: Arm9Header, postSize?: number) => Buffer;
+
+interface DsiCheck {
+    status: "valid" | "invalid" | "not-applicable";
+    reason?: string;
+}
+interface DsiVerification {
+    arm9: DsiCheck;
+    arm7: DsiCheck;
+    arm9i: DsiCheck;
+    arm7i: DsiCheck;
+    arm9NoSecure: DsiCheck;
+    banner: DsiCheck;
+    sectors: DsiCheck;
+    blocks: DsiCheck;
+    master: DsiCheck;
+    signature: DsiCheck;
+}
+type ProgramName = "arm9" | "arm7" | "arm9i" | "arm7i";
+interface Program {
+    name: ProgramName;
+    start: number;
+    length: number;
+    data: Buffer;
+    original: Buffer;
+    replaced: boolean;
+}
+interface CryptRegion {
+    id: 1 | 2;
+    program: ProgramName;
+    offset: number;
+    length: number;
+    kind: "whole" | "secure" | "fixed";
+}
+interface DsiSection {
+    label: string;
+    start: number;
+    originalSize: number;
+    data: Buffer;
+    place: (start: number) => void;
+}
+/** Complete cartridge processing; legacy TWL serialization stays independent. */
+declare class CompleteTWL {
+    readonly header: Header;
+    readonly programs: Map<ProgramName, Program>;
+    readonly regions: CryptRegion[];
+    readonly hasDigests: boolean;
+    readonly Hashtable1Data: Buffer;
+    readonly Hashtable2Data: Buffer;
+    readonly Header2Data: Buffer[];
+    readonly Overlays9Sha1Hmac: Buffer[];
+    readonly twlEncrypted: boolean;
+    readonly firstDSiHashOffset: number;
+    readonly dsiHashSize: number;
+    private readonly original;
+    private readonly limit;
+    constructor(header: Header, overlays: readonly Buffer[], original: Buffer, limit: number);
+    private validateDigests;
+    private decryptPrograms;
+    get DSi9Data(): Buffer;
+    set DSi9Data(data: Buffer);
+    get DSi7Data(): Buffer;
+    set DSi7Data(data: Buffer);
+    getProgram(name: ProgramName): Buffer;
+    setProgram(name: ProgramName, data: Buffer): void;
+    importArm9iData(data: Buffer | string, offset?: number, size?: number): void;
+    importArm7iData(data: Buffer | string, offset?: number, size?: number): void;
+    unchanged(): boolean;
+    updateOverlays9Sha1Hmac(arm9: Buffer, h: Arm9Header, overlays: readonly Buffer[]): Buffer;
+    private view;
+    verify(data?: Buffer<ArrayBufferLike>, h?: Header): DsiVerification;
+    serialize(h: Header, sections: DsiSection[], forceLayout: boolean): Buffer;
+    private checkMovableTwl;
+}
+
+export { type Arm9Header as A, CompleteTWL as C, type DsiCheck as D, Header as H, UnitCode as U, type DsiVerification as a, compressBLZ as b, compressArm9 as c, decompressArm9 as d, decompressBLZ as e };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nitro-patcher",
-  "version": "0.3.0",
+  "version": "1.1.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",
@@ -56,10 +57,11 @@
     "eslint-plugin-import-x": "4.17.1",
     "eslint-plugin-prettier": "5.5.5",
     "eslint-plugin-unused-imports": "4.4.1",
-    "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 +75,11 @@
     "#browser-aes": "@noble/ciphers/aes.js"
   },
   "dependencies": {
-    "markdansi": "0.3.3"
+    "@limrun/xdelta3-wasm": "0.2.0",
+    "fflate": "0.8.3",
+    "iconv-lite": "0.7.3",
+    "markdansi": "0.3.3",
+    "node-forge": "1.4.0"
   },
   "scripts": {
     "clean": "tsx scripts/clean.ts",
@@ -81,6 +87,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

@@ -1,5 +1,6 @@
 import { NDSFile } from "./nitro/nds-file";
 import {
+  createPatch as create,
   extractZipEntry as extractEntry,
   patchBuffer as patch,
   readPatchInfo as readInfo,
@@ -8,6 +9,7 @@ import {
 } from "./nitro-patch-helper";
 
 export interface PatchMetadata {
+  formatVersion?: number;
   id?: string;
   author?: string;
   name?: string;
@@ -30,11 +32,43 @@ export interface BrowserPatchOptions {
   maxUncompressedSize?: number;
   maxEntries?: number;
 }
+export interface CreatePatchOptions extends BrowserPatchOptions {
+  metadata?: Omit<PatchMetadata, "formatVersion">;
+  readme?: string;
+}
+export interface CreatePatchResult {
+  buffer: Uint8Array<ArrayBuffer>;
+  changedFiles: number;
+  warnings: string[];
+}
+/** Create an in-memory XZP with diagnostic warnings. Call in a Web Worker. */
+export const createPatch = (
+  original: Uint8Array,
+  modified: Uint8Array,
+  options: CreatePatchOptions = {},
+): Promise<CreatePatchResult> => create(original, modified, options);
+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 +76,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 +92,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 +113,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. */
@@ -96,6 +133,7 @@ export const extractZipEntry = (
 ): Uint8Array<ArrayBuffer> => new Uint8Array(extractEntry(archive, entryName, options));
 
 export const PatchHelper = Object.freeze({
+  createPatch,
   extractZipEntry,
   patchBuffer,
   readPatchInfo,

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;