@foss.global/codefeed 5.1.0 → 5.2.0

package/ts/classes.giteasourcetransfer.ts

@@ -6,6 +6,11 @@ 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';
+
+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 +35,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 +84,71 @@ 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, read as Gitea serves
+ * it: an npm version document, Swift release metadata, a Swift release's
+ * `Package.swift`, or a crate version's line of the Cargo sparse index.
+ */
+export type TGiteaPackageDocumentKind = 'npm-version' | 'swift-release' | 'swift-manifest' | 'cargo-index-entry';
+
+export interface IGiteaPackageReadOptions {
+  /** Aborts the read with `request-aborted`, also while a stream is read. */
+  signal?: AbortSignal;
+}
+
+/** 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 with the exact bytes Gitea serves and their digest. */
+export interface IGiteaPackageDocument {
+  kind: TGiteaPackageDocumentKind;
+  /** The id of the version the identity reads before and after the read confirmed. */
+  versionId: string;
+  /** For `cargo-index-entry`, the version's line of the sparse index without its newline. */
+  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');
+
 /** 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 +159,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 +191,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 +432,303 @@ 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`: `npm-version` (the version document of an npm
+   * package), `swift-release` (Swift release metadata), `swift-manifest` (the
+   * release's `Package.swift`) or `cargo-index-entry` (the version's line of
+   * the crate's sparse index). The bytes are returned as Gitea serves them,
+   * with their SHA-256, which a consumer records beside the version id. None
+   * of these reads counts a download. A kind that does not belong to the
+   * package's type rejects with `package-document-kind-invalid`, a document
+   * of another media type with `invalid-content-type`, and a crate version
+   * missing from the index with `package-document-missing`.
+   */
+  public async readPackageDocument(
+    packageArg: TGiteaPackageSelector, versionArg: TGiteaPackageVersionSelector, kindArg: TGiteaPackageDocumentKind, optionsArg: IGiteaPackageReadOptions = {},
+  ): Promise<IGiteaPackageDocument> {
+    const selected = this.#packageSelector(packageArg);
+    const version = this.#versionSelector(versionArg);
+    const registry = `${this.#options.baseUrl}/api/packages/${encodeURIComponent(selected.owner)}`;
+    const encodedVersion = encodeURIComponent(version.version);
+    let url: URL;
+    let accept: string;
+    let mediaType: string;
+    if (kindArg === 'npm-version' && selected.type === 'npm') {
+      [url, accept, mediaType] = [new URL(`${registry}/npm/${npmPackagePath(selected.name)}/${encodedVersion}`), 'application/json', 'application/json'];
+    } else if ((kindArg === 'swift-release' || kindArg === 'swift-manifest') && selected.type === 'swift') {
+      const parts = swiftPackageParts(selected.name);
+      const release = `${registry}/swift/${encodeURIComponent(parts.scope)}/${encodeURIComponent(parts.name)}/${encodedVersion}`;
+      [url, accept, mediaType] = kindArg === 'swift-release'
+        ? [new URL(release), 'application/vnd.swift.registry.v1+json', 'application/json']
+        : [new URL(`${release}/Package.swift`), 'application/vnd.swift.registry.v1+swift', 'text/x-swift'];
+    } else if (kindArg === 'cargo-index-entry' && selected.type === 'cargo') {
+      [url, accept, mediaType] = [new URL(`${registry}/cargo/${cargoIndexPath(selected.name)}`), 'text/plain', 'text/plain'];
+    } else {
+      throw new validation.ForgeInventoryError('package-document-kind-invalid');
+    }
+    const { signal } = optionsArg;
+    await this.#versionIdentified(selected, version, signal);
+    let response: Awaited<ReturnType<ForgeRequestClient['requestBytes']>>;
+    try {
+      response = await this.#client.requestBytes(url, { accept, signal });
+    } catch (error) {
+      if (signal?.aborted) throw new validation.ForgeInventoryError('request-aborted');
+      return this.#versionExplained(selected, version, error, signal);
+    }
+    if (response.mediaType !== mediaType) throw new validation.ForgeInventoryError('invalid-content-type');
+    let bytes = response.bytes;
+    if (kindArg === 'cargo-index-entry') {
+      let line: string | undefined;
+      try {
+        line = new TextDecoder('utf-8', { fatal: true }).decode(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');
+      bytes = Buffer.from(line, 'utf8');
+    }
+    await this.#versionIdentified(selected, version, signal);
+    return { kind: kindArg, versionId: version.id, bytes, sha256: sha256Hex(bytes), mediaType };
+  }
+
+  /**
+   * 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

package/ts/forgeinventory.client.ts

@@ -32,11 +32,39 @@ export interface IForgeJsonResponse {
   headers: transport.IForgeTransportResponse['headers'];
 }
 
+export interface IForgeBytesRequestOptions {
+  signal?: AbortSignal;
+  /** Optional lower response-body budget for this request. */
+  maxResponseBytes?: number;
+  /** Additional request headers. */
+  headers?: Record<string, string>;
+  /** Sent as `accept`; the response may carry any content type, which the caller checks. */
+  accept: string;
+}
+
+export interface IForgeBytesResponse {
+  /** The response body exactly as it arrived. */
+  bytes: Buffer;
+  /** The response's media type without parameters, lowercased; null when it sent none. */
+  mediaType: string | null;
+  headers: transport.IForgeTransportResponse['headers'];
+}
+
+interface IReadOptions {
+  signal?: AbortSignal;
+  maxResponseBytes?: number;
+  headers?: Record<string, string>;
+  accept: string;
+  /** The media type the response must carry, checked before its body is read; any when absent. */
+  requiredMediaType?: string;
+  body?: { mediaType: string; bytes: Uint8Array<ArrayBuffer> };
+}
+
 /**
- * One bounded, credential-scoped JSON read at a time, a GET or a POST with a
- * JSON body: a per-request deadline, a response-size budget and a strict JSON
- * content type. Failures surface as
- * `ForgeInventoryError` codes that never contain bodies, URLs or credentials.
+ * One bounded, credential-scoped read at a time, a GET or a POST with a JSON
+ * body: a per-request deadline, a response-size budget and, for JSON, a
+ * strict content type. Failures surface as `ForgeInventoryError` codes that
+ * never contain bodies, URLs or credentials.
  */
 export class ForgeRequestClient {
   readonly #options: IForgeRequestClientOptions;
@@ -49,6 +77,25 @@ export class ForgeRequestClient {
   public get metrics(): IForgeRequestMetrics { return { ...this.#metrics }; }
 
   public async request(url: URL, requestArg: IForgeRequestOptions = {}): Promise<IForgeJsonResponse> {
+    const mediaType = requestArg.mediaType ?? 'application/json';
+    const response = await this.#read(url, {
+      signal: requestArg.signal, maxResponseBytes: requestArg.maxResponseBytes, headers: requestArg.headers, accept: mediaType, requiredMediaType: mediaType,
+      ...(requestArg.json === undefined ? {} : { body: { mediaType, bytes: new TextEncoder().encode(JSON.stringify(requestArg.json)) } }),
+    });
+    try {
+      return { body: JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(response.bytes)) as unknown, headers: response.headers };
+    } catch {
+      throw new validation.ForgeInventoryError('request-or-json-failed');
+    }
+  }
+
+  /** A GET whose body is returned as the bytes that arrived, with the media type the response declared. */
+  public async requestBytes(url: URL, requestArg: IForgeBytesRequestOptions): Promise<IForgeBytesResponse> {
+    const response = await this.#read(url, requestArg);
+    return { bytes: response.bytes, mediaType: mediaTypeOf(response.headers), headers: response.headers };
+  }
+
+  async #read(url: URL, requestArg: IReadOptions): Promise<{ bytes: Buffer; headers: transport.IForgeTransportResponse['headers'] }> {
     const { signal } = requestArg;
     const maxBytes = requestArg.maxResponseBytes ?? this.#options.maxResponseBytes;
     if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) throw new validation.ForgeInventoryError('invalid-response-budget');
@@ -61,14 +108,16 @@ export class ForgeRequestClient {
     let bodyChunks: AsyncIterator<Uint8Array> | undefined;
     try {
       this.#metrics.requests++;
-      const mediaType = requestArg.mediaType ?? 'application/json';
-      const requestBody = requestArg.json === undefined ? undefined : new TextEncoder().encode(JSON.stringify(requestArg.json));
-      const headers = { accept: mediaType, ...(requestBody ? { 'content-type': mediaType } : {}), ...requestArg.headers, ...this.#options.headers };
-      const response = await this.#options.transport(url, headers, controller.signal, requestBody);
+      const headers = {
+        accept: requestArg.accept, ...(requestArg.body ? { 'content-type': requestArg.body.mediaType } : {}), ...requestArg.headers, ...this.#options.headers,
+      };
+      const response = await this.#options.transport(url, headers, controller.signal, requestArg.body?.bytes);
       bodyChunks = response.body?.[Symbol.asyncIterator]();
       if (response.status === 429) this.#metrics.rateLimitedRequests++;
       if (response.status !== 200) throw new validation.ForgeInventoryError(`http-${response.status}`);
-      if (response.headers.get('content-type')?.split(';')[0].trim().toLowerCase() !== mediaType || !bodyChunks) throw new validation.ForgeInventoryError('invalid-content-type');
+      if ((requestArg.requiredMediaType !== undefined && mediaTypeOf(response.headers) !== requestArg.requiredMediaType) || !bodyChunks) {
+        throw new validation.ForgeInventoryError('invalid-content-type');
+      }
       const chunks: Uint8Array[] = [];
       let bytes = 0;
       while (true) {
@@ -79,10 +128,8 @@ export class ForgeRequestClient {
         if (controller.signal.aborted || Date.now() >= deadline) throw new validation.ForgeInventoryError('request-aborted-or-timed-out');
         chunks.push(result.value);
       }
-      const text = new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks));
-      const body = JSON.parse(text) as unknown;
       if (controller.signal.aborted || Date.now() >= deadline) throw new validation.ForgeInventoryError('request-aborted-or-timed-out');
-      return { body, headers: response.headers };
+      return { bytes: Buffer.concat(chunks), headers: response.headers };
     } catch (error) {
       if (error instanceof validation.ForgeInventoryError) throw error;
       throw new validation.ForgeInventoryError(controller.signal.aborted ? 'request-aborted-or-timed-out' : 'request-or-json-failed');
@@ -93,3 +140,7 @@ export class ForgeRequestClient {
     }
   }
 }
+
+/** A response's media type without parameters, lowercased; null when it sent none. */
+const mediaTypeOf = (headersArg: transport.IForgeTransportResponse['headers']): string | null =>
+  headersArg.get('content-type')?.split(';')[0].trim().toLowerCase() || null;