@push.rocks/smartlinuxrepo 0.0.0-stage → 0.1.0

package/ts/rpm/sign.ts

@@ -0,0 +1,200 @@
+import * as plugins from '../plugins.js';
+import { PackageByteSource } from '../readers/bytesource.js';
+import { READ_CHUNK_BYTES } from '../readers/bytes.js';
+import { LinuxRepoError } from '../shared/errors.js';
+import { resolveLinuxPackageLimits, type ILinuxPackageLimits } from '../shared/limits.js';
+import { assertTimestamp } from '../shared/validation.js';
+import { createDetachedBinarySignature } from '../signing/openpgpframing.js';
+import { singleChunk, type IOpenPgpSigner } from '../signing/signers.js';
+import { readRpmHeaders, RPM_SIGNATURE_TAG, RPM_TYPE, writeSignatureHeader, type IRpmPackageHeaders } from './header.js';
+
+const PAYLOAD_DIGEST = 5092;
+const PAYLOAD_DIGEST_ALGORITHM = 5093;
+
+/** go-rpmutils `getPayloadDigest` algorithms (`signatures.go`, RFC 4880 ids). */
+const PAYLOAD_DIGEST_ALGORITHMS = new Map<number, string>([
+  [1, 'md5'],
+  [2, 'sha1'],
+  [8, 'sha256'],
+  [9, 'sha384'],
+  [10, 'sha512'],
+  [11, 'sha224'],
+]);
+
+/**
+ * Signs an RPM package as Gitea 28.2.0 does on upload (`services/packages/rpm/sign.go:17-38`,
+ * go-rpmutils v0.4.0 `SignRpmStream` and `DumpSignatureHeader(false)`):
+ * - the main header digest is checked, and the payload is checked against
+ *   PAYLOADDIGEST (5092/5093), else the signature header MD5 (1004) over
+ *   header and payload; a package with neither is `missing-field`, a mismatch
+ *   `digest-mismatch`;
+ * - tag 1002 gets a signature over the main header and payload, tag 268 one
+ *   over the main header alone; tags 1005, 267 and 1008 are removed; every
+ *   other signature tag from 64 up is kept byte for byte, the tags are written
+ *   in ascending order behind a new region tag 62, and the header is padded to
+ *   8 bytes.
+ *
+ * The signed package is `prefix` (the lead and the new signature header)
+ * followed by the original bytes from `resumeAt`, the start of the main
+ * header. The source is read once; only the headers are held in memory, and
+ * the payload streams through the signer. A signer that returns before reading
+ * the data to its end is `signing-failed`.
+ */
+export async function signRpmPackage(input: {
+  source: AsyncIterable<Uint8Array>;
+  signer: IOpenPgpSigner;
+  timestamp: Date;
+  limits?: Partial<ILinuxPackageLimits>;
+}): Promise<{ prefix: Uint8Array; resumeAt: number }> {
+  if (input === null || typeof input !== 'object') {
+    throw new LinuxRepoError('invalid-input', 'input must be an object', { field: 'input' });
+  }
+  if (input.signer === null || typeof input.signer !== 'object' || typeof input.signer.signBinary !== 'function') {
+    throw new LinuxRepoError('invalid-input', 'signer must implement IOpenPgpSigner', { field: 'signer' });
+  }
+  assertTimestamp(input.timestamp);
+  const limits = resolveLinuxPackageLimits(input.limits);
+  const bytes = new PackageByteSource(input.source, limits.maxPackageBytes);
+  const headers = await readRpmHeaders(bytes, limits);
+  const payloadCheck = payloadDigestCheck(headers);
+
+  const signedData = new SignedDataStream(headers.main.bytes, bytes, payloadCheck);
+  let headerAndPayload: Uint8Array;
+  try {
+    headerAndPayload = await createDetachedBinarySignature({ data: signedData, signer: input.signer, timestamp: input.timestamp });
+  } catch (error) {
+    // a failure of the codec's own stream (or the caller's source) wins over what the signer made of it
+    throw signedData.failure !== undefined ? signedData.failure.error : error;
+  }
+  if (signedData.failure !== undefined) {
+    throw signedData.failure.error;
+  }
+  if (!signedData.completed) {
+    throw new LinuxRepoError('signing-failed', 'the signer returned before reading the package to its end', { field: 'signer' });
+  }
+  const headerOnly = await createDetachedBinarySignature({
+    data: singleChunk(headers.main.bytes),
+    signer: input.signer,
+    timestamp: input.timestamp,
+  });
+
+  const removed = new Set<number>([
+    RPM_SIGNATURE_TAG.pgp,
+    RPM_SIGNATURE_TAG.rsa,
+    RPM_SIGNATURE_TAG.gpg,
+    RPM_SIGNATURE_TAG.dsa,
+    RPM_SIGNATURE_TAG.reservedSpace,
+  ]);
+  const signatureHeader = writeSignatureHeader(headers.signature, removed, [
+    { tag: RPM_SIGNATURE_TAG.pgp, type: RPM_TYPE.bin, count: headerAndPayload.length, contents: headerAndPayload },
+    { tag: RPM_SIGNATURE_TAG.rsa, type: RPM_TYPE.bin, count: headerOnly.length, contents: headerOnly },
+  ]);
+  const prefix = new Uint8Array(headers.lead.length + signatureHeader.length);
+  prefix.set(headers.lead, 0);
+  prefix.set(signatureHeader, headers.lead.length);
+  return { prefix, resumeAt: headers.mainStart };
+}
+
+/** How the payload is checked (go-rpmutils `digestPayload`, `verify_digests.go`). */
+interface IPayloadCheck {
+  hash: ReturnType<typeof plugins.crypto.createHash>;
+  /** Whether the digest also covers the main header (the legacy MD5). */
+  coversHeader: boolean;
+  matches(digestArg: Buffer): boolean;
+}
+
+function payloadDigestCheck(headersArg: IRpmPackageHeaders): IPayloadCheck {
+  // the same lookups, in the same order, as go-rpmutils `getPayloadDigest`
+  const digests = headersArg.main.strings(PAYLOAD_DIGEST);
+  const algorithms = digests === null || digests.length === 0 ? null : headersArg.main.uint32s(PAYLOAD_DIGEST_ALGORITHM);
+  const algorithm = algorithms === null || algorithms.length === 0 ? undefined : PAYLOAD_DIGEST_ALGORITHMS.get(algorithms[0]);
+  if (algorithm !== undefined && digests !== null) {
+    const expected = digests[0];
+    return {
+      hash: plugins.crypto.createHash(algorithm),
+      coversHeader: false,
+      matches: (digestArg) => {
+        const actual = new TextEncoder().encode(digestArg.toString('hex'));
+        return actual.length === expected.length && actual.every((byte, i) => byte === expected[i]);
+      },
+    };
+  }
+  const md5 = headersArg.signature.binary(RPM_SIGNATURE_TAG.md5);
+  if (md5 !== null && md5.length !== 0) {
+    return {
+      hash: plugins.crypto.createHash('md5'),
+      coversHeader: true,
+      matches: (digestArg) => digestArg.length === md5.length && digestArg.every((byte, i) => byte === md5[i]),
+    };
+  }
+  throw new LinuxRepoError('missing-field', 'the RPM package has no usable payload digest', { field: 'payload digest' });
+}
+
+/**
+ * The data tag 1002 signs: the main header, then the payload as it is pulled
+ * from the package source, hashed for the payload check on the way. Iterable
+ * once; it pulls only when the signer asks. Any failure (the caller's source,
+ * a limit, truncation, a digest mismatch) is thrown to the signer and kept, so
+ * `signRpmPackage` reports it instead of whatever the signer made of it.
+ */
+class SignedDataStream implements AsyncIterable<Uint8Array> {
+  public completed = false;
+  public failure: { error: unknown } | undefined = undefined;
+  private iterated = false;
+  private headerSent = false;
+  private queue: Promise<unknown> = Promise.resolve();
+
+  constructor(
+    private readonly mainHeader: Uint8Array,
+    private readonly source: PackageByteSource,
+    private readonly check: IPayloadCheck,
+  ) {}
+
+  public [Symbol.asyncIterator](): AsyncIterator<Uint8Array> {
+    if (this.iterated) {
+      const error = new LinuxRepoError('signing-failed', 'the signer read the package data more than once', { field: 'signer' });
+      this.failure ??= { error };
+      throw error;
+    }
+    this.iterated = true;
+    return {
+      next: () => {
+        // serialize: a signer that does not await one next() before the next one still gets the bytes in order
+        const result = this.queue.then(() => this.pull());
+        this.queue = result.catch(() => undefined);
+        return result;
+      },
+    };
+  }
+
+  private async pull(): Promise<IteratorResult<Uint8Array>> {
+    if (this.failure !== undefined) {
+      throw this.failure.error;
+    }
+    if (this.completed) {
+      return { done: true, value: undefined };
+    }
+    try {
+      if (!this.headerSent) {
+        this.headerSent = true;
+        if (this.check.coversHeader) {
+          this.check.hash.update(this.mainHeader);
+        }
+        return { done: false, value: this.mainHeader };
+      }
+      const chunk = await this.source.read(READ_CHUNK_BYTES);
+      if (chunk !== null) {
+        this.check.hash.update(chunk);
+        return { done: false, value: chunk };
+      }
+      if (!this.check.matches(this.check.hash.digest())) {
+        throw new LinuxRepoError('digest-mismatch', 'the RPM payload does not match its digest', { field: 'payload digest' });
+      }
+      this.completed = true;
+      return { done: true, value: undefined };
+    } catch (error) {
+      this.failure = { error };
+      throw error;
+    }
+  }
+}

package/ts/rpm/updates.ts

@@ -0,0 +1,314 @@
+import { LinuxRepoError } from '../shared/errors.js';
+import type { IRpmUpdate, IRpmUpdateCollection, IRpmUpdatePackage, IRpmUpdateReference } from '../shared/types.js';
+import { assertTimestamp } from '../shared/validation.js';
+import { compareCodePoints, element, textElement, XML_HEADER } from './xml.js';
+
+/**
+ * Merges posted errata into the stored ones, as Gitea 28.2.0's errata route
+ * does (`routers/api/packages/rpm/rpm.go:367-447`). Pure: the inputs are
+ * never changed, and incoming updates are applied in order.
+ * - A known id: its collections merge by `short` and its packages are
+ *   de-duplicated by name, version, release and arch; the seven scalar fields
+ *   and `references` are replaced; `updated` becomes the timestamp and
+ *   `issued` is kept.
+ * - A new id: the update is appended; `issued` and `updated` get the
+ *   timestamp only when they are `null`.
+ * - De-duplication applies to every append, including the collections of a new
+ *   update (Gitea appends those as posted).
+ * Dates are written as `YYYY-MM-DD HH:MM:SS` in UTC (Gitea uses its server's
+ * local time). Contents are not validated, as in Gitea; only the shape is.
+ */
+export function mergeRpmUpdates(input: { existing: IRpmUpdate[]; incoming: IRpmUpdate[]; timestamp: Date }): IRpmUpdate[] {
+  if (input === null || typeof input !== 'object') {
+    throw new LinuxRepoError('invalid-input', 'input must be an object', { field: 'input' });
+  }
+  assertRpmUpdates(input.existing, 'existing');
+  assertRpmUpdates(input.incoming, 'incoming');
+  assertTimestamp(input.timestamp);
+  const now = formatRpmUpdateDate(input.timestamp);
+  const merged = input.existing.map(cloneUpdate);
+  for (const incoming of input.incoming) {
+    const update = cloneUpdate(incoming);
+    const known = merged.find((candidate) => candidate.id === update.id);
+    if (known !== undefined) {
+      mergeCollections(known.collections, update.collections);
+      known.from = update.from;
+      known.status = update.status;
+      known.type = update.type;
+      known.version = update.version;
+      known.title = update.title;
+      known.severity = update.severity;
+      known.description = update.description;
+      known.references = update.references;
+      known.updated = now;
+    } else {
+      const appended: IRpmUpdate = { ...update, issued: update.issued ?? now, updated: update.updated ?? now, collections: [] };
+      mergeCollections(appended.collections, update.collections);
+      merged.push(appended);
+    }
+  }
+  return merged;
+}
+
+/**
+ * The updates of an index: updates with the same id merge as
+ * Gitea's `buildUpdateInfo` does (`services/packages/rpm/repository.go:560-620`),
+ * without setting any date. The scalar fields, dates and references come from
+ * the update with the newest `updated`, then the newest `issued`, then the
+ * greatest canonical JSON of those fields; packages that collide keep the
+ * values of the higher-ranked update. Updates sort by id, collections by
+ * `short`, packages by name, version, release and arch; references keep their
+ * order. The input order never decides.
+ */
+export function combineRpmUpdates(updatesArg: IRpmUpdate[]): IRpmUpdate[] {
+  const byId = new Map<string, IRpmUpdate[]>();
+  for (const update of updatesArg) {
+    const group = byId.get(update.id);
+    if (group === undefined) {
+      byId.set(update.id, [update]);
+    } else {
+      group.push(update);
+    }
+  }
+  const combined: IRpmUpdate[] = [];
+  for (const group of byId.values()) {
+    const ranked = [...group].sort(compareRank);
+    const result: IRpmUpdate = { ...cloneUpdate(ranked[0]), collections: [] };
+    for (const update of ranked) {
+      mergeCollections(result.collections, update.collections.map(cloneCollection));
+    }
+    result.collections.sort((a, b) => compareCodePoints(a.short, b.short));
+    for (const collection of result.collections) {
+      collection.packages.sort(comparePackages);
+    }
+    combined.push(result);
+  }
+  return combined.sort((a, b) => compareCodePoints(a.id, b.id));
+}
+
+/** `updateinfo.xml` for combined updates, as Go's `encoding/xml` writes Gitea's `Update` type. */
+export function renderUpdateInfo(updatesArg: IRpmUpdate[]): string {
+  const updates = updatesArg.map((update) =>
+    element(
+      'update',
+      [
+        ['from', update.from],
+        ['status', update.status],
+        ['type', update.type],
+        ['version', update.version],
+      ],
+      [
+        textElement('id', update.id),
+        textElement('title', update.title),
+        textElement('severity', update.severity),
+        textElement('description', update.description),
+        update.issued === null ? '' : element('issued', [['date', update.issued]]),
+        update.updated === null ? '' : element('updated', [['date', update.updated]]),
+        element(
+          'references',
+          [],
+          update.references
+            .map((reference) =>
+              element('reference', [
+                ['href', reference.href],
+                ['id', reference.id],
+                ['title', reference.title],
+                ['type', reference.type],
+              ]),
+            )
+            .join(''),
+        ),
+        element(
+          'pkglist',
+          [],
+          update.collections
+            .map((collection) =>
+              element(
+                'collection',
+                [['short', collection.short]],
+                collection.packages
+                  .map((pkg) =>
+                    element(
+                      'package',
+                      [
+                        ['arch', pkg.arch],
+                        ['name', pkg.name],
+                        ['release', pkg.release],
+                        ['src', pkg.src],
+                        ['version', pkg.version],
+                      ],
+                      textElement('filename', pkg.fileName),
+                    ),
+                  )
+                  .join(''),
+              ),
+            )
+            .join(''),
+        ),
+      ].join(''),
+    ),
+  );
+  return `${XML_HEADER}${element('updates', [['xmlns', 'http://linux.duke.edu/metadata/updateinfo']], updates.join(''))}`;
+}
+
+/** `YYYY-MM-DD HH:MM:SS` in UTC. */
+export function formatRpmUpdateDate(timestampArg: Date): string {
+  return timestampArg.toISOString().slice(0, 19).replace('T', ' ');
+}
+
+/** Refuses anything that is not an array of plain-JSON `IRpmUpdate` values. */
+export function assertRpmUpdates(valueArg: unknown, fieldArg: string): asserts valueArg is IRpmUpdate[] {
+  if (!Array.isArray(valueArg)) {
+    throw new LinuxRepoError('invalid-input', `${fieldArg} must be an array of RPM updates`, { field: fieldArg });
+  }
+  valueArg.forEach((update: unknown, i) => {
+    const at = `${fieldArg}[${i}]`;
+    const record = assertObject(update, at);
+    for (const key of ['id', 'from', 'status', 'type', 'version', 'title', 'severity', 'description']) {
+      assertStringField(record, key, at);
+    }
+    for (const key of ['issued', 'updated']) {
+      if (record[key] !== null) {
+        assertStringField(record, key, at);
+      }
+    }
+    assertArrayField(record, 'references', at).forEach((reference: unknown, r) => {
+      const referenceRecord = assertObject(reference, `${at}.references[${r}]`);
+      for (const key of ['href', 'id', 'title', 'type']) {
+        assertStringField(referenceRecord, key, `${at}.references[${r}]`);
+      }
+    });
+    assertArrayField(record, 'collections', at).forEach((collection: unknown, c) => {
+      const collectionAt = `${at}.collections[${c}]`;
+      const collectionRecord = assertObject(collection, collectionAt);
+      assertStringField(collectionRecord, 'short', collectionAt);
+      assertArrayField(collectionRecord, 'packages', collectionAt).forEach((pkg: unknown, p) => {
+        const pkgRecord = assertObject(pkg, `${collectionAt}.packages[${p}]`);
+        for (const key of ['name', 'version', 'release', 'arch', 'src', 'fileName']) {
+          assertStringField(pkgRecord, key, `${collectionAt}.packages[${p}]`);
+        }
+      });
+    });
+  });
+}
+
+function assertObject(valueArg: unknown, fieldArg: string): Record<string, unknown> {
+  if (valueArg === null || typeof valueArg !== 'object' || Array.isArray(valueArg)) {
+    throw new LinuxRepoError('invalid-input', `${fieldArg} must be an object`, { field: fieldArg });
+  }
+  return valueArg as Record<string, unknown>;
+}
+
+function assertStringField(recordArg: Record<string, unknown>, keyArg: string, atArg: string): void {
+  if (typeof recordArg[keyArg] !== 'string') {
+    throw new LinuxRepoError('invalid-input', `${atArg}.${keyArg} must be a string`, { field: `${atArg}.${keyArg}` });
+  }
+}
+
+function assertArrayField(recordArg: Record<string, unknown>, keyArg: string, atArg: string): unknown[] {
+  const value = recordArg[keyArg];
+  if (!Array.isArray(value)) {
+    throw new LinuxRepoError('invalid-input', `${atArg}.${keyArg} must be an array`, { field: `${atArg}.${keyArg}` });
+  }
+  return value;
+}
+
+/** Merges `incomingArg` into `targetArg` by `short`, de-duplicating packages (mutates the target only). */
+function mergeCollections(targetArg: IRpmUpdateCollection[], incomingArg: IRpmUpdateCollection[]): void {
+  for (const collection of incomingArg) {
+    let target = targetArg.find((candidate) => candidate.short === collection.short);
+    if (target === undefined) {
+      target = { short: collection.short, packages: [] };
+      targetArg.push(target);
+    }
+    for (const pkg of collection.packages) {
+      if (!target.packages.some((candidate) => samePackage(candidate, pkg))) {
+        target.packages.push(clonePackage(pkg));
+      }
+    }
+  }
+}
+
+function samePackage(aArg: IRpmUpdatePackage, bArg: IRpmUpdatePackage): boolean {
+  return aArg.name === bArg.name && aArg.version === bArg.version && aArg.release === bArg.release && aArg.arch === bArg.arch;
+}
+
+function comparePackages(aArg: IRpmUpdatePackage, bArg: IRpmUpdatePackage): number {
+  return (
+    compareCodePoints(aArg.name, bArg.name) ||
+    compareCodePoints(aArg.version, bArg.version) ||
+    compareCodePoints(aArg.release, bArg.release) ||
+    compareCodePoints(aArg.arch, bArg.arch)
+  );
+}
+
+/** Highest rank first: newest `updated`, newest `issued`, greatest canonical JSON. */
+function compareRank(aArg: IRpmUpdate, bArg: IRpmUpdate): number {
+  return (
+    compareNullableDesc(aArg.updated, bArg.updated) ||
+    compareNullableDesc(aArg.issued, bArg.issued) ||
+    compareCodePoints(canonicalScalars(bArg), canonicalScalars(aArg))
+  );
+}
+
+function compareNullableDesc(aArg: string | null, bArg: string | null): number {
+  if (aArg === bArg) {
+    return 0;
+  }
+  if (aArg === null) {
+    return 1;
+  }
+  if (bArg === null) {
+    return -1;
+  }
+  return compareCodePoints(bArg, aArg);
+}
+
+function canonicalScalars(updateArg: IRpmUpdate): string {
+  return JSON.stringify([
+    updateArg.from,
+    updateArg.status,
+    updateArg.type,
+    updateArg.version,
+    updateArg.title,
+    updateArg.severity,
+    updateArg.description,
+    updateArg.issued,
+    updateArg.updated,
+    updateArg.references.map((reference) => [reference.href, reference.id, reference.title, reference.type]),
+  ]);
+}
+
+function cloneUpdate(updateArg: IRpmUpdate): IRpmUpdate {
+  return {
+    id: updateArg.id,
+    from: updateArg.from,
+    status: updateArg.status,
+    type: updateArg.type,
+    version: updateArg.version,
+    title: updateArg.title,
+    severity: updateArg.severity,
+    description: updateArg.description,
+    issued: updateArg.issued,
+    updated: updateArg.updated,
+    references: updateArg.references.map(
+      (reference): IRpmUpdateReference => ({ href: reference.href, id: reference.id, title: reference.title, type: reference.type }),
+    ),
+    collections: updateArg.collections.map(cloneCollection),
+  };
+}
+
+function cloneCollection(collectionArg: IRpmUpdateCollection): IRpmUpdateCollection {
+  return { short: collectionArg.short, packages: collectionArg.packages.map(clonePackage) };
+}
+
+function clonePackage(pkgArg: IRpmUpdatePackage): IRpmUpdatePackage {
+  return {
+    name: pkgArg.name,
+    version: pkgArg.version,
+    release: pkgArg.release,
+    arch: pkgArg.arch,
+    src: pkgArg.src,
+    fileName: pkgArg.fileName,
+  };
+}

package/ts/rpm/xml.ts

@@ -0,0 +1,101 @@
+/**
+ * The XML output of Go's `encoding/xml` as Gitea 28.2.0 uses it: the header
+ * `xml.Header`, no indentation, no self-closing elements, attributes in struct
+ * field order, and Go's escaping (`EscapeText`/`EscapeString`): `"` and `'`
+ * become numeric references, tab, line feed and carriage return are escaped,
+ * and a code point outside the XML character range becomes U+FFFD.
+ */
+
+export const XML_HEADER = '<?xml version="1.0" encoding="UTF-8"?>\n';
+
+const NEEDS_ESCAPE = /["'&<>\u0000-\u001f\ud800-\udfff\ufffe\uffff]/;
+
+/** Go's escaping of character data and attribute values. */
+export function escapeXml(valueArg: string): string {
+  if (!NEEDS_ESCAPE.test(valueArg)) {
+    return valueArg;
+  }
+  let result = '';
+  for (const character of valueArg) {
+    const codePoint = character.codePointAt(0)!;
+    switch (character) {
+      case '"':
+        result += '&#34;';
+        break;
+      case "'":
+        result += '&#39;';
+        break;
+      case '&':
+        result += '&amp;';
+        break;
+      case '<':
+        result += '&lt;';
+        break;
+      case '>':
+        result += '&gt;';
+        break;
+      case '\t':
+        result += '&#x9;';
+        break;
+      case '\n':
+        result += '&#xA;';
+        break;
+      case '\r':
+        result += '&#xD;';
+        break;
+      default:
+        result += isXmlCharacter(codePoint) ? character : '\ufffd';
+    }
+  }
+  return result;
+}
+
+/** Go's `isInCharacterRange`. */
+function isXmlCharacter(codePointArg: number): boolean {
+  return (
+    codePointArg === 0x09 ||
+    codePointArg === 0x0a ||
+    codePointArg === 0x0d ||
+    (codePointArg >= 0x20 && codePointArg <= 0xd7ff) ||
+    (codePointArg >= 0xe000 && codePointArg <= 0xfffd) ||
+    (codePointArg >= 0x10000 && codePointArg <= 0x10ffff)
+  );
+}
+
+/** Attributes in order; a value of `undefined` is omitted (Go's `omitempty` for an empty string is the caller's choice). */
+export type TXmlAttributes = Array<[string, string | number | undefined]>;
+
+/** `<name attr="…">content</name>`, where `contentArg` is already XML. */
+export function element(nameArg: string, attributesArg: TXmlAttributes, contentArg = ''): string {
+  let start = `<${nameArg}`;
+  for (const [attribute, value] of attributesArg) {
+    if (value !== undefined) {
+      start += ` ${attribute}="${escapeXml(String(value))}"`;
+    }
+  }
+  return `${start}>${contentArg}</${nameArg}>`;
+}
+
+/** `<name>escaped text</name>`. */
+export function textElement(nameArg: string, textArg: string, attributesArg: TXmlAttributes = []): string {
+  return element(nameArg, attributesArg, escapeXml(textArg));
+}
+
+/** Go's `strings.Compare`: UTF-8 byte order, which is code point order. */
+export function compareCodePoints(aArg: string, bArg: string): number {
+  const length = Math.min(aArg.length, bArg.length);
+  for (let i = 0; i < length; i++) {
+    const a = aArg.charCodeAt(i);
+    const b = bArg.charCodeAt(i);
+    if (a !== b) {
+      // a surrogate (an astral code point) sorts after every other BMP unit
+      const aSurrogate = a >= 0xd800 && a <= 0xdfff;
+      const bSurrogate = b >= 0xd800 && b <= 0xdfff;
+      if (aSurrogate !== bSurrogate) {
+        return aSurrogate ? 1 : -1;
+      }
+      return a < b ? -1 : 1;
+    }
+  }
+  return aArg.length === bArg.length ? 0 : aArg.length < bArg.length ? -1 : 1;
+}

package/ts/shared/architecture.ts

@@ -0,0 +1,16 @@
+/**
+ * Whether an architecture can name an index path segment. Readers record any
+ * architecture a package states (Gitea accepts them); builders refuse an entry
+ * whose architecture fails this rule with `invalid-input`, and never skip it
+ * silently. Refused: the empty string, `.` and `..`, and any value containing
+ * `/`, whitespace or a control character.
+ */
+export function isIndexableArchitecture(architectureArg: string): boolean {
+  if (typeof architectureArg !== 'string') {
+    return false;
+  }
+  if (architectureArg === '' || architectureArg === '.' || architectureArg === '..') {
+    return false;
+  }
+  return !/[/\s\p{Cc}]/u.test(architectureArg);
+}