code-provenance 0.1.0

package/src/composeParser.ts

@@ -0,0 +1,79 @@
+import YAML from "yaml";
+import type { ImageRef } from "./types.js";
+
+/**
+ * Parse a Docker image string into an ImageRef.
+ */
+export function parseImageRef(imageString: string): ImageRef {
+  const raw = imageString;
+  let tag: string;
+  let namePart: string;
+
+  // Handle digest references (image@sha256:...)
+  if (imageString.includes("@")) {
+    const atIdx = imageString.indexOf("@");
+    namePart = imageString.slice(0, atIdx);
+    tag = imageString.slice(atIdx + 1);
+  } else {
+    const lastSegment = imageString.split("/").pop()!;
+    if (lastSegment.includes(":")) {
+      const colonPos = imageString.lastIndexOf(":");
+      tag = imageString.slice(colonPos + 1);
+      namePart = imageString.slice(0, colonPos);
+    } else {
+      tag = "latest";
+      namePart = imageString;
+    }
+  }
+
+  // Determine registry
+  const parts = namePart.split("/");
+  let registry: string;
+  let remaining: string[];
+
+  if (parts.length >= 2 && (parts[0].includes(".") || parts[0].includes(":"))) {
+    registry = parts[0];
+    remaining = parts.slice(1);
+  } else {
+    registry = "docker.io";
+    remaining = parts;
+  }
+
+  // Determine namespace and name
+  let namespace: string;
+  let name: string;
+
+  if (remaining.length === 1) {
+    namespace = "library";
+    name = remaining[0];
+  } else if (remaining.length === 2) {
+    namespace = remaining[0];
+    name = remaining[1];
+  } else {
+    namespace = remaining[0];
+    name = remaining.slice(1).join("/");
+  }
+
+  return { registry, namespace, name, tag, raw };
+}
+
+/**
+ * Parse docker-compose YAML and return list of [serviceName, imageString] pairs.
+ */
+export function parseCompose(yamlContent: string): [string, string][] {
+  const data = YAML.parse(yamlContent);
+  const services = data?.services ?? {};
+  const results: [string, string][] = [];
+
+  for (const [serviceName, serviceConfig] of Object.entries(services)) {
+    if (
+      serviceConfig !== null &&
+      typeof serviceConfig === "object" &&
+      "image" in (serviceConfig as Record<string, unknown>)
+    ) {
+      results.push([serviceName, (serviceConfig as Record<string, unknown>).image as string]);
+    }
+  }
+
+  return results;
+}

package/src/github.ts

@@ -0,0 +1,339 @@
+function githubHeaders(): Record<string, string> {
+  const headers: Record<string, string> = {
+    Accept: "application/vnd.github+json",
+  };
+  const token = process.env.GITHUB_TOKEN;
+  if (token) {
+    headers.Authorization = `Bearer ${token}`;
+  }
+  return headers;
+}
+
+function normalizeTag(tag: string): string {
+  return tag.replace(/^v+/, "");
+}
+
+function isPrefixMatch(imageTag: string, gitTag: string): boolean {
+  const normImage = normalizeTag(imageTag);
+  const normGit = normalizeTag(gitTag);
+  return normGit.startsWith(normImage + ".");
+}
+
+function parseVersionTuple(tag: string): number[] | null {
+  let norm = normalizeTag(tag);
+  // Strip pre-release suffixes like -rc1, -beta2
+  norm = norm.split(/[-+]/)[0];
+  const parts = norm.split(".");
+  try {
+    const nums = parts.map((p) => {
+      const n = parseInt(p, 10);
+      if (isNaN(n)) throw new Error();
+      return n;
+    });
+    return nums;
+  } catch {
+    return null;
+  }
+}
+
+function compareVersions(a: number[], b: number[]): number {
+  const len = Math.max(a.length, b.length);
+  for (let i = 0; i < len; i++) {
+    const av = a[i] ?? 0;
+    const bv = b[i] ?? 0;
+    if (av !== bv) return av - bv;
+  }
+  return 0;
+}
+
+/**
+ * Parse the Link header for pagination.
+ * Returns the "next" URL or null.
+ */
+function parseNextLink(linkHeader: string | null): string | null {
+  if (!linkHeader) return null;
+  const match = linkHeader.match(/<([^>]+)>;\s*rel="next"/);
+  return match ? match[1] : null;
+}
+
+interface GitTag {
+  name: string;
+  commit: { sha: string };
+}
+
+/**
+ * Resolve an image tag to a commit SHA by matching against git tags.
+ * Tries exact match first, then prefix match (e.g., v2.10 -> highest v2.10.x).
+ * Returns [commit_sha, is_exact_match] or null.
+ */
+export async function resolveTagToCommit(
+  owner: string,
+  repo: string,
+  tag: string
+): Promise<[string, boolean] | null> {
+  const headers = githubHeaders();
+  let url: string | null =
+    `https://api.github.com/repos/${owner}/${repo}/tags?per_page=100`;
+
+  const prefixCandidates: [number[], string][] = [];
+
+  while (url) {
+    const resp = await fetch(url, {
+      headers,
+      signal: AbortSignal.timeout(10000),
+    });
+    if (!resp.ok) return null;
+
+    const gitTags: GitTag[] = await resp.json() as GitTag[];
+
+    for (const gitTag of gitTags) {
+      const name = gitTag.name;
+      // Exact match (with/without v prefix)
+      if (
+        name === tag ||
+        name === `v${tag}` ||
+        normalizeTag(name) === normalizeTag(tag)
+      ) {
+        return [gitTag.commit.sha, true];
+      }
+
+      // Collect prefix match candidates
+      if (isPrefixMatch(tag, name)) {
+        const version = parseVersionTuple(name);
+        if (version !== null) {
+          prefixCandidates.push([version, gitTag.commit.sha]);
+        }
+      }
+    }
+
+    url = parseNextLink(resp.headers.get("link"));
+  }
+
+  // Return the highest version among prefix matches
+  if (prefixCandidates.length > 0) {
+    prefixCandidates.sort((a, b) => compareVersions(b[0], a[0]));
+    return [prefixCandidates[0][1], false];
+  }
+
+  return null;
+}
+
+/**
+ * Get the commit SHA of the latest GitHub release.
+ * Returns [commit_sha, tag_name] or null.
+ */
+export async function getLatestReleaseCommit(
+  owner: string,
+  repo: string
+): Promise<[string, string] | null> {
+  const headers = githubHeaders();
+  try {
+    const resp = await fetch(
+      `https://api.github.com/repos/${owner}/${repo}/releases/latest`,
+      { headers, signal: AbortSignal.timeout(10000) }
+    );
+    if (!resp.ok) return null;
+    const data = (await resp.json()) as { tag_name?: string };
+    const tagName = data.tag_name;
+    if (!tagName) return null;
+
+    const tagResult = await resolveTagToCommit(owner, repo, tagName);
+    if (tagResult) {
+      return [tagResult[0], tagName];
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get the latest commit SHA on the default branch.
+ */
+export async function getLatestCommit(
+  owner: string,
+  repo: string
+): Promise<string | null> {
+  const headers = githubHeaders();
+  try {
+    const resp = await fetch(
+      `https://api.github.com/repos/${owner}/${repo}/commits?per_page=1`,
+      { headers, signal: AbortSignal.timeout(10000) }
+    );
+    if (!resp.ok) return null;
+    const commits = (await resp.json()) as { sha: string }[];
+    if (commits.length > 0) return commits[0].sha;
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
+/**
+ * Check if a GitHub repo exists.
+ */
+export async function checkGithubRepoExists(
+  owner: string,
+  repo: string
+): Promise<boolean> {
+  const headers = githubHeaders();
+  try {
+    const resp = await fetch(
+      `https://api.github.com/repos/${owner}/${repo}`,
+      { headers, signal: AbortSignal.timeout(10000) }
+    );
+    return resp.status === 200;
+  } catch {
+    return false;
+  }
+}
+
+interface PackageVersionResult {
+  repo: string;
+  commit: string | null;
+  tags: string[];
+}
+
+/**
+ * Find a GHCR package version by digest or tag via the GitHub Packages API.
+ */
+async function findGhcrPackageVersion(
+  owner: string,
+  packageName: string,
+  options: { matchDigest?: string; matchTag?: string }
+): Promise<PackageVersionResult | null> {
+  const headers = githubHeaders();
+  if (!headers.Authorization) return null;
+
+  for (const entityType of ["orgs", "users"]) {
+    const pkgBase = `https://api.github.com/${entityType}/${owner}/packages/container/${packageName}`;
+
+    // Get package metadata for source repo
+    let fullName: string | undefined;
+    try {
+      const pkgResp = await fetch(pkgBase, {
+        headers,
+        signal: AbortSignal.timeout(10000),
+      });
+      if (pkgResp.status === 403) return null;
+      if (!pkgResp.ok) continue;
+      const pkgData = await pkgResp.json();
+      fullName = (pkgData as any)?.repository?.full_name;
+      if (!fullName) continue;
+    } catch {
+      continue;
+    }
+
+    // Search versions
+    let versionsUrl: string | null = `${pkgBase}/versions?per_page=50`;
+    try {
+      while (versionsUrl) {
+        const resp = await fetch(versionsUrl, {
+          headers,
+          signal: AbortSignal.timeout(10000),
+        });
+        if (!resp.ok) break;
+
+        const versions = (await resp.json()) as any[];
+
+        for (const version of versions) {
+          const name: string = version.name ?? "";
+          const metadata = version.metadata?.container ?? {};
+          const tags: string[] = metadata.tags ?? [];
+
+          // Match by digest (version name is the digest)
+          if (options.matchDigest && name !== options.matchDigest) {
+            if (!options.matchTag) continue;
+          }
+          // Match by tag
+          if (options.matchTag && !tags.includes(options.matchTag)) continue;
+
+          // Found matching version - resolve tags to a commit
+          const [repoOwner, repoName] = fullName!.split("/", 2);
+          const resolvableTags = tags.filter((t) => t !== "latest");
+          for (const t of resolvableTags) {
+            const tagResult = await resolveTagToCommit(repoOwner, repoName, t);
+            if (tagResult) {
+              return { repo: fullName!, commit: tagResult[0], tags };
+            }
+          }
+
+          return { repo: fullName!, commit: null, tags };
+        }
+
+        versionsUrl = parseNextLink(resp.headers.get("link"));
+      }
+    } catch {
+      continue;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Find the commit for a GHCR image by its digest.
+ */
+export async function resolveGhcrDigestViaPackages(
+  owner: string,
+  packageName: string,
+  digest: string
+): Promise<PackageVersionResult | null> {
+  return findGhcrPackageVersion(owner, packageName, { matchDigest: digest });
+}
+
+/**
+ * Find the commit for a GHCR image's :latest tag.
+ */
+export async function resolveGhcrLatestViaPackages(
+  owner: string,
+  packageName: string
+): Promise<PackageVersionResult | null> {
+  return findGhcrPackageVersion(owner, packageName, { matchTag: "latest" });
+}
+
+/**
+ * Try to find the GitHub repo for a Docker Hub image.
+ */
+export async function inferRepoFromDockerhub(
+  namespace: string,
+  name: string
+): Promise<[string, string] | null> {
+  // For official images (library/X), try the image name as org/repo directly
+  if (namespace === "library") {
+    if (await checkGithubRepoExists(name, name)) {
+      return [name, name];
+    }
+  }
+
+  // For namespaced images, try namespace/name on GitHub
+  if (namespace !== "library") {
+    if (await checkGithubRepoExists(namespace, name)) {
+      return [namespace, name];
+    }
+  }
+
+  // Fall back to scraping Docker Hub description for GitHub links
+  try {
+    const resp = await fetch(
+      `https://hub.docker.com/v2/repositories/${namespace}/${name}`,
+      { signal: AbortSignal.timeout(10000) }
+    );
+    if (!resp.ok) return null;
+
+    const data = (await resp.json()) as {
+      full_description?: string;
+      description?: string;
+    };
+    const text =
+      (data.full_description || "") + " " + (data.description || "");
+    const match = text.match(/https?:\/\/github\.com\/([\w.-]+)\/([\w.-]+)/);
+    if (match) {
+      return [match[1], match[2]];
+    }
+  } catch {
+    // ignore
+  }
+
+  return null;
+}

package/src/index.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/src/output.ts

@@ -0,0 +1,57 @@
+import type { ImageResult } from "./types.js";
+
+/**
+ * Format results as a JSON array.
+ */
+export function formatJson(results: ImageResult[]): string {
+  return JSON.stringify(results, null, 2);
+}
+
+/**
+ * Format results as a box-drawing table.
+ */
+export function formatTable(results: ImageResult[]): string {
+  const columns = ["SERVICE", "IMAGE", "REPO", "COMMIT", "STATUS", "CONFIDENCE"];
+
+  // Build rows
+  const rows: string[][] = 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: string, w: number) => 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"
+  );
+}

package/src/registry.ts

@@ -0,0 +1,153 @@
+import type { ImageRef } from "./types.js";
+
+/**
+ * Get an anonymous pull token from an OCI registry.
+ */
+export async function getRegistryToken(
+  registry: string,
+  repoPath: string
+): Promise<string | null> {
+  let url: string;
+
+  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()) as { token?: string };
+    return data.token ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function registryBaseUrl(registry: string): string {
+  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",
+]);
+
+interface ManifestPlatform {
+  os?: string;
+  architecture?: string;
+}
+
+interface ManifestEntry {
+  digest: string;
+  platform?: ManifestPlatform;
+}
+
+/**
+ * Resolve a manifest reference to a config blob digest, handling multi-arch indexes.
+ */
+async function resolveManifestToConfigDigest(
+  baseUrl: string,
+  repoPath: string,
+  reference: string,
+  token: string
+): Promise<string | null> {
+  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: string = data.mediaType ?? "";
+
+    // If it's an index/manifest list, pick amd64/linux
+    if (INDEX_MEDIA_TYPES.has(mediaType)) {
+      const manifests: ManifestEntry[] = data.manifests ?? [];
+      let platformDigest: string | null = 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: ImageRef
+): Promise<Record<string, string>> {
+  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 {};
+  }
+}