@cldmv/gh-broker 0.8.0 → 0.9.0

package/src/upstream.ts

@@ -1,85 +0,0 @@
-/**
- *
- *	@Project: @cldmv/gh-broker
- *	@Filename: /src/upstream.ts
- *	@Date: 2026-07-07T00:24:51-07:00 (1783409091)
- *	@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-02T11:30:58-07:00 (1790965858)
- *	-----
- *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
- *
- */
-
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import type { CallToolResult, Tool } from "@modelcontextprotocol/sdk/types.js";
-import type { Config } from "./types.ts";
-import type { Upstream } from "./router.ts";
-
-const CLIENT_INFO = { name: "cldmv-gh-broker", version: "0.1.0" };
-
-/**
- * Pool of MCP client connections to the hosted GitHub MCP — one per bearer token,
- * so each org's PAT drives its own upstream session. Connections are created lazily
- * and reused; the PAT is only ever set as an `Authorization: Bearer` header and is
- * never logged.
- */
-export class UpstreamPool implements Upstream {
-	private readonly url: URL;
-	private readonly clients = new Map<string, Promise<Client>>();
-
-	constructor(config: Config) {
-		this.url = new URL(config.upstream);
-	}
-
-	private connect(token: string): Promise<Client> {
-		const existing = this.clients.get(token);
-		if (existing) return existing;
-		const pending = (async (): Promise<Client> => {
-			const client = new Client(CLIENT_INFO);
-			const transport = new StreamableHTTPClientTransport(this.url, {
-				requestInit: { headers: { Authorization: `Bearer ${token}` } }
-			});
-			await client.connect(transport);
-			return client;
-		})();
-		// Don't cache a failed connect — let the next call retry.
-		pending.catch(() => this.clients.delete(token));
-		this.clients.set(token, pending);
-		return pending;
-	}
-
-	async forward(tool: string, args: Record<string, unknown>, token: string): Promise<CallToolResult> {
-		return this.withReconnect(token, (client) => client.callTool({ name: tool, arguments: args }) as Promise<CallToolResult>);
-	}
-
-	/** Fetch upstream tool schemas (owner-independent) to build the advertised catalog. */
-	async listToolsFor(token: string): Promise<Tool[]> {
-		return this.withReconnect(token, async (client) => (await client.listTools()).tools);
-	}
-
-	/**
-	 * Run an upstream op with a single transparent reconnect. The hosted MCP's
-	 * streamable-HTTP session can die server-side (idle-session expiry, upstream
-	 * restart) even though our cached client still looks connected — the next call
-	 * then fails with "invalid session". Rather than surface that first failure to
-	 * the agent (and leave it stuck until the whole broker restarts), evict the dead
-	 * client and retry ONCE with a fresh connection. A genuinely broken call (bad
-	 * token, real upstream error) fails the retry too and propagates.
-	 */
-	private async withReconnect<T>(token: string, op: (client: Client) => Promise<T>): Promise<T> {
-		for (let attempt = 0; ; attempt++) {
-			const client = await this.connect(token);
-			try {
-				return await op(client);
-			} catch (err) {
-				// Evict the (possibly stale) session so this retry / the next call reconnects.
-				this.clients.delete(token);
-				if (attempt >= 1) throw err;
-			}
-		}
-	}
-}

package/src/verbs/ghcr/archive.ts

@@ -1,314 +0,0 @@
-/**
- *
- *	@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
-	};
-}

package/src/verbs/ghcr/config.ts

@@ -1,142 +0,0 @@
-/**
- *
- *	@Project: @cldmv/gh-broker
- *	@Filename: /src/verbs/ghcr/config.ts
- *	@Date: 2026-10-31T10:57:30-07:00 (1793469450)
- *	@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-11-01T00:40:55-07:00 (1793518855)
- *	-----
- *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
- *
- */
-
-/**
- * Config block for the GHCR verbs (`ghcr_push`, `ghcr_push_status`, `ghcr_tags`).
- *
- * GHCR is a separate credential and a separate policy from the GitHub API routing in
- * `config.owners`: the registry does not accept fine-grained PATs, so it needs a classic
- * PAT with `write:packages`, and that token must only ever reach `ghcr.io`. Keeping it in
- * its own block (rather than a third ref on `owners.<o>`) keeps the existing owner
- * credentials untouched and lets the installer treat the whole block as operator data, set with
- * `--ghcr-*` flags or a `--config` file (see deploy/lib/config-merge.mjs).
- *
- *   "ghcr": {
- *     "dropDir": "/srv/gh-broker/ghcr-drop",
- *     "protectReleaseTags": true,
- *     "owners": {
- *       "your-org": { "username": "your-login", "credential": "cred:your-org-packages", "images": ["your-image", "your-image-worker-*"] }
- *     }
- *   }
- *
- * Every key is checked strictly (unknown keys are refused) because this is a security
- * policy: a typo such as `image` for `images` must fail loudly, not silently allow nothing
- * or everything.
- */
-
-import { isAbsolute, normalize } from "node:path";
-
-export interface GhcrOwnerConfig {
-	/** GitHub login the classic PAT belongs to; sent as the Basic-auth user to ghcr.io/token. */
-	username: string;
-	/** "cred:<name>" ref for the classic PAT (write:packages). */
-	credential: string;
-	/** Image names under ghcr.io/<owner>/ that may be pushed or listed. `*` matches within one path segment. */
-	images: string[];
-}
-
-export interface GhcrConfig {
-	/** The only directory archives are read from. Absolute; the installer creates it. */
-	dropDir: string;
-	/** Refuse to overwrite an existing tag shaped like a release (`1.2.3` / `v1.2.3`). */
-	protectReleaseTags: boolean;
-	/** Largest archive accepted, in bytes. */
-	maxArchiveBytes: number;
-	owners: Record<string, GhcrOwnerConfig>;
-}
-
-export const DEFAULT_MAX_ARCHIVE_BYTES = 16 * 1024 ** 3;
-const TOP_KEYS = new Set(["dropDir", "protectReleaseTags", "maxArchiveBytes", "owners"]);
-const OWNER_KEYS = new Set(["username", "credential", "images"]);
-/** Directories that must never be a drop dir: system state, other users' homes, secrets. */
-const FORBIDDEN_ROOTS = ["/etc", "/proc", "/sys", "/dev", "/run", "/boot", "/root", "/home", "/tmp", "/usr", "/bin", "/sbin", "/lib", "/lib64", "/var/tmp"];
-/** One image-name glob: lowercase OCI path components, `*` allowed, `/` separates segments. */
-const IMAGE_GLOB = /^[a-z0-9*](?:[a-z0-9._*-]*[a-z0-9*])?(?:\/[a-z0-9*](?:[a-z0-9._*-]*[a-z0-9*])?)*$/;
-const OWNER_NAME = /^[a-z0-9](?:[a-z0-9-]{0,38})$/;
-
-const fail = (msg: string): never => {
-	throw new Error(`config.ghcr${msg}`);
-};
-
-function strictKeys(o: Record<string, unknown>, allowed: Set<string>, where: string): void {
-	const extra = Object.keys(o).filter((k) => !allowed.has(k));
-	if (extra.length) fail(`${where}: unknown key(s) ${extra.join(", ")} — expected ${[...allowed].join(", ")}`);
-}
-
-const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
-
-export function parseGhcrConfig(raw: unknown): GhcrConfig {
-	if (!isObject(raw)) return fail(": must be an object");
-	strictKeys(raw, TOP_KEYS, "");
-
-	const dropDir = raw.dropDir;
-	if (typeof dropDir !== "string" || !isAbsolute(dropDir)) fail('.dropDir: must be an absolute path, e.g. "/srv/gh-broker/ghcr-drop"');
-	const dir = normalize(dropDir as string).replace(/\/+$/, "");
-	if (!dir || dir !== (dropDir as string).replace(/\/+$/, "")) fail(".dropDir: must be a normalized path (no ., .. or doubled slashes)");
-	if (dir.split("/").filter(Boolean).length < 2) fail(".dropDir: must be at least two levels deep, e.g. /srv/gh-broker/ghcr-drop");
-	for (const root of FORBIDDEN_ROOTS) {
-		if (dir === root || dir.startsWith(`${root}/`)) fail(`.dropDir: may not be under ${root}`);
-	}
-
-	if (raw.protectReleaseTags !== undefined && typeof raw.protectReleaseTags !== "boolean") fail(".protectReleaseTags: must be a boolean");
-	let maxArchiveBytes = DEFAULT_MAX_ARCHIVE_BYTES;
-	if (raw.maxArchiveBytes !== undefined) {
-		const m = raw.maxArchiveBytes;
-		if (typeof m !== "number" || !Number.isSafeInteger(m) || m <= 0) fail(".maxArchiveBytes: must be a positive integer");
-		maxArchiveBytes = m as number;
-	}
-
-	if (!isObject(raw.owners) || Object.keys(raw.owners).length === 0) fail(".owners: must be an object with at least one owner");
-	const owners: Record<string, GhcrOwnerConfig> = {};
-	for (const [name, v] of Object.entries(raw.owners as Record<string, unknown>)) {
-		const owner = name.toLowerCase();
-		if (!OWNER_NAME.test(owner)) fail(`.owners: "${name}" is not a valid GitHub owner name`);
-		if (!isObject(v)) fail(`.owners.${name}: must be an object`);
-		const o = v as Record<string, unknown>;
-		strictKeys(o, OWNER_KEYS, `.owners.${name}`);
-		if (typeof o.username !== "string" || !/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/.test(o.username)) fail(`.owners.${name}.username: must be the GitHub login that owns the PAT`);
-		if (typeof o.credential !== "string" || !/^cred:[A-Za-z0-9._-]+$/.test(o.credential) || /^cred:\.\.?$/.test(o.credential)) {
-			fail(`.owners.${name}.credential: must be a "cred:<name>" ref`);
-		}
-		if (!Array.isArray(o.images) || o.images.length === 0) fail(`.owners.${name}.images: must be a non-empty list of image names or globs`);
-		for (const img of o.images as unknown[]) {
-			if (typeof img !== "string" || img.length > 255 || !IMAGE_GLOB.test(img)) {
-				fail(`.owners.${name}.images: "${String(img)}" is not a valid image name or glob (lowercase, [a-z0-9._-], "/" between segments, "*" within a segment)`);
-			}
-		}
-		owners[owner] = { username: o.username as string, credential: o.credential as string, images: [...(o.images as string[])] };
-	}
-
-	return { dropDir: dir, protectReleaseTags: raw.protectReleaseTags !== false, maxArchiveBytes, owners };
-}
-
-/** Every "cred:<name>" ref the ghcr block references, for eager validation at startup. */
-export function ghcrCredRefs(cfg: GhcrConfig | undefined): string[] {
-	return cfg ? Object.values(cfg.owners).map((o) => o.credential) : [];
-}
-
-/** Compile an image glob to an anchored regex: `*` matches `[a-z0-9._-]*` (never `/`). */
-export function imageGlobToRegExp(glob: string): RegExp {
-	const body = glob
-		.split("*")
-		.map((part) => part.replace(/[.\\^$+?()[\]{}|-]/g, "\\$&"))
-		.join("[a-z0-9._-]*");
-	return new RegExp(`^${body}$`);
-}
-
-/** True when `image` (a name under the owner, e.g. "hoot-worker-a") is on the owner's allowlist. */
-export function imageAllowed(owner: GhcrOwnerConfig, image: string): boolean {
-	return owner.images.some((g) => imageGlobToRegExp(g).test(image));
-}

package/src/verbs/ghcr/jobs.ts

@@ -1,141 +0,0 @@
-/**
- *
- *	@Project: @cldmv/gh-broker
- *	@Filename: /src/verbs/ghcr/jobs.ts
- *	@Date: 2026-10-31T11:08:29-07:00 (1793470109)
- *	@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.
- *
- */
-
-/**
- * In-memory queue for GHCR push jobs.
- *
- * Images are 1–3 GB, far longer than one MCP call should block, so `ghcr_push` enqueues a
- * job and returns its id; `ghcr_push_status` reads it back. Jobs run one at a time (a
- * push saturates the uplink; two at once only make both slower) in submission order.
- *
- * Bounded on purpose: at most `maxPending` queued-or-running jobs (each holds an open
- * archive descriptor), and only the newest `keepFinished` finished jobs are remembered.
- * State lives in memory only, so a broker restart forgets every job; a push that was
- * running is simply not completed (the registry discards an unfinished upload, and no
- * tag moves until the final manifest PUT).
- */
-
-import { randomUUID } from "node:crypto";
-import type { PushProgress, PushResult } from "./push.ts";
-
-export type JobState = "queued" | "running" | "succeeded" | "failed";
-
-export interface JobMeta {
-	owner: string;
-	/** e.g. "ghcr.io/cldmv/hoot" */
-	image: string;
-	tag: string;
-	archive: string;
-	archiveBytes: number;
-	format: string;
-}
-
-export interface Job extends JobMeta {
-	job: string;
-	state: JobState;
-	progress?: PushProgress;
-	result?: PushResult;
-	error?: string;
-	createdAt: string;
-	startedAt?: string;
-	finishedAt?: string;
-}
-
-export interface JobHooks {
-	/** Does the work. Report progress through `progress`; resolve with the result or throw. */
-	run(progress: (p: PushProgress) => void): Promise<PushResult>;
-	/** Always called once the job ends (success, failure, or never started). */
-	finally?(job: Job): void;
-	/** Turns a thrown error into the message stored on the job (must already be secret-free). */
-	describeError?(err: unknown): string;
-}
-
-export class QueueFull extends Error {}
-
-export class JobQueue {
-	private readonly jobs = new Map<string, Job>();
-	private readonly pending: Array<{ job: Job; hooks: JobHooks }> = [];
-	private running = false;
-	private readonly maxPending: number;
-	private readonly keepFinished: number;
-
-	constructor({ maxPending = 8, keepFinished = 50 }: { maxPending?: number; keepFinished?: number } = {}) {
-		this.maxPending = maxPending;
-		this.keepFinished = keepFinished;
-	}
-
-	/** Queued + running jobs. */
-	activeCount(): number {
-		return this.pending.length + (this.running ? 1 : 0);
-	}
-
-	submit(meta: JobMeta, hooks: JobHooks): Job {
-		if (this.activeCount() >= this.maxPending) throw new QueueFull(`ghcr_push: ${this.activeCount()} pushes are already queued or running — wait for one to finish (ghcr_push_status)`);
-		const job: Job = { ...meta, job: randomUUID(), state: "queued", createdAt: new Date().toISOString() };
-		this.jobs.set(job.job, job);
-		this.pending.push({ job, hooks });
-		const snapshot = { ...job }; // as submitted, before pump() may flip it to running
-		void this.pump();
-		return snapshot;
-	}
-
-	get(id: string): Job | undefined {
-		const j = this.jobs.get(id);
-		return j ? structuredClone(j) : undefined;
-	}
-
-	list(owner: string): Job[] {
-		return [...this.jobs.values()].filter((j) => j.owner === owner).map((j) => structuredClone(j));
-	}
-
-	/** Resolves once nothing is queued or running (for tests and orderly shutdown). */
-	async idle(): Promise<void> {
-		while (this.activeCount() > 0) await new Promise((r) => setTimeout(r, 5));
-	}
-
-	private async pump(): Promise<void> {
-		if (this.running) return;
-		const next = this.pending.shift();
-		if (!next) return;
-		this.running = true;
-		const { job, hooks } = next;
-		job.state = "running";
-		job.startedAt = new Date().toISOString();
-		try {
-			job.result = await hooks.run((p) => {
-				job.progress = p;
-			});
-			job.state = "succeeded";
-		} catch (err) {
-			job.state = "failed";
-			job.error = hooks.describeError ? hooks.describeError(err) : "push failed";
-		} finally {
-			job.finishedAt = new Date().toISOString();
-			try {
-				hooks.finally?.(structuredClone(job));
-			} catch {
-				/* a cleanup/audit hook must not wedge the queue */
-			}
-			this.running = false;
-			this.prune();
-			void this.pump();
-		}
-	}
-
-	private prune(): void {
-		const finished = [...this.jobs.values()].filter((j) => j.state === "succeeded" || j.state === "failed");
-		for (const j of finished.slice(0, Math.max(0, finished.length - this.keepFinished))) this.jobs.delete(j.job);
-	}
-}