@foss.global/codefeed 5.1.0 → 5.3.0

package/ts/classes.giteasourcetransfer.ts

@@ -6,6 +6,13 @@ import { ForgeRequestClient } from './forgeinventory.client.js';
 import { LfsBatchClient } from './classes.lfsbatchclient.js';
 import type { ILfsRequestOptions, TLfsDownload } from './classes.lfsbatchclient.js';
 import { giteaCloneUrl, reserveMirrorScratch } from './giteasourceinventory.git.js';
+import { cargoIndexPath, containerManifestMediaTypes, npmPackagePath, packageTypePattern, swiftPackageParts } from './giteasourceinventory.packages.js';
+import { canonicalPackageDocument, swiftManifestVersionPattern } from './giteasourcetransfer.documents.js';
+import type { TGiteaCanonicalPackageDocumentKind } from './giteasourcetransfer.documents.js';
+
+type IPackageRecord = plugins.fossInterfaces.data.IForgeSourcePackageInventory;
+type IPackageVersion = plugins.fossInterfaces.data.IForgeSourcePackageVersion;
+type IPackageBlob = plugins.fossInterfaces.data.IForgeSourcePackageBlob;
 
 export interface IGiteaSourceTransferOptions {
   /** Instance root, including an optional deployment subpath. HTTPS is required. */
@@ -30,6 +37,8 @@ export interface IGiteaSourceTransferOptions {
   lfsTransferTimeoutMs?: number;
   /** Wall-clock limit of one release asset download, its closing identity reads included; defaults to 30 minutes, at most six hours. */
   releaseAssetTimeoutMs?: number;
+  /** Wall-clock limit of one package blob or file download, its closing identity read included; defaults to 30 minutes, at most six hours. */
+  packageTransferTimeoutMs?: number;
 }
 
 /**
@@ -77,6 +86,95 @@ export interface IGiteaReleaseAssetDownload {
   stream: InstanceType<typeof plugins.stream.Readable>;
 }
 
+/** A package as the source inventory recorded it: what a read names, and the owner id it checks Gitea still holds. */
+export type TGiteaPackageSelector = Pick<IPackageRecord, 'owner' | 'ownerId' | 'type' | 'name'>;
+
+/** A version as the source inventory recorded it; its id identifies it, so a tag pushed again is another version. */
+export type TGiteaPackageVersionSelector = Pick<IPackageVersion, 'id' | 'version'>;
+
+/** Content as the source inventory recorded it: the SHA-256 and size of a blob. */
+export type TGiteaPackageContentSelector = Pick<IPackageBlob, 'sha256' | 'size'>;
+
+/** A file of a version as the source inventory recorded it: its name and the content it holds. */
+export interface IGiteaPackageFileSelector extends TGiteaPackageContentSelector {
+  name: string;
+}
+
+/**
+ * Metadata a package version carries beside its files: an npm version
+ * document, Swift release metadata, a Swift release's manifest
+ * (`Package.swift`, or an alternate `Package@swift-<v>.swift`), a crate
+ * version's line of the Cargo sparse index, or the description the Cargo
+ * search serves for a crate's latest version.
+ */
+export type TGiteaPackageDocumentKind = TGiteaCanonicalPackageDocumentKind | 'swift-manifest';
+
+export interface IGiteaPackageReadOptions {
+  /** Aborts the read with `request-aborted`, also while a stream is read. */
+  signal?: AbortSignal;
+}
+
+/** Reads an alternate Swift manifest. */
+export interface IGiteaSwiftManifestReadOptions extends IGiteaPackageReadOptions {
+  /**
+   * The Swift version Gitea keys the alternate manifest by, trimmed as its
+   * `TrimmedVersionString` writes it (`5.8`, `5.9.1`; the patch only when it
+   * is not zero).
+   */
+  swiftVersion: string;
+}
+
+/** A container manifest with the exact bytes and `Content-Type` Gitea serves. */
+export interface IGiteaContainerManifest {
+  /** `sha256:` and the hex digest the bytes were checked against. */
+  digest: string;
+  /** The `Content-Type` header verbatim: the media type the manifest was pushed with. */
+  mediaType: string;
+  bytes: Buffer;
+}
+
+/**
+ * A version's metadata document and its digest: a JSON document in its
+ * canonical form (`canonicalPackageDocument`), a Swift manifest verbatim.
+ */
+export interface IGiteaPackageDocument {
+  kind: TGiteaPackageDocumentKind;
+  /** The id of the version the identity reads before and after the read confirmed. */
+  versionId: string;
+  /**
+   * The canonical JSON for every kind but `swift-manifest`, whose bytes are
+   * the stored manifest as Gitea serves it. The bytes Gitea served for a JSON
+   * document are not returned: their key order differs from read to read.
+   */
+  bytes: Buffer;
+  /** Lowercase hex SHA-256 of `bytes`. */
+  sha256: string;
+  /** The media type Gitea declared, without parameters. */
+  mediaType: string;
+}
+
+export interface IGiteaPackageDownload {
+  content: TGiteaPackageContentSelector;
+  /**
+   * The content's bytes, never held whole. The last chunk is held back until
+   * exactly `content.size` bytes have arrived, their SHA-256 equals
+   * `content.sha256` and, for a version's file, the closing identity read has
+   * passed. Destroying the stream ends the download.
+   */
+  stream: InstanceType<typeof plugins.stream.Readable>;
+}
+
+const packageContentCodes = {
+  invalidChunk: 'package-content-invalid-chunk', overrun: 'package-content-size-overrun', short: 'package-content-short-body',
+};
+
+const sha256Hex = (bytesArg: Uint8Array): string => plugins.crypto.createHash('sha256').update(bytesArg).digest('hex');
+
+/** Entries asked of one Cargo search page; Gitea serves at most its `MAX_RESPONSE_ITEMS` (50 by default). */
+const cargoSearchPageSize = 50;
+/** Search pages read for one crate's description before `cargo-search-over-bound`: 10,000 entries at 50 a page. */
+const cargoSearchMaxPages = 200;
+
 /** Gitea names attachment content by a random UUID in canonical lowercase form. */
 const attachmentUuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 
@@ -87,19 +185,25 @@ export interface IGiteaMirrorImport {
 }
 
 /**
- * Reads a Gitea repository's Git data and LFS objects for its one-time
- * migration, with the reader's login and token: a mirror clone into a
- * GitManager the caller supplies, verified LFS object downloads and release
- * asset downloads. It never writes to Gitea: Git is read only through
- * `git-upload-pack`, LFS only through batch `download` requests and their
- * download actions, release assets only through GETs of their attachment.
+ * Reads a Gitea repository's Git data and LFS objects, and package content,
+ * for its one-time migration, with the reader's login and token: a mirror
+ * clone into a GitManager the caller supplies, verified LFS object downloads,
+ * release asset downloads, container manifests and blobs, package files and
+ * package metadata documents. It never writes to Gitea: Git is read only
+ * through `git-upload-pack`, LFS only through batch `download` requests and
+ * their download actions, release assets only through GETs of their
+ * attachment, packages only through GETs of the registries and the v1 package
+ * API.
  */
 export class GiteaSourceTransfer {
   readonly #options: {
     baseUrl: string; login: string; token: string; caCertificates?: string[];
     gitTimeoutMs: number; requestTimeoutMs: number; maxResponseBytes: number; lfsTransferTimeoutMs: number; releaseAssetTimeoutMs: number;
+    packageTransferTimeoutMs: number;
   };
   readonly #client: ForgeRequestClient;
+  /** The registry (`/v2`) takes the token as a Basic password with the reader's login. */
+  readonly #registryClient: ForgeRequestClient;
 
   constructor(optionsArg: IGiteaSourceTransferOptions) {
     const baseUrl = validation.httpUrl(optionsArg.baseUrl);
@@ -113,22 +217,34 @@ export class GiteaSourceTransfer {
       maxResponseBytes: optionsArg.maxResponseBytes ?? 16 * 1024 * 1024,
       lfsTransferTimeoutMs: optionsArg.lfsTransferTimeoutMs ?? 30 * 60 * 1000,
       releaseAssetTimeoutMs: optionsArg.releaseAssetTimeoutMs ?? 30 * 60 * 1000,
+      packageTransferTimeoutMs: optionsArg.packageTransferTimeoutMs ?? 30 * 60 * 1000,
     };
     for (const [name, maximum] of [
       ['gitTimeoutMs', 6 * 60 * 60 * 1000], ['requestTimeoutMs', 300_000], ['maxResponseBytes', 64 * 1024 * 1024], ['lfsTransferTimeoutMs', 6 * 60 * 60 * 1000],
-      ['releaseAssetTimeoutMs', 6 * 60 * 60 * 1000],
+      ['releaseAssetTimeoutMs', 6 * 60 * 60 * 1000], ['packageTransferTimeoutMs', 6 * 60 * 60 * 1000],
     ] as const) {
       const value = limits[name];
       if (!Number.isSafeInteger(value) || value < 1 || value > maximum) throw new validation.ForgeInventoryError('invalid-limits');
     }
     const caCertificates = optionsArg.caCertificates === undefined ? undefined : validation.caCertificates(optionsArg.caCertificates);
     this.#options = { baseUrl: baseUrl.replace(/\/+$/, ''), login: optionsArg.login, token: optionsArg.token, caCertificates, ...limits };
+    const requestTransport = caCertificates === undefined ? transport.globalFetchTransport : transport.createHttpsTransport(caCertificates);
     this.#client = new ForgeRequestClient({
-      transport: caCertificates === undefined ? transport.globalFetchTransport : transport.createHttpsTransport(caCertificates),
+      transport: requestTransport,
       headers: { authorization: `token ${optionsArg.token}` },
       requestTimeoutMs: limits.requestTimeoutMs,
       maxResponseBytes: limits.maxResponseBytes,
     });
+    this.#registryClient = new ForgeRequestClient({
+      transport: requestTransport,
+      headers: { authorization: this.#basicAuthorization() },
+      requestTimeoutMs: limits.requestTimeoutMs,
+      maxResponseBytes: limits.maxResponseBytes,
+    });
+  }
+
+  #basicAuthorization(): string {
+    return `Basic ${Buffer.from(`${this.#options.login}:${this.#options.token}`).toString('base64')}`;
   }
 
   /** Validated, normalized instance root; contains no credentials or API suffix. */
@@ -342,6 +458,414 @@ export class GiteaSourceTransfer {
     return { releaseId, asset, stream: createTransferStream(transfer, chunks(), close) };
   }
 
+  /**
+   * Reads one container manifest by digest from the registry with the
+   * reader's Basic credentials: its exact bytes, which must hash to `digest`
+   * (`package-manifest-digest-mismatch`), and its `Content-Type` verbatim,
+   * which must be an OCI or Docker image manifest, index or manifest list
+   * (`package-manifest-media-type-invalid`). A manifest is content-addressed,
+   * so no identity read is needed. Reading it counts a download of the version
+   * holding it, an accepted read stamp (S10 ruling, item 8).
+   */
+  public async readContainerManifest(
+    packageArg: TGiteaPackageSelector, digestArg: string, optionsArg: IGiteaPackageReadOptions = {},
+  ): Promise<IGiteaContainerManifest> {
+    const selected = this.#containerPackage(packageArg);
+    if (typeof digestArg !== 'string' || !/^sha256:[0-9a-f]{64}$/.test(digestArg)) throw new validation.ForgeInventoryError('package-content-invalid');
+    const response = await this.#registryClient.requestBytes(
+      new URL(`/v2/${selected.owner.toLowerCase()}/${selected.name}/manifests/${digestArg}`, this.#options.baseUrl),
+      { accept: containerManifestMediaTypes.join(', '), signal: optionsArg.signal },
+    );
+    const contentDigest = response.headers.get('docker-content-digest');
+    if (`sha256:${sha256Hex(response.bytes)}` !== digestArg || (contentDigest !== null && contentDigest.trim() !== digestArg)) {
+      throw new validation.ForgeInventoryError('package-manifest-digest-mismatch');
+    }
+    const mediaType = response.headers.get('content-type')?.trim() ?? '';
+    if (!containerManifestMediaTypes.includes(mediaType.toLowerCase())) throw new validation.ForgeInventoryError('package-manifest-media-type-invalid');
+    return { digest: digestArg, mediaType, bytes: response.bytes };
+  }
+
+  /**
+   * Downloads one container blob, a config or a layer, by digest from the
+   * registry with the reader's Basic credentials. The bytes stream verified:
+   * the last chunk is held back until exactly `content.size` bytes have
+   * arrived and their SHA-256 equals `content.sha256`. A blob is
+   * content-addressed, so no identity read is needed, and reading one counts
+   * no download. Rejects, or errors the stream, with a fixed code such as
+   * `http-<status>`, `package-content-size-mismatch` (a `content-length` that
+   * is not the size), `package-content-size-overrun`, `package-content-short-body`,
+   * `package-content-digest-mismatch` or `package-content-transfer-timed-out`.
+   */
+  public async downloadContainerBlob(
+    packageArg: TGiteaPackageSelector, contentArg: TGiteaPackageContentSelector, optionsArg: IGiteaPackageReadOptions = {},
+  ): Promise<IGiteaPackageDownload> {
+    const selected = this.#containerPackage(packageArg);
+    const content = this.#content(contentArg);
+    const stream = await this.#verifiedDownload(
+      new URL(`/v2/${selected.owner.toLowerCase()}/${selected.name}/blobs/sha256:${content.sha256}`, this.#options.baseUrl),
+      { authorization: this.#basicAuthorization() }, content, optionsArg.signal, null,
+    );
+    return { content: { sha256: content.sha256, size: content.size }, stream };
+  }
+
+  /**
+   * Downloads one file of a package version: a generic file, an npm tarball
+   * (`{package}/-/{version}/{file}`), a Swift source archive or a crate, by the
+   * route of the package's type with the reader's `token` authorization;
+   * container content is read with `readContainerManifest` and
+   * `downloadContainerBlob` (`package-type-unsupported`). The version is read
+   * by its id before the download and again after the last byte: it must
+   * still be the recorded version of the recorded owner, else
+   * `package-version-identity-changed`, or `http-404` once deleted. The bytes
+   * stream verified as for `downloadContainerBlob`. Reading a file counts a
+   * download of its version, an accepted read stamp (S10 ruling, item 8).
+   */
+  public async downloadPackageFile(
+    packageArg: TGiteaPackageSelector, versionArg: TGiteaPackageVersionSelector, fileArg: IGiteaPackageFileSelector, optionsArg: IGiteaPackageReadOptions = {},
+  ): Promise<IGiteaPackageDownload> {
+    const selected = this.#packageSelector(packageArg);
+    const version = this.#versionSelector(versionArg);
+    const content = this.#content(fileArg);
+    if (typeof fileArg.name !== 'string' || !fileArg.name || /[\u0000-\u001f\u007f/]/.test(fileArg.name)) throw new validation.ForgeInventoryError('package-content-invalid');
+    const registry = `${this.#options.baseUrl}/api/packages/${encodeURIComponent(selected.owner)}`;
+    const encodedVersion = encodeURIComponent(version.version);
+    let url: URL;
+    const headers: Record<string, string> = { authorization: `token ${this.#options.token}` };
+    switch (selected.type) {
+      case 'generic':
+        url = new URL(`${registry}/generic/${encodeURIComponent(selected.name)}/${encodedVersion}/${encodeURIComponent(fileArg.name)}`);
+        break;
+      case 'npm':
+        url = new URL(`${registry}/npm/${npmPackagePath(selected.name)}/-/${encodedVersion}/${encodeURIComponent(fileArg.name)}`);
+        break;
+      case 'swift': {
+        const parts = swiftPackageParts(selected.name);
+        url = new URL(`${registry}/swift/${encodeURIComponent(parts.scope)}/${encodeURIComponent(parts.name)}/${encodedVersion}.zip`);
+        headers.accept = 'application/vnd.swift.registry.v1+zip';
+        break;
+      }
+      case 'cargo':
+        url = new URL(`${registry}/cargo/api/v1/crates/${encodeURIComponent(selected.name)}/${encodedVersion}/download`);
+        break;
+      default:
+        throw new validation.ForgeInventoryError('package-type-unsupported');
+    }
+    const { signal } = optionsArg;
+    await this.#versionIdentified(selected, version, signal);
+    let stream: InstanceType<typeof plugins.stream.Readable>;
+    try {
+      stream = await this.#verifiedDownload(url, headers, content, signal, (signalArg) => this.#versionIdentified(selected, version, signalArg));
+    } catch (error) {
+      if (signal?.aborted) throw error;
+      return this.#versionExplained(selected, version, error, signal);
+    }
+    return { content: { sha256: content.sha256, size: content.size }, stream };
+  }
+
+  /**
+   * Reads one metadata document of a package version with the reader's
+   * `token` authorization, bracketed by identity reads of the version as for
+   * `downloadPackageFile`. None of these reads counts a download.
+   *
+   * - `npm-version`: the npm version document.
+   * - `swift-release`: Swift release metadata.
+   * - `swift-manifest`: the release's `Package.swift`, which must answer 200;
+   *   with `swiftVersion`, the alternate manifest Gitea keys by that version,
+   *   read without following a redirect. It resolves null only when Gitea
+   *   answers 303 to the release's own `Package.swift` URL, its way of saying
+   *   it holds no such manifest; a redirect anywhere else rejects with
+   *   `swift-manifest-redirect-unexpected`, any other status with
+   *   `http-<status>`.
+   * - `cargo-index-entry`: the version's line of the crate's sparse index;
+   *   `package-document-missing` when the index has none.
+   * - `cargo-description`: `{"description":…}` of the crate's entry in the
+   *   Cargo search (`q=<name>`, its exact name), which describes only the
+   *   version with the highest id: its `max_version` must be this version,
+   *   else `package-document-missing`, as when no entry has the name.
+   *
+   * A manifest comes back verbatim, every other document in its canonical
+   * form (`canonicalPackageDocument`, `document-not-canonical` when it has
+   * none), each with the SHA-256 of the returned bytes, which a consumer
+   * records beside the version id. A kind that does not belong to the
+   * package's type, or `swiftVersion` with another kind, rejects with
+   * `package-document-kind-invalid`, a `swiftVersion` Gitea would not key a
+   * manifest by with `swift-version-invalid`, both before any request; a
+   * document of another media type rejects with `invalid-content-type`.
+   */
+  public async readPackageDocument(
+    packageArg: TGiteaPackageSelector, versionArg: TGiteaPackageVersionSelector, kindArg: 'swift-manifest', optionsArg: IGiteaSwiftManifestReadOptions,
+  ): Promise<IGiteaPackageDocument | null>;
+  public async readPackageDocument(
+    packageArg: TGiteaPackageSelector, versionArg: TGiteaPackageVersionSelector, kindArg: TGiteaPackageDocumentKind, optionsArg?: IGiteaPackageReadOptions,
+  ): Promise<IGiteaPackageDocument>;
+  public async readPackageDocument(
+    packageArg: TGiteaPackageSelector, versionArg: TGiteaPackageVersionSelector, kindArg: TGiteaPackageDocumentKind,
+    optionsArg: IGiteaPackageReadOptions & { swiftVersion?: string } = {},
+  ): Promise<IGiteaPackageDocument | null> {
+    const selected = this.#packageSelector(packageArg);
+    const version = this.#versionSelector(versionArg);
+    const { signal, swiftVersion } = optionsArg;
+    if (swiftVersion !== undefined) {
+      if (kindArg !== 'swift-manifest') throw new validation.ForgeInventoryError('package-document-kind-invalid');
+      if (typeof swiftVersion !== 'string' || !swiftManifestVersionPattern.test(swiftVersion)) throw new validation.ForgeInventoryError('swift-version-invalid');
+    }
+    const registry = `${this.#options.baseUrl}/api/packages/${encodeURIComponent(selected.owner)}`;
+    const encodedVersion = encodeURIComponent(version.version);
+    let read: (signalArg: AbortSignal | undefined) => Promise<{ bytes: Buffer; mediaType: string } | null>;
+    if (kindArg === 'npm-version' && selected.type === 'npm') {
+      read = (signalArg) => this.#documentBytes(new URL(`${registry}/npm/${npmPackagePath(selected.name)}/${encodedVersion}`), 'application/json', 'application/json', signalArg);
+    } else if (kindArg === 'swift-release' && selected.type === 'swift') {
+      const parts = swiftPackageParts(selected.name);
+      const release = new URL(`${registry}/swift/${encodeURIComponent(parts.scope)}/${encodeURIComponent(parts.name)}/${encodedVersion}`);
+      read = (signalArg) => this.#documentBytes(release, 'application/vnd.swift.registry.v1+json', 'application/json', signalArg);
+    } else if (kindArg === 'swift-manifest' && selected.type === 'swift') {
+      const parts = swiftPackageParts(selected.name);
+      read = (signalArg) => this.#swiftManifest(selected, parts, version, swiftVersion ?? null, signalArg);
+    } else if (kindArg === 'cargo-index-entry' && selected.type === 'cargo') {
+      const url = new URL(`${registry}/cargo/${cargoIndexPath(selected.name)}`);
+      read = async (signalArg) => {
+        const index = await this.#documentBytes(url, 'text/plain', 'text/plain', signalArg);
+        let line: string | undefined;
+        try {
+          line = new TextDecoder('utf-8', { fatal: true }).decode(index.bytes).split('\n')
+            .find((lineArg) => lineArg !== '' && validation.record(JSON.parse(lineArg) as unknown).vers === version.version);
+        } catch {
+          throw new validation.ForgeInventoryError('invalid-cargo-index');
+        }
+        if (line === undefined) throw new validation.ForgeInventoryError('package-document-missing');
+        return { bytes: Buffer.from(line, 'utf8'), mediaType: index.mediaType };
+      };
+    } else if (kindArg === 'cargo-description' && selected.type === 'cargo') {
+      // Gitea's crate name rule, checked before any request.
+      void cargoIndexPath(selected.name);
+      read = (signalArg) => this.#cargoDescription(registry, selected.name, version.version, signalArg);
+    } else {
+      throw new validation.ForgeInventoryError('package-document-kind-invalid');
+    }
+    await this.#versionIdentified(selected, version, signal);
+    let document: { bytes: Buffer; mediaType: string } | null;
+    try {
+      document = await read(signal);
+    } catch (error) {
+      if (signal?.aborted) throw new validation.ForgeInventoryError('request-aborted');
+      return this.#versionExplained(selected, version, error, signal);
+    }
+    await this.#versionIdentified(selected, version, signal);
+    if (document === null) return null;
+    if (kindArg === 'swift-manifest') {
+      return { kind: kindArg, versionId: version.id, bytes: document.bytes, sha256: sha256Hex(document.bytes), mediaType: document.mediaType };
+    }
+    const canonical = canonicalPackageDocument(kindArg, document.bytes);
+    return { kind: kindArg, versionId: version.id, bytes: canonical.bytes, sha256: canonical.sha256, mediaType: document.mediaType };
+  }
+
+  /** A document's body, which must carry `mediaTypeArg`. */
+  async #documentBytes(urlArg: URL, acceptArg: string, mediaTypeArg: string, signalArg: AbortSignal | undefined): Promise<{ bytes: Buffer; mediaType: string }> {
+    const response = await this.#client.requestBytes(urlArg, { accept: acceptArg, signal: signalArg });
+    if (response.mediaType !== mediaTypeArg) throw new validation.ForgeInventoryError('invalid-content-type');
+    return { bytes: response.bytes, mediaType: mediaTypeArg };
+  }
+
+  /**
+   * A Swift release's `Package.swift`, or with `swiftVersionArg` its
+   * alternate manifest; null when Gitea redirects the alternate one to the
+   * release's own `Package.swift` (303), which is how it answers a version it
+   * holds no manifest for. No redirect is followed.
+   */
+  async #swiftManifest(
+    packageArg: TGiteaPackageSelector, partsArg: { scope: string; name: string }, versionArg: TGiteaPackageVersionSelector, swiftVersionArg: string | null,
+    signalArg: AbortSignal | undefined,
+  ): Promise<{ bytes: Buffer; mediaType: string } | null> {
+    const release = `${this.#options.baseUrl}/api/packages/${encodeURIComponent(packageArg.owner)}/swift/${encodeURIComponent(partsArg.scope)}/${
+      encodeURIComponent(partsArg.name)}/${encodeURIComponent(versionArg.version)}/Package.swift`;
+    const url = new URL(release);
+    if (swiftVersionArg !== null) url.searchParams.set('swift-version', swiftVersionArg);
+    const response = await this.#client.requestBytesOrRedirect(url, { accept: 'application/vnd.swift.registry.v1+swift', signal: signalArg });
+    if (response.kind === 'redirect') {
+      if (swiftVersionArg === null) throw new validation.ForgeInventoryError(`http-${response.status}`);
+      // Gitea's answer for a missing alternate manifest: 303 to the release's
+      // `Package.swift` under its configured root, with the owner lowercased
+      // and scope, name and version as the request named them.
+      const expected = new URL(`${this.#options.baseUrl}/api/packages/${packageArg.owner.toLowerCase()}/swift/${partsArg.scope}/${partsArg.name}/${
+        versionArg.version}/Package.swift`);
+      let location: URL | null = null;
+      try {
+        location = response.location === null ? null : new URL(response.location, url);
+      } catch {
+        location = null;
+      }
+      if (response.status !== 303 || location === null || location.href !== expected.href) {
+        throw new validation.ForgeInventoryError('swift-manifest-redirect-unexpected');
+      }
+      return null;
+    }
+    if (response.mediaType !== 'text/x-swift') throw new validation.ForgeInventoryError('invalid-content-type');
+    return { bytes: response.bytes, mediaType: 'text/x-swift' };
+  }
+
+  /**
+   * `{"description":…}` of the crate's entry in the Cargo search, read page by
+   * page until the entry with exactly `nameArg` turns up. Gitea's search
+   * matches names by substring and serves one entry per crate, describing its
+   * version with the highest id, whose version `max_version` names.
+   */
+  async #cargoDescription(registryArg: string, nameArg: string, versionArg: string, signalArg: AbortSignal | undefined): Promise<{ bytes: Buffer; mediaType: string }> {
+    let seen = 0;
+    for (let page = 1; page <= cargoSearchMaxPages; page++) {
+      const url = new URL(`${registryArg}/cargo/api/v1/crates`);
+      url.searchParams.set('q', nameArg);
+      url.searchParams.set('page', String(page));
+      url.searchParams.set('per_page', String(cargoSearchPageSize));
+      const body = validation.record((await this.#client.request(url, { signal: signalArg })).body);
+      if (!Array.isArray(body.crates)) throw new validation.ForgeInventoryError('invalid-cargo-search');
+      const total = validation.record(body.meta).total;
+      if (typeof total !== 'number' || !Number.isSafeInteger(total) || total < 0) throw new validation.ForgeInventoryError('invalid-cargo-search');
+      for (const entry of body.crates) {
+        const crate = validation.record(entry);
+        if (typeof crate.name !== 'string' || typeof crate.max_version !== 'string' || typeof crate.description !== 'string') {
+          throw new validation.ForgeInventoryError('invalid-cargo-search');
+        }
+        if (crate.name !== nameArg) continue;
+        if (crate.max_version !== versionArg) throw new validation.ForgeInventoryError('package-document-missing');
+        return { bytes: Buffer.from(JSON.stringify({ description: crate.description }), 'utf8'), mediaType: 'application/json' };
+      }
+      seen += body.crates.length;
+      if (body.crates.length === 0 || seen >= total) throw new validation.ForgeInventoryError('package-document-missing');
+    }
+    throw new validation.ForgeInventoryError('cargo-search-over-bound');
+  }
+
+  /**
+   * Streams one download verified against `contentArg`: the response must be a
+   * 200 whose `content-length`, when sent, is the size; the last chunk is held
+   * back until the size and SHA-256 match and `identifiedArg`, when given, has
+   * passed once more.
+   */
+  async #verifiedDownload(
+    urlArg: URL, headersArg: Record<string, string>, contentArg: { sha256: string; size: string; bytes: number }, signalArg: AbortSignal | undefined,
+    identifiedArg: ((signalArg: AbortSignal) => Promise<void>) | null,
+  ): Promise<InstanceType<typeof plugins.stream.Readable>> {
+    if (signalArg?.aborted) throw new validation.ForgeInventoryError('request-aborted');
+    const agents = transport.createNodeAgents(this.#options.caCertificates);
+    const close = () => agents.https?.destroy();
+    const transfer = createTransferBounds(signalArg, {
+      limitMs: this.#options.packageTransferTimeoutMs, idleMs: this.#options.requestTimeoutMs,
+      timedOutCode: 'package-content-transfer-timed-out', failedCode: 'package-content-transfer-failed',
+    });
+    let body: AsyncIterable<Uint8Array>;
+    try {
+      const response = await transfer.run(() => transport.sendNodeRequest(urlArg, { method: 'GET', headers: headersArg, signal: transfer.signal, agents }));
+      if (response.status !== 200 || !response.body) {
+        await transfer.run(() => discardBody(response.body));
+        throw new validation.ForgeInventoryError(`http-${response.status}`);
+      }
+      const length = response.headers.get('content-length');
+      if (length !== null && length.trim() !== contentArg.size) {
+        await transfer.run(() => discardBody(response.body));
+        throw new validation.ForgeInventoryError('package-content-size-mismatch');
+      }
+      body = response.body;
+    } catch (error) {
+      const failure = transfer.failure(error, 'package-content-download-failed');
+      transfer.end();
+      close();
+      throw failure;
+    }
+    const hash = plugins.crypto.createHash('sha256');
+    const complete = async () => {
+      if (hash.digest('hex') !== contentArg.sha256) throw new validation.ForgeInventoryError('package-content-digest-mismatch');
+      if (identifiedArg) {
+        transfer.touch();
+        await transfer.run(() => identifiedArg(transfer.signal));
+      }
+    };
+    const chunks = async function* (): AsyncGenerator<Uint8Array, void, undefined> {
+      try {
+        yield* heldBackChunks(transfer.watch(body), contentArg.bytes, packageContentCodes, { inspect: (chunkArg) => hash.update(chunkArg), complete });
+      } catch (error) {
+        throw transfer.failure(error, 'package-content-download-failed');
+      } finally {
+        transfer.end();
+      }
+    };
+    return createTransferStream(transfer, chunks(), close);
+  }
+
+  /**
+   * Reads the version by Gitea's v1 package API: it must still carry the
+   * recorded version id, owner id, type and name, else
+   * `package-version-identity-changed`; a deleted version answers `http-404`.
+   */
+  async #versionIdentified(packageArg: TGiteaPackageSelector, versionArg: TGiteaPackageVersionSelector, signalArg: AbortSignal | undefined): Promise<void> {
+    let record: Record<string, unknown>;
+    try {
+      record = validation.record((await this.#client.request(new URL(`${this.#options.baseUrl}/api/v1/packages/${encodeURIComponent(packageArg.owner)}/${
+        encodeURIComponent(packageArg.type)}/${encodeURIComponent(packageArg.name)}/${encodeURIComponent(versionArg.version)}`), { signal: signalArg })).body);
+    } catch (error) {
+      if (signalArg?.aborted) throw new validation.ForgeInventoryError('request-aborted');
+      throw error;
+    }
+    if (validation.decimal(record.id) !== versionArg.id || validation.decimal(validation.record(record.owner).id) !== packageArg.ownerId
+      || record.type !== packageArg.type || record.name !== packageArg.name || record.version !== versionArg.version) {
+      throw new validation.ForgeInventoryError('package-version-identity-changed');
+    }
+  }
+
+  /** Rejects with `errorArg` unless the version's identity read explains it: then with `package-version-identity-changed` or `http-404`. */
+  async #versionExplained(
+    packageArg: TGiteaPackageSelector, versionArg: TGiteaPackageVersionSelector, errorArg: unknown, signalArg: AbortSignal | undefined,
+  ): Promise<never> {
+    try {
+      await this.#versionIdentified(packageArg, versionArg, signalArg);
+    } catch (error) {
+      if (error instanceof validation.ForgeInventoryError && (error.code === 'package-version-identity-changed' || error.code === 'http-404')) throw error;
+    }
+    throw errorArg;
+  }
+
+  #packageSelector(packageArg: TGiteaPackageSelector): TGiteaPackageSelector {
+    try {
+      const segments = validation.segments(packageArg?.owner);
+      if (segments.length !== 1 || typeof packageArg.type !== 'string' || !packageTypePattern.test(packageArg.type)
+        || typeof packageArg.name !== 'string' || !packageArg.name || packageArg.name.length > 512 || /[\u0000-\u001f\u007f]/.test(packageArg.name)) throw new Error();
+      return { owner: segments[0], ownerId: validation.decimal(packageArg.ownerId), type: packageArg.type, name: packageArg.name };
+    } catch {
+      throw new validation.ForgeInventoryError('package-invalid');
+    }
+  }
+
+  /** A container package selector whose name is a registry image name, which `/v2` paths carry unencoded. */
+  #containerPackage(packageArg: TGiteaPackageSelector): TGiteaPackageSelector {
+    const selected = this.#packageSelector(packageArg);
+    if (selected.type !== 'container') throw new validation.ForgeInventoryError('package-type-unsupported');
+    if (!/^[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*(?:\/[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*)*$/.test(selected.name)) {
+      throw new validation.ForgeInventoryError('package-invalid');
+    }
+    return selected;
+  }
+
+  #versionSelector(versionArg: TGiteaPackageVersionSelector): TGiteaPackageVersionSelector {
+    try {
+      if (typeof versionArg?.version !== 'string' || !versionArg.version || /[\u0000-\u001f\u007f]/.test(versionArg.version)) throw new Error();
+      return { id: validation.decimal(versionArg.id), version: versionArg.version };
+    } catch {
+      throw new validation.ForgeInventoryError('package-version-invalid');
+    }
+  }
+
+  /** Content as recorded; sizes beyond `Number.MAX_SAFE_INTEGER` are refused. */
+  #content(contentArg: TGiteaPackageContentSelector): { sha256: string; size: string; bytes: number } {
+    try {
+      if (typeof contentArg?.sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(contentArg.sha256)) throw new Error();
+      const size = validation.decimal(contentArg.size);
+      const bytes = Number(size);
+      if (!Number.isSafeInteger(bytes)) throw new Error();
+      return { sha256: contentArg.sha256, size, bytes };
+    } catch {
+      throw new validation.ForgeInventoryError('package-content-invalid');
+    }
+  }
+
   /**
    * Reads the repository by its id and checks that Gitea still names it
    * `owner/name`, without case as Gitea looks names up: other names reject