@push.rocks/smartlinuxrepo 0.0.0-stage → 1.0.0

package/ts/alpine/apkindex.ts

@@ -0,0 +1,241 @@
+import * as plugins from '../plugins.js';
+import { isIndexableArchitecture } from '../shared/architecture.js';
+import { LinuxRepoError } from '../shared/errors.js';
+import type { IAlpinePackageRecord, ILinuxIndexFile } from '../shared/types.js';
+import { assertSegmentName, assertString, assertTimestamp } from '../shared/validation.js';
+import type { IAlpineSigner } from '../signing/signers.js';
+import { concatBytes } from '../readers/bytes.js';
+import { writeGoTar } from '../writers/gotar.js';
+
+/** Gitea's `alpine_module.NoArch`: these packages are listed in every architecture's index too. */
+const NOARCH = 'noarch';
+const INDEX_FILE_NAME = 'APKINDEX';
+const INDEX_ARCHIVE_NAME = 'APKINDEX.tar.gz';
+const INDEX_MODE = 0o600;
+const encoder = new TextEncoder();
+
+/**
+ * Builds the `APKINDEX.tar.gz` set of one Alpine repository (one branch and
+ * repository) as Gitea 28.2.0 does (`services/packages/alpine/repository.go:150-351`):
+ * one index per architecture the entries name, at
+ * `{branch}/{repository}/{architecture}/APKINDEX.tar.gz`. Every index other
+ * than `noarch` also lists the `noarch` packages, and every block's `A:` is the
+ * index's architecture.
+ *
+ * Each archive is a signature gzip member (a tar entry
+ * `.SIGN.RSA.<signer.keyName>` holding RSA PKCS#1 v1.5 over SHA-1 of the
+ * unsigned stream, without an end-of-archive marker) followed by the unsigned
+ * gzip member (a tar entry `APKINDEX`, mode 0600, with the marker). Tar headers
+ * are byte-for-byte what Go `archive/tar` writes for Gitea (`writeGoTar`); the
+ * signature entry is padded to its 512-byte block (a difference from Gitea),
+ * which Gitea's 4096-bit signatures already fill exactly. Entries are sorted by name, version, architecture and file
+ * name (bytewise), so the bytes depend on the entry set, not its order.
+ *
+ * Pure: the signer is the only call out. `timestamp` is validated but not
+ * written; the format carries no build time. An empty entry set returns `[]`.
+ * Bad input is `invalid-input` and names the entry; an error from the signer
+ * propagates unchanged; a signer result that is not non-empty bytes is
+ * `signing-failed`.
+ */
+export async function buildAlpineIndex(inputArg: {
+  branch: string;
+  repository: string;
+  entries: IAlpinePackageRecord[];
+  signer: IAlpineSigner;
+  timestamp: Date;
+}): Promise<ILinuxIndexFile[]> {
+  if (inputArg === null || typeof inputArg !== 'object') {
+    throw new LinuxRepoError('invalid-input', 'input must be an object', { field: 'input' });
+  }
+  assertLayoutSegment(inputArg.branch, 'branch');
+  assertLayoutSegment(inputArg.repository, 'repository');
+  assertTimestamp(inputArg.timestamp);
+  const signer = inputArg.signer;
+  if (signer === null || typeof signer !== 'object' || typeof signer.sign !== 'function') {
+    throw new LinuxRepoError('invalid-input', 'signer must be an IAlpineSigner', { field: 'signer' });
+  }
+  assertSegmentName(signer.keyName, 'signer.keyName');
+  if (!Array.isArray(inputArg.entries)) {
+    throw new LinuxRepoError('invalid-input', 'entries must be an array', { field: 'entries' });
+  }
+
+  const entries = inputArg.entries.map((record, index) => checkRecord(record, `entries[${index}]`));
+  const seen = new Set<string>();
+  for (const record of entries) {
+    const key = `${record.architecture}/${record.fileName}`;
+    if (seen.has(key)) {
+      throw new LinuxRepoError('invalid-input', `duplicate package file ${key}`, { field: 'entries', value: key });
+    }
+    seen.add(key);
+  }
+  entries.sort(compareRecords);
+
+  const architectures = [...new Set(entries.map((record) => record.architecture))].sort(compareBytes);
+  const files: ILinuxIndexFile[] = [];
+  for (const architecture of architectures) {
+    const listed = entries.filter(
+      (record) => record.architecture === architecture || (architecture !== NOARCH && record.architecture === NOARCH),
+    );
+    const text = listed.map((record) => renderAlpineIndexEntry(record, architecture)).join('');
+    const unsigned = await gzip(
+      writeGoTar([{ name: INDEX_FILE_NAME, mode: INDEX_MODE, data: encoder.encode(text) }], { endOfArchive: true }),
+    );
+    const signature: unknown = await signer.sign(unsigned);
+    if (!(signature instanceof Uint8Array) || signature.length === 0) {
+      throw new LinuxRepoError('signing-failed', 'the Alpine signer did not return signature bytes', {
+        field: 'signer',
+      });
+    }
+    const signatureMember = await gzip(
+      writeGoTar([{ name: `.SIGN.RSA.${signer.keyName}`, mode: INDEX_MODE, data: signature }], { endOfArchive: false }),
+    );
+    const bytes = concatBytes([signatureMember, unsigned]);
+    files.push({
+      path: `${inputArg.branch}/${inputArg.repository}/${architecture}/${INDEX_ARCHIVE_NAME}`,
+      bytes,
+      sha256: plugins.crypto.createHash('sha256').update(bytes).digest('hex'),
+      mediaType: 'application/gzip',
+      stage: 'pointer',
+      aliases: [],
+    });
+  }
+  return files;
+}
+
+/**
+ * One APKINDEX block for `recordArg` in the index of `architectureArg`, as
+ * Gitea writes it (`services/packages/alpine/repository.go:215-252`),
+ * including the blank line that ends it. Internal: 1.0.0 exports no
+ * per-entry renderers. The record must have passed `checkRecord`.
+ */
+export function renderAlpineIndexEntry(recordArg: IAlpinePackageRecord, architectureArg: string): string {
+  const metadata = recordArg.metadata;
+  const lines = [
+    `C:Q1${Buffer.from(recordArg.digests.controlSha1, 'hex').toString('base64')}`,
+    `P:${recordArg.name}`,
+    `V:${recordArg.version}`,
+    `A:${architectureArg}`,
+  ];
+  if (metadata.description !== '') {
+    lines.push(`T:${metadata.description}`);
+  }
+  if (metadata.projectUrl !== '') {
+    lines.push(`U:${metadata.projectUrl}`);
+  }
+  if (metadata.license !== '') {
+    lines.push(`L:${metadata.license}`);
+  }
+  lines.push(
+    `S:${recordArg.digests.size}`,
+    `I:${metadata.installedSize}`,
+    `o:${metadata.origin}`,
+    `m:${metadata.maintainer}`,
+    `t:${metadata.buildDate}`,
+  );
+  if (metadata.commit !== '') {
+    lines.push(`c:${metadata.commit}`);
+  }
+  if (metadata.dependencies.length > 0) {
+    lines.push(`D:${metadata.dependencies.join(' ')}`);
+  }
+  if (metadata.provides.length > 0) {
+    lines.push(`p:${metadata.provides.join(' ')}`);
+  }
+  if (metadata.installIf !== '') {
+    lines.push(`i:${metadata.installIf}`);
+  }
+  if (metadata.providerPriority > 0) {
+    lines.push(`k:${metadata.providerPriority}`);
+  }
+  return `${lines.join('\n')}\n\n`;
+}
+
+/**
+ * Checks what the index writes. A value with a line break would forge APKINDEX
+ * fields; Gitea's line-based `.PKGINFO` parser never produces one, so refusing
+ * it refuses no package Gitea stored.
+ */
+function checkRecord(recordArg: unknown, fieldArg: string): IAlpinePackageRecord {
+  const fail = (whatArg: string): never => {
+    throw new LinuxRepoError('invalid-input', `${fieldArg}: ${whatArg}`, { field: fieldArg });
+  };
+  if (recordArg === null || typeof recordArg !== 'object') {
+    return fail('must be an Alpine package record');
+  }
+  const record = recordArg as IAlpinePackageRecord;
+  if (record.format !== 'alpine' || record.metadata === null || typeof record.metadata !== 'object') {
+    return fail('must be an Alpine package record');
+  }
+  if (record.digests === null || typeof record.digests !== 'object') {
+    return fail('digests must be an object');
+  }
+  const text = (valueArg: unknown, nameArg: string, nonEmptyArg = false): void => {
+    if (typeof valueArg !== 'string' || /[\n]/.test(valueArg) || (nonEmptyArg && valueArg === '')) {
+      fail(`${nameArg} must be a${nonEmptyArg ? ' non-empty' : ''} string without line breaks`);
+    }
+  };
+  const integer = (valueArg: unknown, nameArg: string, minimumArg = -Number.MAX_SAFE_INTEGER): void => {
+    if (typeof valueArg !== 'number' || !Number.isSafeInteger(valueArg) || valueArg < minimumArg) {
+      fail(`${nameArg} must be a safe integer${minimumArg === 0 ? ' >= 0' : ''}`);
+    }
+  };
+  const list = (valueArg: unknown, nameArg: string): void => {
+    if (!Array.isArray(valueArg)) {
+      fail(`${nameArg} must be an array`);
+    }
+    (valueArg as unknown[]).forEach((item, index) => text(item, `${nameArg}[${index}]`));
+  };
+  text(record.name, 'name', true);
+  text(record.version, 'version', true);
+  assertString(record.fileName, `${fieldArg}.fileName`);
+  if (!isIndexableArchitecture(record.architecture)) {
+    fail(`architecture ${JSON.stringify(record.architecture)} of ${record.fileName} cannot name an index`);
+  }
+  if (typeof record.digests.controlSha1 !== 'string' || !/^[0-9a-f]{40}$/.test(record.digests.controlSha1)) {
+    fail('digests.controlSha1 must be 40 lowercase hex digits');
+  }
+  integer(record.digests.size, 'digests.size', 0);
+  const metadata = record.metadata;
+  for (const key of ['description', 'license', 'projectUrl', 'maintainer', 'origin', 'commit', 'installIf'] as const) {
+    text(metadata[key], `metadata.${key}`);
+  }
+  integer(metadata.installedSize, 'metadata.installedSize');
+  integer(metadata.buildDate, 'metadata.buildDate');
+  integer(metadata.providerPriority, 'metadata.providerPriority');
+  list(metadata.dependencies, 'metadata.dependencies');
+  list(metadata.provides, 'metadata.provides');
+  return record;
+}
+
+function assertLayoutSegment(valueArg: unknown, fieldArg: string): asserts valueArg is string {
+  assertSegmentName(valueArg, fieldArg);
+  if (valueArg === '.' || valueArg === '..') {
+    throw new LinuxRepoError('invalid-input', `${fieldArg} must not be "." or ".."`, { field: fieldArg });
+  }
+}
+
+function compareRecords(aArg: IAlpinePackageRecord, bArg: IAlpinePackageRecord): number {
+  return (
+    compareBytes(aArg.name, bArg.name) ||
+    compareBytes(aArg.version, bArg.version) ||
+    compareBytes(aArg.architecture, bArg.architecture) ||
+    compareBytes(aArg.fileName, bArg.fileName)
+  );
+}
+
+/** Orders strings by their UTF-8 bytes. */
+function compareBytes(aArg: string, bArg: string): number {
+  return Buffer.compare(Buffer.from(aArg, 'utf8'), Buffer.from(bArg, 'utf8'));
+}
+
+function gzip(bytesArg: Uint8Array): Promise<Uint8Array> {
+  return new Promise((resolve, reject) => {
+    plugins.zlib.gzip(bytesArg, (error, result) => {
+      if (error) {
+        reject(error);
+      } else {
+        resolve(new Uint8Array(result.buffer, result.byteOffset, result.byteLength));
+      }
+    });
+  });
+}

package/ts/alpine/pkginfo.ts

@@ -0,0 +1,183 @@
+import { LinuxRepoError, limitExceeded } from '../shared/errors.js';
+import type { ILinuxPackageLimits } from '../shared/limits.js';
+import { goParseInt64, goTrimSpace } from '../shared/gostrings.js';
+import { isValidUrl } from '../shared/url.js';
+import { decodeGoUtf8 } from '../readers/text.js';
+
+/** What Gitea 28.2.0 derives from an apk `.PKGINFO` (`modules/packages/alpine/metadata.go:137-227`). */
+export interface IAlpinePackageInfo {
+  name: string;
+  version: string;
+  architecture: string;
+  description: string;
+  license: string;
+  projectUrl: string;
+  maintainer: string;
+  packager: string;
+  buildDate: number;
+  installedSize: number;
+  origin: string;
+  commit: string;
+  installIf: string;
+  provides: string[];
+  dependencies: string[];
+  providerPriority: number;
+}
+
+const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
+
+/**
+ * Parses `.PKGINFO` as Gitea's `ParsePackageInfo` does:
+ * - lines split as `bufio.ScanLines` (LF, one trailing CR dropped, a final
+ *   line without LF counts);
+ * - `#` lines and lines without `=` are skipped; key and value are
+ *   `strings.TrimSpace`d around the first `=`; the last value wins, except
+ *   `provides` and `depend`, which collect every non-empty value;
+ * - `builddate`, `size` and `provider_priority` are `strconv.ParseInt(v, 10,
+ *   64)`; a value Go cannot parse (including one outside int64) is ignored,
+ *   so the field keeps its previous value, 0 when there is none
+ *   (`metadata.go:165-174`, `:203-207`);
+ * - an empty `pkgname` or `pkgver` is refused; a `url` Gitea's URL validation
+ *   refuses becomes `''`.
+ *
+ * Bytes are decoded with `decodeGoUtf8`. Where the codec differs from Gitea
+ * (test/test.alpine.reader.node.ts pins each case against Gitea's own code):
+ * - a line is bounded by `maxHeaderBytes` instead of Go's 64 KiB scanner buffer;
+ * - `provides` plus `depend` values are bounded by `maxEntries` instead of 1024;
+ * - invalid UTF-8 becomes U+FFFD per byte, where Gitea 28.2.0 refuses the
+ *   upload because its `encoding/json/v2` cannot store the metadata;
+ * - a number Go parses but JSON cannot hold exactly (beyond
+ *   `Number.MAX_SAFE_INTEGER` in magnitude) is refused as `invalid-field`,
+ *   never rounded.
+ */
+export function parseAlpinePackageInfo(bytesArg: Uint8Array, limitsArg: Readonly<ILinuxPackageLimits>): IAlpinePackageInfo {
+  const info: IAlpinePackageInfo = {
+    name: '',
+    version: '',
+    architecture: '',
+    description: '',
+    license: '',
+    projectUrl: '',
+    maintainer: '',
+    packager: '',
+    buildDate: 0,
+    installedSize: 0,
+    origin: '',
+    commit: '',
+    installIf: '',
+    provides: [],
+    dependencies: [],
+    providerPriority: 0,
+  };
+  for (const line of scanLines(bytesArg, limitsArg.maxHeaderBytes)) {
+    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 'pkgver':
+        info.version = value;
+        break;
+      case 'pkgdesc':
+        info.description = value;
+        break;
+      case 'url':
+        info.projectUrl = value;
+        break;
+      case 'builddate':
+        info.buildDate = goParseInt(value, key) ?? info.buildDate;
+        break;
+      case 'size':
+        info.installedSize = goParseInt(value, key) ?? info.installedSize;
+        break;
+      case 'arch':
+        info.architecture = value;
+        break;
+      case 'origin':
+        info.origin = value;
+        break;
+      case 'commit':
+        info.commit = value;
+        break;
+      case 'maintainer':
+        info.maintainer = value;
+        break;
+      case 'packager':
+        info.packager = value;
+        break;
+      case 'license':
+        info.license = value;
+        break;
+      case 'install_if':
+        info.installIf = value;
+        break;
+      case 'provides':
+      case 'depend':
+        if (value !== '') {
+          if (info.provides.length + info.dependencies.length >= limitsArg.maxEntries) {
+            throw limitExceeded('maxEntries', limitsArg.maxEntries, '.PKGINFO provides and depend values');
+          }
+          (key === 'provides' ? info.provides : info.dependencies).push(value);
+        }
+        break;
+      case 'provider_priority':
+        info.providerPriority = goParseInt(value, key) ?? info.providerPriority;
+        break;
+    }
+  }
+  if (info.name === '') {
+    throw new LinuxRepoError('missing-field', '.PKGINFO has no pkgname', { field: 'pkgname' });
+  }
+  if (info.version === '') {
+    throw new LinuxRepoError('missing-field', '.PKGINFO has no pkgver', { field: 'pkgver' });
+  }
+  if (!isValidUrl(info.projectUrl)) {
+    info.projectUrl = '';
+  }
+  return info;
+}
+
+/** `bufio.ScanLines` over the bytes, each line decoded as Gitea stores it. */
+function* scanLines(bytesArg: Uint8Array, maxLineBytesArg: number): Generator<string> {
+  let start = 0;
+  while (start < bytesArg.length) {
+    const newline = bytesArg.indexOf(0x0a, start);
+    const end = newline < 0 ? bytesArg.length : newline;
+    let lineEnd = end;
+    if (lineEnd > start && bytesArg[lineEnd - 1] === 0x0d) {
+      lineEnd -= 1;
+    }
+    if (lineEnd - start > maxLineBytesArg) {
+      throw limitExceeded('maxHeaderBytes', maxLineBytesArg, '.PKGINFO line');
+    }
+    yield decodeGoUtf8(bytesArg.subarray(start, lineEnd));
+    start = newline < 0 ? bytesArg.length : newline + 1;
+  }
+}
+
+/**
+ * Go `strconv.ParseInt(value, 10, 64)`: `null` where Go returns an error (Gitea
+ * then keeps the previous value); `invalid-field` for an int64 beyond the safe
+ * JSON integer range.
+ */
+function goParseInt(valueArg: string, fieldArg: string): number | null {
+  const value = goParseInt64(valueArg);
+  if (value === null) {
+    return null;
+  }
+  if (value > MAX_SAFE || value < -MAX_SAFE) {
+    throw new LinuxRepoError('invalid-field', `.PKGINFO ${fieldArg} is beyond the safe integer range`, {
+      field: fieldArg,
+      value: valueArg,
+    });
+  }
+  return Number(value) + 0;
+}

package/ts/alpine/reader.ts

@@ -0,0 +1,96 @@
+import { LinuxRepoError, truncated } from '../shared/errors.js';
+import { resolveLinuxPackageLimits, type ILinuxPackageLimits } from '../shared/limits.js';
+import type { IAlpinePackageRecord } from '../shared/types.js';
+import { BufferReader, readUpTo } from '../readers/bytes.js';
+import { PackageByteSource } from '../readers/bytesource.js';
+import { readGzipMember } from '../readers/gzipmember.js';
+import { readTarEntryData, TarReader } from '../readers/tar.js';
+import { parseAlpinePackageInfo } from './pkginfo.js';
+
+const PKGINFO = '.PKGINFO';
+
+/**
+ * Reads an apk v2 package (concatenated gzip members: usually the signature,
+ * the control segment holding `.PKGINFO`, and the data) into a record, as
+ * Gitea 28.2.0's `ParsePackage` does (`modules/packages/alpine/metadata.go:77-134`):
+ * - gzip members are read one at a time; the first member whose tar holds an
+ *   entry named exactly `.PKGINFO` is the control segment. Unsigned packages
+ *   (no signature member) are accepted;
+ * - `digests.controlSha1` is the SHA-1 of exactly that member's bytes (the
+ *   APKINDEX `C:` value is `Q1` plus its base64);
+ * - the rest of the input is hashed, never decompressed;
+ * - the record's `fileName` is Gitea's `{name}-{version}.apk`.
+ *
+ * Each member read before the control segment is buffered and bounded by
+ * `maxMetadataBytes` (member bytes) and `maxDecompressedMetadataBytes` (its
+ * tar). An apk v3 (ADB) package is `unsupported-package-format`, as Gitea
+ * refuses it too. On failure the reader stops pulling and returns no record.
+ */
+export async function readAlpinePackage(
+  sourceArg: AsyncIterable<Uint8Array>,
+  limitsArg?: Partial<ILinuxPackageLimits>,
+): Promise<IAlpinePackageRecord> {
+  const limits = resolveLinuxPackageLimits(limitsArg);
+  const input = new PackageByteSource(sourceArg, limits.maxPackageBytes);
+
+  const head = await readUpTo(input, 3);
+  if (head.length === 0) {
+    throw truncated('apk package');
+  }
+  if (head.length === 3 && head[0] === 0x41 && head[1] === 0x44 && head[2] === 0x42) {
+    throw new LinuxRepoError('unsupported-package-format', 'apk v3 (ADB) packages are not supported', {
+      field: 'apk package',
+    });
+  }
+  input.unread(head);
+
+  for (;;) {
+    const member = await readGzipMember(input, {
+      maxMemberBytes: limits.maxMetadataBytes,
+      memberLimit: 'maxMetadataBytes',
+      maxOutputBytes: limits.maxDecompressedMetadataBytes,
+      outputLimit: 'maxDecompressedMetadataBytes',
+      maxHeaderBytes: limits.maxHeaderBytes,
+    });
+    if (member === null) {
+      throw new LinuxRepoError('missing-field', 'the package has no .PKGINFO', { field: PKGINFO });
+    }
+    const tar = new TarReader(new BufferReader(member.output), {
+      maxEntries: limits.maxEntries,
+      maxHeaderBytes: limits.maxHeaderBytes,
+    });
+    for (let entry = await tar.next(); entry !== null; entry = await tar.next()) {
+      if (entry.name !== PKGINFO) {
+        continue;
+      }
+      // Gitea stops at the first .PKGINFO and ignores the rest of the member's tar
+      const pkginfo = await readTarEntryData(entry, limits.maxDecompressedMetadataBytes, 'maxDecompressedMetadataBytes');
+      const info = parseAlpinePackageInfo(pkginfo, limits);
+      await input.drain();
+      const digests = input.digests();
+      return {
+        format: 'alpine',
+        name: info.name,
+        version: info.version,
+        architecture: info.architecture,
+        fileName: `${info.name}-${info.version}.apk`,
+        digests: { ...digests, controlSha1: member.memberSha1 },
+        metadata: {
+          description: info.description,
+          license: info.license,
+          projectUrl: info.projectUrl,
+          maintainer: info.maintainer,
+          packager: info.packager,
+          buildDate: info.buildDate,
+          installedSize: info.installedSize,
+          origin: info.origin,
+          commit: info.commit,
+          installIf: info.installIf,
+          provides: info.provides,
+          dependencies: info.dependencies,
+          providerPriority: info.providerPriority,
+        },
+      };
+    }
+  }
+}