v2.2.2

changelog.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 2025-11-25 - 2.2.2 - fix(npm)
+Replace console logging with structured Smartlog in NPM registry and silence RubyGems helper error logging
+
+- Replaced console.log calls with this.logger.log (Smartlog) in ts/npm/classes.npmregistry.ts for debug/info/success events
+- Converted console.error in NpmRegistry.handleSearch to structured logger.log('error', ...) including the error message
+- Removed console.error from ts/rubygems/helpers.rubygems.ts; gem metadata extraction failures are now handled silently by returning null
+
+## 2025-11-25 - 2.2.1 - fix(core)
+Normalize binary data handling across registries and add buffer helpers
+
+- Add core/helpers.buffer.ts with isBinaryData and toBuffer utilities to consistently handle Buffer, Uint8Array, string and object inputs.
+- Composer: accept Uint8Array uploads, convert to Buffer before ZIP extraction, SHA-1 calculation and storage.
+- PyPI: accept multipart file content as Buffer or Uint8Array and normalize to Buffer before processing and storage.
+- Maven: normalize artifact body input with toBuffer before validation and storage.
+- OCI: improve upload id generation by using substring for correct random length.
+
+## 2025-11-25 - 2.2.0 - feat(core/registrystorage)
+Persist OCI manifest content-type in sidecar and normalize manifest body handling
+
+- Add getOciManifestContentType(repository, digest) to read stored manifest Content-Type
+- Store manifest Content-Type in a .type sidecar file when putOciManifest is called
+- Update putOciManifest to persist both manifest data and its content type
+- OciRegistry now retrieves stored content type (with fallback to detectManifestContentType) when serving manifests
+- Add toBuffer helper in OciRegistry to consistently convert various request body forms to Buffer for digest calculation and uploads
+
 ## 2025-11-25 - 2.1.2 - fix(oci)
 Prefer raw request body for content-addressable OCI operations and expose rawBody on request context
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartregistry",
-  "version": "2.1.2",
+  "version": "2.2.2",
   "private": false,
   "description": "A composable TypeScript library implementing OCI, NPM, Maven, Cargo, Composer, PyPI, and RubyGems registries for building unified container and package registries",
   "main": "dist_ts/index.js",

test/test.composer.nativecli.node.ts

@@ -0,0 +1,425 @@
+/**
+ * Native Composer CLI Testing
+ * Tests the Composer registry implementation using the actual composer CLI
+ */
+
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import { tapNodeTools } from '@git.zone/tstest/tapbundle_serverside';
+import { SmartRegistry } from '../ts/index.js';
+import { createTestRegistry, createTestTokens, createComposerZip } from './helpers/registry.js';
+import type { IRequestContext, IResponse } from '../ts/core/interfaces.core.js';
+import * as http from 'http';
+import * as url from 'url';
+import * as fs from 'fs';
+import * as path from 'path';
+
+// Test context
+let registry: SmartRegistry;
+let server: http.Server;
+let registryUrl: string;
+let registryPort: number;
+let composerToken: string;
+let testDir: string;
+let composerHome: string;
+
+/**
+ * Create HTTP server wrapper around SmartRegistry
+ */
+async function createHttpServer(
+  registryInstance: SmartRegistry,
+  port: number
+): Promise<{ server: http.Server; url: string }> {
+  return new Promise((resolve, reject) => {
+    const httpServer = http.createServer(async (req, res) => {
+      try {
+        // Parse request
+        const parsedUrl = url.parse(req.url || '', true);
+        const pathname = parsedUrl.pathname || '/';
+        const query = parsedUrl.query;
+
+        // Read body
+        const chunks: Buffer[] = [];
+        for await (const chunk of req) {
+          chunks.push(chunk);
+        }
+        const bodyBuffer = Buffer.concat(chunks);
+
+        // Parse body based on content type
+        let body: any;
+        if (bodyBuffer.length > 0) {
+          const contentType = req.headers['content-type'] || '';
+          if (contentType.includes('application/json')) {
+            try {
+              body = JSON.parse(bodyBuffer.toString('utf-8'));
+            } catch (error) {
+              body = bodyBuffer;
+            }
+          } else {
+            body = bodyBuffer;
+          }
+        }
+
+        // Convert to IRequestContext
+        const context: IRequestContext = {
+          method: req.method || 'GET',
+          path: pathname,
+          headers: req.headers as Record<string, string>,
+          query: query as Record<string, string>,
+          body: body,
+        };
+
+        // Handle request
+        const response: IResponse = await registryInstance.handleRequest(context);
+
+        // Convert IResponse to HTTP response
+        res.statusCode = response.status;
+
+        // Set headers
+        for (const [key, value] of Object.entries(response.headers || {})) {
+          res.setHeader(key, value);
+        }
+
+        // Send body
+        if (response.body) {
+          if (Buffer.isBuffer(response.body)) {
+            res.end(response.body);
+          } else if (typeof response.body === 'string') {
+            res.end(response.body);
+          } else {
+            res.setHeader('Content-Type', 'application/json');
+            res.end(JSON.stringify(response.body));
+          }
+        } else {
+          res.end();
+        }
+      } catch (error) {
+        console.error('Server error:', error);
+        res.statusCode = 500;
+        res.setHeader('Content-Type', 'application/json');
+        res.end(JSON.stringify({ error: 'INTERNAL_ERROR', message: String(error) }));
+      }
+    });
+
+    httpServer.listen(port, () => {
+      const serverUrl = `http://localhost:${port}`;
+      resolve({ server: httpServer, url: serverUrl });
+    });
+
+    httpServer.on('error', reject);
+  });
+}
+
+/**
+ * Setup Composer auth.json for authentication
+ */
+function setupComposerAuth(
+  token: string,
+  composerHomeArg: string,
+  serverUrl: string,
+  port: number
+): string {
+  fs.mkdirSync(composerHomeArg, { recursive: true });
+
+  const authJson = {
+    'http-basic': {
+      [`localhost:${port}`]: {
+        username: 'testuser',
+        password: token,
+      },
+    },
+  };
+
+  const authPath = path.join(composerHomeArg, 'auth.json');
+  fs.writeFileSync(authPath, JSON.stringify(authJson, null, 2), 'utf-8');
+
+  return authPath;
+}
+
+/**
+ * Create a Composer project that uses our registry
+ */
+function createComposerProject(
+  projectDir: string,
+  serverUrl: string
+): void {
+  fs.mkdirSync(projectDir, { recursive: true });
+
+  const composerJson = {
+    name: 'test/consumer-project',
+    description: 'Test consumer project for Composer CLI tests',
+    type: 'project',
+    require: {},
+    repositories: [
+      {
+        type: 'composer',
+        url: `${serverUrl}/composer`,
+      },
+    ],
+    config: {
+      'secure-http': false,
+    },
+  };
+
+  fs.writeFileSync(
+    path.join(projectDir, 'composer.json'),
+    JSON.stringify(composerJson, null, 2),
+    'utf-8'
+  );
+}
+
+/**
+ * Run Composer command with custom home directory
+ */
+async function runComposerCommand(
+  command: string,
+  cwd: string
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  const fullCommand = `cd "${cwd}" && COMPOSER_HOME="${composerHome}" composer ${command}`;
+
+  try {
+    const result = await tapNodeTools.runCommand(fullCommand);
+    return {
+      stdout: result.stdout || '',
+      stderr: result.stderr || '',
+      exitCode: result.exitCode || 0,
+    };
+  } catch (error: any) {
+    return {
+      stdout: error.stdout || '',
+      stderr: error.stderr || String(error),
+      exitCode: error.exitCode || 1,
+    };
+  }
+}
+
+/**
+ * Upload a Composer package via HTTP API
+ */
+async function uploadComposerPackage(
+  vendorPackage: string,
+  version: string,
+  token: string,
+  serverUrl: string
+): Promise<void> {
+  const zipData = await createComposerZip(vendorPackage, version);
+
+  const response = await fetch(`${serverUrl}/composer/packages/${vendorPackage}`, {
+    method: 'PUT',
+    headers: {
+      'Content-Type': 'application/zip',
+      Authorization: `Bearer ${token}`,
+    },
+    body: zipData,
+  });
+
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(`Failed to upload package: ${response.status} ${body}`);
+  }
+}
+
+/**
+ * Cleanup test directory
+ */
+function cleanupTestDir(dir: string): void {
+  if (fs.existsSync(dir)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+// ========================================================================
+// TESTS
+// ========================================================================
+
+tap.test('Composer CLI: should verify composer is installed', async () => {
+  try {
+    const result = await tapNodeTools.runCommand('composer --version');
+    console.log('Composer version output:', result.stdout.substring(0, 200));
+    expect(result.exitCode).toEqual(0);
+  } catch (error) {
+    console.log('Composer CLI not available, skipping native CLI tests');
+    // Skip remaining tests if Composer is not installed
+    tap.skip.test('Composer CLI: remaining tests skipped - composer not available');
+    return;
+  }
+});
+
+tap.test('Composer CLI: should setup registry and HTTP server', async () => {
+  // Create registry
+  registry = await createTestRegistry();
+  const tokens = await createTestTokens(registry);
+  composerToken = tokens.composerToken;
+
+  expect(registry).toBeInstanceOf(SmartRegistry);
+  expect(composerToken).toBeTypeOf('string');
+
+  // Use port 38000 (avoids conflicts with other tests)
+  registryPort = 38000;
+  const serverSetup = await createHttpServer(registry, registryPort);
+  server = serverSetup.server;
+  registryUrl = serverSetup.url;
+
+  expect(server).toBeDefined();
+  expect(registryUrl).toEqual(`http://localhost:${registryPort}`);
+
+  // Setup test directory
+  testDir = path.join(process.cwd(), '.nogit', 'test-composer-cli');
+  cleanupTestDir(testDir);
+  fs.mkdirSync(testDir, { recursive: true });
+
+  // Setup COMPOSER_HOME directory
+  composerHome = path.join(testDir, '.composer');
+  fs.mkdirSync(composerHome, { recursive: true });
+
+  // Setup Composer auth
+  const authPath = setupComposerAuth(composerToken, composerHome, registryUrl, registryPort);
+  expect(fs.existsSync(authPath)).toEqual(true);
+});
+
+tap.test('Composer CLI: should verify server is responding', async () => {
+  // Check server is up by doing a direct HTTP request
+  const response = await fetch(`${registryUrl}/composer/packages.json`);
+  expect(response.status).toBeGreaterThanOrEqual(200);
+  expect(response.status).toBeLessThan(500);
+});
+
+tap.test('Composer CLI: should upload a package via API', async () => {
+  const vendorPackage = 'testvendor/test-package';
+  const version = '1.0.0';
+
+  await uploadComposerPackage(vendorPackage, version, composerToken, registryUrl);
+
+  // Verify package exists via packages.json
+  const response = await fetch(`${registryUrl}/composer/packages.json`);
+  expect(response.status).toEqual(200);
+
+  const packagesJson = await response.json();
+  expect(packagesJson.packages).toBeDefined();
+  expect(packagesJson.packages[vendorPackage]).toBeDefined();
+});
+
+tap.test('Composer CLI: should require package from registry', async () => {
+  const projectDir = path.join(testDir, 'consumer-project');
+  createComposerProject(projectDir, registryUrl);
+
+  // Try to require the package we uploaded
+  const result = await runComposerCommand(
+    'require testvendor/test-package:1.0.0 --no-interaction',
+    projectDir
+  );
+  console.log('composer require output:', result.stdout);
+  console.log('composer require stderr:', result.stderr);
+
+  expect(result.exitCode).toEqual(0);
+});
+
+tap.test('Composer CLI: should verify package in vendor directory', async () => {
+  const projectDir = path.join(testDir, 'consumer-project');
+  const packageDir = path.join(projectDir, 'vendor', 'testvendor', 'test-package');
+
+  expect(fs.existsSync(packageDir)).toEqual(true);
+
+  // Check composer.json exists in package
+  const packageComposerPath = path.join(packageDir, 'composer.json');
+  expect(fs.existsSync(packageComposerPath)).toEqual(true);
+});
+
+tap.test('Composer CLI: should upload second version', async () => {
+  const vendorPackage = 'testvendor/test-package';
+  const version = '2.0.0';
+
+  await uploadComposerPackage(vendorPackage, version, composerToken, registryUrl);
+
+  // Verify both versions exist
+  const response = await fetch(`${registryUrl}/composer/packages.json`);
+  const packagesJson = await response.json();
+
+  expect(packagesJson.packages[vendorPackage]['1.0.0']).toBeDefined();
+  expect(packagesJson.packages[vendorPackage]['2.0.0']).toBeDefined();
+});
+
+tap.test('Composer CLI: should update to new version', async () => {
+  const projectDir = path.join(testDir, 'consumer-project');
+
+  // Update to version 2.0.0
+  const result = await runComposerCommand(
+    'require testvendor/test-package:2.0.0 --no-interaction',
+    projectDir
+  );
+  console.log('composer update output:', result.stdout);
+
+  expect(result.exitCode).toEqual(0);
+
+  // Verify composer.lock has the new version
+  const lockPath = path.join(projectDir, 'composer.lock');
+  expect(fs.existsSync(lockPath)).toEqual(true);
+
+  const lockContent = JSON.parse(fs.readFileSync(lockPath, 'utf-8'));
+  const pkg = lockContent.packages.find((p: any) => p.name === 'testvendor/test-package');
+  expect(pkg?.version).toEqual('2.0.0');
+});
+
+tap.test('Composer CLI: should search for packages', async () => {
+  const projectDir = path.join(testDir, 'consumer-project');
+
+  // Search for packages (may not work on all Composer versions)
+  const result = await runComposerCommand(
+    'search testvendor --no-interaction 2>&1 || true',
+    projectDir
+  );
+  console.log('composer search output:', result.stdout);
+
+  // Search may or may not work depending on registry implementation
+  // Just verify it doesn't crash
+  expect(result.exitCode).toBeLessThanOrEqual(1);
+});
+
+tap.test('Composer CLI: should show package info', async () => {
+  const projectDir = path.join(testDir, 'consumer-project');
+
+  const result = await runComposerCommand(
+    'show testvendor/test-package --no-interaction',
+    projectDir
+  );
+  console.log('composer show output:', result.stdout);
+
+  expect(result.exitCode).toEqual(0);
+  expect(result.stdout).toContain('testvendor/test-package');
+});
+
+tap.test('Composer CLI: should remove package', async () => {
+  const projectDir = path.join(testDir, 'consumer-project');
+
+  const result = await runComposerCommand(
+    'remove testvendor/test-package --no-interaction',
+    projectDir
+  );
+  console.log('composer remove output:', result.stdout);
+
+  expect(result.exitCode).toEqual(0);
+
+  // Verify package is removed from vendor
+  const packageDir = path.join(projectDir, 'vendor', 'testvendor', 'test-package');
+  expect(fs.existsSync(packageDir)).toEqual(false);
+});
+
+tap.postTask('cleanup composer cli tests', async () => {
+  // Stop server
+  if (server) {
+    await new Promise<void>((resolve) => {
+      server.close(() => resolve());
+    });
+  }
+
+  // Cleanup test directory
+  if (testDir) {
+    cleanupTestDir(testDir);
+  }
+
+  // Destroy registry
+  if (registry) {
+    registry.destroy();
+  }
+});
+
+export default tap.start();

test/test.maven.nativecli.node.ts

@@ -0,0 +1,490 @@
+/**
+ * Native Maven CLI Testing
+ * Tests the Maven registry implementation using the actual mvn CLI
+ */
+
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import { tapNodeTools } from '@git.zone/tstest/tapbundle_serverside';
+import { SmartRegistry } from '../ts/index.js';
+import { createTestRegistry, createTestTokens, createTestPom, createTestJar } from './helpers/registry.js';
+import type { IRequestContext, IResponse } from '../ts/core/interfaces.core.js';
+import * as http from 'http';
+import * as url from 'url';
+import * as fs from 'fs';
+import * as path from 'path';
+
+// Test context
+let registry: SmartRegistry;
+let server: http.Server;
+let registryUrl: string;
+let registryPort: number;
+let mavenToken: string;
+let testDir: string;
+let m2Dir: string;
+
+/**
+ * Create HTTP server wrapper around SmartRegistry
+ */
+async function createHttpServer(
+  registryInstance: SmartRegistry,
+  port: number
+): Promise<{ server: http.Server; url: string }> {
+  return new Promise((resolve, reject) => {
+    const httpServer = http.createServer(async (req, res) => {
+      try {
+        // Parse request
+        const parsedUrl = url.parse(req.url || '', true);
+        const pathname = parsedUrl.pathname || '/';
+        const query = parsedUrl.query;
+
+        // Read body
+        const chunks: Buffer[] = [];
+        for await (const chunk of req) {
+          chunks.push(chunk);
+        }
+        const bodyBuffer = Buffer.concat(chunks);
+
+        // Parse body based on content type
+        let body: any;
+        if (bodyBuffer.length > 0) {
+          const contentType = req.headers['content-type'] || '';
+          if (contentType.includes('application/json')) {
+            try {
+              body = JSON.parse(bodyBuffer.toString('utf-8'));
+            } catch (error) {
+              body = bodyBuffer;
+            }
+          } else {
+            body = bodyBuffer;
+          }
+        }
+
+        // Convert to IRequestContext
+        const context: IRequestContext = {
+          method: req.method || 'GET',
+          path: pathname,
+          headers: req.headers as Record<string, string>,
+          query: query as Record<string, string>,
+          body: body,
+        };
+
+        // Handle request
+        const response: IResponse = await registryInstance.handleRequest(context);
+
+        // Convert IResponse to HTTP response
+        res.statusCode = response.status;
+
+        // Set headers
+        for (const [key, value] of Object.entries(response.headers || {})) {
+          res.setHeader(key, value);
+        }
+
+        // Send body
+        if (response.body) {
+          if (Buffer.isBuffer(response.body)) {
+            res.end(response.body);
+          } else if (typeof response.body === 'string') {
+            res.end(response.body);
+          } else {
+            res.setHeader('Content-Type', 'application/json');
+            res.end(JSON.stringify(response.body));
+          }
+        } else {
+          res.end();
+        }
+      } catch (error) {
+        console.error('Server error:', error);
+        res.statusCode = 500;
+        res.setHeader('Content-Type', 'application/json');
+        res.end(JSON.stringify({ error: 'INTERNAL_ERROR', message: String(error) }));
+      }
+    });
+
+    httpServer.listen(port, () => {
+      const serverUrl = `http://localhost:${port}`;
+      resolve({ server: httpServer, url: serverUrl });
+    });
+
+    httpServer.on('error', reject);
+  });
+}
+
+/**
+ * Setup Maven settings.xml for authentication
+ */
+function setupMavenSettings(
+  token: string,
+  m2DirArg: string,
+  serverUrl: string
+): string {
+  fs.mkdirSync(m2DirArg, { recursive: true });
+
+  const settingsXml = `<?xml version="1.0" encoding="UTF-8"?>
+<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
+          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
+          http://maven.apache.org/xsd/settings-1.0.0.xsd">
+  <servers>
+    <server>
+      <id>test-registry</id>
+      <username>testuser</username>
+      <password>${token}</password>
+    </server>
+  </servers>
+  <profiles>
+    <profile>
+      <id>test-registry</id>
+      <repositories>
+        <repository>
+          <id>test-registry</id>
+          <url>${serverUrl}/maven</url>
+          <releases>
+            <enabled>true</enabled>
+          </releases>
+          <snapshots>
+            <enabled>true</enabled>
+          </snapshots>
+        </repository>
+      </repositories>
+    </profile>
+  </profiles>
+  <activeProfiles>
+    <activeProfile>test-registry</activeProfile>
+  </activeProfiles>
+</settings>
+`;
+
+  const settingsPath = path.join(m2DirArg, 'settings.xml');
+  fs.writeFileSync(settingsPath, settingsXml, 'utf-8');
+
+  return settingsPath;
+}
+
+/**
+ * Create a minimal Maven project for testing
+ */
+function createMavenProject(
+  projectDir: string,
+  groupId: string,
+  artifactId: string,
+  version: string,
+  registryUrl: string
+): void {
+  fs.mkdirSync(projectDir, { recursive: true });
+
+  const pomXml = `<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
+         http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>${groupId}</groupId>
+  <artifactId>${artifactId}</artifactId>
+  <version>${version}</version>
+  <packaging>jar</packaging>
+  <name>${artifactId}</name>
+  <description>Test Maven project for SmartRegistry CLI tests</description>
+
+  <distributionManagement>
+    <repository>
+      <id>test-registry</id>
+      <url>${registryUrl}/maven</url>
+    </repository>
+    <snapshotRepository>
+      <id>test-registry</id>
+      <url>${registryUrl}/maven</url>
+    </snapshotRepository>
+  </distributionManagement>
+
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-compiler-plugin</artifactId>
+        <version>3.8.1</version>
+        <configuration>
+          <source>1.8</source>
+          <target>1.8</target>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
+</project>
+`;
+
+  fs.writeFileSync(path.join(projectDir, 'pom.xml'), pomXml, 'utf-8');
+
+  // Create minimal Java source
+  const srcDir = path.join(projectDir, 'src', 'main', 'java', 'com', 'test');
+  fs.mkdirSync(srcDir, { recursive: true });
+
+  const javaSource = `package com.test;
+
+public class Main {
+    public static void main(String[] args) {
+        System.out.println("Hello from SmartRegistry test!");
+    }
+}
+`;
+  fs.writeFileSync(path.join(srcDir, 'Main.java'), javaSource, 'utf-8');
+}
+
+/**
+ * Run Maven command with custom settings
+ */
+async function runMavenCommand(
+  command: string,
+  cwd: string
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  const settingsPath = path.join(m2Dir, 'settings.xml');
+  const fullCommand = `cd "${cwd}" && mvn -s "${settingsPath}" ${command}`;
+
+  try {
+    const result = await tapNodeTools.runCommand(fullCommand);
+    return {
+      stdout: result.stdout || '',
+      stderr: result.stderr || '',
+      exitCode: result.exitCode || 0,
+    };
+  } catch (error: any) {
+    return {
+      stdout: error.stdout || '',
+      stderr: error.stderr || String(error),
+      exitCode: error.exitCode || 1,
+    };
+  }
+}
+
+/**
+ * Cleanup test directory
+ */
+function cleanupTestDir(dir: string): void {
+  if (fs.existsSync(dir)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+// ========================================================================
+// TESTS
+// ========================================================================
+
+tap.test('Maven CLI: should verify mvn is installed', async () => {
+  try {
+    const result = await tapNodeTools.runCommand('mvn -version');
+    console.log('Maven version output:', result.stdout.substring(0, 200));
+    expect(result.exitCode).toEqual(0);
+  } catch (error) {
+    console.log('Maven CLI not available, skipping native CLI tests');
+    // Skip remaining tests if Maven is not installed
+    tap.skip.test('Maven CLI: remaining tests skipped - mvn not available');
+    return;
+  }
+});
+
+tap.test('Maven CLI: should setup registry and HTTP server', async () => {
+  // Create registry
+  registry = await createTestRegistry();
+  const tokens = await createTestTokens(registry);
+  mavenToken = tokens.mavenToken;
+
+  expect(registry).toBeInstanceOf(SmartRegistry);
+  expect(mavenToken).toBeTypeOf('string');
+
+  // Use port 37000 (avoids conflicts with other tests)
+  registryPort = 37000;
+  const serverSetup = await createHttpServer(registry, registryPort);
+  server = serverSetup.server;
+  registryUrl = serverSetup.url;
+
+  expect(server).toBeDefined();
+  expect(registryUrl).toEqual(`http://localhost:${registryPort}`);
+
+  // Setup test directory
+  testDir = path.join(process.cwd(), '.nogit', 'test-maven-cli');
+  cleanupTestDir(testDir);
+  fs.mkdirSync(testDir, { recursive: true });
+
+  // Setup .m2 directory
+  m2Dir = path.join(testDir, '.m2');
+  fs.mkdirSync(m2Dir, { recursive: true });
+
+  // Setup Maven settings
+  const settingsPath = setupMavenSettings(mavenToken, m2Dir, registryUrl);
+  expect(fs.existsSync(settingsPath)).toEqual(true);
+});
+
+tap.test('Maven CLI: should verify server is responding', async () => {
+  // Check server is up by doing a direct HTTP request
+  const response = await fetch(`${registryUrl}/maven/`);
+  expect(response.status).toBeGreaterThanOrEqual(200);
+  expect(response.status).toBeLessThan(500);
+});
+
+tap.test('Maven CLI: should deploy a JAR artifact', async () => {
+  const groupId = 'com.test';
+  const artifactId = 'test-artifact';
+  const version = '1.0.0';
+
+  const projectDir = path.join(testDir, 'test-project');
+  createMavenProject(projectDir, groupId, artifactId, version, registryUrl);
+
+  // Build and deploy
+  const result = await runMavenCommand('clean package deploy -DskipTests', projectDir);
+  console.log('mvn deploy output:', result.stdout.substring(0, 500));
+  console.log('mvn deploy stderr:', result.stderr.substring(0, 500));
+
+  expect(result.exitCode).toEqual(0);
+});
+
+tap.test('Maven CLI: should verify artifact in registry via API', async () => {
+  const groupId = 'com.test';
+  const artifactId = 'test-artifact';
+  const version = '1.0.0';
+
+  // Maven path: /maven/{groupId path}/{artifactId}/{version}/{artifactId}-{version}.jar
+  const jarPath = `/maven/com/test/${artifactId}/${version}/${artifactId}-${version}.jar`;
+  const response = await fetch(`${registryUrl}${jarPath}`, {
+    headers: { Authorization: `Bearer ${mavenToken}` },
+  });
+
+  expect(response.status).toEqual(200);
+
+  const jarData = await response.arrayBuffer();
+  expect(jarData.byteLength).toBeGreaterThan(0);
+});
+
+tap.test('Maven CLI: should verify POM in registry', async () => {
+  const groupId = 'com.test';
+  const artifactId = 'test-artifact';
+  const version = '1.0.0';
+
+  const pomPath = `/maven/com/test/${artifactId}/${version}/${artifactId}-${version}.pom`;
+  const response = await fetch(`${registryUrl}${pomPath}`, {
+    headers: { Authorization: `Bearer ${mavenToken}` },
+  });
+
+  expect(response.status).toEqual(200);
+
+  const pomContent = await response.text();
+  expect(pomContent).toContain(groupId);
+  expect(pomContent).toContain(artifactId);
+  expect(pomContent).toContain(version);
+});
+
+tap.test('Maven CLI: should verify checksums exist', async () => {
+  const artifactId = 'test-artifact';
+  const version = '1.0.0';
+
+  // Check JAR checksums
+  const basePath = `/maven/com/test/${artifactId}/${version}/${artifactId}-${version}.jar`;
+
+  // MD5
+  const md5Response = await fetch(`${registryUrl}${basePath}.md5`, {
+    headers: { Authorization: `Bearer ${mavenToken}` },
+  });
+  expect(md5Response.status).toEqual(200);
+
+  // SHA1
+  const sha1Response = await fetch(`${registryUrl}${basePath}.sha1`, {
+    headers: { Authorization: `Bearer ${mavenToken}` },
+  });
+  expect(sha1Response.status).toEqual(200);
+});
+
+tap.test('Maven CLI: should deploy second version', async () => {
+  const groupId = 'com.test';
+  const artifactId = 'test-artifact';
+  const version = '2.0.0';
+
+  const projectDir = path.join(testDir, 'test-project-v2');
+  createMavenProject(projectDir, groupId, artifactId, version, registryUrl);
+
+  const result = await runMavenCommand('clean package deploy -DskipTests', projectDir);
+  console.log('mvn deploy v2 output:', result.stdout.substring(0, 500));
+
+  expect(result.exitCode).toEqual(0);
+});
+
+tap.test('Maven CLI: should verify metadata.xml exists', async () => {
+  const artifactId = 'test-artifact';
+
+  // Maven metadata is stored at /maven/{groupId path}/{artifactId}/maven-metadata.xml
+  const metadataPath = `/maven/com/test/${artifactId}/maven-metadata.xml`;
+  const response = await fetch(`${registryUrl}${metadataPath}`, {
+    headers: { Authorization: `Bearer ${mavenToken}` },
+  });
+
+  expect(response.status).toEqual(200);
+
+  const metadataXml = await response.text();
+  expect(metadataXml).toContain(artifactId);
+  expect(metadataXml).toContain('1.0.0');
+  expect(metadataXml).toContain('2.0.0');
+});
+
+tap.test('Maven CLI: should resolve dependency from registry', async () => {
+  const groupId = 'com.consumer';
+  const artifactId = 'consumer-app';
+  const version = '1.0.0';
+
+  const projectDir = path.join(testDir, 'consumer-project');
+  fs.mkdirSync(projectDir, { recursive: true });
+
+  // Create a consumer project that depends on our test artifact
+  const pomXml = `<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
+         http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>${groupId}</groupId>
+  <artifactId>${artifactId}</artifactId>
+  <version>${version}</version>
+  <packaging>jar</packaging>
+
+  <repositories>
+    <repository>
+      <id>test-registry</id>
+      <url>${registryUrl}/maven</url>
+    </repository>
+  </repositories>
+
+  <dependencies>
+    <dependency>
+      <groupId>com.test</groupId>
+      <artifactId>test-artifact</artifactId>
+      <version>1.0.0</version>
+    </dependency>
+  </dependencies>
+</project>
+`;
+
+  fs.writeFileSync(path.join(projectDir, 'pom.xml'), pomXml, 'utf-8');
+
+  // Try to resolve dependencies
+  const result = await runMavenCommand('dependency:resolve', projectDir);
+  console.log('mvn dependency:resolve output:', result.stdout.substring(0, 500));
+
+  expect(result.exitCode).toEqual(0);
+});
+
+tap.postTask('cleanup maven cli tests', async () => {
+  // Stop server
+  if (server) {
+    await new Promise<void>((resolve) => {
+      server.close(() => resolve());
+    });
+  }
+
+  // Cleanup test directory
+  if (testDir) {
+    cleanupTestDir(testDir);
+  }
+
+  // Destroy registry
+  if (registry) {
+    registry.destroy();
+  }
+});
+
+export default tap.start();

test/test.oci.nativecli.node.ts

@@ -0,0 +1,406 @@
+/**
+ * Native Docker CLI Testing
+ * Tests the OCI registry implementation using the actual Docker CLI
+ */
+
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import { tapNodeTools } from '@git.zone/tstest/tapbundle_serverside';
+import { SmartRegistry } from '../ts/index.js';
+import type { IRequestContext, IResponse, IRegistryConfig } from '../ts/core/interfaces.core.js';
+import * as qenv from '@push.rocks/qenv';
+import * as http from 'http';
+import * as url from 'url';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const testQenv = new qenv.Qenv('./', './.nogit');
+
+/**
+ * Create a test registry with local token endpoint realm
+ */
+async function createDockerTestRegistry(port: number): Promise<SmartRegistry> {
+  const s3AccessKey = await testQenv.getEnvVarOnDemand('S3_ACCESSKEY');
+  const s3SecretKey = await testQenv.getEnvVarOnDemand('S3_SECRETKEY');
+  const s3Endpoint = await testQenv.getEnvVarOnDemand('S3_ENDPOINT');
+  const s3Port = await testQenv.getEnvVarOnDemand('S3_PORT');
+
+  const config: IRegistryConfig = {
+    storage: {
+      accessKey: s3AccessKey || 'minioadmin',
+      accessSecret: s3SecretKey || 'minioadmin',
+      endpoint: s3Endpoint || 'localhost',
+      port: parseInt(s3Port || '9000', 10),
+      useSsl: false,
+      region: 'us-east-1',
+      bucketName: 'test-registry',
+    },
+    auth: {
+      jwtSecret: 'test-secret-key',
+      tokenStore: 'memory',
+      npmTokens: {
+        enabled: true,
+      },
+      ociTokens: {
+        enabled: true,
+        realm: `http://localhost:${port}/v2/token`,
+        service: 'test-registry',
+      },
+    },
+    oci: {
+      enabled: true,
+      basePath: '/oci',
+    },
+  };
+
+  const reg = new SmartRegistry(config);
+  await reg.init();
+  return reg;
+}
+
+/**
+ * Create test tokens for the registry
+ */
+async function createDockerTestTokens(reg: SmartRegistry) {
+  const authManager = reg.getAuthManager();
+
+  const userId = await authManager.authenticate({
+    username: 'testuser',
+    password: 'testpass',
+  });
+
+  if (!userId) {
+    throw new Error('Failed to authenticate test user');
+  }
+
+  // Create OCI token with full access
+  const ociToken = await authManager.createOciToken(
+    userId,
+    ['oci:repository:*:*'],
+    3600
+  );
+
+  return { ociToken, userId };
+}
+
+// Test context
+let registry: SmartRegistry;
+let server: http.Server;
+let registryUrl: string;
+let registryPort: number;
+let ociToken: string;
+let testDir: string;
+let testImageName: string;
+
+/**
+ * Create HTTP server wrapper around SmartRegistry
+ * CRITICAL: Always passes rawBody for content-addressable operations (OCI manifests/blobs)
+ *
+ * Docker expects registry at /v2/ but SmartRegistry serves at /oci/v2/
+ * This wrapper rewrites paths for Docker compatibility
+ *
+ * Also implements a simple /v2/token endpoint for Docker Bearer auth flow
+ */
+async function createHttpServer(
+  registryInstance: SmartRegistry,
+  port: number,
+  tokenForAuth: string
+): Promise<{ server: http.Server; url: string }> {
+  return new Promise((resolve, reject) => {
+    const httpServer = http.createServer(async (req, res) => {
+      try {
+        // Parse request
+        const parsedUrl = url.parse(req.url || '', true);
+        let pathname = parsedUrl.pathname || '/';
+        const query = parsedUrl.query;
+
+        // Handle token endpoint for Docker Bearer auth
+        if (pathname === '/v2/token' || pathname === '/token') {
+          console.log(`[Token Request] ${req.method} ${req.url}`);
+          res.statusCode = 200;
+          res.setHeader('Content-Type', 'application/json');
+          res.end(JSON.stringify({
+            token: tokenForAuth,
+            access_token: tokenForAuth,
+            expires_in: 3600,
+            issued_at: new Date().toISOString(),
+          }));
+          return;
+        }
+
+        // Log all requests for debugging
+        console.log(`[Registry] ${req.method} ${pathname}`);
+
+        // Docker expects /v2/ but SmartRegistry serves at /oci/v2/
+        if (pathname.startsWith('/v2')) {
+          pathname = '/oci' + pathname;
+        }
+
+        // Read raw body - ALWAYS preserve exact bytes for OCI
+        const chunks: Buffer[] = [];
+        for await (const chunk of req) {
+          chunks.push(chunk);
+        }
+        const bodyBuffer = Buffer.concat(chunks);
+
+        // Parse body based on content type (for non-OCI protocols that need it)
+        let parsedBody: any;
+        if (bodyBuffer.length > 0) {
+          const contentType = req.headers['content-type'] || '';
+          if (contentType.includes('application/json')) {
+            try {
+              parsedBody = JSON.parse(bodyBuffer.toString('utf-8'));
+            } catch (error) {
+              parsedBody = bodyBuffer;
+            }
+          } else {
+            parsedBody = bodyBuffer;
+          }
+        }
+
+        // Convert to IRequestContext
+        const context: IRequestContext = {
+          method: req.method || 'GET',
+          path: pathname,
+          headers: req.headers as Record<string, string>,
+          query: query as Record<string, string>,
+          body: parsedBody,
+          rawBody: bodyBuffer,
+        };
+
+        // Handle request
+        const response: IResponse = await registryInstance.handleRequest(context);
+        console.log(`[Registry] Response: ${response.status} for ${pathname}`);
+
+        // Convert IResponse to HTTP response
+        res.statusCode = response.status;
+
+        // Set headers
+        for (const [key, value] of Object.entries(response.headers || {})) {
+          res.setHeader(key, value);
+        }
+
+        // Send body
+        if (response.body) {
+          if (Buffer.isBuffer(response.body)) {
+            res.end(response.body);
+          } else if (typeof response.body === 'string') {
+            res.end(response.body);
+          } else {
+            res.setHeader('Content-Type', 'application/json');
+            res.end(JSON.stringify(response.body));
+          }
+        } else {
+          res.end();
+        }
+      } catch (error) {
+        console.error('Server error:', error);
+        res.statusCode = 500;
+        res.setHeader('Content-Type', 'application/json');
+        res.end(JSON.stringify({ error: 'INTERNAL_ERROR', message: String(error) }));
+      }
+    });
+
+    httpServer.listen(port, '0.0.0.0', () => {
+      const serverUrl = `http://localhost:${port}`;
+      resolve({ server: httpServer, url: serverUrl });
+    });
+
+    httpServer.on('error', reject);
+  });
+}
+
+/**
+ * Create a test Dockerfile
+ */
+function createTestDockerfile(targetDir: string, content?: string): string {
+  const dockerfilePath = path.join(targetDir, 'Dockerfile');
+  const dockerfileContent = content || `FROM alpine:latest
+RUN echo "Hello from SmartRegistry test" > /hello.txt
+CMD ["cat", "/hello.txt"]
+`;
+  fs.writeFileSync(dockerfilePath, dockerfileContent, 'utf-8');
+  return dockerfilePath;
+}
+
+/**
+ * Run Docker command using the main Docker daemon (not rootless)
+ * Rootless Docker runs in its own network namespace and can't access host localhost
+ *
+ * IMPORTANT: DOCKER_HOST env var overrides --context flag, so we must unset it
+ * and explicitly set the socket path to use the main Docker daemon.
+ */
+async function runDockerCommand(
+  command: string,
+  cwd?: string
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  // First unset DOCKER_HOST then set it to main Docker daemon socket
+  // Using both unset and export ensures we override any inherited env var
+  const dockerCommand = `unset DOCKER_HOST && export DOCKER_HOST=unix:///var/run/docker.sock && ${command}`;
+  const fullCommand = cwd ? `cd "${cwd}" && ${dockerCommand}` : dockerCommand;
+
+  try {
+    const result = await tapNodeTools.runCommand(fullCommand);
+    return {
+      stdout: result.stdout || '',
+      stderr: result.stderr || '',
+      exitCode: result.exitCode || 0,
+    };
+  } catch (error: any) {
+    return {
+      stdout: error.stdout || '',
+      stderr: error.stderr || String(error),
+      exitCode: error.exitCode || 1,
+    };
+  }
+}
+
+/**
+ * Cleanup test directory
+ */
+function cleanupTestDir(dir: string): void {
+  if (fs.existsSync(dir)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Cleanup Docker resources
+ */
+async function cleanupDocker(imageName: string): Promise<void> {
+  await runDockerCommand(`docker rmi ${imageName} 2>/dev/null || true`);
+  await runDockerCommand(`docker rmi ${imageName}:v1 2>/dev/null || true`);
+  await runDockerCommand(`docker rmi ${imageName}:v2 2>/dev/null || true`);
+}
+
+// ========================================================================
+// TESTS
+// ========================================================================
+
+tap.test('Docker CLI: should verify Docker is installed', async () => {
+  const result = await runDockerCommand('docker version');
+  console.log('Docker version output:', result.stdout.substring(0, 200));
+  expect(result.exitCode).toEqual(0);
+});
+
+tap.test('Docker CLI: should setup registry and HTTP server', async () => {
+  // Use localhost - Docker allows HTTP for localhost without any special config
+  registryPort = 15000 + Math.floor(Math.random() * 1000);
+  console.log(`Using port: ${registryPort}`);
+
+  registry = await createDockerTestRegistry(registryPort);
+  const tokens = await createDockerTestTokens(registry);
+  ociToken = tokens.ociToken;
+
+  expect(registry).toBeInstanceOf(SmartRegistry);
+  expect(ociToken).toBeTypeOf('string');
+
+  const serverSetup = await createHttpServer(registry, registryPort, ociToken);
+  server = serverSetup.server;
+  registryUrl = serverSetup.url;
+
+  expect(server).toBeDefined();
+  console.log(`Registry server started at ${registryUrl}`);
+
+  // Setup test directory
+  testDir = path.join(process.cwd(), '.nogit', 'test-docker-cli');
+  cleanupTestDir(testDir);
+  fs.mkdirSync(testDir, { recursive: true });
+
+  testImageName = `localhost:${registryPort}/test-image`;
+});
+
+tap.test('Docker CLI: should verify server is responding', async () => {
+  // Give the server a moment to fully initialize
+  await new Promise(resolve => setTimeout(resolve, 500));
+
+  const response = await fetch(`${registryUrl}/oci/v2/`);
+  expect(response.status).toEqual(200);
+  console.log('OCI v2 response:', await response.json());
+});
+
+tap.test('Docker CLI: should login to registry', async () => {
+  const result = await runDockerCommand(
+    `echo "${ociToken}" | docker login localhost:${registryPort} -u testuser --password-stdin`
+  );
+  console.log('docker login output:', result.stdout);
+  console.log('docker login stderr:', result.stderr);
+
+  const combinedOutput = result.stdout + result.stderr;
+  expect(combinedOutput).toContain('Login Succeeded');
+});
+
+tap.test('Docker CLI: should build test image', async () => {
+  createTestDockerfile(testDir);
+
+  const result = await runDockerCommand(
+    `docker build -t ${testImageName}:v1 .`,
+    testDir
+  );
+  console.log('docker build output:', result.stdout.substring(0, 500));
+
+  expect(result.exitCode).toEqual(0);
+});
+
+tap.test('Docker CLI: should push image to registry', async () => {
+  // This is the critical test - if the digest mismatch bug is fixed,
+  // this should succeed. The manifest bytes must be preserved exactly.
+  const result = await runDockerCommand(`docker push ${testImageName}:v1`);
+  console.log('docker push output:', result.stdout);
+  console.log('docker push stderr:', result.stderr);
+
+  expect(result.exitCode).toEqual(0);
+});
+
+tap.test('Docker CLI: should verify manifest in registry via API', async () => {
+  const response = await fetch(`${registryUrl}/oci/v2/test-image/tags/list`, {
+    headers: { Authorization: `Bearer ${ociToken}` },
+  });
+
+  expect(response.status).toEqual(200);
+
+  const tagList = await response.json();
+  console.log('Tags list:', tagList);
+
+  expect(tagList.name).toEqual('test-image');
+  expect(tagList.tags).toContain('v1');
+});
+
+tap.test('Docker CLI: should pull pushed image', async () => {
+  // First remove the local image
+  await runDockerCommand(`docker rmi ${testImageName}:v1 || true`);
+
+  const result = await runDockerCommand(`docker pull ${testImageName}:v1`);
+  console.log('docker pull output:', result.stdout);
+
+  expect(result.exitCode).toEqual(0);
+});
+
+tap.test('Docker CLI: should run pulled image', async () => {
+  const result = await runDockerCommand(`docker run --rm ${testImageName}:v1`);
+  console.log('docker run output:', result.stdout);
+
+  expect(result.exitCode).toEqual(0);
+  expect(result.stdout).toContain('Hello from SmartRegistry test');
+});
+
+tap.postTask('cleanup docker cli tests', async () => {
+  if (testImageName) {
+    await cleanupDocker(testImageName);
+  }
+
+  if (server) {
+    await new Promise<void>((resolve) => {
+      server.close(() => resolve());
+    });
+  }
+
+  if (testDir) {
+    cleanupTestDir(testDir);
+  }
+
+  if (registry) {
+    registry.destroy();
+  }
+});
+
+export default tap.start();

test/test.pypi.nativecli.node.ts

@@ -0,0 +1,522 @@
+/**
+ * Native PyPI CLI Testing
+ * Tests the PyPI registry implementation using pip and twine CLI tools
+ */
+
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import { tapNodeTools } from '@git.zone/tstest/tapbundle_serverside';
+import { SmartRegistry } from '../ts/index.js';
+import { createTestRegistry, createTestTokens, createPythonWheel, createPythonSdist } from './helpers/registry.js';
+import type { IRequestContext, IResponse } from '../ts/core/interfaces.core.js';
+import * as http from 'http';
+import * as url from 'url';
+import * as fs from 'fs';
+import * as path from 'path';
+
+// Test context
+let registry: SmartRegistry;
+let server: http.Server;
+let registryUrl: string;
+let registryPort: number;
+let pypiToken: string;
+let testDir: string;
+let pipHome: string;
+let hasPip = false;
+let hasTwine = false;
+
+/**
+ * Create HTTP server wrapper around SmartRegistry
+ */
+async function createHttpServer(
+  registryInstance: SmartRegistry,
+  port: number
+): Promise<{ server: http.Server; url: string }> {
+  return new Promise((resolve, reject) => {
+    const httpServer = http.createServer(async (req, res) => {
+      try {
+        // Parse request
+        const parsedUrl = url.parse(req.url || '', true);
+        const pathname = parsedUrl.pathname || '/';
+        const query = parsedUrl.query;
+
+        // Read body
+        const chunks: Buffer[] = [];
+        for await (const chunk of req) {
+          chunks.push(chunk);
+        }
+        const bodyBuffer = Buffer.concat(chunks);
+
+        // Parse body based on content type
+        let body: any;
+        if (bodyBuffer.length > 0) {
+          const contentType = req.headers['content-type'] || '';
+          if (contentType.includes('application/json')) {
+            try {
+              body = JSON.parse(bodyBuffer.toString('utf-8'));
+            } catch (error) {
+              body = bodyBuffer;
+            }
+          } else if (contentType.includes('multipart/form-data')) {
+            // For multipart, pass raw buffer
+            body = bodyBuffer;
+          } else {
+            body = bodyBuffer;
+          }
+        }
+
+        // Convert to IRequestContext
+        const context: IRequestContext = {
+          method: req.method || 'GET',
+          path: pathname,
+          headers: req.headers as Record<string, string>,
+          query: query as Record<string, string>,
+          body: body,
+          rawBody: bodyBuffer,
+        };
+
+        // Handle request
+        const response: IResponse = await registryInstance.handleRequest(context);
+
+        // Convert IResponse to HTTP response
+        res.statusCode = response.status;
+
+        // Set headers
+        for (const [key, value] of Object.entries(response.headers || {})) {
+          res.setHeader(key, value);
+        }
+
+        // Send body
+        if (response.body) {
+          if (Buffer.isBuffer(response.body)) {
+            res.end(response.body);
+          } else if (typeof response.body === 'string') {
+            res.end(response.body);
+          } else {
+            res.setHeader('Content-Type', 'application/json');
+            res.end(JSON.stringify(response.body));
+          }
+        } else {
+          res.end();
+        }
+      } catch (error) {
+        console.error('Server error:', error);
+        res.statusCode = 500;
+        res.setHeader('Content-Type', 'application/json');
+        res.end(JSON.stringify({ error: 'INTERNAL_ERROR', message: String(error) }));
+      }
+    });
+
+    httpServer.listen(port, () => {
+      const serverUrl = `http://localhost:${port}`;
+      resolve({ server: httpServer, url: serverUrl });
+    });
+
+    httpServer.on('error', reject);
+  });
+}
+
+/**
+ * Setup .pypirc for twine authentication
+ */
+function setupPypirc(
+  token: string,
+  pipHomeArg: string,
+  serverUrl: string
+): string {
+  fs.mkdirSync(pipHomeArg, { recursive: true });
+
+  const pypircContent = `[distutils]
+index-servers = testpypi
+
+[testpypi]
+repository = ${serverUrl}/pypi
+username = testuser
+password = ${token}
+`;
+
+  const pypircPath = path.join(pipHomeArg, '.pypirc');
+  fs.writeFileSync(pypircPath, pypircContent, 'utf-8');
+
+  // Set restrictive permissions
+  fs.chmodSync(pypircPath, 0o600);
+
+  return pypircPath;
+}
+
+/**
+ * Setup pip.conf for pip to use our registry
+ */
+function setupPipConf(
+  token: string,
+  pipHomeArg: string,
+  serverUrl: string,
+  port: number
+): string {
+  fs.mkdirSync(pipHomeArg, { recursive: true });
+
+  // pip.conf with authentication
+  const pipConfContent = `[global]
+index-url = ${serverUrl}/pypi/simple/
+trusted-host = localhost
+extra-index-url = https://pypi.org/simple/
+`;
+
+  const pipDir = path.join(pipHomeArg, 'pip');
+  fs.mkdirSync(pipDir, { recursive: true });
+
+  const pipConfPath = path.join(pipDir, 'pip.conf');
+  fs.writeFileSync(pipConfPath, pipConfContent, 'utf-8');
+
+  return pipConfPath;
+}
+
+/**
+ * Create a test Python package wheel file
+ */
+async function createTestWheelFile(
+  packageName: string,
+  version: string,
+  targetDir: string
+): Promise<string> {
+  const wheelData = await createPythonWheel(packageName, version);
+  const normalizedName = packageName.replace(/-/g, '_');
+  const wheelFilename = `${normalizedName}-${version}-py3-none-any.whl`;
+  const wheelPath = path.join(targetDir, wheelFilename);
+
+  fs.writeFileSync(wheelPath, wheelData);
+
+  return wheelPath;
+}
+
+/**
+ * Create a test Python package sdist file
+ */
+async function createTestSdistFile(
+  packageName: string,
+  version: string,
+  targetDir: string
+): Promise<string> {
+  const sdistData = await createPythonSdist(packageName, version);
+  const sdistFilename = `${packageName}-${version}.tar.gz`;
+  const sdistPath = path.join(targetDir, sdistFilename);
+
+  fs.writeFileSync(sdistPath, sdistData);
+
+  return sdistPath;
+}
+
+/**
+ * Run pip command with custom config
+ */
+async function runPipCommand(
+  command: string,
+  cwd: string
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  const pipConfDir = path.join(pipHome, 'pip');
+  const fullCommand = `cd "${cwd}" && PIP_CONFIG_FILE="${path.join(pipConfDir, 'pip.conf')}" pip ${command}`;
+
+  try {
+    const result = await tapNodeTools.runCommand(fullCommand);
+    return {
+      stdout: result.stdout || '',
+      stderr: result.stderr || '',
+      exitCode: result.exitCode || 0,
+    };
+  } catch (error: any) {
+    return {
+      stdout: error.stdout || '',
+      stderr: error.stderr || String(error),
+      exitCode: error.exitCode || 1,
+    };
+  }
+}
+
+/**
+ * Run twine command with custom config
+ */
+async function runTwineCommand(
+  command: string,
+  cwd: string
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  const pypircPath = path.join(pipHome, '.pypirc');
+  const fullCommand = `cd "${cwd}" && twine ${command} --config-file "${pypircPath}"`;
+
+  try {
+    const result = await tapNodeTools.runCommand(fullCommand);
+    return {
+      stdout: result.stdout || '',
+      stderr: result.stderr || '',
+      exitCode: result.exitCode || 0,
+    };
+  } catch (error: any) {
+    return {
+      stdout: error.stdout || '',
+      stderr: error.stderr || String(error),
+      exitCode: error.exitCode || 1,
+    };
+  }
+}
+
+/**
+ * Cleanup test directory
+ */
+function cleanupTestDir(dir: string): void {
+  if (fs.existsSync(dir)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+// ========================================================================
+// TESTS
+// ========================================================================
+
+tap.test('PyPI CLI: should verify pip is installed', async () => {
+  try {
+    const result = await tapNodeTools.runCommand('pip --version');
+    console.log('pip version output:', result.stdout.substring(0, 200));
+    hasPip = result.exitCode === 0;
+    expect(result.exitCode).toEqual(0);
+  } catch (error) {
+    console.log('pip CLI not available');
+  }
+});
+
+tap.test('PyPI CLI: should verify twine is installed', async () => {
+  try {
+    const result = await tapNodeTools.runCommand('twine --version');
+    console.log('twine version output:', result.stdout.substring(0, 200));
+    hasTwine = result.exitCode === 0;
+    expect(result.exitCode).toEqual(0);
+  } catch (error) {
+    console.log('twine CLI not available');
+  }
+
+  if (!hasPip && !hasTwine) {
+    console.log('Neither pip nor twine available, skipping native CLI tests');
+    tap.skip.test('PyPI CLI: remaining tests skipped - no CLI tools available');
+    return;
+  }
+});
+
+tap.test('PyPI CLI: should setup registry and HTTP server', async () => {
+  // Create registry
+  registry = await createTestRegistry();
+  const tokens = await createTestTokens(registry);
+  pypiToken = tokens.pypiToken;
+
+  expect(registry).toBeInstanceOf(SmartRegistry);
+  expect(pypiToken).toBeTypeOf('string');
+
+  // Use port 39000 (avoids conflicts with other tests)
+  registryPort = 39000;
+  const serverSetup = await createHttpServer(registry, registryPort);
+  server = serverSetup.server;
+  registryUrl = serverSetup.url;
+
+  expect(server).toBeDefined();
+  expect(registryUrl).toEqual(`http://localhost:${registryPort}`);
+
+  // Setup test directory
+  testDir = path.join(process.cwd(), '.nogit', 'test-pypi-cli');
+  cleanupTestDir(testDir);
+  fs.mkdirSync(testDir, { recursive: true });
+
+  // Setup pip/pypi home directory
+  pipHome = path.join(testDir, '.pip');
+  fs.mkdirSync(pipHome, { recursive: true });
+
+  // Setup .pypirc for twine
+  const pypircPath = setupPypirc(pypiToken, pipHome, registryUrl);
+  expect(fs.existsSync(pypircPath)).toEqual(true);
+
+  // Setup pip.conf
+  const pipConfPath = setupPipConf(pypiToken, pipHome, registryUrl, registryPort);
+  expect(fs.existsSync(pipConfPath)).toEqual(true);
+});
+
+tap.test('PyPI CLI: should verify server is responding', async () => {
+  // Check server is up by doing a direct HTTP request to simple index
+  const response = await fetch(`${registryUrl}/pypi/simple/`);
+  expect(response.status).toBeGreaterThanOrEqual(200);
+  expect(response.status).toBeLessThan(500);
+});
+
+tap.test('PyPI CLI: should upload wheel with twine', async () => {
+  if (!hasTwine) {
+    console.log('Skipping twine test - twine not available');
+    return;
+  }
+
+  const packageName = 'test-pypi-pkg';
+  const version = '1.0.0';
+  const wheelPath = await createTestWheelFile(packageName, version, testDir);
+
+  expect(fs.existsSync(wheelPath)).toEqual(true);
+
+  const result = await runTwineCommand(
+    `upload --repository testpypi "${wheelPath}"`,
+    testDir
+  );
+  console.log('twine upload output:', result.stdout);
+  console.log('twine upload stderr:', result.stderr);
+
+  expect(result.exitCode).toEqual(0);
+});
+
+tap.test('PyPI CLI: should verify package in simple index', async () => {
+  if (!hasTwine) {
+    console.log('Skipping - twine not available');
+    return;
+  }
+
+  const packageName = 'test-pypi-pkg';
+
+  const response = await fetch(`${registryUrl}/pypi/simple/${packageName}/`);
+  expect(response.status).toEqual(200);
+
+  const html = await response.text();
+  expect(html).toContain('1.0.0');
+});
+
+tap.test('PyPI CLI: should upload sdist with twine', async () => {
+  if (!hasTwine) {
+    console.log('Skipping twine test - twine not available');
+    return;
+  }
+
+  const packageName = 'test-pypi-pkg';
+  const version = '1.1.0';
+  const sdistPath = await createTestSdistFile(packageName, version, testDir);
+
+  expect(fs.existsSync(sdistPath)).toEqual(true);
+
+  const result = await runTwineCommand(
+    `upload --repository testpypi "${sdistPath}"`,
+    testDir
+  );
+  console.log('twine upload sdist output:', result.stdout);
+  console.log('twine upload sdist stderr:', result.stderr);
+
+  expect(result.exitCode).toEqual(0);
+});
+
+tap.test('PyPI CLI: should list all versions in simple index', async () => {
+  if (!hasTwine) {
+    console.log('Skipping - twine not available');
+    return;
+  }
+
+  const packageName = 'test-pypi-pkg';
+
+  const response = await fetch(`${registryUrl}/pypi/simple/${packageName}/`);
+  expect(response.status).toEqual(200);
+
+  const html = await response.text();
+  expect(html).toContain('1.0.0');
+  expect(html).toContain('1.1.0');
+});
+
+tap.test('PyPI CLI: should get JSON metadata', async () => {
+  if (!hasTwine) {
+    console.log('Skipping - twine not available');
+    return;
+  }
+
+  const packageName = 'test-pypi-pkg';
+
+  const response = await fetch(`${registryUrl}/pypi/pypi/${packageName}/json`);
+  expect(response.status).toEqual(200);
+
+  const metadata = await response.json();
+  expect(metadata.info).toBeDefined();
+  expect(metadata.info.name).toEqual(packageName);
+  expect(metadata.releases).toBeDefined();
+  expect(metadata.releases['1.0.0']).toBeDefined();
+});
+
+tap.test('PyPI CLI: should download package with pip', async () => {
+  if (!hasPip || !hasTwine) {
+    console.log('Skipping pip download test - pip or twine not available');
+    return;
+  }
+
+  const downloadDir = path.join(testDir, 'downloads');
+  fs.mkdirSync(downloadDir, { recursive: true });
+
+  // Download (not install) the package
+  const result = await runPipCommand(
+    `download test-pypi-pkg==1.0.0 --dest "${downloadDir}" --no-deps`,
+    testDir
+  );
+  console.log('pip download output:', result.stdout);
+  console.log('pip download stderr:', result.stderr);
+
+  // pip download may fail if the package doesn't meet pip's requirements
+  // Just check it doesn't crash
+  expect(result.exitCode).toBeLessThanOrEqual(1);
+});
+
+tap.test('PyPI CLI: should search for packages via API', async () => {
+  const packageName = 'test-pypi-pkg';
+
+  // Use the JSON API to search/list
+  const response = await fetch(`${registryUrl}/pypi/pypi/${packageName}/json`);
+  expect(response.status).toEqual(200);
+
+  const metadata = await response.json();
+  expect(metadata.info.name).toEqual(packageName);
+});
+
+tap.test('PyPI CLI: should fail upload without auth', async () => {
+  if (!hasTwine) {
+    console.log('Skipping twine test - twine not available');
+    return;
+  }
+
+  const packageName = 'unauth-pkg';
+  const version = '1.0.0';
+  const wheelPath = await createTestWheelFile(packageName, version, testDir);
+
+  // Create a pypirc without proper credentials
+  const badPypircPath = path.join(testDir, '.bad-pypirc');
+  fs.writeFileSync(badPypircPath, `[distutils]
+index-servers = badpypi
+
+[badpypi]
+repository = ${registryUrl}/pypi
+username = baduser
+password = badtoken
+`, 'utf-8');
+
+  const fullCommand = `cd "${testDir}" && twine upload --repository badpypi "${wheelPath}" --config-file "${badPypircPath}"`;
+
+  try {
+    const result = await tapNodeTools.runCommand(fullCommand);
+    // Should fail
+    expect(result.exitCode).not.toEqual(0);
+  } catch (error: any) {
+    // Expected to fail
+    expect(error.exitCode || 1).not.toEqual(0);
+  }
+});
+
+tap.postTask('cleanup pypi cli tests', async () => {
+  // Stop server
+  if (server) {
+    await new Promise<void>((resolve) => {
+      server.close(() => resolve());
+    });
+  }
+
+  // Cleanup test directory
+  if (testDir) {
+    cleanupTestDir(testDir);
+  }
+
+  // Destroy registry
+  if (registry) {
+    registry.destroy();
+  }
+});
+
+export default tap.start();

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartregistry',
-  version: '2.1.2',
+  version: '2.2.2',
   description: 'A composable TypeScript library implementing OCI, NPM, Maven, Cargo, Composer, PyPI, and RubyGems registries for building unified container and package registries'
 }

ts/composer/classes.composerregistry.ts

@@ -7,6 +7,7 @@ import { BaseRegistry } from '../core/classes.baseregistry.js';
 import type { RegistryStorage } from '../core/classes.registrystorage.js';
 import type { AuthManager } from '../core/classes.authmanager.js';
 import type { IRequestContext, IResponse, IAuthToken } from '../core/interfaces.core.js';
+import { isBinaryData, toBuffer } from '../core/helpers.buffer.js';
 import type {
   IComposerPackage,
   IComposerPackageMetadata,
@@ -255,7 +256,7 @@ export class ComposerRegistry extends BaseRegistry {
       };
     }
 
-    if (!body || !Buffer.isBuffer(body)) {
+    if (!body || !isBinaryData(body)) {
       return {
         status: 400,
         headers: {},
@@ -263,8 +264,11 @@ export class ComposerRegistry extends BaseRegistry {
       };
     }
 
+    // Convert to Buffer for ZIP processing
+    const zipData = toBuffer(body);
+
     // Extract and validate composer.json from ZIP
-    const composerJson = await extractComposerJsonFromZip(body);
+    const composerJson = await extractComposerJsonFromZip(zipData);
     if (!composerJson || !validateComposerJson(composerJson)) {
       return {
         status: 400,
@@ -292,13 +296,13 @@ export class ComposerRegistry extends BaseRegistry {
     }
 
     // Calculate SHA-1 hash
-    const shasum = await calculateSha1(body);
+    const shasum = await calculateSha1(zipData);
 
     // Generate reference (use version or commit hash)
     const reference = composerJson.source?.reference || version.replace(/[^a-zA-Z0-9.-]/g, '-');
 
     // Store ZIP file
-    await this.storage.putComposerPackageZip(vendorPackage, reference, body);
+    await this.storage.putComposerPackageZip(vendorPackage, reference, zipData);
 
     // Get or create metadata
     let metadata = await this.storage.getComposerPackageMetadata(vendorPackage);

ts/core/classes.authmanager.ts

@@ -52,6 +52,60 @@ export class AuthManager {
     return token;
   }
 
+  /**
+   * Generic protocol token creation (internal helper)
+   * @param userId - User ID
+   * @param protocol - Protocol type (npm, maven, composer, etc.)
+   * @param readonly - Whether the token is readonly
+   * @returns UUID token string
+   */
+  private async createProtocolToken(
+    userId: string,
+    protocol: TRegistryProtocol,
+    readonly: boolean
+  ): Promise<string> {
+    const scopes = readonly
+      ? [`${protocol}:*:*:read`]
+      : [`${protocol}:*:*:*`];
+    return this.createUuidToken(userId, protocol, scopes, readonly);
+  }
+
+  /**
+   * Generic protocol token validation (internal helper)
+   * @param token - UUID token string
+   * @param protocol - Expected protocol type
+   * @returns Auth token object or null
+   */
+  private async validateProtocolToken(
+    token: string,
+    protocol: TRegistryProtocol
+  ): Promise<IAuthToken | null> {
+    if (!this.isValidUuid(token)) {
+      return null;
+    }
+
+    const authToken = this.tokenStore.get(token);
+    if (!authToken || authToken.type !== protocol) {
+      return null;
+    }
+
+    // Check expiration if set
+    if (authToken.expiresAt && authToken.expiresAt < new Date()) {
+      this.tokenStore.delete(token);
+      return null;
+    }
+
+    return authToken;
+  }
+
+  /**
+   * Generic protocol token revocation (internal helper)
+   * @param token - UUID token string
+   */
+  private async revokeProtocolToken(token: string): Promise<void> {
+    this.tokenStore.delete(token);
+  }
+
   // ========================================================================
   // NPM AUTHENTICATION
   // ========================================================================
@@ -66,9 +120,7 @@ export class AuthManager {
     if (!this.config.npmTokens.enabled) {
       throw new Error('NPM tokens are not enabled');
     }
-
+    return this.createProtocolToken(userId, 'npm', readonly);
-    const scopes = readonly ? ['npm:*:*:read'] : ['npm:*:*:*'];
-    return this.createUuidToken(userId, 'npm', scopes, readonly);
   }
 
   /**
@@ -77,22 +129,7 @@ export class AuthManager {
    * @returns Auth token object or null
    */
   public async validateNpmToken(token: string): Promise<IAuthToken | null> {
-    if (!this.isValidUuid(token)) {
+    return this.validateProtocolToken(token, 'npm');
-      return null;
-    }
-
-    const authToken = this.tokenStore.get(token);
-    if (!authToken || authToken.type !== 'npm') {
-      return null;
-    }
-
-    // Check expiration if set
-    if (authToken.expiresAt && authToken.expiresAt < new Date()) {
-      this.tokenStore.delete(token);
-      return null;
-    }
-
-    return authToken;
   }
 
   /**
@@ -100,7 +137,7 @@ export class AuthManager {
    * @param token - NPM UUID token
    */
   public async revokeNpmToken(token: string): Promise<void> {
-    this.tokenStore.delete(token);
+    return this.revokeProtocolToken(token);
   }
 
   /**
@@ -265,8 +302,7 @@ export class AuthManager {
    * @returns Maven UUID token
    */
   public async createMavenToken(userId: string, readonly: boolean = false): Promise<string> {
-    const scopes = readonly ? ['maven:*:*:read'] : ['maven:*:*:*'];
+    return this.createProtocolToken(userId, 'maven', readonly);
-    return this.createUuidToken(userId, 'maven', scopes, readonly);
   }
 
   /**
@@ -275,22 +311,7 @@ export class AuthManager {
    * @returns Auth token object or null
    */
   public async validateMavenToken(token: string): Promise<IAuthToken | null> {
-    if (!this.isValidUuid(token)) {
+    return this.validateProtocolToken(token, 'maven');
-      return null;
-    }
-
-    const authToken = this.tokenStore.get(token);
-    if (!authToken || authToken.type !== 'maven') {
-      return null;
-    }
-
-    // Check expiration if set
-    if (authToken.expiresAt && authToken.expiresAt < new Date()) {
-      this.tokenStore.delete(token);
-      return null;
-    }
-
-    return authToken;
   }
 
   /**
@@ -298,7 +319,7 @@ export class AuthManager {
    * @param token - Maven UUID token
    */
   public async revokeMavenToken(token: string): Promise<void> {
-    this.tokenStore.delete(token);
+    return this.revokeProtocolToken(token);
   }
 
   // ========================================================================
@@ -312,8 +333,7 @@ export class AuthManager {
    * @returns Composer UUID token
    */
   public async createComposerToken(userId: string, readonly: boolean = false): Promise<string> {
-    const scopes = readonly ? ['composer:*:*:read'] : ['composer:*:*:*'];
+    return this.createProtocolToken(userId, 'composer', readonly);
-    return this.createUuidToken(userId, 'composer', scopes, readonly);
   }
 
   /**
@@ -322,22 +342,7 @@ export class AuthManager {
    * @returns Auth token object or null
    */
   public async validateComposerToken(token: string): Promise<IAuthToken | null> {
-    if (!this.isValidUuid(token)) {
+    return this.validateProtocolToken(token, 'composer');
-      return null;
-    }
-
-    const authToken = this.tokenStore.get(token);
-    if (!authToken || authToken.type !== 'composer') {
-      return null;
-    }
-
-    // Check expiration if set
-    if (authToken.expiresAt && authToken.expiresAt < new Date()) {
-      this.tokenStore.delete(token);
-      return null;
-    }
-
-    return authToken;
   }
 
   /**
@@ -345,7 +350,7 @@ export class AuthManager {
    * @param token - Composer UUID token
    */
   public async revokeComposerToken(token: string): Promise<void> {
-    this.tokenStore.delete(token);
+    return this.revokeProtocolToken(token);
   }
 
   // ========================================================================
@@ -359,8 +364,7 @@ export class AuthManager {
    * @returns Cargo UUID token
    */
   public async createCargoToken(userId: string, readonly: boolean = false): Promise<string> {
-    const scopes = readonly ? ['cargo:*:*:read'] : ['cargo:*:*:*'];
+    return this.createProtocolToken(userId, 'cargo', readonly);
-    return this.createUuidToken(userId, 'cargo', scopes, readonly);
   }
 
   /**
@@ -369,22 +373,7 @@ export class AuthManager {
    * @returns Auth token object or null
    */
   public async validateCargoToken(token: string): Promise<IAuthToken | null> {
-    if (!this.isValidUuid(token)) {
+    return this.validateProtocolToken(token, 'cargo');
-      return null;
-    }
-
-    const authToken = this.tokenStore.get(token);
-    if (!authToken || authToken.type !== 'cargo') {
-      return null;
-    }
-
-    // Check expiration if set
-    if (authToken.expiresAt && authToken.expiresAt < new Date()) {
-      this.tokenStore.delete(token);
-      return null;
-    }
-
-    return authToken;
   }
 
   /**
@@ -392,7 +381,7 @@ export class AuthManager {
    * @param token - Cargo UUID token
    */
   public async revokeCargoToken(token: string): Promise<void> {
-    this.tokenStore.delete(token);
+    return this.revokeProtocolToken(token);
   }
 
   // ========================================================================
@@ -406,8 +395,7 @@ export class AuthManager {
    * @returns PyPI UUID token
    */
   public async createPypiToken(userId: string, readonly: boolean = false): Promise<string> {
-    const scopes = readonly ? ['pypi:*:*:read'] : ['pypi:*:*:*'];
+    return this.createProtocolToken(userId, 'pypi', readonly);
-    return this.createUuidToken(userId, 'pypi', scopes, readonly);
   }
 
   /**
@@ -416,22 +404,7 @@ export class AuthManager {
    * @returns Auth token object or null
    */
   public async validatePypiToken(token: string): Promise<IAuthToken | null> {
-    if (!this.isValidUuid(token)) {
+    return this.validateProtocolToken(token, 'pypi');
-      return null;
-    }
-
-    const authToken = this.tokenStore.get(token);
-    if (!authToken || authToken.type !== 'pypi') {
-      return null;
-    }
-
-    // Check expiration if set
-    if (authToken.expiresAt && authToken.expiresAt < new Date()) {
-      this.tokenStore.delete(token);
-      return null;
-    }
-
-    return authToken;
   }
 
   /**
@@ -439,7 +412,7 @@ export class AuthManager {
    * @param token - PyPI UUID token
    */
   public async revokePypiToken(token: string): Promise<void> {
-    this.tokenStore.delete(token);
+    return this.revokeProtocolToken(token);
   }
 
   // ========================================================================
@@ -453,8 +426,7 @@ export class AuthManager {
    * @returns RubyGems UUID token
    */
   public async createRubyGemsToken(userId: string, readonly: boolean = false): Promise<string> {
-    const scopes = readonly ? ['rubygems:*:*:read'] : ['rubygems:*:*:*'];
+    return this.createProtocolToken(userId, 'rubygems', readonly);
-    return this.createUuidToken(userId, 'rubygems', scopes, readonly);
   }
 
   /**
@@ -463,22 +435,7 @@ export class AuthManager {
    * @returns Auth token object or null
    */
   public async validateRubyGemsToken(token: string): Promise<IAuthToken | null> {
-    if (!this.isValidUuid(token)) {
+    return this.validateProtocolToken(token, 'rubygems');
-      return null;
-    }
-
-    const authToken = this.tokenStore.get(token);
-    if (!authToken || authToken.type !== 'rubygems') {
-      return null;
-    }
-
-    // Check expiration if set
-    if (authToken.expiresAt && authToken.expiresAt < new Date()) {
-      this.tokenStore.delete(token);
-      return null;
-    }
-
-    return authToken;
   }
 
   /**
@@ -486,7 +443,7 @@ export class AuthManager {
    * @param token - RubyGems UUID token
    */
   public async revokeRubyGemsToken(token: string): Promise<void> {
-    this.tokenStore.delete(token);
+    return this.revokeProtocolToken(token);
   }
 
   // ========================================================================
@@ -495,57 +452,42 @@ export class AuthManager {
 
   /**
    * Validate any token (NPM, Maven, OCI, PyPI, RubyGems, Composer, Cargo)
+   * Optimized: O(1) lookup when protocol hint provided
    * @param tokenString - Token string (UUID or JWT)
-   * @param protocol - Expected protocol type
+   * @param protocol - Expected protocol type (optional, improves performance)
    * @returns Auth token object or null
    */
   public async validateToken(
     tokenString: string,
     protocol?: TRegistryProtocol
   ): Promise<IAuthToken | null> {
-    // Try UUID-based tokens (NPM, Maven, Composer, Cargo, PyPI, RubyGems)
+    // OCI uses JWT (contains dots), not UUID - check first if OCI is expected
-    if (this.isValidUuid(tokenString)) {
+    if (protocol === 'oci' || tokenString.includes('.')) {
-      // Try NPM token
+      const ociToken = await this.validateOciToken(tokenString);
-      const npmToken = await this.validateNpmToken(tokenString);
+      if (ociToken && (!protocol || protocol === 'oci')) {
-      if (npmToken && (!protocol || protocol === 'npm')) {
+        return ociToken;
-        return npmToken;
       }
-
+      // If protocol was explicitly OCI but validation failed, return null
-      // Try Maven token
+      if (protocol === 'oci') {
-      const mavenToken = await this.validateMavenToken(tokenString);
+        return null;
-      if (mavenToken && (!protocol || protocol === 'maven')) {
-        return mavenToken;
-      }
-
-      // Try Composer token
-      const composerToken = await this.validateComposerToken(tokenString);
-      if (composerToken && (!protocol || protocol === 'composer')) {
-        return composerToken;
-      }
-
-      // Try Cargo token
-      const cargoToken = await this.validateCargoToken(tokenString);
-      if (cargoToken && (!protocol || protocol === 'cargo')) {
-        return cargoToken;
-      }
-
-      // Try PyPI token
-      const pypiToken = await this.validatePypiToken(tokenString);
-      if (pypiToken && (!protocol || protocol === 'pypi')) {
-        return pypiToken;
-      }
-
-      // Try RubyGems token
-      const rubygemsToken = await this.validateRubyGemsToken(tokenString);
-      if (rubygemsToken && (!protocol || protocol === 'rubygems')) {
-        return rubygemsToken;
       }
     }
 
-    // Try OCI JWT
+    // UUID-based tokens: single O(1) Map lookup
-    const ociToken = await this.validateOciToken(tokenString);
+    if (this.isValidUuid(tokenString)) {
-    if (ociToken && (!protocol || protocol === 'oci')) {
+      const authToken = this.tokenStore.get(tokenString);
-      return ociToken;
+      if (authToken) {
+        // If protocol specified, verify it matches
+        if (protocol && authToken.type !== protocol) {
+          return null;
+        }
+        // Check expiration
+        if (authToken.expiresAt && authToken.expiresAt < new Date()) {
+          this.tokenStore.delete(tokenString);
+          return null;
+        }
+        return authToken;
+      }
     }
 
     return null;

ts/core/classes.registrystorage.ts

@@ -129,7 +129,7 @@ export class RegistryStorage implements IStorageBackend {
   }
 
   /**
-   * Get OCI manifest
+   * Get OCI manifest and its content type
    */
   public async getOciManifest(repository: string, digest: string): Promise<Buffer | null> {
     const path = this.getOciManifestPath(repository, digest);
@@ -137,7 +137,17 @@ export class RegistryStorage implements IStorageBackend {
   }
 
   /**
-   * Store OCI manifest
+   * Get OCI manifest content type
+   * Returns the stored content type or null if not found
+   */
+  public async getOciManifestContentType(repository: string, digest: string): Promise<string | null> {
+    const typePath = this.getOciManifestPath(repository, digest) + '.type';
+    const data = await this.getObject(typePath);
+    return data ? data.toString('utf-8') : null;
+  }
+
+  /**
+   * Store OCI manifest with its content type
    */
   public async putOciManifest(
     repository: string,
@@ -146,7 +156,11 @@ export class RegistryStorage implements IStorageBackend {
     contentType: string
   ): Promise<void> {
     const path = this.getOciManifestPath(repository, digest);
-    return this.putObject(path, data, { 'Content-Type': contentType });
+    // Store manifest data
+    await this.putObject(path, data, { 'Content-Type': contentType });
+    // Store content type in sidecar file for later retrieval
+    const typePath = path + '.type';
+    await this.putObject(typePath, Buffer.from(contentType, 'utf-8'));
   }
 
   /**

ts/core/helpers.buffer.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared buffer utilities for consistent binary data handling across all registry types.
+ *
+ * This module addresses the common issue where `Buffer.isBuffer(Uint8Array)` returns `false`,
+ * which can cause data handling bugs when binary data arrives as Uint8Array instead of Buffer.
+ */
+
+/**
+ * Check if value is binary data (Buffer or Uint8Array)
+ */
+export function isBinaryData(value: unknown): value is Buffer | Uint8Array {
+  return Buffer.isBuffer(value) || value instanceof Uint8Array;
+}
+
+/**
+ * Convert any binary-like data to Buffer.
+ * Handles Buffer, Uint8Array, string, and objects.
+ *
+ * @param data - The data to convert to Buffer
+ * @returns A Buffer containing the data
+ */
+export function toBuffer(data: unknown): Buffer {
+  if (Buffer.isBuffer(data)) {
+    return data;
+  }
+  if (data instanceof Uint8Array) {
+    return Buffer.from(data);
+  }
+  if (typeof data === 'string') {
+    return Buffer.from(data, 'utf-8');
+  }
+  // Fallback: serialize object to JSON
+  return Buffer.from(JSON.stringify(data));
+}

ts/maven/classes.mavenregistry.ts

@@ -7,6 +7,7 @@ import { BaseRegistry } from '../core/classes.baseregistry.js';
 import type { RegistryStorage } from '../core/classes.registrystorage.js';
 import type { AuthManager } from '../core/classes.authmanager.js';
 import type { IRequestContext, IResponse, IAuthToken } from '../core/interfaces.core.js';
+import { toBuffer } from '../core/helpers.buffer.js';
 import type { IMavenCoordinate, IMavenMetadata, IChecksums } from './interfaces.maven.js';
 import {
   pathToGAV,
@@ -296,7 +297,7 @@ export class MavenRegistry extends BaseRegistry {
     coordinate: IMavenCoordinate,
     body: Buffer | any
   ): Promise<IResponse> {
-    const data = Buffer.isBuffer(body) ? body : Buffer.from(JSON.stringify(body));
+    const data = toBuffer(body);
 
     // Validate POM if uploading .pom file
     if (coordinate.extension === 'pom') {

ts/npm/classes.npmregistry.ts

@@ -113,7 +113,7 @@ export class NpmRegistry extends BaseRegistry {
     const unpublishVersionMatch = path.match(/^\/(@?[^\/]+(?:\/[^\/]+)?)\/-\/([^\/]+)$/);
     if (unpublishVersionMatch && context.method === 'DELETE') {
       const [, packageName, version] = unpublishVersionMatch;
-      console.log(`[unpublishVersionMatch] packageName=${packageName}, version=${version}`);
+      this.logger.log('debug', 'unpublishVersionMatch', { packageName, version });
       return this.unpublishVersion(packageName, version, token);
     }
 
@@ -121,7 +121,7 @@ export class NpmRegistry extends BaseRegistry {
     const unpublishPackageMatch = path.match(/^\/(@?[^\/]+(?:\/[^\/]+)?)\/-rev\/([^\/]+)$/);
     if (unpublishPackageMatch && context.method === 'DELETE') {
       const [, packageName, rev] = unpublishPackageMatch;
-      console.log(`[unpublishPackageMatch] packageName=${packageName}, rev=${rev}`);
+      this.logger.log('debug', 'unpublishPackageMatch', { packageName, rev });
       return this.unpublishPackage(packageName, token);
     }
 
@@ -129,7 +129,7 @@ export class NpmRegistry extends BaseRegistry {
     const versionMatch = path.match(/^\/(@?[^\/]+(?:\/[^\/]+)?)\/([^\/]+)$/);
     if (versionMatch) {
       const [, packageName, version] = versionMatch;
-      console.log(`[versionMatch] matched! packageName=${packageName}, version=${version}`);
+      this.logger.log('debug', 'versionMatch', { packageName, version });
       return this.handlePackageVersion(packageName, version, token);
     }
 
@@ -137,7 +137,7 @@ export class NpmRegistry extends BaseRegistry {
     const packageMatch = path.match(/^\/(@?[^\/]+(?:\/[^\/]+)?)$/);
     if (packageMatch) {
       const packageName = packageMatch[1];
-      console.log(`[packageMatch] matched! packageName=${packageName}`);
+      this.logger.log('debug', 'packageMatch', { packageName });
       return this.handlePackage(context.method, packageName, context.body, context.query, token);
     }
 
@@ -254,11 +254,11 @@ export class NpmRegistry extends BaseRegistry {
     version: string,
     token: IAuthToken | null
   ): Promise<IResponse> {
-    console.log(`[handlePackageVersion] packageName=${packageName}, version=${version}`);
+    this.logger.log('debug', 'handlePackageVersion', { packageName, version });
     const packument = await this.storage.getNpmPackument(packageName);
-    console.log(`[handlePackageVersion] packument found:`, !!packument);
+    this.logger.log('debug', 'handlePackageVersion packument', { found: !!packument });
     if (packument) {
-      console.log(`[handlePackageVersion] versions:`, Object.keys(packument.versions || {}));
+      this.logger.log('debug', 'handlePackageVersion versions', { versions: Object.keys(packument.versions || {}) });
     }
     if (!packument) {
       return {
@@ -621,7 +621,7 @@ export class NpmRegistry extends BaseRegistry {
         }
       }
     } catch (error) {
-      console.error('[handleSearch] Error:', error);
+      this.logger.log('error', 'handleSearch failed', { error: (error as Error).message });
     }
 
     // Apply pagination

ts/oci/classes.ociregistry.ts

@@ -198,7 +198,7 @@ export class OciRegistry extends BaseRegistry {
     const digest = query.digest;
     if (digest && body) {
       // Monolithic upload: complete upload in single POST
-      const blobData = Buffer.isBuffer(body) ? body : Buffer.from(JSON.stringify(body));
+      const blobData = this.toBuffer(body);
 
       // Verify digest
       const calculatedDigest = await this.calculateDigest(blobData);
@@ -320,10 +320,17 @@ export class OciRegistry extends BaseRegistry {
       };
     }
 
+    // Get stored content type, falling back to detecting from manifest content
+    let contentType = await this.storage.getOciManifestContentType(repository, digest);
+    if (!contentType) {
+      // Fallback: detect content type from manifest content
+      contentType = this.detectManifestContentType(manifestData);
+    }
+
     return {
       status: 200,
       headers: {
-        'Content-Type': 'application/vnd.oci.image.manifest.v1+json',
+        'Content-Type': contentType,
         'Docker-Content-Digest': digest,
       },
       body: manifestData,
@@ -356,10 +363,18 @@ export class OciRegistry extends BaseRegistry {
 
     const manifestData = await this.storage.getOciManifest(repository, digest);
 
+    // Get stored content type, falling back to detecting from manifest content
+    let contentType = await this.storage.getOciManifestContentType(repository, digest);
+    if (!contentType && manifestData) {
+      // Fallback: detect content type from manifest content
+      contentType = this.detectManifestContentType(manifestData);
+    }
+    contentType = contentType || 'application/vnd.oci.image.manifest.v1+json';
+
     return {
       status: 200,
       headers: {
-        'Content-Type': 'application/vnd.oci.image.manifest.v1+json',
+        'Content-Type': contentType,
         'Docker-Content-Digest': digest,
         'Content-Length': manifestData ? manifestData.length.toString() : '0',
       },
@@ -388,16 +403,7 @@ export class OciRegistry extends BaseRegistry {
 
     // Preserve raw bytes for accurate digest calculation
     // Per OCI spec, digest must match the exact bytes sent by client
-    let manifestData: Buffer;
+    const manifestData = this.toBuffer(body);
-    if (Buffer.isBuffer(body)) {
-      manifestData = body;
-    } else if (typeof body === 'string') {
-      // String body - convert directly without JSON transformation
-      manifestData = Buffer.from(body, 'utf-8');
-    } else {
-      // Body was already parsed as JSON object - re-serialize as fallback
-      manifestData = Buffer.from(JSON.stringify(body));
-    }
     const contentType = headers?.['content-type'] || headers?.['Content-Type'] || 'application/vnd.oci.image.manifest.v1+json';
 
     // Calculate manifest digest
@@ -525,7 +531,7 @@ export class OciRegistry extends BaseRegistry {
 
   private async uploadChunk(
     uploadId: string,
-    data: Buffer,
+    data: Buffer | Uint8Array | unknown,
     contentRange: string
   ): Promise<IResponse> {
     const session = this.uploadSessions.get(uploadId);
@@ -537,8 +543,9 @@ export class OciRegistry extends BaseRegistry {
       };
     }
 
-    session.chunks.push(data);
+    const chunkData = this.toBuffer(data);
-    session.totalSize += data.length;
+    session.chunks.push(chunkData);
+    session.totalSize += chunkData.length;
     session.lastActivity = new Date();
 
     return {
@@ -555,7 +562,7 @@ export class OciRegistry extends BaseRegistry {
   private async completeUpload(
     uploadId: string,
     digest: string,
-    finalData?: Buffer
+    finalData?: Buffer | Uint8Array | unknown
   ): Promise<IResponse> {
     const session = this.uploadSessions.get(uploadId);
     if (!session) {
@@ -567,7 +574,7 @@ export class OciRegistry extends BaseRegistry {
     }
 
     const chunks = [...session.chunks];
-    if (finalData) chunks.push(finalData);
+    if (finalData) chunks.push(this.toBuffer(finalData));
     const blobData = Buffer.concat(chunks);
 
     // Verify digest
@@ -665,6 +672,59 @@ export class OciRegistry extends BaseRegistry {
   // HELPER METHODS
   // ========================================================================
 
+  /**
+   * Detect manifest content type from manifest content.
+   * OCI Image Index has "manifests" array, OCI Image Manifest has "config" object.
+   * Also checks the mediaType field if present.
+   */
+  private detectManifestContentType(manifestData: Buffer): string {
+    try {
+      const manifest = JSON.parse(manifestData.toString('utf-8'));
+
+      // First check if manifest has explicit mediaType field
+      if (manifest.mediaType) {
+        return manifest.mediaType;
+      }
+
+      // Otherwise detect from structure
+      if (Array.isArray(manifest.manifests)) {
+        // OCI Image Index (multi-arch manifest list)
+        return 'application/vnd.oci.image.index.v1+json';
+      } else if (manifest.config) {
+        // OCI Image Manifest
+        return 'application/vnd.oci.image.manifest.v1+json';
+      }
+
+      // Fallback to standard manifest type
+      return 'application/vnd.oci.image.manifest.v1+json';
+    } catch (e) {
+      // If parsing fails, return default
+      return 'application/vnd.oci.image.manifest.v1+json';
+    }
+  }
+
+  /**
+   * Convert any binary-like data to Buffer.
+   * Handles Buffer, Uint8Array (modern cross-platform), string, and objects.
+   *
+   * Note: Buffer.isBuffer(Uint8Array) returns false even though Buffer extends Uint8Array.
+   * This is because Uint8Array is the modern, cross-platform standard while Buffer is Node.js-specific.
+   * Many HTTP frameworks pass request bodies as Uint8Array for better compatibility.
+   */
+  private toBuffer(data: unknown): Buffer {
+    if (Buffer.isBuffer(data)) {
+      return data;
+    }
+    if (data instanceof Uint8Array) {
+      return Buffer.from(data);
+    }
+    if (typeof data === 'string') {
+      return Buffer.from(data, 'utf-8');
+    }
+    // Fallback: serialize object to JSON (may cause digest mismatch for manifests)
+    return Buffer.from(JSON.stringify(data));
+  }
+
   private async getTagsData(repository: string): Promise<Record<string, string>> {
     const path = `oci/tags/${repository}/tags.json`;
     const data = await this.storage.getObject(path);
@@ -678,7 +738,7 @@ export class OciRegistry extends BaseRegistry {
   }
 
   private generateUploadId(): string {
-    return `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
   }
 
   private async calculateDigest(data: Buffer): Promise<string> {

ts/pypi/classes.pypiregistry.ts

@@ -3,6 +3,7 @@ import { BaseRegistry } from '../core/classes.baseregistry.js';
 import { RegistryStorage } from '../core/classes.registrystorage.js';
 import { AuthManager } from '../core/classes.authmanager.js';
 import type { IRequestContext, IResponse, IAuthToken } from '../core/interfaces.core.js';
+import { isBinaryData, toBuffer } from '../core/helpers.buffer.js';
 import type {
   IPypiPackageMetadata,
   IPypiFile,
@@ -328,8 +329,9 @@ export class PypiRegistry extends BaseRegistry {
       const version = formData.version;
       // Support both: formData.content.filename (multipart parsed) and formData.filename (flat)
       const filename = formData.content?.filename || formData.filename;
-      // Support both: formData.content.data (multipart parsed) and formData.content (Buffer directly)
+      // Support both: formData.content.data (multipart parsed) and formData.content (Buffer/Uint8Array directly)
-      const fileData = (formData.content?.data || (Buffer.isBuffer(formData.content) ? formData.content : null)) as Buffer;
+      const rawContent = formData.content?.data || (isBinaryData(formData.content) ? formData.content : null);
+      const fileData = rawContent ? toBuffer(rawContent) : null;
       const filetype = formData.filetype; // 'bdist_wheel' or 'sdist'
       const pyversion = formData.pyversion;
 

ts/rubygems/helpers.rubygems.ts

@@ -455,9 +455,8 @@ export async function extractGemMetadata(gemData: Buffer): Promise<{
     }
 
     return null;
-  } catch (error) {
+  } catch (_error) {
-    // Log error for debugging but return null gracefully
+    // Error handled gracefully - return null and let caller handle missing metadata
-    console.error('Failed to extract gem metadata:', error);
     return null;
   }
 }