@provos/ironcurtain 0.7.2 → 0.8.0

package/dist/docker/registry-proxy.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Registry proxy: URL parsing, metadata filtering, and tarball backstop
+ * for npm and PyPI package registries.
+ *
+ * This module provides:
+ * - URL parsers that extract PackageIdentity from HTTP request paths
+ * - Metadata filtering functions that remove disallowed versions
+ * - Tarball backstop logic that blocks direct tarball URL access
+ * - Built-in registry configurations for npm and PyPI
+ */
+import * as http from 'node:http';
+import type { PackageIdentity, PackageValidator, AllowedVersionCache, RegistryConfig } from './package-types.js';
+export declare const npmRegistry: RegistryConfig;
+export declare const pypiRegistry: RegistryConfig;
+export declare const debianRegistry: RegistryConfig;
+/**
+ * Parses an npm registry URL path into a PackageIdentity.
+ * Returns undefined if the path doesn't match a known pattern.
+ *
+ * Patterns:
+ *   GET /@scope/name           -> metadata (scope + name)
+ *   GET /@scope%2fname         -> metadata (URL-encoded scope)
+ *   GET /name                  -> metadata (unscoped)
+ *   GET /name/-/name-1.0.0.tgz -> tarball (unscoped)
+ *   GET /@scope/name/-/name-1.0.0.tgz -> tarball (scoped)
+ */
+export declare function parseNpmUrl(path: string): PackageIdentity | undefined;
+/**
+ * Parses a PyPI Simple Repository URL path into a PackageIdentity.
+ * Returns undefined if the path doesn't match.
+ *
+ * Pattern: GET /simple/{name}/
+ */
+export declare function parsePypiSimpleUrl(path: string): PackageIdentity | undefined;
+/**
+ * Parses a PyPI tarball URL path into a PackageIdentity.
+ * Returns undefined if the path doesn't match.
+ *
+ * Tarball URLs on files.pythonhosted.org:
+ *   /packages/.../numpy-1.26.0.tar.gz
+ *   /packages/.../numpy-1.26.0-cp312-cp312-manylinux_2_17_x86_64.whl
+ */
+export declare function parsePypiTarballUrl(path: string): PackageIdentity | undefined;
+/**
+ * Extracts package name and version from a PyPI distribution filename.
+ *
+ * Handles both sdist and wheel formats:
+ *   numpy-1.26.0.tar.gz -> { name: 'numpy', version: '1.26.0' }
+ *   numpy-1.26.0-cp312-*.whl -> { name: 'numpy', version: '1.26.0' }
+ */
+export declare function extractPypiPackageFromFilename(filename: string): PackageIdentity | undefined;
+/**
+ * Normalizes a PyPI package name to lowercase with hyphens.
+ * PEP 503: package names are case-insensitive and treat
+ * hyphens, underscores, and dots as equivalent.
+ */
+export declare function normalizePypiName(name: string): string;
+/**
+ * Extracts package name and version from a Debian `.deb` filename.
+ *
+ * Format: {name}_{version}_{arch}.deb
+ * Examples:
+ *   libssl3_3.0.11-1~deb12u2_arm64.deb -> name='libssl3', version='3.0.11-1~deb12u2'
+ *   gcc-14-base_14.2.0-19_arm64.deb    -> name='gcc-14-base', version='14.2.0-19'
+ *
+ * Epoch versions (e.g., 1:2.3-4) use %3a URL-encoding for the colon.
+ */
+export declare function extractDebianPackageFromFilename(filename: string): PackageIdentity | undefined;
+/**
+ * Parses a Debian repository URL path into a PackageIdentity.
+ * Returns undefined for non-.deb paths (metadata, Release files, etc.).
+ *
+ * Matches any URL whose last path segment ends with `.deb` — not restricted
+ * to `/pool/` paths, since mirrors and security repos may use different layouts.
+ * Non-.deb paths (Release, Packages.gz, GPG keys) return undefined for pass-through.
+ */
+export declare function parseDebianPackageUrl(path: string): PackageIdentity | undefined;
+/** Returns true if the URL path is an npm metadata request (no /-/ segment). */
+export declare function isNpmMetadataRequest(path: string): boolean;
+/** Returns true if the URL path is an npm tarball download. */
+export declare function isNpmTarballRequest(path: string): boolean;
+/** Returns true if the URL path is a PyPI Simple Repository request. */
+export declare function isPypiSimpleRequest(path: string): boolean;
+/** Minimal npm packument structure for filtering. */
+export interface NpmPackument {
+    readonly name: string;
+    readonly versions: Record<string, unknown>;
+    readonly 'dist-tags'?: Record<string, string>;
+    readonly time?: Record<string, string>;
+    readonly [key: string]: unknown;
+}
+/**
+ * Filters an npm packument to remove disallowed versions.
+ *
+ * The filtered packument has:
+ * - Disallowed versions removed from `versions` and `time`
+ * - `dist-tags.latest` updated to point to the newest remaining version
+ * - `created` and `modified` timestamps preserved in `time`
+ */
+export declare function filterNpmPackument(packument: NpmPackument, validator: PackageValidator, packageName: string, scope?: string): {
+    filtered: NpmPackument;
+    denied: Array<{
+        version: string;
+        reason: string;
+    }>;
+};
+/**
+ * Filters a PyPI Simple Repository HTML page to remove disallowed versions.
+ *
+ * The HTML contains <a> elements with hrefs pointing to tarballs/wheels.
+ * Version is extracted from the filename in each href.
+ *
+ * Returns the filtered HTML, denied version list, and the set of allowed
+ * versions (collected during filtering to avoid re-parsing the HTML).
+ */
+export declare function filterPypiIndex(html: string, validator: PackageValidator, packageName: string, versionTimestamps: Map<string, Date>): {
+    filtered: string;
+    denied: Array<{
+        version: string;
+        reason: string;
+    }>;
+    allowedVersions: Set<string>;
+};
+/**
+ * Gets allowed versions from cache, returning undefined on miss or expiry.
+ */
+export declare function getCachedVersions(cache: AllowedVersionCache, pkg: PackageIdentity): ReadonlySet<string> | undefined;
+/**
+ * Stores allowed versions in the cache.
+ */
+export declare function setCachedVersions(cache: AllowedVersionCache, pkg: PackageIdentity, versions: ReadonlySet<string>): void;
+/** Options for the registry request handler. */
+export interface RegistryHandlerOptions {
+    readonly validator: PackageValidator;
+    readonly cache: AllowedVersionCache;
+    readonly auditLogPath?: string;
+}
+/**
+ * Handles an HTTP request routed to a registry host.
+ * Dispatches to metadata filtering or tarball backstop based on URL pattern.
+ */
+export declare function handleRegistryRequest(registry: RegistryConfig, clientReq: http.IncomingMessage, clientRes: http.ServerResponse, host: string, port: number, options: RegistryHandlerOptions): Promise<void>;