nitro-patcher 0.3.0 → 1.0.0

package/src/nitro/twl.ts

@@ -1,10 +1,13 @@
-import { hashDigest, hmacSha1, readFileSync, verifyRsaSha1 } from "#nitro-runtime";
+import { hmacSha1, readFileSync, verifyRsaSha1 } from "#nitro-runtime";
 
 import type { BinaryWriter } from "./binary";
+import { DEFAULT_MAX_SIZE } from "./binary";
 import type { Arm9Header } from "./blz";
 import { compressArm9, decompressArm9 } from "./blz";
 import type { ModcryptHeader } from "./crypto";
 import { aes128CtrCrypt, encryptSecureArea, modcryptKey } from "./crypto";
+import { Header } from "./header";
+import { CompleteTWL } from "./twl-complete";
 
 export interface TwlHeader extends ModcryptHeader {
   digest_sector_size: number;
@@ -108,9 +111,46 @@ export class TWL {
   readonly Header2Data: Buffer[] | null;
   readonly Overlays9Sha1Hmac: Buffer[];
   readonly twlEncrypted: boolean;
-  DSi9Data: Buffer;
-  DSi7Data: Buffer;
-  constructor(header: TwlHeader, overlays: readonly OverlayRange[], original: Buffer) {
+  readonly complete: CompleteTWL | undefined;
+  private dsi9Data: Buffer = Buffer.alloc(0);
+  private dsi7Data: Buffer = Buffer.alloc(0);
+  get DSi9Data(): Buffer {
+    return this.complete?.DSi9Data ?? this.dsi9Data;
+  }
+  set DSi9Data(data: Buffer) {
+    if (this.complete) this.complete.DSi9Data = data;
+    else this.dsi9Data = data;
+  }
+  get DSi7Data(): Buffer {
+    return this.complete?.DSi7Data ?? this.dsi7Data;
+  }
+  set DSi7Data(data: Buffer) {
+    if (this.complete) this.complete.DSi7Data = data;
+    else this.dsi7Data = data;
+  }
+  constructor(
+    header: TwlHeader,
+    overlays: readonly OverlayRange[],
+    original: Buffer,
+    options: { dsiMode?: "legacy" | "complete"; maxOutputSize?: number } = {},
+  ) {
+    if (options.dsiMode === "complete") {
+      if (!(header instanceof Header)) throw new TypeError("Complete DSi handling requires a parsed Header");
+      this.complete = new CompleteTWL(
+        header,
+        overlays.map((overlay) => slice(original, overlay.offset, overlay.size, "Signed ARM9 overlay")),
+        original,
+        options.maxOutputSize ?? DEFAULT_MAX_SIZE,
+      );
+      this.firstDSiHashOffset = this.complete.firstDSiHashOffset;
+      this.dsiHashSize = this.complete.dsiHashSize;
+      this.Hashtable1Data = this.complete.Hashtable1Data;
+      this.Hashtable2Data = this.complete.Hashtable2Data;
+      this.Header2Data = this.complete.Header2Data;
+      this.Overlays9Sha1Hmac = this.complete.Overlays9Sha1Hmac;
+      this.twlEncrypted = this.complete.twlEncrypted;
+      return;
+    }
     validate(header);
     const h = header;
     this.firstDSiHashOffset = (h.digest_ntr_size / h.digest_sector_size) * 20;
@@ -167,9 +207,11 @@ export class TWL {
     }
   }
   importArm9iData(data: Buffer | string, offset = 0, size?: number): void {
+    if (this.complete) return this.complete.importArm9iData(data, offset, size);
     this.DSi9Data = this.importData(data, offset, size);
   }
   importArm7iData(data: Buffer | string, offset = 0, size?: number): void {
+    if (this.complete) return this.complete.importArm7iData(data, offset, size);
     this.DSi7Data = this.importData(data, offset, size);
   }
   private importData(data: Buffer | string, offset: number, size?: number): Buffer {
@@ -181,6 +223,7 @@ export class TWL {
     return out;
   }
   updateOverlays9Sha1Hmac(arm9Data: Buffer, header: Arm9Header, overlays: readonly Buffer[]): Buffer {
+    if (this.complete) return this.complete.updateOverlays9Sha1Hmac(arm9Data, header, overlays);
     if (overlays.length !== this.Overlays9Sha1Hmac.length)
       throw new Error("Changing ARM9 overlay count is unsupported");
     const hashes = overlays.map(hash);
@@ -203,6 +246,7 @@ export class TWL {
     return unpacked.compressed ? compressArm9(unpacked.data, header, arm9Data.length - hdrptr) : unpacked.data;
   }
   writeTo(writer: BinaryWriter, h: TwlHeader): Buffer {
+    if (this.complete) throw new Error("Complete DSi serialization requires NDSFile.toBuffer()");
     validate(h);
     // Fixed DSi regions cannot be shifted safely without rewriting the header.
     if (writer.position > h.sector_hashtable_start) {
@@ -266,32 +310,22 @@ export class TWL {
   }
 }
 
-/** Refresh the digest and keep valid RSA signatures; optional no$gba hash mask. */
+/** Refresh the master digest while preserving the cartridge signature. */
 export const updateHeaderSignatures = (
   writer: BinaryWriter,
   header: SignedTwlHeader,
   originalHeader: Buffer,
-  keepOriginal: boolean,
+  _keepOriginal = true,
 ): void => {
   const signedData = Buffer.from(slice(originalHeader, 0, 0xe00, "Signed header"));
   const digest = slice(header.hmac_digest_master, 0, 20, "Master digest");
   const signature = slice(header.rsa_signature, 0, 128, "RSA signature");
   digest.copy(signedData, 0x328);
-  const valid = verifyRsaSha1(signedData, signature);
+  verifyRsaSha1(signedData, signature);
   const position = writer.position;
   writer.position = 0x328;
   writer.write(digest);
-  if (!valid) {
-    if (!keepOriginal) {
-      const mask = Buffer.alloc(128, 0xff);
-      mask[0] = 0;
-      mask[1] = 1;
-      mask[107] = 0;
-      hashDigest("sha1", signedData).copy(mask, 108);
-      header.rsa_signature = mask;
-    }
-    writer.position = 0xf80;
-    writer.write(header.rsa_signature);
-  }
+  writer.position = 0xf80;
+  writer.write(signature);
   writer.position = position;
 };

package/src/nitro-helper.ts

@@ -6,9 +6,10 @@ export { FileAllocationTable, FileNameTable, OverlayTable } from "./nitro/filesy
 export type { FatEntry, NitroFile, NitroFolder, OverlayItem } from "./nitro/filesystem";
 export { BinaryWriter } from "./nitro/binary";
 export { crc16, crc32 } from "./nitro/crc";
-export { aes128CtrCrypt, encryptSecureArea, modcryptKey } from "./nitro/crypto";
+export { aes128CtrCrypt, decryptSecureArea, encryptSecureArea, modcryptKey } from "./nitro/crypto";
 export type { ModcryptHeader } from "./nitro/crypto";
 export { compressArm9, compressBLZ, decompressArm9, decompressBLZ } from "./nitro/blz";
 export type { Arm9Header } from "./nitro/blz";
 export { TWL, updateHeaderSignatures } from "./nitro/twl";
 export type { OverlayRange, SignedTwlHeader, TwlHeader } from "./nitro/twl";
+export type { DsiCheck, DsiVerification } from "./nitro/twl-complete";

package/src/nitro-patch-helper.ts

@@ -2,9 +2,11 @@
 import { hashDigest, readFile } from "#nitro-runtime";
 
 import { bytes } from "./nitro/binary";
+import { OverlayTable } from "./nitro/filesystem";
 import { NDSFile } from "./nitro/nds-file";
+import type { DsiVerification } from "./nitro/twl-complete";
 import { decodeXdelta } from "./patch/xdelta";
-import { extractZipEntry as extractEntry, readZip } from "./patch/zip";
+import { extractZipEntry as extractEntry, readZip, readZipEntries } from "./patch/zip";
 
 export const PatchReturnValue = Object.freeze({
   SUCCESS: "SUCCESS",
@@ -19,6 +21,7 @@ export interface PatchResult {
   /** MD5 of the original input, before preprocessing. */
   inputMd5: string;
   outputMd5: string;
+  dsi?: DsiVerification;
 }
 
 export interface PatchOptions {
@@ -33,6 +36,7 @@ export interface PatchOptions {
 }
 
 export interface PatchMetadata {
+  formatVersion?: number;
   id?: string;
   author?: string;
   name?: string;
@@ -77,6 +81,13 @@ const readMetadata = (files: Map<string, Buffer>): PatchMetadata | null => {
 
   const value = metadata as Record<string, unknown>;
   const result: PatchMetadata = {};
+  if (value.formatVersion !== undefined) {
+    const version = value.formatVersion;
+    if (typeof version !== "number" || !Number.isSafeInteger(version) || version < 1)
+      throw new Error("metadata.json formatVersion must be a positive safe integer");
+    if (version !== 1 && version !== 2) throw new Error(`Unsupported XZP format version: ${version}`);
+    result.formatVersion = version;
+  }
   for (const field of ["id", "author", "name", "homepage", "version"] as const) {
     const fieldValue = value[field];
     if (fieldValue === undefined) continue;
@@ -146,10 +157,18 @@ export const readPatchInfoFile = async (patchPath: string, options: PatchOptions
 /** Apply an existing NitroPatcher ZIP package entirely in memory. */
 export const patchBuffer = (original: Uint8Array, patch: Uint8Array, options: PatchOptions = {}): PatchResult => {
   const input = bytes(original, "original ROM");
-  const patches = readZip(patch, options);
+  const entries = readZipEntries(patch, options);
+  const patches = new Map([...entries].map(([name, entry]) => [name, entry.data]));
+  const formatVersion = readMetadata(patches)?.formatVersion ?? 1;
   const inputMd5 = md5(input);
   const preprocessing = patches.get(`preprocessing/${inputMd5}.xdelta`);
-  const rom = new NDSFile(preprocessing ? decodeXdelta(input, preprocessing, options) : input, options);
+  const romOptions = { ...options, dsiMode: formatVersion === 2 ? ("complete" as const) : ("legacy" as const) };
+  const rom = new NDSFile(preprocessing ? decodeXdelta(input, preprocessing, options) : input, romOptions);
+  if (formatVersion === 2)
+    for (const name of ["arm9i.bin", "arm7i.bin"]) {
+      if ((patches.has(name) || patches.has(`xdelta/${name}`)) && !rom.hasFile(name))
+        throw new Error(`${name} requires a complete DSi-enhanced cartridge`);
+    }
   let matched = true;
   const md5File = patches.get("md5.txt");
   if (md5File) {
@@ -171,12 +190,54 @@ export const patchBuffer = (original: Uint8Array, patch: Uint8Array, options: Pa
     const replacement = delta ? decodeXdelta(rom.getFile(path), delta, options) : patches.get(normalized);
     if (replacement) rom.replaceFile(path, replacement);
   }
+  if (formatVersion === 2) {
+    for (const name of ["overarm9.bin", "overarm7.bin"])
+      if (!rom.hasFile(name)) {
+        const delta = patches.get(`xdelta/${name}`);
+        const replacement = delta ? decodeXdelta(Buffer.alloc(0), delta, options) : patches.get(name);
+        if (replacement) rom.replaceFile(name, replacement);
+      }
+    const candidates = new Map<string, { path: string; data: Buffer; delta: boolean }>();
+    for (const [name, entry] of entries) {
+      const delta = name.startsWith("xdelta/");
+      const target = delta ? name.slice(7) : name;
+      if ((!target.startsWith("data/") && !target.startsWith("overlay/")) || rom.hasFile(target)) continue;
+      if (!delta && entries.has(`xdelta/${target}`)) continue;
+      candidates.set(target, { path: delta ? entry.path.slice(7) : entry.path, data: entry.data, delta });
+    }
+    if (candidates.size && (patches.has("fnt.bin") || patches.has("xdelta/fnt.bin")))
+      throw new Error("Adding files conflicts with an fnt.bin replacement");
+    const overlayTables = new Map<string, OverlayTable>();
+    for (const name of ["overarm9.bin", "overarm7.bin"])
+      if (rom.hasFile(name)) {
+        const raw = rom.getFile(name);
+        overlayTables.set(name, new OverlayTable(raw, 0, raw.length, name === "overarm9.bin"));
+      }
+    const additions = [...candidates.values()].sort((a, b) => Buffer.compare(Buffer.from(a.path), Buffer.from(b.path)));
+    for (const entry of additions) {
+      const content = entry.delta ? decodeXdelta(Buffer.alloc(0), entry.data, options) : entry.data;
+      if (entry.path.toLowerCase().startsWith("overlay/")) {
+        const match = /^overlay\/overlay(7)?_(\d{4,})\.bin$/i.exec(entry.path);
+        const overlayId = match?.[2];
+        const arm9 = !match?.[1];
+        if (!overlayId || String(Number(overlayId)).padStart(4, "0") !== overlayId)
+          throw new Error(`Invalid overlay path: ${entry.path}`);
+        const name = arm9 ? "overarm9.bin" : "overarm7.bin";
+        const table = overlayTables.get(name);
+        if (!table) throw new Error(`New overlay requires ${name}: ${entry.path}`);
+        const metadata = table.entries.find((item) => item.overlayId === Number(overlayId));
+        if (!metadata) throw new Error(`New overlay is missing its table entry: ${entry.path}`);
+        rom.addOverlay(arm9, metadata, content);
+      } else rom.addFile(entry.path, content);
+    }
+  }
   const buffer = rom.toBuffer();
   return {
     buffer,
     returnValue: matched ? PatchReturnValue.SUCCESS : PatchReturnValue.MD5_MISMATCH,
     inputMd5,
     outputMd5: md5(buffer),
+    ...(formatVersion === 2 && rom.header.unitCode === 2 && { dsi: new NDSFile(buffer, romOptions).verifyDsi() }),
   };
 };
 

package/src/patch/zip.ts

@@ -8,6 +8,11 @@ export interface ZipOptions {
   maxEntries?: number;
 }
 
+export interface ZipEntry {
+  path: string;
+  data: Buffer;
+}
+
 const fail = (message: string): never => {
   throw new Error(`ZIP: ${message}`);
 };
@@ -64,7 +69,7 @@ function filename(raw: Buffer, flags: number, fields: Map<number, Buffer>): stri
  * ZIP64, encryption, split archives and other compression methods fail explicitly.
  * Format reference: https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT
  */
-export const readZip = (input: Uint8Array, options: ZipOptions = {}): Map<string, Buffer> => {
+export const readZipEntries = (input: Uint8Array, options: ZipOptions = {}): Map<string, ZipEntry> => {
   if (!(input instanceof Uint8Array)) throw new TypeError("ZIP input must be a Buffer or Uint8Array");
   const bytes = Buffer.from(input.buffer, input.byteOffset, input.byteLength);
   const maxSize = boundOption(options.maxUncompressedSize, 1024 * 1024 * 1024, "maxUncompressedSize");
@@ -96,7 +101,7 @@ export const readZip = (input: Uint8Array, options: ZipOptions = {}): Map<string
   checkRange(bytes, centralOffset, centralSize, eocd);
   if (centralOffset + centralSize !== eocd) fail("central directory size/offset mismatch");
   if (count > Math.floor(centralSize / 46)) fail("entry count exceeds central directory size");
-  const result = new Map<string, Buffer>();
+  const result = new Map<string, ZipEntry>();
   const ranges: { start: number; end: number }[] = [];
   let offset = centralOffset,
     totalSize = 0;
@@ -124,7 +129,8 @@ export const readZip = (input: Uint8Array, options: ZipOptions = {}): Map<string
     checkRange(bytes, offset + 46, nameLength + extraLength + commentLength, eocd);
     const rawName = bytes.subarray(offset + 46, offset + 46 + nameLength);
     const fields = extras(bytes.subarray(offset + 46 + nameLength, offset + 46 + nameLength + extraLength));
-    const name = filename(rawName, flags, fields).replaceAll("\\", "/").toLowerCase();
+    const path = filename(rawName, flags, fields).replaceAll("\\", "/");
+    const name = path.toLowerCase();
     offset += 46 + nameLength + extraLength + commentLength;
 
     checkRange(bytes, localOffset, 30, centralOffset);
@@ -177,7 +183,7 @@ export const readZip = (input: Uint8Array, options: ZipOptions = {}): Map<string
     }
     if (data.length !== size) fail(`uncompressed size mismatch for ${JSON.stringify(name)}`);
     if (crc32(data) !== checksum) fail(`CRC32 mismatch for ${JSON.stringify(name)}`);
-    if (name && !name.endsWith("/")) result.set(name, data);
+    if (name && !name.endsWith("/")) result.set(name, { path, data });
   }
   if (offset !== eocd) fail("central directory entry count/length mismatch");
   ranges.sort((a, b) => a.start - b.start);
@@ -186,6 +192,10 @@ export const readZip = (input: Uint8Array, options: ZipOptions = {}): Map<string
   return result;
 };
 
+/** Read file contents using normalized paths, with the final duplicate winning. */
+export const readZip = (input: Uint8Array, options: ZipOptions = {}): Map<string, Buffer> =>
+  new Map([...readZipEntries(input, options)].map(([name, entry]) => [name, entry.data]));
+
 /** Extract one file using the same normalized, case-insensitive paths as readZip. */
 export const extractZipEntry = (input: Uint8Array, entryName: string, options: ZipOptions = {}): Buffer => {
   if (typeof entryName !== "string" || !entryName) throw new TypeError("ZIP entry name must be a non-empty string");

package/src/runtime/browser.ts

@@ -2,6 +2,7 @@ import { ecb } from "#browser-aes";
 import { md5, sha1 } from "#browser-hashes";
 import { hmac } from "#browser-hmac";
 import { Inflate } from "fflate";
+export { verifyDsiSignature as verifyRsaSha1 } from "./rsa";
 
 export const hashDigest = (algorithm: "md5" | "sha1", data: Uint8Array): Buffer =>
   Buffer.from((algorithm === "md5" ? md5 : sha1)(data));
@@ -30,9 +31,8 @@ export const inflateRawSync = (data: Uint8Array, options: { maxOutputLength: num
 // These Node-only methods are not exposed by the browser public API. Keep a
 // clear error if a future internal call accidentally crosses that boundary.
 const nodeOnly = (): never => {
-  throw new Error("Filesystem and RSA APIs are only available in the Node entry");
+  throw new Error("Filesystem APIs are only available in the Node entry");
 };
 export const readFile = nodeOnly;
 export const writeFile = nodeOnly;
 export const readFileSync = nodeOnly;
-export const verifyRsaSha1 = nodeOnly;

package/src/runtime/node.ts

@@ -1,4 +1,5 @@
-import { createCipheriv, createHash, createHmac, createPublicKey, verify } from "node:crypto";
+import { createCipheriv, createHash, createHmac } from "node:crypto";
+export { verifyDsiSignature as verifyRsaSha1 } from "./rsa";
 export { readFile, writeFile } from "node:fs/promises";
 export { readFileSync } from "node:fs";
 export { inflateRawSync } from "node:zlib";
@@ -11,17 +12,3 @@ export const createAesBlockCipher = (key: Uint8Array): ((block: Uint8Array) => B
   cipher.setAutoPadding(false);
   return (block) => cipher.update(block);
 };
-export const verifyRsaSha1 = (data: Uint8Array, signature: Uint8Array): boolean => {
-  const key = createPublicKey({
-    key: {
-      kty: "RSA",
-      n: Buffer.from(
-        "956F790DF08BB85A76AAEFA27FE874758BED9EDF9E9A670CD818BEB9B2885203B3FA11AEAA186513B5D6BB85A384D0D0EFB366CBC6051AAA86827AB74311F59C9BFC6C7079D5F17BD0819F522056738C721F40CF2361932590A3C5DC94CFD17A8CBC954A918AA858F4D804BAF7D3C1C4D7B8F077012FA170260B2C049056F3A5",
-        "hex",
-      ).toString("base64url"),
-      e: "AQAB",
-    },
-    format: "jwk",
-  });
-  return verify("RSA-SHA1", data, key, signature);
-};

package/src/runtime/rsa.ts

@@ -0,0 +1,14 @@
+import forge from "node-forge";
+
+import { hashDigest } from "#nitro-runtime";
+
+const publicKey = forge.pki.rsa.setPublicKey(
+  new forge.jsbn.BigInteger(
+    "956F790DF08BB85A76AAEFA27FE874758BED9EDF9E9A670CD818BEB9B2885203B3FA11AEAA186513B5D6BB85A384D0D0EFB366CBC6051AAA86827AB74311F59C9BFC6C7079D5F17BD0819F522056738C721F40CF2361932590A3C5DC94CFD17A8CBC954A918AA858F4D804BAF7D3C1C4D7B8F077012FA170260B2C049056F3A5",
+    16,
+  ),
+  new forge.jsbn.BigInteger("10001", 16),
+);
+
+export const verifyDsiSignature = (data: Uint8Array, signature: Uint8Array): boolean =>
+  publicKey.verify(hashDigest("sha1", data).toString("latin1"), Buffer.from(signature).toString("latin1"), "NONE");