nitro-patcher 0.1.0

package/src/nitro/crypto.ts

@@ -0,0 +1,178 @@
+import { createAesBlockCipher } from '#nitro-runtime';
+
+export interface ModcryptHeader {
+  gameCode: string;
+  gameTitle: string;
+  twlInternalFlags: number;
+  appflags?: Buffer;
+  hmac_arm9i?: Buffer;
+}
+
+// KEY1 table carried forward from NitroHelper/Arm9Encryptor.cs (Dirbaio/ndstool).
+const KEY1 = Buffer.from(
+  '99D5205F5744F5B96E19A4D99E6A5A94D8AEF1EB4175E23A9382D03233EE31D5CC57619A3706A21B793972F555AEF6BE5F1B69FBE59DF1E9CE2CD9A15E3205E6' +
+    'FED3FECFD462040D8BF5ECB72B6079BB1295310D6E3FDA2B8884F0F13D127E254522F1BB24061A0611ADDF288B6481342BEB332999AAF2BD9C14959D9FF7F58C' +
+    '7297A1299DD15FCF664D071ADED34A4B85C9A7A31795053A3D490ABF0A898BA24A8249DD2790F10BE9EB1C6A83764505BA817061173F4BDEAECFAB3957F23A56' +
+    '4811AD8A40E1453FFA9B0254CAA693FBEF4DFE6FA3D8879C08BAD5486A8D2DFD6E15F874BDBE528B18228A9EFB7437071B366C4A19BA4262B97991107B676596' +
+    'FE0223E8EE998C773E5C86644D6D7886A54F65E21EB2DF5A0AD07E0814B071ACBDDB831CB9D7A162CDC6637C5269C3E6BF75CE12445D2104FAFBD33C381163D4' +
+    '958541494609F2084311DC1F76C0156D1F3C6370EA87806CC3BD638BC2372137DCEE09232E376A4D7390F75030AC1C92041023914FD207AA683E4F9AC964606A' +
+    'C81421F3D62241124424CFE68A56DD0D534DE1851E8C525A9C1984C20357F16FE300BE58F64CEDD521649C1FBE55033C4ADCFFAAC9DAE05D5EBFE6DEF5D8B1F8' +
+    'FF36B3B9626795DB315F37ED4C70679990B518316C3D9999E442DAD3254213A0AED7706CB155CFC7D746D54361173D4428E93385D5D0A293AA25121FFBC50B46' +
+    'F597765645A6BE87B1946BE8B1FE3399AE1F3E6C39711D09009037E4103E7574FF8C833BB0F1B0F90105474295F1D6AC7E38E69E9574263FB4685018D04330B4' +
+    '4C4BE368BFE54DB6958B0AA074253277CFA1F72CD871135AABEAC951E80DEEEFE9937E19A71E433881162CA148E373CC29216CD35DCEA0D9617143A01513B564' +
+    '92CF2A19DCADB7A59F8665F81A9FE7FBF7FDB8136C27DB6FDF351CF78D2C5B9B12AB386406CCDE31E84E751164E3FAEAEB3454C2AD3F34EB932C7D26369D56F3' +
+    '5AE1F6B398634A9E3283E49A84607D902E130EEE934B36A285EC1638E8880602BFF0A03AEDD76A9A73E157CFF844B8DC2E2359D1DF9552719961A04BD57F6E78' +
+    'BAA9C530D34086329D320C9C37B7022FBA5498A9C41304C98DBEC8E75D97502E93D622590C27BC2292E0A7200F936F7F4C9FD3B5A62A0B7467497D1026CBD1C5' +
+    '8671E78CA09CE95BB21AF601EE8C9E5E83F21ADBE6E5EA845976D27CF68DA5493648C21652BB83A374B9070C3BFF6128E161E9E4EF6E15AA4EBAE85D0596BB32' +
+    '56B0FB72520F0EC84225657689AFF2DE1027F0014B74A79707D5265454091F820A867D30390EB3269B0B57BB360631AFFD79FCD930102B0CB3E19BD77BDC5FEF' +
+    'D2F813454D4775BD46963C7E75F33EB567C59A3BB05B296BDE805BC81505B131B6CE49DDAD84B5AE60DC67313430FE4EBD802FA6BF63392186D9357F16682205' +
+    '54E990268C076C51A43155D70907A83E2E5366C1F8F27BC4F258CFF187C5A2E7278F308758A064622318B9887CFACEC498AEAD17CC4A5BF3E948D556D30DF2C8' +
+    '92738CDBD72F56AC81F992694DC632F6E6C08D21E276806111BCDC6C93AF19699BD0BFB9319F0267A351EE8306227B0CAB494240B8D5017DCE5EF7555339C599' +
+    '46D8879FBAF764B4E39AFAA16D90681030CA8A54A79F60C319F56B0D7A5198E6984351B4D635E94FC3DF0F7BD62F5CBD3A156119F14BCBAADC6D64C9D3C61E56' +
+    'EF384C50718675CC0D0D4EE928F6065D701BAAD345CFA839AC95A62EB4E422D474A8375F487A04CCA54C40D828B428080D1C725241F07D47193A534E5884626B' +
+    '93B58A81214E0DDCB43FA2C6FCC92B40DA3804E95E5A866B0C22258568118D7C921D95554DAB8EBBDAA6E6B751B6325A0541DD052A0A5650911747CCC9E67EB5' +
+    '614ADB736751C833F5DA6E742E54C3370D6DAF08E8158A5FE25921CDA8DE0C065A776B5FDB18653EC850DE78E0B882B35D4E7232074FC13423BA96B7674EA428' +
+    '1E3462EB2D6A70E92F42C4704E5A319CF95B4728AADA716F381FB378C4926B1C9EF6359AB74D0EBFCC1829410348355D55D02BC629AF5C6074698E5E9B7CD4BD' +
+    '7B44647D3F925D69B61F004BD48335CF7E644E17AE8DD52E9A28124E2E2B49085CAEC64685AE41611E6F82D25137161F0BF659A49ACA5AAF0DD4338B2063F184' +
+    '805CCBCF08B4B9D31605BD6283319B5651989FBAB25BAAB2226B2CB5D448FA632B5F58FA61FA6409BB38E0B89D9260A80D676F0E37F50D019FC277D4FEECF173' +
+    '3039E07DF56198E42C2855045655DB2F6BECE55806B664806A2A1A4E5B0FD8C40A2E5219D962F53048BE8C7B4F389BA2C3AFC9D3C7C1624186B96121576F994F' +
+    'C1BACE7BB53B4D5E8A8B44575F135F706D5B2947DC38E2EC045565122AE81743E18EDD2AB3E294F7096E5CE6EB8AF86D89495448F52FADBFEA944BCAFC398782' +
+    '5F8A01F275F2E671D6D842DEF12D1D28A6887EA3A0471D30D9A371DF491CCB01F836B1F2F022585D456BBDA0BBB28842C78C28CE93E8906308907C893CF57DB7' +
+    '042D4F555116FD7E79E8BEC1F212D4F8B4840523A0CCD22BFDE1ABAD0DD1556C2341944D77374F05280CBF17B312676C8CC35AF741842A6DD09412272CB4ED9C' +
+    '4DEC478297D567B91B9DC055077EE58EE2A8E73E12E40E3A2A455534A2F92D5A1BAB527C83105F55D2F15A432BC6A7A4891595E8B44B9DF875E39F60785BD6E6' +
+    '0D44E62106BD472253A400AD8D43138539F7AAFC38AF7BEDFCE42B5450984CFC8580F7DF3C8022E194DADE24C6B07A3938DC0FA1A7F4F96F6318578B84412A2E' +
+    'D453F2D9000FD0DD996E19A60AD0EC5B5824ABC0CB0665EC1A1338940A67032F3FF7E377447733C61439D0E3C0A20879BB409957410B0190CDE1CC4867DBB3AF' +
+    '8874F34C828F72B1B52329C4126C19FC8E46A49CC4256587D36DBE8A93110338ED832BF346A493EA3B53851DCED4F1088327EDFC9B1A18BCF98BAEDC24AB5038' +
+    'E9724B1022177B465DAB5964F340AEF8BBE5C8F926034E557DEBEBFEF739E6E00A11BE2E28FF98EDC0C9425642C3FD00F6AF87A25B013F329247959A72A5323D' +
+    'AE6BD09B07D24992E3784AFAA1067DF241CF77740414B20C86846416D5BB51A1E56FF1D1F2E2F75F58204DB857C7CFDDC5D8BE763DF65F7EE72A8B88241B383F' +
+    '0E412377F5F04BD40C1FFAA40B805FCF45F6E0DA2F345953FB203C52625E35B562FE8B6063E3865A151A6ED14745BC32B4EB6738ABE46E333AB5EDA3AD67E04E' +
+    '4195EE626271261D31EF6230AFD782ACC2DC0504F59707BF11592307C06402E897E53EAF18AC59A68B4A33901C6E7C9C207E4C3C3E6164BBC56B7C7E3E9FC54C' +
+    '9FEA73F5D789C04CF4FBF42DEC141B51D5C112C810DF0B4A8B9CBC93456A3E3E7DC1A9BACDC1B407E4E1688643B26D38F3FB0C5C663771DE56EF6EA0104065A7' +
+    '98F7D0BE0EC83736EC10CA7C9CAB841E051776021C4F52AA5FC1C6A056B9D80484444DA759D8DE60E6380E058F03E13B6D8104336F300BCE69052133FB26BB89' +
+    '7DB6AE877E5107E0ACF7960A6BF9C45C1DE44447B85EFAE3788455424B485EF77D4735861D2B430503EC8AB81E063C760C481A43A7B78AED1E13C643EE10EFDB' +
+    'ECFB3C83B29544EFD854514E2D11441DFB36591E7A34C1C3CA570061EA67A5169B55D055E17FD936D24076AEDC01CEB07A83D5CB2098EC6BC1729234F3825737' +
+    '628A32360C9043AEAE5C9B788E136502FD6871C1FEB031A02482B0C3B17969A7F5D2EBD082C032DC9EC7263C6D8D98C1BB22D4D00F33EC3EB9CCE1DC6A4C7736' +
+    '141CF9BF819F285F71853229907548C4B34ACED8448F142FFD4057EFAA0875D946D1D66E32551FC318FE841FFC84D5FF715E1B48C386950E280827D33883717B' +
+    '4C8063549A56B0ACCF80CA3109EFFEF3BEAF247EA6FE533FC28D4A3368D122A666AD7BEADEB643B0A1259500A33F7546141144ECD795BC92F04FA91653629760' +
+    '2A0F41F17124BEEE947F08CD6093B3855B07003FD80F28839AD1699FD1DA2EC39001A2B96B4E2A669DDAAEA6EA2AD3682F0C0C9CD28C4AEDE29E57659D0987A3' +
+    'B4C4325DC9D4322BB1E0711E644DE69071E31E40ED7DF3840EEDC87876AEC0712772BB05EA0264FBF3486BB542933FED9F1353D2F7FE2AEC1D4725DB3C9186C6' +
+    '8EF011FD237436F7A4F59E7A7E535044D447CAD3EB386DE6D971947F4AC6694B11F452EA22FE8AB036678B59E8E6802AEB650413EEECDC9E5FB1EC056A59E69F' +
+    '5E596B89BFF71ACA44F95B6A718503E42962E0706F41C4CFB2B1CCE37EA607A887E77F8493DB524B6CEC7EDDD4244810699F046074E64818F3E42CB94F2E507A' +
+    'DFD454692B8BA7F3CEFF1FF33E26013917958489B0F04C4B82919FC44BAC9DA574AF1725C9CA32D3BC898A8489CC0DAE7CA2DB9C6A7891EEEA765D4E8760F569' +
+    '1567D402CFAF483607EABF6F662D068FC49AFEF9F6908775B8F7AD0F76105A3D59B02EB3C7352CCC70562BCBE33796C52F461B8A2246C788A726329861DF8622' +
+    '8AF41C2F87A109AACCA9AED3BD00451C9A5487865287EFFF1E8FA18FC1895C351BDA2D3A2C16B2C2F156E278C16B6397C5568FC9327F2CAAAFA6A8AC20912288' +
+    'DEE4608BF94B42251AE37F9C2C19893A7E05D436CC6958C2C1328B2F9085EB7A3950A5A12792C566B0204F587E5583432B45E29CE4D812902C168356167903B3' +
+    'AD2D61181A131F37E2E19C737B80D5FD2D5187FC7BAAD71F2C7A8EAFF48DBBCD95117C720BEE6FE2B9AFDE3783DE8C8D620567B796C68D56B60DD762BAD64636' +
+    'BD8EC8E6EA2A6C1014FF6B5BFA823C46B1304346518A7D9B923E83795B555DB26C5ECE90628E5398C90D6DE52D57CDC58157BAE1E8B88F72E54F13DCEA9D7115' +
+    '10B21188D509D47F5B657F2C3B384C1168508DFB9EB059BF9480894AC51A18128953D14A1029E88C1CECB6EA46C7178B251531A8A26B43B19DE2DB0B879BB011' +
+    '040E71D2297789820A66417F1D0B48FF72BB24FDC248A19BFE7B7FCE88DB86D9853B1CB0DCA83307BF512EE30E9A00971E06C097439DD8B645C486675F00F888' +
+    '9AA4529EC7AA8A8375ECC518AECEC32F1A2BF918FFAE1AF5530BB53351A7FDE8A8E1A264B622174380CC0AD8AE3BBA40D7D9924A89DF0410EE9B182B6A77698A' +
+    '68F4F9B9A221156EE61E3B0362309B60417E259B9E8FC5521008F8C269A1211188375E793566FF1042186EED97B66B1C4E36E56D7DB4E4BF20B9E0053A69D5B8' +
+    'E3D5DCE0B9AC533E07A457AD77FF4818762AAC492A8E47756D9F676330358C390539D56F643A5BADCA0BBB82529945B193363699AF13204436D8024409399285' +
+    'FF4A4A9787A663D7C7B5B524ED0FB46F0C585214D9A67BD379BC3858A1BD3B8406D81A06FD6BA8EA4B69280437AD8299FB0E1B85BDA85D73CDDC58750ABE636C' +
+    '48E74CE4302B0460B915D8DA8681758F96D48D1C5D70857C1C677BD50867A6CE4B0A6670B7E563D45B8A82EA1067CAE2F4EF17852F2A5F8A9782F86AD63410EA' +
+    'EBC95C3CE149F846EBDEBDF6A992F1AAA6A018B03AD30F1FF36FFF31454344D3509AF7880996C1CE76CCF22C2CBAAD82778F1884C0D2079C3690834E0BA54F43' +
+    '3E04AB784FD6FB09012490DA6F3C3A610D7F694AEB2B3002B4DBE084A9ECD735BF377D8558CEA94EE480C7A8D3306748EB29AF2F746AB4A73F0F3F92AFF3CAAC' +
+    'AF4BD994C043CA810D2F48A1B027D5D2EF4B0585A3DE4D93303CF0BB4A8F30274CEBE33E64ED9A2F3BF182F0BAF4CF7F40CBB0E17FBCAA57D3C974F2FA430D22' +
+    'D0F4774E93D785701F99BFB6DE35F130A75E71F06B012D7B64F033530A3988F36B3AA66B35D22F43CD02FDB5E9BC5BAAD8A4197E0E5D94819E6F77ADD60E7493' +
+    '96E7C4185FADF519',
+  'hex',
+);
+
+export const aes128CtrCrypt = (key: Buffer, counter: Buffer, data: Buffer): Buffer => {
+  if (key.length !== 16 || counter.length !== 16)
+    throw new RangeError('AES key and counter must have 16 bytes');
+  const ctr = Buffer.from(counter).reverse();
+  const aes = createAesBlockCipher(Buffer.from(key).reverse());
+  const output = Buffer.alloc(data.length);
+  for (let p = 0; p < data.length; p += 16) {
+    const mask = aes(ctr);
+    for (let j = 0; j < 16 && p + j < data.length; j++) output[p + j] = data[p + j] ^ mask[15 - j];
+    for (let j = 15; j >= 0; j--) {
+      ctr[j] = (ctr[j] + 1) & 255;
+      if (ctr[j]) break;
+    }
+  }
+  return output;
+};
+
+export const modcryptKey = (header: ModcryptHeader): Buffer => {
+  if (typeof header.gameCode !== 'string' || header.gameCode.length !== 4)
+    throw new Error('Expected four-character game code');
+  if (header.twlInternalFlags & 4 || (header.appflags?.[3] ?? 0) & 0x80) {
+    const key = Buffer.alloc(16);
+    key.write(header.gameTitle, 0, 12, 'ascii');
+    key.write(header.gameCode, 12, 4, 'ascii');
+    return key;
+  }
+  if (!header.hmac_arm9i || header.hmac_arm9i.length < 16)
+    throw new Error('Missing ARM9i HMAC for modcrypt key');
+  const x = Buffer.from(
+    'Nintendo' + header.gameCode + [...header.gameCode].reverse().join(''),
+    'ascii',
+  );
+  for (let i = 0; i < 16; i++) x[i] ^= header.hmac_arm9i[i];
+  const mask = (1n << 128n) - 1n;
+  let v = x.readBigUInt64LE(0) | (x.readBigUInt64LE(8) << 64n);
+  v = (v + 0xfffefb4e295902582a680f5f1a4f3e79n) & mask;
+  v = ((v << 42n) | (v >> 86n)) & mask;
+  const out = Buffer.alloc(16);
+  out.writeBigUInt64LE(v & ((1n << 64n) - 1n));
+  out.writeBigUInt64LE(v >> 64n, 8);
+  return out;
+};
+
+export const encryptSecureArea = (gameCode: string, input: Buffer): 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);
+  let magic = new Uint32Array(0x412);
+  let args: [number, number, number] = [0, 0, 0];
+  function encrypt(a: number, b: number): [number, number] {
+    for (let i = 0; i < 16; i++) {
+      const c = (magic[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];
+  }
+  function init2() {
+    [args[2], args[1]] = encrypt(args[2], args[1]);
+    [args[1], args[0]] = encrypt(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);
+      magic[i] = a;
+      magic[i + 1] = b;
+    }
+  }
+  function init1() {
+    magic = Uint32Array.from({ length: 0x412 }, (_, i) => KEY1.readUInt32LE(i * 4));
+    const code = Buffer.from(gameCode, 'ascii').readUInt32LE();
+    args = [code, code >>> 1, (code << 1) >>> 0];
+    init2();
+    init2();
+  }
+  init1();
+  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));
+    output.writeUInt32LE(a, p);
+    output.writeUInt32LE(b, p + 4);
+  }
+  let [b, a] = encrypt(0x6a624f79, 0x72636e65);
+  init1();
+  [b, a] = encrypt(b, a);
+  output.writeUInt32LE(a, 0);
+  output.writeUInt32LE(b, 4);
+  return output;
+};

package/src/nitro/filesystem.ts

@@ -0,0 +1,183 @@
+// Based on NitroHelper FNT/FAT/OverlayTable, GPL-3.0.
+import { bytes, range } from './binary';
+
+/** A file in the original ROM, optionally replaced with new bytes. */
+export interface NitroFile {
+  name: string;
+  id: number;
+  offset: number;
+  size: number;
+  replacement?: Buffer;
+}
+
+export interface NitroFolder {
+  name: string;
+  id: number;
+  files: NitroFile[];
+  folders: NitroFolder[];
+}
+
+export interface FatEntry {
+  id: number;
+  offset: number;
+  size: number;
+}
+
+export class FileAllocationTable {
+  readonly entries: FatEntry[];
+  readonly sortedIDs: number[];
+
+  constructor(input: Uint8Array, offset: number, size: number) {
+    const data = bytes(input);
+    const table = range(data, offset, size, 'FAT');
+    if (size % 8 || size / 8 > 65535) throw new Error('Invalid FAT entry count');
+    this.entries = [];
+    for (let p = 0; p < size; p += 8) {
+      const start = table.readUInt32LE(p),
+        end = table.readUInt32LE(p + 4);
+      range(data, start, end - start, `FAT entry ${p / 8}`);
+      this.entries.push({ id: p / 8, offset: start, size: end - start });
+    }
+    this.sortedIDs = [...this.entries]
+      .sort((a, b) => a.offset - b.offset || a.id - b.id)
+      .map((entry) => entry.id);
+  }
+}
+
+export class FileNameTable {
+  readonly root: NitroFolder;
+
+  constructor(fat: FileAllocationTable, input: Uint8Array, offset: number, size: number) {
+    const table = range(bytes(input), offset, size, 'FNT');
+    range(table, 0, 8, 'FNT root directory');
+    const count = table.readUInt16LE(6);
+    if (count < 1 || count > 4096) throw new Error('Invalid FNT directory count');
+    range(table, 0, count * 8, 'FNT directory table');
+    const decoder = new TextDecoder('shift_jis');
+    const visited = new Set<number>();
+    const fileIds = new Set<number>();
+    const parse = (index: number, name: string, depth: number): NitroFolder => {
+      if (depth > 256 || index >= count || visited.has(index))
+        throw new Error('Invalid FNT directory tree or cycle');
+      visited.add(index);
+      let cursor = table.readUInt32LE(index * 8);
+      let fileId = table.readUInt16LE(index * 8 + 4);
+      if (cursor < count * 8) throw new Error('FNT directory names overlap directory table');
+      const folder: NitroFolder = {
+        name,
+        id: index === 0 ? 0xffff : 0xf000 + index,
+        files: [],
+        folders: [],
+      };
+      const names = new Set<string>();
+      while (true) {
+        const tag = range(table, cursor++, 1, 'FNT name')[0];
+        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'));
+        cursor += length;
+        if (
+          filename.includes('/') ||
+          filename.includes('\\') ||
+          filename.includes('\0') ||
+          filename === '.' ||
+          filename === '..'
+        )
+          throw new Error('Invalid FNT path component');
+        const normalized = filename.toLowerCase();
+        if (names.has(normalized)) throw new Error(`Duplicate FNT path: ${filename}`);
+        names.add(normalized);
+        if (tag & 0x80) {
+          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));
+        } 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 });
+        }
+      }
+      return folder;
+    };
+    this.root = { name: 'root', id: 0xffff, files: [], folders: [parse(0, 'data', 0)] };
+  }
+
+  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) {
+      const file = FileNameTable.findFile(id, subfolder);
+      if (file) return file;
+    }
+    return undefined;
+  }
+}
+
+export interface OverlayItem {
+  overlayId: number;
+  ramAddress: number;
+  ramSize: number;
+  bssSize: number;
+  staticInitialiserStartAddress: number;
+  staticInitialiserEndAddress: number;
+  fileId: number;
+  reserved: number;
+}
+
+const overlayFields = [
+  'overlayId',
+  'ramAddress',
+  'ramSize',
+  'bssSize',
+  'staticInitialiserStartAddress',
+  'staticInitialiserEndAddress',
+  'fileId',
+  'reserved',
+] as const;
+
+export class OverlayTable {
+  readonly entries: OverlayItem[] = [];
+  constructor(
+    input: Uint8Array,
+    offset: number,
+    size: number,
+    readonly isArm9: boolean,
+  ) {
+    if (!size) return;
+    const table = range(bytes(input), offset, size, 'overlay table');
+    if (size % 32) throw new Error('Invalid overlay table size');
+    for (let p = 0; p < size; p += 32) {
+      if (table.readUInt32LE(p) === 0xffffffff) break;
+      this.entries.push({
+        overlayId: table.readUInt32LE(p),
+        ramAddress: table.readUInt32LE(p + 4),
+        ramSize: table.readUInt32LE(p + 8),
+        bssSize: table.readUInt32LE(p + 12),
+        staticInitialiserStartAddress: table.readUInt32LE(p + 16),
+        staticInitialiserEndAddress: table.readUInt32LE(p + 20),
+        fileId: table.readUInt32LE(p + 24),
+        reserved: table.readUInt32LE(p + 28),
+      });
+    }
+  }
+  readBasicOverlays(fat: FileAllocationTable): NitroFile[] {
+    return this.entries.map((item) => {
+      const file = fat.entries[item.fileId];
+      if (!file) throw new Error('Overlay file id is outside FAT');
+      return {
+        ...file,
+        name: `overlay${this.isArm9 ? '' : '7'}_${String(item.overlayId).padStart(4, '0')}.bin`,
+      };
+    });
+  }
+  toBuffer(): Buffer {
+    const data = Buffer.alloc(this.entries.length * 32);
+    this.entries.forEach((entry, i) =>
+      overlayFields.forEach((field, j) => data.writeUInt32LE(entry[field], i * 32 + j * 4)),
+    );
+    return data;
+  }
+}

package/src/nitro/header.ts

@@ -0,0 +1,254 @@
+// Port of NitroHelper/Header.cs. Copyright Xzonn and upstream contributors, GPL-3.0.
+import { bytes, range } from './binary';
+import { crc16 } from './crc';
+import { encryptSecureArea } from './crypto';
+
+export const UnitCode = Object.freeze({ NDS: 0, NDS_DSi: 2, DSi: 3 });
+
+export class Header {
+  raw: Buffer;
+  trimmedRom: boolean;
+  doublePadding: boolean;
+  nitrocode: boolean;
+  decrypted: boolean;
+  headerCRC: boolean;
+  logoCRC: boolean;
+  secureCRC: boolean;
+  dlp_signature: Buffer;
+  declare ARM9romOffset: number;
+  declare ARM9entryAddress: number;
+  declare ARM9ramAddress: number;
+  declare ARM9size: number;
+  declare ARM7romOffset: number;
+  declare ARM7entryAddress: number;
+  declare ARM7ramAddress: number;
+  declare ARM7size: number;
+  declare FNToffset: number;
+  declare FNTsize: number;
+  declare FAToffset: number;
+  declare FATsize: number;
+  declare ARM9overlayOffset: number;
+  declare ARM9overlaySize: number;
+  declare ARM7overlayOffset: number;
+  declare ARM7overlaySize: number;
+  declare flagsRead: number;
+  declare flagsInit: number;
+  declare bannerOffset: number;
+  declare dsi9_rom_offset: number;
+  declare offset_0x1C4: number;
+  declare dsi9_ram_address: number;
+  declare dsi9_size: number;
+  declare dsi7_rom_offset: number;
+  declare offset_0x1D4: number;
+  declare dsi7_ram_address: number;
+  declare dsi7_size: number;
+  declare digest_ntr_start: number;
+  declare digest_ntr_size: number;
+  declare digest_twl_start: number;
+  declare digest_twl_size: number;
+  declare sector_hashtable_start: number;
+  declare sector_hashtable_size: number;
+  declare block_hashtable_start: number;
+  declare block_hashtable_size: number;
+  declare digest_sector_size: number;
+  declare digest_block_sectorcount: number;
+  declare banner_size: number;
+  declare offset_0x20C: number;
+  declare total_rom_size: number;
+  declare offset_0x214: number;
+  declare offset_0x218: number;
+  declare offset_0x21C: number;
+  declare modcrypt1_start: number;
+  declare modcrypt1_size: number;
+  declare modcrypt2_start: number;
+  declare modcrypt2_size: number;
+  declare tid_low: number;
+  declare tid_high: number;
+  declare public_sav_size: number;
+  declare private_sav_size: number;
+  declare unitCode: number;
+  declare encryptionSeed: number;
+  declare twlInternalFlags: number;
+  declare permitsFlags: number;
+  declare ROMversion: number;
+  declare internalFlags: number;
+  declare secureCRC16: number;
+  declare ROMtimeout: number;
+  declare ARM9autoload: number;
+  declare ARM7autoload: number;
+  declare ROMsize: number;
+  declare headerSize: number;
+  declare logoCRC16: number;
+  declare headerCRC16: number;
+  declare debug_romOffset: number;
+  declare debug_size: number;
+  declare debug_ramAddress: number;
+  declare reserved3: number;
+  declare mbk9_wramcnt_setting: number;
+  declare region_flags: number;
+  declare access_control: number;
+  declare scfg_ext_mask: number;
+  declare gameTitle: string;
+  declare gameCode: string;
+  declare makerCode: string;
+  declare reserved: Buffer;
+  declare reserved2: Buffer;
+  declare logo: Buffer;
+  declare appflags: Buffer;
+  declare hmac_arm9: Buffer;
+  declare hmac_arm7: Buffer;
+  declare hmac_digest_master: Buffer;
+  declare hmac_icon_title: Buffer;
+  declare hmac_arm9i: Buffer;
+  declare hmac_arm7i: Buffer;
+  declare hmac_arm9_no_secure: Buffer;
+  declare rsa_signature: Buffer;
+  declare secureDisable: bigint;
+
+  constructor(input: Uint8Array) {
+    const data = bytes(input, 'header');
+    range(data, 0, 0x170, 'header');
+    const size = data.readUInt32LE(0x84);
+    if (size < 0x170 || size > data.length) throw new RangeError(`Invalid header size: ${size}`);
+    this.raw = Buffer.from(data.subarray(0, size));
+    if (this.unitCode & 2 && size > 0x200) range(this.raw, 0, 0x1000, 'DSi header');
+    this.trimmedRom = this.total_rom_size
+      ? this.total_rom_size >= data.length
+      : data.length !== this.size;
+    this.doublePadding =
+      (this.ARM9size % 0x400 < 0x200 &&
+        this.ARM7romOffset % 0x400 === 0 &&
+        this.ARM9overlayOffset % 0x400 === 0) ||
+      (this.ARM7size % 0x400 < 0x200 &&
+        this.FNToffset % 0x400 === 0 &&
+        this.ARM7overlayOffset % 0x400 === 0) ||
+      (this.FNTsize % 0x400 < 0x200 && this.FAToffset % 0x400 === 0) ||
+      (this.FATsize % 0x400 < 0x200 && this.bannerOffset % 0x400 === 0);
+    const nitroOffset = this.ARM9romOffset + this.ARM9size;
+    this.nitrocode =
+      nitroOffset >= size &&
+      nitroOffset + 4 <= data.length &&
+      data.readUInt32LE(nitroOffset) === 0xdec00621;
+    this.decrypted = data.length >= 0x4008 && data.readBigUInt64LE(0x4000) === 0xe7ffdeffe7ffdeffn;
+    this.headerCRC = crc16(this.raw.subarray(0, 0x15e)) === this.headerCRC16;
+    this.logoCRC = crc16(this.logo) === this.logoCRC16;
+    const secure = data.subarray(0x4000, 0x8000);
+    this.secureCRC =
+      secure.length > 0 &&
+      crc16(this.decrypted ? encryptSecureArea(this.gameCode, secure) : secure) ===
+        this.secureCRC16;
+    this.dlp_signature = Buffer.alloc(0);
+    if (
+      this.ROMsize >= size &&
+      this.ROMsize + 0x88 <= data.length &&
+      data.readUInt32LE(this.ROMsize) === 0x00016361
+    ) {
+      this.dlp_signature = Buffer.from(data.subarray(this.ROMsize, this.ROMsize + 0x88));
+    }
+  }
+
+  get size() {
+    return 2 ** (17 + this.raw[0x14]);
+  }
+  set size(value: number) {
+    const power = Math.log2(value);
+    if (!Number.isInteger(power) || power < 17 || power > 32)
+      throw new RangeError('ROM capacity must be a power of two from 128 KiB to 4 GiB');
+    this.raw[0x14] = power - 17;
+  }
+  toBuffer() {
+    const data = Buffer.from(this.raw);
+    data.writeUInt16LE(crc16(data.subarray(0xc0, 0x15c)), 0x15c);
+    data.writeUInt16LE(crc16(data.subarray(0, 0x15e)), 0x15e);
+    return data;
+  }
+  toString() {
+    return `NDS header: ${this.gameTitle.replace(/\0+$/, '')} (${this.gameCode})`;
+  }
+}
+
+function field(
+  name: string,
+  offset: number,
+  length: number,
+  type: 'buffer' | 'string' | 'number' = 'buffer',
+  dsi = false,
+) {
+  Object.defineProperty(Header.prototype, name, {
+    enumerable: true,
+    get(this: Header) {
+      if (dsi && (!(this.unitCode & 2) || this.raw.length <= 0x200))
+        return type === 'buffer' ? Buffer.alloc(length) : 0;
+      const data = range(this.raw, offset, length, `header ${name}`);
+      if (type === 'string') return data.toString('latin1');
+      if (type === 'buffer') return data;
+      return length === 8 ? data.readBigUInt64LE() : data.readUIntLE(0, length);
+    },
+    set(this: Header, value: string | number | bigint | Uint8Array) {
+      const target = range(this.raw, offset, length, `header ${name}`);
+      if (type === 'string') {
+        if (typeof value !== 'string' || Buffer.byteLength(value, 'latin1') > length)
+          throw new TypeError(`Invalid ${name}`);
+        target.fill(0);
+        target.write(value, 'latin1');
+      } else if (type === 'buffer') {
+        if (!(value instanceof Uint8Array)) throw new TypeError(`Invalid ${name}`);
+        const source = bytes(value, name);
+        if (source.length !== length) throw new RangeError(`${name} must contain ${length} bytes`);
+        source.copy(target);
+      } else if (length === 8) {
+        if (typeof value !== 'bigint') throw new TypeError(`Invalid ${name}`);
+        target.writeBigUInt64LE(value);
+      } else {
+        if (typeof value !== 'number') throw new TypeError(`Invalid ${name}`);
+        target.writeUIntLE(value, 0, length);
+      }
+    },
+  });
+}
+field('gameTitle', 0, 12, 'string');
+field('gameCode', 12, 4, 'string');
+field('makerCode', 16, 2, 'string');
+for (const [name, offset] of Object.entries({
+  unitCode: 0x12,
+  encryptionSeed: 0x13,
+  twlInternalFlags: 0x1c,
+  permitsFlags: 0x1d,
+  ROMversion: 0x1e,
+  internalFlags: 0x1f,
+}))
+  field(name, offset, 1, 'number');
+field('reserved', 0x15, 7);
+const ntr32 =
+  'ARM9romOffset ARM9entryAddress ARM9ramAddress ARM9size ARM7romOffset ARM7entryAddress ARM7ramAddress ARM7size FNToffset FNTsize FAToffset FATsize ARM9overlayOffset ARM9overlaySize ARM7overlayOffset ARM7overlaySize flagsRead flagsInit bannerOffset'.split(
+    ' ',
+  );
+ntr32.forEach((name, i) => field(name, 0x20 + i * 4, 4, 'number'));
+field('secureCRC16', 0x6c, 2, 'number');
+field('ROMtimeout', 0x6e, 2, 'number');
+field('ARM9autoload', 0x70, 4, 'number');
+field('ARM7autoload', 0x74, 4, 'number');
+field('secureDisable', 0x78, 8, 'number');
+field('ROMsize', 0x80, 4, 'number');
+field('headerSize', 0x84, 4, 'number');
+field('reserved2', 0x88, 56);
+field('logo', 0xc0, 156);
+field('logoCRC16', 0x15c, 2, 'number');
+field('headerCRC16', 0x15e, 2, 'number');
+'debug_romOffset debug_size debug_ramAddress reserved3'
+  .split(' ')
+  .forEach((name, i) => field(name, 0x160 + i * 4, 4, 'number'));
+field('appflags', 0x1bc, 4, 'buffer', true);
+'mbk9_wramcnt_setting region_flags access_control scfg_ext_mask'
+  .split(' ')
+  .forEach((name, i) => field(name, 0x1ac + i * 4, 4, 'number', true));
+const twl32 =
+  'dsi9_rom_offset offset_0x1C4 dsi9_ram_address dsi9_size dsi7_rom_offset offset_0x1D4 dsi7_ram_address dsi7_size digest_ntr_start digest_ntr_size digest_twl_start digest_twl_size sector_hashtable_start sector_hashtable_size block_hashtable_start block_hashtable_size digest_sector_size digest_block_sectorcount banner_size offset_0x20C total_rom_size offset_0x214 offset_0x218 offset_0x21C modcrypt1_start modcrypt1_size modcrypt2_start modcrypt2_size tid_low tid_high public_sav_size private_sav_size'.split(
+    ' ',
+  );
+twl32.forEach((name, i) => field(name, 0x1c0 + i * 4, 4, 'number', true));
+'hmac_arm9 hmac_arm7 hmac_digest_master hmac_icon_title hmac_arm9i hmac_arm7i'
+  .split(' ')
+  .forEach((name, i) => field(name, 0x300 + i * 20, 20, 'buffer', true));
+field('hmac_arm9_no_secure', 0x3a0, 20, 'buffer', true);
+field('rsa_signature', 0xf80, 0x80, 'buffer', true);