@foss.global/codefeed 5.5.0 → 5.6.0

package/ts/classes.giteasourcefreeze.ts

@@ -0,0 +1,763 @@
+import * as plugins from './plugins.js';
+import * as transport from './forgeinventory.transport.js';
+import * as validation from './forgeinventory.validation.js';
+import { ForgeRequestClient } from './forgeinventory.client.js';
+import { commitinfo } from './00_commitinfo_data.js';
+
+type IQuiescenceReport = plugins.fossInterfaces.data.IForgeSourceQuiescenceReport;
+type IQuiescenceRunner = plugins.fossInterfaces.data.IForgeSourceQuiescenceRunner;
+type ICronTask = plugins.fossInterfaces.data.IForgeSourceCronTask;
+type IQueuedRun = plugins.fossInterfaces.data.IForgeSourceQueuedRun;
+type TQueuedRuns = plugins.fossInterfaces.data.TForgeSourceQueuedRuns;
+type IJobsInProgress = plugins.fossInterfaces.data.IForgeSourceJobsInProgress;
+type IFreezeOrigin = plugins.fossInterfaces.data.IForgeSourceFreezeOrigin;
+type TFreezeCanary = plugins.fossInterfaces.data.TForgeSourceFreezeHttpCanary;
+type ICanaryOutcome = plugins.fossInterfaces.data.IForgeSourceFreezeCanaryOutcome;
+type TResponseHeaders = transport.IForgeTransportResponse['headers'];
+
+/** Gitea's largest page (`MAX_RESPONSE_ITEMS`, 50 unless configured lower), which every quiescence listing asks for. */
+const quiescencePageSize = 50;
+/** Pages read per quiescence listing before it counts as unfinished. */
+const quiescenceMaxPages = 1000;
+/** The statuses Gitea 28.2.0 shows for the runs its `queued` and `pending` filters select (`services/convert/convert.go` `ToActionsStatus`). */
+const queuedRunStatuses: ReadonlySet<string> = new Set(['queued', 'pending', 'requested', 'waiting']);
+/** The header a frozen source's edge filter answers a refused request with; its value is the window's nonce. */
+const freezeMarkerHeader = 'x-gitea-freeze';
+/** The bound of every JSON body the probe reads: the preflight reads, the OCI token and LFS batch answers and a created record. */
+const probeMaxResponseBytes = 4 * 1024 * 1024;
+const lfsMediaType = 'application/vnd.git-lfs+json';
+/** Every HTTP canary the probe knows, in the order of the interfaces union. */
+const freezeCanaries: ReadonlySet<TFreezeCanary> = new Set<TFreezeCanary>([
+  'receive-pack-discovery', 'archive-get', 'issue-post', 'release-post', 'generic-package-put', 'oci-blob-upload', 'lfs-put', 'lfs-off',
+]);
+/** Action headers that set the connection or the body framing, which the probe sets itself. */
+const reservedHeaderNames: ReadonlySet<string> = new Set(['host', 'content-length', 'transfer-encoding', 'connection', 'upgrade', 'te', 'trailer', 'keep-alive', 'expect']);
+const headerNamePattern = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+const maxActionHeaders = 32;
+const maxHeaderValueLength = 8 * 1024;
+const maxHrefLength = 8 * 1024;
+/** Gitea's container upload id pattern (`routers/api/packages/api.go`, `<uuid:[-.=\w]+>`). */
+const uploadIdPattern = /^[-.=\w]{1,256}$/;
+
+const reason = (errorArg: unknown): string => errorArg instanceof validation.ForgeInventoryError ? errorArg.code : 'unexpected-error';
+
+const compareText = (aArg: string, bArg: string): number => aArg < bArg ? -1 : aArg > bArg ? 1 : 0;
+
+/** Orders canonical nonnegative decimal strings numerically. */
+const compareDecimal = (aArg: string, bArg: string): number => aArg.length - bArg.length || compareText(aArg, bArg);
+
+/** Any string the forge reports, `''` included. */
+const text = (valueArg: unknown): string => {
+  if (typeof valueArg !== 'string') throw new validation.ForgeInventoryError('invalid-string');
+  return valueArg;
+};
+
+const requiredBoolean = (valueArg: unknown): boolean => {
+  if (typeof valueArg !== 'boolean') throw new validation.ForgeInventoryError('invalid-boolean');
+  return valueArg;
+};
+
+/** One provider path segment, as an owner or repository name. */
+const segment = (valueArg: unknown): string => {
+  const segments = validation.segments(valueArg);
+  if (segments.length !== 1) throw new validation.ForgeInventoryError('invalid-path');
+  return segments[0];
+};
+
+/** A token for an `authorization` header: no whitespace or control characters. */
+const validToken = (valueArg: unknown): valueArg is string =>
+  typeof valueArg === 'string' && valueArg !== '' && !/[\s\u0000-\u001f\u007f]/.test(valueArg);
+
+/** The deadline of one request; defaults to 60 s, at most 300 s. */
+const requestTimeout = (valueArg: number | undefined): number => {
+  const value = valueArg ?? 60_000;
+  if (!Number.isSafeInteger(value) || value < 1 || value > 300_000) throw new validation.ForgeInventoryError('invalid-limits');
+  return value;
+};
+
+/** An HTTPS instance root without trailing slash, as in `IForgeSourceIdentity.baseUrl`; anything else is `invalid-options`. */
+const httpsBaseUrl = (valueArg: unknown): string => {
+  let url: string | null;
+  try {
+    url = validation.httpUrl(valueArg);
+  } catch {
+    throw new validation.ForgeInventoryError('invalid-options');
+  }
+  if (url === null || !url.startsWith('https:')) throw new validation.ForgeInventoryError('invalid-options');
+  return url.replace(/\/+$/, '');
+};
+
+/** A listing read whole: its rows, or the forge's total alone once it is past the caller's bound. */
+type TPagedRows = { status: 'complete'; rows: unknown[] } | { status: 'overBound'; total: string };
+
+/** One page of a listing: its rows and the total the forge reported with them. */
+type TPageReader = (responseArg: { body: unknown; headers: TResponseHeaders }) => { rows: unknown[]; total: string };
+
+/** A Gitea Actions envelope page: `{ <rows>: [...], total_count }`. */
+const envelope = (rowsKeyArg: string): TPageReader => (responseArg) => {
+  const body = validation.record(responseArg.body);
+  const rows = body[rowsKeyArg];
+  if (!Array.isArray(rows)) throw new validation.ForgeInventoryError('invalid-page');
+  return { rows, total: validation.decimal(body.total_count) };
+};
+
+/** A plain array page whose total is the `X-Total-Count` header. */
+const headerTotal: TPageReader = (responseArg) => {
+  if (!Array.isArray(responseArg.body)) throw new validation.ForgeInventoryError('invalid-page');
+  const total = responseArg.headers.get('x-total-count');
+  if (total === null) throw new validation.ForgeInventoryError('total-missing');
+  return { rows: responseArg.body, total: validation.decimal(total) };
+};
+
+/** The list unchanged; a key listed twice means the listing shifted under its pages. */
+const unique = <T>(itemsArg: T[], keyArg: (itemArg: T) => string, codeArg: string): T[] => {
+  if (new Set(itemsArg.map(keyArg)).size !== itemsArg.length) throw new validation.ForgeInventoryError(codeArg);
+  return itemsArg;
+};
+
+export interface IGiteaQuiescenceReaderOptions {
+  /** Operator-assigned identity of the source instance. */
+  instanceId: string;
+  /** Instance root, including an optional deployment subpath. HTTPS is required. */
+  baseUrl: string;
+  /**
+   * A site administrator's token, the connection's read-only one, retained
+   * only in this reader's memory. It is sent only to `baseUrl`, only in GET
+   * requests, and never appears in reports, reasons or errors.
+   */
+  token: string;
+  /** PEM certificates that replace the default trust store for this reader's connections. */
+  caCertificates?: string[];
+  /** Deadline of one request; defaults to 60 s, at most 300 s. */
+  requestTimeoutMs?: number;
+}
+
+/**
+ * Reads the writers of a Gitea source for a freeze proof, with GET requests
+ * and a site administrator's token only: every enabled Actions runner, the
+ * jobs in progress, the cron tasks and the runs waiting to start. It reports
+ * facts only; whether the source is quiescent is the consumer's decision.
+ */
+export class GiteaQuiescenceReader {
+  readonly #options: { instanceId: string; baseUrl: string };
+  readonly #client: ForgeRequestClient;
+
+  constructor(optionsArg: IGiteaQuiescenceReaderOptions) {
+    if (typeof optionsArg?.instanceId !== 'string' || !optionsArg.instanceId.trim() || !validToken(optionsArg.token)) {
+      throw new validation.ForgeInventoryError('invalid-options');
+    }
+    const baseUrl = httpsBaseUrl(optionsArg.baseUrl);
+    const requestTimeoutMs = requestTimeout(optionsArg.requestTimeoutMs);
+    const caCertificates = optionsArg.caCertificates === undefined ? undefined : validation.caCertificates(optionsArg.caCertificates);
+    this.#options = { instanceId: optionsArg.instanceId, baseUrl };
+    this.#client = new ForgeRequestClient({
+      transport: caCertificates === undefined ? transport.globalFetchTransport : transport.createHttpsTransport(caCertificates),
+      headers: { authorization: `token ${optionsArg.token}` },
+      requestTimeoutMs,
+      maxResponseBytes: 16 * 1024 * 1024,
+    });
+  }
+
+  /** Validated, normalized instance root; contains no credentials or API suffix. */
+  public get baseUrl(): string { return this.#options.baseUrl; }
+
+  /**
+   * Reads the report. Rejects unless the token belongs to a site
+   * administrator (`reader-not-site-admin`) and the forge reports a version;
+   * a part whose read does not finish is null, with `<part>: <code>` in
+   * `incompleteReasons`. Queued runs past
+   * `forgeSourceQuiescenceQueuedRunMaxRecords` are `overBound` with the
+   * forge's count and are not read further. An abort rejects with
+   * `request-aborted`.
+   */
+  public async read(signalArg?: AbortSignal): Promise<IQuiescenceReport> {
+    const reader = validation.record((await this.#get('/user', [], signalArg)).body);
+    if (reader.is_admin !== true) throw new validation.ForgeInventoryError('reader-not-site-admin');
+    const version = validation.record((await this.#get('/version', [], signalArg)).body).version;
+    if (typeof version !== 'string' || version.length > 128 || !/^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9][A-Za-z0-9.+-]*)?$/.test(version)) {
+      throw new validation.ForgeInventoryError('invalid-server-version');
+    }
+    const incompleteReasons: string[] = [];
+    const part = async <T>(nameArg: string, readArg: () => Promise<T>): Promise<T | null> => {
+      try {
+        return await readArg();
+      } catch (error) {
+        if (signalArg?.aborted) throw new validation.ForgeInventoryError('request-aborted');
+        incompleteReasons.push(`${nameArg}: ${reason(error)}`);
+        return null;
+      }
+    };
+    const enabledRunners = await part('enabledRunners', () => this.#enabledRunners(signalArg));
+    const jobsInProgress = await part('jobsInProgress', () => this.#jobsInProgress(signalArg));
+    const cron = await part('cron', () => this.#cron(signalArg));
+    const queuedRuns = await part('queuedRuns', () => this.#queuedRuns(signalArg));
+    return {
+      generator: { package: commitinfo.name, version: commitinfo.version },
+      source: { instanceId: this.#options.instanceId, kind: 'gitea', baseUrl: this.#options.baseUrl, version },
+      enabledRunners,
+      jobsInProgress,
+      cron,
+      queuedRuns,
+      incompleteReasons: incompleteReasons.sort(compareText),
+    };
+  }
+
+  /** Runners of every scope with `disabled=false`, every page until the forge's `total_count` is covered. */
+  async #enabledRunners(signalArg?: AbortSignal): Promise<IQuiescenceRunner[]> {
+    const listing = await this.#pages('/admin/actions/runners', [['disabled', 'false']], envelope('runners'), null, signalArg);
+    if (listing.status !== 'complete') throw new validation.ForgeInventoryError('invalid-page');
+    const runners = listing.rows.map((rowArg) => {
+      const row = validation.record(rowArg);
+      // A disabled runner in this listing means the forge ignored the filter, so the list is not the one asked for.
+      if (row.disabled !== false) throw new validation.ForgeInventoryError('runner-filter-ignored');
+      return { id: validation.decimal(row.id), name: text(row.name), status: text(row.status), busy: requiredBoolean(row.busy) };
+    });
+    return unique(runners, (runnerArg) => runnerArg.id, 'duplicate-id').sort((aArg, bArg) => compareDecimal(aArg.id, bArg.id));
+  }
+
+  /** The forge's count of jobs its `in_progress` filter selects; Gitea's cancelling jobs are in no filter. */
+  async #jobsInProgress(signalArg?: AbortSignal): Promise<IJobsInProgress> {
+    const body = validation.record((await this.#get('/admin/actions/jobs', [['status', 'in_progress'], ['limit', '1'], ['page', '1']], signalArg)).body);
+    if (!Array.isArray(body.jobs) || body.jobs.length > 1) throw new validation.ForgeInventoryError('invalid-page');
+    // A listed job in another state means the forge ignored the filter, so its total counts something else.
+    if (body.jobs.some((jobArg) => validation.record(jobArg).status !== 'in_progress')) throw new validation.ForgeInventoryError('job-filter-ignored');
+    return { total: validation.decimal(body.total_count), blindSpot: 'cancelling' };
+  }
+
+  async #cron(signalArg?: AbortSignal): Promise<ICronTask[]> {
+    const listing = await this.#pages('/admin/cron', [], headerTotal, null, signalArg);
+    if (listing.status !== 'complete') throw new validation.ForgeInventoryError('invalid-page');
+    const tasks = listing.rows.map((rowArg) => {
+      const row = validation.record(rowArg);
+      return { name: text(row.name), schedule: text(row.schedule) };
+    });
+    return unique(tasks, (taskArg) => taskArg.name, 'duplicate-name').sort((aArg, bArg) => compareText(aArg.name, bArg.name));
+  }
+
+  /** Runs the forge lists as queued or pending, in one listing of both status filters. */
+  async #queuedRuns(signalArg?: AbortSignal): Promise<TQueuedRuns> {
+    const listing = await this.#pages('/admin/actions/runs', [['status', 'queued'], ['status', 'pending']], envelope('workflow_runs'),
+      plugins.fossInterfaces.data.forgeSourceQuiescenceQueuedRunMaxRecords, signalArg);
+    if (listing.status === 'overBound') return listing;
+    const runs = listing.rows.map((rowArg): IQueuedRun => {
+      const row = validation.record(rowArg);
+      const status = text(row.status);
+      // A run in another state means the forge ignored the filter, so the list is not the one asked for.
+      if (!queuedRunStatuses.has(status)) throw new validation.ForgeInventoryError('run-filter-ignored');
+      // Gitea 28.2.0 reports the run's own `repository_id` as 0; the embedded repository carries the id and the name.
+      const repository = validation.record(row.repository);
+      const fullName = validation.segments(repository.full_name);
+      if (fullName.length !== 2) throw new validation.ForgeInventoryError('invalid-path');
+      return {
+        id: validation.decimal(row.id),
+        runNumber: validation.decimal(row.run_number),
+        repositoryId: validation.decimal(repository.id),
+        repository: fullName.join('/'),
+        event: text(row.event),
+        // Omitted while empty, as for a run on a tag.
+        ref: row.head_branch === undefined ? '' : text(row.head_branch),
+        sha: text(row.head_sha),
+        status,
+      };
+    });
+    return { status: 'complete', runs: unique(runs, (runArg) => runArg.id, 'duplicate-id').sort((aArg, bArg) => compareDecimal(aArg.id, bArg.id)) };
+  }
+
+  /**
+   * Reads every page of a listing at Gitea's largest page size until its
+   * rows cover the total the forge reports with every page. Rejects when a
+   * page fails or is malformed (`invalid-page`), the total changes between
+   * pages (`total-changed`), a page ends the listing early or the rows
+   * overrun the total (`count-mismatch`), or the page bound is reached
+   * (`page-limit`). With `maxRowsArg`, a first page reporting a larger total
+   * ends the listing as `overBound`.
+   */
+  async #pages(pathArg: string, queryArg: Array<[string, string]>, pageArg: TPageReader, maxRowsArg: number | null, signalArg?: AbortSignal): Promise<TPagedRows> {
+    const rows: unknown[] = [];
+    let total: bigint | null = null;
+    for (let page = 1; ; page++) {
+      if (page > quiescenceMaxPages) throw new validation.ForgeInventoryError('page-limit');
+      const answer = pageArg(await this.#get(pathArg, [...queryArg, ['limit', String(quiescencePageSize)], ['page', String(page)]], signalArg));
+      if (answer.rows.length > quiescencePageSize) throw new validation.ForgeInventoryError('invalid-page');
+      const pageTotal = BigInt(answer.total);
+      if (total !== null && pageTotal !== total) throw new validation.ForgeInventoryError('total-changed');
+      total = pageTotal;
+      if (maxRowsArg !== null && total > BigInt(maxRowsArg)) return { status: 'overBound', total: answer.total };
+      if (answer.rows.length === 0) break;
+      rows.push(...answer.rows);
+      if (BigInt(rows.length) >= total) break;
+    }
+    if (BigInt(rows.length) !== total) throw new validation.ForgeInventoryError('count-mismatch');
+    return { status: 'complete', rows };
+  }
+
+  #get(pathArg: string, queryArg: Array<[string, string]>, signalArg?: AbortSignal) {
+    const url = new URL(`${this.#options.baseUrl}/api/v1${pathArg}`);
+    for (const [key, value] of queryArg) url.searchParams.append(key, value);
+    return this.#client.request(url, { signal: signalArg });
+  }
+}
+
+export interface IGiteaFreezeProbeOptions {
+  /**
+   * The canary credential's token, never the connection's administrator
+   * token, retained only in this probe's memory: a restricted,
+   * non-administrator account whose only organization is the canary
+   * repository's owner and whose only repository is the canary repository.
+   * It is sent only to the origins of a run and never appears in outcomes or
+   * errors.
+   */
+  token: string;
+  /** The canary repository; its owner is the canary organization, and its generic and container packages carry its name. */
+  repository: { owner: string; name: string };
+  /** PEM certificates that replace the default trust store for the probe's connections. */
+  caCertificates?: string[];
+  /** Deadline of one request, its response body included; defaults to 60 s, at most 300 s. */
+  requestTimeoutMs?: number;
+}
+
+export interface IGiteaFreezeProbeRunOptions {
+  /** The network paths to send the canaries through, each at most once; all must reach the same instance. */
+  origins: IFreezeOrigin[];
+  /** The canaries each origin gets, in order, each at most once: the consumer's canary configuration. */
+  canaries: TFreezeCanary[];
+  signal?: AbortSignal;
+}
+
+/** What the preflight read through one origin. */
+interface IPreflight {
+  /** The canary account's id and login. */
+  userId: string;
+  login: string;
+  /** The canary repository's id and default branch. */
+  repositoryId: string;
+  defaultBranch: string;
+}
+
+/** One origin of a run: its normalized form, its root, the agents that reach it and its preflight. */
+interface IOriginContext extends IPreflight {
+  origin: IFreezeOrigin;
+  /** `baseUrl` without trailing slash. */
+  base: string;
+  agents: transport.INodeRequestAgents;
+}
+
+interface IProbeRequest {
+  method: 'GET' | 'POST' | 'PUT';
+  url: URL;
+  headers: Record<string, string>;
+  body?: Uint8Array<ArrayBuffer>;
+}
+
+/** What a canary's own request answered, before it becomes an outcome. */
+type TCanaryResult = Omit<ICanaryOutcome, 'canary' | 'origin'>;
+
+/** A canary object: fresh bytes naming the nonce, their SHA-256 and size. */
+const canaryObject = (nonceArg: string) => {
+  const bytes = new TextEncoder().encode(`freeze canary ${nonceArg}\n`);
+  return { bytes, oid: plugins.crypto.createHash('sha256').update(bytes).digest('hex'), size: bytes.byteLength };
+};
+
+const utf8Json = (bytesArg: Buffer): unknown => JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytesArg));
+
+/** A failed step: no status, no marker, nothing written. */
+const failed = (errorCodeArg: string): TCanaryResult => ({ httpStatus: null, freezeMarker: null, wrote: null, errorCode: errorCodeArg });
+
+/**
+ * Sends a Gitea source's HTTP freeze canaries for a freeze proof, with the
+ * canary credential only. Before any write it reads `/user`, `/user/orgs` and
+ * `/user/repos` through every origin of the run and refuses a credential that
+ * reaches more than the canary repository (`canary-credential-overbroad`).
+ * Each canary targets the canary repository or its packages, and every write
+ * carries a fresh nonce. It reports what each canary's own request answered:
+ * the status, the `X-Gitea-Freeze` header verbatim and what a 2xx created. It
+ * never returns a response body or a credential, never follows a redirect and
+ * never judges the marker.
+ */
+export class GiteaFreezeProbe {
+  readonly #options: { token: string; owner: string; name: string; caCertificates?: string[]; requestTimeoutMs: number };
+
+  constructor(optionsArg: IGiteaFreezeProbeOptions) {
+    if (!validToken(optionsArg?.token)) throw new validation.ForgeInventoryError('invalid-options');
+    let owner: string;
+    let name: string;
+    try {
+      owner = segment(optionsArg.repository?.owner);
+      name = segment(optionsArg.repository?.name);
+    } catch {
+      throw new validation.ForgeInventoryError('invalid-options');
+    }
+    const caCertificates = optionsArg.caCertificates === undefined ? undefined : validation.caCertificates(optionsArg.caCertificates);
+    this.#options = { token: optionsArg.token, owner, name, caCertificates, requestTimeoutMs: requestTimeout(optionsArg.requestTimeoutMs) };
+  }
+
+  /**
+   * Runs the preflight through every origin, then sends each canary through
+   * each origin, origins and canaries in the order given, and returns one
+   * outcome per pair. A preflight that does not pass rejects before any
+   * canary is sent: `canary-credential-overbroad` when the account is an
+   * administrator, is not restricted, or reaches another organization or
+   * repository; `canary-credential-mismatch` when it reaches no organization
+   * or repository at all; `canary-origin-mismatch` when two origins name a
+   * different account or canary repository id; a failed read with its code.
+   * An abort rejects with `request-aborted`; every other failure is an
+   * outcome's `errorCode`.
+   */
+  public async run(optionsArg: IGiteaFreezeProbeRunOptions): Promise<ICanaryOutcome[]> {
+    const origins = this.#origins(optionsArg?.origins);
+    const canaries: unknown = optionsArg.canaries;
+    if (!Array.isArray(canaries) || canaries.length === 0 || new Set(canaries).size !== canaries.length ||
+      canaries.some((canaryArg) => !freezeCanaries.has(canaryArg))) {
+      throw new validation.ForgeInventoryError('invalid-options');
+    }
+    const signal = optionsArg.signal;
+    const aborted = () => {
+      if (signal?.aborted) throw new validation.ForgeInventoryError('request-aborted');
+    };
+    aborted();
+    const agents = origins.map((originArg) => transport.createNodeAgents(this.#options.caCertificates, false, originArg.connectAddress));
+    try {
+      const contexts: IOriginContext[] = [];
+      for (const [index, origin] of origins.entries()) {
+        const preflight = await this.#preflight(origin.baseUrl, agents[index], signal).catch((error: unknown) => {
+          aborted();
+          throw error;
+        });
+        contexts.push({ origin, base: origin.baseUrl, agents: agents[index], ...preflight });
+      }
+      // Every origin is a path to one instance, so each must show the same account and the same canary repository.
+      if (contexts.some((contextArg) => contextArg.userId !== contexts[0].userId || contextArg.repositoryId !== contexts[0].repositoryId)) {
+        throw new validation.ForgeInventoryError('canary-origin-mismatch');
+      }
+      const outcomes: ICanaryOutcome[] = [];
+      for (const context of contexts) {
+        for (const canary of canaries as TFreezeCanary[]) {
+          const result = await this.#canary(context, canary, signal);
+          aborted();
+          outcomes.push({ canary, origin: { ...context.origin }, ...result });
+        }
+      }
+      return outcomes;
+    } finally {
+      for (const agent of agents) agent.https?.destroy();
+    }
+  }
+
+  /** Validated origins, each normalized and at most once. */
+  #origins(originsArg: unknown): IFreezeOrigin[] {
+    if (!Array.isArray(originsArg) || originsArg.length === 0) throw new validation.ForgeInventoryError('invalid-options');
+    const origins = originsArg.map((originArg: unknown): IFreezeOrigin => {
+      let origin: Record<string, unknown>;
+      try {
+        origin = validation.record(originArg);
+      } catch {
+        throw new validation.ForgeInventoryError('invalid-options');
+      }
+      const baseUrl = httpsBaseUrl(origin.baseUrl);
+      if (origin.connectAddress === undefined) return { baseUrl };
+      const host = new URL(baseUrl).hostname.replace(/^\[|\]$/g, '');
+      // A connect address replaces the DNS answer for a name; an IP literal host has none to replace.
+      if (typeof origin.connectAddress !== 'string' || plugins.net.isIP(origin.connectAddress) === 0 || plugins.net.isIP(host) !== 0) {
+        throw new validation.ForgeInventoryError('invalid-options');
+      }
+      return { baseUrl, connectAddress: origin.connectAddress };
+    });
+    const keys = new Set(origins.map((originArg) => `${originArg.baseUrl} ${originArg.connectAddress ?? ''}`));
+    if (keys.size !== origins.length) throw new validation.ForgeInventoryError('invalid-options');
+    return origins;
+  }
+
+  /**
+   * Reads, with the token as a REST credential, the account (`is_admin`
+   * false, `restricted` true), its organizations (exactly the canary
+   * organization) and its repositories (exactly the canary repository).
+   * Both listings must carry Gitea's `X-Total-Count`.
+   */
+  async #preflight(baseArg: string, agentsArg: transport.INodeRequestAgents, signalArg?: AbortSignal): Promise<IPreflight> {
+    const client = new ForgeRequestClient({
+      transport: transport.createAgentTransport(agentsArg),
+      headers: { authorization: `token ${this.#options.token}` },
+      requestTimeoutMs: this.#options.requestTimeoutMs,
+      maxResponseBytes: probeMaxResponseBytes,
+    });
+    const api = (pathArg: string, pagedArg: boolean) => {
+      const url = new URL(`${baseArg}/api/v1${pathArg}`);
+      // Two rows show whether there is more than one.
+      if (pagedArg) url.search = new URLSearchParams({ limit: '2', page: '1' }).toString();
+      return url;
+    };
+    const user = validation.record((await client.request(api('/user', false), { signal: signalArg })).body);
+    if (user.is_admin !== false || user.restricted !== true) throw new validation.ForgeInventoryError('canary-credential-overbroad');
+    const userId = validation.decimal(user.id);
+    const login = segment(user.login);
+    const only = async (pathArg: string, matchesArg: (rowArg: Record<string, unknown>) => boolean): Promise<Record<string, unknown>> => {
+      const response = await client.request(api(pathArg, true), { signal: signalArg });
+      if (!Array.isArray(response.body)) throw new validation.ForgeInventoryError('invalid-page');
+      const totalHeader = response.headers.get('x-total-count');
+      if (totalHeader === null) throw new validation.ForgeInventoryError('total-missing');
+      const total = BigInt(validation.decimal(totalHeader));
+      if (total > 1n) throw new validation.ForgeInventoryError('canary-credential-overbroad');
+      if (BigInt(response.body.length) !== total) throw new validation.ForgeInventoryError('count-mismatch');
+      if (total === 0n) throw new validation.ForgeInventoryError('canary-credential-mismatch');
+      const row = validation.record(response.body[0]);
+      if (!matchesArg(row)) throw new validation.ForgeInventoryError('canary-credential-overbroad');
+      return row;
+    };
+    await only('/user/orgs', (rowArg) => rowArg.name === this.#options.owner);
+    const repository = await only('/user/repos', (rowArg) =>
+      typeof rowArg.owner === 'object' && rowArg.owner !== null && (rowArg.owner as Record<string, unknown>).login === this.#options.owner &&
+      rowArg.name === this.#options.name);
+    const defaultBranch = validation.optionalString(repository.default_branch);
+    if (defaultBranch === null || defaultBranch.split('/').some((partArg) => !partArg || partArg === '.' || partArg === '..')) {
+      throw new validation.ForgeInventoryError('invalid-default-branch');
+    }
+    return { userId, login, repositoryId: validation.decimal(repository.id), defaultBranch };
+  }
+
+  async #canary(contextArg: IOriginContext, canaryArg: TFreezeCanary, signalArg?: AbortSignal): Promise<TCanaryResult> {
+    const { owner, name } = this.#options;
+    const repositoryPath = `${encodeURIComponent(owner)}/${encodeURIComponent(name)}`;
+    const api = `${contextArg.base}/api/v1/repos/${repositoryPath}`;
+    const rest = { authorization: `token ${this.#options.token}` };
+    const basic = { authorization: `Basic ${Buffer.from(`${contextArg.login}:${this.#options.token}`).toString('base64')}` };
+    const json = (valueArg: unknown) => ({ body: new TextEncoder().encode(JSON.stringify(valueArg)), headers: { accept: 'application/json', 'content-type': 'application/json' } });
+    const nonce = plugins.crypto.randomBytes(16).toString('hex');
+    switch (canaryArg) {
+      case 'receive-pack-discovery':
+        return this.#send(contextArg, {
+          method: 'GET', url: new URL(`${contextArg.base}/${repositoryPath}.git/info/refs?service=git-receive-pack`), headers: { ...basic },
+        }, null, signalArg);
+      case 'archive-get': {
+        const archive = `${contextArg.defaultBranch}.zip`;
+        return this.#send(contextArg, {
+          method: 'GET', url: new URL(`${api}/archive/${archive.split('/').map(encodeURIComponent).join('/')}`), headers: { ...rest },
+        }, async () => archive, signalArg);
+      }
+      case 'issue-post': {
+        const request = json({ title: `Freeze canary ${nonce}`, body: 'A freeze proof canary.' });
+        return this.#send(contextArg, { method: 'POST', url: new URL(`${api}/issues`), headers: { ...request.headers, ...rest }, body: request.body },
+          async (readArg) => validation.decimal(validation.record(utf8Json(await readArg())).number), signalArg);
+      }
+      case 'release-post': {
+        const request = json({
+          tag_name: `freeze-canary-${nonce}`, target_commitish: contextArg.defaultBranch, name: `Freeze canary ${nonce}`, body: '', draft: false, prerelease: false,
+        });
+        return this.#send(contextArg, { method: 'POST', url: new URL(`${api}/releases`), headers: { ...request.headers, ...rest }, body: request.body },
+          async (readArg) => validation.decimal(validation.record(utf8Json(await readArg())).id), signalArg);
+      }
+      case 'generic-package-put': {
+        const object = canaryObject(nonce);
+        return this.#send(contextArg, {
+          method: 'PUT', url: new URL(`${contextArg.base}/api/packages/${encodeURIComponent(owner)}/generic/${encodeURIComponent(name)}/${nonce}/canary.txt`),
+          headers: { ...basic, 'content-type': 'application/octet-stream', 'content-length': String(object.size) }, body: object.bytes,
+        }, async () => nonce, signalArg);
+      }
+      case 'oci-blob-upload':
+        return this.#ociBlobUpload(contextArg, basic, signalArg);
+      case 'lfs-put':
+        return this.#lfsPut(contextArg, basic, canaryObject(nonce), signalArg);
+      case 'lfs-off':
+        return this.#send(contextArg, this.#lfsBatch(contextArg, basic, canaryObject(nonce)), null, signalArg);
+    }
+  }
+
+  /** The registry token `GET`, then the upload `POST` with it; a failed token read is the outcome's `errorCode` alone. */
+  async #ociBlobUpload(contextArg: IOriginContext, basicArg: Record<string, string>, signalArg?: AbortSignal): Promise<TCanaryResult> {
+    const { owner, name } = this.#options;
+    // `/v2` sits at the origin's root, whatever the instance's subpath.
+    const root = new URL(contextArg.base).origin;
+    let registryToken: string;
+    try {
+      registryToken = await this.#exchange(contextArg, {
+        method: 'GET', url: new URL(`${root}/v2/token`), headers: { ...basicArg, accept: 'application/json' },
+      }, signalArg, async (responseArg, readArg) => {
+        if (responseArg.status !== 200) throw new validation.ForgeInventoryError(`http-${responseArg.status}`);
+        let value: unknown;
+        try {
+          value = validation.record(utf8Json(await readArg())).token;
+        } catch {
+          throw new validation.ForgeInventoryError('invalid-token-response');
+        }
+        if (!validToken(value)) throw new validation.ForgeInventoryError('invalid-token-response');
+        return value;
+      });
+    } catch (error) {
+      if (signalArg?.aborted) return failed('request-aborted');
+      return failed(`oci-token: ${reason(error)}`);
+    }
+    return this.#send(contextArg, {
+      method: 'POST', url: new URL(`${root}/v2/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/blobs/uploads/`),
+      headers: { authorization: `Bearer ${registryToken}`, 'content-length': '0' }, body: new Uint8Array(0),
+    }, async (_readArg, headersArg) => {
+      const uploadId = headersArg.get('docker-upload-uuid');
+      if (uploadId === null || !uploadIdPattern.test(uploadId)) throw new validation.ForgeInventoryError('invalid-upload-id');
+      return uploadId;
+    }, signalArg);
+  }
+
+  /**
+   * The batch `upload` request for a fresh object, then the object `PUT` to
+   * the upload action with the action's headers only. The action must point
+   * at the origin the batch went to; a failed batch is the outcome's
+   * `errorCode` alone.
+   */
+  async #lfsPut(contextArg: IOriginContext, basicArg: Record<string, string>, objectArg: ReturnType<typeof canaryObject>, signalArg?: AbortSignal): Promise<TCanaryResult> {
+    let action: { href: URL; headers: Record<string, string> };
+    try {
+      action = await this.#exchange(contextArg, this.#lfsBatch(contextArg, basicArg, objectArg), signalArg, async (responseArg, readArg) => {
+        if (responseArg.status !== 200) throw new validation.ForgeInventoryError(`http-${responseArg.status}`);
+        let upload: unknown;
+        try {
+          const objects = validation.record(utf8Json(await readArg())).objects;
+          if (!Array.isArray(objects) || objects.length !== 1) throw new Error('objects');
+          const object = validation.record(objects[0]);
+          if (object.oid !== objectArg.oid || object.size !== objectArg.size || (object.error !== undefined && object.error !== null)) throw new Error('object');
+          upload = object.actions === undefined || object.actions === null ? undefined : validation.record(object.actions).upload;
+        } catch {
+          throw new validation.ForgeInventoryError('invalid-batch-response');
+        }
+        // A fresh object the forge already holds would mean the nonce was not fresh, so the canary wrote nothing.
+        if (upload === undefined || upload === null) throw new validation.ForgeInventoryError('upload-action-missing');
+        return uploadAction(upload, contextArg.base);
+      });
+    } catch (error) {
+      if (signalArg?.aborted) return failed('request-aborted');
+      return failed(`lfs-batch: ${reason(error)}`);
+    }
+    return this.#send(contextArg, {
+      method: 'PUT', url: action.href,
+      headers: { ...action.headers, 'content-type': 'application/octet-stream', 'content-length': String(objectArg.size) }, body: objectArg.bytes,
+    }, async () => objectArg.oid, signalArg);
+  }
+
+  #lfsBatch(contextArg: IOriginContext, basicArg: Record<string, string>, objectArg: ReturnType<typeof canaryObject>): IProbeRequest {
+    const { owner, name } = this.#options;
+    return {
+      method: 'POST', url: new URL(`${contextArg.base}/${encodeURIComponent(owner)}/${encodeURIComponent(name)}.git/info/lfs/objects/batch`),
+      headers: { ...basicArg, accept: lfsMediaType, 'content-type': lfsMediaType },
+      body: new TextEncoder().encode(JSON.stringify({ operation: 'upload', transfers: ['basic'], objects: [{ oid: objectArg.oid, size: objectArg.size }] })),
+    };
+  }
+
+  /**
+   * Sends a canary's own request and reports its status and marker. On a 2xx,
+   * `createdArg` reads what it created; null means the canary creates
+   * nothing. A 2xx whose identity cannot be read keeps its status and marker
+   * with `created-identity-unreadable`.
+   */
+  async #send(
+    contextArg: IOriginContext, requestArg: IProbeRequest,
+    createdArg: ((readArg: () => Promise<Buffer>, headersArg: TResponseHeaders) => Promise<string>) | null, signalArg?: AbortSignal,
+  ): Promise<TCanaryResult> {
+    try {
+      return await this.#exchange(contextArg, requestArg, signalArg, async (responseArg, readArg): Promise<TCanaryResult> => {
+        const httpStatus = responseArg.status;
+        const freezeMarker = responseArg.headers.get(freezeMarkerHeader);
+        if (httpStatus < 200 || httpStatus > 299 || createdArg === null) return { httpStatus, freezeMarker, wrote: null, errorCode: null };
+        try {
+          return { httpStatus, freezeMarker, wrote: await createdArg(readArg, responseArg.headers), errorCode: null };
+        } catch {
+          if (signalArg?.aborted) throw new validation.ForgeInventoryError('request-aborted');
+          return { httpStatus, freezeMarker, wrote: null, errorCode: 'created-identity-unreadable' };
+        }
+      });
+    } catch (error) {
+      return failed(reason(error));
+    }
+  }
+
+  /**
+   * One request through the origin's agents, never following a redirect,
+   * under the probe's deadline, which covers reading the body. `consumeArg`
+   * gets the response and a bounded body read; a body it does not read is
+   * discarded with the connection. Rejects with `request-aborted`,
+   * `request-timed-out`, `request-failed` or the consumer's own code.
+   */
+  async #exchange<T>(
+    contextArg: IOriginContext, requestArg: IProbeRequest, signalArg: AbortSignal | undefined,
+    consumeArg: (responseArg: transport.INodeResponse, readArg: () => Promise<Buffer>) => Promise<T>,
+  ): Promise<T> {
+    const controller = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, this.#options.requestTimeoutMs);
+    const abort = () => controller.abort();
+    signalArg?.addEventListener('abort', abort, { once: true });
+    if (signalArg?.aborted) controller.abort();
+    let chunks: AsyncIterator<Uint8Array> | undefined;
+    try {
+      const response = await transport.sendNodeRequest(requestArg.url, {
+        method: requestArg.method, headers: requestArg.headers, body: requestArg.body, signal: controller.signal, agents: contextArg.agents, redirect: 'return',
+      });
+      const read = async (): Promise<Buffer> => {
+        chunks = response.body?.[Symbol.asyncIterator]();
+        if (!chunks) throw new validation.ForgeInventoryError('response-body-missing');
+        const parts: Uint8Array[] = [];
+        let bytes = 0;
+        while (true) {
+          const result = await chunks.next();
+          if (result.done) return Buffer.concat(parts);
+          bytes += result.value.byteLength;
+          if (bytes > probeMaxResponseBytes) throw new validation.ForgeInventoryError('response-size-limit');
+          parts.push(result.value);
+        }
+      };
+      return await consumeArg(response, read);
+    } catch (error) {
+      if (signalArg?.aborted) throw new validation.ForgeInventoryError('request-aborted');
+      if (timedOut) throw new validation.ForgeInventoryError('request-timed-out');
+      if (error instanceof validation.ForgeInventoryError) throw error;
+      throw new validation.ForgeInventoryError('request-failed');
+    } finally {
+      clearTimeout(timer);
+      signalArg?.removeEventListener('abort', abort);
+      // Discards an unread or partly read body with its connection; a completely read one has already released it.
+      controller.abort();
+      try { await chunks?.return?.(); } catch { /* The request has already been aborted. */ }
+    }
+  }
+}
+
+/**
+ * An LFS upload action's href and headers. The href must stay on the origin
+ * the batch request went to, so the canary write and the credential the
+ * action carries never leave it; its headers may not set connection-level
+ * fields. Gitea asks for a chunked upload (`Transfer-Encoding: chunked`); the
+ * probe sends the object with its length instead.
+ */
+const uploadAction = (actionArg: unknown, baseArg: string): { href: URL; headers: Record<string, string> } => {
+  let action: Record<string, unknown>;
+  let href: URL;
+  try {
+    action = validation.record(actionArg);
+    if (typeof action.href !== 'string' || action.href.length > maxHrefLength) throw new Error('href');
+    href = new URL(action.href);
+  } catch {
+    throw new validation.ForgeInventoryError('invalid-batch-response');
+  }
+  if (href.origin !== new URL(baseArg).origin || href.username || href.password || href.hash) {
+    throw new validation.ForgeInventoryError('upload-href-other-origin');
+  }
+  const headers: Record<string, string> = {};
+  if (action.header !== undefined && action.header !== null) {
+    let entries: Array<[string, unknown]>;
+    try {
+      entries = Object.entries(validation.record(action.header));
+    } catch {
+      throw new validation.ForgeInventoryError('invalid-batch-response');
+    }
+    if (entries.length > maxActionHeaders) throw new validation.ForgeInventoryError('invalid-batch-response');
+    for (const [headerName, value] of entries) {
+      const key = headerName.toLowerCase();
+      if (key === 'transfer-encoding' && typeof value === 'string' && value.trim().toLowerCase() === 'chunked') continue;
+      if (!headerNamePattern.test(headerName) || reservedHeaderNames.has(key) || key in headers ||
+        typeof value !== 'string' || value.length > maxHeaderValueLength || /[\u0000\r\n]/.test(value)) {
+        throw new validation.ForgeInventoryError('invalid-batch-response');
+      }
+      headers[key] = value;
+    }
+  }
+  return { href, headers };
+};