@push.rocks/smartlinuxrepo 0.0.0-stage → 1.0.0

package/ts/readers/tar.ts

@@ -0,0 +1,835 @@
+import { LinuxRepoError, limitExceeded, truncated } from '../shared/errors.js';
+import type { ILinuxPackageLimits } from '../shared/limits.js';
+import { concatBytes, LimitedReader, readExact, readUpTo, type IByteReader } from './bytes.js';
+import { decodeGoUtf8, decodeLatin1 } from './text.js';
+
+const BLOCK = 512;
+/** Type flags whose header size never has data (Go `isHeaderOnlyType`). */
+const HEADER_ONLY_TYPES = new Set(['1', '2', '3', '4', '5', '6']);
+const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
+const INT64_MIN = -(1n << 63n);
+const INT64_MAX = (1n << 63n) - 1n;
+/**
+ * Go `maxSpecialFileSize` (format.go:147-149): the most Go reads of one PAX
+ * header, GNU long name or long link, old GNU sparse map or PAX GNU 1.0
+ * sparse map, whatever `maxHeaderBytes` allows.
+ */
+const MAX_SPECIAL_FILE_SIZE = 1 << 20;
+
+export interface ITarEntry {
+  /**
+   * The final name: PAX `path`, else GNU long name, else USTAR prefix + name;
+   * a recognised PAX GNU sparse header's `GNU.sparse.name` wins. Bytes are
+   * decoded as Gitea's JSON stores a Go string (`decodeGoUtf8`). The name is
+   * reported as it stands: no normalisation of `./`, `..` or absolute paths.
+   */
+  name: string;
+  /** The link target; empty for `'g'`, as Go returns it. */
+  linkName: string;
+  /**
+   * The header's mode field as Go `archive/tar` parses it (octal or base-256;
+   * a field Go cannot parse fails the archive, as in Go); 0 for `'g'`, as Go
+   * returns it.
+   */
+  mode: bigint;
+  /**
+   * The type flag. Go's legacy `\0` becomes `'0'`, or `'5'` when the name ends
+   * with `/`. `'g'` is a PAX global header, returned as an entry as Go does.
+   */
+  typeflag: string;
+  /**
+   * Data bytes readable through `body` (0 for header-only types and `'g'`);
+   * for a sparse entry, the real size Go reports, any non-negative int64.
+   * Stored data above `Number.MAX_SAFE_INTEGER` bytes is refused.
+   */
+  size: bigint;
+  /**
+   * An old GNU (`'S'`) or PAX GNU 0.0, 0.1 or 1.0 sparse entry whose map Go
+   * accepts. The codec does not expand holes: reading its data (through
+   * `body` or `readTarEntryData`) is refused with `unsupported-package-format`,
+   * a known difference from Gitea; skipping it works.
+   */
+  sparse: boolean;
+  body: LimitedReader;
+}
+
+export interface ITarReaderOptions {
+  /** Entries returned per archive. */
+  maxEntries: number;
+  /**
+   * One header chain: header blocks, PAX records, GNU long names and old GNU
+   * sparse extension blocks. A PAX GNU 1.0 map, which heads the entry's data,
+   * is bounded by Go's 1 MiB cap only.
+   */
+  maxHeaderBytes: number;
+}
+
+interface IHeaderBlock {
+  name: string;
+  linkName: string;
+  mode: bigint;
+  typeflag: string;
+  size: bigint;
+  format: TTarFormat;
+}
+
+/** Go `getFormat`'s header formats (format.go:178-201); PAX headers are `'ustar'`. */
+type TTarFormat = 'v7' | 'ustar' | 'star' | 'gnu';
+
+/**
+ * A bounded ustar reader following Go `archive/tar` (Gitea's reader):
+ * USTAR, PAX (`x`, `g`), GNU long names (`L`, `K`), STAR prefixes, Go's
+ * pre-1.8 GNU prefix fallback, base-256 numbers and signed or unsigned
+ * checksums. A header Go refuses for an unparseable numeric field is refused. The archive ends at two zero
+ * blocks, at a clean end of input on a header boundary (apk segments have no
+ * end marker), or when the input ends inside the padding after an entry.
+ * Sparse maps (old GNU, PAX GNU 0.0, 0.1 and 1.0) are read and validated as
+ * Go does; the holes are not expanded, so a sparse entry's data can only be
+ * skipped.
+ */
+export class TarReader {
+  private done = false;
+  private current: LimitedReader | null = null;
+  private pad = 0;
+  private entries = 0;
+
+  constructor(
+    private readonly input: IByteReader,
+    private readonly options: ITarReaderOptions,
+  ) {}
+
+  public async next(): Promise<ITarEntry | null> {
+    if (this.done) {
+      return null;
+    }
+    if (this.current !== null) {
+      await this.current.skipRest();
+      this.current = null;
+    }
+    if (!(await this.consumePadding())) {
+      return this.finish();
+    }
+
+    let chainBytes = 0;
+    let paxRecords: Map<string, string> | null = null;
+    let gnuLongName: string | null = null;
+    let gnuLongLink: string | null = null;
+    const addChain = (bytesArg: number) => {
+      chainBytes += bytesArg;
+      if (chainBytes > this.options.maxHeaderBytes) {
+        throw limitExceeded('maxHeaderBytes', this.options.maxHeaderBytes, 'tar header chain');
+      }
+    };
+
+    for (;;) {
+      const block = await readUpTo(this.input, BLOCK);
+      if (block.length === 0) {
+        return this.finish();
+      }
+      if (block.length < BLOCK) {
+        throw truncated('tar header');
+      }
+      if (isZeroBlock(block)) {
+        const second = await readUpTo(this.input, BLOCK);
+        if (second.length === 0) {
+          return this.finish();
+        }
+        if (second.length < BLOCK) {
+          throw truncated('tar end-of-archive marker');
+        }
+        if (isZeroBlock(second)) {
+          return this.finish();
+        }
+        throw malformed('a zero block is followed by a non-zero block');
+      }
+      addChain(BLOCK);
+      const header = parseHeaderBlock(block);
+
+      if (header.typeflag === 'x' || header.typeflag === 'g') {
+        const size = specialFileSize(header, 'PAX header');
+        addChain(size);
+        const data = await readExact(this.input, size, 'tar PAX header');
+        this.pad = padding(size);
+        const records = parsePax(data);
+        if (header.typeflag === 'g') {
+          this.countEntry();
+          this.current = new LimitedReader(this.input, 0, 'tar entry data');
+          // Go returns a global header's name, type flag and records only, and
+          // ignores mergePAX's error for it (reader.go:107-116); after a failing
+          // record Go's name depends on map order, the codec takes `path`
+          const name = records.get('path') || header.name;
+          return { name, linkName: '', mode: 0n, typeflag: 'g', size: 0n, sparse: false, body: this.current };
+        }
+        paxRecords = records;
+        if (!(await this.consumePadding())) {
+          return this.finish();
+        }
+        continue;
+      }
+
+      if (header.typeflag === 'L' || header.typeflag === 'K') {
+        const size = specialFileSize(header, 'GNU long name or link');
+        addChain(size);
+        const data = await readExact(this.input, size, 'tar GNU long name');
+        this.pad = padding(size);
+        const value = decodeGoUtf8(cutAtNul(data));
+        if (header.typeflag === 'L') {
+          gnuLongName = value;
+        } else {
+          gnuLongLink = value;
+        }
+        if (!(await this.consumePadding())) {
+          return this.finish();
+        }
+        continue;
+      }
+
+      // a real entry: Go mergePAX (reader.go:261-305), then the GNU long names
+      let name = header.name;
+      let linkName = header.linkName;
+      let size = header.size;
+      if (paxRecords !== null) {
+        checkPaxNumbers(paxRecords);
+        const path = paxRecords.get('path');
+        if (path) {
+          name = path;
+        }
+        const linkPath = paxRecords.get('linkpath');
+        if (linkPath) {
+          linkName = linkPath;
+        }
+        const paxSize = paxRecords.get('size');
+        if (paxSize) {
+          size = parsePaxInt(paxSize, 'size');
+        }
+      }
+      if (gnuLongName !== null && gnuLongName !== '') {
+        name = gnuLongName;
+      }
+      if (gnuLongLink !== null && gnuLongLink !== '') {
+        linkName = gnuLongLink;
+      }
+      let typeflag = header.typeflag;
+      if (typeflag === '\0') {
+        typeflag = name.endsWith('/') ? '5' : '0';
+      }
+      const dataSize = HEADER_ONLY_TYPES.has(typeflag) ? 0n : size;
+      if (dataSize < 0n) {
+        throw malformed('negative entry size');
+      }
+      if (dataSize > MAX_SAFE) {
+        throw malformed('entry size is out of range');
+      }
+      const length = Number(dataSize);
+      let body = new LimitedReader(this.input, length, 'tar entry data');
+      // Go handleSparseFile (reader.go:195-214): the reported size becomes the real size
+      let reportedSize = dataSize;
+      let sparse = false;
+      if (typeflag === 'S') {
+        reportedSize = await this.readOldGnuSparseMap(block, header.format, addChain);
+        sparse = true;
+      } else if (paxRecords !== null) {
+        const version = gnuSparseVersion(paxRecords);
+        if (version !== null) {
+          // Go readGNUSparsePAXHeaders (reader.go:220-259)
+          const sparseName = paxRecords.get('GNU.sparse.name') ?? '';
+          if (sparseName !== '') {
+            name = sparseName;
+          }
+          const realSizeText = paxRecords.get('GNU.sparse.size') || paxRecords.get('GNU.sparse.realsize') || '';
+          const realSize = realSizeText === '' ? size : parsePaxInt(realSizeText, 'GNU sparse size');
+          const check = new SparseMapCheck(realSize);
+          if (version === '1.0') {
+            await checkGnuSparseMap1x0(body, check);
+          } else {
+            checkGnuSparseMap0x1(paxRecords, check);
+          }
+          if (HEADER_ONLY_TYPES.has(typeflag) || !check.valid) {
+            throw malformed('invalid sparse map');
+          }
+          reportedSize = realSize;
+          sparse = true;
+        }
+      }
+      this.countEntry();
+      if (sparse) {
+        body = new SparseEntryBody(this.input, body.unreadBytes, name);
+      }
+      this.current = body;
+      this.pad = padding(length);
+      return { name, linkName, mode: header.mode, typeflag, size: reportedSize, sparse, body };
+    }
+  }
+
+  /**
+   * Go `readOldGNUSparseMap` (reader.go:478-525) and the map check of
+   * `handleSparseFile`; returns the real size. The map fills the header's
+   * sparse array and extension blocks; Go gives up once its arrays reach
+   * 1 MiB (`errSparseTooLong`), whatever `maxHeaderBytes` allows.
+   */
+  private async readOldGnuSparseMap(
+    blockArg: Uint8Array,
+    formatArg: TTarFormat,
+    addChainArg: (bytesArg: number) => void,
+  ): Promise<bigint> {
+    if (formatArg !== 'gnu') {
+      throw malformed('old GNU sparse entry outside the GNU format');
+    }
+    const realSize = parseNumeric(blockArg.subarray(483, 495), 'GNU sparse real size');
+    const check = new SparseMapCheck(realSize);
+    let array = blockArg.subarray(386, 483); // format.go:276
+    let totalSize = array.length;
+    while (totalSize < MAX_SPECIAL_FILE_SIZE) {
+      if (!checkOldGnuSparseArray(array, check)) {
+        if (!check.valid) {
+          throw malformed('invalid sparse map');
+        }
+        return realSize;
+      }
+      addChainArg(BLOCK);
+      array = await readExact(this.input, BLOCK, 'tar sparse header'); // a whole block (format.go:173)
+      totalSize += array.length;
+    }
+    throw malformed('the old GNU sparse map is longer than 1 MiB');
+  }
+
+  private countEntry(): void {
+    this.entries += 1;
+    if (this.entries > this.options.maxEntries) {
+      throw limitExceeded('maxEntries', this.options.maxEntries, 'tar entry count');
+    }
+  }
+
+  /** Reads the pending padding; false when the input ended inside it (a clean end, as in Go). */
+  private async consumePadding(): Promise<boolean> {
+    if (this.pad === 0) {
+      return true;
+    }
+    const expected = this.pad;
+    this.pad = 0;
+    const bytes = await readUpTo(this.input, expected);
+    return bytes.length === expected;
+  }
+
+  private finish(): null {
+    this.done = true;
+    this.current = null;
+    return null;
+  }
+}
+
+/**
+ * The stored fragments of a sparse entry. The codec does not expand holes,
+ * so reading is refused; `skipRest`, and so `TarReader.next`, skips them.
+ */
+class SparseEntryBody extends LimitedReader {
+  constructor(
+    innerArg: IByteReader,
+    lengthArg: number,
+    private readonly entryName: string,
+  ) {
+    super(innerArg, lengthArg, 'tar entry data');
+  }
+
+  public override async read(): Promise<Uint8Array | null> {
+    throw sparseDataRefused(this.entryName);
+  }
+}
+
+/**
+ * Reads a whole entry's data into memory, refusing entries larger than
+ * `maxBytesArg` before reading them, and sparse entries at all.
+ */
+export async function readTarEntryData(
+  entryArg: ITarEntry,
+  maxBytesArg: number,
+  limitArg: keyof ILinuxPackageLimits,
+): Promise<Uint8Array> {
+  if (entryArg.sparse) {
+    throw sparseDataRefused(entryArg.name);
+  }
+  if (entryArg.size > BigInt(maxBytesArg)) {
+    throw limitExceeded(limitArg, maxBytesArg, `tar entry ${entryArg.name}`);
+  }
+  return readExact(entryArg.body, Number(entryArg.size), 'tar entry data');
+}
+
+/** Go `block.getFormat`'s magic detection (format.go:187-200); the checksum is checked first. */
+function headerFormat(blockArg: Uint8Array): TTarFormat {
+  const magic = decodeLatin1(blockArg.subarray(257, 263));
+  const version = decodeLatin1(blockArg.subarray(263, 265));
+  const trailer = decodeLatin1(blockArg.subarray(508, 512));
+  if (magic === 'ustar\0' && trailer === 'tar\0') {
+    return 'star';
+  }
+  if (magic === 'ustar\0') {
+    return 'ustar'; // USTAR or PAX
+  }
+  if (magic === 'ustar ' && version === ' \0') {
+    return 'gnu';
+  }
+  return 'v7';
+}
+
+/**
+ * Go `Reader.readHeader` (reader.go:356-468): every numeric field Go parses
+ * with its fatal parser fails the archive here too, although only size and
+ * mode are kept.
+ */
+function parseHeaderBlock(blockArg: Uint8Array): IHeaderBlock {
+  verifyChecksum(blockArg);
+  const format = headerFormat(blockArg);
+  // reader.go:385-389, all formats
+  const size = parseNumeric(blockArg.subarray(124, 136), 'size');
+  const mode = parseNumeric(blockArg.subarray(100, 108), 'mode');
+  parseNumeric(blockArg.subarray(108, 116), 'uid');
+  parseNumeric(blockArg.subarray(116, 124), 'gid');
+  parseNumeric(blockArg.subarray(136, 148), 'mtime');
+  let prefix: Uint8Array = new Uint8Array(0);
+  if (format !== 'v7') {
+    // reader.go:392-397: above V7 only, so a V7 header may hold anything there
+    parseNumeric(blockArg.subarray(329, 337), 'devmajor');
+    parseNumeric(blockArg.subarray(337, 345), 'devminor');
+    if (format === 'ustar') {
+      prefix = cutAtNul(blockArg.subarray(345, 500)); // reader.go:401-404
+    } else if (format === 'star') {
+      // reader.go:417-421
+      prefix = cutAtNul(blockArg.subarray(345, 476));
+      parseNumeric(blockArg.subarray(476, 488), 'STAR atime');
+      parseNumeric(blockArg.subarray(488, 500), 'STAR ctime');
+    } else {
+      prefix = gnuLegacyPrefix(blockArg);
+    }
+  }
+  let name = decodeGoUtf8(cutAtNul(blockArg.subarray(0, 100)));
+  if (prefix.length > 0) {
+    name = `${decodeGoUtf8(prefix)}/${name}`; // reader.go:463-465
+  }
+  return {
+    name,
+    linkName: decodeGoUtf8(cutAtNul(blockArg.subarray(157, 257))),
+    mode,
+    typeflag: String.fromCharCode(blockArg[156]),
+    size,
+    format,
+  };
+}
+
+/**
+ * The old GNU format has no prefix field, but Go before 1.8 wrote one over
+ * atime and ctime. Go parses each of the two only when its first byte is not
+ * NUL, with a parser whose failure is not fatal; when either fails it takes
+ * bytes [345, 500) up to the first NUL as the prefix if they are ASCII
+ * (reader.go:422-461, `isASCII` strconv.go:21-28).
+ */
+function gnuLegacyPrefix(blockArg: Uint8Array): Uint8Array {
+  const parses = (fieldArg: Uint8Array) => fieldArg[0] === 0 || goNumeric(fieldArg) !== null;
+  if (parses(blockArg.subarray(345, 357)) && parses(blockArg.subarray(357, 369))) {
+    return new Uint8Array(0);
+  }
+  const prefix = cutAtNul(blockArg.subarray(345, 500));
+  return prefix.every((byteArg) => byteArg < 0x80) ? prefix : new Uint8Array(0);
+}
+
+/**
+ * Reads one old GNU sparse array (Go `sparseArray`, format.go:304-313):
+ * 24-byte entries, each a 12-byte offset and length, then the isExtended
+ * byte. As in Go `readOldGNUSparseMap` (reader.go:496-511), the entries up to
+ * the first whose offset starts with NUL must parse and go into the map
+ * check. Returns isExtended.
+ */
+function checkOldGnuSparseArray(arrayArg: Uint8Array, checkArg: SparseMapCheck): boolean {
+  const entries = Math.floor(arrayArg.length / 24);
+  for (let i = 0; i < entries; i++) {
+    const entry = arrayArg.subarray(i * 24, i * 24 + 24);
+    if (entry[0] === 0) {
+      break;
+    }
+    const offset = parseNumeric(entry.subarray(0, 12), 'GNU sparse offset');
+    const length = parseNumeric(entry.subarray(12, 24), 'GNU sparse length');
+    checkArg.add(offset, length);
+  }
+  return arrayArg[entries * 24] !== 0;
+}
+
+/**
+ * Go `validateSparseEntries` (common.go:255-278), fed one map entry at a
+ * time: no negative offset or length, no int64 overflow, no fragment past the
+ * real size, fragments in order without overlap; a negative real size fails
+ * even an empty map. Go checks the map once it has parsed all of it
+ * (reader.go:206-209), so callers read `valid` after the last entry. Go's
+ * `maxSparseFileEntries` (reader.go:643-648) is not ported: the 1 MiB caps
+ * keep every map below it.
+ */
+class SparseMapCheck {
+  private previousEnd = 0n;
+  private ok: boolean;
+
+  constructor(private readonly size: bigint) {
+    this.ok = size >= 0n;
+  }
+
+  public get valid(): boolean {
+    return this.ok;
+  }
+
+  public add(offsetArg: bigint, lengthArg: bigint): void {
+    if (!this.ok) {
+      return;
+    }
+    const end = offsetArg + lengthArg;
+    if (offsetArg < 0n || lengthArg < 0n || end > INT64_MAX || end > this.size || this.previousEnd > offsetArg) {
+      this.ok = false;
+      return;
+    }
+    this.previousEnd = end;
+  }
+}
+
+/**
+ * Go `readGNUSparsePAXHeaders`' version detection (reader.go:221-235): 0.0
+ * and 0.1 keep their map in PAX records, 1.0 at the start of the data; null
+ * when the records describe no PAX GNU sparse file.
+ */
+function gnuSparseVersion(recordsArg: Map<string, string>): '0.x' | '1.0' | null {
+  const major = recordsArg.get('GNU.sparse.major') ?? '';
+  const minor = recordsArg.get('GNU.sparse.minor') ?? '';
+  if (major === '0' && (minor === '0' || minor === '1')) {
+    return '0.x';
+  }
+  if (major === '1' && minor === '0') {
+    return '1.0';
+  }
+  if (major !== '' || minor !== '') {
+    return null; // an unknown version
+  }
+  return (recordsArg.get('GNU.sparse.map') ?? '') !== '' ? '0.x' : null;
+}
+
+/**
+ * Go `readGNUSparseMap0x1` (reader.go:607-641): `GNU.sparse.numblocks`
+ * entries in `GNU.sparse.map` as comma-separated offset and length pairs
+ * (0.0 records arrive here already joined by `parsePax`).
+ */
+function checkGnuSparseMap0x1(recordsArg: Map<string, string>, checkArg: SparseMapCheck): void {
+  const count = sparseEntryCount(recordsArg.get('GNU.sparse.numblocks') ?? '');
+  const map = recordsArg.get('GNU.sparse.map') ?? '';
+  const fields = map === '' ? [] : map.split(',');
+  if (BigInt(fields.length) !== 2n * count) {
+    throw malformed('the sparse map does not hold GNU.sparse.numblocks entries');
+  }
+  for (let i = 0; i < fields.length; i += 2) {
+    const offset = goParseInt(fields[i]);
+    const length = goParseInt(fields[i + 1]);
+    if (offset === null || length === null) {
+      throw malformed('a sparse map entry is not a decimal integer');
+    }
+    checkArg.add(offset, length);
+  }
+}
+
+/**
+ * Go `readGNUSparseMap1x0` (reader.go:537-603): the map heads the entry's
+ * data as newline-terminated decimals, the entry count and then offset and
+ * length pairs. Go reads whole blocks until it holds the newlines it needs,
+ * at most 1 MiB of them (`errSparseTooLong`); the data after the last of
+ * those blocks is the stored fragments.
+ */
+async function checkGnuSparseMap1x0(dataArg: LimitedReader, checkArg: SparseMapCheck): Promise<void> {
+  let buffer: Uint8Array = new Uint8Array(0);
+  let cursor = 0;
+  let newlines = 0;
+  let totalSize = 0;
+  const feedTokens = async (countArg: bigint) => {
+    const chunks = [buffer.subarray(cursor)];
+    while (BigInt(newlines) < countArg) {
+      totalSize += BLOCK;
+      if (totalSize > MAX_SPECIAL_FILE_SIZE) {
+        throw malformed('the PAX GNU sparse map is longer than 1 MiB');
+      }
+      const block = await readUpTo(dataArg, BLOCK);
+      if (block.length < BLOCK) {
+        throw malformed('the PAX GNU sparse map runs past the entry data');
+      }
+      chunks.push(block);
+      for (const byte of block) {
+        if (byte === 0x0a) {
+          newlines++;
+        }
+      }
+    }
+    buffer = concatBytes(chunks);
+    cursor = 0;
+  };
+  const nextToken = (): string => {
+    newlines--;
+    const end = buffer.indexOf(0x0a, cursor);
+    const token = decodeLatin1(buffer.subarray(cursor, end));
+    cursor = end + 1;
+    return token;
+  };
+  await feedTokens(1n);
+  const count = sparseEntryCount(nextToken());
+  await feedTokens(2n * count);
+  for (let i = 0n; i < count; i++) {
+    const offset = goParseInt(nextToken());
+    const length = goParseInt(nextToken());
+    if (offset === null || length === null) {
+      throw malformed('a sparse map entry is not a decimal integer');
+    }
+    checkArg.add(offset, length);
+  }
+}
+
+/** A sparse map's entry count as Go checks it (reader.go:579-582, :611-614). */
+function sparseEntryCount(textArg: string): bigint {
+  const count = goParseInt(textArg);
+  if (count === null || count < 0n || 2n * count > INT64_MAX) {
+    throw malformed('invalid sparse map entry count');
+  }
+  return count;
+}
+
+function verifyChecksum(blockArg: Uint8Array): void {
+  const stored = goOctal(blockArg.subarray(148, 156));
+  if (stored === null) {
+    throw malformed('checksum field is not octal');
+  }
+  let unsigned = 0;
+  let signed = 0;
+  for (let i = 0; i < BLOCK; i++) {
+    const byte = i >= 148 && i < 156 ? 0x20 : blockArg[i];
+    unsigned += byte;
+    signed += byte >= 0x80 ? byte - 0x100 : byte;
+  }
+  if (stored !== BigInt(unsigned) && stored !== BigInt(signed)) {
+    throw malformed('header checksum mismatch');
+  }
+}
+
+/** Go `parser.parseNumeric` (strconv.go:96-135), failing the archive where Go sets its error. */
+function parseNumeric(fieldArg: Uint8Array, whatArg: string): bigint {
+  const value = goNumeric(fieldArg);
+  if (value === null) {
+    throw malformed(`${whatArg} field is not a valid tar number`);
+  }
+  return value;
+}
+
+/**
+ * Go `parser.parseNumeric` (strconv.go:96-135): base-256 when the high bit is
+ * set, else octal; null where Go sets the parser's error.
+ */
+function goNumeric(fieldArg: Uint8Array): bigint | null {
+  if (fieldArg.length > 0 && (fieldArg[0] & 0x80) !== 0) {
+    const inverse = (fieldArg[0] & 0x40) !== 0 ? 0xff : 0x00;
+    let value = 0n;
+    for (let i = 0; i < fieldArg.length; i++) {
+      let byte = fieldArg[i] ^ inverse;
+      if (i === 0) {
+        byte &= 0x7f;
+      }
+      if (value >> 56n > 0n) {
+        return null;
+      }
+      value = (value << 8n) | BigInt(byte);
+    }
+    if (value >> 63n > 0n) {
+      return null;
+    }
+    return inverse === 0xff ? -value - 1n : value;
+  }
+  return goOctal(fieldArg);
+}
+
+/**
+ * Go `parser.parseOctal` (strconv.go:158-174): trims spaces and NULs, cuts at
+ * a NUL, parses base 8 into 64 bits; null where Go sets the parser's error.
+ */
+function goOctal(fieldArg: Uint8Array): bigint | null {
+  let start = 0;
+  let end = fieldArg.length;
+  while (start < end && (fieldArg[start] === 0x20 || fieldArg[start] === 0x00)) {
+    start++;
+  }
+  while (end > start && (fieldArg[end - 1] === 0x20 || fieldArg[end - 1] === 0x00)) {
+    end--;
+  }
+  const text = decodeLatin1(cutAtNul(fieldArg.subarray(start, end)));
+  if (text.length === 0) {
+    return 0n;
+  }
+  if (!/^[0-7]+$/.test(text)) {
+    return null;
+  }
+  const value = BigInt(`0o${text}`);
+  return value >> 64n > 0n ? null : value;
+}
+
+/**
+ * Go `strconv.ParseInt(s, 10, 64)`: an optional sign, decimal digits, int64
+ * range; null where Go fails.
+ */
+function goParseInt(textArg: string): bigint | null {
+  if (!/^[+-]?[0-9]+$/.test(textArg)) {
+    return null;
+  }
+  const digits = textArg.replace(/^[+-]/, '').replace(/^0+/, '');
+  if (digits.length > 19) {
+    return null;
+  }
+  const value = BigInt(textArg);
+  return value < INT64_MIN || value > INT64_MAX ? null : value;
+}
+
+/** A PAX integer record Go parses with `strconv.ParseInt`, failing the header where Go does. */
+function parsePaxInt(textArg: string, keyArg: string): bigint {
+  const value = goParseInt(textArg);
+  if (value === null) {
+    throw malformedPax(`${keyArg} is not a decimal integer`);
+  }
+  return value;
+}
+
+/**
+ * Go `mergePAX` (reader.go:261-305) for the records the codec does not keep:
+ * a uid, gid, atime, mtime or ctime Go cannot parse fails the header; an
+ * empty value keeps the USTAR field, as in Go.
+ */
+function checkPaxNumbers(recordsArg: Map<string, string>): void {
+  for (const key of ['uid', 'gid']) {
+    const value = recordsArg.get(key) ?? '';
+    if (value !== '') {
+      parsePaxInt(value, key);
+    }
+  }
+  for (const key of ['atime', 'mtime', 'ctime']) {
+    const value = recordsArg.get(key) ?? '';
+    if (value !== '' && !isGoPaxTime(value)) {
+      throw malformedPax(`${key} is not a PAX time`);
+    }
+  }
+}
+
+/**
+ * Go `parsePAXTime` (strconv.go:197-231): seconds as `strconv.ParseInt`,
+ * then optionally a dot and any number of digits.
+ */
+function isGoPaxTime(textArg: string): boolean {
+  const dot = textArg.indexOf('.');
+  const seconds = dot < 0 ? textArg : textArg.slice(0, dot);
+  const fraction = dot < 0 ? '' : textArg.slice(dot + 1);
+  return goParseInt(seconds) !== null && /^[0-9]*$/.test(fraction);
+}
+
+/**
+ * Go `parsePAX` / `parsePAXRecord` (reader.go:307-346, strconv.go:251-287):
+ * `"<length> <key>=<value>\n"` records; a later `x` header replaces the
+ * earlier records. NUL is refused in `path`, `linkpath`, `uname` and `gname`
+ * values and in every key. GNU sparse 0.0 offset and size records must
+ * alternate, offset first, without commas; Go joins them into
+ * `GNU.sparse.map`, replacing a `GNU.sparse.map` record.
+ */
+function parsePax(dataArg: Uint8Array): Map<string, string> {
+  const records = new Map<string, string>();
+  const sparseMap: string[] = [];
+  let offset = 0;
+  while (offset < dataArg.length) {
+    const rest = dataArg.subarray(offset);
+    const space = rest.indexOf(0x20);
+    if (space < 0) {
+      throw malformedPax('a record has no length');
+    }
+    const lengthText = decodeLatin1(rest.subarray(0, space));
+    if (!/^[+-]?[0-9]+$/.test(lengthText)) {
+      throw malformedPax('a record length is not a decimal integer');
+    }
+    const length = BigInt(lengthText);
+    if (length < 5n || length > BigInt(rest.length)) {
+      throw malformedPax('a record length is out of range');
+    }
+    const recordLength = Number(length);
+    if (recordLength <= space + 1) {
+      throw malformedPax('a record is shorter than its length field');
+    }
+    if (rest[recordLength - 1] !== 0x0a) {
+      throw malformedPax('a record does not end with a newline');
+    }
+    const record = rest.subarray(space + 1, recordLength - 1);
+    const equals = record.indexOf(0x3d);
+    if (equals < 0) {
+      throw malformedPax('a record has no "="');
+    }
+    const keyBytes = record.subarray(0, equals);
+    const valueBytes = record.subarray(equals + 1);
+    if (keyBytes.length === 0 || keyBytes.includes(0)) {
+      throw malformedPax('a record key is empty or contains NUL');
+    }
+    const key = decodeGoUtf8(keyBytes);
+    if (['path', 'linkpath', 'uname', 'gname'].includes(key) && valueBytes.includes(0)) {
+      throw malformedPax(`the ${key} value contains NUL`);
+    }
+    const value = decodeGoUtf8(valueBytes);
+    if (key === 'GNU.sparse.offset' || key === 'GNU.sparse.numbytes') {
+      const expected = sparseMap.length % 2 === 0 ? 'GNU.sparse.offset' : 'GNU.sparse.numbytes';
+      if (key !== expected || value.includes(',')) {
+        throw malformedPax('GNU sparse 0.0 records are out of order or hold a comma');
+      }
+      sparseMap.push(value);
+    } else {
+      records.set(key, value);
+    }
+    offset += recordLength;
+  }
+  if (sparseMap.length > 0) {
+    records.set('GNU.sparse.map', sparseMap.join(','));
+  }
+  return records;
+}
+
+/**
+ * The data size of a PAX header or GNU long name or link. Go reads at most
+ * 1 MiB of it (`readSpecialFile`, reader.go:868-876, `ErrFieldTooLong`); the
+ * codec refuses a larger one from its declared size, before reading.
+ */
+function specialFileSize(headerArg: IHeaderBlock, whatArg: string): number {
+  if (headerArg.size < 0n) {
+    throw malformed('negative entry size');
+  }
+  if (headerArg.size > BigInt(MAX_SPECIAL_FILE_SIZE)) {
+    throw malformed(`${whatArg} is longer than 1 MiB`);
+  }
+  return Number(headerArg.size);
+}
+
+function padding(sizeArg: number): number {
+  return (BLOCK - (sizeArg % BLOCK)) % BLOCK;
+}
+
+function isZeroBlock(blockArg: Uint8Array): boolean {
+  for (let i = 0; i < blockArg.length; i++) {
+    if (blockArg[i] !== 0) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function cutAtNul(bytesArg: Uint8Array): Uint8Array {
+  const nul = bytesArg.indexOf(0);
+  return nul < 0 ? bytesArg : bytesArg.subarray(0, nul);
+}
+
+function malformed(messageArg: string): LinuxRepoError {
+  return new LinuxRepoError('malformed-archive', `tar: ${messageArg}`, { field: 'tar header' });
+}
+
+/** Reading a sparse entry's data: Go expands its holes, the codec does not (a known difference from Gitea). */
+function sparseDataRefused(nameArg: string): LinuxRepoError {
+  const message = `tar: the data of sparse entry ${nameArg} is not read (holes are not expanded)`;
+  return new LinuxRepoError('unsupported-package-format', message, { field: 'tar entry data' });
+}
+
+function malformedPax(messageArg: string): LinuxRepoError {
+  return new LinuxRepoError('malformed-archive', `tar PAX header: ${messageArg}`, { field: 'tar PAX header' });
+}