@cldmv/gh-broker 0.7.0 → 0.8.0

package/src/router.ts

@@ -7,7 +7,7 @@
  *	@Email: <Shinrai@users.noreply.github.com>
  *	-----
  *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
- *	@Last modified time: 2026-10-16T17:17:03-07:00 (1792196223)
+ *	@Last modified time: 2026-10-31T12:12:11-07:00 (1793473931)
  *	-----
  *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
  *
@@ -19,6 +19,7 @@ import type { AppAuth } from "./appauth.ts";
 import { Octokit } from "@octokit/core";
 import { indexTools } from "./config.ts";
 import { audit } from "./audit.ts";
+import { unavailableReason } from "./availability.ts";
 // DEFERRED: link_issue is App-token-only and not wired in — see docs.
 // import { linkIssue, type LinkIssueInput } from "./verbs/link_issue.ts";
 import {
@@ -32,6 +33,11 @@ import { reportSecurityAlerts, type ReportSecurityAlertsInput } from "./verbs/re
 import { reportReleasePrs, type ReportReleasePrsInput } from "./verbs/report_release_prs.ts";
 import { issueLabels, type IssueLabelsInput } from "./verbs/issue_labels.ts";
 import { reportCiStatus, ciStatusForHeadSha, type ReportCiStatusInput, type FailedJobLogsFetcher } from "./verbs/report_ci_status.ts";
+import { npmScaffold } from "./verbs/npm_scaffold.ts";
+import { NpmRegistry } from "./verbs/npm-registry.ts";
+import { GhcrService } from "./verbs/ghcr_push.ts";
+
+const GHCR_TOOLS = new Set(["ghcr_push", "ghcr_push_status", "ghcr_tags"]);
 
 /** What the router needs from the upstream (hosted-MCP) client pool. */
 export interface Upstream {
@@ -48,6 +54,8 @@ export class Router {
 	private readonly upstream: Upstream;
 	private readonly appAuth?: AppAuth;
 	private readonly rules: Map<string, ToolRule>;
+	/** GHCR verbs run on config.ghcr's own credential, not the owner's GitHub PAT (created on first use). */
+	private ghcr?: GhcrService;
 
 	constructor(config: Config, secrets: SecretStore, upstream: Upstream, appAuth?: AppAuth) {
 		this.config = config;
@@ -59,7 +67,7 @@ export class Router {
 
 	/** Tools advertised to the agent (used to build tools/list). */
 	advertisedTools(): ToolRule[] {
-		return this.config.tools;
+		return this.config.tools.filter((rule) => !unavailableReason(rule, this.config, this.secrets));
 	}
 
 	async call(tool: string, args: Record<string, unknown>): Promise<CallToolResult> {
@@ -68,6 +76,15 @@ export class Router {
 			audit({ tool, decision: "deny", detail: "not in allowlist" });
 			throw new Error(`tool "${tool}" is not allowed`);
 		}
+		// An optional integration that isn't set up hides its tools: refuse them the same way.
+		const unavailable = unavailableReason(rule, this.config, this.secrets);
+		if (unavailable) {
+			audit({ tool, decision: "deny", detail: `unavailable: ${unavailable}` });
+			throw new Error(`tool "${tool}" is not available on this broker: ${unavailable}`);
+		}
+		// The GHCR verbs authenticate with config.ghcr's own credential, never an owner's GitHub
+		// PAT, so they don't need (or touch) a config.owners entry.
+		if (GHCR_TOOLS.has(tool)) return this.callGhcr(tool, args, rule);
 		// Owner-less reads (global advisory DB, get_me, notifications) fall back to
 		// the configured defaultOwner's READ PAT. Writes never fall back — a write
 		// must always name the owner it targets.
@@ -102,6 +119,21 @@ export class Router {
 		}
 	}
 
+	/** GHCR verbs: config.ghcr checks the owner and image itself; no GitHub PAT is resolved. */
+	private async callGhcr(tool: string, args: Record<string, unknown>, rule: ToolRule): Promise<CallToolResult> {
+		const owner = extractOwner(args) ?? "";
+		const repo = typeof args.image === "string" ? `${owner}/${args.image}` : owner;
+		try {
+			this.ghcr ??= new GhcrService(this.config.ghcr, this.secrets);
+			const out = tool === "ghcr_push" ? await this.ghcr.push(args) : tool === "ghcr_tags" ? await this.ghcr.tags(args) : this.ghcr.status(args);
+			audit({ tool, owner, mode: rule.mode, repo, decision: "custom", ok: true });
+			return { content: [{ type: "text", text: JSON.stringify(out) }] };
+		} catch (err) {
+			audit({ tool, owner, mode: rule.mode, repo, decision: "custom", ok: false, detail: (err as Error).message });
+			throw err;
+		}
+	}
+
 	private async dispatchCustom(
 		tool: string,
 		args: Record<string, unknown>,
@@ -158,6 +190,15 @@ export class Router {
 				const out = await reportCiStatus(octokit, reportArgs, this.makeJobLogsFetcher(owner, reportArgs.repo, token));
 				return { content: [{ type: "text", text: JSON.stringify(out) }] };
 			}
+			case "npm_scaffold": {
+				const npm = this.config.npm!; // availability already required it
+				// The GitHub side only reads (repo metadata, package.json, workflow file), so it
+				// runs on the read PAT even though the verb is a write.
+				const octokit = new Octokit({ auth: this.secrets.resolve(this.config.owners[owner]!.read) });
+				const registry = new NpmRegistry({ token: this.secrets.resolve(npm.token), ...(npm.registry ? { registry: npm.registry } : {}) });
+				const out = await npmScaffold(args, { octokit, registry, scopes: npm.scopes });
+				return { content: [{ type: "text", text: JSON.stringify(out) }] };
+			}
 			default:
 				throw new Error(`custom verb "${tool}" not implemented`);
 		}

package/src/secrets.ts

@@ -7,7 +7,7 @@
  *	@Email: <Shinrai@users.noreply.github.com>
  *	-----
  *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
- *	@Last modified time: 2026-10-02T11:30:58-07:00 (1790965858)
+ *	@Last modified time: 2026-10-31T12:12:11-07:00 (1793473931)
  *	-----
  *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
  *
@@ -17,6 +17,7 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import type { Config, SecretStore } from "./types.ts";
 import { resolveSecretsPath } from "./paths.ts";
+import { ghcrCredRefs } from "./verbs/ghcr/config.ts";
 
 const CRED_PREFIX = "cred:";
 
@@ -48,6 +49,22 @@ export function loadSecretStore(config: Config): SecretStore {
 
 const SAFE_CRED_NAME = /^[A-Za-z0-9._-]+$/;
 
+/** A store over a reader that throws for a missing/empty credential. */
+function storeFrom(read: (name: string) => string): SecretStore {
+	return {
+		resolve: (ref) => read(credName(ref)),
+		has: (ref) => {
+			const name = credName(ref);
+			try {
+				read(name);
+				return true;
+			} catch {
+				return false;
+			}
+		}
+	};
+}
+
 /**
  * Credential names become filesystem path components (`join(dir, name)`) and are
  * interpolated into systemd drop-in lines, so constrain them to a safe charset —
@@ -66,7 +83,13 @@ function credName(ref: string): string {
 	return assertSafeName(ref.slice(CRED_PREFIX.length));
 }
 
-/** Eagerly read every referenced credential so a missing token fails at startup, not on first request. */
+/**
+ * Eagerly read every REQUIRED credential (the owners' PATs, the App key) so a missing token
+ * fails at startup, not on first request. Optional credentials (the npm token, the GHCR
+ * credentials) are only
+ * format-checked here: when one isn't stored, the tools that need it are hidden instead
+ * (see availability.ts), and the rest of the broker runs normally.
+ */
 function validateRefs(config: Config, read: (name: string) => string): void {
 	for (const [owner, creds] of Object.entries(config.owners)) {
 		for (const ref of [creds.read, creds.write]) {
@@ -82,6 +105,13 @@ function validateRefs(config: Config, read: (name: string) => string): void {
 		}
 		read(assertSafeName(config.app.privateKey.slice(CRED_PREFIX.length)));
 	}
+	if (config.npm) {
+		if (!config.npm.token.startsWith(CRED_PREFIX)) throw new Error(`secrets: config.npm.token must be a "cred:<name>" ref, got "${config.npm.token}"`);
+		assertSafeName(config.npm.token.slice(CRED_PREFIX.length));
+	}
+	// GHCR credentials are optional too: format-checked here, and the ghcr_* tools are hidden
+	// while none is stored (availability.ts).
+	for (const ref of ghcrCredRefs(config.ghcr)) credName(ref);
 }
 
 /** systemd-creds provider: read decrypted creds from $CREDENTIALS_DIRECTORY. */
@@ -105,7 +135,7 @@ function systemdCredsStore(config: Config): SecretStore {
 		return val;
 	};
 	validateRefs(config, read);
-	return { resolve: (ref) => read(credName(ref)) };
+	return storeFrom(read);
 }
 
 /** file provider: read tokens from a JSON `{ "<name>": "<token>" }` map. */
@@ -133,5 +163,5 @@ function fileStore(config: Config): SecretStore {
 		return token;
 	};
 	validateRefs(config, read);
-	return { resolve: (ref) => read(credName(ref)) };
+	return storeFrom(read);
 }

package/src/types.ts

@@ -7,7 +7,7 @@
  *	@Email: <Shinrai@users.noreply.github.com>
  *	-----
  *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
- *	@Last modified time: 2026-10-02T11:30:58-07:00 (1790965858)
+ *	@Last modified time: 2026-10-31T12:12:12-07:00 (1793473932)
  *	-----
  *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
  *
@@ -23,6 +23,8 @@
  * safe to copy between machines.
  */
 
+import type { GhcrConfig } from "./verbs/ghcr/config.ts";
+
 export type Mode = "read" | "write";
 
 /**
@@ -73,6 +75,22 @@ export interface SecretsConfig {
 	path?: string;
 }
 
+/**
+ * npm integration for `npm_scaffold`. Optional: without it the verb refuses. The token is a
+ * granular access token created by the installer without 2FA bypass, so every write it makes
+ * still needs a user-supplied one-time password.
+ */
+export interface NpmConfig {
+	/** Credential reference (e.g. "cred:npm-token") for the granular access token. */
+	token: string;
+	/** Scopes the verb may create packages in, e.g. ["@cldmv"]. */
+	scopes: string[];
+	/** Registry base URL. Defaults to https://registry.npmjs.org. */
+	registry?: string;
+	/** Installer only: npm orgs the token is also granted org read-write on when it is created. */
+	tokenOrgs?: string[];
+}
+
 export interface Config {
 	/** e.g. "unix:/run/gh-broker/gh-broker.sock" */
 	listen: string;
@@ -96,9 +114,15 @@ export interface Config {
 	app?: AppConfig;
 	/** Optional secret-store backend selection. Defaults to the systemd-creds provider. */
 	secrets?: SecretsConfig;
+	/** Optional npm integration (`npm_scaffold`). */
+	npm?: NpmConfig;
+	/** Optional GHCR push policy + credentials for the ghcr_* verbs (src/verbs/ghcr/config.ts). */
+	ghcr?: GhcrConfig;
 }
 
 /** Resolves a "cred:<name>" reference to a token, never logging it. */
 export interface SecretStore {
 	resolve(ref: string): string;
+	/** Whether an optional credential is stored (non-empty). Never throws for a missing one. */
+	has(ref: string): boolean;
 }

package/src/verbs/ghcr/archive.ts

@@ -0,0 +1,314 @@
+/**
+ *
+ *	@Project: @cldmv/gh-broker
+ *	@Filename: /src/verbs/ghcr/archive.ts
+ *	@Date: 2026-10-31T10:59:13-07:00 (1793469553)
+ *	@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:33-07:00 (1793514393)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ *
+ */
+
+/**
+ * Opens an image archive from the GHCR drop directory and works out what to push.
+ *
+ * The archive path comes from the agent, and the broker can read files the agent can't
+ * (its own credentials among them). A path that resolves outside the drop directory would
+ * let the agent have the broker upload a secret into a registry the agent can then pull
+ * from. So the file is opened exactly once, by descriptor, and every check runs against
+ * that descriptor rather than the path:
+ *
+ *  1. lexical: the normalized path must sit under `dropDir`;
+ *  2. the real (symlink-resolved) parent directory must be the real `dropDir` or under it,
+ *     so a symlinked subdirectory pointing elsewhere is refused before anything is opened;
+ *     steps 1 and 2 give the same answer for every refusal, so a path elsewhere reveals
+ *     nothing about what exists there;
+ *  3. `O_NOFOLLOW | O_NONBLOCK`: the last component can't be a symlink, and a FIFO can't
+ *     hang the open;
+ *  4. `/proc/self/fd/<fd>`: the file actually opened lives under the real `dropDir`. This
+ *     runs before any check that describes the file, and catches a parent directory swapped
+ *     between step 2 and the open;
+ *  5. `fstat`: a regular file, exactly one link (no hard link to a file elsewhere), not
+ *     empty, not over `maxArchiveBytes`.
+ *
+ * All later reads use positional reads on that descriptor; the path is never reopened.
+ *
+ * Two archive formats are read:
+ *  - OCI image layout (`index.json` + `blobs/sha256/…`): `docker save` on Docker 25+,
+ *    `docker buildx build --output type=oci`, `skopeo copy … oci-archive:`.
+ *  - docker-archive (`manifest.json` only): `docker save` on older Docker.
+ *
+ * Layers that are already gzip/zstd-compressed are pushed byte-for-byte. Uncompressed
+ * layers (what `docker save` writes for the classic image store) are gzipped on the fly at
+ * push time, and the manifest is then rebuilt as an OCI image manifest.
+ */
+
+import { closeSync, constants, fstatSync, openSync, readlinkSync, realpathSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { dirname, isAbsolute, join, normalize } from "node:path";
+import { indexTar, peekMember, readMember, type TarIndex, type TarMember } from "./tar.ts";
+
+export const MEDIA = {
+	ociIndex: "application/vnd.oci.image.index.v1+json",
+	ociManifest: "application/vnd.oci.image.manifest.v1+json",
+	ociConfig: "application/vnd.oci.image.config.v1+json",
+	ociLayer: "application/vnd.oci.image.layer.v1.tar",
+	ociLayerGzip: "application/vnd.oci.image.layer.v1.tar+gzip",
+	ociLayerZstd: "application/vnd.oci.image.layer.v1.tar+zstd",
+	dockerList: "application/vnd.docker.distribution.manifest.list.v2+json",
+	dockerManifest: "application/vnd.docker.distribution.manifest.v2+json",
+	dockerConfig: "application/vnd.docker.container.image.v1+json",
+	dockerLayer: "application/vnd.docker.image.rootfs.diff.tar",
+	dockerLayerGzip: "application/vnd.docker.image.rootfs.diff.tar.gzip"
+} as const;
+
+const MANIFEST_TYPES = new Set<string>([MEDIA.ociManifest, MEDIA.dockerManifest]);
+const INDEX_TYPES = new Set<string>([MEDIA.ociIndex, MEDIA.dockerList]);
+const LAYER_TYPES = new Set<string>([MEDIA.ociLayer, MEDIA.ociLayerGzip, MEDIA.ociLayerZstd, MEDIA.dockerLayer, MEDIA.dockerLayerGzip]);
+const CONFIG_TYPES = new Set<string>([MEDIA.ociConfig, MEDIA.dockerConfig]);
+const DIGEST = /^sha256:[a-f0-9]{64}$/;
+const MAX_JSON = 4 * 1024 * 1024;
+export const MAX_LAYERS = 256;
+
+export class ArchiveError extends Error {}
+
+const fail = (msg: string): never => {
+	throw new ArchiveError(`archive: ${msg}`);
+};
+
+export interface OpenedArchive {
+	fd: number;
+	/** The real path of the opened file (inside dropDir). */
+	path: string;
+	size: number;
+	close(): void;
+}
+
+/** Securely open `input` (absolute, or relative to dropDir) — see the file comment for the checks. */
+export function openArchive(input: unknown, dropDir: string, maxBytes: number): OpenedArchive {
+	if (typeof input !== "string" || !input || input.length > 4096 || input.includes("\0")) fail('"archive" must be a file path inside the drop directory');
+	const candidate = normalize(isAbsolute(input as string) ? (input as string) : join(dropDir, input as string));
+	// One answer for every path that can't be confirmed to be in the drop dir (outside it,
+	// behind a symlinked or missing subdirectory), so none of them reveals anything.
+	const outside = `"archive" must be an existing file inside the drop directory ${dropDir}`;
+	if (!candidate.startsWith(`${dropDir}/`)) fail(outside);
+
+	let realDrop: string;
+	try {
+		realDrop = realpathSync(dropDir);
+	} catch {
+		return fail(`drop directory ${dropDir} does not exist — the installer creates it`);
+	}
+	// A symlinked subdirectory would make the open below follow it out of the drop dir.
+	let realParent: string;
+	try {
+		realParent = realpathSync(dirname(candidate));
+	} catch {
+		return fail(outside);
+	}
+	if (realParent !== realDrop && !realParent.startsWith(`${realDrop}/`)) fail(outside);
+
+	let fd: number;
+	try {
+		fd = openSync(candidate, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+	} catch (err) {
+		const code = (err as NodeJS.ErrnoException).code;
+		if (code === "ELOOP") return fail(`${candidate} is a symlink — put the archive file itself in the drop directory`);
+		if (code === "ENOENT" || code === "ENOTDIR") return fail(`${candidate} not found`);
+		if (code === "EACCES") return fail(`${candidate} is not readable by the broker — make it group-readable (chmod g+r)`);
+		// openSync errors always carry an errno code, so the "error" fallback is unreachable; it only satisfies the type.
+		/* v8 ignore next */
+		return fail(`cannot open ${candidate} (${code ?? "error"})`);
+	}
+	try {
+		// Containment first: nothing about a file outside the drop dir is described.
+		const real = readlinkSync(`/proc/self/fd/${fd}`);
+		// Reachable when a parent directory is swapped for a symlink between the realpath check
+		// above and the open (a race the suite cannot drive deterministically); guarded because
+		// that race is exactly how a broker-only file could otherwise be read.
+		/* v8 ignore next */
+		if (!real.startsWith(`${realDrop}/`)) fail(outside);
+		const st = fstatSync(fd);
+		if (!st.isFile()) fail(`${candidate} is not a regular file`);
+		if (st.nlink !== 1) fail(`${candidate} has ${st.nlink} hard links — copy the archive instead of linking it`);
+		if (st.size === 0) fail(`${candidate} is empty`);
+		if (st.size > maxBytes) fail(`${candidate} is ${st.size} bytes — over the ${maxBytes}-byte limit (ghcr.maxArchiveBytes)`);
+		let closed = false;
+		return {
+			fd,
+			path: real,
+			size: st.size,
+			close() {
+				if (closed) return;
+				closed = true;
+				closeSync(fd);
+			}
+		};
+	} catch (err) {
+		closeSync(fd);
+		throw err;
+	}
+}
+
+/** One blob to push. `digest`/`size` are what the registry will hold (known up front unless `compress`). */
+export interface BlobPlan {
+	member: TarMember;
+	mediaType: string;
+	/** Digest + size in the archive (for a compressed-on-push layer: of the uncompressed tar). */
+	sourceDigest?: string;
+	sourceSize: number;
+	/** Gzip this layer while pushing it (archive holds it uncompressed). */
+	compress: boolean;
+}
+
+export interface ImagePlan {
+	format: "oci-layout" | "docker-archive";
+	config: BlobPlan & { digest: string };
+	layers: BlobPlan[];
+	/** Set when the archive's own manifest can be pushed unchanged (nothing recompressed or retyped). */
+	verbatimManifest?: { bytes: Buffer; mediaType: string; digest: string };
+	annotations?: Record<string, string>;
+}
+
+const sha256 = (b: Buffer): string => `sha256:${createHash("sha256").update(b).digest("hex")}`;
+
+function parseJson(buf: Buffer, what: string): unknown {
+	try {
+		return JSON.parse(buf.toString("utf8"));
+	} catch {
+		return fail(`${what} is not valid JSON`);
+	}
+}
+
+interface Descriptor {
+	mediaType?: string;
+	digest?: string;
+	size?: number;
+	annotations?: Record<string, string>;
+	platform?: { os?: string; architecture?: string };
+}
+
+function blobMember(index: TarIndex, digest: unknown, what: string): TarMember {
+	if (typeof digest !== "string" || !DIGEST.test(digest)) fail(`${what} has an unsupported digest (only sha256 is accepted)`);
+	const m = index.files.get(`blobs/sha256/${(digest as string).slice("sha256:".length)}`);
+	if (!m) fail(`${what} ${digest} is missing from the archive`);
+	return m as TarMember;
+}
+
+function readBlobJson(fd: number, index: TarIndex, d: Descriptor, what: string): { bytes: Buffer; json: unknown } {
+	const m = blobMember(index, d.digest, what);
+	const bytes = readMember(fd, m, MAX_JSON, what);
+	if (sha256(bytes) !== d.digest) fail(`${what} does not match its digest`);
+	return { bytes, json: parseJson(bytes, what) };
+}
+
+/**
+ * The image entries of an index: buildx attestation manifests and unknown/unknown platform
+ * entries are not images. When several remain, keep only those whose manifest blob is in
+ * the archive: with the containerd image store, `docker save` writes the image's whole
+ * multi-platform index but only the blobs of the platform that was pulled.
+ */
+function images(manifests: unknown, index: TarIndex): Descriptor[] {
+	if (!Array.isArray(manifests)) return fail("index has no manifests list");
+	const list = (manifests as Descriptor[]).filter(
+		(d) => d?.annotations?.["vnd.docker.reference.type"] !== "attestation-manifest" && !(d?.platform?.os === "unknown" && d?.platform?.architecture === "unknown")
+	);
+	if (list.length <= 1) return list;
+	return list.filter((d) => typeof d?.digest === "string" && DIGEST.test(d.digest) && index.files.has(`blobs/sha256/${d.digest.slice("sha256:".length)}`));
+}
+
+function sniff(fd: number, m: TarMember): "gzip" | "zstd" | "none" {
+	const head = peekMember(fd, m, 4);
+	if (head.length >= 2 && head[0] === 0x1f && head[1] === 0x8b) return "gzip";
+	if (head.length >= 4 && head.readUInt32LE(0) === 0xfd2fb528) return "zstd";
+	return "none";
+}
+
+/** Decide how a layer is pushed: verbatim when already compressed, gzipped on the fly otherwise. */
+function layerPlan(fd: number, m: TarMember, declared: string | undefined, sourceDigest: string | undefined): BlobPlan {
+	if (declared !== undefined && !LAYER_TYPES.has(declared)) fail(`layer media type "${declared}" is not supported (non-distributable and foreign layers are refused)`);
+	const kind = sniff(fd, m);
+	if (kind === "gzip") {
+		const mediaType = declared === MEDIA.ociLayerGzip || declared === MEDIA.dockerLayerGzip ? declared : MEDIA.ociLayerGzip;
+		return { member: m, mediaType, sourceDigest, sourceSize: m.size, compress: false };
+	}
+	if (kind === "zstd") return { member: m, mediaType: MEDIA.ociLayerZstd, sourceDigest, sourceSize: m.size, compress: false };
+	return { member: m, mediaType: MEDIA.ociLayerGzip, sourceDigest, sourceSize: m.size, compress: true };
+}
+
+/** Read the archive's index/manifest and plan the push. Reads only small JSON members and 4-byte layer heads. */
+export function planImage(fd: number, size: number): ImagePlan {
+	const index = indexTar(fd, size);
+	const top = index.files.get("index.json");
+	if (top) return planOciLayout(fd, index, top);
+	const legacy = index.files.get("manifest.json");
+	if (legacy) return planDockerArchive(fd, index, legacy);
+	return fail("not an image archive (no index.json or manifest.json) — create it with `docker save <image> -o <file>`");
+}
+
+function planOciLayout(fd: number, index: TarIndex, top: TarMember): ImagePlan {
+	const root = parseJson(readMember(fd, top, MAX_JSON, "index.json"), "index.json") as { manifests?: unknown };
+	let list = images(root.manifests, index);
+	let desc: Descriptor | undefined = list.length === 1 ? list[0] : undefined;
+	// docker save / buildx often wrap the image manifest in one more index level.
+	if (desc && INDEX_TYPES.has(desc.mediaType ?? "")) {
+		const nested = readBlobJson(fd, index, desc, "nested index").json as { manifests?: unknown };
+		list = images(nested.manifests, index);
+		desc = list.length === 1 ? list[0] : undefined;
+	}
+	if (!desc) fail(`archive holds ${list.length} images — save exactly one single-platform image per archive`);
+	const d = desc as Descriptor;
+	if (!MANIFEST_TYPES.has(d.mediaType ?? "")) fail(`manifest media type "${d.mediaType}" is not supported`);
+	const { bytes, json } = readBlobJson(fd, index, d, "image manifest");
+	const man = json as { config?: Descriptor; layers?: Descriptor[]; annotations?: Record<string, string> };
+	if (!man.config || !Array.isArray(man.layers)) fail("image manifest has no config or layers");
+	if (man.layers!.length > MAX_LAYERS) fail(`image has ${man.layers!.length} layers — at most ${MAX_LAYERS}`);
+
+	const cfg = man.config as Descriptor;
+	if (!CONFIG_TYPES.has(cfg.mediaType ?? "")) fail(`config media type "${cfg.mediaType}" is not supported`);
+	const cfgMember = blobMember(index, cfg.digest, "image config");
+	if (cfgMember.size !== cfg.size) fail("image config size does not match its descriptor");
+
+	let changed = false;
+	const layers = man.layers!.map((l, i) => {
+		const m = blobMember(index, l.digest, `layer ${i + 1}`);
+		if (m.size !== l.size) fail(`layer ${i + 1} size does not match its descriptor`);
+		const plan = layerPlan(fd, m, l.mediaType, l.digest);
+		if (plan.compress || plan.mediaType !== l.mediaType) changed = true;
+		return plan;
+	});
+	return {
+		format: "oci-layout",
+		config: { member: cfgMember, mediaType: cfg.mediaType!, digest: cfg.digest!, sourceDigest: cfg.digest, sourceSize: cfgMember.size, compress: false },
+		layers,
+		...(changed ? {} : { verbatimManifest: { bytes, mediaType: d.mediaType!, digest: d.digest! } }),
+		...(man.annotations ? { annotations: man.annotations } : {})
+	};
+}
+
+function planDockerArchive(fd: number, index: TarIndex, legacy: TarMember): ImagePlan {
+	const list = parseJson(readMember(fd, legacy, MAX_JSON, "manifest.json"), "manifest.json");
+	if (!Array.isArray(list) || list.length !== 1) fail(`archive holds ${Array.isArray(list) ? list.length : 0} images — save exactly one image per archive`);
+	const entry = (list as Array<{ Config?: unknown; Layers?: unknown }>)[0]!;
+	if (typeof entry.Config !== "string" || !Array.isArray(entry.Layers)) fail("manifest.json entry has no Config or Layers");
+	if ((entry.Layers as unknown[]).length > MAX_LAYERS) fail(`image has ${(entry.Layers as unknown[]).length} layers — at most ${MAX_LAYERS}`);
+
+	const member = (name: unknown, what: string): TarMember => {
+		const m = typeof name === "string" ? index.files.get(name.replace(/^\.?\//, "")) : undefined;
+		if (!m) fail(`${what} "${String(name)}" is missing from the archive`);
+		return m as TarMember;
+	};
+	const cfgMember = member(entry.Config, "image config");
+	const cfgBytes = readMember(fd, cfgMember, MAX_JSON, "image config");
+	parseJson(cfgBytes, "image config");
+	const layers = (entry.Layers as unknown[]).map((name, i) => layerPlan(fd, member(name, `layer ${i + 1}`), undefined, undefined));
+	return {
+		format: "docker-archive",
+		config: { member: cfgMember, mediaType: MEDIA.ociConfig, digest: sha256(cfgBytes), sourceSize: cfgMember.size, compress: false },
+		layers
+	};
+}