code-provenance 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { ImageRef, ImageResult } from "./types.js";
+export { parseCompose, parseImageRef } from "./composeParser.js";
+export { resolveImage } from "./resolver.js";
+export { formatJson, formatTable } from "./output.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { parseCompose, parseImageRef } from "./composeParser.js";
+export { resolveImage } from "./resolver.js";
+export { formatJson, formatTable } from "./output.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/output.d.ts

@@ -0,0 +1,9 @@
+import type { ImageResult } from "./types.js";
+/**
+ * Format results as a JSON array.
+ */
+export declare function formatJson(results: ImageResult[]): string;
+/**
+ * Format results as a box-drawing table.
+ */
+export declare function formatTable(results: ImageResult[]): string;

package/dist/output.js

@@ -0,0 +1,39 @@
+/**
+ * Format results as a JSON array.
+ */
+export function formatJson(results) {
+    return JSON.stringify(results, null, 2);
+}
+/**
+ * Format results as a box-drawing table.
+ */
+export function formatTable(results) {
+    const columns = ["SERVICE", "IMAGE", "REPO", "COMMIT", "STATUS", "CONFIDENCE"];
+    // Build rows
+    const rows = results.map((r) => [
+        r.service,
+        r.image,
+        r.repo ? r.repo.replace("https://", "") : "-",
+        r.commit ? r.commit.slice(0, 12) : "-",
+        r.status,
+        r.confidence || "-",
+    ]);
+    // Calculate column widths
+    const widths = columns.map((col, i) => {
+        const dataMax = rows.reduce((max, row) => Math.max(max, row[i].length), 0);
+        return Math.max(col.length, dataMax);
+    });
+    const pad = (s, w) => s + " ".repeat(w - s.length);
+    // Build lines
+    const topBorder = "┌" + widths.map((w) => "─".repeat(w + 2)).join("┬") + "┐";
+    const headerSep = "├" + widths.map((w) => "─".repeat(w + 2)).join("┼") + "┤";
+    const bottomBorder = "└" + widths.map((w) => "─".repeat(w + 2)).join("┴") + "┘";
+    const headerRow = "│" +
+        columns.map((col, i) => " " + pad(col, widths[i]) + " ").join("│") +
+        "│";
+    const dataRows = rows.map((row) => "│" +
+        row.map((cell, i) => " " + pad(cell, widths[i]) + " ").join("│") +
+        "│");
+    return [topBorder, headerRow, headerSep, ...dataRows, bottomBorder].join("\n");
+}
+//# sourceMappingURL=output.js.map

package/dist/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"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"}

package/dist/registry.d.ts

@@ -0,0 +1,9 @@
+import type { ImageRef } from "./types.js";
+/**
+ * Get an anonymous pull token from an OCI registry.
+ */
+export declare function getRegistryToken(registry: string, repoPath: string): Promise<string | null>;
+/**
+ * Fetch OCI labels from an image's config blob without pulling the image.
+ */
+export declare function fetchOciLabels(ref: ImageRef): Promise<Record<string, string>>;

package/dist/registry.js

@@ -0,0 +1,123 @@
+/**
+ * Get an anonymous pull token from an OCI registry.
+ */
+export async function getRegistryToken(registry, repoPath) {
+    let url;
+    if (registry === "ghcr.io") {
+        url = `https://ghcr.io/token?scope=repository:${encodeURIComponent(repoPath)}:pull`;
+    }
+    else if (registry === "docker.io") {
+        url =
+            `https://auth.docker.io/token?service=registry.docker.io` +
+                `&scope=repository:${encodeURIComponent(repoPath)}:pull`;
+    }
+    else {
+        return null;
+    }
+    try {
+        const resp = await fetch(url, { signal: AbortSignal.timeout(10000) });
+        if (!resp.ok)
+            return null;
+        const data = (await resp.json());
+        return data.token ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function registryBaseUrl(registry) {
+    if (registry === "docker.io")
+        return "https://registry-1.docker.io";
+    return `https://${registry}`;
+}
+const MANIFEST_ACCEPT = [
+    "application/vnd.docker.distribution.manifest.v2+json",
+    "application/vnd.oci.image.manifest.v1+json",
+    "application/vnd.docker.distribution.manifest.list.v2+json",
+    "application/vnd.oci.image.index.v1+json",
+].join(", ");
+const INDEX_MEDIA_TYPES = new Set([
+    "application/vnd.docker.distribution.manifest.list.v2+json",
+    "application/vnd.oci.image.index.v1+json",
+]);
+/**
+ * Resolve a manifest reference to a config blob digest, handling multi-arch indexes.
+ */
+async function resolveManifestToConfigDigest(baseUrl, repoPath, reference, token) {
+    try {
+        const resp = await fetch(`${baseUrl}/v2/${repoPath}/manifests/${reference}`, {
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: MANIFEST_ACCEPT,
+            },
+            signal: AbortSignal.timeout(10000),
+        });
+        if (!resp.ok)
+            return null;
+        const data = await resp.json();
+        const mediaType = data.mediaType ?? "";
+        // If it's an index/manifest list, pick amd64/linux
+        if (INDEX_MEDIA_TYPES.has(mediaType)) {
+            const manifests = data.manifests ?? [];
+            let platformDigest = null;
+            // Try amd64/linux first
+            for (const m of manifests) {
+                const platform = m.platform ?? {};
+                if (platform.os === "unknown")
+                    continue;
+                if (platform.architecture === "amd64" && platform.os === "linux") {
+                    platformDigest = m.digest;
+                    break;
+                }
+            }
+            // Fall back to first non-attestation manifest
+            if (!platformDigest) {
+                for (const m of manifests) {
+                    if (m.platform?.os !== "unknown") {
+                        platformDigest = m.digest;
+                        break;
+                    }
+                }
+            }
+            if (!platformDigest)
+                return null;
+            return resolveManifestToConfigDigest(baseUrl, repoPath, platformDigest, token);
+        }
+        // Single manifest - extract config digest
+        return data.config?.digest ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Fetch OCI labels from an image's config blob without pulling the image.
+ */
+export async function fetchOciLabels(ref) {
+    const repoPath = `${ref.namespace}/${ref.name}`;
+    const token = await getRegistryToken(ref.registry, repoPath);
+    if (!token)
+        return {};
+    const baseUrl = registryBaseUrl(ref.registry);
+    const configDigest = await resolveManifestToConfigDigest(baseUrl, repoPath, ref.tag, token);
+    if (!configDigest)
+        return {};
+    try {
+        const resp = await fetch(`${baseUrl}/v2/${repoPath}/blobs/${configDigest}`, {
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: "application/vnd.docker.container.image.v1+json",
+            },
+            redirect: "follow",
+            signal: AbortSignal.timeout(10000),
+        });
+        if (!resp.ok)
+            return {};
+        const data = await resp.json();
+        return data.config?.Labels ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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"}

package/dist/resolver.d.ts

@@ -0,0 +1,5 @@
+import type { ImageRef, ImageResult } from "./types.js";
+/**
+ * Run the resolution chain for a single image.
+ */
+export declare function resolveImage(service: string, ref: ImageRef): Promise<ImageResult>;

package/dist/resolver.js

@@ -0,0 +1,165 @@
+import { fetchOciLabels } from "./registry.js";
+import { resolveTagToCommit, inferRepoFromDockerhub, resolveGhcrDigestViaPackages, resolveGhcrLatestViaPackages, getLatestReleaseCommit, getLatestCommit, } from "./github.js";
+const COMMIT_SHA_RE = /^[0-9a-f]{40,}$/;
+const DIGEST_RE = /^sha256:[0-9a-f]{64}$/;
+function isResolvableTag(tag) {
+    return !!tag && tag !== "latest" && !DIGEST_RE.test(tag);
+}
+async function inferRepo(ref) {
+    if (ref.registry === "ghcr.io") {
+        return [ref.namespace, ref.name];
+    }
+    if (ref.registry === "docker.io") {
+        const hubResult = await inferRepoFromDockerhub(ref.namespace, ref.name);
+        if (hubResult)
+            return hubResult;
+    }
+    return [null, null];
+}
+/**
+ * Run the resolution chain for a single image.
+ */
+export async function resolveImage(service, ref) {
+    const result = {
+        service,
+        image: ref.raw,
+        registry: ref.registry,
+        repo: null,
+        tag: ref.tag,
+        commit: null,
+        commit_url: null,
+        status: "repo_not_found",
+        resolution_method: null,
+        confidence: null,
+        steps: [],
+    };
+    // Step 1: Check OCI labels
+    result.steps.push(`[1/5] Fetching OCI labels from ${ref.registry}/${ref.namespace}/${ref.name}:${ref.tag}`);
+    const labels = await fetchOciLabels(ref);
+    const source = labels["org.opencontainers.image.source"];
+    const revision = labels["org.opencontainers.image.revision"];
+    if (source && revision) {
+        result.steps.push(`[1/5] Found OCI labels: source=${source}, revision=${revision.slice(0, 12)}`);
+        result.repo = source;
+        result.commit = revision;
+        result.commit_url = `${source}/commit/${revision}`;
+        result.status = "resolved";
+        result.resolution_method = "oci_labels";
+        result.confidence = ref.tag === "latest" ? "approximate" : "exact";
+        return result;
+    }
+    else {
+        result.steps.push("[1/5] No OCI labels found");
+    }
+    // Step 2: Infer repo
+    result.steps.push(`[2/5] Inferring GitHub repo from ${ref.registry}/${ref.namespace}/${ref.name}`);
+    const [owner, repoName] = await inferRepo(ref);
+    if (owner && repoName) {
+        result.steps.push(`[2/5] Repo inferred: ${owner}/${repoName}`);
+        result.repo = `https://github.com/${owner}/${repoName}`;
+    }
+    else {
+        result.steps.push("[2/5] Could not infer GitHub repo");
+        result.status = "repo_not_found";
+        return result;
+    }
+    // Check if tag is a commit SHA
+    if (COMMIT_SHA_RE.test(ref.tag)) {
+        result.steps.push("[2/5] Tag is a commit SHA, using directly");
+        result.commit = ref.tag;
+        result.commit_url = `${result.repo}/commit/${ref.tag}`;
+        result.status = "resolved";
+        result.resolution_method = "commit_sha_tag";
+        result.confidence = "exact";
+        return result;
+    }
+    // Step 3: Tag-to-commit resolution
+    if (isResolvableTag(ref.tag)) {
+        result.steps.push(`[3/5] Matching tag "${ref.tag}" against git tags in ${owner}/${repoName}`);
+        const tagResult = await resolveTagToCommit(owner, repoName, ref.tag);
+        if (tagResult) {
+            const [commitSha, isExact] = tagResult;
+            if (isExact) {
+                result.steps.push(`[3/5] Exact tag match: ${commitSha.slice(0, 12)}`);
+            }
+            else {
+                result.steps.push(`[3/5] Prefix match (e.g. v2.10 -> v2.10.x): ${commitSha.slice(0, 12)}`);
+            }
+            result.commit = commitSha;
+            result.commit_url = `${result.repo}/commit/${commitSha}`;
+            result.status = "resolved";
+            result.resolution_method = "tag_match";
+            result.confidence = isExact ? "exact" : "approximate";
+            return result;
+        }
+        result.steps.push("[3/5] No matching git tag found");
+        result.status = "repo_found_tag_not_matched";
+        return result;
+    }
+    // Step 4: For GHCR images, try the packages API for digest or :latest
+    if (ref.registry === "ghcr.io") {
+        let pkgResult = null;
+        let pkgConfidence = null;
+        if (DIGEST_RE.test(ref.tag)) {
+            result.steps.push(`[4/5] Trying GHCR packages API for digest ${ref.tag.slice(0, 20)}...`);
+            pkgResult = await resolveGhcrDigestViaPackages(ref.namespace, ref.name, ref.tag);
+            pkgConfidence = "exact";
+        }
+        else if (ref.tag === "latest" || !ref.tag) {
+            result.steps.push("[4/5] Trying GHCR packages API for :latest tag");
+            pkgResult = await resolveGhcrLatestViaPackages(ref.namespace, ref.name);
+            pkgConfidence = "approximate";
+        }
+        if (pkgResult) {
+            const repoFull = pkgResult.repo;
+            result.repo = `https://github.com/${repoFull}`;
+            if (pkgResult.commit) {
+                const commit = pkgResult.commit;
+                result.steps.push(`[4/5] Packages API: repo=${repoFull}, commit=${commit.slice(0, 12)}`);
+                result.commit = commit;
+                result.commit_url = `${result.repo}/commit/${result.commit}`;
+                result.status = "resolved";
+                result.resolution_method = "packages_api";
+                result.confidence = pkgConfidence;
+                return result;
+            }
+            result.steps.push("[4/5] Packages API: found package but no resolvable tags");
+            const tags = pkgResult.tags ?? [];
+            const resolvable = tags.filter((t) => t !== "latest");
+            result.status = resolvable.length > 0 ? "repo_found_tag_not_matched" : "no_tag";
+            return result;
+        }
+    }
+    // Step 5: For :latest on any registry, try the latest GitHub release,
+    // then fall back to the latest commit on the default branch
+    if ((ref.tag === "latest" || !ref.tag) && owner && repoName) {
+        result.steps.push(`[5/5] Trying latest GitHub release for ${owner}/${repoName}`);
+        const releaseResult = await getLatestReleaseCommit(owner, repoName);
+        if (releaseResult) {
+            const [commitSha, tagName] = releaseResult;
+            result.steps.push(`[5/5] Latest release: tag=${tagName}, commit=${commitSha.slice(0, 12)}`);
+            result.commit = commitSha;
+            result.commit_url = `${result.repo}/commit/${commitSha}`;
+            result.status = "resolved";
+            result.resolution_method = "latest_release";
+            result.confidence = "approximate";
+            return result;
+        }
+        // No releases - fall back to latest commit on default branch
+        result.steps.push("[5/5] No release found, trying latest commit on default branch");
+        const latestSha = await getLatestCommit(owner, repoName);
+        if (latestSha) {
+            result.steps.push(`[5/5] Latest commit: ${latestSha.slice(0, 12)}`);
+            result.commit = latestSha;
+            result.commit_url = `${result.repo}/commit/${latestSha}`;
+            result.status = "resolved";
+            result.resolution_method = "latest_commit";
+            result.confidence = "approximate";
+            return result;
+        }
+    }
+    result.steps.push("[5/5] Could not resolve to a commit");
+    result.status = "no_tag";
+    return result;
+}
+//# sourceMappingURL=resolver.js.map

package/dist/resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../src/resolver.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,4BAA4B,EAC5B,4BAA4B,EAC5B,sBAAsB,EACtB,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,MAAM,aAAa,GAAG,iBAAiB,CAAC;AACxC,MAAM,SAAS,GAAG,uBAAuB,CAAC;AAE1C,SAAS,eAAe,CAAC,GAAW;IAClC,OAAO,CAAC,CAAC,GAAG,IAAI,GAAG,KAAK,QAAQ,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC3D,CAAC;AAED,KAAK,UAAU,SAAS,CACtB,GAAa;IAEb,IAAI,GAAG,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;IAED,IAAI,GAAG,CAAC,QAAQ,KAAK,WAAW,EAAE,CAAC;QACjC,MAAM,SAAS,GAAG,MAAM,sBAAsB,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;QACxE,IAAI,SAAS;YAAE,OAAO,SAAS,CAAC;IAClC,CAAC;IAED,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AACtB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAe,EACf,GAAa;IAEb,MAAM,MAAM,GAAgB;QAC1B,OAAO;QACP,KAAK,EAAE,GAAG,CAAC,GAAG;QACd,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,IAAI,EAAE,IAAI;QACV,GAAG,EAAE,GAAG,CAAC,GAAG;QACZ,MAAM,EAAE,IAAI;QACZ,UAAU,EAAE,IAAI;QAChB,MAAM,EAAE,gBAAgB;QACxB,iBAAiB,EAAE,IAAI;QACvB,UAAU,EAAE,IAAI;QAChB,KAAK,EAAE,EAAE;KACV,CAAC;IAEF,2BAA2B;IAC3B,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,kCAAkC,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,SAAS,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC;IAC5G,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,GAAG,CAAC,CAAC;IACzC,MAAM,MAAM,GAAG,MAAM,CAAC,iCAAiC,CAAC,CAAC;IACzD,MAAM,QAAQ,GAAG,MAAM,CAAC,mCAAmC,CAAC,CAAC;IAC7D,IAAI,MAAM,IAAI,QAAQ,EAAE,CAAC;QACvB,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,kCAAkC,MAAM,cAAc,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;QACjG,MAAM,CAAC,IAAI,GAAG,MAAM,CAAC;QACrB,MAAM,CAAC,MAAM,GAAG,QAAQ,CAAC;QACzB,MAAM,CAAC,UAAU,GAAG,GAAG,MAAM,WAAW,QAAQ,EAAE,CAAC;QACnD,MAAM,CAAC,MAAM,GAAG,UAAU,CAAC;QAC3B,MAAM,CAAC,iBAAiB,GAAG,YAAY,CAAC;QACxC,MAAM,CAAC,UAAU,GAAG,GAAG,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC;QACnE,OAAO,MAAM,CAAC;IAChB,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;IACjD,CAAC;IAED,qBAAqB;IACrB,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,oCAAoC,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,SAAS,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;IACnG,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC,CAAC;IAC/C,IAAI,KAAK,IAAI,QAAQ,EAAE,CAAC;QACtB,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,wBAAwB,KAAK,IAAI,QAAQ,EAAE,CAAC,CAAC;QAC/D,MAAM,CAAC,IAAI,GAAG,sBAAsB,KAAK,IAAI,QAAQ,EAAE,CAAC;IAC1D,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC;QACvD,MAAM,CAAC,MAAM,GAAG,gBAAgB,CAAC;QACjC,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,+BAA+B;IAC/B,IAAI,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;QAChC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,2CAA2C,CAAC,CAAC;QAC/D,MAAM,CAAC,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC;QACxB,MAAM,CAAC,UAAU,GAAG,GAAG,MAAM,CAAC,IAAI,WAAW,GAAG,CAAC,GAAG,EAAE,CAAC;QACvD,MAAM,CAAC,MAAM,GAAG,UAAU,CAAC;QAC3B,MAAM,CAAC,iBAAiB,GAAG,gBAAgB,CAAC;QAC5C,MAAM,CAAC,UAAU,GAAG,OAAO,CAAC;QAC5B,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,mCAAmC;IACnC,IAAI,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;QAC7B,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,uBAAuB,GAAG,CAAC,GAAG,yBAAyB,KAAK,IAAI,QAAQ,EAAE,CAAC,CAAC;QAC9F,MAAM,SAAS,GAAG,MAAM,kBAAkB,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;QACrE,IAAI,SAAS,EAAE,CAAC;YACd,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;YACvC,IAAI,OAAO,EAAE,CAAC;gBACZ,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,0BAA0B,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;YACxE,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,+CAA+C,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;YAC7F,CAAC;YACD,MAAM,CAAC,MAAM,GAAG,SAAS,CAAC;YAC1B,MAAM,CAAC,UAAU,GAAG,GAAG,MAAM,CAAC,IAAI,WAAW,SAAS,EAAE,CAAC;YACzD,MAAM,CAAC,MAAM,GAAG,UAAU,CAAC;YAC3B,MAAM,CAAC,iBAAiB,GAAG,WAAW,CAAC;YACvC,MAAM,CAAC,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,aAAa,CAAC;YACtD,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,iCAAiC,CAAC,CAAC;QACrD,MAAM,CAAC,MAAM,GAAG,4BAA4B,CAAC;QAC7C,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,sEAAsE;IACtE,IAAI,GAAG,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC/B,IAAI,SAAS,GAAmE,IAAI,CAAC;QACrF,IAAI,aAAa,GAAkB,IAAI,CAAC;QAExC,IAAI,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5B,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,6CAA6C,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC;YAC1F,SAAS,GAAG,MAAM,4BAA4B,CAC5C,GAAG,CAAC,SAAS,EACb,GAAG,CAAC,IAAI,EACR,GAAG,CAAC,GAAG,CACR,CAAC;YACF,aAAa,GAAG,OAAO,CAAC;QAC1B,CAAC;aAAM,IAAI,GAAG,CAAC,GAAG,KAAK,QAAQ,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;YAC5C,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,gDAAgD,CAAC,CAAC;YACpE,SAAS,GAAG,MAAM,4BAA4B,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;YACxE,aAAa,GAAG,aAAa,CAAC;QAChC,CAAC;QAED,IAAI,SAAS,EAAE,CAAC;YACd,MAAM,QAAQ,GAAG,SAAS,CAAC,IAAI,CAAC;YAChC,MAAM,CAAC,IAAI,GAAG,sBAAsB,QAAQ,EAAE,CAAC;YAC/C,IAAI,SAAS,CAAC,MAAM,EAAE,CAAC;gBACrB,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC;gBAChC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,4BAA4B,QAAQ,YAAY,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;gBACzF,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC;gBACvB,MAAM,CAAC,UAAU,GAAG,GAAG,MAAM,CAAC,IAAI,WAAW,MAAM,CAAC,MAAM,EAAE,CAAC;gBAC7D,MAAM,CAAC,MAAM,GAAG,UAAU,CAAC;gBAC3B,MAAM,CAAC,iBAAiB,GAAG,cAAc,CAAC;gBAC1C,MAAM,CAAC,UAAU,GAAG,aAAa,CAAC;gBAClC,OAAO,MAAM,CAAC;YAChB,CAAC;YACD,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,0DAA0D,CAAC,CAAC;YAC9E,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,IAAI,EAAE,CAAC;YAClC,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC;YACtD,MAAM,CAAC,MAAM,GAAG,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,4BAA4B,CAAC,CAAC,CAAC,QAAQ,CAAC;YAChF,OAAO,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;IAED,sEAAsE;IACtE,4DAA4D;IAC5D,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,QAAQ,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,KAAK,IAAI,QAAQ,EAAE,CAAC;QAC5D,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,0CAA0C,KAAK,IAAI,QAAQ,EAAE,CAAC,CAAC;QACjF,MAAM,aAAa,GAAG,MAAM,sBAAsB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QACpE,IAAI,aAAa,EAAE,CAAC;YAClB,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,GAAG,aAAa,CAAC;YAC3C,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,6BAA6B,OAAO,YAAY,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;YAC5F,MAAM,CAAC,MAAM,GAAG,SAAS,CAAC;YAC1B,MAAM,CAAC,UAAU,GAAG,GAAG,MAAM,CAAC,IAAI,WAAW,SAAS,EAAE,CAAC;YACzD,MAAM,CAAC,MAAM,GAAG,UAAU,CAAC;YAC3B,MAAM,CAAC,iBAAiB,GAAG,gBAAgB,CAAC;YAC5C,MAAM,CAAC,UAAU,GAAG,aAAa,CAAC;YAClC,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,6DAA6D;QAC7D,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,gEAAgE,CAAC,CAAC;QACpF,MAAM,SAAS,GAAG,MAAM,eAAe,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QACzD,IAAI,SAAS,EAAE,CAAC;YACd,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,wBAAwB,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;YACpE,MAAM,CAAC,MAAM,GAAG,SAAS,CAAC;YAC1B,MAAM,CAAC,UAAU,GAAG,GAAG,MAAM,CAAC,IAAI,WAAW,SAAS,EAAE,CAAC;YACzD,MAAM,CAAC,MAAM,GAAG,UAAU,CAAC;YAC3B,MAAM,CAAC,iBAAiB,GAAG,eAAe,CAAC;YAC3C,MAAM,CAAC,UAAU,GAAG,aAAa,CAAC;YAClC,OAAO,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;IAED,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,qCAAqC,CAAC,CAAC;IACzD,MAAM,CAAC,MAAM,GAAG,QAAQ,CAAC;IACzB,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,20 @@
+export interface ImageRef {
+    registry: string;
+    namespace: string;
+    name: string;
+    tag: string;
+    raw: string;
+}
+export interface ImageResult {
+    service: string;
+    image: string;
+    registry: string;
+    repo: string | null;
+    tag: string;
+    commit: string | null;
+    commit_url: string | null;
+    status: string;
+    resolution_method: string | null;
+    confidence: string | null;
+    steps: string[];
+}

package/dist/types.js

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

package/dist/types.js.map

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

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "code-provenance",
+  "version": "0.1.0",
+  "description": "Resolve Docker images to their source code commits on GitHub",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "code-provenance": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test dist/**/*.test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "yaml": "^2.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.0"
+  },
+  "author": "SCRT Labs",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/scrtlabs/code-provenance.git",
+    "directory": "node"
+  },
+  "homepage": "https://github.com/scrtlabs/code-provenance/tree/main/node"
+}

package/run.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# Install deps if needed
+if [ ! -d "$SCRIPT_DIR/node_modules" ]; then
+    echo "Installing dependencies..."
+    npm --prefix "$SCRIPT_DIR" install
+fi
+
+# Build if needed
+if [ ! -d "$SCRIPT_DIR/dist" ]; then
+    echo "Building..."
+    npm --prefix "$SCRIPT_DIR" run build
+fi
+
+# Auto-detect GitHub token from gh CLI if not already set
+if [ -z "${GITHUB_TOKEN:-}" ] && command -v gh &>/dev/null; then
+    GITHUB_TOKEN=$(gh auth token 2>/dev/null) || true
+    export GITHUB_TOKEN
+fi
+
+# Run the tool, passing all arguments through
+node "$SCRIPT_DIR/dist/cli.js" "$@"

package/src/cli.ts

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
+import { parseCompose, parseImageRef } from "./composeParser.js";
+import { resolveImage } from "./resolver.js";
+import { formatJson, formatTable } from "./output.js";
+
+function printHelp(): void {
+  console.log(`usage: code-provenance [-h] [--json] [compose_file]
+
+Resolve Docker images to their source code commits on GitHub.
+
+positional arguments:
+  compose_file  Path to docker-compose file (default: docker-compose.yml)
+
+options:
+  -h, --help       show this help message and exit
+  --json           Output results as JSON
+  -v, --verbose    Show resolution steps`);
+}
+
+async function main(): Promise<number> {
+  const args = process.argv.slice(2);
+
+  if (args.includes("-h") || args.includes("--help")) {
+    printHelp();
+    return 0;
+  }
+
+  const jsonOutput = args.includes("--json");
+  const verbose = args.includes("--verbose") || args.includes("-v");
+  const positionalArgs = args.filter((a) => a !== "--json" && a !== "--verbose" && a !== "-v");
+  const composeFile = positionalArgs[0] || "docker-compose.yml";
+
+  if (!existsSync(composeFile)) {
+    console.error(`Error: ${composeFile} not found`);
+    return 1;
+  }
+
+  const yamlContent = readFileSync(composeFile, "utf-8");
+  const services = parseCompose(yamlContent);
+
+  if (services.length === 0) {
+    console.error("No services with images found.");
+    return 0;
+  }
+
+  // Resolve all images in parallel
+  const results = await Promise.all(
+    services.map(([serviceName, imageString]) => {
+      const ref = parseImageRef(imageString);
+      return resolveImage(serviceName, ref);
+    })
+  );
+
+  if (verbose) {
+    for (const r of results) {
+      console.error(`\nResolving ${r.image} ...`);
+      for (const step of r.steps) {
+        console.error(`  ${step}`);
+      }
+      console.error(
+        `  → ${r.status}` +
+          (r.status === "resolved"
+            ? ` (${r.resolution_method}, ${r.confidence})`
+            : "")
+      );
+    }
+    console.error();
+  }
+
+  if (jsonOutput) {
+    console.log(formatJson(results));
+  } else {
+    console.log(formatTable(results));
+  }
+
+  return 0;
+}
+
+main()
+  .then((code) => process.exit(code))
+  .catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });

package/src/composeParser.test.ts

@@ -0,0 +1,76 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { parseImageRef, parseCompose } from "./composeParser.js";
+
+describe("parseImageRef", () => {
+  it("parses ghcr with tag", () => {
+    const ref = parseImageRef("ghcr.io/excalidraw/excalidraw:v0.17.3");
+    assert.equal(ref.registry, "ghcr.io");
+    assert.equal(ref.namespace, "excalidraw");
+    assert.equal(ref.name, "excalidraw");
+    assert.equal(ref.tag, "v0.17.3");
+  });
+
+  it("parses docker hub official image", () => {
+    const ref = parseImageRef("postgres:16");
+    assert.equal(ref.registry, "docker.io");
+    assert.equal(ref.namespace, "library");
+    assert.equal(ref.name, "postgres");
+    assert.equal(ref.tag, "16");
+  });
+
+  it("parses docker hub namespaced image", () => {
+    const ref = parseImageRef("traefik/whoami:v1.10.3");
+    assert.equal(ref.registry, "docker.io");
+    assert.equal(ref.namespace, "traefik");
+    assert.equal(ref.name, "whoami");
+    assert.equal(ref.tag, "v1.10.3");
+  });
+
+  it("defaults to latest when no tag", () => {
+    const ref = parseImageRef("nginx");
+    assert.equal(ref.registry, "docker.io");
+    assert.equal(ref.namespace, "library");
+    assert.equal(ref.name, "nginx");
+    assert.equal(ref.tag, "latest");
+  });
+
+  it("handles digest reference", () => {
+    const ref = parseImageRef(
+      "ghcr.io/org/app@sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
+    );
+    assert.equal(ref.registry, "ghcr.io");
+    assert.equal(ref.namespace, "org");
+    assert.equal(ref.name, "app");
+    assert.equal(
+      ref.tag,
+      "sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
+    );
+  });
+});
+
+describe("parseCompose", () => {
+  it("extracts services with image field", () => {
+    const yaml = `
+services:
+  web:
+    image: nginx:latest
+  api:
+    build: .
+  db:
+    image: postgres:16
+`;
+    const result = parseCompose(yaml);
+    assert.equal(result.length, 2);
+    assert.deepEqual(result[0], ["web", "nginx:latest"]);
+    assert.deepEqual(result[1], ["db", "postgres:16"]);
+  });
+
+  it("handles empty services", () => {
+    const yaml = `
+services: {}
+`;
+    const result = parseCompose(yaml);
+    assert.equal(result.length, 0);
+  });
+});