@kustodian/registry 1.0.0

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@kustodian/registry",
+  "version": "1.0.0",
+  "description": "Container registry client for fetching image tags from Docker Hub and GHCR",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "typecheck": "bun run tsc --noEmit"
+  },
+  "keywords": [
+    "kustodian",
+    "registry",
+    "docker",
+    "ghcr",
+    "container"
+  ],
+  "author": "Luca Silverentand <luca@onezero.company>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lucasilverentand/kustodian.git",
+    "directory": "packages/registry"
+  },
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com"
+  },
+  "dependencies": {
+    "@kustodian/core": "workspace:*",
+    "semver": "^7.6.0"
+  },
+  "devDependencies": {
+    "@types/semver": "^7.5.0"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,51 @@
+import type { RegistryAuthType } from './types.js';
+
+/**
+ * Gets authentication for Docker Hub from environment variables.
+ */
+export function get_dockerhub_auth(): RegistryAuthType | undefined {
+  const username = process.env['DOCKER_USERNAME'];
+  const password = process.env['DOCKER_PASSWORD'];
+
+  if (username && password) {
+    return { username, password };
+  }
+
+  return undefined;
+}
+
+/**
+ * Gets authentication for GHCR from environment variables.
+ */
+export function get_ghcr_auth(): RegistryAuthType | undefined {
+  const token = process.env['GITHUB_TOKEN'] || process.env['GH_TOKEN'];
+
+  if (token) {
+    return { token };
+  }
+
+  return undefined;
+}
+
+/**
+ * Gets authentication for a registry based on hostname.
+ */
+export function get_auth_for_registry(registry: string): RegistryAuthType | undefined {
+  if (registry === 'docker.io' || registry === 'registry.hub.docker.com') {
+    return get_dockerhub_auth();
+  }
+
+  if (registry === 'ghcr.io') {
+    return get_ghcr_auth();
+  }
+
+  // Generic fallback
+  const username = process.env['REGISTRY_USERNAME'];
+  const password = process.env['REGISTRY_PASSWORD'];
+
+  if (username && password) {
+    return { username, password };
+  }
+
+  return undefined;
+}

package/src/client.ts

@@ -0,0 +1,95 @@
+import { get_auth_for_registry } from './auth.js';
+import { create_dockerhub_client } from './dockerhub.js';
+import { create_ghcr_client } from './ghcr.js';
+import type { ImageReferenceType, RegistryClientConfigType, RegistryClientType } from './types.js';
+
+/**
+ * Parses an image string into its components.
+ *
+ * Supports various formats:
+ * - nginx -> docker.io/library/nginx
+ * - prom/prometheus -> docker.io/prom/prometheus
+ * - ghcr.io/org/image -> ghcr.io/org/image
+ * - ghcr.io/org/image:tag -> ghcr.io/org/image:tag
+ */
+export function parse_image_reference(image: string): ImageReferenceType {
+  let registry = 'docker.io';
+  let namespace = 'library';
+  let repository: string;
+  let tag: string | undefined;
+
+  // Split tag if present
+  const colonIndex = image.lastIndexOf(':');
+  let imagePart = image;
+
+  // Only treat as tag if there's no slash after the colon (to handle ports)
+  if (colonIndex > 0 && !image.slice(colonIndex).includes('/')) {
+    imagePart = image.slice(0, colonIndex);
+    tag = image.slice(colonIndex + 1);
+  }
+
+  const parts = imagePart.split('/');
+
+  if (parts.length === 1 && parts[0]) {
+    // Simple image name: nginx -> docker.io/library/nginx
+    repository = parts[0];
+  } else if (parts.length === 2 && parts[0] && parts[1]) {
+    if (parts[0].includes('.') || parts[0].includes(':')) {
+      // Custom registry without namespace: registry.io/image
+      registry = parts[0];
+      namespace = 'library';
+      repository = parts[1];
+    } else {
+      // Docker Hub with namespace: prom/prometheus
+      namespace = parts[0];
+      repository = parts[1];
+    }
+  } else if (parts.length >= 3 && parts[0] && parts[1]) {
+    // Full path: ghcr.io/org/image
+    registry = parts[0];
+    namespace = parts[1];
+    repository = parts.slice(2).join('/');
+  } else {
+    // Fallback - should not happen with valid input
+    repository = imagePart;
+  }
+
+  return { registry, namespace, repository, tag };
+}
+
+/**
+ * Detects the registry type from an image reference.
+ */
+export function detect_registry_type(image: ImageReferenceType): 'dockerhub' | 'ghcr' {
+  if (image.registry === 'ghcr.io') {
+    return 'ghcr';
+  }
+
+  // Default to Docker Hub
+  return 'dockerhub';
+}
+
+/**
+ * Creates a registry client for the given registry type.
+ */
+export function create_registry_client(
+  registry_type: 'dockerhub' | 'ghcr',
+  config?: RegistryClientConfigType,
+): RegistryClientType {
+  switch (registry_type) {
+    case 'ghcr':
+      return create_ghcr_client(config);
+    default:
+      return create_dockerhub_client(config);
+  }
+}
+
+/**
+ * Creates a registry client with auto-detected type and authentication.
+ */
+export function create_client_for_image(image: ImageReferenceType): RegistryClientType {
+  const registry_type = detect_registry_type(image);
+  const auth = get_auth_for_registry(image.registry);
+
+  return create_registry_client(registry_type, { auth });
+}

package/src/dockerhub.ts

@@ -0,0 +1,130 @@
+import { type ResultType, failure, success } from '@kustodian/core';
+import type { KustodianErrorType } from '@kustodian/core';
+import type {
+  ImageReferenceType,
+  RegistryClientConfigType,
+  RegistryClientType,
+  TagInfoType,
+} from './types.js';
+
+const DOCKERHUB_AUTH_URL = 'https://auth.docker.io/token';
+const DOCKERHUB_REGISTRY_URL = 'https://registry-1.docker.io/v2';
+const DEFAULT_TIMEOUT = 30000;
+
+interface DockerHubTokenResponse {
+  token: string;
+  access_token?: string;
+  expires_in?: number;
+}
+
+interface DockerHubTagsResponse {
+  name: string;
+  tags: string[];
+}
+
+/**
+ * Creates an abort signal with timeout.
+ */
+function create_abort_signal(timeout_ms: number): AbortSignal {
+  const controller = new AbortController();
+  setTimeout(() => controller.abort(), timeout_ms);
+  return controller.signal;
+}
+
+/**
+ * Gets an authentication token for Docker Hub.
+ */
+async function get_dockerhub_token(
+  image: ImageReferenceType,
+  config?: RegistryClientConfigType,
+): Promise<ResultType<string, KustodianErrorType>> {
+  const scope = `repository:${image.namespace}/${image.repository}:pull`;
+  const url = `${DOCKERHUB_AUTH_URL}?service=registry.docker.io&scope=${encodeURIComponent(scope)}`;
+
+  const headers: Record<string, string> = {};
+
+  if (config?.auth?.username && config.auth.password) {
+    const credentials = Buffer.from(`${config.auth.username}:${config.auth.password}`).toString(
+      'base64',
+    );
+    headers['Authorization'] = `Basic ${credentials}`;
+  }
+
+  try {
+    const response = await fetch(url, {
+      headers,
+      signal: create_abort_signal(config?.timeout ?? DEFAULT_TIMEOUT),
+    });
+
+    if (!response.ok) {
+      return failure({
+        code: 'REGISTRY_AUTH_ERROR',
+        message: `Docker Hub auth failed: ${response.status} ${response.statusText}`,
+      });
+    }
+
+    const data = (await response.json()) as DockerHubTokenResponse;
+    const token = data.token || data.access_token;
+
+    if (!token) {
+      return failure({
+        code: 'REGISTRY_AUTH_ERROR',
+        message: 'No token returned from Docker Hub auth',
+      });
+    }
+
+    return success(token);
+  } catch (error) {
+    return failure({
+      code: 'REGISTRY_ERROR',
+      message: `Docker Hub auth request failed: ${error instanceof Error ? error.message : String(error)}`,
+    });
+  }
+}
+
+/**
+ * Creates a Docker Hub registry client.
+ */
+export function create_dockerhub_client(config?: RegistryClientConfigType): RegistryClientType {
+  return {
+    async list_tags(
+      image: ImageReferenceType,
+    ): Promise<ResultType<TagInfoType[], KustodianErrorType>> {
+      // Get auth token
+      const token_result = await get_dockerhub_token(image, config);
+      if (!token_result.success) {
+        return token_result;
+      }
+
+      const url = `${DOCKERHUB_REGISTRY_URL}/${image.namespace}/${image.repository}/tags/list`;
+
+      try {
+        const response = await fetch(url, {
+          headers: {
+            Authorization: `Bearer ${token_result.value}`,
+            Accept: 'application/json',
+          },
+          signal: create_abort_signal(config?.timeout ?? DEFAULT_TIMEOUT),
+        });
+
+        if (!response.ok) {
+          return failure({
+            code: 'REGISTRY_ERROR',
+            message: `Failed to fetch tags: ${response.status} ${response.statusText}`,
+          });
+        }
+
+        const data = (await response.json()) as DockerHubTagsResponse;
+
+        const tags: TagInfoType[] = (data.tags || []).map((name) => ({ name }));
+
+        return success(tags);
+      } catch (error) {
+        return failure({
+          code: 'REGISTRY_ERROR',
+          message: `Failed to fetch tags: ${error instanceof Error ? error.message : String(error)}`,
+        });
+      }
+    },
+  };
+}

package/src/ghcr.ts

@@ -0,0 +1,131 @@
+import { type ResultType, failure, success } from '@kustodian/core';
+import type { KustodianErrorType } from '@kustodian/core';
+import type {
+  ImageReferenceType,
+  RegistryClientConfigType,
+  RegistryClientType,
+  TagInfoType,
+} from './types.js';
+
+const GHCR_URL = 'https://ghcr.io/v2';
+const GHCR_AUTH_URL = 'https://ghcr.io/token';
+const DEFAULT_TIMEOUT = 30000;
+
+interface GhcrTokenResponse {
+  token: string;
+}
+
+interface GhcrTagsResponse {
+  name: string;
+  tags: string[];
+}
+
+/**
+ * Creates an abort signal with timeout.
+ */
+function create_abort_signal(timeout_ms: number): AbortSignal {
+  const controller = new AbortController();
+  setTimeout(() => controller.abort(), timeout_ms);
+  return controller.signal;
+}
+
+/**
+ * Gets an authentication token for GHCR.
+ */
+async function get_ghcr_token(
+  image: ImageReferenceType,
+  config?: RegistryClientConfigType,
+): Promise<ResultType<string, KustodianErrorType>> {
+  const scope = `repository:${image.namespace}/${image.repository}:pull`;
+  const url = `${GHCR_AUTH_URL}?service=ghcr.io&scope=${encodeURIComponent(scope)}`;
+
+  const headers: Record<string, string> = {};
+
+  // GHCR supports token-based auth or username/password
+  if (config?.auth?.token) {
+    // Use bearer token (GitHub PAT)
+    headers['Authorization'] = `Bearer ${config.auth.token}`;
+  } else if (config?.auth?.username && config.auth.password) {
+    const credentials = Buffer.from(`${config.auth.username}:${config.auth.password}`).toString(
+      'base64',
+    );
+    headers['Authorization'] = `Basic ${credentials}`;
+  }
+
+  try {
+    const response = await fetch(url, {
+      headers,
+      signal: create_abort_signal(config?.timeout ?? DEFAULT_TIMEOUT),
+    });
+
+    if (!response.ok) {
+      return failure({
+        code: 'REGISTRY_AUTH_ERROR',
+        message: `GHCR auth failed: ${response.status} ${response.statusText}`,
+      });
+    }
+
+    const data = (await response.json()) as GhcrTokenResponse;
+
+    if (!data.token) {
+      return failure({
+        code: 'REGISTRY_AUTH_ERROR',
+        message: 'No token returned from GHCR auth',
+      });
+    }
+
+    return success(data.token);
+  } catch (error) {
+    return failure({
+      code: 'REGISTRY_ERROR',
+      message: `GHCR auth request failed: ${error instanceof Error ? error.message : String(error)}`,
+    });
+  }
+}
+
+/**
+ * Creates a GitHub Container Registry client.
+ */
+export function create_ghcr_client(config?: RegistryClientConfigType): RegistryClientType {
+  return {
+    async list_tags(
+      image: ImageReferenceType,
+    ): Promise<ResultType<TagInfoType[], KustodianErrorType>> {
+      // Get auth token
+      const token_result = await get_ghcr_token(image, config);
+      if (!token_result.success) {
+        return token_result;
+      }
+
+      const url = `${GHCR_URL}/${image.namespace}/${image.repository}/tags/list`;
+
+      try {
+        const response = await fetch(url, {
+          headers: {
+            Authorization: `Bearer ${token_result.value}`,
+            Accept: 'application/json',
+          },
+          signal: create_abort_signal(config?.timeout ?? DEFAULT_TIMEOUT),
+        });
+
+        if (!response.ok) {
+          return failure({
+            code: 'REGISTRY_ERROR',
+            message: `Failed to fetch tags: ${response.status} ${response.statusText}`,
+          });
+        }
+
+        const data = (await response.json()) as GhcrTagsResponse;
+
+        const tags: TagInfoType[] = (data.tags || []).map((name) => ({ name }));
+
+        return success(tags);
+      } catch (error) {
+        return failure({
+          code: 'REGISTRY_ERROR',
+          message: `Failed to fetch tags: ${error instanceof Error ? error.message : String(error)}`,
+        });
+      }
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+// Types
+export type {
+  ImageReferenceType,
+  RegistryAuthType,
+  RegistryClientConfigType,
+  RegistryClientType,
+  TagInfoType,
+  VersionCheckResultType,
+} from './types.js';
+
+// Client utilities
+export {
+  parse_image_reference,
+  detect_registry_type,
+  create_registry_client,
+  create_client_for_image,
+} from './client.js';
+
+// Registry implementations
+export { create_dockerhub_client } from './dockerhub.js';
+export { create_ghcr_client } from './ghcr.js';
+
+// Auth utilities
+export { get_dockerhub_auth, get_ghcr_auth, get_auth_for_registry } from './auth.js';
+
+// Version utilities
+export {
+  DEFAULT_SEMVER_PATTERN,
+  filter_semver_tags,
+  find_latest_matching,
+  check_version_update,
+} from './version.js';

package/src/types.ts

@@ -0,0 +1,60 @@
+import type { KustodianErrorType, ResultType } from '@kustodian/core';
+
+/**
+ * Authentication configuration for registries.
+ */
+export interface RegistryAuthType {
+  username?: string;
+  password?: string;
+  token?: string;
+}
+
+/**
+ * Registry client configuration.
+ */
+export interface RegistryClientConfigType {
+  auth?: RegistryAuthType | undefined;
+  timeout?: number | undefined;
+}
+
+/**
+ * Parsed image reference components.
+ */
+export interface ImageReferenceType {
+  /** Registry hostname (e.g., docker.io, ghcr.io) */
+  registry: string;
+  /** Namespace/organization (e.g., library, prom) */
+  namespace: string;
+  /** Repository name (e.g., nginx, prometheus) */
+  repository: string;
+  /** Optional tag */
+  tag?: string | undefined;
+}
+
+/**
+ * Tag information from registry.
+ */
+export interface TagInfoType {
+  name: string;
+  digest?: string;
+}
+
+/**
+ * Version check result.
+ */
+export interface VersionCheckResultType {
+  current_version: string;
+  latest_version: string;
+  available_versions: string[];
+  has_update: boolean;
+}
+
+/**
+ * Registry client interface.
+ */
+export interface RegistryClientType {
+  /**
+   * Lists all tags for an image.
+   */
+  list_tags(image: ImageReferenceType): Promise<ResultType<TagInfoType[], KustodianErrorType>>;
+}

package/src/version.ts

@@ -0,0 +1,87 @@
+import * as semver from 'semver';
+import type { TagInfoType, VersionCheckResultType } from './types.js';
+
+/**
+ * Default pattern for semver-like tags.
+ * Matches: 1.0.0, v1.0.0, 1.0.0-alpha, v1.0.0-rc.1
+ */
+export const DEFAULT_SEMVER_PATTERN = /^v?(\d+\.\d+\.\d+)(-[\w.]+)?$/;
+
+/**
+ * Filters tags to only semver-valid versions.
+ */
+export function filter_semver_tags(
+  tags: TagInfoType[],
+  options: {
+    pattern?: RegExp;
+    exclude_prerelease?: boolean;
+  } = {},
+): string[] {
+  const pattern = options.pattern ?? DEFAULT_SEMVER_PATTERN;
+  const exclude_prerelease = options.exclude_prerelease ?? true;
+
+  const versions: string[] = [];
+
+  for (const tag of tags) {
+    if (!pattern.test(tag.name)) {
+      continue;
+    }
+
+    const cleaned = semver.clean(tag.name);
+    if (!cleaned) {
+      continue;
+    }
+
+    const parsed = semver.parse(cleaned);
+    if (!parsed) {
+      continue;
+    }
+
+    if (exclude_prerelease && parsed.prerelease.length > 0) {
+      continue;
+    }
+
+    versions.push(cleaned);
+  }
+
+  // Sort descending (newest first)
+  return versions.sort(semver.rcompare);
+}
+
+/**
+ * Finds the latest version satisfying a constraint.
+ */
+export function find_latest_matching(versions: string[], constraint?: string): string | undefined {
+  if (!constraint) {
+    // Return the latest (first in sorted array)
+    return versions[0];
+  }
+
+  const result = semver.maxSatisfying(versions, constraint);
+  return result ?? undefined;
+}
+
+/**
+ * Checks if a newer version is available.
+ */
+export function check_version_update(
+  current: string,
+  available: string[],
+  constraint?: string,
+): VersionCheckResultType {
+  const cleaned_current = semver.clean(current) ?? current;
+  const latest = find_latest_matching(available, constraint);
+
+  const has_update =
+    latest !== undefined &&
+    semver.valid(latest) !== null &&
+    semver.valid(cleaned_current) !== null &&
+    semver.gt(latest, cleaned_current);
+
+  return {
+    current_version: cleaned_current,
+    latest_version: latest ?? cleaned_current,
+    available_versions: available,
+    has_update,
+  };
+}