@telorun/kernel 0.42.0 → 0.43.0

package/dist/transports/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/transports/transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAEhE;;;sDAGsD;AACtD,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAED;;;;iEAIiE;AACjE,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;kFAEkF;AAClF,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;6CACyC;IACzC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE;QACf,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;KACjB,KAAK,IAAI,CAAC;CACZ;AAED;;;;;;;;;;;;yDAYyD;AACzD,MAAM,WAAW,SAAS;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAE/B;;gFAE4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAEhC;;6EAEyE;IACzE,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IAE5C;;;6BAGyB;IACzB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC;IAEpD;;;kFAG8E;IAC9E,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAErD;;qEAEiE;IACjE,OAAO,CACL,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,aAAa,EACrB,IAAI,CAAC,EAAE,cAAc,GACpB,OAAO,CAAC,aAAa,CAAC,CAAC;IAE1B;;;;;2BAKuB;IACvB,sBAAsB,CACpB,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,eAAe,GACvB,MAAM,CAAC;CACX"}

package/dist/transports/transport.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=transport.js.map

package/dist/transports/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../src/transports/transport.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/kernel",
-  "version": "0.42.0",
+  "version": "0.43.0",
   "description": "Telo Runtime - A lightweight, polyglot execution host.",
   "keywords": [
     "telo",
@@ -47,16 +47,18 @@
   "dependencies": {
     "@marcbachmann/cel-js": "^7.6.1",
     "@sinclair/typebox": "^0.34.48",
-    "@telorun/analyzer": "0.32.0",
+    "@telorun/analyzer": "0.33.0",
     "@telorun/glob": "0.2.0",
-    "@telorun/templating": "0.10.0",
+    "@telorun/templating": "0.10.1",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "packageurl-js": "^2.0.1",
+    "tar-stream": "^3.1.7",
     "yaml": "^2.8.3"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
+    "@types/tar-stream": "^3.1.3",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
     "@telorun/sdk": "0.41.0"
@@ -76,6 +78,7 @@
     "ajv": "$ajv",
     "ajv-formats": "$ajv-formats",
     "packageurl-js": "$packageurl-js",
+    "tar-stream": "$tar-stream",
     "yaml": "$yaml"
   },
   "scripts": {

package/src/bundle/files-integrity.ts

@@ -0,0 +1,46 @@
+import { DEFAULT_MANIFEST_FILENAME, sha256Base64Url } from "@telorun/analyzer";
+
+import { findOwnerDoc, parseManifestDocs } from "./module-manifest.js";
+
+export interface PayloadFile {
+  /** POSIX-relative path inside the bundle. */
+  name: string;
+  content: Buffer | Uint8Array;
+}
+
+/**
+ * Canonical per-file content digest of a module's `files:` payload — the value
+ * of `filesIntegrity` in a bundle's `telo.yaml`. SHA-256 over the sorted
+ * `<path>\0<sha256(content)>` lines of every payload file, `telo.yaml`
+ * excluded (the importer's `#sha256-...` hash already covers the manifest, and
+ * excluding it breaks the self-reference — the manifest embeds this value).
+ *
+ * Hashing file *contents* rather than the tar/gzip bytes makes the digest
+ * independent of archive framing, so publisher and client compute the same
+ * value from the same file set, and it can be re-derived from the extracted
+ * files on disk. Returns `sha256-<base64url>`.
+ */
+export async function computeFilesIntegrity(files: PayloadFile[]): Promise<string> {
+  const lines: string[] = [];
+  for (const file of files) {
+    if (file.name === DEFAULT_MANIFEST_FILENAME) continue;
+    const bytes = file.content instanceof Uint8Array ? file.content : new Uint8Array(file.content);
+    lines.push(`${file.name}\0${await sha256Base64Url(bytes)}`);
+  }
+  lines.sort();
+  const canonical = new TextEncoder().encode(lines.join("\n"));
+  return `sha256-${await sha256Base64Url(canonical)}`;
+}
+
+/** Write `filesIntegrity` onto the manifest's owner doc so the published
+ *  `telo.yaml` pins its payload — transitively covered by importers'
+ *  `#sha256-...` hash. The digest excludes `telo.yaml`, so injecting it does
+ *  not change the digest. Returns the manifest unchanged when it has no owner
+ *  doc. */
+export function injectFilesIntegrity(manifest: string, hash: string): string {
+  const docs = parseManifestDocs(manifest);
+  const owner = findOwnerDoc(docs);
+  if (!owner) return manifest;
+  owner.set("filesIntegrity", hash);
+  return docs.map((d) => d.toString()).join("---\n");
+}

package/src/bundle/module-manifest.ts

@@ -0,0 +1,49 @@
+import { defaultCustomTags } from "@telorun/templating";
+import { parseAllDocuments, type Document } from "yaml";
+
+const OWNER_KINDS = new Set(["Telo.Application", "Telo.Library"]);
+
+/** Parse a manifest's YAML documents, tolerating its `!cel` / `!ref` tags. */
+export function parseManifestDocs(text: string): Document[] {
+  return parseAllDocuments(text, { customTags: defaultCustomTags() });
+}
+
+/** The owner document of a manifest — the single `Telo.Application` /
+ *  `Telo.Library` doc that carries its identity, `files:`, and `filesIntegrity`.
+ *  The one place that selects it, shared by every reader/writer. */
+export function findOwnerDoc(docs: Document[]): Document | undefined {
+  return docs.find((d) => {
+    const kind = (d.toJSON() as { kind?: string } | null)?.kind;
+    return kind !== undefined && OWNER_KINDS.has(kind);
+  });
+}
+
+/** The owner-doc fields the transports read: identity for the publish location,
+ *  and payload markers for artifact fetch. */
+export interface OwnerManifest {
+  namespace?: string;
+  name?: string;
+  version?: string;
+  filesIntegrity?: string;
+  /** True when the owner doc declares a non-empty `files:` list. */
+  declaresFiles: boolean;
+}
+
+/** Read the owner doc's identity + payload fields from a manifest, parsing once
+ *  (never regex-scraping). The single source both transports call for
+ *  `<namespace>/<name>/<version>`, `filesIntegrity`, and payload detection. */
+export function readOwnerManifest(text: string): OwnerManifest {
+  const owner = findOwnerDoc(parseManifestDocs(text));
+  const parsed = owner?.toJSON() as
+    | { metadata?: Record<string, unknown>; files?: unknown; filesIntegrity?: unknown }
+    | undefined;
+  const md = parsed?.metadata ?? {};
+  const str = (v: unknown): string | undefined => (typeof v === "string" ? v : undefined);
+  return {
+    namespace: str(md.namespace),
+    name: str(md.name),
+    version: str(md.version),
+    filesIntegrity: str(parsed?.filesIntegrity),
+    declaresFiles: Array.isArray(parsed?.files) && parsed.files.length > 0,
+  };
+}

package/src/bundle/tar.ts

@@ -0,0 +1,78 @@
+import { extract as tarExtract, pack as tarPack } from "tar-stream";
+import { gunzipSync, gzipSync } from "node:zlib";
+import { Readable } from "node:stream";
+
+import type { PayloadFile } from "./files-integrity.js";
+
+export interface BundleEntry {
+  /** POSIX-relative path inside the archive (e.g. `telo.yaml`, `public/app.js`). */
+  name: string;
+  content: Buffer | string;
+}
+
+/** Normalize decoded tar entries to `PayloadFile`s (Buffer-backed content) —
+ *  the fixed step both transports run after `readTarGz`. */
+export function toPayloadFiles(entries: BundleEntry[]): PayloadFile[] {
+  return entries.map((e) => ({
+    name: e.name,
+    content: typeof e.content === "string" ? Buffer.from(e.content) : e.content,
+  }));
+}
+
+/**
+ * Pack `entries` into a gzipped tar (`module.tar.gz`) — the module-artifact
+ * writer shared by `telo publish` and the transports. Artifacts are small (a
+ * manifest plus a built frontend), so buffering the whole archive before gzip
+ * is fine. (Distinct from `apps/k8s-runner/src/tar.ts`, which is coupled to
+ * `@telorun/runner-core`'s `RunBundle`.)
+ */
+export async function makeTarGz(entries: BundleEntry[]): Promise<Buffer> {
+  const pack = tarPack();
+  const chunks: Buffer[] = [];
+  pack.on("data", (c: Buffer) => chunks.push(c));
+
+  const done = new Promise<void>((resolve, reject) => {
+    pack.on("end", resolve);
+    pack.on("error", reject);
+  });
+
+  for (const entry of entries) {
+    const buf = typeof entry.content === "string" ? Buffer.from(entry.content, "utf-8") : entry.content;
+    await new Promise<void>((resolve, reject) => {
+      pack.entry({ name: entry.name }, buf, (err) => (err ? reject(err) : resolve()));
+    });
+  }
+  pack.finalize();
+  await done;
+
+  return gzipSync(Buffer.concat(chunks));
+}
+
+/** Decompress + untar a `module.tar.gz` buffer into its file entries. */
+export async function readTarGz(buf: Buffer): Promise<BundleEntry[]> {
+  const tar = gunzipSync(buf);
+  const ex = tarExtract();
+  const entries: BundleEntry[] = [];
+
+  await new Promise<void>((resolve, reject) => {
+    ex.on("entry", (header, stream, next) => {
+      if (header.type !== "file") {
+        stream.on("end", next);
+        stream.resume();
+        return;
+      }
+      const chunks: Buffer[] = [];
+      stream.on("data", (c: Buffer) => chunks.push(c));
+      stream.on("end", () => {
+        entries.push({ name: header.name, content: Buffer.concat(chunks) });
+        next();
+      });
+      stream.on("error", reject);
+    });
+    ex.on("finish", resolve);
+    ex.on("error", reject);
+    Readable.from(tar).pipe(ex);
+  });
+
+  return entries;
+}

package/src/index.ts

@@ -10,6 +10,28 @@ export {
   writeManifestCache,
 } from "./manifest-sources/local-manifest-cache-source.js";
 export { MemorySource } from "./manifest-sources/memory-source.js";
+export type { Transport } from "./transports/transport.js";
+export { RegistryTransport } from "./transports/registry-transport.js";
+export { OciTransport } from "./transports/oci/oci-transport.js";
+export { OciClient } from "./transports/oci/oci-client.js";
+export { isOciRef, parseOciRef, type ParsedOciRef } from "./transports/oci/oci-ref.js";
+export {
+  TransportRegistry,
+  defaultTransports,
+  defaultTransportRegistry,
+} from "./transports/transport-registry.js";
+export { makeTarGz, readTarGz, type BundleEntry } from "./bundle/tar.js";
+export {
+  computeFilesIntegrity,
+  injectFilesIntegrity,
+  type PayloadFile,
+} from "./bundle/files-integrity.js";
+export type {
+  FetchedArtifact,
+  PublishBundle,
+  PublishResult,
+  PublishOptions,
+} from "./transports/transport.js";
 export { ExecutionContext } from "./execution-context.js";
 export { Kernel, type KernelOptions } from "./kernel.js";
 export { nodeCelHandlers } from "./cel-handlers.js";

package/src/kernel.ts

@@ -1,7 +1,6 @@
 import {
   AnalysisRegistry,
   buildEvalPaths,
-  defaultSources,
   flattenForAnalyzer,
   flattenLoadedModule,
   isModuleKind,
@@ -48,6 +47,7 @@ import {
 import {
   resolveCacheRoot,
 } from "./manifest-sources/local-manifest-cache-source.js";
+import { defaultTransportRegistry } from "./transports/transport-registry.js";
 import {
   collectDeclaredEnvKeys,
   precompileApplicationEnvSchemas,
@@ -156,7 +156,12 @@ export class Kernel implements IKernel {
     this.env = options.env ?? hostEnv();
     this.argv = options.argv ?? [];
     this.registryUrl = options.registryUrl;
-    this.loader = new Loader(defaultSources(this.registryUrl), { celHandlers: nodeCelHandlers });
+    // Resolution sources come from the transport registry, so a scheme-owning
+    // transport (OCI, later S3) joins the loader's dispatch chain by being
+    // registered — no source-chain edits here.
+    this.loader = new Loader(defaultTransportRegistry(this.registryUrl).sources(), {
+      celHandlers: nodeCelHandlers,
+    });
     for (const source of options.sources) {
       this.loader.register(source);
     }

package/src/manifest-sources/local-manifest-cache-source.ts

@@ -1,17 +1,14 @@
 import { splitIntegrity, verifyIntegrity, type LoadedGraph, type ManifestSource } from "@telorun/analyzer";
-import { createHash } from "crypto";
 import { statSync } from "fs";
 import * as fs from "fs/promises";
 import * as path from "path";
 import { fileURLToPath, pathToFileURL } from "url";
 
 import { hostEnv } from "../host-env.js";
+import { TransportRegistry, defaultTransportRegistry } from "../transports/transport-registry.js";
 
 const CACHE_SUBDIR = ".telo/manifests";
-const HTTP_NAMESPACE = "__http";
-const DEFAULT_MANIFEST_FILENAME = "telo.yaml";
 const DEFAULT_REGISTRY_URL = "https://registry.telo.run";
-const QUERY_HASH_LENGTH = 12;
 
 /** Verify that `candidate` resolves to a path under `root`. Returns the
  *  candidate path on success, `null` when any segment escapes the root.
@@ -27,104 +24,22 @@ function joinUnder(root: string, ...segments: string[]): string | null {
   return candidate;
 }
 
-/** Mirror `HttpSource.read`'s `fetchUrl` derivation: when the URL does not
- *  already point at a YAML file, append `/telo.yaml`. Used by both the
- *  reader and writer so a raw import URL and the canonical source it
- *  resolves to map to the same cache path. */
-function normalizePathname(url: string, parsed: URL): string {
-  let pathname = parsed.pathname;
-  if (!url.includes(".yaml")) {
-    pathname = pathname.endsWith("/")
-      ? `${pathname}${DEFAULT_MANIFEST_FILENAME}`
-      : `${pathname}/${DEFAULT_MANIFEST_FILENAME}`;
-  }
-  return pathname;
-}
-
-/** Compute a short hash of `search + hash` so two URLs that differ only in
- *  query / fragment do not collide at the same cache path. Inserted before
- *  the final extension so the filename stays readable. */
-function disambiguatePath(pathname: string, search: string, hash: string): string {
-  if (!search && !hash) return pathname;
-  const digest = createHash("sha256")
-    .update(search + hash)
-    .digest("hex")
-    .slice(0, QUERY_HASH_LENGTH);
-  const ext = path.extname(pathname);
-  const base = pathname.slice(0, pathname.length - ext.length);
-  return `${base}.${digest}${ext}`;
-}
-
 /** Single source of truth for URL → cache path. Used identically by the
  *  reader (cache lookup) and writer (install-time persistence). For any
- *  given import URL — registry ref, direct registry URL, or arbitrary
- *  HTTP — both sides land on the same file.
+ *  given import ref — registry ref, direct registry URL, arbitrary HTTP, or
+ *  (once registered) `oci://` — both sides land on the same file, because the
+ *  owning transport decides the layout via {@link Transport.cacheLocation}.
  *
- *  Returns `null` for unsupported URLs (file://, memory://, relative paths)
- *  or for path-traversal attempts that would escape `cacheRoot`. */
+ *  Returns `null` for unsupported refs (file://, memory://, relative paths) or
+ *  for path-traversal attempts that would escape `cacheRoot`. */
 function cachePathForUrl(
   rawUrl: string,
   cacheRoot: string,
-  registryUrl: string,
+  transports: TransportRegistry,
 ): string | null {
-  // Strip any inline integrity fragment so the cache path is derived from the
-  // bare ref/URL — the hash never participates in on-disk keying.
-  const url = splitIntegrity(rawUrl).base;
-  const trimmedRegistry = registryUrl.replace(/\/+$/, "");
-
-  // 1. Registry ref form: namespace/name@version
-  if (
-    !url.startsWith("http://") &&
-    !url.startsWith("https://") &&
-    !url.startsWith("/") &&
-    !url.startsWith(".") &&
-    !url.startsWith("file://") &&
-    !url.startsWith("memory://") &&
-    url.includes("@") &&
-    url.includes("/")
-  ) {
-    const atIdx = url.lastIndexOf("@");
-    if (atIdx <= 0 || atIdx === url.length - 1) return null;
-    const modulePath = url.slice(0, atIdx);
-    if (!modulePath.includes("/")) return null;
-    const version = url.slice(atIdx + 1).replace(/^v/, "");
-    if (!version) return null;
-    return joinUnder(cacheRoot, modulePath, version, DEFAULT_MANIFEST_FILENAME);
-  }
-
-  // 2. HTTP(S) URL — could be a direct registry URL or arbitrary external.
-  if (url.startsWith("http://") || url.startsWith("https://")) {
-    let parsed: URL;
-    try {
-      parsed = new URL(url);
-    } catch {
-      return null;
-    }
-    const pathname = normalizePathname(url, parsed);
-
-    // 2a. URL is on the configured registry, with no query/fragment:
-    //     fold into the registry layout so the writer that received a
-    //     registry-ref canonical and the reader that sees a direct URL
-    //     both resolve to the same file.
-    const normalizedUrl = `${parsed.protocol}//${parsed.host}${pathname}`;
-    if (
-      !parsed.search &&
-      !parsed.hash &&
-      (normalizedUrl === trimmedRegistry || normalizedUrl.startsWith(`${trimmedRegistry}/`))
-    ) {
-      const rel = normalizedUrl.slice(trimmedRegistry.length + 1);
-      if (!rel) return null;
-      return joinUnder(cacheRoot, ...rel.split("/"));
-    }
-
-    // 2b. Arbitrary HTTP(S) URL → __http subtree, with a short query-hash
-    //     suffix when query / fragment are present to prevent collisions.
-    const cleanPath = pathname.startsWith("/") ? pathname.slice(1) : pathname;
-    const disambiguated = disambiguatePath(cleanPath, parsed.search, parsed.hash);
-    return joinUnder(cacheRoot, HTTP_NAMESPACE, parsed.host, ...disambiguated.split("/"));
-  }
-
-  return null;
+  const segments = transports.cacheLocation(rawUrl);
+  if (!segments) return null;
+  return joinUnder(cacheRoot, ...segments);
 }
 
 /**
@@ -136,7 +51,7 @@ function cachePathForUrl(
  */
 export class LocalManifestCacheSource implements ManifestSource {
   private readonly cacheRoot: string;
-  private readonly registryUrl: string;
+  private readonly transports: TransportRegistry;
 
   constructor(
     entryDir: string,
@@ -147,7 +62,7 @@ export class LocalManifestCacheSource implements ManifestSource {
     // single `resolveCacheRoot` (honours `TELO_CACHE_DIR`); when absent we fall
     // back to the entry-anchored default so library/test callers are unchanged.
     this.cacheRoot = manifestsDir ?? path.join(entryDir, CACHE_SUBDIR);
-    this.registryUrl = registryUrl;
+    this.transports = defaultTransportRegistry(registryUrl);
   }
 
   supports(url: string): boolean {
@@ -184,7 +99,7 @@ export class LocalManifestCacheSource implements ManifestSource {
   }
 
   private tryMap(url: string): string | null {
-    const candidate = cachePathForUrl(url, this.cacheRoot, this.registryUrl);
+    const candidate = cachePathForUrl(url, this.cacheRoot, this.transports);
     if (!candidate) return null;
     // Require a regular file. A directory, dangling symlink, or stat failure
     // (ENOENT, EACCES, EISDIR-on-component) all fall through as a cache miss
@@ -213,7 +128,7 @@ export function cachePathForCanonical(
   manifestsDir?: string,
 ): string | null {
   const cacheRoot = manifestsDir ?? path.join(entryDir, CACHE_SUBDIR);
-  return cachePathForUrl(canonicalSource, cacheRoot, registryUrl);
+  return cachePathForUrl(canonicalSource, cacheRoot, defaultTransportRegistry(registryUrl));
 }
 
 /**

package/src/transports/oci/docker-credentials.ts

@@ -0,0 +1,85 @@
+import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import * as path from "node:path";
+
+import { hostEnv } from "../../host-env.js";
+
+export interface DockerCredential {
+  username: string;
+  password: string;
+}
+
+interface DockerConfig {
+  auths?: Record<string, { auth?: string; username?: string; password?: string }>;
+  credHelpers?: Record<string, string>;
+  credsStore?: string;
+}
+
+/** Path to `config.json`, honouring `DOCKER_CONFIG`. */
+function dockerConfigPath(): string {
+  const override = hostEnv().DOCKER_CONFIG;
+  const dir = override && override.trim() ? override.trim() : path.join(homedir(), ".docker");
+  return path.join(dir, "config.json");
+}
+
+async function readDockerConfig(): Promise<DockerConfig | null> {
+  try {
+    return JSON.parse(await readFile(dockerConfigPath(), "utf-8")) as DockerConfig;
+  } catch {
+    return null; // no config, unreadable, or malformed → anonymous
+  }
+}
+
+/** Run `docker-credential-<helper> get` with `host` on stdin, per the Docker
+ *  credential-helper protocol, returning `{Username, Secret}` or null. */
+function runCredentialHelper(helper: string, host: string): Promise<DockerCredential | null> {
+  return new Promise((resolve) => {
+    const proc = spawn(`docker-credential-${helper}`, ["get"], {
+      stdio: ["pipe", "pipe", "ignore"],
+    });
+    let out = "";
+    proc.stdout.on("data", (c) => (out += c));
+    proc.on("error", () => resolve(null)); // helper binary not installed
+    proc.on("close", (code) => {
+      if (code !== 0) return resolve(null);
+      try {
+        const parsed = JSON.parse(out) as { Username?: string; Secret?: string };
+        if (parsed.Username && parsed.Secret) {
+          resolve({ username: parsed.Username, password: parsed.Secret });
+        } else {
+          resolve(null);
+        }
+      } catch {
+        resolve(null);
+      }
+    });
+    proc.stdin.end(host);
+  });
+}
+
+/** Resolve credentials for `host` from the ambient Docker credential chain:
+ *  a per-registry credential helper, the global credential store, then the
+ *  inline `auths` entry (base64 `user:password` or explicit fields). Returns
+ *  null for anonymous access — the caller falls back to an anonymous token. */
+export async function resolveDockerCredential(host: string): Promise<DockerCredential | null> {
+  const config = await readDockerConfig();
+  if (!config) return null;
+
+  const helper = config.credHelpers?.[host];
+  if (helper) return runCredentialHelper(helper, host);
+  if (config.credsStore) return runCredentialHelper(config.credsStore, host);
+
+  const entry = config.auths?.[host];
+  if (entry?.auth) {
+    const decoded = Buffer.from(entry.auth, "base64").toString("utf-8");
+    const colon = decoded.indexOf(":");
+    if (colon > 0) {
+      return { username: decoded.slice(0, colon), password: decoded.slice(colon + 1) };
+    }
+  }
+  if (entry?.username && entry?.password) {
+    return { username: entry.username, password: entry.password };
+  }
+  return null;
+}