@foss.global/codefeed 4.0.0 → 4.2.0

package/ts/classes.giteasourceinventory.ts

@@ -13,6 +13,9 @@ type IInstance = plugins.fossInterfaces.data.IForgeSourceInstanceInventory;
 type TOwner = plugins.fossInterfaces.data.TForgeSourceOwnerInventory;
 type IRepository = plugins.fossInterfaces.data.IForgeSourceRepositoryInventory;
 type IPackageTypeCounts = plugins.fossInterfaces.data.IForgeSourcePackageTypeCounts;
+type IRelease = plugins.fossInterfaces.data.IForgeSourceRelease;
+type IBranchProtection = plugins.fossInterfaces.data.IForgeSourceBranchProtection;
+type ITagProtection = plugins.fossInterfaces.data.IForgeSourceTagProtection;
 type IInventory = plugins.fossInterfaces.data.IForgeSourceInventory;
 
 export interface IGiteaSourceInventoryOptions {
@@ -52,6 +55,11 @@ export interface IGiteaSourceMeasureOptions {
   onResult?: (resultArg: TUnitResult) => void | Promise<void>;
 }
 
+/** A repository read by its id: the name Gitea gives it now, or `absent` once it is deleted. */
+export type TGiteaSourceRepositoryLookup =
+  | { status: 'present'; id: string; owner: string; name: string }
+  | { status: 'absent'; id: string };
+
 interface IListing {
   items: unknown[];
   /** A sanitized reason when the listing did not finish. */
@@ -114,6 +122,35 @@ const requiredString = (valueArg: unknown): string => {
   return value;
 };
 
+/** A string the forge may leave empty, such as a release body. */
+const text = (valueArg: unknown): string => {
+  if (typeof valueArg !== 'string') throw new validation.ForgeInventoryError('invalid-string');
+  return valueArg;
+};
+
+/** A list of names; Gitea answers an empty one as `null`. */
+const texts = (valueArg: unknown): string[] => {
+  if (valueArg === null) return [];
+  if (!Array.isArray(valueArg)) throw new validation.ForgeInventoryError('invalid-string');
+  return valueArg.map(text);
+};
+
+/** A signed account id; Gitea's placeholder for a deleted account is -1. */
+const accountId = (valueArg: unknown): string => {
+  if (typeof valueArg === 'number' && Number.isSafeInteger(valueArg)) return String(valueArg);
+  throw new validation.ForgeInventoryError('invalid-or-imprecise-integer');
+};
+
+/** An RFC 3339 time as the forge reports it. */
+const requiredTimestamp = (valueArg: unknown): string => {
+  const value = validation.timestamp(valueArg);
+  if (value === null) throw new validation.ForgeInventoryError('invalid-timestamp');
+  return value;
+};
+
+/** Orders canonical nonnegative decimal strings numerically. */
+const compareDecimal = (aArg: string, bArg: string): number => aArg.length - bArg.length || compareText(aArg, bArg);
+
 /** One provider path segment, as an owner or repository name. */
 const segment = (valueArg: unknown): string => {
   const segments = validation.segments(valueArg);
@@ -137,6 +174,83 @@ const assets = (valueArg: unknown): { count: bigint; bytes: bigint } => {
   }), { count: 0n, bytes: 0n });
 };
 
+/** A release as Gitea reads it, drafts included, with its assets by numeric id. */
+const releaseRecord = (itemArg: unknown): IRelease => {
+  const item = validation.record(itemArg);
+  const author = validation.record(item.author);
+  const itemAssets = item.assets ?? [];
+  if (!Array.isArray(itemAssets)) throw new validation.ForgeInventoryError('invalid-assets');
+  return {
+    id: validation.decimal(item.id),
+    tagName: requiredString(item.tag_name),
+    targetCommitish: text(item.target_commitish),
+    name: text(item.name),
+    body: text(item.body),
+    draft: requiredBoolean(item.draft),
+    prerelease: requiredBoolean(item.prerelease),
+    createdAt: requiredTimestamp(item.created_at),
+    publishedAt: requiredTimestamp(item.published_at),
+    author: { id: accountId(author.id), login: requiredString(author.login) },
+    assets: itemAssets.map((assetArg: unknown) => {
+      const asset = validation.record(assetArg);
+      return {
+        id: validation.decimal(asset.id),
+        uuid: requiredString(asset.uuid),
+        name: requiredString(asset.name),
+        size: validation.decimal(asset.size),
+        downloadCount: validation.decimal(asset.download_count),
+        createdAt: requiredTimestamp(asset.created_at),
+      };
+    }).sort((aArg, bArg) => compareDecimal(aArg.id, bArg.id)),
+  };
+};
+
+const allowlist = (usernamesArg: unknown, teamsArg: unknown) => ({ usernames: texts(usernamesArg), teams: texts(teamsArg) });
+
+/** A branch protection rule with every restriction Gitea reads back. */
+const branchProtection = (itemArg: unknown): IBranchProtection => {
+  const item = validation.record(itemArg);
+  return {
+    ruleName: requiredString(item.rule_name),
+    priority: validation.decimal(item.priority),
+    enablePush: requiredBoolean(item.enable_push),
+    enablePushAllowlist: requiredBoolean(item.enable_push_whitelist),
+    pushAllowlist: allowlist(item.push_whitelist_usernames, item.push_whitelist_teams),
+    pushAllowlistDeployKeys: requiredBoolean(item.push_whitelist_deploy_keys),
+    enableForcePush: requiredBoolean(item.enable_force_push),
+    enableForcePushAllowlist: requiredBoolean(item.enable_force_push_allowlist),
+    forcePushAllowlist: allowlist(item.force_push_allowlist_usernames, item.force_push_allowlist_teams),
+    forcePushAllowlistDeployKeys: requiredBoolean(item.force_push_allowlist_deploy_keys),
+    enableMergeAllowlist: requiredBoolean(item.enable_merge_whitelist),
+    mergeAllowlist: allowlist(item.merge_whitelist_usernames, item.merge_whitelist_teams),
+    enableBypassAllowlist: requiredBoolean(item.enable_bypass_allowlist),
+    bypassAllowlist: allowlist(item.bypass_allowlist_usernames, item.bypass_allowlist_teams),
+    enableStatusCheck: requiredBoolean(item.enable_status_check),
+    statusCheckContexts: texts(item.status_check_contexts),
+    requiredApprovals: validation.decimal(item.required_approvals),
+    enableApprovalsAllowlist: requiredBoolean(item.enable_approvals_whitelist),
+    approvalsAllowlist: allowlist(item.approvals_whitelist_username, item.approvals_whitelist_teams),
+    blockOnRejectedReviews: requiredBoolean(item.block_on_rejected_reviews),
+    blockOnOfficialReviewRequests: requiredBoolean(item.block_on_official_review_requests),
+    blockOnOutdatedBranch: requiredBoolean(item.block_on_outdated_branch),
+    dismissStaleApprovals: requiredBoolean(item.dismiss_stale_approvals),
+    ignoreStaleApprovals: requiredBoolean(item.ignore_stale_approvals),
+    blockAdminMergeOverride: requiredBoolean(item.block_admin_merge_override),
+    requireSignedCommits: requiredBoolean(item.require_signed_commits),
+    protectedFilePatterns: text(item.protected_file_patterns),
+    unprotectedFilePatterns: text(item.unprotected_file_patterns),
+  };
+};
+
+const tagProtection = (itemArg: unknown): ITagProtection => {
+  const item = validation.record(itemArg);
+  return {
+    id: validation.decimal(item.id),
+    namePattern: requiredString(item.name_pattern),
+    allowlist: allowlist(item.whitelist_usernames, item.whitelist_teams),
+  };
+};
+
 /** A `{ <rows>, total_count }` envelope whose rows must match its total. */
 const countedEnvelope = (bodyArg: unknown, rowsKeyArg: string): { rows: unknown[]; failure: string | null } => {
   const body = validation.record(bodyArg);
@@ -217,8 +331,8 @@ export class GiteaSourceInventory {
   }
 
   /**
-   * Identifies the source and its reader and lists every owner and repository.
-   * Rejects unless the token belongs to a site administrator; a listing that
+   * Identifies the source and its reader and lists every owner and repository
+   * with its id. Rejects unless the token belongs to a site administrator; a listing that
    * does not finish, or that lists a repository id twice, is reported in
    * `incompleteReasons`.
    */
@@ -255,7 +369,7 @@ export class GiteaSourceInventory {
       const id = validation.decimal(item.id);
       if (ids.has(id)) continue;
       ids.add(id);
-      discovered.push({ owner: segment(validation.record(item.owner).login), name: segment(item.name) });
+      discovered.push({ owner: segment(validation.record(item.owner).login), name: segment(item.name), id });
     }
     if (ids.size !== repositories.items.length) incompleteReasons.push('discovery: repositories: duplicate-id');
     discovered.sort((aArg, bArg) => compareText(aArg.owner, bArg.owner) || compareText(aArg.name, bArg.name));
@@ -273,18 +387,45 @@ export class GiteaSourceInventory {
     return [
       { kind: 'instance' },
       ...discoveryArg.owners.map((ownerArg): TUnit => ({ kind: 'owner', ownerKind: ownerArg.kind, name: ownerArg.name })),
-      ...discoveryArg.repositories.map((repositoryArg): TUnit => ({ kind: 'repository', owner: repositoryArg.owner, name: repositoryArg.name })),
+      ...discoveryArg.repositories.map((repositoryArg): TUnit => ({
+        kind: 'repository', owner: repositoryArg.owner, name: repositoryArg.name, ...repositoryArg.id === undefined ? {} : { id: repositoryArg.id },
+      })),
     ];
   }
 
-  /** Measures one unit. Never rejects: a unit whose primary record cannot be read is `failed`. */
+  /**
+   * Reads a repository by its id through `GET /repositories/{id}`, which
+   * keeps answering after a rename or transfer: `present` with the name Gitea
+   * gives it now, or `absent` when Gitea answers 404, which a site
+   * administrator only gets for a deleted repository. Any other failed read
+   * rejects with its error, so it never counts as a deletion; an id that is not
+   * a canonical decimal rejects with `invalid-repository-id`.
+   */
+  public async lookupRepository(idArg: string, signalArg?: AbortSignal): Promise<TGiteaSourceRepositoryLookup> {
+    if (typeof idArg !== 'string' || !/^[1-9][0-9]{0,99}$/.test(idArg)) throw new validation.ForgeInventoryError('invalid-repository-id');
+    let item: Record<string, unknown>;
+    try {
+      item = validation.record((await this.#get(`/repositories/${idArg}`, { signal: signalArg })).body);
+    } catch (error) {
+      if (error instanceof validation.ForgeInventoryError && error.code === 'http-404') return { status: 'absent', id: idArg };
+      throw error;
+    }
+    if (validation.decimal(item.id) !== idArg) throw new validation.ForgeInventoryError('repository-identity-changed');
+    return { status: 'present', id: idArg, owner: segment(validation.record(item.owner).login), name: segment(item.name) };
+  }
+
+  /**
+   * Measures one unit. Never rejects: a unit whose primary record cannot be
+   * read is `failed`, and so is a repository unit carrying an id that its name
+   * no longer answers with (`repository-identity-changed`).
+   */
   public async measureUnit(unitArg: TUnit, signalArg?: AbortSignal): Promise<TUnitResult> {
     try {
       if (unitArg.kind === 'instance') return { kind: 'instance', instance: await this.#instance(signalArg) };
       if (unitArg.kind === 'owner') {
         return { kind: 'owner', owner: unitArg.ownerKind === 'organization' ? await this.#organization(unitArg.name, signalArg) : await this.#user(unitArg.name, signalArg) };
       }
-      return { kind: 'repository', repository: await this.#repository(unitArg.owner, unitArg.name, signalArg) };
+      return { kind: 'repository', repository: await this.#repository(unitArg.owner, unitArg.name, unitArg.id, signalArg) };
     } catch (error) {
       return { kind: 'failed', unit: unitArg, reason: reason(error) };
     }
@@ -460,11 +601,14 @@ export class GiteaSourceInventory {
     return counts;
   }
 
-  async #repository(ownerArg: string, nameArg: string, signalArg?: AbortSignal): Promise<IRepository> {
+  async #repository(ownerArg: string, nameArg: string, idArg: string | undefined, signalArg?: AbortSignal): Promise<IRepository> {
     const path = `/repos/${encodeURIComponent(ownerArg)}/${encodeURIComponent(nameArg)}`;
     const item = validation.record((await this.#get(path, { signal: signalArg })).body);
     const owner = validation.record(item.owner);
-    if (segment(owner.login) !== ownerArg || segment(item.name) !== nameArg) throw new validation.ForgeInventoryError('repository-identity-changed');
+    // A name re-created after a rename answers with another id; without a discovered id only the name is checked.
+    if (segment(owner.login) !== ownerArg || segment(item.name) !== nameArg || (idArg !== undefined && validation.decimal(item.id) !== idArg)) {
+      throw new validation.ForgeInventoryError('repository-identity-changed');
+    }
     const visibility = validation.giteaRepositoryVisibility(item.private, item.internal, owner.visibility);
     if (visibility === null) throw new validation.ForgeInventoryError('invalid-visibility');
     const empty = requiredBoolean(item.empty);
@@ -481,6 +625,8 @@ export class GiteaSourceInventory {
     const parent = item.parent === undefined || item.parent === null ? null : requiredString(validation.record(item.parent).full_name);
     if (fork !== (parent !== null)) throw new validation.ForgeInventoryError('inconsistent-fork-parent');
     const options = { signal: signalArg };
+    const branchRules = await this.#unpaged(`${path}/branch_protections`, options);
+    const tagRules = await this.#unpaged(`${path}/tag_protections`, options);
     return {
       owner: ownerArg,
       name: nameArg,
@@ -498,17 +644,21 @@ export class GiteaSourceInventory {
       ...await this.#git(ownerArg, nameArg, item, signalArg),
       collaboration: await this.#collaboration(path, features, signalArg),
       // Releases stay readable while their unit is disabled; a disabled wiki answers 404.
-      releases: await this.#releases(path, signalArg),
+      ...await this.#releases(path, signalArg),
       wikiPages: features.wiki ? await this.#count(`${path}/wiki/pages`, { ...options, missingIsEmpty: true }) : unitDisabled('wiki'),
       access: {
         collaborators: await this.#count(`${path}/collaborators`, options),
         teams: await this.#repositoryTeams(path, options),
         deployKeys: await this.#count(`${path}/keys`, options),
         webhooks: await this.#count(`${path}/hooks`, options),
-        branchProtections: await this.#unpagedCount(`${path}/branch_protections`, options),
-        tagProtections: await this.#unpagedCount(`${path}/tag_protections`, options),
+        branchProtections: branchRules.measure,
+        tagProtections: tagRules.measure,
         pushMirrors: await this.#count(`${path}/push_mirrors`, options),
       },
+      protections: branchRules.rows === null || tagRules.rows === null ? null : {
+        branches: branchRules.rows.map(branchProtection).sort((aArg, bArg) => compareText(aArg.ruleName, bArg.ruleName)),
+        tags: tagRules.rows.map(tagProtection).sort((aArg, bArg) => compareDecimal(aArg.id, bArg.id)),
+      },
       actions: await this.#actions(path, empty, signalArg),
     };
   }
@@ -620,7 +770,8 @@ export class GiteaSourceInventory {
     };
   }
 
-  async #releases(pathArg: string, signalArg?: AbortSignal): Promise<IRepository['releases']> {
+  /** The release counts, and the release records once the listing is complete. */
+  async #releases(pathArg: string, signalArg?: AbortSignal): Promise<Pick<IRepository, 'releases' | 'releaseRecords'>> {
     // An administrator's listing includes drafts.
     const releases = await this.#list(`${pathArg}/releases`, { signal: signalArg });
     let drafts = 0n;
@@ -632,10 +783,15 @@ export class GiteaSourceInventory {
       releaseAssets = { count: releaseAssets.count + itemAssets.count, bytes: releaseAssets.bytes + itemAssets.bytes };
     }
     return {
-      releases: listingMeasure(releases),
-      drafts: listingMeasure(releases, drafts),
-      assets: listingMeasure(releases, releaseAssets.count),
-      assetBytes: listingMeasure(releases, releaseAssets.bytes),
+      releases: {
+        releases: listingMeasure(releases),
+        drafts: listingMeasure(releases, drafts),
+        assets: listingMeasure(releases, releaseAssets.count),
+        assetBytes: listingMeasure(releases, releaseAssets.bytes),
+      },
+      releaseRecords: releases.failure === null
+        ? releases.items.map(releaseRecord).sort((aArg, bArg) => compareDecimal(aArg.id, bArg.id))
+        : null,
     };
   }
 
@@ -690,13 +846,18 @@ export class GiteaSourceInventory {
   }
 
   async #unpagedCount(pathArg: string, optionsArg: IListOptions): Promise<TMeasure> {
+    return (await this.#unpaged(pathArg, optionsArg)).measure;
+  }
+
+  /** A listing Gitea does not page: its count, and its rows when the read succeeded. */
+  async #unpaged(pathArg: string, optionsArg: IListOptions): Promise<{ measure: TMeasure; rows: unknown[] | null }> {
     try {
       const response = (await this.#get(pathArg, optionsArg)).body;
       const body = response === null && optionsArg.nullIsEmpty ? [] : response;
       if (!Array.isArray(body)) throw new validation.ForgeInventoryError('invalid-page');
-      return complete(body.length);
+      return { measure: complete(body.length), rows: body };
     } catch (error) {
-      return partial(0, reason(error));
+      return { measure: partial(0, reason(error)), rows: null };
     }
   }
 
@@ -784,9 +945,10 @@ const measuresOf = (valueArg: unknown, pathArg: string, outArg: Array<{ path: st
 /**
  * Composes the deterministic inventory from a discovery and its unit results.
  * Repeated results for one unit keep the last. Units without a successful
- * result, owner repository counts that disagree with discovery, and every
- * partial or unmeasured value make the inventory incomplete, with reasons
- * aggregated per subject kind, path and reason.
+ * result, a repository result for another id than discovery recorded, two
+ * repositories measured with one id, owner repository counts that disagree
+ * with discovery, and every partial or unmeasured value make the inventory
+ * incomplete, with reasons aggregated per subject kind, path and reason.
  */
 export const composeGiteaSourceInventory = (
   discoveryArg: IDiscovery,
@@ -830,12 +992,15 @@ export const composeGiteaSourceInventory = (
   const failedRepositories: string[] = [];
   for (const repository of discoveryArg.repositories) {
     const result = results.get(unitKey({ kind: 'repository', ...repository }));
-    if (result?.kind === 'repository') repositories.push(result.repository);
+    // A result for another id under the discovered name measured the repository that took the name.
+    if (result?.kind === 'repository' && (repository.id === undefined || result.repository.id === repository.id)) repositories.push(result.repository);
     else {
       failedRepositories.push(`${repository.owner}/${repository.name}`);
-      addReason(`repository: ${result?.kind === 'failed' ? `unit failed: ${result.reason}` : 'unit not measured'}`);
+      addReason(`repository: ${result?.kind === 'failed' ? `unit failed: ${result.reason}` : result?.kind === 'repository' ? 'unit failed: repository-identity-changed' : 'unit not measured'}`);
     }
   }
+  // Without discovered ids, two names measured as one id show a rename between their units.
+  if (new Set(repositories.map((repositoryArg) => repositoryArg.id)).size !== repositories.length) addReason('repository: duplicate-id');
   owners.sort((aArg, bArg) => compareText(aArg.kind, bArg.kind) || compareText(aArg.name, bArg.name));
   repositories.sort((aArg, bArg) => compareText(aArg.owner, bArg.owner) || compareText(aArg.name, bArg.name));
 

package/ts/classes.giteasourcetransfer.ts

@@ -1,6 +1,7 @@
 import * as plugins from './plugins.js';
 import * as transport from './forgeinventory.transport.js';
 import * as validation from './forgeinventory.validation.js';
+import { createTransferBounds, createTransferStream, discardBody, heldBackChunks } from './forgeinventory.transfer.js';
 import { ForgeRequestClient } from './forgeinventory.client.js';
 import { LfsBatchClient } from './classes.lfsbatchclient.js';
 import type { ILfsRequestOptions, TLfsDownload } from './classes.lfsbatchclient.js';
@@ -27,6 +28,8 @@ export interface IGiteaSourceTransferOptions {
   maxResponseBytes?: number;
   /** Wall-clock limit of one LFS object download; defaults to 30 minutes, at most six hours. */
   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;
 }
 
 /**
@@ -52,6 +55,31 @@ export interface IGiteaMirrorImportOptions {
   signal?: AbortSignal;
 }
 
+/**
+ * A release asset as the source inventory recorded it: what a download asks
+ * for and checks Gitea still holds. The download count is not part of it.
+ */
+export type TGiteaReleaseAssetSelector = Pick<plugins.fossInterfaces.data.IForgeSourceReleaseAsset, 'id' | 'uuid' | 'name' | 'size'>;
+
+export interface IGiteaReleaseAssetDownloadOptions {
+  /** Aborts the download with `request-aborted`, also while the stream is read. */
+  signal?: AbortSignal;
+}
+
+export interface IGiteaReleaseAssetDownload {
+  releaseId: string;
+  asset: TGiteaReleaseAssetSelector;
+  /**
+   * The asset's bytes, never held whole. The last chunk is held back until
+   * exactly `asset.size` bytes have arrived and both identity reads have
+   * passed again. Destroying the stream ends the download.
+   */
+  stream: InstanceType<typeof plugins.stream.Readable>;
+}
+
+/** 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}$/;
+
 export interface IGiteaMirrorImport {
   repository: plugins.TGitManagerRepositoryInfo;
   /** The repository size Gitea reported, in KiB, which sized the scratch reservation. */
@@ -61,14 +89,15 @@ 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, and verified LFS object downloads. It never
- * writes to Gitea: Git is read only through `git-upload-pack`, LFS only
- * through batch `download` requests and their download actions.
+ * 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.
  */
 export class GiteaSourceTransfer {
   readonly #options: {
     baseUrl: string; login: string; token: string; caCertificates?: string[];
-    gitTimeoutMs: number; requestTimeoutMs: number; maxResponseBytes: number; lfsTransferTimeoutMs: number;
+    gitTimeoutMs: number; requestTimeoutMs: number; maxResponseBytes: number; lfsTransferTimeoutMs: number; releaseAssetTimeoutMs: number;
   };
   readonly #client: ForgeRequestClient;
 
@@ -83,9 +112,11 @@ export class GiteaSourceTransfer {
       requestTimeoutMs: optionsArg.requestTimeoutMs ?? 60_000,
       maxResponseBytes: optionsArg.maxResponseBytes ?? 16 * 1024 * 1024,
       lfsTransferTimeoutMs: optionsArg.lfsTransferTimeoutMs ?? 30 * 60 * 1000,
+      releaseAssetTimeoutMs: optionsArg.releaseAssetTimeoutMs ?? 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],
     ] as const) {
       const value = limits[name];
       if (!Number.isSafeInteger(value) || value < 1 || value > maximum) throw new validation.ForgeInventoryError('invalid-limits');
@@ -223,6 +254,94 @@ export class GiteaSourceTransfer {
     return download;
   }
 
+  /**
+   * Downloads one release asset by GET of `/attachments/{uuid}` with the
+   * reader's `token` authorization: no redirect is followed and no range is
+   * asked for, so only a 200 answer of the whole content is accepted, and a
+   * `content-length`, when sent, must equal `asset.size`. Before the request
+   * the repository is read by its id as for `importMirror`, then the release
+   * by its id: it must still carry an asset with the same `id`, `uuid`,
+   * `name` and `size`, otherwise the download rejects with
+   * `release-asset-identity-changed` (a replaced file carries another id and
+   * uuid). The bytes stream without a digest; the last chunk is held back
+   * until exactly `size` bytes have arrived and both identity reads have
+   * passed once more, so a consumer never receives a complete asset that is
+   * short, long or no longer the recorded one. Gitea exposes no content
+   * digest; a digest the caller needs comes from the content itself.
+   *
+   * Rejects, or errors the stream, with a fixed `ForgeInventoryError` code:
+   * `invalid-repository`, `release-asset-invalid`, `request-aborted`, a REST
+   * code such as `http-404` (also for a deleted release),
+   * `repository-identity-changed`, `release-asset-identity-changed`,
+   * `http-<status>` for any answer but 200, `release-asset-size-mismatch`,
+   * `release-asset-size-overrun`, `release-asset-short-body`,
+   * `release-asset-transfer-timed-out` (after `releaseAssetTimeoutMs`, or a
+   * stall of `requestTimeoutMs`), `release-asset-download-failed`, such as
+   * for a refused redirect, or `release-asset-transfer-failed` when body bytes
+   * still arrive after the download has ended; the download ends only once
+   * the stream is destroyed or finished, and a destroyed stream reports no
+   * error, so a reader does not see this code. A failed request is explained
+   * by the identity reads as for `downloadLfsObject`.
+   */
+  public async downloadReleaseAsset(
+    repositoryArg: IGiteaSourceRepository,
+    releaseIdArg: string,
+    assetArg: TGiteaReleaseAssetSelector,
+    optionsArg: IGiteaReleaseAssetDownloadOptions = {},
+  ): Promise<IGiteaReleaseAssetDownload> {
+    const repository = this.#repository(repositoryArg);
+    const { releaseId, asset, size } = this.#releaseAssetSelector(releaseIdArg, assetArg);
+    const { signal } = optionsArg;
+    if (signal?.aborted) throw new validation.ForgeInventoryError('request-aborted');
+    await this.#releaseAssetIdentified(repository, releaseId, asset, signal);
+    const agents = transport.createNodeAgents(this.#options.caCertificates);
+    const close = () => agents.https?.destroy();
+    const transfer = createTransferBounds(signal, {
+      limitMs: this.#options.releaseAssetTimeoutMs, idleMs: this.#options.requestTimeoutMs,
+      timedOutCode: 'release-asset-transfer-timed-out', failedCode: 'release-asset-transfer-failed',
+    });
+    let body: AsyncIterable<Uint8Array>;
+    try {
+      const response = await transfer.run(() => transport.sendNodeRequest(new URL(`${this.#options.baseUrl}/attachments/${asset.uuid}`), {
+        method: 'GET', headers: { authorization: `token ${this.#options.token}` }, 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() !== asset.size) {
+        await transfer.run(() => discardBody(response.body));
+        throw new validation.ForgeInventoryError('release-asset-size-mismatch');
+      }
+      body = response.body;
+    } catch (error) {
+      const failure = transfer.failure(error, 'release-asset-download-failed');
+      transfer.end();
+      close();
+      if (signal?.aborted) throw failure;
+      return this.#releaseAssetExplained(repository, releaseId, asset, failure, signal);
+    }
+    // After the last byte, before the held chunk: the repository and the asset are still the ones asked for.
+    const identified = async () => {
+      transfer.touch();
+      await transfer.run(() => this.#releaseAssetIdentified(repository, releaseId, asset, transfer.signal));
+    };
+    const chunks = async function* (): AsyncGenerator<Uint8Array, void, undefined> {
+      try {
+        yield* heldBackChunks(transfer.watch(body), size, {
+          invalidChunk: 'release-asset-invalid-chunk', overrun: 'release-asset-size-overrun', short: 'release-asset-short-body',
+        }, { complete: identified });
+      } catch (error) {
+        throw transfer.failure(error, 'release-asset-download-failed');
+      } finally {
+        transfer.end();
+      }
+    };
+    // Destroying the stream ends the download and closes its connections at once, also while a read is pending.
+    return { releaseId, asset, stream: createTransferStream(transfer, chunks(), close) };
+  }
+
   /**
    * 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
@@ -259,6 +378,65 @@ export class GiteaSourceTransfer {
     throw errorArg;
   }
 
+  /**
+   * Reads the repository by its id, then the release by its id under the
+   * repository's name: the release must still carry the asset with its id,
+   * uuid, name and size, else `release-asset-identity-changed`. A release
+   * read that fails is explained by the repository read as for `#explained`.
+   */
+  async #releaseAssetIdentified(
+    repositoryArg: IGiteaSourceRepository, releaseIdArg: string, assetArg: TGiteaReleaseAssetSelector, signalArg: AbortSignal | undefined,
+  ): Promise<void> {
+    await this.#identified(repositoryArg, signalArg);
+    let release: Record<string, unknown>;
+    try {
+      release = validation.record((await this.#client.request(new URL(
+        `${this.#options.baseUrl}/api/v1/repos/${encodeURIComponent(repositoryArg.owner)}/${encodeURIComponent(repositoryArg.name)}/releases/${releaseIdArg}`,
+      ), { signal: signalArg })).body);
+    } catch (error) {
+      if (signalArg?.aborted) throw new validation.ForgeInventoryError('request-aborted');
+      return this.#explained(repositoryArg, error, signalArg);
+    }
+    const assets = release.assets ?? [];
+    if (validation.decimal(release.id) !== releaseIdArg || !Array.isArray(assets)) throw new validation.ForgeInventoryError('release-asset-identity-changed');
+    const found = assets.map((itemArg: unknown) => validation.record(itemArg)).find((itemArg) => validation.decimal(itemArg.id) === assetArg.id);
+    if (!found || found.uuid !== assetArg.uuid || found.name !== assetArg.name || validation.decimal(found.size) !== assetArg.size) {
+      throw new validation.ForgeInventoryError('release-asset-identity-changed');
+    }
+  }
+
+  /**
+   * Rejects with `errorArg`, a failed asset download, unless the identity
+   * reads explain it: then with `repository-identity-changed`,
+   * `release-asset-identity-changed` or `http-404`.
+   */
+  async #releaseAssetExplained(
+    repositoryArg: IGiteaSourceRepository, releaseIdArg: string, assetArg: TGiteaReleaseAssetSelector, errorArg: unknown, signalArg: AbortSignal | undefined,
+  ): Promise<never> {
+    try {
+      await this.#releaseAssetIdentified(repositoryArg, releaseIdArg, assetArg, signalArg);
+    } catch (error) {
+      if (error instanceof validation.ForgeInventoryError
+        && ['repository-identity-changed', 'release-asset-identity-changed', 'http-404'].includes(error.code)) throw error;
+    }
+    throw errorArg;
+  }
+
+  /** The release id and asset of a download request, validated; sizes beyond `Number.MAX_SAFE_INTEGER` are refused. */
+  #releaseAssetSelector(releaseIdArg: unknown, assetArg: TGiteaReleaseAssetSelector): { releaseId: string; asset: TGiteaReleaseAssetSelector; size: number } {
+    try {
+      if (typeof releaseIdArg !== 'string' || typeof assetArg?.id !== 'string' || typeof assetArg.size !== 'string') throw new Error();
+      const releaseId = validation.decimal(releaseIdArg);
+      const asset = { id: validation.decimal(assetArg.id), uuid: assetArg.uuid, name: assetArg.name, size: validation.decimal(assetArg.size) };
+      const size = Number(asset.size);
+      if (typeof asset.uuid !== 'string' || !attachmentUuidPattern.test(asset.uuid) || typeof asset.name !== 'string' || !asset.name
+        || !Number.isSafeInteger(size)) throw new Error();
+      return { releaseId, asset, size };
+    } catch {
+      throw new validation.ForgeInventoryError('release-asset-invalid');
+    }
+  }
+
   #repository(repositoryArg: IGiteaSourceRepository): IGiteaSourceRepository {
     const single = (valueArg: unknown): string => {
       const segments = validation.segments(valueArg);