@push.rocks/smartlinuxrepo 0.0.0-stage → 0.1.0

package/ts/arch/builder.ts

@@ -0,0 +1,283 @@
+import * as plugins from '../plugins.js';
+import { isIndexableArchitecture } from '../shared/architecture.js';
+import { LinuxRepoError } from '../shared/errors.js';
+import type { IArchPackageRecord, ILinuxIndexFile } from '../shared/types.js';
+import { assertBytes, assertSegmentName, assertTimestamp, hasControlCharacter } from '../shared/validation.js';
+import { createDetachedBinarySignature } from '../signing/openpgpframing.js';
+import { singleChunk, type IOpenPgpSigner } from '../signing/signers.js';
+import { writeGoTar } from '../writers/gotar.js';
+import { ARCH_NAME_PATTERN, ARCH_VERSION_PATTERN } from './reader.js';
+import { compareArchVersions } from './vercmp.js';
+
+/** One package of an Arch repository index. */
+export interface IArchIndexEntry {
+  record: IArchPackageRecord;
+  /**
+   * The package's detached signature (the `.sig` file's bytes) as stored at
+   * upload time; written as `%PGPSIG%`. Without it the entry has no
+   * `%PGPSIG%` and pacman fetches `<file>.sig`. The builder never signs a package.
+   */
+  packageSignature?: Uint8Array;
+}
+
+/** Gitea's stored name of the index archive (`services/packages/arch/repository.go:37`). */
+const INDEX_ARCHIVE_NAME = 'packages.db';
+const ANY_ARCHITECTURE = 'any';
+/** `int64(os.ModePerm)` (`repository.go:393`). */
+const ENTRY_MODE = 0o777;
+
+/**
+ * Builds the Arch index files of one repository: for every architecture that
+ * has packages, the gzip tar `packages.db` and its detached signature, as
+ * Gitea 28.2.0 `buildPackagesIndex` builds them.
+ *
+ * - `any` packages also go into every other architecture's index.
+ * - Each index lists one version per package (Gitea's identity: the
+ *   lower-cased name), the newest by pacman's version comparison; versions
+ *   that compare equal are ordered by architecture (the index's own before
+ *   `any`), then bytewise by version and file name, so input order never decides.
+ * - Entries are written sorted bytewise by `<name>-<version>`, each as
+ *   `<name>-<version>/files` then `<name>-<version>/desc`.
+ * - Only the index is signed (binary detached signature over the gzip bytes).
+ *
+ * Paths are `<repository>/<architecture>/packages.db` and `packages.db.sig`
+ * (no repository prefix when `repository` is `''`), without aliases: the
+ * request names Gitea maps onto them (`<repo>.db`, `.files`, the `any`
+ * fallback) are the consumer's route, documented in the readme.
+ */
+export async function buildArchIndex(inputArg: {
+  repository: string;
+  entries: IArchIndexEntry[];
+  signer: IOpenPgpSigner;
+  timestamp: Date;
+}): Promise<ILinuxIndexFile[]> {
+  if (inputArg === null || typeof inputArg !== 'object') {
+    throw new LinuxRepoError('invalid-input', 'input must be an object', { field: 'input' });
+  }
+  assertRepository(inputArg.repository);
+  assertTimestamp(inputArg.timestamp);
+  if (inputArg.signer === null || typeof inputArg.signer !== 'object' || typeof inputArg.signer.signBinary !== 'function') {
+    throw new LinuxRepoError('invalid-input', 'signer must be an IOpenPgpSigner', { field: 'signer' });
+  }
+  if (!Array.isArray(inputArg.entries)) {
+    throw new LinuxRepoError('invalid-input', 'entries must be an array', { field: 'entries' });
+  }
+  const fileNames = new Set<string>();
+  for (const entry of inputArg.entries) {
+    assertEntry(entry);
+    if (fileNames.has(entry.record.fileName)) {
+      throw new LinuxRepoError('invalid-input', `duplicate package file ${entry.record.fileName}`, {
+        field: 'entries',
+        value: entry.record.fileName,
+      });
+    }
+    fileNames.add(entry.record.fileName);
+  }
+  if (inputArg.entries.length === 0) {
+    return [];
+  }
+
+  const architectures = [...new Set(inputArg.entries.map((entry) => entry.record.architecture))].sort(compareText);
+  const files: ILinuxIndexFile[] = [];
+  for (const architecture of architectures) {
+    const candidates = inputArg.entries.filter(
+      (entry) =>
+        entry.record.architecture === architecture ||
+        (architecture !== ANY_ARCHITECTURE && entry.record.architecture === ANY_ARCHITECTURE),
+    );
+    const selected = selectLatest(candidates, architecture);
+    const tarFiles = selected.flatMap((entry) => {
+      const directory = `${entry.record.name}-${entry.record.version}`;
+      return [
+        { name: `${directory}/files`, mode: ENTRY_MODE, data: encodeText(renderArchFiles(entry.record)) },
+        { name: `${directory}/desc`, mode: ENTRY_MODE, data: encodeText(renderArchDesc(entry)) },
+      ];
+    });
+    const archive = toUint8Array(plugins.zlib.gzipSync(writeGoTar(tarFiles)));
+    const signature = await createDetachedBinarySignature({
+      data: singleChunk(archive),
+      signer: inputArg.signer,
+      timestamp: inputArg.timestamp,
+    });
+    const directory = inputArg.repository === '' ? architecture : `${inputArg.repository}/${architecture}`;
+    files.push(
+      indexFile(`${directory}/${INDEX_ARCHIVE_NAME}`, archive, 'application/gzip'),
+      indexFile(`${directory}/${INDEX_ARCHIVE_NAME}.sig`, signature, 'application/pgp-signature'),
+    );
+  }
+  return files.sort((a, b) => compareText(a.path, b.path));
+}
+
+/** The `desc` member of one entry (`repository.go:353-379`). */
+export function renderArchDesc(entryArg: IArchIndexEntry): string {
+  const record = entryArg.record;
+  const metadata = record.metadata;
+  const signature =
+    entryArg.packageSignature === undefined ? '' : toBuffer(entryArg.packageSignature).toString('base64');
+  return renderFields([
+    ['FILENAME', record.fileName],
+    ['MD5SUM', record.digests.md5],
+    ['SHA256SUM', record.digests.sha256],
+    ['PGPSIG', signature],
+    ['CSIZE', String(record.digests.size)],
+    ['ISIZE', String(metadata.installedSize)],
+    ['NAME', record.name],
+    ['BASE', metadata.base],
+    ['ARCH', record.architecture],
+    ['VERSION', record.version],
+    ['DESC', metadata.description],
+    ['URL', metadata.projectUrl],
+    ['LICENSE', joinFields(metadata.licenses)],
+    ['GROUPS', joinFields(metadata.groups)],
+    ['BUILDDATE', String(metadata.buildDate)],
+    ['PACKAGER', metadata.packager],
+    ['PROVIDES', joinFields(metadata.provides)],
+    ['REPLACES', joinFields(metadata.replaces)],
+    ['CONFLICTS', joinFields(metadata.conflicts)],
+    ['DEPENDS', joinFields(metadata.depends)],
+    ['OPTDEPENDS', joinFields(metadata.optDepends)],
+    ['MAKEDEPENDS', joinFields(metadata.makeDepends)],
+    ['CHECKDEPENDS', joinFields(metadata.checkDepends)],
+  ]);
+}
+
+/** The `files` member of one entry (`repository.go:346-350`). */
+export function renderArchFiles(recordArg: IArchPackageRecord): string {
+  return renderFields([['FILES', joinFields(recordArg.metadata.files)]]);
+}
+
+/** `writeFields`: `%KEY%\nvalue\n\n` per non-empty value. */
+function renderFields(fieldsArg: Array<[string, string]>): string {
+  let text = '';
+  for (const [key, value] of fieldsArg) {
+    if (value !== '') {
+      text += `%${key}%\n${value}\n\n`;
+    }
+  }
+  return text;
+}
+
+/** `joinFields`: LF-joined, dropping values that contain CR or LF (they would forge index lines). */
+function joinFields(valuesArg: string[]): string {
+  return valuesArg.filter((value) => !/[\n\r]/.test(value)).join('\n');
+}
+
+function selectLatest(entriesArg: IArchIndexEntry[], architectureArg: string): IArchIndexEntry[] {
+  const latest = new Map<string, IArchIndexEntry>();
+  for (const entry of entriesArg) {
+    const key = entry.record.name.toLowerCase();
+    const current = latest.get(key);
+    if (current === undefined || isPreferred(entry, current, architectureArg)) {
+      latest.set(key, entry);
+    }
+  }
+  return [...latest.values()].sort((a, b) =>
+    compareText(`${a.record.name}-${a.record.version}`, `${b.record.name}-${b.record.version}`),
+  );
+}
+
+/** True when `candidateArg` wins over `currentArg`: newer by alpm, then the tie order. */
+function isPreferred(candidateArg: IArchIndexEntry, currentArg: IArchIndexEntry, architectureArg: string): boolean {
+  const byVersion = compareArchVersions(candidateArg.record.version, currentArg.record.version);
+  if (byVersion !== 0) {
+    return byVersion > 0;
+  }
+  const ownArchitecture = (entryArg: IArchIndexEntry) => (entryArg.record.architecture === architectureArg ? 0 : 1);
+  const byArchitecture = ownArchitecture(candidateArg) - ownArchitecture(currentArg);
+  if (byArchitecture !== 0) {
+    return byArchitecture < 0;
+  }
+  const byVersionText = compareText(candidateArg.record.version, currentArg.record.version);
+  if (byVersionText !== 0) {
+    return byVersionText < 0;
+  }
+  return compareText(candidateArg.record.fileName, currentArg.record.fileName) < 0;
+}
+
+function indexFile(pathArg: string, bytesArg: Uint8Array, mediaTypeArg: string): ILinuxIndexFile {
+  return {
+    path: pathArg,
+    bytes: bytesArg,
+    sha256: plugins.crypto.createHash('sha256').update(bytesArg).digest('hex'),
+    mediaType: mediaTypeArg,
+    stage: 'pointer',
+    aliases: [],
+  };
+}
+
+/** `''`, or `/`-separated segments that are non-empty, not `.` or `..`, and free of control characters. */
+function assertRepository(valueArg: unknown): asserts valueArg is string {
+  if (typeof valueArg !== 'string') {
+    throw new LinuxRepoError('invalid-input', 'repository must be a string', { field: 'repository' });
+  }
+  if (valueArg === '') {
+    return;
+  }
+  for (const segment of valueArg.split('/')) {
+    if (segment === '' || segment === '.' || segment === '..' || hasControlCharacter(segment)) {
+      throw new LinuxRepoError(
+        'invalid-input',
+        'repository segments must be non-empty, not "." or "..", and free of control characters',
+        { field: 'repository' },
+      );
+    }
+  }
+}
+
+/**
+ * The record values that become index paths and lines must be what the
+ * reader produces: Gitea's name and version patterns, an indexable
+ * architecture, a file name that is one path segment.
+ */
+function assertEntry(entryArg: unknown): asserts entryArg is IArchIndexEntry {
+  if (entryArg === null || typeof entryArg !== 'object') {
+    throw new LinuxRepoError('invalid-input', 'each entry must be an object', { field: 'entries' });
+  }
+  const entry = entryArg as Partial<IArchIndexEntry>;
+  const record = entry.record;
+  if (record === null || typeof record !== 'object' || record.format !== 'arch') {
+    throw new LinuxRepoError('invalid-input', 'each entry needs an Arch package record', { field: 'entries' });
+  }
+  if (typeof record.fileName !== 'string') {
+    throw new LinuxRepoError('invalid-input', 'record.fileName must be a string', { field: 'record.fileName' });
+  }
+  if (typeof record.name !== 'string' || !ARCH_NAME_PATTERN.test(record.name)) {
+    throw new LinuxRepoError('invalid-input', `package ${record.fileName} has an invalid name`, {
+      field: 'record.name',
+      value: record.fileName,
+    });
+  }
+  if (typeof record.version !== 'string' || !ARCH_VERSION_PATTERN.test(record.version)) {
+    throw new LinuxRepoError('invalid-input', `package ${record.fileName} has an invalid version`, {
+      field: 'record.version',
+      value: record.fileName,
+    });
+  }
+  if (!isIndexableArchitecture(record.architecture)) {
+    throw new LinuxRepoError(
+      'invalid-input',
+      `package ${record.fileName} has an architecture that cannot name an index path`,
+      { field: 'record.architecture', value: record.fileName },
+    );
+  }
+  assertSegmentName(record.fileName, 'record.fileName');
+  if (entry.packageSignature !== undefined) {
+    assertBytes(entry.packageSignature, 'packageSignature');
+  }
+}
+
+function compareText(aArg: string, bArg: string): number {
+  return Buffer.compare(Buffer.from(aArg, 'utf8'), Buffer.from(bArg, 'utf8'));
+}
+
+function encodeText(textArg: string): Uint8Array {
+  return new TextEncoder().encode(textArg);
+}
+
+function toBuffer(bytesArg: Uint8Array): Buffer {
+  return Buffer.from(bytesArg.buffer, bytesArg.byteOffset, bytesArg.byteLength);
+}
+
+function toUint8Array(bufferArg: Buffer): Uint8Array {
+  return new Uint8Array(bufferArg.buffer, bufferArg.byteOffset, bufferArg.byteLength);
+}

package/ts/arch/reader.ts

@@ -0,0 +1,307 @@
+import { LinuxRepoError, limitExceeded } from '../shared/errors.js';
+import { goPathBase, goPathClean } from '../shared/gopath.js';
+import { resolveLinuxPackageLimits, type ILinuxPackageLimits } from '../shared/limits.js';
+import type { IArchPackageMetadata, IArchPackageRecord } from '../shared/types.js';
+import { isValidUrl } from '../shared/url.js';
+import { readUpTo, skipToEnd } from '../readers/bytes.js';
+import { PackageByteSource } from '../readers/bytesource.js';
+import { withDecompressingReader, type TLinuxCompression } from '../readers/decompress.js';
+import { readTarEntryData, TarReader, type ITarEntry } from '../readers/tar.js';
+import { decodeGoUtf8 } from '../readers/text.js';
+import { goParseInt64, goTrimSpace } from '../shared/gostrings.js';
+
+/** Gitea `namePattern` (`modules/packages/arch/metadata.go:47`). */
+export const ARCH_NAME_PATTERN = /^[a-zA-Z0-9@._+-]+$/;
+/** Gitea `versionPattern` (`metadata.go:49`); Go's `\d` and `\w` are ASCII, as in a JS RegExp without `u`. */
+export const ARCH_VERSION_PATTERN = /^(?:\d:)?[\w.+~]+(?:-[-\w.+~]+)?$/;
+
+const MAGIC_BYTES = 10;
+const GO_C_ISDIR = 0o40000;
+
+interface IPackageInfo {
+  name: string;
+  version: string;
+  architecture: string;
+  metadata: Omit<IArchPackageMetadata, 'compression' | 'files'>;
+}
+
+/**
+ * Reads an Arch package (`.pkg.tar.zst`, `.xz` or `.gz`, chosen by magic as
+ * Gitea 28.2.0 does) into a record: `.PKGINFO` metadata and the file list,
+ * derived exactly as Gitea's `arch.ParsePackage`, plus the size and digests of
+ * the whole file. The whole payload is decompressed (bounded by
+ * `maxPayloadBytes`) because the file list needs every tar entry, and to the
+ * end of the compressed stream, so a cut or corrupt container is refused
+ * even where it lies past the tar end marker (Go stops reading there).
+ */
+export async function readArchPackage(
+  sourceArg: AsyncIterable<Uint8Array>,
+  limitsArg?: Partial<ILinuxPackageLimits>,
+): Promise<IArchPackageRecord> {
+  const limits = resolveLinuxPackageLimits(limitsArg);
+  const source = new PackageByteSource(sourceArg, limits.maxPackageBytes);
+
+  const magic = await readUpTo(source, MAGIC_BYTES);
+  source.unread(magic);
+  const container = detectContainer(magic);
+  if (container === null) {
+    throw new LinuxRepoError('unsupported-compression', 'not a zst, xz or gz compressed Arch package', {
+      field: 'compression',
+    });
+  }
+
+  const walked = await withDecompressingReader(
+    source,
+    container.decoder,
+    { maxOutputBytes: limits.maxPayloadBytes, outputLimit: 'maxPayloadBytes' },
+    async (payloadArg) => {
+      const result = await walkPayload(
+        new TarReader(payloadArg, { maxEntries: limits.maxEntries, maxHeaderBytes: limits.maxHeaderBytes }),
+        limits,
+      );
+      // Go stops at the tar end marker; the codec decodes the rest of the
+      // stream as well, so a package cut or corrupted after the marker fails
+      // loudly instead of being stored and signed
+      await skipToEnd(payloadArg);
+      return result;
+    },
+  );
+  if (walked.info === null) {
+    throw new LinuxRepoError('missing-field', '.PKGINFO file is missing', { field: '.PKGINFO' });
+  }
+  await source.drain();
+  const info = walked.info;
+  return {
+    format: 'arch',
+    name: info.name,
+    version: info.version,
+    architecture: info.architecture,
+    fileName: `${info.name}-${info.version}-${info.architecture}.pkg.tar.${container.extension}`,
+    digests: source.digests(),
+    metadata: {
+      compression: container.extension,
+      ...info.metadata,
+      files: walked.files,
+    },
+  };
+}
+
+function detectContainer(
+  magicArg: Uint8Array,
+): { extension: IArchPackageMetadata['compression']; decoder: TLinuxCompression } | null {
+  const startsWith = (bytesArg: number[]) => bytesArg.every((byte, index) => magicArg[index] === byte);
+  if (startsWith([0x28, 0xb5, 0x2f, 0xfd])) {
+    return { extension: 'zst', decoder: 'zstd' };
+  }
+  if (startsWith([0xfd, 0x37, 0x7a, 0x58, 0x5a])) {
+    return { extension: 'xz', decoder: 'xz' };
+  }
+  if (startsWith([0x1f, 0x8b])) {
+    return { extension: 'gz', decoder: 'gzip' };
+  }
+  return null;
+}
+
+/**
+ * Gitea's tar walk (`metadata.go:135-163`): regular entries only; a regular
+ * entry whose base name is `.PKGINFO` is parsed (a later one replaces an
+ * earlier one); every other regular entry whose base name does not start with
+ * `.` and whose name holds no CR or LF joins the file list, in archive order.
+ */
+async function walkPayload(
+  tarArg: TarReader,
+  limitsArg: Readonly<ILinuxPackageLimits>,
+): Promise<{ info: IPackageInfo | null; files: string[] }> {
+  let info: IPackageInfo | null = null;
+  const files: string[] = [];
+  let fileBytes = 0;
+  for (;;) {
+    const entry = await tarArg.next();
+    if (entry === null) {
+      break;
+    }
+    if (entry.typeflag !== '0') {
+      continue;
+    }
+    const base = fileInfoName(entry);
+    if (base === '.PKGINFO') {
+      const data = await readTarEntryData(entry, limitsArg.maxDecompressedMetadataBytes, 'maxDecompressedMetadataBytes');
+      info = parsePackageInfo(data, limitsArg);
+    } else if (!base.startsWith('.')) {
+      if (/[\n\r]/.test(entry.name)) {
+        continue;
+      }
+      // Gitea's BoundedFileList: entry count and total name bytes
+      const nameBytes = Buffer.byteLength(entry.name, 'utf8');
+      if (files.length >= limitsArg.maxEntries) {
+        throw limitExceeded('maxEntries', limitsArg.maxEntries, 'Arch file list');
+      }
+      if (fileBytes + nameBytes > limitsArg.maxFileListBytes) {
+        throw limitExceeded('maxFileListBytes', limitsArg.maxFileListBytes, 'Arch file list');
+      }
+      fileBytes += nameBytes;
+      files.push(entry.name);
+    }
+  }
+  return { info, files };
+}
+
+/** Go `tar.Header.FileInfo().Name()` for a regular entry: `path.Base`, after `path.Clean` when the mode marks a directory. */
+function fileInfoName(entryArg: ITarEntry): string {
+  const typeBits = (Number(BigInt.asUintN(32, entryArg.mode)) & ~0o7777) >>> 0;
+  if (typeBits === GO_C_ISDIR) {
+    return goPathBase(goPathClean(entryArg.name));
+  }
+  return goPathBase(entryArg.name);
+}
+
+const MULTI_VALUE_KEYS = {
+  license: 'licenses',
+  provides: 'provides',
+  depend: 'depends',
+  replaces: 'replaces',
+  optdepend: 'optDepends',
+  makedepend: 'makeDepends',
+  checkdepend: 'checkDepends',
+  conflict: 'conflicts',
+  backup: 'backup',
+  group: 'groups',
+  xdata: 'xdata',
+} as const;
+
+type TMultiValueKey = keyof typeof MULTI_VALUE_KEYS;
+
+/**
+ * Gitea's `ParsePackageInfo` (`metadata.go:178-267`): lines as Go's
+ * `bufio.ScanLines` splits them (a trailing CR dropped), `#` lines and lines
+ * without `=` skipped, key and value `strings.TrimSpace`d, single values last
+ * one wins, `builddate` and `size` parsed as int64 (an unparsable value
+ * refuses the package), then the name, version and architecture checks and
+ * the URL check. Lines are bounded by `maxHeaderBytes` (Gitea: 64 KiB) and
+ * each multi-valued key by `maxEntries`.
+ */
+function parsePackageInfo(dataArg: Uint8Array, limitsArg: Readonly<ILinuxPackageLimits>): IPackageInfo {
+  const info: IPackageInfo = {
+    name: '',
+    version: '',
+    architecture: '',
+    metadata: {
+      base: '',
+      description: '',
+      projectUrl: '',
+      licenses: [],
+      installedSize: 0,
+      buildDate: 0,
+      packager: '',
+      groups: [],
+      provides: [],
+      replaces: [],
+      depends: [],
+      optDepends: [],
+      makeDepends: [],
+      checkDepends: [],
+      conflicts: [],
+      xdata: [],
+      backup: [],
+    },
+  };
+  for (const rawLine of splitLines(dataArg, limitsArg.maxHeaderBytes)) {
+    const line = decodeGoUtf8(rawLine);
+    if (line.startsWith('#')) {
+      continue;
+    }
+    const equals = line.indexOf('=');
+    if (equals < 0) {
+      continue;
+    }
+    const key = goTrimSpace(line.slice(0, equals));
+    const value = goTrimSpace(line.slice(equals + 1));
+    switch (key) {
+      case 'pkgname':
+        info.name = value;
+        break;
+      case 'pkgbase':
+        info.metadata.base = value;
+        break;
+      case 'pkgver':
+        info.version = value;
+        break;
+      case 'pkgdesc':
+        info.metadata.description = value;
+        break;
+      case 'url':
+        info.metadata.projectUrl = value;
+        break;
+      case 'packager':
+        info.metadata.packager = value;
+        break;
+      case 'arch':
+        info.architecture = value;
+        break;
+      case 'builddate':
+        info.metadata.buildDate = parseInteger(value, 'builddate');
+        break;
+      case 'size':
+        info.metadata.installedSize = parseInteger(value, 'size');
+        break;
+      default:
+        if (Object.hasOwn(MULTI_VALUE_KEYS, key)) {
+          const list = info.metadata[MULTI_VALUE_KEYS[key as TMultiValueKey]];
+          if (list.length >= limitsArg.maxEntries) {
+            throw limitExceeded('maxEntries', limitsArg.maxEntries, `.PKGINFO ${key} values`);
+          }
+          list.push(value);
+        }
+    }
+  }
+  if (!ARCH_NAME_PATTERN.test(info.name)) {
+    throw new LinuxRepoError('invalid-field', 'package name is invalid', { field: 'pkgname' });
+  }
+  if (!ARCH_VERSION_PATTERN.test(info.version)) {
+    throw new LinuxRepoError('invalid-field', 'package version is invalid', { field: 'pkgver' });
+  }
+  if (info.architecture === '') {
+    throw new LinuxRepoError('invalid-field', 'package architecture is invalid', { field: 'arch' });
+  }
+  if (!isValidUrl(info.metadata.projectUrl)) {
+    info.metadata.projectUrl = '';
+  }
+  return info;
+}
+
+/** int64 as Go parses it; values outside the safe integer range cannot live in a JSON record. */
+function parseInteger(valueArg: string, fieldArg: string): number {
+  const value = goParseInt64(valueArg);
+  if (value === null) {
+    throw new LinuxRepoError('invalid-field', `.PKGINFO ${fieldArg} is not an integer`, { field: fieldArg });
+  }
+  if (value > BigInt(Number.MAX_SAFE_INTEGER) || value < BigInt(Number.MIN_SAFE_INTEGER)) {
+    throw new LinuxRepoError('invalid-field', `.PKGINFO ${fieldArg} is outside the safe integer range`, {
+      field: fieldArg,
+    });
+  }
+  return Number(value);
+}
+
+/** Go `bufio.ScanLines`: split at LF, drop one trailing CR, keep a final unterminated line when non-empty. */
+function splitLines(dataArg: Uint8Array, maxLineBytesArg: number): Uint8Array[] {
+  const lines: Uint8Array[] = [];
+  let start = 0;
+  while (start < dataArg.length) {
+    let end = dataArg.indexOf(0x0a, start);
+    const terminated = end >= 0;
+    if (!terminated) {
+      end = dataArg.length;
+    }
+    if (end - start > maxLineBytesArg) {
+      throw limitExceeded('maxHeaderBytes', maxLineBytesArg, '.PKGINFO line');
+    }
+    let line = dataArg.subarray(start, end);
+    if (line.length > 0 && line[line.length - 1] === 0x0d) {
+      line = line.subarray(0, line.length - 1);
+    }
+    lines.push(line);
+    start = terminated ? end + 1 : end;
+  }
+  return lines;
+}

package/ts/arch/signer.ts

@@ -0,0 +1,70 @@
+import { LinuxRepoError } from '../shared/errors.js';
+import { resolveLinuxPackageLimits, type ILinuxPackageLimits } from '../shared/limits.js';
+import { assertTimestamp } from '../shared/validation.js';
+import { READ_CHUNK_BYTES } from '../readers/bytes.js';
+import { PackageByteSource } from '../readers/bytesource.js';
+import { createDetachedBinarySignature } from '../signing/openpgpframing.js';
+import type { IOpenPgpSigner } from '../signing/signers.js';
+
+/**
+ * Signs an Arch package at upload time, as Gitea 28.2.0 signs every upload
+ * (`routers/api/packages/arch/arch.go:83`, `openpgp.DetachSign`): returns the
+ * `.sig` file, one binary detached signature packet over the package bytes.
+ * The package streams to the signer once, counted against `maxPackageBytes`
+ * of `limits` (pass the limits the package was read with); the codec keeps no
+ * copy, but the built-in OpenPGP signer still holds it in memory: openpgp.js
+ * buffers the whole document when detach-signing a stream.
+ * A failure of the package stream (the limit, or the caller's source error
+ * unchanged) wins over whatever the signer made of it. Pass the result as the index
+ * entry's `packageSignature`. Imported packages keep their stored signature
+ * and are never re-signed.
+ */
+export async function signArchPackage(inputArg: {
+  source: AsyncIterable<Uint8Array>;
+  signer: IOpenPgpSigner;
+  timestamp: Date;
+  limits?: Partial<ILinuxPackageLimits>;
+}): Promise<Uint8Array> {
+  if (inputArg === null || typeof inputArg !== 'object') {
+    throw new LinuxRepoError('invalid-input', 'input must be an object', { field: 'input' });
+  }
+  assertTimestamp(inputArg.timestamp);
+  if (inputArg.signer === null || typeof inputArg.signer !== 'object' || typeof inputArg.signer.signBinary !== 'function') {
+    throw new LinuxRepoError('invalid-input', 'signer must be an IOpenPgpSigner', { field: 'signer' });
+  }
+  const limits = resolveLinuxPackageLimits(inputArg.limits);
+  const source = new PackageByteSource(inputArg.source, limits.maxPackageBytes);
+  let ended = false;
+  let failure: { error: unknown } | undefined;
+  const chunks = async function* (): AsyncGenerator<Uint8Array> {
+    for (;;) {
+      let chunk: Uint8Array | null;
+      try {
+        chunk = await source.read(READ_CHUNK_BYTES);
+      } catch (error) {
+        failure = { error };
+        throw error;
+      }
+      if (chunk === null) {
+        ended = true;
+        return;
+      }
+      yield chunk;
+    }
+  };
+  let packet: Uint8Array;
+  try {
+    packet = await createDetachedBinarySignature({ data: chunks(), signer: inputArg.signer, timestamp: inputArg.timestamp });
+  } catch (error) {
+    throw failure !== undefined ? failure.error : error;
+  }
+  if (failure !== undefined) {
+    throw failure.error;
+  }
+  if (!ended) {
+    throw new LinuxRepoError('signing-failed', 'the signer returned before reading the whole package', {
+      field: 'signer',
+    });
+  }
+  return packet;
+}