@foss.global/codefeed 5.2.0 → 5.4.0

package/ts/forgeinventory.client.ts

@@ -1,4 +1,4 @@
-import type * as transport from './forgeinventory.transport.js';
+import * as transport from './forgeinventory.transport.js';
 import * as validation from './forgeinventory.validation.js';
 
 export interface IForgeRequestMetrics {
@@ -50,6 +50,17 @@ export interface IForgeBytesResponse {
   headers: transport.IForgeTransportResponse['headers'];
 }
 
+/** A redirect a read returned instead of refusing: never followed, its body discarded. */
+export interface IForgeRedirectResponse {
+  /** One of 301, 302, 303, 307 and 308. */
+  status: number;
+  /** The `Location` header verbatim; null when the response sent none. */
+  location: string | null;
+}
+
+/** The answer of `requestBytesOrRedirect`: the body of a 200, or the redirect. */
+export type TForgeBytesOrRedirect = ({ kind: 'bytes' } & IForgeBytesResponse) | ({ kind: 'redirect' } & IForgeRedirectResponse);
+
 interface IReadOptions {
   signal?: AbortSignal;
   maxResponseBytes?: number;
@@ -58,8 +69,14 @@ interface IReadOptions {
   /** The media type the response must carry, checked before its body is read; any when absent. */
   requiredMediaType?: string;
   body?: { mediaType: string; bytes: Uint8Array<ArrayBuffer> };
+  /** `return` resolves a redirect status as `redirect` instead of rejecting; defaults to `refuse`. */
+  redirect?: transport.TForgeRedirectMode;
 }
 
+type TReadResult =
+  | { kind: 'bytes'; bytes: Buffer; headers: transport.IForgeTransportResponse['headers'] }
+  | ({ kind: 'redirect' } & IForgeRedirectResponse);
+
 /**
  * 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
@@ -78,7 +95,7 @@ export class ForgeRequestClient {
 
   public async request(url: URL, requestArg: IForgeRequestOptions = {}): Promise<IForgeJsonResponse> {
     const mediaType = requestArg.mediaType ?? 'application/json';
-    const response = await this.#read(url, {
+    const response = await this.#body(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)) } }),
     });
@@ -91,11 +108,32 @@ export class ForgeRequestClient {
 
   /** 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);
+    const response = await this.#body(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'] }> {
+  /**
+   * A GET like `requestBytes`, except that a redirect status resolves as
+   * `{ kind: 'redirect', status, location }` instead of rejecting. The
+   * redirect is never followed and its body is discarded unread; any status
+   * other than 200 and a redirect still rejects with `http-<status>`.
+   */
+  public async requestBytesOrRedirect(url: URL, requestArg: IForgeBytesRequestOptions): Promise<TForgeBytesOrRedirect> {
+    const response = await this.#read(url, { ...requestArg, redirect: 'return' });
+    return response.kind === 'redirect'
+      ? response
+      : { kind: 'bytes', bytes: response.bytes, mediaType: mediaTypeOf(response.headers), headers: response.headers };
+  }
+
+  /** A read that refuses redirects, so it always answers a body. */
+  async #body(url: URL, requestArg: Omit<IReadOptions, 'redirect'>): Promise<{ bytes: Buffer; headers: transport.IForgeTransportResponse['headers'] }> {
+    const response = await this.#read(url, requestArg);
+    // The transport refuses every redirect status in this mode, so a redirect never arrives here.
+    if (response.kind === 'redirect') throw new validation.ForgeInventoryError('request-or-json-failed');
+    return response;
+  }
+
+  async #read(url: URL, requestArg: IReadOptions): Promise<TReadResult> {
     const { signal } = requestArg;
     const maxBytes = requestArg.maxResponseBytes ?? this.#options.maxResponseBytes;
     if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) throw new validation.ForgeInventoryError('invalid-response-budget');
@@ -111,9 +149,13 @@ export class ForgeRequestClient {
       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);
+      const response = await this.#options.transport(url, headers, controller.signal, requestArg.body?.bytes, { redirect: requestArg.redirect ?? 'refuse' });
       bodyChunks = response.body?.[Symbol.asyncIterator]();
       if (response.status === 429) this.#metrics.rateLimitedRequests++;
+      if (requestArg.redirect === 'return' && transport.redirectStatuses.has(response.status)) {
+        // The body is discarded unread by the `finally` below.
+        return { kind: 'redirect', status: response.status, location: response.headers.get('location') };
+      }
       if (response.status !== 200) throw new validation.ForgeInventoryError(`http-${response.status}`);
       if ((requestArg.requiredMediaType !== undefined && mediaTypeOf(response.headers) !== requestArg.requiredMediaType) || !bodyChunks) {
         throw new validation.ForgeInventoryError('invalid-content-type');
@@ -129,7 +171,7 @@ export class ForgeRequestClient {
         chunks.push(result.value);
       }
       if (controller.signal.aborted || Date.now() >= deadline) throw new validation.ForgeInventoryError('request-aborted-or-timed-out');
-      return { bytes: Buffer.concat(chunks), headers: response.headers };
+      return { kind: 'bytes', 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');

package/ts/forgeinventory.transfer.ts

@@ -1,5 +1,7 @@
 import * as plugins from './plugins.js';
+import * as transport from './forgeinventory.transport.js';
 import * as validation from './forgeinventory.validation.js';
+import type { IForgeRequestMetrics } from './forgeinventory.client.js';
 
 /** Response bytes read from an unused answer before the rest is discarded. */
 const maxDiscardedResponseBytes = 64 * 1024;
@@ -201,3 +203,89 @@ export const createTransferStream = (
   });
   return stream;
 };
+
+/** Passes `sourceArg`'s chunks on, adding each one's bytes to `metricsArg` as it arrives. */
+async function* countedBytes(sourceArg: AsyncIterable<Uint8Array>, metricsArg: IForgeRequestMetrics): AsyncGenerator<Uint8Array, void, undefined> {
+  for await (const chunk of sourceArg) {
+    if (chunk instanceof Uint8Array) metricsArg.responseBytes += chunk.byteLength;
+    yield chunk;
+  }
+}
+
+/** The `heldBackChunks` codes of a package content download. */
+const packageContentCodes = {
+  invalidChunk: 'package-content-invalid-chunk', overrun: 'package-content-size-overrun', short: 'package-content-short-body',
+};
+
+/** The reader settings a verified package content download runs with. */
+export interface IVerifiedPackageDownloadOptions {
+  /** PEM certificates that replace the default trust store for the download's connection. */
+  caCertificates?: string[];
+  /** Wall-clock limit of the whole download, the closing `identifiedArg` read included. */
+  packageTransferTimeoutMs: number;
+  /** Idle limit of the download, re-armed on every chunk and before the closing `identifiedArg` read. */
+  requestTimeoutMs: number;
+  /** Counts the request, a 429 answer and every body byte that arrives, as `ForgeRequestClient` counts its reads. */
+  metrics?: IForgeRequestMetrics;
+}
+
+/**
+ * Streams one package content download verified against `contentArg`, sent
+ * over node:https with the caller's CA certificates: 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.
+ */
+export const verifiedPackageDownload = async (
+  optionsArg: IVerifiedPackageDownloadOptions, 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(optionsArg.caCertificates);
+  const close = () => agents.https?.destroy();
+  const transfer = createTransferBounds(signalArg, {
+    limitMs: optionsArg.packageTransferTimeoutMs, idleMs: optionsArg.requestTimeoutMs,
+    timedOutCode: 'package-content-transfer-timed-out', failedCode: 'package-content-transfer-failed',
+  });
+  const { metrics } = optionsArg;
+  let body: AsyncIterable<Uint8Array>;
+  try {
+    if (metrics) metrics.requests++;
+    const response = await transfer.run(() => transport.sendNodeRequest(urlArg, { method: 'GET', headers: headersArg, signal: transfer.signal, agents }));
+    if (metrics && response.status === 429) metrics.rateLimitedRequests++;
+    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 = metrics ? countedBytes(response.body, metrics) : 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);
+};

package/ts/forgeinventory.transport.ts

@@ -8,16 +8,29 @@ export interface IForgeTransportResponse {
   body: AsyncIterable<Uint8Array> | null;
 }
 
+/**
+ * What a transport does with a redirect status: `refuse` rejects it, `return`
+ * resolves it as the response it is, `Location` included. Neither follows it.
+ */
+export type TForgeRedirectMode = 'refuse' | 'return';
+
+export interface IForgeTransportOptions {
+  /** Defaults to `refuse`. */
+  redirect?: TForgeRedirectMode;
+}
+
 /**
  * Sends one credential-scoped GET, or a POST of `body` when one is given, and
- * resolves once response headers arrive. A redirect status rejects and is
- * never followed; aborting `signal` discards the connection, also while the
- * body is still being read.
+ * resolves once response headers arrive. A redirect status is never followed:
+ * it rejects, unless `options.redirect` is `return`. Aborting `signal`
+ * discards the connection, also while the body is still being read.
  */
-export type TForgeTransport = (url: URL, headers: Record<string, string>, signal: AbortSignal, body?: Uint8Array<ArrayBuffer>) => Promise<IForgeTransportResponse>;
+export type TForgeTransport = (
+  url: URL, headers: Record<string, string>, signal: AbortSignal, body?: Uint8Array<ArrayBuffer>, options?: IForgeTransportOptions,
+) => Promise<IForgeTransportResponse>;
 
 /** The fetch statuses whose redirect mode `error` turns them into a network error. */
-const redirectStatuses: ReadonlySet<number> = new Set([301, 302, 303, 307, 308]);
+export const redirectStatuses: ReadonlySet<number> = new Set([301, 302, 303, 307, 308]);
 
 /**
  * Idle keep-alive sockets close after this delay, or earlier when the server
@@ -27,8 +40,10 @@ const redirectStatuses: ReadonlySet<number> = new Set([301, 302, 303, 307, 308])
 const idleSocketTimeoutMs = 4_000;
 
 /** Node's global `fetch` with the process-wide default trust store. */
-export const globalFetchTransport: TForgeTransport = async (url, headers, signal, body) => {
-  const response = await fetch(url, { method: body ? 'POST' : 'GET', headers, body, redirect: 'error', credentials: 'omit', signal });
+export const globalFetchTransport: TForgeTransport = async (url, headers, signal, body, options) => {
+  // Node's fetch answers `manual` with the redirect response itself, status and `Location` included.
+  const redirect = options?.redirect === 'return' ? 'manual' : 'error';
+  const response = await fetch(url, { method: body ? 'POST' : 'GET', headers, body, redirect, credentials: 'omit', signal });
   return { status: response.status, headers: response.headers, body: response.body };
 };
 
@@ -45,6 +60,8 @@ export interface INodeRequest {
   body?: Uint8Array | AsyncIterable<Uint8Array>;
   signal: AbortSignal;
   agents: INodeRequestAgents;
+  /** Defaults to `refuse`. */
+  redirect?: TForgeRedirectMode;
 }
 
 export interface INodeResponse extends IForgeTransportResponse {
@@ -74,9 +91,10 @@ const drained = (requestArg: InstanceType<typeof plugins.http.ClientRequest>): P
 
 /**
  * Sends one request through `node:http` or `node:https` and resolves once
- * response headers arrive. A redirect status rejects and is never followed;
- * aborting `signal` discards the connection, also while a body is still being
- * sent or read. A streamed body that fails destroys the request and rejects.
+ * response headers arrive. A redirect status is never followed: it rejects,
+ * unless `redirect` is `return`. Aborting `signal` discards the connection,
+ * also while a body is still being sent or read. A streamed body that fails
+ * destroys the request and rejects.
  */
 export const sendNodeRequest = (url: URL, requestArg: INodeRequest): Promise<INodeResponse> => new Promise<INodeResponse>((resolve, reject) => {
   const { signal } = requestArg;
@@ -126,7 +144,7 @@ export const sendNodeRequest = (url: URL, requestArg: INodeRequest): Promise<INo
   request.on('response', (response) => {
     try {
       const status = response.statusCode ?? 0;
-      if (redirectStatuses.has(status)) throw new Error('Refused redirect.');
+      if (redirectStatuses.has(status) && requestArg.redirect !== 'return') throw new Error('Refused redirect.');
       // Same combination rules as fetch: repeated fields join with ", ".
       const responseHeaders = new Headers();
       for (let index = 0; index < response.rawHeaders.length; index += 2) {
@@ -149,8 +167,10 @@ export const sendNodeRequest = (url: URL, requestArg: INodeRequest): Promise<INo
  */
 export const createHttpsTransport = (caCertificates: string[]): TForgeTransport => {
   const agents = createNodeAgents(caCertificates);
-  return async (url, headers, signal, body) => {
-    const { sent: _sent, ...response } = await sendNodeRequest(url, { method: body ? 'POST' : 'GET', headers, body, signal, agents });
+  return async (url, headers, signal, body, options) => {
+    const { sent: _sent, ...response } = await sendNodeRequest(url, {
+      method: body ? 'POST' : 'GET', headers, body, signal, agents, redirect: options?.redirect,
+    });
     return response;
   };
 };

package/ts/giteasourceinventory.packages.ts

@@ -1,5 +1,7 @@
 import * as plugins from './plugins.js';
 import * as validation from './forgeinventory.validation.js';
+import type { ForgeRequestClient } from './forgeinventory.client.js';
+import { swiftManifestKey } from './giteasourcetransfer.documents.js';
 
 type TMeasure = plugins.fossInterfaces.data.TForgeSourceMeasure;
 type IPackageRef = plugins.fossInterfaces.data.IForgeSourcePackageRef;
@@ -64,6 +66,172 @@ export const swiftPackageParts = (nameArg: string): { scope: string; name: strin
   return { scope: match[1], name: match[2] };
 };
 
+/**
+ * A Swift release's `Package.swift`, or with `swiftVersionArg` its alternate
+ * manifest, read with `clientArg`'s `token` authorization; null when Gitea
+ * redirects the alternate one to the release's own `Package.swift` (303),
+ * which is how it answers a version it holds no manifest for. No redirect is
+ * followed: any other redirect rejects with `swift-manifest-redirect-unexpected`,
+ * a redirect of `Package.swift` itself with `http-<status>`, and a body that
+ * is not `text/x-swift` with `invalid-content-type`. The read counts no
+ * download.
+ */
+export const readSwiftManifest = async (
+  clientArg: ForgeRequestClient, baseUrlArg: string, ownerArg: string, partsArg: { scope: string; name: string }, versionArg: string,
+  swiftVersionArg: string | null, signalArg: AbortSignal | undefined,
+): Promise<{ bytes: Buffer; mediaType: string } | null> => {
+  const url = new URL(`${baseUrlArg}/api/packages/${encodeURIComponent(ownerArg)}/swift/${encodeURIComponent(partsArg.scope)}/${
+    encodeURIComponent(partsArg.name)}/${encodeURIComponent(versionArg)}/Package.swift`);
+  if (swiftVersionArg !== null) url.searchParams.set('swift-version', swiftVersionArg);
+  const response = await clientArg.requestBytesOrRedirect(url, { accept: 'application/vnd.swift.registry.v1+swift', signal: signalArg });
+  if (response.kind === 'redirect') {
+    if (swiftVersionArg === null) throw new validation.ForgeInventoryError(`http-${response.status}`);
+    // Gitea's answer for a missing alternate manifest: 303 to the release's
+    // `Package.swift` under its configured root, with the owner lowercased
+    // and scope, name and version as the request named them.
+    const expected = new URL(`${baseUrlArg}/api/packages/${ownerArg.toLowerCase()}/swift/${partsArg.scope}/${partsArg.name}/${versionArg}/Package.swift`);
+    let location: URL | null = null;
+    try {
+      location = response.location === null ? null : new URL(response.location, url);
+    } catch {
+      location = null;
+    }
+    if (response.status !== 303 || location === null || location.href !== expected.href) {
+      throw new validation.ForgeInventoryError('swift-manifest-redirect-unexpected');
+    }
+    return null;
+  }
+  if (response.mediaType !== 'text/x-swift') throw new validation.ForgeInventoryError('invalid-content-type');
+  return { bytes: response.bytes, mediaType: 'text/x-swift' };
+};
+
+/** Distinct manifest keys read per Swift version, `''` included; Gitea keeps at most 64 manifests (`maxManifestFiles`). */
+const maxSwiftManifestCandidates = 64;
+
+/**
+ * The name of every central-directory entry of a zip archive, in directory
+ * order, each byte one code unit (Go strings are bytes, and only ASCII names
+ * can match `manifestPattern`). It reads the directory as Go 1.27.2's
+ * `archive/zip` `NewReader` does, the archive/zip Gitea 28.2.0 builds with:
+ * - the end record is the last signature in the final 65 KiB whose comment
+ *   fits in the archive;
+ * - its zip64 locator and end record are used when a count, size or offset
+ *   is saturated and a locator for disk 0 of 1 sits right before it;
+ * - the base offset of data prepended to the archive is the end record's
+ *   position minus the directory's size and offset, unless a directory
+ *   header sits at the unadjusted offset;
+ * - headers are read one after another until one is malformed or cut off
+ *   (a zip64 field too short for the saturated sizes and offset it stands
+ *   for is malformed), and their count must agree with the end record's in
+ *   its low 16 bits.
+ * Anything Go refuses rejects with `swift-archive-invalid`.
+ */
+export const zipEntryNames = (archiveArg: Buffer): string[] => {
+  const invalid = () => new validation.ForgeInventoryError('swift-archive-invalid');
+  const size = archiveArg.byteLength;
+  const sizeBig = BigInt(size);
+  let endOffset = -1;
+  for (let index = size - 22; index >= Math.max(0, size - 65 * 1024); index--) {
+    if (archiveArg.readUInt32LE(index) === 0x06054b50) {
+      endOffset = index;
+      break;
+    }
+  }
+  if (endOffset < 0 || endOffset + 22 + archiveArg.readUInt16LE(endOffset + 20) > size) throw invalid();
+  let directoryEnd = BigInt(endOffset);
+  let records = BigInt(archiveArg.readUInt16LE(endOffset + 10));
+  let directorySize = BigInt(archiveArg.readUInt32LE(endOffset + 12));
+  let directoryOffset = BigInt(archiveArg.readUInt32LE(endOffset + 16));
+  if (records === 0xffffn || directorySize === 0xffffffffn || directoryOffset === 0xffffffffn) {
+    const locator = endOffset - 20;
+    if (locator >= 0 && archiveArg.readUInt32LE(locator) === 0x07064b50 && archiveArg.readUInt32LE(locator + 4) === 0
+      && archiveArg.readUInt32LE(locator + 16) === 1) {
+      // Go reads the offset as an int64: one past its range is negative and leaves the archive as zip32.
+      const record = archiveArg.readBigInt64LE(locator + 8);
+      if (record >= 0n) {
+        if (record + 56n > sizeBig || archiveArg.readUInt32LE(Number(record)) !== 0x06064b50) throw invalid();
+        directoryEnd = record;
+        records = archiveArg.readBigUInt64LE(Number(record) + 32);
+        directorySize = archiveArg.readBigUInt64LE(Number(record) + 40);
+        directoryOffset = archiveArg.readBigUInt64LE(Number(record) + 48);
+      }
+    }
+  }
+  if (directorySize > 0x7fffffffffffffffn || directoryOffset > 0x7fffffffffffffffn) throw invalid();
+  let baseOffset = directoryEnd - directorySize - directoryOffset;
+  if (baseOffset + directoryOffset < 0n || baseOffset + directoryOffset >= sizeBig) throw invalid();
+  if (baseOffset > 0n && directoryHeader(archiveArg, Number(directoryOffset)).kind === 'entry') baseOffset = 0n;
+  const names: string[] = [];
+  let offset = Number(baseOffset + directoryOffset);
+  while (true) {
+    const header = directoryHeader(archiveArg, offset);
+    if (header.kind === 'end') break;
+    // Go's `io.ReadFull` reports a read that gets no byte at all as `io.EOF`, which fails the archive.
+    if (header.kind === 'eof') throw invalid();
+    names.push(header.name);
+    offset = header.next;
+  }
+  if ((BigInt(names.length) & 0xffffn) !== (records & 0xffffn)) throw invalid();
+  return names;
+};
+
+/**
+ * The central-directory header at `offsetArg`, as Go 1.27.2's
+ * `readDirectoryHeader` reads it: `entry` with its name and the offset of the
+ * next header; `end` where Go stops reading headers (a header cut off by the
+ * archive's end, another signature, or a zip64 field shorter than 8 bytes for
+ * each saturated size and offset); `eof` where a read gets no byte at all.
+ */
+const directoryHeader = (archiveArg: Buffer, offsetArg: number):
+  { kind: 'entry'; name: string; next: number } | { kind: 'end' } | { kind: 'eof' } => {
+  const available = archiveArg.byteLength - offsetArg;
+  if (available <= 0) return { kind: 'eof' };
+  if (available < 46) return { kind: 'end' };
+  if (archiveArg.readUInt32LE(offsetArg) !== 0x02014b50) return { kind: 'end' };
+  const nameLength = archiveArg.readUInt16LE(offsetArg + 28);
+  const extraLength = archiveArg.readUInt16LE(offsetArg + 30);
+  const commentLength = archiveArg.readUInt16LE(offsetArg + 32);
+  const variable = nameLength + extraLength + commentLength;
+  if (variable > 0 && available === 46) return { kind: 'eof' };
+  if (available - 46 < variable) return { kind: 'end' };
+  const saturated = [20, 24, 42].filter((fieldArg) => archiveArg.readUInt32LE(offsetArg + fieldArg) === 0xffffffff).length;
+  let extra = offsetArg + 46 + nameLength;
+  const extraEnd = extra + extraLength;
+  while (extraEnd - extra >= 4) {
+    const tag = archiveArg.readUInt16LE(extra);
+    const fieldSize = archiveArg.readUInt16LE(extra + 2);
+    extra += 4;
+    if (extraEnd - extra < fieldSize) break;
+    // The zip64 field holds 8 bytes for each saturated field, in order.
+    if (tag === 0x0001 && fieldSize < 8 * saturated) return { kind: 'end' };
+    extra += fieldSize;
+  }
+  return { kind: 'entry', name: archiveArg.toString('latin1', offsetArg + 46, offsetArg + 46 + nameLength), next: offsetArg + 46 + variable };
+};
+
+/**
+ * The keys of the manifests Gitea 28.2.0 may hold for a Swift source
+ * archive, sorted in code-unit order: `''`, and the key of every
+ * central-directory entry, in any directory, whose name does not end in `/`
+ * and whose base name matches Gitea's `manifestPattern` and parses
+ * (`swiftManifestKey`). Gitea keeps only the manifests of the shallowest
+ * directory, so the keys are a superset of what it holds, and its answer for
+ * each key decides. More than `maxSwiftManifestCandidates` distinct keys
+ * reject with `swift-manifest-candidates-over-bound`; an archive Go's
+ * `archive/zip` refuses with `swift-archive-invalid`.
+ */
+export const swiftManifestCandidates = (archiveArg: Buffer): string[] => {
+  const keys = new Set<string>(['']);
+  for (const name of zipEntryNames(archiveArg)) {
+    if (name.endsWith('/')) continue;
+    const key = swiftManifestKey(name.slice(name.lastIndexOf('/') + 1));
+    if (key === null) continue;
+    keys.add(key);
+    if (keys.size > maxSwiftManifestCandidates) throw new validation.ForgeInventoryError('swift-manifest-candidates-over-bound');
+  }
+  return [...keys].sort(compareText);
+};
+
 /**
  * The digest of the manifest a container version holds: `sha256:` and the
  * SHA-256 of the blob holding the version's `manifest.json`; null for a

package/ts/giteasourcetransfer.documents.ts

@@ -0,0 +1,140 @@
+import * as plugins from './plugins.js';
+import * as validation from './forgeinventory.validation.js';
+
+/**
+ * Package metadata documents that are JSON, which `canonicalPackageDocument`
+ * brings into one form: an npm version document, Swift release metadata, a
+ * crate version's line of the Cargo sparse index, and `{"description":…}`
+ * of a crate's latest version as the Cargo search serves it.
+ */
+export type TGiteaCanonicalPackageDocumentKind = 'npm-version' | 'swift-release' | 'cargo-index-entry' | 'cargo-description';
+
+export interface IGiteaCanonicalPackageDocument {
+  /** The canonical JSON, UTF-8. */
+  bytes: Buffer;
+  /** Lowercase hex SHA-256 of `bytes`. */
+  sha256: string;
+}
+
+/**
+ * The top-level member each kind removes: state the forge changes without
+ * replacing the version, which the source inventory records apart (a Cargo
+ * version's `yanked`, an npm version's `deprecated`).
+ */
+const mutableStateMembers: Readonly<Record<TGiteaCanonicalPackageDocumentKind, string | null>> = Object.freeze({
+  'npm-version': 'deprecated',
+  'swift-release': null,
+  'cargo-index-entry': 'yanked',
+  'cargo-description': null,
+});
+
+/**
+ * Orders two strings by Unicode code point. UTF-16 code-unit order (the
+ * default sort) differs from it where a surrogate pair meets U+E000 to U+FFFF.
+ */
+const compareCodePoints = (leftArg: string, rightArg: string): number => {
+  let left = 0;
+  let right = 0;
+  while (left < leftArg.length && right < rightArg.length) {
+    const leftPoint = leftArg.codePointAt(left)!;
+    const rightPoint = rightArg.codePointAt(right)!;
+    if (leftPoint !== rightPoint) return leftPoint - rightPoint;
+    left += leftPoint > 0xffff ? 2 : 1;
+    right += rightPoint > 0xffff ? 2 : 1;
+  }
+  return (leftArg.length - left) - (rightArg.length - right);
+};
+
+/** Compact JSON with object keys in code-point order at every depth, arrays in order and only safe integers as numbers. */
+const canonicalJson = (valueArg: unknown): string => {
+  if (valueArg === null || typeof valueArg === 'boolean' || typeof valueArg === 'string') return JSON.stringify(valueArg);
+  if (typeof valueArg === 'number') {
+    if (!Number.isSafeInteger(valueArg)) throw new validation.ForgeInventoryError('document-not-canonical');
+    return JSON.stringify(valueArg);
+  }
+  if (Array.isArray(valueArg)) return `[${valueArg.map(canonicalJson).join(',')}]`;
+  const record = valueArg as Record<string, unknown>;
+  return `{${Object.keys(record).sort(compareCodePoints).map((keyArg) => `${JSON.stringify(keyArg)}:${canonicalJson(record[keyArg])}`).join(',')}}`;
+};
+
+/**
+ * The canonical form of a package metadata document and its SHA-256, which a
+ * consumer records and compares instead of the bytes Gitea served: Gitea 28
+ * writes JSON objects held in maps (a crate's `features`, npm's maps) in a
+ * different key order on every read, and documents carry state that changes
+ * without a new version. In this order: decode as UTF-8 (fatal), parse as a
+ * JSON object, remove the kind's top-level mutable-state member (`yanked`
+ * for `cargo-index-entry`, `deprecated` for `npm-version`), and write it
+ * compact, object keys sorted by code point at every depth, arrays in their
+ * order, strings and safe integers as `JSON.stringify` writes them. Anything
+ * else, a number that is not a safe integer included, rejects with
+ * `document-not-canonical`; an unknown kind with
+ * `package-document-kind-invalid`. The same document gives the same bytes
+ * whatever order its keys arrived in.
+ */
+export const canonicalPackageDocument = (kindArg: TGiteaCanonicalPackageDocumentKind, bytesArg: Uint8Array): IGiteaCanonicalPackageDocument => {
+  if (!Object.hasOwn(mutableStateMembers, kindArg)) throw new validation.ForgeInventoryError('package-document-kind-invalid');
+  let canonical: string;
+  try {
+    const parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytesArg)) as unknown;
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) throw new validation.ForgeInventoryError('document-not-canonical');
+    const member = mutableStateMembers[kindArg];
+    if (member !== null) delete (parsed as Record<string, unknown>)[member];
+    canonical = canonicalJson(parsed);
+  } catch {
+    // Invalid UTF-8 or JSON, a non-object, an unsafe number, or nesting deeper than the stack.
+    throw new validation.ForgeInventoryError('document-not-canonical');
+  }
+  const bytes = Buffer.from(canonical, 'utf8');
+  return { bytes, sha256: plugins.crypto.createHash('sha256').update(bytes).digest('hex') };
+};
+
+/**
+ * The largest segment Gitea's version parser reads: hashicorp/go-version
+ * (v1.9.0 in Gitea 28.2.0) parses every segment as a signed 64-bit integer
+ * and refuses a larger one.
+ */
+const maxSwiftVersionSegment = 9223372036854775807n;
+
+/** Major and minor, and an optional patch, in decimal without leading zeros. */
+const trimmedSwiftVersionShape = /^(0|[1-9]\d*)\.(0|[1-9]\d*)(?:\.([1-9]\d*))?$/;
+
+/**
+ * Whether `valueArg` is a Swift version Gitea 28.2.0 can key an alternate
+ * manifest (`Package@swift-<v>.swift`) by. Gitea parses the file name's
+ * version with go-version's `NewSemver`, refuses an archive whose version
+ * does not parse (`ErrInvalidManifestVersion`), and keys the manifest by
+ * `TrimmedVersionString`: major and minor, and the patch only when it is not
+ * zero, each in decimal without leading zeros (`modules/packages/swift/metadata.go`).
+ * So a key has two or three segments, no leading zeros, no zero patch, and
+ * every segment at most 9223372036854775807, compared by value.
+ */
+export const isSwiftManifestVersion = (valueArg: unknown): valueArg is string => {
+  if (typeof valueArg !== 'string') return false;
+  const match = trimmedSwiftVersionShape.exec(valueArg);
+  if (!match) return false;
+  return match.slice(1).every((segmentArg) => segmentArg === undefined || BigInt(segmentArg) <= maxSwiftVersionSegment);
+};
+
+/** Gitea 28.2.0's `manifestPattern` (`modules/packages/swift/metadata.go:27`), matched against a file's base name. */
+const swiftManifestNamePattern = /^Package(?:@swift-(\d+(?:\.\d+)?(?:\.\d+)?))?\.swift$/;
+
+/**
+ * The key Gitea 28.2.0 would hold a manifest with base name `baseNameArg`
+ * by: `''` for `Package.swift`; for `Package@swift-<v>.swift`, `<v>` parsed
+ * as go-version's `NewSemver` parses it (leading zeros allowed, every segment
+ * a signed 64-bit integer, missing segments zero) and written as
+ * `TrimmedVersionString` writes it, a key `isSwiftManifestVersion` accepts.
+ * Null when the name is not a manifest name, or when a segment is over int64,
+ * which `NewSemver` refuses, so Gitea can never hold the key.
+ */
+export const swiftManifestKey = (baseNameArg: string): string | null => {
+  const match = swiftManifestNamePattern.exec(baseNameArg);
+  if (!match) return null;
+  if (match[1] === undefined) return '';
+  const segments = match[1].split('.').map((segmentArg) => BigInt(segmentArg));
+  if (segments.some((segmentArg) => segmentArg > maxSwiftVersionSegment)) return null;
+  const [major, minor = 0n, patch = 0n] = segments;
+  const key = patch === 0n ? `${major}.${minor}` : `${major}.${minor}.${patch}`;
+  return isSwiftManifestVersion(key) ? key : null;
+};

package/ts/index.ts

@@ -492,3 +492,5 @@ export * from './classes.giteasourcetransfer.js';
 export * from './classes.lfsbatchclient.js';
 export { GitScratchBudget, mirrorScratchBytes } from './giteasourceinventory.git.js';
 export { composeGiteaPackageContent } from './giteasourceinventory.packages.js';
+export { canonicalPackageDocument } from './giteasourcetransfer.documents.js';
+export type { IGiteaCanonicalPackageDocument, TGiteaCanonicalPackageDocumentKind } from './giteasourcetransfer.documents.js';