@cldmv/gh-broker 0.8.0 → 0.10.0

package/src/verbs/ghcr/push.ts

@@ -1,192 +0,0 @@
-/**
- *
- *	@Project: @cldmv/gh-broker
- *	@Filename: /src/verbs/ghcr/push.ts
- *	@Date: 2026-10-31T11:00:50-07:00 (1793469650)
- *	@Author: Nate Corcoran <CLDMV>
- *	@Email: <Shinrai@users.noreply.github.com>
- *	-----
- *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
- *	@Last modified time: 2026-10-31T11:13:29-07:00 (1793470409)
- *	-----
- *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
- *
- */
-
-/**
- * Pushes one planned image (see archive.ts) to a registry repository.
- *
- * Phases:
- *  1. preparing — for every layer the archive holds uncompressed, gzip it once just to
- *     learn the compressed digest and size. This costs a second pass of CPU, but it means
- *     the blob `HEAD` check works for those layers too (a re-push of an unchanged image
- *     uploads nothing), and nothing has to be buffered or written to disk: the broker's
- *     unit has no writable scratch space.
- *  2. uploading — config then layers: `HEAD` each blob and skip it when present,
- *     otherwise stream it. Compressed-on-push layers are gzipped again with the same
- *     settings; zlib is deterministic, and the registry rejects the upload if the bytes
- *     don't match the digest computed in phase 1.
- *  3. manifest — re-check a protected release tag (another push may have landed it while
- *     this one waited in the queue), then `PUT` the manifest under the tag.
- */
-
-import { createReadStream } from "node:fs";
-import { createHash } from "node:crypto";
-import { createGzip } from "node:zlib";
-import { PassThrough, Writable, type Readable } from "node:stream";
-import { pipeline } from "node:stream/promises";
-import { MEDIA, type BlobPlan, type ImagePlan } from "./archive.ts";
-import type { Registry } from "./registry.ts";
-
-export const RELEASE_TAG = /^v?\d+\.\d+\.\d+$/;
-const GZIP_LEVEL = 6;
-
-export type Phase = "queued" | "preparing" | "uploading" | "manifest" | "done";
-
-export interface PushProgress {
-	phase: Phase;
-	layersTotal: number;
-	blobsUploaded: number;
-	blobsSkipped: number;
-	/** Bytes of every blob the image references, as stored in the registry. Known once preparing ends. */
-	bytesTotal: number;
-	bytesSent: number;
-}
-
-export interface PushResult {
-	digest: string;
-	mediaType: string;
-	/** Total size of config + layers in the registry. */
-	size: number;
-	blobsUploaded: number;
-	blobsSkipped: number;
-}
-
-interface Descriptor {
-	mediaType: string;
-	digest: string;
-	size: number;
-}
-
-export class PushRefused extends Error {}
-
-function memberStream(fd: number, plan: BlobPlan): Readable {
-	if (plan.member.size === 0) {
-		const empty = new PassThrough();
-		empty.end();
-		return empty;
-	}
-	return createReadStream("", { fd, start: plan.member.offset, end: plan.member.offset + plan.member.size - 1, autoClose: false });
-}
-
-function gzipStream(fd: number, plan: BlobPlan): Readable {
-	const src = memberStream(fd, plan);
-	const gz = createGzip({ level: GZIP_LEVEL });
-	src.on("error", (e) => gz.destroy(e));
-	return src.pipe(gz);
-}
-
-async function gzipDigest(fd: number, plan: BlobPlan): Promise<{ digest: string; size: number }> {
-	const hash = createHash("sha256");
-	let size = 0;
-	await pipeline(
-		gzipStream(fd, plan),
-		new Writable({
-			write(chunk: Buffer, _enc, cb) {
-				hash.update(chunk);
-				size += chunk.length;
-				cb();
-			}
-		})
-	);
-	return { digest: `sha256:${hash.digest("hex")}`, size };
-}
-
-const sha256 = (b: Buffer): string => `sha256:${createHash("sha256").update(b).digest("hex")}`;
-
-export async function pushImage(
-	registry: Registry,
-	fd: number,
-	plan: ImagePlan,
-	tag: string,
-	opts: { protectReleaseTags: boolean; onProgress?: (p: PushProgress) => void }
-): Promise<PushResult> {
-	const progress: PushProgress = { phase: "preparing", layersTotal: plan.layers.length, blobsUploaded: 0, blobsSkipped: 0, bytesTotal: 0, bytesSent: 0 };
-	const report = () => opts.onProgress?.({ ...progress });
-	report();
-
-	const layers: Descriptor[] = [];
-	for (const l of plan.layers) {
-		if (l.compress) {
-			const { digest, size } = await gzipDigest(fd, l);
-			layers.push({ mediaType: l.mediaType, digest, size });
-		} else {
-			layers.push({ mediaType: l.mediaType, digest: l.sourceDigest ?? (await rawDigest(fd, l)), size: l.sourceSize });
-		}
-	}
-	const config: Descriptor = { mediaType: plan.config.mediaType, digest: plan.config.digest, size: plan.config.sourceSize };
-	progress.bytesTotal = config.size + layers.reduce((n, d) => n + d.size, 0);
-	progress.phase = "uploading";
-	report();
-
-	const blobs: Array<{ desc: Descriptor; plan: BlobPlan }> = [{ desc: config, plan: plan.config }, ...layers.map((desc, i) => ({ desc, plan: plan.layers[i]! }))];
-	const seen = new Set<string>();
-	for (const { desc, plan: p } of blobs) {
-		if (seen.has(desc.digest) || (await registry.blobExists(desc.digest))) {
-			seen.add(desc.digest);
-			progress.blobsSkipped++;
-			report();
-			continue;
-		}
-		seen.add(desc.digest);
-		await registry.uploadBlob(desc.digest, desc.size, () => (p.compress ? gzipStream(fd, p) : memberStream(fd, p)), (n) => {
-			progress.bytesSent += n;
-			report();
-		});
-		progress.blobsUploaded++;
-		report();
-	}
-
-	progress.phase = "manifest";
-	report();
-	let bytes: Buffer;
-	let mediaType: string;
-	if (plan.verbatimManifest) {
-		bytes = plan.verbatimManifest.bytes;
-		mediaType = plan.verbatimManifest.mediaType;
-	} else {
-		mediaType = MEDIA.ociManifest;
-		const cfg = { ...config, mediaType: config.mediaType === MEDIA.dockerConfig ? MEDIA.ociConfig : config.mediaType };
-		bytes = Buffer.from(
-			JSON.stringify({
-				schemaVersion: 2,
-				mediaType,
-				config: cfg,
-				layers: layers.map((l) => ({ ...l, mediaType: l.mediaType === MEDIA.dockerLayerGzip ? MEDIA.ociLayerGzip : l.mediaType })),
-				...(plan.annotations ? { annotations: plan.annotations } : {})
-			})
-		);
-	}
-	if (opts.protectReleaseTags && RELEASE_TAG.test(tag) && (await registry.manifestExists(tag))) {
-		throw new PushRefused(`ghcr_push: tag ${tag} already exists on ${registry.repository} and release tags are protected — push a new version instead`);
-	}
-	await registry.putManifest(tag, mediaType, bytes);
-	progress.phase = "done";
-	report();
-	return { digest: sha256(bytes), mediaType, size: progress.bytesTotal, blobsUploaded: progress.blobsUploaded, blobsSkipped: progress.blobsSkipped };
-}
-
-/** sha256 of a member streamed from the archive (docker-archive layers that are already compressed). */
-async function rawDigest(fd: number, plan: BlobPlan): Promise<string> {
-	const hash = createHash("sha256");
-	await pipeline(
-		memberStream(fd, plan),
-		new Writable({
-			write(chunk: Buffer, _enc, cb) {
-				hash.update(chunk);
-				cb();
-			}
-		})
-	);
-	return `sha256:${hash.digest("hex")}`;
-}

package/src/verbs/ghcr/registry.ts

@@ -1,275 +0,0 @@
-/**
- *
- *	@Project: @cldmv/gh-broker
- *	@Filename: /src/verbs/ghcr/registry.ts
- *	@Date: 2026-10-31T11:00:07-07:00 (1793469607)
- *	@Author: Nate Corcoran <CLDMV>
- *	@Email: <Shinrai@users.noreply.github.com>
- *	-----
- *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
- *	@Last modified time: 2026-10-31T23:26:34-07:00 (1793514394)
- *	-----
- *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
- *
- */
-
-/**
- * OCI distribution API client for ghcr.io, driven with node:https (no new dependency, no
- * docker socket, no skopeo).
- *
- * Credential handling:
- *  - The classic PAT is used for exactly one request: the Basic-auth exchange at
- *    `<base>/token` for a short-lived registry token scoped to one repository.
- *  - The registry token goes only to `<base>` itself. Every URL the registry hands back
- *    (upload `Location`, pagination `Link`) is resolved and refused unless its origin is
- *    `<base>`'s, and redirects are never followed, so neither secret can be carried to
- *    another host.
- *  - Every error message leaving this module goes through `clean()`, which replaces both
- *    secret values and anything shaped like an auth header or a GitHub token. Registry
- *    error bodies are reduced to their `code: message` pairs; response headers are never
- *    included.
- *
- * Upload flow per blob (the one go-containerregistry uses against GHCR):
- * `POST /v2/<name>/blobs/uploads/` → `PATCH <location>` streaming the bytes with a known
- * Content-Length → `PUT <location>?digest=…`. A 401 mid-flow (expired registry token)
- * re-runs the token exchange once and restarts that blob.
- */
-
-import { request as httpRequest, type IncomingHttpHeaders } from "node:http";
-import { request as httpsRequest } from "node:https";
-import type { Readable } from "node:stream";
-
-export const GHCR_BASE = "https://ghcr.io";
-const MAX_BODY = 1024 * 1024;
-const IDLE_TIMEOUT_MS = 10 * 60 * 1000;
-const MAX_TAG_PAGES = 20;
-export const MANIFEST_ACCEPT = [
-	"application/vnd.oci.image.manifest.v1+json",
-	"application/vnd.oci.image.index.v1+json",
-	"application/vnd.docker.distribution.manifest.v2+json",
-	"application/vnd.docker.distribution.manifest.list.v2+json"
-].join(", ");
-
-export class RegistryError extends Error {
-	readonly status?: number;
-	constructor(message: string, status?: number) {
-		super(message);
-		this.status = status;
-	}
-}
-
-interface Res {
-	status: number;
-	headers: IncomingHttpHeaders;
-	body: Buffer;
-}
-
-type Body = Buffer | (() => Readable) | undefined;
-
-export interface RegistryOptions {
-	/** Registry origin. Always GHCR_BASE in production; tests point it at a local fake. */
-	base?: string;
-	username: string;
-	password: string;
-	/** "<owner>/<image>" */
-	repository: string;
-}
-
-export class Registry {
-	private readonly base: URL;
-	private readonly username: string;
-	private readonly password: string;
-	readonly repository: string;
-	private token?: string;
-	private scope?: string;
-
-	constructor(opts: RegistryOptions) {
-		this.base = new URL(opts.base ?? GHCR_BASE);
-		this.username = opts.username;
-		this.password = opts.password;
-		this.repository = opts.repository;
-	}
-
-	/** The registry host name as used in image references (e.g. "ghcr.io"). */
-	get host(): string {
-		return this.base.host;
-	}
-
-	/** Replace every secret (and anything that looks like one) in a message. */
-	clean(msg: string): string {
-		let out = msg;
-		for (const s of [this.password, this.token]) if (s && s.length >= 4) out = out.split(s).join("[redacted]");
-		return out
-			.replace(/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/gi, "$1 [redacted]")
-			.replace(/\bgh[pousr]_[A-Za-z0-9]{20,}\b/g, "[redacted]")
-			.replace(/\bgithub_pat_[A-Za-z0-9_]{20,}\b/g, "[redacted]");
-	}
-
-	private err(step: string, res: Res): RegistryError {
-		let detail = "";
-		try {
-			const j = JSON.parse(res.body.toString("utf8")) as { errors?: Array<{ code?: unknown; message?: unknown }> };
-			if (Array.isArray(j.errors)) detail = j.errors.map((e) => `${String(e.code ?? "")}: ${String(e.message ?? "")}`).join("; ");
-		} catch {
-			detail = res.body.toString("utf8").replace(/\s+/g, " ").trim();
-		}
-		const hint = res.status === 401 || res.status === 403 ? " — check the ghcr credential is a classic PAT with write:packages, not expired, and allowed for this package" : "";
-		// Scrub before truncating: a secret cut at the 300-character boundary would no longer
-		// match the exact-value replacement.
-		const shown = this.clean(detail).slice(0, 300);
-		return new RegistryError(this.clean(`ghcr: ${step} failed: HTTP ${res.status}${shown ? ` (${shown})` : ""}${hint}`), res.status);
-	}
-
-	/** Resolve a registry-provided URL and refuse anything that would leave the registry's origin. */
-	private sameOrigin(raw: string, step: string): URL {
-		let u: URL;
-		try {
-			u = new URL(raw, this.base);
-		} catch {
-			throw new RegistryError(`ghcr: ${step}: registry returned an unparseable URL`);
-		}
-		if (u.origin !== this.base.origin) throw new RegistryError(`ghcr: ${step}: registry pointed at another host (${u.host}) — refused`);
-		return u;
-	}
-
-	private url(path: string): URL {
-		return new URL(path, this.base);
-	}
-
-	private send(method: string, url: URL, headers: Record<string, string>, body: Body, onBytes?: (n: number) => void): Promise<Res> {
-		const fn = url.protocol === "https:" ? httpsRequest : httpRequest;
-		return new Promise<Res>((resolve, reject) => {
-			const req = fn(url, { method, headers }, (res) => {
-				const chunks: Buffer[] = [];
-				let len = 0;
-				res.on("data", (c: Buffer) => {
-					if (len < MAX_BODY) chunks.push(c);
-					len += c.length;
-				});
-				res.on("end", () => resolve({ status: res.statusCode ?? 0, headers: res.headers, body: Buffer.concat(chunks).subarray(0, MAX_BODY) }));
-				res.on("error", reject);
-			});
-			req.setTimeout(IDLE_TIMEOUT_MS, () => req.destroy(new Error(`${method} timed out`)));
-			req.on("error", (e) => reject(new RegistryError(this.clean(`ghcr: ${method} ${url.pathname} failed: ${e.message}`))));
-			if (body === undefined) req.end();
-			else if (Buffer.isBuffer(body)) req.end(body);
-			else {
-				const src = body();
-				src.on("error", (e) => req.destroy(e));
-				if (onBytes) src.on("data", (c: Buffer) => onBytes(c.length));
-				src.pipe(req);
-			}
-		});
-	}
-
-	/** Exchange the PAT for a registry token scoped to this repository. */
-	async login(actions: "pull" | "push,pull"): Promise<void> {
-		const u = this.url("/token");
-		u.searchParams.set("service", this.base.host);
-		u.searchParams.set("scope", `repository:${this.repository}:${actions}`);
-		const basic = Buffer.from(`${this.username}:${this.password}`).toString("base64");
-		const res = await this.send("GET", u, { Authorization: `Basic ${basic}`, Accept: "application/json" }, undefined);
-		if (res.status !== 200) throw this.err("token exchange", res);
-		let token: unknown;
-		try {
-			const j = JSON.parse(res.body.toString("utf8")) as { token?: unknown; access_token?: unknown };
-			token = j.token ?? j.access_token;
-		} catch {
-			/* handled below */
-		}
-		if (typeof token !== "string" || !token) throw new RegistryError("ghcr: token exchange returned no token");
-		this.token = token;
-		this.scope = actions;
-	}
-
-	/** One request with the registry token; on 401 re-login once and retry. */
-	private async authed(method: string, url: URL, headers: Record<string, string>, body: Body, onBytes?: (n: number) => void): Promise<Res> {
-		if (!this.token) await this.login("pull");
-		const go = () => this.send(method, url, { ...headers, Authorization: `Bearer ${this.token}` }, body, onBytes);
-		const res = await go();
-		if (res.status !== 401) return res;
-		// login() sets scope together with token and a token is always present here, so the "pull" fallback is unreachable; it only satisfies the type.
-		/* v8 ignore next */
-		await this.login((this.scope as "pull" | "push,pull") ?? "pull");
-		return go();
-	}
-
-	async blobExists(digest: string): Promise<boolean> {
-		const res = await this.authed("HEAD", this.url(`/v2/${this.repository}/blobs/${digest}`), {}, undefined);
-		if (res.status >= 200 && res.status < 400) return true; // a redirect to storage still means "present"
-		if (res.status === 404) return false;
-		throw this.err(`checking blob ${digest}`, res);
-	}
-
-	/**
-	 * Upload one blob whose digest and size are known. `body` must produce a fresh stream
-	 * each call (a retry after a 401 restarts the upload). `onBytes` reports progress.
-	 */
-	async uploadBlob(digest: string, size: number, body: () => Readable, onBytes?: (n: number) => void): Promise<void> {
-		for (let attempt = 0; ; attempt++) {
-			let sent = 0;
-			const count = (n: number) => {
-				sent += n;
-				onBytes?.(n);
-			};
-			const res = await this.tryUpload(digest, size, body, count);
-			if (res === "ok") return;
-			if (attempt >= 1) throw this.err(`uploading blob ${digest}`, res);
-			onBytes?.(-sent); // roll the progress counter back before the retry
-			await this.login("push,pull");
-		}
-	}
-
-	private async tryUpload(digest: string, size: number, body: () => Readable, onBytes: (n: number) => void): Promise<"ok" | Res> {
-		const start = await this.authed("POST", this.url(`/v2/${this.repository}/blobs/uploads/`), { "Content-Length": "0" }, Buffer.alloc(0));
-		if (start.status === 401) return start;
-		if (start.status !== 202 || typeof start.headers.location !== "string") throw this.err("starting a blob upload", start);
-		const patchUrl = this.sameOrigin(start.headers.location, "blob upload");
-
-		const auth = { Authorization: `Bearer ${this.token}` };
-		const patch = await this.send("PATCH", patchUrl, { ...auth, "Content-Type": "application/octet-stream", "Content-Length": String(size) }, body, onBytes);
-		if (patch.status === 401) return patch;
-		if (patch.status !== 202 && patch.status !== 204) throw this.err(`uploading blob ${digest}`, patch);
-		const putUrl = this.sameOrigin(typeof patch.headers.location === "string" ? patch.headers.location : patchUrl.href, "blob upload");
-		putUrl.searchParams.set("digest", digest);
-
-		const done = await this.send("PUT", putUrl, { ...auth, "Content-Length": "0" }, Buffer.alloc(0));
-		if (done.status === 401) return done;
-		if (done.status !== 201) throw this.err(`finishing blob ${digest}`, done);
-		return "ok";
-	}
-
-	/** True when `reference` (tag or digest) already names a manifest in this repository. */
-	async manifestExists(reference: string): Promise<boolean> {
-		const res = await this.authed("HEAD", this.url(`/v2/${this.repository}/manifests/${reference}`), { Accept: MANIFEST_ACCEPT }, undefined);
-		if (res.status === 200) return true;
-		if (res.status === 404) return false;
-		throw this.err(`checking tag ${reference}`, res);
-	}
-
-	async putManifest(tag: string, mediaType: string, bytes: Buffer): Promise<void> {
-		const res = await this.authed("PUT", this.url(`/v2/${this.repository}/manifests/${tag}`), { "Content-Type": mediaType, "Content-Length": String(bytes.length) }, bytes);
-		if (res.status !== 201 && res.status !== 200) throw this.err(`pushing manifest for tag ${tag}`, res);
-	}
-
-	/** Every tag in the repository; `undefined` when the repository doesn't exist yet. */
-	async listTags(): Promise<string[] | undefined> {
-		const tags: string[] = [];
-		let url: URL | undefined = this.url(`/v2/${this.repository}/tags/list?n=1000`);
-		for (let page = 0; url && page < MAX_TAG_PAGES; page++) {
-			const res = await this.authed("GET", url, { Accept: "application/json" }, undefined);
-			if (res.status === 404) return undefined;
-			if (res.status !== 200) throw this.err("listing tags", res);
-			let j: { tags?: unknown };
-			try {
-				j = JSON.parse(res.body.toString("utf8")) as { tags?: unknown };
-			} catch {
-				throw new RegistryError("ghcr: listing tags returned invalid JSON");
-			}
-			if (Array.isArray(j.tags)) for (const t of j.tags) if (typeof t === "string") tags.push(t);
-			const link = typeof res.headers.link === "string" ? /<([^>]+)>;\s*rel="next"/.exec(res.headers.link) : null;
-			url = link ? this.sameOrigin(link[1]!, "listing tags") : undefined;
-		}
-		return tags;
-	}
-}

package/src/verbs/ghcr/tar.ts

@@ -1,203 +0,0 @@
-/**
- *
- *	@Project: @cldmv/gh-broker
- *	@Filename: /src/verbs/ghcr/tar.ts
- *	@Date: 2026-10-31T10:58:00-07:00 (1793469480)
- *	@Author: Nate Corcoran <CLDMV>
- *	@Email: <Shinrai@users.noreply.github.com>
- *	-----
- *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
- *	@Last modified time: 2026-10-31T11:13:30-07:00 (1793470410)
- *	-----
- *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
- *
- */
-
-/**
- * Minimal read-only tar index for `docker save` / OCI-layout archives.
- *
- * Only headers are read: the index records where each member's data lives in the file
- * (offset + size) so blobs can be streamed straight from the already-open descriptor
- * with positional reads. Nothing is extracted to disk, and links inside the archive are
- * resolved against the archive's own member names, never the filesystem.
- *
- * Supported: ustar/POSIX headers, PAX extended headers (`path`, `linkpath`, `size`), GNU
- * long names (`L`/`K`), base-256 sizes, regular files, hard links and symlinks. Global PAX
- * headers, directories and every other type are skipped.
- */
-
-import { readSync } from "node:fs";
-import { posix } from "node:path";
-
-export interface TarMember {
-	/** Byte offset of the member's data in the archive. */
-	offset: number;
-	size: number;
-}
-
-export interface TarIndex {
-	/** Regular members by normalized name (links already resolved). */
-	files: Map<string, TarMember>;
-}
-
-const BLOCK = 512;
-/** Bounds the header scan so a hostile archive can't make the index unbounded. */
-export const MAX_TAR_MEMBERS = 100_000;
-const MAX_EXT_HEADER = 1024 * 1024;
-const MAX_LINK_DEPTH = 16;
-
-export class TarError extends Error {}
-
-const fail = (msg: string): never => {
-	throw new TarError(`archive: ${msg}`);
-};
-
-function readAt(fd: number, position: number, length: number): Buffer {
-	const buf = Buffer.alloc(length);
-	let got = 0;
-	while (got < length) {
-		const n = readSync(fd, buf, got, length - got, position + got);
-		if (n === 0) break;
-		got += n;
-	}
-	if (got !== length) fail(`truncated at byte ${position + got}`);
-	return buf;
-}
-
-function cstr(buf: Buffer, start: number, len: number): string {
-	const slice = buf.subarray(start, start + len);
-	const nul = slice.indexOf(0);
-	return slice.subarray(0, nul === -1 ? len : nul).toString("utf8");
-}
-
-function parseSize(buf: Buffer): number {
-	const field = buf.subarray(124, 136);
-	if (field[0]! & 0x80) {
-		// base-256 (GNU) for members over 8 GiB
-		let n = 0;
-		for (let i = 1; i < field.length; i++) n = n * 256 + field[i]!;
-		if (!Number.isSafeInteger(n)) fail("member size out of range");
-		return n;
-	}
-	const s = cstr(field, 0, 12).trim();
-	if (!/^[0-7]*$/.test(s)) fail("bad size field in tar header");
-	return s ? parseInt(s, 8) : 0;
-}
-
-function checksumOk(buf: Buffer): boolean {
-	const stored = cstr(buf, 148, 8).trim();
-	if (!/^[0-7]+$/.test(stored)) return false;
-	let sum = 0;
-	for (let i = 0; i < BLOCK; i++) sum += i >= 148 && i < 156 ? 0x20 : buf[i]!;
-	return sum === parseInt(stored, 8);
-}
-
-function parsePax(data: Buffer): Record<string, string> {
-	const out: Record<string, string> = {};
-	let i = 0;
-	while (i < data.length) {
-		const sp = data.indexOf(0x20, i);
-		if (sp === -1) break;
-		const len = parseInt(data.subarray(i, sp).toString("ascii"), 10);
-		if (!Number.isInteger(len) || len <= 0 || i + len > data.length) fail("bad PAX header record");
-		const rec = data.subarray(sp + 1, i + len - 1).toString("utf8");
-		const eq = rec.indexOf("=");
-		if (eq > 0) out[rec.slice(0, eq)] = rec.slice(eq + 1);
-		i += len;
-	}
-	return out;
-}
-
-/** Normalize a member name: strip leading "./" and "/", collapse "..". Returns "" for the root. */
-export function normName(name: string): string {
-	const n = posix.normalize(`/${name}`).slice(1);
-	return n.replace(/\/+$/, "");
-}
-
-/** Index every member of the tar archive open at `fd` (`size` bytes long). */
-export function indexTar(fd: number, size: number): TarIndex {
-	const files = new Map<string, TarMember>();
-	const links = new Map<string, { target: string; hard: boolean }>();
-	let pos = 0;
-	let members = 0;
-	let pax: Record<string, string> = {};
-	let longName: string | undefined;
-	let longLink: string | undefined;
-
-	while (pos + BLOCK <= size) {
-		const hdr = readAt(fd, pos, BLOCK);
-		if (hdr.every((b) => b === 0)) break; // end-of-archive marker
-		if (!checksumOk(hdr)) fail(`bad tar header checksum at byte ${pos}`);
-		if (++members > MAX_TAR_MEMBERS) fail(`more than ${MAX_TAR_MEMBERS} members`);
-
-		const type = String.fromCharCode(hdr[156]!);
-		let memberSize = parseSize(hdr);
-		const dataAt = pos + BLOCK;
-		const next = dataAt + Math.ceil(memberSize / BLOCK) * BLOCK;
-
-		if (type === "x" || type === "g" || type === "L" || type === "K") {
-			if (memberSize > MAX_EXT_HEADER) fail("extended header too large");
-			const data = readAt(fd, dataAt, memberSize);
-			if (type === "x") pax = parsePax(data);
-			else if (type === "L") longName = cstr(data, 0, data.length);
-			else if (type === "K") longLink = cstr(data, 0, data.length);
-			// "g" (global PAX) carries nothing this reader needs.
-			pos = next;
-			continue;
-		}
-
-		const prefix = cstr(hdr, 345, 155);
-		const rawName = pax.path ?? longName ?? (prefix ? `${prefix}/${cstr(hdr, 0, 100)}` : cstr(hdr, 0, 100));
-		const linkName = pax.linkpath ?? longLink ?? cstr(hdr, 157, 100);
-		if (pax.size !== undefined) {
-			if (!/^\d+$/.test(pax.size)) fail("bad PAX size");
-			memberSize = Number(pax.size);
-		}
-		const dataEnd = dataAt + Math.ceil(memberSize / BLOCK) * BLOCK;
-		pax = {};
-		longName = undefined;
-		longLink = undefined;
-
-		const name = normName(rawName);
-		if (type === "0" || type === "\0" || type === "7") {
-			if (dataAt + memberSize > size) fail(`member "${name}" runs past the end of the file`);
-			files.set(name, { offset: dataAt, size: memberSize });
-			links.delete(name);
-		} else if (type === "1") {
-			links.set(name, { target: normName(linkName), hard: true });
-			files.delete(name);
-		} else if (type === "2") {
-			links.set(name, { target: normName(posix.join(posix.dirname(name), linkName)), hard: false });
-			files.delete(name);
-		}
-		pos = dataEnd;
-	}
-
-	// Resolve links to the regular member they finally point at, within the archive only.
-	for (const [name, link] of links) {
-		let target = link.target;
-		for (let depth = 0; ; depth++) {
-			if (depth > MAX_LINK_DEPTH) fail(`link loop at "${name}"`);
-			const hit = files.get(target);
-			if (hit) {
-				files.set(name, hit);
-				break;
-			}
-			const hop = links.get(target);
-			if (!hop) break; // dangling link: simply not a readable member
-			target = hop.target;
-		}
-	}
-	return { files };
-}
-
-/** Read one (small) member fully, refusing anything larger than `max`. */
-export function readMember(fd: number, m: TarMember, max: number, what: string): Buffer {
-	if (m.size > max) fail(`${what} is ${m.size} bytes — larger than the ${max}-byte limit`);
-	return readAt(fd, m.offset, m.size);
-}
-
-/** Read the first `n` bytes of a member (for magic-number sniffing). */
-export function peekMember(fd: number, m: TarMember, n: number): Buffer {
-	return readAt(fd, m.offset, Math.min(n, m.size));
-}